Skip to content

Commit 3fd301c

Browse files
fabik111fabik111
committed
add README.md
1 parent 9ab5500 commit 3fd301c

File tree

1 file changed

+149
-1
lines changed

1 file changed

+149
-1
lines changed

‎README.md‎

Lines changed: 149 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,149 @@
1-
# Network Configurator
1+
# Network Configurator
2+
3+
[![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)
4+
[![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)
5+
[![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)
6+
[![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)
7+
8+
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..
9+
The provided network configuration is stored on persistent storage and loaded at the start up.
10+
11+
The library offers mechanisms for wiping out the saved network configuration on the persistent storage.
12+
13+
## Supported boards and configurable connectivity types matrix
14+
|Boards | WiFi | Ethernet | GSM | NB-IoT | CAT-M1 | Cellular | LoRa |
15+
|-------|:----:|:--------:|:---:|:------:|:------:|:--------:|:----:|
16+
|[`UNO R4 WiFi`](https://store.arduino.cc/products/uno-r4-wifi) | X | | | | | | |
17+
|[`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi) | X | X | | | | | |
18+
|[`Portenta H7`](https://store.arduino.cc/portenta-h7) | X | X | | | X | X | |
19+
|[`GIGA R1 WiFi`](https://store.arduino.cc/products/giga-r1-wifi)| X | | | | | | |
20+
|[`Nicla Vision`](https://store.arduino.cc/products/nicla-vision)| X | | | | | | |
21+
|[`Portenta C33`](https://store.arduino.cc/products/portenta-c33)| X | X | | | | | |
22+
|[`Nano RP2040 Connect`](https://store.arduino.cc/products/arduino-nano-rp2040-connect)| X | | | | | | |
23+
|[`Nano 33 IoT`](https://store.arduino.cc/arduino-nano-33-iot) | X | | | | | | |
24+
|[`MKR WiFi 1010`](https://store.arduino.cc/arduino-mkr-wifi-1010)| X | | | | | | |
25+
26+
## How to clean up the stored configuration
27+
28+
The `NetworkConfigurator` library provides a way for wiping out the stored network settings and forcing
29+
the restart of the BLE interface if turned off.
30+
31+
The procedure:
32+
33+
* `Arduino Opta`: press and hold the user button (`BTN_USER`) until the led (`LED_USER`) turns off
34+
* `Arduino MKR WiFi 1010`: short the pin 7 to GND until the led turns off
35+
* `Arduino GIGA R1 WiFi`: short the pin 7 to GND until the led turns off
36+
* `Arduino Nano RP2040 Connect`: short the pin 2 to 3.3V until the led turns off
37+
* Other boards: short the pin 2 to GND until the led turns off
38+
39+
## Configurator Agents
40+
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.
41+
42+
Out-of-the box there are 2 Configurator Agents
43+
* `BLEAgent`: manage the BLE interface
44+
* `SerialAgent`: manage the Serial interface
45+
46+
### Configurator Agents and supported board matrix
47+
|Boards | BLEAgent | SerialAgent |
48+
|-------|:----:|:--------:|
49+
|[`UNO R4 WiFi`](https://store.arduino.cc/products/uno-r4-wifi) | X | X |
50+
|[`OPTA WiFi`](https://store.arduino.cc/products/opta-wifi) | X | X |
51+
|[`Portenta H7`](https://store.arduino.cc/portenta-h7) | X | X |
52+
|[`GIGA R1 WiFi`](https://store.arduino.cc/products/giga-r1-wifi)| X | X |
53+
|[`Nicla Vision`](https://store.arduino.cc/products/nicla-vision)| X | X |
54+
|[`Portenta C33`](https://store.arduino.cc/products/portenta-c33)| X | X |
55+
|[`Nano RP2040 Connect`](https://store.arduino.cc/products/arduino-nano-rp2040-connect)| X | X |
56+
|[`Nano 33 IoT`](https://store.arduino.cc/arduino-nano-33-iot) | X | X |
57+
|[`MKR WiFi 1010`](https://store.arduino.cc/arduino-mkr-wifi-1010)| X | X |
58+
59+
### How to enable a Configurator Agent
60+
1. Include the *Configurator Agent* header file in the sketch ex.: `#include <configuratorAgents/agents/BLEAgent.h>`
61+
2. Declare a global variable of the *agent* in the sketch ex.: `BLEAgentClass BLEAgent;`
62+
3. Register the *agent* to the `NetworkConfigurator` ex.:`NetworkConfigurator.addAgent(BLEAgent);`
63+
64+
## Storage
65+
66+
The `NetworkConfigurator` needs a *persistent storage* for saving the provided network configuration.
67+
68+
The user must specify a *storage library* in the sketch and pass it to the `NetworkConfigurator` as parameter.
69+
70+
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.
71+
72+
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
73+
74+
### How to set the storage library
75+
1. Include the header file of the *storage library* ex.: `#include <Arduino_KVStore.h>`
76+
2. Declare the instance of the *storage manager* ex.: `KVStore kvstore;`
77+
3. Register the storage manager instance to the `NetworkConfigurator` ex.: `NetworkConfigurator.setStorage(kvstore);`
78+
79+
## How-to-use
80+
1. Choose and include a *storage library* like [`Arduino_KVStore`](https://github.com/arduino-libraries/Arduino_KVStore)
81+
2. Choose and include the *Configurator Agents*
82+
3. Register the *storage library* and the *Configurator Agents* to the `NetworkConfigurator`
83+
84+
```
85+
#include <GenericConnectionHandler.h>
86+
#include <Arduino_KVStore.h>
87+
#include <Arduino_NetworkConfigurator.h>
88+
#include <configuratorAgents/agents/BLEAgent.h>
89+
#include <configuratorAgents/agents/SerialAgent.h>
90+
91+
KVStore kvstore;
92+
BLEAgentClass BLEAgent;
93+
SerialAgentClass SerialAgent;
94+
GenericConnectionHandler conMan;
95+
NetworkConfiguratorClass NetworkConfigurator(conMan);
96+
97+
void setup() {
98+
/* Initialize serial debug port and wait up to 5 seconds for port to open */
99+
Serial.begin(9600);
100+
for(unsigned long const serialBeginTime = millis(); !Serial && (millis() - serialBeginTime <= 5000); ) { }
101+
102+
/* Add callbacks to the ConnectionHandler object to get notified of network
103+
* connection events. */
104+
conMan.addCallback(NetworkConnectionEvent::CONNECTED, onNetworkConnect);
105+
conMan.addCallback(NetworkConnectionEvent::DISCONNECTED, onNetworkDisconnect);
106+
conMan.addCallback(NetworkConnectionEvent::ERROR, onNetworkError);
107+
108+
/* Set the KVStore */
109+
NetworkConfigurator.setStorage(kvstore);
110+
/* Add the interfaces that are enabled for configuring the network*/
111+
NetworkConfigurator.addAgent(BLEAgent);
112+
NetworkConfigurator.addAgent(SerialAgent);
113+
114+
/* Start the network configurator */
115+
NetworkConfigurator.begin();
116+
117+
}
118+
119+
void loop() {
120+
/*
121+
* Poll the networkConfigurator and check if connectionHandler is configured.
122+
* If the ConnectionHandler has been configured, the following code keeps on
123+
* running connection workflows on our allowing reconnection in case of failure
124+
* and notification of connect/disconnect event if enabled.
125+
*
126+
* NOTE: any use of delay() within the loop or methods called from it will delay
127+
* the execution of .update() and .check() methods of the NetworkConfigurator and
128+
* ConnectionHandler objects which might not guarantee the correct functioning
129+
* of the code.
130+
*/
131+
if(NetworkConfigurator.update() == NetworkConfiguratorStates::CONFIGURED) {
132+
conMan.check();
133+
}
134+
}
135+
136+
void onNetworkConnect() {
137+
Serial.println(">>>> CONNECTED to network");
138+
}
139+
140+
void onNetworkDisconnect() {
141+
Serial.println(">>>> DISCONNECTED from network");
142+
}
143+
144+
void onNetworkError() {
145+
Serial.println(">>>> ERROR");
146+
}
147+
```
148+
149+
View the full example in the `example` folder.

0 commit comments

Comments
 (0)