The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)
SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation See the NOTICE file(s) distributed with this work for additional information regarding copyright ownership. This program and the accompanying materials are made available under the terms of the Apache License Version 2.0 which is available at https://www.apache.org/licenses/LICENSE-2.0 SPDX-FileType: DOCUMENTATION SPDX-License-Identifier: Apache-2.0
MQTT is an OASIS standard messaging protocol for the Internet of Things (IoT). It is designed as an extremely lightweight publish/subscribe messaging transport that is ideal for connecting remote devices with a small code footprint and minimal network bandwidth. MQTT today is used in a wide variety of industries, such as automotive, manufacturing, telecommunications, oil and gas etc.
For more information, please refer to https://mqtt.org/
This document defines how MQTT 5 PUBLISH packets can be used to transfer uProtocol messages (UMessages) between uEntities for the following use cases:
-
uEntity-2-uEntity (E2E): Communication between uEntities within the same vehicle by means of an in-vehicle MQTT broker.
-
Device-2-Device (D2D): Communication between uEntities in vehicles and a (cloud) back end system by means of an off-vehicle MQTT broker, e.g. running in the back end. MQTT brokers running on cloud infrastructure often have limitations regarding the number of topics that can be subscribed and the number of segments those topics may contain. The mapping for this use case therefore uses a coarser grained topic structure than the one for in-vehicle only communication.
A uProtocol message consists of UAttributes and optional payload. The following sections define how these are mapped to/from an MQTT 5 PUBLISH packet.
An MQTT 5 PUBLISH packet that is used to convey a uProtocol message MUST contain properties as defined in [uAttributes Mapping to MQTT 5 PUBLISH Properties] for those and only those of the UMessage’s attributes which have a non-empty value.
uAttributes Property |
PUBLISH Packet Property |
Description |
N/A |
User Property [key: uP] |
The uProtocol version being used
|
id |
User Property [key: 1] |
The unique identifier of the message
|
type |
User Property [key: 2] |
The message type
|
source |
User Property [key: 3] |
The origin (address) of the message
|
sink |
User Property [key: 4] |
The destination (address) of the message
|
priority |
User Property [key: 5] |
The message’s service class as defined in Message Priority
|
ttl |
User Property [key: 6] |
The amount of time after which this message must no be delivered/processed anymore The Message Expiry Interval property MUST be set to \(expiry := ceil(ttl/1000)\). The User Property MUST be set to the value of ttl if, and only if \(ttl \bmod 1000 > 0\). This is necessary to retain the original value for the receiving end, because the MQTT message expiry interval has second granularity only. If the TTL is a multiple of 1000, i.e. has second granularity as well, then it is sufficient to set the Message Expiry Interval, from which the receiving side can derive the original TTL. |
permissionLevel |
User Property [key: 7] |
The service consumer’s permission level as defined in Code-Based uEntity Access Permissions (CAPs)
|
commStatus |
User Property [key: 8] |
A UCode indicating an error that has occurred during the delivery of either an RPC Request or Response message
|
reqId |
Correlation Data |
The identifier that a service consumer can use to correlate an RPC response message with its RPC request
|
token |
User Property [key: 10] |
The service consumer’s access token
|
traceparent |
User Property [key: 11] |
A tracing identifier to use for correlating messages across the system
|
payload_format |
Content Type |
The type of data contained in the message’s payload
Note that the enum’s integer value is used instead of the uprotocol.mime_type option’s value in order to reduce the overall size of the PUBLISH packet. |
Message producers publish messages to topics maintained by an MQTT broker. Other clients can then subscribe to such topics in order to receive the messages that are being published to these topics.
The topic name of an MQTT 5 PUBLISH packet that is used to transfer a uProtocol message is derived from the message’s source and sink attributes.
The topic name of an MQTT 5 PUBLISH packet containing a Publish UMessage that is published to an in-vehicle broker MUST consist of the following segments:
{source.authority}/{source.ue_type}/{source.ue_instance}/{source.ue_version}/{source.resource}
The topic name of an MQTT 5 PUBLISH packet containing a Notification, RPC Request or RPC Response UMessage that is published to an in-vehicle broker MUST consist of the following segments:
{source.authority}/{source.ue_type}/{source.ue_instance}/{source.ue_version}/{source.resource}/{sink.authority}/{sink.ue_type}/{sink.ue_instance}/{sink.ue_version}/{sink.resource}
Please refer to UUri Encoding Rules for details regarding the encoding of the source and sink UUris into the topic’s segments.
The examples below show the MQTT 5 topic names to use for sending different types of UMessages via an in-vehicle broker. The sending uEntity has uEntity type ID 3BA.
Source URI |
|
Sink URI |
- |
MQTT Topic Name |
|
Source URI |
|
Sink URI |
|
MQTT Topic Name |
|
Source URI |
|
Sink URI |
|
MQTT Topic Name |
|
Source URI |
|
Sink URI |
|
MQTT Topic Name |
|
The examples below show the MQTT 5 topic filters to use for receiving different types of UMessages via an in-vehicle broker. The receiving uEntity has uEntity type ID AB.
Source Filter |
|
Sink Filter |
- |
MQTT Topic Filter |
|
Source Filter |
|
Sink Filter |
|
MQTT Topic Filter |
|
Source Filter |
- |
Sink Filter |
|
MQTT Topic Filter |
|
Source Filter |
- |
Sink Filter |
|
MQTT Topic Filter |
|
The topic name of an MQTT 5 PUBLISH packet containing a UMessage that is published to an off-vehicle broker MUST consist of the following segments:
{source.authority}/{sink.authority}
Please refer to UUri Encoding Rules for details regarding the encoding of the source and sink UUris into topic segments.
The MQTT 5 topic name used by uEntities with authority name vehicle1 for sending any type of UMessage to uEntities with authority name backend via an off-vehicle broker is
vehicle1/backend
The MQTT 5 topic filter used by uEntities with authority name backend for receiving all types of UMessages from uEntities with arbitrary authority names via an off-vehicle broker is
+/backend
The table below contains the rules for encoding a UUri’s fields into an MQTT topic name’s or filter’s segments.
Topic Segment |
UUri Field |
Encoding |
|
|
The segment MUST contain the (UTF8) string representation of the
|
|
|
The segment MUST contain the (UTF8) string representation of the
|
|
|
The segment MUST contain the (UTF8) string representation of the
|
|
|
The segment MUST contain the (UTF8) string representation of the
|
|
|
The segment MUST contain the (UTF8) string representation of the
|
Each transport implementing this specification MUST provide means to configure the values of the Session Expiry Interval and Clean Start properties of the MQTT CONNECT packet being used when establishing a connection to a broker.
Each transport implementing this specification MUST
-
re-establish a lost connection to an MQTT broker using an exponential backoff strategy.
-
re-subscribe to all previously subscribed topics, if the broker indicates that no session is present after successful reconnection.
The following table provides some guidance for implementation:
Reconnect attempt |
1 |
2 |
3 |
4 |
n > 4 |
Backoff (ms) |
|
|
|
|
|