Automatically translate this page?

How To Send A Command To The Device Over The Channel’s Connection?

Sending commands to a tracker on the gateway level.

flespi channel supports bi-directional connectivity: a device sends telemetry messages to the channel, in turn, the channel sends commands to the device. This guide shows how to send a command from the channel to the tracking device. We will be switching outputs on Galileosky v5.0 device. We assume that the device is connected to the flespi channel.

Step 1. Check supported commands

Each protocol has its own set of supported commands. To find out what commands can be used with the required protocol perform GET /protocols/commands request. E.g. if we request the list of commands supported by the Galileosky protocol (only name and description fields),

curl -X GET --header 'Authorization: FlespiToken Your_flespi_token' 
'https://flespi.io/gw/protocols/name=galileosky/commands/all?fields=name,description'

the response will be the following:

{
  "result": [
    {
      "description": "Send custom command to device",
      "name": "custom"
    }
  ]
}

There are three commands supported by galileosky channels. We are interested in Transistor outputs control commands named “output”.

Step 2. Get schema of the desired command

Command schema describes the format of the command expected by the channel’s commands API. To get command’s schema one can specify commands name and the field schema:

curl -X GET --header 'Authorization: FlespiToken Your_flespi_token' 
'https://flespi.io/gw/protocols/name=galileosky/commands/output?fields=schema'

The response will be the following:

{
  "result": [
    {
      "schema": {
        "additionalProperties": false,
        "description": "Send custom command to device",
        "properties": {
          "hex": {
            "default": false,
            "title": "Payload is encoded as HEX string",
            "type": "boolean"
          },
          "payload": {
            "title": "Text or hex data to send",
            "type": "string"
          }
        },
        "required": [
          "payload"
        ],
        "title": "Custom command",
        "type": "object",
        "x-view-order": [
          "payload",
          "hex"
        ]
      }
    }
  ]
}

Schema says that the command must have one required parameter: string with the payload. If the payload is represented by HEX values, add boolean parameter “hex” with true value.

Step 3. Send command via channel’s REST API call

Suppose that Galileosky device with IMEI ‘1234567890’ is connected to the channel with id=1234. Following is the request that puts the command (to switch on the 1st relay) to the command queue (note, you can use “properties”:{“payload”:”out 1,1”}, this is the same):

curl -X POST --header 'Authorization: FlespiToken Your_flespi_token' -d 
'[{"address":{"ident":"1234567890","type":"connection"},"name":"custom",
"properties":{"hex":true,"payload":"6F757420302C31"},"ttl":86400}]'
'https://flespi.io/gw/channels/1234/commands-queue'

The response will be the following:

{
  "result": [
    {
      "address": {
        "ident": "1234567890",
        "type": "connection"
      },
      "channel_id": 6817,
      "expires": 1542371105,
      "id": 9876543,
      "name": "output",
"properties":{"hex":true,"payload":"6F757420302C31"}
    }
  ]
}

The response refers to the command with id=9876543. You can check the status of the command in the commands-queue via GET commands request. When the connection with the target device is established it will receive appropriate data and command will be removed from the queue. If the device does not appear online within the “expires” time (which is UNIX timestamp of the expiration time, the command was created with ttl = 1 hour), the command will be removed from the queue.

Step 4. Check if the command is delivered

Delivered and expired commands are stored in a special commands-result buffer. You can check this buffer with the GET /channels/commands-result request:

curl -X GET --header 'Authorization: FlespiToken Your_flespi_token' 
'https://flespi.io/gw/channels/1234/commands-result'

The response will be the following:

{
  "result": [
    {
      "address": {
        "ident": "1234567890",
        "type": "connection"
      },
      "channel_id": 1234,
      "executed": true,
      "id": 9876543,
      "name": "output",
      "properties":{"hex":true,"payload":"6F757420302C31"},
      "response": null,
      "timestamp": 1542288737.003206
    }
  ],
  "next_key": 1542288737
}

The field “response”:null here means that the command does not wait for any response. Status “executed”:true means that the device established the connection and received the required data.

Conclusion

The method above describes the communication to the device on the most basic level of the flespi architecture — gateway. Flespi registered devices provide more complex level of organization: you can store states of device’s settings and receive diagnostic data from the device. So if you need to analyze the response from the device, please consider using flespi registered devices. If channel commands do not work the way you expect, you can connect the device through the proxy channel and view the data flow via HEX Viewer. If you need to implement more commands, please contact the flespi team.


See also
Helping you quickly go through the real-life issues.
Forwarding telemetry data into the advanced fleet management system.