Ameba Z2 AWS IoT ExpressLink Evaluation Kit is offers direct access and connections to the AWS Cloud with pre-installed AWS IoT ExpressLink firmware and certificate.
- Document Information
- Overview
- Hardware Description
- Run the Quick Connect demo application
- Setup your AWS account and Permissions for IoT development
- Registering ExpressLink to your development account
- Connecting and Interacting with AWS cloud
- Perform Firmware Over-The-Air Update for AWS IoT ExpressLink
- Troubleshooting
1.0 22-October-2022 Final Draft
AWS IoT ExpressLink is connectivity software that powers a range of hardware modules developed and offered by AWS partners. These modules provide cloud-connectivity and implement AWS-mandated security requirements. Integrating these wireless modules into the hardware design of your device makes it faster and easier to build Internet of Things (IoT) products that connect securely with AWS services.
Realtek's AWS IoT ExpressLink (henceforth referred to as ExpressLink) module is a connectivity module that uses a serial interface (UART) and an abstracted Application Programming Interface (API) to connect any host application processor to AWS IoT Core and its services.
In so doing, the ExpressLink module offloads complex and undifferentiated workloads such as authentication, device management, connectivity, and messaging from the application (host) processor.
More information on AWS IoT ExpressLink can be found here.
The developer documentation can be found here.
Examples for AWS IoT ExpressLink can be found here.
NOTE: Please upgrade your ExpressLink module to the latest available release as shown in Section 9 before proceeding with the Quick Connect demo application from Section 4, or other examples mentioned in this guide.
Realtek's Ameba Z2 AWS IoT ExpressLink board (Henceforth referred to as ExpressLink board) has a pin header, so it can be used with a Raspberry Pi or any other host. It has the following connection pins that need to be made, for full functionality of the board:
| ExpressLink Pin | Ameba-Z2 GPIO Pin |
|---|---|
| TX | PA_14 |
| RX | PA_13 |
| EVENT | PA_20 |
| WAKE | PA_17 |
| RESET | PA_19 |
NOTE: While all the communication between the ExpressLink modules and the AWS cloud is encrypted during transmission (using TLS 1.2 protocol) and at rest, the serial interface (UART) between the host processor and the module is not encrypted.
The Datasheet of Realtek's Ameba Z2 AWS IoT ExpressLink board can be found here.
- One unit of Realtek's Ameba Z2 AWS IoT ExpressLink.
- Raspberry Pi
- Any development host
You may also need the following items:
- MicroUSB cable such as this.
- USB TTL converter such as this one.
- Female to female jumpers such as this.
Refer to the AmebaZ2 Website, for more information on the hardware.
To establish a serial connection between your host machine and the Realtek Ameba Z2, you must install the USB to UART Bridge Virtual Communication Port drivers. You can download these drivers from mbedWinSerial. For more information, see Realtek Ameba-ZII application note.
- To connect the ExpressLink board to the Raspberry Pi, you need to connect the TX, RX, EVENT, WAKE and RESET male pins of the J13 connector on the ExpressLink board to the following GPIO pins of the Raspberry Pi (using female-to-female jumpers):
| ExpressLink Pin | Raspberry Pi GPIO |
|---|---|
| RESET | GPIO 4 |
| WAKE | GPIO 27 |
| EVENT | GPIO 22 |
| RX | GPIO 15 |
| TX | GPIO 14 |
| IOREF | 3V3 Power |
| GND | GND |
- You can now access ExpressLink on your Raspberry Pi, by using a desktop terminal application of your choice and using /dev/ttyS0 with the settings as shown in the table in Section 3.7
The ExpressLink board can be used with any development host, over a USB serial interface (using a USB-to-TTL converter) and using the simple AT commands for controlling ExpressLink.
| ExpressLink Pin | USB-to-TTL converter |
|---|---|
| RX | RX |
| TX | TX |
| GND | GND |
Please note that, in this case, additional functionality like WAKE and EVENT cannot be utilised, but this can serve as a simple way for a quick evaluation and understanding behaviour of commands.
To establish a serial connection between your host machine and ExpressLink, open a desktop terminal application for your host machine (e.g., TeraTerm for Windows, MiniCom for Mac) and select the port corresponding to the evaluation kit. Configure the desktop terminal application as follows:
| Config Option | Value |
|---|---|
| Baudrate | 115200 |
| Bits | 8 |
| Parity | None |
| Stopbit | 1 |
| Flow control | None |
| Local Echo | Yes |
For a quick check, in the terminal window type: AT followed by return. If you receive the answer OK , Congratulations! You have successfully connected the evaluation kit to your host machine.
The Quick Connect demo application allows you to establish a connection with AWS IoT, all in the space of a few minutes; no dependencies to install, no source code to download and build, and no AWS account required.
Note: This demo is designed for ExpressLink boards running ExpressLink firmware v1.X.X and up.
To run the demo, follow the below steps:
- If you opened a terminal application in the previous step, be sure to disconnect that application from the serial port.
- Download the Quick Connect executable:
A. Download for Mac
B. Download for Windows
C. Download for Linux - Unzip the package. You will see a config.txt file. Open this and enter the serial port corresponding to the evaluation kit (for example,
COM5,/dev/ttyS0, and so on) in the serial port field. - Enter your Wi-Fi credentials in the SSID and Passphrase fields.
- Run the "Start_Quick_Connect" executable.
The demo will connect to AWS IoT and give you a URL that you can use to visualize data flowing from the device to the cloud using AT+SEND commands. The demo will run for up to two minutes, and afterwards, you will be able to type AT+SEND commands yourself and see the data coming in on the visualizer.
The following sections will guide you through next steps where you will set up your AWS account and interact with the modules to send and receive data directly with your AWS account.
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:
Pay special attention to the Notes.
To create an IoT Thing and add it to your account we will need to retrieve the AWS IoT ExpressLink module Thing Name and its corresponding certificate. Follow the below steps:
- Open the AWS IoT Console. Select Manage then select Things. Choose Create things , select Create single thing , click Next.
- In the terminal application type the command: AT+CONF? ThingName
- Copy the returned string (a sequence of alphanumeric characters) from terminal. On the Specify thing properties page, paste the copied string from terminal into the Thing name under Thing properties on the console. Leave other fields as default, then click Next
- In the terminal application type the command: AT+CONF? Certificate pem
- Copy the returned string (a longer sequence of alphanumeric symbols), save into a text file on your host machine as "ThingName.cert.pem".
- On the Configure device certificate page , select Use my certificate , choose CA is not registered with AWS IoT.
- Under Certificate , select Choose file. Double click on "ThingName.cert.pem" file in step 5.
- Under Certificate Status , select Active
- Click Next to Attach policies to certificate.
- Under Secure , select Policies.
- Click Create to Create a policy. Put policy name (e.g. IoTDevPolicy) and click Advanced mode.
- Copy the below section into the console.
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "*", "Resource": "*" }] }
NOTE – The examples in this document are intended only for dev environments. All devices in your fleet must have credentials with privileges that authorize only intended actions on specific resources. The specific permission policies can vary for your use case. Identify the permission policies that best meet your business and security requirements. For more information, refer to Example policies and Security Best practices.
Click Save to complete the Thing creation.
- In the AWS IoT Console, choose Settings , copy your account Endpoint string under Device data endpoint.
- In the desktop terminal application type the command: AT+CONF Endpoint=<your-endpoint-string-here>
AWS IoT ExpressLink modules that support Wi-Fi connectivity require access to a local Wi-Fi router in order to connect to the internet. You can enter the required security credentials with the following two additional steps:
- In the desktop terminal application type the command: AT+CONF SSID=<your-router-ssid>
- In the desktop terminal application type the command: AT+CONF Passphrase=<your-router-passphrase>
Note : Your local router's SSID and passphrase are stored securely inside the ExpressLink module. While the SSID can be retrieved later (i.e., for debugging purposes) any attempt to retrieve the Passphrase will return an error.
Congratulations! You have completed the registration of the evaluation kit as a Thing in your IoT account. You will not need to repeat these steps the next time you connect, as the AWS IoT ExpressLink module will remember its configuration and will be ready to connect to your AWS account automatically.
We will use the MQTT client in the AWS IoT console to help us monitor the communication between your evaluation kit and the AWS Cloud.
- Navigate to the AWS IoT console (https://console.aws.amazon.com/iot/).
- To open the MQTT client, in the navigation pane, choose Test and then MQTT Test Client.
- In Subscribe to a topic, enter #, and then click Subscribe.
Establish a secure connection by entering the command: AT+CONNECT
After a short time, you will receive the message OK 1 CONNECTED
Congratulations! You have successfully connected to your AWS cloud account.
To send “Hello World!” message, first enter the command AT+CONF Topic1=data
You will receive the response from the module: OK
Next, enter the command: AT+SEND1 Hello World!
After a short time, you will receive the message OK
You should see the "Hello World!" message appear on the AWS IoT MQTT Test client under the topic "data".
To receive messages, first enter the command: AT+CONF Topic1=MyTopic
You will receive the response from the module: OK
Next, enter the command: AT+SUBSCRIBE1
From the AWS IoT console, MQTT client, select Publish to a topic , type MyTopic in Topic name field, keep "Hello from the AWS IoT console" message then click "Publish".
On your terminal, enter the command: AT+GET1
You will receive the message OK Hello from the AWS IoT console
You should have received a firmware image signed by the manufacturer of the ExpressLink module. Along with the firmware image, you should receive additional signing metadata such as:
- Signature hashing algorithm used (Example: SHA-256)
- Signature encryption algorithm used (Example: ECDSA)
- Actual signature encoded using the base64 encoding format.
- The path name (a string) which identifies the location where the certificate is provisioned in the ExpressLink (optional)
- Create an OTA Update role in your account using the steps outlined here.
- Open AWS IoT Console. Select Manage then select Jobs. Choose Create job , select Create FreeRTOS OTA Update Job , click Next.
- Provide a job name which is unique within your AWS account. Provide an optional description. Click Next.
- From Devices to update dropdown choose the thing name with which the ExpressLink is registered with the account. Select MQTT as the protocol to transfer, and unselect HTTP if selected.
- Choose Use my custom signed file which will display a form to be filled. Use the details from the prerequisites to fill the form.
- In the signature field provide the base64 encoded signature for the image. From the Original hashing algorithm drop down, select the hashing algorithm provided by the manufacturer. From the Original encryption algorithm drop down, select the encryption algorithm provided by the manufacturer. For Path name of code signing certificate on device, fill the box with path name if any provided by the manufacturer. If path name is not provided then you can just enter NA.
- Select Upload a new file , click on Choose file and upload the firmware binary. Choose the S3 bucket in your account that you had created in the prerequisite steps, by selecting Browse S3 option.
- Under Path Name of file on device you can enter NA.
- Under File type drop down set value to
101to signify it's an ExpressLink firmware update as opposed to a host firmware update. - Choose the OTA update role created above from role dropdown under IAM role section. Click Next.
- Click Create Job. On successful creation it should list the job name and state as "in progress".
You need to add the signature obtained previously, to the ExpressLink board so that the firmware can be verified.
Start by giving the command:
AT+CONF OTACertificate=PEM
The module will respond with "OK" and go into "Certificate writing" mode.
You can then paste the contents of the ecdsasigner.crt file in your terminal.
- ExpressLink module polls for firmware update jobs, receives and validates a job, and enters a state waiting for update to be accepted.
- Host application receives an OTA event indicating a new firmware image is available for ExpressLink. Host application can query the state of the job using the command AT+OTA?. You should see the module response OK 1 version to inform a module OTA firmware update was proposed.
- Host application can accept a new firmware update by issuing command AT+OTA ACCEPT.
- ExpressLink should now start downloading the firmware update from cloud. Host can monitor the state of the job using AT+OTA?
- On download completion and successful image signature validation, host receives an event to apply the new image.
- Host application can apply the new image by issuing the command AT+OTA APPLY
- ExpressLink now reboots and boots up with the new image. Host receives a STARTUP event indicating the new image is booted. To see the event, issuing AT+EVENT?. (Notes: the event queue is shown in FIFO order, you may have to issue AT+EVENT? command multiple times, depending on how many events are previously on the queue).
- Host application can connect back to the AWS IoT by issuing AT+CONNECT
- ExpressLink should now connect to AWS IoT, complete the self-test and mark the image as valid preventing any further rollback to old image.
- Going back to the AWS IoT console, job status should be marked as completed and succeeded.
Note: You need to run AT+CONNECT after the OTA update has been applied in order to complete the OTA. Failure to do so during the first bootup of the new firmware, will result in a rollback to the previous firmware.
-
If you are not able to establish connection over the UART using microUSB port on the ExpressLink board in step 6, you will need to download the drivers for it and check the additional information for your operating system in the application note.
-
For Realtek-Ameba-z2 usage issues, please refer AMEBA IoT forum to create your issue.
-
For common AT command issues, please refer to AWS IoT ExpressLink FAQ page.