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.