lab/multi-agent-paper
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
multi-agent-paper/gRPC_Based_Interface/docs/references/MQTT_v5_OASIS_Standard.pdf
T
Godopu 06a95a6d5b init
2026-06-25 12:19:20 +09:00

419 lines
20 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
MQTT Version 5.0
OASIS Standard
07 March 2019
NOTE: This file contains the text content extracted from the PDF at:
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.pdf
Specification URIs:
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.docx (Authoritative)
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html
https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.pdf
Technical Committee: OASIS Message Queuing Telemetry Transport (MQTT) TC
Editors: Andrew Banks (IBM), Ed Briggs (Microsoft), Ken Borgendale (IBM), Rahul Gupta (IBM)
Abstract:
MQTT is a Client Server publish/subscribe messaging transport protocol. It is light weight, open,
simple, and designed to be easy to implement. These characteristics make it ideal for use in many
situations, including constrained environments such as Machine to Machine (M2M) and Internet
of Things (IoT) contexts where a small code footprint is required and/or network bandwidth is
at a premium.
The protocol runs over TCP/IP, or over other network protocols that provide ordered, lossless,
bidirectional connections. Its features include:
- Use of the publish/subscribe message pattern which provides one-to-many message
distribution and decoupling of applications.
- A messaging transport that is agnostic to the content of the payload.
- Three qualities of service for message delivery:
o "At most once": messages delivered according to best efforts; message loss can occur.
o "At least once": messages assured to arrive but duplicates can occur.
o "Exactly once": messages assured to arrive exactly once.
- A small transport overhead and protocol exchanges minimized to reduce network traffic.
- A mechanism to notify interested parties when an abnormal disconnection occurs.
Copyright © OASIS Open 2019. All Rights Reserved.
================================================================================
Table of Contents
================================================================================
1 Introduction
1.1 Organization of the MQTT specification
1.2 Terminology
1.3 Normative references
1.4 Non-normative references
1.5 Data representation
1.5.1 Bits
1.5.2 Two Byte Integer
1.5.3 Four Byte Integer
1.5.4 UTF-8 Encoded String
1.5.5 Variable Byte Integer
1.5.6 Binary Data
1.5.7 UTF-8 String Pair
1.6 Security
1.7 Editing convention
1.8 Change history
2 MQTT Control Packet format
2.1 Structure of an MQTT Control Packet
2.1.1 Fixed Header
2.1.2 MQTT Control Packet type
2.1.3 Flags
2.1.4 Remaining Length
2.2 Variable Header
2.2.1 Packet Identifier
2.2.2 Properties
2.3 Payload
2.4 Reason Code
3 MQTT Control Packets
3.1 CONNECT – Connection Request
3.2 CONNACK – Connect acknowledgement
3.3 PUBLISH – Publish message
3.4 PUBACK – Publish acknowledgement (QoS 1)
3.5 PUBREC – Publish received (QoS 2 delivery part 1)
3.6 PUBREL – Publish release (QoS 2 delivery part 2)
3.7 PUBCOMP – Publish complete (QoS 2 delivery part 3)
3.8 SUBSCRIBE – Subscribe request
3.9 SUBACK – Subscribe acknowledgement
3.10 UNSUBSCRIBE – Unsubscribe request
3.11 UNSUBACK – Unsubscribe acknowledgement
3.12 PINGREQ – PING request
3.13 PINGRESP – PING response
3.14 DISCONNECT – Disconnect notification
3.15 AUTH – Authentication exchange
4 Operational behavior
4.1 Session State
4.2 Network Connections
4.3 Quality of Service levels and protocol flows
4.4 Message delivery retry
4.5 Message receipt
4.6 Message ordering
4.7 Topic Names and Topic Filters
4.8 Subscriptions
4.9 Flow Control
4.10 Request / Response
4.11 Server redirection
4.12 Enhanced authentication
4.13 Handling errors
5 Security (non-normative)
6 Using WebSocket as a network transport
7 Conformance
Appendix A. Summary of new features in MQTT v5.0
Appendix B. Mandatory normative statements
Appendix C. Non-normative bibliographic references
================================================================================
1 Introduction
================================================================================
1.1 Organization of the MQTT specification
Chapter 1 - Introduction
Chapter 2 - MQTT Control Packet format
Chapter 3 - MQTT Control Packets
Chapter 4 - Operational behavior
Chapter 5 - Security
Chapter 6 - Using WebSocket as a network transport
Chapter 7 - Conformance Targets
1.2 Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be
interpreted as described in IETF RFC 2119.
Key terms:
- **Application Message**: The data carried by the MQTT protocol across the network
- **Client**: A program or device that uses MQTT. A Client always establishes the Network Connection
to the Server. It can Publish Application Messages, Subscribe/Unsubscribe to request messages.
- **Server**: A program or device that acts as an intermediary between Clients which publish
Application Messages and Clients which have made Subscriptions.
- **Session**: A stateful interaction between a Client and a Server. Can span more than one Network Connection.
- **Subscription**: A Subscription comprises a Topic Filter and a maximum QoS. Associated with a single Session.
- **Shared Subscription**: A Subscription with multiple Clients to allow load balancing.
- **Wildcard Subscription**: A Subscription using a Topic Filter containing a wildcard character.
- **Topic Name**: A label attached to an Application Message which is matched against Subscriptions.
- **Topic Filter**: An expression in a Subscription to indicate matching Topic Names.
- **MQTT Control Packet**: A packet of information sent across the Network Connection. The MQTT
specification defines fifteen different types.
- **Malformed Packet**: A Control Packet that cannot be parsed according to this specification.
- **Protocol Error**: An error discovered after packet parsing which does not conform to the specification.
- **Will Message**: An Application Message which is published by the Server after the Network
Connection is closed in cases where the Network Connection is not closed normally.
- **Disallowed Unicode code point**: Code points defined in section 1.5.4 which should not appear
in a UTF-8 Encoded String.
1.5 Data representation
1.5.2 Two Byte Integer
Two Byte Integer values are 16-bit unsigned integers in big-endian order: high order byte followed
by low order byte. This means a 16-bit word is presented on the network as Most Significant Byte
(MSB), followed by Least Significant Byte (LSB).
1.5.3 Four Byte Integer
Four Byte Integer values are 32-bit unsigned integers in big-endian order.
1.5.4 UTF-8 Encoded String
Text fields within the MQTT Control Packets are encoded as UTF-8 strings.
- Maximum size: 65,535 bytes
- A UTF-8 Encoded String MUST NOT include an encoding of the null character U+0000.
- A UTF-8 encoded sequence 0xEF 0xBB 0xBF is always interpreted as U+FEFF (ZERO WIDTH
NO-BREAK SPACE) wherever it appears in a string; it MUST NOT be skipped over or stripped
off by a packet receiver.
1.5.5 Variable Byte Integer
The Variable Byte Integer uses a scheme where the low seven bits of each byte encode the data,
and the high bit indicates whether there are bytes following in the representation.
- 1 byte: 0 to 127
- 2 bytes: 128 to 16,383
- 3 bytes: 16,384 to 2,097,151
- 4 bytes: 2,097,152 to 268,435,455
================================================================================
2 MQTT Control Packet format
================================================================================
2.1.2 MQTT Control Packet type
| Name | Value | Direction of flow | Description |
|----------|-------|----------------------|--------------------------|
| CONNECT | 1 | Client to Server | Connection request |
| CONNACK | 2 | Server to Client | Connect acknowledgement |
| PUBLISH | 3 | Client to Server or | Publish message |
| | | Server to Client | |
| PUBACK | 4 | Client to Server or | Publish acknowledgement |
| | | Server to Client | (QoS 1) |
| PUBREC | 5 | Client to Server or | Publish received |
| | | Server to Client | (QoS 2 delivery part 1) |
| PUBREL | 6 | Client to Server or | Publish release |
| | | Server to Client | (QoS 2 delivery part 2) |
| PUBCOMP | 7 | Client to Server or | Publish complete |
| | | Server to Client | (QoS 2 delivery part 3) |
| SUBSCRIBE| 8 | Client to Server | Subscribe request |
| SUBACK | 9 | Server to Client | Subscribe acknowledgement|
| UNSUBSCRIBE|10 | Client to Server | Unsubscribe request |
| UNSUBACK | 11 | Server to Client | Unsubscribe acknowledge |
| PINGREQ | 12 | Client to Server | PING request |
| PINGRESP | 13 | Server to Client | PING response |
| DISCONNECT|14 | Client to Server or | Disconnect notification |
| | | Server to Client | |
| AUTH | 15 | Client to Server or | Authentication exchange |
| | | Server to Client | |
2.2.2 Properties
Properties were introduced in MQTT v5.0 to provide extensibility.
Each property has an identifier encoded as a Variable Byte Integer.
Key properties (by packet type):
- Payload Format Indicator (0x01): PUBLISH
- Message Expiry Interval (0x02): PUBLISH
- Content Type (0x03): PUBLISH
- Response Topic (0x08): PUBLISH
- Correlation Data (0x09): PUBLISH
- Subscription Identifier (0x0B): PUBLISH, SUBSCRIBE
- Session Expiry Interval (0x11): CONNECT, CONNACK, DISCONNECT
- Assigned Client Identifier (0x12): CONNACK
- Server Keep Alive (0x13): CONNACK
- Authentication Method (0x15): CONNECT, CONNACK, AUTH
- Authentication Data (0x16): CONNECT, CONNACK, AUTH
- Request Problem Information (0x17): CONNECT
- Will Delay Interval (0x18): Will Properties
- Request Response Information (0x19): CONNECT
- Response Information (0x1A): CONNACK
- Server Reference (0x1C): CONNACK, DISCONNECT
- Reason String (0x1F): CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP,
SUBACK, UNSUBACK, DISCONNECT, AUTH
- Receive Maximum (0x21): CONNECT, CONNACK
- Topic Alias Maximum (0x22): CONNECT, CONNACK
- Topic Alias (0x23): PUBLISH
- Maximum QoS (0x24): CONNACK
- Retain Available (0x25): CONNACK
- User Property (0x26): All packets
- Maximum Packet Size (0x27): CONNECT, CONNACK
- Wildcard Subscription Available (0x28): CONNACK
- Subscription Identifier Available (0x29): CONNACK
- Shared Subscription Available (0x2A): CONNACK
2.4 Reason Code
New in MQTT v5.0. Reason Codes communicate the result of an operation.
| Dec | Hex | Name | Packets |
|-----|------|-------------------------------|--------------------------------------|
| 0 | 0x00 | Success/Normal disconnection | CONNACK, PUBACK, PUBREC, PUBREL, |
| | | | PUBCOMP, UNSUBACK, AUTH, DISCONNECT |
| 1 | 0x01 | Granted QoS 1 | SUBACK |
| 2 | 0x02 | Granted QoS 2 | SUBACK |
| 4 | 0x04 | Disconnect with Will Message | DISCONNECT |
| 16 | 0x10 | No matching subscribers | PUBACK, PUBREC |
| 17 | 0x11 | No subscription found | UNSUBACK |
| 24 | 0x18 | Continue authentication | AUTH |
| 25 | 0x19 | Re-authenticate | AUTH |
| 128 | 0x80 | Unspecified error | CONNACK, PUBACK, PUBREC, SUBACK, |
| | | | UNSUBACK, DISCONNECT |
| 129 | 0x81 | Malformed Packet | CONNACK, DISCONNECT |
| 130 | 0x82 | Protocol Error | CONNACK, DISCONNECT |
| 131 | 0x83 | Implementation specific error | CONNACK, PUBACK, PUBREC, SUBACK, |
| | | | UNSUBACK, DISCONNECT |
| 132 | 0x84 | Unsupported Protocol Version | CONNACK |
| 133 | 0x85 | Client Identifier not valid | CONNACK |
| 134 | 0x86 | Bad User Name or Password | CONNACK |
| 135 | 0x87 | Not authorized | CONNACK, PUBACK, PUBREC, SUBACK, |
| | | | UNSUBACK, DISCONNECT |
| 136 | 0x88 | Server unavailable | CONNACK |
| 137 | 0x89 | Server busy | CONNACK, DISCONNECT |
| 144 | 0x90 | Topic Name invalid | CONNACK, PUBACK, PUBREC, DISCONNECT |
| 145 | 0x91 | Packet Identifier in use | PUBACK, PUBREC, SUBACK, UNSUBACK |
| 146 | 0x92 | Packet Identifier not found | PUBREL, PUBCOMP |
| 147 | 0x93 | Receive Maximum exceeded | DISCONNECT |
| 148 | 0x94 | Topic Alias invalid | DISCONNECT |
| 149 | 0x95 | Packet too large | CONNACK, DISCONNECT |
| 151 | 0x97 | Quota exceeded | CONNACK, PUBACK, PUBREC, SUBACK, |
| | | | DISCONNECT |
| 153 | 0x99 | Payload format invalid | CONNACK, PUBACK, PUBREC, DISCONNECT |
| 154 | 0x9A | Retain not supported | CONNACK, DISCONNECT |
| 155 | 0x9B | QoS not supported | CONNACK, DISCONNECT |
| 156 | 0x9C | Use another server | CONNACK, DISCONNECT |
| 157 | 0x9D | Server moved | CONNACK, DISCONNECT |
| 158 | 0x9E | Shared Subscriptions not supported | CONNACK, SUBACK, DISCONNECT |
| 159 | 0x9F | Connection rate exceeded | CONNACK, DISCONNECT |
| 160 | 0xA0 | Maximum connect time | DISCONNECT |
| 161 | 0xA1 | Subscription Identifiers not supported | CONNACK, SUBACK, DISCONNECT |
| 162 | 0xA2 | Wildcard Subscriptions not supported | CONNACK, SUBACK, DISCONNECT |
================================================================================
3 MQTT Control Packets (Key Sections)
================================================================================
3.1 CONNECT – Connection Request
3.1.2.3 Connect Flags
Connect Flags byte contains parameters specifying the behavior of the MQTT Connection:
- Bit 7: User Name Flag
- Bit 6: Password Flag
- Bit 5: Will Retain
- Bits 4-3: Will QoS
- Bit 2: Will Flag
- Bit 1: Clean Start
- Bit 0: Reserved (MUST be 0)
3.1.2.4 Clean Start
Bit 1 of Connect Flags. If set to 1, the Client and Server MUST discard any existing Session
and start a new Session. If set to 0, the Server MUST resume communications based on the
state from any existing Session.
3.1.2.11.3 Receive Maximum
Two Byte Integer. Client uses this to limit the number of QoS 1 and QoS 2 publications
that it is willing to process concurrently. Default: 65,535.
3.1.2.11.2 Session Expiry Interval
Four Byte Integer. Represents the Session Expiry Interval in seconds. If 0 or absent: Session
ends when Network Connection is closed. If 0xFFFFFFFF: Session does not expire.
3.3 PUBLISH – Publish message
3.3.1.1 DUP flag: Bit 3. If set to 0, indicates first delivery of this PUBLISH packet.
3.3.1.2 QoS level: Bits 2-1. Quality of Service level:
- 0b00 (0): At most once delivery
- 0b01 (1): At least once delivery
- 0b10 (2): Exactly once delivery
- 0b11 (3): MUST NOT be used
3.3.1.3 RETAIN flag: Bit 0. If set to 1, Application Message is stored by the Server.
3.3.2.1 Topic Name: MUST NOT contain wildcard characters.
3.3.2.2 Packet Identifier: Only present for QoS 1 and QoS 2.
3.8 SUBSCRIBE – Subscribe request
3.8.4 SUBSCRIBE Payload:
Each Subscription consists of:
- Topic Filter (UTF-8 string)
- Subscription Options byte:
- Bits 0-1: Maximum QoS
- Bit 2: No Local (don't receive own publishes)
- Bit 3: Retain As Published
- Bits 4-5: Retain Handling
- 0: Send retained at subscribe
- 1: Send only if new subscription
- 2: Do not send retained at subscribe
================================================================================
4 Operational Behavior (Key Sections)
================================================================================
4.3 Quality of Service levels and protocol flows
4.3.1 QoS 0: At most once delivery
The sender sends the PUBLISH packet.
No response, no retry.
4.3.2 QoS 1: At least once delivery
Sender -> Receiver: PUBLISH (Packet Identifier X)
Receiver -> Sender: PUBACK (Packet Identifier X)
If Sender does not receive PUBACK, it retransmits with DUP=1.
4.3.3 QoS 2: Exactly once delivery
Sender -> Receiver: PUBLISH (Packet Identifier X)
Receiver -> Sender: PUBREC (Packet Identifier X)
Sender -> Receiver: PUBREL (Packet Identifier X)
Receiver -> Sender: PUBCOMP (Packet Identifier X)
4.7 Topic Names and Topic Filters
Topic level separator: '/' (forward slash, U+002F)
Wildcards:
- '#' (Number sign, U+0023): Multi-level wildcard. MUST be the last character in the Topic
Filter, preceded only by a separator. Example: "sport/#"
- '+' (Plus sign, U+002B): Single-level wildcard. Example: "sport/+/player1"
Topic Names and Topic Filters beginning with '$' are reserved for Server-internal use.
A Subscription Topic Filter starting with '$' MUST NOT be matched by a Topic Name beginning
with a topic level not starting with '$'.
4.9 Flow Control (NEW in v5.0)
- Client sends CONNECT with Receive Maximum value (e.g., 10)
- Server tracks how many PUBLISH packets with QoS>0 are unacknowledged
- Server MUST NOT send more QoS 1 or QoS 2 PUBLISH packets to the Client than allowed
by the Receive Maximum
4.10 Request / Response (NEW in v5.0)
MQTT v5.0 includes a Request/Response pattern:
- Requestor sends PUBLISH with Response Topic and optional Correlation Data
- Responder publishes to Response Topic with same Correlation Data
- Enables point-to-point communication without pre-knowledge of each other
4.12 Enhanced authentication (NEW in v5.0)
Extended authentication allows the use of challenge/response style authentication:
1. Client sends CONNECT with Authentication Method property
2. Server sends AUTH (0x18 Continue authentication) with Authentication Data
3. Client responds with AUTH containing more Authentication Data
4. Exchange continues until Server sends CONNACK (success or failure)
================================================================================
Appendix A. Summary of new features in MQTT v5.0
================================================================================
New features compared to MQTT v3.1.1:
1. **Session expiry**: Separate control of when session state should be discarded
2. **Message expiry**: Expiry time for application messages
3. **Reason codes on all ACKs**: All response packets include a Reason Code
4. **Reason string**: Optional human-readable reason string on most packets
5. **Server disconnect**: Server can now send DISCONNECT to indicate why the connection was closed
6. **Payload format and content type**: Description of application message content
7. **Request/Response**: Pattern support with Response Topic and Correlation Data
8. **Shared Subscriptions**: Allows load-balanced message processing
9. **Subscription identifier**: Client can specify an identifier in SUBSCRIBE
10. **Topic alias**: Reduces overhead by using integer instead of Topic Name
11. **Flow control**: Client and Server can specify how many simultaneous messages they can handle
12. **User properties**: On most packets, arbitrary name-value string pairs
13. **Maximum packet size**: Client and Server can specify maximum packet size they can handle
14. **Server reference**: CONNACK and DISCONNECT can indicate another Server to use
15. **Enhanced authentication**: Challenge/response style authentication
16. **Will delay**: Delay publication of Will Messages at end of session
Reference in New Issue View Git Blame Copy Permalink