"Application" mode
The "application" mode purpose is to retrieve messages available in your FIFOs.
Typically, use this mode when you want to consume flows of data collected by Live Objects.
The FIFO you connect to, must be declared using the FIFO APIs. To push data toward these FIFOs, you must use the Fifo publish action rules.
Application mode can also be used to publish a DataMessage in the specific case that it is not linked to any device.
Summary
In "application" mode, you can use these authorized topics:
| Direction | Topic | Description |
|---|---|---|
Subscribe |
|
Consume the messages of a fifo |
Publish |
|
Store a DataMessage (specific use case where data is not linked to a device) |
Connection
When initiating the MQTT connection, to select the "application" mode you must use the following credentials:
-
clientId : any string between 1 and 128 characters long, containing no spaces or special characters except :, - or _ . The MQTT protocol indicates it must be unique per connection, but Live Objects does not enforce it.
-
username : application (case sensitive)
-
password : a valid API Key with BUS_R role to subscribe to FIFO and/or DATA_W to publish DataMessage
To find more information regarding Live Objects MQTT endpoints, please refer to: MQTT endpoints
| You must use a secured connection (MQTTS port 8883). The MQTT non-secured connection is not supported for "application" mode. |
FIFO usage
An action policy with FIFO publish action pushes messages to a FIFO queue, allowing the "application" mode to consume them in a reliable way using MQTT subscription.
When creating an action policy with a FIFO publish action, the targeted FIFO is automatically created.
FIFO queues behaviour
Messages are persisted on disk in a FIFO queue until acknowledged or expired.
Each message is delivered to a single consumer; when multiple consumers are subscribed, messages are load-balanced among them. FIFO consumption requires acknowledgement to avoid message loss.
Examples:
-
If a message enters a FIFO with no consumer subscribed, it remains on disk until a consumer subscribes and acknowledges the reception of the message.
-
If a message enters a FIFO while a consumer is subscribed, it is delivered immediately and removed only after acknowledgement; if the consumer does not acknowledge the message, it is returned to the queue and will be delivered to the next available consumer.
There are two ways a message in a FIFO can expire:
-
Expiration delay: if a message is not consumed and acknowledged within the delay defined in your offer settings, it is automatically dropped from the FIFO.
-
noRetention = true: when the action policy sets noRetention to true, unconsumed messages are not kept — without an ongoing MQTT subscription, data messages are dropped immediately.
FIFO subscription
To subscribe to a FIFO queue, a MQTT client connected in "application" mode must subscribe to the following MQTT topic:
fifo/\{fifoName\}
where fifoName is the identifier of the targeted FIFO queue.
This works only if the used API key has no restriction or if the FIFO queue is specified in the API key’s restriction list.
If the subscription succeeds, Live Objects only returns a MQTT SUBACK packet once the subscription is active.
If the subscription fails (for ex. because the FIFO does not exist), a MQTT SUBACK packet is returned based on the MQTT protocol version used. In MQTT 3.1.1, the Failure return code 0x80 will be used. In MQTT 3.1, 0x01 will be returned.
You can refer to your Audit Logs where additional information regarding errors during MQTT connection will be displayed.
Data publication
The nominal way to publish DataMessage is to use MQTT External connector mode and publish a Data as a device.
In some specific use cases you may want to publish data without any device enrichment process, similar to the HTTP data store API.
To publish such DataMessage, a MQTT client connected in "application" mode must publish to the following MQTT topic:
application/v1/data
The payload of this publication should follow:
{
"streamId":"urn:lo:nsid:detector_A8:12435355",
"timestamp":"2019-05-20T16:01:47Z",
"model":"data_v0",
"value":{
"temperature":14.6,
"battery":53,
"messageAlert":"low battery"
},
"location":{
"lat":48.86667,
"lon":2.33333,
"alt":35.2,
"accuracy":12.3,
"provider":"GPS"
},
"tags":[
"production",
"london"
],
"metadata":{
"encoding":"base64",
"source":"urn:lo:nsid:detector_A8:12435355"
}
}| Field | Description |
|---|---|
streamId |
(Mandatory). The streamId where the data will be stored in; and retrieved using the HTTP store API. |
timestamp |
(Optional). Should follow ISO-8601 format. If not set, current timestamp will be used. |
model |
(Optional). Can not contain ' ' (space) or '.' (dot) character. Model is needed to be able to use the search APIs on fields inside the value object. |
value |
(Optional). JSON compliant object. No inner field name should contain '.' (dot) character. |
location |
(Optional). If set, geo-query will be available through search APIs. |
tags |
(Optional) List of additional information used to tag the DataMessage |
metadata.encoding |
(Optional) In order for the data to be enriched by decoders and pipelines functionalities, 'metadata.encoding' field must be set. |
metadata.source |
(Optional) source of the data. |
If the publication succeeds, Live Objects will acknowledge the message according to the QoS level.
If the publication fails (for ex. because the JSON is badly formatted), Live Objects will nevertheless acknowledge the message according to the QoS level, and an AuditLog message will be sent with anomaly details.