Introduction to the Command Language

 

This document describes the SCPI command language for the Keysight 34970A/34972A multifunction switch/measure unit. These commands are based on a hierarchical tree system in which associated commands are grouped together under a common node or root to form subsystems. A portion of the INPut subsystem is shown below to illustrate the tree system.

INPut:
	COUPling:
	IMPedance:

INPut is the root keyword of the command, and COUPling and IMPedance are second-level keywords. A colon ( : ) separates a command keyword from a lower-level keyword.

Syntax Conventions

The format used to show commands is illustrated below:

MEASure:INSTall:DELete {<label>|ALL}

The command syntax shows most commands (and some parameters) as a mixture of upper- and lower-case letters. The upper-case letters indicate the abbreviated spelling for the command. For shorter program lines, you can send the abbreviated form. For better program readability, you can send the long form.

For example, in the above syntax statement, MEAS and MEASure are both acceptable forms. You can use upper- or lower-case letters. Therefore, MEASure, meas, and Meas are all acceptable. Other forms, such as MEA and MEASUR, are not valid and will generate an error.

• Braces ( { } ) enclose the parameter choices for a given command string. The braces are not sent with the command string.
• A vertical bar ( | ) separates multiple parameter choices for a given command string. For example, {<label>|ALL} in the above command indicates that you can specify a <label>, or "ALL". The bar is not sent with the command string.
• Angle brackets ( < > ) indicate that you must specify a value for the enclosed parameter. For example, the above syntax statement shows the <label> parameter enclosed in angle brackets. The brackets are not sent with the command string. You must specify a value for the parameter (for example, MEASure:INSTall:DELete "MEZ_25") unless you select one of the other options shown in the syntax (for example, MEASure:INSTall:DELete ALL).
• Some parameters are enclosed in square brackets ( [ ] ). This indicates that the parameter is optional. The brackets are not sent with the command string. If you do not specify a value for an optional parameter, the instrument chooses a default value.

Command Separators

A colon ( : ) separates a command keyword from a lower-level keyword. You must insert a blank space to separate a parameter from a command keyword. If a command requires more than one parameter, you must separate adjacent parameters using a comma as shown below:

MEASure:THResholds:ABSolute (@1:4),90,50,10

A semicolon ( ; ) is used to separate commands within the same subsystem, and can also minimize typing. For example, sending the following command string:

TRIG:SOUR EXT; COUNT 10

... is the same as sending the following two commands:

TRIG:SOUR EXT
TRIG:COUNT 10

Use a colon and a semicolon to link commands from different subsystems. For example, in the following command string, an error is generated if you do not use both the colon and semicolon:

TRIG:COUN MIN;:SAMP:COUN MIN

Querying Parameter Settings

You can query the current value of most parameters by adding a question mark ( ? ) to the command. For example, the following command turns protection on for channels 1 through 4.

CONFigure:CHANnel:PROTection (@1:4),1

You can then query the protection by sending:

CONFigure:CHANnel:PROTection? (@1:4)

This would return +1,+1,+1,+1.

Command Terminators

A command string sent to the instrument must terminate with a <new line> (<NL>) character. The IEEE-488 EOI (End-Or-Identify) message is interpreted as a <NL> character and can be used to terminate a command string in place of a <NL> character. A <carriage return> followed by a <NL> is also accepted. Command string termination will always reset the current command path to the root level.

For every message that includes a query and is sent to the instrument , the instrument terminates the returned response with a <NL> or line-feed character (EOI). For example, if *IDN? is sent, the response is terminated with a <NL> after the block of data that is returned. If a message includes multiple queries separated by semicolons (for example "*ESR?;*IDN?"), the returned response is again terminated by a <NL> after the response to the last query. In either case, the program must read this <NL> in the response before another command is sent to the instrument, or an error will occur.

 

IEEE-488.2 Common Commands

The IEEE-488.2 standard defines a set of common commands that perform functions such as reset, self-test, and status operations. Common commands always begin with an asterisk ( * ), are three characters in length, and may include one or more parameters. The command keyword is separated from the first parameter by a blank space. Use a semicolon ( ; ) to separate multiple commands as shown below:

*RST; *CLS; *ESE 32; *OPC?

Parameter Types

The language defines several data formats to be used in program messages and response messages.

Numeric Parameters

Commands that require numeric parameters will accept all commonly used decimal representations of numbers including optional signs, decimal points, and scientific notation. You can also send engineering unit suffixes with numeric parameters (e.g.,  M, k, m, or u). If a command accepts only certain specific values, the instrument will automatically round the input numeric parameters to the accepted values. The following command requires numeric parameters for the <vHigh>, <vMid> and <vLow> parameters.

MEASure:THResholds:ABSolute (@<ch_list>)[,<vHigh>,<vMid>,<vLow>]

Because the parser is case-insensitive, there is some confusion over the letter "M" (or "m"). For your convenience, the instrument interprets "mV" (or "MV") as millivolts, and "MHZ" (or "mhz") as megahertz. Likewise "MΩ" (or "mΩ") is interpreted as megohms. You can use the prefix "MA" for mega. For example, "MAV" is interpreted as megavolts.

Discrete Parameters

Discrete parameters are used to program settings that have a limited number of values (like IMMediate, EXTernal, or BUS). They have a short form and a long form just like command keywords. You can mix upper- and lower-case letters. Query responses will always return the short form in all upper-case letters. The following command requires a discrete parameter for the trigger source:

CONFigure:TRIGger:SOURce {IMMediate|SOFTware|EXTernal|CHANnel|OR}

Boolean Parameters

Boolean parameters represent a single binary condition that is either true or false. For a false condition, the instrument will accept "OFF" or 0. For a true condition, the instrument will accept "ON" or "1". When you query a Boolean setting, the instrument will always return 0 or 1. The following command requires a Boolean parameter:

CALibration:SECure:STATe {OFF|0|ON|1}

ASCII String Parameters

String parameters can contain virtually any set of ASCII characters. A string must begin and end with matching quotes; either with a single quote or a double quote. You can include the quote delimiter as part of the string by typing it twice without any characters in between. The following command uses a string parameter:

DISPlay:TEXT <quoted string>

For example, the following command displays the message "WAITING..." on the instrument's front panel (the quotes are not displayed).

DISP:TEXT "WAITING..."

You can also display the same message using the following command with single quotes.

DISP:TEXT 'WAITING...'

Using Device Clear

Device Clear is an IEEE-488 low-level bus message that you can use to return the instrument to a responsive state. Different programming languages and IEEE-488 interface cards provide access to this capability through their own unique commands. The status registers, the error queue, and all configuration states are left unchanged when a Device Clear message is received.

Device Clear performs the following actions:

• If a measurement is in progress, it is aborted.
• The instrument returns to the trigger "idle" state.
• The instrument's input and output buffers are cleared.
• The instrument is prepared to accept a new command string.
• An overlapped command, if any, will be terminated with no "Operation Complete" indication.

The ABORt command is the recommended method to terminate a measurement.

LAN Port Usage 

The Keysight 34972A uses the following LAN ports:

• Port 5024 is used for SCPI Telnet sessions.
• Port 5025 is used for Socket sessions.