6.7. SCPI Usage Guide

The M81-SSM adheres to the Standard Commands for Programmable Instruments (SCPI) command language. SCPI is a standardized command language, presently maintained by the Interchangeable Virtual Instruments (IVI) Foundation, used for controlling test and measurement instruments. SCPI provides instrument control with a standardized command syntax and style.

The following sections provide a brief overview of the SCPI language, syntax, and behavior, that will allow a new instrument user to get up and running quickly. The complete SCPI specification can be found on the IVI website.

Command Parameter Data Types

Boolean	The Boolean datatype in SCPI is used to indicate whether a setting should be enabled or disabled, where 0 or OFF represents disable and 1 or ON represents enable.
NR1	Integer number with no decimal point. Example: 123.
NRf	A decimal number that can be represented as an integer (77), a real number (77.325), or an exponential number (7732.5E02).
String	Character string enclosed in double quotes. Example: “abc”.
Character	Short mnemonic alphanumeric strings used to represent specific commands or functions, enabling concise and convenient identification of operations or queries. Ex. SWE or SWEep.
Decimal Numeric	Superset of NRf where values such as MIN and MAX are also valid.

Command Types

The M81-SSM responds to two different types of SCPI commands: common and subsystem.

Common

SCPI builds upon the IEEE 488.2 standard. Because of this, several of the commands found in IEEE 488.2 are required by the M81-SSM to be considered SCPI compliant. These commands include, but are not limited to, functionality to reset (*RST), clear the status registers (*CLS), or identify the instrument (*IDN?).

These commands are identifiable by the fact that they:

Always consist of three letters and
Are always preceded by an asterisk

Subsystem

In addition to the common commands, SCPI defines subsystem commands. If the M81-SSM is considered a “system,” then the logical grouping of its various functions can be considered different “subsystems,” forming a hierarchical “tree.” Each subsystem is composed of program headers. Together, these make up the individual SCPI command. The following is an example of several SCPI commands and how they fit into the hierarchical tree:

READ
    :SENSe#
        :DC?

SOURce#
    :COUPling?
    :COUPling <coupling>

SENSe#
    :MODE?
    :MODE <mode>
    :VOLTage
        :RANGe?
        :RANGe <range>
            :AUTO?
            :AUTO <state>

Queries

Many times, a command will have a corresponding query. Queries require a question mark at the end of the command header. For example:

READ:SENSe1:DC?

If a query requires a parameter, place the question mark at the end of the header and before the query parameters.

Infinity and NaN Values

As defined in the IEEE 488.2 standard, positive infinity is represented by 9.9E+37, negative infinity is represented by -9.9E+37, and NaN (not a number) is represented by 9.91E+37.

Optional Commands

If a command header is enclosed in brackets ([ ]), then it is optional. Do not include the brackets if you send the optional command to the instrument. For example, the following command messages are both valid:

SENSe1:FILTer:STATe?
SENSe1:FILTer?

Short and Long Form

SCPI specifies a short and long form for its command headers. The command header is completely spelled out in the long form while it is abbreviated to the first three or four letters for short form. The following is an example of the same command in both short and long form:

SENSe1:CONFiguration GROund
SENS1:CONF GRO

Number Suffix

When a command header is used to represent multiple instances of a given function of the instrument, the selection of which to use is designated by a numeric suffix attached to the command header. This suffix is applicable for both short and long forms. Examples:

READ:SENSe1:DC?
READ:SENS1:DC?

Multiple Commands in a Single Message

Many times, it is desirable to chain multiple commands and queries together into one message transmission. To do this, separate each command/query with a semicolon and be sure to include a colon before the next command, unless it is a common command that uses the “*” prefix.

If multiple commands are provided in a given message, the M81-SSM will process the commands in the order in which they were received. Subsequently, if multiple queries are included in chained message, the M81-SSM will respond to the queries in the order in which they were received. For example:

SENSe1:CONFiguration GROund;:READ:SENSe1:DC?;*OPC?

This will set measure module 1 input configuration to ground, request a DC measurement from measure module 1, then wait for an operation complete query response. What is returned might look like the following:

2.438927059283;1

Commands Within the Same Subsystem

Referring to the subsystem tree shown in section 4.2.1.2, if multiple commands within the same level of the SCPI tree are sent in the same chained message, the colon does not need to be included in order to reset the SCPI header path. An example of this is the RANGe and MODE headers within the SENSe subsystem. For example:

READ:SENSe1:LIA:X?;Y?

This will return both an X and Y measurement.

Terminators

All data in a given SCPI message is encoded in the American Standard Code for Information Interchange (ASCII) format. A special ASCII character, the line feed (LF, hex 0A, decimal 10), is required by the instrument to know where the SCPI message ends. The instrument also allows an optional carriage return (CR, hex 0D, decimal 13) to precede the line feed. The instrument query response terminator will include both carriage return and line feed.

Message Flow Control

It is important to remember that the user program is in charge of SCPI communication at all times, independent of the communications bus used to control the instrument. The instrument cannot initiate communication, determine which device should be transmitting at a given time, or guarantee timing between messages. All of this is the responsibility of the user program.

Most commands sent to the M81-SSM will execute within 100 ms of the last character being transmitted. However, the SCPI command protocol does not specify that an instrument return an acknowledge message when a given command is finished executing. Because of this, a user program could potentially flood and overload the instrument’s SCPI buffer.

Therefore, it is highly recommended to append the Operation Complete Query (*OPC?) to the end of any given command string. The operation complete query is a SCPI mandated IEEE 488.2 query that will cause the instrument to send a “1” back to the user program when all commands have been processed. This scheme closes the timing loop and provides the proper balance for a user program to maximize command throughput yet not risk overrunning the instrument SCPI buffer. *OPC? can be appended onto a single command or a chained SCPI message. For example:

SENSe1:CONFiguration AB;:SENSe1:COUPling DC;*OPC?

This will set measure module 1 configuration to differential (A-B), coupling to DC and then wait for an operation complete query response.