If you want to instruct the device to do something, you need to send a proper command. To start with remote device management we suggest to read general command and settings overview where you can find UI tools needed to construct the command API call based on particular device type. However if you need to repeat this functionality in your own application you can find all the steps below.
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": "custom",
"address": [
"sms",
"connection"
],
"examples": [
{
"description": "Force device to generate a record and connect to server to deliver it",
"properties": {
"text": "getrecord"
}
},
{
"description": "Send custom bytes to device as codec 12 command. May be used to communicate with external equipment connected over serial port",
"properties": {
"hex": "DEADBEEF"
}
}
],
"schema": {
"anyOf": [
{
"additionalProperties": false,
"description": "Send custom command with text payload",
"properties": {
"text": {
"title": "Text payload",
"type": "string"
}
},
"required": [
"text"
],
"title": "Text payload",
"type": "object",
"x-view-order": [
"text"
]
},
{
"additionalProperties": false,
"description": "Send custom command with binary payload",
"properties": {
"hex": {
"pattern": "^(?:[0-9A-Fa-f]{2})+$",
"title": "Binary payload in HEX form",
"type": "string"
}
},
"required": [
"hex"
],
"title": "Binary payload",
"type": "object",
"x-view-order": [
"hex"
]
}
],
"description": "Send custom command via connection or over SMS",
"title": "Custom command"
},
"tags": {
"custom": 1
}
}
}Prepare JSON payload for sending a command to the device
Specify command name and command properties according to the fetched schema:
[
{
"name": "custom",
"properties": {
"text": "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":"custom","properties":{"text":"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 'custom' 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": "custom",
"device_id": 2177081,
"executed": true,
"properties": {
"text": "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":"custom","properties":{"text":"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. If you know the command ID, you can fetch its execution result using the GET /gw/devices/{..}/commands-result/{...} API method. Alternatively, you can queue all executed commands with a single request GET /gw/devices/{..}/commands-result
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": "custom",
"origin_id": 2187409,
"properties": {
"text": "setdigout 1?"
},
"response": "DOUT1:0 Timeout:INFINITY DOUT2:IGNORED",
"timestamp": 1632734785.503132
}
]
}Command meta
You can assign an arbitrary meta object to commands posted to queue or sent in a real-time mode. When assigned, it will be automatically added to:
- all device logs related to command processing
- command result
- media or tacho files uploaded by this command
Just add a "meta":{...} object near "properties" and "name" of the command, for example:
curl -X POST --header 'Authorization: FlespiToken XXX' -d '[{"name":"custom","properties":{"text":"setdigout 1?"},"meta":{"any":"value"}]' 'https://flespi.io/gw/devices/<DEVICE_ID>/commands-queue'"meta" consists from up to 100 keys with total JSON serialized size of up to 8KB.
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.
MQTT topics
You can track commands execution over particular device through subscribing to these MQTT topics:
- flespi/log/gw/devices/{device_id}/commands-queue/{command_name}/queued - device command added to the queue;
- flespi/log/gw/devices/{device_id}/commands-queue/{command_name}/sent - device command sent;
- flespi/log/gw/devices/{device_id}/commands-queue/{command_name}/processed - device command processed;
- flespi/log/gw/devices/{device_id}/commands-queue/{command_name}/canceled - device command removed from the queue;
- flespi/log/gw/devices/{device_id}/commands-queue/{command_name}/expired - device command expired;
Similar but distinct MQTT topics can be used to track device settings modifications:
- flespi/log/gw/devices/{device_id}/settings/{setting_name}/updated - received current value of the setting from the device;
- flespi/log/gw/devices/{device_id}/settings/{setting_name}/set - user queued new pending value of the setting;
- flespi/log/gw/devices/{device_id}/settings/{setting_name}/accepted - device confirmed pending value of the setting;
- flespi/log/gw/devices/{device_id}/settings/{setting_name}/rejected - device rejected pending value of the setting;
- flespi/log/gw/devices/{device_id}/settings/{setting_name}/canceled - user deleted queued pending value of the setting;
- flespi/log/gw/devices/{device_id}/settings/{setting_name}/cleared - user deleted current value of the setting;
- flespi/log/gw/devices/{device_id}/settings/{setting_name}/unreadable - marked the setting as unreadable due to exceeded retries limit;
- flespi/log/gw/devices/{device_id}/settings/{setting_name}/sent - sent command to the device;