AWS MQTT Demo

This demo application connects to AWS MQTT broker using TLS with mutual authentication between the client and the server. It demonstrates the subscribe-publish workflow of MQTT.

Visit coreMQTT Demo (Mutual Authentication) for further information. Please note, that a properly configured thing is required to successfully run the demo application.

Requirements

• AWS Account to create the AWS IoT Thing.
• A CMSIS-Toolbox enabled toolchain such as Keil Studio for VS Code. The MDK Community Edition provides all tools required for evaluation.

Project Structure

This AWS MQTT Mutual Authentication example uses the CMSIS-Toolbox csolution project format with CMSIS software packs and software layers. The default configuration uses a AVH-FVP simulation model. No physical hardware is required to explore this example. By using different layers it can run on physical evaluation boards, use different communication stacks, or WiFi modules.

Project File	Description
Demo.csolution.yml	Specifies the target hardware, build types, and defines the actual software layers used.
Demo.cproject.yml	Contains the source files and components that belong to user application.
Socket/.../Socket.clayer.yml	Contains the source files and components of the communication interface.
Board/.../Board.clayer.yml	Contains the hardware interfaces to the device and board peripherals.
Shield/.../Shield.clayer.yml	Contains the interface source files to an optional Arduino WiFi Shield.

Configure AWS IoT Thing

After creating the AWS IoT Thing, the demo application needs to be configured with the relevant information of the AWS IoT Thing. This is done by updating the placeholder definitions in the configuration file.

• Copy the file FreeRTOS-Plus/Demo/Config/demo_config_template.h to FreeRTOS-Plus/Demo/Config/demo_config.h.
• Modify the following definitions in FreeRTOS-Plus/Demo/Config/demo_config.h:
  • democonfigCLIENT_IDENTIFIER: Thing Name (AWS IoT->Manage->Things->Name in AWS IoT console)
  • democonfigMQTT_BROKER_ENDPOINT: Remote Host Address (AWS IoT->Settings in AWS IoT console)
  • democonfigROOT_CA_PEM: Server's root CA Certificate
  • democonfigCLIENT_CERTIFICATE_PEM: Client Certificate
  • democonfigCLIENT_PRIVATE_KEY_PEM: Client Private Key

Rather than copying the template and modifying the definitions manually, you can provide AWS IoT Thing information through environment variables and run the script configure-aws-iot-thing.js. The script updates the relevant defines based on those environment variables. This approach keeps configuration consistent across local development, CI runs on GitHub runners, and cloud environments such as GitHub Codespaces. Ensure that the relevant environment variables are correctly set and execute the script with:

node ./scripts/configure-aws-iot-thing.js ./FreeRTOS-Plus/Demo/Config/demo_config_template.h ./FreeRTOS-Plus/Demo/Config/demo_config.h

or run the task Configure AWS IoT Thing when using VS Code.

Run on AVH-FVP Simulation Model

Once the AWS IoT Thing is configured it can be built and run on AVH-FVP simulation models.

cbuild Demo.csolution.yml --context .Debug+Simulator --packs
FVP_Corstone_SSE-300 -f Board/AVH_MPS3_Corstone-300/fvp_config.txt out/Demo/Simulator/Debug/Demo.axf -Q 10

The execution on AVH-FVP simulation models should create this output:

[...] ---------STARTING DEMO---------
[...] Creating a TLS connection to xxx-ats.iot.us-east-2.amazonaws.com:8883.
[...] TLS handshake successful.
[...] Connection to xxx-ats.iot.us-east-2.amazonaws.com established.
[...] Creating an MQTT connection to xxx-ats.iot.us-east-2.amazonaws.com.
[...] An MQTT connection is established with xxx-ats.iot.us-east-2.amazonaws.com.
[...] Attempt to subscribe to the MQTT topic thing/example/topic.
[...] SUBSCRIBE sent for topic thing/example/topic to broker.
[...] Subscribed to the topic thing/example/topic with maximum QoS 1.
[...] Publish to the MQTT topic thing/example/topic.
[...] Attempt to receive publish message from broker.
[...] PUBACK received for packet Id 2.
[...] Incoming QoS : 1
[...]
Incoming Publish Topic Name: thing/example/topic matches subscribed topic.
Incoming Publish Message : Hello World!
[...] Keeping Connection Idle...
[...] Publish to the MQTT topic thing/example/topic.
[...] Attempt to receive publish message from broker.
[...] PUBACK received for packet Id 3.
[...] Incoming QoS : 1
[...]
Incoming Publish Topic Name: thing/example/topic matches subscribed topic.
Incoming Publish Message : Hello World!
[...] Keeping Connection Idle...
[...] Publish to the MQTT topic thing/example/topic.
[...] Attempt to receive publish message from broker.
[...] PUBACK received for packet Id 4.
[...] Incoming QoS : 1
[...]
Incoming Publish Topic Name: thing/example/topic matches subscribed topic.
Incoming Publish Message : Hello World!
[...] Keeping Connection Idle...
[...] Unsubscribe from the MQTT topic thing/example/topic.
[...] Unsubscribed from the topic thing/example/topic.
[...] Disconnecting the MQTT connection with xxx-ats.iot.us-east-2.amazonaws.com.
[...] TLS close-notify sent.
[...] prvMQTTDemoTask() completed an iteration successfully. Total free heap is 7440.
[...] Demo completed successfully.
[...] -------DEMO FINISHED-------

The MQTT messages can be viewed in the AWS IoT console.

Development environments

• Command line tools
• Keil Studio for VS Code on a local machine
• Keil Studio for VS Code in GitHub Codespaces

Continuous Integration (CI)

The GitHub Actions in the directory .github/workflows are the scripts for the CI tests. These scripts contain detailed comments about each step that is executed. Ensure that environment variables for the AWS IoT Thing are correctly set via GitHub Secrets.

Configure for Evaluation Boards

The AWS MQTT Demo can be deployed to physical evaluation boards using these steps:

• The pack: MDK-Packs::IoT_Socket is the interface to the communication stack.
• Select a Board that offers suitable board layer. Several Board Support Packs for ST Boards contain a suitable board layer for this MQTT example. The pack overview lists the Provided API Interfaces. The IoT Socket interface requires for Ethernet CMSIS_ETH, for WiFi ARDUINO_UNO_I2C or ARDUINO_UNO_UART.
• The pack: ARM::CMSIS-Driver provides the layers for various WiFi modules. These connect to boards that provide Arduino connectors.

Depending on the selected hardware, the file Demo.csolution.yml is configured. Below the configuration for NUCLEO-F756ZG is shown.

   packs:
    - pack: ARM::V2M_MPS3_SSE_300_BSP@1.5.0
    - pack: Keil::NUCLEO-F756ZG_BSP@2.0.0       # Add BSP
    - pack: ARM::CMSIS-Driver@2.10.0            # Add CMSIS-Driver for WiFi Shields

  target-types:
    - type: Simulator
      board: ARM::V2M-MPS3-SSE-300-FVP
        :

    - type: MyBoard
      board: NUCLEO-F756ZG                      # Add board name

Using Keil Studio for VS Code

Once, the file Demo.csolution.yml is configured, use the Manage Solution view and change the Active Target.

The IDE will evaluate the compatible software layers and shows the Configure Solution view. Depending on the board several options can be selected. Click OK to choose a selection.

This completes the setup and the file Demo.csolution.yml now contains the settings for the layers.

  target-types:
    - type: Simulator
      board: ARM::V2M-MPS3-SSE-300-FVP
        :
    - type: MyBoard
      board: NUCLEO-F756ZG
      variables:
        - Board-Layer: $SolutionDir()$/Board/NUCLEO-F756ZG/Board.clayer.yml
        - Shield-Layer: $SolutionDir()$/Shield/WiFi/Sparkfun_DA16200/Shield.clayer.yml
        - Socket-Layer: $SolutionDir()$/Socket/WiFi/Socket.clayer.yml

Use Build solution to translate the application.

Manual Configuration

Refer to CMSIS-Toolbox - Reference Applications - Usage for use command line tools to obtain above information. However you may also use the CMSIS-Toolbox command csolution list layers to obtain information about the layers that are available in the installed packs. These layers may be copied to your project directory and defined as shown above.

csolution list layers
.../Arm/Packs/ARM/CMSIS-Driver/2.10.0/Shield/WiFi/Inventek_ISMART43362-E/Shield.clayer.yml (layer type: Shield)
.../Arm/Packs/ARM/CMSIS-Driver/2.10.0/Shield/WiFi/Sparkfun_DA16200/Shield.clayer.yml (layer type: Shield)
.../Arm/Packs/ARM/CMSIS-Driver/2.10.0/Shield/WiFi/Sparkfun_ESP8266/Shield.clayer.yml (layer type: Shield)
.../Arm/Packs/ARM/CMSIS-Driver/2.10.0/Shield/WiFi/WizNet_WizFi360-EVB/Shield.clayer.yml (layer type: Shield)
.../Arm/Packs/Keil/NUCLEO-F756ZG_BSP/2.0.0/Layers/Default/Board.clayer.yml (layer type: Board)
.../Arm/Packs/MDK-Packs/IoT_Socket/1.4.0/layer/FreeRTOS_Plus_TCP/Socket.clayer.yml (layer type: Socket)
.../Arm/Packs/MDK-Packs/IoT_Socket/1.4.0/layer/MDK_Network_ETH/Socket.clayer.yml (layer type: Socket)
.../Arm/Packs/MDK-Packs/IoT_Socket/1.4.0/layer/VSocket/Socket.clayer.yml (layer type: Socket)
.../Arm/Packs/MDK-Packs/IoT_Socket/1.4.0/layer/WiFi/Socket.clayer.yml (layer type: Socket)

Use cbuild to translate the application.

cbuild Demo.csolution.yml --context .Debug+MyBoard --packs

Build and Run

Once the application is translated use:

• A programmer or debugger to download the application.
• Run the application and view messages in a debug printf or terminal window.

Issues

Please feel free to raise an issue on GitHub to report problems.