Last updated
Last updated
(Message Queuing Telemetry Transport) is a lightweight and widely adopted messaging protocol well-suited for resource-constrained devices.
If a device communicates over MQTT with akenza, an MQTT data flow has to be set up.
There are two ways to authenticate: device credentials with JWTs use a per-device public/private key pair with JSON Web Tokens (JWTs, ) and uplink secrets use a shared key per device connector that is passed as a password to the MQTT broker. The authentication type can be selected during creation of the device connector.
Refer to for a more in-depth introduction into the authentication options.
Using device credentials
Using the private key, a JWT has to be generated that is sent as the MQTT password when setting up connection to the akenza MQTT broker.
MQTT username: arbitrary username (not used). Depending on framework this needs to be set in order for the password to be sent as well
MQTT password: must be a valid JWT signed with the private key. Refer to
MQTT client id: the clientId
must be the deviceId
MQTT topic: a topic with the following structure
uplink topic: /up/device/id/{deviceId}
downlink topic: /down/device/id/{deviceId}/#
Using uplink secret
After the creation of the MQTT device connector, a secret is generated which needs to be provided in the topic structure of the uplink request.
MQTT username: the device connector id
MQTT password: the device connector secret
MQTT topic: a topic with the following structure
uplink topic: /up/<deviceConnectorSecret>/id/<deviceID>
downlink topic: /up/<deviceConnectorSecret>/id/<deviceID>/#
It is possible to additionally specify a sub topic by appending it to the uplink topic, e.g. /up/device/id/{deviceId}/alerts
will result in the akenza topic alerts
. The subtopic will be used as the topic under which data is stored in akenza and is available in the uplink decoder script of the device type. If multiple levels of subtopics are specified, the resulting topic will be separated by underscores, e.g. /up/device/id/{deviceId}/alerts/critical
will result in alerts_critical
.
Subscribing to downlinks is possible by providing the following info:
MQTT username: the device connector id
MQTT password: the device connector secret
MQTT topic: a topic with the following structure /down/<deviceConnectorSecret>/id/<deviceID>
The downlink topic added in akenza will be appended to the topic subscribed to e.g. when providing "myTopic" the resulting downlink topic will look as follows: /down/{0}/id/{1}/myTopic.
akenza allows sending data using transport layer security (TLS). For this the port 8883 has to be used.
Why am I getting a certificate expired error?
With MQTT v5 it is possible to send different content types by setting the ContentType property. The supported MIME types are:
application/json
text/plain
application/octet-stream
application/xml
text/csv
If this property is not set, a published message will be interpreted as a JSON message.
A set of examples for using MQTT with akenza can be found here:
Refer to the documentation for more information.
Akenza is using an ISRG Root X1 root certificate provided by Let's Encrypt to sign certificates. If your device is older, it might not contain an up to date root certificate. Aquire the root certificate from and update your trust store accordingly.
This page describes MQTT Connectivity in more detail