Data Service Configuration

The DataService provides the ability to connect to a remote broker, publish messages, subscribe to topics, receive messages on the subscribed topics, and disconnect from the remote message broker. The DataService delegates to the MqttDataTransport service the implementation of the transport protocol that is used to interact with the remote server.

The DataService also adds the capability of storing published messages in a persistent store function and sending them over the wire at a later time. The purpose of this feature is to relieve service users from implementing their own persistent store. Service users may publish messages independently on the DataService connection status.

📘

Note

Starting from ESF 7.3.0, the DataService allows to bind to custom persistent stores. A custom persistent store can be defined by creating an implementation the new org.eclipse.kura.message.store.provider.MessageStoreProvider service interface and registering it as an OSGi service.

In order to overcome the potential latencies introduced by buffering messages, the DataService allows a priority level to be assigned to​ each published message. Depending on the store configuration, there are certain guarantees that stored messages are not lost due to sudden crashes or power outages.

To use this service, select the DataService option located in the Cloud Services area as shown in the screen capture below.

The DataService offers methods and configuration options to manage the connection to the remote server including the following (all required) parameters described below.

• Connect Auto-on-startup - When set to true, the service tries to auto-connect to the remote server on start-up and restore the connection every time the device is disconnected. These attempts are made at the frequency defined in the Connect Retry-interval parameter until the connection is established.
  Using the Connect/Disconnect button disables this function.
• Connect Retry-interval - Frequency in seconds to retry a connection of the Data Publishers after a disconnect.
• Enable Recovery On Connection Failure - Enables the recovery feature on connection failure. If the device is not able to connect to a remote cloud platform, the service will wait for a specified amount of connection retries. If the recovery fails, the device will be rebooted. Being based on the Watchdog service, it needs to be activated as well.
• Connection Recovery Max Failure - Number of failures in Data Publishers connection before forcing a reboot.
• Disconnect Quiesce-timeout - Allows the delivery of in-flight messages to be completed before disconnecting from the broker when a disconnection from the broker is being forced.
• Message Store Provider Service PID - The Kura service pid of the Message Store instance to be used. The pid of the default instance is org.eclipse.kura.db.H2DbService. The Message Store instance must implement the org.eclipse.kura.message.store.provider.MessageStoreProvider interface.
• Store Housekeeper-interval - Defines the interval in seconds used to run the Data Store housekeeper task.
• Store Purge-age - defines the age in seconds of completed messages (either published with QoS = 0 or confirmed with QoS > 0) after which they are deleted (minimum 5).
• Store Capacity - Defines the maximum number of messages persisted in the Data Store.
• In-flight-messages parameters - Define the management of messages that have been published and not yet confirmed, including:
  • In-flight-messages Republish-on-new-session - Whether to republish in-flight messages on a new MQTT session.
  • In-flight-messages Max-number - The maximum number of in-flight messages.
  • In-flight-messages Congestion-timeout - Timeouts the in-flight messages congestion condition. The service will force a disconnect attempting to reconnect (0 to disable).

Message Publishing Backoff Delay

In order to have a finer control on the data flow, when a device reconnects to a remote cloud platform, Kura integrates into the Data Service a Backoff delay feature that limits the rate of messages sent.

This feature, enabled by default, integrates the Token Bucket concept to limit the bursts of messages sent to a remote cloud platform.

• Enable Rate Limit - Enables the token bucket message rate limiting.
• Rate Limit Average - he average message publish rate in number of messages per unit of time (e.g. 10 messages per MINUTE).

🚧

Average message rate limitations

The maximum allowed message rate is 1 message per millisecond, so the following limitations are applied:

• 86400000 per DAY
• 3600000 per HOUR
• 60000 messages per MINUTE
• 1000 messages per SECOND

• Rate Limit Time Unit - The time unit for the Rate Limit Average.
• Rate Limit Burst Size - The token bucket burst size.