Private website

Back to Messinstrumente.

Script

 


Introduction

A script executes simple instructions to control one or more instruments. Data can be sent to the instruments, and also data can be received. The received data can be displayed with instructions and saved.

Example scripts are available in the 'Script' directory, and in the help online: Example scripts.


General

Upper and lower case are ignored. The script lines are cleaned before processing, from leading or trailing spaces, tabs and line endings. Comments are removed completely to the end of the line. Script lines cannot be wrapped over multiple lines. All statements must be on one line. Spaces within name for constants, variables, instruments, etc. are not possible. Everything in quotes will not be changed.


// - Comment

A comment starts with a double slash. Everything after the slashes is ignored until the end of the line.

Examples:

// This is a comment.
instrument com1 // Comment.
function scpi read :SYSTem:ECHO? "No // comment"

# - Constant

A constant starts with the number sign '#'. There are no restrictions for the actual name. A value is assigned to the constant with the keyword 'set'. Everything after the 'set' until the end of the line is assigned to the constant. Constants with the same name, can be created only once in the script. If the constant is used in a line without assignment with 'set', it will be replaced with its assigned value. Constants inside quotation marks are not replaced.

If the number sign is used without a corresponding constant, there is no error message. The number sign can be used e.g. within a SCPI command.

Examples:

// Create a constant for opening an instrument.
// The constant can be created e.g. in the global constants.
#$rtb set instrument $rtb vxi 192.168.1.55 1024 192.168.1.37 // Open an instrument, and assign the name '$rtb'.

#$rtb // Open instrument. The constant is replaced by its value 'instrument $rtb vxi 192...'.

#rst set :SYST:PRESet // Define a SCPI command.
function scpi write #rst // The constant #rst is replaced by its value ':SYST:PRESet'.
#rst set *RST // Returns an error because the constant '#rst' has already been defined in the script.
function scpi read :SYSTem:ECHO? "#rst" // The constant will not be replaced.

function scpi write :TEST:DATA #500003,1.5,1.8,9 // No created constant is recognized, and thus nothing is replaced.

integer, string, ... set, add, sub, mul, div, crc, ... - Variable

A variable is created when a keyword for a data type is specified, followed by a variable name. The variable name must not be the same as most of the keywords, otherwise an error message is returned. There are no restrictions for the actual name. A value is assigned to the variable with the keyword 'set'. The assignment of a value must be done in a separate line, after the variable has been created. If a variable is created several times in the script, with the same data type, there is no error message. Creating a variable several times with different data type is not allowed and there is an error message.

Literals or other variables can be added to variables. The keyword 'add' can be used to specify a variable or literal. The rules for addition are the same as for assignment if the variable types are different. Variables of type data and waveform can only be added to the same type data or waveform variable. A type image is not allowed in addition.

For the type waveform only the logic data is added. For the analog and other channels the function is still missing. This function is intended for the recordings of the history or segments. So that the individual recordings can be read in, summarized and stored as a file.

With variables of the type integer and float, literals or other variables can be calculated. With the keyword 'sub', 'mul' or 'div' a variable or a literal can be specified. The rules for the calculations are the same as for the assignment, if the variable types are different. However, only variables of type integer and float can be calculated. For all other types the calculation is not allowed. A division by zero is ignored and does not trigger an error.

From variables with the type data, a checksum can be calculated with the keyword 'crc16ccitt'. The checksum can only be assigned to a variable of type 'integer'. The checksum can be used, for example, for a firmware update on the R&S RTB2000, with the ':DIAG:UPD:TRAN:DATA ...' SCPI command. The checksum variant is also called 'CRC-16/IBM-3740', 'CRC-16/CCITT-FALSE' or 'CRC-16/CCITT (0xFFFF)'. An ASCII text of '123456789' results in 0x29B1 as checksum.

Data types:

Special values for assignment with set or add:

The assignment is treated like a literal. The values are meant for variables with type string.

Special values for assignment with set or add:

The assignments are valid only for variables with type string and data.

Examples:

boolean result // Create a boolean variable with the name 'result'.
integer counter // Create an integer variable with the name 'counter'.
float volt // Create a floating point variable with the name 'volt'.
string answer // Create a string variable with the name 'answer'.
data setting // Create a data variable with the name 'setting'.
image screen // Create an image variable with the name 'screen'.

// Assign values to the variables created above:
result set true         // Only the keyword 'true' or 'false' can be assigned.
counter set 5
counter set 5.3         // The decimal places are ignored for literals and integer variables,
                        // the value 5 is assigned.
counter set $FF         // Hexadecimal values start with '$'.
counter set %1011       // Binary values start with '%'.
volt set 1.7            // The dot must be used as decimal point.
answer set "2021 05 20" // Values for string variables can be inside quotes.
answer set 2021 05 20   // Values for string variables can also be assigned without quotes.
answer set $datetime    // Assign the current date with time.
result set counter      // If a Boolean variable is assigned the value of another variable,
                        // anything non-zero becomes 'true', and zero becomes 'false'.
counter set volt        // If a float variable is assigned to an integer variable, the value
                        // is rounded mathematically. 0.5 becomes 0, and 0.6 becomes 1.
answer set volt         // If a string variable is assigned the value of another variable,
                        // the value is converted to a string.
screen function screencopy // Assign the result of the function for a screen copy to the variable 'screen'.

counter add 1    // Add the value 1.
counter sub 3    // Subtract the value 3.
volt div 2.5     // Divide the value.
volt mul 2       // Multiply the value.
volt sub counter // Subtracting variables.
answer add " "   // Add a space character.
answer add $date // Add the current date.

// Read in a file and insert the SCPI block format at the beginning.
setting set $file "E:\Einstellungen\DS1000Z-1.bin"
setting add $block
// Calculate the CRC-16-CCITT checksum from the data.
integer crc
crc crc16ccitt setting

// Add waveform data. Is currently only possible for logic channels, analog and other channels are ignored.
waveform logic1
waveform logic2
logic1 function waveform logic
logic2 function waveform logic
logic1 add logic2
logic1 function save "T:\RTB2004 logic1 u 2 /Y-/M-/D /H/N/S" vcd

instrument - Open instrument and change settings

An instrument is opened with the keyword 'instrument'. If multiple instruments are used, an instrument name can be specified. The name must start with the dollar sign '$', otherwise there are no further restrictions. The last opened instrument is always used. To change the open instruments, the instrument name must be specified alone in one line. After the optional instrument name, the interface and associated parameters must be specified.

USBTMC

USB Test & Measurement Class. The vendor and product IDs must be specified as hexadecimal values without prefix.

instrument [$name] usbtmc VID PID [Seriennummer]

LXI respectively VXI-11

RPC/VXI network connection, most LXI instruments should work with this. If the VXI port is not specified, or 0 (zero) is specified instead, the port is queried by the instrument when it is opened, RPC UDP port 111 is used for this. If there are several network cards in the PC, the IP address of the desired card can be specified last. Otherwise, an attempt is made to determine the suitable network card automatically.

instrument [$name] vxi IP-address [VXI-Port [IP address of the network card]]

RawTCP

Raw TCP network connection without protocol. If there are several network cards in the PC, the IP address of the desired card can be specified last. Otherwise the IP address of the first network card is used.

instrument [$name] rawtcp IP-address Port [IP address of the network card]

Serial

Serial RS232 port or virtual COM port via USB connection.

instrument [$name] serial Port-number [Baud-rate [Data-bits [Stop-bits [Parity [Flow-control]]]]]

Parameters:

Default values are: 9600 8 1 None None

Examples:

instrument $rtb vxi 192.168.1.54 // Open an instrument named '$rtb' via the VXI network connection.
instrument rawtcp 192.168.1.55 5025 // Open an instrument via the Raw TCP network connection.
instrument $picotest usbtmc 164E 0DAD // Open an instrument named '$picotest' via the USBTMC connection.
instrument serial com2 115200 8 1.5 even none none // Open an instrument via the serial port.
instrument $hm2008 serial com3 // Open an instrument with the name '$hm2008' via the serial port.

When an instrument is opened in the program via the selection window, an output with the 'instrument ...' information can be found in the log window.

Further settings of the instruments can be made with the instrument name and the keyword 'set'.

Settings:

$name set timeout 2000   // Sets the wait time in milliseconds for how long to wait for a response
                         // from the instrument. If 0 (zero) or no time is specified, a default value
                         // for the wait time is used.
                         // Interface: all
$name set termchar 0A,0D // Sets one or more termination characters present at the end of the
                         // transmitted data. If no character is specified, only the waiting time
                         // is used when receiving the data. The characters must be specified as
                         // hexadecimal values.
                         // Interface: RawTCP, Serial
$name set local          // Unlocks the instrument for local operation.
                         // Interface: vxi
$name set remote         // Locks the instrument for remote operation.
                         // Interface: vxi
$name set wait scpi 200  // Waiting time that is waited between the individual SCPI commands.
                         // The specification is in milliseconds.
                         // Interface: all
$name set wait stbmav    // When reading data from the instrument, wait until the data is ready.
                         // Waiting until the MAV bit is set in the status byte.
                         // Interface: usbtmc
$name set wait srq       // When reading data from the instrument, wait until the data is ready.
                         // It waits for the service request interrupt.
                         // Interface: usbtmc
$name set wait           // Without parameters, the program will no longer wait for the data to be ready,
                         // the option will be deleted.

Example - wait stbmav:

float Volt
instrument $picotest usbtmc 164E 0DAD // Open an instrument named '$picotest' via the USBTMC connection.
$picotest set wait stbmav             // Wait until data is ready when reading in.
Volt function scpi read :INIT;:FETCH? // It waits until the measurement is finished and then reads in the value.

Example - wait srq:

float Volt
instrument $picotest usbtmc 164E 0DAD // Open an instrument named '$picotest' via the USBTMC connection.
$picotest set wait srq                // Wait until data is ready when reading in.
function scpi write *CLS              // Clear status bytes.
function scpi write *ESE 0;*SRE 16    // Set bits for the service request
Volt function scpi read :INIT;:FETCH? // It waits until the measurement is finished and then reads in the value.
function scpi write *SRE 0

label, goto - Jump label

A jump label can be created with the keyword 'label' followed by a label name. There are no restrictions for the label name. With the keyword or statement 'goto', and a following label name, it is possible to jump to the line where the label was created. The 'goto' statement can also be used after the 'true' or 'false' statements. If a jump label is created several times with the same name, there will be an error message.

Examples:

label loop // Jump label with the name 'loop'.
goto loop // The program jumps to the line with the label 'loop'.
true goto loop // After a comparison with the result 'true', the program jumps to the label 'loop'.

locale - Set floating point number conversion

The 'locale' instruction can be used to determine the conversion of floating point values. As parameter 'true', 'on', '1' or 'false', 'off', '0' is allowed. If the local setting is activated with 'true', the floating point values are converted in the format of the local system setting. If 'false' is set, the enlish format with dot as decimal point is always used. By default the setting is disabled and the English format is used.

Examples:

float number
string text
number set 123456.789
locale true
text set number
function wait msg number = $number - text = $text
locale false
text set number
function wait msg number = $number - text = $text

equal, greater, less, true, false - Comparing a variable

Variables can be compared with the keywords 'equal', 'greater' and 'less', with values or other variables. As a result, a boolean value with 'true' or 'false' is stored internally in the script. Only the last result of a comparison is available. The keywords 'true' and 'false' can be used to react to the result with further statements.

Examples:

string state // Create variable.
label loop // Create jump label.
state function scpi read :ACQ:STAT? // Assign the instrument response to the variable.
state equal COMP // Compare the variable with the value 'COMP'.
false goto loop  // If the variable is not equal to the value 'COMP',
                 // the result is 'false' and it jumps to the label 'loop'.
... // If the variable is equal to the value, the result is 'true'.
    // Since 'true' was not checked, we continue with the next line.

true function scpi write *RST // If the last result of a comparison was 'true', the SCPI command is sent.

function beep - Output advisory tone

With the keyword 'function' and the action 'beep' and optional parameters, a warning sound can be emitted. The sounds are the same as those set in the control panel under 'Sound'.

Parameters:

Examples:

function beep       // A standard sound is output.
function beep error // The default sound for an error is output.

function clipboard - Copy variables to the clipboard

With the keyword 'function' and the action 'clipboard' the contents of variables can be copied to the clipboard. Variables of type boolean, integer, float and string are copied as text and converted accordingly. For data variables, part of the data is copied as text formatted as hex and ascii characters. Variables of type image are copied to the clipboard as an image.

Examples:

screen function clipboard // Copy the variable screen of type image as image.

function remove - Remove parts from string or data variables

The content of variables with type string or data can be shortened by unneeded parts. With the keyword 'function' and the action 'remove' and further parameters, the parts to be removed can be determined. The removal is performed in the order of the specified parameters.

Parameters:

Examples:

data function remove block // Remove an existing block format at the beginning of the data.
data function remove first 5 block // Remove 5 bytes from the beginning, then remove an existing block format.
string function remove last 1 // Remove 1 character from the end.

function replace - Replace parts of string or data variables

Parts of the content of variables with type string or data, can be replaced by other values. With the keyword 'function' and the action 'replace' and further parameters, the parts to be replaced can be determined. The first parameter specifies the part to be replaced. The second parameter is used for the replacement. If the searched part is to be deleted, an empty text must be specified for it. The optional third parameter specifies the number of replacements. Without specification all occurrences of the searched part are replaced. Texts or single hexadecimal values can be specified. Texts must be enclosed in quotes, and the hexadecimal values must be separated by commas. Texts are case sensitive.

Examples:

string function replace "." "," // Replace all dots with commas.
string function replace "DAT2" "" 1 // Delete the first text found.
string function replace 0D,0A "" // Delete the line break.
data function replace A5,D3,30,00 00,30,D3,A5 1 // Replace the first four bytes found.
data function replace "END" 0D,0A // Replace all found texts.

For a string variable, do not specify hexadecimal values with zero '00'.


function save - Saving a variable

The value or content of a variable can be saved to a file with the keyword 'function' and the action 'save'. A file path including file name in quotation marks must be specified. Depending on the file type of the variable, further parameters are possible. There is no particular order for the file path and parameters when specifying them. Placeholders can be specified in the file name, which are replaced by their corresponding value when saving. Variables can also be used as placeholders.

Variables of type 'image' are saved in PNG format. The extension '.png' is automatically appended to the file name or replaces an existing extension.

For variables of type 'waveform', the corresponding channel names, source, etc., are appended to the file name.

Existing files are overwritten without prompting.

Parameters:

Parameters for type waveform:

Examples:

// Save the contents of the variable 'screen', of data type 'image', as a PNG file.
screen function save "T:\Test\Messung.png"

// Use placeholders for date and time.
screen function save "T:\Messung /Y-/M-/D /H/N/S-/Z.png"

// Save an integer variable as text with line break.
intval function save asc "T:\value.txt" eol

// Add an integer variable as text with line break to the file.
intval function save add asc "T:\value.txt" eol

// Replace the placeholder in the filename with the contents of the variable.
daten function save "T:\Record Nr /$counter.dat"

// Read in the visible logic channels from the memory and save them.
waveform logicchannels
logicchannels function waveform logic memory
logicchannels function save "T:\Signal /F /O" vcd

Placeholder in the file path:

/$... - Use the content of the specified variable.
/F - Manufacturer name.
/O - Model name.
/Y - four-digit year.
/M - double-digit month.
/D - double-digit day.
/H - double-digit hour.
/N - double-digit minute.
/S - double-digit second.
/Z - three-digit millisecond.


function scpi - Sending and receiving a SCPI command

With the keyword 'function' and the action 'scpi', SCPI commands can be sent to the instrument and the response can be read. For the action 'scpi' there are two parameters, 'write' for send, and 'read' for send and receive. This is followed by the SCPI commands without any further restrictions. To store the response data from the instrument, a variable name must be specified at the beginning of the entire instruction. The variable must have been created before with a suitable file type. SCPI commands are used without modification until the end of the line.

The values of variables can be sent if the variable name is marked with a dollar sign. It is checked whether a suitable variable name is available after the dollar sign. The values of the variables are converted into a text, this applies to boolean, integer, float and string data types.

For variables of type data only the last variable is used. The data is appended to the SCPI command at the end. All other data types are replaced by an empty text.

Examples:

function scpi write *RST // Send the SCPI command '*RST' to the instrument, no response is expected.
string idn // Create variable for text.
idn function scpi read *IDN? // Send the command '*IDN?' to the instrument,
                              // then read the response and store it in the variable 'idn'.
function scpi write :HOR:FFT:CENT $Freq // The value of the 'Freq' variable is inserted converted to text

// Read a file, insert the SCPI block format at the beginning and send it.
setting set $file "E:\Settings\DS1000Z-1.bin"
setting add $block
function scpi write :SYST:SET $setting

function screencopy - Reading in a screenshot

To read in a screen copy from the instrument, the keyword 'function' can be used with the action 'screencopy'. The result must be assigned to a variable with the data type 'image'. If the instrument is supported by the program, no further specifications need to be made. Alternatively, a screen copy can also be read in with the function for SCPI commands. However, the data cannot then be displayed directly and must be assigned to a variable with the data type 'data'. If no variable is specified for saving the screen copy, the data is discarded after it has been read in.

Supported instruments:

Examples:

image screen // Create variable 'screen' with data type 'image'.
screen function screencopy // Read a screen copy from the instrument, and assign it to the variable 'screen'.

function waveform - Reading in measurement curves

Measurement curves can be read in with the keyword 'function' and the action 'waveform', as well as other parameters of supported instruments. The read-in data can only be assigned to a variable of type 'waveform'.

The parameters are named for the different instruments, but can be used for each instrument if a corresponding function is available. It does not matter if e.g. 'bus1' or 'pod1' is specified.

If no parameter is specified, all active or visible analog, digital and Math channels are read in from the screen memory. All other channels, such as FFT etc. must be specified. If the memory is to be read, the instrument is stopped beforehand.

On the R&S RTB2000, the envelope data is also read in for the analog channel if this acquisition mode is activated. However, there are always only 2 x 1,200 samples as shown on the screen.

Supported instruments:

Parameters:

Examples:

instrument vxi 192.168.1.39 // Connect with instrument.
waveform channels           // Create variable for the measurement curves.
channels function waveform  // Read all visible channels without parameters.

channels function waveform analog // Read in all visible analog channels.
channels function waveform ch1 ch3 16 // Read channels 1 and 3 with more than 8 bits.
channels function waveform ch1 logic // Read channel 1 and all visible digital channels.
channels function waveform bus1 d12 // Read in all visible digital channels of Bus/Pod 1 and D12.

function view - Display a variable - Not available

To display the content of variables, the keyword 'function' can be used with the action 'view'. The variable with any data type must be specified first, then the statement. Other parameters can be used for a specific display and behavior of the view window.

Examples:

screen function view // Displays a read-in screenshot.

function wait - Wait

With the keyword 'function' and the action 'wait', it is possible to wait for the expiration of a time, for a time or for a date with time. With a time specification of 0 (zero) or with the parameter 'msg', a hint is output and a confirmation is waited for. In the current script window, the 'Run' button must be pressed again for this.

If the number of milliseconds is specified after 'wait', this time is waited.

Examples:

function wait 1000 // Wait for a second.
function wait 0    // Waiting for confirmation.

If the parameter 'abs' with the number of milliseconds is specified after 'wait', only the remaining time that has passed since the last call of the script line is waited. The parameter 'abs' is only useful when waiting within a loop.

Examples:

integer count
label loop
function wait abs 1000  // The first time is waited for 1000 milliseconds,
function wait 700       // after that only the remaining time is waited for 
count add 1             // the 1,000 milliseconds.
count equal 5           // In this example it is then about 300 milliseconds.
false goto loop

If the parameter 'time' or 'date' with a time or date specification is specified after 'wait', the program waits until this time.

Examples:

function wait time 19:24:00            // Wait until the time matches.
function wait date 2021-11-09 19:24:00 // Wait until the date matches.

If after 'wait' still the parameter 'msg' is specified with a message, this message is displayed and waited for a confirmation. Values of variables can also be displayed if the variable name is marked with a dollar sign. It is checked whether a suitable variable name is available after the dollar sign. The values of the variables are converted into a text, this applies to boolean, integer, float and string data types.

Examples:

function wait msg Enable output 2. // Displays the message and waits for confirmation.
function wait msg The counter is $counter. // Displays the message with the content of the variable 'counter'.

 

Back to Messinstrumente.