GenericConnectionhandler redesign of internal structures

examples/GenericConnectionHandlerDemo/GenericConnectionHandlerDemo.ino

@@ -0,0 +1,139 @@
+/* SECRET_ fields are in `arduino_secrets.h` (included below)
+ *
+ * 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_WIFI_SSID) and password (SECRET_WIFI_PASS) in the
+ * arduino_secrets.h file (or Secrets tab in Create Web Editor).
+ *
+ *    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
+ *
+ *    GSMConnectionHandler conMan(SECRET_PIN, SECRET_APN, SECRET_GSM_USER, SECRET_GSM_PASS);
+ *
+ * If using a MKR NB1500 you'll need a NBConnectionHandler object as follows
+ *
+ *    NBConnectionHandler conMan(SECRET_PIN);
+ *
+ * If using a Portenta + Ethernet shield you'll need a EthernetConnectionHandler object as follows:
+ *
+ * DHCP mode
+ *    EthernetConnectionHandler conMan;
+ *
+ * Manual configuration
+ *    EthernetConnectionHandler conMan(SECRET_IP, SECRET_DNS, SECRET_GATEWAY, SECRET_NETMASK);
+ *
+ * Manual configuration will fallback on DHCP mode if SECRET_IP is invalid or equal to INADDR_NONE.
+ *
+ */
+
+#include <GenericConnectionHandler.h>
+
+#include "arduino_secrets.h"
+
+#define CONN_TOGGLE_MS 60000
+
+#if !(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
+
+GenericConnectionHandler conMan;
+
+
+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); ) { }
+
+#ifndef __AVR__
+  /* 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);
+#endif
+
+  models::NetworkSetting setting = models::settingsDefault(NetworkAdapter::WIFI);
+
+  strcpy(setting.wifi.ssid, SECRET_WIFI_SSID);
+  strcpy(setting.wifi.pwd, SECRET_WIFI_PASS);
+
+  /* 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);
+
+  conMan.updateSetting(setting);
+  Serial.print("Network Adapter Interface: ");
+  switch (conMan.getInterface()) {
+    case NetworkAdapter::WIFI:
+      Serial.println("Wi-Fi");
+      break;
+    case NetworkAdapter::ETHERNET:
+      Serial.println("Ethernet");
+      break;
+    case NetworkAdapter::NB:
+      Serial.println("Narrowband");
+      break;
+    case NetworkAdapter::GSM:
+      Serial.println("GSM");
+      break;
+    case NetworkAdapter::LORA:
+      Serial.println("LoRa");
+      break;
+    case NetworkAdapter::CATM1:
+      Serial.println("Category M1");
+      break;
+    case NetworkAdapter::CELL:
+      Serial.println("Cellular");
+      break;
+    default:
+      Serial.println("Unknown");
+      break;
+  }
+}
+
+void loop() {
+  /* Toggle the connection every `CONN_TOGGLE_MS` milliseconds */
+  if ((millis() - lastConnToggleMs) > CONN_TOGGLE_MS) {
+    Serial.println("Toggling connection...");
+    if (attemptConnect) {
+      conMan.connect();
+    } else {
+      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 onNetworkConnect() {
+  Serial.println(">>>> CONNECTED to network");
+}
+
+void onNetworkDisconnect() {
+  Serial.println(">>>> DISCONNECTED from network");
+}
+
+void onNetworkError() {
+  Serial.println(">>>> ERROR");
+}

examples/GenericConnectionHandlerDemo/arduino_secrets.h

@@ -0,0 +1,19 @@
+// Required for WiFiConnectionHandler
+const char SECRET_WIFI_SSID[] = "SSID";
+const char SECRET_WIFI_PASS[] = "PASSWORD";
+
+// Required for GSMConnectionHandler
+const char SECRET_APN[]       = "MOBILE PROVIDER APN ADDRESS";
+const char SECRET_PIN[]       = "0000";  // Required for NBConnectionHandler
+const char SECRET_GSM_USER[]  = "GSM USERNAME";
+const char SECRET_GSM_PASS[]  = "GSM PASSWORD";
+
+// Required for LoRaConnectionHandler
+const char SECRET_APP_EUI[]  = "APP_EUI";
+const char SECRET_APP_KEY[]  = "APP_KEY";
+
+// Required for EthernetConnectionHandler (without DHCP mode)
+const char SECRET_IP[]       = "IP ADDRESS";
+const char SECRET_DNS[]      = "DNS ADDRESS";
+const char SECRET_GATEWAY[]  = "GATEWAY ADDRESS";
+const char SECRET_NETMASK[]  = "NETWORK MASK";

src/CatM1ConnectionHandler.cpp

@@ -28,16 +28,21 @@
    CTOR/DTOR
  ******************************************************************************/
 
-CatM1ConnectionHandler::CatM1ConnectionHandler(const char * pin, const char * apn, const char * login, const char * pass, RadioAccessTechnologyType rat, uint32_t band, bool const keep_alive)
+CatM1ConnectionHandler::CatM1ConnectionHandler()
+: ConnectionHandler(true, NetworkAdapter::CATM1) { }
+
+CatM1ConnectionHandler::CatM1ConnectionHandler(
+  const char * pin, const char * apn, const char * login, const char * pass,
+  RadioAccessTechnologyType rat, uint32_t band, bool const keep_alive)
 : ConnectionHandler{keep_alive, NetworkAdapter::CATM1}
-, _pin(pin)
-, _apn(apn)
-, _login(login)
-, _pass(pass)
-, _rat(rat)
-, _band(band)
 {
-
+  _settings.type = NetworkAdapter::CATM1;
+  strncpy(_settings.catm1.pin, pin, sizeof(_settings.catm1.pin)-1);
+  strncpy(_settings.catm1.apn, apn, sizeof(_settings.catm1.apn)-1);
+  strncpy(_settings.catm1.login, login, sizeof(_settings.catm1.login)-1);
+  strncpy(_settings.catm1.pass, pass, sizeof(_settings.catm1.pass)-1);
+  _settings.catm1.rat  = static_cast<uint8_t>(rat);
+  _settings.catm1.band = band;
 }
 
 /******************************************************************************
@@ -64,7 +69,13 @@ NetworkConnectionState CatM1ConnectionHandler::update_handleInit()
 
 NetworkConnectionState CatM1ConnectionHandler::update_handleConnecting()
 {
-  if(!GSM.begin(_pin, _apn, _login, _pass, _rat, _band))
+  if(!GSM.begin(
+    _settings.catm1.pin,
+    _settings.catm1.apn,
+    _settings.catm1.login,
+    _settings.catm1.pass,
+    static_cast<RadioAccessTechnologyType>(_settings.catm1.rat) ,
+    _settings.catm1.band))
   {
     Debug.print(DBG_ERROR, F("The board was not able to register to the network..."));
     return NetworkConnectionState::ERROR;

src/CatM1ConnectionHandler.h

@@ -40,6 +40,7 @@ class CatM1ConnectionHandler : public ConnectionHandler
 {
   public:
 
+    CatM1ConnectionHandler();
     CatM1ConnectionHandler(const char * pin, const char * apn, const char * login, const char * pass, RadioAccessTechnologyType rat = CATM1, uint32_t band = BAND_3 | BAND_20 | BAND_19, bool const keep_alive = true);
 
 
@@ -59,14 +60,6 @@ class CatM1ConnectionHandler : public ConnectionHandler
 
   private:
 
-    const char * _pin;
-    const char * _apn;
-    const char * _login;
-    const char * _pass;
-
-    RadioAccessTechnologyType _rat;
-    uint32_t _band;
-
     GSMUDP _gsm_udp;
     GSMClient _gsm_client;
 };

src/CellularConnectionHandler.cpp

@@ -21,14 +21,17 @@
 /******************************************************************************
    CTOR/DTOR
  ******************************************************************************/
+CellularConnectionHandler::CellularConnectionHandler()
+: ConnectionHandler(true, NetworkAdapter::CELL) {}
 
 CellularConnectionHandler::CellularConnectionHandler(const char * pin, const char * apn, const char * login, const char * pass, bool const keep_alive)
 : ConnectionHandler{keep_alive, NetworkAdapter::CELL}
-, _pin(pin)
-, _apn(apn)
-, _login(login)
-, _pass(pass)
 {
+  _settings.type = NetworkAdapter::CELL;
+  strncpy(_settings.cell.pin, pin, sizeof(_settings.cell.pin)-1);
+  strncpy(_settings.cell.apn, apn, sizeof(_settings.cell.apn)-1);
+  strncpy(_settings.cell.login, login, sizeof(_settings.cell.login)-1);
+  strncpy(_settings.cell.pass, pass, sizeof(_settings.cell.pass)-1);
 
 }
 
@@ -55,7 +58,7 @@ NetworkConnectionState CellularConnectionHandler::update_handleInit()
 {
   _cellular.begin();
   _cellular.setDebugStream(Serial);
-  if (String(_pin).length() > 0 && !_cellular.unlockSIM(_pin)) {
+  if (strlen(_settings.cell.pin) > 0 && !_cellular.unlockSIM(_settings.cell.pin)) {
     Debug.print(DBG_ERROR, F("SIM not present or wrong PIN"));
     return NetworkConnectionState::ERROR;
   }
@@ -64,7 +67,7 @@ NetworkConnectionState CellularConnectionHandler::update_handleInit()
 
 NetworkConnectionState CellularConnectionHandler::update_handleConnecting()
 {
-  if (!_cellular.connect(_apn, _login, _pass)) {
+  if (!_cellular.connect(String(_settings.cell.apn), String(_settings.cell.login), String(_settings.cell.pass))) {
     Debug.print(DBG_ERROR, F("The board was not able to register to the network..."));
     return NetworkConnectionState::ERROR;
   }

src/CellularConnectionHandler.h

@@ -33,7 +33,7 @@
 class CellularConnectionHandler : public ConnectionHandler
 {
   public:
-
+    CellularConnectionHandler();
     CellularConnectionHandler(const char * pin, const char * apn, const char * login, const char * pass, bool const keep_alive = true);
 
 
@@ -53,11 +53,6 @@ class CellularConnectionHandler : public ConnectionHandler
 
   private:
 
-    const char * _pin;
-    const char * _apn;
-    const char * _login;
-    const char * _pass;
-
     ArduinoCellular _cellular;
     TinyGsmClient _gsm_client = _cellular.getNetworkClient();
 };

src/ConnectionHandlerDefinitions.h

@@ -174,6 +174,7 @@ enum class NetworkConnectionEvent {
 };
 
 enum class NetworkAdapter {
+  NONE,
   WIFI,
   ETHERNET,
   NB,

src/ConnectionHandlerInterface.cpp

@@ -46,49 +46,69 @@ NetworkConnectionState ConnectionHandler::check()
   if((now - _lastConnectionTickTime) > connectionTickTimeInterval)
   {
     _lastConnectionTickTime = now;
-    NetworkConnectionState next_net_connection_state = _current_net_connection_state;
 
-    /* While the state machine is implemented here, the concrete implementation of the
-     * states is done in the derived connection handlers.
-     */
-    switch (_current_net_connection_state)
-    {
-      case NetworkConnectionState::INIT:          next_net_connection_state = update_handleInit         (); break;
-      case NetworkConnectionState::CONNECTING:    next_net_connection_state = update_handleConnecting   (); break;
-      case NetworkConnectionState::CONNECTED:     next_net_connection_state = update_handleConnected    (); break;
-      case NetworkConnectionState::DISCONNECTING: next_net_connection_state = update_handleDisconnecting(); break;
-      case NetworkConnectionState::DISCONNECTED:  next_net_connection_state = update_handleDisconnected (); break;
-      case NetworkConnectionState::ERROR:                                                                   break;
-      case NetworkConnectionState::CLOSED:                                                                  break;
-    }
+    NetworkConnectionState old_net_connection_state = _current_net_connection_state;
+    NetworkConnectionState next_net_connection_state = updateConnectionState();
 
     /* Here we are determining whether a state transition from one state to the next has
      * occurred - and if it has, we call eventually registered callbacks.
      */
-    if(next_net_connection_state != _current_net_connection_state)
-    {
-      /* Check the next state to determine the kind of state conversion which has occurred (and call the appropriate callback) */
-      if(next_net_connection_state == NetworkConnectionState::CONNECTED)
-      {
-        if(_on_connect_event_callback) _on_connect_event_callback();
-      }
-      if(next_net_connection_state == NetworkConnectionState::DISCONNECTED)
-      {
-        if(_on_disconnect_event_callback) _on_disconnect_event_callback();
-      }
-      if(next_net_connection_state == NetworkConnectionState::ERROR)
-      {
-        if(_on_error_event_callback) _on_error_event_callback();
-      }
-
-      /* Assign new state to the member variable holding the state */
+
+    if(old_net_connection_state != next_net_connection_state) {
+      updateCallback(next_net_connection_state);
+
+      /* It may happen that the local _current_net_connection_state
+       * is not updated by the updateConnectionState() call. This is the case for GenericConnection handler
+       * where the call of updateConnectionState() is replaced by the inner ConnectionHandler call
+       * that updates its state, but not the outer one. For this reason it is required to perform this call twice
+       */
       _current_net_connection_state = next_net_connection_state;
     }
   }
 
   return _current_net_connection_state;
 }
 
+NetworkConnectionState ConnectionHandler::updateConnectionState() {
+  NetworkConnectionState next_net_connection_state = _current_net_connection_state;
+
+  /* While the state machine is implemented here, the concrete implementation of the
+   * states is done in the derived connection handlers.
+   */
+  switch (_current_net_connection_state)
+  {
+    case NetworkConnectionState::INIT:          next_net_connection_state = update_handleInit         (); break;
+    case NetworkConnectionState::CONNECTING:    next_net_connection_state = update_handleConnecting   (); break;
+    case NetworkConnectionState::CONNECTED:     next_net_connection_state = update_handleConnected    (); break;
+    case NetworkConnectionState::DISCONNECTING: next_net_connection_state = update_handleDisconnecting(); break;
+    case NetworkConnectionState::DISCONNECTED:  next_net_connection_state = update_handleDisconnected (); break;
+    case NetworkConnectionState::ERROR:                                                                   break;
+    case NetworkConnectionState::CLOSED:                                                                  break;
+  }
+
+  /* Assign new state to the member variable holding the state */
+  _current_net_connection_state = next_net_connection_state;
+
+  return next_net_connection_state;
+}
+
+void ConnectionHandler::updateCallback(NetworkConnectionState next_net_connection_state) {
+
+  /* Check the next state to determine the kind of state conversion which has occurred (and call the appropriate callback) */
+  if(next_net_connection_state == NetworkConnectionState::CONNECTED)
+  {
+    if(_on_connect_event_callback) _on_connect_event_callback();
+  }
+  if(next_net_connection_state == NetworkConnectionState::DISCONNECTED)
+  {
+    if(_on_disconnect_event_callback) _on_disconnect_event_callback();
+  }
+  if(next_net_connection_state == NetworkConnectionState::ERROR)
+  {
+    if(_on_error_event_callback) _on_error_event_callback();
+  }
+}
+
 void ConnectionHandler::connect()
 {
   if (_current_net_connection_state != NetworkConnectionState::INIT && _current_net_connection_state != NetworkConnectionState::CONNECTING)