This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new ea161e4fa98 documentation: Document MQTT-C with Mbed TLS usage.
ea161e4fa98 is described below
commit ea161e4fa984837d94e2cee7bd8b04baff6914ac
Author: Arjav Patel <[email protected]>
AuthorDate: Tue Apr 14 05:47:48 2026 +0530
documentation: Document MQTT-C with Mbed TLS usage.
Add Kconfig guidance, mqttc_pub TLS options and default port, the
mqttc_mbedtls_pub example, and cross-links between the mqttc example and
mbedtls overview pages
Signed-off-by: Arjav Patel <[email protected]>
---
.../applications/crypto/mbedtls/index.rst | 8 ++
.../applications/examples/mqttc/index.rst | 16 ++-
.../applications/netutils/mqttc/index.rst | 122 +++++++++++++++++++++
3 files changed, 145 insertions(+), 1 deletion(-)
diff --git a/Documentation/applications/crypto/mbedtls/index.rst
b/Documentation/applications/crypto/mbedtls/index.rst
index 7599ec62665..22f71716a0e 100644
--- a/Documentation/applications/crypto/mbedtls/index.rst
+++ b/Documentation/applications/crypto/mbedtls/index.rst
@@ -1,3 +1,11 @@
=========================================
``mbedtls`` Mbed TLS Cryptography Library
=========================================
+
+NuttX can build the Mbed TLS cryptography library from ``nuttx-apps`` (under
+``apps/crypto/mbedtls``). Enable ``CONFIG_CRYPTO_MBEDTLS`` in ``menuconfig``
and
+select application options as needed.
+
+Mbed TLS is commonly used for TLS clients and servers on NuttX. For MQTT over
TLS
+with the MQTT-C integration, enable ``CONFIG_CRYPTO_MBEDTLS`` and
+``CONFIG_NETUTILS_MQTTC_WITH_MBEDTLS``; see :doc:`../../netutils/mqttc/index`.
diff --git a/Documentation/applications/examples/mqttc/index.rst
b/Documentation/applications/examples/mqttc/index.rst
index aa6eeea327e..b9e06a0fe49 100644
--- a/Documentation/applications/examples/mqttc/index.rst
+++ b/Documentation/applications/examples/mqttc/index.rst
@@ -2,12 +2,15 @@
``mqttc`` MQTT-C Example
========================
-This is a simple MQTT publisher example using MQTT-C
+This is a simple MQTT publisher example using MQTT-C.
By default it publishes to the "test" topic and exits. Default behaviour
including, host, port, topic, message and loop count can be changed through
different arguments.
+Plain TCP (no Mbed TLS)
+=======================
+
To test:
From the host start an MQTT broker and subscribe to the "test" topic. Here
mosquitto is used::
@@ -24,3 +27,14 @@ Launch the built-in app ``mqttc_pub`` specifying the host::
mqttc_pub -h HOST
The target will publish the message "test".
+
+TLS with Mbed TLS
+=================
+
+To use TLS, enable Mbed TLS and MQTT-C with Mbed TLS in ``menuconfig`` (see
+:doc:`../../netutils/mqttc/index`). The same ``mqttc_pub`` binary is built with
+TLS support; the default port becomes **8883**. You can pass ``-c`` with a path
+to your broker CA certificate in PEM format.
+
+For full configuration symbols, CLI options, and the separate
+``mqttc_mbedtls_pub`` example, see :doc:`../../netutils/mqttc/index`.
diff --git a/Documentation/applications/netutils/mqttc/index.rst
b/Documentation/applications/netutils/mqttc/index.rst
index 94f71ab13b4..5699474af48 100644
--- a/Documentation/applications/netutils/mqttc/index.rst
+++ b/Documentation/applications/netutils/mqttc/index.rst
@@ -1,3 +1,125 @@
========================
``mqttc`` MQTT-C library
========================
+
+Overview
+========
+
+The `MQTT-C <https://github.com/LiamBindle/MQTT-C>`_ client library is
integrated
+into NuttX through ``nuttx-apps`` (``apps/netutils/mqttc``). It provides an
MQTT
+v3.1.1 client with a small platform abstraction layer.
+
+You can use MQTT-C over plain TCP or, when enabled, over TLS using Mbed TLS.
The
+TLS path defines ``MQTT_USE_MBEDTLS`` for code that includes the library and
the
+``examples/mqttc`` publisher application.
+
+Prerequisites
+=============
+
+- A NuttX tree and a matching ``nuttx-apps`` checkout (see the top-level
+ ``README`` in each repository).
+- A working network stack and route to your MQTT broker (Ethernet, Wi-Fi, or
+ other), unless you only run loopback tests on the host.
+- For TLS with certificate verification, ensure the device has a valid clock
+ (RTC or NTP) before connecting; otherwise verification of ``notBefore`` /
+ ``notAfter`` may fail.
+
+Configuration
+=============
+
+Enable the MQTT-C package and optional pieces from ``menuconfig``:
+
+**Library and TLS**
+
+- ``CONFIG_NETUTILS_MQTTC``: Build the MQTT-C static library.
+- ``CONFIG_CRYPTO_MBEDTLS``: Build Mbed TLS (required for the TLS integration).
+- ``CONFIG_NETUTILS_MQTTC_WITH_MBEDTLS``: Compile MQTT-C and dependent apps
with
+ ``MQTT_USE_MBEDTLS``. This option depends on ``CRYPTO_MBEDTLS`` and selects
+ ``DEV_URANDOM`` for entropy.
+- ``CONFIG_NETUTILS_MQTTC_VERSION``: Upstream MQTT-C version string (default is
+ ``1.1.5``).
+
+**Example: ``mqttc_pub`` (``apps/examples/mqttc``)**
+
+- ``CONFIG_EXAMPLES_MQTTC``: Build the NSH publisher example. Program name is
+ ``CONFIG_EXAMPLES_MQTTC_PROGNAME`` (default ``mqttc_pub``). Requires
+ ``NETUTILS_MQTTC``.
+- ``CONFIG_EXAMPLES_MQTTC_ALLOW_UNVERIFIED_TLS``: If TLS verification fails,
+ continue anyway. Intended for development with self-signed brokers; do not
+ rely on this for production.
+
+**Bundled upstream examples (``apps/netutils/mqttc``)**
+
+- ``CONFIG_NETUTILS_MQTTC_EXAMPLE``: Build extra sample programs from the
+ MQTT-C tree. With Mbed TLS enabled this produces ``mqttc_mbedtls_pub``;
+ otherwise ``mqttc_posix_pub`` and ``mqttc_posix_sub``.
+- ``CONFIG_NETUTILS_MQTTC_TEST``: CMocka-based tests. This option is not
+ available when ``CONFIG_NETUTILS_MQTTC_WITH_MBEDTLS`` is enabled.
+
+A minimal ``kconfig`` fragment for TLS-enabled ``mqttc_pub`` might look like:
+
+.. code-block:: kconfig
+
+ CONFIG_CRYPTO_MBEDTLS=y
+ CONFIG_NETUTILS_MQTTC=y
+ CONFIG_NETUTILS_MQTTC_WITH_MBEDTLS=y
+ CONFIG_EXAMPLES_MQTTC=y
+
+Using ``mqttc_pub`` with Mbed TLS
+=================================
+
+When ``CONFIG_NETUTILS_MQTTC_WITH_MBEDTLS`` is set, ``mqttc_pub`` uses Mbed TLS
+for the broker connection. The default broker port is **8883** (TLS). Typical
+arguments:
+
+.. code-block:: text
+
+ mqttc_pub -h BROKER [-p PORT] [-c CAFILE] [-t TOPIC] [-m MESSAGE] [-n
COUNT] [-q QOS]
+
+- ``-h``: Broker hostname or address (required for non-default use).
+- ``-p``: Port (default ``8883`` in TLS mode).
+- ``-c``: Path to a PEM file containing the broker CA certificate (or chain).
+ If omitted, the example uses an embedded test CA (PolarSSL/Mbed TLS test
+ material), which is only appropriate for matching test servers—not for
+ arbitrary production brokers.
+- ``-t``, ``-m``, ``-n``, ``-q``: Topic, payload, publish repeat count, and
QoS.
+
+Example (NSH, after the network is up):
+
+.. code-block:: text
+
+ nsh> mqttc_pub -h mqtt.example.com -p 8883 -c /etc/ssl/certs/broker-ca.pem
+
+If verification fails and you must use a self-signed broker during bring-up,
+enable ``CONFIG_EXAMPLES_MQTTC_ALLOW_UNVERIFIED_TLS`` or fix the CA/time on the
+device.
+
+Using ``mqttc_mbedtls_pub``
+===========================
+
+When ``CONFIG_NETUTILS_MQTTC_EXAMPLE`` and
+``CONFIG_NETUTILS_MQTTC_WITH_MBEDTLS`` are set, the ``mqttc_mbedtls_pub``
+program is built from the upstream ``examples/mbedtls_publisher.c``. It expects
+positional arguments:
+
+.. code-block:: text
+
+ mqttc_mbedtls_pub CAFILE [ADDRESS [PORT [TOPIC]]]
+
+Defaults are similar to the upstream sample (e.g. public test broker and port
+``8883`` if not overridden). Use a CA file that matches your broker.
+
+Build systems (Make and CMake)
+==============================
+
+Make-based and CMake-based NuttX builds both support these options. For CMake,
+ensure Mbed TLS and MQTT-C targets resolve includes and dependencies; recent
+``nuttx-apps`` changes wire ``mqttc`` to ``mbedtls`` when both TLS options are
+enabled.
+
+See also
+========
+
+- :doc:`../../examples/mqttc/index` — Quick test steps for ``mqttc_pub``.
+- :doc:`../../crypto/mbedtls/index` — Mbed TLS package overview.
+- :doc:`../paho_mqtt/index` — Eclipse Paho MQTT C client (alternative stack).
