{"id":13575980,"url":"https://github.com/wolfSSL/wolfMQTT","last_synced_at":"2025-04-05T05:30:31.730Z","repository":{"id":2025665,"uuid":"44983668","full_name":"wolfSSL/wolfMQTT","owner":"wolfSSL","description":"wolfMQTT is a small, fast, portable MQTT client implementation, including support for TLS 1.3.","archived":false,"fork":false,"pushed_at":"2025-03-28T20:37:55.000Z","size":2177,"stargazers_count":535,"open_issues_count":11,"forks_count":158,"subscribers_count":56,"default_branch":"master","last_synced_at":"2025-03-30T16:11:21.723Z","etag":null,"topics":["embedded","iot","iot-security","mqqt-packet","mqtt","mqtt-client","mqtt-library","mqtt-sn","mqtt-tls","qos-0-2","quality-of-service","security","sensor-network","tls","tls13","tls13-support","wolfmqtt","wolfssl","wolfssl-library"],"latest_commit_sha":null,"homepage":"https://www.wolfssl.com","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wolfSSL.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-10-26T16:58:13.000Z","updated_at":"2025-03-28T20:38:00.000Z","dependencies_parsed_at":"2023-01-13T11:35:09.078Z","dependency_job_id":"f1c20249-d202-416e-8337-95976447cd63","html_url":"https://github.com/wolfSSL/wolfMQTT","commit_stats":{"total_commits":462,"total_committers":19,"mean_commits":24.31578947368421,"dds":0.4458874458874459,"last_synced_commit":"6a1a7f85b4b42e8818a3b3d91760f55ed34d345f"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2FwolfMQTT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2FwolfMQTT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2FwolfMQTT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2FwolfMQTT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wolfSSL","download_url":"https://codeload.github.com/wolfSSL/wolfMQTT/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247293999,"owners_count":20915329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["embedded","iot","iot-security","mqqt-packet","mqtt","mqtt-client","mqtt-library","mqtt-sn","mqtt-tls","qos-0-2","quality-of-service","security","sensor-network","tls","tls13","tls13-support","wolfmqtt","wolfssl","wolfssl-library"],"created_at":"2024-08-01T15:01:05.982Z","updated_at":"2025-04-05T05:30:31.719Z","avatar_url":"https://github.com/wolfSSL.png","language":"C","readme":"# wolfMQTT\n\nThis is an implementation of the MQTT Client written in C for embedded use, which supports SSL/TLS via the wolfSSL library. This library was built from the ground up to be multi-platform, space conscious and extensible. Integrates with wolfSSL to provide TLS support.\n\nFor details on wolfMQTT [see the wolfMQTT Manual](https://www.wolfssl.com/documentation/manuals/wolfmqtt/wolfMQTT-Manual.pdf).\n\n## Building\n\n### Mac/Linux/Unix\n\n1. `./autogen.sh` (if cloned from GitHub)\n2. `./configure` (to see a list of build options use `./configure --help`)\n3. `make`\n4. `sudo make install`\n\nNotes:\n* If `wolfssl` was recently installed, run `sudo ldconfig` to update the linker cache.\n* Debug messages can be enabled using `--enable-debug` or `--enable-debug=verbose` (for extra logging).\n* For a list of build options run `./configure --help`.\n* The build options are generated in a file here: `wolfmqtt/options.h`.\n\n### Windows Visual Studio\n\nFor building wolfMQTT with TLS support in Visual Studio:\n\n1. Open the `\u003cwolfssl-root\u003e/wolfssl64.sln`.\n2. Re-target for your Visual Studio version (right-click on solution and choose `Retarget solution`).\n3. Make sure the `Debug DLL` or `Release DLL` configuration is selected. Make note if you are building 32-bit `x86` or 64-bit `x64`.\n4. Build the wolfSSL solution.\n5. Copy the `wolfssl.lib` and `wolfssl.dll` files into `\u003cwolfmqtt-root\u003e`.\n   * For `DLL Debug` with `x86` the files are in: `DLL Debug`.\n   * For `DLL Release` with `x86` the files are in: `DLL Release`.\n   * For `DLL Debug` with `x64` the files are in: `x64/DLL Debug`.\n   * For `DLL Release` with `x64` the files are in: `x64/DLL Release`.\n6. Open the `\u003cwolfmqtt-root\u003e/wolfmqtt.sln` solution.\n7. Make sure you have the same architecture (`x86` or `x64` selected) as used in wolfSSL above.\n8. By default the include path for the wolfssl headers is `./../wolfssl/`. If your wolfssl root location is different you can go into the project settings and adjust this in `C/C++` -\u003e `General` -\u003e `Additional Include Directories`.\n9. Configure your Visual Studio build settings using `wolfmqtt/vs_settings.h`.\n10. Build the wolfMQTT solution.\n\n### CMake\nCMake supports compiling in many environments including Visual Studio\nif CMake support is installed. The commands below can be run in\n`Developer Command Prompt`.\n\n```\nmkdir build\ncd build\n# to use installed wolfSSL location (library and headers)\ncmake .. -DWITH_WOLFSSL=/prefix/to/wolfssl/install/\n# OR to use a wolfSSL source tree\ncmake .. -DWITH_WOLFSSL_TREE=/path/to/wolfssl/\n# build\ncmake --build .\n```\n\n### vcpkg\n\n You can download and install wolfMQTT using the [vcpkg](https://github.com/Microsoft/vcpkg):\n\n    git clone https://github.com/Microsoft/vcpkg.git\n    cd vcpkg\n    ./bootstrap-vcpkg.sh\n    OR for Windows\n    bootstrap-vcpkg.bat\n\n    ./vcpkg integrate install\n    ./vcpkg install wolfmqtt\n\nThe wolfMQTT port in vcpkg is kept up to date by wolfSSL.\n\nWe also have vcpkg ports for wolftpm, wolfssl and curl.\n\n### Arduino\n\nSee `README.md` at [IDE/ARDUINO.README.md](IDE/ARDUINO.README.md)\n\n### MinGW\n\n```sh\nexport PATH=\"/opt/mingw-w32-bin_i686-darwin/bin:$PATH\"\nexport PREFIX=$PWD/build\n\n# wolfSSL\ncd wolfssl\n./configure --host=i686 CC=i686-w64-mingw32-gcc LD=i686-w64-mingw32-ld CFLAGS=\"-DWIN32 -DMINGW -D_WIN32_WINNT=0x0600\" LIBS=\"-lws2_32 -L$PREFIX/lib -lwolfssl\" --prefix=$PREFIX\nmake\nmake install\n\n# wolfMQTT\ncd ../wolfmqtt\n./configure --host=i686 CC=i686-w64-mingw32-gcc LD=i686-w64-mingw32-ld CFLAGS=\"-DWIN32 -DMINGW -D_WIN32_WINNT=0x0600 -DBUILDING_WOLFMQTT -I$PREFIX/include\" LDFLAGS=\"-lws2_32 -L$PREFIX/lib -lwolfssl\" --prefix=$PREFIX --disable-examples\nmake\n```\n\n### Zephyr RTOS\n\nSupport for Zephyr is available in the [zephyr](zephyr) directory. For instructions on how to build for Zephyr, see the [README.md](zephyr/README.md).\n\n## Architecture\n\nThe library has three components.\n\n### 1. mqtt_client\n\nThis is where the top level application interfaces for the MQTT client reside.\n\n* `int MqttClient_Init(MqttClient *client, MqttNet *net, MqttMsgCb msg_cb, byte *tx_buf, int tx_buf_len, byte *rx_buf, int rx_buf_len, int cmd_timeout_ms);`\n\nThese API's are blocking on `MqttNet.read` until error/timeout (`cmd_timeout_ms`):\n\n* `int MqttClient_Connect(MqttClient *client, MqttConnect *connect);`\n* `int MqttClient_Publish(MqttClient *client, MqttPublish *publish);`\n* `int MqttClient_Subscribe(MqttClient *client, MqttSubscribe *subscribe);`\n* `int MqttClient_Unsubscribe(MqttClient *client, MqttUnsubscribe *unsubscribe);`\n* `int MqttClient_Ping(MqttClient *client);`\n* `int MqttClient_Disconnect(MqttClient *client);`\n\nThis function blocks waiting for a new publish message to arrive for a maximum duration of `timeout_ms`.\n\n* `int MqttClient_WaitMessage(MqttClient *client, MqttMessage *message, int timeout_ms);`\n\nThese are the network connect / disconnect interfaces that wrap the MqttNet callbacks and handle WolfSSL TLS:\n\n* `int MqttClient_NetConnect(MqttClient *client, const char* host, word16 port, int timeout_ms, int use_tls, MqttTlsCb cb);`\n* `int MqttClient_NetDisconnect(MqttClient *client);`\n\nHelper functions:\n\n* `const char* MqttClient_ReturnCodeToString(int return_code);`\n\n### 2. mqtt_packet\n\nThis is where all the packet encoding/decoding is handled.\n\nThe header contains the MQTT Packet structures for:\n\n* Connect: `MqttConnect`\n* Publish / Message: `MqttPublish` / `MqttMessage` (they are the same)\n* Subscribe: `MqttSubscribe`\n* Unsubscribe: `MqttUnsubscribe`\n\n\n### 3. mqtt_socket\n\nThis is where the transport socket optionally wraps TLS and uses the `MqttNet` callbacks for the platform specific network handling.\n\nThe header contains the MQTT Network structure `MqttNet` for network callback and context.\n\n\n## Implementation\n\nHere are the steps for creating your own implementation.\n\n1. Create network callback functions for Connect, Read, Write and Disconnect. See `examples/mqttnet.c` and `examples/mqttnet.h`.\n2. Define the callback functions and context in a `MqttNet` structure.\n3. Call `MqttClient_Init` passing in a `MqttClient` structure pointer, `MqttNet` structure pointer, `MqttMsgCb` function pointer, TX/RX buffers with maximum length and command timeout.\n4. Call `MqttClient_NetConnect` to connect to broker over network. If `use_tls` is non-zero value then it will perform a TLS connection. The TLS callback `MqttTlsCb` should be defined for wolfSSL certificate configuration.\n5. Call `MqttClient_Connect` passing pointer to `MqttConnect` structure to send MQTT connect command and wait for Connect Ack.\n6. Call `MqttClient_Subscribe` passing pointer to `MqttSubscribe` structure to send MQTT Subscribe command and wait for Subscribe Ack (depending on QoS level).\n7. Call `MqttClient_WaitMessage` passing pointer to `MqttMessage` to wait for incoming MQTT Publish message.\n\n\n## Examples\n\n### Client Example\nThe example MQTT client is located in `/examples/mqttclient/`. This example exercises many of the exposed API's and prints any incoming publish messages for subscription topic \"wolfMQTT/example/testTopic\". This client contains examples of many MQTTv5 features, including the property callback and server assignment of client ID. The mqqtclient example is a good starting template for your MQTT application.\n\n### Simple Standalone Client Example\nThe example MQTT client is located in `/examples/mqttsimple/`. This example demonstrates a standalone client using standard BSD sockets. This requires `HAVE_SOCKET` to be defined, which comes from the ./configure generated `wolfmqtt/config.h` file. All parameters are build-time macros defined at the top of `/examples/mqttsimple/mqttsimple.c`.\n\n### Non-Blocking Client Example\nThe example MQTT client is located in `/examples/nbclient/`. This example uses non-blocking I/O for message exchange. The wolfMQTT library must be configured with the `--enable-nonblock` option (or built with `WOLFMQTT_NONBLOCK`).\n\n### Firmware Example\nThe MQTT firmware update is located in `/examples/firmware/`. This example has two parts. The first is called \"fwpush\", which signs and publishes a firmware image. The second is called \"fwclient\", which receives the firmware image and verifies the signature. This example publishes message on the topic \"wolfMQTT/example/firmware\". The \"fwpush\" application is an example of using a publish callback to send the payload data.\n\n### Azure IoT Hub Example\nWe setup a wolfMQTT IoT Hub on the Azure server for testing. We added a device called `demoDevice`, which you can connect and publish to. The example demonstrates creation of a SasToken, which is used as the password for the MQTT connect packet. It also shows the topic names for publishing events and listening to `devicebound` messages. This example only works with `ENABLE_MQTT_TLS` set and the wolfSSL library present because it requires Base64 Encode/Decode and HMAC-SHA256. Note: The wolfSSL library must be built with `./configure --enable-base64encode` or `#define WOLFSSL_BASE64_ENCODE`. The `wc_GetTime` API was added in 3.9.1 and if not present you'll need to implement your own version of this to get current UTC seconds or update your wolfSSL library.\n**NOTE** The Azure broker only supports MQTT v3.1.1\n\n### AWS IoT Example\nWe setup an AWS IoT endpoint and testing device certificate for testing. The AWS server uses TLS client certificate for authentication. The example is located in `/examples/aws/`. The example subscribes to `$aws/things/\"AWSIOT_DEVICE_ID\"/shadow/update/delta` and publishes to `$aws/things/\"AWSIOT_DEVICE_ID\"/shadow/update`.\n**NOTE** The AWS broker only supports MQTT v3.1.1\n\n### Watson IoT Example\nThis example enables the wolfMQTT client to connect to the IBM Watson Internet of Things (WIOT) Platform. The WIOT Platform has a limited test broker called \"Quickstart\" that allows non-secure connections to exercise the component. The example is located in `/examples/wiot/`. Works with MQTT v5 support enabled.\n**NOTE** The WIOT Platform will be disabled DEC2023. The demo may still be useful for users of IBM Watson IOT. \n\n### MQTT-SN Example\nThe Sensor Network client implements the MQTT-SN protocol for low-bandwidth networks. There are several differences from MQTT, including the ability to use a two byte Topic ID instead the full topic during subscribe and publish. The SN client requires an MQTT-SN gateway. The gateway acts as an intermediary between the SN clients and the broker. This client was tested with the Eclipse Paho MQTT-SN Gateway, which connects by default to the public Eclipse broker, much like our wolfMQTT Client example. The address of the gateway must be configured as the host. The example is located in `/examples/sn-client/`.\n\nMore about MQTT-SN examples in [examples/sn-client/README.md](examples/sn-client/README.md)\n\n### Multithread Example\nThis example exercises the multithreading capabilities of the client library. The client implements two tasks: one that publishes to the broker; and another that waits for messages from the broker. The publish thread is created `NUM_PUB_TASKS` times (5 by default) and sends unique messages to the broker. This feature is enabled using the `--enable-mt` configuration option. The example is located in `/examples/multithread/`.\n\nThe multi-threading feature can also be used with the non-blocking socket (--enable-nonblock).\n\nIf you are having issues with thread synchronization on Linux consider using not the conditional signal (`WOLFMQTT_NO_COND_SIGNAL`).\n\n### Atomic publish and subscribe examples\nIn the `examples/pub-sub` folder, there are two simple client examples:\n* mqtt-pub - publishes to a topic\n* mqtt-sub - subscribes to a topic and waits for messages\n\nThese examples are useful for quickly testing or scripting.\n\n## Example Options\nThe command line examples can be executed with optional parameters. To see a list of the available parameters, add the `-?`\n\n```\n ./examples/mqttclient/mqttclient -?\nmqttclient:\n-?          Help, print this usage\n-h \u003chost\u003e   Host to connect to, default: test.mosquitto.org\n-p \u003cnum\u003e    Port to connect on, default: Normal 1883, TLS 8883\n-t          Enable TLS\n-A \u003cfile\u003e   Load CA (validate peer)\n-K \u003ckey\u003e    Use private key (for TLS mutual auth)\n-c \u003ccert\u003e   Use certificate (for TLS mutual auth)\n-S \u003cstr\u003e    Use Host Name Indication, blank defaults to host\n-q \u003cnum\u003e    Qos Level 0-2, default: 0\n-s          Disable clean session connect flag\n-k \u003cnum\u003e    Keep alive seconds, default: 60\n-i \u003cid\u003e     Client Id, default: WolfMQTTClient\n-l          Enable LWT (Last Will and Testament)\n-u \u003cstr\u003e    Username\n-w \u003cstr\u003e    Password\n-m \u003cstr\u003e    Message, default: test\n-n \u003cstr\u003e    Topic name, default: wolfMQTT/example/testTopic\n-r          Set Retain flag on publish message\n-C \u003cnum\u003e    Command Timeout, default: 30000ms\n-P \u003cnum\u003e    Max packet size the client will accept, default: 1048576\n-T          Test mode\n-f \u003cfile\u003e   Use file contents for publish\n```\nThe available options vary depending on the library configuration.\n\n\n## Broker compatibility\nwolfMQTT client library has been tested with the following brokers:\n* Adafruit IO by Adafruit\n* AWS by Amazon\n* Azure by Microsoft\n* flespi by Gurtam\n* HiveMQ and HiveMQ Cloud by HiveMQ GmbH\n* IBM WIoTP Message Gateway by IBM\n* Mosquitto by Eclipse\n* Paho MQTT-SN Gateway by Eclipse\n* VerneMQ by VerneMQ/Erlio\n* EMQX broker\n\n## Specification Support\n\n### MQTT v3.1.1 Specification Support\n\nThe initially supported version with full specification support for all features and packets type such as:\n* QoS 0-2\n* Last Will and Testament (LWT)\n* Client examples for: AWS, Azure IoT, Firmware update, non-blocking and generic.\n\n### MQTT v5.0 Specification Support\n\nThe wolfMQTT client supports connecting to v5 enabled brokers when configured with the `--enable-v5` option. \nThe following v5.0 specification features are supported by the wolfMQTT client:\n* AUTH packet\n* User properties\n* Server connect ACK properties\n* Format and content type for publish\n* Server disconnect\n* Reason codes and strings\n* Maximum packet size\n* Server assigned client identifier\n* Subscription ID\n* Topic Alias\n\nThe v5 enabled wolfMQTT client was tested with the following MQTT v5 brokers:\n* Mosquitto\n** Runs locally.\n** `./examples/mqttclient/mqttclient -h localhost`\n* Flespi\n** Requires an account tied token that is regenerated hourly.\n** `./examples/mqttclient/mqttclient -h \"mqtt.flespi.io\" -u \"\u003cyour-flespi-token\u003e\"`\n* VerneMQ MQTTv5 preview\n** Runs locally.\n** `./examples/mqttclient/mqttclient -h localhost`\n* HiveMQ 4.0.0 EAP\n** Runs locally.\n** `./examples/mqttclient/mqttclient -h localhost`\n* HiveMQ Cloud\n** `./examples/mqttclient/mqttclient -h 833f87e253304692bd2b911f0c18dba1.s1.eu.hivemq.cloud -t -S -u wolf1 -w NEZjcm7i8eRjFKF -p 8883`\n* EMQX broker\n** `./examples/mqttclient/mqttclient -h \"broker.emqx.io\"`\n\nProperties are allocated from a local stack (size `MQTT_MAX_PROPS`) by default. Define `WOLFMQTT_DYN_PROP` to use malloc for property allocation.\n\n### MQTT Sensor Network (MQTT-SN) Specification Support\n\nThe wolfMQTT SN Client implementation is based on the OASIS MQTT-SN v1.2 specification. The SN API is configured with the `--enable-sn` option. There is a separate API for the sensor network API, which all begin with the \"SN_\" prefix. The wolfMQTT SN Client operates over UDP, which is distinct from the wolfMQTT clients that use TCP. The following features are supported by the wolfMQTT SN Client:\n* Register\n* Will topic and message set up\n* Will topic and message update\n* All QoS levels\n* Variable-sized packet length field\n\nUnsupported features:\n* Automatic gateway discovery is not implemented\n* Multiple gateway handling\n\nThe SN client was tested using the Eclipse Paho MQTT-SN Gateway (https://github.com/eclipse/paho.mqtt-sn.embedded-c) running locally and on a separate network node. Instructions for building and running the gateway are in the project README.\n\n## Post-Quantum MQTT Support\n\nRecently the OpenQuantumSafe project has integrated their fork of OpenSSL with the mosquito MQTT broker. You can now build wolfMQTT with wolfSSL and liboqs and use that to publish to the mosquito MQTT broker. Currently, wolfMQTT supports the `KYBER_LEVEL1` and `P256_KYBER_LEVEL1` groups and FALCON_LEVEL1 for authentication in TLS 1.3. This works on Linux.\n\n### Getting Started with Post-Quantum Mosquito MQTT Broker and Subscriber\n\nTo get started, you can use the code from the following github pull request:\n\nhttps://github.com/open-quantum-safe/oqs-demos/pull/143\n\nFollow all the instructions in README.md and USAGE.md. This allows you to create a docker image and a docker network. Then you will run a broker, a subscriber and a publisher. At the end the publisher will exit and the broker and subscriber will remain active. You will need to re-activate the publisher docker instance and get the following files onto your local machine:\n\n- /test/cert/CA.crt\n- /test/cert/publisher.crt\n- /test/cert/publisher.key\n\nNOTE: Do not stop the broker and the subscriber instances.\n\n### Building and Running Post-Quantum wolfMQTT Publisher [DEPRECATED]\n\nPlease see the following issue on Open Quantum Safe's oqs-demo repo:\n\nhttps://github.com/open-quantum-safe/oqs-demos/issues/346\n\n## Curl Easy Socket Support\n\nwolfMQTT now supports using libcurl's easy socket interface as a backend.\nWhen enabled, wolfMQTT will use the libcurl API for the socket backend,\nand libcurl will use wolfSSL to negotiate TLS.\nThis can be enabled with `--enable-curl`.\n\nAt this time wolfMQTT's libcurl option supports both TLS and mTLS, but not Post-Quantum TLS.\n\n### How to use libcurl with wolfMQTT\n\nTo use wolfMQTT with libcurl and wolfSSL:\n- build wolfssl with `--enable-curl` and install to `/usr/local`.\n- build libcurl with `--with-wolfssl` and install to `/usr/local`.\n\nFinally, build wolfMQTT with `--enable-curl`.\n\n### Supported Build Options\n\nThe `--enable-curl` option works with these combinations:\n- `--enable-mt`\n- `--enable-nonblock`\n- `--enable-tls` (default enabled)\n- `--enable-timeout` (default enabled)\n\nHowever `--enable-curl` is incompatible and not supported with these options:\n- `--enable-all`\n- `--enable-sn`\n\n## Stress Build Option\n\nTo simplify testing a stress build option has been added, `--enable-stress=[args]`.\nThe Stress option enables multithreading and nonblocking, and adds defines for\n`TEST_NONBLOCK`, `NUM_PUB_TASKS`, and `NUM_PUB_PER_TASK`.\n\nExamples of usage:\n- `--enable-stress`: stress with default options.\n- `--enable-stress=t7,p8`: stress with 7 threads, and 8 publishes per thread.\n- `--enable-stress=t7,p8 --enable-curl`: same as above, but with curl backend.\n\nNote: When stress is enabled, the Multithread Example becomes localhost only\nand will not connect to remote servers. Additionally the test `scripts/stress.test`\nis added to `make check`, and all other tests are disabled.\n\n## WebSocket Support\n\nwolfMQTT supports MQTT over WebSockets, allowing clients to connect to MQTT brokers through WebSocket endpoints. This is useful for environments where traditional MQTT ports might be blocked or when integrating with web applications.\n\nBoth standard WebSockets and secure WebSockets (WSS) are supported.\n\n### Building with WebSocket Support\n\nTo build wolfMQTT with WebSocket support:\n\n1. Install the libwebsockets development library:\n\n```\n# On Debian/Ubuntu\nsudo apt-get install libwebsockets-dev\n\n# On macOS with Homebrew\nbrew install libwebsockets\n```\n\n2. Configure wolfMQTT with WebSocket support:\n\n```\n./configure --enable-websocket\n```\n   Note: You can also build wolfSSL with `--enable-opensslcoexist` (to support both OpenSSL and wolfSSL in the same build) if you encounter any conflicts.\n\n3. Build as usual:\n\n```\nmake\n```\n\n### WebSocket Example\n\nThe WebSocket client example is located in `/examples/websocket/`. This example demonstrates how to connect to an MQTT broker using WebSockets. The example subscribes to the topic \"test/topic\" and waits for incoming messages.\n\nTo run the example:\n\n```\n./examples/websocket/websocket_client [-h host] [-p port] [-t]\n```\n\nBy default, it connects to `localhost` on port `8080`.\n\n#### Secure WebSocket Support\n\nwolfMQTT also supports secure WebSockets (WSS), which use TLS to encrypt the WebSocket connection.\n\nTo use secure WebSockets:\n\n* Make sure you have built wolfMQTT with both WebSocket and TLS support:\n\n```\n./configure --enable-websocket --enable-tls\n```\n* Run the WebSocket example with TLS enabled:\n\n```\n./examples/websocket/websocket_client -t -p 8081\n```\n* You can also specify a CA certificate for TLS verification:\n\n```\n./examples/websocket/websocket_client -t -p 8081 -A /path/to/ca-cert.pem\n```\n* For mutual TLS authentication, you can specify client certificate and key:\n\n```\n./examples/websocket/websocket_client -t -p 8081 -A /path/to/ca-cert.pem --cert /path/to/client-cert.pem --key /path/to/client-key.pem\n```\n\n* You can also build the libwebsockets library from source with support for TLS from wolfSSL:\n\n```\ncmake .. -DLWS_WITH_WOLFSSL=1 -DLWS_WOLFSSL_INCLUDE_DIRS=/usr/local/include/wolfssl -DLWS_WOLFSSL_LIBRARIES=/usr/local/lib/libwolfssl.so -DLWS_WITH_EXTERNAL_POLL=1 -DCMAKE_BUILD_TYPE=DEBUG ..\n```\n\n   This option requires wolfSSL to be built with `./configure --enable-libwebsockets --enable-alpn` and installed to `/usr/local`.\n\n### Broker Configuration\n\nTo use the WebSocket example, your MQTT broker must be configured to support WebSockets. For Mosquitto, add the following to your `mosquitto.conf`:\n\n```\n# WebSocket settings\nlistener 8080\nprotocol websockets\n```\n\nFor Secure WebSocket Support, add:\n\n```\n# Secure WebSocket\nlistener 8081\nprotocol websockets\ncafile \u003cpath-to\u003e/ca-cert.pem\n# Path to the PEM encoded server certificate.\ncertfile \u003cpath-to\u003e/server-cert.pem\n# Path to the PEM encoded keyfile.\nkeyfile \u003cpath-to\u003e/server-key.pem\n```\n\nThen restart Mosquitto with this configuration:\n\n```\nmosquitto -c mosquitto.conf\n```\n\nThere is an example mosquitto configuration file in the websocket folder:\n`\u003cwolfMQTT\u003e$ mosquitto -c examples/websocket/mosq_ws.conf`\n\nYou can also build the mosquitto broker to use wolfSSL for the TLS connection:\nhttps://github.com/wolfSSL/osp/tree/master/mosquitto\n\n### Implementation Details\n\nThe WebSocket implementation uses libwebsockets as the backend and provides custom network callbacks for the MQTT client:\n\n- `NetWebsocket_Connect`: Establishes a WebSocket connection to the broker\n- `NetWebsocket_Read`: Reads data from the WebSocket connection\n- `NetWebsocket_Write`: Writes data to the WebSocket connection\n- `NetWebsocket_Disconnect`: Closes the WebSocket connection\n\nThe example also implements a ping mechanism to keep the WebSocket connection alive, sending a ping to the broker every 30 seconds.\n\n### Testing with public brokers\nYou can test the wolfMQTT client against public brokers supporting websockets:\n* Mosquitto unencrypted\n\n    `./examples/websocket/websocket_client -h test.mosquitto.org -p8080`\n \n* Mosquitto secure websocket\n\n    `./examples/websocket/websocket_client -h test.mosquitto.org -p8081 -t`\n \n* HiveMQ unencrypted\n\n    `./examples/websocket/websocket_client -h broker.hivemq.com -p8000`\n\n* HiveMQ secure websockets\n\n    `./examples/websocket/websocket_client -h broker.hivemq.com -p8884 -t`\n","funding_links":[],"categories":["Protocol Library","C"],"sub_categories":["MQTT"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FwolfSSL%2FwolfMQTT","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FwolfSSL%2FwolfMQTT","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FwolfSSL%2FwolfMQTT/lists"}