This section describes the general use of SCPI commands. 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 a list of the specific commands available, refer to the SCPI Command List.
For additional information on the SCPI language, 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 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. |
|
Query |
A query is a special type of command used to instruct the instrument to make response data available to the controller. 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]:DM:IQADjustment[:STATe] ON|OFF|1|0
In the example above, the [:STATe] portion of the command immediately follows the :DM:IQADjustment portion with no separating space. The portion following [:STATe], ON|OFF|1|0, are the parameters (argument for the command statement). There is a separating space (white space) between the command and its parameter.
Additional conventions in syntax statements are shown in Table 1 and Table 2 below.
|
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. |
|
|
[ ] |
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. |
|
|
< > |
Angle brackets around a word (or words) indicate they are not to be used literally in the command. They represent the needed item. |
In this command, the words
|
|
{ } |
Braces indicate that parameters can optionally be used in the command once, several times, or not at all. |
a single power listing:
a series of power listings:
|
|
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). |
|
|
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. This is the flexible format principle called forgiving listening. Refer to Command Parameters and Responses for more information. |
Either
|
|
When a colon is placed between two command mnemonics, it moves the current path down one level in the command tree. Refer to Command Tree for more information on command paths. |
|
|
If a command requires more than one parameter, you must separate adjacent parameters using a comma. Parameters are not part of the command path, so commas do not affect the path level. |
|
|
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. |
A |
SCPI uses a structure for the commands similar to the file systems on most computers. In SCPI, this command structure is called a command tree and is shown in Figure 1. Simplified Command Tree.
Figure 1. Simplified Command Tree
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. In the following example, :POWer represents AA, :ALC represents BB, :SOURce represents GG. The complete command path is :POWer:ALC:SOURce? (:AA:BB:GG).
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 :OUTPut:STATe ON|OFF|1|0 command, an MXG accepts :OUTPut:STATe ON, :OUTPut:STATe 1, :OUTP:STAT ON, :OUTP:STAT 1 to turn on the RF output.
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 power state (:POWer:ALC:STATe?) when it is on, the response is always 1, regardless of whether you previously sent :POWer:ALC:STATe 1 or :POWer:ALC:STATe ON. Table 3 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 data1 |
Numeric parameters are used in many commands and these commands accept all commonly used decimal representations of numbers including optional signs, decimal points, and scientific notation.
If an 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. For example, if a signal generator has a programmable output impedance of 50 or 75 ohms, and you specified 76.1 for the output impedance, the value is rounded to 75.
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 left of decimal point optional |
When specifying physical quantities, most commands use extended numeric parameters. 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.
The following example command can use one of three possible discrete parameters:
:POWer:ALC:SEARch:REFerence RMS|FIXed|MODulated
|
RMS |
power search uses a DC bias value |
|
FIXed |
power search uses a fixed 0.5 V reference |
|
MODulated |
power search uses an AC bias from the modulating signal |
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:
|
:POWer:ALC:SEARch:REFerence RMS |
|
:POWer:ALC:SEARch:REFerence FIXed |
|
:POWer:ALC:SEARch:REFerence MODulated |
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' |
Definite block is always prefixed by the # symbol to indicate the beginning of block data. The definite block (#ABC) is described as follows:
|
# |
This character indicates the beginning of the data block |
|
A |
Number of digits in the byte count B |
|
B |
Byte count in C |
|
C |
data |
Real response data represent decimal numbers in either fixed decimal or scientific notation. Most high-level programming languages that support instrument input/output (I/O) handle either decimal or scientific notation transparently.
The following are examples of real response data:
|
+4.000000E+010, -2.000000E+004 |
|
-9.990000E+002 |
|
+4.0000000000000E+010 |
|
+1 |
|
0 |
Integer response data are decimal representations of integer values including optional signs.
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!" |
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, but the file path can sometimes be optional or designated. See Table 4 for examples:
|
Format |
File Name Variable |
Example |
|---|---|---|
|
Format 1 |
"<file name>" |
"Test_Data" |
|
Format 2 |
"<file path/file name>" |
"/USER/SEQ/Test_Data" |
Format 1 can only be used with SCPI commands that imply the path name as part of the command syntax. Typically, SCPI load commands that access user-data files do not need to have a file path designated.
The maximum length for a file name is 23 characters, excluding the file path.
As a general rule, programming languages require that SCPI commands be enclosed in double quotes as shown in the following example:
":POWer:ALTernate:AMPLitude 55"
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:
"RADio:EDGE:BURSt:SHAPe ""myfile""" used in BASIC programming languages
"RADio:EDGE:BURSt:SHAPe \"myfile"" used in C, C++, Java, and PERL
"RADio:EDGE:BURSt:SHAPe 'myfile'" accepted by most programming languages
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 an instrument assumes this format when a numeric value is entered without one. The identifiers for the formats that require them are as follows:
#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
The following example sets the RF output power to 10 dBm (or the equivalent value for the currently selected power unit, such as DBUV or DBUVEMF) using the hexadecimal value 000A:
:POW #H000A
A unit of measure such as dBm or mV will not work with the values when using a format other than decimal.