Basic channels API has been carved in stone for more than five years. The initial implementation of commands in flespi was done on the channel level because we didn’t even have the devices API at that time. Later on, the commands and settings were introduced on the device level. Back then we left the legacy mechanism on the channel level as well. Now we believe it’s time to let it go.
Important! The changes affect only the commands functionality on the channel level. All data reception functionality on the channel level remains intact.
Reasoning
It’s confusing. Having several similar mechanisms working in parallel leads to unnecessary questions and choices. This is one of the initiatives to make the flespi API more straightforward and intuitive.
Commands belong to devices. Seriously, if you intend to send a command to the device, it will affect a specific device, it seems totally logical to do that on the device level.
Complex maintenance. Making the two mechanisms work consistently takes more effort from our team and increases the probability of error. We want to prevent that.
Upcoming changes in the API
We are going to mark all commands-related API calls on the channels level as deprecated on September 26th.
This means that when you execute such calls along with the result you will also get a warnings array in the response. We will also highlight such requests in yellow and inform you about warnings during execution in the channel logs:
We will completely discontinue the support of commands on the channel level on December 1, 2022.
What do I have to do on my side?
1. Create devices
For each GPS tracker, you intend to control from flespi, you want to create a dedicated device.
Since you may need to create hundreds of devices, learn how to create devices in bulk.
Note that the Start plan includes the creation of 1000 devices in the base price and each extra 100 devices costs just €1, so even on large volumes, the overhead will be minimal.
2. Use device commands API
You should rely on the commands and settings requests in the devices API.
Note: unlike in the channels API where you can only put the command in the queue, with the devices API you can either send commands in real time or put them in the queue.
Hints:
Use configuration.ident=”xxx” property to refer to a device by ident, not by deviceID.
Use our interactive APIbox documentation to test the new requests.
Use our SetBox tool to conveniently send commands and settings via GUI.
Example:
If you have a code to execute the channel level command like this:
curl -X POST --header 'Authorization: FlespiToken XXX' -d '[{"address":{"ident":"123456789012345","type":"connection"},"name":"custom","properties":{"text":"custom_payload"},"ttl":3600}]' 'https://flespi.io/gw/channels/<channel_id>/commands-queue'You want to change it to the device-level command like this:
curl -X POST --header 'Authorization: FlespiToken XXX' -d '[{"name":"custom","properties":{"text":"custom_payload"},"ttl":3600}]' 'https://flespi.io/gw/devices/configuration.ident=123456789012345/commands-queue'Or use the real-time device command like this:
curl -X POST --header 'Authorization: FlespiToken XXX' -d '[{"name":"custom","properties":{"text":"custom_payload"},"timeout":10}]' 'https://flespi.io/gw/devices/configuration.ident=123456789012345/commands'Benefits of devices
Apart from the possibility to manage your GPS hardware by sending commands and settings, the creation of flespi devices offers the following powerful benefits:
10GB dedicated storage with up to 10 years storage period.
Analytics — extract trips/stops, detect geofence ins/outs, and a lot more.
Data enrichment — apply plugins to the device messages to add/remove parameters, add reverse geocoding data, define sets of geofences, etc.
Telemetry — you can easily get the latest values of all parameters received from the device and the time they were updated.
Dot on the map — you can visualize device location in TrackIt! — an open-source web application for basic GPS tracking.
How to check if channel commands are still in use?
Open the Platform logs in the flespi panel and filter the log records by "response_code=289":
Reminders
To help you stay on track and not postpone the changes your solution may require, we will remind you of the upcoming changes (discontinuation) in the channel commands API every month.
You have more than three months to schedule, implement, and test the changes to your solution. Please allot sufficient time to address all possible issues.
With any related questions please contact us in the chat.
Remember, that the change affects the channel commands API only; all the requests for receiving the data from the channels remain the same.
***
Even though switching to the devices commands API will require extra efforts on your side, we believe that in the long-term the benefits will justify this transition and result in a more efficient, more complete, and logically consistent use of the flespi capabilities.