diff --git a/.github/workflows/compile-examples.yml b/.github/workflows/compile-examples.yml index 8e3d1e0..e467e73 100644 --- a/.github/workflows/compile-examples.yml +++ b/.github/workflows/compile-examples.yml @@ -29,11 +29,10 @@ jobs: # Install the NetworkConfigurator library from the repository - source-path: ./ - name: Arduino_DebugUtils - - source-url: https://github.com/fabik111/Arduino_ConnectionHandler.git - version: 54b93d64da130f653fb437819c22fb89b78732d0 - - source-url: https://github.com/arduino-libraries/ArduinoBLE.git - - source-url: https://github.com/arduino-libraries/Arduino_CloudUtils.git - - source-url: https://github.com/arduino-libraries/Arduino_KVStore.git + - name: Arduino_ConnectionHandler + - name: ArduinoBLE + - name: Arduino_CloudUtils + - name: Arduino_KVStore SKETCH_PATHS: | - examples/NetworkConfiguratorDemo SKETCHES_REPORTS_PATH: sketches-reports diff --git a/README.md b/README.md index 99f1827..0546307 100644 --- a/README.md +++ b/README.md @@ -1 +1,149 @@ -# Network Configurator \ No newline at end of file +# Network Configurator + +[![Check Arduino status](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/actions/workflows/check-arduino.yml/badge.svg)](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/actions/workflows/check-arduino.yml) +[![Compile Examples](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/workflows/Compile%20Examples/badge.svg)](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/actions?workflow=Compile+Examples) +[![Spell Check](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/workflows/Spell%20Check/badge.svg)](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/actions?workflow=Spell+Check) +[![Unit Tests](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/workflows/Unit%20Tests/badge.svg)](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/actions?workflow=Unit+Tests) + +This library enables the *remote* configuration of an [`Arduino_ConnectionHandler`](https://github.com/arduino-libraries/Arduino_ConnectionHandler) instance through the board's physical interfaces like "Bluetooth Low Energy (BLE)", Serial, etc.. +The provided network configuration is stored on persistent storage and loaded at the start up. + +The library offers mechanisms for wiping out the saved network configuration on the persistent storage. + +## Supported boards and configurable connectivity types matrix +|Boards | WiFi | Ethernet | GSM | NB-IoT | CAT-M1 | Cellular | LoRa | +|-------|:----:|:--------:|:---:|:------:|:------:|:--------:|:----:| +|[`UNO R4 WiFi`](https://store.arduino.cc/products/uno-r4-wifi) | X | | | | | | | +|[`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi) | X | X | | | | | | +|[`Portenta H7`](https://store.arduino.cc/portenta-h7) | X | X | | | X | X | | +|[`GIGA R1 WiFi`](https://store.arduino.cc/products/giga-r1-wifi)| X | | | | | | | +|[`Nicla Vision`](https://store.arduino.cc/products/nicla-vision)| X | | | | | | | +|[`Portenta C33`](https://store.arduino.cc/products/portenta-c33)| X | X | | | | | | +|[`Nano RP2040 Connect`](https://store.arduino.cc/products/arduino-nano-rp2040-connect)| X | | | | | | | +|[`Nano 33 IoT`](https://store.arduino.cc/arduino-nano-33-iot) | X | | | | | | | +|[`MKR WiFi 1010`](https://store.arduino.cc/arduino-mkr-wifi-1010)| X | | | | | | | + +## How to clean up the stored configuration + +The `NetworkConfigurator` library provides a way for wiping out the stored network settings and forcing +the restart of the BLE interface if turned off. + +The procedure: + +* `Arduino Opta`: press and hold the user button (`BTN_USER`) until the led (`LED_USER`) turns off +* `Arduino MKR WiFi 1010`: short the pin 7 to GND until the led turns off +* `Arduino GIGA R1 WiFi`: short the pin 7 to GND until the led turns off +* `Arduino Nano RP2040 Connect`: short the pin 2 to 3.3V until the led turns off +* Other boards: short the pin 2 to GND until the led turns off + +## Configurator Agents +The library provides a set of *Configurator Agents* that added as plug-in to the sketch handle the communication between the Arduino Network Configurator and an external client ([*Arduino IoT App*](https://cloud.arduino.cc/iot-remote-app/) and Arduino IoT Cloud) for configuring the board. + +Out-of-the box there are 2 Configurator Agents +* `BLEAgent`: manage the BLE interface +* `SerialAgent`: manage the Serial interface + +### Configurator Agents and supported board matrix +|Boards | BLEAgent | SerialAgent | +|-------|:----:|:--------:| +|[`UNO R4 WiFi`](https://store.arduino.cc/products/uno-r4-wifi) | X | X | +|[`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi) | X | X | +|[`Portenta H7`](https://store.arduino.cc/portenta-h7) | X | X | +|[`GIGA R1 WiFi`](https://store.arduino.cc/products/giga-r1-wifi)| X | X | +|[`Nicla Vision`](https://store.arduino.cc/products/nicla-vision)| X | X | +|[`Portenta C33`](https://store.arduino.cc/products/portenta-c33)| X | X | +|[`Nano RP2040 Connect`](https://store.arduino.cc/products/arduino-nano-rp2040-connect)| X | X | +|[`Nano 33 IoT`](https://store.arduino.cc/arduino-nano-33-iot) | X | X | +|[`MKR WiFi 1010`](https://store.arduino.cc/arduino-mkr-wifi-1010)| X | X | + +### How to enable a Configurator Agent +1. Include the *Configurator Agent* header file in the sketch ex.: `#include ` +2. Declare a global variable of the *agent* in the sketch ex.: `BLEAgentClass BLEAgent;` +3. Register the *agent* to the `NetworkConfigurator` ex.:`NetworkConfigurator.addAgent(BLEAgent);` + +## Storage + +The `NetworkConfigurator` needs a *persistent storage* for saving the provided network configuration. + +The user must specify a *storage library* in the sketch and pass it to the `NetworkConfigurator` as parameter. + +The user can use the [`Arduino_KVStore`](https://github.com/arduino-libraries/Arduino_KVStore) library as storage, otherwise he can implement his own custom storage library. + +The custom storage library must be based on a Key-Value storage system and must implement the interface `KVStoreInterface` of the [`Arduino_KVStore`](https://github.com/arduino-libraries/Arduino_KVStore) library + +### How to set the storage library +1. Include the header file of the *storage library* ex.: `#include ` +2. Declare the instance of the *storage manager* ex.: `KVStore kvstore;` +3. Register the storage manager instance to the `NetworkConfigurator` ex.: `NetworkConfigurator.setStorage(kvstore);` + +## How-to-use +1. Choose and include a *storage library* like [`Arduino_KVStore`](https://github.com/arduino-libraries/Arduino_KVStore) +2. Choose and include the *Configurator Agents* +3. Register the *storage library* and the *Configurator Agents* to the `NetworkConfigurator` + +``` +#include +#include +#include +#include +#include + +KVStore kvstore; +BLEAgentClass BLEAgent; +SerialAgentClass SerialAgent; +GenericConnectionHandler conMan; +NetworkConfiguratorClass NetworkConfigurator(conMan); + +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); ) { } + + /* 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); + + /* Set the KVStore */ + NetworkConfigurator.setStorage(kvstore); + /* Add the interfaces that are enabled for configuring the network*/ + NetworkConfigurator.addAgent(BLEAgent); + NetworkConfigurator.addAgent(SerialAgent); + + /* Start the network configurator */ + NetworkConfigurator.begin(); + +} + +void loop() { + /* + * Poll the networkConfigurator and check if connectionHandler is configured. + * If the ConnectionHandler has been configured, the following code keeps on + * running connection workflows on our allowing reconnection in case of failure + * and notification of connect/disconnect event if enabled. + * + * NOTE: any use of delay() within the loop or methods called from it will delay + * the execution of .update() and .check() methods of the NetworkConfigurator and + * ConnectionHandler objects which might not guarantee the correct functioning + * of the code. + */ + if(NetworkConfigurator.update() == NetworkConfiguratorStates::CONFIGURED) { + conMan.check(); + } +} + +void onNetworkConnect() { + Serial.println(">>>> CONNECTED to network"); +} + +void onNetworkDisconnect() { + Serial.println(">>>> DISCONNECTED from network"); +} + +void onNetworkError() { + Serial.println(">>>> ERROR"); +} +``` + +View the full example in the `example` folder. diff --git a/src/Arduino_NetworkConfigurator.h b/src/Arduino_NetworkConfigurator.h index ff1d1db..e22bf1c 100644 --- a/src/Arduino_NetworkConfigurator.h +++ b/src/Arduino_NetworkConfigurator.h @@ -13,7 +13,7 @@ #include "Arduino.h" #include "Arduino_ConnectionHandler.h" #include "configuratorAgents/AgentsManager.h" -#include +#include #include #include #include "utility/ResetInput.h" diff --git a/src/configuratorAgents/AgentsManager.cpp b/src/configuratorAgents/AgentsManager.cpp index 5d29311..71f8f34 100644 --- a/src/configuratorAgents/AgentsManager.cpp +++ b/src/configuratorAgents/AgentsManager.cpp @@ -10,7 +10,6 @@ #include #include -#include #include "AgentsManager.h" #include "NetworkOptionsDefinitions.h" #include "utility/LEDFeedback.h" diff --git a/src/configuratorAgents/MessagesDefinitions.h b/src/configuratorAgents/MessagesDefinitions.h index f79e888..2f2d460 100644 --- a/src/configuratorAgents/MessagesDefinitions.h +++ b/src/configuratorAgents/MessagesDefinitions.h @@ -9,7 +9,7 @@ #pragma once #include "Arduino.h" #include "NetworkOptionsDefinitions.h" -#include +#include #define MAX_UHWID_SIZE 32 #define MAX_JWT_SIZE 269 diff --git a/src/configuratorAgents/agents/ConfiguratorAgent.h b/src/configuratorAgents/agents/ConfiguratorAgent.h index 32cd731..0b44863 100644 --- a/src/configuratorAgents/agents/ConfiguratorAgent.h +++ b/src/configuratorAgents/agents/ConfiguratorAgent.h @@ -7,7 +7,6 @@ */ #pragma once -#include "settings/settings.h" #include "configuratorAgents/NetworkOptionsDefinitions.h" #include "configuratorAgents/MessagesDefinitions.h" #include "Arduino.h" diff --git a/src/configuratorAgents/agents/boardConfigurationProtocol/CBORAdapter.cpp b/src/configuratorAgents/agents/boardConfigurationProtocol/CBORAdapter.cpp index 456a163..96fcbf5 100644 --- a/src/configuratorAgents/agents/boardConfigurationProtocol/CBORAdapter.cpp +++ b/src/configuratorAgents/agents/boardConfigurationProtocol/CBORAdapter.cpp @@ -11,7 +11,6 @@ #include "CBORAdapter.h" #include "cbor/MessageEncoder.h" #include "cbor/MessageDecoder.h" -#include bool CBORAdapter::uhwidToCBOR(const byte *uhwid, uint8_t *data, size_t *len) { CBORMessageEncoder encoder; diff --git a/src/configuratorAgents/agents/boardConfigurationProtocol/CBORAdapter.h b/src/configuratorAgents/agents/boardConfigurationProtocol/CBORAdapter.h index 88fc856..09aeef8 100644 --- a/src/configuratorAgents/agents/boardConfigurationProtocol/CBORAdapter.h +++ b/src/configuratorAgents/agents/boardConfigurationProtocol/CBORAdapter.h @@ -9,7 +9,7 @@ #pragma once #include "Arduino.h" #include "configuratorAgents/MessagesDefinitions.h" -#include "settings/settings.h" +#include #include "cbor/CBOR.h" #include "./cbor/CBOR.h" diff --git a/src/configuratorAgents/agents/boardConfigurationProtocol/cbor/Decoder.cpp b/src/configuratorAgents/agents/boardConfigurationProtocol/cbor/Decoder.cpp index df6e657..bac0846 100644 --- a/src/configuratorAgents/agents/boardConfigurationProtocol/cbor/Decoder.cpp +++ b/src/configuratorAgents/agents/boardConfigurationProtocol/cbor/Decoder.cpp @@ -9,7 +9,7 @@ #if NETWORK_CONFIGURATOR_COMPATIBLE #include "Decoder.h" -#include +#include #if defined(BOARD_HAS_ETHERNET) #include #endif diff --git a/src/configuratorAgents/agents/boardConfigurationProtocol/cbor/ProvisioningMessage.h b/src/configuratorAgents/agents/boardConfigurationProtocol/cbor/ProvisioningMessage.h index 97387d5..240a7b5 100644 --- a/src/configuratorAgents/agents/boardConfigurationProtocol/cbor/ProvisioningMessage.h +++ b/src/configuratorAgents/agents/boardConfigurationProtocol/cbor/ProvisioningMessage.h @@ -11,7 +11,7 @@ #include #include #include -#include +#include #include #define UHWID_SIZE 32