This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.



This sample application demonstrates the implementation of an MQTT client that can publish messages to AWS IoT Core using the MQTT protocol. Key features include:

  • Acquiring a DHCPv4 lease

  • Connecting to an SNTP server to obtain the current time

  • Establishing a TLS 1.2 connection with AWS IoT Core servers

  • Subscribing to a topic on AWS IoT Core

  • Publishing data to AWS IoT Core

  • Passing the AWS Device Qualification Program (DQP) test suite: Device Qualification Program (DQP)

  • Sending and receiving keep-alive pings

  • Retrying connections using an exponential backoff algorithm


  • An entropy source

  • An AWS account with access to AWS IoT Core

  • AWS credentials and necessary information

  • Network connectivity

Building and Running

This application has been built and tested on the ST NUCLEO-F429ZI board and QEMU x86 target. A valid certificate and private key are required to authenticate to the AWS IoT Core. The sample includes a script to convert the certificate and private key in order to embed them in the application.

Register a thing in AWS IoT Core and download the certificate and private key. Copy these files to the samples/net/cloud/aws_iot_mqtt/src/creds directory. Run the samples/net/cloud/aws_iot_mqtt/src/creds/ script, which will generate files ca.c, cert.c and key.c.

To configure the sample, set the following Kconfig options based on your AWS IoT Core region, thing, and device advisor configuration:

  • CONFIG_AWS_ENDPOINT: The AWS IoT Core broker endpoint, found in the AWS IoT Core console. This will be specific if running a test suite using device advisor.

  • CONFIG_AWS_MQTT_PORT: Port number for AWS IoT Core MQTT broker.

  • CONFIG_AWS_THING_NAME: The name of the thing created in AWS IoT Core. Associated with the certificate it will be used as the client id. We will use zephyr_sample in this example.

  • CONFIG_AWS_SUBSCRIBE_TOPIC: The topic to subscribe to.

  • CONFIG_AWS_PUBLISH_TOPIC: The topic to publish to.

  • CONFIG_AWS_QOS: The QoS level for subscriptions and publications.

  • CONFIG_AWS_EXPONENTIAL_BACKOFF: Enable the exponential backoff algorithm.

Refer to the AWS IoT Core Documentation for more information.

Additionnaly, it is possible to tune the firmware to pass the AWS DQP test suite, to do set Kconfig option CONFIG_AWS_TEST_SUITE_DQP to y.

More information about the AWS device advisor can be found here: AWS IoT Core Device Advisor.

MQTT test client

Access the MQTT test client in the AWS IoT Core console, subscribe to the zephyr_sample/data topic, and publish a payload to the zephyr_sample/downlink topic. The device console will display the payload received by your device, and the AWS console will show the JSON message sent by the device under the zephyr_sample/data topic.

Sample output

This is the output from the ST-Link UART on the NUCLEO-F429ZI board.

*** Booting Zephyr OS build zephyr-v3.3.0 ***
[00:00:01.626,000] <inf> aws: starting DHCPv4
[00:00:01.969,000] <dbg> aws: sntp_sync_time: Acquired time from NTP server: 1683472436
[00:00:01.977,000] <inf> aws: Resolved:
[00:00:03.327,000] <dbg> aws: mqtt_event_cb: MQTT event: CONNACK [0] result: 0
[00:00:03.327,000] <inf> aws: Subscribing to 1 topic(s)
[00:00:03.390,000] <dbg> aws: mqtt_event_cb: MQTT event: SUBACK [7] result: 0
[00:00:03.390,000] <inf> aws: PUBLISHED on topic "zephyr_sample/data" [ id: 1 qos: 0 ], payload: 13 B
[00:00:03.390,000] <dbg> aws: publish_message: Published payload:
                              7b 22 63 6f 75 6e 74 65  72 22 3a 30 7d          |{"counte r":0}
[00:00:11.856,000] <dbg> aws: mqtt_event_cb: MQTT event: PUBLISH [2] result: 0
[00:00:11.856,000] <inf> aws: RECEIVED on topic "zephyr_sample/downlink" [ id: 13 qos: 0 ] payload: 45 / 4096 B
[00:00:11.856,000] <dbg> aws: handle_published_message: Received payload:
                              7b 0a 20 20 22 6d 65 73  73 61 67 65 22 3a 20 22 |{.  "mes sage": "
                              48 65 6c 6c 6f 20 66 72  6f 6d 20 41 57 53 20 49 |Hello fr om AWS I
                              6f 54 20 63 6f 6e 73 6f  6c 65 22 0a 7d          |oT conso le".}
[00:00:11.857,000] <inf> aws: PUBLISHED on topic "zephyr_sample/data" [ id: 2 qos: 0 ], payload: 13 B
[00:00:11.857,000] <dbg> aws: publish_message: Published payload:
                              7b 22 63 6f 75 6e 74 65  72 22 3a 31 7d          |{"counte r":1}
[00:01:11.755,000] <dbg> aws: mqtt_event_cb: MQTT event: 9 result: 0
[00:02:11.755,000] <dbg> aws: mqtt_event_cb: MQTT event: 9 result: 0

Run in QEMU x86

The sample can be run in QEMU x86. To do so, you will need to configure NAT/MASQUERADE on your host machine. Refer to the Zephyr documentation Networking with QEMU. for more information.