This section describes the general use of the SCPI language. It is not intended to teach you everything about the SCPI language; the SCPI Consortium or IEEE can provide that level of detailed information.
For additional information, refer to the following publications:
IEEE Standard 488.1-2003, IEEE Standard For Higher Performance Protocol for the Standard Digital Interface for Programmable Instrumentation. New York, NY, 2003.
IEEE Standard 488.2-1992, IEEE Standard Codes, Formats, Protocols and Command Commands for Use with ANSI/IEEE Standard 488.1-1987. New York, NY, 1998.
The following terms are used throughout the remainder of this section:
|
Command |
A command is an instruction in SCPI consisting of mnemonics (keywords), parameters (arguments), and punctuation. You combine commands to form messages that control instruments. |
|
Controller |
A controller is any device used to control the instrument, for example the instrument itself, a computer, or another instrument. |
|
Event Command |
Some commands are events and cannot be queried. An event has no corresponding setting; it initiates an action at a particular time. |
|
Program Message |
A program message is a combination of one or more properly formatted commands. |
|
Query |
A query is a special type of command used to instruct the instrument to make response data available. A query ends with a question mark. Generally you can query any command value that you set. |
|
Response Message |
A response message is a collection of data in specific SCPI formats sent from the instrument to the controller. Response messages tell the controller about the internal state of the instrument. |
A typical command is made up of keywords prefixed with colons (:). The keywords are followed by parameters. The following is an example syntax statement:
[:SOURce]:FSIMulator[1]2:FADer[1]|2|3|4|5|6|7|8:STANdard:LINK
|
In the example above, the :FADer[1]|2|3|4|5|6|7|8:STANdard:LINK portion of the command immediately follows the:FSIMulator[1]2 portion with no separating space. The parameter arguments for the command statement immediately follow the :STANdard:LINK portion with a separating space (white space) between the command and its parameter arguments.
|
Characters |
Meaning |
Example |
|
| |
A vertical stroke between keywords or parameters indicates alterative choices. For parameters, the effect of the command varies depending on the choice. |
:CONTrol:CLOCk:SOURce INTernal|EXTernal INTernal or EXTernal are the choices. |
|
[ ] |
Square brackets indicate that the enclosed keywords or parameters are optional when composing the command. These implied keywords or parameters will be executed even if they are omitted. |
:CONTrol:PLAY[:STATe]1|0 ON|OFF |
|
< > |
Angle brackets around a word (or words) indicate they are not to be used literally in the command. They represent the needed item. |
:CONTrol:CONFig <config type>,"<config name>" In this command, the words <config type> and , <config name> should be replaced by the actual configuration type and name of the configuration. CONT:CONF SMIM,"2x2” |
|
Characters, Keywords, and Syntax |
Example |
|
Upper-case lettering indicates the minimum set of characters required to execute the command. But, each mode of the command must be in either short form or the complete long form (no in between). Correct: :FSIM Incorrect: :FSIMul |
[:SOURce]:FSIMulator FSIM is the minimum requirement.
|
|
Lower-case lettering indicates the portion of the command that is optional; it can either be included with the upper-case portion of the command or omitted. Lower case, either the short form or the complete long form, is also acceptable. |
:FSIMulator Either :FSIM, :fsim, :FSIMulator, : |
|
When a colon is placed between two command mnemonics, it moves the current path down one level in the command tree. |
:CONTrol:TRIGger:POLarity? CONTrol is the root level keyword for this command. Note: You can omit the leading colon if the command is the first of a new program line. |
|
A semicolon separates two commands in the same program message without changing the current path. |
:CONTrol:TRIGger:SOURce HW;:POLarity POS This is equivalent to sending :CONT:TRIG:SOUR HW;:CONT:TRIG:POL POS |
|
White space characters, such as <tab> and <space>, are generally ignored as long as they do not occur within or between keywords. However, you must use white space to separate the command from the parameter, but this does not affect the current path. |
:CONTrol:CLOCk:RATE 10E+06 :CONT rol or :CONTrol :CLOCk:RATE are
not allowed. |
Commands can be separated into two groups: common commands and subsystem commands. The diagram below shows the separation of the two command groups.
Common commands are used to manage status registers, synchronization, and data storage and are defined by IEEE 488.2. They are easy to recognize because they all begin with an asterisk. For example *IDN?, *OPC, and *RST are common commands. Common commands are not part of any subsystem and the instrument interprets them in the same way, regardless of the current path setting.
Subsystem commands are distinguished by the colon (:). The colon is used at the beginning of a command statement and between keywords, as in :CONTrol:IO1:OUTPut. Each command subsystem is a set of commands that roughly correspond to a functional block inside the instrument. For example, the :IO subsystem contains commands for controlling the I/O flow, while the output subsystem contains commands that affect the output only.
Most programming tasks involve subsystem commands. SCPI uses a structure for subsystem commands similar to the file systems on most computers. In SCPI, this command structure is called a command tree. A simplified example is shown below.
The command closest to the top is the root command, or simply ”the root.” Notice that you must follow a particular path to reach lower level commands.
To access commands from different paths in the command tree, you must understand how the instrument interprets commands. The parser, a part of the firmware, decodes each message sent. The parser breaks up the message into component commands using a set of rules to determine the command tree path used. The parser keeps track of the current path (the level in the command tree) and where it expects to find the next command statement. This is important because the same keyword may appear in different paths. The particular path is determined by the keyword(s) in the command statement.
A message terminator, such as a <new line> character, sets the current path to the root. Many programming languages have output statements that automatically send message terminators.
| The current path is set to the root after the line-power is cycled or when *RST is sent. |
SCPI defines different data formats for use in program and response messages. It does this to accommodate the principle of forgiving listening and precise talking. For more information on program data types, refer to IEEE 488.2.
Forgiving listening means the command and parameter formats are flexible.
For example, with the [:SOURce]:RADio:[1]|2|3|4|5|6|7|8:ARB::ENABle ON|OFF|1|0, the instrument accepts any of the following commands to turn on channels 1 and 2:
[:SOURce]:RADio1:ARB:ENABled ON
[:SOURce]:RADio1:ARB: ENABled 1
[:SOUR]:RAD1:ARB::ENAB ON
[:SOUR]:RAD1:ARB::ENAB 1
Each parameter type has one or more corresponding response data types. A setting that you program using a numeric parameter returns either real or integer response data when queried. Response data (data returned to the controller) is more concise and restricted, and is called precise talking.
Precise talking means that the response format for a particular query is always the same.
For example, if you query the digital I/O status, :CONTrol:IO1:DIGital:ENABle? when it is on, the response is always 1, regardless of whether you previously sent :CONTrol:IO1:DIGital:ENABle 1 or :CONTrol:IO1:DIGital:ENABled ON. The table below shows the response for a given parameter type.
Parameter Types | Response Data Types |
Numeric | Real, Integer |
Extended Numeric | Real, Integer |
Discrete | Discrete |
Boolean | Numeric Boolean |
String | String |
Definite Block | Arbitrary byte data |
Numeric parameters are used in both common and subsystem commands. They accept all commonly used decimal representations of numbers including optional signs, decimal points, and scientific notation.
If the instrument setting is programmed with a numeric parameter which can only assume a finite value, it automatically rounds any entered parameter which is greater or less than the finite value. The following are examples of numeric parameters:
100 | no decimal point required |
100. | fractional digits optional |
–1.23 | leading signs allowed |
4.56E<space>3 | space allowed after the E in exponential |
–7.89E-001 | use either E or e in exponential |
+256 | leading + allowed |
.5 | digits to the left of decimal point optional |
Most subsystems use extended numeric parameters to specify physical quantities. Extended numeric parameters accept all numeric parameter values and other special values as well.
The following are examples of extended numeric parameters:
100 | any simple numeric value |
1.2GHz | GHz can be used for exponential (E009) |
200MHz | MHz can be used for exponential (E006) |
–100mV | negative 100 millivolts |
10DEG | 10 degrees |
Extended numeric parameters also include the following special parameters:
DEFault | resets the parameter to its default value |
UP | increments the parameter |
DOWN | decrements the parameter |
MINimum | sets the parameter to the smallest possible value |
MAXimum | sets the parameter to the largest possible value |
Discrete parameters use mnemonics to represent each valid setting. They have a long and a short form, just like command mnemonics. You can mix upper and lower case letters for discrete parameters.
[:SOURce]:RADio[1]|2|3|4|5|6|7|8:ARB:FORMat:BORDer NORMal|SWAPped
The following examples of discrete parameters are used with the command.
NORMal | This choice plays the waveform file reading the bytes in sequential order. |
SWAPped | This choice plays the waveform file swapping every other byte position. |
Although discrete parameters look like command keywords, do not confuse the two. In particular, be sure to use colons and spaces properly. Use a colon to separate command mnemonics from each other and a space to separate parameters from command mnemonics.
The following are examples of discrete parameters in commands:
:RADio1,2,3,4:ARB:FORMat:BORDer NORMal |
:RADio1,2,3,4:ARB:FORMat:BORDer SWAPped |
Boolean parameters represent a single binary condition that is either true or false. The two-state boolean parameter has four arguments. The following list shows the arguments for the two-state boolean parameter:
ON | boolean true, upper/lower case allowed |
OFF | boolean false, upper/lower case allowed |
1 | boolean true |
0 | boolean false |
String parameters allow ASCII strings to be sent as parameters. Single or double quotes are used as delimiters.
The following are examples of string parameters:
'This is valid' |
"This is also valid" |
'SO IS THIS' |
Real response data represent decimal numbers in either fixed decimal or scientific notation. Most high-level programming languages that support input/output (I/O) handle either decimal or scientific notation transparently.
The following are examples of real response data:
+4.000000E+010, –9.990000E+002 |
–9.990000E+002 |
+4.0000000000000E+010 |
+1 |
0 |
Integer response data are decimal representations of integer values including optional signs. Most status register related queries return integer response data.
The following are examples of integer response data:
0 | signs are optional |
+100 | leading + allowed |
–100 | leading – allowed |
256 | never any decimal point |
Discrete response data are similar to discrete parameters. The main difference is that discrete response data only returns the short form of a particular mnemonic, in all upper case letters.
The following are examples of discrete response data:
IMM |
EXT |
INT |
NEG |
Boolean response data returns a binary numeric value of one or zero.
String response data are similar to string parameters. The main difference is that string response data returns double quotes, rather than single quotes. Embedded double quotes may be present in string response data. Embedded quotes appear as two adjacent double quotes with no characters between them.
The following are examples of string response data:
"This is a string" |
"one double quote inside brackets: [""]" |
"Hello!" |
The following commands will be used to demonstrate the creation of program messages used in a basic program flow.
:CONTrol:CONFigure GSUM,"2Ch" |
:CONTrol:CONFigure:APPLy |
:CONTrol:IO1:OUTPut:MARKer1:ENABled ON|OFF |
:CONTrol:CONFigure:IO1:PORT "A1" |
Example 1
:CONTrol:CONFigure GSUM,"2Ch";CONFigure:APPLy
This program message is correct and will not cause errors; both commands are at the same root level, CONTrol. Note that :CONFigure is required with the second command to apply the configuration which distinguishes it from the :FSIM:APPLy command which applies a fading model. It is equivalent to sending the following message:
:CONTrol:CONFigure GSUM,"2Ch";:CONTrol:CONFigure:APPLy
Example 2
:CONTrol:CONFigure:IO1:PORT "A1";OUTPut:MARKer1:ENABled ON
This program message results in a command error. Even though both commands pertain to IO functionality, the :CONTROL:CONFigure subsystem and the :CONTrol:IO subsystem have different functionality. In general, send configuring commands and IO commands as two separate commands. The following shows the correct program message:
:CONTrol:CONFigure:IO1:PORT "A2";:CONTrol:IO1:OUTPut:MARKer1:ENABled OFF
Example 3
:CONTrol:IO1:OUTPut:MARKer1,2,3:ENABled ON
This program message will not work. Each marker must be enabled separately. Comma separated numbering can only be used for a series of values.
:CONTrol:IO1:OUTPut:MARKer1:ENABled ON;MARKer3:ENABled OFF;MARKer4:ENABled ON
File name variables designate a data file and file path. File name variables are used in the SCPI command syntax whenever files are accessed. The name of the file is always required in the command syntax and is shown as "<file name>" in the command when a file name is required.
The following table shows the different file path formats:
Format | File Name Variable | Example |
Format 1 | Use the short name: "mywaveform.bin" | Stores "mywaveform.bin" in the default directory: |
Format 2 | Use the full file path: "<D:\myfiles\mywaveform.bin>" | Stores mywaveform.bin in the directory |
Format 3 | Use the "msus file name": "<NVWFM1, NVWFM2, ..., NVWFM9:mywaveform.bin>" | Stores "NVWFM2:mywaveform.bin" in |
The instrument uses a standard MS Windows® directory structure that has the same properties as a PC running an equivalent operating system. The PXB provides predefined directories for storing waveform files.
C:\Program Files\Agilent\PXB\FactoryDefaultWaveforms contains default waveform that are included when the instrument is shipped.
D:\Waveforms\ChannelN (N = 1, 2, 3,...9) are directories for waveform storage that correspond respectively to the available baseband selections. These directories are also referenced as the corresponding MSUS files: NVWFM1, NVWFM2, NVWFM3, NVWFM4, ..., NVWFM9 respectively. Waveforms generated from Signal Studio applications are automatically stored in these directories according to the current PXB configuration when they are generated and downloaded in the software.
| The D: partition of the hard drive is designated for user data and will not be affected in the event that the hard disk recovery is needed. Current waveform downloads are not preserved in baseband memory if you preset the instrument, close the user interface, cycle the power, or turn the instrument off. |
As a general rule, programming languages require that SCPI commands be enclosed in double quotes as shown in the following example:
":CONT:PLAY ON"
However when a string is the parameter for a SCPI command, additional quotes or other delimiters may be required to identify the string. Your programming language may use two sets of double quotes, one set of single quotes, or back slashes with quotes to signify the string parameter. The following examples illustrate these different formats accepted by most programming languages.
"RADio1:ARB:WAVeform ""myfile"""
used in BASIC programming languages
"RADio1:ARB:WAVeform\"myfile\""
used in C, C++, Java, and
"RADio1:ARB:WAVeform 'myfile'"
Consult your programming language reference manual to determine the correct format.
Command values may be entered using a binary, decimal, hexadecimal, or octal format. When the binary, hexadecimal, or octal format is used, their values must be preceded with the proper identifier. The decimal format (default format) requires no identifier and the instrument assumes this format when a numeric value is entered without one. The following list shows the identifiers for the formats that require them:
#B identifies the number as a binary numeric value (base 2).
#H identifies the number as a hexadecimal alphanumeric value (base 16).
#Q identifies the number as a octal alphanumeric value (base 8).
The following are examples of SCPI command values and identifiers for the decimal value 45:
#B101101 | binary equivalent |
#H2D | hexadecimal equivalent |
#Q55 | octal equivalent |
A unit of measure, such as dBm or mV, will not work with the values when using a format other than decimal.
