### Run Mosquitto with Example WebSocket Configuration

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Start the Mosquitto broker using the provided example WebSocket configuration file.

```bash
mosquitto -c examples/websocket/mosq_ws.conf
```

--------------------------------

### Run WebSocket Client Example

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Execute the WebSocket client example, optionally specifying host and port.

```bash
./examples/websocket/websocket_client [-h host] [-p port] [-t]
```

--------------------------------

### Running wolfMQTT Examples

Source: https://github.com/wolfssl/wolfmqtt/blob/master/AGENTS.md

Examples of how to run the wolfMQTT client executable, including showing help and connecting to a local broker with or without TLS.

```bash
./examples/mqttclient/mqttclient -?    # Show help with available options
./examples/mqttclient/mqttclient -h localhost -p 1883   # Connect to local broker
./examples/mqttclient/mqttclient -h localhost -t -p 8883  # TLS connection
```

--------------------------------

### Create Project from Example and Flash

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/components/wolfmqtt/README.md

This script demonstrates how to create a new ESP-IDF project from a wolfMQTT example, set up the component registry URL for staging, and then flash and monitor the device.

```bash
#!/bin/bash

. ~/esp/esp-idf/export.sh

# Needed for Staging site:
export IDF_COMPONENT_REGISTRY_URL=https://components-staging.espressif.com

idf.py create-project-from-example "gojimmypi/mywolfmqtt^1.18.0:AWS_IOT_MQTT"

cd AWS_IOT_MQTT

idf.py -p /dev/ttyS9 -b 921600 flash monitor -b 115200

```

--------------------------------

### Create and Build AWS IoT MQTT Example Project

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/wolfmqtt_template/components/wolfmqtt/README.md

This script sets up the ESP-IDF environment, configures the component registry URL for staging, creates a new project from a specific wolfMQTT example (AWS_IoT_MQTT), navigates into the project directory, and then flashes and monitors the project on a specified serial port.

```bash
#!/bin/bash

. ~/esp/esp-idf/export.sh

# Needed for Staging site:
export IDF_COMPONENT_REGISTRY_URL=https://components-staging.espressif.com

idf.py create-project-from-example "gojimmypi/mywolfmqtt^1.18.0-preview8a::AWS_IoT_MQTT"

cd AWS_IoT_MQTT

idf.py -p /dev/ttyS9 -b 921600 flash monitor -b 115200

```

--------------------------------

### Install wolfMQTT using vcpkg

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Install wolfMQTT via the vcpkg package manager. This command assumes vcpkg has been cloned and bootstrapped.

```bash
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
# OR for Windows
bootstrap-vcpkg.bat

./vcpkg integrate install
./vcpkg install wolfmqtt
```

--------------------------------

### Install WolfMQTT Library and Headers

Source: https://github.com/wolfssl/wolfmqtt/blob/master/CMakeLists.txt

Installs the WolfMQTT library targets, export set, and header files. This ensures the library can be used by other projects after installation.

```cmake
include(GNUInstallDirs)

install(TARGETS wolfmqtt
        EXPORT  wolfmqtt-targets
        LIBRARY DESTINATION lib
        ARCHIVE DESTINATION lib
        RUNTIME DESTINATION bin
        )

# Install the export set
install(EXPORT wolfmqtt-targets
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/wolfmqtt
        FILE wolfmqtt-config.cmake)

# Install the headers
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/wolfmqtt/
        DESTINATION include/wolfmqtt
        FILES_MATCHING PATTERN "*.h")
install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/wolfmqtt/
        DESTINATION include/wolfmqtt
        FILES_MATCHING PATTERN "*.h")
```

--------------------------------

### Run Secure WebSocket Client Example

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Run the WebSocket client example with TLS enabled, specifying port and optionally a CA certificate.

```bash
./examples/websocket/websocket_client -t -p 8081
./examples/websocket/websocket_client -t -p 8081 -A /path/to/ca-cert.pem
```

--------------------------------

### Conditional Example Code Handling

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/wolfmqtt_template/main/CMakeLists.txt

This block handles the inclusion of example code. If the project is not the 'wolfmqtt_template', it proceeds to locate example source files.

```cmake
if("${THIS_PROJECT_PARENT_DIR}" STREQUAL "wolfmqtt_template")
    message(STATUS "For reference only in wolfmqtt_template project, no additional example code is added")
else()
    # All other examples are expected to have some example code available.

    # Set the specific example to look for in core examples:
    set(EXAMPLE_HEADER_FILE "mqttexample.h")

    # We'll first check if we are in the GitHub repo directory structure:
    set(PATH_TO_GITHUB_EXAMPLES "../../../../../../examples/")
    get_filename_component(PATH_TO_GITHUB_EXAMPLES "${PATH_TO_GITHUB_EXAMPLES}" ABSOLUTE)
    message(STATUS "Looking in PATH_TO_GITHUB_EXAMPLES: '${PATH_TO_GITHUB_EXAMPLES}'")

    # Otherwise we'll assume a stand-alone example, such as that from a Managed Component
    # Example: idf.py create-project-from-example "gojimmypi/mywolfmqtt=1.18.0-preview7:AWS_IoT_MQTT"
    get_filename_component(THIS_DIR "${CMAKE_CURRENT_LIST_DIR}" ABSOLUTE)
    message(STATUS "This CMakeLists.txt is located in: '${THIS_DIR}'")

    # Set a path to the example code.
    # Note that PATH_TO_EXAMPLES may be will be set to PATH_TO_GITHUB_EXAMPLES as appropriate.
    set(PATH_TO_EXAMPLES "${THIS_DIR}/examples")
    get_filename_component(PATH_TO_EXAMPLES "${PATH_TO_EXAMPLES}" ABSOLUTE)
    message(STATUS "Looking in PATH_TO_EXAMPLES: '${PATH_TO_EXAMPLES}'")

    # We cannot have source in both, so check that first:
    if (EXISTS "${PATH_TO_GITHUB_EXAMPLES}/${EXAMPLE_HEADER_FILE}" AND EXISTS "${PATH_TO_EXAMPLES}/${EXAMPLE_HEADER_FILE}")
        message(STATUS "ERROR: Found example source in multiple directories:")
        message(STATUS "Directory 1: '${THIS_DIR}'")
        get_filename_component(THIS_DIR "${PATH_TO_EXAMPLES}" ABSOLUTE)
        message(STATUS "Directory 1: '${THIS_DIR}'")
        message(FATAL_ERROR "Unable to resolve source. Please pick one.")
    elseif (EXISTS "${PATH_TO_GITHUB_EXAMPLES}/${EXAMPLE_HEADER_FILE}")
        # GitHub repository structure
        set(PATH_TO_EXAMPLES "${PATH_TO_GITHUB_EXAMPLES}" )
        message(STATUS "Using source from repository path: '${PATH_TO_EXAMPLES}'")
    elseif (EXISTS "${PATH_TO_EXAMPLES}/${EXAMPLE_HEADER_FILE}")
        # Standalone example
        message(STATUS "Using example source in '${PATH_TO_EXAMPLES}'")
    else()
        # Source not found
        set(PATH_TO_EXAMPLES "")
        message(STATUS "ERROR: Could not find example source code.")
    endif()
endif() # Example code check
```

--------------------------------

### Initialize and Use MQTT-SN Client API

Source: https://context7.com/wolfssl/wolfmqtt/llms.txt

Initializes an MQTT-SN client for UDP communication. This example demonstrates discovering a gateway, connecting, registering a topic name to get a topic ID, subscribing, and publishing using topic IDs.

```c
#ifdef WOLFMQTT_SN
#include "wolfmqtt/mqtt_sn_client.h"

int run_sn_client(MqttClient *client, MqttNet *net)
{
    SN_Connect  connect;
    SN_SearchGw search;
    SN_Register reg;
    SN_Subscribe subscribe;
    SN_Publish   publish;
    int rc;

    /* Initialize client for UDP (caller sets up MqttNet for UDP) */
    byte tx[512], rx[512];
    MqttClient_Init(client, net, /*on_message*/NULL,
                    tx, sizeof(tx), rx, sizeof(rx), 5000);

    /* Discover gateway (optional for known-address gateways) */
    memset(&search, 0, sizeof(search));
    search.radius = 1; /* hop radius */
    rc = SN_Client_SearchGW(client, &search);
    /* (gateway address stored in net->context after discovery) */

    /* Connect to gateway */
    memset(&connect, 0, sizeof(connect));
    connect.client_id      = "sn-sensor-01";
    connect.keep_alive_sec = 30;
    connect.clean_session  = 1;
    rc = SN_Client_Connect(client, &connect);
    if (rc != MQTT_CODE_SUCCESS) return rc;
    printf("SN Connected, gateway protocol ver %d\n",
           connect.ack.return_code);

    /* Register a topic name to obtain a short topic ID */
    memset(&reg, 0, sizeof(reg));
    reg.packet_id  = 1;
    reg.topicName  = "sensors/temp";
    rc = SN_Client_Register(client, &reg);
    if (rc != MQTT_CODE_SUCCESS) return rc;
    word16 topic_id = reg.regack.topicId;
    printf("Registered topic ID: %d\n", topic_id);

    /* Subscribe by topic ID */
    memset(&subscribe, 0, sizeof(subscribe));
    subscribe.packet_id         = 2;
    subscribe.topic_type        = SN_TOPIC_SHORT;
    subscribe.topics[0].topic_id = topic_id;
    subscribe.topics[0].qos      = MQTT_QOS_0;
    subscribe.topic_count        = 1;
    rc = SN_Client_Subscribe(client, &subscribe);

    /* Publish by topic ID */
    memset(&publish, 0, sizeof(publish));
    publish.topic_type  = SN_TOPIC_SHORT;
    publish.topic_id    = topic_id;
    publish.packet_id   = 3;
    publish.qos         = MQTT_QOS_0;
    const char *data    = "23.5";
    publish.buffer      = (byte*)data;
    publish.total_len   = (word32)strlen(data);
    rc = SN_Client_Publish(client, &publish);

    /* Disconnect (duration > 0 = enter sleep state) */
    SN_Client_Disconnect(client);
    return rc;
}
#endif /* WOLFMQTT_SN */
```

--------------------------------

### Install wolfMQTT Component (Windows)

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/components/wolfmqtt/README.md

Execute this command in Windows to copy all wolfMQTT component files to the local project directory.

```batch
.\install_wolfMQTT.cmd

```

--------------------------------

### Start QEMU Debug Server

Source: https://github.com/wolfssl/wolfmqtt/blob/master/zephyr/README.md

Initiate a debug server for the QEMU instance. This allows attaching a debugger like GDB to inspect the running application.

```bash
west build -t debugserver_qemu

```

--------------------------------

### Install libwebsockets Development Library

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Install the necessary development library for WebSocket support on Debian/Ubuntu or macOS.

```bash
# On Debian/Ubuntu
sudo apt-get install libwebsockets-dev

# On macOS with Homebrew
brew install libwebsockets
```

--------------------------------

### Install wolfMQTT Component (Linux/Mac/WSL)

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/components/wolfmqtt/README.md

Use this command to copy all wolfMQTT component files to the local project directory on Linux, macOS, or Windows Subsystem for Linux.

```bash
./install_wolfMQTT.cmd

```

--------------------------------

### Add Example Target with CMake

Source: https://github.com/wolfssl/wolfmqtt/blob/master/CMakeLists.txt

Defines a function to add an executable for a given source file, linking it against the wolfmqtt library and the mqtt_test_lib. This is used to build various MQTT examples.

```cmake
function(add_mqtt_example name src)
    add_executable(${name})
        examples/${src}
    )
    target_link_libraries(${name} wolfmqtt mqtt_test_lib)
endfunction()
```

--------------------------------

### Component Registration for AWS IoT MQTT Example

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/main/CMakeLists.txt

Registers the main component for the AWS IoT MQTT example, specifying source files, include directories, and dependencies.

```cmake
idf_component_register(
    SRCS
        main.c
        wifi_connect.c
        time_helper.c
        "${PATH_TO_EXAMPLES}/mqttexample.c"
        "${PATH_TO_EXAMPLES}/mqttnet.c"
        "${PATH_TO_EXAMPLES}/mqttport.c"
        "${PATH_TO_EXAMPLES}/aws/awsiot.c"
    INCLUDE_DIRS
        "."
        "include"
        "${PATH_TO_EXAMPLES}"
        "${PATH_TO_EXAMPLES}/aws"
#   REQUIRES
#       "${WOLFMQTT_COMPONENT_NAME}"
#       "${WOLFSSL_COMPONENT_NAME}"
#                          lwip
#                          nvs_flash
#                          esp_event
)
# idf_component_register
```

--------------------------------

### Start MQTT Broker and Subscriber

Source: https://github.com/wolfssl/wolfmqtt/blob/master/zephyr/README.md

Run a local MQTT broker and a subscriber for testing. Ensure the broker is configured to listen on port 11883.

```bash
cd modules/lib/wolfmqtt && mosquitto -c scripts/broker_test/mosquitto.conf
mosquitto_sub -p 11883 -t sensors

```

--------------------------------

### Set Protocol Examples Directory

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/wolfmqtt_template/CMakeLists.txt

Sets the PROTOCOL_EXAMPLES_DIR variable to the common protocol examples path within the ESP-IDF. This is used to include shared components.

```cmake
set (PROTOCOL_EXAMPLES_DIR $ENV{IDF_PATH}/examples/common_components/protocol_examples_common)

if (EXISTS "${PROTOCOL_EXAMPLES_DIR}")
    message(STATUS "Found PROTOCOL_EXAMPLES_DIR=${PROTOCOL_EXAMPLES_DIR}")
    set(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/examples/common_components/protocol_examples_common)
    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DFOUND_PROTOCOL_EXAMPLES_DIR")
else()
    message("NOT FOUND: PROTOCOL_EXAMPLES_DIR=${PROTOCOL_EXAMPLES_DIR}")
endif()
```

--------------------------------

### Minimal MQTT Client Publish/Subscribe Example

Source: https://context7.com/wolfssl/wolfmqtt/llms.txt

This C code implements a basic MQTT client that connects to a broker, subscribes to a topic, publishes a message, and then waits for incoming messages. It uses standard BSD sockets for network communication and includes network callbacks for connect, read, write, and disconnect operations. Ensure the necessary headers are included and the broker details are correctly configured.

```c
#include <stdio.h>
#include <string.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netdb.h>
#include <unistd.h>
#include "wolfmqtt/mqtt_client.h"

#define BROKER_HOST     "test.mosquitto.org"
#define BROKER_PORT     1883
#define CLIENT_ID       "wolfMQTT-demo"
#define TOPIC           "wolfMQTT/demo/topic"
#define PUBLISH_MSG     "Hello from wolfMQTT"
#define QOS             MQTT_QOS_1
#define CMD_TIMEOUT_MS  30000

static int g_sock = -1;
static volatile word16 g_packet_id = 0;

/* ---- Network callbacks ---- */
static int net_connect(void *ctx, const char *host, word16 port, int timeout_ms)
{
    (void)timeout_ms;
    struct addrinfo hints = {0}, *res;
    char port_str[8];
    snprintf(port_str, sizeof(port_str), "%d", port);
    hints.ai_socktype = SOCK_STREAM;
    if (getaddrinfo(host, port_str, &hints, &res) != 0) return MQTT_CODE_ERROR_NETWORK;
    g_sock = socket(res->ai_family, SOCK_STREAM, 0);
    int rc = connect(g_sock, res->ai_addr, res->ai_addrlen);
    freeaddrinfo(res);
    return (rc == 0) ? MQTT_CODE_SUCCESS : MQTT_CODE_ERROR_NETWORK;
}
static int net_read(void *ctx, byte *buf, int len, int timeout_ms)
{
    (void)ctx; (void)timeout_ms;
    int rc = (int)recv(g_sock, buf, len, 0);
    return (rc > 0) ? rc : MQTT_CODE_ERROR_NETWORK;
}
static int net_write(void *ctx, const byte *buf, int len, int timeout_ms)
{
    (void)ctx; (void)timeout_ms;
    int rc = (int)send(g_sock, buf, len, 0);
    return (rc > 0) ? rc : MQTT_CODE_ERROR_NETWORK;
}
static int net_disconnect(void *ctx)
{
    (void)ctx;
    if (g_sock >= 0) { close(g_sock); g_sock = -1; }
    return MQTT_CODE_SUCCESS;
}

/* ---- Message callback ---- */
static int on_msg(MqttClient *c, MqttMessage *msg, byte is_new, byte is_done)
{
    (void)c;
    if (is_new)
        printf("RX topic=%.*s qos=%d len=%u\n",
               msg->topic_name_len, msg->topic_name, msg->qos, msg->total_len);
    printf("  data=%.*s\n", (int)msg->buffer_len, msg->buffer);
    if (is_done) printf("  [done]\n");
    return MQTT_CODE_SUCCESS;
}

int main(void)
{
    MqttClient  client;
    MqttNet     net = { .connect=net_connect, .read=net_read,
                        .write=net_write,     .disconnect=net_disconnect };
    MqttObject  obj;
    MqttTopic   topic = { .topic_filter=TOPIC, .qos=QOS };
    byte tx[1024], rx[1024];
    int  rc;

    /* 1. Init */
    MqttClient_Init(&client, &net, on_msg, tx, sizeof(tx), rx, sizeof(rx), CMD_TIMEOUT_MS);

    /* 2. TCP connect */
    rc = MqttClient_NetConnect(&client, BROKER_HOST, BROKER_PORT, 5000, 0, NULL);
    if (rc) goto done;

    /* 3. MQTT CONNECT */
    memset(&obj, 0, sizeof(obj));
    obj.connect.clean_session  = 1;
    obj.connect.keep_alive_sec = 60;
    obj.connect.client_id      = CLIENT_ID;
    rc = MqttClient_Connect(&client, &obj.connect);
    if (rc) goto done;

    /* 4. SUBSCRIBE */
    memset(&obj, 0, sizeof(obj));
    obj.subscribe.packet_id   = ++g_packet_id;
    obj.subscribe.topic_count = 1;
    obj.subscribe.topics      = &topic;
    rc = MqttClient_Subscribe(&client, &obj.subscribe);
    if (rc && rc != MQTT_CODE_ERROR_SUBSCRIBE_REJECTED) goto done;

    /* 5. PUBLISH */
    memset(&obj, 0, sizeof(obj));
    obj.publish.qos        = QOS;
    obj.publish.topic_name = TOPIC;
    obj.publish.packet_id  = ++g_packet_id;
    obj.publish.buffer     = (byte*)PUBLISH_MSG;
    obj.publish.total_len  = (word32)strlen(PUBLISH_MSG);
    rc = MqttClient_Publish(&client, &obj.publish);
    if (rc) goto done;

    /* 6. Wait for messages (with keep-alive) */
    for (int i = 0; i < 5; i++) {
        memset(&obj, 0, sizeof(obj));
        rc = MqttClient_WaitMessage_ex(&client, &obj, CMD_TIMEOUT_MS);
        if (rc == MQTT_CODE_ERROR_TIMEOUT) {
            MqttClient_Ping_ex(&client, &obj.ping);
        } else if (rc != MQTT_CODE_SUCCESS) {
            break;
        }
    }

done:
    if (rc && rc != MQTT_CODE_ERROR_TIMEOUT)
        fprintf(stderr, "Error: %s (%d)\n", MqttClient_ReturnCodeToString(rc), rc);
    MqttClient_Disconnect(&client);
    MqttClient_NetDisconnect(&client);
    MqttClient_DeInit(&client);
    return rc == MQTT_CODE_SUCCESS ? 0 : 1;
}

```

--------------------------------

### Example Source Path Resolution

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/main/CMakeLists.txt

Determines the correct path to example source files, checking both GitHub repository structure and standalone component locations. It includes error handling for duplicate source detection.

```cmake
get_filename_component(THIS_PROJECT_DIR ${CMAKE_CURRENT_LIST_DIR} DIRECTORY)
get_filename_component(THIS_PROJECT_PARENT_DIR ${THIS_PROJECT_DIR} NAME)
if("${THIS_PROJECT_PARENT_DIR}" STREQUAL "wolfmqtt_template")
    message(STATUS "For reference only in wolfmqtt_template project, no additional example code is added")
else()
    # All other examples are expected to have some example code available.

    # Set the specific example to look for in core examples:
    set(EXAMPLE_HEADER_FILE "mqttexample.h")

    # We'll first check if we are in the GitHub repo directory structure:
    set(PATH_TO_GITHUB_EXAMPLES "../../../../../../examples/")
    get_filename_component(PATH_TO_GITHUB_EXAMPLES "${PATH_TO_GITHUB_EXAMPLES}" ABSOLUTE)
    message(STATUS "Looking in PATH_TO_GITHUB_EXAMPLES: '${PATH_TO_GITHUB_EXAMPLES}'")

    # Otherwise we'll assume a stand-alone example, such as that from a Managed Component
    # Example: idf.py create-project-from-example "gojimmypi/mywolfmqtt=1.18.0-preview7:AWS_IOT_MQTT"
    get_filename_component(THIS_DIR "${CMAKE_CURRENT_LIST_DIR}" ABSOLUTE)
    message(STATUS "This CMakeLists.txt is located in: '${THIS_DIR}'")

    # Set a path to the example code.
    # Note that PATH_TO_EXAMPLES may be will be set to PATH_TO_GITHUB_EXAMPLES as appropriate.
    set(PATH_TO_EXAMPLES "${THIS_DIR}/examples")
    get_filename_component(PATH_TO_EXAMPLES "${PATH_TO_EXAMPLES}" ABSOLUTE)
    message(STATUS "Looking in PATH_TO_EXAMPLES: '${PATH_TO_EXAMPLES}'")

    # We cannot have source in both, so check that first:
    if (EXISTS "${PATH_TO_GITHUB_EXAMPLES}/${EXAMPLE_HEADER_FILE}" AND EXISTS "${PATH_TO_EXAMPLES}/${EXAMPLE_HEADER_FILE}")
        message(STATUS "ERROR: Found example source in multiple directories:")
        message(STATUS "Directory 1: '${THIS_DIR}'")
        get_filename_component(THIS_DIR "${PATH_TO_EXAMPLES}" ABSOLUTE)
        message(STATUS "Directory 1: '${THIS_DIR}'")
        message(FATAL_ERROR "Unable to resolve source. Please pick one.")
    elseif (EXISTS "${PATH_TO_GITHUB_EXAMPLES}/${EXAMPLE_HEADER_FILE}")
        # GitHub repository structure
        set(PATH_TO_EXAMPLES "${PATH_TO_GITHUB_EXAMPLES}" )
        message(STATUS "Using source from repository path: '${PATH_TO_EXAMPLES}'")
    elseif (EXISTS "${PATH_TO_EXAMPLES}/${EXAMPLE_HEADER_FILE}")
        # Standalone example
        message(STATUS "Using example source in '${PATH_TO_EXAMPLES}'")
    else()
        # Source not found
        set(PATH_TO_EXAMPLES "")
        message(STATUS "ERROR: Could not find example source code.")
    endif()
endif() # Example code check
```

--------------------------------

### Publish Post-Quantum MQTT Message

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Use the mqttclient example to publish a message using TLS 1.3 with post-quantum algorithms. Ensure the broker and subscriber are running.

```bash
./examples/mqttclient/mqttclient -T -h 174.18.0.2 -p 8883 -t -A CA.crt -K publisher.key -c publisher.crt -m "Hello from post-quantum wolfMQTT" -n test/sensor1 -Q SecP384r1MLKEM768
```

--------------------------------

### Build wolfMQTT with MinGW

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Configure and build wolfMQTT using MinGW, ensuring wolfSSL is built and installed first. This includes setting up environment variables for the cross-compilation toolchain and specifying include and library paths.

```bash
export PATH="/opt/mingw-w32-bin_i686-darwin/bin:$PATH"
export PREFIX=$PWD/build

# wolfSSL
cd wolfssl
./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
make
make install

# wolfMQTT
cd ../wolfmqtt
./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
make
```

--------------------------------

### CMake Build for wolfMQTT

Source: https://github.com/wolfssl/wolfmqtt/blob/master/AGENTS.md

Steps to build wolfMQTT using CMake. Supports specifying the wolfSSL installation path or source tree.

```bash
mkdir build && cd build
cmake .. -DWITH_WOLFSSL=/path/to/wolfssl/install/   # Use installed wolfSSL
# OR
cmake .. -DWITH_WOLFSSL_TREE=/path/to/wolfssl/      # Use source tree
cmake --build .
```

--------------------------------

### Build wolfMQTT with CMake

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Use CMake to configure the build process, specifying the location of an installed wolfSSL or a wolfSSL source tree. The build can be configured to disable unit tests.

```bash
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 .
```

--------------------------------

### MqttBroker_Init / MqttBroker_Run — Embedded MQTT broker

Source: https://context7.com/wolfssl/wolfmqtt/llms.txt

Initializes and runs the embedded MQTT broker. MqttBroker_Init initializes the broker, and MqttBroker_Run starts a blocking main loop. For cooperative scheduling, MqttBroker_Start and MqttBroker_Step can be used.

```APIDOC
## MqttBroker_Init / MqttBroker_Run — Embedded MQTT broker

wolfMQTT v2.0 ships a built-in lightweight broker (enabled with `--enable-broker`). Initialize it with `MqttBroker_Init`, configure optional TLS via the `MqttBroker` struct fields, then call `MqttBroker_Run` (blocking) or use `MqttBroker_Start` + `MqttBroker_Step` for cooperative scheduling on embedded RTOS targets. The broker supports MQTT v3.1.1 and v5 clients simultaneously.

### MqttBroker_Init

Initializes the MQTT broker.

### MqttBroker_Run

Starts a blocking main loop for the MQTT broker.

### MqttBroker_Start

Initializes the listening and TLS for the broker, intended for cooperative scheduling.

### MqttBroker_Step

Performs a single non-blocking iteration of the broker's main loop, suitable for cooperative multitasking.

### MqttBroker_Free

Frees resources allocated by the MQTT broker.

### MqttBrokerNet_Init

Initializes the networking backend for the broker.
```

--------------------------------

### Setting WOLFSSL_ROOT in CMakeLists.txt

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/components/wolfssl/CMakeLists.txt

Examples of how to set the WOLFSSL_ROOT variable in your top-level project's CMakeLists.txt file to point to the WolfSSL installation directory. Paths can include spaces and use different drive letters or absolute paths.

```cmake
set(WOLFSSL_ROOT  "C:/some path/with/spaces")
```

```cmake
set(WOLFSSL_ROOT  "c:/workspace/wolfssl-[username]")
```

```cmake
set(WOLFSSL_ROOT  "/mnt/c/some path/with/spaces")
```

--------------------------------

### Build wolfMQTT using Makefile

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/QNX/README.md

Build the wolfMQTT project from the command line using the provided Makefile. Ensure the QNX environment script is sourced before running the build commands.

```bash
source ~/qnx710/qnxsdp-env.sh
cd wolfmqtt/IDE/QNX/wolfmqtt
make
```

--------------------------------

### Create and Build AWS IoT MQTT Project

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/README.md

This script automates the creation of an AWS IoT MQTT project from the Espressif component registry, sets up the ESP-IDF environment, and builds the project. It also includes steps for configuring Wi-Fi credentials and flashing the device.

```bash
#!/bin/bash

WRK_IDF_PATH=/mnt/c/SysGCC/esp32/esp-idf/v5.2

echo "Run export.sh from ${WRK_IDF_PATH}"

pushd ${WRK_IDF_PATH}
. ./export.sh
popd

# Needed for Staging site ONLY:
export IDF_COMPONENT_REGISTRY_URL=https://components-staging.espressif.com

idf.py create-project-from-example "gojimmypi/mywolfmqtt^1.0.14-test:AWS_IoT_MQTT"

cd AWS_IoT_MQTT

# Set your SSID and wifi Password in example configuration
idf.py menuconfig

idf.py -p /dev/ttyS9 -b 921600 flash monitor -b 115200

```

--------------------------------

### Build, Flash, and Monitor ESP-IDF Project

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/README.md

These commands demonstrate how to build, flash, and monitor an ESP-IDF project using idf.py. Ensure your WRK_IDF_PATH is correctly set and the serial port is specified.

```bash
WRK_IDF_PATH=/mnt/c/SysGCC/esp32/esp-idf/v5.1

echo "Run export.sh from ${WRK_IDF_PATH}"
. ${WRK_IDF_PATH}/export.sh

# build the example:
idf.py build

# flash the code onto the serial device at /dev/ttyS19
idf.py flash -p /dev/ttyS19 -b 115200

# build, flash, and view UART output with one command:
idf.py flash -p /dev/ttyS19 -b 115200 monitor

```

--------------------------------

### mqttclient Command Line Options

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Displays the available command-line parameters for the mqttclient utility. Use -? to view this help message. Options may vary based on library configuration.

```bash
./examples/mqttclient/mqttclient -?
mqttclient:
-?          Help, print this usage
-h <host>   Host to connect to, default: test.mosquitto.org
-p <num>    Port to connect on, default: Normal 1883, TLS 8883
-t          Enable TLS
-A <file>   Load CA (validate peer)
-K <key>    Use private key (for TLS mutual auth)
-c <cert>   Use certificate (for TLS mutual auth)
-S <str>    Use Host Name Indication, blank defaults to host
-q <num>    Qos Level 0-2, default: 0
-s          Disable clean session connect flag
-k <num>    Keep alive seconds, default: 60
-i <id>     Client Id, default: WolfMQTTClient
-l          Enable LWT (Last Will and Testament)
-u <str>    Username
-w <str>    Password
-m <str>    Message, default: test
-n <str>    Topic name, default: wolfMQTT/example/testTopic
-r          Set Retain flag on publish message
-C <num>    Command Timeout, default: 30000ms
-P <num>    Max packet size the client will accept, default: 1048576
-T          Test mode
-f <file>   Use file contents for publish

```

--------------------------------

### WOLFMQTT_ROOT Logging

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/wolfmqtt_template/main/CMakeLists.txt

Logs the WOLFMQTT_ROOT variable, which is important for locating wolfMQTT related files and examples within the project structure.

```cmake
message(STATUS "WOLFMQTT_ROOT for examples = ${WOLFMQTT_ROOT}")
```

--------------------------------

### Build and Run Client Test Application

Source: https://github.com/wolfssl/wolfmqtt/blob/master/zephyr/README.md

Build and execute the wolfMQTT client test application within the Zephyr environment. This requires the Zephyr project to be set up.

```bash
cd [zephyrproject]
west build -p auto -b qemu_x86 modules/lib/wolfmqtt/zephyr/samples/client
west build -t run

```

--------------------------------

### Build and Run Client TLS Test Application

Source: https://github.com/wolfssl/wolfmqtt/blob/master/zephyr/README.md

Build and execute the wolfMQTT client test application over TLS. Ensure the wolfSSL Zephyr module is added as a prerequisite.

```bash
cd [zephyrproject]
west build -p auto -b qemu_x86 modules/lib/wolfmqtt/zephyr/samples/client_tls
west build -t run

```

--------------------------------

### Find WolfSSL Directory CMake Function

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/components/wolfssl/CMakeLists.txt

Use this function to locate the WolfSSL installation directory. It searches parent directories for the WOLFSSL_DIRECTORY.

```cmake
# Example usage:
#
# Simply find the WOLFSSL_DIRECTORY by searching parent directories:
#   FIND_WOLFSSL_DIRECTORY(WOLFSSL_ROOT)
#

```

--------------------------------

### Build wolfMQTT Broker with Autotools

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Build the embedded wolfMQTT broker using autotools. The `--enable-broker` flag is required.

```bash
./configure --enable-broker
make
```

--------------------------------

### Run Secure WebSocket Client with Mutual TLS

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Execute the secure WebSocket client example, providing client certificate and key for mutual TLS authentication.

```bash
./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
```

--------------------------------

### Determine Project Directory and Type

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/wolfmqtt_template/main/CMakeLists.txt

Determines the current project directory and its parent directory name. This is used to identify if the current project is the 'wolfmqtt_template' or another example.

```cmake
get_filename_component(THIS_PROJECT_DIR ${CMAKE_CURRENT_LIST_DIR} DIRECTORY)
get_filename_component(THIS_PROJECT_PARENT_DIR ${THIS_PROJECT_DIR} NAME)
```

--------------------------------

### Set Environment Variable for ESP-IDF

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/components/wolfssl/README.md

Set the WRK_IDF_PATH environment variable to your ESP-IDF installation directory before running export.sh. This is necessary for the build system to locate the ESP-IDF.

```shell
# Set environment variable to ESP-IDF location
# For example, VisualGDB in WSL
WRK_IDF_PATH=/mnt/c/SysGCC/esp32/esp-idf/v5.2
WRK_IDF_PATH=/mnt/c/SysGCC/esp32-master/esp-idf/v5.3-master

# Or wherever the ESP-IDF is installed:
WRK_IDF_PATH=~/esp/esp-idf

echo "Run export.sh from ${WRK_IDF_PATH}"
. ${WRK_IDF_PATH}/export.sh

cd [your project]

idf.py menuconfig
```

--------------------------------

### Duplicate Component Detection for Libraries

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/main/CMakeLists.txt

Calls the CHECK_DUPLICATE_LIBRARIES function to check for duplicate installations of wolfSSL and related libraries. This helps in identifying potential conflicts early in the build process.

```cmake
set (git_cmd "git")

message(STATUS "Checking for duplicate components. CMAKE_HOME_DIRECTORY='${CMAKE_HOME_DIRECTORY}'")
CHECK_DUPLICATE_LIBRARIES(DUPE_WOLFSSL_FOUND "wolfssl")
CHECK_DUPLICATE_LIBRARIES(DUPE_WOLFSSL_FOUND "wolfmqtt")
CHECK_DUPLICATE_LIBRARIES(DUPE_WOLFSSL_FOUND "wolfssh")
CHECK_DUPLICATE_LIBRARIES(DUPE_WOLFSSL_FOUND "wolftpm")
```

--------------------------------

### Check for Conflicting wolfSSL Components

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/wolfmqtt_template/CMakeLists.txt

Checks for and warns about conflicting wolfSSL component installations (managed vs. local). It ensures only one version of wolfSSL is used to prevent build errors.

```cmake
message(STATUS "Checking for wolfSSL as Managed Component or not... ${CMAKE_HOME_DIRECTORY}")
message(STATUS "Checking for duplicate components. CMAKE_HOME_DIRECTORY='${CMAKE_HOME_DIRECTORY}'")
CHECK_DUPLICATE_LIBRARIES(DUPE_WOLFSSL_FOUND "wolfssl")
CHECK_DUPLICATE_LIBRARIES(DUPE_WOLFSSL_FOUND "wolfmqtt")
CHECK_DUPLICATE_LIBRARIES(DUPE_WOLFSSL_FOUND "wolfssh")
CHECK_DUPLICATE_LIBRARIES(DUPE_WOLFSSL_FOUND "wolftpm")

if( EXISTS "${CMAKE_HOME_DIRECTORY}/managed_components/wolfssl__wolfssl" AND EXISTS "${CMAKE_HOME_DIRECTORY}/components/wolfssl" )
    # These exclude statements don't seem to be honored by the $ENV{IDF_PATH}/tools/cmake/project.cmake'
    # add_subdirectory("${CMAKE_HOME_DIRECTORY}/managed_components/wolfssl__wolfssl" EXCLUDE_FROM_ALL)
    # add_subdirectory("${CMAKE_HOME_DIRECTORY}/managed_components/wolfssl__wolfssl/include" EXCLUDE_FROM_ALL)
    # So we'll error out and let the user decide how to proceed:
    message(WARNING "\nFound wolfSSL components in\n" 
                    "./managed_components/wolfssl__wolfssl\n"
                    "and\n"
                    "./components/wolfssl\n"
                    "in project directory: \n"
                    "${CMAKE_HOME_DIRECTORY}")
    message(FATAL_ERROR "\nPlease use either the ESP Registry Managed Component or the wolfSSL component directory but not both.\n" 
                        "If removing the ./managed_components/wolfssl__wolfssl directory, remember to also remove " 
                        "or rename the idf_component.yml file typically found in ./main/")
elseif(EXISTS "${CMAKE_HOME_DIRECTORY}/components/wolfssl")
    # A standard project component (not a Managed Component)
    message(STATUS "No conflicting wolfSSL components found.")
    set(WOLFSSL_PATH "${CMAKE_HOME_DIRECTORY}/components/wolfssl")
elseif(EXISTS "${CMAKE_HOME_DIRECTORY}/managed_components/wolfssl__wolfssl")
    # The official Managed Component called wolfssl from the wolfssl user.
    message(STATUS "No conflicting wolfSSL components found as a Managed Component.")
    set(WOLFSSL_PATH "${CMAKE_HOME_DIRECTORY}/managed_components/wolfssl__wolfssl")
elseif(EXISTS "${CMAKE_HOME_DIRECTORY}/managed_components/gojimmypi__mywolfssl")
    # There is a known gojimmypi staging component available for anyone:
    message(STATUS "No conflicting wolfSSL components found as a gojimmypi staging Managed Component.")
elseif(EXISTS "${CMAKE_HOME_DIRECTORY}/managed_components/${THIS_USER}__mywolfssl")
    # Other users with permissions might publish their own mywolfssl staging Managed Component
    message(STATUS "No conflicting wolfSSL components found as a Managed Component.")
    set(WOLFSSL_PATH "${CMAKE_HOME_DIRECTORY}/managed_components/${THIS_USER}__mywolfssl")
else()
    message(STATUS "WARNING: wolfssl component directory not found.")
endif()
```

--------------------------------

### MqttClient Initialization

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Initializes the MQTT client with network settings, message callback, and buffer configurations. This is a blocking call.

```APIDOC
## MqttClient_Init

### Description
Initializes the MQTT client structure with network interface, message callback, transmit/receive buffers, and command timeout.

### Signature
`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);`

### Parameters
- **client** (*MqttClient*): Pointer to the MqttClient structure.
- **net** (*MqttNet*): Pointer to the MqttNet structure for network callbacks.
- **msg_cb** (*MqttMsgCb*): Callback function for handling incoming messages.
- **tx_buf** (*byte*): Pointer to the transmit buffer.
- **tx_buf_len** (int): Size of the transmit buffer.
- **rx_buf** (*byte*): Pointer to the receive buffer.
- **rx_buf_len** (int): Size of the receive buffer.
- **cmd_timeout_ms** (int): Timeout in milliseconds for commands.
```

--------------------------------

### Standard Build Commands for wolfMQTT

Source: https://github.com/wolfssl/wolfmqtt/blob/master/AGENTS.md

Commands for building wolfMQTT on Linux/macOS. Requires autogen.sh if cloned from GitHub, followed by configure and make.

```bash
./autogen.sh          # Required if cloned from GitHub
./configure           # See --help for options
make
sudo make install
```

--------------------------------

### WolfSSL Dual Installation Warning

Source: https://github.com/wolfssl/wolfmqtt/blob/master/IDE/Espressif/ESP-IDF/examples/AWS_IoT_MQTT/main/CMakeLists.txt

Checks if wolfSSL is present in both the local project components directory and the ESP-IDF components directory. If found in both, it sets a warning flag in CMAKE_C_FLAGS to alert the user about the potential conflict.

```cmake
if( EXISTS "${CMAKE_HOME_DIRECTORY}/components/wolfssl/" AND EXISTS "$ENV{IDF_PATH}/components/wolfssl/" )
    #
    # wolfSSL found in both ESP-IDF and local project - needs to be resolved by user
    #
    message(STATUS "")
    message(STATUS "WARNING: Found components/wolfssl in both local project and IDF_PATH")
    message(STATUS "")
    set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -DWOLFSSL_MULTI_INSTALL_WARNING")
endif()
```

--------------------------------

### Build wolfSSL with Post-Quantum Support

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Build wolfSSL with Dilithium and ML-KEM support. Ensure wolfSSL is built before wolfMQTT if post-quantum features are needed.

```bash
./autogen.sh (if obtained from github)
./configure --enable-dilithium --enable-mlkem
make all
make check
```

--------------------------------

### Enable Stress Build Option in wolfMQTT

Source: https://github.com/wolfssl/wolfmqtt/blob/master/README.md

Use the `--enable-stress=[args]` option to simplify testing. This option enables multithreading and nonblocking, and sets defines for TEST_NONBLOCK, NUM_PUB_TASKS, and NUM_PUB_PER_TASK. It also makes the Multithread Example localhost only and disables other tests.

```bash
--enable-stress: stress with default options.
--enable-stress=t7,p8: stress with 7 threads, and 8 publishes per thread.
--enable-stress=t7,p8 --enable-curl: same as above, but with curl backend.
```

--------------------------------

### Initialize MQTT Client and Network Callbacks

Source: https://context7.com/wolfssl/wolfmqtt/llms.txt

Initializes the MqttClient structure with network callbacks and message handling functions. Ensure all platform-specific network functions are correctly implemented and bound before calling MqttClient_Init. This function must be called once before any other client API.

```c
#include "wolfmqtt/mqtt_client.h"

/* Message arrival callback */
static int on_message(MqttClient *client, MqttMessage *msg,
                      byte msg_new, byte msg_done)
{
    (void)client;
    if (msg_new) {
        printf("Topic: %.*s  QoS: %d  Total: %u bytes\n",
               (int)msg->topic_name_len, msg->topic_name,
               msg->qos, msg->total_len);
    }
    printf("  Payload chunk [%u-%u]: %.*s\n",
           msg->buffer_pos, msg->buffer_pos + msg->buffer_len,
           (int)msg->buffer_len, (char*)msg->buffer);
    if (msg_done)
        printf("  [message complete]\n");
    return MQTT_CODE_SUCCESS; /* return non-zero to close connection */
}

/* Network callbacks (BSD sockets example) */
static int net_connect(void *ctx, const char *host, word16 port, int timeout_ms);
static int net_read   (void *ctx, byte *buf, int len, int timeout_ms);
static int net_write  (void *ctx, const byte *buf, int len, int timeout_ms);
static int net_disconnect(void *ctx);

static MqttClient client;
static MqttNet    net;
static byte tx_buf[1024], rx_buf[1024];
static int  sock_fd = -1;

int main(void)
{
    int rc;

    /* Bind platform callbacks */
    memset(&net, 0, sizeof(net));
    net.connect    = net_connect;
    net.read       = net_read;
    net.write      = net_write;
    net.disconnect = net_disconnect;
    net.context    = &sock_fd;

    rc = MqttClient_Init(&client, &net, on_message,
                         tx_buf, sizeof(tx_buf),
                         rx_buf, sizeof(rx_buf),
                         30000 /* cmd timeout ms */);
    if (rc != MQTT_CODE_SUCCESS) {
        fprintf(stderr, "Init failed: %s\n", MqttClient_ReturnCodeToString(rc));
        return 1;
    }
    printf("Client initialized\n");
    /* ... proceed to MqttClient_NetConnect ... */
    return 0;
}
```