Arduino Cloud IoT Cheat Sheet

Arduino IoT Cloud is a service that allows you to configure, program and deploy your Arduino devices. It is an all-in-one solution for IoT development, where you can build visual dashboards to monitor and control your devices, integrate with other services and much more.

This article summarizes the use of the Arduino Cloud IoT, and includes information regarding requirements, installation, API and general usage of the platform.

Compatible Hardware

To use the Arduino IoT Cloud, a cloud compatible board is required. You can choose between using an official Arduino board, or a board based on the ESP32 / ESP8266 microcontroller. The Arduino IoT Cloud currently supports connection via Wi-Fi, LoRaWAN® (via The Things Network) and mobile networks.

All cloud-compatible Arduino boards come with a hardware secure element (such as the ECC508 cryptochip), where you can store your security keys.

Wi-Fi

Official Arduino boards only supports the 2.4GHz frequency band for transmitting data.

The following boards connect to the Arduino IoT Cloud via Wi-Fi.

• MKR 1000 WiFi
• MKR WiFi 1010
• Nano RP2040 Connect
• Nano 33 IoT
• GIGA R1 WiFi
• Portenta H7
• Portenta H7 Lite Connected
• Nicla Vision

Connection via Wi-Fi is an easy alternative, and your credentials can safely be entered during the configuration of a project. This type of connection is most suitable for low-range projects, where you connect your board to the cloud via your home/work/school router.

LoRaWAN®

The following boards connect to the Arduino IoT Cloud via The Things Stack, a LoRaWAN® Network Server connected to thousands of public LoRa® gateways.

• MKR WAN 1300
• MKR WAN 1310

Connection via LoRaWAN® is recommended for low-power projects in both remote and urban areas, where Wi-Fi or other popular connectivity types are not available. The MKR WAN 1300/1310 boards are equipped with a LoRa radio module and has a slot for an antenna. With the right low-power configuration, the board can send data to the cloud for months on a single battery.

To learn more about setting up LoRaWAN® devices, visit the Configuring LoRaWAN® devices in the Arduino Cloud guide.

GSM / NB-IoT Boards

The MKR GSM 1400 and MKR NB 1500 require a SIM card to connect to the cloud, as they communicate over the mobile networks.

• MKR GSM 1400
• MKR NB 1500

Connection through mobile networks can be considered in remote areas where there's no Wi-Fi, or in mobile projects (such as cargo tracking).

For more information, visit the Arduino SIM page.

ESP32 / ESP8266

The Arduino IoT Cloud supports a wide range of third party boards based on the ESP32 and ESP8266 microcontrollers with support for Wi-Fi. To set them up, simply choose the third party option in the device setup.

To learn more about ESP32/ESP8266 support and how to set it up, visit the Connecting ESP32 & ESP8266 to Arduino Cloud IoT guide.

Software Requirements

Create Agent

The Arduino Create Agent is a single binary that will appear on the menu bar and work in the background. It allows you to use the Arduino IoT Cloud and the Arduino Web Editor to seamlessly upload code to any board directly from the browser.

Downloading and installing the Arduino Create Agent plugin can be simply done following this quick and easy process.

The full documentation of the Arduino Create Agent is available here for more advanced usage.

Arduino Account

An Arduino account is needed to use all of the Arduino Cloud services including Arduino IoT Cloud and the Arduino Web Editor. Follow this link to make an account.

In addition to IoT Cloud, the Arduino account provides access to the Arduino Web Editor which is the full online IDE. Arduino and non-Arduino boards can be programmed using the Arduino Web Editor without the need for installing board drivers or libraries.

Device configuration

Configuration of the device to be used with the Arduino IoT Cloud is required once for every new device.

Configuring a new device can be achieved following the steps below:

1. Sign in to the Arduino IoT Cloud.

2. Navigate to "Devices" on the top menu.

3. Connect an Arduino IoT Cloud compatible device.

4. Click on the "ADD DEVICE" button.

5. Select the correct device, either an Arduino device or a third party device.

6. Wait until the configuration is complete.

Once a device is successfully configured it appears in the "Devices" list and can be used to create a thing, or can be linked to an existing thing.

The Devices page displays the name, status, and linked Things for each of the configured devices. Clicking on the device allows for renaming it, as well as accessing more information about the device such as its ID number, type, FQBN, serial number, NINA firmware version and the option to update it, linked Thing, status, latest activity and the date when the device was added.

The status of the device indicates whether it's connected to the Arduino IoT Cloud (online), or not successfully connected (offline).

A shortcut to add a device is also provided in "Things" page as explained in the next section.

Features

Below you will find a list of features that are available in the Arduino IoT Cloud.

Uploading Over-The-Air (OTA)

This feature allows for uploading sketches wirelessly to Arduino boards, without the need to connect the board physically. This feature is supported for the following boards:

• Arduino MKR WiFi 1010
• Arduino NANO 33 IoT
• Arduino Nano RP2040 Connect
• Portenta H7
• Cloud compatible ESP32 boards (see list below).

Verified ESP32 Boards Supporting OTA

The following ESP32 boards have been tested and verified to support OTA:

• ESP32-S2-DevKitC
• NODEMCU-32-S2
• WEMOS LOLIN D32
• ESP32-S3-DevKitC
• WEMOS LOLIN D32
• ESP32-CAM
• NodeMCU-32S
• Freenove ESP32 WROVER
• ESP32-DevKitC32E
• DOIT ESP32 DevKit v1

In order to enable over-the-air uploads, an initial upload should be done in the traditional way via a cable connection using the IoT Cloud interface. After such initial upload, "Over-the-Air" will appear as an option whenever the board is connected to the cloud via its network connection. For more information about this topic, check out the tutorial about uploading sketches Over-the-Air (OTA).

Variable Synchronisation

This feature allows Arduino devices to communicate with each other by sharing variables, without writing a single line of code or spending time with radio modules and network protocols.

Using this feature you can link variables of the same data type between two or more cloud-enabled devices, and Arduino IoT Cloud will automatically ensure any change to their value is propagated among all linked boards. For example, one button could set three smart bulbs to the same color by just setting a variable on one device and reading it on the others. Or you could turn on a heater when temperature sensors in your room or outside in your weather station drop below a certain level.

Local Time

To retrieve local time, use the

ArduinoCloud.getLocalTime()

The returned timestamp can be displayed in a dashboard using a

CloudTime

Copy
1myTimeVariable = ArduinoCloud.getLocalTime()

***Note that when using a board equipped with a hardware Real-Time Clock (RTC) the Arduino_IoTCloud library will use it automatically, thus communicating with the RTC from within your sketch or other libraries is not recommended. You can use the

getLocalTime()

getInternalTime()

Things

In order to use your devices in IoT Cloud, you need to associate a Thing to each of them. A Thing is an abstract concept which holds the configuration of the variables and other settings, as well as the history of the data collected for the variables.

Devices and things are distinct concepts in IoT Cloud so that you can easily swap the actual hardware without reconfiguring everything from scratch: just detach a thing from a device, and ressign it to another device.

The Things page can be accessed either by clicking on "CREATE THING" on the added device in the "Device" page, or by navigating to the "Things" tab in the top menu, then clicking on the "CREATE THING". The first method links the device to the created Thing automatically, while the later method requires a manual linking of the device on the Things page.

The steps below can be used as guidance when setting up a Thing:

1. Attach a device if not already attached.
2. Add a variable, or variables by clicking on the "Add Variable" button.
3. Configure the network, by entering the WiFi's name and password.
4. Edit the sketch in the "Sketch" tab.

You can learn more about Things in the Getting Started with the Arduino IoT Cloud guide.

Variables

Visit the main article on Cloud Variables for a more detailed coverage.

A thing can have one or more variables. A variable can be used for multiple purposes:

• collect data over time in the cloud (sensor readings, status changes, log messages etc.)
• show data in real-time in a dashboard using the various available visual widgets
• receive changes originated from a dashboard or other linked devices

When you configure a variable, Arduino IoT Cloud will handle all the communication and synchronization behind the scenes. Variables can be used directly just like any other variables in an Arduino sketch.

When adding a variable the following values need to be determined:

1. A Display Name, which can any string name, preferably something that indicates the function of the variable. It can not include spaces and special characters, and it cannot start with a number.

2. The Type of Variable corresponds to the data type of the variable and must be chosen from the provided list. See below for a full list of the available types.

   Please note: when a variable is added, it is automatically declared in the

   thingProperties.h

   file so you don't need to declare it yourself in the sketch.

3. A Declaration Name, a unique name by which the variable will be called in the sketch. It can not include spaces and special characters, and it cannot start with a number. The display name chosen for the variable may be used here to avoid conflicts.

4. The Variable's Permission, which can be either Read & Write or Read Only. A Read & Write variable can work both as input and output, the data can be sent from the device to the cloud and vice versa. A Read Only variable can only send data from the device to the cloud.

5. The Variable Update Policy, which may be either On Change or Periodically. If On Change is chosen, the variable will be updated to the cloud whenever the change in value is greater than or equal to the set threshold. If Periodically is chosen, the variable will be updated to the cloud each time the number of seconds set is elapsed.

Configuring Network

Configuring the network allows for connecting an Arduino, or third party devices to a Wi-Fi network. The credentials entered are saved in the Secret file, inside the sketch.

Entering the network details can be done simply by navigating to "Network" and clicking on "Configure". A popup screen appears where the Network's Name and Password can be entered. The network details are saved and only gets uploaded to the device when the sketch is uploaded.

The network details can be modified by clicking the "Change" button, correcting the entered credentials, saving the new details, and uploading the sketch again.

Editing the sketch

The "Sketch" tab in the Things page includes a code editor, which is a lite version of the Arduino Web Editor that enables for editing, formatting, compiling and saving a sketch. An automatically generated code is found in the editor after adding at least one variable.

The sketch may be also displayed and modified in the full Arduino Web Editor by clicking the "Open full editor" button, which provides more features.

The sketches generated automatically in IoT Cloud include four files:

thingProperties.h

This is a file containing the code generated by the Arduino IoT Cloud that should not be edited. This file includes the ArduinoIoTCloud and Arduino_ConnectionHandler libraries, the network configuration, initializations of variables and function, and properties of each variable saved in the

initProperties()

The example below shows a basic code generated in the

thingProperties.h

Please note: for READ & WRITE variables a callback function (in this case called

onVariableName01Change()

Copy
1#include ArduinoIoTCloud.h
2#include Arduino_ConnectionHandler.h
3
4const char SSID[]     = SECRET_SSID;    // Network SSID (name)
5const char PASS[]     = SECRET_PASS;    // Network password (use for WPA, or use as key for WEP)
6
7void onVariableName01Change(); // declaring a function for the read & write variables
8
9int Variable_Name_01; // declare a normal integer variable
10CloudTemperature Variable_Name_02; // declare a Cloud specific temperature variable
11
12void initProperties(){
13
14  ArduinoCloud.addProperty(Variable_Name_01, READWRITE, ON_CHANGE, onVariableName01Change); // linking the read & write variable with its function and updating it on change
15  ArduinoCloud.addProperty(Variable_Name_02, READ, 10 * SECONDS, NULL); // setting up the read only variable and updating it every 10 seconds
16
17}
18
19WiFiConnectionHandler ArduinoIoTPreferredConnection(SSID, PASS); // setting up the network name and password chosen in the Network configuration

As of 2022/02/09 the

thingProperties.h

thingProperties.h

Copy
1const char THING_ID[] = "A-UNIQUE-THING-ID-NUMBER";
2
3ArduinoCloud.setThingId(THING_ID); //previously located inside initProperties()

sketch.ino

This file includes the main Arduino sketch that can be edited and uploaded to the device. The sketch includes the

thingProperties.h

setup()

loop()

thingProperties.h

Copy
1#include "thingProperties.h"
2
3void setup() {
4  Serial.begin(9600);   // Initialize serial and wait for port to open:
5  delay(1500);  // This delay gives the chance to wait for a Serial Monitor without blocking if none is found
6
7  initProperties();   // Defined in thingProperties.h
8
9  ArduinoCloud.begin(ArduinoIoTPreferredConnection);   // Connect to Arduino IoT Cloud
10
11  setDebugMessageLevel(2);
12  ArduinoCloud.printDebugInfo();
13}
14
15void loop() {
16  ArduinoCloud.update();
17  // Your code here
18}
19
20void onVariableName01Change() {
21  // Do something
22}

The

setup()

Serial.begin(9600);

initProperties();

ArduinoCloud.begin(ArduinoIoTPreferredConnection);

thingProperties.h

setDebugMessageLevel(2);

ArduinoCloud.printDebugInfo();

Secret

This is a file to save sensitive data such as passwords and API keys that will be protected and hidden from public access. The network configuration details are saved in this file.

ReadMe.adoc

This is a Read Me file as a placeholder for adding a description of the project.

Uploading A Sketch

Uploading a sketch through the Arduino IoT Cloud can be achieved in two ways, either through the code editor in the thing page (Sketch tab) or through the full editor (click on "Open full editor" to open it).

The full editor allows for more control over the code and its libraries and provides access to all files included in the sketch, as well as more editing and sharing options.

Please note: the status of the connection to the Network and Arduino IoT Cloud may be checked by opening the Serial Monitor after uploading a sketch. If the

while(!Serial);

setup()

Dashboards & Widgets

Dashboards are visual user interfaces for interacting with your boards over the cloud, which can be customized with different setups depending on the project's needs.

One or more Things can be added to a Dashboard, with all or some of their variables. The dashboards can be accessed by navigating to the “Dashboards” page at the top menu of the Arduino IoT Cloud interface, where a list of the existing Dashboards and an option to create a new Dashboard are available.

You can read more about Dashboards & Widgets.

Recommended Code Practices

This section highlights some important aspects of writing code with regard to the implementations in the ArduinoIoTCloud.

Watchdog Timer (WDT)

All IoT Cloud sketches use a Watchdog Timer (WDT) by default. The WDT can be used to automatically recover from hardware faults or unrecoverable software errors.

A WDT is essentially a countdown timer, whereas it starts counting from a set value, and upon reaching zero, it resets the board. To prevent it from reaching zero, we continuously call it from the

loop()

ArduinoCloud.update()

This is why, it is very important to not use any long blocking code in your sketch. For example, using a long

delay()

loop()

The WDT can however be disabled inside of the

setup()

false

Copy
1ArduinoCloud.begin(ArduinoIoTPreferredConnection, false).

You can view the source code of this implementation here.

Alternatives to Delays

The

loop()

ArduinoCloud.update();

loop()

A common blocking pattern is the use of the

delay()

millis()

Let's see how to blink a LED. The traditional way involves the

delay()

Copy
1void loop() {
2  ArduinoCloud.update();
3
4  digitalWrite(LED_BUILTIN, HIGH);
5  delay(1000);
6  digitalWrite(LED_BUILTIN, LOW);
7  delay(1000);
8}

This works, but it will cause a delay of at least two seconds between one execution of

ArduinoCloud.update()

This can be rewritten in a non-blocking way as follows:

Copy
1void loop() {
2  ArduinoCloud.update();
3
4  digitalWrite(LED_PIN, (millis() % 2000) < 1000);
5}

How does this work? It gets the current execution time provided by

millis()

For a more complex and commented example, you can have a look at the BlinkWithoutDelay example.

I2C Usage

Components connected via I²C (including the sensors onboard the MKR IoT Carrier) uses the same bus as the ECCX08 cryptochip. As the crypto chip is an essential part of establishing a connection to the IoT Cloud (it contains the credentials), it is important that other I²C peripherals are initialized after the connection has been made.

For example, if you are initializing a library such as Arduino_MKRENV, your

setup()

Copy
1void setup() {
2  Serial.begin(9600);
3  delay(1500);
4
5  initProperties();
6
7  ArduinoCloud.begin(ArduinoIoTPreferredConnection);
8  setDebugMessageLevel(2);
9  ArduinoCloud.printDebugInfo();
10
11  //initializing the Arduino_MKRENV library
12  if (!ENV.begin()) {
13    Serial.println("Failed to initialize MKR ENV shield!");
14    while (1);
15  }

Avoid Blocking Serial Communication

while(!Serial) {}

while(!Serial){}

while(!Serial){}

A common trick is to add a

delay(1500);

Serial.begin(9600);

Arduino IoT Cloud API

We provide two Arduino Iot Cloud APIs:

1. The first is the REST API which allows you to adding and configuring new Arduino IoT Cloud Devices, Things, Properties, as well as reading historical data. An example of this API's use is making custom dashboards in a local server. A full documentation of the Arduino IoT Cloud REST API is available for advanced users.

The Arduino IoT Cloud REST API can be called just with any HTTP Client, or using one of these clients:

• Javascript NPM package.
• Python® PYPI Package.
• Golang Module.

2. The second is the Data API (MQTT) which allows you to send/receive Variables' data. An example of this API's use is sending IoT Cloud Variables' updates to the browser. A full documentation of the Arduino IoT Cloud Data API (MQTT) is available for advanced users.