SCPI Basics

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:

Common Terms

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.

Command Syntax

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.

Table 1. Special Characters in Command Syntax

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.

[:SOURce]:IQ:AUX:INPut:STRobe:SLOPe POSitive|NEGative

POSitive or NEGative 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.

[:SOURce]:FREQuency[:CW]?

SOURce and CW are optional items.

< >

Angle brackets around a word (or words) indicate they are not to be used literally in the command. They represent the needed item.

[:SOURce]:FREQuency[:CW] <value><unit>

In this command, the words <value> and <unit> should be replaced by the actual frequency and unit.

:FREQuency 2.5GHz

{ }

Braces indicate that parameters can optionally be used in the command once, several times, or not at all.

[:SOURce]:LIST:POWer <value>{,<value>}

a single power listing:

:LIST:POWer 5

a series of power listings:

:LIST:POWer 5,10,15,20

Table 2. Command Syntax

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).

[:SOURce]:FREQuency[:CW]?,

:FREQ 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. This is the flexible format principle called forgiving listening. Refer to Command Parameters and Responses for more information.

:FREQuency

Either :FREQ, :FREQuency, or :FREQUENCY is correct.

:FREQuenc is incorrect.

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.

:IQ:OUTPut:TRIGger:EXTernal:POLarity?

:IQ is the root level keyword for this command.

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.

[:SOURce]:LIST:DWELl <value>{,<value>}

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.

:FREQ uency or :POWer :LEVel are not allowed.

A <space> between :LEVel and 6.2 is mandatory: :POWer:LEVel 6.2

Command Tree

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).

Command Parameters and Responses

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.

Table 3. Parameter and Response Types

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

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

Extended Numeric Parameters

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

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

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

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

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

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

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

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

Numeric Boolean Response

Boolean response data returns a binary numeric value of one or zero.

String Response Data

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

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:

Table 4. File Name Path Formats

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.

Quote Usage with SCPI Commands

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.

Binary, Decimal, Hexadecimal, and Octal Formats

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.