2. Syntax and style

Throughout this document, the following conventions are used for the SCPI command syntax:

• Square brackets ([]) indicate optional keywords or parameters. The braces are not sent with the command string.
• Braces ({}) enclose parameters within a command string.
• Triangle brackets (<>) indicate that you must substitute a value or a code for the enclosed parameter.
• A vertical bar (|) separates one of two or more alternative parameters.

2.1. Root Specifier

When it precedes the first header of a message unit, the colon becomes the root specifier. It tells the command parser that this is the root or the top node of the command tree.

2.2. Command termination

A command string sent to the BB3 must terminate with a <new line>character. A <carriage return>

followed by a <new line>is also accepted. Command string termination will always reset the current SCPI command path to the root level.

2.3. Command separators

A colon (:) is used to separate a command keyword from a lower-level keyword as shown below:

SOURce1:CURRent:PROTection:STATe

A semicolon (;) is used to separate two commands within the same subsystem, and can also minimize typing. For example, sending the following command string,

SOURce1:VOLTage 20;CURRent 300mA

is the same as sending the following two commands:

SOURce1:VOLTage 20

SOURce1:CURRent 1.5

Use a colon and a semicolon to link commands from different subsystems. For example, in the following command string, an error is generated if you do not use the colon and semicolon:

SYSTem:BEEP;:SOURce1:CURRent 2.5

2.4. Querying parameter settings

You can query the value of most parameters by adding a question mark (?) to the command. For example, the following command sets the output voltage to 25.5 V:

VOLTage 25.5

You can query the value by executing:

VOLTage?

If error is occurred use SYSTem:ERRor[:NEXT]? to get more information about error.

2.5. Using the MIN, MAX, and DEF Parameters

For many commands, you can substitute "MIN" or "MAX" in place of a parameter. In some cases you may also substitute "DEF". For example, consider the following command:

[SOURce[<n>]]:VOLTage[:LEVel][:IMMediate][:AMPLitude] {<voltage>|MIN|DEF|MAX|UP|DOWN}

Instead of selecting a specific value for the <voltage> parameter, you can substitute MIN to set the voltage to its minimum value, MAX to set the voltage to its maximum value, or DEF to set the voltage to its default value. For list of parameter values see Section 8.1

2.6. Command and message types

SCPI commands can be divided to common and subsystem commands.

• Common commands are defined by the IEEE 488.2 standard to perform common interface functions. They begin with an * and consist of three letters (command) or three letters and a ? (query). Description of supported common commands can be found in Section 4
• Subsystem commands are specific to instrument functions. They can be a single command or a group of commands. The groups are comprised of commands that extend one or more levels below the root. See Section 5 for commands that is created in accordance to the SCPI 1999.0 standard. Commands that is not defined by SCPI 1999.0 is labeled "unclassified" and are presented in Section 6

There are two types of SCPI messages, program and response.

• A program message consists of one or more properly formatted SCPI commands sent from the controller to the instrument. The message, which may be sent at any time, requests the instrument to perform some action.
• A response message consists of data in a specific SCPI format sent from the instrument to the controller. The instrument sends the message only in response to a query header.

2.7. Required Commands

The following commands are required in all SCPI instruments (see SCPI 1999.0 Section 4.2.1):

 

Mnemonic	SCPI 1999.0 Command Reference Section	SCPI 1999.0 Syntax and Style Section
:SYSTem
:ERRor	21.8
[:NEXT]?	21.8.3e	1996
:VERSion?	19.16	1991
:STATus	18	5
:OPERation
[:EVENt]?
:CONDition?
:ENABle
:ENABle?
:QUEStionable
[:EVENt]?
:CONDition?
:ENABle
:ENABle?
:PRESet

2.7.1. Base functionality for the Power supply instrument class

SCPI Command	Description
OUTPut
[:STATe] <bool>	Enables the specified output channel(s)
[SOURce[<n>]]
CURRent
[:LEVel]
[:IMMediate][:AMPLitude] <current>	Sets the output current
VOLTage
[:LEVel]
[:IMMediate][:AMPLitude] <voltage>	Sets the output voltage

 

All SCPI power supplies shall implement the status reporting structure. STATus Subsystem defines the commands which shall be used to control the status reporting structure.

For a power supply, the bits of interest in the QUEStionable status structure are VOLTage and CURRent. When a power supply is operating as a voltage source, bit 1 (CURRent) shall be set. When a power supply is operating as a current source, bit 0 (VOLTage) shall be set. When the output is unregulated, both bits shall be set (for example, while the output is changing to a new programmed value).

2.8. Multiple Commands in a Message

Multiple SCPI commands can be combined and sent as a single message with one message terminator. There are two important considerations when sending several commands within a single message:

• Use a semicolon to separate commands within a message.
• There is an implied header path that affects how commands are interpreted by the BB3.

The header path can be thought of as a string that gets inserted before each command within a message. For the first command in a message, the header path is a null string. For each subsequent command the header path is defined as the characters that make up the headers of the previous command in the message up to and including the last colon separator. An example of a message with two commands is:

OUTPut:STATe ON,CH1;PROTection:CLEar CH1

which shows the use of the semicolon separating the two commands, and also illustrates the header path concept. Note that with the second command, the leading header OUTPut was omitted because after the OUTPut:STATe ON command, the header path became defined as OUTPut and thus the instrument interpreted the second command as:

OUTPut:PROTection:CLEar CH1

In fact, it would have been syntactically incorrect to include the OUTPut explicitly in the second command, since the result after combining it with the header path would be:

OUTPut:OUTPut:PROTection:CLEar CH1

which is incorrect.

 

You can combine common commands (IEEE488) with subsystem commands in the same message. Treat the common command as a message unit by separating it with a semicolon (the message unit separator). Common commands do not affect the header path; you may insert them anywhere in the message.

*TST?;SYSTem:ERRor?

2.9. Moving Among Subsystems

In order to combine commands from different subsystems, you need to be able to reset the header path to a null string within a message. You do this by beginning the command with a colon (:), which discards any previous header path. For example, you could clear the output protection and check the status of the Operation Condition register in one message by using a root specifier as follows:

OUTPut:PROTection:CLEar CH1;:STATus:OPERation:CONDition?

The following message shows how to combine commands from different subsystems as well as within the same subsystem:

SOURce1:VOLTage:LEVel 7.5;:VOLTage:PROTection:DELay 10;:CURRent:LEVel 0.5

Note the use of the optional header LEVel to maintain the correct path within the subsystems, and the use of the root specifier to move between subsystems.

2.10. SCPI parameter types

The SCPI language defines several different data formats to be used in program messages and response messages:

 

Numeric	Commands that require numeric parameters will accept all commonly used representations of numbers like integer (also known as NR1 format specified in ANSI X3.42-1990) or decimal representations of numbers including optional signs, decimal points (NR2 format), and scientific notation (i.e. 10E3 or NR3 format). Special values for numeric parameters like MINimum, MAXimum, and DEFault are also accepted. You can also send engineering unit suffixes (V, A, or SEC) with numeric parameters. If only specific numeric values are accepted, the BB3 will automatically round the input numeric parameters. The following command uses a numeric parameter: VOLT:STEP {<step>}
Discrete	Used to program settings that have a limited number of values such as BUS and IMM or CH1 and CH2. Query responses will always return the short form in all uppercase letters. The following command uses discrete parameters: CAL:CURR:LEV {MIN|MID|MAX}
Boolean	Represent a single binary condition that is either true or false. For a false condition, the BB3 will accept OFF or 0. For a true condition, the BB3 will accept ON or any nonzero value (i.e. 1 but also 2.34 or -3). When you query a Boolean setting, the BB3 will always return 0 or 1. The following command uses a Boolean parameter: OUTP {OFF|ON}
String	Can contain virtually any set of ASCII characters. A string must begin and end with matching quotes, either with a single quote or with a double quote. You can include the quote delimiter as part of the string by typing it twice without any characters in between. The following command uses a string parameter: CAL:REM <quoted string>
Data block	#<length-digits><length><block>
	<length-digits>	NR1	<length> number of digits (e.g. 2 for two digit number)
	<length>	NR1	Limited only with available space on SD card
	<block>	Discrete	Only exact size is allowed as defined with <length>
	Downloads text Hello world and store into the file "test file" in the current directory. Digit 2 denotes two digits of data length (11). MMEM:DOWN:FNAM "test file" MMEM:DOWN:DATA #211Hello world MMEM:DOWN:FNAM ""
Channel	Channel number of the power module can be specified as discrete (e.g. CH1, CH2, etc.) or in format (@ncc) where n is the slot number, and cc is the channel number. Channels that belongs to the relay matrix module (SMX46) should be defined as (@nrc) where n is the slot number, r is the row number and c is the column number.
Channel list	The channel list parameter is used for identifying the channel number as well as the numeric suffix. A channel list always starts with an @ and is enclosed in parentheses.   The notation (@1,2) specifies a channel list that includes channels 1 and 2. The notation (@2:4) specifies a channel list that includes channels 2 to 4. The notation (@1,3:4) specifies a channel list that includes channels 1, 3 and 4. No space is allowed after or before comma separator.   The channel list parameter is only available on certain commands.