Get Started

Note: ESP RainMaker works with all variants of ESP32 like ESP32, ESP32-S2, ESP32-C3 and ESP32-S3. We will just use the name ESP32 to mean all of these, unless explicitly specified otherwise.

Introduction

The ESP RainMaker GitHub project should be used for implementing a "Node" which can then be configured by logged in Users using the clients (like a phone app) and then controlled via the ESP RainMaker Cloud. The examples in this guide are best suited for ESP32-S2-Saola-1, ESP32-C3-DevKitC and ESP32-S3-DevKitC, but the same can be used on other boards by re-configuring Button/LED GPIOs.

rainmaker-intro

High level workflow

Here is a high level workflow for getting started that will be covered in detail in the subsequent sections.

Setup

  • Set up Host environment and ESP IDF as that is the base SDK for ESP RainMaker.
  • Download ESP RainMaker Project which has the core RainMaker firmware functionality, CLI and examples.

Flash

  • Compile and flash Switch example which will serve as the minimalistic starting point.

Wi-Fi Provision and Control

  • Download the Phone app which will be used to pair with the board and control it.
  • Sign Up from the Phone app and login so that you can be uniquely identified by the cloud and can be given secure access to your own devices.
  • Add the switch from the phone app (Wi-Fi provisioning and association with user).
  • Control and monitor the device from the phone app.

Set up Host environment

Setup the Host environment and ESP IDF (master branch) as per the steps given here.

A Visual Studio Code Extension for ESP-IDF and ESP RainMaker is now available. You can check out the information here.

Get the ESP RainMaker Project

Download ESP RainMaker using the following:

$ git clone --recursive https://github.com/espressif/esp-rainmaker.git

This repository has the agent code required for firmware development and the CLI required for testing.

Note the --recursive option. This is required to pull in the JSON dependencies into esp-rainmaker. In case you have already cloned the repository without this option, execute this to pull in the submodules: git submodule update --init --recursive

Build and Flash firmware

It is recommended to first erase the flash if you are using this for the first time and then flash the firmware. Here are the steps:

$ cd /path/to/esp-rainmaker/examples/switch/
$ export ESPPORT=/dev/tty.SLAB_USBtoUART #Set your ESP32's serial port here
$ idf.py set-target esp32 # Set target platform to esp32, esp32s2, esp32c3 or esp32s3
$ idf.py build
$ idf.py erase_flash
$ idf.py flash monitor

When you try this out for the first time, the monitor log will show a print like this:

I (755) esp_claim: Initialising Self Claiming. This may take time.

OR

I (895) esp_claim: Initialising Assisted Claiming. This may take time

This means that your board does not have the credentials to connect to the ESP RainMaker Cloud but will eventually get them from the Claiming service after it connects to the Wi-Fi.

When all the basic initialisations are done, the device will show a QR code on the terminal, which can be used for Wi-Fi provisioning.

QR code not rendering?

It is possible that the QR code may not render properly in your terminal. Something like this:

In that case, check the below lines on your terminal and copy paste the given URL in a browser.

I (1080) app_wifi: If QR code is not visible, copy paste the below URL in a browser.
https://rainmaker.espressif.com/qrcode.html?data={"ver":"v1","name":"PROV_000317","pop":"a1000317","transport":"softap"}

Note: You may have to pull the latest code from GitHub if you do not see this URL. Each board will have own unique QR code. So, use the URL from your serial terminal, not from the above snippet.

Wi-Fi Provisioning and Control

The RainMaker CLI can be used for Wi-Fi provisioning and controlling devices. However, it is recommended to use the RainMaker Phone apps for this purpose. The apps can be found here:

Follow these steps on the Phone apps

  • Sign in using any of the third party options available (or sign up using email address and then sign in).
  • Click on "Add Device" (or if you already have a device added, then the "+" symbol on top right).
  • This will open the camera for QR code scanning.
    • Alternatively, click on the "I don't have a QR code" button. Tap on "Connect" and connect to your ESP32's SoftAP/BLE interface (SoftAP for ESP32-S2, BLE for the rest)
  • Follow the "Provision" workflow so that the ESP32 can connect to your Wi-Fi network.
  • If everything goes well, you should see a "Switch" device added at the end.
  • Tapping on the Switch icon will take you to the Control page.

What to expect in this example?

  • This example uses the BOOT button and RGB LED on the development board to demonstrate a switch. ESP32-S2-Saola-1, ESP32-C3-DevKit and ESP32-S3-DevKit are best suited for this as they have the LED connected to the default configured GPIO.

esp32-s2-saola-1

  • The LED state (green color) indicates the state of the switch.
  • Pressing the BOOT button will toggle the state of the switch and hence the LED. This will also reflect on the phone app.
  • Toggling the button on the phone app should toggle the LED on your board, and also print messages like these on the ESP32's monitor:
I (16073) app_main: Received value = true for Switch - output

LED not working?

The ESP32-S2-Saola-1 board has the RGB LED connected to GPIO 18. However, a few earlier boards may have it on GPIO 17. Please use CONFIG_WS2812_LED_GPIO to set the appropriate GPIO.

$ idf.py menuconfig
    Component config -> WS2812 RGB LED -> WS2812 LED GPIO -> 17

Resetting the board

  • Press and hold the BOOT button for more than 3 seconds to reset the Wi-Fi setting.
  • Press and hold the BOOT button for more than 10 seconds to reset to factory defaults.

You will have to provision the board again to use it.

Set up the CLI (Optional)

The RainMaker CLI offers client functionality (similar to phone apps) integral to the RainMaker solution and can be used for testing and debugging. Please follow the steps here to set up the CLI.

Develop own firmware

Now that the basics are done, let's move onto developing own firmware.

Basics →