Imagine that you want to amend device telemetry with some other parameters, additionally calculated by certain conditions. For such use cases flespi provides a set of tools:
Calculators - to define these parameters and calculate them
Webhooks - to re-post calculated interval data as a device message
Such re-posted device messages will follow the standard device message flow - be processed by plugins to which this device is assigned to, forwarded via streams and also automatically be processed by calculators. That's why this approach can also be an alternative to streaming intervals via MQTT channel in cases when you want to forward data produced by the calculator.
In our use-case we will calculate device daily stats such as mileage, driving duration, engine run duration. And re-publish it to device telemetry during interval created or updated events using webhook.
In order to distinguish messages generated from the calculator out of normal device messages we will mark them with some additional parameter, for example “calculated” set to “true”. If you would like to prevent plugins or streams from processing them, just set their “validation_message” configuration option to “$calculated == false”.
Create calculator to calculate device daily statistics
Create a new calculator in the Telematics Hub section of the flespi panel. Pay attention to the following details:
Selector’s type is “datetime” with split set to “day”. This selector will make an interval to include all messages within a day according to the “timezone” specified in the calculator configuration. Whenever any new device message is registered, the calculator will automatically recalculate all its messages within this day.
Create a mileage counter using the expression “mileage()” and method “summary” to calculate total mileage between all interval messages. You may apply additional filtering such as “position.valid == true” in "validate_message" field to exclude some messages from calculation, if needed.
Create a driving_duration counter using the expression “position.speed > 0” and method “duration”. This will calculate the combined duration of messages with positive speed.
Create an engine_duration counter using the expression “engine.ignition.status” and method “duration”. This will calculate the combined duration of messages when engine ignition status was true. We expect that your device is reporting this parameter.
You may add more counters. Just ensure they are meaningful for daily stats and your device is reporting the source data for calculated parameters.
You can copy full JSON representation of this calculator below:
{
"name": "Daily stats",
"selectors": [
{
"split": "day",
"type": "datetime"
}
],
"intervals_rotate": 0,
"counters": [
{
"expression": "mileage()",
"method": "summary",
"name": "mileage",
"type": "expression"
},
{
"expression": "position.speed > 0",
"method": "duration",
"name": "driving_duration",
"type": "expression"
},
{
"expression": "engine.ignition.status",
"method": "duration",
"name": "engine_duration",
"type": "expression"
}
]
}This JSON can be imported into your calculator's configuration directly by clicking on the orange curly brackets button when you edit or create a calculator.
Now navigate to the “DEVICES” tab of the calculator, assign devices to it, wait a bit until their status becomes synced (green checkmark on the device card) and ensure that your daily stats in each interval were calculated correctly.
Finally copy the ID of the newly created calculator. You will need it to subscribe to a webhook to the calculator events. You may find it in the top-left corner of the calculator's card. It is prefixed with ‘#’ sign.
Create webhook to re-post data from interval into device
Create a new webhook in the Utils section of the flespi panel. Webhook will handle all interval creation or update events and use interval “end” time to register daily stats back into the device as a message.
The webhook trigger topic is “flespi/interval/gw/calcs/10494/devices/+/created,updated” (replace 1094 with the ID of your calculator). This will trigger a webhook on any interval create or update event.
The webhook action will perform a device message registration call with uri “/gw/devices/%topics[6]%/messages” where “%topics[6]%” will be automatically replaced with device ID from the calculator event. The body will be the JSON of new message:
[{"timestamp":%payload["end"]%,"daily_mileage":%payload["mileage"]%,"daily_driving_duration":%payload["driving_duration"]%,"daily_engine_duration":%payload["engine_duration"]%,”calculated”:true}]
This message will contain a timestamp same as the interval end time, some parameters we calculated and additional “calculate” flag for message so that you can easily distinguish this message from regular device messages in plugins or calculators (optional).
You can copy full JSON representation of this webhook below:
{
"triggers": [
{
"topic": "flespi/interval/gw/calcs/10494/devices/+/created,updated"
}
],
"name": "Re-post dily stats as device message",
"configuration": {
"body": "[{\n\"timestamp\":%payload[\"end\"]%,\n\"daily_mileage\":%payload[\"mileage\"]%,\n\"daily_driving_duration\":%payload[\"driving_duration\"]%,\n\"daily_engine_duration\":%payload[\"engine_duration\"]%,\n\"calculated\":true\n}]",
"method": "POST",
"type": "flespi-platform",
"uri": "/gw/devices/%topics[6]%/messages"
}
}This JSON can be imported into your webhook's configuration directly by clicking on the orange curly brackets button when you edit or create a webhook. Just do not forget to replace the ID of the calculator with yours in the trigger topic.
Diagnose and test webhook
Now you can navigate into webhook logs in one window and in the other window navigate to calculator devices. Unassign and assign devices back to the calculator to force regeneration of their intervals. If everything is OK, you should see plenty of green lines in webhook logs with event_code=1100 (message was sent) meaning that device message registration call succeeded. On any error the webhook log line will be yellow with event_code=1102 (message was skipped). You can click on this line to investigate the problem in more detail. You can even right click and select “Show traffic” to check the fully formatted REST API call request that was sent and actual response from the flespi platform.
In device messages and telemetry you should also now see actual values of registered messages with daily stats. Such messages in the toolbox are in blue color to indicate their artificial origin (registered via REST).
