MQTT Transport
←Transports · Index↑ · Transport - Websocket→
This document describes the use of the MQTT transport.
Other sections can be accessed from the Overview.
1. Introduction
- Simple and lightweight
- Broker based
- Can be used on top of TCP or WebSockets
- Can use encryption
- Supports various QOS settings for message delivery
- Inherently solves the problem of late joiners using retained messages
- Events filtering is handled by the broker with topic filtering mechanics
2. NMOS Resources transport
NMOS resources using MQTT will use the urn:x-nmos:transport:mqtt transport.
3. Connection management
Only IS-05 connection management will be used for connection management of resources defined in this specification.
3.1 broker_topic
The broker_topic parameter will hold the MQTT topic and will always be set to the source id, prefixed with x-nmos/source/ for easier filtering.
3.2 ext_is_07_rest_api_url
The ext_is_07_rest_api_url parameter will represent the url to the API path which offers the current state and type of an event emitter (source) (see Event & Tally REST API)
Example of IS-05 PATCH request
{
"sender_id": "9f463872-9621-4939-aa3a-dc3c82d8578b",
"master_enable": true,
"activation": {
"mode": "activate_immediate",
"requested_time": null
},
"transport_params": [
{
"broker_topic": "x-nmos/source/9f463872-9621-4939-aa3a-dc3c82d8578b",
"ext_is_07_rest_api_url": "http://hostname/x-nmos/events/v1.0/sources/9f463872-9621-4939-aa3a-dc3c82d8578b/"
}
]
}
Disconnecting/Parking
A disconnection IS-05 patch request should always trigger the receiver to unsubscribe from the associated broker_topic.
4. QOS Settings
MQTT publishers are recommended to use the exactly once QOS (2)
5. Late joiners
MQTT publishers are required to send the retained message flag with every message in order to solve the problem of late joiners.
Consumers (receivers) have a choice to either use the retained message or query the late joiners api using ext_is_07_rest_api_url to access the latest state of an emitter in order to get in sync.
6. MQTT WILL message
All event emitters (MQTT publishers) should send an MQTT WILL message upon first connection to the MQTT broker.
This should be the connection_lost message described in 1.4 The connection lost message under Message types.
7. Broker discovery
The MQTT broker will be advertised via the DNS-SD service type _nmos-mqtt._tcp.