/ 
Lab-Measurement-3.831
River stage zero No dependents
/ Lab::Connection::Trace

NAME

Lab::Connection::Trace - Trace communication with instruments

VERSION

version 3.831

SYNOPSIS

This module is designed to provide a simple, compact record of messages sent to and received from an instrument, suitable for later analysis. The trace file has one line per message. Examples:

01>"DAT:STAR 1" 01>"HEAD 1" 01>"DAT?" 01<":DATA:ENCDG RPBINARY;DESTINATION REFC;SOURCE CH1;START 1;STOP 2500;WIDTH 1" 01>"HEAD 0" 01>"DAT:SOU?" 01<CH1 01>"*RST"

Each connection gets a 'connection number' prefix (01 in example above), followed by a single character to indicate commands written TO the instrument (>), replies read FROM the instrument (<), communication setup commands (*) or user comments (|). The quoting is provided by Data::Dumper, with Useqq=1, so that included spaces, nonprintible chars, etc are properly escaped and quoted.

This module is mostly useful for instruments that return a lot of data with complex configuration, so that an optimum DAQ strategy is "record it all, sort it out later". Digital oscilloscopes, for example, although the module is set up so that one can combine oscilloscopes, pulse generators, power suppplies, meters, etc., and yield a single trace file.

Perl modules for parsing/decoding the trace file are needed, and may be specific to particular instruments.

OpenTraceFile

use Lab::Connection::Trace;

OpenTraceFile('tracefilename');

Opens a new trace file, reseting the trace channel count. You should call this routine before opening device channels to instruments, so that the connections get logged to the trace file.

Opening Connections

use Lab::Instrument::HP34401A;

my $m = new Lab::Instrument::HP34401A( connection_type => 'LinuxGPIB::Trace', ... );

Comment

use Lab::Connection::Trace;

Comment('global comment');

puts 00|"global comment" in trace file

$m = new Lab::Instrument:HP34401A (connection_type=>'LinuxGPIB::Trace',..);

$m->connection->Comment('meter comment');

puts 01|"meter comment" in the trace file, if the HP34410A is the first instrument using a 'Trace' connection.

Data organization

The trace data file can be divided into 'runs' and 'events', where run = 1..Nrun and event = 1..Nevnts

Use SetRun(nrun) to set an initial run number, StartRun('comment') to start a run (and reset event number) NextEvent() to go to the next event, and StopRun() to end a run.

NextRun() increments run number and resets event number.

Example: SetRun(12); # first run is number 12 StartRun('test run dozen'); # comment stored in start run marker NextEvent(); ...take data # run 12 event 1 NextEvent(); ... take data # run 12 event 2 NextEvent(); ... take data # run 12 event 3 NextRun('dozen+1'); # end run 12, start run 13. with comment ... take data # run 13 event 1 NextEvent(); ... take data # run 13 event 2 StopRun(); # write end of run marker.

These routines are provided for convenience when using Trace output as a means of storing measurement data.

SetRun

SetRun($n);

Set the run number that will be used for the next run to be started.

StartRun

Insert a global comment to indicate the start of an acquisition run sequence

StartRun($comment[,$runnum]);

If $runnum is provided, does a SetRun($runnum) first, otherwise the current run is incremented and the event number reset.

StopRun

StopRun();

Insert a line in the trace file indicating that the run has stopped.

NextRun

NextRun($comment);

Stop current run, starts new run.

NextEvent

$thisevent = NextEvent();

Puts an 'event' marker in the trace file, increments event number and returns the event number that was just started.

MuteTrace

$instrument->connection->MuteTrace($mute); # per-instrument

MuteTrace($mute); # global

Mute the tracing or unmute; $mute = 'True/1-9/Y/On' gives muted, $mute = 'False/0/N/Off' turns off muting.

Muting does not apply to Comment entries, or to Run Start/Stop or Event entries.

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by the Lab::Measurement team; in detail:

Copyright 2016       Charles Lane
          2017       Andreas K. Huettel
          2020       Andreas K. Huettel

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.