SCPI

Description

The SCPI driver enables the control of one or multiple devices operated by the Standard Commands for Programmable Instruments (SCPI). The SCPI driver can operate over TCP/IP using an Ethernet physical link. It is the user's responsibility to select the communication protocol that matches the network configuration.

For more information about the standard consult the SCPI: Syntax and Style documentation.

Supported features

The following is a list of the features supported by the driver:

Initial commands	These commands are sent at the beginning of the simulation. These are useful to ensure that the SCPI device is in the proper operation configuration.
Measurements	Measurements can be used to collect numeric data from the SCPI device during runtime. The measurement commands can be sent based on a defined cyclic rate or based on a trigger data point.
Controls	Controls can be used to set SCPI device parameters during runtime. The control commands can be sent with a value from the model according to a defined cyclic rate. These commands can also be sent based on a trigger from the model.
Reset commands	These commands are sent at the reset of the model to set the device to the desired post-simulation state.

Allows multiple SCPI device control.
Allows configurable TCP port when operating over TCP mode.
Supports reconnection with the SCPI device(s) if a connection is lost.
Embedded support of a basic command set for the Keysight RP79xx family.

Configuration

The driver is entirely configurable via the RT-LAB interface. Users can add, delete and duplicate SCPI devices and configure their commands. Configuring SCPI commands requires a basic comprehension of the standard and a knowledge of the device's command set.

General configuration

The first parameters to be configured are:

Use an RT core for asynchronous computation:
- If set to true, the driver reserves a real-time CPU core for its communication system and will be able to handle a bigger amount of data.
- If set to false, the communication system will default to core 0.
Verbose: If enabled, additional information will be displayed during the load of the model.

SCPI configuration

By default, the driver is configured with one TCP SCPI device using the internal loopback network on port 5025.

The next image shows an SCPI device configured with TCP/IP.

Each SCPI device has multiple parameters:

Device: Two choices are available:

Keysight RP79xx: When selected a set of default commands compatible with an RP79xx device are automatically configured.
Custom: This type can be selected to fully customize a set of commands.

CAUTION: When you modify this field from Custom to Keysight RP79xx, all the configured commands are replaced by the default Keysight RP79xx command set.

Mode	Only TCP is available. TCP specific parameters: NIC name: The desired network interface name. The proper interface name should be selected based on the information given by the Linux command "ifconfig". If the driver is running on Windows this field will be ignored. IP address: The IP address of the SCPI device. TCP port: Select the TCP port on which the SCPI device waits for a connection. The default port is 5025 as the standard defines it.
Cycle rate (ms)	Defines the rate (in milliseconds) at which the cyclic control commands are sent and the cyclic measurements are fetched from the SCPI device.
Wait time (ms)	Some equipment is not able to reply properly when multiple commands are sent too fast. Use this option to increase the number of milliseconds to wait before the transmission of each command.
Log SCPI data to a CSV file	This option is useful for debugging. If enabled, the SCPI data sent and received will be logged in a CSV file. The columns of this file are separated by a ';' (semicolon). This file will be transferred in the host sub-system folder during the reset of the model. To find this file after the reset of the model, search for SCPI.csv* pattern in a Windows File Explorer opened at the location of your RT-LAB project.

An example of the file is given below.

Timestamp	Direction (TX: Opal-RT → SCPI)	Data
13576	TX	:OUTP:INH:MODE LIVE\n
13676	TX	:SOUR:CURR:LIM:POS:IMM:AMPL 2\n
13777	TX	:SOUR:CURR:LIM:NEG:IMM:AMPL -2\n
17397	TX	:SOUR:VOLT:LEV:IMM:AMPL 1\n
17497	TX	:MEAS:SCAL:CURR:DC?\n
17497	RX	1.000001\n

Enable automatic command formatting: If enabled, the SCPI command will be prepended with ':' character, and the end-of-line character '\n' will be appended at the end of each command sent.
- SCPI terminators: Only modifiable if the 'enable automatic command formatting' option is disabled. This option allows specifying the characters that will be appended to the configured commands.

The four next sub-sections describe the four types of commands available in the driver.

Initial commands

The initial commands based on the default Keysight RP79xx device configuration are shown in the image below. Details will follow.

The two modifiable fields are:

Name: A specific name describing the command. This name must be unique within the initial commands.
- SCPI command: The SCPI command to be sent at the beginning of the simulation.
  The commands must not contain a question mark ('?'), begin with ':' or end with ';'.

Measurements

The measurements based on the default Keysight RP79xx device configuration are shown in the image below. Details will follow.

The two modifiable fields are:

Name: A specific name describing the command. This name must be unique within the measurements. A model input connection point will be instantiated with this name.
- SCPI command: The SCPI command to be sent at every cycle rate (ms) to fetch a measurement.
  The measurement commands must contain a question mark ('?'), however, they must not begin with ':' or end with ';’.
- Request on trigger: If enabled, a trigger model output data point will be created and the SCPI measure will be fetched when this trigger data point will reach the value of 1. If disabled, the SCPI measure command will be sent according to the configured cycle rate (ms).

If the SCPI device returns an alpha-numeric measurement, only the numeric value will be returned to the model. It is possible to see the complete returned message in the RT-LAB console at the pause of the model if the verbose mode is enabled.
If the SCPI device returns a complete string measurement an error message will be logged in the RT-LAB console at the pause of the model.

Controls

The controls based on the default Keysight RP79xx device configuration are shown in the image below. Details will follow.

The three modifiable fields are:

Name: A specific name describing the command. A model output connection point is instantiated with this name. If this name is not unique the command will be sent based on the trigger value configured.
- SCPI command: The SCPI command to be sent.
  The commands must not contain a question mark ('?'), begin with ':' or end with ';'.
- Send on trigger: If enabled, the command will be sent when the trigger data point will reach the configured trigger value. If disabled, the command to send will contain the value of the model output connection point and this command will be sent at every cycle rate (ms) only if the value from the model has changed. This field is enabled when the command's name is not unique.
- Send when trigger value is: This field allows the user to defined the trigger value when the send on trigger option is enabled.
- Full SCPI command: This read-only field shows the full command that will be sent to the SCPI device. During runtime, the mark '< command name >' is replaced by the model output connection point value.

If the field trigger command on value is not enabled, the command that will be sent is composed of the model output connection point value concatenated at the end of the SCPI command. Otherwise, only the configured SCPI command is sent.

Reset commands

The reset commands based on the default Keysight RP79xx device configuration are shown in the image below.

The two modifiable fields are:

Name: A specific name describing the command. This name must be unique within the reset commands.
- SCPI command: The SCPI command to be sent at the end of the simulation.
  The commands must not contain a question mark ('?'), begin with ':' or end with ';'.

Connections

Once the driver has been configured as desired and associated with the proper model subsystem, the user will have to connect points in the model to points in the driver by using the designated RT-LAB GUI. This connection panel will show all the driver's and model's connectable points, once the model has been compiled. It is also possible to make connections to LabVIEW panels.

The connection points are classified in the following categories:

Device Name
- Measurements
  - Controls

The "Connected" connection point is available and can be used in the model to indicate if the SCPI device is connected to the simulation or not.

The "Reception error" connection point is available only when the measurements have been configured. This connection point takes the value of '1', if an error occurred during reception. Two types of error can occur:

The response of a measurement given by the SCPI device doesn't contain a number.
The SCPI device didn't answer to a request, in that case the OPAL-RT SCPI driver will attempt to reconnect to the SCPI device.

To troubleshoot these types of error, the 'Log SCPI data to a CSV file' option can be used to investigate how the SCPI device is reacting. Also, to retrieve the log from the SCPI driver after the reset of the model, the model must be put in exhaustive mode and the driver in verbose mode.

Under each category, the configured operations will show-up with the command names that have been given by the user in the driver configuration GUI. If the icon is blue, it is a model output and this signal is returned to the simulation at the beginning of each time step. It means that this signal needs to be connected to an OpInput block of the Simulink model. If the icon is red, it is a model output. It means that this signal needs to be connected to an OpOutput block of the Simulink model.

The next figure shows the connection points instantiated with the configuration showed above.

We can see that the measurement command Voltage value and the control command Output state are configured with a trigger.

Limitations

The following is a list of the limitations of the driver:

Question mark (?) is only allowed with measurements.
- Only TCP mode is available.
- Only scalar measurements are reported to the model during runtime. A non-numerical answer of a measurement command will only be printed in the RT-LAB console at the reset of the model if the model is in exhaustive mode and the driver verbose mode is enabled.