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 <arjav1528@gmail.com>

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

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

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).