Arduino IoT Cloud APIs

The Arduino IoT Cloud has different sets of APIs that provide different functionalities. This article serves as an introduction to how to work and what you can achieve with them.

Application API

The main goal of the Application API is to allow you to create and manage IoT resources like dashboards, devices, things, and variables, along with the retrieval and handling of historical data coming from your IoT Devices.

The core of those APIs is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use those APIs, both directly calling our HTTP endpoints or using our clients that wrap those calls into easy-to-use abstractions like objects and functions. We have Applications API clients available in

javascript

golang

python

With this API, you can:

• Build an automated script to create your things, in bulk
• Duplicate the configuration of things, dashboards, devices
• Create your own personal web application to manage your resources
• Build a script that reads your variables' data and provides custom analytics

Resources

You can find the full list of available resources and actions in the Arduino IoT Cloud Application API Technical Reference.

For learning how to successfully authenticate and interface with this API, visit the Arduino Cloud REST API & SDK article. Examples using JavaScript, Python and Golang are available here.

Device API

The Device API allows sending and receiving any kind of data (sensors' values, commands for actuators, configuration changes...) from and to IoT Devices and the Cloud. Under the hood, they:

• take care of the data exchange with our MQTT broker
• handle best in class authentication & security
• manage compression, data format, and transport protocols

With this API, you can:

• Send sensors' values to the cloud
• Send and receive input and commands from and to dashboards
• Listen for variables' values changes and act upon them

As a wrapper for the Device API, we have the following libraries:

• An official Arduino IoT Cloud Library for your Arduino sketches:

  ArduinoIoTCloud.h

• An NPM Javascript package:

  arduino-iot-js

Arduino IoT Cloud Sketch library

The Arduino (C++) library allows your Arduino devices to connect and exchange data with the IoT Cloud. If you use the Arduino Cloud online environment, you do not need to install this library.

This library is also available in the library manager for Arduino IDE. With a paid subscription, you can push/pull changes to your online sketches in the offline editor.

You can find more details at:

• The official repository
• The cheat sheet

Arduino IoT JS

The

arduino-iot-js

Example:

Copy
1const { ArduinoIoTCloud } = require('@arduino/arduino-iot-js');
2
3ArduinoIoTCloud.connect(options)
4  .then(() => {
5    console.log("Connected to Arduino IoT Cloud");
6    return ArduinoIoTCloud.onPropertyValue(thingId, variableName, showUpdates = value => console.log(value));
7  })
8  .then(() => console.log("Callback registered"))
9  .catch(error => console.log(error));

Full examples and documentation can be found at:

• The official repository
• The NPM module page

MicroPython

The Arduino IoT Cloud Python Client can be installed on a board running MicroPython, and is designed to be easy to use. With just a few lines of code you can connect to the cloud, using credentials obtained during the manual device configuration.

Below is a minimal example:

Copy
1DEVICE_ID = "YOUR_DEVICE_ID"
2SECRET_KEY = "YOUR_SECRET_KEY"
3
4client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY)
5
6client.register("variable")  
7client["variable"] = 255
8
9client.start()

For more information, visit the Connecting to Arduino IoT Cloud using MicroPython guide.

Python

The Arduino IoT Cloud Python Client can also be used with regular python, and is very similar to how you connect using MicroPython, with a few adjustments.

To find out more about how to connect using Python, you can refer to the Python section of the Manual Device Configuration guide.

Backward Compatibility Policy

Public Arduino IoT Cloud APIs are exposing versioned endpoints and are committed to preserving compatibility with the following policies in place:

• When making a breaking change to the API signature or behavior, we will expose a new version of the endpoint.
• If we are making a change that is backward compatible with the existing version, we won't change the endpoint version.
• When introducing a new version of the API, we will preserve the previous version as deprecated for a reasonable amount of time to allow client migrations.
• We will not preserve multiple previous versions, just N-1 with respect to the current last released, hence upgrades are recommended.
• In any case, the frequency of version changes is expected to be less than once a year.
• It's also recommended that the client keeps the base URL of the API configurable because the base URL (currently api2.arduino.cc) might also change.