1.. zephyr:code-sample:: aws-iot-mqtt
2   :name: AWS IoT Core MQTT
3   :relevant-api: bsd_sockets mqtt_socket dns_resolve tls_credentials json sntp random_api
4
5   Connect to AWS IoT Core and publish messages using MQTT.
6
7Overview
8********
9
10This sample application demonstrates the implementation of an MQTT client that
11can publish messages to AWS IoT Core using the MQTT protocol. Key features include:
12
13- Acquiring a DHCPv4 lease
14- Connecting to an SNTP server to obtain the current time
15- Establishing a TLS 1.2 connection with AWS IoT Core servers
16- Subscribing to a topic on AWS IoT Core
17- Publishing data to AWS IoT Core
18- Passing the AWS Device Qualification Program (DQP) test suite: `Device Qualification Program (DQP) <https://aws.amazon.com/partners/programs/dqp/>`_
19- Sending and receiving keep-alive pings
20- Retrying connections using an exponential backoff algorithm
21
22Requirements
23************
24
25- An entropy source
26- An AWS account with access to AWS IoT Core
27- AWS credentials and necessary information
28- Network connectivity
29
30Building and Running
31********************
32
33This application has been built and tested on the ST NUCLEO-F429ZI board and
34QEMU x86 target. A valid certificate and private key are required to
35authenticate to the AWS IoT Core. The sample includes a script to convert
36the certificate and private key in order to embed them in the application.
37
38Register a *thing* in AWS IoT Core and download the certificate and private key.
39Copy these files to the :zephyr_file:`samples/net/cloud/aws_iot_mqtt/src/creds`
40directory. Run the :zephyr_file:`samples/net/cloud/aws_iot_mqtt/src/creds/convert_keys.py`
41script, which will generate files ``ca.c``, ``cert.c`` and ``key.c``.
42
43To configure the sample, set the following Kconfig options based on your AWS IoT
44Core region, thing, and device advisor configuration:
45
46- :kconfig:option:`CONFIG_AWS_ENDPOINT`: The AWS IoT Core broker endpoint, found in the AWS IoT Core
47  console. This will be specific if running a test suite using device advisor.
48- :kconfig:option:`CONFIG_AWS_MQTT_PORT`: Port number for AWS IoT Core MQTT broker.
49- :kconfig:option:`CONFIG_AWS_THING_NAME`: The name of the thing created in AWS IoT Core. Associated
50  with the certificate it will be used as the client id. We will use
51  ``zephyr_sample`` in this example.
52- :kconfig:option:`CONFIG_AWS_SUBSCRIBE_TOPIC`: The topic to subscribe to.
53- :kconfig:option:`CONFIG_AWS_PUBLISH_TOPIC`: The topic to publish to.
54- :kconfig:option:`CONFIG_AWS_QOS`: The QoS level for subscriptions and publications.
55- :kconfig:option:`CONFIG_AWS_EXPONENTIAL_BACKOFF`: Enable the exponential backoff algorithm.
56
57Refer to the `AWS IoT Core Documentation <https://docs.aws.amazon.com/iot/index.html>`_
58for more information.
59
60Additionnaly, it is possible to tune the firmware to pass the AWS DQP test
61suite, to do set Kconfig option :kconfig:option:`CONFIG_AWS_TEST_SUITE_DQP` to ``y``.
62
63More information about the AWS device advisor can be found here:
64`AWS IoT Core Device Advisor <https://aws.amazon.com/iot-core/device-advisor/>`_.
65
66MQTT test client
67================
68
69Access the MQTT test client in the AWS IoT Core console, subscribe to the
70``zephyr_sample/data`` topic, and publish a payload to the ``zephyr_sample/downlink``
71topic. The device console will display the payload received by your device, and
72the AWS console will show the JSON message sent by the device under the
73``zephyr_sample/data`` topic.
74
75Sample output
76=============
77
78This is the output from the ST-Link UART on the NUCLEO-F429ZI board.
79
80.. code-block:: console
81
82  *** Booting Zephyr OS build zephyr-v3.3.0 ***
83  [00:00:01.626,000] <inf> aws: starting DHCPv4
84  [00:00:01.969,000] <dbg> aws: sntp_sync_time: Acquired time from NTP server: 1683472436
85  [00:00:01.977,000] <inf> aws: Resolved: 52.212.60.110:8883
86  [00:00:03.327,000] <dbg> aws: mqtt_event_cb: MQTT event: CONNACK [0] result: 0
87  [00:00:03.327,000] <inf> aws: Subscribing to 1 topic(s)
88  [00:00:03.390,000] <dbg> aws: mqtt_event_cb: MQTT event: SUBACK [7] result: 0
89  [00:00:03.390,000] <inf> aws: PUBLISHED on topic "zephyr_sample/data" [ id: 1 qos: 0 ], payload: 13 B
90  [00:00:03.390,000] <dbg> aws: publish_message: Published payload:
91                                7b 22 63 6f 75 6e 74 65  72 22 3a 30 7d          |{"counte r":0}
92  [00:00:11.856,000] <dbg> aws: mqtt_event_cb: MQTT event: PUBLISH [2] result: 0
93  [00:00:11.856,000] <inf> aws: RECEIVED on topic "zephyr_sample/downlink" [ id: 13 qos: 0 ] payload: 45 / 4096 B
94  [00:00:11.856,000] <dbg> aws: handle_published_message: Received payload:
95                                7b 0a 20 20 22 6d 65 73  73 61 67 65 22 3a 20 22 |{.  "mes sage": "
96                                48 65 6c 6c 6f 20 66 72  6f 6d 20 41 57 53 20 49 |Hello fr om AWS I
97                                6f 54 20 63 6f 6e 73 6f  6c 65 22 0a 7d          |oT conso le".}
98  [00:00:11.857,000] <inf> aws: PUBLISHED on topic "zephyr_sample/data" [ id: 2 qos: 0 ], payload: 13 B
99  [00:00:11.857,000] <dbg> aws: publish_message: Published payload:
100                                7b 22 63 6f 75 6e 74 65  72 22 3a 31 7d          |{"counte r":1}
101  [00:01:11.755,000] <dbg> aws: mqtt_event_cb: MQTT event: 9 result: 0
102  [00:02:11.755,000] <dbg> aws: mqtt_event_cb: MQTT event: 9 result: 0
103
104Run in QEMU x86
105===============
106
107The sample can be run in QEMU x86. To do so, you will need to configure
108NAT/MASQUERADE on your host machine. Refer to the Zephyr documentation
109:ref:`networking_with_qemu`. for more information.
110