From c56fdc087ded982748f385c7e3bdfc3697e6677d Mon Sep 17 00:00:00 2001 From: Josefine Hansson Date: Fri, 5 Jan 2024 10:40:42 +0100 Subject: [PATCH 01/11] cloud tutorials --- .../01.guides/00.overview/overview.md | 298 +++---- .../01.guides/02.arduino-c/arduino-c.md | 252 +++--- .../arduino-cloud/01.guides/03.esp32/esp32.md | 244 +++--- .../01.guides/04.micropython/content.md | 450 +++++----- .../01.guides/05.python/python.md | 346 ++++---- .../01.guides/06.javascript/javascript.md | 248 +++--- .../01.guides/07.node-red/nodered-intro.md | 2 +- .../arduino-cloud/01.guides/08.alexa/alexa.md | 344 ++++---- .../arduino-cloud/02.hardware/02.wifi/wifi.md | 2 +- .../arduino-cloud/02.hardware/03.lora/lora.md | 2 +- .../00.sketches/sketches.md | 10 +- .../03.cloud-interface/01.things/things.md | 10 +- .../02.variables/variables.md | 20 +- .../03.dashboard-widgets/dashboard-widgets.md | 6 +- ...tchbook-and-libraries-to-the-web-editor.md | 4 +- .../share-your-sketches.md | 2 +- .../01.getting-started/iot-remote-app.md | 158 ++-- .../iot-remote-phone-sensors.md | 344 ++++---- .../02.cloud-scheduler/cloud-scheduler.md | 620 +++++++------- .../03.device-to-device/device-to-device.md | 588 ++++++------- .../ota-getting-started.md | 318 +++---- .../sharing-dashboards.md | 4 +- .../06.thing-to-thing/thing-to-thing.md | 326 ++++---- .../arduino-cloud-callbacks.md | 82 +- .../iot-cloud-historical-data.md | 128 +-- .../08.manual-device/manual-devices.md | 572 ++++++------- .../09.advanced-chart/advanced-chart.md | 300 +++---- .../11.webhooks/iot-cloud-webhooks.md | 304 +++---- .../07.api/01.api-overview/api-overview.md | 4 +- .../07.api/03.c-library/c-library.md | 4 +- .../07.getting-started/arduino-cloud-cli.md | 2 +- .../security-considerations.md | 6 +- .../09.arduino-cloud-for-business/contend.md | 788 +++++++++--------- .../09.arduino-cloud-for-education/content.md | 772 ++++++++--------- .../cloud-environmental-data.md | 10 +- .../cloud-relay-control.md | 6 +- 36 files changed, 3788 insertions(+), 3788 deletions(-) diff --git a/content/arduino-cloud/01.guides/00.overview/overview.md b/content/arduino-cloud/01.guides/00.overview/overview.md index 9f3ad93d2e..b86ad4e8fd 100644 --- a/content/arduino-cloud/01.guides/00.overview/overview.md +++ b/content/arduino-cloud/01.guides/00.overview/overview.md @@ -1,150 +1,150 @@ ---- -title: 'Getting Started with Arduino Cloud' -description: 'Get started with the Arduino Cloud, an online platform that makes it easy for you to code, deploy and monitor IoT projects.' -tags: [Arduino Cloud, Getting Started] -author: 'Karl Söderby' ---- - -The [Arduino Cloud](https://app.arduino.cc/) is a platform for developing Arduino projects and connecting them to the world. It supports secure connections with boards via [Wi-Fi®](/arduino-cloud/hardware/wifi), [LoRa®](/arduino-cloud/hardware/lora), [Ethernet](/arduino-cloud/hardware/ethernet) and [Cellular (GSM/NB-IoT)](/arduino-cloud/hardware/cellular), and lets you create a system for sending any variable information you can think of from one board to another within minutes of unboxing them. - -The Arduino Cloud platform includes: -- an **Integrated Development Environment (IDE)** for programming your boards, -- a **cloud backend service** for synchronizing data from Arduino boards, but also from [Python](/arduino-cloud/guides/python) & [JavaScript](/arduino-cloud/guides/javascript) clients, -- a **graphical tool (dashboard)** for controlling and monitoring your board (as well as an [mobile app](/arduino-cloud/iot-remote-app/getting-started)). -- [REST API](/arduino-cloud/api/arduino-iot-api) and [command line tools](/arduino-cloud/arduino-cloud-cli/getting-started) for larger scale automations. - -Very simply explained, with the Arduino Cloud you can: -1. Create a program for an Arduino based on a brilliant idea you just hatched. -2. Upload the program to your board and synchronize any data you want to (most commonly through Wi-Fi®). -3. Create a dashboard with a set of widgets to control and monitor your data. - -Developing a sketch made for the Arduino Cloud is almost just like developing any other sketch. You have your setup, and loop just like normal. But you are also able to select variables to be automatically synced to the Arduino Cloud. - -Once a variable is synced to the Arduino Cloud you can access it from any of your other devices connected to the Arduino Cloud. - -Once you have setup your project, this is how you could interact & monitor it. - -For example, turning ON / OFF a light connected to a device would work like this: - -![Interacting with your device](assets/overview-interaction.png) - -And if you want to read the value of a sensor connected to your device, it would work like this: - -![Monitoring your device.](assets/overview-monitor.png) - -Networking code and data synchronizing is **automatically done**, so just focus on the project, and let the Arduino Cloud handle the rest. - -***This document will help you get familiar with the [Arduino Cloud](https://app.arduino.cc/) service, and once you've got a good hang of it, you can explore the [rest of the documentation](/arduino-cloud/).*** - -## Compatible Boards - -***Throughout the documentation, we will often refer to a "board" as a "device". A board is your physical hardware or virtual setup (Python/JS), and a "device" is how it is configured in the cloud.*** - -Compatibility with the Arduino Cloud is divided into two categories: -- **Cloud Editor Support** - you can program **any** official Arduino board in the cloud editor. The editor also supports a large amount of third party boards. -- **IoT Support** - board with a radio module (e.g. Wi-Fi®) are supported. ESP32 based boards are also supported. - -For more information and list of supported boards, see the links below: -- [Wi-Fi®](/arduino-cloud/hardware/wifi) -- [LoRa®](/arduino-cloud/hardware/lora) -- [Ethernet](/arduino-cloud/hardware/ethernet) -- [Cellular (GSM/NB-IoT)](/arduino-cloud/hardware/cellular). - -***You can also create something called [manual devices](/arduino-cloud/hardware/devices#manual-devices), which allows you to create a virtual instance directly on your computer using JavaScript, Python or MicroPython.*** - -## Overview - -![The Arduino Cloud home page.](assets/home.png) - -Anything in the Arduino Cloud can be accessed via the left action bar. In the list below, some with links to a documentation pages. - -- **[Sketches](/arduino-cloud/cloud-interface/sketches)** - your sketches (programs) are stored here, divided into either a "normal" or "cloud" sketch. -- **[Devices](/arduino-cloud/hardware/devices)** - here you can configure your Arduino boards, ESP32 devices, manual devices (Python, JavaScript and more). -- **[Things](/arduino-cloud/cloud-interface/things)** - a Thing is a project configuration, where you select device, create variables to synchronize, and enter credentials. -- **[Dashboards](/arduino-cloud/cloud-interface/dashboard-widgets)** - dashboards are used to monitor & control your board through widgets. There's also a [mobile version](/arduino-cloud/iot-remote-app/getting-started) available to view your dashboards from a smartphone. -- **[Triggers](/arduino-cloud/cloud-interface/triggers)** - triggers can be used to send emails and push notifications based on a value change of a variable. -- **Resources** - helpful links and resources. You might have found this article here. -- **Courses** - tailored content for specific products and kits connected to the Arduino Cloud. -- **Templates** - templates are ready-made project that will automatically configure your device, Thing, -- **Integrations** - third party services that are integrated with the Arduino Cloud. - -## A Walkthrough the Arduino Cloud - -Setting up a project in the Arduino Cloud is easy, and can be done through a few simple steps summarized in this section. - -### 1. Create an Account - -To use the Arduino Cloud, you will need an Arduino account, which you can register [here](https://login.arduino.cc/login). - -By default, you will have a **free plan**, which can be upgraded to a number of affordable plans starting at 1.99$ a month. - -***Read more about [Arduino Cloud plans](https://cloud.arduino.cc/plans)*** - -### 2. Configure a Device - -First you will need to connect your board to your computer, and configure your device in the [Devices](https://app.arduino.cc/devices) tab. - -![Devices in the Arduino Cloud.](assets/device.png) - -The configurations varies between boards, but everything is covered in the installation wizard. - -***Learn more in the documentation for [Arduino Cloud Devices](/arduino-cloud/hardware/devices).*** - -### 3. Create a Thing - -After configuring a device, we can create a Thing, which is the **virtual twin** of your board. Here we configure network details, select device we want to associate and create the variables that we want to synchronize. - -![Things in the Arduino Cloud.](assets/thing.png) - -Variables we create will be used in the sketch, and will keep synchronizing as long as the board is connected to the cloud. - -When working with your IoT projects, consider this the "main space" for configurations, as you can access your sketches from here as well. - -***Learn more in the documentation for [Arduino Cloud Things](/arduino-cloud/cloud-interface/things).*** - -### 4. Write a Sketch - -Once you have done the above configurations, you can move on to **create a program/sketch**. This is where *you* decide what you want to create, and what data you want sent to the cloud. - -![A sketch in the Arduino Cloud.](assets/editor.png) - -When your program is ready, upload it to your board. If your board supports [Over-the-air (OTA)](/arduino-cloud/features/ota-getting-started) uploads, you can from now on upload without your board being connected to your computer! - -***Learn more in the documentation for [Arduino Cloud sketches](/arduino-cloud/cloud-interface/sketches).*** - -### 5. Create a Dashboard - -A dashboard allows you to interact with your device from a web interface or mobile app. A dashboard is composed of **widgets**, which you can link to a variable in your Thing. - -![Dashboards in the Arduino Cloud.](assets/dashboard.png) - -Choose from switches, sliders, RGB picker, message box, gauges and much more to create dashboards. Dashboards are not linked to a specific Thing/device, meaning you can control many different boards from the same dashboard. - -Some widgets can be linked to multiple variables, for example the [Advanced Chart](/arduino-cloud/cloud-interface/dashboard-widgets#advanced-chart) widget can graph up to 4 variables from different boards simultaneously! - -***Learn more in the documentation for [Arduino Cloud dashboards](/arduino-cloud/cloud-interface/dashboard-widgets).*** - -### 6. Track Your Project - -Once you done all configurations, created a program & dashboard, you can sit back and monitor & interact with your project from the web interface or the mobile app. - -![Arduino Cloud Dashboard & IoT Remote App](assets/dashboard-app.png) - -## Guides - -We recommend checking out the following guides to get started with various coding frameworks: -- [Arduino / C++ setup (default setup)](/arduino-cloud/guides/arduino-c) - the default installation using the built-in code editor and an Arduino / ESP32 board. -- [Python setup](/arduino-cloud/guides/python) - set up of a manual device to run on a PC / Linux system such as Raspberry Pi. -- [MicroPython setup](/arduino-cloud/guides/micropython) - setup of MicroPython on a select number of supported boards. -- [JavaScript / node.js setup](/arduino-cloud/guides/javascript) - setup of JavaScript using node.js, perfect for integrating your front-end projects with the Arduino Cloud. - -## Features - -Make sure to explore the various features of the Arduino Cloud through the links below: -- [**Data Monitoring**](/arduino-cloud/application-notes/cloud-environmental-data) - learn how to easily monitor environmental sensor values through a dashboard. -- [**Variable Synchronisation**](/arduino-cloud/features/thing-to-thing) - variable synchronisation allows you to sync variables across devices, enabling communication between devices with minimal coding. -- [**Scheduler**](/arduino-cloud/features/cloud-scheduler) - schedule jobs to go on/off for a specific amount of time (seconds, minutes, hours). -- [**Over-The-Air (OTA) Uploads**](/arduino-cloud/features/ota-getting-started) - upload code to devices not connected to your computer. -- [**Webhooks**](/arduino-cloud/features/webhooks) - integrate your project with another service, such as IFTTT. -- [**Amazon Alexa Support**](/arduino-cloud/guides/alexa) - make your project voice controlled with the Amazon Alexa integration. +--- +title: 'Getting Started with Arduino Cloud' +description: 'Get started with the Arduino Cloud, an online platform that makes it easy for you to code, deploy and monitor IoT projects.' +tags: [Arduino Cloud, Getting Started] +author: 'Karl Söderby' +--- + +The [Arduino Cloud](https://app.arduino.cc/) is a platform for developing Arduino projects and connecting them to the world. It supports secure connections with boards via [Wi-Fi®](/arduino-cloud/hardware/wifi), [LoRa®](/arduino-cloud/hardware/lora), [Ethernet](/arduino-cloud/hardware/ethernet) and [Cellular (GSM/NB-IoT)](/arduino-cloud/hardware/cellular), and lets you create a system for sending any variable information you can think of from one board to another within minutes of unboxing them. + +The Arduino Cloud platform includes: +- an **Integrated Development Environment (IDE)** for programming your boards, +- a **cloud backend service** for synchronizing data from Arduino boards, but also from [Python](/arduino-cloud/guides/python) & [JavaScript](/arduino-cloud/guides/javascript) clients, +- a **graphical tool (dashboard)** for controlling and monitoring your board (as well as an [mobile app](/arduino-cloud/iot-remote-app/getting-started)). +- [REST API](/arduino-cloud/api/arduino-iot-api) and [command line tools](/arduino-cloud/arduino-cloud-cli/getting-started) for larger scale automations. + +Very simply explained, with the Arduino Cloud you can: +1. Create a program for an Arduino based on a brilliant idea you just hatched. +2. Upload the program to your board and synchronize any data you want to (most commonly through Wi-Fi®). +3. Create a dashboard with a set of widgets to control and monitor your data. + +Developing a sketch made for the Arduino Cloud is almost just like developing any other sketch. You have your setup, and loop just like normal. But you are also able to select variables to be automatically synced to the Arduino Cloud. + +Once a variable is synced to the Arduino Cloud you can access it from any of your other devices connected to the Arduino Cloud. + +Once you have setup your project, this is how you could interact & monitor it. + +For example, turning ON / OFF a light connected to a device would work like this: + +![Interacting with your device](assets/overview-interaction.png) + +And if you want to read the value of a sensor connected to your device, it would work like this: + +![Monitoring your device.](assets/overview-monitor.png) + +Networking code and data synchronizing is **automatically done**, so just focus on the project, and let the Arduino Cloud handle the rest. + +***This document will help you get familiar with the [Arduino Cloud](https://app.arduino.cc/) service, and once you've got a good hang of it, you can explore the [rest of the documentation](/arduino-cloud/).*** + +## Compatible Boards + +***Throughout the documentation, we will often refer to a "board" as a "device". A board is your physical hardware or virtual setup (Python/JS), and a "device" is how it is configured in the Cloud.*** + +Compatibility with the Arduino Cloud is divided into two categories: +- **Cloud Editor Support** - you can program **any** official Arduino board in the Cloud editor. The editor also supports a large amount of third party boards. +- **IoT Support** - board with a radio module (e.g. Wi-Fi®) are supported. ESP32 based boards are also supported. + +For more information and list of supported boards, see the links below: +- [Wi-Fi®](/arduino-cloud/hardware/wifi) +- [LoRa®](/arduino-cloud/hardware/lora) +- [Ethernet](/arduino-cloud/hardware/ethernet) +- [Cellular (GSM/NB-IoT)](/arduino-cloud/hardware/cellular). + +***You can also create something called [manual devices](/arduino-cloud/hardware/devices#manual-devices), which allows you to create a virtual instance directly on your computer using JavaScript, Python or MicroPython.*** + +## Overview + +![The Arduino Cloud home page.](assets/home.png) + +Anything in the Arduino Cloud can be accessed via the left action bar. In the list below, some with links to a documentation pages. + +- **[Sketches](/arduino-cloud/cloud-interface/sketches)** - your sketches (programs) are stored here, divided into either a "normal" or "cloud" sketch. +- **[Devices](/arduino-cloud/hardware/devices)** - here you can configure your Arduino boards, ESP32 devices, manual devices (Python, JavaScript and more). +- **[Things](/arduino-cloud/cloud-interface/things)** - a Thing is a project configuration, where you select device, create variables to synchronize, and enter credentials. +- **[Dashboards](/arduino-cloud/cloud-interface/dashboard-widgets)** - dashboards are used to monitor & control your board through widgets. There's also a [mobile version](/arduino-cloud/iot-remote-app/getting-started) available to view your dashboards from a smartphone. +- **[Triggers](/arduino-cloud/cloud-interface/triggers)** - triggers can be used to send emails and push notifications based on a value change of a variable. +- **Resources** - helpful links and resources. You might have found this article here. +- **Courses** - tailored content for specific products and kits connected to the Arduino Cloud. +- **Templates** - templates are ready-made project that will automatically configure your device, Thing, +- **Integrations** - third party services that are integrated with the Arduino Cloud. + +## A Walkthrough the Arduino Cloud + +Setting up a project in the Arduino Cloud is easy, and can be done through a few simple steps summarized in this section. + +### 1. Create an Account + +To use the Arduino Cloud, you will need an Arduino account, which you can register [here](https://login.arduino.cc/login). + +By default, you will have a **free plan**, which can be upgraded to a number of affordable plans starting at 1.99$ a month. + +***Read more about [Arduino Cloud plans](https://cloud.arduino.cc/plans)*** + +### 2. Configure a Device + +First you will need to connect your board to your computer, and configure your device in the [Devices](https://app.arduino.cc/devices) tab. + +![Devices in the Arduino Cloud.](assets/device.png) + +The configurations varies between boards, but everything is covered in the installation wizard. + +***Learn more in the documentation for [Arduino Cloud Devices](/arduino-cloud/hardware/devices).*** + +### 3. Create a Thing + +After configuring a device, we can create a Thing, which is the **virtual twin** of your board. Here we configure network details, select device we want to associate and create the variables that we want to synchronize. + +![Things in the Arduino Cloud.](assets/thing.png) + +Variables we create will be used in the sketch, and will keep synchronizing as long as the board is connected to the Cloud. + +When working with your IoT projects, consider this the "main space" for configurations, as you can access your sketches from here as well. + +***Learn more in the documentation for [Arduino Cloud Things](/arduino-cloud/cloud-interface/things).*** + +### 4. Write a Sketch + +Once you have done the above configurations, you can move on to **create a program/sketch**. This is where *you* decide what you want to create, and what data you want sent to the Cloud. + +![A sketch in the Arduino Cloud.](assets/editor.png) + +When your program is ready, upload it to your board. If your board supports [Over-the-air (OTA)](/arduino-cloud/features/ota-getting-started) uploads, you can from now on upload without your board being connected to your computer! + +***Learn more in the documentation for [Arduino Cloud sketches](/arduino-cloud/cloud-interface/sketches).*** + +### 5. Create a Dashboard + +A dashboard allows you to interact with your device from a web interface or mobile app. A dashboard is composed of **widgets**, which you can link to a variable in your Thing. + +![Dashboards in the Arduino Cloud.](assets/dashboard.png) + +Choose from switches, sliders, RGB picker, message box, gauges and much more to create dashboards. Dashboards are not linked to a specific Thing/device, meaning you can control many different boards from the same dashboard. + +Some widgets can be linked to multiple variables, for example the [Advanced Chart](/arduino-cloud/cloud-interface/dashboard-widgets#advanced-chart) widget can graph up to 4 variables from different boards simultaneously! + +***Learn more in the documentation for [Arduino Cloud dashboards](/arduino-cloud/cloud-interface/dashboard-widgets).*** + +### 6. Track Your Project + +Once you done all configurations, created a program & dashboard, you can sit back and monitor & interact with your project from the web interface or the mobile app. + +![Arduino Cloud Dashboard & IoT Remote App](assets/dashboard-app.png) + +## Guides + +We recommend checking out the following guides to get started with various coding frameworks: +- [Arduino / C++ setup (default setup)](/arduino-cloud/guides/arduino-c) - the default installation using the built-in code editor and an Arduino / ESP32 board. +- [Python setup](/arduino-cloud/guides/python) - set up of a manual device to run on a PC / Linux system such as Raspberry Pi. +- [MicroPython setup](/arduino-cloud/guides/micropython) - setup of MicroPython on a select number of supported boards. +- [JavaScript / node.js setup](/arduino-cloud/guides/javascript) - setup of JavaScript using node.js, perfect for integrating your front-end projects with the Arduino Cloud. + +## Features + +Make sure to explore the various features of the Arduino Cloud through the links below: +- [**Data Monitoring**](/arduino-cloud/application-notes/cloud-environmental-data) - learn how to easily monitor environmental sensor values through a dashboard. +- [**Variable Synchronisation**](/arduino-cloud/features/thing-to-thing) - variable synchronisation allows you to sync variables across devices, enabling communication between devices with minimal coding. +- [**Scheduler**](/arduino-cloud/features/cloud-scheduler) - schedule jobs to go on/off for a specific amount of time (seconds, minutes, hours). +- [**Over-The-Air (OTA) Uploads**](/arduino-cloud/features/ota-getting-started) - upload code to devices not connected to your computer. +- [**Webhooks**](/arduino-cloud/features/webhooks) - integrate your project with another service, such as IFTTT. +- [**Amazon Alexa Support**](/arduino-cloud/guides/alexa) - make your project voice controlled with the Amazon Alexa integration. - [**Dashboard Sharing**](/arduino-cloud/features/sharing-dashboards) - share your data with other people around the world. \ No newline at end of file diff --git a/content/arduino-cloud/01.guides/02.arduino-c/arduino-c.md b/content/arduino-cloud/01.guides/02.arduino-c/arduino-c.md index ecb32df913..18525d7dfd 100644 --- a/content/arduino-cloud/01.guides/02.arduino-c/arduino-c.md +++ b/content/arduino-cloud/01.guides/02.arduino-c/arduino-c.md @@ -1,127 +1,127 @@ ---- -title: 'Arduino / C++' -description: 'Get started with the Arduino Cloud using the C++ programming language.' -tags: [Arduino Cloud, Setup] -author: 'Karl Söderby' ---- - -The default option for programming your board to connect to the Arduino Cloud is by using the **C++ language**. The configuration and connection between your board and the Arduino Cloud is supported by the [ArduinoIoTCloud library](https://github.com/arduino-libraries/ArduinoIoTCloud) & [Arduino_ConnectionHandler](https://github.com/arduino-libraries/Arduino_ConnectionHandler) libraries. - -***When programming in C++, you can use the Arduino API (which is also known as the Arduino Language). To learn more about the Arduino API, check out the [language reference](https://www.arduino.cc/reference/en/).*** - -Whenever you create a [Thing](/arduino-cloud/cloud-interface/things) in the Arduino Cloud, you automatically start generating a set of files that will handle the configurations, credentials & connection: -- `.ino` - your main sketch file, -- `thingProperties.h` - your main configuration file, -- `arduino_secrets.h` - your credentials file (for API key, Wi-Fi network etc.) - -***If you want to find out more about what the Arduino Cloud service can do, go to the [overview](/arduino-cloud/guides/overview) section.*** - -## Requirements - -For this guide, you will need to have a registered account at Arduino. Register through the link below: -- [Create an Arduino account](https://login.arduino.cc/login) - -You will also need a supported board: -- [Official Arduino Wi-Fi® boards](/arduino-cloud/hardware/wifi) -- [ESP32 / ESP8266 boards](/arduino-cloud/hardware/wifi#configure-esp-boards) -- [Official LoRaWAN® boards](/arduino-cloud/hardware/lora) -- [Official Ethernet setups](/arduino-cloud/hardware/ethernet) -- [Official cellular boards (GSM/NB-IoT)](/arduino-cloud/hardware/cellular) - -## Setup - -In this section, we will go through the steps necessary to connect your Arduino board to the Arduino Cloud. To follow these steps, please make sure you have a [registered Arduino account](https://login.arduino.cc/login), and that you have access to the [Arduino Cloud](https://app.arduino.cc/). - -### Configure Device - -First navigate to [Arduino Cloud](https://app.arduino.cc/), and click on the **Devices** tab. Here you can see all your devices, and configure a new one. Depending on what type of board you have, the configuration will vary. - -***For more details, see the [documentation for devices](/arduino-cloud/hardware/devices).*** - -### Configure Thing - -Next, navigate to the **Things** tab. Here you will see a list of your Things, and a button to create a new one. When you create a new Thing, you will open up a new configuration space. - -![Arduino Cloud Thing Interface](assets/thing-config.png) - -A "Thing" is a virtual twin of your hardware, and it is here that we create variables that we want to synchronize between the cloud and board. Any changes we make here will be reflected in an [automatically generated sketch](/arduino-cloud/cloud-interface/sketches#iot-sketches). - -1. First, let's attach the device we want to use, by clicking the **"Select Device"** button in the **"Associated Devices"** section to the right. -2. let's create a new variable, call it `test`, and select it to be a `boolean` type and with a **read/write** permission. -3. finally, configure your network in the **Network** section. Here you will enter your Wi-Fi® credentials, and if you are using an ESP32 based board, you need to enter the secret key here. - -![Enter network credentials.](assets/esp32-only.png) - -***Your secret key is obtained during the device configuration. Read more at [Configuring ESP boards](/arduino-cloud/hardware/wifi#configure-esp-boards).*** - -All the above configurations have now been generated into a set of files that can be accessed in the **Sketch** tab. - -***For more details, see the [documentation for Things](/arduino-cloud/cloud-interface/things).*** - -### Create Sketch - -The automatically generated sketch is now available to be edited. This sketch includes all necessities to connect to the cloud, and has a callback function generated for each **read/write** variable. - -Below is a sketch generated for a single `boolean` variable called `test`. We modified it to turn on/off the built-in LED of the board anytime the `test` bool is `true`. - -```arduino -#include "thingProperties.h" - -void setup() { - pinMode(LED_BUILTIN, OUTPUT); - - Serial.begin(9600); - delay(1500); - - initProperties(); - - ArduinoCloud.begin(ArduinoIoTPreferredConnection); - - setDebugMessageLevel(2); - ArduinoCloud.printDebugInfo(); -} - -void loop() { - ArduinoCloud.update(); -} - -void onTestChange() { - if(test){ - digitalWrite(LED_BUILTIN, HIGH); - } - else{ - digitalWrite(LED_BUILTIN, LOW); - } -} -``` - -- The sketch is automatically updated whenever you change your Thing (e.g. adding a variable, changing device), -- **Read/Write** permission variables adds a callback function to the bottom of your code. This function executes whenever the variable changes, -- the `ArduinoCloud.update()` function synchronises data between the board and cloud. -- if we update the `test` variable in the sketch, if it is connected to the cloud, we will see the change there as well. - -### Compile & Upload - -When our sketch is ready, we can **compile & upload** our sketch to our board. This process can take some time, depending on how large your sketch is. - -1. First make sure that you have the [Create Agent](https://create.arduino.cc/getting-started/plugin/welcome) installed. This allows Arduino Cloud to communicate with your board in the web interface. -2. Check that your board is connected and visible in the board selection menu. -3. Click the verify/upload button. -4. Wait until the code has successfully been uploaded. -5. Open the serial monitor tool to check for debug messages. If your board is failing to connect, it will print the errors here. - -### Verify Connection - -After a complete upload, you can verify the connection by checking the Thing interface. Here you can see the latest value & time stamp, as well as your device status (online/offline). - -In this case, we have just a single boolean variable named `test`, which is used to switch the state of the built-in LED. - -To control the state of the `test` variable, we can setup a **dashboard** and a **switch widget**. This will allow us to control the LED remotely. - -1. Go to **Dashboards**, and create a new dashboard. -2. Click on the edit button at the top left, then on the **"Add"** button. Select the Thing you want to associate it with, and then click on **"Create Widgets"**. -3. A switch widget will have generated, which is now linked to your board. Flicking it should control the state of the LED (on/off). - -![Dashboard in the Arduino Cloud.](assets/dashboard.png) - +--- +title: 'Arduino / C++' +description: 'Get started with the Arduino Cloud using the C++ programming language.' +tags: [Arduino Cloud, Setup] +author: 'Karl Söderby' +--- + +The default option for programming your board to connect to the Arduino Cloud is by using the **C++ language**. The configuration and connection between your board and the Arduino Cloud is supported by the [ArduinoIoTCloud library](https://github.com/arduino-libraries/ArduinoIoTCloud) & [Arduino_ConnectionHandler](https://github.com/arduino-libraries/Arduino_ConnectionHandler) libraries. + +***When programming in C++, you can use the Arduino API (which is also known as the Arduino Language). To learn more about the Arduino API, check out the [language reference](https://www.arduino.cc/reference/en/).*** + +Whenever you create a [Thing](/arduino-cloud/cloud-interface/things) in the Arduino Cloud, you automatically start generating a set of files that will handle the configurations, credentials & connection: +- `.ino` - your main sketch file, +- `thingProperties.h` - your main configuration file, +- `arduino_secrets.h` - your credentials file (for API key, Wi-Fi network etc.) + +***If you want to find out more about what the Arduino Cloud service can do, go to the [overview](/arduino-cloud/guides/overview) section.*** + +## Requirements + +For this guide, you will need to have a registered account at Arduino. Register through the link below: +- [Create an Arduino account](https://login.arduino.cc/login) + +You will also need a supported board: +- [Official Arduino Wi-Fi® boards](/arduino-cloud/hardware/wifi) +- [ESP32 / ESP8266 boards](/arduino-cloud/hardware/wifi#configure-esp-boards) +- [Official LoRaWAN® boards](/arduino-cloud/hardware/lora) +- [Official Ethernet setups](/arduino-cloud/hardware/ethernet) +- [Official cellular boards (GSM/NB-IoT)](/arduino-cloud/hardware/cellular) + +## Setup + +In this section, we will go through the steps necessary to connect your Arduino board to the Arduino Cloud. To follow these steps, please make sure you have a [registered Arduino account](https://login.arduino.cc/login), and that you have access to the [Arduino Cloud](https://app.arduino.cc/). + +### Configure Device + +First navigate to [Arduino Cloud](https://app.arduino.cc/), and click on the **Devices** tab. Here you can see all your devices, and configure a new one. Depending on what type of board you have, the configuration will vary. + +***For more details, see the [documentation for devices](/arduino-cloud/hardware/devices).*** + +### Configure Thing + +Next, navigate to the **Things** tab. Here you will see a list of your Things, and a button to create a new one. When you create a new Thing, you will open up a new configuration space. + +![Arduino Cloud Thing Interface](assets/thing-config.png) + +A "Thing" is a virtual twin of your hardware, and it is here that we create variables that we want to synchronize between the Cloud and board. Any changes we make here will be reflected in an [automatically generated sketch](/arduino-cloud/cloud-interface/sketches#iot-sketches). + +1. First, let's attach the device we want to use, by clicking the **"Select Device"** button in the **"Associated Devices"** section to the right. +2. let's create a new variable, call it `test`, and select it to be a `boolean` type and with a **read/write** permission. +3. finally, configure your network in the **Network** section. Here you will enter your Wi-Fi® credentials, and if you are using an ESP32 based board, you need to enter the secret key here. + +![Enter network credentials.](assets/esp32-only.png) + +***Your secret key is obtained during the device configuration. Read more at [Configuring ESP boards](/arduino-cloud/hardware/wifi#configure-esp-boards).*** + +All the above configurations have now been generated into a set of files that can be accessed in the **Sketch** tab. + +***For more details, see the [documentation for Things](/arduino-cloud/cloud-interface/things).*** + +### Create Sketch + +The automatically generated sketch is now available to be edited. This sketch includes all necessities to connect to the Cloud, and has a callback function generated for each **read/write** variable. + +Below is a sketch generated for a single `boolean` variable called `test`. We modified it to turn on/off the built-in LED of the board anytime the `test` bool is `true`. + +```arduino +#include "thingProperties.h" + +void setup() { + pinMode(LED_BUILTIN, OUTPUT); + + Serial.begin(9600); + delay(1500); + + initProperties(); + + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); +} + +void loop() { + ArduinoCloud.update(); +} + +void onTestChange() { + if(test){ + digitalWrite(LED_BUILTIN, HIGH); + } + else{ + digitalWrite(LED_BUILTIN, LOW); + } +} +``` + +- The sketch is automatically updated whenever you change your Thing (e.g. adding a variable, changing device), +- **Read/Write** permission variables adds a callback function to the bottom of your code. This function executes whenever the variable changes, +- the `ArduinoCloud.update()` function synchronises data between the board and Cloud. +- if we update the `test` variable in the sketch, if it is connected to the Cloud, we will see the change there as well. + +### Compile & Upload + +When our sketch is ready, we can **compile & upload** our sketch to our board. This process can take some time, depending on how large your sketch is. + +1. First make sure that you have the [Create Agent](https://create.arduino.cc/getting-started/plugin/welcome) installed. This allows Arduino Cloud to communicate with your board in the web interface. +2. Check that your board is connected and visible in the board selection menu. +3. Click the verify/upload button. +4. Wait until the code has successfully been uploaded. +5. Open the serial monitor tool to check for debug messages. If your board is failing to connect, it will print the errors here. + +### Verify Connection + +After a complete upload, you can verify the connection by checking the Thing interface. Here you can see the latest value & time stamp, as well as your device status (online/offline). + +In this case, we have just a single boolean variable named `test`, which is used to switch the state of the built-in LED. + +To control the state of the `test` variable, we can setup a **dashboard** and a **switch widget**. This will allow us to control the LED remotely. + +1. Go to **Dashboards**, and create a new dashboard. +2. Click on the edit button at the top left, then on the **"Add"** button. Select the Thing you want to associate it with, and then click on **"Create Widgets"**. +3. A switch widget will have generated, which is now linked to your board. Flicking it should control the state of the LED (on/off). + +![Dashboard in the Arduino Cloud.](assets/dashboard.png) + ***You can find more details in the [dashboards documentation](/arduino-cloud/cloud-interface/dashboard-widgets).*** \ No newline at end of file diff --git a/content/arduino-cloud/01.guides/03.esp32/esp32.md b/content/arduino-cloud/01.guides/03.esp32/esp32.md index 0c58069715..44a432fe9c 100644 --- a/content/arduino-cloud/01.guides/03.esp32/esp32.md +++ b/content/arduino-cloud/01.guides/03.esp32/esp32.md @@ -1,123 +1,123 @@ ---- -title: ESP32 / ESP8266 -description: Learn how to set up ESP32/ESP8266 based boards in the Arduino Cloud. -tags: [ESP32, ESP8266, Arduino Cloud] -author: Karl Söderby ---- - -Arduino Cloud supports a wide range of ESP32 / ESP8266 based development boards. The ESP chips are great for any IoT project, and they can be programmed using the Arduino language (C++). - -Setting up ESP based boards in the Arduino Cloud is quick and simple. It is done by generating a **Device ID** and **Secret Key**, which together with your Wi-Fi® credentials is enough to connect to the Arduino Cloud. - -This guide will show you how to set up a generic ESP32/ESP8266 board to communicate with the Arduino Cloud. - -***The official guide for connecting to Arduino Cloud using the C++ environment is found [here](/arduino-cloud/guides/arduino-c). This article is specifically for connecting ESP32/ESP8266 development boards.*** - -## Requirements - -For this guide, you will need to have a registered account at Arduino. Register through the link below: -- [Create an Arduino account](https://login.arduino.cc/login) - -You will also need a **ESP32 or ESP8266** development board. - -***ESP32 and ESP8266 boards are third-party boards. Arduino Cloud supports the both variations but cannot guarantee that certain boards based on these SoCs work. A list of tested and officially supported development boards can be found at [here](/arduino-cloud/hardware/wifi#list-of-supported-boards).*** - -## Setup - -In this section, we will go through the steps necessary to connect your ESP32 board to the Arduino Cloud. To follow these steps, please make sure you have a [registered Arduino account](https://login.arduino.cc/login), and that you have access to the [Arduino Cloud](https://app.arduino.cc/). - -### Configure Device - -First navigate to [Arduino Cloud - Devices](https://app.arduino.cc/devices). Here you can see all your devices, and configure a new one. - -1. Click on **"Add Device"** -2. Select **"Third Party Device"** -3. Choose your board from the list (if not there, choose e.g. `ESP32S3 Dev Board`). -4. Name your board, e.g. `Device_ESP32_LivingRoom`. -5. Save your **Device ID** and **Secret Key**. This will be used to connect to the Arduino Cloud. - -***More details on this step is available in the [Setup ESP32/ESP8266 devices.](#setup-esp32esp8266-boards)*** - -### Configure Thing - -Next, navigate to the **Things** tab. Here you will see a list of your Things, and a button to create a new one. When you create a new Thing, you will open up a new configuration space. - -![Arduino Cloud Thing Interface](assets/thing-config.png) - -A "Thing" is a virtual twin of your hardware, and it is here that we create variables that we want to synchronize between the cloud and board. Any changes we make here will be reflected in an [automatically generated sketch](/arduino-cloud/cloud-interface/sketches#iot-sketches). - -1. First, let's attach the device we want to use, by clicking the **"Select Device"** button in the **"Associated Devices"** section to the right. -2. let's create a new variable, call it `test`, and select it to be a `boolean` type and with a **read/write** permission. -3. finally, configure your network in the **Network** section. Here you will enter your Wi-Fi® credentials, and your **Secret Key**, obtained when configuring your device. - -![Enter network credentials.](assets/esp32-only.png) - -All the above configurations have now been generated into a set of files that can be accessed in the **Sketch** tab. - -***For more details, see the [documentation for Things](/arduino-cloud/cloud-interface/things).*** - -The automatically generated sketch is now available to be edited. This sketch includes all necessities to connect to the cloud, and has a callback function generated for each **read/write** variable. - -Below is a sketch generated for a single `boolean` variable called `test`. We modified it to turn on/off the built-in LED of the board anytime the `test` bool is `true`. - -```arduino -#include "thingProperties.h" - -void setup() { - pinMode(LED_BUILTIN, OUTPUT); - - Serial.begin(9600); - delay(1500); - - initProperties(); - - ArduinoCloud.begin(ArduinoIoTPreferredConnection); - - setDebugMessageLevel(2); - ArduinoCloud.printDebugInfo(); -} - -void loop() { - ArduinoCloud.update(); -} - -void onTestChange() { - if(test){ - digitalWrite(LED_BUILTIN, HIGH); - } - else{ - digitalWrite(LED_BUILTIN, LOW); - } -} -``` - -- The sketch is automatically updated whenever you change your Thing (e.g. adding a variable, changing device), -- **Read/Write** permission variables adds a callback function to the bottom of your code. This function executes whenever the variable changes, -- the `ArduinoCloud.update()` function synchronises data between the board and cloud. -- if we update the `test` variable in the sketch, if it is connected to the cloud, we will see the change there as well. - -### Compile & Upload - -When our sketch is ready, we can **compile & upload** our sketch to our board. This process can take some time, depending on how large your sketch is. - -1. First make sure that you have the [Create Agent](https://create.arduino.cc/getting-started/plugin/welcome) installed. This allows Arduino Cloud to communicate with your board in the web interface. -2. Check that your board is connected and visible in the board selection menu. -3. Click the verify/upload button. -4. Wait until the code has successfully been uploaded. -5. Open the serial monitor tool to check for debug messages. If your board is failing to connect, it will print the errors here. - -### Verify Connection - -After a complete upload, you can verify the connection by checking the Thing interface. Here you can see the latest value & time stamp, as well as your device status (online/offline). - -In this case, we have just a single boolean variable named `test`, which is used to switch the state of the built-in LED. - -To control the state of the `test` variable, we can setup a **dashboard** and a **switch widget**. This will allow us to control the LED remotely. - -1. Go to **Dashboards**, and create a new dashboard. -2. Click on the edit button at the top left, then on the **"Add"** button. Select the Thing you want to associate it with, and then click on **"Create Widgets"**. -3. A switch widget will have generated, which is now linked to your board. Flicking it should control the state of the LED (on/off). - -![Dashboard in the Arduino Cloud.](assets/dashboard.png) - +--- +title: ESP32 / ESP8266 +description: Learn how to set up ESP32/ESP8266 based boards in the Arduino Cloud. +tags: [ESP32, ESP8266, Arduino Cloud] +author: Karl Söderby +--- + +Arduino Cloud supports a wide range of ESP32 / ESP8266 based development boards. The ESP chips are great for any IoT project, and they can be programmed using the Arduino language (C++). + +Setting up ESP based boards in the Arduino Cloud is quick and simple. It is done by generating a **Device ID** and **Secret Key**, which together with your Wi-Fi® credentials is enough to connect to the Arduino Cloud. + +This guide will show you how to set up a generic ESP32/ESP8266 board to communicate with the Arduino Cloud. + +***The official guide for connecting to Arduino Cloud using the C++ environment is found [here](/arduino-cloud/guides/arduino-c). This article is specifically for connecting ESP32/ESP8266 development boards.*** + +## Requirements + +For this guide, you will need to have a registered account at Arduino. Register through the link below: +- [Create an Arduino account](https://login.arduino.cc/login) + +You will also need a **ESP32 or ESP8266** development board. + +***ESP32 and ESP8266 boards are third-party boards. Arduino Cloud supports the both variations but cannot guarantee that certain boards based on these SoCs work. A list of tested and officially supported development boards can be found at [here](/arduino-cloud/hardware/wifi#list-of-supported-boards).*** + +## Setup + +In this section, we will go through the steps necessary to connect your ESP32 board to the Arduino Cloud. To follow these steps, please make sure you have a [registered Arduino account](https://login.arduino.cc/login), and that you have access to the [Arduino Cloud](https://app.arduino.cc/). + +### Configure Device + +First navigate to [Arduino Cloud - Devices](https://app.arduino.cc/devices). Here you can see all your devices, and configure a new one. + +1. Click on **"Add Device"** +2. Select **"Third Party Device"** +3. Choose your board from the list (if not there, choose e.g. `ESP32S3 Dev Board`). +4. Name your board, e.g. `Device_ESP32_LivingRoom`. +5. Save your **Device ID** and **Secret Key**. This will be used to connect to the Arduino Cloud. + +***More details on this step is available in the [Setup ESP32/ESP8266 devices.](#setup-esp32esp8266-boards)*** + +### Configure Thing + +Next, navigate to the **Things** tab. Here you will see a list of your Things, and a button to create a new one. When you create a new Thing, you will open up a new configuration space. + +![Arduino Cloud Thing Interface](assets/thing-config.png) + +A "Thing" is a virtual twin of your hardware, and it is here that we create variables that we want to synchronize between the Cloud and board. Any changes we make here will be reflected in an [automatically generated sketch](/arduino-cloud/cloud-interface/sketches#iot-sketches). + +1. First, let's attach the device we want to use, by clicking the **"Select Device"** button in the **"Associated Devices"** section to the right. +2. let's create a new variable, call it `test`, and select it to be a `boolean` type and with a **read/write** permission. +3. finally, configure your network in the **Network** section. Here you will enter your Wi-Fi® credentials, and your **Secret Key**, obtained when configuring your device. + +![Enter network credentials.](assets/esp32-only.png) + +All the above configurations have now been generated into a set of files that can be accessed in the **Sketch** tab. + +***For more details, see the [documentation for Things](/arduino-cloud/cloud-interface/things).*** + +The automatically generated sketch is now available to be edited. This sketch includes all necessities to connect to the Cloud, and has a callback function generated for each **read/write** variable. + +Below is a sketch generated for a single `boolean` variable called `test`. We modified it to turn on/off the built-in LED of the board anytime the `test` bool is `true`. + +```arduino +#include "thingProperties.h" + +void setup() { + pinMode(LED_BUILTIN, OUTPUT); + + Serial.begin(9600); + delay(1500); + + initProperties(); + + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); +} + +void loop() { + ArduinoCloud.update(); +} + +void onTestChange() { + if(test){ + digitalWrite(LED_BUILTIN, HIGH); + } + else{ + digitalWrite(LED_BUILTIN, LOW); + } +} +``` + +- The sketch is automatically updated whenever you change your Thing (e.g. adding a variable, changing device), +- **Read/Write** permission variables adds a callback function to the bottom of your code. This function executes whenever the variable changes, +- the `ArduinoCloud.update()` function synchronises data between the board and Cloud. +- if we update the `test` variable in the sketch, if it is connected to the Cloud, we will see the change there as well. + +### Compile & Upload + +When our sketch is ready, we can **compile & upload** our sketch to our board. This process can take some time, depending on how large your sketch is. + +1. First make sure that you have the [Create Agent](https://create.arduino.cc/getting-started/plugin/welcome) installed. This allows Arduino Cloud to communicate with your board in the web interface. +2. Check that your board is connected and visible in the board selection menu. +3. Click the verify/upload button. +4. Wait until the code has successfully been uploaded. +5. Open the serial monitor tool to check for debug messages. If your board is failing to connect, it will print the errors here. + +### Verify Connection + +After a complete upload, you can verify the connection by checking the Thing interface. Here you can see the latest value & time stamp, as well as your device status (online/offline). + +In this case, we have just a single boolean variable named `test`, which is used to switch the state of the built-in LED. + +To control the state of the `test` variable, we can setup a **dashboard** and a **switch widget**. This will allow us to control the LED remotely. + +1. Go to **Dashboards**, and create a new dashboard. +2. Click on the edit button at the top left, then on the **"Add"** button. Select the Thing you want to associate it with, and then click on **"Create Widgets"**. +3. A switch widget will have generated, which is now linked to your board. Flicking it should control the state of the LED (on/off). + +![Dashboard in the Arduino Cloud.](assets/dashboard.png) + ***You can find more details in the [dashboards documentation](/arduino-cloud/cloud-interface/dashboard-widgets).*** \ No newline at end of file diff --git a/content/arduino-cloud/01.guides/04.micropython/content.md b/content/arduino-cloud/01.guides/04.micropython/content.md index ccdd03d444..5a41469212 100644 --- a/content/arduino-cloud/01.guides/04.micropython/content.md +++ b/content/arduino-cloud/01.guides/04.micropython/content.md @@ -1,226 +1,226 @@ ---- -title: 'MicroPython' -description: 'Learn how to connect to the Arduino Cloud using MicroPython.' -tags: - - Arduino Cloud - - IoT - - MicroPython -author: 'Sebastian Romero' -libraries: - - name: Arduino IoT Cloud Python - url: https://github.com/arduino/arduino-iot-cloud-py ---- - -## Introduction - -This tutorial guides you on how to use the MicroPython library to connect your Arduino device to the Arduino Cloud. - -It requires your board to have a version of MicroPython installed, which is covered in [this article](/micropython/basics/board-installation). - -To find our full MicroPython documentation, head over to the [MicroPython Docs](/micropython) page. - -## Goals - -The goals of this tutorial are: - -- Connect your Arduino device to your Wi-Fi® network. -- Connect your Arduino device to the Arduino Cloud via MicroPython. -- Control an LED using the Arduino Cloud. - -## Hardware & Software Needed - -- [Arduino Lab for MicroPython](https://labs.arduino.cc/en/labs/micropython) -- [Arduino GIGA R1 WiFi](/hardware/giga-r1-wifi) or [Portenta H7](/hardware/portenta-h7) -- [Nano ESP32](https://store.arduino.cc/products/nano-esp32) -- MicroPython >= 1.2 installed on your Arduino device. - -***To install MicroPython, read the [MicroPython Installation Guide](https://docs.arduino.cc/micropython/basics/board-installation) written for all Arduino boards.*** - -## Cloud Setup - -Before we start, make sure you have MicroPython installed on your board. If you haven't you can follow [this tutorial](https://docs.arduino.cc/micropython/basics/board-installation). - -Then, we need to configure a Thing in the [Arduino Cloud](https://app.arduino.cc/things) consisting of two boolean variables called `led` and `ledSwitch`. Follow the instructions below to do so. - -### Thing & Device Configuration - -1. Create a new Thing, by clicking on the **"Create Thing"** button. -2. Click on the **"Select Device"** in the **"Associated Devices"** section of your Thing. -3. Click on **"Set Up New Device"**, and select the bottom category (**"Manual Device"**). Click continue in the next window, and choose a name for your device. -4. Finally, you will see a new **Device ID** and a **Secret Key** generate. You can download them as a PDF. Make sure to save it as you cannot access your Secret Key again. - -![Device Key.](assets/device-key.png) - -- Learn more about Things in the [Things documentation](/arduino-cloud/cloud-interface/things) -- Learn more about Devices in the [Devices documentation](/arduino-cloud/hardware/devices) - -### Create Variables - -Next step is to create some cloud variables, which we will later interact with via a MicroPython script. - -1. While in Thing configuration, click on **"Add Variable"** which will open a new window. -2. Name your variable `led` and select it to be of an `boolean` type. -3. Click on **"Add Variable"** at the bottom of the window. -4. Create another variable, name it `ledSwitch` and select it to be `int` type. - -You should now have **two variables**: -- `led` - boolean -- `ledSwitch` - boolean - -It is important that they are named exactly like this, as we will be using them in the example script of this guide. - -Your Thing should look something like this when you are finished: - -![Finished Thing interface.](assets/thing.png) - -***Learn more about how variables work in the [Variables documentation](/arduino-cloud/cloud-interface/variables)*** - -### Create Dashboard - -When finished with creating your Thing, we also need to create a dashboard, a tool to monitor & interact with the cloud variables. - -1. Go to the [dashboards](https://app.arduino.cc/dashboards) section, and **create a new dashboard.** -2. In the dashboard, first create a **LED** widget, and link it to the `led` variable we created earlier. -3. Create a **Switch** widget, and link it to `ledSwitch`. -4. You should now have two widgets, looking something like the image below: - -![Dashboard with LED & Switch widgets.](assets/dashboard.png) - -We are now finished with the Arduino Cloud configuration, and we can proceed with the MicroPython setup. - -## MicroPython Setup - -In this section, we will install the [Arduino IoT Cloud Python](https://pypi.org/project/arduino-iot-cloud/) library on the Arduino board, and run a script that synchronizes the board with the Arduino Cloud. - -### Create Secret.py File - -During the [device configuration](#thing--device-configuration), you obtained a **device ID** and **secret key**. These details can be stored, along with your Wi-Fi® credentials, in a `secrets.py` file. Here is an example of how `secrets.py` should look like: - -```python -WIFI_SSID = "myNetwork" # Network SSID -WIFI_PASSWORD = "passwordForWiFi" # Network key -DEVICE_ID = b"ef77wer88-0432-4574-85e1-54e3d5cac861" -CLOUD_PASSWORD = b"TQHFHEKKKLSYMPB1OZLF" -``` - -In a MicroPython editor, you can create this file, and save it on your board running MicroPython. - -This file should be copied over to the flash drive that mounts when MicroPython boots. To do so you can use the file manager tool in Arduino Lab for MicroPython. Please note that the latter option is not recommended as the file system can potentially get corrupted when copying files manually. - -### Install Cloud Library - -To install the Arduino Cloud (Micro)Python library on your board, you can use the Python based tool `mpremote`. This requires Python to be installed. On macOS and Linux Python usually comes pre-installed. If it's not installed on your system you may download it from [here](https://www.python.org/downloads/). Then, to install `mpremote` you can use pip: - -```bash -$ pip install mpremote -``` - -Run `mpremote connect list` to retrieve the serial number of your device. The output will look similar to this: - -``` -/dev/cu.usbmodem3871345733302 335B34603532 2341:055b Arduino Portenta Virtual Comm Port in HS Mode -``` - -Pass this serial number (the second value) to the install command: - -```bash -$ mpremote connect id:335B34603532 mip install github:arduino/arduino-iot-cloud-py -``` - -This will install the library and all required dependencies on the board. -Another option is to manually copy the files from the library's [repository](https://github.com/arduino/arduino-iot-cloud-py/tree/main/src/arduino_iot_cloud) to the board's file system. It's good practice to put those files into a folder called `lib` to have the files organized neatly. - -For more options on how to install libraries on your board, check out our [Installing Modules Guide](/micropython/basics/installing-modules). - -## Programming the Board - -Here is the example code to copy and paste into your sketch. It connects your device - -```python -from machine import Pin -import time -import network -import logging -from arduino_iot_cloud import ArduinoCloudClient - -from secrets import WIFI_SSID -from secrets import WIFI_PASSWORD -from secrets import DEVICE_ID -from secrets import CLOUD_PASSWORD - -led = Pin("LEDB", Pin.OUT) # Configure the desired LED pin as an output. - -def on_switch_changed(client, value): - # Toggles the hardware LED on or off. - led.value(not value) - - # Sets the value of the cloud variable "led" to the current state of the LED - # and thus mirrors the hardware state in the cloud. - client["led"] = value - -def wifi_connect(): - if not WIFI_SSID or not WIFI_PASSWORD: - raise (Exception("Network is not configured. Set SSID and passwords in secrets.py")) - wlan = network.WLAN(network.STA_IF) - wlan.active(True) - wlan.connect(WIFI_SSID, WIFI_PASSWORD) - while not wlan.isconnected(): - logging.info("Trying to connect. Note this may take a while...") - time.sleep_ms(500) - logging.info(f"WiFi Connected {wlan.ifconfig()}") - -if __name__ == "__main__": - # Configure the logger. - # All message equal or higher to the logger level are printed. - # To see more debugging messages, set level=logging.DEBUG. - logging.basicConfig( - datefmt="%H:%M:%S", - format="%(asctime)s.%(msecs)03d %(message)s", - level=logging.INFO, - ) - - # NOTE: Add networking code here or in boot.py - wifi_connect() - - # Create a client object to connect to the Arduino IoT cloud. - # For MicroPython, the key and cert files must be stored in DER format on the filesystem. - # Alternatively, a username and password can be used to authenticate: - client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=CLOUD_PASSWORD) - - # Register cloud objects. - # Note: The following objects must be created first in the dashboard and linked to the device. - # This cloud object is initialized with its last known value from the cloud. When this object is updated - # from the dashboard, the on_switch_changed function is called with the client object and the new value. - client.register("ledSwitch", value=None, on_write=on_switch_changed, interval=0.250) - - # This cloud object is updated manually in the switch's on_write_change callback to update the LED state in the cloud. - client.register("led", value=None) - - # Start the Arduino IoT cloud client. - client.start() - -``` - -**Explanations:** - -- `wifi_connect()` - Connects to your local Wi-Fi® using the credentials specified in secrets.py. -- `client.register` - Registers a variable that will be synced with the cloud. -- `on_switch_changed` - Is the callback that gets executed when the `ledSwitch` variable is changed by toggling the switch on the cloud dashboard. This function in turn toggles the on-board LED and updates the cloud variable `led` that reflects the state of the on-board LED to be displayed in the cloud dashboard. -- `client.start()` - Enters a loop that runs as long as the board is connected to the cloud and synchronises data as it runs. - -## Testing It Out - -Open Arduino Lab for MicroPython and connect to your board. Pasting the above code and run the script. Then open your Arduino Cloud dashboard. You should see the registered "ledSwitch" and "led" widgets. Toggle the "ledSwitch", and the LED on your Arduino board should light up accordingly. The state of the "led" variable should also change, mirroring the state of the physical LED. - -## Troubleshoot - -If the code is not working, there are some common issues we can troubleshoot: - -- Make sure MicroPython >= 1.2 is installed on your board. -- Check the Wi-Fi® credentials in the `secrets.py` file. -- Ensure the device ID and Cloud password in the `secrets.py` file match with what is registered on the Arduino Cloud. -- Make sure your Arduino Cloud Thing is correctly set up and your device is assigned to it. - -## Conclusion - +--- +title: 'MicroPython' +description: 'Learn how to connect to the Arduino Cloud using MicroPython.' +tags: + - Arduino Cloud + - IoT + - MicroPython +author: 'Sebastian Romero' +libraries: + - name: Arduino IoT Cloud Python + url: https://github.com/arduino/arduino-iot-cloud-py +--- + +## Introduction + +This tutorial guides you on how to use the MicroPython library to connect your Arduino device to the Arduino Cloud. + +It requires your board to have a version of MicroPython installed, which is covered in [this article](/micropython/basics/board-installation). + +To find our full MicroPython documentation, head over to the [MicroPython Docs](/micropython) page. + +## Goals + +The goals of this tutorial are: + +- Connect your Arduino device to your Wi-Fi® network. +- Connect your Arduino device to the Arduino Cloud via MicroPython. +- Control an LED using the Arduino Cloud. + +## Hardware & Software Needed + +- [Arduino Lab for MicroPython](https://labs.arduino.cc/en/labs/micropython) +- [Arduino GIGA R1 WiFi](/hardware/giga-r1-wifi) or [Portenta H7](/hardware/portenta-h7) +- [Nano ESP32](https://store.arduino.cc/products/nano-esp32) +- MicroPython >= 1.2 installed on your Arduino device. + +***To install MicroPython, read the [MicroPython Installation Guide](https://docs.arduino.cc/micropython/basics/board-installation) written for all Arduino boards.*** + +## Cloud Setup + +Before we start, make sure you have MicroPython installed on your board. If you haven't you can follow [this tutorial](https://docs.arduino.cc/micropython/basics/board-installation). + +Then, we need to configure a Thing in the [Arduino Cloud](https://app.arduino.cc/things) consisting of two boolean variables called `led` and `ledSwitch`. Follow the instructions below to do so. + +### Thing & Device Configuration + +1. Create a new Thing, by clicking on the **"Create Thing"** button. +2. Click on the **"Select Device"** in the **"Associated Devices"** section of your Thing. +3. Click on **"Set Up New Device"**, and select the bottom category (**"Manual Device"**). Click continue in the next window, and choose a name for your device. +4. Finally, you will see a new **Device ID** and a **Secret Key** generate. You can download them as a PDF. Make sure to save it as you cannot access your Secret Key again. + +![Device Key.](assets/device-key.png) + +- Learn more about Things in the [Things documentation](/arduino-cloud/cloud-interface/things) +- Learn more about Devices in the [Devices documentation](/arduino-cloud/hardware/devices) + +### Create Variables + +Next step is to create some Cloud variables, which we will later interact with via a MicroPython script. + +1. While in Thing configuration, click on **"Add Variable"** which will open a new window. +2. Name your variable `led` and select it to be of an `boolean` type. +3. Click on **"Add Variable"** at the bottom of the window. +4. Create another variable, name it `ledSwitch` and select it to be `int` type. + +You should now have **two variables**: +- `led` - boolean +- `ledSwitch` - boolean + +It is important that they are named exactly like this, as we will be using them in the example script of this guide. + +Your Thing should look something like this when you are finished: + +![Finished Thing interface.](assets/thing.png) + +***Learn more about how variables work in the [Variables documentation](/arduino-cloud/cloud-interface/variables)*** + +### Create Dashboard + +When finished with creating your Thing, we also need to create a dashboard, a tool to monitor & interact with the Cloud variables. + +1. Go to the [dashboards](https://app.arduino.cc/dashboards) section, and **create a new dashboard.** +2. In the dashboard, first create a **LED** widget, and link it to the `led` variable we created earlier. +3. Create a **Switch** widget, and link it to `ledSwitch`. +4. You should now have two widgets, looking something like the image below: + +![Dashboard with LED & Switch widgets.](assets/dashboard.png) + +We are now finished with the Arduino Cloud configuration, and we can proceed with the MicroPython setup. + +## MicroPython Setup + +In this section, we will install the [Arduino IoT Cloud Python](https://pypi.org/project/arduino-iot-cloud/) library on the Arduino board, and run a script that synchronizes the board with the Arduino Cloud. + +### Create Secret.py File + +During the [device configuration](#thing--device-configuration), you obtained a **device ID** and **secret key**. These details can be stored, along with your Wi-Fi® credentials, in a `secrets.py` file. Here is an example of how `secrets.py` should look like: + +```python +WIFI_SSID = "myNetwork" # Network SSID +WIFI_PASSWORD = "passwordForWiFi" # Network key +DEVICE_ID = b"ef77wer88-0432-4574-85e1-54e3d5cac861" +CLOUD_PASSWORD = b"TQHFHEKKKLSYMPB1OZLF" +``` + +In a MicroPython editor, you can create this file, and save it on your board running MicroPython. + +This file should be copied over to the flash drive that mounts when MicroPython boots. To do so you can use the file manager tool in Arduino Lab for MicroPython. Please note that the latter option is not recommended as the file system can potentially get corrupted when copying files manually. + +### Install Cloud Library + +To install the Arduino Cloud (Micro)Python library on your board, you can use the Python based tool `mpremote`. This requires Python to be installed. On macOS and Linux Python usually comes pre-installed. If it's not installed on your system you may download it from [here](https://www.python.org/downloads/). Then, to install `mpremote` you can use pip: + +```bash +$ pip install mpremote +``` + +Run `mpremote connect list` to retrieve the serial number of your device. The output will look similar to this: + +``` +/dev/cu.usbmodem3871345733302 335B34603532 2341:055b Arduino Portenta Virtual Comm Port in HS Mode +``` + +Pass this serial number (the second value) to the install command: + +```bash +$ mpremote connect id:335B34603532 mip install github:arduino/arduino-iot-cloud-py +``` + +This will install the library and all required dependencies on the board. +Another option is to manually copy the files from the library's [repository](https://github.com/arduino/arduino-iot-cloud-py/tree/main/src/arduino_iot_cloud) to the board's file system. It's good practice to put those files into a folder called `lib` to have the files organized neatly. + +For more options on how to install libraries on your board, check out our [Installing Modules Guide](/micropython/basics/installing-modules). + +## Programming the Board + +Here is the example code to copy and paste into your sketch. It connects your device + +```python +from machine import Pin +import time +import network +import logging +from arduino_iot_cloud import ArduinoCloudClient + +from secrets import WIFI_SSID +from secrets import WIFI_PASSWORD +from secrets import DEVICE_ID +from secrets import CLOUD_PASSWORD + +led = Pin("LEDB", Pin.OUT) # Configure the desired LED pin as an output. + +def on_switch_changed(client, value): + # Toggles the hardware LED on or off. + led.value(not value) + + # Sets the value of the Cloud variable "led" to the current state of the LED + # and thus mirrors the hardware state in the Cloud. + client["led"] = value + +def wifi_connect(): + if not WIFI_SSID or not WIFI_PASSWORD: + raise (Exception("Network is not configured. Set SSID and passwords in secrets.py")) + wlan = network.WLAN(network.STA_IF) + wlan.active(True) + wlan.connect(WIFI_SSID, WIFI_PASSWORD) + while not wlan.isconnected(): + logging.info("Trying to connect. Note this may take a while...") + time.sleep_ms(500) + logging.info(f"WiFi Connected {wlan.ifconfig()}") + +if __name__ == "__main__": + # Configure the logger. + # All message equal or higher to the logger level are printed. + # To see more debugging messages, set level=logging.DEBUG. + logging.basicConfig( + datefmt="%H:%M:%S", + format="%(asctime)s.%(msecs)03d %(message)s", + level=logging.INFO, + ) + + # NOTE: Add networking code here or in boot.py + wifi_connect() + + # Create a client object to connect to the Arduino Cloud. + # For MicroPython, the key and cert files must be stored in DER format on the filesystem. + # Alternatively, a username and password can be used to authenticate: + client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=CLOUD_PASSWORD) + + # Register Cloud objects. + # Note: The following objects must be created first in the dashboard and linked to the device. + # This Cloud object is initialized with its last known value from the Cloud. When this object is updated + # from the dashboard, the on_switch_changed function is called with the client object and the new value. + client.register("ledSwitch", value=None, on_write=on_switch_changed, interval=0.250) + + # This Cloud object is updated manually in the switch's on_write_change callback to update the LED state in the Cloud. + client.register("led", value=None) + + # Start the Arduino Cloud client. + client.start() + +``` + +**Explanations:** + +- `wifi_connect()` - Connects to your local Wi-Fi® using the credentials specified in secrets.py. +- `client.register` - Registers a variable that will be synced with the Cloud. +- `on_switch_changed` - Is the callback that gets executed when the `ledSwitch` variable is changed by toggling the switch on the Cloud dashboard. This function in turn toggles the on-board LED and updates the Cloud variable `led` that reflects the state of the on-board LED to be displayed in the Cloud dashboard. +- `client.start()` - Enters a loop that runs as long as the board is connected to the Cloud and synchronises data as it runs. + +## Testing It Out + +Open Arduino Lab for MicroPython and connect to your board. Pasting the above code and run the script. Then open your Arduino Cloud dashboard. You should see the registered "ledSwitch" and "led" widgets. Toggle the "ledSwitch", and the LED on your Arduino board should light up accordingly. The state of the "led" variable should also change, mirroring the state of the physical LED. + +## Troubleshoot + +If the code is not working, there are some common issues we can troubleshoot: + +- Make sure MicroPython >= 1.2 is installed on your board. +- Check the Wi-Fi® credentials in the `secrets.py` file. +- Ensure the device ID and Cloud password in the `secrets.py` file match with what is registered on the Arduino Cloud. +- Make sure your Arduino Cloud Thing is correctly set up and your device is assigned to it. + +## Conclusion + This tutorial has guided you through the process of connecting your Arduino device to the Arduino Cloud using MicroPython. You learned how to install the necessary library, set up your device, and control an LED via the Arduino Cloud. This opens up possibilities for more complex applications, as you can control and monitor your Arduino device remotely. \ No newline at end of file diff --git a/content/arduino-cloud/01.guides/05.python/python.md b/content/arduino-cloud/01.guides/05.python/python.md index 1b1f953f12..c2e214e6c9 100644 --- a/content/arduino-cloud/01.guides/05.python/python.md +++ b/content/arduino-cloud/01.guides/05.python/python.md @@ -1,173 +1,173 @@ ---- -title: 'Python' -description: 'Learn how to use the Python library to connect to the Arduino Cloud.' -tags: - - IoT - - Python - - Arduino Cloud -author: 'Karl Söderby' -libraries: - - name: Arduino IoT Cloud Python - url: https://github.com/arduino/arduino-iot-cloud-py ---- - -***It is recommended to have some experience with the Python environment before reading this guide. However, installation and setup is covered in the [Python Setup](#python-setup) section.*** - -The [Arduino IoT Cloud Python Client](https://pypi.org/project/arduino-iot-cloud/) is a library that allows you to interact with the Arduino Cloud via MQTT. It supports basic authentication using the **device ID** as well as **secret key** that is obtained from the Arduino Cloud when configuring a manual device. - - -## Overview - -In this guide we will: -- Configure a manual device in the Arduino Cloud, -- install the Arduino IoT Cloud Python library, -- write a Python script that connects to the Arduino Cloud. - -## Requirements - -To follow this guide, make sure to have: - -- An [Arduino account](https://login.arduino.cc/login), -- a version of [Python](https://www.python.org/downloads/) installed, -- [pip](https://packaging.python.org/en/latest/tutorials/installing-packages/) package manager installed, -- [Arduino IoT Python Client](https://pypi.org/project/arduino-iot-client/) installed. -- A code editor (we recommend [VSCode](https://code.visualstudio.com/) with the Python extension installed). - -***The experience with Python and the pip package manager varies depending on your computer and operating system. Python needs to be in your PATH to use the Arduino IoT Cloud Python client.*** - -## Cloud Setup - -To begin with, we need to create a manual device, and create a new [Thing](/arduino-cloud/cloud-interface/things). Navigate to the [Arduino Cloud](https://app.arduino.cc/) and to the **"Things"** tab. - -### Thing & Device Configuration - -1. Create a new Thing, by clicking on the **"Create Thing"** button. -2. Click on the **"Select Device"** in the **"Associated Devices"** section of your Thing. -3. Click on **"Set Up New Device"**, and select the bottom category (**"Manual Device"**). Click continue in the next window, and choose a name for your device. -4. Finally, you will see a new **Device ID** and a **Secret Key** generate. You can download them as a PDF. Make sure to save it as you cannot access your Secret Key again. - -![Device ID & Secret key.](assets/device-key.png) - -- Learn more about Things in the [Things documentation](/arduino-cloud/cloud-interface/things) -- Learn more about Devices in the [Devices documentation](/arduino-cloud/hardware/devices) - -### Create Variables - -Next step is to create some cloud variables, which we will later interact with via a Python script. - -1. While in Thing configuration, click on **"Add Variable"** which will open a new window. -2. Name your variable `test_switch` and select it to be of an `boolean` type. -3. Click on **"Add Variable"** at the bottom of the window. -4. Create another variable, name it `test_value` and select it to be `int` type. - -You should now have **two variables**, `test_switch` and `test_value`. It is important that they are named exactly like this, as we will be using them in the example script of this guide. - -![Complete Thing.](assets/thing.png) - -- Learn more about how variables work in the [Variables documentation](/arduino-cloud/cloud-interface/variables) - -***Variables that we create here can also be synchronized with variables running on any other device in the platform. This makes it possible to link an Arduino boards with a Python or JavaScript project without writing any connection code!*** - -## Python Setup - -Before continuing, make sure you have a version of [Python](https://www.python.org/downloads/) installed. You can check this by opening a terminal and running: - -``` -python --version -python3 --version -``` - -### Install Packages - -To install the Arduino IoT Cloud Python client, run the following command: - -``` -pip install arduino-iot-cloud -``` - -You will also need to install the [swig](https://pypi.org/project/swig/) package. - -``` -pip install swig -``` - -To test out to see if your installation worked correctly, start the Python interpreter in your terminal by typing `python`, once running, test out this command: - -```python -from arduino_iot_cloud import ArduinoCloudClient -``` - -If you don't receive any import error, it means it is accessible and we can move on to testing out the example script. - -### Example Script - -The script below creates a client that connects to the Arduino Cloud and synchronizes the variable values. Make sure to enter your device credentials (see [Cloud Setup](#cloud-setup)) in the `DEVICE_ID` and `SECRET_KEY` variables. - -Create a python file, and name it something appropriate, such as `cloud_first_test.py`, and copy the contents of the code snippet below into it. - -```python -import time -import logging - -import sys -sys.path.append("lib") - -from arduino_iot_cloud import ArduinoCloudClient - -DEVICE_ID = b"YOUR_DEVICE_ID" -SECRET_KEY = b"YOUR_SECRET_KEY" - -def logging_func(): - logging.basicConfig( - datefmt="%H:%M:%S", - format="%(asctime)s.%(msecs)03d %(message)s", - level=logging.INFO, - ) - -# This function is executed each time the "test_switch" variable changes -def on_switch_changed(client, value): - print("Switch Pressed! Status is: ", value) - -if __name__ == "__main__": - - logging_func() - client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY) - - client.register("test_value") - client["test_value"] = 20 - client.register("test_switch", value=None, on_write=on_switch_changed) - - client.start() -``` - -- The script uses the `client.register()` to configure the variables. -- The `test_value` we simply set a static value of `20`. -- For the `test_switch` variable, we create a callback function that is triggered any time the value is updated. This can be controlled from a dashboard in the Arduino Cloud. - -To run this script, use the following command (or the "Run" button in VSCode): - -```python -python cloud_first_test.py -``` - -After running the script, you should see in the terminal that we first attempt to connect to the Arduino Cloud. Once connected, we push the variable update for `test_value`. You should now see this value updated in the Thing interface in the Arduino Cloud. - -![Value updated in the Arduino Cloud](assets/variable-update.png) - -You can test out the `test_switch` variable by creating a dashboard in the Arduino Cloud with a switch widget linked to the variable. Head over to "Dashboards" and create a value widget and a switch widget: - -![Control the switch from a dashboard.](assets/dashboard.png) - -When flicking the switch, you should see the following command being printed in the terminal: - -``` -Switch Pressed! Status is -``` - -For creating dashboards and linking variables, check out the [Dashboard & Widgets documentation](/arduino-cloud/cloud-interface/dashboard-widgets). - -### Troubleshooting - -- `command not found: python` - encountering this error when running a script indicates that the terminal can't access Python. You can try running `python3`, as some versions of Python requires this. -- `Connection failed 5, retrying after 1.0s` - this error is likely due to an invalid **device ID** or **secret key**. -- `ModuleNotFoundError: No module named '_m2crypto'` - likely if you are running an older version of the library. Try updating the library. +--- +title: 'Python' +description: 'Learn how to use the Python library to connect to the Arduino Cloud.' +tags: + - IoT + - Python + - Arduino Cloud +author: 'Karl Söderby' +libraries: + - name: Arduino IoT Cloud Python + url: https://github.com/arduino/arduino-iot-cloud-py +--- + +***It is recommended to have some experience with the Python environment before reading this guide. However, installation and setup is covered in the [Python Setup](#python-setup) section.*** + +The [Arduino IoT Cloud Python Client](https://pypi.org/project/arduino-iot-cloud/) is a library that allows you to interact with the Arduino Cloud via MQTT. It supports basic authentication using the **device ID** as well as **secret key** that is obtained from the Arduino Cloud when configuring a manual device. + + +## Overview + +In this guide we will: +- Configure a manual device in the Arduino Cloud, +- install the Arduino IoT Cloud Python library, +- write a Python script that connects to the Arduino Cloud. + +## Requirements + +To follow this guide, make sure to have: + +- An [Arduino account](https://login.arduino.cc/login), +- a version of [Python](https://www.python.org/downloads/) installed, +- [pip](https://packaging.python.org/en/latest/tutorials/installing-packages/) package manager installed, +- [Arduino IoT Python Client](https://pypi.org/project/arduino-iot-client/) installed. +- A code editor (we recommend [VSCode](https://code.visualstudio.com/) with the Python extension installed). + +***The experience with Python and the pip package manager varies depending on your computer and operating system. Python needs to be in your PATH to use the Arduino IoT Cloud Python client.*** + +## Cloud Setup + +To begin with, we need to create a manual device, and create a new [Thing](/arduino-cloud/cloud-interface/things). Navigate to the [Arduino Cloud](https://app.arduino.cc/) and to the **"Things"** tab. + +### Thing & Device Configuration + +1. Create a new Thing, by clicking on the **"Create Thing"** button. +2. Click on the **"Select Device"** in the **"Associated Devices"** section of your Thing. +3. Click on **"Set Up New Device"**, and select the bottom category (**"Manual Device"**). Click continue in the next window, and choose a name for your device. +4. Finally, you will see a new **Device ID** and a **Secret Key** generate. You can download them as a PDF. Make sure to save it as you cannot access your Secret Key again. + +![Device ID & Secret key.](assets/device-key.png) + +- Learn more about Things in the [Things documentation](/arduino-cloud/cloud-interface/things) +- Learn more about Devices in the [Devices documentation](/arduino-cloud/hardware/devices) + +### Create Variables + +Next step is to create some Cloud variables, which we will later interact with via a Python script. + +1. While in Thing configuration, click on **"Add Variable"** which will open a new window. +2. Name your variable `test_switch` and select it to be of an `boolean` type. +3. Click on **"Add Variable"** at the bottom of the window. +4. Create another variable, name it `test_value` and select it to be `int` type. + +You should now have **two variables**, `test_switch` and `test_value`. It is important that they are named exactly like this, as we will be using them in the example script of this guide. + +![Complete Thing.](assets/thing.png) + +- Learn more about how variables work in the [Variables documentation](/arduino-cloud/cloud-interface/variables) + +***Variables that we create here can also be synchronized with variables running on any other device in the platform. This makes it possible to link an Arduino boards with a Python or JavaScript project without writing any connection code!*** + +## Python Setup + +Before continuing, make sure you have a version of [Python](https://www.python.org/downloads/) installed. You can check this by opening a terminal and running: + +``` +python --version +python3 --version +``` + +### Install Packages + +To install the Arduino IoT Cloud Python client, run the following command: + +``` +pip install arduino-iot-cloud +``` + +You will also need to install the [swig](https://pypi.org/project/swig/) package. + +``` +pip install swig +``` + +To test out to see if your installation worked correctly, start the Python interpreter in your terminal by typing `python`, once running, test out this command: + +```python +from arduino_iot_cloud import ArduinoCloudClient +``` + +If you don't receive any import error, it means it is accessible and we can move on to testing out the example script. + +### Example Script + +The script below creates a client that connects to the Arduino Cloud and synchronizes the variable values. Make sure to enter your device credentials (see [Cloud Setup](#cloud-setup)) in the `DEVICE_ID` and `SECRET_KEY` variables. + +Create a python file, and name it something appropriate, such as `cloud_first_test.py`, and copy the contents of the code snippet below into it. + +```python +import time +import logging + +import sys +sys.path.append("lib") + +from arduino_iot_cloud import ArduinoCloudClient + +DEVICE_ID = b"YOUR_DEVICE_ID" +SECRET_KEY = b"YOUR_SECRET_KEY" + +def logging_func(): + logging.basicConfig( + datefmt="%H:%M:%S", + format="%(asctime)s.%(msecs)03d %(message)s", + level=logging.INFO, + ) + +# This function is executed each time the "test_switch" variable changes +def on_switch_changed(client, value): + print("Switch Pressed! Status is: ", value) + +if __name__ == "__main__": + + logging_func() + client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY) + + client.register("test_value") + client["test_value"] = 20 + client.register("test_switch", value=None, on_write=on_switch_changed) + + client.start() +``` + +- The script uses the `client.register()` to configure the variables. +- The `test_value` we simply set a static value of `20`. +- For the `test_switch` variable, we create a callback function that is triggered any time the value is updated. This can be controlled from a dashboard in the Arduino Cloud. + +To run this script, use the following command (or the "Run" button in VSCode): + +```python +python cloud_first_test.py +``` + +After running the script, you should see in the terminal that we first attempt to connect to the Arduino Cloud. Once connected, we push the variable update for `test_value`. You should now see this value updated in the Thing interface in the Arduino Cloud. + +![Value updated in the Arduino Cloud](assets/variable-update.png) + +You can test out the `test_switch` variable by creating a dashboard in the Arduino Cloud with a switch widget linked to the variable. Head over to "Dashboards" and create a value widget and a switch widget: + +![Control the switch from a dashboard.](assets/dashboard.png) + +When flicking the switch, you should see the following command being printed in the terminal: + +``` +Switch Pressed! Status is +``` + +For creating dashboards and linking variables, check out the [Dashboard & Widgets documentation](/arduino-cloud/cloud-interface/dashboard-widgets). + +### Troubleshooting + +- `command not found: python` - encountering this error when running a script indicates that the terminal can't access Python. You can try running `python3`, as some versions of Python requires this. +- `Connection failed 5, retrying after 1.0s` - this error is likely due to an invalid **device ID** or **secret key**. +- `ModuleNotFoundError: No module named '_m2crypto'` - likely if you are running an older version of the library. Try updating the library. diff --git a/content/arduino-cloud/01.guides/06.javascript/javascript.md b/content/arduino-cloud/01.guides/06.javascript/javascript.md index 91a9aad9ec..f47af26fc3 100644 --- a/content/arduino-cloud/01.guides/06.javascript/javascript.md +++ b/content/arduino-cloud/01.guides/06.javascript/javascript.md @@ -1,125 +1,125 @@ ---- -title: 'JavaScript' -description: 'Learn how to connect to the Arduino Cloud via JavaScript (node.js).' -tags: - - IoT - - JavaScript - - Arduino Cloud -author: 'Karl Söderby' ---- - -The [arduino-iot-js](https://www.npmjs.com/package/arduino-iot-js) library allows you to interact with the Arduino Cloud via MQTT. It supports basic authentication using the **device ID** as well as **secret key** that is obtained from the Arduino Cloud when configuring a manual device. - -## Overview - -In this guide we will: -- Configure a manual device in the Arduino Cloud, -- install the **arduino-iot-js** library, -- create a JavaScript example code that connects to the Arduino Cloud. - -## Requirements - -To follow this guide, make sure to have: - -- An [Arduino account](https://login.arduino.cc/login), -- a version of [node.js](https://nodejs.org/en/download/current) installed (confirmed to work with `v16.15.0`), -- [arduino-iot-js](https://www.npmjs.com/package/arduino-iot-js) installed. -- A code editor (we recommend [VSCode](https://code.visualstudio.com/)). - -## Cloud Setup - -To begin with, we need to create a manual device, and create a new [Thing](/arduino-cloud/cloud-interface/things). Navigate to the [Arduino Cloud](https://app.arduino.cc/) and to the **"Things"** tab. - -### Thing & Device Configuration - -1. Create a new Thing, by clicking on the **"Create Thing"** button. -2. Click on the **"Select Device"** in the **"Associated Devices"** section of your Thing. -3. Click on **"Set Up New Device"**, and select the bottom category (**"Manual Device"**). Click continue in the next window, and choose a name for your device. -4. Finally, you will see a new **Device ID** and a **Secret Key** generate. You can download them as a PDF. Make sure to save it as you cannot access your Secret Key again. - -![Device credentials.](assets/device-key.png) - -- Learn more about Things in the [Things documentation](/arduino-cloud/cloud-interface/things) -- Learn more about Devices in the [Devices documentation](/arduino-cloud/hardware/devices) - -### Create Variable - -Next step is to create a cloud variable, which we will later interact with in our JavaScript code. - -1. While in Thing configuration, click on **"Add Variable"** which will open a new window. -2. Name your variable `test_value` and select it to be of an `int` type. -3. Click on **"Add Variable"** at the bottom of the window. - -You should now have a variable named `test_value`. It is important that it is named exactly like this, as we will be using it in the example script of this guide. - -![Complete Thing.](assets/thing.png) - -- Learn more about how variables work in the [Variables documentation](/arduino-cloud/cloud-interface/variables) - -***Variables that we create here can also be synchronized with variables running on any other device in the platform. This makes it possible to link an Arduino boards with a Python or JavaScript project without writing any connection code!*** - -## JavaScript Setup - -Before continuing, make sure you have a version of [node.js](https://nodejs.org/en/download/current) installed. You can check that it is installed by opening a terminal and running: - -``` -node -v -``` - -### Install NPM Package - -The [arduino-iot-js](https://www.npmjs.com/package/arduino-iot-js) library can be installed by running the following command: - -``` -npm install arduino-iot-js -``` - -This will install the library in your current directory. You can check that the library is installed by running `npm list`. - -### Example Script - -Create a file with a `.js` extension, and call it something appropriate such as `cloud_first_test.js`. Note that it needs to be in the same directory as you installed the library. - -Below is a script that connects to the cloud using the **device ID** and **secret key** that we obtained in the [cloud setup](#cloud-setup) section. Copy the contents into your `.js` file. - -```javascript -const { ArduinoIoTCloud } = require('arduino-iot-js'); - -(async () => { - const client = await ArduinoIoTCloud.connect({ - deviceId: 'YOUR_DEVICE_ID', - secretKey: 'YOUR_SECRET_KEY', - onDisconnect: (message) => console.error(message), - }); - - const value = 20; - let cloudVar = "test_value" - - client.sendProperty(cloudVar, value); - console.log(cloudVar, ":", value); - - client.onPropertyValue(cloudVar, (value) => console.log(cloudVar, ":", value)); -})(); -``` - -- `sendProperty(cloudVar, value)` - update a variable in the cloud, -- `onPropertyValue(cloudVar, (value))` - when receiving an update from the Arduino Cloud, updates the `value` variable. - -This example simply sends an update to the Arduino Cloud (updating the value of `test_value` to `20`), and awaits any changes from the cloud. You can ensure it is working by checking your Thing interface as well: - -![Value in the Thing interface](assets/test_value.png) - -You can test out the `test_value` variable by creating a dashboard in the Arduino Cloud with a **value** widget linked to the variable. - -When entering a new number, you should see the following command being printed in the terminal: - -``` -test_value : -``` - -For creating dashboards and linking variables, check out the [Dashboard & Widgets documentation](/arduino-cloud/cloud-interface/dashboard-widgets). - -### Troubleshooting - -- `Error: Cannot find module` - the package is not installed/accessible from your current directory. Double check that your directory is correct and that you have successfully installed the package. +--- +title: 'JavaScript' +description: 'Learn how to connect to the Arduino Cloud via JavaScript (node.js).' +tags: + - IoT + - JavaScript + - Arduino Cloud +author: 'Karl Söderby' +--- + +The [arduino-iot-js](https://www.npmjs.com/package/arduino-iot-js) library allows you to interact with the Arduino Cloud via MQTT. It supports basic authentication using the **device ID** as well as **secret key** that is obtained from the Arduino Cloud when configuring a manual device. + +## Overview + +In this guide we will: +- Configure a manual device in the Arduino Cloud, +- install the **arduino-iot-js** library, +- create a JavaScript example code that connects to the Arduino Cloud. + +## Requirements + +To follow this guide, make sure to have: + +- An [Arduino account](https://login.arduino.cc/login), +- a version of [node.js](https://nodejs.org/en/download/current) installed (confirmed to work with `v16.15.0`), +- [arduino-iot-js](https://www.npmjs.com/package/arduino-iot-js) installed. +- A code editor (we recommend [VSCode](https://code.visualstudio.com/)). + +## Cloud Setup + +To begin with, we need to create a manual device, and create a new [Thing](/arduino-cloud/cloud-interface/things). Navigate to the [Arduino Cloud](https://app.arduino.cc/) and to the **"Things"** tab. + +### Thing & Device Configuration + +1. Create a new Thing, by clicking on the **"Create Thing"** button. +2. Click on the **"Select Device"** in the **"Associated Devices"** section of your Thing. +3. Click on **"Set Up New Device"**, and select the bottom category (**"Manual Device"**). Click continue in the next window, and choose a name for your device. +4. Finally, you will see a new **Device ID** and a **Secret Key** generate. You can download them as a PDF. Make sure to save it as you cannot access your Secret Key again. + +![Device credentials.](assets/device-key.png) + +- Learn more about Things in the [Things documentation](/arduino-cloud/cloud-interface/things) +- Learn more about Devices in the [Devices documentation](/arduino-cloud/hardware/devices) + +### Create Variable + +Next step is to create a Cloud variable, which we will later interact with in our JavaScript code. + +1. While in Thing configuration, click on **"Add Variable"** which will open a new window. +2. Name your variable `test_value` and select it to be of an `int` type. +3. Click on **"Add Variable"** at the bottom of the window. + +You should now have a variable named `test_value`. It is important that it is named exactly like this, as we will be using it in the example script of this guide. + +![Complete Thing.](assets/thing.png) + +- Learn more about how variables work in the [Variables documentation](/arduino-cloud/cloud-interface/variables) + +***Variables that we create here can also be synchronized with variables running on any other device in the platform. This makes it possible to link an Arduino boards with a Python or JavaScript project without writing any connection code!*** + +## JavaScript Setup + +Before continuing, make sure you have a version of [node.js](https://nodejs.org/en/download/current) installed. You can check that it is installed by opening a terminal and running: + +``` +node -v +``` + +### Install NPM Package + +The [arduino-iot-js](https://www.npmjs.com/package/arduino-iot-js) library can be installed by running the following command: + +``` +npm install arduino-iot-js +``` + +This will install the library in your current directory. You can check that the library is installed by running `npm list`. + +### Example Script + +Create a file with a `.js` extension, and call it something appropriate such as `cloud_first_test.js`. Note that it needs to be in the same directory as you installed the library. + +Below is a script that connects to the Cloud using the **device ID** and **secret key** that we obtained in the [cloud setup](#cloud-setup) section. Copy the contents into your `.js` file. + +```javascript +const { ArduinoIoTCloud } = require('arduino-iot-js'); + +(async () => { + const client = await ArduinoIoTCloud.connect({ + deviceId: 'YOUR_DEVICE_ID', + secretKey: 'YOUR_SECRET_KEY', + onDisconnect: (message) => console.error(message), + }); + + const value = 20; + let cloudVar = "test_value" + + client.sendProperty(cloudVar, value); + console.log(cloudVar, ":", value); + + client.onPropertyValue(cloudVar, (value) => console.log(cloudVar, ":", value)); +})(); +``` + +- `sendProperty(cloudVar, value)` - update a variable in the Cloud, +- `onPropertyValue(cloudVar, (value))` - when receiving an update from the Arduino Cloud, updates the `value` variable. + +This example simply sends an update to the Arduino Cloud (updating the value of `test_value` to `20`), and awaits any changes from the Cloud. You can ensure it is working by checking your Thing interface as well: + +![Value in the Thing interface](assets/test_value.png) + +You can test out the `test_value` variable by creating a dashboard in the Arduino Cloud with a **value** widget linked to the variable. + +When entering a new number, you should see the following command being printed in the terminal: + +``` +test_value : +``` + +For creating dashboards and linking variables, check out the [Dashboard & Widgets documentation](/arduino-cloud/cloud-interface/dashboard-widgets). + +### Troubleshooting + +- `Error: Cannot find module` - the package is not installed/accessible from your current directory. Double check that your directory is correct and that you have successfully installed the package. - `Error: connection failed: client not connected` - likely due to wrong credentials (device ID / secret key). Double check these parameters. \ No newline at end of file diff --git a/content/arduino-cloud/01.guides/07.node-red/nodered-intro.md b/content/arduino-cloud/01.guides/07.node-red/nodered-intro.md index 1d35927af3..d5f769fba4 100644 --- a/content/arduino-cloud/01.guides/07.node-red/nodered-intro.md +++ b/content/arduino-cloud/01.guides/07.node-red/nodered-intro.md @@ -31,7 +31,7 @@ In this tutorial, we will look into the applications of using Node-RED together - [Node.js](https://nodejs.org/en/) and [Node-RED installed](https://nodered.org/) - An [Arduino account](http://create.arduino.cc/iot). -For this tutorial, you will need a cloud compatible board. You will find all compatible boards in the link below: +For this tutorial, you will need a Cloud compatible board. You will find all compatible boards in the link below: - [Arduino Cloud compatible hardware.](/arduino-cloud/hardware/devices#type-of-devices) diff --git a/content/arduino-cloud/01.guides/08.alexa/alexa.md b/content/arduino-cloud/01.guides/08.alexa/alexa.md index fc02e758db..3068342118 100644 --- a/content/arduino-cloud/01.guides/08.alexa/alexa.md +++ b/content/arduino-cloud/01.guides/08.alexa/alexa.md @@ -1,172 +1,172 @@ ---- -title: 'Alexa' -description: 'Learn how to connect the Arduino Cloud with the Amazon Alexa service.' -tags: -- Amazon Alexa -author: 'Karl Söderby' -featuredImage: 'cloud' ---- - -## Introduction - - - -In this tutorial you will learn how to integrate the [Arduino Cloud](https://app.arduino.cc/) with the [Amazon Alexa skill](https://www.amazon.com/Arduino-LLC/dp/B07ZT2PK2H). At the end of this tutorial, we will be able to change the color of an RGB matrix connected to your Arduino, using only voice commands in the Alexa app. - -![The Alexa and Arduino Cloud integration.](assets/alexa-mkr-rgb-shield-img-08.png) - -This tutorial focuses on using the [MKR RGB Shield](https://store.arduino.cc/products/arduino-mkr-rgb-shield) but can easily be modified to use any other RGB pixels / matrices. - -***You can also find all variables that can be synchronized between Arduino Cloud and Alexa in the [Cloud Variables guide](/arduino-cloud/getting-started/cloud-variables#alexa-variables).*** - -## Goals - -The goals of this project are: - -- Set up the Arduino Cloud. -- Create a program that controls the RGB pixels. -- Install the Arduino Skill on the Alexa app. -- Sync the Arduino Cloud with Alexa. - -## Hardware & Software Needed - -- [Arduino Cloud](https://app.arduino.cc/) -- [Amazon Alexa skill](https://www.amazon.com/Arduino-LLC/dp/B07ZT2PK2H) -- \*[Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010). -- \*[MKR RGB Shield](https://store.arduino.cc/arduino-mkr-rgb-shield) or other RGB matrices. - -***\*You can use any supported Wi-Fi® board in this tutorial, but the example provided is made specifically for the MKR WiFi 1010 + MKR RGB Shield.*** - -## Circuit - -Simply mount the MKR RGB Shield on top of the MKR WiFi 1010. - -![Mounting the shield.](assets/alexa-mkr-rgb-shield-img-01.png) - -## Cloud Setup - -To set up the cloud, you will need to: -1. Log in to the [Arduino Cloud](https://login.arduino.cc/login). -2. Go to **"Things"** and create a new Thing. -3. Select and attach the device you want to use (or configure a new one). -4. Create a variable called `LoungeArea` and select it to be of a **colored light** type. This is the variable that will be used to store incoming data from the Alexa service. - -***If you are new to the Arduino Cloud, visit the [Arduino / C++ Setup Guide](/arduino-cloud/guides/arduino-c) which has detailed instructions on how to set up devices, configuring Things and more.*** - -### Example Sketch - -With all configurations done, we can move onto creating the program. By clicking on the **"Sketch"** tab, we can start editing the code that we will upload to our device. - -First we need to include two libraries called `ArduinoGraphics` and `Arduino_MKRRGB`. These will help us control the MKR RGB Shield. If you are using any other matrix or RGB pixel, you will need to adjust this example. - -When we later on will be connecting the cloud to Alexa, the data will be received directly from the Alexa app. Whenever the data updates, the `onLoungeAreaChange()` will execute, where it will fetch the data from Alexa (the RGB values) and display them on the RGB matrix. You can find the full code in the snippet below. - -```arduino -#include -#include -#include "thingProperties.h" - -void setup() { - Serial.begin(9600); - delay(1500); - - MATRIX.begin(); - MATRIX.brightness(10); - - initProperties(); - - ArduinoCloud.begin(ArduinoIoTPreferredConnection); - - setDebugMessageLevel(2); - ArduinoCloud.printDebugInfo(); -} - -void loop() { - ArduinoCloud.update(); - // No code required in the loop for this setup -} - - -void onLoungeAreaChange() { - uint8_t r, g, b; - loungeArea.getValue().getRGB(r, g, b); - if (loungeArea.getSwitch()) { - Serial.println("R:" + String(r) + " G:" + String(g) + " B:" + String(b)); //prints the current R, G, B values - MATRIX.beginDraw(); //starts a new "drawing" on the RGB shield's pixels - MATRIX.clear(); //clears the RGB shield's pixels - MATRIX.noStroke(); - MATRIX.fill(r, g, b); //the r, g, b values are fed into the shield's pixels - MATRIX.rect(0, 0, MATRIX.width(), MATRIX.height()); //creates a rectangle (this covers the entire matrix) - MATRIX.endDraw(); // ends the draw, and displays the new "drawing" - - } else { - Serial.println("Lamp Off"); - //the following code simply turns everything off - MATRIX.beginDraw(); - MATRIX.clear(); - MATRIX.noStroke(); - MATRIX.fill(0, 0, 0); - MATRIX.rect(0, 0, MATRIX.width(), MATRIX.height()); - MATRIX.endDraw(); - } -} -``` - -Upload the code in the snippet above to your board. You can check the Serial Monitor to make sure you have successfully connected to the Arduino Cloud. - -We can now move on to the next step: **setting up Alexa.** - -## Alexa Setup - -For this step, we will need the Amazon Alexa app which can be downloaded from the [Apple App Store](https://apps.apple.com/us/app/amazon-alexa/id944011620) or the [Google Play Store](https://play.google.com/store/apps/details?id=com.amazon.dee.app&hl=en). Once installed, login with your existing account or create a new one. - -### Installing the Arduino Alexa Skill - -Let's go through the steps necessary to install the Arduino Alexa Skill. - -![Installing the Alexa Skill.](assets/alexa_phone_1.png) - -1. Once in the Amazon Alexa app, begin by tapping on "Devices". -2. Tap on the "Enable Smart home skills" button. -3. We will now see a list of featured ones, where we need to search for the right skill. -4. If we search for "Arduino" we will see a skill that has that exact name. - -![Installing the Alexa skill part 2.](assets/alexa_phone_2.png) - -5. Once we have selected it, we'll need to enable it. -6. We now need to sync it with our Arduino Cloud, by logging into it. -7. Our Alexa and Arduino Cloud is now synced! -8. We can now start discovering our devices! - -![Looking for devices.](assets/alexa_phone_3.png) - -### Amazon Alexa Devices Setup - -After waiting a little bit, we should see a new screen appear, where it says **"1 light found and connected"**. - -Click **"Set Up Device"**. If you like you can also add it to a group (this way you can control and organize your devices more easily), otherwise skip this part. - -![Light found and connected.](assets/alexa-mkr-rgb-shield-img-06.png) - -Congratulations! You should now be able to control the lights through your Alexa app. - -## Controlling the Lights - -To control the lights on our setup, we will need to head over to the **"Devices"** tab in the Alexa app. Once in the Devices tab, click on the **"Lights"** button. We will now see the available lights. If you have other lights already connected, they will appear here as well. In our case, we only have one, which is `LoungeArea`, which is the same name as the variable we created earlier in the Arduino Cloud. If we click on `LoungeArea` we will access the color / brightness control. - -![Controlling the lights through the Alexa app.](assets/alexa-mkr-rgb-shield-img-07.png) - -Any changes of color / brightness you make will be sent to our MKR WiFi 1010, which will change the pixels on the MKR RGB Shield accordingly. - - -### Troubleshooting - -One great way of knowing if data is coming through from the Alexa app is by checking the Serial Monitor. The sketch that we uploaded to the board includes a command that prints out the value of **r, g** and **b** whenever they receive new data. If the board is successfully connecting to the cloud, it is most likely a problem on setting up the Alexa device. - -## Over-the-Air (OTA) - -Did you know that the Arduino Cloud supports over the air uploads? When you've uploaded a sketch to your board once, it will become available for you to upload a new sketch to the board without connecting it to your computer! - -***Over the Air uploads require an Entry plan to the Arduino Cloud*** - -To use this feature, make sure the board has power. If your board is already connected to the Arduino Cloud, you will be able to upload to it over the air. Navigate to the Things sketch tab in the Arduino Cloud interface, and you should see it being discovered just as if it was connected via USB. +--- +title: 'Alexa' +description: 'Learn how to connect the Arduino Cloud with the Amazon Alexa service.' +tags: +- Amazon Alexa +author: 'Karl Söderby' +featuredImage: 'cloud' +--- + +## Introduction + + + +In this tutorial you will learn how to integrate the [Arduino Cloud](https://app.arduino.cc/) with the [Amazon Alexa skill](https://www.amazon.com/Arduino-LLC/dp/B07ZT2PK2H). At the end of this tutorial, we will be able to change the color of an RGB matrix connected to your Arduino, using only voice commands in the Alexa app. + +![The Alexa and Arduino Cloud integration.](assets/alexa-mkr-rgb-shield-img-08.png) + +This tutorial focuses on using the [MKR RGB Shield](https://store.arduino.cc/products/arduino-mkr-rgb-shield) but can easily be modified to use any other RGB pixels / matrices. + +***You can also find all variables that can be synchronized between Arduino Cloud and Alexa in the [Cloud Variables guide](/arduino-cloud/getting-started/cloud-variables#alexa-variables).*** + +## Goals + +The goals of this project are: + +- Set up the Arduino Cloud. +- Create a program that controls the RGB pixels. +- Install the Arduino Skill on the Alexa app. +- Sync the Arduino Cloud with Alexa. + +## Hardware & Software Needed + +- [Arduino Cloud](https://app.arduino.cc/) +- [Amazon Alexa skill](https://www.amazon.com/Arduino-LLC/dp/B07ZT2PK2H) +- \*[Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010). +- \*[MKR RGB Shield](https://store.arduino.cc/arduino-mkr-rgb-shield) or other RGB matrices. + +***\*You can use any supported Wi-Fi® board in this tutorial, but the example provided is made specifically for the MKR WiFi 1010 + MKR RGB Shield.*** + +## Circuit + +Simply mount the MKR RGB Shield on top of the MKR WiFi 1010. + +![Mounting the shield.](assets/alexa-mkr-rgb-shield-img-01.png) + +## Cloud Setup + +To set up the Cloud, you will need to: +1. Log in to the [Arduino Cloud](https://login.arduino.cc/login). +2. Go to **"Things"** and create a new Thing. +3. Select and attach the device you want to use (or configure a new one). +4. Create a variable called `LoungeArea` and select it to be of a **colored light** type. This is the variable that will be used to store incoming data from the Alexa service. + +***If you are new to the Arduino Cloud, visit the [Arduino / C++ Setup Guide](/arduino-cloud/guides/arduino-c) which has detailed instructions on how to set up devices, configuring Things and more.*** + +### Example Sketch + +With all configurations done, we can move onto creating the program. By clicking on the **"Sketch"** tab, we can start editing the code that we will upload to our device. + +First we need to include two libraries called `ArduinoGraphics` and `Arduino_MKRRGB`. These will help us control the MKR RGB Shield. If you are using any other matrix or RGB pixel, you will need to adjust this example. + +When we later on will be connecting the Cloud to Alexa, the data will be received directly from the Alexa app. Whenever the data updates, the `onLoungeAreaChange()` will execute, where it will fetch the data from Alexa (the RGB values) and display them on the RGB matrix. You can find the full code in the snippet below. + +```arduino +#include +#include +#include "thingProperties.h" + +void setup() { + Serial.begin(9600); + delay(1500); + + MATRIX.begin(); + MATRIX.brightness(10); + + initProperties(); + + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); +} + +void loop() { + ArduinoCloud.update(); + // No code required in the loop for this setup +} + + +void onLoungeAreaChange() { + uint8_t r, g, b; + loungeArea.getValue().getRGB(r, g, b); + if (loungeArea.getSwitch()) { + Serial.println("R:" + String(r) + " G:" + String(g) + " B:" + String(b)); //prints the current R, G, B values + MATRIX.beginDraw(); //starts a new "drawing" on the RGB shield's pixels + MATRIX.clear(); //clears the RGB shield's pixels + MATRIX.noStroke(); + MATRIX.fill(r, g, b); //the r, g, b values are fed into the shield's pixels + MATRIX.rect(0, 0, MATRIX.width(), MATRIX.height()); //creates a rectangle (this covers the entire matrix) + MATRIX.endDraw(); // ends the draw, and displays the new "drawing" + + } else { + Serial.println("Lamp Off"); + //the following code simply turns everything off + MATRIX.beginDraw(); + MATRIX.clear(); + MATRIX.noStroke(); + MATRIX.fill(0, 0, 0); + MATRIX.rect(0, 0, MATRIX.width(), MATRIX.height()); + MATRIX.endDraw(); + } +} +``` + +Upload the code in the snippet above to your board. You can check the Serial Monitor to make sure you have successfully connected to the Arduino Cloud. + +We can now move on to the next step: **setting up Alexa.** + +## Alexa Setup + +For this step, we will need the Amazon Alexa app which can be downloaded from the [Apple App Store](https://apps.apple.com/us/app/amazon-alexa/id944011620) or the [Google Play Store](https://play.google.com/store/apps/details?id=com.amazon.dee.app&hl=en). Once installed, login with your existing account or create a new one. + +### Installing the Arduino Alexa Skill + +Let's go through the steps necessary to install the Arduino Alexa Skill. + +![Installing the Alexa Skill.](assets/alexa_phone_1.png) + +1. Once in the Amazon Alexa app, begin by tapping on "Devices". +2. Tap on the "Enable Smart home skills" button. +3. We will now see a list of featured ones, where we need to search for the right skill. +4. If we search for "Arduino" we will see a skill that has that exact name. + +![Installing the Alexa skill part 2.](assets/alexa_phone_2.png) + +5. Once we have selected it, we'll need to enable it. +6. We now need to sync it with our Arduino Cloud, by logging into it. +7. Our Alexa and Arduino Cloud is now synced! +8. We can now start discovering our devices! + +![Looking for devices.](assets/alexa_phone_3.png) + +### Amazon Alexa Devices Setup + +After waiting a little bit, we should see a new screen appear, where it says **"1 light found and connected"**. + +Click **"Set Up Device"**. If you like you can also add it to a group (this way you can control and organize your devices more easily), otherwise skip this part. + +![Light found and connected.](assets/alexa-mkr-rgb-shield-img-06.png) + +Congratulations! You should now be able to control the lights through your Alexa app. + +## Controlling the Lights + +To control the lights on our setup, we will need to head over to the **"Devices"** tab in the Alexa app. Once in the Devices tab, click on the **"Lights"** button. We will now see the available lights. If you have other lights already connected, they will appear here as well. In our case, we only have one, which is `LoungeArea`, which is the same name as the variable we created earlier in the Arduino Cloud. If we click on `LoungeArea` we will access the color / brightness control. + +![Controlling the lights through the Alexa app.](assets/alexa-mkr-rgb-shield-img-07.png) + +Any changes of color / brightness you make will be sent to our MKR WiFi 1010, which will change the pixels on the MKR RGB Shield accordingly. + + +### Troubleshooting + +One great way of knowing if data is coming through from the Alexa app is by checking the Serial Monitor. The sketch that we uploaded to the board includes a command that prints out the value of **r, g** and **b** whenever they receive new data. If the board is successfully connecting to the Cloud, it is most likely a problem on setting up the Alexa device. + +## Over-the-Air (OTA) + +Did you know that the Arduino Cloud supports over the air uploads? When you've uploaded a sketch to your board once, it will become available for you to upload a new sketch to the board without connecting it to your computer! + +***Over the Air uploads require an Entry plan to the Arduino Cloud*** + +To use this feature, make sure the board has power. If your board is already connected to the Arduino Cloud, you will be able to upload to it over the air. Navigate to the Things sketch tab in the Arduino Cloud interface, and you should see it being discovered just as if it was connected via USB. diff --git a/content/arduino-cloud/02.hardware/02.wifi/wifi.md b/content/arduino-cloud/02.hardware/02.wifi/wifi.md index 2af33e9d45..04220bc462 100644 --- a/content/arduino-cloud/02.hardware/02.wifi/wifi.md +++ b/content/arduino-cloud/02.hardware/02.wifi/wifi.md @@ -15,7 +15,7 @@ There are currently two ways of configuring a Wi-Fi® board: ## Supported Boards -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 network router. +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 network router. ## Configure Wi-Fi® Boards diff --git a/content/arduino-cloud/02.hardware/03.lora/lora.md b/content/arduino-cloud/02.hardware/03.lora/lora.md index f67b74668f..b9ee7e13cb 100644 --- a/content/arduino-cloud/02.hardware/03.lora/lora.md +++ b/content/arduino-cloud/02.hardware/03.lora/lora.md @@ -49,7 +49,7 @@ In this tutorial, we will walk you through the steps needed to successfully prov - **MKR WAN 1300/1310** - development boards that have a LoRa® module capable of sending and receiving packets of data. - **End device/node** - end device/node is a term used for deployed devices such as the MKR WAN 1310, that for example are reading and processing sensor data. - **The Things Network (TTN)** - a nonprofit association, making the TTS Community Edition available as a public LoRaWAN® network service for free. -- **The Things Stack Network (TTS)** - a cloud platform used by TTN and TTI for their LoRaWAN® connectivity networks. +- **The Things Stack Network (TTS)** - a Cloud platform used by TTN and TTI for their LoRaWAN® connectivity networks. - **The Things Industries (TTI)** - a company that runs and manages The Things Network and offers private LoRaWAN network and support for enterprise customers. - **The Things Stack console (TTC)** - a service that allows you to register devices and handle incoming or outgoing data. - **Device EUI** - a code to identify your device. diff --git a/content/arduino-cloud/03.cloud-interface/00.sketches/sketches.md b/content/arduino-cloud/03.cloud-interface/00.sketches/sketches.md index fe9efe98e2..aa766a51d4 100644 --- a/content/arduino-cloud/03.cloud-interface/00.sketches/sketches.md +++ b/content/arduino-cloud/03.cloud-interface/00.sketches/sketches.md @@ -53,7 +53,7 @@ IoT sketches are more complex and are generated automatically when you create a ### Sketch File -The sketch file is generated with a set of additional cloud-specific methods included, the essentials being: +The sketch file is generated with a set of additional Cloud-specific methods included, the essentials being: - `initProperties()` - initializes properties/variables from your Thing. - `ArduinoCloud.begin()` starts the library with the preferred connection (e.g. Wi-Fi® or LoRaWAN®). - `ArduinoCloud.update()` - synchronizes all data between the board and the Arduino Cloud. @@ -79,7 +79,7 @@ void setup(){ ArduinoCloud.printDebugInfo(); } void loop() { - //sync with cloud + //sync with Cloud ArduinoCloud.update(); } @@ -104,7 +104,7 @@ The file cannot be edited in the Arduino Cloud as it is in sync with the platfor The "Secret" File contains your secret credentials, such as Wi-Fi® network SSID/PASS or device secret key. -This file will be visible as a "Secret" tab in the Cloud Editor and is named `arduino_secrets.h`, which is not visible on the cloud platform. +This file will be visible as a "Secret" tab in the Cloud Editor and is named `arduino_secrets.h`, which is not visible on the Cloud platform. Note that if you are using the offline IDE / Arduino CLI, you will need to manually create this file. More information is in the **Offline Sketches section** just below. @@ -144,7 +144,7 @@ ArduinoCloud.begin(ArduinoIoTPreferredConnection, false). ### Alternatives to Delays -The `loop()` function includes the `ArduinoCloud.update();` call, which sends data to the cloud and receives updates. 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. +The `loop()` function includes the `ArduinoCloud.update();` call, which sends data to the Cloud and receives updates. 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. @@ -161,7 +161,7 @@ void loop() { } ``` -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 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: diff --git a/content/arduino-cloud/03.cloud-interface/01.things/things.md b/content/arduino-cloud/03.cloud-interface/01.things/things.md index 5823dd0325..cc98a44b4f 100644 --- a/content/arduino-cloud/03.cloud-interface/01.things/things.md +++ b/content/arduino-cloud/03.cloud-interface/01.things/things.md @@ -8,7 +8,7 @@ author: Karl Söderby The communication between IoT devices and the Arduino Cloud is handled through something called **Things**. Things are a virtual twin of your hardware/setup, where you perform a lot of the configurations for your projects. In the Thing interface you can: -- Create cloud variables that can be synced across devices, +- Create Cloud variables that can be synced across devices, - select the main device you want to associate with, - enter network credentials (such as Wi-Fi network/password), - edit & upload sketches to your board, @@ -38,7 +38,7 @@ The variables section is where you create **"Cloud Variables"**, a variable that When you create a variable, it is automatically\* added to your `thingProperties.h` file, which is included in your Arduino Cloud sketch. This means that you do not need to declare them again. Read more in the [Automatic Sketch Generation](#automatic-sketch-generation) section further down. -For example, if you want to send temperature values to the cloud from a sensor, all you need to do is: +For example, if you want to send temperature values to the Cloud from a sensor, all you need to do is: ```arduino temperature = sensor.readTemperature(); @@ -105,7 +105,7 @@ Your Thing ID can be obtained from your metadata tab, and looks like this: cd628fe4-31d1-42a8-bf33-a627997ce602 ``` -This ID is used when connecting with the [REST API](/arduino-cloud/api/arduino-iot-api) or with the [Arduino CLI](/arduino-cloud/arduino-cloud-cli/getting-started). Using either of these clients provides information about your Thing, such as device associated and cloud variables. +This ID is used when connecting with the [REST API](/arduino-cloud/api/arduino-iot-api) or with the [Arduino CLI](/arduino-cloud/arduino-cloud-cli/getting-started). Using either of these clients provides information about your Thing, such as device associated and Cloud variables. ### Timezone @@ -129,6 +129,6 @@ For example: - Creating a variable with **read/write** permission will also add a callback function at the bottom of your sketch. This will trigger any time the value changes. - Changing your network credentials will update the `arduino_secrets.h` file. -This is implemented so that the connection and synchronization between the board and cloud is handled automatically, meaning you do not need to do any networking code when using the Arduino / C++ language. +This is implemented so that the connection and synchronization between the board and Cloud is handled automatically, meaning you do not need to do any networking code when using the Arduino / C++ language. -***Please note that if you are using an offline environment, [Arduino IDE](/software/ide-v2), changes will only be made in the cloud environment and will manually need to be adjusted. If you plan on using the offline IDE, you make use of the [sketch synchronisation](/software/ide-v2/tutorials/ide-v2-cloud-sketch-sync) feature that allows you to push/pull your cloud sketches from the offline IDE.*** +***Please note that if you are using an offline environment, [Arduino IDE](/software/ide-v2), changes will only be made in the Cloud environment and will manually need to be adjusted. If you plan on using the offline IDE, you make use of the [sketch synchronisation](/software/ide-v2/tutorials/ide-v2-cloud-sketch-sync) feature that allows you to push/pull your Cloud sketches from the offline IDE.*** diff --git a/content/arduino-cloud/03.cloud-interface/02.variables/variables.md b/content/arduino-cloud/03.cloud-interface/02.variables/variables.md index f32a3a952a..8c8487006b 100644 --- a/content/arduino-cloud/03.cloud-interface/02.variables/variables.md +++ b/content/arduino-cloud/03.cloud-interface/02.variables/variables.md @@ -10,7 +10,7 @@ difficulty: beginner Variables are essential components of the [Arduino Cloud](https://app.arduino.cc) and are created and configured inside a **Thing**. -A cloud variable is synced between your Arduino board and the Arduino Cloud. If a variable is updated on your board (like reading a sensor), the Arduino Cloud will also receive this value. Similarly, if a board receives an update from the cloud, the variable also updates on your board. +A Cloud variable is synced between your Arduino board and the Arduino Cloud. If a variable is updated on your board (like reading a sensor), the Arduino Cloud will also receive this value. Similarly, if a board receives an update from the Cloud, the variable also updates on your board. As long as your board maintains a connection to the Arduino Cloud, the variables will be updated. @@ -38,7 +38,7 @@ Inside a variable configuration, we have several options: - [**Complex:**](#complex-types) e.g. `CloudColor`, `CloudTelevision`. - **Declaration:** the declaration of your variable. This is what you will use in a sketch. - **Variable Permission:** - - **Read & Write:** variable can be updated from board and cloud. + - **Read & Write:** variable can be updated from board and Cloud. - **Read Only:** variable can only be updated from the board. - **Variable Update Policy:** - **On Change:** variable synchronizes whenever value changes (threshold is `0` by default). @@ -60,7 +60,7 @@ test_value = 1; When creating a variable with a **Read & Write** permission, a function is generated at the bottom of your sketch. -For example, a boolean variable named `button_switch` will generate a function called `void onButtonSwitch(){}`. This function executes every time the variable is changed from the cloud (through a dashboard). +For example, a boolean variable named `button_switch` will generate a function called `void onButtonSwitch(){}`. This function executes every time the variable is changed from the Cloud (through a dashboard). You can for example implement an ON/OFF switch with the following code: @@ -77,9 +77,9 @@ void onButtonSwitch(){ ## Cloud Updates -Data between a board and the cloud synchronizes whenever the `ArduinoCloud.update()` function is executed. This is automatically included in your sketch, inside the `void loop()`. +Data between a board and the Cloud synchronizes whenever the `ArduinoCloud.update()` function is executed. This is automatically included in your sketch, inside the `void loop()`. -It is a good practice to **not** use the `delay()` function in a cloud sketch. Please refer to the [millis()](https://www.arduino.cc/reference/en/language/functions/time/millis/) function that can be used to create non-blocking delays. +It is a good practice to **not** use the `delay()` function in a Cloud sketch. Please refer to the [millis()](https://www.arduino.cc/reference/en/language/functions/time/millis/) function that can be used to create non-blocking delays. Below is an example of how to use the `millis()` function: @@ -98,13 +98,13 @@ void loop(){ previousMillis = currentMillis; //code here will update every 1 second - //without blocking the program and the cloud update + //without blocking the program and the Cloud update } } ``` -***Note that a variable's sync between a board and the cloud is limited to two messages per second (500ms)*** +***Note that a variable's sync between a board and the Cloud is limited to two messages per second (500ms)*** ## Variable Synchronisation @@ -289,9 +289,9 @@ Here are some examples of how to use the variables in a sketch: ### Basic Types -The example below shows how to use some of the basic types. Remember that cloud variables are configured in the Arduino Cloud, and generated into your Thing's `thingProperties.h` file. +The example below shows how to use some of the basic types. Remember that Cloud variables are configured in the Arduino Cloud, and generated into your Thing's `thingProperties.h` file. -In this example, we are using the following cloud variables: +In this example, we are using the following Cloud variables: - `buttonSwitch` - boolean. - `sensorVal` - int. @@ -556,4 +556,4 @@ In this article, we have covered how to use variables in the Arduino Cloud, and We have also shown some code examples and good practices to keep variable synchronization optimal, such as using the `millis()` function. -The use of cloud variables is almost identical to how you use variables in a regular sketch, with the exception that they are synchronized with the Arduino Cloud. \ No newline at end of file +The use of Cloud variables is almost identical to how you use variables in a regular sketch, with the exception that they are synchronized with the Arduino Cloud. \ No newline at end of file diff --git a/content/arduino-cloud/03.cloud-interface/03.dashboard-widgets/dashboard-widgets.md b/content/arduino-cloud/03.cloud-interface/03.dashboard-widgets/dashboard-widgets.md index 11dd9f005e..40b2474767 100644 --- a/content/arduino-cloud/03.cloud-interface/03.dashboard-widgets/dashboard-widgets.md +++ b/content/arduino-cloud/03.cloud-interface/03.dashboard-widgets/dashboard-widgets.md @@ -14,7 +14,7 @@ Dashboards are composed of [widgets](#widgets), which are directly linked to a v ![Widgets in a dashboard.](assets/dashboard.png) -A dashboard consists of one or several **widgets** that are linked with your cloud variables. You can for example set up a switch to turn on/off a light, a gauge that displays temperature, or a chart that shows data over time. +A dashboard consists of one or several **widgets** that are linked with your Cloud variables. You can for example set up a switch to turn on/off a light, a gauge that displays temperature, or a chart that shows data over time. Dashboards are not tied to one Thing, or one device, and they can be used to control and monitor several devices simultaneously. For example, you can have 10 devices monitoring temperature in different parts of the world, and the data is displayed in one single dashboard. @@ -53,7 +53,7 @@ You can share your live dashboards with other people, allowing them to monitor a ## Widgets -Widgets are the building blocks of your dashboard and can be used to either visualize data or interact with your board. Widgets are linked to a single cloud variable, and as that variable updates, the widget will as well. +Widgets are the building blocks of your dashboard and can be used to either visualize data or interact with your board. Widgets are linked to a single Cloud variable, and as that variable updates, the widget will as well. There are many different widgets available that fit different types of uses, such as: - **Gauge** - displaying data in a "gauge" style. @@ -217,7 +217,7 @@ Can be linked with a **Dimmed Light** variable. An example of how it is used in a sketch: ```arduino - //retrieve and map brightness value from cloud + //retrieve and map brightness value from Cloud uint8_t brightness = map(dimmedVariable.getBrightness(), 0, 100, 0, 255); //then check if switch is on/off diff --git a/content/arduino-cloud/04.cloud-editor/import-your-sketchbook-and-libraries-to-the-web-editor/import-your-sketchbook-and-libraries-to-the-web-editor.md b/content/arduino-cloud/04.cloud-editor/import-your-sketchbook-and-libraries-to-the-web-editor/import-your-sketchbook-and-libraries-to-the-web-editor.md index 71dc652a3c..0db2599dbb 100644 --- a/content/arduino-cloud/04.cloud-editor/import-your-sketchbook-and-libraries-to-the-web-editor/import-your-sketchbook-and-libraries-to-the-web-editor.md +++ b/content/arduino-cloud/04.cloud-editor/import-your-sketchbook-and-libraries-to-the-web-editor/import-your-sketchbook-and-libraries-to-the-web-editor.md @@ -5,7 +5,7 @@ description: 'Learn how to import your local sketchbook and custom libraries to ## Import Your Sketchbook and Libraries to the Web Editor -Are you sticking to the desktop Arduino IDE because all your work is saved locally? That’s no longer a problem! Our brand new import tool enables you to upload your entire sketchbook with just a few clicks on the [Arduino Web Editor](https://create.arduino.cc/editor). It is particularly handy because it lets you **move all your sketches and libraries to the cloud** in a single flow. +Are you sticking to the desktop Arduino IDE because all your work is saved locally? That’s no longer a problem! Our brand new import tool enables you to upload your entire sketchbook with just a few clicks on the [Arduino Web Editor](https://create.arduino.cc/editor). It is particularly handy because it lets you **move all your sketches and libraries to the Cloud** in a single flow. Once your sketchbook is online it will be available on any device and backed up. @@ -34,7 +34,7 @@ Make a `.zip` pack of your sketchbook, you should obtain a file called *Arduino. ![import_sketch_and_library_img_1](assets/import_sketch_and_library_img_1.jpg) ![import_sketch_and_library_img_2](assets/import_sketch_and_library_img_2.jpg) -### 3. Import your sketchbook to the cloud +### 3. Import your sketchbook to the Cloud Go to [create.arduino.cc/editor](https://create.arduino.cc/editor). For some general information on how to get started on the Web Editor see [this tutorial](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-4b3e4a?ref=platform&ref_id=424_trending___&offset=0). When you are logged in and ready, hit the import button on the sketchbook panel. A popup with some instructions on how to import files into the Web Editor will be displayed. Press `“Import”` to continue. diff --git a/content/arduino-cloud/04.cloud-editor/share-your-sketches/share-your-sketches.md b/content/arduino-cloud/04.cloud-editor/share-your-sketches/share-your-sketches.md index 2a3872b911..65885a47d8 100644 --- a/content/arduino-cloud/04.cloud-editor/share-your-sketches/share-your-sketches.md +++ b/content/arduino-cloud/04.cloud-editor/share-your-sketches/share-your-sketches.md @@ -63,7 +63,7 @@ In the same Share popup window you can also copy your project’s related iFrame ## Always Up-To-Date! -Now your code is ready to be shared across a variety of platforms! Do you know what’s cool about this feature? Now that your sketch is on the cloud (literally!) once edited on the Web Editor, it will be also updated across all the places where you have embedded it! +Now your code is ready to be shared across a variety of platforms! Do you know what’s cool about this feature? Now that your sketch is on the Cloud (literally!) once edited on the Web Editor, it will be also updated across all the places where you have embedded it! ### More tutorials diff --git a/content/arduino-cloud/05.iot-remote-app/01.getting-started/iot-remote-app.md b/content/arduino-cloud/05.iot-remote-app/01.getting-started/iot-remote-app.md index 5ea7801e85..b215169d43 100644 --- a/content/arduino-cloud/05.iot-remote-app/01.getting-started/iot-remote-app.md +++ b/content/arduino-cloud/05.iot-remote-app/01.getting-started/iot-remote-app.md @@ -1,80 +1,80 @@ ---- -title: IoT Remote App -description: Learn how to set up the IoT Remote app to control & monitor your dashboards and access your phone's sensor data. -author: Karl Söderby -tags: [Arduino Cloud, Remote App, Phone Data] ---- - -The **Arduino IoT Remote** phone application lets you control and monitor all of your dashboards in the [Arduino Cloud](https://app.arduino.cc/). With the app, you can also access your phone's internal sensors such as GPS data, light sensor, IMU and more (depending on what phone you have). - -The phone's sensor data is automatically stored in cloud variables, which you can also synchronize with other Things. This means your phone can become a part of your IoT system, acting as another node in your network. - -***The Arduino IoT Remote app now supports data collection in background mode. This can be enabled inside the app. Please note that your microphone is NEVER used in background mode, only when the app is being used directly. See more in the [Background Mode](#background-mode) section*** - -## Hardware & Software Needed - -- Android / iOS smart phone. -- Arduino account (sign up [here](https://login.arduino.cc/login)). -- Arduino IoT Remote App: - - [App Store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431). - - [Google Play](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot). - -## Install App - -To use the Arduino IoT Remote app, visit Google Play / App Store and search for **"Arduino IoT Remote"**. Links are available just above. - -***NOTE: The IoT Remote app requires iOS 12.4 or later for iOS the version. If you are using Android, version 8.0 or later is required. Make sure the iOS or Android version on your device is up to date before downloading the app.*** - -After installing the app, you will need to log in to your Arduino account. If you do not have one, you can [sign up here](https://login.arduino.cc/login). - -After you login, you will discover all of your dashboards (if you have any), in the main menu. - -![Dashboards in the Arduino IoT Remote app.](assets/overview.png) - -## Themes - -You can change between the default (light) to the dark theme, by navigating to **Settings > App theme**. - -![Change theme (light/dark)](assets/app-theme.png) - - -## Access Phone Sensor Data - -To access phone sensor data, go to the **"Settings"** menu, located at the top right corner. Inside the settings, click on the **"Phone as Device"**. - -This will start an configuration process, as seen in the image below. Complete the process to access your phone's sensor data. - -![Accessing phone sensor data.](assets/remote-app-setup.png) - -Upon completion, head over to the new dashboard, that should contain your name + your phone's name (in this case, it is `Karl_s S20_Dashboard`). Here you can view your phone's data in real time, such as: -- GPS coordinates (location on map) -- Accelerometer data -- Compass - -![Phone sensor data in the dashboard.](assets/remote-app-dashboard.png) - -For a more in depth guide on how to set this up, and how to use it to control your other devices, head over to the full [Phone Sensor Data Guide](/arduino-cloud/iot-remote-app/iot-remote-phone-sensors). - -***When setting up your phone as a device, a Thing with a similar name is created in the Arduino Cloud. It can not be programmed as a regular device.*** - -### Background Mode - -Now that you've got access to your phone's data, you can also enable the **background mode**. This will allow your phone to continue streaming data to the cloud, even though the app is not being used. - -The exception is your microphone, this one is always disabled in background mode, for data privacy reasons. - -To enable it, go to the settings menu (top left corner), and flick the switch next to **"Background data stream"**. - -![Enable background mode.](assets/remote-app-activate-bkg-mode.png) - -Here you can also choose the update frequency, (either on change, or every `x` seconds). - -## Phone & Board Sync - -The sensor data from your phone is tracked through **variables** in the Arduino Cloud, and can therefore be synchronized with other variables. - -Head over to the [Arduino Cloud - Things](https://app.arduino.cc/things) and go to the Thing created for your phone (in this case, it is named `Karl_s S20_ Thing`), and select a variable you want to synchronize. In the following menu you can link it to other variables on other Things. - -![Synchronizing variables.](assets/remote-app-cloud-variables.png) - +--- +title: IoT Remote App +description: Learn how to set up the IoT Remote app to control & monitor your dashboards and access your phone's sensor data. +author: Karl Söderby +tags: [Arduino Cloud, Remote App, Phone Data] +--- + +The **Arduino IoT Remote** phone application lets you control and monitor all of your dashboards in the [Arduino Cloud](https://app.arduino.cc/). With the app, you can also access your phone's internal sensors such as GPS data, light sensor, IMU and more (depending on what phone you have). + +The phone's sensor data is automatically stored in Cloud variables, which you can also synchronize with other Things. This means your phone can become a part of your IoT system, acting as another node in your network. + +***The Arduino IoT Remote app now supports data collection in background mode. This can be enabled inside the app. Please note that your microphone is NEVER used in background mode, only when the app is being used directly. See more in the [Background Mode](#background-mode) section*** + +## Hardware & Software Needed + +- Android / iOS smart phone. +- Arduino account (sign up [here](https://login.arduino.cc/login)). +- Arduino IoT Remote App: + - [App Store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431). + - [Google Play](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot). + +## Install App + +To use the Arduino IoT Remote app, visit Google Play / App Store and search for **"Arduino IoT Remote"**. Links are available just above. + +***NOTE: The IoT Remote app requires iOS 12.4 or later for iOS the version. If you are using Android, version 8.0 or later is required. Make sure the iOS or Android version on your device is up to date before downloading the app.*** + +After installing the app, you will need to log in to your Arduino account. If you do not have one, you can [sign up here](https://login.arduino.cc/login). + +After you login, you will discover all of your dashboards (if you have any), in the main menu. + +![Dashboards in the Arduino IoT Remote app.](assets/overview.png) + +## Themes + +You can change between the default (light) to the dark theme, by navigating to **Settings > App theme**. + +![Change theme (light/dark)](assets/app-theme.png) + + +## Access Phone Sensor Data + +To access phone sensor data, go to the **"Settings"** menu, located at the top right corner. Inside the settings, click on the **"Phone as Device"**. + +This will start an configuration process, as seen in the image below. Complete the process to access your phone's sensor data. + +![Accessing phone sensor data.](assets/remote-app-setup.png) + +Upon completion, head over to the new dashboard, that should contain your name + your phone's name (in this case, it is `Karl_s S20_Dashboard`). Here you can view your phone's data in real time, such as: +- GPS coordinates (location on map) +- Accelerometer data +- Compass + +![Phone sensor data in the dashboard.](assets/remote-app-dashboard.png) + +For a more in depth guide on how to set this up, and how to use it to control your other devices, head over to the full [Phone Sensor Data Guide](/arduino-cloud/iot-remote-app/iot-remote-phone-sensors). + +***When setting up your phone as a device, a Thing with a similar name is created in the Arduino Cloud. It can not be programmed as a regular device.*** + +### Background Mode + +Now that you've got access to your phone's data, you can also enable the **background mode**. This will allow your phone to continue streaming data to the Cloud, even though the app is not being used. + +The exception is your microphone, this one is always disabled in background mode, for data privacy reasons. + +To enable it, go to the settings menu (top left corner), and flick the switch next to **"Background data stream"**. + +![Enable background mode.](assets/remote-app-activate-bkg-mode.png) + +Here you can also choose the update frequency, (either on change, or every `x` seconds). + +## Phone & Board Sync + +The sensor data from your phone is tracked through **variables** in the Arduino Cloud, and can therefore be synchronized with other variables. + +Head over to the [Arduino Cloud - Things](https://app.arduino.cc/things) and go to the Thing created for your phone (in this case, it is named `Karl_s S20_ Thing`), and select a variable you want to synchronize. In the following menu you can link it to other variables on other Things. + +![Synchronizing variables.](assets/remote-app-cloud-variables.png) + Simply described, this allows you to use your phone as an input for a number of different applications. For example, the `Compass` variable can be used to control the angle of a servo motor on another device. You can read more about how to synchronize these variables in the [Use Sensor Data From Your Phone](/arduino-cloud/iot-remote-app/iot-remote-phone-sensors) tutorial, that includes a practical example. \ No newline at end of file diff --git a/content/arduino-cloud/05.iot-remote-app/02.iot-remote-phone-sensors/iot-remote-phone-sensors.md b/content/arduino-cloud/05.iot-remote-app/02.iot-remote-phone-sensors/iot-remote-phone-sensors.md index 45f2fca222..fb11d52420 100644 --- a/content/arduino-cloud/05.iot-remote-app/02.iot-remote-phone-sensors/iot-remote-phone-sensors.md +++ b/content/arduino-cloud/05.iot-remote-app/02.iot-remote-phone-sensors/iot-remote-phone-sensors.md @@ -1,173 +1,173 @@ ---- -title: 'Use Sensor Data From Your Phone' -description: 'Stream sensor data from your phone live to the Arduino Cloud' -tags: -- Arduino Cloud -- Remote app -- Mobile sensors -- Android -- iOS -author: 'Jacob Hylén' ---- - -The Arduino Cloud is a powerful platform that can help you with setting up your own IoT devices within minutes. - -It is now possible to synchronize your phone's sensor data with the cloud, using the Arduino IoT Remote App for [iOS](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) and [Android](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US). Furthermore, this data can also be used to control your Arduino boards, such as mapping a value from a sensor on your phone to an actuator on your Arduino. - -Your smartphone is absolutely **packed** with sophisticated sensors that constantly measure everything from GPS position, to magnetic fields, acceleration, and so on. But they're difficult for a maker to take advantage of without having extensive knowledge of mobile development. - -That is changed by the Arduino IoT Remote app - as you are able to, with the latest version of the app for [Android](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) and [iOS](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431), set up a dashboard in the Arduino Cloud that tracks and displays all your sensor data in a neat dashboard within a minute. - -The goal with this project is to learn about how you can use your smartphone as a remote, sending sensor data to the Arduino Cloud. You'll also learn how this sensor data can be used by other Things in your Arduino Cloud account, essentially letting you control your IoT devices depending on your variables such as GPS position, compass orientation, or any of the other in the long list of variables the IoT Remote app can stream live to the cloud. - -You will learn this by making a small project where a servo motor reacts to where you point your phone, as shown below. - -![Expected Outcome](assets/expected-outcome.gif) - -## Requirements -To Follow along with this article, you will need the following: - -- An Android or iOS Smartphone/tablet -- An [Arduino Cloud](https://cloud.arduino.cc/home/) Account -- An Arduino Cloud-compatible board (optional). -- A Servo motor (optional). - -## Phone Setup -To start this process, you will need to download the Arduino IoT Remote app from either the [Google Play Store](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) or the[ Apple App store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) depending on your device, if you don't already have it installed. If you do have it installed already you may need to update it, so take a quick look to make sure that you have the latest version downloaded. - -Once you have the app installed, open it and log into your [Arduino Cloud](https://cloud.arduino.cc/home/) account. At this point you should be presented with a list of all your previous dashboards if you have any. - -![Dashboards](assets/dashboards.png) - -Tap the hamburger-menu in the top left of your screen, if you're using version 1.1 of the app or later you should have two options, press "**Use data from your phone**". - -At this point, if you expand the section, you can see all the sensors that can be tracked in the Arduino Cloud listed. You'll need to consent to the sensor data being sent to the Arduino Cloud by checking the box, then you're ready to start the automated process of building the dashboard. Tap "**SET YOUR PHONE**" and sit back, relax, while the app takes care of everything else for you. - -Once done, check out all the sensor data in the dashboard. How neat is that? - -![Dashboard](assets/dashboard.png) - -Try manipulating your phone in different ways to see how the data reacts, move it around, bring magnets close, make sounds, try anything you can think of! - -## Use the Data -Now that you've got your sensor data in the Arduino Cloud, the next step is to use it for a project. As an example, let's sync the compass orientation of your phone to a variable controlling the angle of a servo motor. - -The mobile "**Thing**" can't be programmed, but you can sync the variables from it with variables in other "**Things**" - -So go to the [Arduino Cloud](https://app.arduino.cc/things) on your computer, and create a new **Thing**. - -Grab your **Arduino Cloud** compatible Arduino board and connect it to your computer, and configure it with your thing. I am using an **Arduino Nano 33 IoT**, and I am going with the suggested name for my device, which happens to be "**Robby**" - -You will also need to enter your network credentials at this stage. - -Now you can add a new variable in your **Thing**. When configuring this variable, you have the option to sync it to variables in other **Things**. This is very powerful and lets your devices talk to each other seamlessly, while still acting just like the variables you are familiar with in the code you're writing. - -Name the variable something appropriate, "Compass" for example. Click the **"Sync with other Things"** button to open up the syncing menu, search for **"compass"** and make sure to tick the box of the compass variable tied to your mobile devices Thing. - -![Variable syncing](assets/variablesync.png) - -When one of the variables are updated, the other one will sync to the same value. This means that if we refer to the Compass variable in the sketch of our Arduino Thing we can access the values from the mobile device. - -Now that the input is figured out, let's move on to creating our sketch. If you want to skip the code explanation, the full sketch can be found at the bottom of this section. - -At the very top of the sketch we want to do three things, the first one is to include the servo library, the second one is to initialise the servo library, and the third is to create a variable to hold a mapped value from the compass. The compass in your phone reports a value between 0-360, but because servo motors usually cannot rotate 360 degrees we need to make sure that the value we send to the servo is witing the acceptables ranges for the servo we're using. Most small servos can move within a 90 or 180 degree range. - -So start by including and initialising the servo library, and creating an empty integer variable at the top of your sketch. - -```arduino -#include - -Servo myServo; - -int mappedCompass; -``` - -Within `void setup()` we'll need select a pin for the servo motor. We'll also write it to a default starting position. - -Add the following code somwehere in the setup function: -``` - myServo.attach(2); - myServo.write(80); -``` - -In `void loop()` we need to remap the compass value like explained earlier, but once that is done all we need to do is to write the remapped value to the servo motor. - -Add the following code in the loop function: -``` - mappedCompass = map(compass, 0, 360, 0, 90); - - myServo.write(mappedCompass); -``` - -The full code can be found here: -``` -/* - Arduino Cloud Variables description - - The following variables are automatically generated and updated when changes are made to the Thing - - float compass; - - Variables which are marked as READ/WRITE in the Cloud Thing will also have functions - which are called when their values are changed from the Dashboard. - These functions are generated with the Thing and added at the end of this sketch. -*/ - -#include "thingProperties.h" -#include - -Servo myServo; - -int mappedCompass; - -void setup() { - // Initialize serial and wait for port to open: - Serial.begin(9600); - // This delay gives the chance to wait for a Serial Monitor without blocking if none is found - delay(1500); - - myServo.attach(2); - myServo.write(80); - - // Defined in thingProperties.h - initProperties(); - - // Connect to Arduino Cloud - ArduinoCloud.begin(ArduinoIoTPreferredConnection); - - /* - The following function allows you to obtain more information - related to the state of network and Arduino Cloud connection and errors - the higher number the more granular information you’ll get. - The default is 0 (only errors). - Maximum is 4 - */ - setDebugMessageLevel(2); - ArduinoCloud.printDebugInfo(); -} - -void loop() { - ArduinoCloud.update(); - // Your code here - mappedCompass = map(compass, 0, 360, 0, 90); - - myServo.write(mappedCompass); - -} - -/* - Since Compass is READ_WRITE variable, onCompassChange() is - executed every time a new value is received from Arduino Cloud. -*/ -void onCompassChange() { - // Add your code here to act upon Compass change -} - -``` - -Once the sketch is uploaded to your board, wait for it to connect to your network, then open the IoT Remote app on your phone and watch as the Servo reacts when you rotate your phone. - -## Conclusion -With this tutorial, you have learned how to connect your android or iOS smartphone to the Arduino Cloud and send all sorts of sensor data from your device, and how to integrate this sensor data with your other Arduino Cloud Things. - +--- +title: 'Use Sensor Data From Your Phone' +description: 'Stream sensor data from your phone live to the Arduino Cloud' +tags: +- Arduino Cloud +- Remote app +- Mobile sensors +- Android +- iOS +author: 'Jacob Hylén' +--- + +The Arduino Cloud is a powerful platform that can help you with setting up your own IoT devices within minutes. + +It is now possible to synchronize your phone's sensor data with the Cloud, using the Arduino IoT Remote App for [iOS](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) and [Android](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US). Furthermore, this data can also be used to control your Arduino boards, such as mapping a value from a sensor on your phone to an actuator on your Arduino. + +Your smartphone is absolutely **packed** with sophisticated sensors that constantly measure everything from GPS position, to magnetic fields, acceleration, and so on. But they're difficult for a maker to take advantage of without having extensive knowledge of mobile development. + +That is changed by the Arduino IoT Remote app - as you are able to, with the latest version of the app for [Android](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) and [iOS](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431), set up a dashboard in the Arduino Cloud that tracks and displays all your sensor data in a neat dashboard within a minute. + +The goal with this project is to learn about how you can use your smartphone as a remote, sending sensor data to the Arduino Cloud. You'll also learn how this sensor data can be used by other Things in your Arduino Cloud account, essentially letting you control your IoT devices depending on your variables such as GPS position, compass orientation, or any of the other in the long list of variables the IoT Remote app can stream live to the Cloud. + +You will learn this by making a small project where a servo motor reacts to where you point your phone, as shown below. + +![Expected Outcome](assets/expected-outcome.gif) + +## Requirements +To Follow along with this article, you will need the following: + +- An Android or iOS Smartphone/tablet +- An [Arduino Cloud](https://cloud.arduino.cc/home/) Account +- An Arduino Cloud-compatible board (optional). +- A Servo motor (optional). + +## Phone Setup +To start this process, you will need to download the Arduino IoT Remote app from either the [Google Play Store](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) or the[ Apple App store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) depending on your device, if you don't already have it installed. If you do have it installed already you may need to update it, so take a quick look to make sure that you have the latest version downloaded. + +Once you have the app installed, open it and log into your [Arduino Cloud](https://cloud.arduino.cc/home/) account. At this point you should be presented with a list of all your previous dashboards if you have any. + +![Dashboards](assets/dashboards.png) + +Tap the hamburger-menu in the top left of your screen, if you're using version 1.1 of the app or later you should have two options, press "**Use data from your phone**". + +At this point, if you expand the section, you can see all the sensors that can be tracked in the Arduino Cloud listed. You'll need to consent to the sensor data being sent to the Arduino Cloud by checking the box, then you're ready to start the automated process of building the dashboard. Tap "**SET YOUR PHONE**" and sit back, relax, while the app takes care of everything else for you. + +Once done, check out all the sensor data in the dashboard. How neat is that? + +![Dashboard](assets/dashboard.png) + +Try manipulating your phone in different ways to see how the data reacts, move it around, bring magnets close, make sounds, try anything you can think of! + +## Use the Data +Now that you've got your sensor data in the Arduino Cloud, the next step is to use it for a project. As an example, let's sync the compass orientation of your phone to a variable controlling the angle of a servo motor. + +The mobile "**Thing**" can't be programmed, but you can sync the variables from it with variables in other "**Things**" + +So go to the [Arduino Cloud](https://app.arduino.cc/things) on your computer, and create a new **Thing**. + +Grab your **Arduino Cloud** compatible Arduino board and connect it to your computer, and configure it with your thing. I am using an **Arduino Nano 33 IoT**, and I am going with the suggested name for my device, which happens to be "**Robby**" + +You will also need to enter your network credentials at this stage. + +Now you can add a new variable in your **Thing**. When configuring this variable, you have the option to sync it to variables in other **Things**. This is very powerful and lets your devices talk to each other seamlessly, while still acting just like the variables you are familiar with in the code you're writing. + +Name the variable something appropriate, "Compass" for example. Click the **"Sync with other Things"** button to open up the syncing menu, search for **"compass"** and make sure to tick the box of the compass variable tied to your mobile devices Thing. + +![Variable syncing](assets/variablesync.png) + +When one of the variables are updated, the other one will sync to the same value. This means that if we refer to the Compass variable in the sketch of our Arduino Thing we can access the values from the mobile device. + +Now that the input is figured out, let's move on to creating our sketch. If you want to skip the code explanation, the full sketch can be found at the bottom of this section. + +At the very top of the sketch we want to do three things, the first one is to include the servo library, the second one is to initialise the servo library, and the third is to create a variable to hold a mapped value from the compass. The compass in your phone reports a value between 0-360, but because servo motors usually cannot rotate 360 degrees we need to make sure that the value we send to the servo is witing the acceptables ranges for the servo we're using. Most small servos can move within a 90 or 180 degree range. + +So start by including and initialising the servo library, and creating an empty integer variable at the top of your sketch. + +```arduino +#include + +Servo myServo; + +int mappedCompass; +``` + +Within `void setup()` we'll need select a pin for the servo motor. We'll also write it to a default starting position. + +Add the following code somwehere in the setup function: +``` + myServo.attach(2); + myServo.write(80); +``` + +In `void loop()` we need to remap the compass value like explained earlier, but once that is done all we need to do is to write the remapped value to the servo motor. + +Add the following code in the loop function: +``` + mappedCompass = map(compass, 0, 360, 0, 90); + + myServo.write(mappedCompass); +``` + +The full code can be found here: +``` +/* + Arduino Cloud Variables description + + The following variables are automatically generated and updated when changes are made to the Thing + + float compass; + + Variables which are marked as READ/WRITE in the Cloud Thing will also have functions + which are called when their values are changed from the Dashboard. + These functions are generated with the Thing and added at the end of this sketch. +*/ + +#include "thingProperties.h" +#include + +Servo myServo; + +int mappedCompass; + +void setup() { + // Initialize serial and wait for port to open: + Serial.begin(9600); + // This delay gives the chance to wait for a Serial Monitor without blocking if none is found + delay(1500); + + myServo.attach(2); + myServo.write(80); + + // Defined in thingProperties.h + initProperties(); + + // Connect to Arduino Cloud + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + /* + The following function allows you to obtain more information + related to the state of network and Arduino Cloud connection and errors + the higher number the more granular information you’ll get. + The default is 0 (only errors). + Maximum is 4 + */ + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); +} + +void loop() { + ArduinoCloud.update(); + // Your code here + mappedCompass = map(compass, 0, 360, 0, 90); + + myServo.write(mappedCompass); + +} + +/* + Since Compass is READ_WRITE variable, onCompassChange() is + executed every time a new value is received from Arduino Cloud. +*/ +void onCompassChange() { + // Add your code here to act upon Compass change +} + +``` + +Once the sketch is uploaded to your board, wait for it to connect to your network, then open the IoT Remote app on your phone and watch as the Servo reacts when you rotate your phone. + +## Conclusion +With this tutorial, you have learned how to connect your android or iOS smartphone to the Arduino Cloud and send all sorts of sensor data from your device, and how to integrate this sensor data with your other Arduino Cloud Things. + The small project done in this tutorial is just the tip of the iceberg, you could take what you learned here and apply it in other ways to create an endless amount of cool interactive IoT projects that take advantage of the sophisticated sensors you carry in your pocket every day. \ No newline at end of file diff --git a/content/arduino-cloud/06.features/02.cloud-scheduler/cloud-scheduler.md b/content/arduino-cloud/06.features/02.cloud-scheduler/cloud-scheduler.md index ac05f071b1..40edbca2f5 100644 --- a/content/arduino-cloud/06.features/02.cloud-scheduler/cloud-scheduler.md +++ b/content/arduino-cloud/06.features/02.cloud-scheduler/cloud-scheduler.md @@ -1,310 +1,310 @@ ---- -title: 'Scheduler' -description: 'Learn how to use the scheduler feature to trigger repeating jobs during specific times.' -tags: [Arduino Cloud, Scheduler, Time] -author: 'Karl Söderby' -software: - - iot-cloud ---- - -It is now possible to schedule jobs with the [Arduino Cloud](https://app.arduino.cc/), using the new `CloudSchedule` variable type. You can pick a start & end date for when the variable should be triggered, and for how long it should be active. This variable can be controlled in real time using a graphical widget that you can place on an Arduino Cloud dashboard. - -We can for example have: - -- One trigger scheduled to run every minute for 10 seconds -- One trigger scheduled to run every hour for 10 minutes - -## Goals - -The goals of this project are: - -- Learn how the `CloudSchedule` variable works. -- Learn how to access local time in your sketch. - -Make sure you have a [cloud-compatible board](/arduino-cloud/hardware/devices#type-of-devices). - -## How Does it Work? - -A variable of `CloudSchedule` type can be configured to trigger at a specific time, with a specific duration. In the code, you do not need to worry about the logic for this. The configuration of the variable is done in the dashboard, through a widget associated to the variable. - -For example, we can set such variable to be: -- ON for 10 seconds, every minute. -- ON for 8 hours, every day. -- ON for a week, and then finish. - -![Example of a schedule configured to run for 10 seconds every minute.](assets/cloud-scheduler-img-01.png) - -## Application Examples - -There are countless examples where schedulers can be used, but predominantly it can be utilized for timer projects. Below are a few examples that can be used as inspiration. - -***Note that "schedule_variable" used in these examples is the name we give when creating the variable in the Thing settings.*** - -### Basic Example - -To test out functionality of your scheduler job, we can turn on an LED while the job is active. - -```arduino -if (schedule_variable.isActive()) { - // whenever the job is "active", turn on the LED - digitalWrite(LED, HIGH); -} else { - // whenever the job is "not active", turn off the LED - digitalWrite(LED, LOW); -} -``` - -### Multiple Schedulers - -You can set up **multiple scheduler variables.** This way, you can have a different code executing at specific times. In the example below, there are three schedulers, each performing a unique task whenever triggered: - -- Write a high state to a pin. -- Read a sensor. -- Change a string. - -```arduino -// scheduler 1 (write a high state to a pin) -if (schedule_variable_1.isActive()) { - digitalWrite(3, HIGH); -} else { - digitalWrite(3, LOW); -} - -// scheduler 2 (read a sensor) -if(schedule_variable_2.isActive()) { - sensor_variable = analogRead(A1); -} - -// scheduler 3 (change a string) -if (schedule_variable_3.isActive()) { - string_variable = ""; - string_variable = "Update something here!"; -} -``` - - -### Smart Light Automation - -Turning on and off light sources can be a great power saver for the office, home or vacation home. This can be achieved with a few lines of code and a [relay shield](https://store.arduino.cc/products/arduino-mkr-relay-proto-shield). - -```arduino -if (schedule_variable.isActive()) { - // can be configured to be ON between 8am - 5pm - digitalWrite(relay, HIGH); -} else { - //can be set to OFF between 5pm - 8am the next morning - digitalWrite(relay, LOW); -} -``` - - - -### Plant Watering - -For a "smart watering" setup, if you connect a pump through a relay, you can schedule a job to be on for a period of time (pumping water) and then turn off. This could for example occur for a few seconds every day to keep your plants alive. - -```arduino -// configure to be "on" for 10 seconds every day -if (schedule_variable.isActive()) { - digitalWrite(pump, HIGH); -} else { - digitalWrite(pump, LOW); -} -``` - -Or, if you use a driver, such as **L298N**, you can control the pump through: - -```arduino -if (schedule_variable.isActive()) { - analogWrite(pump, 127); // range between 0-255 -} else { - analogWrite(pump, 0); -} -``` - -## Creating a Scheduler (Tutorial) - -In this section you will find a step by step tutorial that will guide you to creating and testing out the **scheduler feature**. - -- Create a Thing. -- Configure an Arduino board. -- Create a basic sketch & upload it to the board. -- Create a dashboard. - -### API - -The two **variables types** introduced in this tutorial are `CloudTime` and `CloudSchedule`. These are used to retrieve local time and to schedule a job respectively. - -The `CloudSchedule` variable is of a **complex type**. It has a **internal boolean state**, which can be checked through the `isActive()` function (returns `true` or `false`). - -```arduino -if(schedule_variable.isActive()) { - //do something -} -``` - -The `CloudTime` variable is an unsigned integer which is used to store current time. We can use the `getLocalTime()` function to retrieve local time. - -```arduino -time_variable = ArduinoCloud.getLocalTime(); -``` - -### Create a Thing - -***If you are new to the Arduino Cloud, you can either visit the [Getting Started with Arduino Cloud](/arduino-cloud/guides/overview) guide, or any of the tutorials in the [Arduino Cloud documentation](/arduino-cloud/). There you will find detailed step by step guides.*** - -**1.** Navigate to [Arduino Cloud](https://app.arduino.cc/). You will need to log in with your Arduino account. - -**2.** Create a new Thing by clicking on the "Create Thing" button. You can name it something like "Scheduler Test". - -**3.** Now, we need to attach a device to our Thing, by clicking on **"Select Device"**. If you already have a device configured, you can select it, otherwise, follow the configuration. - -***Note that your board will need to be connected to your computer at this point.*** - -Once your device is configured and attached to your Thing, we can move on to create variables. - -### Create Variables - -For this project, we will need to create the following variables, by clicking on the "Add Variable" button. - -| Variable Name | Variable Type | Permission | -| ------------- | ------------- | ------------ | -| schedule_test | CloudSchedule | Read & Write | -| time_read | CloudTime | Read Only | -| light | bool | Read Only | -| counter | int | Read Only | - -Your Thing overview should now look like the image below: - -![The Thing overview.](assets/cloud-scheduler-img-02.png) - -### Set Time Zone - -In order for our job to go off at the right time, we need to set the **time zone** for our Thing. This is done in our Thing configuration, by selecting your time zone through the drop down menu available at the bottom of the page. - -![Change time zone for a Thing.](assets/cloud-scheduler-img-timezone.png) - -### Network Credentials - -To connect your device to the Arduino Cloud, you need to enter your network credentials in the "network" section. - -***Note that this only applies to Wi-Fi enabled boards.*** - -### Programming the Board - -Now, let's take a look at the sketch used for this tutorial. First, we need to navigate to the **"Sketch Tab"**. - -- This sketch first checks whether the `schedule_test` variable is true, and if it is, increase the `counter` variable and turn on the `light`. -- The `light` variable is used for feedback later on, when we create a dashboard. Whenever `schedule_test` is true, so is `light`. -- The `LED` variable is also attached to pin 6, which is **ON** when the job is active, and **OFF** when the job is inactive. - -### Complete Sketch - -```arduino -#include "thingProperties.h" - -bool toggle; -int LED = 6; - -void setup() { - Serial.begin(9600); - delay(1500); - - initProperties(); - - ArduinoCloud.begin(ArduinoIoTPreferredConnection); - setDebugMessageLevel(2); - ArduinoCloud.printDebugInfo(); - counter = 0; - light = false; -} - -void loop() { - ArduinoCloud.update(); - // Your code here - if (schedule_test.isActive()) { - light = true; - digitalWrite(LED, HIGH); - - if (toggle) { - counter = ++counter; - toggle = false; - } - } else { - light = false; - digitalWrite(LED, LOW); - toggle = true; - } - if(ArduinoCloud.connected()){ - time_read = ArduinoCloud.getLocalTime(); - } -} - -void onScheduleTestChange() { - -} -``` - -***If you want to see if your board successfully connects to the cloud, open the Serial Monitor right after the upload finishes. If there's any errors, you will see them there.*** - -### Creating a Dashboard - -Finally, let's build a dashboard that will help us interface with our Arduino board. - -**1.** Head over to the **"Dashboards"** section, and click on the **"Build Dashboard"** button. - -**2.** Now we will need to create a set of widgets that we will link to our variables. Follow the table below to create them. - -| Widget | Variable | -| ----------- | ------------- | -| Scheduler | schedule_test | -| Time Picker | time_read | -| Value | value | -| LED | light | - -***When you create a widget, you will need to click on "Link Variable" in the widget settings, and then choose the variable you want to link (see the image below).*** - -![Linking a widget to a variable.](assets/cloud-scheduler-img-04.png) - -When the dashboard is finished, it should look something like the image below, where we have four widgets in total: - -![The final dashboard.](assets/cloud-scheduler-img-05.png) - -We are now finished with the setup, and can move on to testing out the scheduler feature. - -## Scheduling a Job - -To schedule a job, there are several parameters that can be set: - -- **Start & end** date for a "job". For example, **start** on 1st of December at 00:00, **end** at 31st of December at 12.00. -- **Duration** of the job, set in hours, minutes, seconds. If we for example set 1 minute, the `schedule_test` variable will be `true` for 1 minute. -- **Repetition** interval, how often should this job occur: every minute, hour, day, week, month, day or year. - -To create a job, simply click anywhere on the **scheduler widget**, and configure the job after your preferences. - -![Scheduler Widget settings.](assets/cloud-scheduler-img-06.png) - -### Testing the Scheduler - -In this tutorial, we created a job that has the following parameters: - -- **Start:** today. -- **End:** never. -- **Duration:** 10 seconds. -- **Repeat Every:** minute. - -The sketch used for this is configured to switch the `light` variable to true, whenever the `schedule_test` variable is true. While it is true, the **LED widget**, which is linked to the `light` variable, will be on (for 10 seconds). Each time this happens, the `counter` variable will also increase by 1. - -![The scheduler in action.](assets/scheduler-action.gif) - -### Troubleshoot - -If you have any issues with finishing this tutorial, you can check out some common troubleshooting issues: - -- Is your network credentials correct? If you change these, you will need to upload the sketch again for the changes to have effect. -- If you can't link a widget to a variable, you may have selected the wrong variable type. The **scheduler widget** will only work with the **scheduler variable**. -- Does the variables created in your Thing match the variables in your sketch? For example, if your variable is named `Schedule_test`, the code provided in this tutorial will not work since it is **case sensitive**. - -## Conclusion - -The scheduler is yet another amazing Arduino Cloud feature that allows you to control the future. In this tutorial, we used **just one scheduler**, but you might just as easily create 10 schedulers that can perform actions automatically. This makes it an ideal building block for IoT projects. +--- +title: 'Scheduler' +description: 'Learn how to use the scheduler feature to trigger repeating jobs during specific times.' +tags: [Arduino Cloud, Scheduler, Time] +author: 'Karl Söderby' +software: + - iot-cloud +--- + +It is now possible to schedule jobs with the [Arduino Cloud](https://app.arduino.cc/), using the new `CloudSchedule` variable type. You can pick a start & end date for when the variable should be triggered, and for how long it should be active. This variable can be controlled in real time using a graphical widget that you can place on an Arduino Cloud dashboard. + +We can for example have: + +- One trigger scheduled to run every minute for 10 seconds +- One trigger scheduled to run every hour for 10 minutes + +## Goals + +The goals of this project are: + +- Learn how the `CloudSchedule` variable works. +- Learn how to access local time in your sketch. + +Make sure you have a [cloud-compatible board](/arduino-cloud/hardware/devices#type-of-devices). + +## How Does it Work? + +A variable of `CloudSchedule` type can be configured to trigger at a specific time, with a specific duration. In the code, you do not need to worry about the logic for this. The configuration of the variable is done in the dashboard, through a widget associated to the variable. + +For example, we can set such variable to be: +- ON for 10 seconds, every minute. +- ON for 8 hours, every day. +- ON for a week, and then finish. + +![Example of a schedule configured to run for 10 seconds every minute.](assets/cloud-scheduler-img-01.png) + +## Application Examples + +There are countless examples where schedulers can be used, but predominantly it can be utilized for timer projects. Below are a few examples that can be used as inspiration. + +***Note that "schedule_variable" used in these examples is the name we give when creating the variable in the Thing settings.*** + +### Basic Example + +To test out functionality of your scheduler job, we can turn on an LED while the job is active. + +```arduino +if (schedule_variable.isActive()) { + // whenever the job is "active", turn on the LED + digitalWrite(LED, HIGH); +} else { + // whenever the job is "not active", turn off the LED + digitalWrite(LED, LOW); +} +``` + +### Multiple Schedulers + +You can set up **multiple scheduler variables.** This way, you can have a different code executing at specific times. In the example below, there are three schedulers, each performing a unique task whenever triggered: + +- Write a high state to a pin. +- Read a sensor. +- Change a string. + +```arduino +// scheduler 1 (write a high state to a pin) +if (schedule_variable_1.isActive()) { + digitalWrite(3, HIGH); +} else { + digitalWrite(3, LOW); +} + +// scheduler 2 (read a sensor) +if(schedule_variable_2.isActive()) { + sensor_variable = analogRead(A1); +} + +// scheduler 3 (change a string) +if (schedule_variable_3.isActive()) { + string_variable = ""; + string_variable = "Update something here!"; +} +``` + + +### Smart Light Automation + +Turning on and off light sources can be a great power saver for the office, home or vacation home. This can be achieved with a few lines of code and a [relay shield](https://store.arduino.cc/products/arduino-mkr-relay-proto-shield). + +```arduino +if (schedule_variable.isActive()) { + // can be configured to be ON between 8am - 5pm + digitalWrite(relay, HIGH); +} else { + //can be set to OFF between 5pm - 8am the next morning + digitalWrite(relay, LOW); +} +``` + + + +### Plant Watering + +For a "smart watering" setup, if you connect a pump through a relay, you can schedule a job to be on for a period of time (pumping water) and then turn off. This could for example occur for a few seconds every day to keep your plants alive. + +```arduino +// configure to be "on" for 10 seconds every day +if (schedule_variable.isActive()) { + digitalWrite(pump, HIGH); +} else { + digitalWrite(pump, LOW); +} +``` + +Or, if you use a driver, such as **L298N**, you can control the pump through: + +```arduino +if (schedule_variable.isActive()) { + analogWrite(pump, 127); // range between 0-255 +} else { + analogWrite(pump, 0); +} +``` + +## Creating a Scheduler (Tutorial) + +In this section you will find a step by step tutorial that will guide you to creating and testing out the **scheduler feature**. + +- Create a Thing. +- Configure an Arduino board. +- Create a basic sketch & upload it to the board. +- Create a dashboard. + +### API + +The two **variables types** introduced in this tutorial are `CloudTime` and `CloudSchedule`. These are used to retrieve local time and to schedule a job respectively. + +The `CloudSchedule` variable is of a **complex type**. It has a **internal boolean state**, which can be checked through the `isActive()` function (returns `true` or `false`). + +```arduino +if(schedule_variable.isActive()) { + //do something +} +``` + +The `CloudTime` variable is an unsigned integer which is used to store current time. We can use the `getLocalTime()` function to retrieve local time. + +```arduino +time_variable = ArduinoCloud.getLocalTime(); +``` + +### Create a Thing + +***If you are new to the Arduino Cloud, you can either visit the [Getting Started with Arduino Cloud](/arduino-cloud/guides/overview) guide, or any of the tutorials in the [Arduino Cloud documentation](/arduino-cloud/). There you will find detailed step by step guides.*** + +**1.** Navigate to [Arduino Cloud](https://app.arduino.cc/). You will need to log in with your Arduino account. + +**2.** Create a new Thing by clicking on the "Create Thing" button. You can name it something like "Scheduler Test". + +**3.** Now, we need to attach a device to our Thing, by clicking on **"Select Device"**. If you already have a device configured, you can select it, otherwise, follow the configuration. + +***Note that your board will need to be connected to your computer at this point.*** + +Once your device is configured and attached to your Thing, we can move on to create variables. + +### Create Variables + +For this project, we will need to create the following variables, by clicking on the "Add Variable" button. + +| Variable Name | Variable Type | Permission | +| ------------- | ------------- | ------------ | +| schedule_test | CloudSchedule | Read & Write | +| time_read | CloudTime | Read Only | +| light | bool | Read Only | +| counter | int | Read Only | + +Your Thing overview should now look like the image below: + +![The Thing overview.](assets/cloud-scheduler-img-02.png) + +### Set Time Zone + +In order for our job to go off at the right time, we need to set the **time zone** for our Thing. This is done in our Thing configuration, by selecting your time zone through the drop down menu available at the bottom of the page. + +![Change time zone for a Thing.](assets/cloud-scheduler-img-timezone.png) + +### Network Credentials + +To connect your device to the Arduino Cloud, you need to enter your network credentials in the "network" section. + +***Note that this only applies to Wi-Fi enabled boards.*** + +### Programming the Board + +Now, let's take a look at the sketch used for this tutorial. First, we need to navigate to the **"Sketch Tab"**. + +- This sketch first checks whether the `schedule_test` variable is true, and if it is, increase the `counter` variable and turn on the `light`. +- The `light` variable is used for feedback later on, when we create a dashboard. Whenever `schedule_test` is true, so is `light`. +- The `LED` variable is also attached to pin 6, which is **ON** when the job is active, and **OFF** when the job is inactive. + +### Complete Sketch + +```arduino +#include "thingProperties.h" + +bool toggle; +int LED = 6; + +void setup() { + Serial.begin(9600); + delay(1500); + + initProperties(); + + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); + counter = 0; + light = false; +} + +void loop() { + ArduinoCloud.update(); + // Your code here + if (schedule_test.isActive()) { + light = true; + digitalWrite(LED, HIGH); + + if (toggle) { + counter = ++counter; + toggle = false; + } + } else { + light = false; + digitalWrite(LED, LOW); + toggle = true; + } + if(ArduinoCloud.connected()){ + time_read = ArduinoCloud.getLocalTime(); + } +} + +void onScheduleTestChange() { + +} +``` + +***If you want to see if your board successfully connects to the Cloud, open the Serial Monitor right after the upload finishes. If there's any errors, you will see them there.*** + +### Creating a Dashboard + +Finally, let's build a dashboard that will help us interface with our Arduino board. + +**1.** Head over to the **"Dashboards"** section, and click on the **"Build Dashboard"** button. + +**2.** Now we will need to create a set of widgets that we will link to our variables. Follow the table below to create them. + +| Widget | Variable | +| ----------- | ------------- | +| Scheduler | schedule_test | +| Time Picker | time_read | +| Value | value | +| LED | light | + +***When you create a widget, you will need to click on "Link Variable" in the widget settings, and then choose the variable you want to link (see the image below).*** + +![Linking a widget to a variable.](assets/cloud-scheduler-img-04.png) + +When the dashboard is finished, it should look something like the image below, where we have four widgets in total: + +![The final dashboard.](assets/cloud-scheduler-img-05.png) + +We are now finished with the setup, and can move on to testing out the scheduler feature. + +## Scheduling a Job + +To schedule a job, there are several parameters that can be set: + +- **Start & end** date for a "job". For example, **start** on 1st of December at 00:00, **end** at 31st of December at 12.00. +- **Duration** of the job, set in hours, minutes, seconds. If we for example set 1 minute, the `schedule_test` variable will be `true` for 1 minute. +- **Repetition** interval, how often should this job occur: every minute, hour, day, week, month, day or year. + +To create a job, simply click anywhere on the **scheduler widget**, and configure the job after your preferences. + +![Scheduler Widget settings.](assets/cloud-scheduler-img-06.png) + +### Testing the Scheduler + +In this tutorial, we created a job that has the following parameters: + +- **Start:** today. +- **End:** never. +- **Duration:** 10 seconds. +- **Repeat Every:** minute. + +The sketch used for this is configured to switch the `light` variable to true, whenever the `schedule_test` variable is true. While it is true, the **LED widget**, which is linked to the `light` variable, will be on (for 10 seconds). Each time this happens, the `counter` variable will also increase by 1. + +![The scheduler in action.](assets/scheduler-action.gif) + +### Troubleshoot + +If you have any issues with finishing this tutorial, you can check out some common troubleshooting issues: + +- Is your network credentials correct? If you change these, you will need to upload the sketch again for the changes to have effect. +- If you can't link a widget to a variable, you may have selected the wrong variable type. The **scheduler widget** will only work with the **scheduler variable**. +- Does the variables created in your Thing match the variables in your sketch? For example, if your variable is named `Schedule_test`, the code provided in this tutorial will not work since it is **case sensitive**. + +## Conclusion + +The scheduler is yet another amazing Arduino Cloud feature that allows you to control the future. In this tutorial, we used **just one scheduler**, but you might just as easily create 10 schedulers that can perform actions automatically. This makes it an ideal building block for IoT projects. diff --git a/content/arduino-cloud/06.features/03.device-to-device/device-to-device.md b/content/arduino-cloud/06.features/03.device-to-device/device-to-device.md index f8057356c8..5ca308105d 100644 --- a/content/arduino-cloud/06.features/03.device-to-device/device-to-device.md +++ b/content/arduino-cloud/06.features/03.device-to-device/device-to-device.md @@ -1,295 +1,295 @@ ---- -title: 'Device to Device' -description: 'Learn how to connect two boards through the Arduino Cloud, by syncing their variables.' -tags: - - Device to device -author: 'Karl Söderby' ---- - -## Introduction - -In this tutorial, we will find out how to send data between two Arduino boards, using the Arduino Cloud. Each board will have **one LED and one button each** that will be used to send data between the boards. - -This will be made possible through something called **syncing variables**, which will be explained further in this tutorial. - -## Goals - -The goals of this project are: - -- Set up the Arduino Cloud. -- Create synchronized variables. -- Control an LED remotely with a push button. - -## Hardware & Software needed - -- [Arduino Cloud](https://app.arduino.cc/). -- 2x [Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010) or, -- 2x [Arduino MKR WiFi 1000](https://store.arduino.cc/arduino-mkr1000-wifi) or, -- 2x [Arduino Nano 33 IoT](https://store.arduino.cc/arduino-nano-33-iot) or, -- 2x [Arduino Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect-with-headers). -- Micro USB cable. - -***Note: It is not required to have two devices of the same type. You can for example use a Nano RP2040 Connect and a MKR WiFi 1010. Any [Arduino Cloud enabled Wi-Fi board](/arduino-cloud/hardware/devices#type-of-devices) will work with this tutorial.*** - -We will also need the following components for the circuit: - -- 2x generic LEDs. -- 2x pushbuttons. -- 2x 220 ohm resistors. -- Jumper wires. -- Breadboard. - -## Circuit - -Follow the circuit below to connect the buttons and LEDs to your Arduino board. - -***Note that the pinouts are different on a Nano board. The circuit below is for a MKR WiFi 1000/1010 board.*** - -![Two identical circuits with 1x button and 1x LED each.](assets/device-to-device-img-01.png) - -## Setting up the Arduino Cloud - -To start, we will need to head over to the [Arduino Cloud](https://app.arduino.cc/). This is also accessible through the menu at the top right. - -![1Navigate to the cloud.](assets/device-to-device-img-02.png) - -### Step 1: Configuring two devices - -In this tutorial, we will need to set up **two devices in the Arduino Cloud**. If you have never used this service before, you can check out [our getting started with the IoT cloud guide](https://www.arduino.cc/en/Tutorial/iot-cloud-getting-started). - -Now that we are working with two devices, it is important to separate them from each other, since they will later be linked to two different Things. In this tutorial, we named the devices: - -- **Device_1** -- **Device_2** - -It is a good idea to place a label on the physical board to remember which one is which as well! - -### Step 2: Creating the first Thing - -Let's start by creating a new Thing, for simplicity, let's name it **Remote Light One**. - -![1The Thing overview.](assets/device-to-device-img-02-1.png) - -Now, we will need to add two variables, with the following settings: - -| Variable Name | Data Type | Permission | -| ------------- | --------- | ------------ | -| switch_1 | boolean | read & write | -| switch_2 | boolean | read & write | - -We also need to enter our network details, and select our device (which should be **Device_1**). - -The final overview should look something like this: - -![1The final view.](assets/device-to-device-img-03.png) - -### Step 3: Program the first Thing - -Now, we also need to complete the sketch for our first Thing. First, let's head over to the **"Sketch"** tab in the Arduino Cloud. - -![2Click on the "Sketch" tab to edit the sketch.](assets/device-to-device-img-04.png) - -The code that is needed can be found in the snippet below. Upload the sketch to the first board. - -### Step 4: Complete code for Device_1 - -```arduino -#include "thingProperties.h" - -int buttonPin = 2; -int ledPin = 7; - -void setup() { - // Initialize serial and wait for port to open: - pinMode(buttonPin, INPUT_PULLUP); - pinMode(ledPin, OUTPUT); - - // Initialize serial and wait for port to open: - Serial.begin(9600); - // This delay gives the chance to wait for a Serial Monitor without blocking if none is found - delay(1500); - - // Defined in thingProperties.h - initProperties(); - - // Connect to Arduino Cloud - ArduinoCloud.begin(ArduinoIoTPreferredConnection); - - /* - The following function allows you to obtain more information - related to the state of network and Arduino Cloud connection and errors - the higher number the more granular information you’ll get. - The default is 0 (only errors). - Maximum is 4 - */ - setDebugMessageLevel(2); - ArduinoCloud.printDebugInfo(); -} - -void loop() { - ArduinoCloud.update(); - // Your code here - - int buttonState = digitalRead(buttonPin); - - if(buttonState == LOW) { - switch_1 = !switch_1; - delay(500); - } - -} - -void onSwitch2Change() { - // Do something - -} - -void onSwitch1Change() { - // Do something - if(switch_2) { - digitalWrite(ledPin, HIGH); - } - else{ - digitalWrite(ledPin, LOW); - } -} -``` - -### Step 5: Creating the second Thing - -After we have successfully uploaded the code to our first board, we can go on to create our **second Thing.** - -To create our second Thing, we need to click on the **"Things"** tab, and click on **"Create Thing"**. We can name this one **Remote Light Two**. - -![1Creating the second thing.](assets/device-to-device-img-05.png) - -Now, we need to create the variables we want to sync with the other Thing. First, click on the **"Add Variable"** button. We will name this one **switch_1** as well, and then click on the **"Sync with other things"** option. - -![1Click on "Sync with other things".](assets/device-to-device-img-06.png) - -We will now see the two variables we created inside **Remote Light One**. Let's select the **switch_1** variable and click on **"Synchronize variables"** and finally click on **Add Variable**. - -![1Selecting the variables we want to synchronize.](assets/device-to-device-img-07.png) - -Next, we can repeat the same process for the boolean variable, but instead of selecting the **switch_2** variable to sync with, select the **boolean_sync** variable. Now we should have two variables that are synced with our other Thing. - -Here we will also need to enter our network details, and select our device (which should be **Device_2**). - -### Step 6: Program the second Thing - -Now we will need to edit the sketch for our second Thing. This sketch is almost identical to the previous sketch we made, but the only difference is that we switched places on the **boolean variables**. - -This means that whenever the button is pressed, `switch_2` will change. As it is synced, it will turn ON / OFF the LED on the other board. Similarly, we check if `switch_1` has changed, and turn ON / OFF the LED on this board. - -The code that is needed can be found in the snippet below. Upload the sketch to the board. - ->**Note:** Make sure that you upload this sketch to **Device_2**, as we have already uploaded the first sketch to **Device_1**. - -### Step 7: Complete for Device_2 - -```arduino -#include "thingProperties.h" - -int buttonPin = 2; -int ledPin = 7; - -void setup() { - // Initialize serial and wait for port to open: - pinMode(buttonPin, INPUT_PULLUP); - pinMode(ledPin, OUTPUT); - - // Initialize serial and wait for port to open: - Serial.begin(9600); - // This delay gives the chance to wait for a Serial Monitor without blocking if none is found - delay(1500); - - // Defined in thingProperties.h - initProperties(); - - // Connect to Arduino Cloud - ArduinoCloud.begin(ArduinoIoTPreferredConnection); - - /* - The following function allows you to obtain more information - related to the state of network and Arduino Cloud connection and errors - the higher number the more granular information you’ll get. - The default is 0 (only errors). - Maximum is 4 - */ - setDebugMessageLevel(2); - ArduinoCloud.printDebugInfo(); -} - -void loop() { - ArduinoCloud.update(); - // Your code here - - int buttonState = digitalRead(buttonPin); - - if(buttonState == LOW) { - switch_2 = !switch_2; - delay(500); - } - - -} - -void onSwitch2Change() { - // Do something - -} - -void onSwitch1Change() { - // Do something - if(switch_1) { - digitalWrite(ledPin, HIGH); - } - else{ - digitalWrite(ledPin, LOW); - } -} -``` - -## Testing it out - -After we have successfully uploaded the code to our second Thing, we have completed all the configurations needed for the two boards to communicate. - -Just to re-cap here's what we have done so far: - -- Configured two devices. -- Created two Things. -- Created two variables, `switch_1` and `switch_2`. -- Synced the variables between the Things. -- Uploaded the sketches to **Device_1** and **Device_2**. - -If everything is working properly, and the circuit is wired correctly, we should be able to control both LEDs on each board, by **pressing the button on the opposite board.** - -- The button on **Device_1** will control the LED on **Device_2.** -- The button on **Device_2** will control the LED on **Device_1.** -- The logic is set to turn ON and OFF the LED with the same button. - -![Simple abstraction of how the setup will work.](assets/device-to-device-img-10.png) - -The logic behind it is that one button is each linked to one of the booleans. If for example, `switch_2` is `false`, then the LED in **Remote Light One** will be OFF, and if `switch_1` is set to `true`, the LED in **Remote Light Two** will be off. - -![How the variables synchronize.](assets/device-to-device-img-09.png) - -### Troubleshooting - -- Have you uploaded the sketches correctly? Remember that you need to upload the sketch for **Remote Light One** to **Device_1** and **Remote Light Two** to **Device_2**. -- Have you entered the network details correctly? After you have uploaded the sketch, open the Serial Monitor to see if there is any errors with your connection. -- Have you configured the devices properly? It can sometimes be confusing to which board is which, sometimes it helps to re-configure and re-upload the sketches! - -## Conclusion - -In this tutorial, we created a connection between two Arduino boards, using the Arduino Cloud. We set up two identical circuits, and uploaded two almost identical sketches to the boards. - -The connection between the boards is made through the **syncing of variables**, which allows two Things to communicate with each other. In this case, whenever a boolean is activated on one device, it is also activated on the other device. This **remote ON/OFF switch** is a great building block for creating other cool IoT projects. - -### More tutorials - -You can find more tutorials in the [Arduino Cloud documentation page](/arduino-cloud/). - - - +--- +title: 'Device to Device' +description: 'Learn how to connect two boards through the Arduino Cloud, by syncing their variables.' +tags: + - Device to device +author: 'Karl Söderby' +--- + +## Introduction + +In this tutorial, we will find out how to send data between two Arduino boards, using the Arduino Cloud. Each board will have **one LED and one button each** that will be used to send data between the boards. + +This will be made possible through something called **syncing variables**, which will be explained further in this tutorial. + +## Goals + +The goals of this project are: + +- Set up the Arduino Cloud. +- Create synchronized variables. +- Control an LED remotely with a push button. + +## Hardware & Software needed + +- [Arduino Cloud](https://app.arduino.cc/). +- 2x [Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010) or, +- 2x [Arduino MKR WiFi 1000](https://store.arduino.cc/arduino-mkr1000-wifi) or, +- 2x [Arduino Nano 33 IoT](https://store.arduino.cc/arduino-nano-33-iot) or, +- 2x [Arduino Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect-with-headers). +- Micro USB cable. + +***Note: It is not required to have two devices of the same type. You can for example use a Nano RP2040 Connect and a MKR WiFi 1010. Any [Arduino Cloud enabled Wi-Fi board](/arduino-cloud/hardware/devices#type-of-devices) will work with this tutorial.*** + +We will also need the following components for the circuit: + +- 2x generic LEDs. +- 2x pushbuttons. +- 2x 220 ohm resistors. +- Jumper wires. +- Breadboard. + +## Circuit + +Follow the circuit below to connect the buttons and LEDs to your Arduino board. + +***Note that the pinouts are different on a Nano board. The circuit below is for a MKR WiFi 1000/1010 board.*** + +![Two identical circuits with 1x button and 1x LED each.](assets/device-to-device-img-01.png) + +## Setting up the Arduino Cloud + +To start, we will need to head over to the [Arduino Cloud](https://app.arduino.cc/). This is also accessible through the menu at the top right. + +![1Navigate to the Cloud.](assets/device-to-device-img-02.png) + +### Step 1: Configuring two devices + +In this tutorial, we will need to set up **two devices in the Arduino Cloud**. If you have never used this service before, you can check out [our getting started with the Arduino Cloud guide](https://www.arduino.cc/en/Tutorial/iot-cloud-getting-started). + +Now that we are working with two devices, it is important to separate them from each other, since they will later be linked to two different Things. In this tutorial, we named the devices: + +- **Device_1** +- **Device_2** + +It is a good idea to place a label on the physical board to remember which one is which as well! + +### Step 2: Creating the first Thing + +Let's start by creating a new Thing, for simplicity, let's name it **Remote Light One**. + +![1The Thing overview.](assets/device-to-device-img-02-1.png) + +Now, we will need to add two variables, with the following settings: + +| Variable Name | Data Type | Permission | +| ------------- | --------- | ------------ | +| switch_1 | boolean | read & write | +| switch_2 | boolean | read & write | + +We also need to enter our network details, and select our device (which should be **Device_1**). + +The final overview should look something like this: + +![1The final view.](assets/device-to-device-img-03.png) + +### Step 3: Program the first Thing + +Now, we also need to complete the sketch for our first Thing. First, let's head over to the **"Sketch"** tab in the Arduino Cloud. + +![2Click on the "Sketch" tab to edit the sketch.](assets/device-to-device-img-04.png) + +The code that is needed can be found in the snippet below. Upload the sketch to the first board. + +### Step 4: Complete code for Device_1 + +```arduino +#include "thingProperties.h" + +int buttonPin = 2; +int ledPin = 7; + +void setup() { + // Initialize serial and wait for port to open: + pinMode(buttonPin, INPUT_PULLUP); + pinMode(ledPin, OUTPUT); + + // Initialize serial and wait for port to open: + Serial.begin(9600); + // This delay gives the chance to wait for a Serial Monitor without blocking if none is found + delay(1500); + + // Defined in thingProperties.h + initProperties(); + + // Connect to Arduino Cloud + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + /* + The following function allows you to obtain more information + related to the state of network and Arduino Cloud connection and errors + the higher number the more granular information you’ll get. + The default is 0 (only errors). + Maximum is 4 + */ + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); +} + +void loop() { + ArduinoCloud.update(); + // Your code here + + int buttonState = digitalRead(buttonPin); + + if(buttonState == LOW) { + switch_1 = !switch_1; + delay(500); + } + +} + +void onSwitch2Change() { + // Do something + +} + +void onSwitch1Change() { + // Do something + if(switch_2) { + digitalWrite(ledPin, HIGH); + } + else{ + digitalWrite(ledPin, LOW); + } +} +``` + +### Step 5: Creating the second Thing + +After we have successfully uploaded the code to our first board, we can go on to create our **second Thing.** + +To create our second Thing, we need to click on the **"Things"** tab, and click on **"Create Thing"**. We can name this one **Remote Light Two**. + +![1Creating the second thing.](assets/device-to-device-img-05.png) + +Now, we need to create the variables we want to sync with the other Thing. First, click on the **"Add Variable"** button. We will name this one **switch_1** as well, and then click on the **"Sync with other things"** option. + +![1Click on "Sync with other things".](assets/device-to-device-img-06.png) + +We will now see the two variables we created inside **Remote Light One**. Let's select the **switch_1** variable and click on **"Synchronize variables"** and finally click on **Add Variable**. + +![1Selecting the variables we want to synchronize.](assets/device-to-device-img-07.png) + +Next, we can repeat the same process for the boolean variable, but instead of selecting the **switch_2** variable to sync with, select the **boolean_sync** variable. Now we should have two variables that are synced with our other Thing. + +Here we will also need to enter our network details, and select our device (which should be **Device_2**). + +### Step 6: Program the second Thing + +Now we will need to edit the sketch for our second Thing. This sketch is almost identical to the previous sketch we made, but the only difference is that we switched places on the **boolean variables**. + +This means that whenever the button is pressed, `switch_2` will change. As it is synced, it will turn ON / OFF the LED on the other board. Similarly, we check if `switch_1` has changed, and turn ON / OFF the LED on this board. + +The code that is needed can be found in the snippet below. Upload the sketch to the board. + +>**Note:** Make sure that you upload this sketch to **Device_2**, as we have already uploaded the first sketch to **Device_1**. + +### Step 7: Complete for Device_2 + +```arduino +#include "thingProperties.h" + +int buttonPin = 2; +int ledPin = 7; + +void setup() { + // Initialize serial and wait for port to open: + pinMode(buttonPin, INPUT_PULLUP); + pinMode(ledPin, OUTPUT); + + // Initialize serial and wait for port to open: + Serial.begin(9600); + // This delay gives the chance to wait for a Serial Monitor without blocking if none is found + delay(1500); + + // Defined in thingProperties.h + initProperties(); + + // Connect to Arduino Cloud + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + /* + The following function allows you to obtain more information + related to the state of network and Arduino Cloud connection and errors + the higher number the more granular information you’ll get. + The default is 0 (only errors). + Maximum is 4 + */ + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); +} + +void loop() { + ArduinoCloud.update(); + // Your code here + + int buttonState = digitalRead(buttonPin); + + if(buttonState == LOW) { + switch_2 = !switch_2; + delay(500); + } + + +} + +void onSwitch2Change() { + // Do something + +} + +void onSwitch1Change() { + // Do something + if(switch_1) { + digitalWrite(ledPin, HIGH); + } + else{ + digitalWrite(ledPin, LOW); + } +} +``` + +## Testing it out + +After we have successfully uploaded the code to our second Thing, we have completed all the configurations needed for the two boards to communicate. + +Just to re-cap here's what we have done so far: + +- Configured two devices. +- Created two Things. +- Created two variables, `switch_1` and `switch_2`. +- Synced the variables between the Things. +- Uploaded the sketches to **Device_1** and **Device_2**. + +If everything is working properly, and the circuit is wired correctly, we should be able to control both LEDs on each board, by **pressing the button on the opposite board.** + +- The button on **Device_1** will control the LED on **Device_2.** +- The button on **Device_2** will control the LED on **Device_1.** +- The logic is set to turn ON and OFF the LED with the same button. + +![Simple abstraction of how the setup will work.](assets/device-to-device-img-10.png) + +The logic behind it is that one button is each linked to one of the booleans. If for example, `switch_2` is `false`, then the LED in **Remote Light One** will be OFF, and if `switch_1` is set to `true`, the LED in **Remote Light Two** will be off. + +![How the variables synchronize.](assets/device-to-device-img-09.png) + +### Troubleshooting + +- Have you uploaded the sketches correctly? Remember that you need to upload the sketch for **Remote Light One** to **Device_1** and **Remote Light Two** to **Device_2**. +- Have you entered the network details correctly? After you have uploaded the sketch, open the Serial Monitor to see if there is any errors with your connection. +- Have you configured the devices properly? It can sometimes be confusing to which board is which, sometimes it helps to re-configure and re-upload the sketches! + +## Conclusion + +In this tutorial, we created a connection between two Arduino boards, using the Arduino Cloud. We set up two identical circuits, and uploaded two almost identical sketches to the boards. + +The connection between the boards is made through the **syncing of variables**, which allows two Things to communicate with each other. In this case, whenever a boolean is activated on one device, it is also activated on the other device. This **remote ON/OFF switch** is a great building block for creating other cool IoT projects. + +### More tutorials + +You can find more tutorials in the [Arduino Cloud documentation page](/arduino-cloud/). + + + \ No newline at end of file diff --git a/content/arduino-cloud/06.features/04.ota-getting-started/ota-getting-started.md b/content/arduino-cloud/06.features/04.ota-getting-started/ota-getting-started.md index da96c6ab32..467e65b7ef 100644 --- a/content/arduino-cloud/06.features/04.ota-getting-started/ota-getting-started.md +++ b/content/arduino-cloud/06.features/04.ota-getting-started/ota-getting-started.md @@ -1,159 +1,159 @@ ---- -title: 'Over-The-Air (OTA)' -description: 'Learn how to utilize Over-The-Air (OTA), a feature that allows you to upload sketches remotely.' -tags: - - OTA - - Wireless upload -author: 'Jose Garcia' ---- - -The new Arduino Cloud brings a lot of new things, and one of them is the OTA (over-the-air) feature. This feature allows you to upload programs wirelessly to your Arduino boards. This way, as soon as you have a compatible board connected to a WiFi network and configured to work with OTA, you won’t need to physically connect the board to the computer in order to upload new sketches to it. Instead, everything will work over-the-air. - - -![Over-the-Air uploads.](assets/other_power_supplier.png) - - -Over-the-air update is now available through [Arduino Cloud](https://app.arduino.cc/) and the [Arduino Web Editor](https://create.arduino.cc/editor), which is an always up-to-date online IDE that stores sketches in the Cloud. It also allows you to wirelessly upload sketches from a browser, to any board that is connected to that computer. - -This tutorial will guide you through the necessary steps to configure your board to work with the OTA feature. - -## Compatible Hardware - -OTA is supported on several Arduino devices, as well as many ESP32 devices. - -### Supported Arduino Boards - -- [Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010) -- [Arduino Nano 33 IoT](https://store.arduino.cc/arduino-nano-33-iot) -- [Arduino Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect-with-headers) -- [Portenta H7](https://store.arduino.cc/portenta-h7) -- [Portenta Machine Control](https://store.arduino.cc/products/arduino-portenta-machine-control) -- [Nicla Vision](https://store.arduino.cc/products/nicla-vision) - -### 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 - -## How does it work - -In order to configure the feature, we will need to create a project in the Arduino Cloud following the next steps. - -**1.** Go to the [Arduino Cloud](https://app.arduino.cc/) by opening the grid menu in any Arduino Site. - -![Navigating to the cloud.](assets/iot_cloud_grid.png) - -> **Note:** You will need to have an Arduino account to be able to use both the Web editor and Arduino Cloud features. - - -**2.** Once you are logged in the Arduino Cloud, you need to create a new thing and name it “smart_led”. - Inside the thing let’s include a boolean variable called `light`, activate the interaction **Modify from dashboard API** and select the **on change** variable update. Once we have these characteristics set, click on **add variable**. - - -![Adding a variable.](assets/adding_variable.png) - -> **Note:** If you want to know more about how to get started with the Arduino Cloud, visit the [getting started tutorial](/arduino-cloud/guides/overview). - - -**3.** Once you have added the variable, you’ll need to associate your device (Arduino MKR WiFi 1010 or Arduino Nano 33 IoT) to this new thing and add your network credentials. - -![Selecting a device to associate.](assets/select_device.png) - -***Note: If it is the first time you configure the MKR WiFi 1010 or the Nano 33 IoT board to the Arduino Cloud, you will need to have the latest version of the WiFi Nina firmware installed. The configuration process updates it automatically. However, if you get any error during the configuration process, you can manually update the FW version of the Nina module following [these instructions](https://support.arduino.cc/hc/en-us/articles/360013896579-Check-and-update-the-firmware-for-WiFiNINA-and-WiFi101).*** - - -**4.** Next step is to create a dashboard with a **Switch** widget, linked to the lights variable that you created before. Once it is set, click on the **use dashboard** button and go to **things > smart_led > Sketch** - -![A switch widget.](assets/dashboard_widget.png) - - -**5.** It is time now to edit the sketch. Let’s create a program that turns ON/OFF the `LED_BUILTIN` embedded on your board. To do so, you will need to add just four lines of code to the auto generated sketch: - 1. Initialise as `false` the boolean variable `led_status` at the beginning of the program. - 2. Set as `OUTPUT` the `LED_BUILTIN` pin of the board in the `setup()` function. - 3. Modify the state of the `LED_BUILTIN` pin with the `led_status` variable in the `loop()` function. To do so, let’s use the `digitalWrite()` statement. - 4. Add the statement `led_status = !led_status` inside the `onLightChange()`auto generated function. - - -Check the highlighted lines in the following code to see what required changes are. - - - - - -**6.** Once the sketch has uploaded to your board, let’s check that everything is working as it should. To do so, go back to the Arduino Cloud and once in there, go to the **smart_led** dashboard we created before. Now, when you turn the **light** widget in the dashboard ON or OFF, the LED in your board should also turn ON or OFF. - -![Final dashboard.](assets/final_dashboard.png) - - -Now that we have checked that everything is working as it should, let’s go back to the **Things > smart_led >** **Sketch** tab in the Arduino Cloud, and see what has happened there. - -Once in the sketch tab, let’s open the board's drop down menu. There, a new option to connect our board should be available. The name of the board configured for the cloud will appear, followed by the **Over-the-Air** option. - -![List of devices available.](assets/device_OtA.png) - - -If you select this option, you should be able to upload sketches to your board wirelessly. Let’s learn how to do it, by following the next steps. - -**1.** Let’s modify the program in order to blink the LED each second when we click the button ON, and switch it Off when the button OFF is pressed. - To do it, you will need to modify the `loop()` function by adding the highlighted lines shown in the following sketch. - - - -**2.** Power your board from a different power supplier than your computer's USB cable. Powering it through a phone charger's USB should be enough. - -![img](assets/other_power_supplier.png) - -**3.** Once you have powered the board from a power source other than your computer, you should only see the **Over-the-Air** option. Select it, and upload the program to the board. - -![Over-the-Air board connection](assets/OtA_board_selection.png) - -> **Note:** This option will take a bit longer than usual, since the process of compiling and uploading the program to the board over-the-air is a longer process. - -**4.** Now, if you switch the widget on the Arduino Cloud dashboard ON and OFF, the LED will either blink every second or go off. - - -## But how does it work, inside? - -An Arduino Cloud sketch is generated by the Arduino Cloud application, it leverages the Arduino Cloud and [Arduino Connection Handler](https://github.com/arduino-libraries/Arduino_ConnectionHandler) libraries to give your sketch IoT powers. - - -When uploading a sketch over-the-air: - -- The sketch is compiled for the selected board type. -- The compiled file is stored in a [AWS S3](https://aws.amazon.com/s3/) bucket. -- OTA file url location is associated with the target device. -- OTA_REQ flag set to true to instruct the board to start the OTA file download. -- OTA file length/CRC is verified. -- Updated sketch is flashed on the board. - - -## Conclusion - -In order to upload sketches Over-the-Air to your Arduino board you need: - -- An [Arduino NANO 33 IoT](https://store.arduino.cc/arduino-nano-33-iot) or [Arduino MKR WiFi 1010](https://store.arduino.cc/arduino-mkr-wifi-1010) board. -- NINA firmware on the board, updated to version 1.4.1 or later. -- An **IoT Sketch** to be uploaded. - - -### Next steps - -If you want to continue learning about amazing IoT features or projects you can check: - -- [Oplà IoT Kit](https://opla.arduino.cc/) - ---- - -### More tutorials - -You can find more tutorials in the [Arduino Cloud documentation page](/arduino-cloud/). +--- +title: 'Over-The-Air (OTA)' +description: 'Learn how to utilize Over-The-Air (OTA), a feature that allows you to upload sketches remotely.' +tags: + - OTA + - Wireless upload +author: 'Jose Garcia' +--- + +The new Arduino Cloud brings a lot of new things, and one of them is the OTA (over-the-air) feature. This feature allows you to upload programs wirelessly to your Arduino boards. This way, as soon as you have a compatible board connected to a WiFi network and configured to work with OTA, you won’t need to physically connect the board to the computer in order to upload new sketches to it. Instead, everything will work over-the-air. + + +![Over-the-Air uploads.](assets/other_power_supplier.png) + + +Over-the-air update is now available through [Arduino Cloud](https://app.arduino.cc/) and the [Arduino Web Editor](https://create.arduino.cc/editor), which is an always up-to-date online IDE that stores sketches in the Cloud. It also allows you to wirelessly upload sketches from a browser, to any board that is connected to that computer. + +This tutorial will guide you through the necessary steps to configure your board to work with the OTA feature. + +## Compatible Hardware + +OTA is supported on several Arduino devices, as well as many ESP32 devices. + +### Supported Arduino Boards + +- [Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010) +- [Arduino Nano 33 IoT](https://store.arduino.cc/arduino-nano-33-iot) +- [Arduino Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect-with-headers) +- [Portenta H7](https://store.arduino.cc/portenta-h7) +- [Portenta Machine Control](https://store.arduino.cc/products/arduino-portenta-machine-control) +- [Nicla Vision](https://store.arduino.cc/products/nicla-vision) + +### 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 + +## How does it work + +In order to configure the feature, we will need to create a project in the Arduino Cloud following the next steps. + +**1.** Go to the [Arduino Cloud](https://app.arduino.cc/) by opening the grid menu in any Arduino Site. + +![Navigating to the Cloud.](assets/iot_cloud_grid.png) + +> **Note:** You will need to have an Arduino account to be able to use both the Web editor and Arduino Cloud features. + + +**2.** Once you are logged in the Arduino Cloud, you need to create a new thing and name it “smart_led”. + Inside the thing let’s include a boolean variable called `light`, activate the interaction **Modify from dashboard API** and select the **on change** variable update. Once we have these characteristics set, click on **add variable**. + + +![Adding a variable.](assets/adding_variable.png) + +> **Note:** If you want to know more about how to get started with the Arduino Cloud, visit the [getting started tutorial](/arduino-cloud/guides/overview). + + +**3.** Once you have added the variable, you’ll need to associate your device (Arduino MKR WiFi 1010 or Arduino Nano 33 IoT) to this new thing and add your network credentials. + +![Selecting a device to associate.](assets/select_device.png) + +***Note: If it is the first time you configure the MKR WiFi 1010 or the Nano 33 IoT board to the Arduino Cloud, you will need to have the latest version of the WiFi Nina firmware installed. The configuration process updates it automatically. However, if you get any error during the configuration process, you can manually update the FW version of the Nina module following [these instructions](https://support.arduino.cc/hc/en-us/articles/360013896579-Check-and-update-the-firmware-for-WiFiNINA-and-WiFi101).*** + + +**4.** Next step is to create a dashboard with a **Switch** widget, linked to the lights variable that you created before. Once it is set, click on the **use dashboard** button and go to **things > smart_led > Sketch** + +![A switch widget.](assets/dashboard_widget.png) + + +**5.** It is time now to edit the sketch. Let’s create a program that turns ON/OFF the `LED_BUILTIN` embedded on your board. To do so, you will need to add just four lines of code to the auto generated sketch: + 1. Initialise as `false` the boolean variable `led_status` at the beginning of the program. + 2. Set as `OUTPUT` the `LED_BUILTIN` pin of the board in the `setup()` function. + 3. Modify the state of the `LED_BUILTIN` pin with the `led_status` variable in the `loop()` function. To do so, let’s use the `digitalWrite()` statement. + 4. Add the statement `led_status = !led_status` inside the `onLightChange()`auto generated function. + + +Check the highlighted lines in the following code to see what required changes are. + + + + + +**6.** Once the sketch has uploaded to your board, let’s check that everything is working as it should. To do so, go back to the Arduino Cloud and once in there, go to the **smart_led** dashboard we created before. Now, when you turn the **light** widget in the dashboard ON or OFF, the LED in your board should also turn ON or OFF. + +![Final dashboard.](assets/final_dashboard.png) + + +Now that we have checked that everything is working as it should, let’s go back to the **Things > smart_led >** **Sketch** tab in the Arduino Cloud, and see what has happened there. + +Once in the sketch tab, let’s open the board's drop down menu. There, a new option to connect our board should be available. The name of the board configured for the Cloud will appear, followed by the **Over-the-Air** option. + +![List of devices available.](assets/device_OtA.png) + + +If you select this option, you should be able to upload sketches to your board wirelessly. Let’s learn how to do it, by following the next steps. + +**1.** Let’s modify the program in order to blink the LED each second when we click the button ON, and switch it Off when the button OFF is pressed. + To do it, you will need to modify the `loop()` function by adding the highlighted lines shown in the following sketch. + + + +**2.** Power your board from a different power supplier than your computer's USB cable. Powering it through a phone charger's USB should be enough. + +![img](assets/other_power_supplier.png) + +**3.** Once you have powered the board from a power source other than your computer, you should only see the **Over-the-Air** option. Select it, and upload the program to the board. + +![Over-the-Air board connection](assets/OtA_board_selection.png) + +> **Note:** This option will take a bit longer than usual, since the process of compiling and uploading the program to the board over-the-air is a longer process. + +**4.** Now, if you switch the widget on the Arduino Cloud dashboard ON and OFF, the LED will either blink every second or go off. + + +## But how does it work, inside? + +An Arduino Cloud sketch is generated by the Arduino Cloud application, it leverages the Arduino Cloud and [Arduino Connection Handler](https://github.com/arduino-libraries/Arduino_ConnectionHandler) libraries to give your sketch IoT powers. + + +When uploading a sketch over-the-air: + +- The sketch is compiled for the selected board type. +- The compiled file is stored in a [AWS S3](https://aws.amazon.com/s3/) bucket. +- OTA file url location is associated with the target device. +- OTA_REQ flag set to true to instruct the board to start the OTA file download. +- OTA file length/CRC is verified. +- Updated sketch is flashed on the board. + + +## Conclusion + +In order to upload sketches Over-the-Air to your Arduino board you need: + +- An [Arduino NANO 33 IoT](https://store.arduino.cc/arduino-nano-33-iot) or [Arduino MKR WiFi 1010](https://store.arduino.cc/arduino-mkr-wifi-1010) board. +- NINA firmware on the board, updated to version 1.4.1 or later. +- An **IoT Sketch** to be uploaded. + + +### Next steps + +If you want to continue learning about amazing IoT features or projects you can check: + +- [Oplà IoT Kit](https://opla.arduino.cc/) + +--- + +### More tutorials + +You can find more tutorials in the [Arduino Cloud documentation page](/arduino-cloud/). diff --git a/content/arduino-cloud/06.features/05.sharing-dashboards/sharing-dashboards.md b/content/arduino-cloud/06.features/05.sharing-dashboards/sharing-dashboards.md index 50edc7a8bd..f5557d8cde 100644 --- a/content/arduino-cloud/06.features/05.sharing-dashboards/sharing-dashboards.md +++ b/content/arduino-cloud/06.features/05.sharing-dashboards/sharing-dashboards.md @@ -9,7 +9,7 @@ software: - iot-cloud --- -The Arduino Cloud IoT is a great tool for remote control and analytics of your devices. A central component in the cloud system is the **dashboards**, the tool that is used to visualize and interact with you devices. +The Arduino Cloud IoT is a great tool for remote control and analytics of your devices. A central component in the Cloud system is the **dashboards**, the tool that is used to visualize and interact with you devices. In this tutorial, we will show how to share these dashboards with other Arduino Cloud users! @@ -20,7 +20,7 @@ If you want to get started with the Arduino Cloud IoT, you can check out [gettin >**Note:** Before we start, let's make sure that we have a **Thing** and **Dashboard** already set up. If you haven't got that set up, check out the [Getting Started with Arduino Cloud](/arduino-cloud/guides/overview) tutorial. -The Arduino Cloud's dashboard feature is a really good tool for sending, receiving and storing data through the cloud. You can now also share your dashboards with other people, so that they can access your devices as well, without having access to your account! +The Arduino Cloud's dashboard feature is a really good tool for sending, receiving and storing data through the Cloud. You can now also share your dashboards with other people, so that they can access your devices as well, without having access to your account! The **sharing dashboards** feature is really easy to use, but let's take a look at how it is done! diff --git a/content/arduino-cloud/06.features/06.thing-to-thing/thing-to-thing.md b/content/arduino-cloud/06.features/06.thing-to-thing/thing-to-thing.md index 818b9b3a47..eafdce7209 100644 --- a/content/arduino-cloud/06.features/06.thing-to-thing/thing-to-thing.md +++ b/content/arduino-cloud/06.features/06.thing-to-thing/thing-to-thing.md @@ -1,164 +1,164 @@ ---- -title: 'Syncing Variables Across Things' -description: 'Learn how two Things can communicate with each other through variable syncing.' -tags: - - Variable Synchronization -author: 'Karl Söderby' ---- - -## Introduction - -The Thing to Thing communication is a great feature that allows you to synchronize your Arduino devices. It enables you to pair **variables** of the same data type between things and with the Arduino Cloud, creating a two-way communication between your devices has never been easier. - -## Goals - -The goals of this project are: - -- Learn how to set up the Thing to Thing communication. -- Sync a variable containing a value between two Things. -- Trigger a boolean between two Things. - -## Hardware & Software needed - -- [Arduino Cloud](https://app.arduino.cc/) (with a Maker subscription, read more [here](https://store.arduino.cc/digital/create)). -- 2x [Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010) or, -- 2x [Arduino MKR WiFi 1000](https://store.arduino.cc/arduino-mkr1000-wifi) or, -- 2x [Arduino Nano 33 IoT](https://store.arduino.cc/arduino-nano-33-iot) or, -- 2x [Arduino Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect-with-headers). - - -## Circuit - -In this tutorial, we are using no external circuit. You will only need 2x Arduino Cloud compatible devices. You can for example use one Nano 33 IoT and one MKR WiFi 1010. - -![Choosing two IoT boards.](assets/thing-to-thing-circuit.png) - -## Setting up the Things - -To start, we will need to head over to the [Arduino Cloud](https://app.arduino.cc/). This is also accessible through the menu at the top right. - -![Navigate to the cloud.](assets/thing-to-thing-img-00.png) - -### Step 1: Configuring two devices - -To enable Thing to Thing communication, we will first need to configure the two devices. If you have never used the Arduino Cloud before, you can check out [our getting started with the IoT cloud guide](https://www.arduino.cc/en/Tutorial/iot-cloud-getting-started). - -Now that we are working with two devices, it is important to separate them from each other, since they will later be linked to two different Things. In this tutorial, we named the devices: - -- **Device_1** -- **Device_2** - -It is a good idea to place a label on the physical board to remember which one is which as well! - -### Step 2: Creating the first Thing - -Let's start by creating a new Thing, for simplicity, let's name it **Thing Number One**. - -![Creating Thing number one.](assets/thing-to-thing-img-01.png) - -Now, we will need to add two variables, with the following settings: - -| Variable Name | Data Type | Permission | -| ------------- | --------- | ------------ | -| analog_value | integer | read & write | -| boolean_sync | boolean | read & write | - -We also need to enter our network details, and select our device (which should be **Device_1**). - -The final overview should look something like this: - -![Final overview.](assets/thing-to-thing-img-02.png) - -Finally, we need to edit and upload the code to the board. We are only making one addition to the code. Inside `void loop()`, add the following line: - -```arduino -analog_value = analogRead(A1); -``` - -This means we would simply read pin A1, which we have not connected anything to, but will generate random values. You can now upload the code to the board. - -When it is finished uploading, we can move on to the next step. - -### Step 3: Creating the second Thing - -To create our second Thing, we need to click on the **"Things"** tab, and click on **"Create Thing"**. We can name this one **Thing Number Two**. - -![Creating a second Thing.](assets/thing-to-thing-img-03.png) - -Now, we need to create the variables we want to sync with the other Thing. First, click on the **"Add Variable"** button. We will now click on the **"Sync with other things"** option. - -![Click on "Sync with other Things".](assets/thing-to-thing-img-04.png) - -We will now see the two variables we created inside **Thing Number One**. Let's select the **analog_value** variable and click on **"Synchronize variables"**. - -![Selecting variables to synchronize.](assets/thing-to-thing-img-05.png) - -Finally, we need to name it something fitting, such as **analog_value_2**, and click on the **"Add Variable"** button. - -![Adding the variable.](assets/thing-to-thing-img-06.png) - -Next, we can repeat the same process for the boolean variable, but instead of selecting the **analog_value** variable to sync with, select the **boolean_sync** variable. Now we should have two variables that are synced with our other Thing. - -Here we will also need to enter our network details, and select our device (which should be **Device_2**). - -Then we can move on to the sketch. Inside the sketch we actually **don't need to edit anything**. Simply upload the sketch to **Device_2**. - -Once the upload is successful, we can move on to the next step! - -## Creating a dashboard - -With both **Device_1** and **Device_2** up and running, we can go on to **create a dashboard**. Navigate to the **"Dashboards"** tab, and click on the **"Build Dashboard"** button. - -### Step 1: Creating widgets for Thing Number One - -In the new, empty dashboard, click on **"Add"** and select **"Gauge"** from the list. - -![Adding a gauge widget.](assets/thing-to-thing-img-07.png) - -Then, we need to click on the **"Link Variable"** button. - -![Click on](assets/thing-to-thing-img-08.png) - -Now, let's link it to the **analog_value** variable, inside **Thing Number One**. Then click on the **"Link Variable"** button. - -![Linking the variable.](assets/thing-to-thing-img-09.png) - -We need to set the threshold values to **Min: 0** and **Max: 1000**, and click on the **"Done"** button. - -![Setting the thresholds values.](assets/thing-to-thing-img-10.png) - -Our widget will now appear in the dashboard. Next, let's add a **Switch** widget, following the same process to link it to the **boolean_sync** variable inside **Thing Number One**. After adding it, we will have two widgets: a **gauge** and a **switch**. - -![Dashboard with gauge and switch.](assets/thing-to-thing-img-11.png) - -### Step 2: Creating widgets for Thing Number Two - -Now that we have created the widgets and linked them to the variables from **Thing Number One**, we need to do the same for the variables that we sync from **Thing Number Two**. - -The process of creating them is identical to the previous steps, but we need to select the variables inside **Thing Number Two**. When it is finished, the complete dashboard should look like this: - -![The complete dashboard.](assets/thing-to-thing-img-12.png) - -## Testing it out - -Now that everything is set up, let's test it out. First of all, we can verify that the two **gauge widgets** are updating continuously, and that they show the same values (with a short delay). - -This is because they are only recorded by **Device_1**, linked with **Thing Number One**, which has the variable **analog_value**. Since **analog_value** and **analog_value_2** are synced, the values in the widgets are the same! - -![Synced variables.](assets/thing-to-thing-img-13.png) - -Now, that the boolean variables are set up just to test that the communication is working between the two Things. To test it, simply change the state of the switch to **"ON"** by clicking on it. After a short pause we will see the other switch turn to **"ON"** as well. The same thing will happen if we turn one switch to **"OFF"**, then the other should follow shortly after. - -![Two synchronized Things.](assets/dashboard_motion.gif) - -This means that our devices are linked, and whenever we update one of them, the other one follows. And that's how the variable sync works in a nutshell! - -## Conclusion - -The **Thing to Thing Communication** is an amazing feature that is easy to set up and has various benefits. In this tutorial we simply demonstrated the very basics by syncing two variables between two Things, but there is a lot more to explore! - -We hope you enjoyed this tutorial and that it helped you to get started with your next IoT project! - -### More tutorials - +--- +title: 'Syncing Variables Across Things' +description: 'Learn how two Things can communicate with each other through variable syncing.' +tags: + - Variable Synchronization +author: 'Karl Söderby' +--- + +## Introduction + +The Thing to Thing communication is a great feature that allows you to synchronize your Arduino devices. It enables you to pair **variables** of the same data type between things and with the Arduino Cloud, creating a two-way communication between your devices has never been easier. + +## Goals + +The goals of this project are: + +- Learn how to set up the Thing to Thing communication. +- Sync a variable containing a value between two Things. +- Trigger a boolean between two Things. + +## Hardware & Software needed + +- [Arduino Cloud](https://app.arduino.cc/) (with a Maker subscription, read more [here](https://store.arduino.cc/digital/create)). +- 2x [Arduino MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010) or, +- 2x [Arduino MKR WiFi 1000](https://store.arduino.cc/arduino-mkr1000-wifi) or, +- 2x [Arduino Nano 33 IoT](https://store.arduino.cc/arduino-nano-33-iot) or, +- 2x [Arduino Nano RP2040 Connect](https://store.arduino.cc/nano-rp2040-connect-with-headers). + + +## Circuit + +In this tutorial, we are using no external circuit. You will only need 2x Arduino Cloud compatible devices. You can for example use one Nano 33 IoT and one MKR WiFi 1010. + +![Choosing two IoT boards.](assets/thing-to-thing-circuit.png) + +## Setting up the Things + +To start, we will need to head over to the [Arduino Cloud](https://app.arduino.cc/). This is also accessible through the menu at the top right. + +![Navigate to the Cloud.](assets/thing-to-thing-img-00.png) + +### Step 1: Configuring two devices + +To enable Thing to Thing communication, we will first need to configure the two devices. If you have never used the Arduino Cloud before, you can check out [our getting started with the Arduino Cloud guide](https://www.arduino.cc/en/Tutorial/iot-cloud-getting-started). + +Now that we are working with two devices, it is important to separate them from each other, since they will later be linked to two different Things. In this tutorial, we named the devices: + +- **Device_1** +- **Device_2** + +It is a good idea to place a label on the physical board to remember which one is which as well! + +### Step 2: Creating the first Thing + +Let's start by creating a new Thing, for simplicity, let's name it **Thing Number One**. + +![Creating Thing number one.](assets/thing-to-thing-img-01.png) + +Now, we will need to add two variables, with the following settings: + +| Variable Name | Data Type | Permission | +| ------------- | --------- | ------------ | +| analog_value | integer | read & write | +| boolean_sync | boolean | read & write | + +We also need to enter our network details, and select our device (which should be **Device_1**). + +The final overview should look something like this: + +![Final overview.](assets/thing-to-thing-img-02.png) + +Finally, we need to edit and upload the code to the board. We are only making one addition to the code. Inside `void loop()`, add the following line: + +```arduino +analog_value = analogRead(A1); +``` + +This means we would simply read pin A1, which we have not connected anything to, but will generate random values. You can now upload the code to the board. + +When it is finished uploading, we can move on to the next step. + +### Step 3: Creating the second Thing + +To create our second Thing, we need to click on the **"Things"** tab, and click on **"Create Thing"**. We can name this one **Thing Number Two**. + +![Creating a second Thing.](assets/thing-to-thing-img-03.png) + +Now, we need to create the variables we want to sync with the other Thing. First, click on the **"Add Variable"** button. We will now click on the **"Sync with other things"** option. + +![Click on "Sync with other Things".](assets/thing-to-thing-img-04.png) + +We will now see the two variables we created inside **Thing Number One**. Let's select the **analog_value** variable and click on **"Synchronize variables"**. + +![Selecting variables to synchronize.](assets/thing-to-thing-img-05.png) + +Finally, we need to name it something fitting, such as **analog_value_2**, and click on the **"Add Variable"** button. + +![Adding the variable.](assets/thing-to-thing-img-06.png) + +Next, we can repeat the same process for the boolean variable, but instead of selecting the **analog_value** variable to sync with, select the **boolean_sync** variable. Now we should have two variables that are synced with our other Thing. + +Here we will also need to enter our network details, and select our device (which should be **Device_2**). + +Then we can move on to the sketch. Inside the sketch we actually **don't need to edit anything**. Simply upload the sketch to **Device_2**. + +Once the upload is successful, we can move on to the next step! + +## Creating a dashboard + +With both **Device_1** and **Device_2** up and running, we can go on to **create a dashboard**. Navigate to the **"Dashboards"** tab, and click on the **"Build Dashboard"** button. + +### Step 1: Creating widgets for Thing Number One + +In the new, empty dashboard, click on **"Add"** and select **"Gauge"** from the list. + +![Adding a gauge widget.](assets/thing-to-thing-img-07.png) + +Then, we need to click on the **"Link Variable"** button. + +![Click on](assets/thing-to-thing-img-08.png) + +Now, let's link it to the **analog_value** variable, inside **Thing Number One**. Then click on the **"Link Variable"** button. + +![Linking the variable.](assets/thing-to-thing-img-09.png) + +We need to set the threshold values to **Min: 0** and **Max: 1000**, and click on the **"Done"** button. + +![Setting the thresholds values.](assets/thing-to-thing-img-10.png) + +Our widget will now appear in the dashboard. Next, let's add a **Switch** widget, following the same process to link it to the **boolean_sync** variable inside **Thing Number One**. After adding it, we will have two widgets: a **gauge** and a **switch**. + +![Dashboard with gauge and switch.](assets/thing-to-thing-img-11.png) + +### Step 2: Creating widgets for Thing Number Two + +Now that we have created the widgets and linked them to the variables from **Thing Number One**, we need to do the same for the variables that we sync from **Thing Number Two**. + +The process of creating them is identical to the previous steps, but we need to select the variables inside **Thing Number Two**. When it is finished, the complete dashboard should look like this: + +![The complete dashboard.](assets/thing-to-thing-img-12.png) + +## Testing it out + +Now that everything is set up, let's test it out. First of all, we can verify that the two **gauge widgets** are updating continuously, and that they show the same values (with a short delay). + +This is because they are only recorded by **Device_1**, linked with **Thing Number One**, which has the variable **analog_value**. Since **analog_value** and **analog_value_2** are synced, the values in the widgets are the same! + +![Synced variables.](assets/thing-to-thing-img-13.png) + +Now, that the boolean variables are set up just to test that the communication is working between the two Things. To test it, simply change the state of the switch to **"ON"** by clicking on it. After a short pause we will see the other switch turn to **"ON"** as well. The same thing will happen if we turn one switch to **"OFF"**, then the other should follow shortly after. + +![Two synchronized Things.](assets/dashboard_motion.gif) + +This means that our devices are linked, and whenever we update one of them, the other one follows. And that's how the variable sync works in a nutshell! + +## Conclusion + +The **Thing to Thing Communication** is an amazing feature that is easy to set up and has various benefits. In this tutorial we simply demonstrated the very basics by syncing two variables between two Things, but there is a lot more to explore! + +We hope you enjoyed this tutorial and that it helped you to get started with your next IoT project! + +### More tutorials + You can find more tutorials in the [Arduino Cloud documentation page](/arduino-cloud/). \ No newline at end of file diff --git a/content/arduino-cloud/06.features/07.arduino-cloud-callbacks/arduino-cloud-callbacks.md b/content/arduino-cloud/06.features/07.arduino-cloud-callbacks/arduino-cloud-callbacks.md index 0a8fec4027..faf798a03d 100644 --- a/content/arduino-cloud/06.features/07.arduino-cloud-callbacks/arduino-cloud-callbacks.md +++ b/content/arduino-cloud/06.features/07.arduino-cloud-callbacks/arduino-cloud-callbacks.md @@ -1,42 +1,42 @@ ---- -title: 'Event & Callbacks' -description: 'Learn how to subscribe to events and add callback functions.' -tags: [Arduino Cloud, Events, Callbacks] -author: 'Karl Söderby' ---- - -The [Arduino Cloud](https://app.arduino.cc/) has support for events and callbacks. This can be used to trigger specific functionalities depending on what state your device is in. - -You can for example trigger a specific block of code whenever the board is in a **connecting**, **synchronized** or **disconnected** state. In this document, we will explore how to set it up, using an example from the [ArduinoIoTCloud](https://github.com/arduino-libraries/ArduinoIoTCloud/blob/master/examples/ArduinoIoTCloud-Callbacks/ArduinoIoTCloud-Callbacks.ino) library. - -## Events - -The `ArduinoIoTCloudEvent` enumeration class has three possible events: -- `CONNECT` (0) - Board successfully connects to Arduino Cloud. -- `SYNC` (1) - Data is successfully synced between Board and Arduino Cloud. -- `DISCONNECT` (2) - Board has lost connection to Arduino Cloud. - -The `CONNECT` and `DISCONNECT` events can occur even though no variable is created inside the Thing. However, `SYNC` requires a variable to be created, as this triggers whenever data is synchronized between the board and cloud. - -These events can be subscribed to using the `addCallback()` function, which is documented in the next section. - -## Callbacks - -Callbacks can be added for each event, and essentially triggers a custom function whenever the event occurs. - -Callbacks are added via the `addCallback()` method from the `ArduinoIoTCloud` class, where the **event** and **custom function** are added as parameters. - -```arduino -ArduinoCloud.addCallback(ArduinoIoTCloudEvent::CONNECT, doThisOnConnect); -``` - -The above code will trigger the `doThisOnConnect()` -function whenever the `CONNECT` event occurs. - -***Please note that callback functions should be added inside the `setup()` of your sketch.*** - -## Full Example - -The example below demonstrates how to use events & callbacks in the Arduino Cloud. - +--- +title: 'Event & Callbacks' +description: 'Learn how to subscribe to events and add callback functions.' +tags: [Arduino Cloud, Events, Callbacks] +author: 'Karl Söderby' +--- + +The [Arduino Cloud](https://app.arduino.cc/) has support for events and callbacks. This can be used to trigger specific functionalities depending on what state your device is in. + +You can for example trigger a specific block of code whenever the board is in a **connecting**, **synchronized** or **disconnected** state. In this document, we will explore how to set it up, using an example from the [ArduinoIoTCloud](https://github.com/arduino-libraries/ArduinoIoTCloud/blob/master/examples/ArduinoIoTCloud-Callbacks/ArduinoIoTCloud-Callbacks.ino) library. + +## Events + +The `ArduinoIoTCloudEvent` enumeration class has three possible events: +- `CONNECT` (0) - Board successfully connects to Arduino Cloud. +- `SYNC` (1) - Data is successfully synced between Board and Arduino Cloud. +- `DISCONNECT` (2) - Board has lost connection to Arduino Cloud. + +The `CONNECT` and `DISCONNECT` events can occur even though no variable is created inside the Thing. However, `SYNC` requires a variable to be created, as this triggers whenever data is synchronized between the board and Cloud. + +These events can be subscribed to using the `addCallback()` function, which is documented in the next section. + +## Callbacks + +Callbacks can be added for each event, and essentially triggers a custom function whenever the event occurs. + +Callbacks are added via the `addCallback()` method from the `ArduinoIoTCloud` class, where the **event** and **custom function** are added as parameters. + +```arduino +ArduinoCloud.addCallback(ArduinoIoTCloudEvent::CONNECT, doThisOnConnect); +``` + +The above code will trigger the `doThisOnConnect()` +function whenever the `CONNECT` event occurs. + +***Please note that callback functions should be added inside the `setup()` of your sketch.*** + +## Full Example + +The example below demonstrates how to use events & callbacks in the Arduino Cloud. + \ No newline at end of file diff --git a/content/arduino-cloud/06.features/08.iot-cloud-historical-data/iot-cloud-historical-data.md b/content/arduino-cloud/06.features/08.iot-cloud-historical-data/iot-cloud-historical-data.md index 1da44bfd10..09e66a1283 100644 --- a/content/arduino-cloud/06.features/08.iot-cloud-historical-data/iot-cloud-historical-data.md +++ b/content/arduino-cloud/06.features/08.iot-cloud-historical-data/iot-cloud-historical-data.md @@ -1,65 +1,65 @@ ---- -title: 'Download Historical Data' -description: 'Learn how to download historical data from the Arduino Cloud' -tags: [Arduino Cloud, Historical Data, CSV] -author: 'Benjamin Dannegård' ---- - -## Introduction - -It is possible to download historical data from your [Arduino Cloud](https://app.arduino.cc/) Things and Variables. It is downloaded in `.csv` format, and can be used for data comparison. - -## Goals - -The goals of this tutorial are: - -- Learn about Arduino cloud historical data -- Learn how to use this data - -## Hardware & Software Needed - -You do not need an active board to download the historical data, but for initial data collection, you will need a cloud compatible board. - -To see all compatible boards, check out the link below: - -- [Arduino Cloud compatible boards](/arduino-cloud/hardware/devices#type-of-devices). - -### Different Historical Data - -If you are running a home automation to turn the lights on when it's dark, your system is working with (pretty much) real-time data. So 24 hours of sensor information is perfectly adequate. It's not like you'll be turning a lamp on or off based on yesterday's ambient light levels. - -A weather station might work a bit differently though. If you're measuring the temperature or rainfall or daylight hours, you may want to build a comparison to see how the weather is changing. In this case using 15 days of data would be more suitable, allowing you to monitor and record recent changes in your weather station's variables. - -Historical data for an IoT greenhouse, or maybe an aquarium or terrarium, would be much more important. Maybe it's even an industrial project that's monitoring equipment for predictive maintenance needs. In these cases, being able to look back at your variables over previous weeks and months could be essential. - -### Putting Historical Data to Use in Arduino Cloud - -Arduino Cloud is really clever when it comes to the data generated by sensors and used as variables. For example, you can specify how often new data is sent to your Arduino Cloud. Let's say you are monitoring Wi-Fi signal strength at the end of the garden, where a project (weather station for example) is installed. If this is a solar and/or battery powered device, power consumption becomes essential. By changing the data sampling interval from updating a variable on Arduino Cloud every second to updating once a minute, you can extend battery life by a huge amount. The device is only operating a fraction of the time it was before, and the information is just as useful. - -Combined with 15 days or three months of historical data, you can build a detailed picture of Wi-Fi performance that lets you keep everything running perfectly. Or, if you need to find out when and why your signal has been dropping, the story is right there in your Arduino Cloud dashboard historical data. - -## Instructions - -### Downloading Historical Data - -First, to download historical data navigate into one of your dashboards on the [Arduino Cloud](https://app.arduino.cc/dashboards). - -![Arduino cloud dashboard.](assets/cloud-historical-data-dashboard.png) - -While inside a dashboard, press the **Download** icon up in the right corner. This will open a new window that allows you to select historical data to download. - -![Window with historical data inside dashboard.](assets/cloud-historical-data.png) - -From here you can select all the variables you want to download by checking the boxes. If your dashboard is using multiple Things, you can swap between them from the dropdown at the top. - -When you have selected the data, click on the **"Select Data Source"** button. - -![Selecting variables for historical data.](assets/cloud-historical-data-selecting-variable.png) - -In the next window, click on the **"Get Data"** button. The download link will now be sent directly to your email address linked to your account. - -![Email confirmation.](assets/cloud-historical-data-confirmation.png) - -## Conclusion - +--- +title: 'Download Historical Data' +description: 'Learn how to download historical data from the Arduino Cloud' +tags: [Arduino Cloud, Historical Data, CSV] +author: 'Benjamin Dannegård' +--- + +## Introduction + +It is possible to download historical data from your [Arduino Cloud](https://app.arduino.cc/) Things and Variables. It is downloaded in `.csv` format, and can be used for data comparison. + +## Goals + +The goals of this tutorial are: + +- Learn about Arduino Cloud historical data +- Learn how to use this data + +## Hardware & Software Needed + +You do not need an active board to download the historical data, but for initial data collection, you will need a Cloud compatible board. + +To see all compatible boards, check out the link below: + +- [Arduino Cloud compatible boards](/arduino-cloud/hardware/devices#type-of-devices). + +### Different Historical Data + +If you are running a home automation to turn the lights on when it's dark, your system is working with (pretty much) real-time data. So 24 hours of sensor information is perfectly adequate. It's not like you'll be turning a lamp on or off based on yesterday's ambient light levels. + +A weather station might work a bit differently though. If you're measuring the temperature or rainfall or daylight hours, you may want to build a comparison to see how the weather is changing. In this case using 15 days of data would be more suitable, allowing you to monitor and record recent changes in your weather station's variables. + +Historical data for an IoT greenhouse, or maybe an aquarium or terrarium, would be much more important. Maybe it's even an industrial project that's monitoring equipment for predictive maintenance needs. In these cases, being able to look back at your variables over previous weeks and months could be essential. + +### Putting Historical Data to Use in Arduino Cloud + +Arduino Cloud is really clever when it comes to the data generated by sensors and used as variables. For example, you can specify how often new data is sent to your Arduino Cloud. Let's say you are monitoring Wi-Fi signal strength at the end of the garden, where a project (weather station for example) is installed. If this is a solar and/or battery powered device, power consumption becomes essential. By changing the data sampling interval from updating a variable on Arduino Cloud every second to updating once a minute, you can extend battery life by a huge amount. The device is only operating a fraction of the time it was before, and the information is just as useful. + +Combined with 15 days or three months of historical data, you can build a detailed picture of Wi-Fi performance that lets you keep everything running perfectly. Or, if you need to find out when and why your signal has been dropping, the story is right there in your Arduino Cloud dashboard historical data. + +## Instructions + +### Downloading Historical Data + +First, to download historical data navigate into one of your dashboards on the [Arduino Cloud](https://app.arduino.cc/dashboards). + +![Arduino Cloud dashboard.](assets/cloud-historical-data-dashboard.png) + +While inside a dashboard, press the **Download** icon up in the right corner. This will open a new window that allows you to select historical data to download. + +![Window with historical data inside dashboard.](assets/cloud-historical-data.png) + +From here you can select all the variables you want to download by checking the boxes. If your dashboard is using multiple Things, you can swap between them from the dropdown at the top. + +When you have selected the data, click on the **"Select Data Source"** button. + +![Selecting variables for historical data.](assets/cloud-historical-data-selecting-variable.png) + +In the next window, click on the **"Get Data"** button. The download link will now be sent directly to your email address linked to your account. + +![Email confirmation.](assets/cloud-historical-data-confirmation.png) + +## Conclusion + In this tutorial you learned what applications historical data could have, and how to extract historical data from your Arduino Cloud dashboard. \ No newline at end of file diff --git a/content/arduino-cloud/06.features/08.manual-device/manual-devices.md b/content/arduino-cloud/06.features/08.manual-device/manual-devices.md index 26a9a8f83a..fd7ccb3f8e 100644 --- a/content/arduino-cloud/06.features/08.manual-device/manual-devices.md +++ b/content/arduino-cloud/06.features/08.manual-device/manual-devices.md @@ -1,286 +1,286 @@ ---- -title: Manual Devices -description: Connect to the Arduino Cloud any kind of device that uses Python, MicroPython or JavaScript (Node.js) -author: Karl Söderby -tags: [Arduino Cloud, Device API, JavaScript, Node.js, Python, MicroPython] ---- - -Authentication & data synchronisation is automatically handled when you choose the automatic configuration option in the [Arduino Cloud](https://app.arduino.cc/). - -You can during the setup of your device instead choose the manual configuration option. This allows you to connect to the cloud using the **Device API** (MicroPython, Python or Node.js). - -This opens up possibilities for more kinds of devices, mainly Linux based, to connect to the Arduino Cloud. - -***Manual configuration is recommended for more advanced users, mainly those that are looking to integrate existing projects with the Arduino Cloud.*** - -## Goals - -In this article you will learn how to configure a manual device, and how to connect to the Arduino Cloud with: -- MicroPython -- Python -- JavaScript (Node.js) - -## Hardware & Software Needed - -Depending on what framework you choose to connect with, you will need various requirements. -- To connect using MicroPython you need to have a [GIGA R1 WiFi](https://store.arduino.cc/products/giga-r1-wifi), [Portenta H7](https://store.arduino.cc/products/portenta-h7), [Nano RP2040 Connect](https://store.arduino.cc/products/arduino-nano-rp2040-connect) with MicroPython => 1.2 installed. -- To connect using Python you need to have a [version of Python](https://www.python.org/) installed on your machine (check `python --version`). This has been tested with Python version **3.11**. -- To connect using JavaScript, you will need to install [Node.js](https://nodejs.org/en) is required to be installed to connect via JS. - -Each method of interaction with the Device API requires various levels of complexity. - -## Device API - -The **Device API** allows you to interact with the Arduino Cloud MQTT broker, by sending/receiving updates from your Arduino Cloud variables. - -This API is ideal for you who'd like to integrate existing Python or JavaScript projects with Arduino. - -This API is currently split between two repositories: -- [arduino-iot-js](https://github.com/arduino/arduino-iot-js) - for Node.js / JavaScript -- [arduino-iot-cloud-py](https://github.com/arduino/arduino-iot-cloud-py) for Python / MicroPython - -Note that the Device API is designed to interact with the MQTT broker. To manage devices, Things etc., please refer to the [Application API](https://www.arduino.cc/reference/en/iot/api) which can be interacted with using HTTP requests. - -## Configure Manual Devices - -To configure a manual device, go to [devices in the Arduino Cloud](https://app.arduino.cc/devices), and click the **"Add"** button. This will open a new window, where you will be asked to either configure automatically, or manually. Choose the **"Manual"** option. - -![Add a new device.](assets/configure-manual-device.png) - -Follow the steps (name your device), and at the end of the wizard you will receive your credentials, which you can also download as a PDF. - -![Device ID & Secret Key](assets/api-key.png) - -***Make sure to save the credentials, as the Secret Key will no longer be obtainable after completing the installation.*** - -After you have created your device, you need to link it to a Thing before using it. This is done in the Thing interface, under **"Associated Devices"**. - -## MicroPython - -The pre-requisities for connecting the the Arduino Cloud via MicroPython are: -- A [GIGA R1 WiFi](https://store.arduino.cc/products/giga-r1-wifi) / [Portenta H7](https://store.arduino.cc/products/portenta-h7) board with MicroPython installed, -- [Arduino Lab for MicroPython](https://labs.arduino.cc/en/labs/micropython) code editor, -- [arduino-iot-cloud-py](https://github.com/arduino/arduino-iot-cloud-py) installed, - - -To install MicroPython, you can check out the [Installation Guide](/micropython/basics/board-installation#giga-r1-wifi). The installation process is the same for both boards as they are based on the same MCU (STM32H7). - -To connect with MicroPython, you will need to have a manual device created in the Arduino Cloud. When you create it, you will receive a **Device ID** and a **Secret Key**. - -### MicroPython Example - -Below is a script that connects to the cloud, and allows you to control the onboard LED from a dashboard in the cloud. You will need to have exactly matching variables created inside your Thing in the cloud for this to work. For example: -- `client.register("led", value=None)` requires a variable named `led`. - -```python -from machine import Pin -import time -import network -import logging -from arduino_iot_cloud import ArduinoCloudClient - -WIFI_SSID = "WIFI_NETWORK" -WIFI_PASSWORD = "WIFI_PASSWORD" -DEVICE_ID = "YOUR_DEVICE_ID" -SECRET_KEY = "YOUR_SECRET_KEY" - -led = Pin("LEDB", Pin.OUT) # Configure the desired LED pin as an output. - -def on_switch_changed(client, value): - # Toggles the hardware LED on or off. - led.value(not value) - - # Sets the value of the cloud variable "led" to the current state of the LED - # and thus mirrors the hardware state in the cloud. - client["led"] = value - -def wifi_connect(): - if not WIFI_SSID or not WIFI_PASSWORD: - raise (Exception("Network is not configured. Set SSID and passwords in secrets.py")) - wlan = network.WLAN(network.STA_IF) - wlan.active(True) - wlan.connect(WIFI_SSID, WIFI_PASSWORD) - while not wlan.isconnected(): - logging.info("Trying to connect. Note this may take a while...") - time.sleep_ms(500) - logging.info(f"WiFi Connected {wlan.ifconfig()}") - -if __name__ == "__main__": - # Configure the logger. - # All message equal or higher to the logger level are printed. - # To see more debugging messages, set level=logging.DEBUG. - logging.basicConfig( - datefmt="%H:%M:%S", - format="%(asctime)s.%(msecs)03d %(message)s", - level=logging.INFO, - ) - - # NOTE: Add networking code here or in boot.py - wifi_connect() - - # Create a client object to connect to the Arduino Cloud. - # For MicroPython, the key and cert files must be stored in DER format on the filesystem. - # Alternatively, a username and password can be used to authenticate: - client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY) - - # Register cloud objects. - # Note: The following objects must be created first in the dashboard and linked to the device. - # This cloud object is initialized with its last known value from the cloud. When this object is updated - # from the dashboard, the on_switch_changed function is called with the client object and the new value. - client.register("ledSwitch", value=None, on_write=on_switch_changed, interval=0.250) - - # This cloud object is updated manually in the switch's on_write_change callback to update the LED state in the cloud. - client.register("led", value=None) - - # Start the Arduino Cloud client. - client.start() -``` - -For a more details, you can visit a more complete guide at [Connecting to Arduino Cloud using MicroPython](/arduino-cloud/getting-started/iot-cloud-micropython). - -## Python - -The pre-requisities for connecting with Python is: -- [Python](https://www.python.org/) installed on your machine (this is tested and confirmed to work with v3.11), -- [arduino-iot-cloud-py](https://github.com/arduino/arduino-iot-cloud-py) installed, -- a Thing + [manual device](#configure-manual-devices) created in the Arduino Cloud. - -Connection to the cloud via Python uses the same API as the MicroPython example listed in this article. To install the [arduino-iot-cloud-py](https://github.com/arduino/arduino-iot-cloud-py) module, we can use `pip`. - -``` -pip install arduino-iot-cloud -``` - -You will also need to install [SWIG](https://pypi.org/project/swig/), which is also done via `pip`: - -``` -pip install swig -``` - -You will also need to have configured a manual device in the cloud. The **Device ID** and **Secret Key** are required in your script to authenticate. To connect, we use the following command: - -```python -client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY) -``` - -To use the script further below, you will need to create a Thing with the following variables: -- `ledSwitch` - boolean -- `temperature` - float - -The variables are set up to test bi-directional communication between the cloud and the manual device. The `temperature` variable will send just a dummy value to the cloud, and the `ledSwitch` will send data from the cloud to the manual device. - -In the script, we need register the variables to use them, and set some parameters. - -```python -# register and send "temperature" data -client.register("temperature") -client["temperature"] = 20 - -# register and set callback (on_switch_changed) -client.register("ledSwitch", value=None, on_write=on_switch_changed) -``` - -### Python Example - -Below is a script that you can use to test out the API. Make sure to replace the `DEVICE_ID` and `SECRET_KEY` entries with your own credentials. - -```python -import time -import logging - -import sys -sys.path.append("lib") - -from arduino_iot_cloud import ArduinoCloudClient - -DEVICE_ID = b"YOUR_DEVICE_ID" -SECRET_KEY = b"YOUR_SECRET_KEY" - -def logging_func(): - logging.basicConfig( - datefmt="%H:%M:%S", - format="%(asctime)s.%(msecs)03d %(message)s", - level=logging.INFO, - ) - -# This function is executed each time the "ledSwitch" variable changes -def on_switch_changed(client, value): - print("Switch Pressed! Status is: ", value) - -if __name__ == "__main__": - - logging_func() - client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY) - - client.register("temperature") - client["temperature"] = 20 - client.register("ledSwitch", value=None, on_write=on_switch_changed) - - client.start() -``` - -Once you run the script, you will start the client and you will be able to interact with it from a dashboard. The script is setup so that anytime the `ledSwitch` changes, we will print the current state of the variable (true/false) in the REPL. - -## JavaScript/Node.js - -The pre-requisities for connecting with Node.js is: -- [Node.js](https://nodejs.org/en) installed on your machine (this is tested and confirmed to work with v20.2.0), -- [arduino-iot-js](https://github.com/arduino/arduino-iot-js) installed, -- a Thing created in the Arduino Cloud, -- a manual device created in the Arduino Cloud, associated to your Thing. - -Connection to the cloud via Node.js/Javascript requires you to first install the [arduino-iot-js](https://github.com/arduino/arduino-iot-js) package. You will also need to configure a manual device in the cloud, which will generate the **Device ID** and **Secret Key** needed to connect. - -```sh -npm install arduino-iot-js -``` - -After installation, you can use the example below to connect and send variable updates to the cloud. - -### JavaScript Example - -This example connects to the cloud (MQTT broker), and sends a variable update with `sendProperty()`, and then listens for updates using the `onPropertyValue()` method. - -***Please note: `cloudVar` needs to contain the variable name you create in the Arduino Cloud. In this case, we are calling it `test_variable`*** - -```js -const { ArduinoIoTCloud } = require('arduino-iot-js'); - -(async () => { - const client = await ArduinoIoTCloud.connect({ - deviceId: 'YOUR_DEVICE_ID', - secretKey: 'YOUR_SECRET_KEY', - onDisconnect: (message) => console.error(message), - }); - - const value = 20; - let cloudVar = "test_variable" - - client.sendProperty(cloudVar, value); - console.log(cloudVar, ":", value); - - client.onPropertyValue(cloudVar, (value) => console.log(cloudVar, ":", value)); -})(); -``` - -On successful connection, we should receive the following: - -```sh -found association to thing: -``` - -And upon receiving an update (if you change the value in the dashboard), you should see: - -```sh -test_variable: -``` - -## Summary - -In this article, you have learned about the Arduino Cloud's **Device API**, and how to connect to it using MicroPython, Python & JavaScript (Node.js). - -This API makes it easier to integrate existing software projects written in Python & JavaScript. - - - - +--- +title: Manual Devices +description: Connect to the Arduino Cloud any kind of device that uses Python, MicroPython or JavaScript (Node.js) +author: Karl Söderby +tags: [Arduino Cloud, Device API, JavaScript, Node.js, Python, MicroPython] +--- + +Authentication & data synchronisation is automatically handled when you choose the automatic configuration option in the [Arduino Cloud](https://app.arduino.cc/). + +You can during the setup of your device instead choose the manual configuration option. This allows you to connect to the Cloud using the **Device API** (MicroPython, Python or Node.js). + +This opens up possibilities for more kinds of devices, mainly Linux based, to connect to the Arduino Cloud. + +***Manual configuration is recommended for more advanced users, mainly those that are looking to integrate existing projects with the Arduino Cloud.*** + +## Goals + +In this article you will learn how to configure a manual device, and how to connect to the Arduino Cloud with: +- MicroPython +- Python +- JavaScript (Node.js) + +## Hardware & Software Needed + +Depending on what framework you choose to connect with, you will need various requirements. +- To connect using MicroPython you need to have a [GIGA R1 WiFi](https://store.arduino.cc/products/giga-r1-wifi), [Portenta H7](https://store.arduino.cc/products/portenta-h7), [Nano RP2040 Connect](https://store.arduino.cc/products/arduino-nano-rp2040-connect) with MicroPython => 1.2 installed. +- To connect using Python you need to have a [version of Python](https://www.python.org/) installed on your machine (check `python --version`). This has been tested with Python version **3.11**. +- To connect using JavaScript, you will need to install [Node.js](https://nodejs.org/en) is required to be installed to connect via JS. + +Each method of interaction with the Device API requires various levels of complexity. + +## Device API + +The **Device API** allows you to interact with the Arduino Cloud MQTT broker, by sending/receiving updates from your Arduino Cloud variables. + +This API is ideal for you who'd like to integrate existing Python or JavaScript projects with Arduino. + +This API is currently split between two repositories: +- [arduino-iot-js](https://github.com/arduino/arduino-iot-js) - for Node.js / JavaScript +- [arduino-iot-cloud-py](https://github.com/arduino/arduino-iot-cloud-py) for Python / MicroPython + +Note that the Device API is designed to interact with the MQTT broker. To manage devices, Things etc., please refer to the [Application API](https://www.arduino.cc/reference/en/iot/api) which can be interacted with using HTTP requests. + +## Configure Manual Devices + +To configure a manual device, go to [devices in the Arduino Cloud](https://app.arduino.cc/devices), and click the **"Add"** button. This will open a new window, where you will be asked to either configure automatically, or manually. Choose the **"Manual"** option. + +![Add a new device.](assets/configure-manual-device.png) + +Follow the steps (name your device), and at the end of the wizard you will receive your credentials, which you can also download as a PDF. + +![Device ID & Secret Key](assets/api-key.png) + +***Make sure to save the credentials, as the Secret Key will no longer be obtainable after completing the installation.*** + +After you have created your device, you need to link it to a Thing before using it. This is done in the Thing interface, under **"Associated Devices"**. + +## MicroPython + +The pre-requisities for connecting the the Arduino Cloud via MicroPython are: +- A [GIGA R1 WiFi](https://store.arduino.cc/products/giga-r1-wifi) / [Portenta H7](https://store.arduino.cc/products/portenta-h7) board with MicroPython installed, +- [Arduino Lab for MicroPython](https://labs.arduino.cc/en/labs/micropython) code editor, +- [arduino-iot-cloud-py](https://github.com/arduino/arduino-iot-cloud-py) installed, + + +To install MicroPython, you can check out the [Installation Guide](/micropython/basics/board-installation#giga-r1-wifi). The installation process is the same for both boards as they are based on the same MCU (STM32H7). + +To connect with MicroPython, you will need to have a manual device created in the Arduino Cloud. When you create it, you will receive a **Device ID** and a **Secret Key**. + +### MicroPython Example + +Below is a script that connects to the Cloud, and allows you to control the onboard LED from a dashboard in the Cloud. You will need to have exactly matching variables created inside your Thing in the Cloud for this to work. For example: +- `client.register("led", value=None)` requires a variable named `led`. + +```python +from machine import Pin +import time +import network +import logging +from arduino_iot_cloud import ArduinoCloudClient + +WIFI_SSID = "WIFI_NETWORK" +WIFI_PASSWORD = "WIFI_PASSWORD" +DEVICE_ID = "YOUR_DEVICE_ID" +SECRET_KEY = "YOUR_SECRET_KEY" + +led = Pin("LEDB", Pin.OUT) # Configure the desired LED pin as an output. + +def on_switch_changed(client, value): + # Toggles the hardware LED on or off. + led.value(not value) + + # Sets the value of the Cloud variable "led" to the current state of the LED + # and thus mirrors the hardware state in the Cloud. + client["led"] = value + +def wifi_connect(): + if not WIFI_SSID or not WIFI_PASSWORD: + raise (Exception("Network is not configured. Set SSID and passwords in secrets.py")) + wlan = network.WLAN(network.STA_IF) + wlan.active(True) + wlan.connect(WIFI_SSID, WIFI_PASSWORD) + while not wlan.isconnected(): + logging.info("Trying to connect. Note this may take a while...") + time.sleep_ms(500) + logging.info(f"WiFi Connected {wlan.ifconfig()}") + +if __name__ == "__main__": + # Configure the logger. + # All message equal or higher to the logger level are printed. + # To see more debugging messages, set level=logging.DEBUG. + logging.basicConfig( + datefmt="%H:%M:%S", + format="%(asctime)s.%(msecs)03d %(message)s", + level=logging.INFO, + ) + + # NOTE: Add networking code here or in boot.py + wifi_connect() + + # Create a client object to connect to the Arduino Cloud. + # For MicroPython, the key and cert files must be stored in DER format on the filesystem. + # Alternatively, a username and password can be used to authenticate: + client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY) + + # Register Cloud objects. + # Note: The following objects must be created first in the dashboard and linked to the device. + # This Cloud object is initialized with its last known value from the Cloud. When this object is updated + # from the dashboard, the on_switch_changed function is called with the client object and the new value. + client.register("ledSwitch", value=None, on_write=on_switch_changed, interval=0.250) + + # This Cloud object is updated manually in the switch's on_write_change callback to update the LED state in the Cloud. + client.register("led", value=None) + + # Start the Arduino Cloud client. + client.start() +``` + +For a more details, you can visit a more complete guide at [Connecting to Arduino Cloud using MicroPython](/arduino-cloud/getting-started/iot-cloud-micropython). + +## Python + +The pre-requisities for connecting with Python is: +- [Python](https://www.python.org/) installed on your machine (this is tested and confirmed to work with v3.11), +- [arduino-iot-cloud-py](https://github.com/arduino/arduino-iot-cloud-py) installed, +- a Thing + [manual device](#configure-manual-devices) created in the Arduino Cloud. + +Connection to the Cloud via Python uses the same API as the MicroPython example listed in this article. To install the [arduino-iot-cloud-py](https://github.com/arduino/arduino-iot-cloud-py) module, we can use `pip`. + +``` +pip install arduino-iot-cloud +``` + +You will also need to install [SWIG](https://pypi.org/project/swig/), which is also done via `pip`: + +``` +pip install swig +``` + +You will also need to have configured a manual device in the Cloud. The **Device ID** and **Secret Key** are required in your script to authenticate. To connect, we use the following command: + +```python +client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY) +``` + +To use the script further below, you will need to create a Thing with the following variables: +- `ledSwitch` - boolean +- `temperature` - float + +The variables are set up to test bi-directional communication between the Cloud and the manual device. The `temperature` variable will send just a dummy value to the Cloud, and the `ledSwitch` will send data from the Cloud to the manual device. + +In the script, we need register the variables to use them, and set some parameters. + +```python +# register and send "temperature" data +client.register("temperature") +client["temperature"] = 20 + +# register and set callback (on_switch_changed) +client.register("ledSwitch", value=None, on_write=on_switch_changed) +``` + +### Python Example + +Below is a script that you can use to test out the API. Make sure to replace the `DEVICE_ID` and `SECRET_KEY` entries with your own credentials. + +```python +import time +import logging + +import sys +sys.path.append("lib") + +from arduino_iot_cloud import ArduinoCloudClient + +DEVICE_ID = b"YOUR_DEVICE_ID" +SECRET_KEY = b"YOUR_SECRET_KEY" + +def logging_func(): + logging.basicConfig( + datefmt="%H:%M:%S", + format="%(asctime)s.%(msecs)03d %(message)s", + level=logging.INFO, + ) + +# This function is executed each time the "ledSwitch" variable changes +def on_switch_changed(client, value): + print("Switch Pressed! Status is: ", value) + +if __name__ == "__main__": + + logging_func() + client = ArduinoCloudClient(device_id=DEVICE_ID, username=DEVICE_ID, password=SECRET_KEY) + + client.register("temperature") + client["temperature"] = 20 + client.register("ledSwitch", value=None, on_write=on_switch_changed) + + client.start() +``` + +Once you run the script, you will start the client and you will be able to interact with it from a dashboard. The script is setup so that anytime the `ledSwitch` changes, we will print the current state of the variable (true/false) in the REPL. + +## JavaScript/Node.js + +The pre-requisities for connecting with Node.js is: +- [Node.js](https://nodejs.org/en) installed on your machine (this is tested and confirmed to work with v20.2.0), +- [arduino-iot-js](https://github.com/arduino/arduino-iot-js) installed, +- a Thing created in the Arduino Cloud, +- a manual device created in the Arduino Cloud, associated to your Thing. + +Connection to the Cloud via Node.js/Javascript requires you to first install the [arduino-iot-js](https://github.com/arduino/arduino-iot-js) package. You will also need to configure a manual device in the Cloud, which will generate the **Device ID** and **Secret Key** needed to connect. + +```sh +npm install arduino-iot-js +``` + +After installation, you can use the example below to connect and send variable updates to the Cloud. + +### JavaScript Example + +This example connects to the Cloud (MQTT broker), and sends a variable update with `sendProperty()`, and then listens for updates using the `onPropertyValue()` method. + +***Please note: `cloudVar` needs to contain the variable name you create in the Arduino Cloud. In this case, we are calling it `test_variable`*** + +```js +const { ArduinoIoTCloud } = require('arduino-iot-js'); + +(async () => { + const client = await ArduinoIoTCloud.connect({ + deviceId: 'YOUR_DEVICE_ID', + secretKey: 'YOUR_SECRET_KEY', + onDisconnect: (message) => console.error(message), + }); + + const value = 20; + let cloudVar = "test_variable" + + client.sendProperty(cloudVar, value); + console.log(cloudVar, ":", value); + + client.onPropertyValue(cloudVar, (value) => console.log(cloudVar, ":", value)); +})(); +``` + +On successful connection, we should receive the following: + +```sh +found association to thing: +``` + +And upon receiving an update (if you change the value in the dashboard), you should see: + +```sh +test_variable: +``` + +## Summary + +In this article, you have learned about the Arduino Cloud's **Device API**, and how to connect to it using MicroPython, Python & JavaScript (Node.js). + +This API makes it easier to integrate existing software projects written in Python & JavaScript. + + + + diff --git a/content/arduino-cloud/06.features/09.advanced-chart/advanced-chart.md b/content/arduino-cloud/06.features/09.advanced-chart/advanced-chart.md index 040c183b57..9eca9f9dca 100644 --- a/content/arduino-cloud/06.features/09.advanced-chart/advanced-chart.md +++ b/content/arduino-cloud/06.features/09.advanced-chart/advanced-chart.md @@ -1,151 +1,151 @@ ---- -title: Multiple Variable Chart Widget -description: Learn how to use the advanced chart widget, which allows you to track several variables in real time or during a specific time period. -author: Karl Söderby -tags: [Arduino Cloud, Charts, Data Plotting] ---- - -The **advanced chart widget** is used to display data from several Arduino Cloud variables in a single chart. You can track the data in both real time, select from a specific time period while selecting the variables you want to display. - -![The advanced chart widget.](assets/advanced-chart.gif) - -This widget can be added onto existing projects (if you are already tracking data), and is particularly interesting to use in projects such as: -- Weather stations, -- Environmental data tracking, -- Energy consumption, -- Various science projects where data comparison is needed. - -This widget can use variables from **different Things**, so you can monitor data from various devices and plot it all in one place. - -For example, you could set up a series of sensors around a city, and measure the CO2 emissions from your phone or laptop in a single chart! - -## Hardware & Software Needed - -- [Arduino Cloud](https://app.arduino.cc/). -- Cloud compatible boards, [see full list](https://docs.arduino.cc/arduino-cloud/guides/overview#compatible-hardware). - -***In this tutorial, we use the [MKR WiFi 1010](/hardware/mkr-wifi-1010) and [MKR ENV Shield](/hardware/mkr-env-shield) for recording environmental values. This is not a requirement, you can use any board for this tutorial.*** - -## Setup & Configuration - -To use the advanced widget, you will need to set up a Thing and some variables that you want to track. We choose to set up and track: -- `temperature` -- `humidity` -- `pressure` -- `light` - -***If you are unfamiliar with how to set up a Thing and variables, head on over to the [Getting Started with the Arduino Cloud](/arduino-cloud/guides/overview) article.*** - -**1.** Head on over to the **"Dashboards"** in the Arduino Cloud, and create a new dashboard (or use an existing dashboard). - -**2.** Add a new **"Advanced Chart Widget"**, selecting it from the list of available widgets. - -**3.** Link the variables you want to compare. In this case, we are using `temperature`, `humidity`, `pressure` and `light`. - -![Link variables.](assets/select-variables.png) - ->You can use up to a maximum of 5 variables. - -**4.** After selection, your variables will appear in the right panel, with a number of configuration options. You can for example choose how each data point will be represented (line, spline, spline area, line area and bar). - -![Advanced chart widget configuration.](assets/widget-config.png) - -**5.** Click on **"Done"** when finished selecting the variables. If your board is connected and is sending data to the cloud, you will see the widget's data update frequently. - -## Example Code - -The sketch of your project does not require much complexity. In your automatically generated code, simply add the sensor reading code inside of the loop. We are using the [Arduino_MKRENV](https://www.arduino.cc/reference/en/libraries/arduino_mkrenv/) library, and we only needed to add these following lines to the loop to read all sensors: - -```arduino -temperature = ENV.readTemperature(); -humidity = ENV.readHumidity(); -pressure = ENV.readPressure(); -light = ENV.readIlluminance(); -``` - -The full sketch used is found below: - -```arduino -#include - -#include "thingProperties.h" - -void setup() { - // Initialize serial and wait for port to open: - Serial.begin(9600); - - if (!ENV.begin()) { - while (1); - } - - delay(1500); - - initProperties(); - - ArduinoCloud.begin(ArduinoIoTPreferredConnection); - - setDebugMessageLevel(2); - ArduinoCloud.printDebugInfo(); -} - -void loop() { - ArduinoCloud.update(); - - temperature = ENV.readTemperature(); - humidity = ENV.readHumidity(); - pressure = ENV.readPressure(); - light = ENV.readIlluminance(); - -} -``` - -## Usage - -With the widget set up, let's explore some of its features. - -### Toggle Variables - -You can enable or disable to variables you want to display by simply clicking the name of the variable. - -![Toggle variables.](assets/advanced-chart-toggle.gif) - -### Value Tracking - -Hover over a line to see what the value of a variable was in a specific point in time. In this case, we choose to check only the temperature and the humidity. - -![View values.](assets/advanced-chart.gif) - -### Specific Time Period - -To see a specific time period, click on the calendar icon, where you can select the starting & end time & date. - -![Select time & date.](assets/select-time-date.png) - -As an example, the widget below shows the illuminance (LUX) recorded via the **MKR ENV Shield**, the `light` variable. - -Here, we can see that sunset occurred around 18.00 (6PM), and sunrise sometime around 07.00 (7AM). - -![Light tracking.](assets/light-tracking.png) - -## Limitations - -The following variables are not supported in the advanced chart widget. - -- Character String -- Schedule -- Location -- Color -- Custom Variable -- Colored Light -- Dimmed Light -- Contact Sensor -- Motion Sensor -- Television -- Boolean -- Light -- Smart Plug -- Switch - -## Summary - +--- +title: Multiple Variable Chart Widget +description: Learn how to use the advanced chart widget, which allows you to track several variables in real time or during a specific time period. +author: Karl Söderby +tags: [Arduino Cloud, Charts, Data Plotting] +--- + +The **advanced chart widget** is used to display data from several Arduino Cloud variables in a single chart. You can track the data in both real time, select from a specific time period while selecting the variables you want to display. + +![The advanced chart widget.](assets/advanced-chart.gif) + +This widget can be added onto existing projects (if you are already tracking data), and is particularly interesting to use in projects such as: +- Weather stations, +- Environmental data tracking, +- Energy consumption, +- Various science projects where data comparison is needed. + +This widget can use variables from **different Things**, so you can monitor data from various devices and plot it all in one place. + +For example, you could set up a series of sensors around a city, and measure the CO2 emissions from your phone or laptop in a single chart! + +## Hardware & Software Needed + +- [Arduino Cloud](https://app.arduino.cc/). +- Cloud compatible boards, [see full list](https://docs.arduino.cc/arduino-cloud/guides/overview#compatible-hardware). + +***In this tutorial, we use the [MKR WiFi 1010](/hardware/mkr-wifi-1010) and [MKR ENV Shield](/hardware/mkr-env-shield) for recording environmental values. This is not a requirement, you can use any board for this tutorial.*** + +## Setup & Configuration + +To use the advanced widget, you will need to set up a Thing and some variables that you want to track. We choose to set up and track: +- `temperature` +- `humidity` +- `pressure` +- `light` + +***If you are unfamiliar with how to set up a Thing and variables, head on over to the [Getting Started with the Arduino Cloud](/arduino-cloud/guides/overview) article.*** + +**1.** Head on over to the **"Dashboards"** in the Arduino Cloud, and create a new dashboard (or use an existing dashboard). + +**2.** Add a new **"Advanced Chart Widget"**, selecting it from the list of available widgets. + +**3.** Link the variables you want to compare. In this case, we are using `temperature`, `humidity`, `pressure` and `light`. + +![Link variables.](assets/select-variables.png) + +>You can use up to a maximum of 5 variables. + +**4.** After selection, your variables will appear in the right panel, with a number of configuration options. You can for example choose how each data point will be represented (line, spline, spline area, line area and bar). + +![Advanced chart widget configuration.](assets/widget-config.png) + +**5.** Click on **"Done"** when finished selecting the variables. If your board is connected and is sending data to the Cloud, you will see the widget's data update frequently. + +## Example Code + +The sketch of your project does not require much complexity. In your automatically generated code, simply add the sensor reading code inside of the loop. We are using the [Arduino_MKRENV](https://www.arduino.cc/reference/en/libraries/arduino_mkrenv/) library, and we only needed to add these following lines to the loop to read all sensors: + +```arduino +temperature = ENV.readTemperature(); +humidity = ENV.readHumidity(); +pressure = ENV.readPressure(); +light = ENV.readIlluminance(); +``` + +The full sketch used is found below: + +```arduino +#include + +#include "thingProperties.h" + +void setup() { + // Initialize serial and wait for port to open: + Serial.begin(9600); + + if (!ENV.begin()) { + while (1); + } + + delay(1500); + + initProperties(); + + ArduinoCloud.begin(ArduinoIoTPreferredConnection); + + setDebugMessageLevel(2); + ArduinoCloud.printDebugInfo(); +} + +void loop() { + ArduinoCloud.update(); + + temperature = ENV.readTemperature(); + humidity = ENV.readHumidity(); + pressure = ENV.readPressure(); + light = ENV.readIlluminance(); + +} +``` + +## Usage + +With the widget set up, let's explore some of its features. + +### Toggle Variables + +You can enable or disable to variables you want to display by simply clicking the name of the variable. + +![Toggle variables.](assets/advanced-chart-toggle.gif) + +### Value Tracking + +Hover over a line to see what the value of a variable was in a specific point in time. In this case, we choose to check only the temperature and the humidity. + +![View values.](assets/advanced-chart.gif) + +### Specific Time Period + +To see a specific time period, click on the calendar icon, where you can select the starting & end time & date. + +![Select time & date.](assets/select-time-date.png) + +As an example, the widget below shows the illuminance (LUX) recorded via the **MKR ENV Shield**, the `light` variable. + +Here, we can see that sunset occurred around 18.00 (6PM), and sunrise sometime around 07.00 (7AM). + +![Light tracking.](assets/light-tracking.png) + +## Limitations + +The following variables are not supported in the advanced chart widget. + +- Character String +- Schedule +- Location +- Color +- Custom Variable +- Colored Light +- Dimmed Light +- Contact Sensor +- Motion Sensor +- Television +- Boolean +- Light +- Smart Plug +- Switch + +## Summary + The advanced chart widget can be used for **any** project that includes data monitoring. It is perfect for scientific projects when monitoring & comparing data over time is needed. \ No newline at end of file diff --git a/content/arduino-cloud/06.features/11.webhooks/iot-cloud-webhooks.md b/content/arduino-cloud/06.features/11.webhooks/iot-cloud-webhooks.md index fd03067a47..d86ce7f1d3 100644 --- a/content/arduino-cloud/06.features/11.webhooks/iot-cloud-webhooks.md +++ b/content/arduino-cloud/06.features/11.webhooks/iot-cloud-webhooks.md @@ -1,152 +1,152 @@ ---- -title: 'Webhooks' -description: 'Learn how to setup webhooks with the Arduino Cloud to work with third party platforms such as IFTTT.' -tags: - - Webhooks - - Arduino Cloud - - IFTTT -author: 'Liam Aljundi' ---- - -## Introduction - -Webhooks allow you to send and receive automated messages to and from other services. For example, you can use webhooks to receive a notification when a property of your Thing changes. To do this, there are third party platforms that link the properties from your Arduino Cloud projects to the desired trigger action. - -## Goals - -- Learn how to set up webhooks in the Arduino Cloud. -- Provide an overview of available platforms where webhooks may be used. -- Demonstrate an example that uses a webhook to send data from the Arduino Cloud to Google Sheets, via the IFTTT platform. - -## Hardware & Software Requirements - -- The [Arduino Create Agent](https://github.com/arduino/arduino-create-agent) -- An [Arduino account](http://create.arduino.cc/iot). - -You will also need a cloud compatible board: - -***Read more about compatible board [here](/arduino-cloud/guides/overview#compatible-boards)*** - -## Webhook Setup - -A webhook can be set for any **Thing** on the Arduino Cloud, allowing us to send data from the Arduino Cloud to various third party platforms. For example, you can use webhooks to receive an email when any of you devices is disconnected, or send and save live sensor values collected from your device in a Google Spreadsheet. - -There are many available platforms that support the use of Webhooks, for this tutorial we will try the **IFTTT** platform. IFTTT allows you to integrate services with your DIY projects. With IFTTT you can create Applets that work with any device or app that can make or receive a web request. - -Let's try it out by creating an Applet that uses a webhook to receive String Values sent via the **Message Widget** on the Arduino Cloud, and save them into a Google Sheets. - -### IFTTT Configuration - -The first step is to create an Applet on the IFTTT platform using the following steps: - -![Creating an Applet](assets/creating-an-applet.gif) - -**1.** Go to [IFTTT website](https://maker.ifttt.com) and sign in. - -**2.** Click **Create** in the top right, then select **If This**. - -**3.** In the search field, type **"Webhooks"** and select that service. - -**4.** Select Receive a web request. - -**5.** In the Event Name field, type "message", and click the Create trigger button. - -**6.** Now, click on **Then That**, type **"Google Sheets"** and select that service. - -**7.** Choose the **"Add row to spreadsheet"** option. - -**8.** You can keep the default settings, scroll down and click on **"Create action"**. - -Both the trigger and action have now been configured. Click **Continue**. Optionally, change the applet title, and click **Finish** to create the applet. - -The final step is finding the webhook link that you will need to set to your Thing on the Arduino Cloud. You can find the link under **Profile picture in the top right > My Services > Webhooks > Documentation.** - -![Finding the Webhook link](assets/finding-webhook-link.png) - -### Setting a Webhook to a Thing - -Linking a webhook to a Thing is a quite simple process, follow the steps below to set a webhook to your Thing: - -**1.** [Sign in to your Arduino account](https://create.arduino.cc/iot), and open the [Arduino Cloud](https://create.arduino.cc/iot). - -**2.** Navigate to [**Things** -> **Create Thing**](https://app.arduino.cc/things). - -**3.** Create your Variables. In our case, we will create a **"message"** Variable and set its type to **"Character String"**. - -![Create Variable](./assets/webhooks-01.png) - -**4.** Add your **Device**, and configure your **Network** from the right side menu. - -**5.** Click on "**Set Webhook**", one the bottom left corner. - -![Set Webhook](./assets/webhooks-02.png) - -**6.** Enter the webhook link provided from the platform you are using. - -![Enter Webhook](./assets/webhooks-03.png) - -**7.** Finally, navigate to the **Sketch** tab, and upload the automatically generated code to your board. - -The Arduino Cloud will share **five sets of values** through the assigned webhook: - -- `"event_id": "EVENT_UUID"` -- `"webhook_id": "WEBHOOK_ID"` -- `"device_id": "DEVICE_UUID"` -- `"thing_id": "THING_UUID"` - -The fifth value contains an array of objects, each representing a Variable in your Thing, as the following: - -- `"values":` - - ```js - [ - { - "id": "VARIABLE_01_ID", - "name": "NAME_OF_VARIABLE_01", - "value": "VARIABLE_01_VALUE", - "persist": true/false, - "updated_at": "DATE", - "created_by": "USERID" - },1 - { - "id": "VARIABLE_02_ID", - "name": "NAME_OF_VARIABLE_02", - "value": "VARIABLE_02_VALUE", - "persist": true/false, - "updated_at": "DATE", - "created_by": "USERID" - } - ] - ``` - -### Testing the Webhook - -To test the webhook, we need to create a *Messenger widget*. We can do that by: - -**1.** Navigating to [*Dashboards*](https://app.arduino.cc/dashboards) -> *Edit* -> *Add* -> stay on the *Widgets tab* -> select "Messenger". - -![Add Messenger Widget](./assets/webhooks-04.png) - -**2.** Press on *Link Variable*, select the Thing we created, then the **"message"** Variable. - -![Link Widge](./assets/webhooks-05.png) - -In the "messenger widget", we are modifying the value of the "message" Variable. Whenever we send a message, the "message" Variable is updated and using the webhook we set, the updates are sent to the spreadsheet file created by IFTTT. - -To try it out, all you need to do is to navigate to your **Dashboards** on the Arduino Cloud and send messages using the **Messenger Widget**. The messages, along with the exact date and time will be found in the Google Sheets file created by IFTTT, on our Google account. To access this file, you need to navigate to your [Google Sheets](https://docs.google.com/spreadsheets) -> find and open the file names **"IFTTT_Maker_Webhooks_Events"**. - -![Setting a webhook](assets/ezgif.com-crop.gif) - -## Available Platforms - -In addition to IFTTT, here are examples of platforms that you can use webhooks with: - -### Zapier - -[Zapier](https://zapier.com/) works similarly to IFTTT. In addition to connecting your APIs quickly using **Zaps**, you can use Zapier's visual builder, which allows you to build an integration and preview data in real time. - -### Google Services - -- [**Google Cloud APIs**](https://cloud.google.com/apis/docs/overview): with Google APIs you can develop application programming interfaces (APIs) to communicate with Google services such as Search, Gmail, Translate or Google Maps apps or other applications like Arduino Cloud. - -- [**Google Script**](https://developers.google.com/apps-script): allows you to interact with all your Google G-Suite files such as Google Sheets, Docs and more. +--- +title: 'Webhooks' +description: 'Learn how to setup webhooks with the Arduino Cloud to work with third party platforms such as IFTTT.' +tags: + - Webhooks + - Arduino Cloud + - IFTTT +author: 'Liam Aljundi' +--- + +## Introduction + +Webhooks allow you to send and receive automated messages to and from other services. For example, you can use webhooks to receive a notification when a property of your Thing changes. To do this, there are third party platforms that link the properties from your Arduino Cloud projects to the desired trigger action. + +## Goals + +- Learn how to set up webhooks in the Arduino Cloud. +- Provide an overview of available platforms where webhooks may be used. +- Demonstrate an example that uses a webhook to send data from the Arduino Cloud to Google Sheets, via the IFTTT platform. + +## Hardware & Software Requirements + +- The [Arduino Create Agent](https://github.com/arduino/arduino-create-agent) +- An [Arduino account](http://create.arduino.cc/iot). + +You will also need a Cloud compatible board: + +***Read more about compatible board [here](/arduino-cloud/guides/overview#compatible-boards)*** + +## Webhook Setup + +A webhook can be set for any **Thing** on the Arduino Cloud, allowing us to send data from the Arduino Cloud to various third party platforms. For example, you can use webhooks to receive an email when any of you devices is disconnected, or send and save live sensor values collected from your device in a Google Spreadsheet. + +There are many available platforms that support the use of Webhooks, for this tutorial we will try the **IFTTT** platform. IFTTT allows you to integrate services with your DIY projects. With IFTTT you can create Applets that work with any device or app that can make or receive a web request. + +Let's try it out by creating an Applet that uses a webhook to receive String Values sent via the **Message Widget** on the Arduino Cloud, and save them into a Google Sheets. + +### IFTTT Configuration + +The first step is to create an Applet on the IFTTT platform using the following steps: + +![Creating an Applet](assets/creating-an-applet.gif) + +**1.** Go to [IFTTT website](https://maker.ifttt.com) and sign in. + +**2.** Click **Create** in the top right, then select **If This**. + +**3.** In the search field, type **"Webhooks"** and select that service. + +**4.** Select Receive a web request. + +**5.** In the Event Name field, type "message", and click the Create trigger button. + +**6.** Now, click on **Then That**, type **"Google Sheets"** and select that service. + +**7.** Choose the **"Add row to spreadsheet"** option. + +**8.** You can keep the default settings, scroll down and click on **"Create action"**. + +Both the trigger and action have now been configured. Click **Continue**. Optionally, change the applet title, and click **Finish** to create the applet. + +The final step is finding the webhook link that you will need to set to your Thing on the Arduino Cloud. You can find the link under **Profile picture in the top right > My Services > Webhooks > Documentation.** + +![Finding the Webhook link](assets/finding-webhook-link.png) + +### Setting a Webhook to a Thing + +Linking a webhook to a Thing is a quite simple process, follow the steps below to set a webhook to your Thing: + +**1.** [Sign in to your Arduino account](https://create.arduino.cc/iot), and open the [Arduino Cloud](https://create.arduino.cc/iot). + +**2.** Navigate to [**Things** -> **Create Thing**](https://app.arduino.cc/things). + +**3.** Create your Variables. In our case, we will create a **"message"** Variable and set its type to **"Character String"**. + +![Create Variable](./assets/webhooks-01.png) + +**4.** Add your **Device**, and configure your **Network** from the right side menu. + +**5.** Click on "**Set Webhook**", one the bottom left corner. + +![Set Webhook](./assets/webhooks-02.png) + +**6.** Enter the webhook link provided from the platform you are using. + +![Enter Webhook](./assets/webhooks-03.png) + +**7.** Finally, navigate to the **Sketch** tab, and upload the automatically generated code to your board. + +The Arduino Cloud will share **five sets of values** through the assigned webhook: + +- `"event_id": "EVENT_UUID"` +- `"webhook_id": "WEBHOOK_ID"` +- `"device_id": "DEVICE_UUID"` +- `"thing_id": "THING_UUID"` + +The fifth value contains an array of objects, each representing a Variable in your Thing, as the following: + +- `"values":` + + ```js + [ + { + "id": "VARIABLE_01_ID", + "name": "NAME_OF_VARIABLE_01", + "value": "VARIABLE_01_VALUE", + "persist": true/false, + "updated_at": "DATE", + "created_by": "USERID" + },1 + { + "id": "VARIABLE_02_ID", + "name": "NAME_OF_VARIABLE_02", + "value": "VARIABLE_02_VALUE", + "persist": true/false, + "updated_at": "DATE", + "created_by": "USERID" + } + ] + ``` + +### Testing the Webhook + +To test the webhook, we need to create a *Messenger widget*. We can do that by: + +**1.** Navigating to [*Dashboards*](https://app.arduino.cc/dashboards) -> *Edit* -> *Add* -> stay on the *Widgets tab* -> select "Messenger". + +![Add Messenger Widget](./assets/webhooks-04.png) + +**2.** Press on *Link Variable*, select the Thing we created, then the **"message"** Variable. + +![Link Widge](./assets/webhooks-05.png) + +In the "messenger widget", we are modifying the value of the "message" Variable. Whenever we send a message, the "message" Variable is updated and using the webhook we set, the updates are sent to the spreadsheet file created by IFTTT. + +To try it out, all you need to do is to navigate to your **Dashboards** on the Arduino Cloud and send messages using the **Messenger Widget**. The messages, along with the exact date and time will be found in the Google Sheets file created by IFTTT, on our Google account. To access this file, you need to navigate to your [Google Sheets](https://docs.google.com/spreadsheets) -> find and open the file names **"IFTTT_Maker_Webhooks_Events"**. + +![Setting a webhook](assets/ezgif.com-crop.gif) + +## Available Platforms + +In addition to IFTTT, here are examples of platforms that you can use webhooks with: + +### Zapier + +[Zapier](https://zapier.com/) works similarly to IFTTT. In addition to connecting your APIs quickly using **Zaps**, you can use Zapier's visual builder, which allows you to build an integration and preview data in real time. + +### Google Services + +- [**Google Cloud APIs**](https://cloud.google.com/apis/docs/overview): with Google APIs you can develop application programming interfaces (APIs) to communicate with Google services such as Search, Gmail, Translate or Google Maps apps or other applications like Arduino Cloud. + +- [**Google Script**](https://developers.google.com/apps-script): allows you to interact with all your Google G-Suite files such as Google Sheets, Docs and more. diff --git a/content/arduino-cloud/07.api/01.api-overview/api-overview.md b/content/arduino-cloud/07.api/01.api-overview/api-overview.md index 97ca0f6bdc..f0a61a6af6 100644 --- a/content/arduino-cloud/07.api/01.api-overview/api-overview.md +++ b/content/arduino-cloud/07.api/01.api-overview/api-overview.md @@ -36,7 +36,7 @@ The **Device API** allows sending and receiving any kind of data (sensors' value - manage compression, data format, and transport protocols With this API, you can: -- Send sensors' values to the cloud +- 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 @@ -81,7 +81,7 @@ Full examples and documentation can be found at: ### MicroPython -The [Arduino Cloud Python Client](https://github.com/arduino/arduino-iot-cloud-py) 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. +The [Arduino Cloud Python Client](https://github.com/arduino/arduino-iot-cloud-py) 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: diff --git a/content/arduino-cloud/07.api/03.c-library/c-library.md b/content/arduino-cloud/07.api/03.c-library/c-library.md index 28aa376041..0ea88989dc 100644 --- a/content/arduino-cloud/07.api/03.c-library/c-library.md +++ b/content/arduino-cloud/07.api/03.c-library/c-library.md @@ -40,7 +40,7 @@ Most of its functions are already pre-configured in your sketch files, so for mo ## Arduino IDE (Offline) -This library can be used with the offline version of the Arduino IDE (download through the [Arduino Downloads Page](https://www.arduino.cc/en/software/)). You can program your devices offline and monitor them via the cloud, but your Thing configuration is not synchronized if you do so. +This library can be used with the offline version of the Arduino IDE (download through the [Arduino Downloads Page](https://www.arduino.cc/en/software/)). You can program your devices offline and monitor them via the Cloud, but your Thing configuration is not synchronized if you do so. To use it offline, you will manually need to install the following libraries in the Arduino IDE: - [ArduinoIoTCloud](https://github.com/arduino-libraries/ArduinoIoTCloud) @@ -59,7 +59,7 @@ The `ArduinoIoTCloudEvent` enumeration class has three possible events: - `SYNC` (1) - Data is successfully synced between Board and Arduino Cloud. - `DISCONNECT` (2) - Board has lost connection to Arduino Cloud. -The `CONNECT` and `DISCONNECT` events can occur even though no variable is created inside the Thing. However, `SYNC` requires a variable to be created, as this triggers whenever data is synchronized between the board and cloud. +The `CONNECT` and `DISCONNECT` events can occur even though no variable is created inside the Thing. However, `SYNC` requires a variable to be created, as this triggers whenever data is synchronized between the board and Cloud. These events can be subscribed to using the `addCallback()` function, which is documented in the next section. diff --git a/content/arduino-cloud/08.arduino-cloud-cli/07.getting-started/arduino-cloud-cli.md b/content/arduino-cloud/08.arduino-cloud-cli/07.getting-started/arduino-cloud-cli.md index d00ecce356..afb9e31b12 100644 --- a/content/arduino-cloud/08.arduino-cloud-cli/07.getting-started/arduino-cloud-cli.md +++ b/content/arduino-cloud/08.arduino-cloud-cli/07.getting-started/arduino-cloud-cli.md @@ -454,6 +454,6 @@ The Arduino Cloud CLI can also be well combined with the [Arduino CLI](https://a To recap, this tool can be used to: - Extract templates from your existing Things & dashboards previously created in the Arduino Cloud. - Perform the same actions as the Arduino Cloud but from a terminal (like creating/deleting devices, Things and linking them). -- List all available components from the cloud (like `thing list`). +- List all available components from the Cloud (like `thing list`). - Tag your devices & Things with the `--tags =` command. diff --git a/content/arduino-cloud/09.business/00.security-considerations/security-considerations.md b/content/arduino-cloud/09.business/00.security-considerations/security-considerations.md index a69c756c59..73b65c7f19 100644 --- a/content/arduino-cloud/09.business/00.security-considerations/security-considerations.md +++ b/content/arduino-cloud/09.business/00.security-considerations/security-considerations.md @@ -14,11 +14,11 @@ author: 'Arduino Security Team' In order to provide secure digital services to customers, we at Arduino are committed to regularly monitor and update our services, applications, and infrastructure. In general, the approach to Security is aligned with Cybersecurity standards such as ISO27001. To ensure the highest level of confidentiality, integrity and availability, Arduino operates under a shared security responsibility model. The shared security responsibility model identifies the distinct security responsibilities of the customer and Arduino. In this model: -* **Arduino** is responsible for the security of the cloud infrastructure services provided to customers and the confidentiality of sensitive data. We provide such security via a number of best practices that all employee in Arduino follow and that are described in the following sections of this document; for example, but not limited to the following: +* **Arduino** is responsible for the security of the Cloud infrastructure services provided to customers and the confidentiality of sensitive data. We provide such security via a number of best practices that all employee in Arduino follow and that are described in the following sections of this document; for example, but not limited to the following: * We limit as much as possible the level of access that Arduino employees have on customers data. * Security and privacy training are conducted regularly to ensure the highest possible level of awareness to Arduino employees. * Regular penetration and vulnerability security tests are performed to our infrastructure and services to assess that security practices in place are working as intended. -* **Customers** are responsible for the security of their account, personal access credentials, and for the information they decide to store in the cloud. Arduino recommends to pay particular attention to the following best practices: +* **Customers** are responsible for the security of their account, personal access credentials, and for the information they decide to store in the Cloud. Arduino recommends to pay particular attention to the following best practices: * **Strong authentication:** taking advantage of strong authentication can significantly help to improve the security of your Arduino account. Options offered by Arduino Cloud are: * **Two-step verification:** a second step to verify your identity during login adds an extra layer of protection to your account. Once enabled, you will be asked to provide your regular password and a digit code when logging in. It will be your responsibility to make sure that all relevant data to enter your account when two-step verification is enabled are properly backed up. * **Social login:** managing multiple accounts with multiple passwords might become problematic, which is why you can choose to login to your Arduino account using a social login that you already own. Via social login you can authenticate to your Arduino account by using your favorite social account without sharing any sensitive login information with Arduino. @@ -47,7 +47,7 @@ Security measures are applied to ensure confidentiality and integrity of data: * Users’ credentials are hashed using state of the art hashing algorithms. * **Protection in transit**: * Any Browser-based or API-based communication uses HTTPS protocol secured with TLS. - * IoT devices are sending data to our cloud using MQTT protocol secured with TLS. + * IoT devices are sending data to our Cloud using MQTT protocol secured with TLS. ### Secure Software Development Practices diff --git a/content/arduino-cloud/09.business/09.arduino-cloud-for-business/contend.md b/content/arduino-cloud/09.business/09.arduino-cloud-for-business/contend.md index 1b68d98834..679d3aa739 100644 --- a/content/arduino-cloud/09.business/09.arduino-cloud-for-business/contend.md +++ b/content/arduino-cloud/09.business/09.arduino-cloud-for-business/contend.md @@ -1,394 +1,394 @@ ---- -beta: true -title: 'Getting started with Arduino Cloud for Business' -description: 'Get a general overview of Arduino Cloud for Business and its features' -difficulty: intermediate -tags: - - Arduino Cloud - - Fleet Management - - RBAC -author: 'Marta Barbero' -software: - - iot-cloud ---- - - -## Overview - -The [Arduino Cloud for Business](https://www.arduino.cc/pro/software-arduino-iot-cloud/) is an Arduino Cloud plan dedicated to companies and industrial clients wanting enhanced features in terms of device management, Role-Based Access Control (RBAC), fleet management, and safe remote access. - -In this article, you will get a general overview of the major features of the Arduino Cloud for Business. - -If you are not familiar with Arduino Cloud, we strongly recommend you to take a look at the following documentation: - -* To find all tutorials & articles, visit the [Arduino Cloud Documentation page](https://docs.arduino.cc/cloud/iot-cloud). -* For API & SDK Documentation, visit the developer reference at [Arduino Cloud API](https://www.arduino.cc/reference/en/iot/api/). - -## Goals - -* Get in-depth information about how the Arduino Cloud for Business works -* Learn about the multiple dedicated features Arduino Cloud for Business provides -* Learn how to get started with Arduino Cloud for Business - -## Required Software - -* [Arduino Cloud for Business](https://cloud.arduino.cc/plans#business) - -## Purchase An Arduino Cloud For Business Plan - -In order to get started with Arduino Cloud for Business, you need to [subscribe to a plan](https://cloud.arduino.cc/plans#business). - -The Arduino Cloud for Business plan consists of two main subscriptions: - -* **Enterprise Base Plan.** It includes all the Arduino Cloud for Business features, like data plane, fleet management, Role-Based-Access-Control, Web Editor with Over-the-air updates, IoT Cloud with dashboards, etc. Multiples of 50 devices can be connected under the Enterprise Base Plan – and you can always [contact our team](https://www.arduino.cc/pro/contact-us) for a tailored plan to accelerate your IoT solutions. -* **Optional Add-Ons.** To address additional needs, Arduino Cloud for Business can be customized with optional add-ons. Check the [dedicated section](#optional-add-ons) of this tutorial to learn more. - -If you do not need any tailored plan, go to [Arduino Cloud for Business page](https://cloud.arduino.cc/plans#business) and select **Purchase**. You will be then asked to log in with your Arduino credentials. If you do not have an account yet, feel free to create a new one. - -![Arduino Cloud login](assets/arduino-account-login.png "Arduino Cloud login") - -It is now time to customize your plan. Select the billing frequency you prefer and the number of Things (and so devices) that you would like to connect with your Arduino Cloud for Business workspace. Click on **Continue**. - -![Customize your plan](assets/plan-customization.png "Customize your plan") - -Proceed by marking the optional add-ons you may need in your projects and click on **Add billing information**. To learn more about these add-ons, check the [dedicated section](#optional-add-ons) of the present getting started guide. - -![Add-ons section](assets/add-on-selection.png "Add-ons section") - -In the next steps, add all your billing and payment information and then purchase your plan. - -Now you are ready to get started with your brand new Arduino Cloud for Business plan. - -Check the next sections to understand how to set up your account and which features are included in your plan. - -## Manage Your Spaces - -Once your plan has been successfully activated, you will be asked to define the company/space name for your workspace. You are free to modify it later by navigating to `Arduino Cloud > General Settings > Space information > Edit info > Name`. - -![Create new shared space](assets/create-new-space.png "Create new shared space") - -Your Arduino Cloud for Business plan comes with two spaces by default: - -* **My Cloud**. My Cloud is an automatically created private space once the Arduino Cloud for Business plan is purchased. You can use this space for personal projects you do not want to share with all your team. This space is free and includes two Things, unlimited dashboards, and 100MB of Sketch storage by default, but it can be further extended and customized within *My plans* settings. Have a look at the [Arduino IT Cloud Getting Started](https://docs.arduino.cc/arduino-cloud/guides/overview) if you would like to start using your private space. -* **Shared Space**. A *Shared Space* is a company space you can use with all your team. It can have any number of members, who can all access the resources within its space. The access level and specific permissions can be customized by the *Space Admin* (see [Invite members into your space section](#invite-members-into-your-space) to learn more). - -In the next sections, you will learn more about Shared Space features and functionalities. - -### Switch Between Spaces - -If you are the owner of more than one Shared Space, or you have been invited into a Shared Space by another user, you can switch to other Shared Spaces at any time using the corresponding menu. - -Move your mouse over the Space-Selector, which you can find at the top right-hand corner, and click on it. All the Spaces you have access to will be listed there. - -![Switch between Spaces](assets/switch-spaces.png "Switch between Spaces") - -The Space-Selector shows you at any time which Space you are currently working on, in this case, *Arduino PRO*. To switch to another Space, simply select the Space you would like to work on. - -### Change Shared Space Settings - -To change the current settings of your Shared Space, navigate to the **General Settings** tab using the sidebar. - -![Shared Space settings](assets/shared-space-settings.png "Shared space settings") - -There you will find multiple options to customize your Shared Space, including: - -* Editing the Space name -* Assigning your custom logo - -### Create Additional Spaces - -The Arduino Cloud for Business plan allows you to create and manage one Shared Space and one Private Space. If you need additional Spaces, you have to purchase a new Arduino Cloud plan. Check the available plans [here](https://cloud.arduino.cc/plans). - -In order to create a new Shared Space, click on **New Shared Space** in the Space-Selector. - -![Switch between Spaces](assets/switch-spaces.png "Switch between Spaces") - -Then you will be asked which type of Shared Space you want to create (i.e. For Business or For Education). Click on the type of your interest and proceed with purchasing a new plan. - -![Shared Space type selection](assets/shared-space-type-selection.png "Shared Space Type Selection") - -### Invite Members Into Your Space - -To add more members to your Shared Space, use the sidebar to navigate to the **Members** item under **Your space** group. - -![List of Shared Space Members](assets/members-home.png "List of Shared Space Members") - -There you will find the complete list of all members who have access to your Shared Space, as well as the current role of each member. - -#### Members Types - -There are multiple role types in Arduino Cloud for Business to allow the admin to have full control of the rights/permissions each user has in the Shared Space. In this way, the admin can set up Role-Based-Access-Control (RBAC) by assigning profiles and sharing with any number of users. - -By default the member who has activated the plan and created the workspace is set as Admin. The Role-Based-Access-Control can support multiple Admins with same permissions. - -The table below reports the list of supported roles and corresponding permissions. - -| | Admin | Editor | Service Account | -|-------------------------------------------|-------|---------|-----------------| -| **Create/edit/delete Things** | X | X | | -| **View Things** | X | X | | -| **Add/edit/delete Devices** | X | X | | -| **View Devices** | X | X | | -| **Create/edit/delete Dashboards/Widgets** | X | X | | -| **View Dashboards** | X | X | | -| **Widget Interaction** | X | X | | -| **Download Historical Data** | X | X | | -| **Add/remove Members** | X | X \[1\] | | -| **Manage billing** | X | | | -| **Create/edit/delete API keys** | | | X | - -\[1\] It can add/remove only Editors. - -In addition to editor role, we added a Service Account, which should be one dedicated to the creation and maintenance of API Keys Tokens. We recommend having at least one Service Account for each Shared Space and linking it to a non-personal email account. In this way, API Keys do not risk getting lost with the cancellation of a personal email address. - -#### Add A New Member - -To add a new member, click on **Add member** in the top right-hand corner. - -![Add a new member](assets/members-home.png "Add a new member") - -The following page will appear to allow you to send an email invitation to all the members you would like to join your Space. - -![New member invitation](assets/new-member-invitation.png "New member invitation") - -Type the email addresses of all your team and define which role they will cover in your Space based on the available options. Click on **Invite**. -The users you added will get the invitation by email with a link to join your Shared Space. You are now ready to start working all together on your Arduino Cloud projects. - -## Device Management - -The Arduino Cloud for Business allows for device management with Over-The-Air updates, secure provisioning to connect boards leveraging their secure element, and easy verification of their status (connected, not connected) and maintenance. - -### Compatible Hardware - -The Arduino Cloud for Business is compatible with multiple Arduino boards or devices based on the ESP32 / ESP8266 microcontrollers. The Arduino Cloud currently supports devices connected via Wi-Fi®, Ethernet, LoRaWAN® (via The Things Network), and cellular connectivity. - -To check the full list of compatible Hardware, have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/guides/overview). - -### Device Provisioning - -Arduino Cloud allows you to securely provision your devices through two different tools: - -* **Arduino Cloud.** Arduino Cloud is an App integrated into your Arduino Cloud Space, guaranteeing straightforward provisioning of Arduino or other Cloud-compatible devices. It is provided with a dedicated User Interface which will guide you step-by-step during the onboarding process. This is a great choice in case you need to provision a few devices or you are not an advanced user. -* **Arduino Cloud CLI.** As explained in [this section](#arduino-cloud-cli), Arduino has developed a command line tool enabling the access of all Arduino Cloud features from a terminal window. Arduino Cloud CLI is the right choice when you need to provision multiple devices at the same time and you are an advanced user. - -#### Device Provisioning With Arduino Cloud - -If your device is compatible with Arduino Cloud, you can start provisioning it into your Shared Space by connecting it to your computer through a USB cable. - -In addition, Arduino Cloud requires your computer to have the [Arduino Create Agent installed](https://create.arduino.cc/getting-started/plugin/welcome). - -When you are all set up correctly, you can click on **Arduino Cloud** button in your Shared Space. - -![Arduino Cloud button](assets/iot-cloud-button.png "Arduino Cloud button") - -Go to the **Devices** tab, click on **Add** and decide which type of device you would like to onboard. In this case, a Portenta H7 board will be used. - -![Device selection](assets/device-onboarding.png "Device selection") - -The agent will start looking for your board. When your board has been found, the following screen will appear. Click on **Configure**. - -![Device configuration during provisioning](assets/portenta-found.png "Device configuration during provisioning") - -Select a board name to be able to correctly identify your device and click on **Next**. - -![Device name configuration](assets/device-name-configuration.png "Device name configuration") - -Define the connection type you want to use with your board and click on **Next.** The agent will start securely provisioning your device by leveraging the secure element embedded in your board. This way, your security keys will be stored in the secure element and full data encryption will be guaranteed during data exchanges between Arduino devices and the Cloud. - -***If you want to learn more about security in Arduino Cloud, please check the [dedicated documentation](https://docs.arduino.cc/arduino-cloud/features/security-considerations).*** - -If the onboarding proceeds as expected, the following page will appear confirming that your device has been successfully provisioned in Arduino Cloud. - -![Successful provisioning](assets/provisioning-success.png "Successful provisioning") - -You can now check its status under the Devices section. This section 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, firmware version, linked Thing, latest activity, and the date when the device was added. - -The device status indicates whether it is connected to the Arduino Cloud (online), or not connected (offline). - -![List of devices in your Arduino Cloud](assets/devices-list.png "List of devices in your Arduino Cloud") - -#### Device Provisioning With Arduino Cloud CLI - -If you need to provision more than one device at a time or you prefer to work through your terminal window, we have the right tool for you: [Arduino Cloud CLI](https://github.com/arduino/arduino-cloud-cli). - -To proceed with the onboarding, check [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli). It will explain to you all the required steps to provision your board through your terminal. - -### Assign A Thing To Your Device - -As already said, 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. - -To use your devices in IoT Cloud, you need to associate a Thing with each of them. A Thing is the digital twin of your device, holding the configuration of some variables and other settings, as well as the history of the data collected for those variables. - -To create a Thing, click on **Create Thing** next to the device of your interest, and your Thing will be automatically created for you. At this point, you can start updating it. - -![Create a new Thing](assets/create-thing.png "Create a new Thing") - -***If you want to understand how to work with your Things, check the dedicated documentation available [here](https://docs.arduino.cc/arduino-cloud/guides/overview#3-creating-a-thing).*** - -***Do you want to learn more about the different types of Variables and their features? Have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/cloud-variables).*** - -### Device Programming - -It is now time to start uploading sketches on your devices. - -The Arduino Cloud has a feature capable of creating some pre-built sections of the sketch related to a Thing, including some libraries necessary to interact with the cloud variables, as well as directly populating and updating the sketch once the new cloud variables are created and defined. - -The sketch related to the thing is visible from the tab "Sketch" next to the "Setup" view, where the Thing's list of cloud variables is shown. - -From this sketch view, by clicking the "Open full editor button", it is fast and smooth to access the Arduino Cloud integrated [Web Editor](https://docs.arduino.cc/learn/starting-guide/the-arduino-web-editor), which allows you to program your boards from any browser and use the latest Arduino IDE features and libraries without having to install any software locally. - -Otherwise, to open the Web Editor to directly retrieve your sketches, go to Arduino Cloud Home and click on the [Web Editor](https://create.arduino.cc/editor) button. - -![Get started with the Web Editor](assets/web-editor-button.png "Get started with the Web Editor") - -***To get started with the Web Editor, check the dedicated tutorial at [this link](https://docs.arduino.cc/arduino-cloud/getting-started/getting-started-web-editor). However, if you have already developed your sketch and you would like to import it into the Web Editor, see the corresponding documentation [here](https://docs.arduino.cc/arduino-cloud/tutorials/import-your-sketchbook-and-libraries-to-the-web-editor)*** - -All the created sketches are individual and owned by the user that created them. Other members of the Shared Space can access your sketch in their Web Editor only if you share it with them. If you would like to do so, have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/share-your-sketches) on how to do it. - -Keep in mind that your sketch may contain some sensitive data that you do not want to share with other members, like Wi-Fi® credentials or API keys. If this is the case, check [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/store-your-sensitive-data-safely-when-sharing) to learn how to share sketches without sharing sensitive data. - -### OTA Updates - -Arduino Cloud for Business integrates an amazing feature: Over-The-Air updates. This feature allows you to upload sketches wirelessly to your Arduino boards. This way, as soon as you have a compatible board connected to a Wi-Fi®/Ethernet network and configured to work with OTA, you will not need to physically connect the board to your computer to upload new sketches to it; instead, everything will work Over-The-Air, even from remote. - -***Are you interested in learning how to perform an OTA update? Check [this tutorial](https://docs.arduino.cc/arduino-cloud/features/ota-getting-started#how-does-it-work). If you prefer to use the Arduino Cloud CLI instead, go to [this link](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#ota-over-the-air).*** - -## Fleet Management - -Now it is time for you to start managing your fleet of devices/Things. The Arduino Cloud for Business fleet management features allow you to filter your devices/Things by status, add tags to more efficiently identify your projects, search between boards, and list and order them. - -Get started with this awesome feature by going to **Things** or **Devices** tab in [Arduino Cloud](https://app.arduino.cc/devices) and start searching and filtering among your Things/devices. - -![Search and filter among devices](assets/search-things.png "Search and filter among devices") - -If you want to create your tag, which you can use as a filtering option, go to **Things** tab, click on the Thing you would like to tag and go to the Metadata tab as shown in the figure below. - -![Thing metadata](assets/thing-metadata.png "Thing metadata"). - -Click on **Add**. You will be asked to customize your tag through two fields: - -* **Key**. The Key is the filter name which you will see among the list of available filtering options. E.g. Location. -* **Value**. The Value corresponds to the specific value your tag has for that specific Thing. E.g. Rome. - -![Customize your tag](assets/add-tag.png "Customize your tag") - -You can add an unlimited number of tags to each Thing. - -At this point, you can go back to the Things tab and start filtering your Things according to the new tag you have just created. - -![New tag filtering](assets/new-tag-filtering.png "New tag filtering") - -## Dashboards - -With Arduino Cloud for Business, you can create an unlimited number of dashboards. Push button, Switch, Scheduler, Map, Chart… These are just a few of the many widgets you can customize to visualize all your data or to remotely control your devices. - -To start creating your dashboard, go to the **Dashboards** tab in [Arduino Cloud](https://app.arduino.cc/dashboards) and select the Thing you want to create a dashboard for. - -![Dashboard example](assets/dashboard-example.png "Dashboard example") - -***If you want to learn more on how to customize your dashboard and leverage the wide widget portfolio, check the dedicated documentation available at [this link](https://docs.arduino.cc/arduino-cloud/getting-started/dashboard-widgets).*** - -### Sharing Dashboards - -Whether it is your teammate, your customer, or your system integrator; you can freely share your dashboards with all the people you like. Just keep in mind that the interested stakeholders need to have an Arduino Account to access the dashboards. - -![Share your dashboard](assets/dashboard-sharing.png "Share your dashboard") - -***Ready to share your dashboard? Have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/features/sharing-dashboards).*** - -### Data Export - -Arduino Cloud for Business allows any user to download historical data from Arduino Cloud Things and Variables. The data are downloaded in **.csv** format to be ready for further evaluation or manipulation. - -The Arduino Cloud for Business plan includes 1-year of data retention by default; this means that your data will be available and downloadable from your Arduino Cloud account for 1 year. - -To start exporting your data locally, navigate into one of your dashboards on the [Arduino Cloud](https://app.arduino.cc/dashboards). While inside a dashboard, press the Download icon in the upper right corner. This will open a new window that will allow you to select which historical data you would like to download. - -![Download icon](assets/download-button.png "Download icon") - -From here you can select all the variables you want to download by checking the boxes as well as the time frame you are interested in. - -When you have selected the data, click on the **Select Data Source** button. - -![Export your data](assets/download-data.png "Exporte your data") - -At this point, click on **Get data** to receive your data by email. - -![Get your data](assets/get-data.png "Get your data") - -You will get an email like the one below with a link allowing you to download all your data. - -![Link to download your data](assets/email-data.png "Link to download your data") - -You are now ready to monitor and manipulate all your Cloud data. - -## Arduino Cloud API - -Use Arduino Cloud back-end to control Things and devices via Arduino rest APIs in [Javascript](https://www.npmjs.com/package/@arduino/arduino-iot-client), [Python](https://pypi.org/project/arduino-iot-client/), or [Go](https://github.com/arduino/iot-client-go). With Arduino rest APIs, you will be able to manage up to 10 requests per second, guaranteeing stable data sharing. - -Leveraging the APIs, you can interact with any element of the Cloud: data, devices, dashboards, and web properties. At the same time, APIs allow you to add power to the script, create complex scenarios or send and receive data from your custom service, 3rd party solution, or mobile application. - -To use the APIs, you need to create an API Key Token in the API Keys section of your Space. - -***We strongly recommend you add a Service Account role to your Shared Space to create/manage/maintain API Keys Tokens. The Service Account should not be linked to a personal email account so that the API Keys which will be created do not risk getting lost if that email account gets canceled.*** - -***If you want to start creating your own API Keys Token, take a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-iot-api) and [this documentation](https://www.arduino.cc/reference/en/iot/api/).*** - -## IoT Remote App - -Monitor your dashboards anywhere, anytime, and use your dashboards on the go with the free IoT Remote App. - -To start exploring it, you will need to download it from either [Google Play Store](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) or the [Apple App Store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) depending on your device. - -***Do you want to get started with IoT Remote App? Read [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/iot-remote-phone-sensors#phone-setup).*** - -## Arduino Cloud CLI - -As already mentioned, Arduino Cloud for Business fully supports the [Arduino Cloud CLI](https://github.com/arduino/arduino-cloud-cli). The Arduino Cloud CLI allows accessing all the Arduino Cloud features from your terminal window. - -Arduino Cloud CLI is the right choice when you are familiar with command-line interfaces and you would like to manage multiple devices and Things at the same time with few lines of code. - -These are the main features of Arduino Cloud CLI: - -* [Mass provisioning](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#device), i.e. provisioning of multiple devices at the same time. -* [Mass OTA updates](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#ota-over-the-air), i.e. Over-The-Air update of multiple devices at the same time. -* Advanced fleet management, including multiple devices [tagging](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#list-devices). -* Things monitoring and management, such as Things [tagging](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#tag-a-thing), [listing](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#list-things), [cloning](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#clone-things) and [template creation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#extract-thing-template). -* Dashboard [creation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#create-dashboard)/[cancellation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#delete-dashboards), maintenance and dashboard [template extraction](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#extract-dashboard-template). - -***If you would like to learn more about Arduino Cloud CLI and get started with it, check the corresponding documentation available [here](https://docs.google.com/document/d/1UBh5L-GXiAJiZG4LoZ5nY7ldXd7PAXSDax3pyb5DULU/edit).*** - -## Optional Add-Ons - -Arduino Cloud for Business can be customized with optional add-ons: - -* **Portenta X8 Manager** -* **Machine Learning Tools Enterprise** - -![Arduino Cloud Homepage with Add-ons](assets/cloud-add-on.png "Arduino Cloud Homepage with Add-ons") - -To get started with them, it is sufficient to click on the corresponding tab. - -### Portenta X8 Manager - -Securely maintain Portenta X8 Linux distribution with this dedicated add-on, powered by [Foundries.io](https://foundries.io/). Deploy and update all your applications packaged into containers and perform secure Over-The-Air differential updates to target Portenta X8 devices/fleets. - -***Check [Portenta X8 documentation](https://docs.arduino.cc/hardware/portenta-x8) to find out more and start working with Portenta X8 Manager.*** - -### Machine Learning Tools Enterprise - -Build and train professional-grade predictive models with just a few lines of code through this dedicated add-on, powered by [Edge Impulse®](https://www.edgeimpulse.com/). Deploy premade models out of the box to quickly develop your machine learning projects, starting from object detection, and machine vision to audio segmentation. - -***If you are interested in learning more about this add-on, have a look at [this documentation](https://cloud.arduino.cc/machine-learning-tools). Otherwise, we have plenty of tutorials already using Machine Learning Tools. Check if your device is compatible with it in the board documentation available [here](https://docs.arduino.cc/).*** - -## Additional Tutorials - -You can find more tutorials on the [Arduino Cloud documentation page](https://docs.arduino.cc/arduino-cloud/). - -## Congratulations - -You are just a few easy steps from deploying your very own IoT project. Having a project connected to the Arduino Cloud for Business opens up many possibilities, such as tracking data in real-time, triggering remote devices and building wireless systems. - -What will you create? - -[Start your Cloud journey now](https://cloud.arduino.cc/plans#business). +--- +beta: true +title: 'Getting started with Arduino Cloud for Business' +description: 'Get a general overview of Arduino Cloud for Business and its features' +difficulty: intermediate +tags: + - Arduino Cloud + - Fleet Management + - RBAC +author: 'Marta Barbero' +software: + - iot-cloud +--- + + +## Overview + +The [Arduino Cloud for Business](https://www.arduino.cc/pro/software-arduino-iot-cloud/) is an Arduino Cloud plan dedicated to companies and industrial clients wanting enhanced features in terms of device management, Role-Based Access Control (RBAC), fleet management, and safe remote access. + +In this article, you will get a general overview of the major features of the Arduino Cloud for Business. + +If you are not familiar with Arduino Cloud, we strongly recommend you to take a look at the following documentation: + +* To find all tutorials & articles, visit the [Arduino Cloud Documentation page](https://docs.arduino.cc/cloud/iot-cloud). +* For API & SDK Documentation, visit the developer reference at [Arduino Cloud API](https://www.arduino.cc/reference/en/iot/api/). + +## Goals + +* Get in-depth information about how the Arduino Cloud for Business works +* Learn about the multiple dedicated features Arduino Cloud for Business provides +* Learn how to get started with Arduino Cloud for Business + +## Required Software + +* [Arduino Cloud for Business](https://cloud.arduino.cc/plans#business) + +## Purchase An Arduino Cloud For Business Plan + +In order to get started with Arduino Cloud for Business, you need to [subscribe to a plan](https://cloud.arduino.cc/plans#business). + +The Arduino Cloud for Business plan consists of two main subscriptions: + +* **Enterprise Base Plan.** It includes all the Arduino Cloud for Business features, like data plane, fleet management, Role-Based-Access-Control, Web Editor with Over-the-air updates, IoT Cloud with dashboards, etc. Multiples of 50 devices can be connected under the Enterprise Base Plan – and you can always [contact our team](https://www.arduino.cc/pro/contact-us) for a tailored plan to accelerate your IoT solutions. +* **Optional Add-Ons.** To address additional needs, Arduino Cloud for Business can be customized with optional add-ons. Check the [dedicated section](#optional-add-ons) of this tutorial to learn more. + +If you do not need any tailored plan, go to [Arduino Cloud for Business page](https://cloud.arduino.cc/plans#business) and select **Purchase**. You will be then asked to log in with your Arduino credentials. If you do not have an account yet, feel free to create a new one. + +![Arduino Cloud login](assets/arduino-account-login.png "Arduino Cloud login") + +It is now time to customize your plan. Select the billing frequency you prefer and the number of Things (and so devices) that you would like to connect with your Arduino Cloud for Business workspace. Click on **Continue**. + +![Customize your plan](assets/plan-customization.png "Customize your plan") + +Proceed by marking the optional add-ons you may need in your projects and click on **Add billing information**. To learn more about these add-ons, check the [dedicated section](#optional-add-ons) of the present getting started guide. + +![Add-ons section](assets/add-on-selection.png "Add-ons section") + +In the next steps, add all your billing and payment information and then purchase your plan. + +Now you are ready to get started with your brand new Arduino Cloud for Business plan. + +Check the next sections to understand how to set up your account and which features are included in your plan. + +## Manage Your Spaces + +Once your plan has been successfully activated, you will be asked to define the company/space name for your workspace. You are free to modify it later by navigating to `Arduino Cloud > General Settings > Space information > Edit info > Name`. + +![Create new shared space](assets/create-new-space.png "Create new shared space") + +Your Arduino Cloud for Business plan comes with two spaces by default: + +* **My Cloud**. My Cloud is an automatically created private space once the Arduino Cloud for Business plan is purchased. You can use this space for personal projects you do not want to share with all your team. This space is free and includes two Things, unlimited dashboards, and 100MB of Sketch storage by default, but it can be further extended and customized within *My plans* settings. Have a look at the [Arduino IT Cloud Getting Started](https://docs.arduino.cc/arduino-cloud/guides/overview) if you would like to start using your private space. +* **Shared Space**. A *Shared Space* is a company space you can use with all your team. It can have any number of members, who can all access the resources within its space. The access level and specific permissions can be customized by the *Space Admin* (see [Invite members into your space section](#invite-members-into-your-space) to learn more). + +In the next sections, you will learn more about Shared Space features and functionalities. + +### Switch Between Spaces + +If you are the owner of more than one Shared Space, or you have been invited into a Shared Space by another user, you can switch to other Shared Spaces at any time using the corresponding menu. + +Move your mouse over the Space-Selector, which you can find at the top right-hand corner, and click on it. All the Spaces you have access to will be listed there. + +![Switch between Spaces](assets/switch-spaces.png "Switch between Spaces") + +The Space-Selector shows you at any time which Space you are currently working on, in this case, *Arduino PRO*. To switch to another Space, simply select the Space you would like to work on. + +### Change Shared Space Settings + +To change the current settings of your Shared Space, navigate to the **General Settings** tab using the sidebar. + +![Shared Space settings](assets/shared-space-settings.png "Shared space settings") + +There you will find multiple options to customize your Shared Space, including: + +* Editing the Space name +* Assigning your custom logo + +### Create Additional Spaces + +The Arduino Cloud for Business plan allows you to create and manage one Shared Space and one Private Space. If you need additional Spaces, you have to purchase a new Arduino Cloud plan. Check the available plans [here](https://cloud.arduino.cc/plans). + +In order to create a new Shared Space, click on **New Shared Space** in the Space-Selector. + +![Switch between Spaces](assets/switch-spaces.png "Switch between Spaces") + +Then you will be asked which type of Shared Space you want to create (i.e. For Business or For Education). Click on the type of your interest and proceed with purchasing a new plan. + +![Shared Space type selection](assets/shared-space-type-selection.png "Shared Space Type Selection") + +### Invite Members Into Your Space + +To add more members to your Shared Space, use the sidebar to navigate to the **Members** item under **Your space** group. + +![List of Shared Space Members](assets/members-home.png "List of Shared Space Members") + +There you will find the complete list of all members who have access to your Shared Space, as well as the current role of each member. + +#### Members Types + +There are multiple role types in Arduino Cloud for Business to allow the admin to have full control of the rights/permissions each user has in the Shared Space. In this way, the admin can set up Role-Based-Access-Control (RBAC) by assigning profiles and sharing with any number of users. + +By default the member who has activated the plan and created the workspace is set as Admin. The Role-Based-Access-Control can support multiple Admins with same permissions. + +The table below reports the list of supported roles and corresponding permissions. + +| | Admin | Editor | Service Account | +|-------------------------------------------|-------|---------|-----------------| +| **Create/edit/delete Things** | X | X | | +| **View Things** | X | X | | +| **Add/edit/delete Devices** | X | X | | +| **View Devices** | X | X | | +| **Create/edit/delete Dashboards/Widgets** | X | X | | +| **View Dashboards** | X | X | | +| **Widget Interaction** | X | X | | +| **Download Historical Data** | X | X | | +| **Add/remove Members** | X | X \[1\] | | +| **Manage billing** | X | | | +| **Create/edit/delete API keys** | | | X | + +\[1\] It can add/remove only Editors. + +In addition to editor role, we added a Service Account, which should be one dedicated to the creation and maintenance of API Keys Tokens. We recommend having at least one Service Account for each Shared Space and linking it to a non-personal email account. In this way, API Keys do not risk getting lost with the cancellation of a personal email address. + +#### Add A New Member + +To add a new member, click on **Add member** in the top right-hand corner. + +![Add a new member](assets/members-home.png "Add a new member") + +The following page will appear to allow you to send an email invitation to all the members you would like to join your Space. + +![New member invitation](assets/new-member-invitation.png "New member invitation") + +Type the email addresses of all your team and define which role they will cover in your Space based on the available options. Click on **Invite**. +The users you added will get the invitation by email with a link to join your Shared Space. You are now ready to start working all together on your Arduino Cloud projects. + +## Device Management + +The Arduino Cloud for Business allows for device management with Over-The-Air updates, secure provisioning to connect boards leveraging their secure element, and easy verification of their status (connected, not connected) and maintenance. + +### Compatible Hardware + +The Arduino Cloud for Business is compatible with multiple Arduino boards or devices based on the ESP32 / ESP8266 microcontrollers. The Arduino Cloud currently supports devices connected via Wi-Fi®, Ethernet, LoRaWAN® (via The Things Network), and cellular connectivity. + +To check the full list of compatible Hardware, have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/guides/overview). + +### Device Provisioning + +Arduino Cloud allows you to securely provision your devices through two different tools: + +* **Arduino Cloud.** Arduino Cloud is an App integrated into your Arduino Cloud Space, guaranteeing straightforward provisioning of Arduino or other Cloud-compatible devices. It is provided with a dedicated User Interface which will guide you step-by-step during the onboarding process. This is a great choice in case you need to provision a few devices or you are not an advanced user. +* **Arduino Cloud CLI.** As explained in [this section](#arduino-cloud-cli), Arduino has developed a command line tool enabling the access of all Arduino Cloud features from a terminal window. Arduino Cloud CLI is the right choice when you need to provision multiple devices at the same time and you are an advanced user. + +#### Device Provisioning With Arduino Cloud + +If your device is compatible with Arduino Cloud, you can start provisioning it into your Shared Space by connecting it to your computer through a USB cable. + +In addition, Arduino Cloud requires your computer to have the [Arduino Create Agent installed](https://create.arduino.cc/getting-started/plugin/welcome). + +When you are all set up correctly, you can click on **Arduino Cloud** button in your Shared Space. + +![Arduino Cloud button](assets/iot-cloud-button.png "Arduino Cloud button") + +Go to the **Devices** tab, click on **Add** and decide which type of device you would like to onboard. In this case, a Portenta H7 board will be used. + +![Device selection](assets/device-onboarding.png "Device selection") + +The agent will start looking for your board. When your board has been found, the following screen will appear. Click on **Configure**. + +![Device configuration during provisioning](assets/portenta-found.png "Device configuration during provisioning") + +Select a board name to be able to correctly identify your device and click on **Next**. + +![Device name configuration](assets/device-name-configuration.png "Device name configuration") + +Define the connection type you want to use with your board and click on **Next.** The agent will start securely provisioning your device by leveraging the secure element embedded in your board. This way, your security keys will be stored in the secure element and full data encryption will be guaranteed during data exchanges between Arduino devices and the Cloud. + +***If you want to learn more about security in Arduino Cloud, please check the [dedicated documentation](https://docs.arduino.cc/arduino-cloud/features/security-considerations).*** + +If the onboarding proceeds as expected, the following page will appear confirming that your device has been successfully provisioned in Arduino Cloud. + +![Successful provisioning](assets/provisioning-success.png "Successful provisioning") + +You can now check its status under the Devices section. This section 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, firmware version, linked Thing, latest activity, and the date when the device was added. + +The device status indicates whether it is connected to the Arduino Cloud (online), or not connected (offline). + +![List of devices in your Arduino Cloud](assets/devices-list.png "List of devices in your Arduino Cloud") + +#### Device Provisioning With Arduino Cloud CLI + +If you need to provision more than one device at a time or you prefer to work through your terminal window, we have the right tool for you: [Arduino Cloud CLI](https://github.com/arduino/arduino-cloud-cli). + +To proceed with the onboarding, check [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli). It will explain to you all the required steps to provision your board through your terminal. + +### Assign A Thing To Your Device + +As already said, 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. + +To use your devices in IoT Cloud, you need to associate a Thing with each of them. A Thing is the digital twin of your device, holding the configuration of some variables and other settings, as well as the history of the data collected for those variables. + +To create a Thing, click on **Create Thing** next to the device of your interest, and your Thing will be automatically created for you. At this point, you can start updating it. + +![Create a new Thing](assets/create-thing.png "Create a new Thing") + +***If you want to understand how to work with your Things, check the dedicated documentation available [here](https://docs.arduino.cc/arduino-cloud/guides/overview#3-creating-a-thing).*** + +***Do you want to learn more about the different types of Variables and their features? Have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/cloud-variables).*** + +### Device Programming + +It is now time to start uploading sketches on your devices. + +The Arduino Cloud has a feature capable of creating some pre-built sections of the sketch related to a Thing, including some libraries necessary to interact with the Cloud variables, as well as directly populating and updating the sketch once the new Cloud variables are created and defined. + +The sketch related to the thing is visible from the tab "Sketch" next to the "Setup" view, where the Thing's list of Cloud variables is shown. + +From this sketch view, by clicking the "Open full editor button", it is fast and smooth to access the Arduino Cloud integrated [Web Editor](https://docs.arduino.cc/learn/starting-guide/the-arduino-web-editor), which allows you to program your boards from any browser and use the latest Arduino IDE features and libraries without having to install any software locally. + +Otherwise, to open the Web Editor to directly retrieve your sketches, go to Arduino Cloud Home and click on the [Web Editor](https://create.arduino.cc/editor) button. + +![Get started with the Web Editor](assets/web-editor-button.png "Get started with the Web Editor") + +***To get started with the Web Editor, check the dedicated tutorial at [this link](https://docs.arduino.cc/arduino-cloud/getting-started/getting-started-web-editor). However, if you have already developed your sketch and you would like to import it into the Web Editor, see the corresponding documentation [here](https://docs.arduino.cc/arduino-cloud/tutorials/import-your-sketchbook-and-libraries-to-the-web-editor)*** + +All the created sketches are individual and owned by the user that created them. Other members of the Shared Space can access your sketch in their Web Editor only if you share it with them. If you would like to do so, have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/share-your-sketches) on how to do it. + +Keep in mind that your sketch may contain some sensitive data that you do not want to share with other members, like Wi-Fi® credentials or API keys. If this is the case, check [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/store-your-sensitive-data-safely-when-sharing) to learn how to share sketches without sharing sensitive data. + +### OTA Updates + +Arduino Cloud for Business integrates an amazing feature: Over-The-Air updates. This feature allows you to upload sketches wirelessly to your Arduino boards. This way, as soon as you have a compatible board connected to a Wi-Fi®/Ethernet network and configured to work with OTA, you will not need to physically connect the board to your computer to upload new sketches to it; instead, everything will work Over-The-Air, even from remote. + +***Are you interested in learning how to perform an OTA update? Check [this tutorial](https://docs.arduino.cc/arduino-cloud/features/ota-getting-started#how-does-it-work). If you prefer to use the Arduino Cloud CLI instead, go to [this link](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#ota-over-the-air).*** + +## Fleet Management + +Now it is time for you to start managing your fleet of devices/Things. The Arduino Cloud for Business fleet management features allow you to filter your devices/Things by status, add tags to more efficiently identify your projects, search between boards, and list and order them. + +Get started with this awesome feature by going to **Things** or **Devices** tab in [Arduino Cloud](https://app.arduino.cc/devices) and start searching and filtering among your Things/devices. + +![Search and filter among devices](assets/search-things.png "Search and filter among devices") + +If you want to create your tag, which you can use as a filtering option, go to **Things** tab, click on the Thing you would like to tag and go to the Metadata tab as shown in the figure below. + +![Thing metadata](assets/thing-metadata.png "Thing metadata"). + +Click on **Add**. You will be asked to customize your tag through two fields: + +* **Key**. The Key is the filter name which you will see among the list of available filtering options. E.g. Location. +* **Value**. The Value corresponds to the specific value your tag has for that specific Thing. E.g. Rome. + +![Customize your tag](assets/add-tag.png "Customize your tag") + +You can add an unlimited number of tags to each Thing. + +At this point, you can go back to the Things tab and start filtering your Things according to the new tag you have just created. + +![New tag filtering](assets/new-tag-filtering.png "New tag filtering") + +## Dashboards + +With Arduino Cloud for Business, you can create an unlimited number of dashboards. Push button, Switch, Scheduler, Map, Chart… These are just a few of the many widgets you can customize to visualize all your data or to remotely control your devices. + +To start creating your dashboard, go to the **Dashboards** tab in [Arduino Cloud](https://app.arduino.cc/dashboards) and select the Thing you want to create a dashboard for. + +![Dashboard example](assets/dashboard-example.png "Dashboard example") + +***If you want to learn more on how to customize your dashboard and leverage the wide widget portfolio, check the dedicated documentation available at [this link](https://docs.arduino.cc/arduino-cloud/getting-started/dashboard-widgets).*** + +### Sharing Dashboards + +Whether it is your teammate, your customer, or your system integrator; you can freely share your dashboards with all the people you like. Just keep in mind that the interested stakeholders need to have an Arduino Account to access the dashboards. + +![Share your dashboard](assets/dashboard-sharing.png "Share your dashboard") + +***Ready to share your dashboard? Have a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/features/sharing-dashboards).*** + +### Data Export + +Arduino Cloud for Business allows any user to download historical data from Arduino Cloud Things and Variables. The data are downloaded in **.csv** format to be ready for further evaluation or manipulation. + +The Arduino Cloud for Business plan includes 1-year of data retention by default; this means that your data will be available and downloadable from your Arduino Cloud account for 1 year. + +To start exporting your data locally, navigate into one of your dashboards on the [Arduino Cloud](https://app.arduino.cc/dashboards). While inside a dashboard, press the Download icon in the upper right corner. This will open a new window that will allow you to select which historical data you would like to download. + +![Download icon](assets/download-button.png "Download icon") + +From here you can select all the variables you want to download by checking the boxes as well as the time frame you are interested in. + +When you have selected the data, click on the **Select Data Source** button. + +![Export your data](assets/download-data.png "Exporte your data") + +At this point, click on **Get data** to receive your data by email. + +![Get your data](assets/get-data.png "Get your data") + +You will get an email like the one below with a link allowing you to download all your data. + +![Link to download your data](assets/email-data.png "Link to download your data") + +You are now ready to monitor and manipulate all your Cloud data. + +## Arduino Cloud API + +Use Arduino Cloud back-end to control Things and devices via Arduino rest APIs in [Javascript](https://www.npmjs.com/package/@arduino/arduino-iot-client), [Python](https://pypi.org/project/arduino-iot-client/), or [Go](https://github.com/arduino/iot-client-go). With Arduino rest APIs, you will be able to manage up to 10 requests per second, guaranteeing stable data sharing. + +Leveraging the APIs, you can interact with any element of the Cloud: data, devices, dashboards, and web properties. At the same time, APIs allow you to add power to the script, create complex scenarios or send and receive data from your custom service, 3rd party solution, or mobile application. + +To use the APIs, you need to create an API Key Token in the API Keys section of your Space. + +***We strongly recommend you add a Service Account role to your Shared Space to create/manage/maintain API Keys Tokens. The Service Account should not be linked to a personal email account so that the API Keys which will be created do not risk getting lost if that email account gets canceled.*** + +***If you want to start creating your own API Keys Token, take a look at [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-iot-api) and [this documentation](https://www.arduino.cc/reference/en/iot/api/).*** + +## IoT Remote App + +Monitor your dashboards anywhere, anytime, and use your dashboards on the go with the free IoT Remote App. + +To start exploring it, you will need to download it from either [Google Play Store](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) or the [Apple App Store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) depending on your device. + +***Do you want to get started with IoT Remote App? Read [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/iot-remote-phone-sensors#phone-setup).*** + +## Arduino Cloud CLI + +As already mentioned, Arduino Cloud for Business fully supports the [Arduino Cloud CLI](https://github.com/arduino/arduino-cloud-cli). The Arduino Cloud CLI allows accessing all the Arduino Cloud features from your terminal window. + +Arduino Cloud CLI is the right choice when you are familiar with command-line interfaces and you would like to manage multiple devices and Things at the same time with few lines of code. + +These are the main features of Arduino Cloud CLI: + +* [Mass provisioning](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#device), i.e. provisioning of multiple devices at the same time. +* [Mass OTA updates](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#ota-over-the-air), i.e. Over-The-Air update of multiple devices at the same time. +* Advanced fleet management, including multiple devices [tagging](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#list-devices). +* Things monitoring and management, such as Things [tagging](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#tag-a-thing), [listing](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#list-things), [cloning](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#clone-things) and [template creation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#extract-thing-template). +* Dashboard [creation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#create-dashboard)/[cancellation](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#delete-dashboards), maintenance and dashboard [template extraction](https://docs.arduino.cc/arduino-cloud/getting-started/arduino-cloud-cli#extract-dashboard-template). + +***If you would like to learn more about Arduino Cloud CLI and get started with it, check the corresponding documentation available [here](https://docs.google.com/document/d/1UBh5L-GXiAJiZG4LoZ5nY7ldXd7PAXSDax3pyb5DULU/edit).*** + +## Optional Add-Ons + +Arduino Cloud for Business can be customized with optional add-ons: + +* **Portenta X8 Manager** +* **Machine Learning Tools Enterprise** + +![Arduino Cloud Homepage with Add-ons](assets/cloud-add-on.png "Arduino Cloud Homepage with Add-ons") + +To get started with them, it is sufficient to click on the corresponding tab. + +### Portenta X8 Manager + +Securely maintain Portenta X8 Linux distribution with this dedicated add-on, powered by [Foundries.io](https://foundries.io/). Deploy and update all your applications packaged into containers and perform secure Over-The-Air differential updates to target Portenta X8 devices/fleets. + +***Check [Portenta X8 documentation](https://docs.arduino.cc/hardware/portenta-x8) to find out more and start working with Portenta X8 Manager.*** + +### Machine Learning Tools Enterprise + +Build and train professional-grade predictive models with just a few lines of code through this dedicated add-on, powered by [Edge Impulse®](https://www.edgeimpulse.com/). Deploy premade models out of the box to quickly develop your machine learning projects, starting from object detection, and machine vision to audio segmentation. + +***If you are interested in learning more about this add-on, have a look at [this documentation](https://cloud.arduino.cc/machine-learning-tools). Otherwise, we have plenty of tutorials already using Machine Learning Tools. Check if your device is compatible with it in the board documentation available [here](https://docs.arduino.cc/).*** + +## Additional Tutorials + +You can find more tutorials on the [Arduino Cloud documentation page](https://docs.arduino.cc/arduino-cloud/). + +## Congratulations + +You are just a few easy steps from deploying your very own IoT project. Having a project connected to the Arduino Cloud for Business opens up many possibilities, such as tracking data in real-time, triggering remote devices and building wireless systems. + +What will you create? + +[Start your Cloud journey now](https://cloud.arduino.cc/plans#business). diff --git a/content/arduino-cloud/10.education/09.arduino-cloud-for-education/content.md b/content/arduino-cloud/10.education/09.arduino-cloud-for-education/content.md index c30ca74d55..81e1128991 100644 --- a/content/arduino-cloud/10.education/09.arduino-cloud-for-education/content.md +++ b/content/arduino-cloud/10.education/09.arduino-cloud-for-education/content.md @@ -1,386 +1,386 @@ ---- -title: 'Getting started with Arduino Cloud for Education' -description: 'Get a general overview of Arduino Cloud for Education and its features.' -difficulty: intermediate -tags: - - Cloud - - Education - - RBAC -author: 'Gaia Castronovo' -software: - - iot-cloud ---- - -## Introduction - -The [Arduino Cloud for Schools](https://cloud.arduino.cc/schools/) is a tool that provides an online space for teachers and students. - -In this article, you will get a general overview of the major features of the Arduino Cloud for Education and the features *Free* and *School* plan can offer. - -## What is Arduino Cloud? - -Arduino Cloud is an easy-to-use Internet of Things application platform. Arduino Cloud makes the creation of connected objects quick, simple, and secure. You can connect multiple devices and allow them to exchange real-time data. You can also monitor them from anywhere using a simple user interface. It is integrated with the online Arduino Web Editor. - -## How to Create an Account - -In order to get started with Arduino Cloud, you need to [have an Arduino account](https://login.arduino.cc/login). An **Arduino account gives** you **full access to all Arduino websites, apps**, and **services**. - -If you do not have an account yet, feel free to create a new one. You can follow [this tutorial](https://support.arduino.cc/hc/en-us/articles/360016724040-Create-an-Arduino-account) for a step-by-step explanation on how to do it. - -![Arduino Cloud login](assets/arduino-account-login.png) - -After the registration is completed, you should verify your email address by clicking CONFIRM NOW in the email that was automatically sent to your inbox. - -Now let's explore https://app.arduino.cc/. - -![Arduino Cloud Homepage view](assets/cloud-home-u.png) - -The Arduino Cloud for Education consists of **two main subscriptions**: - -* Free Plan -* [School Plan](https://cloud.arduino.cc/plans#school) - -By default, any new user who created an Arduino account has access to Arduino Cloud with a *Free Plan*. - -## Free Plan - -### Access to free online courses content - -Once you've logged in, you are free to check out our free content in `Arduino Cloud > Courses` or click [here](https://app.arduino.cc/courses). - -![Free Content Courses in the Cloud](assets/content-courses.png) - -Here, you get access to several free online courses, for different age groups and topics. This library of courses gets widened and extended regularly with new releases. - -***With a School Plan you unlock access to extra online courses.*** - - -## Manage Your Spaces - -Your Arduino Cloud *Free plan* comes with one **space** by default: - -![Free courses in the Cloud](assets/private-space-details.png) - - -* **Private Space**. Private space is an *automatically* created private space once joined Arduino Cloud. You can use this space for personal projects you do not want to share with all your class. This space is free and includes - - * *two Things*, - * unlimited dashboards, - * 100 MB of sketch storage, - * 1-day data retention by default. - - You have a quick glance on Device and Things from the menu on the top right corner. - -* **Shared Space**. It's an easy tool to keep track of your students' recent activities on their IoT projects and monitor their project progress. - - * *Save online unlimited amount of sketches* and dashboards, and easily search for them later, - * Quickly share your data flow from sensors adding up to *five Things* - * Integrate your lesson plan with Google Classroom, assign tasks and share courses. - * Study data analysis with your students with 6 months of data retention by default - -### Create a Shared Space - -In order to create a shared space go to [this link](https://app.arduino.cc/space?spaceType=%22edu%22). - -Then you will be asked which type of Shared Space you want to create (i.e. For Business or For Education). Click on **For Education** and proceed with creating a online space to share with your students or other colleagues. - -![Shared Space type selection](assets/shared-space-type-selection.png) - -Fill in additional information. - -![Fill in school information for the new Space](assets/fillschoolinfo.png) - -Congratulations! Now you own a Shared Space linked to your Arduino account. - -### Switch Between Spaces - -You can switch to other Shared Spaces at any time using the corresponding menu, which you can find at the top left-corner, and click on it. - -***With a Free Plan or School Plan there is no limitations in the number of Shared Space you can have.*** - -![Switch between Space Menu](assets/switch-space.png) - -### Change Shared Space Settings - -To change the current settings of your Shared Space, navigate to the **Space Settings** tab using the sidebar. - -![Shared Space Side Bar](assets/space-setting-side-bar.png) - -Here you can **Edit** your information, change name or **Disband Shared Space**. From this menu you can also manage the members you've invited into your Shared Space. - -![Shared Space settings](assets/space-setting.png) - -From `Arduino Cloud > Space Setting` menu you can check your plan's limit and quota or upgrade it to a School Plan. - -### Invite Members Into Your Space - -You can add more members to your Shared Space from the `Cloud > Home`, clicking on the shortcut green button `INVITE MEMBERS` or you can [click here](https://app.arduino.cc/settings). - -![invite members to shared space](assets/invite-members.png) - -Once inside the Cloud homepage, from the card on the right top corner, you will find the complete list of all members who have access to your Shared Space, as well as the current role of each member. - -You can add members in **three possible ways**: - -1. Type the **email addresses** of each user and define which role they will cover in your Space based on the available options. Click on **Invite**. The users you added will get the invitation by email with a link to join your Shared Space. - -2. You can invite your students to the Space through **Code** invitation (check *Join Space* explained above). - -3. **Copy pasting the link** and share it with the whole class. - -![Invite members through email](assets/add-members.png) - -**Join Space**. Here you copy and paste the space code that another admin or teacher shared with you to join their space. See image below: - - -![Join Space](assets/copy-code-join.png) - -### Role types - -There are three role types in Arduino Cloud for Schools: - -* Admin -* Teacher -* Students - -By default the member who has activated the plan and created the class-space is set as *Admin*. It is possible to have multiple Admins with same permissions. The admin has full control of the rights/permissions each user has in a Shared Space. - -The list of supported roles and corresponding permissions can be found here: https://cloud.arduino.cc/home/roles-permissions - -Important to remember are **Student role limitations:** - -* They are not allowed to add new members to your School organization -* They are not allowed to assign members roles -* They are not allowed to view the Plan Management and Payment information - -![school user roles differences](assets/user-roles.png) - -***There is no limitation on the numbers of members you can add into a Shared Space.*** - -*** - -## IoT Components - -On the left menu bar in https://app.arduino.cc/, all the elements you will use to set up your IoT projects for a quick access are listed: - -1. [Devices](https://app.arduino.cc/devices) -2. [Things](https://app.arduino.cc/things) -3. [Dashboards](https://app.arduino.cc/dashboards) -4. [Triggers](https://app.arduino.cc/triggers) - -![Cloud left bar IoT components](assets/iot-cloud.png) - -| Cloud components | Free Plan | School Plan | -| :--------------: | :-------: | :---------: | -| Devices | x | x | -| Things | x | x | -| Dashboards | x | x | -| Triggers | | x | - -With a *Free Plan* you won't have access to Cloud Triggers, so you'll see something similar to this: - -![Triggers with a free plan](assets/triggers-freeplan.png) - -If you want to unlock this function, you'll need to upgrade to a [School Plan](https://digital-store.arduino.cc/education/purchase). - - -### Let's Setup a IoT Project - -In your IoT projects with Arduino you will need **three elements**: - -1. The [**Arduino Cloud**](https://docs.arduino.cc/arduino-cloud/guides/overview) -2. The [**Arduino Create Agent**](https://create.arduino.cc/getting-started/plugin/welcome) the middle man between Arduino’s Web Editor, Arduino Cloud and your computer. It allows you to use the browser to edit and deploy sketches to your Arduino board. -3. **A device** of your choice. - -### Setup a Device in Arduino Cloud - -Arduino Cloud is compatible with multiple Arduino boards or devices based on the ESP32 / ESP8266 microcontrollers. The Arduino Cloud currently supports devices connected via Wi-Fi®, Ethernet, LoRaWAN® (via The Things Network), and cellular connectivity. You can check the [full list of compatible hardware here](https://support.arduino.cc/hc/en-us/articles/360016077320-What-devices-can-be-used-with-Arduino-IoT-Cloud-). - -If your device is compatible with Arduino Cloud, you can start to **Setup Device** by connecting it to your computer through a USB cable, going to `Arduino Cloud Homepage > Devices > Add Device`. - -![Device selection](assets/plugin-device.png) - -The agent will start looking for your board, select the kind of device you're setting up and continue to follow the next guided steps. - -![Set up board in the cloud](assets/setup-device.png) - -Select a board name to be able to correctly identify your device and click on **Next**. - -![Give a name to the device](assets/name-device.png) - -If the onboarding proceeds as expected, the following page will appear confirming that your device has been successfully set up. - -![Successfully set up device](assets/been-configured.png) - -When you click on a `Device`'s name it displays all the associated `Things`, more information about the device, such as its ID number, FQBN, serial number, firmware version, Device Status history, and the date when the device was added. - -![Details of a device when you click on it](assets/device-details.png) - -The device status indicates whether it is connected to the Arduino Cloud (online), or not connected (offline). Click on the three dots to rename your device. - -![List of devices added into Cloud](assets/device-list.png) - -### Link A Thing To Your Device - -To use a device in Arduino Cloud, you need to [create a Thing](https://app.arduino.cc/things), or associate it to an existing Thing. A Thing is the digital twin of your device, like a reference to the actual hardware used to implement them. Each Thing is represented by a collection of properties, the configuration of some variables and other settings, as well as the history of the data collected for those variables. - -Let's make your first Thing, going to Cloud homepage sidebar, click on the green button CREATE THING. - -![Create a thing from device tab](assets/create-thing.png) - -If you want to explore more on how Things work, check [here](https://docs.arduino.cc/arduino-cloud/guides/overview#3-creating-a-thing). - -***With a Free Plan you can only connect two Things with the Cloud at a time. With a School Plan, each member you've included in your plan can connect up to five Things to a Device.*** - -### Variables - -In order to retrieve and store information we need to create Variables in the Arduino Cloud, they are very similar to the variables we create in a regular sketch. - -![Variables associated to a Thing](assets/add-variable.png) - -When we create variables here, they are automatically generated in a sketch, and when we upload the code to the board, the variables used in the sketch synchronize with the variables in the Cloud. - -To learn more about the different types of variables, go to [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/cloud-variables). - -***The Arduino Cloud - Free Plan allows a maximum number of 5 variables per Thing by default. The Arduino Cloud - School Plan allows an unlimited number of variables per Thing.*** - -### Dashboards - -Dashboards are used to visualize real-time data and to enable direct interaction with the board through the Cloud. Go to `Dashboard` and click the green button `Create`. We'll link `Variables` we've created before to a *Widget*. - -***With a Free Plan is not possible to share your Dashboard with other users. If you want to unlock this function, you'll need to upgrade to a [School Plan](https://digital-store.arduino.cc/education/purchase).*** - -![Dashboard example](assets/create-dashboard.png) - -**Widgets** are the ‘building blocks’ of a dashboard, and are directly linked to our properties. They allow us to visualize the data we get from sensors. There are several different widgets: gauges, sliders, switches, color palettes, messenger and more. - -![Widgets Selection](assets/add-widget.png) - -If you want to learn more on how to customize your dashboard and widgets, check [this link](https://docs.arduino.cc/arduino-cloud/getting-started/dashboard-widgets). - -***If want to use to Advanced Chart Widget for your IoT projects, that allows you to visualize multiple variables in one chart, you'll need access to the School Plan.*** - -![Advanced Chart Widget](assets/advanced-chart.gif) - -You can read more about Advance Chart Widget [here](https://docs.arduino.cc/arduino-cloud/features/advanced-chart). - -### Data Export - -Arduino Cloud, both with *Free* or *School Plan*, allows any user to download historical data from Arduino Cloud Things and Variables. The data are downloaded in **.csv** format to be ready for further editing. - -***The Arduino Cloud - Free Plan allows only 1 day of data retention by default. The Arduino Cloud - School Plan includes 6 months of data retention by default; this means that your data will be available and downloadable from your Arduino Cloud account for 6 months.*** - -To start exporting your data locally, navigate into one of your dashboards on the [Arduino Cloud](https://app.arduino.cc/dashboards). While inside a dashboard, press the **Download** icon in the upper right corner. This will open a new window that will allow you to select which historical data you would like to download. - -![Download icon](assets/download-button.png) - -From here you can select all the variables you want to download by checking the boxes as well as the time frame you are interested in. - -Read more about how to use on download collected data [in this tutorial](https://docs.arduino.cc/arduino-cloud/features/iot-cloud-historical-data). - -### What is Arduino Web Editor? - -[Arduino Web Editor](http://create.arduino.cc/editor) allows you to **write code** and **upload sketches** to any Arduino board after installing a **[simple plug-in](https://create.arduino.cc/getting-started/plugin/welcome) for your browser**. Your Sketchbook will be stored in the Cloud and accessible from any device. If you have a *Free Plan* you can store to a maximum of 100 MB of sketches. - -You can import your Sketchbook via a .zip file. Arduino Web Editor is part of Arduino Cloud, that simplifies a project by bringing all the different tools you need together in one place. This is a complementary solutions for schools or institutions that don't want to install [Arduino IDE](https://www.arduino.cc/en/software) to program their devices. - -If you want to know more about Arduino Web Editor [visit this link](https://docs.arduino.cc/arduino-cloud/getting-started/getting-started-web-editor). - -A **lite version of the Web Editor** is included in the Arduino Cloud, under `Things > Sketch`, which is actually a preview of a sketch saved on the Web Editor. - -![Arduino Cloud Lite Editor](assets/thing-sketchtab.png) - -***The Arduino Cloud - Free Plan allows a maximum online space to store your sketches and libraries of 100 MB and a maximum of 25 code compilations per day by default. The Arduino Cloud - School Plan allows unlimited online storage space and unlimited code compilations for your sketches.*** - -You can check how many times you have left to verify and upload your program from the [Arduino Cloud > Space Setting > Plan Usage](https://app.arduino.cc/plan-usage). - -![Feature usage menu](assets/features-usage.png) - - - -*** - -## School Plan - -As an Educator you might need: - -* To create and store in the Cloud more sketches -* To collaborate in your IoT projects sharing real-time data dashboards and programs -* To integrate your IoT Project with an LMS tool -* To customize your projects with additional functionalities provided by APIS -* To handle several students' accounts with one Admin - -### Buy a School Plan - -To upgrade from a *Free Plan* to *School Plan* and get access to the features mentioned in this article, go here: - -https://digital-store.arduino.cc/education/purchase/institution - -1. If you're not logged in with an Arduino account, you'll be redirected to the login page. If you've already created a Shared Space **select the institution Space you want to add your members' seats to** or click **Set up new shared Space** to make a brand new one. - - ![Select the institution space](assets/school-plan.png) - -2. **Add as many members seats** you need for your classes. - - ![add members to the school plan](assets/configure-your-plan.png) - -3. Then click on the button **Add Billing Information** and fill in with your educational institution information and payment method. - - ![add billing information](assets/add-billing-information.png) - -Then click on the green button `ACTIVATE PLAN`. - -Congratulations! Now you own a *School Plan* linked to your Arduino account. You should have received a confirmation email. Continue reading to discover more about the additional functions you've now unlocked. - -### Sharing Dashboards - -With a *School Plan* is possible to share any Dashboard with anyone. Go to the [Dashboard](https://app.arduino.cc/dashboards) tab in Arduino Cloud, go inside the Dashboard you would like to share, click on the three dots, next to the download button. - -As shown in the image below you can either send it directly to the user's *email* or *username*, or *share the link* with your class. - -![Share your dashboard](assets/share-dashboards.png) - -You can check [this tutorial](https://docs.arduino.cc/arduino-cloud/features/sharing-dashboards) to learn more about sharing a dashboard. - -### Google Classroom™ Integration - -With a *School plan* any educator that is part of a Shared Space can create assignments and share a sketch directly from the Arduino Web Editor. - -![Share sketch with Google Classroom](assets/google-integration-arduino-cloud02.png) - -It is also possible to share the content of a course or give it as an assignment. - -![Share content with Google Classroom](assets/google-classroom-content-share.png) - -## IoT Templates - -[Templates](https://app.arduino.cc/templates) are ready-made projects that will automatically configure your device, Thing, and variables. - -It's the easiest way to proceed with a beginner class and you can check that section to get inspiration for your own class project. - -### Over-the-air Uploads - -This feature, included in the Arduino Cloud *School Plan*, allows you to upload programs wirelessly to your Arduino boards. If you have a compatible board connected to a Wi-Fi®/Ethernet network and configured it to work with OTA (over-the-air), you won’t need to physically connect the board to the computer in order to upload new sketches to it. - -Check [this tutorial](https://docs.arduino.cc/arduino-cloud/features/ota-getting-started#how-does-it-work) to learn how to upload your program remotely to your board. - -### Billing & subscriptions - -![Billing & subscriptions menu](assets/my-cloud-space.png) - -School Plan is specifically designed for institutions that aim to cover a larger amount of users. The billing account can be managed by a single Arduino account that then will grant access to different users and assign a role. - -### Account settings - Junior Account - -If your students are **under the age of 14**, they need parental consent to sign up for an Arduino account. We recommend to read [this tutorial](https://support.arduino.cc/hc/en-us/articles/360022234360) to learn how to manage a Junior account. Arduino Education provides [several solutions for middle school](https://www.arduino.cc/education/middle-school/) students. The content courses included in the *School Plan* are only partially available for minor users. They will get access only to COPPA-compliant courses. - -## Cloud Remote App - -Cloud Remote App allows you to monitor your dashboards anywhere, anytime, from a **mobile device** i.e. smartphone or tablet for **free**. Download it from either [Google Play Store](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) or the [Apple App Store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) depending on your device. - -***Do you want to get started with Cloud Remote app? Read [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/iot-remote-phone-sensors#phone-setup).*** - -## Arduino Cloud Tutorials - -You can find a full list of tutorials on the [Arduino Cloud documentation page](https://docs.arduino.cc/arduino-cloud/). - +--- +title: 'Getting started with Arduino Cloud for Education' +description: 'Get a general overview of Arduino Cloud for Education and its features.' +difficulty: intermediate +tags: + - Cloud + - Education + - RBAC +author: 'Gaia Castronovo' +software: + - iot-cloud +--- + +## Introduction + +The [Arduino Cloud for Schools](https://cloud.arduino.cc/schools/) is a tool that provides an online space for teachers and students. + +In this article, you will get a general overview of the major features of the Arduino Cloud for Education and the features *Free* and *School* plan can offer. + +## What is Arduino Cloud? + +Arduino Cloud is an easy-to-use Internet of Things application platform. Arduino Cloud makes the creation of connected objects quick, simple, and secure. You can connect multiple devices and allow them to exchange real-time data. You can also monitor them from anywhere using a simple user interface. It is integrated with the online Arduino Web Editor. + +## How to Create an Account + +In order to get started with Arduino Cloud, you need to [have an Arduino account](https://login.arduino.cc/login). An **Arduino account gives** you **full access to all Arduino websites, apps**, and **services**. + +If you do not have an account yet, feel free to create a new one. You can follow [this tutorial](https://support.arduino.cc/hc/en-us/articles/360016724040-Create-an-Arduino-account) for a step-by-step explanation on how to do it. + +![Arduino Cloud login](assets/arduino-account-login.png) + +After the registration is completed, you should verify your email address by clicking CONFIRM NOW in the email that was automatically sent to your inbox. + +Now let's explore https://app.arduino.cc/. + +![Arduino Cloud Homepage view](assets/cloud-home-u.png) + +The Arduino Cloud for Education consists of **two main subscriptions**: + +* Free Plan +* [School Plan](https://cloud.arduino.cc/plans#school) + +By default, any new user who created an Arduino account has access to Arduino Cloud with a *Free Plan*. + +## Free Plan + +### Access to free online courses content + +Once you've logged in, you are free to check out our free content in `Arduino Cloud > Courses` or click [here](https://app.arduino.cc/courses). + +![Free Content Courses in the Cloud](assets/content-courses.png) + +Here, you get access to several free online courses, for different age groups and topics. This library of courses gets widened and extended regularly with new releases. + +***With a School Plan you unlock access to extra online courses.*** + + +## Manage Your Spaces + +Your Arduino Cloud *Free plan* comes with one **space** by default: + +![Free courses in the Cloud](assets/private-space-details.png) + + +* **Private Space**. Private space is an *automatically* created private space once joined Arduino Cloud. You can use this space for personal projects you do not want to share with all your class. This space is free and includes + + * *two Things*, + * unlimited dashboards, + * 100 MB of sketch storage, + * 1-day data retention by default. + + You have a quick glance on Device and Things from the menu on the top right corner. + +* **Shared Space**. It's an easy tool to keep track of your students' recent activities on their IoT projects and monitor their project progress. + + * *Save online unlimited amount of sketches* and dashboards, and easily search for them later, + * Quickly share your data flow from sensors adding up to *five Things* + * Integrate your lesson plan with Google Classroom, assign tasks and share courses. + * Study data analysis with your students with 6 months of data retention by default + +### Create a Shared Space + +In order to create a shared space go to [this link](https://app.arduino.cc/space?spaceType=%22edu%22). + +Then you will be asked which type of Shared Space you want to create (i.e. For Business or For Education). Click on **For Education** and proceed with creating a online space to share with your students or other colleagues. + +![Shared Space type selection](assets/shared-space-type-selection.png) + +Fill in additional information. + +![Fill in school information for the new Space](assets/fillschoolinfo.png) + +Congratulations! Now you own a Shared Space linked to your Arduino account. + +### Switch Between Spaces + +You can switch to other Shared Spaces at any time using the corresponding menu, which you can find at the top left-corner, and click on it. + +***With a Free Plan or School Plan there is no limitations in the number of Shared Space you can have.*** + +![Switch between Space Menu](assets/switch-space.png) + +### Change Shared Space Settings + +To change the current settings of your Shared Space, navigate to the **Space Settings** tab using the sidebar. + +![Shared Space Side Bar](assets/space-setting-side-bar.png) + +Here you can **Edit** your information, change name or **Disband Shared Space**. From this menu you can also manage the members you've invited into your Shared Space. + +![Shared Space settings](assets/space-setting.png) + +From `Arduino Cloud > Space Setting` menu you can check your plan's limit and quota or upgrade it to a School Plan. + +### Invite Members Into Your Space + +You can add more members to your Shared Space from the `Cloud > Home`, clicking on the shortcut green button `INVITE MEMBERS` or you can [click here](https://app.arduino.cc/settings). + +![invite members to shared space](assets/invite-members.png) + +Once inside the Cloud homepage, from the card on the right top corner, you will find the complete list of all members who have access to your Shared Space, as well as the current role of each member. + +You can add members in **three possible ways**: + +1. Type the **email addresses** of each user and define which role they will cover in your Space based on the available options. Click on **Invite**. The users you added will get the invitation by email with a link to join your Shared Space. + +2. You can invite your students to the Space through **Code** invitation (check *Join Space* explained above). + +3. **Copy pasting the link** and share it with the whole class. + +![Invite members through email](assets/add-members.png) + +**Join Space**. Here you copy and paste the space code that another admin or teacher shared with you to join their space. See image below: + + +![Join Space](assets/copy-code-join.png) + +### Role types + +There are three role types in Arduino Cloud for Schools: + +* Admin +* Teacher +* Students + +By default the member who has activated the plan and created the class-space is set as *Admin*. It is possible to have multiple Admins with same permissions. The admin has full control of the rights/permissions each user has in a Shared Space. + +The list of supported roles and corresponding permissions can be found here: https://cloud.arduino.cc/home/roles-permissions + +Important to remember are **Student role limitations:** + +* They are not allowed to add new members to your School organization +* They are not allowed to assign members roles +* They are not allowed to view the Plan Management and Payment information + +![school user roles differences](assets/user-roles.png) + +***There is no limitation on the numbers of members you can add into a Shared Space.*** + +*** + +## IoT Components + +On the left menu bar in https://app.arduino.cc/, all the elements you will use to set up your IoT projects for a quick access are listed: + +1. [Devices](https://app.arduino.cc/devices) +2. [Things](https://app.arduino.cc/things) +3. [Dashboards](https://app.arduino.cc/dashboards) +4. [Triggers](https://app.arduino.cc/triggers) + +![Cloud left bar IoT components](assets/iot-cloud.png) + +| Cloud components | Free Plan | School Plan | +| :--------------: | :-------: | :---------: | +| Devices | x | x | +| Things | x | x | +| Dashboards | x | x | +| Triggers | | x | + +With a *Free Plan* you won't have access to Cloud Triggers, so you'll see something similar to this: + +![Triggers with a free plan](assets/triggers-freeplan.png) + +If you want to unlock this function, you'll need to upgrade to a [School Plan](https://digital-store.arduino.cc/education/purchase). + + +### Let's Setup a IoT Project + +In your IoT projects with Arduino you will need **three elements**: + +1. The [**Arduino Cloud**](https://docs.arduino.cc/arduino-cloud/guides/overview) +2. The [**Arduino Create Agent**](https://create.arduino.cc/getting-started/plugin/welcome) the middle man between Arduino’s Web Editor, Arduino Cloud and your computer. It allows you to use the browser to edit and deploy sketches to your Arduino board. +3. **A device** of your choice. + +### Setup a Device in Arduino Cloud + +Arduino Cloud is compatible with multiple Arduino boards or devices based on the ESP32 / ESP8266 microcontrollers. The Arduino Cloud currently supports devices connected via Wi-Fi®, Ethernet, LoRaWAN® (via The Things Network), and cellular connectivity. You can check the [full list of compatible hardware here](https://support.arduino.cc/hc/en-us/articles/360016077320-What-devices-can-be-used-with-Arduino-IoT-Cloud-). + +If your device is compatible with Arduino Cloud, you can start to **Setup Device** by connecting it to your computer through a USB cable, going to `Arduino Cloud Homepage > Devices > Add Device`. + +![Device selection](assets/plugin-device.png) + +The agent will start looking for your board, select the kind of device you're setting up and continue to follow the next guided steps. + +![Set up board in the Cloud](assets/setup-device.png) + +Select a board name to be able to correctly identify your device and click on **Next**. + +![Give a name to the device](assets/name-device.png) + +If the onboarding proceeds as expected, the following page will appear confirming that your device has been successfully set up. + +![Successfully set up device](assets/been-configured.png) + +When you click on a `Device`'s name it displays all the associated `Things`, more information about the device, such as its ID number, FQBN, serial number, firmware version, Device Status history, and the date when the device was added. + +![Details of a device when you click on it](assets/device-details.png) + +The device status indicates whether it is connected to the Arduino Cloud (online), or not connected (offline). Click on the three dots to rename your device. + +![List of devices added into Cloud](assets/device-list.png) + +### Link A Thing To Your Device + +To use a device in Arduino Cloud, you need to [create a Thing](https://app.arduino.cc/things), or associate it to an existing Thing. A Thing is the digital twin of your device, like a reference to the actual hardware used to implement them. Each Thing is represented by a collection of properties, the configuration of some variables and other settings, as well as the history of the data collected for those variables. + +Let's make your first Thing, going to Cloud homepage sidebar, click on the green button CREATE THING. + +![Create a thing from device tab](assets/create-thing.png) + +If you want to explore more on how Things work, check [here](https://docs.arduino.cc/arduino-cloud/guides/overview#3-creating-a-thing). + +***With a Free Plan you can only connect two Things with the Cloud at a time. With a School Plan, each member you've included in your plan can connect up to five Things to a Device.*** + +### Variables + +In order to retrieve and store information we need to create Variables in the Arduino Cloud, they are very similar to the variables we create in a regular sketch. + +![Variables associated to a Thing](assets/add-variable.png) + +When we create variables here, they are automatically generated in a sketch, and when we upload the code to the board, the variables used in the sketch synchronize with the variables in the Cloud. + +To learn more about the different types of variables, go to [this tutorial](https://docs.arduino.cc/arduino-cloud/getting-started/cloud-variables). + +***The Arduino Cloud - Free Plan allows a maximum number of 5 variables per Thing by default. The Arduino Cloud - School Plan allows an unlimited number of variables per Thing.*** + +### Dashboards + +Dashboards are used to visualize real-time data and to enable direct interaction with the board through the Cloud. Go to `Dashboard` and click the green button `Create`. We'll link `Variables` we've created before to a *Widget*. + +***With a Free Plan is not possible to share your Dashboard with other users. If you want to unlock this function, you'll need to upgrade to a [School Plan](https://digital-store.arduino.cc/education/purchase).*** + +![Dashboard example](assets/create-dashboard.png) + +**Widgets** are the ‘building blocks’ of a dashboard, and are directly linked to our properties. They allow us to visualize the data we get from sensors. There are several different widgets: gauges, sliders, switches, color palettes, messenger and more. + +![Widgets Selection](assets/add-widget.png) + +If you want to learn more on how to customize your dashboard and widgets, check [this link](https://docs.arduino.cc/arduino-cloud/getting-started/dashboard-widgets). + +***If want to use to Advanced Chart Widget for your IoT projects, that allows you to visualize multiple variables in one chart, you'll need access to the School Plan.*** + +![Advanced Chart Widget](assets/advanced-chart.gif) + +You can read more about Advance Chart Widget [here](https://docs.arduino.cc/arduino-cloud/features/advanced-chart). + +### Data Export + +Arduino Cloud, both with *Free* or *School Plan*, allows any user to download historical data from Arduino Cloud Things and Variables. The data are downloaded in **.csv** format to be ready for further editing. + +***The Arduino Cloud - Free Plan allows only 1 day of data retention by default. The Arduino Cloud - School Plan includes 6 months of data retention by default; this means that your data will be available and downloadable from your Arduino Cloud account for 6 months.*** + +To start exporting your data locally, navigate into one of your dashboards on the [Arduino Cloud](https://app.arduino.cc/dashboards). While inside a dashboard, press the **Download** icon in the upper right corner. This will open a new window that will allow you to select which historical data you would like to download. + +![Download icon](assets/download-button.png) + +From here you can select all the variables you want to download by checking the boxes as well as the time frame you are interested in. + +Read more about how to use on download collected data [in this tutorial](https://docs.arduino.cc/arduino-cloud/features/iot-cloud-historical-data). + +### What is Arduino Web Editor? + +[Arduino Web Editor](http://create.arduino.cc/editor) allows you to **write code** and **upload sketches** to any Arduino board after installing a **[simple plug-in](https://create.arduino.cc/getting-started/plugin/welcome) for your browser**. Your Sketchbook will be stored in the Cloud and accessible from any device. If you have a *Free Plan* you can store to a maximum of 100 MB of sketches. + +You can import your Sketchbook via a .zip file. Arduino Web Editor is part of Arduino Cloud, that simplifies a project by bringing all the different tools you need together in one place. This is a complementary solutions for schools or institutions that don't want to install [Arduino IDE](https://www.arduino.cc/en/software) to program their devices. + +If you want to know more about Arduino Web Editor [visit this link](https://docs.arduino.cc/arduino-cloud/getting-started/getting-started-web-editor). + +A **lite version of the Web Editor** is included in the Arduino Cloud, under `Things > Sketch`, which is actually a preview of a sketch saved on the Web Editor. + +![Arduino Cloud Lite Editor](assets/thing-sketchtab.png) + +***The Arduino Cloud - Free Plan allows a maximum online space to store your sketches and libraries of 100 MB and a maximum of 25 code compilations per day by default. The Arduino Cloud - School Plan allows unlimited online storage space and unlimited code compilations for your sketches.*** + +You can check how many times you have left to verify and upload your program from the [Arduino Cloud > Space Setting > Plan Usage](https://app.arduino.cc/plan-usage). + +![Feature usage menu](assets/features-usage.png) + + + +*** + +## School Plan + +As an Educator you might need: + +* To create and store in the Cloud more sketches +* To collaborate in your IoT projects sharing real-time data dashboards and programs +* To integrate your IoT Project with an LMS tool +* To customize your projects with additional functionalities provided by APIS +* To handle several students' accounts with one Admin + +### Buy a School Plan + +To upgrade from a *Free Plan* to *School Plan* and get access to the features mentioned in this article, go here: + +https://digital-store.arduino.cc/education/purchase/institution + +1. If you're not logged in with an Arduino account, you'll be redirected to the login page. If you've already created a Shared Space **select the institution Space you want to add your members' seats to** or click **Set up new shared Space** to make a brand new one. + + ![Select the institution space](assets/school-plan.png) + +2. **Add as many members seats** you need for your classes. + + ![add members to the school plan](assets/configure-your-plan.png) + +3. Then click on the button **Add Billing Information** and fill in with your educational institution information and payment method. + + ![add billing information](assets/add-billing-information.png) + +Then click on the green button `ACTIVATE PLAN`. + +Congratulations! Now you own a *School Plan* linked to your Arduino account. You should have received a confirmation email. Continue reading to discover more about the additional functions you've now unlocked. + +### Sharing Dashboards + +With a *School Plan* is possible to share any Dashboard with anyone. Go to the [Dashboard](https://app.arduino.cc/dashboards) tab in Arduino Cloud, go inside the Dashboard you would like to share, click on the three dots, next to the download button. + +As shown in the image below you can either send it directly to the user's *email* or *username*, or *share the link* with your class. + +![Share your dashboard](assets/share-dashboards.png) + +You can check [this tutorial](https://docs.arduino.cc/arduino-cloud/features/sharing-dashboards) to learn more about sharing a dashboard. + +### Google Classroom™ Integration + +With a *School plan* any educator that is part of a Shared Space can create assignments and share a sketch directly from the Arduino Web Editor. + +![Share sketch with Google Classroom](assets/google-integration-arduino-cloud02.png) + +It is also possible to share the content of a course or give it as an assignment. + +![Share content with Google Classroom](assets/google-classroom-content-share.png) + +## IoT Templates + +[Templates](https://app.arduino.cc/templates) are ready-made projects that will automatically configure your device, Thing, and variables. + +It's the easiest way to proceed with a beginner class and you can check that section to get inspiration for your own class project. + +### Over-the-air Uploads + +This feature, included in the Arduino Cloud *School Plan*, allows you to upload programs wirelessly to your Arduino boards. If you have a compatible board connected to a Wi-Fi®/Ethernet network and configured it to work with OTA (over-the-air), you won’t need to physically connect the board to the computer in order to upload new sketches to it. + +Check [this tutorial](https://docs.arduino.cc/arduino-cloud/features/ota-getting-started#how-does-it-work) to learn how to upload your program remotely to your board. + +### Billing & subscriptions + +![Billing & subscriptions menu](assets/my-cloud-space.png) + +School Plan is specifically designed for institutions that aim to cover a larger amount of users. The billing account can be managed by a single Arduino account that then will grant access to different users and assign a role. + +### Account settings - Junior Account + +If your students are **under the age of 14**, they need parental consent to sign up for an Arduino account. We recommend to read [this tutorial](https://support.arduino.cc/hc/en-us/articles/360022234360) to learn how to manage a Junior account. Arduino Education provides [several solutions for middle school](https://www.arduino.cc/education/middle-school/) students. The content courses included in the *School Plan* are only partially available for minor users. They will get access only to COPPA-compliant courses. + +## Cloud Remote App + +Cloud Remote App allows you to monitor your dashboards anywhere, anytime, from a **mobile device** i.e. smartphone or tablet for **free**. Download it from either [Google Play Store](https://play.google.com/store/apps/details?id=cc.arduino.cloudiot&hl=en&gl=US) or the [Apple App Store](https://apps.apple.com/us/app/arduino-iot-cloud-remote/id1514358431) depending on your device. + +***Do you want to get started with Cloud Remote app? Read [this tutorial](https://docs.arduino.cc/arduino-cloud/tutorials/iot-remote-phone-sensors#phone-setup).*** + +## Arduino Cloud Tutorials + +You can find a full list of tutorials on the [Arduino Cloud documentation page](https://docs.arduino.cc/arduino-cloud/). + diff --git a/content/arduino-cloud/11.application-notes/cloud-environmental-data/cloud-environmental-data.md b/content/arduino-cloud/11.application-notes/cloud-environmental-data/cloud-environmental-data.md index 5ba879599a..d84f029401 100644 --- a/content/arduino-cloud/11.application-notes/cloud-environmental-data/cloud-environmental-data.md +++ b/content/arduino-cloud/11.application-notes/cloud-environmental-data/cloud-environmental-data.md @@ -14,7 +14,7 @@ featuredImage: 'cloud' In this tutorial, we will combine the functionality of the [MKR WiFi 1010](https://store.arduino.cc/mkr-wifi-1010) and the [MKR ENV Shield](https://store.arduino.cc/arduino-mkr-env-shield). The shield, mounted on top of the board, will record environmental data, such as temperature, humidity, pressure and illuminance. This data will be synced with the [Arduino Cloud](https://app.arduino.cc/), a service that allows us to remotely control and monitor our devices. -This means that whenever we read data on the board, it will also be visible in the cloud dashboard, where we can create different ways of visualizing the data. +This means that whenever we read data on the board, it will also be visible in the Cloud dashboard, where we can create different ways of visualizing the data. >**Note:** Newer versions of the MKR ENV Shield does not have the UV sensor component. You can read more about the different versions in [this Arduino Help Center article](https://support.arduino.cc/hc/en-us/articles/360019197540-Different-MKR-ENV-Shield-versions). @@ -124,7 +124,7 @@ void loop() { Once the code has been uploaded, open the Serial Monitor (tab next to sketch) to initialize the program. If everything went well, it should like the image below: -![Information regarding connection to network & cloud.](./assets/serial.png) +![Information regarding connection to network & Cloud.](./assets/serial.png) The most important thing is that the two following commands are printed: @@ -142,7 +142,7 @@ To use this feature, make sure the board has power. If your board is already con ## Building a dashboard -Once we have confirmed that the board is connected to the cloud, the last step is to build the dashboard that we can monitor the environmental data in. Click on the **"Dashboards"** tab, which will take you to the dashboards page. Here, we need to click on the **"Build Dashboard"** button. +Once we have confirmed that the board is connected to the Cloud, the last step is to build the dashboard that we can monitor the environmental data in. Click on the **"Dashboards"** tab, which will take you to the dashboards page. Here, we need to click on the **"Build Dashboard"** button. ![Building a new dashboard.](./assets/new_dashboard.png) @@ -164,9 +164,9 @@ Congratulations! You can now view your real time data directly in the dashboard. ## Conclusion -In this tutorial, we demonstrated simply how a MKR WiFi 1010, a MKR ENV Shield and the Arduino Cloud is used to create a simple IoT application. This, without having to connect a single wire, or create a difficult program: the cloud takes care of all of that. +In this tutorial, we demonstrated simply how a MKR WiFi 1010, a MKR ENV Shield and the Arduino Cloud is used to create a simple IoT application. This, without having to connect a single wire, or create a difficult program: the Cloud takes care of all of that. -You can now start thinking about how this application might work in real life. There are a lot of different things you can add to it, such as wind sensors (anemometers), rain sensors, CO2 sensors and much more. With some easy connections, you can build anything you want to, connect it to the cloud and view all the data live from anywhere in the world! +You can now start thinking about how this application might work in real life. There are a lot of different things you can add to it, such as wind sensors (anemometers), rain sensors, CO2 sensors and much more. With some easy connections, you can build anything you want to, connect it to the Cloud and view all the data live from anywhere in the world! ### More tutorials diff --git a/content/arduino-cloud/11.application-notes/cloud-relay-control/cloud-relay-control.md b/content/arduino-cloud/11.application-notes/cloud-relay-control/cloud-relay-control.md index d39e5803c2..9765c6d0dd 100644 --- a/content/arduino-cloud/11.application-notes/cloud-relay-control/cloud-relay-control.md +++ b/content/arduino-cloud/11.application-notes/cloud-relay-control/cloud-relay-control.md @@ -58,7 +58,7 @@ To configure a device, navigate to the [app.arduino.cc/devices](https://app.ardu ### Create Variables -Next step is to create some cloud variables, which we will later sync with our Arduino MKR WiFi 1010 board. +Next step is to create some Cloud variables, which we will later sync with our Arduino MKR WiFi 1010 board. While in Thing configuration, click on **"Add Variable"** which will open a new window. Add the following variables with the specified configurations: @@ -71,7 +71,7 @@ Your Thing interface should now look something like this: ![Thing Interface](assets/thing.png) -***Need help understanding cloud variables? Check out the [Variables](/arduino-cloud/cloud-interface/variables) section.*** +***Need help understanding Cloud variables? Check out the [Variables](/arduino-cloud/cloud-interface/variables) section.*** ### Create Sketch @@ -153,7 +153,7 @@ You can also access your dashboard via the [Arduino IoT Remote app](/arduino-clo ***Note: Working with higher voltage components should be done with extreme caution. Do not alter the circuit while it is connected to a higher power source, and do not connect any high voltage components directly to the Arduino.*** -We've now set up the cloud to control the relays, but there's nothing connected to the relays. The relays on the MKR Relay Shield are designed to typically handle anything from 5-24V, where you will need to connect an external power supply and a higher power component that can be controlled through the relays. +We've now set up the Cloud to control the relays, but there's nothing connected to the relays. The relays on the MKR Relay Shield are designed to typically handle anything from 5-24V, where you will need to connect an external power supply and a higher power component that can be controlled through the relays. There are six **high power pins** for both relays on the shield, with three different type of connections: NO, COM and NC. From 355e37347dbd2f51f96e80b2f9e87083530f244d Mon Sep 17 00:00:00 2001 From: Josefine Hansson Date: Fri, 5 Jan 2024 10:41:06 +0100 Subject: [PATCH 02/11] mkr products --- ...a-mkr-gsm-1400-to-google-cloud-iot-core.md | 4 +- .../01.mkr/01.boards/mkr-nb-1500/product.md | 2 +- ...ing-an-arduino-nb-1500-to-azure-iot-hub.md | 2 +- .../01.mkr/01.boards/mkr-wan-1300/features.md | 64 +- .../01.mkr/01.boards/mkr-wan-1300/product.md | 2 +- .../01.mkr/01.boards/mkr-wan-1310/features.md | 64 +- .../01.mkr/01.boards/mkr-wan-1310/product.md | 2 +- .../mkr-wifi-1010/datasheet/datasheet.md | 4 +- ...n-arduino-mkr-wifi-1010-to-aws-iot-core.md | 4 +- .../datasheet/datasheet.md | 726 +++++------ .../tutorials/cheat-sheet/cheat-sheet.md | 1104 ++++++++-------- .../mkr-iot-carrier/datasheet/datasheet.md | 686 +++++----- .../mkr-iot-carrier-01-technical-reference.md | 1112 ++++++++--------- .../smart-garden-project.md | 22 +- 14 files changed, 1899 insertions(+), 1899 deletions(-) diff --git a/content/hardware/01.mkr/01.boards/mkr-gsm-1400/tutorials/securely-connecting-a-mkr-gsm-1400-to-google-cloud-iot-core/securely-connecting-a-mkr-gsm-1400-to-google-cloud-iot-core.md b/content/hardware/01.mkr/01.boards/mkr-gsm-1400/tutorials/securely-connecting-a-mkr-gsm-1400-to-google-cloud-iot-core/securely-connecting-a-mkr-gsm-1400-to-google-cloud-iot-core.md index 3e6455ae99..43008fb9fa 100644 --- a/content/hardware/01.mkr/01.boards/mkr-gsm-1400/tutorials/securely-connecting-a-mkr-gsm-1400-to-google-cloud-iot-core/securely-connecting-a-mkr-gsm-1400-to-google-cloud-iot-core.md +++ b/content/hardware/01.mkr/01.boards/mkr-gsm-1400/tutorials/securely-connecting-a-mkr-gsm-1400-to-google-cloud-iot-core/securely-connecting-a-mkr-gsm-1400-to-google-cloud-iot-core.md @@ -61,7 +61,7 @@ The private and public can be generated using an example sketch from the Arduino This sketch will prompt you to permanently configure your ATECC508A to ECC608A crypto element if it is not configured and locked. - ***NOTE: This locking process is permanent and irreversible, but is needed to use the the crypto element - the configuration the sketch sets allows you to use 5 private key slots with any cloud provider(or server) and a private key can be regenerated any time for any of the 5 private key slots (0 - 4).*** + ***NOTE: This locking process is permanent and irreversible, but is needed to use the the crypto element - the configuration the sketch sets allows you to use 5 private key slots with any Cloud provider(or server) and a private key can be regenerated any time for any of the 5 private key slots (0 - 4).*** When the board is shipped from the factory, the crypto element is in an unconfigured and unlocked state. @@ -140,7 +140,7 @@ Enter the device name, in the screenshot below "MyMKRGSM1400" was used. "ES256" #define SECRET_GPRS_PASSWORD "password" // replace with your GPRS password ``` -4) Then update the project id, cloud region, registry id and device id values. +4) Then update the project id, Cloud region, registry id and device id values. ```arduino // Fill in your Google Cloud Platform - IoT Core info diff --git a/content/hardware/01.mkr/01.boards/mkr-nb-1500/product.md b/content/hardware/01.mkr/01.boards/mkr-nb-1500/product.md index 4956278749..4100b8c3ea 100644 --- a/content/hardware/01.mkr/01.boards/mkr-nb-1500/product.md +++ b/content/hardware/01.mkr/01.boards/mkr-nb-1500/product.md @@ -11,4 +11,4 @@ certifications: [RCM, CE, UKCA] productCode: '022' --- -The Arduino MKR NB 1500 adds Narrowband communication to your projects. It can communicate over NB-IoT and LTE-M networks, and is excellent to use for low-power projects in remote areas. The MKR NB 1500 is also compatible with the Arduino IoT Cloud, making it easy to access wherever you are in the world. \ No newline at end of file +The Arduino MKR NB 1500 adds Narrowband communication to your projects. It can communicate over NB-IoT and LTE-M networks, and is excellent to use for low-power projects in remote areas. The MKR NB 1500 is also compatible with the Arduino Cloud, making it easy to access wherever you are in the world. \ No newline at end of file diff --git a/content/hardware/01.mkr/01.boards/mkr-nb-1500/tutorials/securely-connecting-an-arduino-nb-1500-to-azure-iot-hub/securely-connecting-an-arduino-nb-1500-to-azure-iot-hub.md b/content/hardware/01.mkr/01.boards/mkr-nb-1500/tutorials/securely-connecting-an-arduino-nb-1500-to-azure-iot-hub/securely-connecting-an-arduino-nb-1500-to-azure-iot-hub.md index 24780d9ddf..a8c128d616 100644 --- a/content/hardware/01.mkr/01.boards/mkr-nb-1500/tutorials/securely-connecting-an-arduino-nb-1500-to-azure-iot-hub/securely-connecting-an-arduino-nb-1500-to-azure-iot-hub.md +++ b/content/hardware/01.mkr/01.boards/mkr-nb-1500/tutorials/securely-connecting-an-arduino-nb-1500-to-azure-iot-hub/securely-connecting-an-arduino-nb-1500-to-azure-iot-hub.md @@ -62,7 +62,7 @@ The self signed certificate can be generated using an example sketch from the Ar This sketch will prompt you to permanently configure your ATECC508A to ECC608A crypto element if it is not configured and locked. - ***Note: This locking process is permanent and irreversible, but is needed to use the the crypto element - the configuration the sketch sets allows to use 5 private key slots with any cloud provider(or server) and a private key can be regenerated any time for any of the 5 private key slots (0 - 4).When the board is shipped from the factory, the crypto element is in an un-configured and unlocked state.*** + ***Note: This locking process is permanent and irreversible, but is needed to use the the crypto element - the configuration the sketch sets allows to use 5 private key slots with any Cloud provider(or server) and a private key can be regenerated any time for any of the 5 private key slots (0 - 4).When the board is shipped from the factory, the crypto element is in an un-configured and unlocked state.*** After this, you will be prompted for information to include in the self signed certificate, including the issue year, month, day and hour of the certificate and the expiry period in years. For this tutorial we'll be using slot 0 to generate and store the private key used to sign the self signed certificate (slots 1 to 4 can be used to generate and store additional private keys if needed) - then slot 8 will be used to store the issue and expiry date of the certificate along with it's signature. diff --git a/content/hardware/01.mkr/01.boards/mkr-wan-1300/features.md b/content/hardware/01.mkr/01.boards/mkr-wan-1300/features.md index 69aed97d5b..0a94d3c24f 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wan-1300/features.md +++ b/content/hardware/01.mkr/01.boards/mkr-wan-1300/features.md @@ -1,33 +1,33 @@ - -The MKR WAN 1300 brings LoRa® connectivity to your projects. Using the popular Arm® Cortex®-M0 32-bit SAMD21 processor, it also features the powerful Murata CMWX1ZZABZ module and the ECC508 crypto-chip for security. The board is part of the MKR family, where you can choose from a large variety of shields to build projects out of the box with minimal effort! - - - - - - -Use LoRaWAN® in remote places to send data to nearby gateways connected to the TTS service, which in turn forwards the data to the Arduino IoT Cloud. - - - - - - - -Use the LoRa® wireless protocol to implement your own networks, or connect to various LoRaWAN® networks, such as [The Things Network](https://www.thethingsnetwork.org/). - - - - - - - - -Set up two Arduino MKR WAn 1300 to host a remote LED control. Learn more about board-to-board communication and using LoRa® in your projects. - - - - - - + +The MKR WAN 1300 brings LoRa® connectivity to your projects. Using the popular Arm® Cortex®-M0 32-bit SAMD21 processor, it also features the powerful Murata CMWX1ZZABZ module and the ECC508 crypto-chip for security. The board is part of the MKR family, where you can choose from a large variety of shields to build projects out of the box with minimal effort! + + + + + + +Use LoRaWAN® in remote places to send data to nearby gateways connected to the TTS service, which in turn forwards the data to the Arduino Cloud. + + + + + + + +Use the LoRa® wireless protocol to implement your own networks, or connect to various LoRaWAN® networks, such as [The Things Network](https://www.thethingsnetwork.org/). + + + + + + + + +Set up two Arduino MKR WAn 1300 to host a remote LED control. Learn more about board-to-board communication and using LoRa® in your projects. + + + + + + \ No newline at end of file diff --git a/content/hardware/01.mkr/01.boards/mkr-wan-1300/product.md b/content/hardware/01.mkr/01.boards/mkr-wan-1300/product.md index a277ebd7f5..d8a36b08d1 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wan-1300/product.md +++ b/content/hardware/01.mkr/01.boards/mkr-wan-1300/product.md @@ -11,4 +11,4 @@ productCode: '129' --- -The Arduino MKR WAN 1300 was the first LoRa® board released by Arduino, as a practical and cost effective solution with minimal power requirements. This open source board can connect to the Arduino IoT Cloud, your own LoRa® network using the Arduino LoRa® PRO Gateway, existing LoRaWAN® infrastructure like The Things Network, or even other boards using the direct connectivity mode. \ No newline at end of file +The Arduino MKR WAN 1300 was the first LoRa® board released by Arduino, as a practical and cost effective solution with minimal power requirements. This open source board can connect to the Arduino Cloud, your own LoRa® network using the Arduino LoRa® PRO Gateway, existing LoRaWAN® infrastructure like The Things Network, or even other boards using the direct connectivity mode. \ No newline at end of file diff --git a/content/hardware/01.mkr/01.boards/mkr-wan-1310/features.md b/content/hardware/01.mkr/01.boards/mkr-wan-1310/features.md index bb4490849a..3f38669439 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wan-1310/features.md +++ b/content/hardware/01.mkr/01.boards/mkr-wan-1310/features.md @@ -1,33 +1,33 @@ - -The MKR WAN 1310 brings LoRa® connectivity to your projects. Using the popular Arm® Cortex®-M0 32-bit SAMD21 processor, it also features the powerful Murata CMWX1ZZABZ module and the ECC508 crypto-chip for security. The board is part of the MKR family, where you can choose from a large variety of shields to build projects out of the box with minimal effort! - - - - - - -Use LoRaWAN® in remote places to send data to nearby gateways connected to the TTS service, which in turn forwards the data to the Arduino IoT Cloud. - - - - - - - -Use the LoRa® wireless protocol to implement your own networks, or connect to various LoRaWAN® networks, such as [The Things Network](https://www.thethingsnetwork.org/). - - - - - - - - -Set up two Arduino MKR WAn 1300 to host a remote LED control. Learn more about board-to-board communication and using LoRa® in your projects. - - - - - - + +The MKR WAN 1310 brings LoRa® connectivity to your projects. Using the popular Arm® Cortex®-M0 32-bit SAMD21 processor, it also features the powerful Murata CMWX1ZZABZ module and the ECC508 crypto-chip for security. The board is part of the MKR family, where you can choose from a large variety of shields to build projects out of the box with minimal effort! + + + + + + +Use LoRaWAN® in remote places to send data to nearby gateways connected to the TTS service, which in turn forwards the data to the Arduino Cloud. + + + + + + + +Use the LoRa® wireless protocol to implement your own networks, or connect to various LoRaWAN® networks, such as [The Things Network](https://www.thethingsnetwork.org/). + + + + + + + + +Set up two Arduino MKR WAn 1300 to host a remote LED control. Learn more about board-to-board communication and using LoRa® in your projects. + + + + + + \ No newline at end of file diff --git a/content/hardware/01.mkr/01.boards/mkr-wan-1310/product.md b/content/hardware/01.mkr/01.boards/mkr-wan-1310/product.md index a981441ad1..2141201bb3 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wan-1310/product.md +++ b/content/hardware/01.mkr/01.boards/mkr-wan-1310/product.md @@ -10,4 +10,4 @@ certifications: [FCC, REACH, CE, RoHS, IC, UKCA, WEEE, GB4943, RCM, MIC] productCode: '030' --- -The Arduino MKR WAN 1310 provides a practical and cost effective solution to add LoRa® connectivity to projects requiring low power. This open source board can connect to the Arduino IoT Cloud, your own LoRa® network using the Arduino LoRa® PRO Gateway, existing LoRaWAN® infrastructure like The Things Network, or even other boards using the direct connectivity mode. \ No newline at end of file +The Arduino MKR WAN 1310 provides a practical and cost effective solution to add LoRa® connectivity to projects requiring low power. This open source board can connect to the Arduino Cloud, your own LoRa® network using the Arduino LoRa® PRO Gateway, existing LoRaWAN® infrastructure like The Things Network, or even other boards using the direct connectivity mode. \ No newline at end of file diff --git a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/datasheet/datasheet.md b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/datasheet/datasheet.md index f613d84291..00ee8f6cf0 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/datasheet/datasheet.md +++ b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/datasheet/datasheet.md @@ -148,8 +148,8 @@ If you want to program your Arduino MKR WiFi 1010 while offline you need to inst All Arduino boards, including this one, work out-of-the-box on the Arduino Web Editor [2], by just installing a simple plugin. The Arduino Web Editor is hosted online, therefore it will always be up-to-date with the latest features and support for all boards. Follow [3] to start coding on the browser and upload your sketches onto your board. -### Getting Started - Arduino IoT Cloud -All Arduino IoT enabled products are supported on Arduino IoT Cloud which allows you to Log, graph and analyze sensor data, trigger events, and automate your home or business. +### Getting Started - Arduino Cloud +All Arduino IoT enabled products are supported on Arduino Cloud which allows you to Log, graph and analyze sensor data, trigger events, and automate your home or business. ### Arduino Forum Discussions and ideas for the Arduino MKR WiFi 1010 can be found in the Arduino Forum [4]. diff --git a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/securely-connecting-an-arduino-mkr-wifi-1010-to-aws-iot-core/securely-connecting-an-arduino-mkr-wifi-1010-to-aws-iot-core.md b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/securely-connecting-an-arduino-mkr-wifi-1010-to-aws-iot-core/securely-connecting-an-arduino-mkr-wifi-1010-to-aws-iot-core.md index 442bdf8b93..be9449ad79 100644 --- a/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/securely-connecting-an-arduino-mkr-wifi-1010-to-aws-iot-core/securely-connecting-an-arduino-mkr-wifi-1010-to-aws-iot-core.md +++ b/content/hardware/01.mkr/01.boards/mkr-wifi-1010/tutorials/securely-connecting-an-arduino-mkr-wifi-1010-to-aws-iot-core/securely-connecting-an-arduino-mkr-wifi-1010-to-aws-iot-core.md @@ -22,7 +22,7 @@ source: "https://create.arduino.cc/projecthub/Arduino_Genuino/securely-connectin ### Introduction -[AWS IoT Core](https://aws.amazon.com/iot-core/) is a managed cloud service that lets connected devices easily and securely interact with cloud applications and other devices. AWS IoT Core can support billions of devices and trillions of messages, and can process and route those messages to AWS endpoints and to other devices reliably and securely. +[AWS IoT Core](https://aws.amazon.com/iot-core/) is a managed Cloud service that lets connected devices easily and securely interact with Cloud applications and other devices. AWS IoT Core can support billions of devices and trillions of messages, and can process and route those messages to AWS endpoints and to other devices reliably and securely. Devices can connect to AWS IoT Core using the following protocols: HTTP, WebSockets and MQTT. This tutorial will walk you through how to connect an [Arduino MKR WiFi 1010](https://store.arduino.cc/products/arduino-mkr-wifi-1010) (or MKR1000) board securely to AWS IoT Core using the MQTT protocol. [MQTT](http://mqtt.org/) (**Message Queuing Telemetry Transport**) is an extremely lightweight M2M (machine-to-machine) connectivity protocol which provides a messaging subscription and publish transport. @@ -58,7 +58,7 @@ The CSR can be generated using an example sketch from the ArduinoECCX08 library. This sketch will prompt you to permanently configure your ATECC508A to ECC608A crypto element if it is not configured and locked. - ***NOTE: This locking process is permanent and irreversible, but is needed to use the the crypto element - the configuration the sketch sets allows to use 5 private key slots with any cloud provider (or server) and a CSR can be regenerated any time for each of the other four slots.*** + ***NOTE: This locking process is permanent and irreversible, but is needed to use the the crypto element - the configuration the sketch sets allows to use 5 private key slots with any Cloud provider (or server) and a CSR can be regenerated any time for each of the other four slots.*** When the board is shipped from the factory, the crypto element is in an un-configured and unlocked state. diff --git a/content/hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2/datasheet/datasheet.md b/content/hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2/datasheet/datasheet.md index 7726239a93..4f85329607 100644 --- a/content/hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2/datasheet/datasheet.md +++ b/content/hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2/datasheet/datasheet.md @@ -1,364 +1,364 @@ ---- -identifier: ABX00073 -title: Arduino® MKR IoT Carrier -type: maker -revision: Rev2 -variant: Rev2 ---- - -![](assets/featured.png) - -# Description -The **MKR IoT Carrier Rev2** provides infinite possibilities for IoT projects, including a TFT display to display information, Grove connectors and multiple sensors. - -The integrated sensors, circuits and display leave you free to focus on programming and prototyping your ideas. - -# Target areas: -IoT applications, MKR hobbyists - -# Features - -***Note: This board is passive and requires a MKR board to function.*** - -***Requirements: This device require the library Arduino_MKRIoTCarrier version to be 2.0.0 or later in order to function*** - -* **Grove Connectors** - * Easy interface with wide range of Grove modules and sensors - * 2x analog sensor input - * 1x I2C interface - -* **ST LSM6DSOXTR 6-axis IMU** - * 3D Gyroscope - * ±2/±4/±8/±16 g full scale - * 3D Accelerometer - * ±125/±250/±500/±1000/±2000 dps full scale - * Advanced pedometer, step detector and step counter - * Significant Motion Detection, Tilt detection - * Standard interrupts: free-fall, wake-up, 6D/4D orientation, click and double-click - * Programmable finite state machine: accelerometer, gyroscope and external sensors - * Machine Learning Core - * Embedded temperature sensor - -* **Rounded 1.3” TFT Display** - * 240 x 240 resolution - * 36 x 40 mm - -- **Bosch BME688** Environmental sensing with Artificial Intelligence - - Operating range - - Pressure: 300-1100 hPa - - Humidity: 0-100% - - Temperature: -40 - +85°C - - eNose Gas sensor - - Sensor-to-sensor deviation (IAQ): ± 15% ± 15 IAQ - - Standard scan speed: 10.8 s/scan - - Electric charge for standard scan: 0.18 mAh (5 scans - 1 min) - - Major Sensor outputs - - Index for air quality (IAQ) - - bVOC- & CO2-equivalents (ppm) - - Gas scan result (%) - - Intensity level - -* **Broadcom APDS-9660 RGB and Gesture Sensor** - * Ambient light and RGB Colour Sensing - * Proximity Sensing - * Gesture Detection - * UV/IR Blocking Filter - * I2C interface to Arduino MKR board - -* **Relays** - * 2x KEMET EE2-5NU-L relays - * 5V Coil voltage - * 2A Current - * 220V DC, 250V AC - * Non-latching - * Common, normally open and normally closed contacts - * LED Status Indicator - -* **Peripherals** - * 5x Capacitive buttons - * Buzzer - * 5x Digital RGB LEDs - * Rounded OLED 1,3” Display - * 5x Capacitive qTouch buttons - -* **Memory** - * Micro SD Card - -* **Power** - * Li-ion 18650 3.7 v battery holder - * USB Battery charging via MKR Board (Runs up to 48h with a 3.7v 2500mAh) - -* **I/O** - * All sensors feature wake up function - * 2x Analog Grove connectors - * 1x I2C Grove connector - * 2x relay connector - -* **Safety information** - * Class A - -# Contents - -## The Board - -### Application Examples - -**Light controller:** Control your house lightning with the **MKR IoT Carrier Rev2**, using the RGB light sensor. This feature identifies the general amount of light in a room or environment and adapts. If the board is connected to Wi-Fi®, you can manage and control your device remotely on a smartphone via the IoT Cloud. - -**Light and water controller for greenhouse:** With moisture sensor, pressure sensor and temperature the IoT Carrier can evaluate and recognize the moisture of the soil, depending on air humidity and sun. Through the various sensors, it can reconstruate suitable climate (e.g. tropical) with the help of heaters and relays to increase the humidity. It can also be programmed with a watering system thanks to the relays. - -**Weather station:** With temperature sensor, pressure sensor, humidity sensor and light sensors, you can easily use your IoT carrier as a local weather station. The various sensors can via sensors collect statistics about the different variables required to display weather. - -### Accessories - -***(Not Included)*** -* 18650 Li-ion battery -* [Grove sensors](https://search.arduino.cc/search/?q=Grove%20Sensors&tab=store) -* SD Card - -### Related Products - -* [Arduino® MKR WiFi 1010 (SKU: ABX00023)](https://store.arduino.cc/products/arduino-mkr-wifi-1010) -* [Arduino® MKR Zero (SKU: ABX00012)](https://store.arduino.cc/products/arduino-mkr-zero-i2s-bus-sd-for-sound-music-digital-audio-data) -* [Arduino® MKR WAN 1310 (SKU: MKRWAN1310WANT)](https://store.arduino.cc/products/arduino-mkr-wan-1310) -* [Arduino® MKR GSM 1400 (SKU: MKRGSM1400WANT)](https://store.arduino.cc/products/arduino-mkr-gsm-1400) -* [Arduino® MKR NB 1500 (SKU: MKRNB1500WANT)](https://store.arduino.cc/products/arduino-mkr-nb-1500) - - -## Functional Overview - -### Board Topology - -#### Top View - -![Top view - components](assets/top_view.svg) - -| **Ref.** | **Description** | **Ref.** | **Description** | -| -------- | -------------------------------------- | -------- | ----------------------------------- | -| U1 | LSM6DSOXTR 6-axis IMU IC | U2 | APDS-9660 RGB and Gesture Sensor IC | -| U4 | Bosch BME688 Environmental Sensor IC | L0-L4 | APA1022020-2018 RGB LED IC | -| J6 | FH26W-45S-0.3SHW(60) Display Connector | PB1 | Reset push-button | - - -#### Bottom View - -![Bottom view](assets/bottom_view.svg) - -| **Ref.** | **Description** | **Ref.** | **Description** | -| --------- | ------------------------------------- | -------- | --------------------------------- | -| J2, J3 | Analog Grove Connectors | J4 | I2C Grove Connector | -| J11 | B2B-PH-SM4-TB(LF)(SN) Power Connector | J9, J10 | 1771033 3-pin Relay Connector | -| JDIGITAL1 | MKR Power and Digital Pin Connector | JANALOG1 | MKR AREF and Analog Pin Connector | -| S1, S2 | EE2-5NU-L 2A 250V Mechanical Relay | M1 | Buzzer | -| J1 | Micro SD Module | J7, J8 | Li-Ion 18650 Holder | - -### Power Tree -The **MKR IoT Carrier Rev2** makes use of the power management features of the Arduino MKR boards to power itself as well as to interface with the Li-Ion battery. - -![Power tree](assets/Power_Tree_MKR_IoT_Carrier.png) - -## Board Operation - -### Getting Started - IDE -If you want to program your **MKR IoT Carrier Rev2** while offline you need to install the Arduino Desktop IDE [**[1]**](#10-reference-documentation). To connect the **MKR IoT Carrier Rev2** to your computer, you’ll need a Micro-B USB cable. This also provides power to the board, as indicated by the LED. - -### Getting Started - Arduino Web Editor -All Arduino boards, including this one, work out-of-the-box on the Arduino Web Editor [**[2]**](#10-reference-documentation), by just installing a simple plugin. - -The Arduino Web Editor is hosted online, therefore it will always be up-to-date with the latest features and support for all boards. Follow [**[3]**](#10-reference-documentation) to start coding on the browser and upload your sketches onto your board. - -### Getting Started - Arduino IoT Cloud -All Arduino IoT enabled products are supported on Arduino IoT Cloud which allows you to log, graph and analyze sensor data, trigger events, and automate your home or business. - -### Sample Sketches -Sample sketches for the **MKR IoT Carrier Rev2** can be found either in the “Examples” menu in the Arduino IDE and further documentation can be found in Arduino Documentation [**[7]**](#10-reference-documentation) which also contains links to the troubleshooting articles. - -### Online Resources -Now that you have gone through the basics of what you can do with the board you can explore the endless possibilities it provides by checking exciting projects on ProjectHub [**[4]**](#10-reference-documentation), the Arduino Library Reference [**[5]**](#10-reference-documentation) and the online store [**[6]**](#10-reference-documentation) where you will be able to complement your board with sensors, actuators and more. - -### Board Recovery -All Arduino boards have a built-in bootloader which allows flashing the board via USB. In case a sketch locks up the processor and the board is not reachable anymore via USB it is possible to enter bootloader mode by double-tapping the reset button right after power up. - -## Connector Pinouts - -![Pinout](assets/Pinout.png) - -Detailed information on the pinouts are available in a separate document: [Docs Arduino - MKR IoT Carrier Rev2 pinout](https://docs.arduino.cc/resources/pinouts/ABX00073-full-pinout.pdf) - -### Battery Clips - -| Pin | **Function** | **Type** | **Description** | -| :---: | :----------: | :------: | :------------------------------ | -| 1 | GND | Power | Ground | -| 2 | VBAT | Power | Positive 18650 Battery Terminal | - -### Grove Connectors -#### A0 - -| Pin | **Function** | **Type** | **Description** | -| :---: | :----------: | :------: | ---------------- | -| 1 | AN0 | Analog | Analog Input 0 | -| 2 | NC | NC | Not Connected | -| 3 | +3.3V | Power | +3.3V power rail | -| 4 | GND | Power | Ground | - -#### A6 - -| Pin | **Function** | **Type** | **Description** | -| :---: | :----------: | :------: | ---------------- | -| 1 | AN6 | Analog | Analog Input 6 | -| 2 | NC | NC | Not Connected | -| 3 | +3.3V | Power | +3.3V power rail | -| 4 | GND | Power | Ground | - -#### I2C - -| Pin | **Function** | **Type** | **Description** | -| :---: | :----------: | :------: | ---------------- | -| 1 | SCL | Digital | I2C Clock Signal | -| 2 | SDA | Digital | I2C Data Signal | -| 3 | +3.3V | Power | +3.3V power rail | -| 4 | GND | Power | Ground | - -### Relays -#### Relay 1 and 2 - -* Relay 1 driven by digital pin 1 -* Relay 2 driven by digital pin 2 - - -| Pin | **Function** | **Type** | **Description** | -| :---: | :----------: | :------: | --------------- | -| 1 | NC | Switch | Normally Closed | -| 2 | COM | Switch | Common | -| 3 | NO | Switch | Normally Open | - -## Mechanical Information - -### Board Outline / Mounting Holes - -![Mechanical view](assets/mechanical.svg) - -### Connectors - -![Connectors positioning](assets/connectors.svg) - -### Relays Connectors - -![Left Side Relay positioning](assets/mechanical_left.svg) - -## Ratings - -### Absolute Maximum Ratings - -| Symbol | Description | Min | Typ | Max | Unit | -| -------------------- | ---------------------------------------- | :---: | :---: | :---: | :---: | -| TMax | Maximum thermal limit1 | -30 | 20 | 85 | °C | -| VBattMax | Maximum input voltage from battery input | 3.2 | 3.7 | 4.3 | V | -| ARelayMax | Maximum current through relay switch | - | - | 2 | A | -| PMax | Maximum Power Consumption | - | - | 5000 | mW | - -## Certifications - -### Declaration of Conformity CE DoC (EU) - -We declare under our sole responsibility that the products above are in conformity with the essential requirements of the following EU Directives and therefore qualify for free movement within markets comprising the European Union (EU) and European Economic Area (EEA). - -### Declaration of Conformity to EU RoHS & REACH 211 01/19/2021 - -Arduino boards are in compliance with RoHS 2 Directive 2011/65/EU of the European Parliament and RoHS 3 Directive 2015/863/EU of the Council of 4 June 2015 on the restriction of the use of certain hazardous substances in electrical and electronic equipment. - -| **Substance** | **Maximum Limit (ppm)** | -| -------------------------------------- | ----------------------- | -| Lead (Pb) | 1000 | -| Cadmium (Cd) | 100 | -| Mercury (Hg) | 1000 | -| Hexavalent Chromium (Cr6+) | 1000 | -| Poly Brominated Biphenyls (PBB) | 1000 | -| Poly Brominated Diphenyl ethers (PBDE) | 1000 | -| Bis(2-Ethylhexyl} phthalate (DEHP) | 1000 | -| Benzyl butyl phthalate (BBP) | 1000 | -| Dibutyl phthalate (DBP) | 1000 | -| Diisobutyl phthalate (DIBP) | 1000 | - -Exemptions : No exemptions are claimed. - -Arduino Boards are fully compliant with the related requirements of European Union Regulation (EC) 1907 /2006 concerning the Registration, Evaluation, Authorization and Restriction of Chemicals (REACH). We declare none of the SVHCs (https://echa.europa.eu/web/guest/candidate-list-table), the Candidate List of Substances of Very High Concern for authorization currently released by ECHA, is present in all products (and also package) in quantities totaling in a concentration equal or above 0.1%. To the best of our knowledge, we also declare that our products do not contain any of the substances listed on the "Authorization List" (Annex XIV of the REACH regulations) and Substances of Very High Concern (SVHC) in any significant amounts as specified by the Annex XVII of Candidate list published by ECHA (European Chemical Agency) 1907 /2006/EC. - -### Conflict Minerals Declaration - -As a global supplier of electronic and electrical components, Arduino is aware of our obligations with regards to laws and regulations regarding Conflict Minerals, specifically the Dodd-Frank Wall Street Reform and Consumer Protection Act, Section 1502. Arduino does not directly source or process conflict minerals such as Tin, Tantalum, Tungsten, or Gold. Conflict minerals are contained in our products in the form of solder, or as a component in metal alloys. As part of our reasonable due diligence Arduino has contacted component suppliers within our supply chain to verify their continued compliance with the regulations. Based on the information received thus far we declare that our products contain Conflict Minerals sourced from conflict-free areas. - -## FCC Caution - -Any Changes or modifications not expressly approved by the party responsible for compliance could void the user’s authority to operate the equipment. - -This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: - -(1) This device may not cause harmful interference - -(2) this device must accept any interference received, including interference that may cause undesired operation. - -**FCC RF Radiation Exposure Statement:** - -1. This Transmitter must not be co-located or operating in conjunction with any other antenna or transmitter. - -2. This equipment complies with RF radiation exposure limits set forth for an uncontrolled environment. - -3. This equipment should be installed and operated with minimum distance 20cm between the radiator & your body. - -**English**: -User manuals for licence-exempt radio apparatus shall contain the following or equivalent notice in a conspicuous location in the user manual or alternatively on the device or both. This device complies with Industry Canada licence-exempt RSS standard(s). Operation is subject to the following two conditions: - -(1) this device may not cause interference - -(2) this device must accept any interference, including interference that may cause undesired operation of the device. - -**French**: -Le présent appareil est conforme aux CNR d’Industrie Canada applicables aux appareils radio exempts de licence. L’exploitation est autorisée aux deux conditions suivantes : - -(1) l’ appareil nedoit pas produire de brouillage - -(2) l’utilisateur de l’appareil doit accepter tout brouillage radioélectrique subi, même si le brouillage est susceptible d’en compromettre le fonctionnement. - -**IC SAR Warning:** - -**English** -This equipment should be installed and operated with minimum distance 20 cm between the radiator and your body. - -**French**: -Lors de l’ installation et de l’ exploitation de ce dispositif, la distance entre le radiateur et le corps est d ’au moins 20 cm. - -**Important:** The operating temperature of the EUT can’t exceed 85℃ and shouldn’t be lower than -40℃. - -Hereby, Arduino S.r.l. declares that this product is in compliance with essential requirements and other relevant provisions of Directive 2014/53/EU. This product is allowed to be used in all EU member states. - -| Frequency bands | Maximum output power (ERP) | -| :-------------: | :------------------------: | -| 863-870Mhz | -3.22dBm | - -## Company Information - -| Company name | Arduino S.r.l. | -| --------------- | ------------------------------------------ | -| Company Address | Via Andrea Appiani,25 20900 MONZA (Italy） | - -## Reference Documentation - -| **Id** | **Ref** | **Link** | -| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------- | -| 1 | Arduino IDE (Desktop) | https://www.arduino.cc/en/Main/Software | -| 2 | Arduino IDE (Cloud) | https://create.arduino.cc/editor | -| 3 | Cloud IDE Getting Started | https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-4b3e4a | -| 4 | Project Hub | https://create.arduino.cc/projecthub?by=part&part_id=11332&sort=trending | -| 5 | Library Reference | https://www.arduino.cc/reference/en/libraries/arduino_mkriotcarrier/ | -| 6 | Online Store | https://store.arduino.cc/mkr-iot-carrier-rev2 | -| 7 | Arduino Documentation | https://docs.arduino.cc/hardware/mkr-iot-carrier-rev2 | - -## Revision History - -| **Date DD/MM/YY** | **Revision** | **Changes** | -| ----------------- | ------------ | ----------------------------------------------------- | -| 20/02/2023 | 3 | Change grove connector power rail from +5.0V to +3.3V | -| 16/01/2023 | 2 | Update Pinout graphic | +--- +identifier: ABX00073 +title: Arduino® MKR IoT Carrier +type: maker +revision: Rev2 +variant: Rev2 +--- + +![](assets/featured.png) + +# Description +The **MKR IoT Carrier Rev2** provides infinite possibilities for IoT projects, including a TFT display to display information, Grove connectors and multiple sensors. + +The integrated sensors, circuits and display leave you free to focus on programming and prototyping your ideas. + +# Target areas: +IoT applications, MKR hobbyists + +# Features + +***Note: This board is passive and requires a MKR board to function.*** + +***Requirements: This device require the library Arduino_MKRIoTCarrier version to be 2.0.0 or later in order to function*** + +* **Grove Connectors** + * Easy interface with wide range of Grove modules and sensors + * 2x analog sensor input + * 1x I2C interface + +* **ST LSM6DSOXTR 6-axis IMU** + * 3D Gyroscope + * ±2/±4/±8/±16 g full scale + * 3D Accelerometer + * ±125/±250/±500/±1000/±2000 dps full scale + * Advanced pedometer, step detector and step counter + * Significant Motion Detection, Tilt detection + * Standard interrupts: free-fall, wake-up, 6D/4D orientation, click and double-click + * Programmable finite state machine: accelerometer, gyroscope and external sensors + * Machine Learning Core + * Embedded temperature sensor + +* **Rounded 1.3” TFT Display** + * 240 x 240 resolution + * 36 x 40 mm + +- **Bosch BME688** Environmental sensing with Artificial Intelligence + - Operating range + - Pressure: 300-1100 hPa + - Humidity: 0-100% + - Temperature: -40 - +85°C + - eNose Gas sensor + - Sensor-to-sensor deviation (IAQ): ± 15% ± 15 IAQ + - Standard scan speed: 10.8 s/scan + - Electric charge for standard scan: 0.18 mAh (5 scans - 1 min) + - Major Sensor outputs + - Index for air quality (IAQ) + - bVOC- & CO2-equivalents (ppm) + - Gas scan result (%) + - Intensity level + +* **Broadcom APDS-9660 RGB and Gesture Sensor** + * Ambient light and RGB Colour Sensing + * Proximity Sensing + * Gesture Detection + * UV/IR Blocking Filter + * I2C interface to Arduino MKR board + +* **Relays** + * 2x KEMET EE2-5NU-L relays + * 5V Coil voltage + * 2A Current + * 220V DC, 250V AC + * Non-latching + * Common, normally open and normally closed contacts + * LED Status Indicator + +* **Peripherals** + * 5x Capacitive buttons + * Buzzer + * 5x Digital RGB LEDs + * Rounded OLED 1,3” Display + * 5x Capacitive qTouch buttons + +* **Memory** + * Micro SD Card + +* **Power** + * Li-ion 18650 3.7 v battery holder + * USB Battery charging via MKR Board (Runs up to 48h with a 3.7v 2500mAh) + +* **I/O** + * All sensors feature wake up function + * 2x Analog Grove connectors + * 1x I2C Grove connector + * 2x relay connector + +* **Safety information** + * Class A + +# Contents + +## The Board + +### Application Examples + +**Light controller:** Control your house lightning with the **MKR IoT Carrier Rev2**, using the RGB light sensor. This feature identifies the general amount of light in a room or environment and adapts. If the board is connected to Wi-Fi®, you can manage and control your device remotely on a smartphone via the IoT Cloud. + +**Light and water controller for greenhouse:** With moisture sensor, pressure sensor and temperature the IoT Carrier can evaluate and recognize the moisture of the soil, depending on air humidity and sun. Through the various sensors, it can reconstruate suitable climate (e.g. tropical) with the help of heaters and relays to increase the humidity. It can also be programmed with a watering system thanks to the relays. + +**Weather station:** With temperature sensor, pressure sensor, humidity sensor and light sensors, you can easily use your IoT carrier as a local weather station. The various sensors can via sensors collect statistics about the different variables required to display weather. + +### Accessories + +***(Not Included)*** +* 18650 Li-ion battery +* [Grove sensors](https://search.arduino.cc/search/?q=Grove%20Sensors&tab=store) +* SD Card + +### Related Products + +* [Arduino® MKR WiFi 1010 (SKU: ABX00023)](https://store.arduino.cc/products/arduino-mkr-wifi-1010) +* [Arduino® MKR Zero (SKU: ABX00012)](https://store.arduino.cc/products/arduino-mkr-zero-i2s-bus-sd-for-sound-music-digital-audio-data) +* [Arduino® MKR WAN 1310 (SKU: MKRWAN1310WANT)](https://store.arduino.cc/products/arduino-mkr-wan-1310) +* [Arduino® MKR GSM 1400 (SKU: MKRGSM1400WANT)](https://store.arduino.cc/products/arduino-mkr-gsm-1400) +* [Arduino® MKR NB 1500 (SKU: MKRNB1500WANT)](https://store.arduino.cc/products/arduino-mkr-nb-1500) + + +## Functional Overview + +### Board Topology + +#### Top View + +![Top view - components](assets/top_view.svg) + +| **Ref.** | **Description** | **Ref.** | **Description** | +| -------- | -------------------------------------- | -------- | ----------------------------------- | +| U1 | LSM6DSOXTR 6-axis IMU IC | U2 | APDS-9660 RGB and Gesture Sensor IC | +| U4 | Bosch BME688 Environmental Sensor IC | L0-L4 | APA1022020-2018 RGB LED IC | +| J6 | FH26W-45S-0.3SHW(60) Display Connector | PB1 | Reset push-button | + + +#### Bottom View + +![Bottom view](assets/bottom_view.svg) + +| **Ref.** | **Description** | **Ref.** | **Description** | +| --------- | ------------------------------------- | -------- | --------------------------------- | +| J2, J3 | Analog Grove Connectors | J4 | I2C Grove Connector | +| J11 | B2B-PH-SM4-TB(LF)(SN) Power Connector | J9, J10 | 1771033 3-pin Relay Connector | +| JDIGITAL1 | MKR Power and Digital Pin Connector | JANALOG1 | MKR AREF and Analog Pin Connector | +| S1, S2 | EE2-5NU-L 2A 250V Mechanical Relay | M1 | Buzzer | +| J1 | Micro SD Module | J7, J8 | Li-Ion 18650 Holder | + +### Power Tree +The **MKR IoT Carrier Rev2** makes use of the power management features of the Arduino MKR boards to power itself as well as to interface with the Li-Ion battery. + +![Power tree](assets/Power_Tree_MKR_IoT_Carrier.png) + +## Board Operation + +### Getting Started - IDE +If you want to program your **MKR IoT Carrier Rev2** while offline you need to install the Arduino Desktop IDE [**[1]**](#10-reference-documentation). To connect the **MKR IoT Carrier Rev2** to your computer, you’ll need a Micro-B USB cable. This also provides power to the board, as indicated by the LED. + +### Getting Started - Arduino Web Editor +All Arduino boards, including this one, work out-of-the-box on the Arduino Web Editor [**[2]**](#10-reference-documentation), by just installing a simple plugin. + +The Arduino Web Editor is hosted online, therefore it will always be up-to-date with the latest features and support for all boards. Follow [**[3]**](#10-reference-documentation) to start coding on the browser and upload your sketches onto your board. + +### Getting Started - Arduino Cloud +All Arduino IoT enabled products are supported on Arduino Cloud which allows you to log, graph and analyze sensor data, trigger events, and automate your home or business. + +### Sample Sketches +Sample sketches for the **MKR IoT Carrier Rev2** can be found either in the “Examples” menu in the Arduino IDE and further documentation can be found in Arduino Documentation [**[7]**](#10-reference-documentation) which also contains links to the troubleshooting articles. + +### Online Resources +Now that you have gone through the basics of what you can do with the board you can explore the endless possibilities it provides by checking exciting projects on ProjectHub [**[4]**](#10-reference-documentation), the Arduino Library Reference [**[5]**](#10-reference-documentation) and the online store [**[6]**](#10-reference-documentation) where you will be able to complement your board with sensors, actuators and more. + +### Board Recovery +All Arduino boards have a built-in bootloader which allows flashing the board via USB. In case a sketch locks up the processor and the board is not reachable anymore via USB it is possible to enter bootloader mode by double-tapping the reset button right after power up. + +## Connector Pinouts + +![Pinout](assets/Pinout.png) + +Detailed information on the pinouts are available in a separate document: [Docs Arduino - MKR IoT Carrier Rev2 pinout](https://docs.arduino.cc/resources/pinouts/ABX00073-full-pinout.pdf) + +### Battery Clips + +| Pin | **Function** | **Type** | **Description** | +| :---: | :----------: | :------: | :------------------------------ | +| 1 | GND | Power | Ground | +| 2 | VBAT | Power | Positive 18650 Battery Terminal | + +### Grove Connectors +#### A0 + +| Pin | **Function** | **Type** | **Description** | +| :---: | :----------: | :------: | ---------------- | +| 1 | AN0 | Analog | Analog Input 0 | +| 2 | NC | NC | Not Connected | +| 3 | +3.3V | Power | +3.3V power rail | +| 4 | GND | Power | Ground | + +#### A6 + +| Pin | **Function** | **Type** | **Description** | +| :---: | :----------: | :------: | ---------------- | +| 1 | AN6 | Analog | Analog Input 6 | +| 2 | NC | NC | Not Connected | +| 3 | +3.3V | Power | +3.3V power rail | +| 4 | GND | Power | Ground | + +#### I2C + +| Pin | **Function** | **Type** | **Description** | +| :---: | :----------: | :------: | ---------------- | +| 1 | SCL | Digital | I2C Clock Signal | +| 2 | SDA | Digital | I2C Data Signal | +| 3 | +3.3V | Power | +3.3V power rail | +| 4 | GND | Power | Ground | + +### Relays +#### Relay 1 and 2 + +* Relay 1 driven by digital pin 1 +* Relay 2 driven by digital pin 2 + + +| Pin | **Function** | **Type** | **Description** | +| :---: | :----------: | :------: | --------------- | +| 1 | NC | Switch | Normally Closed | +| 2 | COM | Switch | Common | +| 3 | NO | Switch | Normally Open | + +## Mechanical Information + +### Board Outline / Mounting Holes + +![Mechanical view](assets/mechanical.svg) + +### Connectors + +![Connectors positioning](assets/connectors.svg) + +### Relays Connectors + +![Left Side Relay positioning](assets/mechanical_left.svg) + +## Ratings + +### Absolute Maximum Ratings + +| Symbol | Description | Min | Typ | Max | Unit | +| -------------------- | ---------------------------------------- | :---: | :---: | :---: | :---: | +| TMax | Maximum thermal limit1 | -30 | 20 | 85 | °C | +| VBattMax | Maximum input voltage from battery input | 3.2 | 3.7 | 4.3 | V | +| ARelayMax | Maximum current through relay switch | - | - | 2 | A | +| PMax | Maximum Power Consumption | - | - | 5000 | mW | + +## Certifications + +### Declaration of Conformity CE DoC (EU) + +We declare under our sole responsibility that the products above are in conformity with the essential requirements of the following EU Directives and therefore qualify for free movement within markets comprising the European Union (EU) and European Economic Area (EEA). + +### Declaration of Conformity to EU RoHS & REACH 211 01/19/2021 + +Arduino boards are in compliance with RoHS 2 Directive 2011/65/EU of the European Parliament and RoHS 3 Directive 2015/863/EU of the Council of 4 June 2015 on the restriction of the use of certain hazardous substances in electrical and electronic equipment. + +| **Substance** | **Maximum Limit (ppm)** | +| -------------------------------------- | ----------------------- | +| Lead (Pb) | 1000 | +| Cadmium (Cd) | 100 | +| Mercury (Hg) | 1000 | +| Hexavalent Chromium (Cr6+) | 1000 | +| Poly Brominated Biphenyls (PBB) | 1000 | +| Poly Brominated Diphenyl ethers (PBDE) | 1000 | +| Bis(2-Ethylhexyl} phthalate (DEHP) | 1000 | +| Benzyl butyl phthalate (BBP) | 1000 | +| Dibutyl phthalate (DBP) | 1000 | +| Diisobutyl phthalate (DIBP) | 1000 | + +Exemptions : No exemptions are claimed. + +Arduino Boards are fully compliant with the related requirements of European Union Regulation (EC) 1907 /2006 concerning the Registration, Evaluation, Authorization and Restriction of Chemicals (REACH). We declare none of the SVHCs (https://echa.europa.eu/web/guest/candidate-list-table), the Candidate List of Substances of Very High Concern for authorization currently released by ECHA, is present in all products (and also package) in quantities totaling in a concentration equal or above 0.1%. To the best of our knowledge, we also declare that our products do not contain any of the substances listed on the "Authorization List" (Annex XIV of the REACH regulations) and Substances of Very High Concern (SVHC) in any significant amounts as specified by the Annex XVII of Candidate list published by ECHA (European Chemical Agency) 1907 /2006/EC. + +### Conflict Minerals Declaration + +As a global supplier of electronic and electrical components, Arduino is aware of our obligations with regards to laws and regulations regarding Conflict Minerals, specifically the Dodd-Frank Wall Street Reform and Consumer Protection Act, Section 1502. Arduino does not directly source or process conflict minerals such as Tin, Tantalum, Tungsten, or Gold. Conflict minerals are contained in our products in the form of solder, or as a component in metal alloys. As part of our reasonable due diligence Arduino has contacted component suppliers within our supply chain to verify their continued compliance with the regulations. Based on the information received thus far we declare that our products contain Conflict Minerals sourced from conflict-free areas. + +## FCC Caution + +Any Changes or modifications not expressly approved by the party responsible for compliance could void the user’s authority to operate the equipment. + +This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: + +(1) This device may not cause harmful interference + +(2) this device must accept any interference received, including interference that may cause undesired operation. + +**FCC RF Radiation Exposure Statement:** + +1. This Transmitter must not be co-located or operating in conjunction with any other antenna or transmitter. + +2. This equipment complies with RF radiation exposure limits set forth for an uncontrolled environment. + +3. This equipment should be installed and operated with minimum distance 20cm between the radiator & your body. + +**English**: +User manuals for licence-exempt radio apparatus shall contain the following or equivalent notice in a conspicuous location in the user manual or alternatively on the device or both. This device complies with Industry Canada licence-exempt RSS standard(s). Operation is subject to the following two conditions: + +(1) this device may not cause interference + +(2) this device must accept any interference, including interference that may cause undesired operation of the device. + +**French**: +Le présent appareil est conforme aux CNR d’Industrie Canada applicables aux appareils radio exempts de licence. L’exploitation est autorisée aux deux conditions suivantes : + +(1) l’ appareil nedoit pas produire de brouillage + +(2) l’utilisateur de l’appareil doit accepter tout brouillage radioélectrique subi, même si le brouillage est susceptible d’en compromettre le fonctionnement. + +**IC SAR Warning:** + +**English** +This equipment should be installed and operated with minimum distance 20 cm between the radiator and your body. + +**French**: +Lors de l’ installation et de l’ exploitation de ce dispositif, la distance entre le radiateur et le corps est d ’au moins 20 cm. + +**Important:** The operating temperature of the EUT can’t exceed 85℃ and shouldn’t be lower than -40℃. + +Hereby, Arduino S.r.l. declares that this product is in compliance with essential requirements and other relevant provisions of Directive 2014/53/EU. This product is allowed to be used in all EU member states. + +| Frequency bands | Maximum output power (ERP) | +| :-------------: | :------------------------: | +| 863-870Mhz | -3.22dBm | + +## Company Information + +| Company name | Arduino S.r.l. | +| --------------- | ------------------------------------------ | +| Company Address | Via Andrea Appiani,25 20900 MONZA (Italy） | + +## Reference Documentation + +| **Id** | **Ref** | **Link** | +| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------------- | +| 1 | Arduino IDE (Desktop) | https://www.arduino.cc/en/Main/Software | +| 2 | Arduino IDE (Cloud) | https://create.arduino.cc/editor | +| 3 | Cloud IDE Getting Started | https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-4b3e4a | +| 4 | Project Hub | https://create.arduino.cc/projecthub?by=part&part_id=11332&sort=trending | +| 5 | Library Reference | https://www.arduino.cc/reference/en/libraries/arduino_mkriotcarrier/ | +| 6 | Online Store | https://store.arduino.cc/mkr-iot-carrier-rev2 | +| 7 | Arduino Documentation | https://docs.arduino.cc/hardware/mkr-iot-carrier-rev2 | + +## Revision History + +| **Date DD/MM/YY** | **Revision** | **Changes** | +| ----------------- | ------------ | ----------------------------------------------------- | +| 20/02/2023 | 3 | Change grove connector power rail from +5.0V to +3.3V | +| 16/01/2023 | 2 | Update Pinout graphic | | 23/11/2022 | 1 | First Release | \ No newline at end of file diff --git a/content/hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2/tutorials/cheat-sheet/cheat-sheet.md b/content/hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2/tutorials/cheat-sheet/cheat-sheet.md index 4ad6bec9f4..95edf91e78 100644 --- a/content/hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2/tutorials/cheat-sheet/cheat-sheet.md +++ b/content/hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2/tutorials/cheat-sheet/cheat-sheet.md @@ -1,553 +1,553 @@ ---- -title: 'MKR IoT Carrier Rev2 Cheat Sheet' -description: 'Learn how to set up the MKR IoT Carrier Rev2, get a quick overview of the compatible boards, components, and the library.' -author: 'Liam Aljundi, Karl Söderby' -tags: - - API - - Installation - - Sensors -libraries: - - name: Arduino MKRIoTCarrier - url: https://www.arduino.cc/reference/en/libraries/arduino_mkriotcarrier/ -hardware: - - hardware/01.mkr/03.carriers/mkr-iot-carrier-rev2 ---- - -![The Arduino MKR IoT Carrier Rev2](assets/hero.png) - -The Arduino® MKR IoT Carrier Rev2 is equipped with different sensors, actuators and with a display to leave you free to focus on prototyping and programming your next IoT projects. The carrier does not come equipped with a microcontroller, meaning it only works in combination with an Arduino board. The MKR IoT Carrier Rev2 comes equipped with 5 RGB LEDs, 5 capacitive touch buttons, a colored display, IMU and a variety of quality sensors. It also features a battery holder for a 18650 Li-Ion battery, SD card holder and Grove connectors. - -## Compatible Boards - -The MKR family of boards share a common pinout, meaning that they can all be easily connected to the MKR IoT Carrier Rev2. Here is a list of the MKR boards: - -- [MKR 1000 WiFi](https://docs.arduino.cc/hardware/mkr-1000-wifi) -- [MKR FOX 1200](https://docs.arduino.cc/hardware/mkr-fox-1200) -- [MKR GSM 1400](https://docs.arduino.cc/hardware/mkr-gsm-1400) -- [MKR NB 1500](https://docs.arduino.cc/hardware/mkr-nb-1500) -- [MKR Vidor 4000](https://docs.arduino.cc/hardware/mkr-vidor-4000) -- [MKR WAN 1300](https://docs.arduino.cc/hardware/mkr-wan-1300) -- [MKR WAN 1310](https://docs.arduino.cc/hardware/mkr-wan-1310) -- [MKR WiFi 1010](https://docs.arduino.cc/hardware/mkr-wifi-1010) -- [MKR Zero](https://docs.arduino.cc/hardware/mkr-zero) - -The MKR family boards offer different features that can be useful for your projects. You can [browse through the boards](https://store.arduino.cc/collections/mkr-family) and pick the one that is most compatible for your project. - -### Assembly - -The chosen Arduino MKR board needs to be mounted on top of the MKR IoT Carrier Rev2 and connected to a computer. The board can be connected as shown in the image below, matching the pin numbers on the board to the ones on the carrier. - -![Mounting board on the MKR IoT Carrier Rev2](assets/mkr-mount.png) - -## Datasheet - -The full datasheet is available as a downloadable PDF from the link below: - -- [Download the Arduino MKR IoT Carrier Rev2 datasheet](https://docs.arduino.cc/resources/datasheets/ABX00073-datasheet.pdf) - -## Arduino IoT Cloud - -The MKR IoT Carrier Rev2 can be controlled through the [Arduino IoT Cloud](https://create.arduino.cc/iot/things), a cloud service that allows us to create IoT applications in just minutes, if combined with an Arduino IoT Cloud compatible board. Here's a list of the Arduino MKR family boards that are compatible with the Arduino IoT Cloud: - -- [MKR 1000 WiFi](https://docs.arduino.cc/hardware/mkr-1000-wifi) -- [MKR GSM 1400](https://docs.arduino.cc/hardware/mkr-gsm-1400) -- [MKR NB 1500](https://docs.arduino.cc/hardware/mkr-nb-1500) -- [MKR WAN 1300](https://docs.arduino.cc/hardware/mkr-wan-1300) -- [MKR WAN 1310](https://docs.arduino.cc/hardware/mkr-wan-1310) -- [MKR WiFi 1010](https://docs.arduino.cc/hardware/mkr-wifi-1010) - -***Note: The MKR GSM 1400 and MKR NB 1500 require a SIM card to connect to the Cloud, as they communicate over the mobile networks. The MKR WAN 1300 and 1310 board requires a Arduino PRO Gateway LoRa® to connect to the cloud.*** - -If you need help to get started, you can go through the [Arduino IoT Cloud tutorial](https://docs.arduino.cc/cloud/iot-cloud/tutorials/iot-cloud-getting-started). - -## Pinout - -![The pinout for MKR IoT Carrier Rev2](assets/mkrIoTCarrier-pinout.png) - -The full pinout is available in the [resources section](/hardware/mkr-iot-carrier-rev2#resources). - -## Grove Connectors - -![Grove connectors on the MKR IoT Carrier Rev2](assets/grove-connector.png) - -The MKR IoT Carrier Rev2 comes with **three grove connectors** (2 analog and 1 I2C) that enables us to easily connect external sensors. The type of the connector is labeled clearly on the back of the carrier. - -## Carrier Library - -To program the MKR IoT Carrier Rev2, the **[Arduino_MKRIoTCarrier](https://www.arduino.cc/reference/en/libraries/arduino_mkriotcarrier/)** library needs to be included. This library allows us to control and read all the components of the MKR IoT Carrier Rev2. Setting up the **Arduino_MKRIoTCarrier** library requires an addition of few code lines in the **initialization** and **setup**. Practically speaking, the code used in the initialization and setup is rarely changed, and it is required in every sketch. - -### Initialization - -In the initialization (the very top) of every sketch, the **Arduino_MKRIoTCarrier** library needs to be included, which includes the individual libraries of the components mounted onto the carrier. - -Next, an object of type `MKRIoTCarrier` needs to be created. We'll call it `carrier` for simplicity. - -```arduino -#include -MKRIoTCarrier carrier; -``` - -### Setup - -Inside the `setup()` of every sketch that created, 2 lines of code needs to added. - -First, we need to tell the library whether the carrier is being used inside the **plastic enclosure** included in the Oplà IoT Kit or not. The library uses this information in order to calibrate the sensitivity of the capacitive buttons. - -If you use the plastic enclosure, add this line: - -``` -carrier.withCase(); -``` - -Otherwise, add this line: - -``` -carrier.noCase(); -``` - -After that, the `carrier.begin();` command is needed. Final example is: - -```arduino -void setup() { - carrier.noCase(); - carrier.begin(); -} -``` - -## BME688 Environmental Sensor - -![The BME688 Humidity Sensor on the MKR IoT Carrier Rev2](assets/bme-688.png) - -The **[BME688 Environmental Sensor](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bme688-ds000.pdf)** is a 4 in 1 sensor capable of providing the following measurements: -- **Humidity**, 0‒100% r.H. -- **Temperature**, -40 to +85 °C. -- **Pressure**, 300-1100 hPa. -- **Gas**, IAQ, VOC, CO2. - -BME688 is a low-power sensor with current consumption as low as **2.1 µA at 1 Hz**. It communicates over the I²C bus as other sensors onboard this carrier. - -### Code - -The values from the **temperature, humidity & pressure** can be retrieved and stored in **float** variables as shown below. For this, we need to use the `Env` class. - -```arduino -float temperature = carrier.Env.readTemperature(); -float temperature = carrier.Env.readTemperature(FAHRENHEIT); -float humidity = carrier.Env.readHumidity(); -float pressure = carrier.Env.readPressure(); //returns value in kPa -``` - -***Temperature is returned in degrees Celsius, while relative humidity is returned in percentage.*** - -To access **gas** various values, we need to use the `AirQuality` class. - -```arduino -float gasResistor = carrier.AirQuality.readGasResistor(); -float volatileOrganicCompounds = carrier.AirQuality.readVOC(); -float co2 = carrier.AirQuality.readCO2(); -``` - -## IMU Accelerometer & Gyroscope Sensors - -The IMU (Inertial Measurement Unit) used on the MKR IoT Carrier Rev2 is the located **behind the display**. - -### LSM6DSOX - -The [LSM6DSOX](https://www.st.com/resource/en/datasheet/lsm6dsox.pdf) from STM is an IMU (Inertial Measurement Unit) that features a 3D digital **accelerometer** and a 3D digital **gyroscope**. - -### Code - -The 3-axis values from the **accelerometer** and **gyroscope** sensors can be retrieved and stored in **float** variables as shown below: - -```arduino -float x, y, z; - -void loop(){ - if (carrier.IMUmodule.accelerationAvailable()) - { - carrier.IMUmodule.readAcceleration(x, y, z); - Serial.println(x); - } -} - -``` - -The following methods can be used to detect movement: - -```arduino -carrier.IMUmodule.accelerationAvailable(); -``` - -Returns 0 if no new acceleration data sample is available, 1 if new acceleration data sample is available. - -```arduino -carrier.IMUmodule.readAcceleration(x, y, z); -``` - -Reads acceleration data from the sensor on the three axis and assigns it to the provided variables. - -The underlying library used to read the sensor is **[LSM6DSOX](https://github.com/arduino-libraries/Arduino_LSM6DSOX)**. - -## RGB and Gesture Sensor - -![The APDS-9960 sensor on the MKR IoT Carrier Rev2](assets/apds-9960.png) - -The MKR IoT Carrier Rev2 contains a Broadcom **APDS-9960 RGB and Gesture sensors**, situated under the display and marked with a bulb icon. The sensor is useful for **ambient light** and **RGB** color sensing, **proximity** sensing, and **gesture** detection. - -### Code - -The color values from the **RGB** sensor can be retrieved and stored in **int** variables as shown below. - -The `carrier.Light.readColor(r, g, b);` method can be used to detect colors. - -The if statement `if (r >= 135 && g >= 135 && b >= 135)` in the code below checks if the color detected ranges from light gray to white, but the numbers assigned to red (r), green (g) and blue (b) can be customized to any desired color. - -```arduino - int r, g, b; - - void loop(){ - - if (carrier.Light.colorAvailable()){ - carrier.Light.readColor(r, g, b); //read rgb color values - - // check if color/light is bright enough - if (r >= 135 && g >= 135 && b >= 135){ - Serial.print("White color detected"); - } - } - } - -``` - -The following methods can be used to detect gesture: - -```arduino -carrier.Light.gestureAvailable(); -``` - -Checks the availability of the **gesture** sensor. - -```arduino -carrier.Light.readGesture(); -``` - -Confirms which gesture is being detected, and **returns** UP, DOWN, RIGHT or LEFT. - -The code example below shows the gesture value in a fixed width integer `uint8_t` variable, and the if statement checks `if (gesture == UP)`. To detect movements in other directions, UP can be replaced with DOWN, RIGHT or LEFT. - -```arduino - - void loop(){ - - if (carrier.Light.gestureAvailable()) - { - uint8_t gesture = carrier.Light.readGesture(); // a variable to store the type of gesture read by the light sensor - Serial.print("Gesture: "); - - // when gesture is UP - if (gesture == UP) - { - Serial.println("UP"); - } - } - -``` - -The underlying library used to read the sensor is **[Arduino_APDS9960](https://www.arduino.cc/reference/en/libraries/arduino_apds9960/)**. - -## Relays - -![The relays on the MKR IoT Carrier Rev2](assets/relay-specs.png) - -The MKR IoT Carrier Rev2 is equipped with two 5V Coil voltage **KEMET EE2-5NU-L relays**, located on the back side of the carrier. The relays are non-latching with a **COM** (common), **NO** (Normally open) and **NC** (normally closed) contacts, and can take up a max of **2A** Current and **24 V** of input each. - -The connections between a high power circuit and the relays will be done through these connectors (marked **"high power pins"** in the image above). - -Once the cables are introduced inside the connectors, they will automatically be locked inside. To unlock a cable and remove it from the connector, a tool is needed to be inserted through the top square hole (it can be a flat screwdriver, a hard piece of plastic, etc.). - -![The L1 and L2 LEDs indicators](assets/relay-lights.png) - -The **L1 and L2 LEDs** on the carrier are visual indicators of the state of the relays. If the LED is ON, it means that the **COM** and the **NO** terminal of the relay are **connected**, and if the LED is OFF it means that **COM** and **NC** are **connected**. - -### Code - -The `carrier.RelayX.open();` and `carrier.RelayX.close();` methods can be used to control the relays, and `carrier.RelayX.getStatus();` to read the status of the relays. - -Swap to the Normally Open (NO) circuit of relay 1 (turns it on): - -```arduino -carrier.Relay1.open(); -``` - -Swap to the Normally Closed (NC) circuit of relay 2 (turns it off), default mode on power off: - -```arduino -carrier.Relay2.close(); -``` - - -Bool, returns the status LOW means NC and HIGH means NO: - -```arduino -carrier.Relay2.getStatus(); -``` - -## Peripherals - -### Display - -![The MKR IoT Carrier Rev2's display](assets/display.png) - -The screen on the MKR IoT Carrier Rev2 is a **rounded 1.3” TFT display**, with a 240 x 240 resolution and a diameter of 36 x 40 mm. - -#### Code - -The display is controlled through the `carrier.display` object which is an instance of the **Adafruit_ST7789** class, based on the more general **Adafruit_GFX** interface. Most tutorials mentioning **Adafruit_GFX** should be usable on your MKR IoT Carrier Rev2. - -To get started, check the [Adafruit_GFX documentation](https://learn.adafruit.com/adafruit-gfx-graphics-library) and see the examples included in the Arduino_MKTIoTCarrier library. - - - -](https://www.arduino.cc/reference/en/libraries/adafruit-st7735-and-st7789-library/), which is included in the carrier's library, meaning that it does not need to be added it separately. - -We'll list here some of the most useful methods to configure the MKR IoT Carrier Rev2's display, including basic configurations, background and text colors, font size, position of the cursor and a loading animation. - -```arduino -carrier.display.fillScreen(color); -``` - -This method sets the color of the background of the display using hex codes. Example values are: - -* `0xFFFF` for white -* `0x0000` for black -* `0xF800` for red -* `0x07E0` for green -* `0x001F` for blue -* `0x07FF` for cyan -* `0xF81F` for magenta -* `0xFFE0` for yellow -* `0xFC00` for orange - -```arduino -carrier.display.setRotation(0); -``` - -This method sets the angle of the screen. 0 is the starting position with no rotation.The screen can only be rotated 90, 180 or 270 degrees by replacing the 0 with 1, 2 or 3. - -```arduino -carrier.display.drawBitmap(x, y, bitmap_visual, w, h, color); -``` - -This method displays a bitmap visual on the carrier's screen. The values x & y values are the top left coordinates where the visual is drawn, w & h are the width and height of the visual. The data for the bitmap_visual graphic can be stored as a byte array and used as the `bitmap_visual`. - -```arduino -carrier.display.setTextColor(color); -``` - -This method sets the color of the text using hex codes. - -```arduino -carrier.display.setTextSize(number); -``` - -This method sets the text size. 2 is an average text size since it is visible, but not too small, 3 is a bit larger. - -```arduino -carrier.display.setCursor(x, y); -``` - -This method is very important, as it indicates where on the printing starts on the display. It is indicated by pixels, so, if **0, 0** are used for example, it will start printing in the top left corner. - -```arduino -display.print("text"); -``` - -This method will print the text inside the string at the current cursor position. - -#### More Resources - -In order to develop a graphical user interface with the MKR IoT Carrier Rev2, the **[Arduino_OplaUI](https://www.arduino.cc/reference/en/libraries/arduino_oplaui/)** library can be used. This library uses the color LEDs, the buzzer and the touch buttons to build an interactive user interface featuring multiple pages. It also includes a few predefined gauges to display values. See the library examples to get started. - -### Buttons - -![The MKR IoT Carrier Rev2's buttons](assets/buttons.png) - -The carrier has five **capacitive touch buttons** on its top side, numbered from 0 to 4. The buttons are sensitive to direct touch and can also detect wireless touch. - -#### Code - -```arduino -carrier.Buttons.update(); -``` - -Reads the state of the pads and save them to be used in the different types of touch events. - -```arduino -carrier.Buttons.getTouch(TOUCH0); -``` - -Get if the pad is getting touched, true until it gets released. - -```arduino -carrier.Buttons.onTouchDown(TOUCH0); -``` - -Get when have been a touch down. - -```arduino -carrier.Buttons.onTouchUp(TOUCH0); -``` - -Get when the button has been released. - -```arduino -carrier.Buttons.onTouchChange(TOUCH0); -``` - -Get both, touched and released. - -Replace `TOUCH0` with `TOUCH1`, `TOUCH2`, `TOUCH3`, `TOUCH4` in the examples above to access the other buttons. The code example below shows how the status of a button can be checked. - -```arduino - - void loop(){ - // updates buttons status - carrier.Buttons.update(); - - // Checks if button 00 is touched - if (carrier.Buttons.onTouchDown(TOUCH0)) - { - Serial.print("Button 0 pressed down"); - } - } - -``` - -### LEDs - -![The LEDs on the MKR IoT Carrier Rev2](assets/mkrIotCarrier-leds.png) - -The MKR IoT Carrier Rev2 comes with 5 **digital RGB LEDs** placed on the top side of the carrier in front of the buttons. - -#### Code - -The LEDs are controlled with the Adafruit’s DotStar library, which is included in the `MKRIoTCarrier` library. - -The `carrier.leds.show();` method is necessary for updating the new state of the LEDs and needs to be called after any change of the state of the LEDs (turning on & off or change of color). - -Here are some of the useful methods used to control the LEDs on the MKR IoT Carrier Rev2: - -```arduino -carrier.leds.setPixelColor(index, red, green, blue); -``` - -Sets the color of the index’s LED. - -```arduino -carrier.leds.setBrightness(255); -``` - -Set the overall brightness, from 0 (no brightness) to 255 (maximum brightness). - -```arduino -carrier.leds.clear(); -``` - -Clear the buffer of the LEDs. - -```arduino -carrier.leds.fill(color, firstLedToCount, count); -``` - -Fill X amount of the LEDs with the same color. - -```arduino -uint32_t myColor = carrier.leds.Color(red, green, blue) -``` - -Saves a custom color. - -The code example below shows how to light up all 5 LEDs with our customized color. - -```arduino - -#include -MKRIoTCarrier carrier; - -uint32_t myCustomColor = carrier.leds.Color(255,100,50); - -void setup() { - carrier.noCase(); - carrier.begin(); - carrier.leds.fill(myCustomColor, 0, 5); - carrier.leds.show(); -} - -``` - -### Buzzer - -![The buzzer on the MKR IoT Carrier Rev2](assets/buzzer.png) - -The MKR IoT Carrier Rev2 is equipped with a **sound buzzer** on the bottom side of the carrier, under the MKR board. - -#### Code - -The buzzer can be controlled with the following methods: - -```arduino -carrier.Buzzer.sound(freq); -``` - -Equivalent to tone(), it will make the tone with the selected frequency. - -```arduino -carrier.Buzzer.noSound(); -``` - -Equivalent to noTone(), it will stop the tone signal. - -```arduino -carrier.Buzzer.beep(); -carrier.Buzzer.beep(800, 20); -``` - -This method is a handy shortcut generating a beep. The two arguments are optional and can be set to customize the frequency and the duration (in milliseconds); - -## Memory - -The MKR IoT Carrier Rev2 contains a **SD card slot** that accepts a Micro SD. - -### Code - -The memory can be used with the SD library commands that is already included in the `MKRIoTCarrier` library. - -The SD class initialized in the main `carrier.begin()` so you don't need to do it yourself. The code below demonstrates how to save data on a file on a SD card. - -```arduino -#include -MKRIoTCarrier carrier; - -File myFile; - -void setup() { - carrier.noCase(); - carrier.begin(); //SD card initialized here - - myFile = SD.open("test.txt", FILE_WRITE); -} -``` - -In order to learn more, check any of the many tutorials about using the `SD` library on Arduino. - -## Power - -![JST battery connector on the MKR IoT Carrier Rev2.](assets/battery-connector.png) - -The MKR IoT Carrier Rev2 can be either powered through a USB cable connected to the mounted MKR board, or through a battery. The battery used should be a LI-ION 18650 3.7v battery, which can be mounted to the carrier via the battery holder on the bottom side. - -In order to use the USB power to charge the battery, a little cable with JST connectors on both ends is needed between the MKR IoT Carrier Rev2 and the MKR board. The battery can then be recharged via a USB connection through the MKR Board (runs up to 48h with a 3.7v 2500mAh). - -