| date | title | description | author |
|---|---|---|---|
September 24, 2021, at 11:11 AM |
Arduino Cloud IoT Cheat Sheet |
Learn how to set up the Arduino Cloud IoT, get a quick overview of the compatible boards, the API, configuration, Things, variables and dashboards. |
Liam Aljundi |
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.
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.
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
- 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.
The following boards connect to the Arduino IoT Cloud via The Things Stack, a LoRaWAN® Network Server connected to thousands of public LoRa® gateways.
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.
The MKR GSM 1400 and MKR NB 1500 require a SIM card to connect to the cloud, as they communicate over the mobile networks.
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.
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.
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.
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.
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:
-
Connect an Arduino IoT Cloud compatible device.
-
Click on the "ADD DEVICE" button.
-
Select the correct device, either an Arduino device or a third party device.
-
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.
Below you will find a list of features that are available in the Arduino IoT Cloud.
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 compatible Arduino boards:
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).
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.
To retrieve local time, use the ArduinoCloud.getLocalTime() method in your sketch. The value returned represents the current local time expressed as a Unix timestamp (i.e. seconds from the epoch), and it automatically takes your time zone settings and DST (Daylight Saving Time) into account. Time zone can be set in the Thing configuration page within the Arduino IoT Cloud platform.
The returned timestamp can be displayed in a dashboard using a CloudTime variable and the Time Picker widget, or can be parsed with a third-party library such as Time in case you want to show it on a display.
myTimeVariable = 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() and getInternalTime() methods provided by Arduino_IoTCloud instead.
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:
- Attach a device if not already attached.
- Add a variable, or variables by clicking on the "Add Variable" button.
- Configure the network, by entering the WiFi's name and password.
- Edit the sketch in the "Sketch" tab.
You can learn more about Things in the Getting Started with the Arduino IoT Cloud guide.
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:
-
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.
-
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.hfile so you don't need to declare it yourself in the sketch. -
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.
-
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.
-
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 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.
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:
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() function.
The example below shows a basic code generated in the thingProperties.h file as a result of adding two variables. The first variable "Variable_Name_01" is an integer variable with a READ & WRITE permission, and the second is a READ ONLY CloudTemperature variable.
Please note: for READ & WRITE variables a callback function (in this case called onVariableName01Change()) is automatically generated in sketch. This will allow for writing commands inside the function to trigger actions whenever the value is changed from the cloud.
#include ArduinoIoTCloud.h
#include Arduino_ConnectionHandler.h
const char SSID[] = SECRET_SSID; // Network SSID (name)
const char PASS[] = SECRET_PASS; // Network password (use for WPA, or use as key for WEP)
void onVariableName01Change(); // declaring a function for the read & write variables
int Variable_Name_01; // declare a normal integer variable
CloudTemperature Variable_Name_02; // declare a Cloud specific temperature variable
void initProperties(){
ArduinoCloud.addProperty(Variable_Name_01, READWRITE, ON_CHANGE, onVariableName01Change); // linking the read & write variable with its function and updating it on change
ArduinoCloud.addProperty(Variable_Name_02, READ, 10 * SECONDS, NULL); // setting up the read only variable and updating it every 10 seconds
}
WiFiConnectionHandler ArduinoIoTPreferredConnection(SSID, PASS); // setting up the network name and password chosen in the Network configuration
As of 2022/02/09 the thingProperties.h no longer contains your Thing ID. If you have created a Thing prior to this date, simply update your Thing and your thingProperties.h will automatically be updated. You can see the lines that were removed in the snippet below:
const char THING_ID[] = "A-UNIQUE-THING-ID-NUMBER";
ArduinoCloud.setThingId(THING_ID); //previously located inside initProperties()
This file includes the main Arduino sketch that can be edited and uploaded to the device. The sketch includes the thingProperties.h file, the setup() and loop() functions, and an empty function for every Read & Write variable. The code below is a basic example of an auto generated code in the sketch file, using the same variables from the previous example displayed in thingProperties.h section.
#include "thingProperties.h"
void setup() {
Serial.begin(9600); // Initialize serial and wait for port to open:
delay(1500); // This delay gives the chance to wait for a Serial Monitor without blocking if none is found
initProperties(); // Defined in thingProperties.h
ArduinoCloud.begin(ArduinoIoTPreferredConnection); // Connect to Arduino IoT Cloud
setDebugMessageLevel(2);
ArduinoCloud.printDebugInfo();
}
void loop() {
ArduinoCloud.update();
// Your code here
}
void onVariableName01Change() {
// Do something
}
The setup() function includes an initialization of the Serial Monitor and the properties using the Serial.begin(9600); and initProperties(); commands. Additionally, the connection to the Arduino IoT Cloud is initialized using the ArduinoCloud.begin(ArduinoIoTPreferredConnection); command, which uses methods from the ArduinoIoTCloud and Arduino_ConnectionHandler libraries that are included in the thingProperties.h file. Finally, setDebugMessageLevel(2); and ArduinoCloud.printDebugInfo(); are used for debugging, it prints information related to the state of network and IoT Cloud connection and errors. The higher number the more granular information obtained, the default is 0 (only errors) and the maximum is 4.
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.
This is a Read Me file as a placeholder for adding a description of the project.
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); loop is included in the setup() function, the code would not execute before opening the Serial Monitor.
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.
The loop() function includes the ArduinoCloud.update(); call, which sends data to the cloud and receives updates. In order to get the best responsiveness in your cloud-connected projects, the loop() function should run as fast as possible. This means that no blocking commands should be used inside, and you should prefer a non-blocking programming approach whenever possible.
A common blocking pattern is the use of the delay() function which stops the execution of the function for the given time. We strongly advise to get rid of this function and achieve the same behavior in a non-blocking way with the millis() function as described below.
Let's see how to blink a LED. The traditional way involves the delay() function:
void loop() {
ArduinoCloud.update();
digitalWrite(LED_BUILTIN, HIGH);
delay(1000);
digitalWrite(LED_BUILTIN, LOW);
delay(1000);
}
This works, but it will cause a delay of at least two seconds between one execution of ArduinoCloud.update() and the next one, thus causing bad performance of the cloud communication.
This can be rewritten in a non-blocking way as follows:
void loop() {
ArduinoCloud.update();
digitalWrite(LED_PIN, (millis() % 2000) < 1000);
}
How does this work? It gets the current execution time provided by millis() and divides it by 2 seconds. If the remainder is smaller than one second it will turn the LED on, and if it's greater it will turn the LED off.
For a more complex and commented example, you can have a look at the BlinkWithoutDelay example.
while(!Serial) {} loops endlessly until the Serial Monitor is opened. This is a useful practice in cases where you want to see all debug output from the start of the sketch execution. However, when building IoT systems using while(!Serial){} can hinder our project from running autonomously, stopping the board from connecting to the network and IoT Cloud before manually opening the Serial Monitor. Therefore, it is recommended to consider removing the while(!Serial){} loop if it's not necessary.
A common trick is to add a delay(1500); command after Serial.begin(9600);. This will slightly slow down the initialization of your device, but will give you some time to open the serial monitor when you're interested in seeing its output within losing the very first lines.
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:
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.