Skip to content

Latest commit

 

History

History
239 lines (171 loc) · 9.11 KB

mqtt_5.adoc

File metadata and controls

239 lines (171 loc) · 9.11 KB

MQTT 5 Transport Protocol

Table of Contents

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

1. Overview

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 will discuss the uTransport implementation on MQTT 5 for two well known use cases: 1. Device-2-Device (D2D) Communication: This is when devices (through the streamer) was to send messages to other devices through a cloud gateway (broker). 2. uE-2-uE Communication: When MQTT is used as a local software bus for uEs to talk to each other through a local broker.

The reason for the different configurations is that cloud MQTT brokers often have limitations on the number of topics that can be subscribed to as well as the topic segment lengths so we need to ensure that message routing is as efficient as possible.

2. MQTT5 Header

MQTT 5 supports custom header fields, and we leverage this to map the UAttributes values into the UserProperty MQTT header in string format.

  • All non-empty attribute values MUST be mapped to MQTT header User Properties using the keys defined below.

  • Empty attribute values MUST NOT be mapped.

Table 1. uAttributes Mapping to MQTT5 User Properties
key value Description

"0"

"1"

The version of the UAttributes protobuf

  • MUST represent the major version of the UAttributes protobuf. Currently should be set to 1.

"1"

"{UAttributes.id}"

Unique identifier for the message

"2"

"{UAttributes.type}"

The type of message

"3"

"{UAttributes.source}"

The origin (address) of the message

"4"

"{UAttributes.sink}"

The destination (address) of the message

"5"

"{UAttributes.priority}"

The message’s priority as defined in QoS doc

  • MUST be set to the enum value for UAttributes.priority UPriority enum.

"6"

"{UAttributes.ttl}"

The amount of time (in milliseconds) after which this message MUST NOT be delivered/processed anymore

  • MUST be set to the TTL value in milliseconds as a string.

"7"

"{UAttributes.permissionLevel}"

The service consumer’s permission level as defined in Code-Based uE Access Permissions (CAPs)

  • MUST be set to the CAPs's integer value as a string.

"8"

"{UAttributes.commStatus}"

A UCode indicating an error that has occurred during the delivery of either an RPC Request or Response message

  • MUST be set to the UCode's integer value as a string.

"9"

"{UAttributes.reqId}"

The identifier that a service consumer can use to correlate an RPC response message with its RPC request

"10"

"{UAttributes.token}"

The service consumer’s access token

  • MUST be the token value as a string.

"11"

"{UAttributes.traceparent}"

A tracing identifier to use for correlating messages across the system

  • MUST be set to the traceparent value as a string.

"12"

"{UAttributes.payload_format}"

The format for the data stored in the UMessage

All uAttributes are mapped to a MQTT header UserProperty, where the key is the UAttributes protobuf field number. The value is a string representation of the UAttributes field. Only UAttributes that are used in the message are included in the MQTT header. If a UAttributes field is not present in the header, than it is considered not used when recompiling the UAttributes.

3. Payload Encoding

  • The MQTT payload MUST be the UMessage.payload field, which is a byte array to reduce size.

4. MQTT5 Topics

The MQTT topic a message is published on utilizes the source and sink UUri fields. The topic is dependent on the use case for the transport implementation that will be discussed below.

4.1. uE-2-uE Communication

When MQTT5 (broker) is used for local (within a device) uE-2-uE communication, the topic shall consist of the entire source and sink UUri from UAttributes as shown below:

{source.authority_name}/{source.ue_id}/{source.ue_version_major}/{source.resource_id}/{sink.authority_name}/{sink.ue_id}/{sink.ue_version_major}/{sink.resource_id}

If the messages does not have a sink UUri, then the sink portion of the MQTT5 topic MUST be omitted.

4.1.1. Examples

Table 2. uE-2-uE Communication Topics
Type source URI sink URI MQTT5 Topic

Request

//device1/AB34/1/0

//device1/43BA/1/2

device1/AB34/1/0/device1/43BA/1/2

Response

//device1/43BA/1/2

//device1/AB34/1/0

device1/43BA/1/2/device1/AB34/1/0

Publish

//device1/AB34/1/8000

None

device1/AB34/1/8000

Notification

//device1/43BA/1/8001

//device1/AB34/1/0

device1/43BA/1/8001/device1/AB34/1/0
Table 3. uE-2-uE Communication UTransport::registerListener() Examples
Use Case source filter sink filter MQTT Subscription

Single Publish Topic

//device1/AB34/1/8000

None

device1/AB34/1/8000

Incoming requests for a Method

empty

//device1/AB34/1/12CD

+/+/+/+/device1/AB34/1/12CD

Any Notifications or RPC Responses

empty

//device1/AB34/1/0

+/+/+/+/device1/AB34/1/0

4.2. D2D Communication

When MQTT5 (broker) is used for D2D communication, the topic shall consist of only the authority portion of the source and sink UUri from UAttributes as shown below:

{source.authority_name}/{sink.authority_name}

4.2.1. Examples

Registering Listener to Receive All Messages

UTransport::registerListener(ANY, getSource()) where getSource() returns the local device’s UUri, this translates into the MQTT subscribe to topic +/{my_source_authority_name}

Sending a Message

UTransport::send(UMessage) translates to the MQTT publish to topic {UMessage.source.authority_name}/{UMessage.sink.authority_name}