<commit_before>.. _mqtt-publisher-sample:

MQTT Publisher
##############

Overview
********

`MQTT <http://mqtt.org/>`_ (MQ Telemetry Transport) is a lightweight
publish/subscribe messaging protocol optimized for small sensors and
mobile devices.

The Zephyr MQTT Publisher sample application is a MQTT v3.1.1
client that sends MQTT PUBLISH messages to a MQTT broker.
See the `MQTT V3.1.1 spec`_ for more information.

.. _MQTT V3.1.1 spec: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html

The source code of this sample application can be found at:
:zephyr_file:`samples/net/mqtt_publisher`.

Requirements
************

- Linux machine
- Freedom Board (FRDM-K64F)
- Mosquitto server: any version that supports MQTT v3.1.1. This sample
  was tested with mosquitto 1.3.4.
- Mosquitto subscriber
- LAN for testing purposes (Ethernet)

Build and Running
*****************

Currently, this sample application only supports static IP addresses.
Open the :file:`src/config.h` file and set the IP addresses according
to the LAN environment.
Alternatively, set the IP addresses in the :file:`prj_frdm_k64f.conf` file.

This file :file:`src/config.h` also contains some variables that may be changed:

MQTT broker TCP port:

.. code-block:: c

	#define SERVER_PORT		1883

Application sleep time:

.. code-block:: c

	#define APP_SLEEP_MSECS		500

Application RX and TX timeout:

.. code-block:: c

	#define APP_TX_RX_TIMEOUT       300

Max number of connection tries:

.. code-block:: c

	#define APP_CONNECT_TRIES	10

Max number of MQTT PUBLISH iterations:

.. code-block:: c

	#define APP_MAX_ITERATIONS	5

MQTT Client Identifier:

.. code-block:: c

	#define MQTT_CLIENTID		"zephyr_publisher"

This sample application supports the IBM Bluemix Watson topic format that can
be enabled by changing the default value of APP_BLUEMIX_TOPIC from 0 to 1:

.. code-block:: c

	#define APP_BLUEMIX_TOPIC	1

The Bluemix topic may include some parameters like device type, device
identifier, event type and message format. This application uses the
following macros to specify those values:

.. code-block:: c

	#define BLUEMIX_DEVTYPE		"sensor"
	#define BLUEMIX_DEVID		"carbon"
	#define BLUEMIX_EVENT		"status"
	#define BLUEMIX_FORMAT		"json"

On your Linux host computer, open a terminal window, locate the source code
of this sample application (i.e. :zephyr_file:`samples/net/mqtt_publisher`) and type:

.. zephyr-app-commands::
   :zephyr-app: samples/net/mqtt_publisher
   :board: frdm_k64f
   :goals: build flash
   :compact:

Open another terminal window and type:

.. code-block:: console

	$ sudo mosquitto -v -p 1883

Open another terminal window and type:

.. code-block:: console

	$ mosquitto_sub -t sensors

TLS offloading
==============

For boards that support this feature, TLS offloading is used by
specifying ``-DOVERLAY_CONFIG=overlay-tls-offload.conf`` when running cmake.

Using this overlay enables TLS without bringing in mbedtls.
<commit_msg>samples: net: mqtt_publisher: Add section on connecting with TLS<commit_after>.. _mqtt-publisher-sample:

MQTT Publisher
##############

Overview
********

`MQTT <http://mqtt.org/>`_ (MQ Telemetry Transport) is a lightweight
publish/subscribe messaging protocol optimized for small sensors and
mobile devices.

The Zephyr MQTT Publisher sample application is a MQTT v3.1.1
client that sends MQTT PUBLISH messages to a MQTT broker.
See the `MQTT V3.1.1 spec`_ for more information.

.. _MQTT V3.1.1 spec: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html

The source code of this sample application can be found at:
:zephyr_file:`samples/net/mqtt_publisher`.

Requirements
************

- Linux machine
- Freedom Board (FRDM-K64F)
- Mosquitto server: any version that supports MQTT v3.1.1. This sample
  was tested with mosquitto 1.3.4.
- Mosquitto subscriber
- LAN for testing purposes (Ethernet)

Build and Running
*****************

Currently, this sample application only supports static IP addresses.
Open the :file:`src/config.h` file and set the IP addresses according
to the LAN environment.
Alternatively, set the IP addresses in the :file:`prj_frdm_k64f.conf` file.

This file :file:`src/config.h` also contains some variables that may be changed:

MQTT broker TCP port:

.. code-block:: c

	#define SERVER_PORT		1883

Application sleep time:

.. code-block:: c

	#define APP_SLEEP_MSECS		500

Application RX and TX timeout:

.. code-block:: c

	#define APP_TX_RX_TIMEOUT       300

Max number of connection tries:

.. code-block:: c

	#define APP_CONNECT_TRIES	10

Max number of MQTT PUBLISH iterations:

.. code-block:: c

	#define APP_MAX_ITERATIONS	5

MQTT Client Identifier:

.. code-block:: c

	#define MQTT_CLIENTID		"zephyr_publisher"

This sample application supports the IBM Bluemix Watson topic format that can
be enabled by changing the default value of APP_BLUEMIX_TOPIC from 0 to 1:

.. code-block:: c

	#define APP_BLUEMIX_TOPIC	1

The Bluemix topic may include some parameters like device type, device
identifier, event type and message format. This application uses the
following macros to specify those values:

.. code-block:: c

	#define BLUEMIX_DEVTYPE		"sensor"
	#define BLUEMIX_DEVID		"carbon"
	#define BLUEMIX_EVENT		"status"
	#define BLUEMIX_FORMAT		"json"

On your Linux host computer, open a terminal window, locate the source code
of this sample application (i.e. :zephyr_file:`samples/net/mqtt_publisher`) and type:

.. zephyr-app-commands::
   :zephyr-app: samples/net/mqtt_publisher
   :board: frdm_k64f
   :goals: build flash
   :compact:

Open another terminal window and type:

.. code-block:: console

	$ sudo mosquitto -v -p 1883

Open another terminal window and type:

.. code-block:: console

	$ mosquitto_sub -t sensors

Connecting securely using TLS
=============================

While it is possible to set up a local secure MQTT server and update the
sample to connect to it, it does require some work on the user's part to
create the certificates and to set them up with the server.

Alternatively, a `publicly available Mosquitto MQTT server/broker
<https://test.mosquitto.org/>`_ is available to quickly and easily
try this sample with TLS enabled, by following these steps:

- Download the server's CA certificate file in DER format from
  https://test.mosquitto.org
- In :file:`src/test_certs.h`, set ``ca_certificate[]`` using the certificate
  contents (or set it to its filename if the socket offloading feature is
  enabled on your platform and :option:`CONFIG_TLS_CREDENTIAL_FILENAMES` is
  set to ``y``).
- In :file:`src/config.h`, set SERVER_ADDR to the IP address to connect to,
  ie. the IP address of test.mosquitto.org ``"192.168.3.11"``
- In :file:`src/main.c`, set TLS_SNI_HOSTNAME to ``"test.mosquitto.org"``
  to match the Common Name (CN) in the downloaded certificate.
- Build the sample by specifying ``-DOVERLAY_CONFIG=overlay-tls.conf``
  when running cmake (or refer to the TLS offloading section below if
  your platform uses the offloading feature).
- Flash the binary onto the device to run the sample:

.. code-block:: console

        $ ninja flash

TLS offloading
==============

For boards that support this feature, TLS offloading is used by
specifying ``-DOVERLAY_CONFIG=overlay-tls-offload.conf`` when running cmake.

Using this overlay enables TLS without bringing in mbedtls.

{'fraction_non_alphanumeric': 0.09930527176134042, 'fraction_numerical': 0.014030785996458248, 'mean_word_length': 4.221906116642959, 'pattern_counts': {'":': 0, '<': 6, '<?xml version=': 0, '>': 6, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4025659', 'n_tokens_mistral': 2484, 'n_tokens_neox': 2319, 'n_words': 888}