MQTT Broker: HiveMQ

The Itron back office includes an MQTT broker that allows applications to publish messages on topics and other applications to subscribe to messages on particular topics. Of the various MQTT broker implementations available, Itron uses a Java based enterprise called HiveMQ. It supports standard client connection and message publication or subscription on topics, and can be configured to apply security rules for these actions. HiveMQ also provides a plugin model that allows writing custom Java code to receive and react to callbacks when various broker events occur.

Differences from JMS Message Queues

An MQTT publisher client sends a message to the broker for publication on a particular topic. The broker then examines the active subscriptions of connected clients and places a copy of the message into a queue for each client. This implies several differences from traditional message queue systems like JMS:

• Message topics are dynamic and are a mechanism for pattern match filtering. Topics do not need to be declared in advance.
• The broker does not internally maintain a queue per topic, it only maintains queues per client.
• A published message is delivered to and consumed by all clients with a matching subscription.
• If a client publishes to a topic with no subscribers, the broker will discard the message.

Client Message Queueing/Buffering

HiveMQ internally maintains a message queue per client that contains all messages that match the client's subscriptions. In normal operation, this queue should be offloaded very quickly. As publications come in and are matched to the client's topic subscriptions, a copy of the message is placed in the client's queue. HiveMQ then works to send these messages to that client as quickly as it can.

Higher subscription QoS levels require additional message roundtrips between the broker and the subscriber to acknowledge receipt of the message. In this case, the process of delivering the message might be slower than messages are received. The client message queue can be thought of as a buffer to decouple the publish rate from the client receive rate. The subscriber can "fall behind" the publisher for a short period of time and the broker will hold the other messages for the subscriber until it can "catch up". If the client buffer becomes full, then the broker will begin dropping messages for that client. The amount of time that a client can "fall behind" depends on the queue capacity and the rate of messages being placed into the queue.

The Itron configuration of the HiveMQ broker defaults to a queue depth of 50,000 offline messages per client. The queued message limit is the limit for all queued messages of an individual client, independent of the number of concrete topics the client subscribed to.

Disconnected Message Queueing/Persistence

When a client with a persistent session subscribes to a topic with QoS 1 or 2, HiveMQ will save missed messages for these topics if the client goes offline. The number of messages stored while the client is offline is also limited by configuration. When the client reconnects to the broker with the same client ID, then broker will begin delivering the queued messages received during the offline period.

HiveMQ only queues messages published to and subscribed to using QoS 1 or QoS 2. This means that the publisher also needs to be configured to use QoS 1+ when supporting queued messages is desired. With Gateway as the main MQTT publisher for milli-based traffic, this means changing a deployment configuration parameter:

# The MQTT QoS to use when sending messages to the broker.  Supported values include the following:

#   "AT_MOST_ONCE"  - QoS 0

#   "AT_LEAST_ONCE" - QoS 1

#   "EXACTLY_ONCE"  - QoS 2

gateway_coap_mqtt_bridge_default_message_qos: "AT_LEAST_ONCE"

Tenant Topic Restrictions

Device data published through MQTT is now segregated into topics based on the tenant that owns each device. Each device MAC address is associated with a tenant and this tenant ownership is specified at the time the device is provisioned for the network. This allows the MQTT broker to restrict access so that tenants can subscribe to data from their devices without being allowed to see data from other tenant's devices.

In the role privileges table described in the CONNECT Authorization section, the topic filters contain a "{tenantId}" token. At the time that the CONNECT message is processed by the broker, this token is replaced with the tenantId of the client. The tenantId is determined based on the authentication mechanism used in the CONNECT message:

• CAAS - All clients connecting to the broker using CAAS username/password credentials are considered "internal" clients and are assigned the tenantId "ssni"
• JWT - All clients connecting to the broker using JWT credentials are assigned the tenantId specified in the JWT "sub" claim.

For example, a CAAS client that has the BUBBLE_UP_READ_CONSUMER role will be granted subscribe privileges for the topic ssni/read/#. This means that the client can subscribe to any topic starting with that string. A JWT client with the tenantId "testTenant" and the mqttScope claim ["BUBBLE_UP_READ_CONSUMER”] would be granted subscribe privileges for the topic testTenant/read/#. The result is that the JWT client is allowed only to subscribe to topics starting with its own tenantId.

For the Itron Developer Program, the tenant and Oauth ClientID/secret key pair are associated with each other as part of user access control.

Itron Network MQTT Implementation 

The following is an overview of Itron's implementation of the Message Queuing Telemetry Transport (MQTT) and how Itron is using it to strengthen its presence in the Internet of Things (IoT) world. 

Itron strongly encourages integrators and developers to consume alerts/alarms and periodic measurements through MQTT instead of CoAP. Major advantages of adopting MQTT include the following:

• The asynchronous, event-driven interaction model
• Eliminate the difficulty of maintaining a client/server CoAP session across a self healing RF mesh due to changing IPV6 addresses when this occurs
• Familiar security and firewall demands
  • MQTT uses TCP/SSL similar to HTTPS, which is easier for Operations to administer than CoAP UDP

The back office applications should still implement CoAP for command and control of the sensor as well as on demand requests to the sensor.

The Itron back office includes an MQTT broker that allows applications to publish messages on topics and other applications to subscribe to messages on particular topics. Itron uses a Java based enterprise software called HiveMQ.

Itron’s platform supports sensor endpoint generated bubble up messages as MQTT at the back office application layer. The sensor is implemented as a CoAP server. The Milli is configured via onboard settings for the MQTT delivery of persistent observes rather than via CoAP.  In this case the Milli still behaves as a CoAP proxy for any CoAP messages initiated from a CoAP client.

However, the Milli also behaves as a CoAP client and manages the a CoAP Observe across the serial port to the sensor CoAP server. When new data is sent, the Milli sends it to Gateway with special identification for delivery as an MQTT message. Gateway delivers the data to the MQTT Broker. The MQTT Broker then delivers the data to any application clients that have subscribed to the sensor data topic.

More information can be found on how to use the MQTT programmatic interface on the MQTT API page. 

One use case has a NIC as the CoAP proxy for sensors that are attached to it. The NIC also acts as a CoAP server for data that it provides, such as date, time, battery level, signal strength, or any other sensor data built into it. The intelligent endpoints and sensors are implemented as CoAP servers.

Sensors

Sensor devices communicate using CoAP through the NIC based developer kits. The NIC can be configured to route persistent observe data to Gateway and the CoAP API or it can route them to the MQTT Broker and the MQTT API. These messages are routed through the mesh via an access point (AP) or IoT Router WAN mode. A sensor device acts as a CoAP server and the application that consumes the .

A CoAP Client can still reach the sensor by sending CoAP requests to the CoAP Gateway using CoAP Gateway APIs. The NIC contains a CoAP proxy that communicates to an attached sensor via a UART interface using CoAP over HDLC. Embedded in the HDLC are CoAP calls that are handled by the sensor attached to the NIC. When the NIC is configured for MQTT for persistent observe responses it also acts as a CoAP client to manage the Observe. 

Any application command and control or on demand retrieval of sensor data should still be implemented as a CoAP client application. A CoAP protocol command is sent by the client to the Gateway which acts as a CoAP proxy. This communication with end devices is facilitated through the CoAP Gateway API. The persistent observe data however is managed by the NIC and delivered to the back office application as MQTT topics. These topics are then retrieved in the application layer by subscribing to the appropriate MQTT topics with the MQTT API.