MQTT Namespace New (DRAFT)
Kapua provides out of the box support for Kura Devices. Communication take place using an open application protocol built on top of the MQTT communication protocol. The application protocol defines the MQTT name space and the MQTT payload used by Kapua and Kura to interact.
Interactions may be solicited by Kapua to the Kura Device using a request/response messaging model, or unsolicited when the Kura Device simply reports messages or events to a remote server based on periodic or event-driven patterns.
- Unsolicited interactions
- Device lifecycle
- Device data collection
- Solicited interactions
- Request/response conversations
Kapua ensures that MQTT connections are established on behalf of valid Kapua users and that the users are authorised to publish and/or subscribe to topics.
The table below defines some basic terms used in this document:
| Term | Description |
|---|---|
| account_name | Identifies a group of devices and users. It can be seen as partition of the MQTT topic namespace. For example, access control lists can be defined so that users are only given access to the child topics of a given account_name. |
| client_id | Identifies a single gateway device within an account (typically the MAC address of a gateway’s primary network interface). The client_id maps to the Client Identifier (Client ID) as defined in the MQTT specifications. |
| semantic_topic | The application specific part of a topic it is used to group messages by hierarchical criteria. For example if a building is instrumented with temperature sensors and the application is designed to report to Kapua the temperature within the buildings an example of semantic topic could be floor_number/room_name |
| app_id | Unique string identifier for application (e.g., “CONF-V1”, “CONF-V2”, etc.). |
| resource_id | Identifies a resource(s) that is owned and managed by a particular application. Management of resources (e.g., sensors, actuators, local files, or configuration options) includes listing them, reading the latest value, or updating them to a new value. A resource_id may be a hierarchical topic, where, for example, “sensors/temp” may identify a temperature sensor and “sensor/hum” a humidity sensor. |
Device Lifecycle
Device Lifecycle messages are used to manage the connection status of the device and to represent the device properties and capabilities:
- MQTT Connect message
- Kura Birth Certificate message
- Kura Disconnect Certificate message
- MQTT Disconnect message
While Connect and Disconnect messages are MQTT native messages, the Birth and Disconnect certificates are Kura specific.
Birth Certificate
The device uses the Birth Certificate message to describe its properties and capabilities to Kapua. Kapua uses the message content to create its own representation of the device and save it in the Device Registry. The registry is accessible via the Console and the REST API. The Birth Certificate message must be published to the following control topic:
- $EDC/account_name/client_id/MQTT/BC
Disconnect Certificate
The device uses the Disconnect Certificate message to inform Kapua about its intention to terminate the connection. Kapua uses the message to cleanely manage the connection status of the device and represent it within the Device Registry. The Disconnect Certificate message must be published to the following control topic:
- $EDC/account_name/client_id/MQTT/DC
Interaction Flow
The device establishes a connection by sending an MQTT Connect message to Kapua MQTT Endpoint
- The device publishes a BIRTH Certificate message describing its properties and capabilities
- The device publishes data messages and/or the user or a client application execute request/response conversations with the device using for example the Web Console or the REST API
- The device sends a DISCONNECT Certificate message to cleanely close the session
- The device closes the connection by sending an MQTT Disconnect message to Kpaua MQTT Endpoint
Kapua will use the MQTT Keep Alive mechanism to detect if a client device becomes unresponsive or disconnected. In this case the MQTT Last Will and Testament (LWT) feature will be used to inform subscribers if any.
Device Data
The device can publish data by sending a message to the following topic:
- account_name/client_id/semantic_topic
A good practice is to keep the semantic_topic short in lenght and depth (with as few levels as possible).
Request/Response Conversations
Solicited interactions require a request/response message pattern to be established over MQTT. To initiate a solicited conversation, a remote server first sends a request message to a given application running on a specific device and then waits for a response.
To ensure the delivery of request messages, applications that support request/response conversations via MQTT should subscribe to the following topic on startup:
$EDC/account_name/client_id/app_id/#
A requester (i.e., the remote server) initiates a request/response conversation through the following events:
- Generating a conversation identifier known as a request.id (e.g., by concatenating a random number to a timestamp)
- Subscribing to the topic where the response message will be published, where requester.client.id is the client ID of the requester, such as:
$EDC/account_name/requester.client.id/app_id/REPLY/request.id
- Sending the request message to the appropriate application-specific topic with the following fields in the payload:
- request.id (identifier used to match a response with a request)
- requester.client.id (client ID of the requester)
The application receives the request, processes it, and responds on a REPLY topic structured as:
$EDC/account_name/requester.client.id/app_id/REPLY/request.id
For more details regarding request/response conversations please refer to the MQTT Namespace chapter of the Eclipse Kura documentation
Updated 13 days ago