feat: NotecardConnectionManager

Author: zfields

.gitignore

@@ -0,0 +1 @@
+.vscode/

README.md

@@ -20,7 +20,7 @@ Library for handling and managing network connections by providing keep-alive fu
 #if 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/ConnectionHandlerDemo.ino

@@ -1,10 +1,21 @@
 /* SECRET_ fields are in arduino_secrets.h included above
- * if using a WiFi board (Arduino MKR1000, MKR WiFi 1010, Nano 33 IoT, UNO
+ *
+ * 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, Serial);
+ *
+ * If using a WiFi board (Arduino MKR1000, MKR WiFi 1010, Nano 33 IoT, UNO
  * WiFi Rev 2 or ESP8266/32), create a WiFiConnectionHandler object by adding
- * Network Name (SECRET_SSID) and password (SECRET_PASS) in the arduino_secrets.h
- * file (or Secrets tab in Create Web Editor).
+ * Network Name (SECRET_WIFI_SSID) and password (SECRET_WIFI_PASS) in the
+ * arduino_secrets.h file (or Secrets tab in Create Web Editor).
  *
- *    WiFiConnectionHandler conMan(SECRET_SSID, SECRET_PASS);
+ *    WiFiConnectionHandler conMan(SECRET_WIFI_SSID, SECRET_WIFI_PASS);
  *
  * If using a MKR GSM 1400 or other GSM boards supporting the same API you'll
  * need a GSMConnectionHandler object as follows
@@ -31,10 +42,25 @@
 
 #include <Arduino_ConnectionHandler.h>
 
-#if defined(BOARD_HAS_ETHERNET)
+#if !(defined(USE_NOTECARD) || defined(BOARD_HAS_WIFI) || defined(BOARD_HAS_GSM) || defined(BOARD_HAS_LORA) || \
+      defined(BOARD_HAS_NB) || defined(BOARD_HAS_ETHERNET) || defined(BOARD_HAS_CATM1_NBIOT))
+  #error "Please check Arduino Connection Handler supported boards list: https://github.com/arduino-libraries/Arduino_ConnectionHandler/blob/master/README.md"
+#endif
+
+#if defined(USE_NOTECARD)
+  /* 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"
+#endif
+
+#if defined(USE_NOTECARD)
+NotecardConnectionHandler conMan(NOTECARD_PRODUCT_UID);
+#elif defined(BOARD_HAS_ETHERNET)
 EthernetConnectionHandler conMan(SECRET_IP, SECRET_DNS, SECRET_GATEWAY, SECRET_NETMASK);
 #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_USER, SECRET_GSM_PASS);
 #elif defined(BOARD_HAS_NB)
@@ -48,9 +74,9 @@ CellularConnectionHandler conMan(SECRET_PIN, SECRET_APN, SECRET_GSM_USER, SECRET
 #endif
 
 void setup() {
+  /* Initialize serial and wait up to 5 seconds for port to open */
   Serial.begin(9600);
-  /* Give a few seconds for the Serial connection to be available */
-  delay(4000);
+  for(unsigned long const serialBeginTime = millis(); !Serial && (millis() - serialBeginTime <= 5000); ) { }
 #ifndef __AVR__
   setDebugMessageLevel(DBG_INFO);
 #endif

examples/ConnectionHandlerDemo/arduino_secrets.h

@@ -1,6 +1,6 @@
 // Required for WiFiConnectionHandler
-const char SECRET_SSID[] = "NETWORK NAME";
-const char SECRET_PASS[] = "NETWORK PASSWORD";
+const char SECRET_WIFI_SSID[] = "NETWORK NAME";
+const char SECRET_WIFI_PASS[] = "NETWORK PASSWORD";
 
 // Required for GSMConnectionHandler
 const char SECRET_APN[] 		= "MOBILE PROVIDER APN ADDRESS";

library.properties

@@ -2,9 +2,9 @@ name=Arduino_ConnectionHandler
 version=0.9.0
 author=Ubi de Feo, Cristian Maglie, Andrea Catozzi, Alexander Entinger et al.
 maintainer=Arduino <info@arduino.cc>
-sentence=Arduino Library for network connection management (WiFi, GSM, NB, [Ethernet])
+sentence=Arduino Library for network connection management (WiFi, GSM, NB, [Ethernet], Notecard)
 paragraph=Originally part of ArduinoIoTCloud
 category=Communication
 url=https://github.com/arduino-libraries/Arduino_ConnectionHandler
-architectures=samd,esp32,esp8266,mbed,megaavr,mbed_nano,mbed_portenta,mbed_nicla,mbed_opta,mbed_giga,renesas_portenta,renesas_uno,mbed_edge
-depends=Arduino_DebugUtils, WiFi101, WiFiNINA, MKRGSM, MKRNB, MKRWAN
+architectures=samd,esp32,esp8266,mbed,megaavr,mbed_nano,mbed_portenta,mbed_nicla,mbed_opta,mbed_giga,renesas_portenta,renesas_uno,mbed_edge,stm32
+depends=Arduino_DebugUtils, WiFi101, WiFiNINA, MKRGSM, MKRNB, MKRWAN, Blues Wireless Notecard (>=1.6.0)

src/Arduino_ConnectionHandler.h

@@ -29,6 +29,10 @@
 #include <Arduino.h>
 #include "Arduino_ConnectionHandlerDefinitions.h"
 
+#if defined(USE_NOTECARD)
+  #include "Arduino_NotecardConnectionHandler.h"
+#else
+
 #if defined(BOARD_HAS_WIFI)
   #include "Arduino_WiFiConnectionHandler.h"
 #endif
@@ -57,4 +61,6 @@
   #include "Arduino_CellularConnectionHandler.h"
 #endif
 
+#endif // USE_NOTECARD
+
 #endif /* CONNECTION_HANDLER_H_ */

src/Arduino_ConnectionHandlerDefinitions.h

@@ -21,8 +21,16 @@
    INCLUDES
  ******************************************************************************/
 
+#if defined __has_include
+  #if __has_include (<Notecard.h>)
+    #define USE_NOTECARD
+  #endif
+#endif
+
 #include <Arduino.h>
 
+#ifndef USE_NOTECARD
+
 #ifdef ARDUINO_SAMD_MKR1000
   #define BOARD_HAS_WIFI
   #define NETWORK_HARDWARE_ERROR WL_NO_SHIELD
@@ -136,6 +144,8 @@
   #define NETWORK_HARDWARE_ERROR
 #endif
 
+#endif // USE_NOTECARD
+
 /******************************************************************************
    TYPEDEFS
  ******************************************************************************/
@@ -163,7 +173,8 @@ enum class NetworkAdapter {
   GSM,
   LORA,
   CATM1,
-  CELL
+  CELL,
+  NOTECARD
 };
 
 /******************************************************************************

src/Arduino_ConnectionHandlerInterface.h

@@ -48,16 +48,17 @@ class ConnectionHandler {
 
     NetworkConnectionState check();
 
-    #if defined(BOARD_HAS_WIFI) || defined(BOARD_HAS_GSM) || defined(BOARD_HAS_NB) || defined(BOARD_HAS_ETHERNET) || defined(BOARD_HAS_CATM1_NBIOT)
+    #if not defined(BOARD_HAS_LORA)
       virtual unsigned long getTime() = 0;
-      virtual Client &getClient() = 0;
-      virtual UDP &getUDP() = 0;
     #endif
 
-    #if defined(BOARD_HAS_LORA)
-      virtual int write(const uint8_t *buf, size_t size) = 0;
-      virtual int read() = 0;
+    #if defined(USE_NOTECARD) || defined(BOARD_HAS_LORA)
       virtual bool available() = 0;
+      virtual int read() = 0;
+      virtual int write(const uint8_t *buf, size_t size) = 0;
+    #else
+      virtual Client &getClient() = 0;
+      virtual UDP &getUDP() = 0;
     #endif
 
     NetworkConnectionState getStatus() __attribute__((deprecated)) {
@@ -87,7 +88,6 @@ class ConnectionHandler {
     virtual NetworkConnectionState update_handleDisconnecting() = 0;
     virtual NetworkConnectionState update_handleDisconnected () = 0;
 
-
   private:
 
     unsigned long _lastConnectionTickTime;

src/Arduino_NotecardConnectionHandler.cpp

@@ -0,0 +1,151 @@
+/*
+   This file is part of ArduinoIoTCloud.
+
+   Copyright 2019 ARDUINO SA (http://www.arduino.cc/)
+
+   This software is released under the GNU General Public License version 3,
+   which covers the main part of arduino-cli.
+   The terms of this license can be found at:
+   https://www.gnu.org/licenses/gpl-3.0.en.html
+
+   You can be released from the requirements of the above licenses by purchasing
+   a commercial license. Buying such a license is mandatory if you want to modify or
+   otherwise use the software for commercial activities involving the Arduino
+   software without disclosing the source code of your own applications. To purchase
+   a commercial license, send an email to license@arduino.cc.
+*/
+
+//TODO: Understand how `_keep_alive` is updated and used in the `ConnectionHandler` class
+
+#ifndef ARDUINO_NOTECARD_CONNECTION_HANDLER_H_
+#define ARDUINO_NOTECARD_CONNECTION_HANDLER_H_
+
+/******************************************************************************
+   INCLUDE
+ ******************************************************************************/
+
+#if defined(USE_NOTECARD) /* Only compile if the Notecard is present */
+
+#include <stdint.h>
+#include <Notecard.h>
+
+#include "Arduino_ConnectionHandlerInterface.h"
+
+/******************************************************************************
+   CLASS DECLARATION
+ ******************************************************************************/
+
+class NotecardConnectionHandler final : public ConnectionHandler
+{
+  public:
+    enum class TopicType : uint8_t {
+      Invalid = 0,
+      Command,
+      Thing,
+      Notehub = 255
+    };
+
+    typedef enum {
+      NOTECARD_ERROR_NONE                 = 0,
+      NOTECARD_ERROR_NO_DATA_AVAILABLE    = -1,
+      NOTECARD_ERROR_GENERIC              = -2,
+      HOST_ERROR_OUT_OF_MEMORY            = -3,
+    } NotecardCommunicationError;
+
+    static const uint32_t NOTEHUB_CONN_TIMEOUT_MS = 185000;
+
+    NotecardConnectionHandler(
+      const String & project_uid,
+      bool en_hw_int = false,
+      bool keep_alive = true,
+      uint32_t i2c_address = NOTE_I2C_ADDR_DEFAULT,
+      uint32_t i2c_max = NOTE_I2C_MAX_DEFAULT,
+      TwoWire & wire = Wire,
+      const String & notehub_url = ""
+    );
+
+    NotecardConnectionHandler(
+      const String & project_uid,
+      HardwareSerial & serial,
+      uint32_t speed = 9600,
+      bool en_hw_int = false,
+      bool keep_alive = true,
+      const String & notehub_url = ""
+    );
+
+    // Notehub Logging
+    inline int disableNotehubLogging (void) const
+    {
+      Debug.print(DBG_INFO, F("Disabling Notehub logging..."));
+      return notehubLogging(false);
+    }
+    inline int enableNotehubLogging (void) const
+    {
+      Debug.print(DBG_INFO, F("Enabling Notehub logging..."));
+      return notehubLogging(true);
+    }
+
+    // Accessors for Unique Hardware Identifiers
+    const String & getNotecardUid(void) const {
+      return _notecard_uid;
+    }
+
+    // Identify the target topic for R/W operations
+    TopicType getTopicType(void) const {
+      return _topic_type;
+    }
+    void setTopicType(TopicType topic) {
+      _topic_type = topic;
+    }
+
+    int setWiFiCredentials (const String & ssid, const String & pass);
+    const String & syncArduinoDeviceId (const String & device_id);
+    int syncSecretDeviceKey (const String & secret_device_key);
+
+    // ConnectionHandler interface
+    virtual bool available() override;
+    virtual unsigned long getTime() override;
+    virtual int read() override;
+    virtual int write(const uint8_t *buf, size_t size) override;
+
+  protected:
+
+    virtual NetworkConnectionState update_handleInit         () override;
+    virtual NetworkConnectionState update_handleConnecting   () override;
+    virtual NetworkConnectionState update_handleConnected    () override;
+    virtual NetworkConnectionState update_handleDisconnecting() override;
+    virtual NetworkConnectionState update_handleDisconnected () override;
+
+  private:
+
+    // Private members
+    HardwareSerial * _serial;
+    TwoWire * _wire;
+    uint8_t * _inbound_buffer;
+    uint32_t _conn_start_ms;
+    uint32_t _i2c_address;
+    uint32_t _i2c_max;
+    uint32_t _uart_speed;
+    uint32_t _inbound_buffer_index;
+    uint32_t _inbound_buffer_size;
+    bool _en_hw_int;
+    TopicType _topic_type;
+    Notecard _notecard;
+    String _device_id;
+    String _notecard_uid;
+    String _notehub_url;
+    String _project_uid;
+
+    // Private methods
+    bool armInterrupt (void) const;
+    bool configureConnection (bool connect) const;
+    uint_fast8_t connected (void) const;
+    J * getNote (bool pop = false) const;
+    int initiateNotehubSync (void) const;
+    int notehubLogging (bool enable) const;
+    bool updateUidCache (void);
+};
+
+#endif /* #ifdef USE_NOTECARD */
+
+#endif /* ARDUINO_NOTECARD_CONNECTION_HANDLER_H_ */