Fact 1. Learn SCPI Basics
It's easy to send a command to FlexOTO. Simply create a command string from the various commands, and place the string in your program language's output statement. For commands other than common commands, include a colon before the subsystem name. Commands can be sent using any combination of uppercase or lowercase ASCII characters. FlexOTO responses, however, are always returned in uppercase.
Program Message Terminator
The FlexOTO SCPI commands sent within a data message are executed by FlexOTO after the program message terminator is received. The terminator may be one of the following types:
- ASCII NL (new line) character ("\n", decimal 10, hex 0A)
- Combination CR (carriage return) and NL characters ("\r\n", decimal 13/10, hex 0D/0A). If you use the Keysight IO Monitor that is provided with Connection Expert, note that the CR character is represented by a "." (period) within the monitor.
- EOI (End-Or-Identify) asserted in the GPIB interface
Asserting the EOI sets the EOI control line low on the last byte of the data message. The NL (New Line) terminator has the same function as an EOS (End Of String) and EOT (End Of Text/Transmission) terminator.
Short or Long Forms
Commands and queries may be sent in either long form (complete spelling) or short form (abbreviated spelling). The description for each command shows both versions; the extra characters for the long form are shown in lowercase. However, commands can be sent using any combination of uppercase or lowercase ASCII characters. FlexOTO responses, however, are always returned in uppercase. Programs written in long form are easily read and are almost self-documenting. Using short form commands conserves the amount of controller memory needed for program storage and reduces the amount of I/O activity.
The short form is the first four characters of the keyword, unless the fourth character is a vowel. Then the mnemonic is the first three characters of the keyword. If the length of the keyword is four characters or less, this rule does not apply, and the short form is the same as the long form. For example:
:TIMEBASE:POSITION 1E-6
is the long form, and
:TIM:POS 1E-6
is the short form.
| Long Form | Short Form | How the Rule is Applied |
|---|---|---|
| BRATE | BRAT | Short form is the first four characters of the keyword. |
| DELAY | DEL | Fourth character is a vowel, short form is the first three characters. |
| PATTERN | PATT | Short form is the first four characters of the keyword. |
| DISK | DISK | Short form is the same as the long form. |
| SAVE | SAVE | Short form is the same as the long form. |
White Space
White space is defined to be one or more characters from the ASCII set of 0 through 32 decimal, excluding 10 (NL). White space is usually optional, and can be used to increase the readability of a program.
Adding Parameters to a Command
Many commands have parameters that require an argument. Use a space character to separate the argument from the command as shown in the following line:
:TIMEBASE:SCALE 100E-6
String Arguments
Strings contain groups of alphanumeric characters which are treated as a unit of data by FlexOTO. You may delimit embedded strings with either single (') or double (") quotation marks. Strings are case-sensitive, and spaces act as legal characters just like any other character. For example, this command saves a setup file:
:DISK:SETup:SAVE "Test4Setup.setx"
Numbers
Some commands require number arguments. All numbers are expected to be strings of ASCII characters. You can use exponential notation or suffix multipliers to indicate the numeric value. The following numbers are all equal:
28 = 0.28E2 = 280E-1 = 28000m = 0.028K
When a syntax definition specifies that a number is an integer, any fractional part is ignored and truncated. Using "mV" or "V" following the numeric voltage value in some commands will cause an error. Instead, use the convention for the suffix multiplier.
| Value | Mnemonic |
|---|---|
| 1E18 | EX |
| 1E15 | PE |
| 1E12 | T |
| 1E9 | G |
| 1E6 | MA |
| 1E3 | K |
| 1E−3 | m |
| 1E−6 | u |
| 1E−9 | n |
| 1E−12 | p |
| 1E−15 | f |
| 1E−18 | a |
| Suffix | Referenced Unit |
|---|---|
| V | Volt |
| s | Second |
| W | Watt |
| BIT | Bits |
| dB | Decibel |
| % | Percent |
| Hz | Hertz |
Infinity Representation
The representation for infinity for this instrument is 9.99999E+37. This is also the value returned when a measurement cannot be made.
Queries
Command headers immediately followed by a question mark (?) are queries. After receiving a query, the instrument interrogates the requested subsystem and places the answer in its output queue. The answer remains in the output queue until it is read or until another command is issued. When read, the answer is transmitted across the bus to the designated listener (typically a computer). For example, the query:
:TIMEBASE:SCALE?
places the horizontal timebase scale setting in the output queue. Use your programming environment's input statement to pass the value across the bus to the computer and places it in a variable. Queries can be used to discover how the FlexOTO is currently configured as well as return measurement results. For example, the command:
:MEASURE:EYE:RISETIME?
tells FlexOTO to measure the rise time of your eye diagram and place the result in the output queue. The output queue must be read before the next program message is sent. For example, when you send the query :MEASURE:EYE:RISETIME? you must follow it with an input statement. If you send another command or query before reading the result of a query, the output buffer is cleared and the current response is lost. This also generates a query-interrupted error in the error queue. If you execute an input statement before you send a query, it will cause the computer to wait indefinitely.
If a measurement cannot be made because of the lack of data, because the source signal is not displayed, the requested measurement is not possible (for example, a period measurement on an FFT waveform), or for some other reason, 9.99999E+37 is returned as the measurement result.
Endiannes of Returned Binary Block Data
To specify the byte order of binary data that is returned in response to a query, use the :SYSTem:BORDer command.
NaN (Not A Number)
NaN is represented by 9.91E+37.
Sequential and Overlapped Commands
IEEE 488.2 makes a distinction between sequential and overlapped commands. Sequential commands finish their task before the execution of the next command starts. Overlapped commands run concurrently. Commands following an overlapped command may be started before the overlapped command is completed. The common commands *WAI and *OPC may be used to ensure that commands are completely processed before subsequent commands are executed.
The *OPC Command and *OPC? Query
The *OPC command sets bit 0 in the Standard Status Event Register when all pending device operations have finished. (Use *ESR? to query the register.) The *OPC command is useful for verifying the completion of commands that could take a variable amount of time or commands executed in parallel with other commands, such as :SYSTem:AUToscale. The *OPC command does not stop the execution of the remote script.
The *OPC? query allows synchronization between the computer and FlexOTO by using the message available (MAV) bit (bit 4 in the Status Byte) or by reading the output queue. (Use *STB? to query the Status Byte register.) Unlike the *OPC command, the *OPC? query does not affect the OPC event bit in the Standard Event Status Register. The execution of the remote script is halted and therefore the *OPC? query should be used judiciously. For example, running a acquisition limit test with the command string,
:LTESt:ACQuire:STATe ON
:ACQuire:RUN;*OPC?
locks the remote interface until specified number of acquisitions are completed, which could take some time. The *OPC topic provides a list of commands that require *OPC?.
The *WAI Command
The *WAI command is similar to the *OPC? query as it also blocks the execution of the remote script until all pending operations are finished. *WAI is particularly useful if the host computer is connected to FlexOTO and one or more instruments. This command will not block the GPIB bus, allowing the computer to continue issuing commands to FlexOTO or an instrument that is not executing the *WAI command.
SCPI Tree
In accordance with IEEE 488.2, the instrument's commands are grouped into subsystems. Commands in each subsystem perform similar tasks. The command tree refers to the relationship of the commands to each other. You can view this relationship in the SCPI Remote Command Tree Viewer. The IEEE 488.2 common commands do not affect the position of the parser within the tree. A leading colon or a program message terminator (<NL> or EOI true on the last byte) places the parser at the root of the command tree. A leading colon is a colon that is the first character of a program header. Executing a subsystem command places you in that subsystem until a leading colon or a program message terminator is found.
The commands can be placed into two types: common commands and subsystem commands. Common commands (defined by IEEE 488.2) control functions that are common to all IEEE 488.2 instruments. These commands are independent of the tree and do not affect the position of the parser within the tree. *RST is an example of a common command. Subsystem commands are grouped together under a common node of the command tree, such as the :SYSTem commands. Only one subsystem may be selected at a given time. When FlexOTO is initially started, the command parser is set to the root of the command tree and no subsystem is selected.