Skip to content

Commit 41d60bb

Browse files
zfieldszfields
committed
feat: ArduinoIoTCloudNotecard
1 parent cb933c6 commit 41d60bb

18 files changed

+931
-51
lines changed

‎.github/workflows/compile-examples.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,13 @@ jobs:
2626
- name: Arduino_DebugUtils
2727
- name: ArduinoMqttClient
2828
- name: Arduino_SecureElement
29+
- name: Blues Wireless Notecard
2930
# sketch paths to compile (recursive) for all boards
3031
UNIVERSAL_SKETCH_PATHS: |
3132
- examples/ArduinoIoTCloud-Advanced
3233
- examples/ArduinoIoTCloud-Basic
3334
- examples/ArduinoIoTCloud-Callbacks
35+
- examples/ArduinoIoTCloud-Notecard
3436
- examples/ArduinoIoTCloud-Schedule
3537
- examples/utility/ArduinoIoTCloud_Travis_CI
3638
SKETCHES_REPORTS_PATH: sketches-reports

‎README.md

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,18 @@
88
[![codecov](https://codecov.io/gh/arduino-libraries/ArduinoIoTCloud/branch/master/graph/badge.svg)](https://codecov.io/gh/arduino-libraries/ArduinoIoTCloud)
99

1010
### What?
11+
1112
The `ArduinoIoTCloud` library is the central element of the firmware enabling certain Arduino boards to connect to the [Arduino IoT Cloud](https://www.arduino.cc/en/IoT/HomePage). The following boards are supported:
1213

1314
* **WiFi**: [`MKR 1000`](https://store.arduino.cc/arduino-mkr1000-wifi), [`MKR WiFi 1010`](https://store.arduino.cc/arduino-mkr-wifi-1010), [`Nano 33 IoT`](https://store.arduino.cc/arduino-nano-33-iot), [`Portenta H7`](https://store.arduino.cc/portenta-h7), [`Nano RP2040 Connect`](https://store.arduino.cc/products/arduino-nano-rp2040-connect), [`Nicla Vision`](https://store.arduino.cc/products/nicla-vision), [`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi), [`GIGA R1 WiFi`](https://store.arduino.cc/products/giga-r1-wifi), [`Portenta C33`](https://store.arduino.cc/products/portenta-c33), [`UNO R4 WiFi`](https://store.arduino.cc/products/uno-r4-wifi), [`Nano ESP32`](https://store.arduino.cc/products/nano-esp32), [`ESP8266`](https://github.com/esp8266/Arduino/releases/tag/2.5.0), [`ESP32`](https://github.com/espressif/arduino-esp32/releases/tag/2.0.5)
1415
* **GSM**: [`MKR GSM 1400`](https://store.arduino.cc/arduino-mkr-gsm-1400-1415)
1516
* **5G**: [`MKR NB 1500`](https://store.arduino.cc/arduino-mkr-nb-1500-1413)
1617
* **LoRa**: [`MKR WAN 1300/1310`](https://store.arduino.cc/mkr-wan-1310)
1718
* **Ethernet**: [`Portenta H7`](https://store.arduino.cc/products/portenta-h7) + [`Vision Shield Ethernet`](https://store.arduino.cc/products/arduino-portenta-vision-shield-ethernet), [`Max Carrier`](https://store.arduino.cc/products/portenta-max-carrier), [`Breakout`](https://store.arduino.cc/products/arduino-portenta-breakout), [`Portenta Machine Control`](https://store.arduino.cc/products/arduino-portenta-machine-control), [`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi), [`OPTA RS485`](https://store.arduino.cc/products/opta-rs485), [`OPTA Lite`](https://store.arduino.cc/products/opta-lite), [`Portenta C33`](https://store.arduino.cc/products/portenta-c33) + [`Vision Shield Ethernet`](https://store.arduino.cc/products/arduino-portenta-vision-shield-ethernet)
19+
* **Notecard**: [Provides Cellular/LoRa/Satellite/Wi-Fi to any modern board/architecture](examples/ArduinoIoTCloud-Notecard/README.md)
1820

1921
### How?
22+
2023
1) Register your Arduino IoT Cloud capable board via [Arduino IoT Cloud](https://create.arduino.cc/iot) (Devices Section).
2124
2) Create a new logical representation known as a [Thing](https://create.arduino.cc/iot/things).
2225

@@ -29,7 +32,9 @@ The `ArduinoIoTCloud` library is the central element of the firmware enabling ce
2932
- **Properties**: Qualities defining the characteristics of a system. A _Property_ can be defined as *read-only* (`READ`) to indicate that Arduino IoT Cloud can read the data, but cannot change the value of such _Property_. On the other end, it may be designated to be **read-and-write** (`READWRITE`), allowing Arduino IoT Cloud to remotely change the property’s value and trigger an event notification on the device. It is also possible to mark properties as *write-only* (`WRITE`) which means the cloud can write to this property but not read its value (this limits data transmission for properties which are used to trigger events only).
3033

3134
### How-to-use
35+
3236
* `thingProperties.h`
37+
3338
```C++
3439
void onLedChange();
3540
/* ... */
@@ -46,6 +51,7 @@ WiFiConnectionHandler ArduinoIoTPreferredConnection("SECRET_SSID", "SECRET_PASS"
4651
```
4752
4853
* `MyCloudApplication.ino`
54+
4955
```C++
5056
#include "thingProperties.h"
5157
@@ -69,31 +75,36 @@ void onLedChange() {
6975
```
7076

7177
### FAQ
78+
7279
#### Watchdog
73-
The [1.0.0](https://github.com/arduino-libraries/ArduinoIoTCloud/releases/tag/1.0.0) release of this library adds watchdog functionality to all ATSAMD21G18 based cloud connected boards. A watchdog is simply an electronic timer counting down from a preset start value which, upon reaching zero, triggers a reset of the microcontroller. It can be used to automatically recover from temporary hardware faults or unrecoverable software errors. In order to avoid the watchdog from reaching zero the countdown timer needs to be regularly re-set to its start value. This is happening within `ArduinoCloud.update()` which is periodically called at the start of the `loop()` function. Although the watchdog is automatically enabled it can be disabled by setting the second parameter of `ArduinoCloud.begin(...)` to `false`:
80+
81+
The [1.0.0](https://github.com/arduino-libraries/ArduinoIoTCloud/releases/tag/1.0.0) release of this library adds watchdog functionality to all ATSAMD21G18 based cloud connected boards. A watchdog is simply an electronic timer counting down from a preset start value which, upon reaching zero, triggers a reset of the microcontroller. It can be used to automatically recover from temporary hardware faults or unrecoverable software errors. In order to avoid the watchdog from reaching zero the countdown timer needs to be regularly re-set to its start value. This is happening within `ArduinoCloud.update()` which is periodically called at the start of the `loop()` function. Although the watchdog is automatically enabled it can be disabled by setting the second parameter of `ArduinoCloud.begin(...)` to `false`:
82+
7483
```C++
7584
ArduinoCloud.begin(ArduinoIoTPreferredConnection, false).
7685
```
7786

7887
Whatchdog is enabled by default using the following boards: [`MKR 1000`](https://store.arduino.cc/arduino-mkr1000-wifi), [`MKR WiFi 1010`](https://store.arduino.cc/arduino-mkr-wifi-1010), [`MKR GSM 1400`](https://store.arduino.cc/arduino-mkr-gsm-1400-1415), [`MKR NB 1500`](https://store.arduino.cc/arduino-mkr-nb-1500-1413), [`MKR WAN 1300/1310`](https://store.arduino.cc/mkr-wan-1310), [`Nano 33 IoT`](https://store.arduino.cc/arduino-nano-33-iot), [`Portenta H7`](https://store.arduino.cc/portenta-h7), [`Nano RP2040 Connect`](https://store.arduino.cc/products/arduino-nano-rp2040-connect), [`Nicla Vision`](https://store.arduino.cc/products/nicla-vision), [`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi), [`OPTA RS485`](https://store.arduino.cc/products/opta-rs485), [`OPTA Lite`](https://store.arduino.cc/products/opta-lite), [`GIGA R1 WiFi`](https://store.arduino.cc/products/giga-r1-wifi)
7988

8089
#### Device can not subscribe to `THING_ID`
90+
8191
```
8292
ArduinoIoTCloudTCP::handle_SubscribeMqttTopics could not subscribe to /a/t/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/e/i
8393
```
94+
8495
In this case either the device has not been associated with the thing within the Arduino IoT Cloud GUI configuration or there's a typo in the thing ID.
8596

8697
#### OTA
98+
8799
OTA is supported by the following boards:
88100
[`MKR WiFi 1010`](https://store.arduino.cc/arduino-mkr-wifi-1010), [`Nano 33 IoT`](https://store.arduino.cc/arduino-nano-33-iot), [`Portenta H7`](https://store.arduino.cc/portenta-h7), [`Nano RP2040 Connect`](https://store.arduino.cc/products/arduino-nano-rp2040-connect), [`Nicla Vision`](https://store.arduino.cc/products/nicla-vision), [`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi), [`OPTA RS485`](https://store.arduino.cc/products/opta-rs485), [`OPTA Lite`](https://store.arduino.cc/products/opta-lite), [`GIGA R1 WiFi`](https://store.arduino.cc/products/giga-r1-wifi), [`Nano ESP32`](https://store.arduino.cc/products/nano-esp32), [`ESP32`](https://github.com/espressif/arduino-esp32/releases/tag/2.0.5)
89101

90102
#### Authentication
103+
91104
Boards can authenticate to the ArduinoIoTCloud servers using 3 methods:
92105

93106
* `DEVICE_LOGIN_NAME` and `DEVICE_KEY`. This values are defined in the `thingProperties.h` file and included in the Sketch. Boards that are using this method are: [`UNO R4 WiFi`](https://store.arduino.cc/products/uno-r4-wifi), [`Nano ESP32`](https://store.arduino.cc/products/nano-esp32), [`ESP8266`](https://github.com/esp8266/Arduino/releases/tag/2.5.0), [`ESP32`](https://github.com/espressif/arduino-esp32/releases/tag/2.0.5)
94107

95108
* `DEVICE_CERTIFICATE` and `PRIVATE_KEY`. This values are stored inside the board secure element during the device provisioning phase. Boards that are using this method are: [`MKR 1000`](https://store.arduino.cc/arduino-mkr1000-wifi), [`MKR WiFi 1010`](https://store.arduino.cc/arduino-mkr-wifi-1010), [`MKR GSM 1400`](https://store.arduino.cc/arduino-mkr-gsm-1400-1415), [`MKR NB 1500`](https://store.arduino.cc/arduino-mkr-nb-1500-1413), [`Nano 33 IoT`](https://store.arduino.cc/arduino-nano-33-iot), [`Portenta H7`](https://store.arduino.cc/portenta-h7), [`Nano RP2040 Connect`](https://store.arduino.cc/products/arduino-nano-rp2040-connect), [`Nicla Vision`](https://store.arduino.cc/products/nicla-vision), [`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi), [`OPTA RS485`](https://store.arduino.cc/products/opta-rs485), [`OPTA Lite`](https://store.arduino.cc/products/opta-lite), [`GIGA R1 WiFi`](https://store.arduino.cc/products/giga-r1-wifi), [`Portenta C33`](https://store.arduino.cc/products/portenta-c33)
96109

97110
* `APP_EUI` and `APP_KEY`. This values are defined in the `thingProperties.h` file and included in the Sketch. Boards that are using this method are: [`MKR WAN 1300/1310`](https://store.arduino.cc/mkr-wan-1310)
98-
99-

‎examples/ArduinoIoTCloud-Notecard/ArduinoIoTCloud-Notecard.ino

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
/*
2+
This sketch demonstrates how to exchange data between your board and the
3+
Arduino IoT Cloud, while using the Notecard for wireless communication.
4+
5+
* Connect a potentiometer (or other analog sensor) to A0.
6+
* When the potentiometer (or sensor) value changes the data is sent to the Cloud.
7+
* When you flip the switch in the Cloud dashboard the onboard LED lights gets turned ON or OFF.
8+
9+
IMPORTANT:
10+
This sketch works with any Wi-Fi, Cellular, LoRa or Satellite enabled Notecard.
11+
12+
The full list of compatible boards can be found here:
13+
- https://github.com/arduino-libraries/ArduinoIoTCloud#what
14+
*/
15+
16+
#include <Notecard.h>
17+
#include "thingProperties.h"
18+
19+
#if !defined(LED_BUILTIN) && !defined(ARDUINO_NANO_ESP32)
20+
static int const LED_BUILTIN = 2;
21+
#endif
22+
23+
/*
24+
* Choose an interrupt capable pin to reduce polling and improve
25+
* the overall responsiveness of the ArduinoIoTCloud library
26+
*/
27+
// #define ATTN_PIN 9
28+
29+
void setup() {
30+
/* Initialize serial and wait up to 5 seconds for port to open */
31+
Serial.begin(9600);
32+
for(unsigned long const serialBeginTime = millis(); !Serial && (millis() - serialBeginTime <= 5000); ) { }
33+
34+
/* Set the debug message level:
35+
* - DBG_ERROR: Only show error messages
36+
* - DBG_WARNING: Show warning and error messages
37+
* - DBG_INFO: Show info, warning, and error messages
38+
* - DBG_DEBUG: Show debug, info, warning, and error messages
39+
* - DBG_VERBOSE: Show all messages
40+
*/
41+
setDebugMessageLevel(DBG_INFO);
42+
43+
/* Configure LED pin as an output */
44+
pinMode(LED_BUILTIN, OUTPUT);
45+
46+
/* This function takes care of connecting your sketch variables to the ArduinoIoTCloud object */
47+
initProperties();
48+
49+
/* Initialize Arduino IoT Cloud library */
50+
#ifndef ATTN_PIN
51+
ArduinoCloud.begin(ArduinoIoTPreferredConnection);
52+
ArduinoCloud.setNotecardPollingInterval(3000); // default: 1000ms, min: 250ms
53+
#else
54+
ArduinoCloud.begin(ArduinoIoTPreferredConnection, ATTN_PIN);
55+
#endif
56+
57+
ArduinoCloud.printDebugInfo();
58+
}
59+
60+
void loop() {
61+
ArduinoCloud.update();
62+
potentiometer = analogRead(A0);
63+
seconds = millis() / 1000;
64+
}
65+
66+
/*
67+
* 'onLedChange' is called when the "led" property of your Thing changes
68+
*/
69+
void onLedChange() {
70+
Serial.print("LED set to ");
71+
Serial.println(led);
72+
digitalWrite(LED_BUILTIN, led);
73+
}

‎examples/ArduinoIoTCloud-Notecard/README.md

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
Notecard Connectivity
2+
=====================
3+
4+
The Notecard is a wireless, secure abstraction for device connectivity, that can
5+
be used to enable _ANY*_ device with I2C, or UART, to connect to the Arduino IoT
6+
Cloud via cellular, LoRa, satellite or Wi-Fi!
7+
8+
As a result, your existing device architecture can now have first class support
9+
in the Arduino IoT Cloud, by using a Notecard as a secure communication channel.
10+
11+
> \*_While any device with I2C/UART may use the Notecard, the Arduino IoT Cloud
12+
> library is not supported by the AVR toolchain. Therefore, devices based on the
13+
> AVR architecture cannot access the Arduino IoT Cloud via the Notecard._
14+
>
15+
> _However, any device (including AVR), may use the Notecard library to send data
16+
> to Notehub, then that data may be routed to any endpoint of your choosing. See the
17+
> [Notecard Routing Guide](https://dev.blues.io/guides-and-tutorials/routing-data-to-cloud)
18+
> for more information..._
19+
20+
Wireless Connectivity Options
21+
-----------------------------
22+
23+
- [Cellular](https://shop.blues.com/collections/notecard/products/notecard-cellular)
24+
- [Cellular + Wi-Fi](https://shop.blues.com/collections/notecard/products/notecard-cell-wifi)
25+
- [Wi-Fi](https://shop.blues.com/collections/notecard/products/wifi-notecard)
26+
- [LoRa](https://shop.blues.com/collections/notecard/products/notecard-lora)
27+
- [Satellite](https://shop.blues.com/products/starnote)
28+
29+
How it Works
30+
------------
31+
32+
**Architecture Diagram:**
33+
34+
```
35+
-------- ------------ ----------- -----------
36+
| | | | | | | |
37+
| Host | | | Secure | | | Arduino |
38+
| MCU |---<I2C/UART>---| Notecard | ( ( Wireless ) ) | Notehub |---<TLS>---| IoT |
39+
| | | | Protocol | | | Cloud |
40+
|______| |__________| |_________| |_________|
41+
```
42+
43+
Getting Started
44+
---------------
45+
46+
### Setup a Notehub Account
47+
48+
Using the Notecard only requires a couple of easy steps:
49+
50+
1. [Purchase a Notecard](https://shop.blues.com/collections/notecard) (and
51+
[Notecarrier](https://shop.blues.com/collections/notecarrier)) that fits the
52+
needs of your device.
53+
> _**NOTE:** We recommend starting with our [Dev Kit](https://shop.blues.com/products/blues-global-starter-kit)
54+
> if you are unsure._
55+
1. [Setup a Notehub account](https://dev.blues.io/quickstart/notecard-quickstart/notecard-and-notecarrier-f/#set-up-notehub).
56+
> _**NOTE:** Notehub accounts are free (no credit card required)._
57+
1. [Create a project on your Notehub account](https://dev.blues.io/quickstart/notecard-quickstart/notecard-and-notecarrier-f/#create-a-notehub-project).
58+
1. In `thingProperties.h`, replace "com.domain.you:product" (from
59+
`NOTECARD_PRODUCT_UID`) with the ProductUID of your new Notehub project.
60+
61+
### Power-up the Device
62+
63+
1. [Connect the Notecard to your Host MCU](https://dev.blues.io/quickstart/notecard-quickstart/notecard-and-notecarrier-f/#connect-your-notecard-and-notecarrier)
64+
1. Flash the `ArduinoIoTCloud-Notecard` example sketch to your device. You
65+
should see the device reporting itself as online in your [Notehub Project](https://notehub.io).
66+
67+
### Associate Notecard to Arduino IoT Cloud
68+
69+
1. Create a "MANUAL Device" in the Arduino IoT Cloud, then [add environment
70+
variables for the "Device ID" and "Secret Key" to your Notecard in Notehub](https://dev.blues.io/guides-and-tutorials/notecard-guides/understanding-environment-variables/#setting-a-notehub-device-variable).
71+
- `_sn`: \<Device ID\>
72+
- `_secret_key`: \<Secret Key\>
73+
74+
### More Information
75+
76+
For more information about the Notecard and Notehub in general, please see our
77+
[Quickstart Guide](https://dev.blues.io/quickstart/) for a general overview of
78+
how the Notecard and Notehub are designed to work.

‎examples/ArduinoIoTCloud-Notecard/arduino_secrets.h

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#include <Arduino_ConnectionHandler.h>
2+
3+
/* If provided, the Wi-Fi Credentials will be passed along to the Notecard. If
4+
* the Notecard supports Wi-Fi, it will attempt to connect to the network using
5+
* these credentials, if not, the Notecard will safely ignore these values. */
6+
#define SECRET_WIFI_SSID "YOUR_WIFI_NETWORK_NAME"
7+
#define SECRET_WIFI_PASS "YOUR_WIFI_PASSWORD"

‎examples/ArduinoIoTCloud-Notecard/thingProperties.h

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#include <string.h>
2+
3+
#include <ArduinoIoTCloud.h>
4+
#include <Arduino_ConnectionHandler.h>
5+
#include "arduino_secrets.h"
6+
7+
/* The Notecard can provide connectivity to almost any board via ESLOV (I2C)
8+
* or UART. An empty string (or the default value provided below) will not
9+
* override the Notecard's existing configuration.
10+
* Learn more at: https://dev.blues.io */
11+
#define NOTECARD_PRODUCT_UID "com.domain.you:product"
12+
13+
/* Uncomment the following line to use the Notecard over UART */
14+
// #define UART_INTERFACE Serial1
15+
16+
void onLedChange();
17+
18+
bool led;
19+
int potentiometer;
20+
int seconds;
21+
22+
#ifndef UART_INTERFACE
23+
NotecardConnectionHandler ArduinoIoTPreferredConnection(NOTECARD_PRODUCT_UID);
24+
#else
25+
NotecardConnectionHandler ArduinoIoTPreferredConnection(NOTECARD_PRODUCT_UID, UART_INTERFACE);
26+
#endif
27+
28+
void initProperties() {
29+
ArduinoCloud.addProperty(led, Permission::ReadWrite).onUpdate(onLedChange);
30+
ArduinoCloud.addProperty(potentiometer, Permission::Read).publishOnChange(10);
31+
ArduinoCloud.addProperty(seconds, Permission::Read).publishEvery(5 * MINUTES);
32+
33+
if (::strncmp(SECRET_WIFI_SSID, "YOUR_WIFI_NETWORK_NAME", sizeof(SECRET_WIFI_SSID))) {
34+
ArduinoIoTPreferredConnection.setWiFiCredentials(SECRET_WIFI_SSID, SECRET_WIFI_PASS);
35+
}
36+
}

‎keywords.txt

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ getThingId KEYWORD2
2525
setDeviceId KEYWORD2
2626
getDeviceId KEYWORD2
2727
getConnection KEYWORD2
28+
getInternalTime KEYWORD2
29+
getLocalTime KEYWORD2
2830
addCallback KEYWORD2
2931
addProperty KEYWORD2
3032

@@ -46,6 +48,14 @@ getBrokerPort KEYWORD2
4648
setOTAStorage KEYWORD2
4749
reconnect KEYWORD2
4850

51+
# ArduinoIoTCloudNotecard.h
52+
begin KEYWORD2
53+
setNotecardPollingInterval KEYWORD2
54+
55+
# OTA
56+
onOTARequestCallbackFunc KEYWORD2
57+
onOTARequestCb KEYWORD2
58+
4959
#######################################
5060
# Constants (LITERAL1)
5161
#######################################

‎library.properties

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,6 @@ sentence=This library allows connecting to the Arduino IoT Cloud service.
66
paragraph=It provides a ConnectionManager to handle connection/disconnection, property-change updates and events callbacks. The supported boards are MKR GSM, MKR1000 and WiFi101.
77
category=Communication
88
url=https://github.com/arduino-libraries/ArduinoIoTCloud
9-
architectures=mbed,samd,esp8266,mbed_nano,mbed_portenta,mbed_nicla,esp32,mbed_opta,mbed_giga,renesas_portenta,renesas_uno,mbed_edge
9+
architectures=mbed,samd,esp8266,mbed_nano,mbed_portenta,mbed_nicla,esp32,mbed_opta,mbed_giga,renesas_portenta,renesas_uno,mbed_edge,stm32
1010
includes=ArduinoIoTCloud.h
1111
depends=Arduino_ConnectionHandler,Arduino_DebugUtils,Arduino_SecureElement,ArduinoMqttClient,ArduinoECCX08,RTCZero,Adafruit SleepyDog Library,ArduinoHttpClient

0 commit comments

Comments
 (0)