Connect to AWS IoT Core with Avnet's MaaXBoard 8M SBC

INTRO

This project will help the user create an AWS IoT Core Thing, and then configure the aws-iot-device-client application to connect to the new Thing. Amazon provides a working c++ example application called aws-iot-device-client that we'll leverage for the exercise.

The aws-iot-device-client application is an open-source project that demonstrates AWS best practices for developing device client applications. In this project we'll use a pre-built aws-iot-device-client application to send and receive MQTT data to/from AWS.

PREREQUISITES

• MaaXBoard 8M board
• 5V/3A USB-C Power Supply
• 16GB (or larger) Micro SD Card
• USB Keyboard
• HDMI Monitor
• HDMI Cable
• Ethernet Cable
• Windows Environment: The blog references windows tools, however experienced Linux users will be able to follow along.
• AWS account

SETUP

The setup consists of...

• Logging into your AWS account
• Creating a new AWS IoT Core Thing
• Downloading the Certificates and Keys associated with the new Thing
• Flashing a new image onto the MaaXBoard 8M board
• Copying the certificates and keys onto the MaaXBoard 8M board
• Updating the configuration file to identify details of your Thing

SETUP YOUR AWS ACCOUNT AND PERMISSIONS

If you already have an AWS account, please review the steps below to make sure you've got everything setup correctly

Refer to the online AWS documentation at Set up your AWS Account. Follow the steps outlined in the sections below to create your account and a user and get started:

• Sign up for an AWS account
• Create a user and grant permissions

CREATING A NEW THING

Login to your AWS account console

• Open the AWS IoT console by selecting IoT Core

• Select Manage --> All devices --> Things
• Select the "Create things" link

• Select "Create a single thing" then Next

• Name your thing and click Next

• Auto generate thing certificates

• Create a policy for the new thing
• Note the policy below does NOT follow AWS best practices

• Create a policy similar to the one shown below
• Click the Create link

• Navigate back to the Create single thing web page; my new policy form opened in a separate tab in my browser.
• Select the new policy just created
• Select the Create thing link

• The Download certificates and keys dialog opens
• Download all the items identified below
• Click on the Done link

• I like to rename the device certificate and the keys to match my thing's name

FLASH THE AWS IMAGE ONTO THE MAAXBOARD 8M

• Download the file package from here
• Unzip the contents into an empty directory
• Using an application like Balena Etcher flash the avet-lite-image-maaxboard-8m-aws.wic file onto your MaaXBoard 8M SD card. The *.wic file is included in the file package.

• Insert the SD card into your MaaXBoard 8M
• Connect the board to your network with an ethernet cable
• Apply power to the board using the USB-C connector on the board

CHECKPOINT

At this point in the exercise, we have...

• Created a new AWS IoT Core Thing
• Flashed our MaaXBoard 8M device with an image that contains the aws-iot-device-client application

Next we'll move the thing certificates and keys to the MaaXBoard and update the aws-iot-device-client configuration

MOVE CERTIFICATES TO THE MAAXBOARD 8M

• Determine the IP Address of the board by connecting a HDMI monitor and USB keyboard to the MaaXBoard, open a terminal and use the ifconfig command to see the IP address.
• Open a Windows PowerShell window
• ssh into the MaaXBoard with > ssh root@maaxboard
• Enter "avnet" for the password
• On the MaaXBoard create a new directory called aws and another called aws/certs

• Using a tool such as WinSCP, copy the certificates and keys to the ~/aws/certs directory

• Copy the myConfig.json and publish.json files from the download package to the ~/aws directory

• Change the file permissions
• > chmod 600 certs/*-private.pem.key

UPDATE THE CONFIGURATION FILE

• Open the myConfig.json file to edit: > nano myConfig.json
• If using winSCP you can also edit remote files from the WinSCP interface by double clicking on the file to edit
• Edit the file to include...

cert, key, root-ca: entries should be updated to reference your path and certificate file names

thing-name: Update to match the thing name we created earlier in the AWS console

publish-file: Update to match the path and filename of a Json document containing JSON to publish on the "publish-topic"

endpoint: Can be found in the AWS IoT Console under Settings

• Exit and save your changes

• Review the contents of the publish.json file

• In the SSH window, update the permissions on the new publish file using the command
• > chmod 600 publish.json

CHECK POINT

We're ready to connect the MaaXBoard to AWS!

Exercise the aws-iot-device-client

• Run the application using our new configuration...
• > aws-iot-device-client --config-file myConfig.json

At this point you may see some errors. Most likely there are file permission errors. Examine the output to see which files need to be updated. The debug will output what the expected permissions should be set to.

For example the output below indicates that the certs/MaaXBoard8M-certificate.pem.crt file has incorrect permissions. It tells the user that the desired permissions are "644" but the actual permissions are set to "700."

To correct this error, in the ssh window update the permissions with the chmod command.

A successful startup looks similar to the graphic below.

• Go back to the AWS console
• Select Test --> MQTT test client
• Subscribe to the topic "myTopic"
• Kill the aws-iot-device-client and restart it by entering a ctrl-c key sequence in the ssh window. When the application connects to AWS it sends a MQTT message with the content from your publish.json file
• Observe the incoming MQTT message from the MaaXBoard
• Now in the MQTT test client publish to a topic
• For topic name enter "myTopic"
• For the message payload enter DC-Publish
• Hit the Publish button

• Note in the debug windows you see that a message was received, and another message was sent. The aws-iot-device-client will resend the MQTT publish data when it receives the DC-Publish text!

CONCLUSION

In this project the user learned how to...

• Create a new AWS IoT Thing
• Flash the MaaXBoard 8ULP board with a new image
• Configure the aws-iot-device-client to connect to AWS to receive and send MQTT data
• Verified that MQTT data is sent between our thing and AWS

The aws-iot-device-client application supports other features that we're not exercising. Feel free to review the aws-iot-device-client on-line documentation and exercise other features on the MaaXBoard 8ULP.

If you run into any issues reproducing this exercise, please post your issue here and I'll do my best to help.

Please post any questions or comments below and thank you for your time!

Brian