The oneM2M MQTT Client

In addition to the oneM2M HTTP Client, the OpenMTC application framework features an MQTT client.

About MQTT

MQTT is short for “Message Queue Telemetry Transport,” a protocol that has originally been developed by IBM as a means of transportation for data in sensor networks. In contrast to HTTP, MQTT does not work in a request-response-manor; a publish-subscribe-approach is being embraced instead.

For the protocol to work, an intermediary called “Broker” is required: Its role is to accept messages from connected clients and relay them among existing subscriptions. Through this centralised structure, communication through MQTT will always require at least one additional peer in comparison to other protocols supported by the framework.

Setting up a broker is imperative, but due to the wealth of available solutions well outside the scope of this document. Exhaustive testing has been conducted against Moquette, which allows interoperability to be pretty much guaranteed for version 0.8+. For a quick start (or testing), you may use an openly available public broker such as iot.eclipse.org. It goes without saying that message confidentiality on public infrastructure is nil. Hence, those brokers do not present an option in production environments. Doing so is hereby strongly discouraged.

In the event of a reduced-complexity, low-maintenance set-up being desired, using a docker image were recommended over a public broker. There is no absolute requirement on docker, though.

Working With The MQTT Client

The OneM2MMQTTClient class implements protocol binding in accordance to TS-0010 akin to OneM2MHTTPClient. The two classes have been designed to work interchangeably from an application standpoint; differences in behaviours should be strictly related to the respective underlying transport protocols.

Actual low-level MQTT handling is performed by the paho mqtt library. Users are encouraged to open issues with that project in case of pure MQTT havoc.

Establishing Connectivity

Although the interfaces of both, OneM2MHTTPClient and OneM2MMQTTClient are identical, addressing endpoints varies drastically. Through the necessity of a broker commonly reachable by two peers, said broker has to be the endpoint instead of the peer's machines. Subsequently, an address suitable for OneM2MMQTTClient can in general not be crafted by merely substituting http:// with mqtt://. (A notable exception is a set-up in which all peers - including the broker - are located on one and the same machine.)

For a simple set-up of one AE and one CSE, proceed as follows:

Gateway (CSE)

Locate the config-gateway.json configuration file
Find the plugins.openmtc_cse key
Add the following stanza to the list:

{
  "name": "MQTTTransportPlugin",
  "package": "openmtc_cse.plugins.transport_gevent_mqtt",
  "disabled": false,
  "config": {
    "interface": "iot.eclipse.org",
    "port": 1883
  }
},

ℹ️ Hint: A gateway is not locked in a single protocol. Multiple transport plugins can be active at the same time, allowing for a CSE to be reachable through a set of protocols.

⚠️ Warning: For the sake of brevity, iot.eclipse.org is set as broker. Please consider the introduction on MQTT regarding the ramifications.

Start the gateway through the openmtc-gateway-gevent script

On a related note, enabling the plugin in the backend (NSE) is done in an almost identical way: Just read config-backend.json in step 1 and openmtc-backend-gevent in step 4.

Application Entity

Programmatically, it is sufficient to create an instance of OneM2MMQTTClient with a given endpoint. In adoption of example 8a:

from openmtc_onem2m.client.mqtt import OneM2MMQTTClient

client = OneM2MMQTTClient("mqtt://iot.eclipse.org#mn-cse-1")

All subsequent examples should be modifiable in the same fashion in order to enable MQTT support. In general, adjusting endpoints and providing the proper client is concluding the required steps.

Please note the particle of the endpoint's URL being the name of a CSE. Due to the addressing scheme in oneM2M/MQTT, a requesting entity has to know the responding entities name in advance. It should be duly noted that this is a workaround neither mandated nor sanctioned by TS-0010. In fact, the semantics of particles in MQTT-URLs are entirely undefined. This inconvenience may or may not vanish in future releases.

5.1 KiB Raw Blame History Unescape Escape