SCPI commands can be sent to the instrument through any Virtual Instrument Software Architecture (VISA) controller. VISA is a commonly used API in the Test and Measurement industry for communicating with instruments from a PC. The physical connection between the PC and the instrument can be Ethernet or USB. NI‑VISA is the National Instruments implementation of the VISA I/O standard. Information and downloads are available at http://www.ni.com/visa/.
The following example describes the verification that a VISA controller can interact with the instrument. The images shown and the instructions for your instrument and software may differ from the example shown here, so refer to the NI user instructions for more details.
1. On the PC, run VISA Interactive Control and double‑click on the instrument listed in the USB Instrument Resources section.
VISA Interactive Control
2. Select the viWrite tab and execute the default *IDN? write by clicking the Execute button.
VISA Interactive Control viWrite Tab
3. Select the viRead tab and click the Execute button. If the PC is connected to the instrument, the command returns the following information from the Buffer: manufacturer name (“Anritsu”), model number/options, serial number, and firmware package number.
VISA Interactive Control viRead Tab
SCPI Command Overview
SCPI commands, which are also referred to as SCPI instructions, are messages to the instrument to perform specific tasks and to return data. The following sections provide descriptions of the command syntax and notational conventions, command types and the hierarchical command structure, and command subsystems and data parameter format. For further information about SCPI, refer to the Standard Commands for Programmable Instruments (SCPI) 1999.0 document hosted by the IVI Foundation. A subset of the standard conventions defined in that document as they apply to the MS208xA are covered in this manual.
Command Names
Typical SCPI commands consist of one or more keywords, parameters, and punctuation. SCPI command keywords can be a mixture of upper and lower case characters. As with any programming language, the exact command keywords and command syntax must be used. The syntax of the individual commands is described in detail in the programming command chapters. Unrecognized versions of long form or short form commands or improper syntax will generate an error.
Long Format vs. Short Format
Except for common commands, each keyword has a long and a short form. The short form is a subset of the long form of the command. In this manual, the long form is presented with the short form in upper case and the remainder in lower case. For example, the long form of the command keyword to control the instrument display is :DISPlay.
The short form keyword is usually the first four characters of the long form (:DISP for :DISPlay). The exception to this rule is when the long form is longer than four characters and the fourth character is a vowel. In such cases, the vowel is dropped and the short form becomes the first three characters of the keyword. For example, the short form of the keyword :POWer is :POW.
A mixture of short form keywords with the entire long form keyword of each command is acceptable. For example, :SENS:FREQuency:STAR is an acceptable form of the command. However, :SENS:FREQuen:STAR is not an acceptable form of the command because :FREQuen is not the entire short nor long form of the command keyword.
Command Syntax
The command statement usually starts with a colon “:” and includes a number of keywords and parameters. The leading colon is optional, but each subsequent keyword must be separated by a colon “:” and may be followed by a parameter setting when they are available. The end of the command string and the first command parameter must be separated by a space. For example:
:DISPlay:POINtcount 201
A comma “,” is generally used for separating multiple command parameters, for example:
:SYSTem:DATE 2018,10,31
Complete command strings may be combined on a single line and separated by a semicolon “;” as follows:
Some command keywords may have a keyword parameter suffix to differentiate between multiple instrument features such as multiple trace options. When these features are available, the keyword parameter is identified and enclosed by curly braces. For example, :TRACe<n> is entered as :TRACe1 or :TRACe3.
Note
If a keyword parameter is not included in a command, the first option is implied. In the previous paragraph, :TRACe is identical to :TRACe1.
The SCPI interface standardizes command syntax and style that simplifies the task of programming across a wide range of instrumentation. As with any programming language, the exact command syntax, and command keywords, must be used. Unrecognized commands or improper syntax will not function and most often produce an error condition. The table below lists the standard notational conventions used in this document.
Notational Conventions
:
A colon links command keywords together to form commands. The colon is not an actual part of the keyword, but is a signal to the SCPI interface parser. A colon must precede a root keyword immediately following a semicolon (see Notational Examples).
;
A semicolon separates commands if multiple commands are placed on a single program line.
[ ]
Square brackets enclose one or more optional keywords.
{ }
Curly braces enclose one or more keyword or command parameters that may be included one or more times.
|
A vertical bar indicates “or” and is used to separate alternative parameter options. For example: ON|OFF is the same as ON or OFF.
< >
Angle brackets enclose keyword and command parameters (see Data Parameters).
Command Terminators
The newline character \n (ASCII 10) in the last data byte of a command string is used as a command terminator. Use of a command terminator will reset the command path to the root of the tree.
Data Parameters
Data parameters, referred to simply as “parameters,” are the quantitative values used as arguments for the SCPI commands. The parameter type associated with a particular SCPI command is determined by the type of information required to control the particular instrument function. For example, Boolean (ON|OFF) type parameters are used with commands that control switch functions. Some command descriptions specify the type of data parameter to be used with each command. The most commonly used parameter types are numeric, extended numeric, discrete, string, and Boolean.
Numeric
Numeric parameters comprise integer numbers or any number in decimal or scientific notation, and may include polarity signs. This includes specific extended values as defined in Data Parameter Notations below.
Extended Numeric
Extended numeric parameters include values such as NAN|INFinity|NINFinity (not a number|infinity|negative infinity).
Discrete
Discrete parameters, such as INTernal and EXTernal, are used to control program settings to a predetermined finite value or condition.
Boolean
Boolean parameters represent binary conditions and may be expressed as ON, OFF or 1, 0.
Data Parameter Notations
The following conventions are used to note data parameter descriptions:
Parameter Notations
<integer>
an unsigned integer without a decimal point (implied radix point)
<numeric_value>
SCPI numeric value: <NRf>|NAN|INFinity|NINFinity or other types
<NRf> is any of <NR1>|<NR2>|<NR3> <NR1> is a signed integer without a decimal point (implied radix point) <NR2> is a signed number with an explicit radix point <NR3> is a scaled explicit decimal point numeric with an exponent (floating point number)
+/- infinity (INFinity|NINFinity) and Not-A-Number (NAN) values can be specified for parameters of type NR3 with the values of +/- 9.9e37 and 9.91e37, respectively.
<char>
<CHARACTER PROGRAM DATA> Examples: CW, FIXed, UP, and DOWN
<string>
<STRING PROGRAM DATA> ASCII characters enclosed by double quotes, such as “OFF”
Trace data uses SCPI standard (IEEE 488.2) block data format. The data format is '#AXD', where D is a comma separated list of amplitudes (in ASCII) terminated with a newline \n character, X is one or more ASCII digits specifying the number of bytes in D, and A is a single ASCII digit specifying the number of digits in X.
Trace data only contains amplitude. The frequency information for each point is
Frequency = start_frequency + (span/(display_points-1))*N where N = 0, 1, 2, … display_points
Unit Suffixes
Unit suffixes are not required for data parameters, provided the values are scaled for the global default units; they do not require a space and they are not case sensitive. The instrument SCPI default units are:
• HZ (hertz) for frequency related parameters
• DB for power related parameters
• MS (milliseconds) for time related parameters
• M (meters) for distance related parameters
Query Commands
All commands, unless specifically noted in the commands syntax descriptions, have a query form. As defined in IEEE-488.2, a query is a command with a question mark “?” appended to the command. For example:
SENS:FREQ:STAR?
When a query form of a command is received, the current setting associated with the command is placed in the output buffer. Query commands always return the short form of the parameter unless otherwise specified. Boolean values are returned as 1 or 0, even when they can be set as on or off.
Hierarchical Command Structure
All SCPI commands, except the common commands, are organized in a hierarchical structure similar to the inverted tree file structure used in most computers. The SCPI standard refers to this structure as “the Command Tree.” The command keywords that correspond to the major instrument control functions are located at the top of the command tree. The root command keywords for the SCPI command set are shown in Figure: SCPI Command Tree.
SCPI Command Tree
All instrument SCPI commands, except the :ABORt command, have one or more subcommands (keywords) associated with them to further define the instrument function to be controlled. The subcommand keywords may also have one or more associated subcommands (keywords). Each subcommand level adds another layer to the command tree. The command keyword and its associated subcommand keywords form a portion of the command tree called a command subsystem. A sample of the :UNIT command subsystem is shown in Figure: SCPI :Sample :UNIT Subsystem.
