Connect the ESP32 to Arduino Cloud and switch an LED from your phone

Arduino Cloud is Arduino's own internet service for projects like yours. You describe your project as a Thing with a few variables, Arduino Cloud writes the connection code for you, and you build a dashboard of switches, gauges and charts by dragging widgets. The same dashboard works in a browser and in the free Arduino IoT Remote app, so you can control your ESP32 from anywhere with internet. In this first lesson you set everything up and switch an LED inside a little printed cloud lamp from your phone.

What you'll learn

• How Arduino Cloud is organised: devices, Things, variables and dashboards
• How to add the ESP32 as a third-party device
• How a cloud variable and an onChange function work together
• How to build a dashboard and use it on your phone

What you need

• ESP32 board, expansion board and USB cable (ESP32 IoT Starter Kit)
• 1 LED and 1 resistor, 220 Ω (ESP32 IoT Starter Kit)
• A free Arduino Cloud account (an adult's help to sign up if you are under 14)
• A 2.4 GHz Wi-Fi network
• The printed parts from the 3D printing box below (cloud lamp), or the cardboard version described there
• Breadboard and jumper wires (ESP32 IoT Starter Kit)

Wiring

Set up Arduino Cloud

1. Go to Arduino Cloud and create a free account. Install the Arduino Cloud Agent when Arduino Cloud asks for it: it lets the browser upload sketches to the board over USB.
2. Open Devices, click + Device, choose Third party device, then ESP32 and ESP32 Dev Module. Give it a name, such as "My ESP32".
3. Arduino Cloud shows a Device ID and a Secret Key. Click Download the PDF and keep it safe: the secret key is shown only once and works like a password.
4. Open Things and click + Thing. Rename it to Cloud Lamp. Under Associated device, pick your ESP32.
5. Under Network, enter your Wi-Fi name, password (2.4 GHz only) and the secret key from the PDF.
6. Click + Add next to Cloud Variables. Name it led, type Boolean, permission Read & Write, update policy On change, and save.

Free plan: Arduino Cloud's free plan lets you use 2 Things with up to 5 variables each and keeps your data for 1 day. Every lesson in this path fits in it. Check the plans page for the current limits.

The sketch

Arduino Cloud writes the sketch's first version for you, with a thingProperties.h tab that lists your variables and a Secret tab with your Wi-Fi details and device key. In the Thing, open the Sketch tab, click Open full editor, replace the main sketch with the code below and upload. Leave the other tabs as they are.

#include "thingProperties.h"

const int LED_PIN = 25;

void setup() {
  Serial.begin(115200);
  delay(1500);                      // give the Serial Monitor time to open
  pinMode(LED_PIN, OUTPUT);

  initProperties();
  ArduinoCloud.begin(ArduinoIoTPreferredConnection);
  setDebugMessageLevel(2);          // connection messages in the Serial Monitor
  ArduinoCloud.printDebugInfo();
}

void loop() {
  ArduinoCloud.update();            // keeps the connection alive and syncs variables
}

// Runs every time the led variable changes in the dashboard or the app
void onLedChange() {
  digitalWrite(LED_PIN, led);
  Serial.println(led ? "LED on" : "LED off");
}

For reference, this is the thingProperties.h that Arduino Cloud creates from the variables above. Yours has your own device ID, and may use an older but equally valid style such as addProperty(led, READWRITE, ON_CHANGE, onLedChange).

// Code generated by Arduino Cloud (yours has your own device ID)
#include <ArduinoIoTCloud.h>
#include <Arduino_ConnectionHandler.h>

const char DEVICE_LOGIN_NAME[] = "YOUR_DEVICE_ID";
const char SSID[] = SECRET_SSID;              // from the Secret tab
const char PASS[] = SECRET_OPTIONAL_PASS;
const char DEVICE_KEY[] = SECRET_DEVICE_KEY;

void onLedChange();

bool led;

void initProperties() {
  ArduinoCloud.setBoardId(DEVICE_LOGIN_NAME);
  ArduinoCloud.setSecretDeviceKey(DEVICE_KEY);
  ArduinoCloud.addProperty(led, Permission::ReadWrite).onUpdate(onLedChange);
}

WiFiConnectionHandler ArduinoIoTPreferredConnection(SSID, PASS);

Build the dashboard

1. Open Dashboards, click + Dashboard and name it "Cloud Lamp".
2. Click Add, choose a Switch widget and link it to the led variable of the Cloud Lamp Thing.
3. Flip the switch: within a second the LED in the cloud lights up. The Serial Monitor says "LED on".
4. Install Arduino IoT Remote on your phone, sign in with the same account and open the dashboard. It works on mobile data too.

How it works

Arduino Cloud keeps a copy of every variable on its servers. When you flip the switch, the server's copy of led changes and it sends the new value to the ESP32. ArduinoCloud.update(), which runs in every pass of loop(), receives it, stores it in the sketch's led variable and calls onLedChange(). That is the moment to do something with the new value.

The thingProperties.h tab connects the two worlds: each addProperty() line links a variable in your sketch to the one with the same name in the cloud. Read & Write means both the dashboard and the ESP32 can change it.

The secret device key proves to Arduino Cloud that it is really your ESP32 connecting, which is why it must stay private.

Try this next

• Add a second Boolean called blink and make the LED blink while it is on.
• Add a Schedule widget to switch the lamp on every evening.
• Share the dashboard with someone in your family (Dashboards → Share).

Troubleshooting

• The device stays "Offline": open the Serial Monitor at 115200 baud. Check the Wi-Fi name and password in the Secret tab (2.4 GHz only) and that the secret device key is the one you saved when you added the device.
• Compile error about a variable: the variable names in the sketch must match the ones in your Thing exactly, including capital letters. Rename the Thing's variable or the sketch's to match.
• Upload fails in the browser: the Arduino Cloud Agent must be running, and the board must be selected as "ESP32 Dev Module" on the right port.
• The switch moves but the LED stays off: check the long leg on the resistor side and GPIO 25.
• A printed part is too tight or too loose: printers differ by a few tenths of a millimetre. Sand or file a tight hole, and fix a loose part with a drop of hot glue or a strip of tape.