.. _user/protocols/sopas: ****** 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: .. code-block:: 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 :ref:`user/services/structure/resources/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` .. _user/protocols/sopas_connection: .. include:: ../protocolSchemas/SopasConnection.rst .. _user/protocols/sopas_endpoint: .. include:: ../protocolSchemas/SopasEndpoint.rst Sample Commissioning file: ========================== Download: :download:`sopas-example.yml` .. literalinclude:: sopas-example.yml :language: yaml :linenos: 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 :ref:`user/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 :ref:`user/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: .. code-block:: json { "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: .. code:: json { "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`: .. code-block:: json { "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.