Skip to content

Commit d755eb5

Browse files
authored
Merge pull request #122 from zfields/notecard
feat: NotecardConnectionManager
2 parents 4419df1 + df5c827 commit d755eb5

14 files changed

+1552
-31
lines changed

Diff for: .github/workflows/compile-examples.yml

+42
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,9 @@ jobs:
3535
- name: MKRNB
3636
- name: MKRWAN
3737
- name: Arduino_Cellular
38+
- name: Blues Wireless Notecard
39+
SKETCH_PATHS: |
40+
- examples/ConnectionHandlerDemo
3841
ARDUINOCORE_MBED_STAGING_PATH: extras/ArduinoCore-mbed
3942
ARDUINOCORE_API_STAGING_PATH: extras/ArduinoCore-API
4043
SKETCHES_REPORTS_PATH: sketches-reports
@@ -106,6 +109,8 @@ jobs:
106109
platforms: |
107110
# Install Arduino SAMD Boards via Boards Manager
108111
- name: arduino:samd
112+
sketch-paths: |
113+
- examples/ConnectionHandlerDemo-Notecard
109114
- board:
110115
platform-name: arduino:mbed
111116
platforms: |
@@ -114,21 +119,53 @@ jobs:
114119
# Overwrite the Arduino mbed-Enabled Boards release version with version from the tip of the default branch (located in local path because of the need to first install ArduinoCore-API)
115120
- source-path: extras/ArduinoCore-mbed
116121
name: arduino:mbed
122+
sketch-paths: |
123+
- examples/ConnectionHandlerDemo-Notecard
124+
- board:
125+
platform-name: arduino:mbed_portenta
126+
sketch-paths: |
127+
- examples/ConnectionHandlerDemo-Notecard
128+
- board:
129+
platform-name: arduino:mbed_nano
130+
sketch-paths: |
131+
- examples/ConnectionHandlerDemo-Notecard
132+
- board:
133+
platform-name: arduino:mbed_nicla
134+
sketch-paths: |
135+
- examples/ConnectionHandlerDemo-Notecard
136+
- board:
137+
platform-name: arduino:mbed_opta
138+
sketch-paths: |
139+
- examples/ConnectionHandlerDemo-Notecard
140+
- board:
141+
platform-name: arduino:mbed_giga
142+
sketch-paths: |
143+
- examples/ConnectionHandlerDemo-Notecard
144+
- board:
145+
platform-name: arduino:mbed_edge
146+
sketch-paths: |
147+
- examples/ConnectionHandlerDemo-Notecard
117148
- board:
118149
platform-name: arduino:renesas_portenta
119150
platforms: |
120151
# Install Arduino Renesas portenta Boards via Boards Manager
121152
- name: arduino:renesas_portenta
153+
sketch-paths: |
154+
- examples/ConnectionHandlerDemo-Notecard
122155
- board:
123156
platform-name: arduino:renesas_uno
124157
platforms: |
125158
# Install Arduino Renesas uno Boards via Boards Manager
126159
- name: arduino:renesas_uno
160+
sketch-paths: |
161+
- examples/ConnectionHandlerDemo-Notecard
127162
- board:
128163
platform-name: arduino:esp32
129164
platforms: |
130165
# Install Arduino ESP32 Boards via Boards Manager
131166
- name: arduino:esp32
167+
sketch-paths: |
168+
- examples/ConnectionHandlerDemo-Notecard
132169
- board:
133170
platform-name: esp8266:esp8266
134171
platforms: |
@@ -142,6 +179,8 @@ jobs:
142179
# Install ESP32 platform via Boards Manager
143180
- name: esp32:esp32
144181
source-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
182+
sketch-paths: |
183+
- examples/ConnectionHandlerDemo-Notecard
145184
146185
steps:
147186
- uses: actions/checkout@v4
@@ -180,6 +219,9 @@ jobs:
180219
platforms: ${{ matrix.platforms }}
181220
fqbn: ${{ matrix.board.fqbn }}
182221
libraries: ${{ env.LIBRARIES }}
222+
sketch-paths: |
223+
${{ env.SKETCH_PATHS }}
224+
${{ matrix.sketch-paths }}
183225
enable-deltas-report: 'true'
184226
sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }}
185227

Diff for: README.md

+6-2
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+
910
* **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)
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](examples/ConnectionHandlerDemo-Notecard/README.md)
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)
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 <Arduino_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+
}

Diff for: 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.
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";

0 commit comments

Comments
 (0)