Sopas

The Sopas protocol is used to communicate with sensor devices from SICK AG http://www.sick.com

About the SOPAS protocol

The protocol used to communicate with SICK sensors is the SOPAS command language which utilizes command strings (telegrams) and comes in two protocol formats: CoLa A (Command Language A) with ASCII telegram format, and CoLa B with binary telegram format, not covered here. Often, the terms SOPAS and CoLa are used interchangeably, although strictly speaking the Connectware will send the SOPAS commands over the CoLa A protocol format.

The examples below explains the SOPAS communication to a SICK RFU620 RFID reading device. RFID stands for “Radio Frequency Identification” and enables reading from (and writing to) small RFID tags using radio frequency. The examples use CoLa A protocol format only, as this is supported by the example sensor RFU620. (Some SICK sensors only support CoLa A, others only CoLa B, and yet others support both.)

The SICK configuration software SOPAS ET also utilizes the SOPAS protocol to change settings of a device and retrieve data. The telegrams used for the communication can be monitored with the SOPAS ET’s integrated terminal emulator. Additional documentation with telegram listing and description of your device can be obtained from SICK either on their website or on request.

Identifying SOPAS commands

For integration of a SICK device, three different pieces of information are needed about the SOPAS commands:

  • Interface type: The telegram listing of your device will probably distinguish telegrams in events, methods and variables. However, this part is a bit tricky because the terminology sometimes varies, and sometimes you won’t find the term “variable” but only the description “Read”/”Write”.

  • Command name: Every event, method or variable is addressed using a unique string

  • Parameters: In case of variable writing or method calling some parameters may be required

The three interface types have the following characteristics:

  • Events can be subscribed to and will provide asynchronous messages

  • Methods can be called and will be executed by the device

  • Variables can be read or written, for example to adjust the configuration of the device

The telegram listing from your device’s documentation is the most important source of this information. But for getting a hint of the structure of telegrams, we will take a short look at it.

Command format

For example, a command string for the RFU620 device that can be monitored with SOPAS ET’s integrated terminal emulator could look like this:

sMN TAreadTagData +0 0 0 0 0 1

The first word in this string is the command type which in case of a request can be of the following values:

Value

Command type

Interface type

sRN

Read

variable

sWN

Write

variable

sMN

Method call

method

sEN

Event subscription

event

The command type is sMN (where M stands for “method call”, and N for the naming scheme “by name” as opposed to “by index”). This command name TAreadTagData enable us to read data from an RFID tag. Following the command name there are several space-separated parameters for the method call, for example the ID of the tag to read from. In this case we could extract the name TAreadTagData and the type method from the command string for our Commissioning File but yet don’t know the meaning of each parameter so we still have to consult the device’s telegram listing.

Example commands of RFU620

When using the RFU620 sensor to read RFID tags, the following commands are needed:

Name

Type

Parameters

Description

QSinv

event

Inventory

MIStartIn

method

Start inventory

MIStopIn

method

Stop inventory

QSIsRn

variable

Inventory running

HMISetFbLight

method

color, mode

Switch feedback light

SOPAS Command endpoints

As usual, each Cybus::Endpoint resource needs a definition of the protocol and the connection it belongs to. Here you can easily refer to the previously declared connection by using !ref and its name.

To define a SOPAS command we need to specify the desired operation as a property which can be read, write or subscribe and among this the command name and its interface type. The available operations depend on the interface type:

Type

Operation

Result

event

read

n/a

write

n/a

subscribe

Subscribes to asynchronous messages

method

read

n/a

write

Calls a method

subscribe

Subscribes to method’s answers

variable

read

Requests the actual value of the variable

write

Writes a value to the variable

subscribe

Subscribes to the results of read-requests

This means some endpoints in this example can now be defined as follows:

  • inventory subscribes to asynchonous messages of QSinv

  • inventoryStart calls the method MIStartIn

  • inventoryStop calls the method MIStopIn

  • inventoryCheck triggers the request of the variable QSIsRn

  • inventoryRunning receives the data from QSIsRn requested by inventoryCheck

  • feedbackLight calls the method HMISetFbLight

Connection Properties

host (string, required)

Hostname or IP address of the Sopas device

Examples: "126.4.10.52", "example.org"

port (integer, required)

Port of the Sopas device

Default: 2111

Example: 2111

timeout (integer)

Timeout used for connecting to the Sopas device

Default: 5000

Additional restrictions:

  • Minimum: 1

connectionStrategy (object)

If a connection attempt fails, retries will be performed with increasing delay (waiting time) in between. The following parameters control how these delays behave.

Properties of the connectionStrategy object:

initialDelay (integer)

Delay (waiting time) of the first connection retry (in milliseconds). For subsequent retries, the delay will be increased according to the parameter incrementFactor which has a default value of 2.

Default: 1000

Additional restrictions:

  • Minimum: 1000

maxDelay (integer)

Maximum delay (waiting time) to wait until the next retry (in milliseconds). The delay (waiting time) for any subsequent connection retry will not be larger than this value. Must be strictly greater than initialDelay.

Default: 30000

incrementFactor (integer)

The factor used to increment initialDelay up to maxDelay. For example if initialDelay is set to 1000 and maxDelay to 5000 the values for the delay would be 1000, 2000, 4000, 5000.

Default: 2

Additional restrictions:

  • Minimum: 2

Endpoint Properties

type (string, enum, required)

The type of the identifier. It can be one of the following: event, method or variable.

This element must be one of the following enum values:

  • event

  • method

  • variable

name (string, required)

The name of the method to call. For example MIStartIn.

index (string)

The index number of the method to call.

accessMode (integer)

The access mode (user level) when writing to a variable in the device. The default access mode 0 (zero) is always active. Higher access modes such as 1 (Operator), 2 (Maintenance), 3 (Authorized Client), or 4 (Service) all require some password, which should be listed in the manufacturer’s documentation. (The numbers 5 through 7 are internal values of the manufacturer.)

Default: 0

Additional restrictions:

  • Maximum: 7

password (string)

Only needed with an increased access mode (user level) parameter, when writing to a variable in the device.

Sample Commissioning file:

Download: sopas-example.yml

  1---
  2# ----------------------------------------------------------------------------#
  3# Commissioning File
  4# ----------------------------------------------------------------------------#
  5# Copyright: Cybus GmbH (2020)
  6# Contact: support@cybus.io
  7# ----------------------------------------------------------------------------#
  8# Source Interface Definition - Sopas - RFU620, SICK AG
  9# ----------------------------------------------------------------------------#
 10
 11description: >
 12  Sample commissioning file for SICK Sopas protocol connectivity and data mapping
 13
 14metadata:
 15  name: Sopas Protocol Connectivity
 16  icon: https://www.cybus.io/wp-content/uploads/2017/10/for-whom1.svg
 17  provider: cybus
 18  homepage: https://www.cybus.io
 19  version: 0.0.1
 20
 21parameters:
 22
 23  IP_Address:
 24    description: IP address of the SICK device
 25    type: string
 26    default: 192.168.10.10
 27
 28  Port_Number:
 29    description: Port on the SICK device. Usually 2111 (sometimes 2112).
 30    type: number
 31    default: 2112
 32
 33  initialReconnectDelay:
 34    type: integer
 35    default: 1000
 36
 37  maxReconnectDelay:
 38    type: integer
 39    default: 30000
 40
 41  factorReconnectDelay:
 42    type: integer
 43    default: 2
 44
 45resources:
 46  sopasConnection:
 47    type: Cybus::Connection
 48    properties:
 49      protocol: Sopas
 50      connection:
 51        host: !ref IP_Address
 52        port: !ref Port_Number
 53        connectionStrategy:
 54          initialDelay: !ref initialReconnectDelay
 55          maxDelay: !ref maxReconnectDelay
 56          incrementFactor: !ref factorReconnectDelay
 57
 58  inventory:
 59    type: Cybus::Endpoint
 60    properties:
 61      protocol: Sopas
 62      connection: !ref sopasConnection
 63      subscribe:
 64        name: QSinv
 65        type: event
 66
 67  inventoryStart:
 68    type: Cybus::Endpoint
 69    properties:
 70      protocol: Sopas
 71      connection: !ref sopasConnection
 72      write:
 73        name: MIStartIn
 74        type: method
 75
 76  inventoryStop:
 77    type: Cybus::Endpoint
 78    properties:
 79      protocol: Sopas
 80      connection: !ref sopasConnection
 81      write:
 82        name: MIStopIn
 83        type: method
 84
 85  inventoryCheck:
 86    type: Cybus::Endpoint
 87    properties:
 88      protocol: Sopas
 89      connection: !ref sopasConnection
 90      read:
 91        name: QSIsRn
 92        type: variable
 93
 94  inventoryRunning:
 95    type: Cybus::Endpoint
 96    properties:
 97      protocol: Sopas
 98      connection: !ref sopasConnection
 99      subscribe:
100        name: QSIsRn
101        type: variable
102
103  feedbackLight:
104    type: Cybus::Endpoint
105    properties:
106      protocol: Sopas
107      connection: !ref sopasConnection
108      write:
109        name: HMISetFbLight
110        type: method
111
112  mapping:
113    type: Cybus::Mapping
114    properties:
115      mappings:
116        - subscribe:
117            endpoint: !ref inventory
118          publish:
119            topic: !sub '${Cybus::MqttRoot}/inventory'
120        - subscribe:
121            topic: !sub '${Cybus::MqttRoot}/inventory/start'
122          publish:
123            endpoint: !ref inventoryStart
124        - subscribe:
125            topic: !sub '${Cybus::MqttRoot}/inventory/stop'
126          publish:
127            endpoint: !ref inventoryStop
128        - subscribe:
129            topic: !sub '${Cybus::MqttRoot}/inventory/check'
130          publish:
131            endpoint: !ref inventoryCheck
132        - subscribe:
133            endpoint: !ref inventoryRunning
134          publish:
135            topic: !sub '${Cybus::MqttRoot}/inventory/running'
136        - subscribe:
137            topic: !sub '${Cybus::MqttRoot}/light'
138          publish:
139            endpoint: !ref feedbackLight

Example communication

With the above commissioning file, a connection can be established between the SICK RFID sensor and the Connectware. Once this is up and running, we can go to the Explorer tab, where we see a tree structure of our newly created datapoints. Hover an entry and select the eye icon on the right – this activates the live view and you should see data coming in.

Input Format

To start the reading process, simply send an empty message to inventoryStart endpoint, for example using the Workbench and injecting a message there. The request must be sent to the MQTT topic of the read endpoint with a /req suffix added, or for a write endpoint with a /set suffix.

To stop the reading process, send an empty message to inventoryStop endpoint.

If other SOPAS method calls or variable write requires input arguments, those must be supplied as one (JSON) string in the payload of the MQTT message. If multiple input argument values are required, those values must be supplied as multiple space-separated words in one single string as payload, such as "value1 value2 value3" for three values.

Output Format

The response message on any read endpoint will be sent according to the following format, and the message will be sent to the MQTT topic of the endpoint with a /res suffix added. For write endpoints, there is no response message.

Although it may not be represented by the Explorer view, on MQTT topics the data is provided in JSON format and applications consuming the data must take care of JSON parsing to pick the desired property. The response messages published on /res MQTT topics contain a "timestamp" and a "value" key like the following:

{
  "timestamp": 1581949802832,
  "value": "sSN QSinv 1 0 8 *noread* 0 0 0 0 0 AC"
}

This particular example is an inventory message published on topic ‘sick/rfid/inventory’ for the case when no RFID tags have been recognized (a “no read” situation). You recognize its "value" is a string in the form of the SOPAS protocol containing some space-separated values and parameters. This is the original message received from the SICK device which means you still have to parse it according to SOPAS specifications. The Connectware is not capable of this task since most messages received from SICK devices are quite device-specific and can not be interpreted on a general base. Other SICK devices may produce rather different output.

When some RFID tag is recognized, the output on the inventory endpoint changes into this example:

{
  "timestamp": 1581950481059,
  "value": "sSN QSinv 2 E 34 0 E2 0 20 64 81 18 1 20 15 70 71 75 D Non-EPCglobal 0 FFCB 0 0 0 1 E 30 0 E2 0 20 64 81 18 1 21 27 0 8 D6 D Non-EPCglobal 0 FFD0 0 0 0 1"
}

Fortunately, answers to variable read requests are usually rather intuitively to read since they usually only contain the variable’s value. For instance, this is the answer to inventoryCheck on endpoint inventoryRunning:

{
  "timestamp": 1581950874186,
  "value": "sRA QSIsRn 1"
}

It contains just the command type (sRA = read answer), the variable name (QSIsRn) and the value 1 indicating that the inventory is running. If the inventory is not running, a 0 is observed there.

Summary

The Sopas protocol implements communication with SICK sensor devices using the SOPAS and CoLa A telegram language. The examples shown above demonstrate communication with the RFU620 RFID reading device. Other SICK devices can be used similarly. The Connectware will pass on the original SOPAS messages with space-separated parameters. Further interpretation needs to be implemented in another layer of data processing.