Have you read the article on how to access telematics data generated by devices and parsed by flespi in your software? It covers a variety of data access methods leveraging REST, MQTT, and even streams. It was published before we created Knowledge Base and still serves as a good starting point for engineers who want to understand what kind of information flespi can provide and how to configure incoming data flow into their software.
We wrote that longread in reply to a common question: “What is the best way to integrate flespi into our software?”. It does not answer this question directly, because each integration, its requirements and restrictions are unique, but it provides an overview of what we can bring to the table and simplifies decision-making.
Now, four years later, is high time to make a similar overview in the opposite direction — about the methods for remote device management. This is especially important since we have a diverse customer base with varying requirements to device control:
Micro-mobility platforms require devices to be constantly online and commands to execute instantly — no one will wait half a minute or so for the scooter to unlock.
Telematics platforms with security in mind require automatic and immediate ordered command execution once the device establishes the connection.
And standard fleet management platforms want flexible remote configuration possibilities in order to tune the device behavior.
Device commands
Remote device control works only with registered flespi devices:
Device REST API for remote management gives a lot of possibilities while also eliminating the need to know the exact command format:
The only drawback here is that you have to understand all available device management options flespi offers to pick the most suitable API methods. To help you with that let me make an overview of what we have on the menu.
First, let’s take a look at device settings:
A setting is a configuration state of the device plus action settings with no state. All device settings can be manipulated with mouse-clicks in a special SetBox application that you can easily embed into your solution:
Here are the screenshots from SetBox for two types of settings:
Action command setdigout is an action-type setting that does not have a state associated with it.
Battery voltage is a standard configuration setting which state was automatically read by flespi from the device once it was connected to the channel. With flespi, it is possible to delete (DELETE) the cached value and thus force flespi to re-read the actual value from the device or to change (PUT) this configuration.
Settings are like shadows — the platform remembers only the last requested state. You may execute the PUT method to change the configuration five times but if the device is offline at that moment, it will receive only the latest configuration change request once connected. The same applies to action-type settings. If you activate digital outputs multiple times, only the latest activation request will be sent to the device. For more information about settings, read our dedicated KB article about device settings and how to use them via API.
Settings are good for configuring devices but not that good for managing them with actions. That’s why we introduced a command queue in devices:
With this API method, you can control how many times and in what order the device will receive command requests. You can use both channel-level commands (e.g. custom message with protocol-specific fields) and setting commands (e.g. request to activate an output, reboot the device, change the setting value, etc.) and they will be delivered to the connected device in the same order and quantity as queued. Full list of commands and their schema available for specific device type you may fetch using this API method.
You add commands to the queue no matter if the device is connected or not and you are confident that flespi will deliver them to the device once it is back online. Once the command is processed by the device or timed out, it is placed to the commands-result read-only queue. This is convenient for standard fleet management platforms where you need to maintain durability.
If you do not need durability from flespi but simply want to send a command to the device in real-time and know exactly if it has been delivered to the device or not, then we also have a special method for you:
With this API method, flespi finishes the REST API call only when the device responds to the command. If the device is offline, the method will indicate this and return an error message immediately. If the device is online, the method will wait for a specified time (timeout) until the command is delivered to the device and will return its response to the caller.
This method is suitable for scooter and car-sharing platforms because they need to lock or unlock the device immediately or report an error.
Same as with device command queue in this method it is possible to use both channel-level commands and setting commands. Full list of commands and their schema available for specific device type you may fetch using this API method.
And last but not least, for managing devices via SMS we have special methods:
POST method will format SMS message text according to provided parameters, deliver it to the modem available to the user and return the delivery status plus the SMS text itself.
GET method will just format the text of the SMS message according to the device configuration and provided call parameters. Here the user is responsible for sending the SMS to the device.
To sum up, here are our recommendations:
Device settings — for remote configuration;
Device commands queue — when you want to delegate buffering and guaranteed delivery to flespi regardless of the device connection state;
Real-time device commands — when you want to have the immediate command execution result and you are responsible for guaranteeing the command delivery;
SMS commands — when you need them (e.g. devices are located in the area with a poor internet connection).
Troubleshooting commands
To track any changes that occurred to the device in real-time I suggest subscribing to its logs via MQTT. Or monitor and track live and historical logs in Toolbox.
When operating with device commands, all events are reported to the flespi/log/gw/devices/{device-id}/commands-queue/{command-name}/{event-type} topic. So, to track all changes to commands for all devices, subscribe to the flespi/log/gw/devices/+/commands-queue/+/+ topic.
Here are the possible event types (EVENT CODES) for device commands management:
processed (332) — command has been processed on the device;
queued (330) — command has been queued;
sent (334) — command has been sent to the device;
canceled (331) — command was removed from the queue;
expired (333) — command in the queue has been expired;
The same applies to settings. Any operation with setting values, all updates received from the device — everything is reported to the flespi/log/gw/devices/{device-id}/settings/{setting-name}/{event-type} topic. So, to track all changes to settings for all devices, subscribe to the flespi/log/gw/devices/+/settings/+/+ topic.
Here are the possible event types (EVENT CODES) for settings management:
updated (310) — received a new setting value from the device;
set (311) — the system accepted new setting value;
accepted (312) — the pending value of the setting has been sent to the device and assigned as the current setting value;
rejected (313) — device rejected the new setting value;
canceled (314) — the sending of new setting value was canceled by the user;
cleared (315) — current setting value was cleared from the system by the user;
unreadable (316) — the system marked the setting as unreadable due to exceeded retries limit;
sent (317) — the command to request or change the setting has been sent;
expired (318) — the command to request or change the setting has been expired;
If you prefer REST API instead, you can use this method to access device logs. You may filter the log entries by the event_code numeric parameter which is unique for each event type.
***
There are a lot of options for remote device management with flespi. It’s a huge step forward compared to the simple reception of incoming messages. And this is where the world is currently moving. Bidirectional device communication is what your clients will expect from you in the near future if not yet. Want to stand out in our competitive telematics market? Offer remote management services for your devices. And flespi will help you with that.