The main idea of the MQTT channel is to get messages from the MQTT broker and inject them into flespi.
To obtain MQTT messages MQTT channel has to establish an MQTT connection to an MQTT broker and subscribe to an MQTT topic to which some other agent publishes MQTT messages.
To inject a message into the flespi system MQTT channel has to identify the device and define message parameters.
MQTT channel configuration solves the following tasks:
how to get MQTT messages
where to get the device identifier
which parameters to include in the message
How to get MQTT messages
MQTT channel acts as an MQTT client. The configuration section for the MQTT connection differs depending on the broker choice: flespi MQTT broker or custom MQTT broker.
Custom MQTT broker
A custom MQTT broker option requires the following fields to be filled in:
Authorization with username and password
Enabled SSL allows specifying certificates
MQTT version 5.0 allows specifying retain_handling for each topic
Flespi MQTT broker
Flespi MQTT broker requires only the flespi token field to authorize the connection.
The default setup is:
URI: mqtt.flespi.io:8883
MQTT 5.0
SSL enabled
retain_handling in topic set to 1.
Common fields
Client ID will be created automatically if not specified. Client ID must be unique. If you specify it manually, make sure that no other MQTT sessions use the same Client ID.
MQTT session will be clean by default. Clean session means that messages are not accumulated when the session is disconnected (e.g. when the channel is disabled). Non-clean session has separate session storage, messages will be delivered to the MQTT client after reconnecting.
QoS can be specified for each topic individually. QoS 1 is recommended for more stable data flow; QoS 2 is not supported.
Where to get device identifier
MQTT channel can take a device identifier either from the MQTT message topic or MQTT message payload.
Identifier from topic
To extract the identifier from the topic, you should specify an index of the topic segment to take (and optionally how many segments to use).
E.g., if the topic is project/message/gateway/devices/12345 and 12345 has to be taken as a device identifier, use “4” as a topic component index (0-based).
If the topic is house/bathroom/temperature/4 and the topic component index is 1 and the segments count is 3 then the identification field will be bathroom_temperature_4 (note that slashes will be replaced with underlines).
Identifier from payload
To extract the identifier from the payload, the payload must be parsed as JSON. In this case, the identifier field name has to be specified between the % signs (e.g. %vehicleVin%). By default, the identifier will be taken from the “ident” field.
Which topic to use
Choose any topic arbitrary just make sure that it does not start from 'flespi/'. We suggest to use some topic that contains device identifier inside, something like 'devices/ingest/my-device-ident'. But in general you are free to select any topic, just it can not starts from 'flespi/'.
Topics that starts from 'flespi/' are reserved only for MQTT messages generated by flespi platform and not available to you. If you will try to publish MQTT message to any topic that starts from "flespi/" it will be discarded by the MQTT Broker.
Which parameters to include in the message
MQTT message payload can be taken as a parameter value or parsed as JSON and processed further.
MQTT payload as a parameter value
Two things have to be specified:
which name to use for the parameter and
how to treat the payload.
Parameter name
The parameter name can be specified manually (just specify a static name in the appropriate field) or taken from the topic.
If the parameter name has to be created from the topic, the index of the topic segment has to be used. If more than one segment has to be used, it is specified under the segments_count field. The parameter naming policy is not as strict as the ident naming policy, so the segments separator may be specified too.
E.g. topic house/bathroom/temperature/4, index = 2, segments_count=2, and “-” as a separator will result in the parameter name temperature-4.
How to treat payload
If the JSON value data type is selected, the MQTT channel tries to parse the payload as JSON. If a valid JSON object or array will be stored as a nested object or array with a name specified earlier. A number will be stored as a simple numeric value. A string has to be published in quotes.
Plaintext string will store the whole payload as a string parameter. Non-printable characters may lead to unexpected behavior.
If binary data is published, use Binary/HEX data to store it as a string in HEX format.
Parse MQTT payload as JSON
If the message is a valid JSON, then additional processing can be set up.
At first, as mentioned above, the device identifier may be taken from a parsed JSON field.
Second, if messages to be injected in the flespi system are encapsulated inside some bigger JSON, a path to these messages may be specified. E.g. a publisher sends the following message
{
"result": {
"messages": [{
"info": 1
}, {
"info": 2
}, {
"info": 3
}]
}
}If the JSON messages path is specified as “result.messages”, each JSON object in the array will be stored as a separate message in flespi.
The Message parameters configuration is responsible for applying a custom naming scheme.
The Skip invalid messages option (true by default) if enabled, will cause the MQTT channel to disconnect from the broker and record an error in the channel log if the payload cannot be parsed according to configuration.
