Moonlight MQTT

A small, simple, and secure MQTT 5.0 client for microcontrollers.

Moonlight MQTT runs on ESP32, ESP8266, Arduino, Raspberry Pi, and other common
boards. You get full MQTT 5.0 with all three QoS levels, retained messages, last
will, auto reconnect, and TLS, over WiFi, Ethernet, or GSM. You choose the
buffer size yourself and every call returns a clear result, so messages never
vanish without a reason.

Contents

• Why Moonlight MQTT
• Features
• Install
• Dependencies
• Quick start
• API reference
• Transports
• Buffer sizes
• Security
• Result codes
• Examples
• Broker compatibility
• License

Why Moonlight MQTT

Moonlight MQTT gives you full MQTT 5.0 with a simple API that runs the same way
on many boards. It is built around a few clear ideas:

• You own the buffer. You set the size once in the constructor, so you
  always know how much memory the client uses, and large messages are never
  dropped by surprise.
• No silent failures. Every call returns a clear result code, so you always
  know what happened.
• Honest state. A keep alive and a liveness check mean connected() tells
  the truth.
• It never freezes. loop() is non blocking, so your program keeps running
  while messages flow.

Features

• MQTT 5.0 protocol
• QoS 0 (at most once), QoS 1 (at least once), QoS 2 (exactly once, full handshake)
• Retained messages
• Last will and testament
• Keep alive with a true liveness check
• Auto reconnect with backoff
• TLS using the stack already on your board (mbedTLS, BearSSL, OpenSSL)
• Works over WiFi, Ethernet, and GSM
• Fixed buffers, no hidden memory use, no exceptions
• One header to include

Install

Arduino IDE

Open Tools > Manage Libraries, search for Moonlight MQTT, and click
Install. You can also download this repository as a ZIP and use
Sketch > Include Library > Add .ZIP Library.

PlatformIO

Add this repository to your lib_deps, or clone it into your project lib
folder. The library ships a library.json.

Linux and Raspberry Pi (CMake)

cmake -S . -B build
cmake --build build

Dependencies

• None for the core on ESP32, ESP8266, and Arduino. It uses only the board's own
  network client (WiFiClient, WiFiClientSecure, EthernetClient).
• The GSM example uses the TinyGSM library.
• The Linux and Raspberry Pi TLS transport uses OpenSSL.

Quick start

#include <MoonlightMQTT.h>
using namespace moonlight;

WiFiClient net;                                // use WiFiClientSecure for TLS
ArduinoTransport<WiFiClient> transport(net);
StaticClient<1024, 512> mqtt(transport);       // 1 KB receive, 512 B send

void onMessage(const Message& m, void*) {
  // m.topic / m.topicLen and m.payload / m.payloadLen are valid only here
}

void setup() {
  net.connect("broker.example.com", 1883);     // open the socket first
  mqtt.onMessage(onMessage);

  ConnectOptions opts;
  opts.clientId = "my-device";
  opts.keepAlive = 30;

  if (mqtt.connect(opts) == OK) {
    mqtt.subscribe("devices/my-device/cmd", QOS1);
  }
}

void loop() {
  mqtt.loop();                                  // call this often
  mqtt.publish("devices/my-device/data", "42", QOS1);
}

API reference

Client

ConnectOptions

Message

Transports

Moonlight talks to the network through a small Transport interface, so it does
not care how the bytes travel.

Buffer sizes

You own the two buffers. StaticClient<RxCap, TxCap> holds them for you.

• RxCap must fit the largest message you receive (topic plus payload plus a
  little header).
• TxCap must fit the largest message you send.

If a message does not fit, the call returns ERR_BUFFER_FULL. It is never
dropped in silence.

Security

TLS is the recommended way to connect. Moonlight does not ship its own crypto.
It uses the TLS stack already on your board, which gets security updates from the
platform.

Certificate checking is on by default on the Linux transport, and you should set
a CA certificate on ESP boards. See examples/Esp32_WiFi_Secure.

Very small boards like the Arduino Uno do not have the memory for TLS. That is a
hardware limit. Plain MQTT still works on them.

Result codes

Every call returns one of these. Values at or above zero mean success.

Examples

• examples/Esp32_WiFi_Secure secure MQTT over TLS on ESP32
• examples/Esp8266_WiFi plain MQTT on ESP8266
• examples/Arduino_SIM900A plain MQTT on an Arduino with a SIM900A GSM module

Broker compatibility

Moonlight MQTT works with standard MQTT 5.0 brokers, such as Mosquitto, EMQX,
and HiveMQ.

License

MIT. See LICENSE.