Flespi devices feature both commands and settings for device management and since the concepts are tightly interwoven, the choice between the two may be confusing. So let us clarify.
Commands
Commands include the entirety of all instructions that can be sent to the device (as per the protocol documentation) to change its behavior.
You can send specific commands via the flespi panel interface — from the Commands & Settings tab on the device configuration screen:
Here are the respective REST API calls to send a command
- in real-time: https://flespi.io/docs/#/gw/devices/post_devices_dev_selector_commands
- to commands queue: https://flespi.io/docs/#/gw/devices/post_devices_dev_selector_commands_queue
- SMS via modem: https://flespi.io/docs/#/gw/devices/post_devices_dev_selector_sms
Note: SMS option only becomes available when the SMS transport is supported for the given command, the proper modem is created, and the phone number is specified in the device configuration. If you want to see the SMS text to send it manually, use this method: https://flespi.io/docs/#/gw/devices/get_devices_dev_selector_sms.
Most protocols integrated into flespi support a so-called custom command that accepts arbitrary command text and, as long as the command syntax is correct, the command will be executed on the device.
Here’s how a custom command looks for Queclink devices:
Here’s the commands API to send any command to the device.
Real-time commands vs commands queue
Sending a command in real-time is straightforward but gives little flexibility and configurability. If you send a real-time command, it has a default timeout of 15 seconds (configurable from 5 to 60 seconds). If the device does not go online within that timeout and does not respond to the command (acknowledge it), the command is rejected. So real-time commands work fine if you are sure the device is online.
If you send a command to the queue, you can set a TTL (from 60 to 2592000 seconds) or expiration date and time. Moreover, flespi will make 10 attempts to deliver the command from the queue to the device before it gets cancelled.
Settings
A setting is a clearly named wrapper around a specific command instruction that also stores the current (latest known) state of the related device configuration feature (aka device shadow). You can use the settings API or the Settings tab on the device configuration screen to send a command to change the corresponding setting value.
To re-read setting value from device you just DELETE it and flespi will automatically request fresh setting value from the connected device.
Settings represent a subset of commands, so, basically, everything you can send as a setting can also be sent as a corresponding custom command (see examples in the Commands section of the article).
There is a class of action commands/settings (e.g. “reboot”) that might not have the state to store. For such commands triggering the corresponding action via a commands API or settings API is identical. For settings such action items are grouped on the Action tab:
It becomes simply a matter of convenience.
If you don’t see a specific setting but have a protocol specification at hand, the custom command can be your last resort. Or you can ask us to add the settings for you:)
Commands vs settings processing specifics
If you send a command to the device commands queue, it will be delivered to the device as soon as it connects to the channel. If the device does not connect to the server, the command will wait in the queue until its "TTL" or "expire" is reached and will then be deleted.
If you update a setting for the device, the command will also be delivered to the device once it connects. However, if the device does not connect to the server, the setting will stay in the "pending" state and will wait for the device to connect for an unlimited period of time, until you delete the pending value with a DELETE request.
Another difference between the commands queue and settings, is that the commands queue allows you to send several commands to the device, and they will be delivered to the device in the exact same order in which they were added to the queue. This allows executing series of commands in a predefined order.
In contrast, a setting allows only one pending value (no queue). So you need to wait until the pending value is applied (acknowledged by the device) to be able to send subsequent changes to the setting. So with settings, the flow requires more manual control from you.
One more difference is the capacity: device queue is limited to 100 commands, whereas the number of "pending" settings is not limited.
Configuring device settings polling for more control over traffic consumption
Once a new device connects to flespi (i.e. establishes a connection with the proper channel), the platform will request the device configuration to know its current state. As a result of synchronization, the flespi platform gets a complete up-to-date virtual copy of the physical device’s actual state also known as device shadow.
Sometimes when the device attempts to sync all its numerous settings, it triggers substantial cellular traffic consumption. And if you have a fleet of a thousand vehicles equipped with such devices, you get a bloated bill from your connectivity provider.
To put you in control of the above situation, we introduced a new configuration option for the device that allows adjusting the device settings polling interval. You can now do that on the “pencil” tab on the device configuration screen:
The possible polling frequency values to choose from include:
once (default) — query device setting values only once (usually upon connecting to the channel)
never — do not request settings from the device. This is useful for reducing device traffic.
daily, weekly, monthly — update the device settings once in the specified period.
Sidenote: another way to optimize expenses is to adjust flespi resource consumption.
Commands field for easy access to the list of available commands
To make access to the list of available device commands more convenient, we added a new commands device field. This field contains an array with the descriptions of all available commands and can be requested via API:
As a result, you will get the list of commands and their schemas available for the device:
More about how to send commands to devices is outlined in a dedicated article.