feat: NotecardConnectionManager

.github/workflows/compile-examples.yml

@@ -35,6 +35,9 @@ jobs:
         - name: MKRNB
         - name: MKRWAN
         - name: Arduino_Cellular
+        - name: Blues Wireless Notecard
+      SKETCH_PATHS: |
+        - examples/ConnectionHandlerDemo
       ARDUINOCORE_MBED_STAGING_PATH: extras/ArduinoCore-mbed
       ARDUINOCORE_API_STAGING_PATH: extras/ArduinoCore-API
       SKETCHES_REPORTS_PATH: sketches-reports
@@ -106,6 +109,8 @@ jobs:
             platforms: |
               # Install Arduino SAMD Boards via Boards Manager
               - name: arduino:samd
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
           - board:
               platform-name: arduino:mbed
             platforms: |
@@ -114,21 +119,53 @@ jobs:
               # 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)
               - source-path: extras/ArduinoCore-mbed
                 name: arduino:mbed
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
+          - board:
+              platform-name: arduino:mbed_portenta
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
+          - board:
+              platform-name: arduino:mbed_nano
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
+          - board:
+              platform-name: arduino:mbed_nicla
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
+          - board:
+              platform-name: arduino:mbed_opta
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
+          - board:
+              platform-name: arduino:mbed_giga
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
+          - board:
+              platform-name: arduino:mbed_edge
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
           - board:
               platform-name: arduino:renesas_portenta
             platforms: |
               # Install Arduino Renesas portenta Boards via Boards Manager
               - name: arduino:renesas_portenta
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
           - board:
               platform-name: arduino:renesas_uno
             platforms: |
               # Install Arduino Renesas uno Boards via Boards Manager
               - name: arduino:renesas_uno
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
           - board:
               platform-name: arduino:esp32
             platforms: |
               # Install Arduino ESP32 Boards via Boards Manager
               - name: arduino:esp32
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
           - board:
               platform-name: esp8266:esp8266
             platforms: |
@@ -142,6 +179,8 @@ jobs:
               # Install ESP32 platform via Boards Manager
               - name: esp32:esp32
                 source-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
+            sketch-paths: |
+              - examples/ConnectionHandlerDemo-Notecard
 
     steps:
       - uses: actions/checkout@v4
@@ -180,6 +219,9 @@ jobs:
           platforms: ${{ matrix.platforms }}
           fqbn: ${{ matrix.board.fqbn }}
           libraries: ${{ env.LIBRARIES }}
+          sketch-paths: |
+            ${{ env.SKETCH_PATHS }}
+            ${{ matrix.sketch-paths }}
           enable-deltas-report: 'true'
           sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }}
 

README.md

@@ -6,21 +6,25 @@ Arduino Library for network connections management
 [![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)
 
 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:
+
 * **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)
 * **GSM**: [`MKR GSM 1400`](https://store.arduino.cc/arduino-mkr-gsm-1400-1415)
 * **5G**: [`MKR NB 1500`](https://store.arduino.cc/arduino-mkr-nb-1500-1413)
 * **LoRa**: [`MKR WAN 1300/1310`](https://store.arduino.cc/mkr-wan-1310)
 * **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)
+* **Notecard**: [Provides Cellular/LoRa/Satellite/Wi-Fi to any modern board/architecture](examples/ConnectionHandlerDemo-Notecard/README.md)
 
 ### How-to-use
 
 ```C++
 #include <Arduino_ConnectionHandler.h>
 /* ... */
-#if defined(BOARD_HAS_ETHERNET)
+#if defined(BOARD_HAS_NOTECARD)
+NotecardConnectionHandler conMan("com.domain.you:product");
+#elif defined(BOARD_HAS_ETHERNET)
 EthernetConnectionHandler conMan;
 #elif defined(BOARD_HAS_WIFI)
-WiFiConnectionHandler conMan("SECRET_SSID", "SECRET_PASS");
+WiFiConnectionHandler conMan("SECRET_WIFI_SSID", "SECRET_WIFI_PASS");
 #elif defined(BOARD_HAS_GSM)
 GSMConnectionHandler conMan("SECRET_PIN", "SECRET_APN", "SECRET_GSM_LOGIN", "SECRET_GSM_PASS");
 #elif defined(BOARD_HAS_NB)

examples/ConnectionHandlerDemo-Notecard/ConnectionHandlerDemo-Notecard.ino

@@ -0,0 +1,144 @@
+/* SECRET_ fields are in `arduino_secrets.h` (included below)
+ *
+ * If using a Host + Notecard connected over I2C you'll need a
+ * NotecardConnectionHandler object as follows:
+ *
+ *   NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID);
+ *
+ * If using a Host + Notecard connected over Serial you'll need a
+ * NotecardConnectionHandler object as follows:
+ *
+ *   NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID, UART_INTERFACE);
+ */
+
+#include <Notecard.h> // MUST include this first to enable Notecard support
+#include <Arduino_ConnectionHandler.h>
+
+#include "arduino_secrets.h"
+
+/* Uncomment the following line to use this example in a manner that is more
+ * compatible with LoRa.
+ */
+// #define USE_NOTE_LORA
+
+#ifndef USE_NOTE_LORA
+#define CONN_TOGGLE_MS 60000
+#else
+#define CONN_TOGGLE_MS 300000
+#endif
+
+/* The Notecard can provide connectivity to almost any board via ESLOV (I2C)
+ * or UART. An empty string (or the default value provided below) will not
+ * override the Notecard's existing configuration.
+ * Learn more at: https://dev.blues.io */
+#define NOTECARD_PRODUCT_UID "com.domain.you:product"
+
+/* Uncomment the following line to use the Notecard over UART */
+// #define UART_INTERFACE Serial1
+
+#ifndef UART_INTERFACE
+NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID);
+#else
+NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID, UART_INTERFACE);
+#endif
+
+bool attemptConnect = false;
+uint32_t lastConnToggleMs = 0;
+
+void setup() {
+  /* Initialize serial debug port and wait up to 5 seconds for port to open */
+  Serial.begin(9600);
+  for(unsigned long const serialBeginTime = millis(); !Serial && (millis() - serialBeginTime <= 5000); ) { }
+
+  /* Set the debug message level:
+   * - DBG_ERROR: Only show error messages
+   * - DBG_WARNING: Show warning and error messages
+   * - DBG_INFO: Show info, warning, and error messages
+   * - DBG_DEBUG: Show debug, info, warning, and error messages
+   * - DBG_VERBOSE: Show all messages
+   */
+  setDebugMessageLevel(DBG_INFO);
+
+  /* Add callbacks to the ConnectionHandler object to get notified of network
+   * connection events. */
+  conMan.addCallback(NetworkConnectionEvent::CONNECTED, onNetworkConnect);
+  conMan.addCallback(NetworkConnectionEvent::DISCONNECTED, onNetworkDisconnect);
+  conMan.addCallback(NetworkConnectionEvent::ERROR, onNetworkError);
+
+  /* First call to `check()` initializes the connection to the Notecard. While
+   * not strictly necessary, it cleans up the logging from this application.
+   */
+  conMan.check();
+
+#ifndef USE_NOTE_LORA
+  /* Set the Wi-Fi credentials for the Notecard */
+  String ssid = SECRET_WIFI_SSID;
+  if (ssid.length() > 0 && ssid != "NETWORK NAME") {
+    conMan.setWiFiCredentials(SECRET_WIFI_SSID, SECRET_WIFI_PASS);
+  }
+#else
+  conMan.setNotehubPollingInterval(720);  // poll twice per day
+#endif
+
+  /* Confirm Interface */
+  Serial.print("Network Adapter Interface: ");
+  if (NetworkAdapter::NOTECARD == conMan.getInterface()) {
+    Serial.print("Notecard ");
+    Serial.print(conMan.getNotecardUid());
+#ifndef UART_INTERFACE
+    Serial.println(" (via I2C)");
+#else
+    Serial.println(" (via UART)");
+#endif
+  } else {
+    Serial.println("ERROR: Unexpected Interface");
+    while(1);
+  }
+
+  /* Display the Arduino IoT Cloud Device ID */
+  displayCachedDeviceId();
+}
+
+void loop() {
+  /* Toggle the connection every `CONN_TOGGLE_MS` milliseconds */
+  if ((millis() - lastConnToggleMs) > CONN_TOGGLE_MS) {
+    Serial.println("Toggling connection...");
+    if (attemptConnect) {
+      displayCachedDeviceId();
+      conMan.connect();
+    } else {
+      // Flush any queued Notecard requests before disconnecting
+      conMan.initiateNotehubSync(NotecardConnectionHandler::SyncType::Outbound);
+      conMan.disconnect();
+    }
+    attemptConnect = !attemptConnect;
+    lastConnToggleMs = millis();
+  }
+
+  /* The following code keeps on running connection workflows on our
+   * ConnectionHandler object, hence allowing reconnection in case of failure
+   * and notification of connect/disconnect event if enabled (see
+   * addConnectCallback/addDisconnectCallback) NOTE: any use of delay() within
+   * the loop or methods called from it will delay the execution of .update(),
+   * which might not guarantee the correct functioning of the ConnectionHandler
+   * object.
+   */
+  conMan.check();
+}
+
+void displayCachedDeviceId() {
+  Serial.print("Cached Arduino IoT Cloud Device ID: ");
+  Serial.println(conMan.getDeviceId());
+}
+
+void onNetworkConnect() {
+  Serial.println(">>>> CONNECTED to network");
+}
+
+void onNetworkDisconnect() {
+  Serial.println(">>>> DISCONNECTED from network");
+}
+
+void onNetworkError() {
+  Serial.println(">>>> ERROR");
+}

examples/ConnectionHandlerDemo-Notecard/README.md

@@ -0,0 +1,71 @@
+Notecard Connectivity
+=====================
+
+The Notecard is a wireless, secure abstraction for device connectivity, that can
+be used to enable _ANY*_ device with I2C, or UART, to connect to the Arduino IoT
+Cloud via cellular, LoRa, satellite or Wi-Fi!
+
+As a result, your existing device architecture can now have first class support
+in the Arduino IoT Cloud, by using a Notecard as a secure communication channel.
+
+> \*_While any device with I2C/UART may use the Notecard, the Arduino IoT Cloud
+> library is not supported by the AVR toolchain. Therefore, devices based on the
+> AVR architecture cannot access the Arduino IoT Cloud via the Notecard._
+>
+> _However, any device (including AVR), may use the Notecard library to send data
+> to Notehub, then that data may be routed to any endpoint of your choosing. See the
+> [Notecard Routing Guide](https://dev.blues.io/guides-and-tutorials/routing-data-to-cloud)
+> for more information..._
+
+Wireless Connectivity Options
+-----------------------------
+
+- [Cellular](https://shop.blues.com/collections/notecard/products/notecard-cellular)
+- [Cellular + Wi-Fi](https://shop.blues.com/collections/notecard/products/notecard-cell-wifi)
+- [Wi-Fi](https://shop.blues.com/collections/notecard/products/wifi-notecard)
+- [LoRa](https://shop.blues.com/collections/notecard/products/notecard-lora)
+- [Satellite](https://shop.blues.com/products/starnote)
+
+How it Works
+------------
+
+**Architecture Diagram:**
+
+```
+--------                ------------                  -----------           -----------
+|      |                |          |                  |         |           |         |
+| Host |                |          |      Secure      |         |           | Arduino |
+| MCU  |---<I2C/UART>---| Notecard | ( ( Wireless ) ) | Notehub |---<TLS>---|   IoT   |
+|      |                |          |     Protocol     |         |           |  Cloud  |
+|______|                |__________|                  |_________|           |_________|
+```
+
+Getting Started
+---------------
+
+### Setup a Notehub Account
+
+Using the Notecard only requires a couple of easy steps:
+
+1. [Purchase a Notecard](https://shop.blues.com/collections/notecard) (and
+[Notecarrier](https://shop.blues.com/collections/notecarrier)) that fits the
+needs of your device.
+   > _**NOTE:** We recommend starting with our [Dev Kit](https://shop.blues.com/products/blues-global-starter-kit)
+   > if you are unsure._
+1. [Setup a Notehub account](https://dev.blues.io/quickstart/notecard-quickstart/notecard-and-notecarrier-f/#set-up-notehub).
+   > _**NOTE:** Notehub accounts are free (no credit card required)._
+1. [Create a project on your Notehub account](https://dev.blues.io/quickstart/notecard-quickstart/notecard-and-notecarrier-f/#create-a-notehub-project).
+1. In `ConnectionHandlerDemo-Notecard`, replace "com.domain.you:product" (from
+`NOTECARD_PRODUCT_UID`) with the ProductUID of your new Notehub project.
+
+### Power-up the Device
+
+1. [Connect the Notecard to your Host MCU](https://dev.blues.io/quickstart/notecard-quickstart/notecard-and-notecarrier-f/#connect-your-notecard-and-notecarrier)
+1. Flash the `ConnectionHanderDemo-Notecard` example sketch to your device. You
+should see the device reporting itself as online in your [Notehub Project](https://notehub.io).
+
+### More Information
+
+For more information about the Notecard and Notehub in general, please see our
+[Quickstart Guide](https://dev.blues.io/quickstart/) for a general overview of
+how the Notecard and Notehub are designed to work.

examples/ConnectionHandlerDemo-Notecard/arduino_secrets.h

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