We’re ready to compile and flash our application on to the device, provision the Wi-Fi through the ESP Rainmaker Phone App, register a user to assign the device to, and begin controlling our peripherals over AWS IoT.
There are several folders at the root of the project you cloned or downloaded and extracted. For this tutorial, we will open the Getting-Started project in PlatformIO. First open Visual Studio Code and after waiting a few seconds for the PlatformIO extension to load, click the PlatformIO logo on the left bar, select Open from the left PlatformIO menu, click Open Project, navigate to the
Core2-for-AWS-IoT-EduKit/Getting-Started folder, and click open.
You need to know which port you’ll use for communications with the device for uploading firmware or monitoring the serial output. For macOS, the device is typically on /dev/cu.SLAB_USBtoUART or starts with /dev/cu.usbserial- and the included configuration should not require any changes. Linux is typically /dev/ttyUSB0 and requires the user be added to the dialout group. For Windows, you’ll need to replace the value with COM and end with the corresponding port number (e.g. COM3). For more specific Windows instructions or Linux distros that require additional configuration, please reference Espressif’s offical doc for establishing serial connections with the ESP32.
Choose the Visual Studio Code file explorer ( on the left bar), open the platformio.ini file, and change your upload_port value to match the serial port the device is connected to.
View the official PlatformIO docs about the upload_port option to see formatting and other examples.
You are now ready to build and flash your firmware. Start by clicking the PlatformIO logo on the left bar. Then click the icon (hover your mouse next to PROJECT TASKS) to refresh the available options. You’ll click the Build button to start building the device firmware. This will take a few minutes depending on your computer. Once that is complete, click Upload and Monitor option from the PlatformIO project tasks menu. Once the upload has completed successfully, the device will boot with the firmware that was just compiled and uploaded. It will also begin display the serial output from the device in that terminal viewport (now the serial monitor window). The device will be going through the process of generating security keys and performing a self claim. Key generation can take a few seconds, up to a few minutes to complete but once claiming completes a QR code will display on the serial monitor window.
For additional troubleshooting or FAQs, visit the official Espressif RainMaker FAQs.
On your mobile phone, open the ESP RainMaker Phone App, grant the requested mobile app permissions, press Add Device, and then scan the QR code displayed on your computer’s serial monitor (not the QR code on the device). It will then go through the provisioning process, which includes Wi-Fi provisioning with your Wi-Fi credentials for your 2.4GHz wireless home network. After a successful Wi-Fi connection, the device will authenticate itself and your phone app will populate with multiple virtual devices that can be viewed and/or controlled. If the virtual devices are marked offline on the phone app after a minute or two, try scrolling down to refresh.
With the virtual device listed and online in your mobile app, you can turn the on-board motor or LEDs on or off, adjust the speed of the motor, set the color and brightness of the LED bars, and view the internal device temperature.
If you entered the wrong Wi-Fi credentials, you’ll need to erase the firmware first, re-upload the Espressif RainMaker Agent firmware to the device, and add the device with your mobile phone again.
Once you are done with this application and ready to move on to other tutorials, you’ll need to first wipe the device firmware. However, you’ll need to stop the active serial monitor first since it’s blocking other communication to the port. You can stop the serial monitor by selecting the Visual Studio Code pane with the serial monitor running and pressing CTRL + C. Then to erase the flash memory, enter the PlatformIO menu, expand the Platform menu list, and then click the Erase Flash option. This will remove all the data on the device, including the RainMaker certificates that were used.
Powercycling the device with a empty flash will result in the device screen being blank and a audible ticking sound from the speaker. This is expected behavior as the device is continually rebooting itself without an application to run.
You’ve just built a connected home application through the AWS IoT EduKit program! Not only that, but you have the tools necessary to create, edit, compile, and flash embedded code on to your device! In the next tutorials, you’ll get more hands-on and learn the skills to start building your own end-to-end IoT solutions.
On to Blinky Hello World.