Network Provisioning Support in Client Libraries

Network provisioning enables your IoT application to dynamically provide provisioning information over the network for your devices. IoT applications can use network provisioning for seamless onboarding and activation of trusted assets.

When registering new devices with Oracle IoT Cloud Service, you need to provision the devices with information like the server name, port, device ID, and certificate before they can connect securely with Oracle IoT Cloud Service. Network provisioning enables you to dynamically provision your devices over the network.

After a device is registered, it waits for the provisioning information from a network provisioner. Once it receives the provisioning information, the device can perform activation and start communicating messages with Oracle IoT Cloud Service.

Network provisioning support enables you to build applications that can dynamically register and provision your devices. A service technician with the required privileges/roles to register a device, for example, can use the Oracle Asset Monitoring mobile application to scan the device details QR code, register the device using these details, and dynamically provision the device over the network.

To enable network provisioning, the client libraries include the bootstrapper and network provisioning utilities:

Bootstrapper: The client libraries include the bootstrapper utility. When the device is switched on, the bootstrapper looks into the specified trusted assets store to check if provisioning is complete for the device. If the device isn't provisioned, then the bootstrapper waits for it to get provisioned before handing over the control to the device application that completes activation. On subsequent reboots, the bootstrapper detects that the device is already provisioned and directly launches the device application.
Network Provisioner: The network provisioner is a stand-alone application that discovers available clients waiting to be provisioned, and sends them the provisioning information required to complete provisioning. The provisioning information includes information like the server name, port, device ID, and certificate required for the device to securely connect to the Oracle IoT Cloud Service server.

The network provisioner uses UDP multicast messages to discover registered clients waiting to be provisioned. The network provisioner returns this list to the user, who then selects the device to be provisioned. The network provisioner next unicasts the provisioning information to the selected device. The device stores the provisioning information in its trusted assets store, and uses the information to perform direct activation.

Network Provisioner

Network Provisioner Usage:

networkProvisioner.[sh|bat] [client_host provisioning_file]

Where:

client_host is the IP address of the gateway.

provisioning_file is the name of the file containing the provisioning information in the unified provisioner format (upf).

For example:

./bin/networkProvisioner 10.0.0.1 ~/Downloads/mytas.ufp

Java Client Library Bootstrapper and Network Provisioner

The Bootstrapper class files are contained in the lib/bootstrapper.jar file.

Bootstrapper Usage:
```
java oracle.iot.client.util.Bootstrapper trust_assets_file trust_assets_password
   application_class_name [application_argument_0...application_argument_8]
```
Where:

trust_assets_file is the relative or fully-qualified filename of the trusted assets store.

trust_assets_password is the password of the trusted assets store. It must match the file protection password of the provisioning file.

application_class_name is the name of the application to start.

application_argument_0 .... application_argument_8 are any optional arguments to be passed to the application.
So, for example:
```
java -cp ../lib/bootstrapper.jar:./build/libs/iotcs-csl-samples.jar
   oracle.iot.client.util.Bootstrapper MyFile MyPassword123 com.oracle.iot.sample.DirectlyConnectedDeviceSample
```
Network Provisioner Usage:
```
java -jar network-provisioner.jar [client_host Provisioning_file] 
```
Where:

client_host is the IP address of the device where the bootstrapper is running.

provisioning_file is the name of the file containing the provisioning information.

If no arguments are provided, then the network provisioner discovers the available clients. Else, the network provisioner provisions the specified client.

JavaScript Client Library Bootstrapper and Network Provisioner

Bootstrapper Usage:

Note:
Make sure that the NODE_PATH environment variable points to the location where the required node modules are installed.
```
bootstrapper.[sh|bat] provisioned_file password app_class_name [app_arg_0...app_arg_8]
```
Where:

provisioned_file is the relative or fully-qualified filename of the trusted assets store.

password is the password of the trusted assets store. It must match the file protection password of the provisioning file.

app_class_name is the name of the application to start.

app_arg_0 .... app_arg_8 are any optional arguments to be passed to the application.
Network Provisioner Usage:

Note:
Make sure that the NODE_PATH environment variable points to the location where the required node modules are installed.
```
networkProvisioner.[sh|bat] [client_host provisioning_file]
```
Where:

client_host is the IP address of the device where the bootstrapper is running.

provisioning_file is the name of the file containing the provisioning information in the unified provisioner format (upf).

If no arguments are provided, then the network provisioner discovers the available clients. Else, the network provisioner provisions the specified client.

C Client Library Bootstrapper

Bootstrapper Usage:

# Posix
$PATH_TO_BT/bootstrapper taStore=trusted_assets_store taStorePassword=password 
$PATH_TO_SAMPLE/directly_connected_device_sample trusted_assets_store password
# Windows
$PATH_TO_BT/bootstrapper.exe taStore=trusted_assets_store taStorePassword=password 
$PATH_TO_SAMPLE/directly_connected_device_sample.exe trusted_assets_store password

For MBED, the samples automatically perform bootstrap. If the provisioning information is not found in the trusted assets store, network provisioning is attempted over the UDP connection.

Android Client Library and iOS Client Library Samples

The samples can use network provisioning if the network provisioning option is selected on the Provisioning screen.