ModBee MQTT

MQTT 5.0 and 3.1.1 in C++14: a client, a broker and a bridge. It runs on a
microcontroller and on a Linux server, and nothing in it ever waits on the
network.

It was written for industrial control. There, a network call that blocks is a
scan cycle that overran, and a message that vanishes quietly is a pump that did
not start. Those two constraints shaped everything else in it.

 library:  esp32 · esp8266 · mbed (Portenta, Opta, Nano 33) · rp2040 · stm32 · Linux · macOS
 server:   Linux on x86-64 and ARM64, as a Docker image

What is in it

The library: for a board, or for your own program

src/, included with #include <ModBeeMqtt.h>. It has no dependencies, and is
the same source on every platform.

Nothing is behind a build flag. A part your program never uses is code nothing
references, and the linker drops it; footprint.md measures
that.

TLS uses whatever is there: wolfSSL or OpenSSL on a host; on an ESP32 the
core's own mbedTLS over any channel (MqttChannelTlsTransport - the same checks
on Wi-Fi, Ethernet and a modem, with key pinning); and WiFiClientSecure or
SSLClient on other boards.

The server: the broker at scale

server/, cli/ and docker/. Linux only, and not part of the Arduino
library.

Quick start

On a board

Put this repository in your Arduino libraries/ folder, or use Sketch →
Include Library → Add .ZIP Library. This is a complete device: it announces
itself, registers a Will so its absence is noticed, and reconnects by itself.
It publishes the level only when it changes, and holds what you send while
the link is down.

#include <Ethernet.h>            // or <WiFi.h>, or <TinyGsmClient.h>
#include <ModBeeMqtt.h>

byte MAC[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0x01 };
const uint8_t PUMP = 5;
float tankLevel = 0.0f;

EthernetClient net;
MqttDevice mqtt(net);

void onCommand(const char*, const MqttPayload& payload) {
    digitalWrite(PUMP, payload.toBool() ? HIGH : LOW);
}

void setup() {
    Ethernet.begin(MAC);

    mqtt.statusTopic("plant/tank-01/status");       // online / offline
    mqtt.onMessage("plant/tank-01/pump", &onCommand);

    // Publish the level when it moves 20 mm, and at least every 30 seconds.
    mqtt.report("plant/tank-01/level", &tankLevel, 0.02, 30000);

    mqtt.connect("192.168.1.10", "tank-01");        // returns immediately
}

void loop() {
    mqtt.poll();                                    // the whole contract
    tankLevel = analogRead(A0) * (10.0f / 1023.0f);
}

Only the network lines differ between links:

WiFiClient net;             MqttDevice mqtt(net);   // WiFi
EthernetClient net;         MqttDevice mqtt(net);   // wired
TinyGsmClient net(modem);   MqttDevice mqtt(net);   // cellular
MqttChannelTlsTransport<EthernetClient> tls(net, "broker", 8883);
                            MqttDevice mqtt(tls);   // TLS on any channel, ESP32
WiFiClientSecure net;       MqttDevice mqtt(net);   // TLS, ESP8266
SSLClient net(wired, TAs, TAs_NUM, A5);             // TLS where the chip has none

New to MQTT? Getting started explains brokers,
topics and QoS before any code.

In your own C++ program

add_subdirectory(modbee-mqtt)
target_link_libraries(my-app PRIVATE modbee-mqtt)

The same MqttDevice on a host needs no network object:

MqttDevice mqtt;
mqtt.secure("/etc/ssl/certs/ca-certificates.crt");
mqtt.connect("broker.example.com", "gateway-1");

A broker in your own program:

MqttBrokerConfig config;
config.maxConnections = 64;

MqttTcpListener plain;
plain.configure(nullptr, 1883, config.maxConnections);   // address, port, slots
if (!plain.begin()) { /* plain.lastError() says why */ }

MqttBroker broker;
broker.begin(config);                      // allocates everything, once
broker.addListener(plain);

while (running) broker.poll();             // never waits

As a server, in Docker

docker run -d --name modbee -p 1883:1883 --restart unless-stopped ghcr.io/mod-bee/modbee-mqtt

That is an MQTT broker on port 1883. For a server in production,
docker/examples/ has one ready-to-run folder per case,
each with a README:

Each needs, at most, a domain name, an email address and passwords, all in one
.env file. You never handle a certificate file. To try the Kafka pipe on
this computer first: docker/compose.yml.

From a terminal

The modbee command is in the Docker image:

docker run --rm ghcr.io/mod-bee/modbee-mqtt pub -h broker.example.com -t test/hello -m hi -q 1
#1 test/hello: delivered to the broker

It is also built with this repository on Linux and macOS. It is not part of
the Arduino library. cli.md covers both.

How it behaves

• Nothing blocks, including connect(). You call poll(), and outcomes
  arrive there. That is what lets it live inside a scan cycle or an Arduino
  loop(). The one call that can stall is the Arduino core's own
  Client::connect(), and transports.md says what to do
  about it.
• Nothing is silently dropped. Every operation ends in exactly one stated
  outcome: sent, refused, superseded or failed. A publish that will not fit is
  refused with a reason before it is accepted. A broker whose subscribers are
  backed up answers 0x97 Quota Exceeded, not a PUBACK that claims success.
• One core, every role. The client, the broker and the bridge share the
  same framing, codecs, sessions and flow control. A plant panel can run its
  own broker, keep working when the site link drops, and bridge the topics
  head office needs.
• One source, every platform. The same files build for an ESP32 and for a
  Linux container. Nothing above the transport layer knows which platform it
  is on.
• The source says why. Constants, lengths and reason codes cite the clause
  of the MQTT standard that requires them.

The codebase

The library has five layers, and dependencies point downward only:

 L4  ABOVE     MqttDevice, typed values, Sparkplug B    conveniences over the raw API
 L3  ROLE      MqttClient, MqttBroker, MqttBridge       the only layers that know which end they are
 L2  CORE      MqttLink, MqttOperations, MqttSession    framing, the operation queue, what survives a connection
 L1  PROTOCOL  MqttWire, the codecs, MqttProperties     functions over buffers: no I/O, no clock, no allocation
 L0  LINK      MqttTransport, MqttListener              one ordered, reliable byte stream

Two rules are checked in CI: no layer below L3 knows which role it is playing,
and no layer above the platform layer knows which platform it is on.
ARCHITECTURE.md explains why each boundary is where it
is.

Building

cmake -S . -B build
cmake --build build -j
ctest --test-dir build

That builds the library, the examples and the tests, and, on a host, the
modbee command (build/cli/modbee) and the server. TLS is used if wolfSSL or
OpenSSL is installed. The Kafka pipe is built if the librdkafka development
package (librdkafka-dev) is installed. Neither is required.

When another CMake project adds this one with add_subdirectory(), it gets the
library alone.

C++14 is all the library needs, because the mbed-based Arduino cores and
OpenPLC's STruC++ compile at C++14. It builds clean with
-fno-exceptions -fno-rtti -Werror.

Examples

examples/arduino/:

examples/cpp/: publish, subscribe, gateway, broker, bridge,
secure_broker, and sparkplug_node with sparkplug_host, which talk to each
other.

examples/kafka/nodejs/: a Node.js app on the Kafka pipe - it reads every MQTT
message from Kafka and sends a pump command back
(kafka-apps.md).

What it is not

• Not MQTT-SN. That is a separate protocol for links without TCP; run an
  MQTT-SN gateway in front of a broker (versions.md).
• Not a WiFi manager or an OTA updater. It does MQTT over the network
  connection you already have.
• Not a multi-machine cluster. modbee serve uses every core of one
  machine. Kafka is how several servers share data.
• No streaming publish. A payload is a buffer. A streamed write could block,
  and a QoS 1 message could not be resent after a reconnect
  (api.md).

Documentation

Licence

GNU Affero General Public License, Version 3, with additional ModBee terms
(see LICENSE). Use is non-commercial; commercial use requires a
separate licence, and the LICENSE says how to ask for one.

To report a security defect, see SECURITY.md.