emMQTT
Message Queuing Telemetry Transport Protocol

emMQTT provides the client functionality of the Message Queue Telemetry Transport protocol to a stack. emMQTT uses sockets and can be used with any IP stack such as emNet using the socket interface.

Downloads

Documentation

Overview

Message Queuing Telemetry Transport (MQTT) is a publish/subscribe messaging transport protocol for use on top of the TCP/IP protocol. It is simple, lightweight, and open. These characteristics make it ideal for use in many situations, including constrained environments such as for communication in Machine to Machine (M2M) and Internet of Things (IoT) contexts.

MQTT infrastructure is easily scalable and therefore used for communication of thousands of devices. It can be used to transmit sensor data, device states, tracking information, events, configuration data and much more.

Why SEGGER's MQTT Client emMQTT?

SEGGER’s MQTT Client works with any MQTT Broker which adheres to the v3.1.1 standard. This makes it possible to add it to an end application with full confidence that everything will simply work.

Sample applications and demos are available for all popular brokers. A Microsoft Windows sample can be used to see just how easy it is to work with SEGGER’s MQTT Client.

SEGGER has developed the MQTT Client emMQTT from scratch to keep stack usage as small as possible and memory requirements to a minimum.

Key features

Full MQTT version 3.1.1 support
Publish/subscribe client included
Support for Quality of Service data delivery
Low memory footprint
Independent of the TCP/IP stack: any stack with sockets can be used
Publisher and subscriber demo included
Project for executable on PC for Microsoft Visual Studio included

MQTT Background

MQTT is a very lightweight communication protocol originally designed for communication in M2M contexts. It is easy to implement on client side and has only a minimal packet overhead. This makes it ideal for the use with devices with limited resources.

It uses the publish/subscribe pattern, which is an alternative to the well-known client/server model. In opposite to the client/server model, where a client directly communicates with an endpoint, the publish/subscribe pattern decouples the sender and receiver of a particular message. In the MQTT context the sending client is called publisher, the receiving client subscriber.

Publisher and subscriber do not know about the existence of one another. To enable the transport of a message a third party is required. The service provided by the third party is called broker in the MQTT context. The broker filters all incoming messages from the publishers and distributes them to the subscribers.

MQTT uses subject-based filtering of messages. Publishers sends topic related messages, subscribers receive messages if they have subscribed the topic.

To get messages a from an MQTT broker a subscriber establishes a connection to the broker. The broker checks if a publisher has sent a message for the subscribed topic and if so, sends it to the subscriber. The advantage of this approach is that publisher and subscriber do not need to know each other and that they do not need to run at the same time. All they need to know is the IP address of the broker.

Download the MQTT specification from oasis-open.org

Download the MQTT specification Version 3.1.1

Getting Started with emMQTT

To easily get started with emMQTT and to evaluate the use of it, an MQTT Client Application using emMQTT is available for download.

The MQTT Client Application is a simple commandline-based MQTT client to connect to any MQTT broker.
It uses emMQTT and the emSSL SSL/TLS library on top of the host’s (i.e. Windows) native TCP/IP stack.

All features available in the MQTT Client Application can be used the same way on any embedded target system.

Download SEGGER MQTT Client Application for Windows

emMQTT Application Usage

emMQTT Application Usage
MQTTClient --pub|--sub [Options]
  --pub              Start the publisher.
  --sub              Start the subscriber.

Options:
  [-h <Hostname>]     Broker to connect to. Host or IP address.
  [-p <Port>]         Port of the broker to connect to.
  [-i <ClientName>]   Name of the client.
  [-t <TopicFilter>]  Topic(s) to subscribe/publish to.
  [-c <Count>]        Message count to receive/publish.
Will Options:
  [-w]                Register will to be sent on disconnect.
  [--will-topic]      Topic to publish will to.
  [--will-payload]    Payload of will to publish.
  [--will-qos <Level>]QoS level of will.
  [--will-retain]     Set retain flag on will.
Security Options:
  [--tls]             Enable use of SSL/TLS.
  [--cert]            Client certificate file.
  [--key]             Private key file.
Publisher only:
  [-m <Message>]      Message to publish.
  [-q <QoSLevel>]     Quality of Service level.
  [-r]                Set retain flag.
  [-d <Seconds>]      Delay after publish.
Subscriber only:
Logging:
  [-v <Level>]        Verbosity level.
  [--debug]           Debug output.
Options
-c Count
Number of messages to receive or publish before client exits automatically.
Default: off, unlimited

--cert Filename
Set certificate file for client authentication with secured connection.
The certificate file needs to be a DER encoded RSA certificate.
Default: none

-d Seconds
Seconds to delay between publish of messages.
Default: 1

--debug
Enable diagnostic debug output.
Default: off

-h Hostname
Hostname or IP address of the MQTT broker to connect to.
Default: mqtt.eclipse.org

-i ClientName
Name of the client that will be passed to the broker.
The client name has to be unique with most brokers.
Default: SEGGER-MQTT-<Random>

--key Filename
Set the private key file for the client certificate.
The private key file needs to be a DER encoded RSA key.
Default: none

-m Message
The message payload to publish.
Default: www.SEGGER.com embOS/IP MQTT Demo running.

-p Port
Port of the broker to connect to.
Default: 1883

--pub
Start the MQTT Client as publisher.

-q QoSLevel
Set the Quality of Service for published messages to 0, 1, or 2.
Default: 0

-r
Set the retain flag for published messages.
Default: off, no retain

--sub
Start the MQTT Client as subscriber.

-t TopicFilter
Topic filter to subscribe to or topic to publish to.
Default: SEGGER/Demo

--tls
Enable secured connection using SSL/TLS.
Default: off, unsecured

-v Level
Set the verbosity level for output between 0 and 3.
Default: 1

-w
Register a will to be published by the broker when the client unexpectedly disconnects.
Default: off, no will

--will-payload Payload
Payload of will message.
Default: MQTT Demo disconnected.

--will-qos QoSLevel
Set the Quality of Service for will message to 0, 1, or 2.
Default: 0

--will-retain
Set the retain flag for will message.
Default: off, no retain

--will-topic Topic
Topic to publish will message to.
Default: SEGGER/disconnect

Examples

MQTTClient --pub -h mqtt.eclipse.org -p 1883 -t SEGGER/Demo -m "Hello World from SEGGER MQTT."
Connect to broker at mqtt.eclipse.org:1883 and publish “Hello World from SEGGER emMQTT.” to “SEGGER/Demo” every second.

MQTTClient --sub -h mqtt.eclipse.org -p 1883 -t SEGGER/Demo
Connect to broker mqtt.eclipse.org:1883 and subscribe to “SEGGER/Demo” to receive all published messages from that topic.

MQTTClient --pub -h 1a2b3c4d5e6f7g.iot.eu-central-1.amazonaws.com -p 8883 -t SEGGER/Demo -m "Hello World from SEGGER MQTT." --tls --cert C:\Temp\aws_cert.der --key C:\Temp\aws_private.der -d 5
Securely connect to broker at 1a2b3c4d5e6f7g.iot.eu-central-1.amazonaws.com:8883 using TLS with certificate file aws_cert and private key file aws_private to publish “Hello World from SEGGER MQTT.” to “SEGGER/Demo” with 5 second delay.

MQTT Broker

The counterpart to an MQTT Client is the MQTT Broker. All MQTT Clients connect to one MQTT Broker to subscribe or publish to topics. The MQTT broker manages all client connections and sends published messages to subscribers. An MQTT broker is usually a server, running locally or in a cloud infrastructure. It can be connected to other software, such as a database to further process messages or a job scheduler to send messages on certain events. There are various MQTT brokers available, for commercial or non-commercial use, for local or server installation or as a hosted service, with and without further backend software.

emMQTT can connect to any MQTT broker that supports MQTT Version 3.1.1.

Broker Overview

emMQTT can be used with any MQTT broker. The following table provides an overview of some brokers the add-on has been tested with.
Do you miss your broker or cloud provider in this list? emMQTT will still be an option for you. Simply test connecting to your broker using the MQTT Client Application. For any issues, feel free to contact us.

Broker / Service	MQTT over TLS	MQTT over TLS with Client Certificate	Notes
mosquitto			Open-source MQTT broker for Linux, Windows, macOS. Tested with public broker at mqtt.eclipse.org
HiveMQ	¹	¹	Enterprise MQTT broker for Linux servers. Tested with public broker at hivemq.com
AWS			AWS supports MQTT to connect to the AWS IoT Message Broker.

¹: Not available on public broker.

Requirements

TCP/IP Stack

emMQTT Client is a software component that works on top of TCP and requires a TCP/IP stack. It is optimized for emNet, but any RFC-compliant TCP/IP stack can be used. The integration of a TCP/IP stack is easily done with a simple API callback structure. A demo application for Windows which uses the standard Windsock API is available for download.
emMQTT can also be used with other protocols that work on top of TCP, such as SSL/TLS for secure communication or WebSockets for bowser-based applications.

Resource Usage

The ROM usage depends on the compiler options, the compiler version and the used CPU. The memory requirements of emMQTT presented in the tables below have been measured on a Cortex-M4 system.

The following resource usage has been measured on a Cortex-M4 system using SEGGER Embedded Studio V3.34, size optimization.

Resource Usage	Value
emMQTT Client Size (ROM)	Approx. 2.4 kByte
emMQTT Client Size (RAM)	8 Byte
emMQTT Client Context (RAM)	76 Byte

Licensing

emMQTT is available under various Embedded Software License models and delivered in source code packages. With a wide range of licensing options, emMQTT can fulfill commercial requirements as well as technical requirements. All licenses are one-time payments. emMQTT is royalty-free and not subscription-based. This makes the software a part of the equipment expenses, keeping the costs static.

* Applies to second seat/product and all additional seats/products of the Single Product License and Single Developer License.