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

Endpoint Properties

Sample Commissioning File:

Download:

4KB

sopas-example.yml

---
# ----------------------------------------------------------------------------#
# Commissioning File
# ----------------------------------------------------------------------------#
# Copyright: Cybus GmbH (2020)
# Contact: [e-mail]
# ----------------------------------------------------------------------------#
# Source Interface Definition - Sopas - RFU620, SICK AG
# ----------------------------------------------------------------------------#

description: >
    Sample commissioning file for SICK Sopas protocol connectivity and data mapping

metadata:
    name: Sopas Protocol Connectivity
    icon: https://www.cybus.io/wp-content/uploads/2017/10/for-whom1.svg
    provider: cybus
    homepage: https://www.cybus.io
    version: 0.0.1

parameters:
    IP_Address:
        description: IP address of the SICK device
        type: string
        default: 192.168.10.10

    Port_Number:
        description: Port on the SICK device. Usually 2111 (sometimes 2112).
        type: number
        default: 2112

    initialReconnectDelay:
        type: integer
        default: 1000

    maxReconnectDelay:
        type: integer
        default: 30000

    factorReconnectDelay:
        type: integer
        default: 2

resources:
    sopasConnection:
        type: Cybus::Connection
        properties:
            protocol: Sopas
            connection:
                host: !ref IP_Address
                port: !ref Port_Number
                connectionStrategy:
                    initialDelay: !ref initialReconnectDelay
                    maxDelay: !ref maxReconnectDelay
                    incrementFactor: !ref factorReconnectDelay

    inventory:
        type: Cybus::Endpoint
        properties:
            protocol: Sopas
            connection: !ref sopasConnection
            subscribe:
                name: QSinv
                type: event

    inventoryStart:
        type: Cybus::Endpoint
        properties:
            protocol: Sopas
            connection: !ref sopasConnection
            write:
                name: MIStartIn
                type: method

    inventoryStop:
        type: Cybus::Endpoint
        properties:
            protocol: Sopas
            connection: !ref sopasConnection
            write:
                name: MIStopIn
                type: method

    inventoryCheck:
        type: Cybus::Endpoint
        properties:
            protocol: Sopas
            connection: !ref sopasConnection
            read:
                name: QSIsRn
                type: variable

    inventoryRunning:
        type: Cybus::Endpoint
        properties:
            protocol: Sopas
            connection: !ref sopasConnection
            subscribe:
                name: QSIsRn
                type: variable

    feedbackLight:
        type: Cybus::Endpoint
        properties:
            protocol: Sopas
            connection: !ref sopasConnection
            write:
                name: HMISetFbLight
                type: method

    mapping:
        type: Cybus::Mapping
        properties:
            mappings:
                - subscribe:
                      endpoint: !ref inventory
                  publish:
                      topic: !sub '${Cybus::MqttRoot}/inventory'
                - subscribe:
                      topic: !sub '${Cybus::MqttRoot}/inventory/start'
                  publish:
                      endpoint: !ref inventoryStart
                - subscribe:
                      topic: !sub '${Cybus::MqttRoot}/inventory/stop'
                  publish:
                      endpoint: !ref inventoryStop
                - subscribe:
                      topic: !sub '${Cybus::MqttRoot}/inventory/check'
                  publish:
                      endpoint: !ref inventoryCheck
                - subscribe:
                      endpoint: !ref inventoryRunning
                  publish:
                      topic: !sub '${Cybus::MqttRoot}/inventory/running'
                - subscribe:
                      topic: !sub '${Cybus::MqttRoot}/light'
                  publish:
                      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.