thin-edge.io - custom operation handler guide

c8y-custom-operation-handler.md

Before creating a custom operation handler, create the configuration and confirm that the operation will be delivered to the device. Once you have confirm this, then you can add your custom handler.

Part 1: Send operations from Cumulocity IoT to thin-edge.io

Below shows the steps to create a custom SmartREST collection for Cumulocity IoT, and how to check that the message arrives on the local thin-edge.io MQTT broker.

1. Create a SmartREST template collection in Cumulocity IoT, and create a custom "response"

   Below is an example collection which create two custom operations for the message ids:

   • set wifi (message id: dm101)
   • get wifi (message id: dm102)

   {
     "name": "custom_devmgmt",
     "type": "c8y_SmartRest2Template",
     "com_cumulocity_model_smartrest_csv_CsvSmartRestTemplate": {
       "requestTemplates": [],
       "responseTemplates": [
         {
           "msgId": "dm101",
           "condition": "set_wifi",
           "base": "set_wifi",
           "name": "set_wifi",
           "pattern": [
             "name",
             "ssid",
             "type"
           ]
         },
         {
           "msgId": "dm102",
           "condition": "get_wifi",
           "base": "get_wifi",
           "name": "get_wifi",
           "pattern": [
             "name"
           ]
         }
       ]
     },
     "__externalId": "custom_devmgmt"
   }

   See the Cumulocity IoT docs for more details.

2. Add the id of the SmartRest Template collection created in step 1 (note the you can not change the id after the template has been created)

   sudo tedge config set c8y.smartrest.templates custom_devmgmt

3. Recreate the bridge using the tedge cli (required because the mosquitto bridge config can't be reloaded at runtime)

   sudo tedge reconnect c8y

   You can check if the setting was added correctly by checking the c8y bridge file:

   file: /etc/tedge/mosquitto-conf/c8y-bridge.conf

   # ...
   topic s/uc/custom_devmgmt out 2 c8y/ ""
   topic s/dc/custom_devmgmt in 2 c8y/ ""
   

4. On the device check if the message is being delivered by creating the operation in Cumulocity and checking if the message arrives on the local MQTT broker.

   On the client, create an operation for the thin-edge.io device that matches your response SmartREST template

   c8y identity get --name ginger \
   | c8y operations create --template "{'set_wifi':{name:'LocalWifi',ssid:'factory-floor',type:'CERTIFICATES'}}" -f

   On the device, you can subscribe the to the Cumulocity smart rest message to check if it is arriving (before you create the above operation):

   tedge mqtt sub 'c8y/#'

   Example output (the exact message depends on your content)

   [c8y/s/dc/custom_devmgmt] dm101,ginger,LocalWifi,factory-floor,CERTIFICATES
   

Part 2: Create custom operation handler

Since the communication between Cumulocity IoT and thin-edge.io has been confirmed, then you can create the actual custom operation handler (e.g. script) to handle what to do when it the message arrives.

1. Create the custom operation definition file

   The definition ties the operation with a script which will be called on the operation.

   file: /etc/tedge/operations/c8y/set_wifi

   [exec]
   topic = "c8y/s/dc/custom_devmgmt"
   on_message = "dm101"
   command = "/usr/bin/set-wifi.sh"
   

   The on_message should match the messageId of the template.

2. Create the script which will be executed

   file: /usr/bin/set-wifi.sh

   #!/bin/sh
   MESSAGE="$@"
   echo "Processing message: $MESSAGE" >> /tmp/set-wifi.log

   Make sure the script is executable:

   chmod +x /usr/bin/set-wifi.sh

3. Now create an operation in Cumulocity IoT for your device and check if the

   In the above example, the /tmp/set-wifi.log file should have been created with a log entry about the operation that was received on the device.