Skip to content

Commit 7bae6d2

Browse files
zfieldszfields
committed
feat: NotecardConnectionHandler
1 parent 4419df1 commit 7bae6d2

14 files changed

+1513
-33
lines changed

‎.github/workflows/compile-examples.yml

+2-1
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ jobs:
3535
- name: MKRNB
3636
- name: MKRWAN
3737
- name: Arduino_Cellular
38+
- name: Blues Wireless Notecard
3839
ARDUINOCORE_MBED_STAGING_PATH: extras/ArduinoCore-mbed
3940
ARDUINOCORE_API_STAGING_PATH: extras/ArduinoCore-API
4041
SKETCHES_REPORTS_PATH: sketches-reports
@@ -135,7 +136,7 @@ jobs:
135136
# Install ESP8266 platform via Boards Manager
136137
- name: esp8266:esp8266
137138
source-url: https://arduino.esp8266.com/stable/package_esp8266com_index.json
138-
version: 2.5.0
139+
version: 3.1.2
139140
- board:
140141
platform-name: esp32:esp32
141142
platforms: |

‎README.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,25 @@ Arduino Library for network connections management
66
[![Spell Check status](https://github.com/arduino-libraries/Arduino_ConnectionHandler/actions/workflows/spell-check.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_ConnectionHandler/actions/workflows/spell-check.yml)
77

88
Library for handling and managing network connections by providing keep-alive functionality and automatic reconnection in case of connection-loss. It supports the following boards:
9-
* **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/products/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)
9+
10+
* **Wi-Fi**: [`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/products/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)
1011
* **GSM**: [`MKR GSM 1400`](https://store.arduino.cc/arduino-mkr-gsm-1400-1415)
1112
* **5G**: [`MKR NB 1500`](https://store.arduino.cc/arduino-mkr-nb-1500-1413)
1213
* **LoRa**: [`MKR WAN 1300/1310`](https://store.arduino.cc/mkr-wan-1310)
1314
* **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)
15+
* **Notecard**: [Provides Cellular/LoRa/Satellite/Wi-Fi to any modern board/architecture](https://shop.blues.com/collections/notecard)
1416

1517
### How-to-use
1618

1719
```C++
1820
#include <Arduino_ConnectionHandler.h>
1921
/* ... */
20-
#if defined(BOARD_HAS_ETHERNET)
22+
#if defined(BOARD_HAS_NOTECARD)
23+
NotecardConnectionHandler conMan("com.domain.you:product");
24+
#elif defined(BOARD_HAS_ETHERNET)
2125
EthernetConnectionHandler conMan;
2226
#elif defined(BOARD_HAS_WIFI)
23-
WiFiConnectionHandler conMan("SECRET_SSID", "SECRET_PASS");
27+
WiFiConnectionHandler conMan("SECRET_WIFI_SSID", "SECRET_WIFI_PASS");
2428
#elif defined(BOARD_HAS_GSM)
2529
GSMConnectionHandler conMan("SECRET_PIN", "SECRET_APN", "SECRET_GSM_LOGIN", "SECRET_GSM_PASS");
2630
#elif defined(BOARD_HAS_NB)

‎examples/ConnectionHandlerDemo-Notecard/ConnectionHandlerDemo-Notecard.ino

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
/* SECRET_ fields are in `arduino_secrets.h` (included below)
2+
*
3+
* If using a Host + Notecard connected over I2C you'll need a
4+
* NotecardConnectionHandler object as follows:
5+
*
6+
* NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID);
7+
*
8+
* If using a Host + Notecard connected over Serial you'll need a
9+
* NotecardConnectionHandler object as follows:
10+
*
11+
* NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID, UART_INTERFACE);
12+
*/
13+
14+
#include <Notecard.h> // MUST include this first to enable Notecard support
15+
#include <ConnectionHandler.h>
16+
17+
#include "arduino_secrets.h"
18+
19+
/* Uncomment the following line to use this example in a manner that is more
20+
* compatible with LoRa.
21+
*/
22+
// #define USE_NOTE_LORA
23+
24+
#ifndef USE_NOTE_LORA
25+
#define CONN_TOGGLE_MS 60000
26+
#else
27+
#define CONN_TOGGLE_MS 300000
28+
#endif
29+
30+
/* The Notecard can provide connectivity to almost any board via ESLOV (I2C)
31+
* or UART. An empty string (or the default value provided below) will not
32+
* override the Notecard's existing configuration.
33+
* Learn more at: https://dev.blues.io */
34+
#define NOTECARD_PRODUCT_UID "com.domain.you:product"
35+
36+
/* Uncomment the following line to use the Notecard over UART */
37+
// #define UART_INTERFACE Serial1
38+
39+
#ifndef UART_INTERFACE
40+
NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID);
41+
#else
42+
NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID, UART_INTERFACE);
43+
#endif
44+
45+
bool attemptConnect = false;
46+
uint32_t lastConnToggleMs = 0;
47+
48+
void setup() {
49+
/* Initialize serial debug port and wait up to 5 seconds for port to open */
50+
Serial.begin(9600);
51+
for(unsigned long const serialBeginTime = millis(); !Serial && (millis() - serialBeginTime <= 5000); ) { }
52+
53+
/* Set the debug message level:
54+
* - DBG_ERROR: Only show error messages
55+
* - DBG_WARNING: Show warning and error messages
56+
* - DBG_INFO: Show info, warning, and error messages
57+
* - DBG_DEBUG: Show debug, info, warning, and error messages
58+
* - DBG_VERBOSE: Show all messages
59+
*/
60+
setDebugMessageLevel(DBG_INFO);
61+
62+
/* Add callbacks to the ConnectionHandler object to get notified of network
63+
* connection events. */
64+
conMan.addCallback(NetworkConnectionEvent::CONNECTED, onNetworkConnect);
65+
conMan.addCallback(NetworkConnectionEvent::DISCONNECTED, onNetworkDisconnect);
66+
conMan.addCallback(NetworkConnectionEvent::ERROR, onNetworkError);
67+
68+
/* First call to `check()` initializes the connection to the Notecard. While
69+
* not strictly necessary, it cleans up the logging from this application.
70+
*/
71+
conMan.check();
72+
73+
#ifndef USE_NOTE_LORA
74+
/* Set the Wi-Fi credentials for the Notecard */
75+
String ssid = SECRET_WIFI_SSID;
76+
if (ssid.length() > 0 && ssid != "NETWORK NAME") {
77+
conMan.setWiFiCredentials(SECRET_WIFI_SSID, SECRET_WIFI_PASS);
78+
}
79+
#else
80+
conMan.setNotehubPollingInterval(720); // poll twice per day
81+
#endif
82+
83+
/* Confirm Interface */
84+
Serial.print("Network Adapter Interface: ");
85+
if (NetworkAdapter::NOTECARD == conMan.getInterface()) {
86+
Serial.print("Notecard ");
87+
Serial.print(conMan.getNotecardUid());
88+
#ifndef UART_INTERFACE
89+
Serial.println(" (via I2C)");
90+
#else
91+
Serial.println(" (via UART)");
92+
#endif
93+
} else {
94+
Serial.println("ERROR: Unexpected Interface");
95+
while(1);
96+
}
97+
98+
/* Display the Arduino IoT Cloud Device ID */
99+
displayCachedDeviceId();
100+
}
101+
102+
void loop() {
103+
/* Toggle the connection every `CONN_TOGGLE_MS` milliseconds */
104+
if ((millis() - lastConnToggleMs) > CONN_TOGGLE_MS) {
105+
Serial.println("Toggling connection...");
106+
if (attemptConnect) {
107+
displayCachedDeviceId();
108+
conMan.connect();
109+
} else {
110+
// Flush any queued Notecard requests before disconnecting
111+
conMan.initiateNotehubSync(NotecardConnectionHandler::SyncType::Outbound);
112+
conMan.disconnect();
113+
}
114+
attemptConnect = !attemptConnect;
115+
lastConnToggleMs = millis();
116+
}
117+
118+
/* The following code keeps on running connection workflows on our
119+
* ConnectionHandler object, hence allowing reconnection in case of failure
120+
* and notification of connect/disconnect event if enabled (see
121+
* addConnectCallback/addDisconnectCallback) NOTE: any use of delay() within
122+
* the loop or methods called from it will delay the execution of .update(),
123+
* which might not guarantee the correct functioning of the ConnectionHandler
124+
* object.
125+
*/
126+
conMan.check();
127+
}
128+
129+
void displayCachedDeviceId() {
130+
Serial.print("Cached Arduino IoT Cloud Device ID: ");
131+
Serial.println(conMan.getDeviceId());
132+
}
133+
134+
void onNetworkConnect() {
135+
Serial.println(">>>> CONNECTED to network");
136+
}
137+
138+
void onNetworkDisconnect() {
139+
Serial.println(">>>> DISCONNECTED from network");
140+
}
141+
142+
void onNetworkError() {
143+
Serial.println(">>>> ERROR");
144+
}

‎examples/ConnectionHandlerDemo-Notecard/README.md

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
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 `ConnectionHandlerDemo-Notecard`, 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 `ConnectionHanderDemo-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+
### More Information
68+
69+
For more information about the Notecard and Notehub in general, please see our
70+
[Quickstart Guide](https://dev.blues.io/quickstart/) for a general overview of
71+
how the Notecard and Notehub are designed to work.

‎examples/ConnectionHandlerDemo-Notecard/arduino_secrets.h

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/* If provided, the Wi-Fi Credentials will be passed along to the Notecard. If
2+
* the Notecard supports Wi-Fi, it will attempt to connect to the network using
3+
* these credentials, if not, the Notecard will safely ignore these values. */
4+
const char SECRET_WIFI_SSID[] = "NETWORK NAME";
5+
const char SECRET_WIFI_PASS[] = "NETWORK PASSWORD";

‎examples/ConnectionHandlerDemo/ConnectionHandlerDemo.ino

+71-10
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
/* SECRET_ fields are in arduino_secrets.h included above
2-
* if using a WiFi board (Arduino MKR1000, MKR WiFi 1010, Nano 33 IoT, UNO
1+
/* SECRET_ fields are in `arduino_secrets.h` (included below)
2+
*
3+
* If using a WiFi board (Arduino MKR1000, MKR WiFi 1010, Nano 33 IoT, UNO
34
* WiFi Rev 2 or ESP8266/32), create a WiFiConnectionHandler object by adding
4-
* Network Name (SECRET_SSID) and password (SECRET_PASS) in the arduino_secrets.h
5-
* file (or Secrets tab in Create Web Editor).
5+
* Network Name (SECRET_WIFI_SSID) and password (SECRET_WIFI_PASS) in the
6+
* arduino_secrets.h file (or Secrets tab in Create Web Editor).
67
*
7-
* WiFiConnectionHandler conMan(SECRET_SSID, SECRET_PASS);
8+
* WiFiConnectionHandler conMan(SECRET_WIFI_SSID, SECRET_WIFI_PASS);
89
*
910
* If using a MKR GSM 1400 or other GSM boards supporting the same API you'll
1011
* need a GSMConnectionHandler object as follows
@@ -27,14 +28,21 @@
2728
*
2829
*/
2930

31+
#include <Arduino_ConnectionHandler.h>
32+
3033
#include "arduino_secrets.h"
3134

32-
#include <Arduino_ConnectionHandler.h>
35+
#define CONN_TOGGLE_MS 60000
36+
37+
#if !(defined(BOARD_HAS_WIFI) || defined(BOARD_HAS_GSM) || defined(BOARD_HAS_LORA) || \
38+
defined(BOARD_HAS_NB) || defined(BOARD_HAS_ETHERNET) || defined(BOARD_HAS_CATM1_NBIOT))
39+
#error "Please check Arduino Connection Handler supported boards list: https://github.com/arduino-libraries/Arduino_ConnectionHandler/blob/master/README.md"
40+
#endif
3341

3442
#if defined(BOARD_HAS_ETHERNET)
3543
EthernetConnectionHandler conMan(SECRET_IP, SECRET_DNS, SECRET_GATEWAY, SECRET_NETMASK);
3644
#elif defined(BOARD_HAS_WIFI)
37-
WiFiConnectionHandler conMan(SECRET_SSID, SECRET_PASS);
45+
WiFiConnectionHandler conMan(SECRET_WIFI_SSID, SECRET_WIFI_PASS);
3846
#elif defined(BOARD_HAS_GSM)
3947
GSMConnectionHandler conMan(SECRET_PIN, SECRET_APN, SECRET_GSM_USER, SECRET_GSM_PASS);
4048
#elif defined(BOARD_HAS_NB)
@@ -47,19 +55,73 @@ CatM1ConnectionHandler conMan(SECRET_PIN, SECRET_APN, SECRET_GSM_USER, SECRET_GS
4755
CellularConnectionHandler conMan(SECRET_PIN, SECRET_APN, SECRET_GSM_USER, SECRET_GSM_PASS);
4856
#endif
4957

58+
bool attemptConnect = false;
59+
uint32_t lastConnToggleMs = 0;
60+
5061
void setup() {
62+
/* Initialize serial debug port and wait up to 5 seconds for port to open */
5163
Serial.begin(9600);
52-
/* Give a few seconds for the Serial connection to be available */
53-
delay(4000);
64+
for(unsigned long const serialBeginTime = millis(); !Serial && (millis() - serialBeginTime <= 5000); ) { }
65+
5466
#ifndef __AVR__
67+
/* Set the debug message level:
68+
* - DBG_ERROR: Only show error messages
69+
* - DBG_WARNING: Show warning and error messages
70+
* - DBG_INFO: Show info, warning, and error messages
71+
* - DBG_DEBUG: Show debug, info, warning, and error messages
72+
* - DBG_VERBOSE: Show all messages
73+
*/
5574
setDebugMessageLevel(DBG_INFO);
5675
#endif
76+
77+
/* Add callbacks to the ConnectionHandler object to get notified of network
78+
* connection events. */
5779
conMan.addCallback(NetworkConnectionEvent::CONNECTED, onNetworkConnect);
5880
conMan.addCallback(NetworkConnectionEvent::DISCONNECTED, onNetworkDisconnect);
5981
conMan.addCallback(NetworkConnectionEvent::ERROR, onNetworkError);
82+
83+
Serial.print("Network Adapter Interface: ");
84+
switch (conMan.getInterface()) {
85+
case NetworkAdapter::WIFI:
86+
Serial.println("Wi-Fi");
87+
break;
88+
case NetworkAdapter::ETHERNET:
89+
Serial.println("Ethernet");
90+
break;
91+
case NetworkAdapter::NB:
92+
Serial.println("Narrowband");
93+
break;
94+
case NetworkAdapter::GSM:
95+
Serial.println("GSM");
96+
break;
97+
case NetworkAdapter::LORA:
98+
Serial.println("LoRa");
99+
break;
100+
case NetworkAdapter::CATM1:
101+
Serial.println("Category M1");
102+
break;
103+
case NetworkAdapter::CELL:
104+
Serial.println("Cellular");
105+
break;
106+
default:
107+
Serial.println("Unknown");
108+
break;
109+
}
60110
}
61111

62112
void loop() {
113+
/* Toggle the connection every `CONN_TOGGLE_MS` milliseconds */
114+
if ((millis() - lastConnToggleMs) > CONN_TOGGLE_MS) {
115+
Serial.println("Toggling connection...");
116+
if (attemptConnect) {
117+
conMan.connect();
118+
} else {
119+
conMan.disconnect();
120+
}
121+
attemptConnect = !attemptConnect;
122+
lastConnToggleMs = millis();
123+
}
124+
63125
/* The following code keeps on running connection workflows on our
64126
* ConnectionHandler object, hence allowing reconnection in case of failure
65127
* and notification of connect/disconnect event if enabled (see
@@ -68,7 +130,6 @@ void loop() {
68130
* which might not guarantee the correct functioning of the ConnectionHandler
69131
* object.
70132
*/
71-
72133
conMan.check();
73134
}
74135

0 commit comments

Comments
 (0)