Merge pull request #2645 from arduino/benjamindannegard/provisioning-document-feedback-changes

BenjaminDannegard · web-flow · commit c559187526e9 · 2025-10-23T01:01:45.000+02:00
[PXCT-1437] Cloud - Provisioning documentation changes
diff --git a/content/arduino-cloud/02.hardware/06.device-provisioning/content.md b/content/arduino-cloud/02.hardware/06.device-provisioning/content.md
@@ -65,6 +65,8 @@ Here are the boards that are compatible with Bluetooth provisioning via a Blueto
 
 - [Arduino UNO R4 WiFi](https://docs.arduino.cc/hardware/uno-r4-wifi/) (Wi-Fi firmware version 0.6.0 or later required)
 
+A board that is ready for Bluetooth provisioning has a specific provisioning sketch installed and displays a pulsing LED or a Bluetooth icon on the LED matrix (for UNO R4 WiFi). Newer boards are delivered with this specific sketch already installed. If the pulsing LED is not visible, please use the USB provisioning method.
+
 ### Setting up Your Device With Bluetooth
 
 After selecting the Bluetooth option you will see a page telling you how to connect your board. Follow the steps to connect your board via Bluetooth.
@@ -79,6 +81,8 @@ After completing these steps your device will connect to your Wi-Fi and you will
 
 ![Attach thing after Bluetooth](assets/attach-thing-to-bluetooth.png)
 
+The Bluetooth LE interface is automatically turned off at the end of the procedure, and it remains off until the board is reset. More information about this can be found in the [How to set up the Reconfiguration Procedure](#how-to-set-up-the-reconfiguration-procedure) section.
+
 Now you are ready to start using your board with the Arduino Cloud!
 
 ## USB Provisioning
@@ -125,11 +129,65 @@ Now your board will be updated to version 2.0, wait for the process to finish.
 
 When this is done you can continue setting up the network connection for your board and it will now be using the latest provisioning method with the Arduino Cloud!
 
-### Removing Saved Network Configuration
+## How to update the Stored Network Configuration
+
+To proceed with the next steps, the Cloud-generated sketch must be uploaded to the board. If you want to update the stored network configuration, there are two ways:
+
+### Update Using the Bluetooth LE Interface
+
+Ensure that the Cloud sketch has enabled the BLEAgent, 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).
+
+You can update the network settings from the detail page of the device on the Arduino Cloud webpage or the mobile app.
+
+During this process you will be asked to wipe out the current network configuration to restart the board's Bluetooth LE interface. 
+
+1. Power on the board.
+2. Open the devices page of the Mobile App or the Arduino Cloud webpage.
+3. Click on the device you want to update the network settings for.
+4. Click on the "change" button by the network section.
+5. If you are using the Arduino Cloud webpage, select the Bluetooth method.
+6. 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.
+7. The board will reboot, and you will see the LED pulsing.
+8. Connect to the board on the Arduino Cloud.
+9. Input the new network configuration.
+10. The board will validate it, and if correct, it will close the connection.
+
+### Update Using the Serial Interface
+
+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).
+
+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.
+
+1. Turn on the board and connect it to your PC using a USB cable.
+2. Open the devices page on the Arduino Cloud webpage.
+3. Click on the board you want to update the network settings for.
+4. Click on the "change" button by the network section.
+5. Input the new network configuration.
+6. The board will validate it, and if correct, it will close the connection.
 
-This section will explain how to remove the stored network credentials and force the restart of the BLE interface of a board that has been provisioned with version 2.0. This can be useful to either reset the board or to update the network credentials via BLE.
+## How to Delete a Stored Network Configuration
 
-If you want to remove the stored network credentials and force the restart of the BLE interface, so that the network credentials can be updated via BLE. Please follow these instructions depending on your board:
+If you want to delete the stored network configuration without updating it, there are two possible methods to do so.
+
+### Board Reset Procedure
+
+To proceed with the next steps, the Cloud-generated sketch must be uploaded to the board.
+
+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.
+
+### Using the DeleteConfiguration Sketch
+
+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.
+
+The sketch can also be found [here](https://github.com/arduino-libraries/Arduino_NetworkConfigurator/blob/main/examples/utility/DeleteConfiguration/DeleteConfiguration.ino).
+
+### How to set up the Reconfiguration Procedure
+
+As the Provisioning 2.0 ends, the Bluetooth LE interface is turned off. 
+
+To restart the Bluetooth LE interface to update the network settings, the [**Arduino_NetworkConfigurator**](https://github.com/arduino-libraries/Arduino_NetworkConfigurator?tab=readme-ov-file) library provides a procedure called "Reconfiguration Procedure". This procedure is based on the shorting of two pins of the board.
+
+The library provides a default implementation according to the board type. 
 
 - `Arduino Opta`: Press and hold the user button (BTN_USER) until the led (LED_USER) turns off
 - `Arduino MKR WiFi 1010`: Short pin 7 to GND until the led turns off
@@ -138,8 +196,4 @@ If you want to remove the stored network credentials and force the restart of th
 - `Arduino Portenta H7`: Short pin 0 to GND until the led turns off
 - `Arduino Portenta C33`: Short pin 0 to GND until the led turns off
 - `Other boards`: Short pin 2 to GND until the led turns off
-- `Portenta Machine Control`: Currently the reset procedure is not available
-
-If you would like to remove the network credentials from the board, you can use the [**Arduino_NetworkConfigurator**](https://github.com/arduino-libraries/Arduino_NetworkConfigurator?tab=readme-ov-file) library.
-
-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.
+- `Portenta Machine Control`: Currently the reset procedure is not available
diff --git a/content/arduino-cloud/03.cloud-interface/00.sketches/sketches.md b/content/arduino-cloud/03.cloud-interface/00.sketches/sketches.md
@@ -129,7 +129,188 @@ The "Secret" File contains your secret credentials, such as Wi-Fi® network SSID
 
 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.
 
-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.
+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**.
+
+## thingsProperties.h and the NetworkConfigurator
+
+The thingProperties.h file plays a key role in managing credential capabilities, including the NetworkConfigurator, which enables two main features:
+
+- **Credentials stored on NVS**: Boards can now securely store network settings in Non-Volatile Storage (NVS), removing them from the sketch (secrets.h).
+- **Over-the-Air (OTA) communication**: Enables the possibility to provide network configuration settings via Bluetooth LE.
+
+The `thingProperties.h` will be generated accordingly to the provisioning mechanism, so if the board has been registered using Provisioning 2.0, the `thingProperties.h` file will automatically have the NetworkConfigurator component enabled. A board registered with Provisioning 2.0 includes `Arduino_NetworkConfigurator.h` in the generated `thingProperties.h` file. For more information about device provisioning have a look [here](https://docs.arduino.cc/arduino-cloud/hardware/device-provisioning/).
+
+### How the NetworkConfigurator works
+
+To work, the NetworkConfigurator needs:
+
+- **One or more Configurator Agents**: Objects that handle the communication between the board and the user device (PC, laptop, or Mobile phone).
+- **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.
+- **A ConnectionHandler**: the object responsible for the board's Internet connection management.
+
+The `NetworkConfigurator` library out-of-the-box provides two Agents:
+
+- `BLEAgent` for handling the Bluetooth LE communication.
+- `SerialAgent` for the Serial communication.
+
+## thingsProperties.h Default Setup
+
+Here is how the `thingsProperties.h` file changes to set up the NetworkConfigurator. This setup is automatically generated if the board has been registered with Provisioning 2.0.
+
+*** Do not follow these steps if the board has not been registered with the Provisioning 2.0. For more information about device provisioning have a look [here](https://docs.arduino.cc/arduino-cloud/hardware/device-provisioning/). ***
+
+### Libraries and Object Declarations
+
+The following libraries are automatically included:
+
+- Arduino_NetworkConfigurator library
+- BLEAgent.h
+- SerialAgent.h
+
+These objects are declared in `thingsProperties.h`:
+
+- `kvStore`: handles the NVM operations
+- `BLEAgent`: handles the Bluetooth LE interface
+- `SerialAgent`: handles the Serial Interface
+- `NetworkConfigurator`: the networkConfigurator instance
+
+```arduino
+#include <ArduinoIoTCloud.h>
+#include <Arduino_ConnectionHandler.h>
+#include <Arduino_NetworkConfigurator.h>
+#include <configuratorAgents/agents/BLEAgent.h>
+#include <configuratorAgents/agents/SerialAgent.h>
+void onVariableChange();
+int variable;
+KVStore kvStore;
+BLEAgentClass BLEAgent;
+SerialAgentClass SerialAgent;
+WiFiConnectionHandler ArduinoIoTPreferredConnection; 
+NetworkConfiguratorClass NetworkConfigurator(ArduinoIoTPreferredConnection);
+```
+
+### initProperties()
+
+In the initProperties function, the following instructions are added:
+
+- `NetworkConfigurator.addAgent(BLEAgent);` For enabling the BLEAgent.
+- `NetworkConfigurator.addAgent(SerialAgent);` For enabling the SerialAgent.
+- `NetworkConfigurator.setStorage(kvStore);` For setting the KVStore.
+- `ArduinoCloud.setConfigurator(NetworkConfigurator);` For embedding the NetworkConfigurator in the ArduinoCloud.
+
+```arduino
+NetworkConfigurator.addAgent(BLEAgent);
+NetworkConfigurator.addAgent(SerialAgent);
+NetworkConfigurator.setStorage(kvStore);
+ArduinoCloud.setConfigurator(NetworkConfigurator);
+```
+
+The final `thingProperties.h` file:
+
+```arduino
+#include <ArduinoIoTCloud.h>
+#include <Arduino_ConnectionHandler.h>
+#include <Arduino_NetworkConfigurator.h>
+#include <configuratorAgents/agents/BLEAgent.h>
+#include <configuratorAgents/agents/SerialAgent.h>
+void onVariableChange();
+int variable;
+KVStore kvStore;
+BLEAgentClass BLEAgent;
+SerialAgentClass SerialAgent;
+WiFiConnectionHandler ArduinoIoTPreferredConnection; 
+NetworkConfiguratorClass NetworkConfigurator(ArduinoIoTPreferredConnection);
+void initProperties(){
+  NetworkConfigurator.addAgent(BLEAgent);
+  NetworkConfigurator.addAgent(SerialAgent);
+  NetworkConfigurator.setStorage(kvStore);
+  ArduinoCloud.setConfigurator(NetworkConfigurator);
+// For changing the default reset pin (2) uncomment and set your preferred pin. Use DISABLE_PIN for disabling the reset procedure.
+// NetworkConfigurator.setReconfigurePin(YOUR_PIN);
+  ArduinoCloud.addProperty(variable, READWRITE, ON_CHANGE, onVariableChange);
+}
+```
+
+### Disable the BLEAgent
+
+To save board storage and memory, after the provisioning, the `BLEAgent` can be removed. ~30 kB of storage and ~2 kB of memory are saved for BSS and Data. The network credentials provided in the provisioning phase can no longer be changed via Bluetooth if this is disabled.
+
+To disable the `BLEAgent`, just comment out or remove the lines of code that include, declare, and enable it. The final result should be the following:
+
+```arduino
+#include <ArduinoIoTCloud.h>
+#include <Arduino_ConnectionHandler.h>
+#include <Arduino_NetworkConfigurator.h>
+//#include <configuratorAgents/agents/BLEAgent.h>
+#include <configuratorAgents/agents/SerialAgent.h>
+void onVariableChange();
+int variable;
+KVStore kvStore;
+//BLEAgentClass BLEAgent;
+SerialAgentClass SerialAgent;
+WiFiConnectionHandler ArduinoIoTPreferredConnection; 
+NetworkConfiguratorClass NetworkConfigurator(ArduinoIoTPreferredConnection);
+void initProperties(){
+//  NetworkConfigurator.addAgent(BLEAgent);
+  NetworkConfigurator.addAgent(SerialAgent);
+  NetworkConfigurator.setStorage(kvStore);
+  ArduinoCloud.setConfigurator(NetworkConfigurator);
+// For changing the default reset pin (2) uncomment and set your preferred pin. Use DISABLE_PIN for disabling the reset procedure.
+// NetworkConfigurator.setReconfigurePin(YOUR_PIN);
+  ArduinoCloud.addProperty(variable, READWRITE, ON_CHANGE, onVariableChange);
+}
+```
+
+### Disable the SerialAgent
+
+To save board storage and memory, after the provisioning, the SerialAgent can be removed. ~1 kB of storage is saved for BSS and Data. The network credentials provided in the provisioning phase can no longer be changed via USB if this is disabled.
+
+To disable the `SerialAgent`, just comment out or remove the lines of code that include, declare, and enable it. The final result should be the following:
+
+```arduino
+#include <ArduinoIoTCloud.h>
+#include <Arduino_ConnectionHandler.h>
+#include <Arduino_NetworkConfigurator.h>
+#include <configuratorAgents/agents/BLEAgent.h>
+//#include <configuratorAgents/agents/SerialAgent.h>
+void onVariableChange();
+int variable;
+KVStore kvStore;
+BLEAgentClass BLEAgent;
+//SerialAgentClass SerialAgent;
+WiFiConnectionHandler ArduinoIoTPreferredConnection; 
+NetworkConfiguratorClass NetworkConfigurator(ArduinoIoTPreferredConnection);
+void initProperties(){
+  NetworkConfigurator.addAgent(BLEAgent);
+//  NetworkConfigurator.addAgent(SerialAgent);
+  NetworkConfigurator.setStorage(kvStore);
+  ArduinoCloud.setConfigurator(NetworkConfigurator);
+// For changing the default reset pin (2) uncomment and set your preferred pin. Use DISABLE_PIN for disabling the reset procedure.
+// NetworkConfigurator.setReconfigurePin(YOUR_PIN);
+  ArduinoCloud.addProperty(variable, READWRITE, ON_CHANGE, onVariableChange);
+}
+```
+
+### Disable the NetworkConfigurator
+
+To save board storage and memory, after the provisioning, the NetworkConfigurator can be removed. ~40 kB of storage and ~2.9 kB of memory are saved for BSS and Data.
+
+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.
+
+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 webpage or the mobile app. The final result should be the following (`thingProperties.h` file):
+
+```arduino
+#include <ArduinoIoTCloud.h>
+#include <Arduino_ConnectionHandler.h>
+const char SSID[]     = SECRET_SSID;    // Network SSID (name)
+const char PASS[]     = SECRET_OPTIONAL_PASS;    // Network password (use for WPA, or use as key for WEP)
+void onVariableChange();
+int variable;
+WiFiConnectionHandler ArduinoIoTPreferredConnection(SECRET_SSID, SECRET_OPTIONAL_PASS); 
+void initProperties(){
+  ArduinoCloud.addProperty(variable, READWRITE, ON_CHANGE, onVariableChange);
+}
+```
 
 ## Offline Sketches
 
