How liambindle/mqtt-c works
Purpose and Public Entry Points
MQTT-C is a portable ANSI C (C89-compatible) MQTT v3.1.1 client library for embedded and desktop systems. Consumers include include/mqtt.h, instantiate struct mqtt_client, then drive it through mqtt_init, mqtt_connect, publish/subscribe calls, and broker I/O processing. The public portability contract is include/mqtt_pal.h.
Paths: include/mqtt.h, include/mqtt_pal.h
Core Client Engine
The library’s primary state machine, MQTT packet construction/parsing, response handling, QoS flows, and outbound message queue management are centralized in the client implementation. A client translates API operations into MQTT wire packets and consumes incoming broker packets into response/callback state.
Paths: src/mqtt.c, include/mqtt.h
Platform Abstraction Boundary
The protocol engine is separated from host-specific facilities through the PAL. This boundary supplies required types and operations such as synchronization, time, and I/O-facing portability mechanisms, allowing the same MQTT engine to target single-threaded embedded platforms or threaded PC environments.
Paths: src/mqtt_pal.c, include/mqtt_pal.h, src/mqtt.c
Primary Runtime Flow
Application-owned transport setup precedes client initialization. The application initializes a mqtt_client with buffers and PAL/transport integration, sends CONNECT, then repeatedly services network input/output through the library while issuing publish, subscribe, unsubscribe, ping, and disconnect operations. Broker responses—CONNACK, PUBLISH, acknowledgements, and keepalive responses—are parsed by the engine and update queued-message/QoS state.
Paths: include/mqtt.h, src/mqtt.c, include/mqtt_pal.h
Transport and TLS Integration
MQTT-C does not impose a single socket or TLS runtime; examples provide integration templates for POSIX sockets and TLS stacks. This keeps TCP/TLS ownership at the application boundary while supporting OpenSSL, Mbed TLS, and BearSSL-backed clients. Example executables connect to external MQTT brokers, including Mosquitto’s public test service.
Paths: examples/templates/posix_sockets.h, examples/templates/openssl_sockets.h, examples/templates/mbedtls_sockets.h
Executable Usage Patterns
Examples are the practical entry points for basic publishing/subscribing, reconnect behavior, and secure transports. They demonstrate how application code binds a socket implementation to the library rather than introducing a separate server or web runtime.
Paths: examples/simple_publisher.c, examples/simple_subscriber.c, examples/reconnect_subscriber.c
Build and Verification
The library can be consumed directly by compiling its two implementation files, or built through CMake, Make, or Zig build definitions. Tests use cmocka and can contact a configurable MQTT broker; CI runs repository validation.
Paths: CMakeLists.txt, makefile, build.zig
Main entry points: mqtt.c Client engine · mqtt.h MQTT client API · simple_publisher.c Publisher and subscriber · CMakeLists.txt Build definitions
Components 12
Public API
- MQTT client API · Client lifecycle, publish, subscribe, and broker I/O API.
include/mqtt.h - Portability API · Host abstraction contract for the protocol engine.
include/mqtt_pal.h
MQTT-C Library
- Client engine · Drives MQTT state, packet encoding/parsing, and broker responses.
src/mqtt.c - QoS and outbound queue · Tracks outbound messages and acknowledgement-driven QoS state.
src/mqtt.c - PAL implementation · Supplies portable synchronization, time, and platform facilities.
src/mqtt_pal.c
Application Integration
- Consumer application · Owns transport setup, buffers, and the mqtt_client instance.
- POSIX socket template
examples/templates/posix_sockets.h - TLS socket templates · OpenSSL and Mbed TLS integration patterns.
examples/templates/openssl_sockets.h - Publisher and subscriber · Basic application usage patterns.
examples/simple_publisher.c - Reconnect subscriber · Reconnect-oriented client usage.
examples/reconnect_subscriber.c
Build & Verification
- Build definitions · Supports CMake, Make, and Zig builds.
CMakeLists.txt
Other components
- External MQTT broker · Receives MQTT traffic and returns protocol responses.
Connections 15
- Consumer application → MQTT client API: uses
- MQTT client API → Client engine: declares
- Client engine → QoS and outbound queue: manages
- Client engine → Portability API: depends on
- Portability API → PAL implementation: implemented by
- Consumer application → POSIX socket template: binds transport
- Consumer application → TLS socket templates: may bind TLS
- Consumer application → Client engine: services I/O
- Client engine → External MQTT broker: MQTT packets
- External MQTT broker → Client engine: responses and publishes
- Publisher and subscriber → MQTT client API: demonstrate
- Publisher and subscriber → POSIX socket template: use
- Reconnect subscriber → MQTT client API: demonstrates
- Build definitions → Client engine: builds
- Build definitions → PAL implementation: builds