Network Configurator

This library enables the remote configuration of an 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	X
OPTA WiFi	X	X
Portenta H7	X	X			X	X
GIGA R1 WiFi	X
Nicla Vision	X
Portenta C33	X	X
Nano RP2040 Connect	X
Nano 33 IoT	X
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 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	X	X
OPTA WiFi	X	X
Portenta H7	X	X
GIGA R1 WiFi	X	X
Nicla Vision	X	X
Portenta C33	X	X
Nano RP2040 Connect	X	X
Nano 33 IoT	X	X
MKR WiFi 1010	X	X

How to enable a Configurator Agent

1. Include the Configurator Agent header file in the sketch ex.: #include <configuratorAgents/agents/BLEAgent.h>
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 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 library

How to set the storage library

1. Include the header file of the storage library ex.: #include <Arduino_KVStore.h>
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
2. Choose and include the Configurator Agents
3. Register the storage library and the Configurator Agents to the NetworkConfigurator

#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 the example folder.