# Welcome to SCPI Device’s documentation!

Contents:

## How to write a SCPI device

### Introduction

From wikipedia: ‘The Standard Commands for Programmable Instruments (SCPI) (often pronounced “skippy”) defines a standard for syntax and commands to use in controlling programmable test and measurement devices.’

The terms ‘instrument’ and ‘device’ will be used when when referring to hardware instruments and software (Karabo) devices, respectively.

### Supported interfaces

The base class currently supports TCP/IP, USB and serial communication with the SCPI instrument. The interface can be set-up by means of the `Instrument URL` device property. The URL must contain a scheme and a path. If no scheme is specified, ‘socket’ is assumed.

In case of TCP/IP communication the scheme to be used is ‘socket’ or ‘tcp’ and the path must contain the hostname and port separated by a colon, namely ‘socket://hostname:port’ or ‘tcp://hostname:port’.

In case of serial interface the scheme to be used is ‘serial’ and the path must contain the file pointer to the serial port (e.g. /dev/ttyUSB0). The other mandatory parameter is the baud rate, to be specified in the query part of the URL. A minimal serial URL would be for example ‘serial:///dev/ttyUSB0?baudRate=57600’. Optional parameters like ‘dataBits’, ‘stopBits’ and ‘parity’ can be specified in the query, e.g. ‘serial:///dev/ttyUSB0?baudRate=57600&dataBits=7&stopBits=1&parity=O’.

In case of a USB interface the scheme shall be ‘usb’ and the path shall contain the vendor and product ID separated by a colon, namely ‘usb://idVendor:idProduct’. In case more than one USB device of the same kind is attached to the computer, you must also give its serial number or the bus and address in the query part of the URL to unambiguously identify one of them. For example ‘usb://2457:1012?serialNumber=SN12345’ or ‘usb://2457:1012? bus=003&address=002’. In order to find out the correct values of the parameters, you can run in a terminal the `lsusb -v` command .

### How to Create a SCPI Karabo Device

Create a python Karabo Device, called for example myScpiDevice:

    ./karabo new myScpiDevice python

Go into the base directory of the project:

    cd karabo/devices/myScpiDevice

Add a plaintext file named DEPENDS that contains the scpi version tag, like this:

    #package, Branch
    scpi, 2.1.0-2.16.5

Do not forget to add the DEPENDS file to the repository:

    git add DEPENDS

Now you can open the source file, MyScpiDevice.py, for editing.

### Base Device Classes

There are currently three base classes available for SCPI devices: `ScpiDevice`, `ScpiOnOff`, `ScpiStartStop`.

`ScpiDevice` is the simplest one. It has only three states: `UNKNOWN` (i.e. the software device is not connected to the hardware), `NORMAL` (i.e. the hardware is functional) and `ERROR` (i.e. the hardware is returning some error).

`ScpiOnOff` has five states: `UNKNOWN`, `ERROR`, `ON`, `OFF` and `CHANGING` (e.g. for when the hardware is switching between `ON` and `OFF`). This class is suitable for example for power supplies.

`ScpiStartStop` has also five states: `UNKNOWN`, `ERROR`, `STARTED`, `STOPPED` and `CHANGING` (e.g. for when the hardware is switching between `STARTED` and `STOPPED`). This class is suitable for example for measurement devices.

### Writing a Device

#### Writing a Simple SCPI Device

The base class to be used is `ScpiDevice`. The device is very simple and should look like:

    ############################################################################
    # Author: <john.smith@xfel.eu>
    # Created on March 29, 2023
    # Copyright (C) European XFEL GmbH Schenefeld. All rights reserved.
    ############################################################################

    from karabo.bound import KARABO_CLASSINFO

    from scpi.scpi_device import ScpiDevice
    from ._version import version as deviceVersion

    @KARABO_CLASSINFO("MyScpiDevice", deviceVersion)
    class MyScpiDevice(ScpiDevice):

        def __init__(self, configuration):
            # always call superclass constructor first!
            super().__init__(configuration)

            self.commandTerminator = "\r\n" # The command terminator

        @staticmethod
        def expectedParameters(expected):
            (
            # Fill here with the list of expected parameters
            )

The SCPI parameters can be accessed using Karabo expected parameters (see the Expected Parameters Section for details).

#### Writing an On/Off Device

The base class to be used is `ScpiOnOff`. The device should look pretty much like the Ok/Error one, except for the base class to be used.

You will also need to define an `alias` for the `on` and `off` slots, see the Expected Parameters Section for details).

    ############################################################################
    # Author: <john.smith@xfel.eu>
    # Created on March 29, 2023
    # Copyright (C) European XFEL GmbH Schenefeld. All rights reserved.
    ############################################################################

    from karabo.bound import (
        KARABO_CLASSINFO, OVERWRITE_ELEMENT
    )

    from scpi.scpi_on_off import ScpiOnOff
    from ._version import version as deviceVersion

    @KARABO_CLASSINFO("MyScpiDevice", deviceVersion)
    class MyScpiDevice(ScpiOnOff):

        def __init__(self, configuration):
            # always call superclass constructor first!
            super().__init__(configuration)

            self.commandTerminator = "\r\n" # The command terminator

        @staticmethod
        def expectedParameters(expected):
            (
            # Define alias for the "on" slot
            OVERWRITE_ELEMENT(expected).key("on")
            .setNewAlias("OUTP ON;;;;")
            .commit(),

            # Define alias for the "off" slot
            OVERWRITE_ELEMENT(expected).key("off")
            .setNewAlias("OUTP OFF;;;;")
            .commit(),

            # Fill here with the list of expected parameters
            )

By default the `on` and `off` slots will send the corresponding SCPI command and immediately change device state (to respectively `ON` and `OFF`). In case the switch takes some time, and the instrument has some property which can be used to evaluate its actual state, this default behaviour shall be overridden, e.g.

    @staticmethod
    def expectedParameters(expected):
        (
        [...]

        # This parameter is tagged as 'poll', thus the query 'OUTP?' will
        # be sent periodically and the Karabo device updated accordingly.
        BOOL_ELEMENT(expected).key("isOn")
        .tags("scpi,poll")
        .alias(";;OUTP?;{isOn:b};")
        .displayedName("Device is ON")
        .description("True when the device is ON.")
        .readOnly()
        .commit(),
        )

    # Overrides ScpiOnOff.on()
    def on(self):
        self["status"] = "Being switched on"
        self.updateState(State.CHANGING)
        self.sendCommand("on")
        # followHardwareState() will take care of updating the state when
        # the hardware is done.

    # Overrides ScpiOnOff.off()
    def off(self):
        self["status"] = "Being switched off"
        self.updateState(State.CHANGING)
        self.sendCommand("off")
        # followHardwareState() will take care of updating the state when
        # the hardware is done.

    # This function will be called at the end periodic device poll
    def followHardwareState(self):
        is_on = self["isOn"]
        state = self["state"]

        if state in (State.CHANGING, State.OFF) and is_on:
            self.log.INFO('Follow hardware state -> ON')
            self.updateState(State.ON)
        elif state in (State.CHANGING, State.ON) and not is_on:
            self.log.INFO('Follow hardware state -> OFF')
            self.updateState(State.OFF)

#### Writing a Start/Stop Device

The base class to be used is `ScpiStartStop`. Similarly to the On-Off one, you will need to define here aliases for the `start` and `stop` slots. You will also need to provide a `processAsyncData` function to process the data that are received asynchronously during a measurement.

The device should look like

    ############################################################################
    # Author: <john.smith@xfel.eu>
    # Created on March 29, 2023
    # Copyright (C) European XFEL GmbH Schenefeld. All rights reserved.
    ############################################################################

    from karabo.bound import (
        KARABO_CLASSINFO, OVERWRITE_ELEMENT
    )

    from scpi.scpi_start_stop import ScpiStartStop
    from ._version import version as deviceVersion

    @KARABO_CLASSINFO("MyScpiDevice", deviceVersion)
    class MyScpiDevice(ScpiStartStop):

        def __init__(self, configuration):
            # always call superclass constructor first!
            super().__init__(configuration)

            self.commandTerminator = "\r\n" # The command terminator

        @staticmethod
        def expectedParameters(expected):
            (
            # Define alias for the "start" slot
            OVERWRITE_ELEMENT(expected).key("start")
            .setNewAlias("INIT;;;;")
            .commit(),

            # Define alias for the "stop" slot
            OVERWRITE_ELEMENT(expected).key("stop")
            .setNewAlias("ABORT;;;;")
            .commit(),

            # Fill here with the list of expected parameters
            )
        # Use this one to process asynchronously received data and possibly
        # update device properties.
        def processAsyncData(self, data):
            pass

Also in the case of `ScpiStartStop` the `start` and `stop` will send the respective SCPI command and change immediately the device state. The default behaviour can be changed as described in the previous section.

#### How to read/write parameters from/to the instrument

Each parameter on the instrument you want to expose in the Karabo device must have a corresponding expected parameter in the Karabo device. The expected parameter must be tagged as `scpi`. Please have a look at the Expected Parameters Section for the details.

#### How to deal with asynchronous instrument messages

To parse unexpected messages (e.g. error message) that may come while instrument is polled [Note that this violates SCPI specifications] the method `parseAsyncStrings()` can be implemented in the derived class.

### Expected Parameters

#### Tags

- `scpi` tag: Parameters to be read from (written to) the SCPI instrument must have the `scpi` tag.
- `readOnConnect` and `writeOnConnect` tags: Parameters having the `readOnConnect` (respectively `writeOnConnect`) flag will be read from (written to) the instrument when the Karabo device connects to it.
- `poll` tag: Parameters having the `poll` tag will be polled periodically. The poll interval is a parameter of the base class.

#### The `sendOnConnect` Parameter

Commands to be sent to the instrument when the Karabo device connects to it (for example some initial configuration), can be listed in the `__init__` function. For example:

    self.sendOnConnect = ['TRIG:LEV 10', 'TRIG:SOURCE EXT', 'SYST:COMM:SER:BAUD 19200']

These commands will be sent before the expected parameters with `writeOnConnect` tag (see Tags Section).

#### The `sendOnReset` Parameter

Commands to be sent to the instrument when executing the `reset` command, can be listed in the `__init__` function. For example:

    self.sendOnReset = ['Reset Uc']

#### Aliases

The SCPI commands and queries corresponding to writing and reading any parameter must be written in the parameter `alias`. Different fields in the `alias` have to be separated by semicolons (;) or a different separator (as explained in The aliasSeparator Parameter Section). For example:

    INT32_ELEMENT(expected).key("resolutionMode")
            .tags("scpi poll")
            .alias(">S1H {resolutionMode};E0;>S1H?;S1H:{resolutionMode:d};")
            .displayedName("Current Resolution Mode")
            .description("Set the current resolution mode (0=normal 1=high resolution).")
            .assignmentOptional().defaultValue(0)
            .options("0 1")
            .allowedStates(State.ON, State.OFF)
            .reconfigurable()
            .commit(),

The first field in the `alias` contains the set command (ie `>S1H`) and its parameters (ie `{resolutionMode}`) for the `resolutionMode`. This string will be parsed, and `{resolutionMode}` will be replaced by the configuration value corresponding to the key. The second field (ie `E0`) is the expected reply to the set command; it is also parsed to extract parameters (none in this example).

The third field contains the query command (ie `>S1H?`) and its parameters (none). The fourth field (ie `{resolutionMode:d}`) is the expected reply to the query; it is parsed and `resolutionMode` is extracted as integer (`d`). The parsing is done by using the python parse package (see documentation), therefore all types defined there can be used:

Type | Characters Matched | Output
--- | --- | ---
w | Letters and underscore | str
W | Non-letter and underscore | str
s | Whitespace | str
S | Non-whitespace | str
d | Digits (effectively integer numbers) | int
D | Non-digit | str
n | Numbers with thousands separators (, or .) | int
% | Percentage (converted to value/100.0) | float
f | Fixed-point numbers | float
e | Floating-point numbers with exponent e.g. 1.1e-10, NAN (all case insensitive) | float
g | General number format (either d, f or e) | float
b | Binary numbers | int
o | Octal numbers | int
x | Hexadecimal numbers (lower and upper case) | int
ti | ISO 8601 format date/time e.g. 1972-01-20T10:21:36Z (“T” and “Z” optional) | datetime
te | RFC2822 e-mail format date/time e.g. Mon, 20 Jan 1972 10:21:36 +1000 | datetime
tg | Global (day/month) format date/time e.g. 20/1/1972 10:21:36 AM +1:00 | datetime
ta | US (month/day) format date/time e.g. 1/20/1972 10:21:36 PM +10:30 | datetime
tc | ctime() format date/time e.g. Sun Sep 16 01:03:52 1973 | datetime
th | HTTP log format date/time e.g. 21/Nov/2011:00:07:11 +0000 | datetime
ts | Linux system log format date/time e.g. Nov 9 03:37:44 | datetime
tt | Time e.g. 10:21:36 PM -5:30 | time

In addition, two extra types can be used for the SCPI devices:

Type | Characters Matched | Output
--- | --- | ---
p | All printable characters | str
P | All non-printable characters | str

#### The `aliasSeparator` Parameter

The separator for the fields in the `alias` is by default the semicolon (;), but can be changed to a different one in the `__init__` function; for example:

    self.aliasSeparator = "|"

will change it to the pipe character (|).

#### The `initialConnectedState` Parameter

It defines which will be the device state after successful connection to the remote instrument. It is set to `State.NORMAL` for a `ScpiDevice`, to `State.OFF` for a `ScpiOnOffDevice` and to `State.STOPPED` for a `ScpiStartStopDevice`.

#### The `commandPrefix` and `terminator` Parameters

The command prefix and terminator - to be used in the communications between the Karabo device and the SCPI instrument - can be set in two different ways. For a given device, the command prefix and terminator are usually known and fixed, therefore should be hard-coded in the Karabo device. This can be done by adding lines like these to the `__init__` function:

    self.commandTerminator = "\r\n" # The command terminator

    self.commandPrefix = "*" # all command strings starts with
                             # asterisk ('*') char

The second way to set command prefix and terminator is by adding the `commandPrefix` and/or `terminator` expected parameters. This should be done for “generic” devices, for which different prefixes and terminators should be available at instantiation time. For example:

    # Re-define default value and options
    STRING_ELEMENT(expected).key("terminator")
            .displayedName("Command Terminator")
            .description("The command terminator.")
            .assignmentOptional().defaultValue("\\n")
            .options("\\n \\r \\r\\n")
            .init()
            .commit(),

    # Re-define default value and options
    STRING_ELEMENT(expected).key("commandPrefix")
            .displayedName("Command Prefix")
            .description("The command prefix.")
            .assignmentOptional().defaultValue("")
            .options('* > ""')
            .init()
            .commit(),

If the terminator is not set in the Karabo device, the default one will be used for communications with the SCPI instrument: `\n`. If the command prefix is not set in the Karabo device, the default one will be used for communications with the SCPI instrument: `''` (empty string i.e. no prefix).

#### The `responsePrefix` and `responseTerminator` Parameters

In addition to the command prefix and terminator described in the previous section, prefix and terminator for responses can be optionally set. If response prefix/terminator value is not set, the command prefix/terminator will be used for responses as well.

Also for the response prefix and terminator there are two ways of setting. You can use either:

    self.responseTerminator = "\0"

    self.responsePrefix = ">"

in the `__init__` function, or add the `responsePrefix` and/or `responseTerminator` expected parameter. This second option should be used for “generic” devices, as explained in the previous section.

#### The `scpiTimeout` Parameter

The default scpi communication timeout used in the base class is 1 second. This value is normally ok, but some instruments (eg the agilentMultimeterPy) may need a longer time to give back a measurement.

The scpi timeout (in seconds) can be changed in `__init__` with something like:

    self.scpiTimeout = 5.0 # New timeout value in seconds

A second way to set it is by adding the `scpiTimeout` expected parameter. In this way the timeout can be changed during the lifetime of the Karabo device. For example:

    FLOAT_ELEMENT(expected).key("scpiTimeout")
            .displayedName("SCPI Timeout")
            .description("The scpi communication timeout.")
            .unit(Unit.SECOND)
            .assignmentOptional().defaultValue(1.0)
            .reconfigurable()
            .commit(),

If the scpi timeout is not set in the Karabo device, the default value of 1 s will be used.

#### The `scpiWaitAfterRequest` Parameter

By default there is no wait time between two consecutive queries or commands, in the base class. This means: as soon as the reply comes from the instrument, the next query or command is sent. There is the possibility to modify the wait time in `__init__` by doing

    self.scpiWaitAfterRequest = 0.01 # New wait time in seconds

or by adding a `scpiWaitAfterRequest` element to the expected parameters.

#### The `socketTimeout` Parameter

The default TCP socket timeout used in the base class is 1 second. Similarly to the scpi communication timeout, also the TCP socket timeout for the device can be set to a differene value, either in the `__init__` by doing

    self.socketTimeout = 2.0 # New timeout value in seconds

or by adding a `socketTimeout` element to the expected parameters.

#### The `usbTimeout` Parameter

The default USB timeout used in the base class is 1 second. Similarly to the other timeouts, it can be changed, either in the `__init__` by doing

    self.usbTimeout = 2.0 # New timeout value in seconds

or by adding a `usbTimeout` element to the expected parameters.

#### On/Off (and Start/Stop) Slots

For On/Off (Start/Stop) devices, the on/off (start/stop) slots are already defined. What you have to do, is to set the SCPI command in the slots’s `alias`. For example, for the start/stop:

    # Define alias for the "start" slot
    OVERWRITE_ELEMENT(expected).key("start")
            .setNewAlias("INIT;;;;")
            .commit(),

    # Define alias for the "stop" slot
    OVERWRITE_ELEMENT(expected).key("stop")
            .setNewAlias("ABORT;;;;")
            .commit(),

#### A Complete Example

Here is a complete example of expected parameters for a Start/Stop device:

    # Define alias for the "start" slot
    OVERWRITE_ELEMENT(expected).key("start")
            .setNewAlias("INIT;;;;") # No query available
            .commit(),

    # Define alias for the "stop" slot
    OVERWRITE_ELEMENT(expected).key("stop")
            .setNewAlias("ABORT;;;;") # No query available
            .commit(),

    # Re-define default value and options
    STRING_ELEMENT(expected).key("terminator")
              .displayedName("Command Terminator")
              .description("The command terminator.")
             .assignmentOptional().defaultValue("\\n")
              .options("\\n")
              .init()
              .commit(),

    STRING_ELEMENT(expected).key("handshake")
              .tags("scpi")
              .alias("SYST:COMM:HAND {handshake};;SYST:COMM:HAND?;{handshake:w};")
              .displayedName("Handshake")
              .description("Set the state of the message roundtrip handshaking.")
              .assignmentOptional().defaultValue("OFF")
              .options("OFF ON")
              .allowedStates(State.STOPPED)
              .reconfigurable()
              .commit(),

    STRING_ELEMENT(expected).key("baudRate")
              .tags("scpi")
              .alias("SYST:COMM:SER:BAUD {baudRate};;SYST:COMM:SER:BAUD?;{baudRate:w};")
              .displayedName("Serial Baud Rate")
              .description("Set the transmit and receive baud rates on the RS-232 port.")
              .assignmentOptional().defaultValue("9600")
              .options("DEFAULT 9600 19200 38400 57600 115200")
              .allowedStates(State.STOPPED)
              .reconfigurable()
              .commit(),

    INT32_ELEMENT(expected).key("errorCount")
              .tags("scpi poll")
              .alias(";;SYST:ERR:COUNT?;{errorCount:d};") # Only query available
              .displayedName("Error Count")
              .description("The number of error records in the queue.")
              .readOnly()
              .commit(),

    STRING_ELEMENT(expected).key("measureType")
              .tags("scpi writeOnConnect") # Write to h/w at initialization
              .alias("CONF:MEAS:TYPE {measureType};;CONF:MEAS:TYPE?;{measureType:w};")
              .displayedName("Measure Type")
              .description("Set the meter measurement mode (energy or power).")
              .assignmentOptional().defaultValue("J")
              .options("DEFAULT J W")
              .allowedStates(State.STOPPED)
              .reconfigurable()
              .commit(),

    STRING_ELEMENT(expected).key("serialNumber")
              .tags("scpi readOnConnect") # Read from h/w at initialization
              .alias(";;SYST:INF:SNUM?;\"{serialNumber:p}\";") # Only query available
              .displayedName("Serial Number")
              .description("The serial number.")
              .readOnly()
              .commit(),

### Polling Device Properties

All the expected parameters having the `poll` tag will be automatically polled (see Tags Section). The refresh interval is given by the `pollInterval` device parameter.

An immediate refresh can be triggered by the `pollNow` command.

The list of parameters to be polled can be reconfigured be means of the `propertiesToPoll` property. For example, if you set it to `handshake,baudRate` these two properties will be polled. The access level for `propertiesToPoll` property is expert.

A user’s hook is also provided by the base class, allowing the post-processing of the polled properties. For example, if you read some temperature in Fahrenheit degrees and you want to display it in Celsius, you can define two expected parameters, like in the following:

    FLOAT_ELEMENT(expected).key("temperature")
              .displayedName("Temperature")
              .description("Blah blah.")
              .unit(Unit.DEGREE_CELSIUS)
              .readOnly()
              .commit(),

    FLOAT_ELEMENT(expected).key("temperatureFahrenheit")
              .tags("scpi poll")
              .alias(";;GETTEMP;{temperatureHex:g};")
              .displayedName("Temperature Fahrenheit")
              .description("Blah blah.")
              .expertAccess() # Only visible to expert
              .readOnly()
              .commit(),

Then, you can postprocess the polled data this way:

    def pollInstrumentSpecific(self):

        # 'temperatureFahrenheit' is a polled property
        tF = self.get('temperatureFahrenheit')

        # Convert temperatureFahrenheit into Celsius degrees
        tC = (tF - 32.) / 1.8

        # Set 'temperature' on the Karabo device, which is a derived property
        self.set('temperature', tC)

#### The `gotoErrorOnPollFailure` Parameter

If the poll of a parameter fails, an error message will be logged, but no further action will be by default taken. By setting the `gotoErrorOnPollFailure` parameter to `True`, if all parameter polls fail, the device will go to error state.

### Reading and Writing Properties on Connection

As mentioned above (see Tags Section) parameters to be sent to hardware upon connection (e.g. stored configuration values) are marked with `writeOnConnect` tag, while parameters to be retrieved from the hardware at connection are marked with `readOnConnect` tag.

The base class provides the `readOnConnectInstrumentSpecific` hook that can be optionally implemented in the derived device to perform any parsing or post processing of these parameters, similarly to `pollInstrumentSpecific`.

### Preprocessing the Incoming Reconfiguration

The base class provides a user’s hook to preprocess the incoming reconfiguration, before any command is sent to the instrument. It can be used for example when the instrument expects a parameter in some unusual units, and you would like to allow the user to input the parameter with a more standard unit.

This can be done by using two expected parameters, like in the following:

    FLOAT_ELEMENT(expected).key("temperature")
              .tags("scpi")
              .alias("SETTEMP {temperatureHex};;;;")
              .displayedName("Temperature")
              .description("Blah blah.")
              .unit(Unit.DEGREE_CELSIUS)
              .reconfigurable()
              .commit(),

    STRING_ELEMENT(expected).key("temperatureHex")
              .displayedName("TemperatureHex")
              .description("Blah blah.")
              .expertAccess() # Only visible to expert
              .readOnly()
              .commit(),

and then by coding the relation between temperature and temperatureHex in the preprocessConfiguration function,

    def preprocessConfiguration(self, inputConfig):

        if inputConfig.has('temperature'):
            # Get temperature from inputConfig, change unit,
            # represent it as bytes
            temp = inputConfig.get('temperature') # eg -23.15
            temp100 = np.int16(100*temp) # -2315
            tempBytes = temp100.tostring() # b'\xf5\xf6'
            tempHex = '%02X%02X'%(tempBytes[0], tempBytes[1]) # 'F5F6'

            self.set('temperatureHex', tempHex)

Setting a new value for `temperature` will make preprocessConfiguration called. A new value for `temperatureHex` will be set in the device, and only then the command `SETTEMP` will be sent to the instrument, with `temperatureHex` as an additional parameter.

### Postprocessing the Incoming Reconfiguration

The base class provides an additional user’s hook called when all actions defined in an incoming reconfiguration have been performed. This can be used to immediately trigger property polling after a property, e.g. ‘xyz’, has been reconfigured which is known to cause side-effects on other properties. Manipulating the polling event loop in this way reduces the period when misalignment of property values are exposed to clients.

    def postprocessConfiguration(self, inputConfig):

        if inputConfig.has('xyz'):
            self.pollTrigger = True

### Enabling the Heartbeat

The scpi Karabo device can periodically send a heartbeat query to the instrument. The default query is `*IDN?`, which should be available for all SCPI-compliant instruments. The sending of the heartbeat query is by default disabled, but it can be enabled by setting the `enableHeartbeat` property to `True`.

Once a reply to the query is received, it is published in the `heartbeatReply` property, and the `heartbeatTime` is updated as well, with the current time.

The query can be changed in the `heartbeatCommand` property, and also the time interval can be changed in the `heartbeatPeriod` property (default value is 5 s).

### Enabling Auto-Connect

Setting the `autoConnect` property `True` will enable auto connecting to the instrument when the state is `UNKNOWN`. The default property value is `False`.

### Injecting into the Schema

The `postOnConnect` hook is provided and can be used, amongst other actions, to inject properties into the schema.

For schema injection the user must control in the derived class whether multiple injection, after each connect, is required or must be prevented. The base class always calls the hook.

### Name Swapping on Write and Read

The `addValueSwap` function is used to associate a class with the key of a property. Calling addValueSwap(self, key, className) associates className with key.

The list of user friendly device swvalue value and instrument side hwvalue value associations are defined in module imported into the device. The ValueSwap class is required to be iterable and have attributes swvalue and hwvalue, and can be provided most easily by using an enum as shown below.

    @unique
    class GasTypes(ValueSwapEnum):
        N2orAir = ('N2orAir', '0')
        Ar = ('Ar', '1')
        Unknown = ('Unknown', '2')

, or are created inline

    aa = ['N2orAir', 'Ar', 'Unknown']
    bb = ['0', '1', '2']
    GasTypes = ValueSwapEnum('GasTypes', [(a, (a, b)) for a, b, c in zip(aa, bb)])

In either case the value swap must be registered.

    self.addValueSwap('xgsSensor{}.gas'.format(name), GasTypes)

Both inherit from ValueSwapEnum

    from enum import Enum, unique
    @unique
    class ValueSwapEnum(Enum):
        def __init__(self, swvalue, hwvalue):
            self.swvalue = swvalue
            self.hwvalue = hwvalue

The enum can also simplify creating expected properties.

    gas_desc = ', '.join(['{} = {}'.format(x.swvalue, x.hwvalue) for x in GasTypes])
    gas_opts = ', '.join(['{}'.format(x.swvalue) for x in GasTypes])
    gas_def = GasTypes.Unknown.swvalue

    (
        STRING_ELEMENT(expected).key('xgsSensor{}.gas'.format(name))
            .tags('scpi poll')
            .alias('4F{}{{xgsSensor{}.gas}};;4E{};{{xgsSensor{}.gas}};'.format(gauge, name, gauge, name))
            .displayedName('Gas type')
            .description('Gas type = hw id: ({})'.format(gas_desc))
            .allowedStates(State.NORMAL)
            .options(gas_opts)
            .assignmentOptional().defaultValue(gas_def)
            .reconfigurable()
            .commit(),
    )

### Sending an Arbitrary Command to the Instrument

An arbitrary command (or query) can be sent to the instrument. To do so, it is enough to write the command (or query) in the `sendCommand` device property. This property is expert access level.

Once a reply is received, it is published in the `replyToCommand` property. If no reply is received after the scpi timeout (see The scpiTimeout Parameter), `replyToCommand` is left empty.

### Query and Command Statistics

The query and command statistics are accessible at expert level,

For both queries and commands, the number of successes and failures is available, as well as the date/time of the last one. The counters will be reset on reconnection to the device.

### Initial Check of the Connection to Equipment

Some SCPI hardware equipments are connected via an intermediate interface. An example is the Lantronix, which is used to allow a remote access (via its TCP/IP address) to an RS-232-based EnergyMax instrument. If the TCP/IP and port of the Lantronix device are correctly assigned, the SCPI karabo device will successfully establish a TCP/IP connection to that port, but no error will be reported if no equipment is there connected.

In this hardware configuration, the developer should set the parameter `self.enableConnectionCheck` to `True` in the `__init__` function. This will verify an established communication by requesting the heartbeat; the proper value `Heartbeat text` (`heartbeatCommand` key) should be set according to the used equipment.

### Useful Tips for Write (Set) and Read (Get) Patterns to Use

In this section patterns for write (set) and read (get) operations are described. The tips derive from coding scpi-like instruments which are not fully compatible with the scpi-1999 standard.

#### Use Names Instead of Numbers

Using ‘ON’ and ‘OFF’ at the device interface and converting these to ‘1’ and ‘0’ when written to the instrument and reversing the procedure on reading produces an easily understandable interface for the user. This can be achieved by using name swapping as described in `Name swapping on write and read` which additionally simplifies filling in property definitions.

#### Consider Minimizing the Number Device Buttons

Most SCPI instruments are relatively simple and require only a few command actions (e.g. ‘on/off’, ‘factory reset’, ‘calibrate device’, etc.) and implementing these commands as device buttons is clean and follows the Karabo principle that commands are buttons. However, when coding multi-channel devices, it may be more appropriate to perform actions through read/write properties. This technique is used by MPOD, where O(100) channels can be present.

#### Minimize the Number of Properties Defined

Two methods to set an instrument property value are typically encountered, 1) where a set command followed by the value to set are written to the instrument, and 2) where different commands are written without a qualifying value, meaning each command represents a particular value to be set. A single command is defined to read the value set.

In the following example the type 2 set commands defined are 10 = Torr, 11 = mBar and 12 = Pascal. The read command is 13.

By moving the second character of the command into a name swap definition the number of properties defined is minimized.

    @unique
    class PressureUnits(ValueSwapEnum):
        Torr = ('Torr', '0')
        Mbar = ('mBar', '1')
        Pascal = ('Pascal', '2')

    punit_desc = ', '.join(
        ['{} = {}'.format(x.swvalue, x.hwvalue) for x in PressureUnits])
    punit_opts = ', '.join(
        ['{}'.format(x.swvalue) for x in PressureUnits])
    punit_def = PressureUnits.Mbar.value[0]

    STRING_ELEMENT(expected).key("pressureUnits")
        .tags("scpi writeOnConnect readOnConnect poll")
        .alias("1{pressureUnits};;13;0{pressureUnits};")
        .displayedName('Pressure units')
        .description('Choices are {}. Note 1: the unit is set to {}'
                     ' when the connection is established.'.format(
                      punit_names, punit_def))
        .allowedStates(State.NORMAL)
        .options(punit_opts)
        .assignmentOptional().defaultValue(punit_def)
        .reconfigurable()
        .commit(),

    self.addValueSwap('pressureUnits', PressureUnits)

#### Use Option Sets Whenever Possible

Name swapping is not a requirement of using option sets. If a property value written and the read value is an item of the same set (e.g. [‘a’, ‘b’, ‘c’]), i.e. no name swap is needed, then use the options attribute when defining the property. This has the advantage of exposing a pull down menu of the set at the gui and turning on property value validation on set and read.

#### String Comments

Command and queries exchanged between instruments and devices are character strings. It is good practise is to use the correct type (int, float…) in (Karabo) devices for a property as validation of the property type is performed automatically.

Strings are only loosely validated and devices may have to enforce requirements on string properties required by the instrument in Karabo’s preConfiguration() callback. Strings which fail requirements must not be set and an ERROR log message must be injected. Some requirements are softer, e.g. a supplied string is too long but can be set if truncated, in this case a WARN log message must be injected. It is good practice is to document format requirements in the properties description.

# Indices and tables

- Index
- Module Index
- Search Page

Read the Docs v: latest

Versions
  latest
  stable

Downloads
  pdf
  html
  epub

On Read the Docs
  Project Home
  Builds

Free document hosting provided by Read the Docs.