Skip to content

Commit 8331d93

Browse files
BenjaminDannegardBenjaminDannegard
committed
Fixed new sections
1 parent 35168c6 commit 8331d93

File tree

2 files changed

+223
-32
lines changed
  • content/arduino-cloud

2 files changed

+223
-32
lines changed

‎content/arduino-cloud/02.hardware/06.device-provisioning/content.md‎

Lines changed: 16 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -135,23 +135,23 @@ To proceed with the next steps, the cloud-generated sketch must be uploaded to t
135135

136136
### Update Using the BLE Interface
137137

138-
Ensure that the cloud sketch has enabled the "BLEAgent" in the cloud sketch, via "thingProperties.h". Check [this document](https://docs.arduino.cc/arduino-cloud/cloud-interface/sketches) for enabling it.
138+
Ensure that the cloud sketch has enabled the "BLEAgent" in the cloud sketch, via "thingProperties.h". This is enabled by default if the board has been registered with Provisioning 2.0. If you need to enable it, please have a look at [this documentation](https://docs.arduino.cc/arduino-cloud/cloud-interface/sketches).
139139

140-
You can update the Network settings from the detail page of the device in the Arduino Cloud Web UI or the mobile app.
140+
You can update the network settings from the detail page of the device on the Arduino Cloud webpage or the mobile app.
141141

142142
During this process you will be asked to wipe out the current network configuration to restart the board's BLE interface.
143143

144-
- Turn on the board.
144+
- Power on the board.
145145

146-
- Open the devices page of the Mobile App or the Arduino Cloud Web UI.
146+
- Reset the board using the method of your board. Have a look at the [How to set up the Reconfiguration Procedure](#How-to-set-up-the Reconfiguration-Procedure) section of this article to find the default board reset pin. If you have changed the reset pin from the default one, please use that.
147+
148+
- Open the devices page of the Mobile App or the Arduino Cloud webpage.
147149

148150
- Click on the device you want to update the network settings for.
149151

150152
- Click on the "change" button by the network section.
151153

152-
- If you are using the Arduino Cloud Web UI, select the BLE method.
153-
154-
- Reset the board using the procedure of your board. In this article, the default reset pin is used. If you have chosen a different pin, please use that. Review the section of the document about the default board reset pin [here](#How to set up the Reconfiguration Procedure).
154+
- If you are using the Arduino Cloud webpage, select the BLE method.
155155

156156
- The board will reboot, and you will see the LED pulsing.
157157

@@ -163,31 +163,22 @@ During this process you will be asked to wipe out the current network configurat
163163

164164
### Update Using the Serial Interface
165165

166-
Ensure that the "SerialAgent" is enabled in the cloud sketch, via "thingProperties.h".
167-
168-
Check [this document](https://docs.arduino.cc/arduino-cloud/cloud-interface/sketches) for enabling it.
166+
Ensure that the "SerialAgent" is enabled in the cloud sketch, via "thingProperties.h". This is enabled by default if the board has been registered with Provisioning 2.0. If you need to enable it, please have a look at [this documentation](https://docs.arduino.cc/arduino-cloud/cloud-interface/sketches).
169167

170-
You can run this procedure only with the Arduino Cloud Web UI
168+
This method only works with the Arduino Cloud website. You can update the network settings from the detail page of the board on the webpage. The Serial interface, if enabled, is always ready to receive a new configuration.
171169

172-
- You can update the network settings from the detail page of the board of the Web UI.
170+
- Turn on the board and connect it to your PC using a USB cable.
173171

174-
- The Serial interface, if enabled, is always ready to receive a new configuration.
175-
176-
- Turn on the board and connect to your PC using the USB cable.
177-
178-
- Open the devices page on the Arduino Cloud Web UI.
172+
- Open the devices page on the Arduino Cloud webpage.
179173

180174
- Click on the board you want to update the network settings for.
181175

182176
- Click on the "change" button by the network section.
183177

184-
- Connect to the board.
185-
186-
- Inputs the new configuration.
178+
- Input the new network configuration.
187179

188180
- The board will validate it, and if correct, it will close the connection.
189181

190-
191182
## How to delete a stored network configuration
192183

193184
If you want to delete the stored network configuration without updating it, there are two possible methods to do so.
@@ -196,17 +187,13 @@ If you want to delete the stored network configuration without updating it, ther
196187

197188
To proceed with the next steps, the cloud-generated sketch must be uploaded to the board.
198189

199-
Reset the board using the procedure of your board.
200-
201-
In this article, the default reset pin is used. If you had chosen a different pin, please use yours.
202-
203-
Review the section of the document about the default board reset pin here.
190+
Reset the board using the method of your board. Have a look at the [How to set up the Reconfiguration Procedure](#How-to-set-up-the Reconfiguration-Procedure) section of this article to find the default board reset pin. If you have changed the reset pin from the default one, please use that.
204191

205192
### Using the DeleteConfiguration sketch
206193

207-
Upload this sketch to delete your configuration.
194+
Open Arduino IDE and on the left side open the **library manager**. Search for **Arduino_NetworkConfigurator** and download it. Once it is downloaded go to **File > Examples > Arduino_NetworkConfigurator > Utility > DeleteConfiguration**, this will open a new example sketch. Select your board and port then upload this example sketch to your board. When the sketch has been uploaded you can look at the serial monitor to monitor the progress and troubleshoot if needed.
208195

209-
Please confirm the choice for starting the procedure
196+
The sketch can also be found [here.](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/blob/main/examples/utility/DeleteConfiguration/DeleteConfiguration.ino)
210197

211198
### How to set up the Reconfiguration Procedure
212199

@@ -223,6 +210,4 @@ The library provides a default implementation according to the board type. (The
223210
- `Arduino Portenta H7`: Short pin 0 to GND until the led turns off
224211
- `Arduino Portenta C33`: Short pin 0 to GND until the led turns off
225212
- `Other boards`: Short pin 2 to GND until the led turns off
226-
- `Portenta Machine Control`: Currently the reset procedure is not available
227-
228-
Open Arduino IDE and on the left side open the **library manager**. Search for **Arduino_NetworkConfigurator** and download it. Once it is downloaded go to **File > Examples > Arduino_NetworkConfigurator > Utility > DeleteConfiguration**, this will open a new example sketch. Select your board and port then upload this example sketch to your board. When the sketch has been uploaded you can look at the serial monitor to monitor the progress and troubleshoot if needed.
213+
- `Portenta Machine Control`: Currently the reset procedure is not available

‎content/arduino-cloud/03.cloud-interface/00.sketches/sketches.md‎

Lines changed: 207 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,213 @@ The "Secret" File contains your secret credentials, such as Wi-Fi® network SSID
129129

130130
This file will be visible as a "Secret" tab in the Cloud Editor and is named `arduino_secrets.h`, which is not visible on the Cloud platform.
131131

132-
Note that if you are using the offline IDE / Arduino CLI, you will need to manually create this file. More information is in the **Offline Sketches section** just below.
132+
Note that if you are using the offline IDE / Arduino CLI, you will need to manually create this file. More information is in the **Offline Sketches section**.
133+
134+
135+
136+
## thingsProperties.h and the NetworkConfigurator
137+
138+
The thingProperties.h file plays a key role in managing credential capabilities, including the NetworkConfigurator, which enables two main features:
139+
140+
- Credentials stored on NVS: Boards can now securely store network settings in Non-Volatile Storage (NVS), removing them from the sketch (secrets.h).
141+
142+
- Over-the-Air (OTA) communication: Enables the possibility to provide network settings configuration via Bluetooth (BLE)
143+
144+
The thingProperties.h will be generated accordingly to the provisioning mechanism, so if the board has been registered using the provisioning 2.0, automatically the thingProperties.h file will have the NetworkConfigurator component enabled.
145+
146+
A board registered with Provisioning 2.0 includes Arduino_NetworkConfigurator.h in the generated thingProperties.h.
147+
148+
### How the NetworkConfigurator works
149+
150+
To work, the NetworkConfigurator needs:
151+
152+
- One or more Configurator Agents: Objects that handle the communication between the board and the user device (PC, laptop, or Mobile phone). The NetworkConfigurator library out-of-the-box provides two Agents:
153+
154+
- BLEAgent for handling the BLE communication
155+
156+
- SerialAgents for the Serial communication.
157+
158+
- A Key-Value Storage library: the NetworkConfigurator needs an external storage library that implements the KVStoreInterface. Arduino provides the Arduino_KVStore library for handling the storage and saving the NetworkConfigurator configurations.
159+
160+
- A ConnectionHandler: the object responsible for the board’s Internet connection management
161+
162+
### thingsProperties.h
163+
Here is how the thingsProperties.h file changes to set up the NetworkConfigurator.
164+
165+
### Default setup
166+
This setup is automatically generated if the board has been registered with Provisioning 2.0.
167+
168+
Do not try if the board has not been registered with the Provisioning 2.0
169+
170+
Automatically, both the SeralAgent and the BLEAgent are enabled
171+
172+
Libraries and object declarations
173+
The following libraries are automatically included:
174+
175+
Arduino_NetworkConfigurator library
176+
177+
BLEAgent.h and SerialAgent.h
178+
179+
The objects declared:
180+
181+
kvStore: for handling the NVM operations
182+
183+
BLEAgent for handling the BLE interface
184+
185+
SerialAgent: for handling the Serial Interface
186+
187+
NetworkConfigurator: the networkConfigurator instance
188+
189+
190+
```arduino
191+
#include <ArduinoIoTCloud.h>
192+
#include <Arduino_ConnectionHandler.h>
193+
#include <Arduino_NetworkConfigurator.h>
194+
#include <configuratorAgents/agents/BLEAgent.h>
195+
#include <configuratorAgents/agents/SerialAgent.h>
196+
void onVariableChange();
197+
int variable;
198+
KVStore kvStore;
199+
BLEAgentClass BLEAgent;
200+
SerialAgentClass SerialAgent;
201+
WiFiConnectionHandler ArduinoIoTPreferredConnection;
202+
NetworkConfiguratorClass NetworkConfigurator(ArduinoIoTPreferredConnection);
203+
```
204+
205+
### initProperties()
206+
In the initProperties function, the following instructions are added:
207+
208+
NetworkConfigurator.addAgent(BLEAgent); For enabling the BLEAgent
209+
210+
NetworkConfigurator.addAgent(SerialAgent); For enabling the SerialAgent
211+
212+
NetworkConfigurator.setStorage(kvStore); For setting the KVStore
213+
214+
ArduinoCloud.setConfigurator(NetworkConfigurator); For embedding the NetworkConfigurator in the ArduinoCloud
215+
216+
```arduino
217+
NetworkConfigurator.addAgent(BLEAgent);
218+
NetworkConfigurator.addAgent(SerialAgent);
219+
NetworkConfigurator.setStorage(kvStore);
220+
ArduinoCloud.setConfigurator(NetworkConfigurator);
221+
```
222+
223+
The final thingProperties.h file:
224+
225+
```arduino
226+
#include <ArduinoIoTCloud.h>
227+
#include <Arduino_ConnectionHandler.h>
228+
#include <Arduino_NetworkConfigurator.h>
229+
#include <configuratorAgents/agents/BLEAgent.h>
230+
#include <configuratorAgents/agents/SerialAgent.h>
231+
void onVariableChange();
232+
int variable;
233+
KVStore kvStore;
234+
BLEAgentClass BLEAgent;
235+
SerialAgentClass SerialAgent;
236+
WiFiConnectionHandler ArduinoIoTPreferredConnection;
237+
NetworkConfiguratorClass NetworkConfigurator(ArduinoIoTPreferredConnection);
238+
void initProperties(){
239+
NetworkConfigurator.addAgent(BLEAgent);
240+
NetworkConfigurator.addAgent(SerialAgent);
241+
NetworkConfigurator.setStorage(kvStore);
242+
ArduinoCloud.setConfigurator(NetworkConfigurator);
243+
// For changing the default reset pin (2) uncomment and set your preferred pin. Use DISABLE_PIN for disabling the reset procedure.
244+
// NetworkConfigurator.setReconfigurePin(YOUR_PIN);
245+
ArduinoCloud.addProperty(variable, READWRITE, ON_CHANGE, onVariableChange);
246+
}
247+
```
248+
249+
### Disable the BLEAgent
250+
251+
To save board storage and memory, after the provisioning, the BLEAgent can be removed. ~30KB of storage and ~ 2KB of memory are saved for BSS and Data.
252+
253+
The network credentials provided in the provisioning phase can no longer be changed via Bluetooth
254+
255+
To disable the BLEAgent, just comment out or remove the lines of code that include, declare, and enable it.
256+
257+
The final result should be the following:
258+
259+
```arduino
260+
#include <ArduinoIoTCloud.h>
261+
#include <Arduino_ConnectionHandler.h>
262+
#include <Arduino_NetworkConfigurator.h>
263+
//#include <configuratorAgents/agents/BLEAgent.h>
264+
#include <configuratorAgents/agents/SerialAgent.h>
265+
void onVariableChange();
266+
int variable;
267+
KVStore kvStore;
268+
//BLEAgentClass BLEAgent;
269+
SerialAgentClass SerialAgent;
270+
WiFiConnectionHandler ArduinoIoTPreferredConnection;
271+
NetworkConfiguratorClass NetworkConfigurator(ArduinoIoTPreferredConnection);
272+
void initProperties(){
273+
// NetworkConfigurator.addAgent(BLEAgent);
274+
NetworkConfigurator.addAgent(SerialAgent);
275+
NetworkConfigurator.setStorage(kvStore);
276+
ArduinoCloud.setConfigurator(NetworkConfigurator);
277+
// For changing the default reset pin (2) uncomment and set your preferred pin. Use DISABLE_PIN for disabling the reset procedure.
278+
// NetworkConfigurator.setReconfigurePin(YOUR_PIN);
279+
ArduinoCloud.addProperty(variable, READWRITE, ON_CHANGE, onVariableChange);
280+
}
281+
```
282+
283+
### Disable the SerialAgent
284+
285+
To save board storage and memory, after the provisioning, the SerialAgent can be removed. ~1KB of storage is saved for BSS and Data
286+
287+
The network credentials provided in the provisioning phase can no longer be changed via USB
288+
289+
To disable the SerialAgent, just comment out or remove the lines of code that include, declare, and enable it.
290+
291+
The final result should be the following:
292+
293+
```arduino
294+
#include <ArduinoIoTCloud.h>
295+
#include <Arduino_ConnectionHandler.h>
296+
#include <Arduino_NetworkConfigurator.h>
297+
#include <configuratorAgents/agents/BLEAgent.h>
298+
//#include <configuratorAgents/agents/SerialAgent.h>
299+
void onVariableChange();
300+
int variable;
301+
KVStore kvStore;
302+
BLEAgentClass BLEAgent;
303+
//SerialAgentClass SerialAgent;
304+
WiFiConnectionHandler ArduinoIoTPreferredConnection;
305+
NetworkConfiguratorClass NetworkConfigurator(ArduinoIoTPreferredConnection);
306+
void initProperties(){
307+
NetworkConfigurator.addAgent(BLEAgent);
308+
// NetworkConfigurator.addAgent(SerialAgent);
309+
NetworkConfigurator.setStorage(kvStore);
310+
ArduinoCloud.setConfigurator(NetworkConfigurator);
311+
// For changing the default reset pin (2) uncomment and set your preferred pin. Use DISABLE_PIN for disabling the reset procedure.
312+
// NetworkConfigurator.setReconfigurePin(YOUR_PIN);
313+
ArduinoCloud.addProperty(variable, READWRITE, ON_CHANGE, onVariableChange);
314+
}
315+
```
316+
317+
### Disable the NetworkConfigurator
318+
319+
To save board storage and memory, after the provisioning, the NetworkConfigurator can be removed. ~40KB of storage and ~ 2,9KB of memory are saved for BSS and Data.
320+
321+
In this setup, the only way to handle network settings is to return to using the secrets declared in secrets.h file. This can be done manually by adding the secrets.h file with the defines needed.
322+
323+
In order to change the network settings, you must flash your sketch with the updated network settings in the secrets.h file. The network settings can no longer be updated using the Arduino Cloud WebUI or the mobile app.
324+
325+
The final result should be the following (thingProperties.h file):
326+
327+
```arduino
328+
#include <ArduinoIoTCloud.h>
329+
#include <Arduino_ConnectionHandler.h>
330+
const char SSID[] = SECRET_SSID; // Network SSID (name)
331+
const char PASS[] = SECRET_OPTIONAL_PASS; // Network password (use for WPA, or use as key for WEP)
332+
void onVariableChange();
333+
int variable;
334+
WiFiConnectionHandler ArduinoIoTPreferredConnection(SECRET_SSID, SECRET_OPTIONAL_PASS);
335+
void initProperties(){
336+
ArduinoCloud.addProperty(variable, READWRITE, ON_CHANGE, onVariableChange);
337+
}
338+
```
133339

134340
## Offline Sketches
135341

0 commit comments

Comments
 (0)