u-blox MQTT User Manual
describes how to connect and configure Message Queuing Telemetry
u-connectXpress
MQTT
Application note
Abstract
This application note
Transport (MQTT) using u-connectXpress software.
UBX-19005066 - R03
C1-Public www.u-blox.com
u-connectXpress MQTT - Application note
u-blox or third parties may hold intellectual property rights in the products, names, logos and designs included in this
document. Copying, reproduction, modification or disclosure to third parties of this document or any part thereof is only
permitted with the
The information contained herein is provided “as is” and u
implied, is given, including but not limited
purpose of the information. This document may be revised by u
documents, visit www.u
Copyright © u
Document information
Title u-connectXpress
Subtitle MQTT
Document type Application note
Document number UBX-19005066
Revision and date R03 22-Feb-2021
Disclosure restriction C1-Public
This document applies to the following products:
Product name Software version
NINA-W131 2.1.x onwards
NINA-W132 2.1.x onwards
NINA-W151 1.0.x onwards
NINA-W152 1.0.x onwards
NINA-W156 3.1.x onwards
ODIN-W260 7.0.x onwards
ODIN-W262 7.0.x onwards
ODIN-W263 7.0.x onwards
express written permission of u-blox.
-blox assumes no liability for its use. No warranty, either express or
to, with respect to the accuracy, correctness, reliability and fitness for a particular
-blox at any time without notice. For the most recent
-blox.com.
-blox AG.
UBX-19005066 - R03 Document information Page 2 of 18
C1-Public
u-connectXpress MQTT - Application note
Contents
1 Overview ................................................................................................................................................ 4
2 MQTT-SN gateway ............................................................................................................................. 5
2.1 Connect MQTT-SN gateway to broker ................................................................................................... 6
2.1.1 URL format (for AT+UDCP and AT+UDDRP) ................................................................................ 6
2.1.2 Example Mosquitto test broker ....................................................................................................... 7
2.2 MQTT-SN client connect/disconnect ..................................................................................................... 8
2.3 MQTT-SN client publish ............................................................................................................................ 9
2.4 MQTT-SN client subscribe ...................................................................................................................... 10
2.5 MQTT-SN client PING ............................................................................................................................... 11
2.6 MQTT-SN sleeping clients ...................................................................................................................... 12
3 MQTT client gateway ...................................................................................................................... 14
3.1 Connect MQTT client gateway to broker ............................................................................................. 14
A Publish packet size limitations .................................................................................................... 15
B Glossary .............................................................................................................................................. 16
UBX-19005066 - R03 Contents Page 3 of 18
C1-Public
u-connectXpress MQTT - Application note
broker
MQTT-SN
1 Overview
Message Queuing Telemetry Transport (MQTT) is a publish/subscribe, simple messaging protocol,
designed for communication between multiple devices. This application note describes how to
connect and configure MQTT using u-connectXpress software.
It is possible to configure the gateway as an MQTT-SN gateway. This is intended for end devices that
do not support TCP/TLS directly; instead, an end device connects to the gateway using a serial
connection such as Bluetooth SPS or SPP and communicates with the gateway using the MQTT-SN
protocol, as described in Figure 1.
It is also possible to configure the gateway as an MQTT client gateway. The host of the gateway can
then transmit or receive transparent MQTT data directly over the UART.
Figure 1: Gateway using a serial connection such as Bluetooth SPS or SPP with gateway communication using MQTT-SN
MQTT-SN gateway
SPP or SPS
End device
End device
MQTT
TCP / TLS
MQTT client gateway
UART
Host
End device
Different combinations of the configurations described in Figure 1 can also be achieved. Hence, it is
possible for the host, and the end devices to communicate with the MQTT broker via the same
gateway simultaneously.
For information about how to get started with a module, see the corresponding EVK user guides (EVKODIN-W2 user guide [1] and EVK-NINA-W1 and EVK-NINA-B2 user guide [4].
See the u-connect AT commands manual [3] for details of the AT commands that can be used with ublox short range stand-alone modules and the u-connectXpress user guide [2] for more information
on the u-connectXpress software.
Refer to the MQTT-SN v1.2 protocol specification available at http://mqtt.org/documentation for
information about the MQTT-SN protocol.
UBX-19005066 - R03 Overview Page 4 of 18
C1-Public
u-connectXpress MQTT - Application note
MQTT-SN
MQTT
SPP or SPS
TCP/TLS
Streams bound
2 MQTT-SN gateway
An MQTT-SN (SN=Sensor Network) gateway enables end devices with no TCP/TLS support to
communicate with an MQTT broker (which requires TCP/TLS). The end device connects to the
gateway using a serial connection, such as Bluetooth SPS or SPP, and communicates using the
MQTT-SN protocol. The gateway then converts the MQTT-SN packets, from the end device, to MQTT
packets and sends to the broker and vice versa.
End Device
ANNA-B112 or
NINA-B1/B2/B3
Figure 2: End device connects to the gateway using serial connection
MQTT-SN
gateway
ODIN-W2 or
NINA-W15
MQTT
broker
The MQTT-SN gateway is an aggregating gateway, which means that there is only one TCP or TLS
connection to the MQTT broker. Hence, multiple end devices do not require one connection each as in
the case of a transparent gateway. This is good since many brokers limit the number of connections
and it is then better for many end nodes to share one TCP/TLS connection.
The end device will act as an MQTT-SN client (or client from here on) and it can publish or subscribe
to data identified by a unique topic string. The MQTT broker is data agnostic meaning it considers all
data to be a byte array. Hence, a publish data packet consists of:
• A topic string that uniquely identifies the data
• Data as a byte array.
The steps to get the MQTT-SN gateway configured and running typically are:
1. Create one or more MQTT streams by using the AT commands,
AT+UDCP or AT+UDDRP. The first
created stream will setup the actual TCP/TLS connection to the MQTT broker.
2. Create one or more end device streams, Bluetooth SPS or SPP, by using the AT commands,
AT+UDCP, AT+UDDRP or by enabling one of the associated services, AT+UDSC, for the end device to
connect to the gateway.
3. Bind the MQTT stream with the end device stream using one of the following:
o Dynamic bind, AT command
o Static bind configured using “
AT+UDBIND (requires host to execute the command)
sys.sid” key in stream URL (automatic bind once both the
connections are active)
End device
MQTT-SN
SPS
SPS
MQTT
MQTT on
TCP/TLS
MQTT
broker
Figure 3: End device acts as MQTT-SN client with agnostic MQTT broker
Gateway
☞ The end device must transmit and receive MQTT-SN packets on the Bluetooth SPS or SPP link.
Hence, some basic MQTT-SN packet parsing is required by the end device.
UBX-19005066 - R03 MQTT-SN gateway Page 5 of 18
C1-Public
u-connectXpress MQTT - Application note
MQTT on
TCP/TLS
The gateway does not support the full MQTT-SN specification. Only the following packet types are
supported:
• CONNECT / CONNACK (client connects to the gateway)
• DISCONNECT (client disconnects from the gateway or enter sleep mode)
• REGISTER / REGACK (client register topic to the gateway)
• PUBLISH / PUBACK (client or gateway forwards data)
• SUBSCRIBE / SUBACK (client subscribes to data identified with topic)
• PINGREQ / PINGRESP (client checks connection to the gateway or polls for data when in sleep
mode)
☞ To ease implementation of a propriety MQTT-SN end device, it is recommended to use the MQTT-
SN packet parser code available at https://github.com/eclipse/paho.mqtt-sn.embedded-c.
2.1 Connect MQTT-SN gateway to broker
The MQTT-SN gateway is configured using either the connect peer AT command, AT+UDCP, or the
default remote peer AT command,
AT+UDDRP.
Figure 4: MQTT-SN gateway connect to broker
Gateway
MQTT
broker
☞ One MQTT stream must be setup for every connected MQTT-SN end device. For example, if the
gateway must handle 5 parallel Bluetooth LE connected end devices, then five MQTT streams
must be activated. However, for sleeping clients, it is possible to have more clients than the MQTT
streams if they do not need to be connected simultaneously.
2.1.1 URL format (for AT+UDCP and AT+UDDRP)
mqtt://<host address>:<port>/?<keys>
• <host address>: Host name or IP address, e.g., test.mosquitto.org or 37.187.106.16
•
<port>: IP address port number, e.g., 1883
•
<keys>: key=value (with separating and character) for gateway to broker connection
MQTT related keys:
o client: Client name, e.g.,
o user: User name, e.g.,
client=my_client
user=my_user
☞ The end devices must ensure that data is transmitted to the broker within the keep-alive timeout.
o passwd: User password, e.g.,
o keepAlive: Keep alive timeout in seconds, e.g., keepAlive=60
o qos: Quality of Service level (0,1,2). Refer to the MQTT specification [5] for details.
If not, the broker may disconnect.
o
maxSnClients: Number of MQTT-SN clients supported, e.g., maxSnClients=24
Default is 16.
UBX-19005066 - R03 MQTT-SN gateway Page 6 of 18
C1-Public
passwd=my_passwd
Loading...