NAME

Lab::Instrument::TDS2024B - Tektronix TDS2024B digital oscilloscope

VERSION

version 3.803

SYNOPSIS

 use Lab::Instrument::TDS2024B;

 my $s = new Lab::Instrument::TDS2024B (
     usb_serial => 'C12345',
     # usb_vendor and usb_product set automatically        
 );

 $s->set_channel(3);
 $s->set_scale(scale=>'20mV/div');
 $s->set_display_persist(persist=>'5s');
 $s->set_acquire_average(32);
 $s->set_acquire_state(state=>'RUN');

Many of the 'quantities' passed to the code can use scientific notation, order of magnitude suffixes ('u', 'm', etc) and unit suffixes. The routines can be called using positional parameters (check the documentation for order), or with keyword parameters.

There are a few 'big' routines that let you set many parameters in one call, use keyword parameters for those.

In general, keywords passed TO these routines are case-independent, with only the first few characters being significant. So, in the example above: state=>'Run', state=>'running', both work. In cases where the keywords distinguish an "on/off" situation (RUN vs STOP for acquistion, for example) you can use a Boolean quantity, and again, the Boolean values are flexible:

TRUE = 't' or 'y' or 'on' or number!=0

FALSE = 'f' or 'n' or 'off' or number ==0

(only the first part of these is checked, case independent)

The oscilloscope input 'channels' are CH1..CH4, but there are also MATH, REFA..REFD that can be displayed or manipulated. To perform operations on a channel, one should first $s->set_channel($chan); Channel can be specified as 1..4 for the input channels, and it will be translated to 'CH1..CH4'.

The state of the TDS2024B scope is cached only when the front-panel is in a 'locked' state, so that it cannot be changed by users fiddling with knobs.

GENERAL/SYSTEM ROUTINES

new

my $s = new Lab::Instrument::TDS2024B( usb_serial => '...', );

serial only needed if multiple TDS2024B scopes are attached, it defaults to '*', which selects the first TDS2024B found. See Lab::Bus::USBtmc.pm documentation for more information.

reset

$s->reset()

Reset the oscilloscope (*RST)

get_error

($code,$message) = $s->get_error();

Fetch an error from the device error queue

get_status

$status = $s->get_status(['statusbit']);

Fetches the scope status, and returns either the requested status bit (if a 'statusbit' is supplied) or a reference to a hash of status information. Reading the status register causes it to be cleared. A status bit 'ERROR' is combined from the other error bits.

Example: $s->get_status('OPC');

Example: $s->get_status()->{'DDE'};

Status bit names:

PON: Power on

URQ: User Request (not used)

CME: Command Error

EXE: Execution Error

DDE: Device Error

QYE: Query Error

RQC: Request Control (not used)

OPC: Operation Complete

ERROR: CME or EXE or DDE or QYE

get_datetime

$datetime = $s->get_datetime();

fetches the date and time from the scope, returned in form "YYYY-MM-DD HH:MM:SS" (numeric month, 24hr time)

set_datetime

$s->set_datetime(); set to current date and time $s->set_datetime($unixtime); set to unix time $unixtime

Note that the TDS2024B has no notion of 'time zones', so default is 'local time'.

Returns the date and time in the same format as get_datetime.

wait_done

$s->wait_done([$time[,$deltaT]);

$s->wait_done(timeout => $time, checkinterval=>$deltaT);

Wait for "operation complete". If the $time optional argument is given, it is the (max) number of seconds to wait for completion before returning, otherwise a timeout of 10 seconds is used. $time can be a simple number of seconds, or a text string with magnitude and unit suffix. (Ex: $time = "200ms"). If $time="INF" then this routine will run indefinitely until completion (or some I/O error).

If $deltaT is given, checks are performed in intervals of $deltaT seconds (again, number or text), except when $deltaT is less than $time. $deltaT defaults to 500ms.

Returns 1 if completed, 0 if timed out.

test_busy

$busy = $s->test_busy();

Returns 1 if busy (waiting for trigger, etc), 0 if not busy.

get_id

$s->get_id()

Fetch the *IDN? string from device

get_header

$header = $s->get_header();

Fetch whether headers are included with query response; returns 0 or 1.

save

$s->save($n);

$s->save(setup=>$n);

Save the scope setup to a nonvolatile internal memory $n = 1..10

recall

$s->recall($n);

$s->recall(setup=>$n);

Recall scope setup from internal memory location $n = 1..10

set_header

$s->set_header($boolean); $s->set_header(header=>$boolean);

Turns on or off headers in query replies; Boolean values described above.

get_verbose

$verb = $s->get_verbose();

Fetch boolean indicating whether query responses (headers, if enabled, and response keywords) are returned in 'long form'

set_verbose

$s->set_verbose($bool); $s->set_verbose(verbose=>$bool);

Sets the 'verbose' mode for replies, with the longer form of command headers (if enabled) and keyword values. Note that when using the get_* routines, the replies are processed before being returned as 'long' values, so this routine only affects the communication between the scope and this code.

get_locked

$locked = $s->get_locked()

Get whether user front-panel controls are locked. Returns 1 (all controls locked) or 0 (no controls locked). Caching for most quantities is turned off when the controls are unlocked.

set_locked

$s->set_locked($bool); $s->set_locked(locked=>$bool);

Lock or unlock front panel controls;

NOTE: locking the front panel enables the device_cache, and reinitializes cached values (other than the special ones that are not alterable from the front panel)

get_setup

$setup = get_setup();

Get a long GPIB string that has the scope setup information

Note that the scope I am testing with generates a "300, Device-specific error; no alternate chosen" error when triggering on "AC LINE". Might be a firmware bug, so filtering it out.

set_setup

$s->set_setup($setup);

$s->set_setup(setup=>$setup);

Send configuration to scope. The '$setup' string is of the form returned from get_setup(), but can be any valid command string for the scope. The setup string is processed into separate commands, and transmitted sequentially, to avoid communications timeouts.

ACQUIRE ROUTINES

get_acquire_mode

$acqmode = $s->get_acquire_mode();

Fetches acquisition mode: SAMple,PEAKdetect,AVErage

set_acquire_mode

$s->set_acquire_mode($mode); $s->set_acquire_mode(mode=>$mode);

Sets the acquire mode: SAMple, PEAKdetect or AVErage

get_acquire_numacq

$numacq = $s->get_acquire_numacq();

Fetch the number of acquisitions that have happened since starting acquisition.

get_acquire_numavg

$numavg = $s->get_acquire_numavg();

Fetch the number of waveforms specified for averaging

set_acquire_numavg

$s->set_acquire_numavg($n); $s->set_acquire_numavg(average=>$n);

Set the number of waveforms to average valid values are 4, 16, 64 and 128

get_acquire_state

$state = $s->get_acquire_state()

Fetch the acquisition state: STOP (stopped) or RUN (running) NOTE: to check if acq is complete: wait_done()

set_acquire_state

$s->set_acquire_state($state); $s->set_acquire_state(state=>$state);

$state = 'RUN' (or boolean 'true') starts acquisition 'STOP' (or boolean 'false') stops acquisition

get_acquire_stopafter

$mode = $s->get_acquire_stopafter();

Fetch whether acquisition is in "RUNSop" mode (run until stopped) or "SEQuence" mode

set_acquire_stopafter

$s->set_acquire_stopafter($mode); $s->set_acquire_stopafter(mode=>$mode);

Sets stopafter mode: RUNStop : run until stopped, or SEQuence: stop after some defined sequence (single trigger, pattern, etc)

get_acquire

%hashref = $s->get_acquire();

Get the "acquire" information in a hash; this is a combined "get_acquire_*" with the keywords that can be use for set_acquire()

set_acquire

$s->set_acquire(state=>$state, # RUN|STOP (or boolean) mode=>$mode, # SAM|PEAK|AVE stopafter=>$stopa # STOPAfter|SEQ average=>$navg); $s->set_acquire($hashref); # from get_acquire $s->set_acquire($state,$mode,$stopa,$navg);

Sets acquisition parameters

get_autorange_state

$arstate = $s->get_autorange_state()

Fetch the autorange state, boolean, indicating whether the scope is autoranging

set_autorange_state

$s->set_autorange_state(state=>$bool); $s->set_autorange_state($bool);

Set autoranging on or off.

get_autorange_settings

$arset = $s->get_autorange_settings()

Fetch the autorange settings, returns value (HORizontal|VERTical|BOTH)

set_autorange_settings

$s->set_autorange_settings(set=>$arset);

$s->set_autorange_settings($arset);

Set what is subject to autoranging: $arset = HORizontal, VERTical, BOTH

do_autorange

$s->do_autorange();

Causes scope to adjust horiz/vert, like pressing 'autoset' button This command may take some time to complete.

get_autorange_signal

$sig = $s->get_autorange_signal()

returns the type of signal found by the most recent autoset, or NON if the autoset menu is not displayed.

get_autorange_view

$view = $s->get_autoset_view();

Fetch the menu display; view can be one of (depending on scope options): MULTICY SINGLECY FFT RISING FALLING FIELD ODD EVEN LINE LINEN DCLI DEF NONE

set_autorange_view

$s->set_autoset_view($view)

$s->set_autoset_view(view=>$view)

Set the menu display; view can be one of (depending on scope options): MULTICY SINGLECY FFT RISING FALLING FIELD ODD EVEN LINE LINEN DCLI DEF NONE

get_autorange

%hashref = $s->get_autorange();

get autorange settings as a hash

CHANNEL ROUTINES

get_channel

$chan = $s->get_channel();

Get the current channel selected for operations 1..4

set_channel

$s->set_channel(channel=>$chan); $s->set_channel($chan);

sets the channel number (1..4) for operations with the set_chan_XXX and get_chan_YYY methods on oscilloscope channels

Channel can be specified as an integer 1..4, or Ch1, Ch2, etc., or 'MATH'.

get_vertical_settings

This is like get_chan_setup, but faster (one query to scope) and output is kept in original form.

$settings = $s->get_vertical_settings($chan); $settings = $s->get_vertical_settings(channel => $chan);

$chan = scope channel or MATH

Fetch the vertical settings for a channel into a hash structure (example for CH1): $settings->{CH1:POS} # position on display $settings->{CH1:INV} # inverted? $settings->{CH1:SCAL} # vertical scale $settings->{CH1:YUN} # units for y-axis (volts, db, etc) $settings->{CH1:PRO} # voltage probe attenuation $settings->{CH1:CURRENTPRO} # current probe attenuation $settings->{CH1:COUP} # input coupling (AC, DC,..) $settings->{CH1:BANWID} # input bandwidth setting $settings->{MATH:DEFINE} # math definition, if $chan=MATH

set_visible

$s->set_visible([$chan,[$vis]]);

$s->set_visible(channel=>$chan [, visible=>$vis]);

Set/reset channel visiblity.

If no channel is given, the current channel (set by set_channel ) is used. Otherwise $chan = CH1..4, REFA..D, MATH

If $vis is not specified, it defaults to "make channel visible".

To make turn off display of a channel, use $vis=(boolean false).

get_visible

$vis = $s->get_visible($chan);

$vis = $s->get_visible(channel=>$chan);

Fetch boolean value for whether the channel (CH1..4, REFA..D, MATH) is being displayed. If channel is not specified, the current channel (from 'set_channel()') is used.

get_chan_bwlimit

$bwlim = $s->get_chan_bwlimit()

Fetch whether the channel has bandwidth limited to 20MHz (boolean)

set_chan_bwlimit

$s->set_chan_bwlimit(limit=>'on')

Turns on or off bandwith limiting (limit = boolean, true = 'limit')

get_chan_coupling

$coupling = $s->get_chan_coupling()

Fetch the channel coupling (AC/DC/GND).

set_chan_coupling

$s->set_coupling(coupling => $coupling);

Set the coupling to AC|DC|GND for an input channel

get_chan_current_probe

$iprobe = $s->get_chan_current_probe();

Get the probe scale factor. This does not mean that a current probe is in use, just what 'probe scale factor' would be applied if current probe use is selected.

set_chan_current_probe

$self->set_chan_current_probe(factor=>$x);

Set the current probe scale factor. Valid values are 0.2, 1, 2, 5, 10, 50, 100, 1000

get_chan_invert

$inv = $s->get_chan_invert();

fetch whether the channel is 'inverted' -> boolean

set_chan_invert

$s->set_chan_invert(invert=>$inv);

sets a channel to 'invert' mode if $inv is true, $inv=boolean

get_chan_position

$p = $s->get_chan_position();

get the vertical position of "zero volts" for a channel The value is the number of graticule divisions from the center.

set_chan_position

$s->set_chan_position(position=> -24)

Sets the trace 'zero' position, in graticule divisions from the center of the display. Note that the limits depend on the vertical scale, +/- 50V for >= 500mV/div, +/- 2V for < 500mV/div

get_chan_probe

$probe = $s->get_chan_probe();

Fetch the voltage probe attenuation.

set_chan_probe

$self->set_chan_probe(factor=>X);

Set the voltage probe scale factor. Valid values are 1, 10, 20, 50, 100, 500, 1000

get_chan_scale

$scale = $s->get_chan_scale();

Fetch the vertical scale for a channel, in V/div (or A/div when used with a current probe)

set_chan_scale

$self->set_chan_scale(scale=>$scale);

Set the vertical scale for a channel, in V/div or A/div. X can be a number, or a string with suffixes and units Ex: '2.0V/div' '100m'.

get_chan_yunit

$scale = $s->get_chan_yunit();

Fetch the units for the vertical scale of a channel, returns either "V" or "A"

set_chan_yunit

$self->set_chan_yunit(unit=>X);

Set the vertical scale units to either 'V' or 'A'

get_chan_setup

$hashref = $s->get_chan_setup([channel=>$chan])

Fetches channel settings and returns them as a hashref: =over 2 =item channel => channel selected (otherwise default from set_channel) =item probe => probefactor, =item postion => screen vertical position, in divisions =item scale => screen vertical scale, V/div or A/div =item coupling => (AC|DC|GND) =item bandwidth => (ON|OFF) =item yunit => (V|A) =item invert => ON|OFF =item probe => probe attentuation (for yunit=V) =item currentprobe => current probe factor (for yunit=A) =back

The hash is set up so that it can be passed to $s->set_channel($hashref)

set_chan_setup

$s->set_channel([channel=>1],scale=>...)

Can pass the hash returned from "get_chan_setup" to set a an oscilloscope channel to the desired state.

TODO: check current/voltage probe selection, adjust order of calls to avoid settings conflicts

CURSOR CONTROLS

The cursors can either be 'horizontal bars' (HBARS), attached to a particular trace, measuring amplitude; or 'vertical bars' (VBARS) that are measuring horizontally (time or frequency).

Since these names can be confusing, you can also use 'X' to select VBARS and 'Y' to select HBARS, since that gives a more natural indication of what you are measuring.

get_cursor_type

$cursor = $s->get_cursor_type([$opt]);

$cursor = $s->get_cursor_type([option=>$opt]);

Fetch cursor type: (OFF|HBARS|VBARS) default

cursor type returned as: (OFF|X|Y) if $opt = 'xy';

set_cursor_type

$s->set_cursor_type($type);

$s->set_cursor_type(type=>$type)

$type = OFF|HBAr|Y|VBAr|X

get_cursor_xunits

$units = $s->get_cursor_xunits()

gets the x (horizontal) units for the cursors (VBAR type), returns either SECONDS or HERTZ.

get_cursor_yunits

$self->get_cursor_yunits();

Fetch the units used for the cursor y positions (HBARS, or the waveform vertical position with VBARS).

The units returned can be: VOLTS, DIVISIONS, DECIBELS UNKNOWN AMPS VOLTSSQUARED AMPSSQUARED VOLTSAMPS.

get_cursor_source

$src = $s->get_cursor_source();

Fetch the source waveform being used with the cursors, determines the units of the cursor for horizontal bar (HBAR, Y) cursors.

set_cursor_source

$s->set_cursor_sourch($chan);

$s->set_cursor_source(channel => $chan);

set_cursor_xunits

$s->set_cursor_xunits($units);

$s->set_cursor_xunits(unit=>$units);

Set the units used for VBAR (x) cursor, for VBAR the possible units are (SEConds|s) or (HERtz|Hz). HBAR cursor units cannot be changed.

get_cursor_dx

$delt = $s->get_cursor_dx();

Fetch the difference between x (VBAR) cursor positions.

get_cursor_dy

$delt = $s->get_cursor_dy();

Fetch the difference between y (HBAR) cursor positions.

get_cursor_x1

$pos = $s->get_cursor_x1();

Fetch the x position of cursor 1 (VBAR), typically in units of seconds.

get_cursor_x2

$pos = $s->get_cursor_x2();

Fetch the x position of cursor 2 (VBAR), typically in units of seconds.

get_cursor_y1

$pos = $s->get_cursor_y1();

Fetch the y position of cursor 1 (HBAR), typically in units of volts, but possibly other units

get_cursor_y2

$pos = $s->get_cursor_y2();

Fetch the y position of cursor 2 (HBAR), typically in units of volts, but possibly other units.

set_cursor_x1

$s->set_cursor_x1($location);

$s->set_cursor_x1(position => $location);

set cursor 1 x location (VBAR type cursor)

set_cursor_x2

$s->set_cursor_x2($location);

$s->set_cursor_x2(position => $location);

set cursor 2 x location (VBAR type cursor)

set_cursor_y1

$s->set_cursor_y1($location);

$s->set_cursor_y1(position => $location);

set cursor 1 y position (HBAR type)

set_cursor_y2

$s->set_cursor_y2($location);

$s->set_cursor_y2(position => $location);

set cursor 2 y position (HBAR type)

get_cursor_v1

$vcursor = $s->get_cursor_v1();

If using HBAR (y) cursors, get the vertical position of cursors; if using VBAR (x) cursors, get the waveform voltage (or other vertical unit) at the cursor1 position.

get_cursor_v2

$vcursor = $s->get_cursor_v2();

If using HBAR (y) cursors, get the vertical position of cursors; if using VBAR (x) cursors, get the waveform voltage (or other vertical unit) at the cursor2 position.

get_cursor_dv

$dv = $s->get_cursor_dv();

Get the vertical distance between the cursors (dy if HBAR cursors, dv2-dv1 if VBAR cursors)

$hashref = $s->get_cursor()

Fetches cursor information and returns it in a hash, in a form that can be used with set_cursor()

set_cursor

$s->set_cursor( type=>$type, x1 => $x1, x2 => $x2, ...);

sets cursor information. If used with a hash from get_cursor, the entries that cannot be used to set the cursors are ignored

DISPLAY CONTROLS

get_display_contrast

$cont = $s->get_display_contrast()

Fetches the display contrast: 1 .. 100

set_display_contrast

$s->set_display_contrast($cont)

(alternate set_display_contrast(contrast => number) ) Set the display contrast, percent 1..100

get_display_format

$form = $s->get_display_format()

Fetch the display format: YT or XY

set_display_format

$s->set_display_format($format);

$s->set_display_format(format => $format);

Where $format = XY or YT.

get_display_persist

$pers = $s->get_display_persist()

Fetch the display persistance, values 1,2,5,INF,OFF Numbers are in seconds.

set_display_persist

$s->set_display_persist($pers);

$s->set_display_persist(persist=>$pers);

Sets display persistence. $pers = 1,2,5 seconds, INF, or OFF

get_display_style

$style = $s->get_display_style()

Fetch the display style = 'DOTS' or 'VECTORS'

set_display_style

$s->set_display_style($style)l\;

$s->set_display_style(style=>$style);

Sets the display style: $style is DOTs or VECtors

get_display

$hashref = $s->get_display();

Fetch display settings (contrast, format, etc) in a hash, that can be used with "set_display".

set_display

$s->set_display(contrast=>$contrast, ...)

Set the display characteristics

FILESYSTEM ROUTINES

get_cwd

$s->get_cwd();

Gets the current working directory on any USB flash drive plugged into the oscilloscope, or a null string ( '' ) if no drive is plugged in.

set_cwd

$s->set_cwd($cwd);

$s->set_cwd(cwd => $cwd);

Set the current working directory on the flash drive. The flash drive is on the "A:" drive, and the cwd uses "DOS" type syntax. For compatibility, forward slashes are translated to backslashes.

It would be a good idea to check for errors after this call.

delete

$self->delete($file);

$self->delete(file => $file);

Delete a file from the USB filesystem; use DOS format, and note that the USB filesystem is on "A:\topdir\subdir..."

For ease of use, this routine translates forward slashes to backslashes. It would be a good idea to check for errors after calling this routine.

get_dir

@files = $s->get_dir();

Get a list of filenames in the current (USB flash drive) directory.

get_freespace

$bytes = $s->get_freespace();

Get the amount of freespace on the USB flash.

mkdir

$s->mkdir($dirname);

$s->mkdir(directory=>$dirname);

Create a directory on the flash drive, uses MSDOS file syntax, only on the A: drive.

Forward slashes are translated to backslashes for compatibility.

It is a good idea to check for errors after calling this routine.

rename

$s->rename($old,$new);

$s->rename(old=>$old, new=>$new);

Rename $old filepath to $new filepath. Note that these are in MSDOS file syntax, all on the "A:" drive.

Forward slashes are translated to backslashes.

It is a good idea to check for errors after calling this routine.

rmdir

$s->rmdir($dir);

$s->rmdir(directory=>$rmdir);

Removes a directory from the USB flash drive. The directory name is in MSDOS syntax; forward slashes are translated to backslashes.

A directory must be empty before deletion; it is a good idea to check for errors after calling this routien.

HARDCOPY ROUTINES

get_hardcopy_format

$format = $s->get_hardcopy_format();

Fetch the hardcopy format, returns one of:

BMP BUBBLEJET DESKJET DPU3445 DPU411 DPU412 EPSC60 EPSC80 

EPSIMAGE EPSON INTERLEAF JPEG LASERJET PCX RLE THINK TIFF

set_hardcopy_format

$s->set_hardcopy_format($format);

$s->set_hardcopy_format(format => $format);

Set the 'hardcopy' format, used for screen captures:

BMP BUBBLEJET DESKJET DPU3445 DPU411 DPU412 EPSC60 EPSC80 

EPSIMAGE EPSON INTERLEAF JPEG LASERJET PCX RLE THINK TIFF

get_hardcopy_layout

$layout = $s->get_hardcopy_layout();

Fetch the hardcopy layout: PORTRAIT or LANDSCAPE

set_hardcopy_layout

$s->set_hardcopy_layout($layout);

$s->set_hardcopy_layout(layout => $layout);

Set the hardcopy layout: LANdscpe or PORTRait.

get_hardcopy_port

$port = $s->get_hardcopy_port();

Fetch the port used for hardcopy printing; for the TDS2024B, this should aways return 'USB'.

set_hardcopy_port

$s->set_hardcopy_port($port);

$s->set_hardcopy_port(port => $port);

Set the hardcopy port; for the TDS2024B, this should always be USB. Included for compatibility with other scopes.

get_hardcopy

$hashref = get_hardcopy();

Fetch hardcopy parameters (format, layout, port; although port is always 'USB') and return in a hashref.

set_hardcopy

$s->set_hardcopy(format=>$format, layout=>$layout, port=>$port);

Set hardcopy parameters; this can use a hashref returned from get_hardcopy();

get_image

$img = $s->get_image();

$img = $s->get_image($filename[, $force]);

$img = $s->get_image(file=>$filename, force=>$force, timeout=>$timeout, read_length=>$rlength, [hardcopy options]);

Fetch a screen-capture image of the scope, using the the current hardcopy options (format, layout). If the filename is specified, write to that filename (in addition to returning the image data); error if the file already exists, unless $force is true.

timeout (in seconds) and read_length (in bytes) are only passed with the "hash" form of the call.

HORIZONTAL CONTROL ROUTINES

get_horiz_view

$view = $s->get_horiz_view();

Fetch the horizontal view: MAIN, WINDOW, ZONE

WINDOW is a selection of the MAIN view; ZONE is the same as MAIN, but with vertical bar cursors to show the range displayed in WINDOW view.

set_horiz_view

$s->set_horiz_view($view);

$s->set_horiz_view(view=>$view);

Set the horizontal view to MAIn, WINDOW, or ZONE.

get_horiz_position

$pos = $s->get_horiz_position();

Fetch the horizontal position of the main view, in seconds; this is the difference between the trigger point and the horizontal center of the screen.

set_horiz_position

$s->set_horiz_position($t);

$s->set_horiz_position(time => $t);

Set the horizontal position, in seconds, for the main view. Positive time values puts the trigger point to the left of the center of the screen.

get_delay_position

$time = $s->get_delay_position();

Fetch the delay time for the WINDOW view. Time is relative to the center of the screen.

set_delay_position

$s->set_delay_position($time);

$s->set_delay_position(delaytime=>$time);

Set the postion of the WINDOW view horizontally. $time is in seconds, relative to the center of the screen.

get_horiz_scale

$secdiv = $s->get_horiz_scale();

Fetch the scale (in seconds/division) for the 'main' view.

set_horiz_scale

$s->set_horiz_scale($secdiv);

$s->set_horiz_scale(scale=>$secdiv);

Set the horizontal scale, main window, to $secdiv seconds/division.

get_delay_scale

$secdiv = $s->get_delay_scale();

Fetch the scale (in seconds/division) for the 'window' view.

set_del_scale

$s->set_del_scale($secdiv);

$s->set_del_scale(delayscale=>$secdiv);

Set the horizontal scale, window view, to $secdiv seconds/division.

get_recordlength

$samples = $s->get_recordlength();

Returns record length, in number of samples. For the TDS200B, this is always 2500, so a constant is returned.

get_horizontal

$hashref = $s->get_horizontal();

Fetch a hashref, with entries that describe the horizontal setup, and can be passesd to set_horizontal

keys: view, time, delaytime, scale, delayscale, recordlength

set_horizontal

$s->set_horizontal(time=>..., scale=>...);

Set the horizontal characteristics. See get_horizontal()

MATH/FFT ROUTINES

get_math_definition

$string = $s->get_math_definition();

Fetch the definition used for the MATH waveform

set_math_definition

$s->set_math_definition($string);

$s->set_math_definition(math => $string);

Define the 'MATH' waveform; the input is sufficiently complex that the user should check for errors after calling this routine.

Choices:

CH1+CH2

CH3+CH4

CH1-CH2

CH2-CH1

CH3-CH4

CH4-CH3 

CH1*CH2

CH3*CH4

FFT (CHx[, <window>])

<window> is HANning, FLATtop, or RECTangular.

get_math_position

$y => $s->get_math_position();

Fetch the MATH trace vertical position, in divisions from the center of the screen.

set_math_position

$s->set_math_position($y);

$s->set_math_postition(position=>$y);

Set the MATH trace veritical position, in divisions from the center of the screen.

get_fft_xposition

$pos = $s->get_fft_xposition();

Fetch FFT horizontal position, a percentage of the total FFT length, relative to the center of the screen.

set_fft_xposition

$s->set_fft_xposition($percent);

$s->set_fft_xposition(fft_xposition=>$percent);

Set the horizontal position of the FFT trace; the "percent" of the trace is placed at the center of the screen.

get_fft_xscale

$scale = $s->get_fft_xscale();

Fetch the horizontal zoom factor for FFT display, possible values are 1,2,5 and 10.

set_fft_xscale

$s->set_fft_xscale($zoom);

$s->set_fft_xscale(fft_xscale => $zoom);

Set the FFT horizontal scale zoom factor: 1,2,5, or 10.

get_fft_position

$divs = $s->get_fft_position();

Fetch the y position of the FFT display, in division from the screen center.

set_fft_position

$s->set_fft_position($divs);

$s->set_fft_position(fft_position=>$divs);

Set the FFT trace y position, in screen divisions relative to the screen center.

get_fft_scale

$zoom = $s->get_fft_scale();

Fetch the FFT vertical zoom factor, returns one of 0.5, 1, 2, 5, 10

set_fft_scale

$s->set_fft_scale($zoom);

$s->set_fft_yscale(fft_scale => $zoom);

Set the fft vertical zoom factor, valid values are 0.5, 1, 2, 5, 10

MEASUREMENT ROUTINES

The TDS2024B manual suggests using the 'IMMediate' measurements; when measurements 1..5 are used, it results in an on-screen display of the measurement results, because the on-screen display is update (at most) every 500ms. It would be a good idea to check for errors after calling get_measurement_value, because errors can result if the waveform is out of range. Also note that when the MATH trace is in FFT mode, 'normal' measurement is not possible.

The 'IMMediate' measurements cannot be accessed from the scope front panel, so will be cached even if the scope is in an 'unlocked' state. (see set_locked)

get_measurement_type

$type = $s->get_measurement_type($n);

$type = $s->get_measurement_type(measurement=>$n);

Fetch the measurement type for measurement $n = 'IMMediate' or 1..5 $n defaults to 'IMMediate'

returns one of: FREQuency | MEAN | PERIod | PHAse | PK2pk | CRMs | MINImum | MAXImum | RISe | FALL | PWIdth | NWIdth | NONE

set_measurement_type

$s->set_measurement_type($n,$type);

$s->set_measurement_type(measurement=>$n, type=>$type);

$s->set_measurement_type($type); (defaults to $n = 'IMMediate')

Set the measurement type, for measurement $n= 'IMMediate', 1..5

The type is one of: FREQuency | MEAN | PERIod | PHAse | PK2pk | CRMs | MINImum | MAXImum | RISe | FALL | PWIdth | NWIdth or NONE (only for $n=1..5).

get_measurement_units

$units = $s->get_measurement_units($n);

$units = $s->get_measurement_units(measurement=>$n);

Fetch the measurement units for measurement $n (IMMediate, 1..5) result: V, A, S, Hz, VA, AA, VV

If $n is missing or undefined, uses IMMediate.

get_measurement_source

$wfm = $s->get_measurement_source($n);

$wfm = $s->get_measurement_source(measurement=>$n);

Fetch the source waveform for measurements: CH1..CH4 or MATH for measurement $n = IMMediate, 1..5

If $n is undefined or missing, IMMediate is used.

set_measurement_source

$s->set_measurement_source($n,$wfm);

$s->set_measurement_source(measurement=>$n, measurement_source => $wfm);

Set the measurement source, CH1..CH4 or MATH for measurement $n = IMMediate, 1..5. If $n is undefined or missing uses IMMediate.

get_measurement_value

$val = $s->get_measurement_value($n);

$val = $s->get_measurement_value(measurement=>$n);

Fetch measurement value, measurement $n = IMMediate, 1..5 If $n is missing or undefined, use IMMediate.

TRIGGER ROUTINES

trigger

$s->trigger();

Force a trigger, equivalent to pushing the "FORCE TRIGGE" button on front panel

get_trig_coupling

$coupling = $s->get_trig_coupling();

returns $coupling = AC|DC|HFREJ|LFREJ|NOISEREJ

(only applies to 'EDGE' trigger)

set_trig_coupling

$s->set_trig_coupling($coupling);

$s->set_trig_coupling(coupling=>$coupling);

Set trigger coupling, $coupling = AC|DC|HFRej|LFRej|NOISErej Only applies to EDGE trigger

get_trig_slope

$sl = $s->get_trig_slope();

Fetch the trigger slope, FALL or RISE only applies to EDGE trigger.

set_trig_slope

$s->set_trig_slope($sl);

$s->set_trig_slope(slope=>$sl);

Set the trigger slope: RISE|UP|POS|+ or FALL|DOWN|NEG|-

Only applies to EDGE trigger

get_trig_source

$ch = $s->get_trig_source([$trigtype]);

$ch = $s->get_trig_source([type=>$trigtype]);

Fetch the trigger source, returns one of CH1..4, EXT, EXT5, LINE

(EXT5 is 'external source, attenuated by a factor of 5')

Trigger type is the "currently selected" trigger type, unless specified with the type parameter.

set_trig_source

$s->set_trig_source($ch);

$s->set_trig_source(source=>$ch[, type=>$type]);

Set the trigger source to one of CH1..4, EXT, EXT5, LINE (or 'AC LINE') for the current trigger type, unless type=>$type is specified.

get_trig_frequency

$f = $s->get_trig_frequency();

Fetch the trigger frequency in Hz. This function is not for use when in 'video' trigger type. If the frequcency is less than 10Hz, 1Hz is returned.

get_trig_holdoff

$hold = $s->get_trig_holdoff();

Fetch the trigger holdoff, in seconds

set_trig_holdoff

$s->set_trig_holdoff($time);

$s->set_trig_holdoff(holdoff=>$time);

Set the trigger holdoff. If $time is a number it is taken to be in seconds; text can be passed with the usual order-of-magnitude and unit suffixes.

holdoff can range from 500ns to 10s

get_trig_level

$lev = $s->get_trig_level();

Fetch the trigger level, in volts

set_trig_level

$s->set_trig_level($lev);

$s->set_trig_level(level => $lev);

Set the trigger level, in volts. The usual magnitude/suffix rules apply. This routine has no effect when the trigger ssource is set to 'AC LINE'

get_trig_mode

$mode = $s->get_trig_mode();

Fetch the trigger mode: AUTO or NORMAL

set_trig_mode

$s->set_trig_mode($mode);

$s->set_trig_mode(mode=>$mode);

Set the trigger mode: AUTO or NORMAL

get_trig_type

$type = $s->get_trig_type();

Fetch the trigger type, returns EDGE or PULSE or VIDEO.

set_trig_type

$s->set_trig_type($type);

$s->set_trig_type(type=>$type);

Set trigger type to EDGE, PULse or VIDeo.

get_trig_pulse_width

$wid = $s->get_trig_pulse_width();

Fetch trigger pulse width for PULSE trigger type

set_trig_pulse_width

$s->set_trig_pulse_width($wid);

$s->set_trig_pulse_width(width=>$wid);

Set the pulse width for PULSE type triggers, in seconds. Valid range is from 33ns to 10s.

get_trig_pulse_polarity

$pol = $s->get_trig_pulse_polarity();

Fetch the polarity for the PULSE type trigger, returns POSITIVE or NEGATIVE

set_trig_pulse_polarity

$s->set_trig_pulse_polarity($pol);

$s->set_trig_pulse_polarity(pulse_polarity=>$pol);

Set the polarity for PULSE type trigger.

$pol can be (Postive|P|+) or (Negative|N|M|-)

get_trig_pulse_when

$when = $s->get_trig_pulse_when();

Fetch the "when" condition for pulse triggering, possible values are

EQUAL: triggers on trailing edge of specified width)

NOTEQUAL: triggers on trailing edge of pulse shorter than specified width, or if pulse continues longer than specified width.

INSIDE: triggers on the trailing edge of pulses that are less than the specified width.

OUTSIDE: triggers when a pulse continues longer than the specified width

set_trig_pulse_when

$s->set_trig_pulse_when($when);

$s->set_trig_pulse_when(pulse_when=>$when);

Set the PULSE type trigger to trigger on the specified condition, relative to the pulse width.

EQ|EQUAL|= : trigger on trailing edge of pulse equal to 'width'.

NOTE|NOTEQUAL|NE|!=|<>: trigger on trailing edge of pulse that is shorter than specified width, or when the pulse exceeds the specified width.

IN|INSIDE|LT|< : trigger on trailing edge when less than specified width

OUT|OUTSIDE|GT|> : trigger when pulse width exceeds specified width.

The pulse width for this trigger is set by set_trig_pulse_width();

get_trig_vid_line

$line = $s->get_trig_vid_line();

Get the video line number for triggering when SYNC is set to LINENUM.

set_trig_vid_line

$s->set_trig_vid_line($line);

$s->set_trig_vid_line(vid_line => $line);

Set the video line number for triggering with video trigger, when SYNC is set to LINENUM.

get_trig_vid_polarity

$pol = $s->get_trig_vid_polarity();

Fetch the video trigger polarity: NORMAL or INVERTED

set_trig_vid_polarity

$s->set_trig_vid_polarity($pol);

$s->set_trig_vid_polarity(vid_polarity=>$pol);

Set the video trigger polarity: NORMal|-SYNC or INVerted|+SYNC

get_trig_vid_standard

$std = $s->get_trig_vid_standard();

Fetch the video standard used for video-type triggering; returns NTSC or PAL (PAL = PAL or SECAM).

set_trig_vid_standard

$s->set_trig_vid_standard($std);

$s->set_trig_vid_standard(vid_standard=>$std);

Set the video standard used for video triggering. $std = NTSC, PAL, SECAM (SECAM selects PAL triggering).

get_trig_vid_sync

$sync = $s->get_trig_vid_sync();

Fetcht the syncronization used for video trigger, possible values are FIELD, LINE, ODD, EVEN and LINENUM.

set_trig_vid_sync

$s->set_trig_vid_sync($sync);

$s->set_trig_vid_sync(vid_sync => $sync);

Set the synchronization used for video triggering; possible values are FIELD, LINE, ODD, EVEN, and LINENum.

get_trig_state

$state = $s->get_trig_state();

Fetch the trigger state (warning: this is not a good way to determine if acquisition is completed). Possible values are:

ARMED: aquiring pretrigger information, triggers ignored

READY: ready to accept a trigger

TRIGGER: trigger has been accepted, scope is processing postrigger information.

AUTO: in auto mode, acquiring even without a trigger.

SAVE: acquisition stopped, or all channels off.

SCAN: scope is in scan mode

WAVEFORM ROUTINES

get_data_width

$nbytes = $s->get_data_width();

Fetch the number of bytes transferred per waveform sample, returns 1 or 2.

Note that only the MSB is used, unless the waveform is averaged or a MATH waveform.

set_data_width

$s->set_data_width($nbytes);

$s->set_data_width(nbytes=>$nbytes);

Set the number of bytes per waveform sample, either 1 or 2.

Note that only the MSB is used for waveforms that are not the result of averaging or MATH operations.

get_data_encoding

$enc = $s->get_data_encoding();

Fetch the encoding that is used to transfer waveform data from the scope.

returns one of

ASCII: numbers returned as ascii signed integers, comma separated

RIBINARY: signed integer binary, MSB transferred first (if width=2)

RPBINARY: unsigned integer binary, MSB first

SRIBINARY: signed integer binary, LSB first

SRPBINARY: unsigned integer binary, LSB first

RIBINARY is the fastest transfer mode, particularly with width=1, as is used for simple waveform traces, with values ranging from -128..127 with 0 corresponding to the center of the screen.

(width = 2 data range -32768 .. 32767 with center = 0)

For unsigned data, width=1, range is 0..255 with 127 at center, width=2 range is 0..65535.

In all cases the "lower limit" is one division below the bottom of the screen, and the "upper limit" is one division above the top of the screen.

set_data_encoding

$s->set_data_encoding($enc);

$s->set_data_encoding(encoding=>$enc);

Set the waveform transfer encoding, see get_waveform_encoding for possible values and their meanings.

get_data_start

$i = $s->get_data_start();

Fetch the index of the first waveform sample for transfers $i = 1..2500

set_data_start

$s->set_data_start($i);

$s->set_data_start(start=>$i);

Set the index of the first waveform sample for transfers, $i = 1..2500.

get_data_stop

$i = $s->get_data_stop();

Fetch the index of the last waveform sample for transfers $i = 1..2500

set_data_stop

$s->set_data_stop($i);

$s->set_data_stop(stop=>$i);

Set the index of the lat waveform sample for transfers, $i = 1..2500.

get_data_destination

$dst = $s->get_data_destination();

Fetch the destination (REFA..REFD) for data transfered TO the scope.

set_data_destination

$s->set_data_destination($dst);

$s->set_data_destination(destination=>$dst);

Set the destination ($dst = REFA..REFD) for waveforms transferred to the scope.

set_data_init

$s->set_data_init();

initialize all data parameters (source, destination, encoding, etc) to factory defaults

get_data_source

$src = $s->get_data_source();

Fetch the source of waveforms transferred FROM the scope.

Possible values are CH1..CH4, MATH, or REFA..REFD.

set_data_source

$s->set_data_source($src);

$s->set_data_source(source => $src);

Set the source of waveforms transferred from the scope. Possible values are CH1..CH4, MATH, or REFA..REFD.

get_data

$h = $s->get_data();

return a hash reference with data transfer information such as width, encoding, source, etc, suitable for use with the set_data($h) routine

set_data

$s->set_data(width=>$w, start=>$istart, ... );

set data transfer characteristics, call with a hash or hashref similar to what one gets from get_data()

get_waveform

$hashref = $s->get_waveform();

$hashref = $s->get_waveform( waveform=>$wfm, start=>$startbin, stop=>$stopbin, ...data parameters...);

Fetch waveform from specified channel; if parameters are not set, use the current setup from the scope (see get_data_source) The value of $wfm can be CH1..4, MATH, or REFA..D.

returns $hashref = { v=>[voltages], t=>[times], various x,y parameters };

Note that voltages and times are indexed starting at '1', or at the 'data_start' index (see set_data_start()) $hashref->{v}->[1] ...first voltage sample, default

Alternately:
$s->set_data_start(33);
...
$hashref->{v}->[33]  ... first voltage sample

The hashref contains keys DAT:STAR and DAT:STOP for start and stop
sample numbers. 

If you are going to alter the data in $hashref->{v}->[], make sure to delete($hashref->{rawdata}) before the waveform is transmitted to the scope, this will case the rawdata to be regenerated from the $hashref->{v}->[] entries.

create_waveform

$hwfd = $s->create_waveform();

$hwfd = $s->create_waveform($t0,$t1[,$n[,\&vfunc]]);

$hwfd = $s->create_waveform(tstart=>$t0, tstop=>$t1[, nbins=$n][, vfunc=\&vfunc]);

returns a hashref with an array of time values (useful for creating a waveform) starting at $t0 and ending at $t1 with $n bins. Please note that the TDS2024B can use $n=2500 at most, although this routine will work for larger values of $n. If $n is not specified $n=2500 for a simple waveform, and $n=1250 for an 'envelope' waveform.

$t0 and $t1 can be numbers, in seconds, or text with suffixes: $t1='33ms'

The bin numbers start with '1', matching the scope behavior: $hwfd->{t}->[1] = $t0 ... $hwfd->{t}->[$n] = $t1

If a "vfunc" is given, it is called with the time values:

$v = vfunc($t);  # $t in seconds   

If vfunc returns an array of two voltages, it is taken as "min,max" values for an 'ENVELOPE' style waveform:

($vmin,$vmax) = vfunc($t);

In either case, the result is analyzed to produce a 'rawdata' entry with 8 bit waveform data, filling in the parameters needed for transmitting the waveform to the scope.

If you do not provide a reference to a "vfunc" function, you will have to create and fill in an array: $hwfd->{v}->[$n] = voltage($n) If you do not specify the $t0 and $t1 times, then you will also have to create and fill in the $hwfd->{t}->[$n] = time($n) array.

To make use of an "envelope" waveform, fill in $hwfd->{vmin}->[$n] and $hwfd->{vmax}->[$n].

put_waveform

$s->put_waveform($hwfm);

$s->put_waveform(waveform=>$hwfm, [destination=>$dst, position=>$ypos, scale=>$yscale] )

Store waveform to one of the REFA..REFD traces. If not set explicitly in the call arguments, uses the location set in the scope (see get_data_destination).

The vertical position of the trace is set with $ypos = divisions from the screen center, and the vertical scale with $yscale = V/div.

If $hwfm->{rawdata} exists, it will be transmitted to the scope unchanged. Otherwise the $hwfm->{rawdata} entry will be regenerated from the $hwfm->{v}->[] (or $hwfm->{vmin|vmax}->[]) array(s).

The error/consistency checking is certainly not complete, so doing something 'tricky' with the $hwfm hash may give unexpected results.

print_waveform

$s->print_waveform($hwfm [,$IOhandle]);

$s->print_waveform(waveform=>$hwfm [,output=>$iohandle]);

print information from the waveform stored in a hasref $hwfm, taken from get_waveform();

This is mostly for diagnostic purposes.

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
          2021       Charles Lane

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

cpanm Lab::Measurement

perl -MCPAN -e shell
install Lab::Measurement