wolfMQTT is an MQTT client that fits beside wolfSSL on a device

Built for embedded targets rather than for servers

wolfMQTT is an implementation of the MQTT client written in C for embedded use, and the README states plainly that it was built from the ground up to be multi-platform, space conscious and extensible. Those three words set the agenda. Space conscious is why it is a client rather than a broker, and why it works alongside wolfSSL rather than replacing the TLS stack. The relationship is explicit: SSL/TLS support comes via the wolfSSL library, and the client integrates with it to provide TLS, including TLS 1.3, which the repository topics list alongside mqtt, qos-0-2, quality-of-service, iot and embedded. The intended user is an engineer with a microcontroller or embedded Linux target who needs to publish telemetry or subscribe to commands over MQTT, and who would rather link a few thousand lines of C than pull in a full broker stack. The licence is GPL-3.0, which is the one decision that constrains who can ship it, and it is worth reading before you start.

Three layers: packets, client, network

The architecture section splits the library into three components, and the split is what makes it extensible. The first is `mqtt_packet`, where all the packet encoding and decoding happens, with the header holding the MQTT packet structures for Connect, Publish and Message among others. The second is `mqtt_client`, which is where the top level application interfaces reside, and it holds the `MqttClient` struct, the `MqttNet` struct, the `MqttMsgCb` callback and the two buffers with their lengths. The third layer is the network interface itself, the `MqttNet` callbacks that the client calls, which your application implements for whatever transport you have. The client layer wraps those callbacks and handles the wolfSSL TLS work on top. The consequence for a user is that the transport is yours to write, and the README's own example directory shows the shape of that work with `mqttnet.c`, `mqttport.c` and `mqttuart.c` files for a serial port transport, so there is a template to start from rather than a blank page.

The client API blocks on the network read

The API surface is small and, more importantly, synchronous. `MqttClient_Init` takes the client, the net struct, the message callback, a transmit buffer with its length, a receive buffer with its length, and a command timeout in milliseconds. The README is explicit that the APIs are blocking on `MqttNet.read` until an error or timeout, and that timeout is the `cmd_timeout_ms` you passed at init. That covers `MqttClient_Connect`, `MqttClient_Publish`, `MqttClient_Subscribe`, `MqttClient_Unsubscribe`, `MqttClient_Ping` and `MqttClient_Disconnect`. For receiving, `MqttClient_WaitMessage` blocks waiting for a new publish message for up to `timeout_ms`. The network layer has its own pair, `MqttClient_NetConnect` and `MqttClient_NetDisconnect`, which wrap the `MqttNet` callbacks and handle wolfSSL TLS, and there is a helper `MqttClient_ReturnCodeToString` for turning a return code into a message. On a single-task embedded system with a cooperative network callback, blocking is a reasonable design. In a system with an event loop or several threads, it is a constraint you have to design around.

Host identity is where the deployment fails

The longest and most useful part of the README is about TLS identity checking, and it is a series of hard requirements. Verified TLS connections to IP addresses require wolfSSL 5.9.1 or newer built with `WOLFSSL_IP_ALT_NAME`, so that the certificate's IP address subject alternative name can be verified; without it those connections fail before the handshake. DNS name verification works with older wolfSSL releases. Legacy numeric IP spellings, bracketed IPv6 and scoped IPv6 are rejected. And wolfSSL 5.9.2 and newer also reject single-label DNS names other than `localhost` during identity setup, so a fully qualified DNS name is needed for portable verified connections. The default `VERIFY_NONE` context skips these identity checks entirely. If your application supplies a TLS callback that disables server authentication, either with `WOLFSSL_VERIFY_NONE` or a callback that accepts every certificate, it must set `MQTT_CLIENT_FLAG_TLS_SKIP_HOST_CHECK` with `MqttClient_Flags`, and the flag has to be set on each new connection because disconnecting clears it. The example sets it for `-t` without `-A` and for `WOLFMQTT_ALLOW_INSECURE_TLS`, and even then embedded CA builds still verify the peer. There is also a compatibility change: a TLS callback that configures its own certificate identity on `client->tls.ssl` must set `MQTT_CLIENT_FLAG_TLS_CUSTOM_PEER_NAME` after the name or IP check succeeds, or wolfMQTT replaces that identity with the connection host.

Building it on Linux, with CMake, or through vcpkg

The Unix build is the autotools path, and the README lists the four steps: run `./autogen.sh` if you cloned from GitHub, then `./configure`, then `make`, then `sudo make install`. That first step is only needed if you cloned from GitHub, and `./configure --help` lists the build options, which are generated into `wolfmqtt/options.h`. Debug messages can be enabled with `--enable-debug` or `--enable-debug=verbose`. CMake is the alternative, and it also covers Visual Studio.

mkdir build
cd build
# to use installed wolfSSL location (library and headers)
cmake .. -DWITH_WOLFSSL=/prefix/to/wolfssl/install/
# OR to use a wolfSSL source tree
cmake .. -DWITH_WOLFSSL_TREE=/path/to/wolfssl/
# build
cmake --build .

There is also a vcpkg route, where the port is kept up to date by wolfSSL, and the same vcpkg ports exist for wolftpm, wolfssl and curl.

    ./vcpkg integrate install
    ./vcpkg install wolfmqtt

A CMake option worth knowing about is `-DWOLFMQTT_UNIT_TESTS=no`, which disables the `wolfmqtt_unit_tests` target, whose default is yes. That target is only added when wolfMQTT is the top-level project, so downstream consumers using `add_subdirectory()` are unaffected. Beyond the mainstream paths there are platform-specific build guides in the repository for Arduino, MinGW and Zephyr, with Zephyr support living in the `zephyr` directory.

Windows means building wolfSSL first and matching architectures

The Visual Studio route is the longest set of instructions in the README, and it exists because wolfMQTT is built on wolfSSL rather than bundling TLS. You open the `wolfssl64.sln` from the wolfSSL root, retarget the solution to your Visual Studio version, select the Debug DLL or Release DLL configuration and note whether you are building 32-bit x86 or 64-bit x64, then build the wolfSSL solution. The `wolfssl.lib` and `wolfssl.dll` files are copied into the wolfMQTT root, and the README gives the exact source directories for the four combinations, from `DLL Debug` through `x64/DLL Release`. You then open `wolfmqtt.sln` in the wolfMQTT root and make sure the architecture matches the one you used for wolfSSL, because a mismatch there is a linker error rather than a subtle bug. The include path for the wolfSSL headers defaults to `./../wolfssl/`, and if your wolfSSL root is elsewhere you adjust it under C/C++ then General then Additional Include Directories, and the Visual Studio build settings are configured through `wolfmqtt/vs_settings.h`. The repository also carries `wolfmqtt.sln`, `wolfmqtt.vcxproj` and `wolfmqtt.vcxproj.filters` at the top level.

Example code for the transports people actually ship

The example directory is where the practical guidance lives, and it is broad. There is the general `mqttexample.c` with its header, a `mqttclient` directory, a `mqttsimple` example, and a `pub-sub` example. Transport implementations sit alongside them, with `mqttnet.c` and `mqttnet.h` for the network layer, `mqttport.c` and `mqttport.h` for the port layer, and `mqttuart.c` for serial. Then there are the specific integrations a device team is likely to need: `aws/`, `azure/`, `firmware/`, `multithread/`, `nbclient/`, `sn-client/` for MQTT-SN, `threadx/`, `websocket/`, `wiot/` for Azure IoT, and `nbclient/`. The topics list includes mqtt-sn, which matches the `sn-client` example, and mqtt-tls. The repository also carries a `BROKER.md` at the top level and a `certs/` directory, and a ChangeLog alongside COPYING and the MIT-style licensing files. The release cadence is steady, with v2.0.0 in March 2026, v2.1.0 in July 2026 and v2.2.0 in October 2026, and the last push to the repository was on 2026-10-16.

Editorial conclusion

Adopt wolfMQTT when you are putting an MQTT client on a device where library size and TLS support both matter, and you already use wolfSSL or can accept its licensing. Skip it if you want a client with an asynchronous or event-driven API, since the documented calls block on the network read, and skip it if you need a permissive licence, since wolfMQTT is GPL-3.0. Before you commit, read the host identity rules in the README, because a device connecting to a broker by numeric IP needs a recent wolfSSL with the right build flag, and getting that wrong fails before the handshake rather than after it.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. wolfSSL/wolfMQTT on GitHub