How to send commands to the device connected to flespi via API

The sequence of steps to find a proper command for your device type, configure it, and send in one of the two ways.

If you want to instruct the device to do something, you need to send a proper command. Below are the steps to follow in order to perform this task.

Get the list of supported commands for your device

Method: GET /gw/devices/{..}

curl -X GET --header 'Authorization: FlespiToken XXX' 'https://flespi.io/gw/devices/<DEVICE_ID>?fields=commands'

Find the command name and schema in the received commands JSON

{
  "name": "codec12",
  "schema": {
    "additionalProperties": false,
    "description": "Send command encoded in Codec 12",
    "properties": {
      "crlf": {
        "default": true,
        "title": "Add CR and LF bytes after text payload",
        "type": "boolean"
      },
      "hex": {
        "default": false,
        "title": "Payload is encoded as HEX string",
        "type": "boolean"
      },
      "payload": {
        "title": "Text or hex data to send",
        "type": "string"
      }
    },
    "required": [
      "payload"
    ]
  }
}

Prepare JSON payload for sending a command to the device

Specify command name and command properties according to the fetched schema:

[
  {
    "name": "codec12",
    "properties": {
      "payload": "setdigout 1?"
    }
  }
]

Send a command to the device

(a) in real-time

Method: POST /gw/devices/{..}/commands

curl -X POST --header 'Authorization: FlespiToken XXX' -d '[{"name":"codec12","properties":{"payload":"setdigout 1?"}}]' 'https://flespi.io/gw/devices/<DEVICE_ID>/commands'

If the device is not connected to the flespi channel at the moment, you will receive an error:

   {
      "code": 2,
      "reason": "failed to deliver command 'codec12' with timeout pending, device with id <DEVICE_ID> is not connected"
    }

If the device is connected, the command will be sent to the device and the response from the device will be returned:

{
  "result": [
    {
      "timestamp": 1632732067,
      "response": "DOUT1:0 Timeout:INFINITY DOUT2:IGNORED",
      "id": 97064380653476,
      "position": 1,
      "name": "codec12",
      "device_id": 2177081,
      "executed": true,
      "properties": {
        "crlf": true,
        "hex": false,
        "payload": "setdigout 1?"
      }
    }
  ]
}

(b) or put command to the device commands queue

Method: POST /gw/devices/{..}/commands-queue

curl -X POST --header 'Authorization: FlespiToken XXX' -d '[{"name":"codec12","properties":{"payload":"setdigout 1?"}}]' 'https://flespi.io/gw/devices/<DEVICE_ID>/commands-queue'

The command enqueued will be sent to the device as soon as it connects to the flespi channel. To view and delete the command from the queue use the following API methods:

GET /gw/devices/{..}/commands-queue 

DELETE /gw/devices/{..}/commands-queue

As soon as the command is delivered to the device and the reply from the device is received (or the command expires — whichever sooner), the result of the command execution will appear in the commands results queue. To get the command result from the queue, use the GET /gw/devices/{..}/commands-result API method:

curl -X GET --header 'Authorization: FlespiToken XXX' 'https://flespi.io/gw/devices/<DEVICE_ID>/commands-result'

Result:

{
  "result": [
    {
      "channel_id": 72893,
      "executed": true,
      "id": 7589884856184060,
      "name": "codec12",
      "origin_id": 2187409,
      "properties": {
        "crlf": true,
        "hex": false,
        "payload": "setdigout 1?"
      },
      "response": "DOUT1:0 Timeout:INFINITY DOUT2:IGNORED",
      "timestamp": 1632734785.503132
    }
  ]
}

Sending commands from the interface

The above scenario is hidden behind the interface of the Commands tab on the device configuration screen:

You can send a command in real-time or place it in the commands queue in a few mouse clicks.

Note: some commands in the list have ".set" and ".get" versions; make sure to pick the right one — ".set" to change the setting value and ".get" to read the setting value. 

Also, note that you can configure the Queue TTL and Request timeout parameters by clicking on the stopwatch icon.


See also
Certain flespi-compatible devices may encrypt traffic using TLS. This article explains how to set up TLS encryption using flespi certificates chain.
A comprehensive guide to the flespi platform API.