Communication between Client and Cloud Backend

ESP RainMaker offers two client tools: app and CLI, both of which are implemented using the RESTful API. This section briefly explains how to use the CLI tool that comes with the device SDK to communicate with the cloud backend.

The CLI tool is a Python-based submodule of the esp-rainmaker repository, under the esp-rainmaker/cli directory. To use it, please refer to Chapter 4 to set up the ESP-IDF environment and export the ESP-IDF environment variables. You can verify whether the ESP-IDF and Python environments are ready by running the following commands:

# Print ESP-IDF version
$ idf.py --version
ESP-IDF v4.3.2

# Print Python version
$ python3 --version
Python 3.6.9

A similar Shell output to the above indicates that the ESP-IDF environment is ready. Note that the CLI tool depends on Python 3.x, and the older versions need upgrading.

After the ESP-IDF environment is ready, use pip to install the Python dependencies of the CLI tool with the following commands:

$ cd your RainMaker path/esp-rainmaker/cli
$ pip install -r requirements.txt
Collecting argparse
    Using cached argparse-1.4.0-py2.py3-none-any.whl (23 kB)
...
...
...
Installing collected packages: cryptography, argparse
    Attempting uninstall: cryptography
    Found existing installation: cryptography 2.9.2
    Uninstalling cryptography-2.9.2:
        Successfully uninstalled cryptography-2.9.2
Successfully installed argparse-1.4.0 cryptography-2.4.2
WARNING: You are using pip version 21.1.2; however, version 21.3.1 is available.

Once the environment is set up, you can use the CLI tool to communicate with the cloud backend. All the commands supported by the CLI are listed in Table 9.4, and you can view the usage of each command by running python3 rainmaker.py –h. Additionally, you can use the parameter -h together with each command to view more help information.

Table 9.4. CLI commands

CommandDescription
signupSign up for ESP RainMaker
loginLogin to ESP RainMaker
logoutLogout current (logged-in) user
forgotpasswordReset the password
getnodesList all nodes associated with the user
getnodeconfigGet node configuration
getnodestatusGet online/offline status of the node
setparamsSet node parameters
getparamsGet the last parameter of the node in the cloud
removenodeRemove user node mapping
provisionProvision the node to join Wi-Fi network
getmqtthostGet the address of the MQTT host that the node connects to
claimPerform host driven claimming to the node and get the MQTT cerficate
testTest whether the node has been mapped to the user
otaupgradeDistribute OTA upgrade information
getuserinfoGet detailed information of the logged-in user
sharingShare the node

The claim command in the CLI tool is for host driven claiming, which is no longer supported in ESP32-C3. Instead, the more convenient Self Claiming is supported in ESP32-C3.

Before using any other command, you need to first run the signup command to sign up for an ESP RainMaker account:

$ cd your RainMaker path/esp-rainmaker/cli
$ cd python3 rainmaker.py signup someone@example.com
Choose a password
Password :
Confirm Password :
Enter verification code sent on your Email.
Verification Code : 973854
Signup Successful
Please login to continue with ESP Rainmaker CLI

Check the verification code in your email, as shown in Figure 9.9.

Figure 9.9. Verification code in email

Then, log in.

Execute the login command, and the Shell will open a web page, as shown in Figure 9.10. Enter your account and password in the box.

Figure 9.10. Log in to ESP RainMaker using web browser

Alternatively, you can enter the command login together with the parameter -email to directly log in using CLI:

$ python3 rainmaker.py login --email someone@example.com
Password:
Login Successful