Espressif AWS IoT ExpressLink Evaluation and Firmware Repository
APACHE-2.0 License
IMPORTANT: ExpressLink firmware releases can only be flashed on ExpressLink modules and DevKits.
1.0 29-November-2021 Final Draft 1.1 20-June-2022 Revised GSG with extended CONFMODE, steps for Quick Connect demo and better OTA steps
Espressif's AWS IoT ExpressLink (Henceforth referred to as ExpressLink) module is a connectivity module that connects via a serial interface (UART) and uses an abstracted Application Programming Interface (API) to connect any host application to AWS IoT Core and its services. In so doing, the ExpressLink module offloads complex and undifferentiated workload such as authentication, device management, connectivity, and messaging from the application (host) processor. It enables a scalable migration for millions of embedded applications to cloud-connected applications and offers fast time to market. 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.
The OTW upgrade approach requires a smaller number of setup steps and is the preferred method for the first upgrade during evaluation.
Espressif's AWS IoT ExpressLink board (ESP32-C3-AWS-ExpressLink-DevKit) (Henceforth referred to as ExpressLink board) has an Arduino shield form factor, so it can be plugged directly on top of the standard Arduino. It can also 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 | ESP32-C3 GPIO Pin | ESP32-C3-MINI-1-N4-A Module Pin |
---|---|---|
TX | IO19 | 27 |
RX | IO18 | 26 |
EVENT | IO10 | 16 |
WAKE | IO3 | 6 |
RESET | EN | 8 |
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. If sensitive data needs to be transmitted to and from the ExpressLink module, and an unauthorized person can be assumed to gain physical control of the device, we recommend the host processor and the corresponding cloud application to implement a suitable additional end-to-end message encryption scheme
Espressif's AWS IoT ExpressLink board is based on the ESP32-C3-MINI-1-N4-A. The Datasheet can be found here.
You may also need the following items:
Arduino purchase link Raspberry Pi purchase link
Refer to the ESP32-C3 Hardware Reference, for more information on the hardware.
The pins of the ExpressLink board are mapped to the Arduino as follows:
ExpressLink Pin | Arduino Pin |
---|---|
RESET | 4 |
WAKE | 3 |
EVENT | 2 |
RX | 1 |
TX | 0 |
IOREF | IOREF |
GND | GND |
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 |
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 | TX |
TX | RX |
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, CoolTerm 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.
Please note that it is NOT possible to use the ExpressLink board using ONLY the connections shown in step 6a, i.e. it is NOT possible to give the AT commands using the console where you can see the ExpressLink bootup log. You will need to do additional steps as shown in 3.6.2 and 3.6.3 in case of Raspberry Pi and hosts other than Arduino.
Keep the terminal open, as it is needed for subsequent steps.
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:
COM14
, /dev/cu.usbserial-12345
, and so on) in the serial port field.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.
Refer to the instructions at Set up your AWS Account. Follow the steps outlined in these sections 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 ExpressLink module Thing Name and its corresponding certificate. There are two methods to obtain the certificate, as shown in steps 6a and 6b:
-----BEGIN CERTIFICATE-----
line till the -----END CERTIFICATE-----
line and save it to a file named ThingName.cert.pem
{ "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.
The ExpressLink board requires access to a local Wi-Fi router in order to connect to the Internet. You can enter the required security credentials in two ways, as shown in steps 6.1.1 and 6.1.2
Note : When the Wi-Fi on the ExpressLink board is not configured, the board will try to connect to the following SSID: ESP-ExpressLink-Demo and Passphrase: ExpressLink@12345 by default.
Google Play Store link Apple App Store link
Both the apps are open source, and the source code for the apps is available on GitHub.
Android Provisioning App on GitHub iOS/iPadOS Provisioning App on GitHub
Note: By default, the BLE device name is PROV_XXXXXX where XXXXXX are the last 3 bytes of the MAC address of your ExpressLink in hex format and no Proof-of-Possession (PoP).
It is also possible to specify a BLE Device Name and the Proof-of-Possession (PoP) value by using the command AT+CONFMODE <device-name>, <PoP-value>
The <device-name> can be 29 characters long, anything longer would be truncated. It cannot contain a comma. The <PoP-value> length is limited by the maximum AT command length (5000 characters) and leading spaces are ignored.
Additional technical information about the provisioning process can be found here.
Few examples of using CONFMODE:
ExpressLink AT Command BLE Device Name PoP Value AT+CONFMODE PROV_XXXXXX - AT+CONFMODE MyDevice, abcd1234 MyDevice abcd1234 AT+CONFMODE ,abcd1234 PROV_XXXXXX abcd1234 AT+CONFMODE MyDevice MyDevice -
Now, open the Espressif provisioning app on your mobile device that you have installed in the previous step, and click on the "Provision Device" button.
Then click on "I don't have a QR code".
The app will now search for active BLE devices.
When you see your device, click on its name.
If you have specified a PoP, you will need to enter it after selecting the device.
You will now see a list of the 2.4 Ghz Wi-Fi networks that the ExpressLink board can see. Select the Wi-Fi network that you would like to connect to, and enter the credentials.
The credentials will be sent and saved to the device.
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 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.
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 console 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
We have provided a basic sketch in this repository sketches/arduino_sample_sketch.ino to get started quickly, with an Arduino. The sketch will do the following:
Before you flash the provided sketch, change the hardcoded value of the Endpoint in the script the AWS IoT Endpoint that you obtained in Step 6c.
You can flash the sketch onto the Arduino board, using the steps shown here.
Note that the sketch is just a starting point, and is not the only way to use the ExpressLink board with an Arduino.
Arduino's standard RX and TX pins are used to communicate with the ExpressLink board. Hence, standard USB interface of Arduino cannot be used for logging and debugging. You can use any other UART of Arduino for debugging purpose, as described below:
ExpressLink Pin | USB-to-TTL converter Pin | Arduino Pin |
---|---|---|
RX | RX | 8 |
TX | TX | 9 |
GND | GND | GND |
#include <SoftwareSerial.h>
SoftwareSerial mySerial(8, 9); // RX, TX
void setup()
{
mySerial.begin(115200);
while (!mySerial) {
;
}
}
void loop()
{
mySerial.print("Hello World!");
delay(2000);
}
In order to upgrade the ExpressLink board to the latest available firmware, you can follow any one of the approaches shown in Section 9.1 and 9.2
Download the latest release for ExpressLink from the releases section.
Follow the general OTA update prerequisites mentioned here and Prerequisites for OTA updates using MQTT.
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 Sign a new file for me which will display an option to 'Create new profile'.
Follow the steps here to create your own code signing profile.
Ensure that you keep the ecdsasigner.crt
file handy, it will be needed in subsequent steps.
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.
101
to 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. You should see "OK COMPLETE" at the end.
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.
To facilitate situations in which OTA upgrades are difficult to setup or completely not possible due to poor connectivity, we have provided the facility to carry out OTW upgrades.
First, download the latest release for ExpressLink from the releases section.
The file otw.py
needed for carrying out the OTW upgrade is available in this repository in the tools
directory.
pip3 install pyserial==3.5
python3 otw.py (UART serial port) (Firmware binary filename)
Uploaded 100.0% Done...
on the console once it is complete.If you are not able to establish connection over the UART using microUSB port on the ExpressLink board in step 6a, you will need to download the drivers for it and check the additional information for your operating system in the Establish Serial Connection guide.
For common AT command issues, please refer to AWS IoT ExpressLink FAQ page.