Repository files navigation

This library enables theremote configuration of anArduino_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.

TheNetworkConfigurator library provides a way for wiping out the stored network settings and forcingthe 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
• Arduino Portenta H7: short the pin 0 to GND until the led turns off
• Arduino Portenta C33: short the pin 0 to GND until the led turns off
• Other boards: short the pin 2 to GND until the led turns off
• Portenta Machine Control: currently the reset procedure is not available

Internally, the pin indicated in the procedure is set asINPUT_PULLUP (except forArduino Opta ) and it's attached to an ISR fired on every change of the pin's status.

In order to be notified when the ISR is fired, it's possible to register a callback function using the functionNetworkConfigurator.addReconfigurePinCallback(callback). Please take the example as reference.

In order to change the default pin for resetting the board, it's possible to use the functionNetworkConfigurator.setReconfigurePin(your_pin) specifying the new pin.The pin must be in the list of digital pins usable for interrupts. Please refer to the Arduino documentation for more details:https://docs.arduino.cc/language-reference/en/functions/external-interrupts/attachInterrupt/

In order to disable the reconfiguration procedure, use this function in the sketchNetworkConfigurator.setReconfigurePin(DISABLE_PIN)

The library provides a set ofConfigurator Agents that added as plug-in to the sketch handle the communication between the Arduino Network Configurator and an external client (Arduino IoT 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

1. Include theConfigurator Agent header file in the sketch ex.:#include <configuratorAgents/agents/BLEAgent.h>
2. Declare a global variable of theagent in the sketch ex.:BLEAgentClass BLEAgent;
3. Register theagent to theNetworkConfigurator ex.:NetworkConfigurator.addAgent(BLEAgent);

TheNetworkConfigurator needs apersistent storage for saving the provided network configuration.

The user must specify astorage library in the sketch and pass it to theNetworkConfigurator as parameter.

The user can use theArduino_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 interfaceKVStoreInterface of theArduino_KVStore library

1. Include the header file of thestorage library ex.:#include <Arduino_KVStore.h>
2. Declare the instance of thestorage manager ex.:KVStore kvstore;
3. Register the storage manager instance to theNetworkConfigurator ex.:NetworkConfigurator.setStorage(kvstore);

1. Choose and include astorage library likeArduino_KVStore
2. Choose and include theConfigurator Agents
3. Register thestorage library and theConfigurator Agents to theNetworkConfigurator

#include <GenericConnectionHandler.h>#include <Arduino_KVStore.h>#include <Arduino_NetworkConfigurator.h>#include <configuratorAgents/agents/BLEAgent.h>#include <configuratorAgents/agents/SerialAgent.h>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 theexample folder.