The Everyware Cloud Device Provisioning feature allows a user to automatically and remotely configure a new device without having to directly interact with it on site and to configure devices with user-supplied parameters.

This feature can be used for easy and fast deployment of a large number of devices that have similar configurations, applications, or areas of application.

General Architecture

The device manager configures the device with the provisioning parameters by directly accessing the device and sets the device in provisioning mode. The device is then ready to be deployed on the field by a deployment operator. The operator physically installs the hardware on site, optionally he configures the network parameters to enable the physical connection between the device and Everyware Cloud. The device manager creates a provision request in Everyware Cloud that matches the device to be provisioned, the provision request need be in place when the device will start the provisioning process. Upon successful connection, the device sends a message to the platform initiating the provisioning flow.

The platform validates the message received from the device, and if it is valid, responds to the device with the new configuration and applications. After all configurations are received and installed, the device disconnects from the provision broker and reconnects to the broker of the account that owns the device. A device provisioning flow is illustrated in the diagram below.

📘
The Provisioning process is designed to promote separation of concerns. The operators that configure the device for the provisioning process and the operators that deploy the device on the field may be kept distinct. This approach is beneficial for the security aspects of the solution since that each group of operators has access to exactly the information that are required to accomplish his task. The option to automate the process strengthens security and logistic aspects even further.

Before a device may be provisioned, two prerequisite steps are required:

The device requires Internet access. If the device is behind a firewall or proxy that limits outgoing connections, ensure that the provision broker URL may be reached on destination port. Often the ports are often 8883 for MQTTS or 1883 for MQTT but they can vary depending on the specific deployment, contact your system administrator for more information regarding the endpoints to be used.
The user needs to know the device data (i.e., client identifier [clientId], username, and password) that is used by the device in order to connect to the provision broker. To understand how to retrieve this information, refer to the Provision Request section.

Responsibilities

With Everyware Cloud Device Provisioning, various components work together to complete the device provisioning operations. Each component has specific roles and functions as explained in the paragraphs that follow.

Provision Broker

The provision broker is the broker to which all devices that need provisioning connect to in order for provisioning operations to be supported. It is shared across all accounts of the Everyware Cloud platform. For security reasons, devices connected to the provisioning broker have read and write permissions limited to the MQTT topics necessary for the provisioning process; no other message exchanges are allowed. In order to connect to the provision broker, a provision request with the device data must already exist.

NOTE: For information on how to configure the cloud connection, please refer to the MqttDataTransport section.

Provision Request

Everyware Cloud Device Provisioning requires that a provision request is created in the platform.
The provision request contains all of the information needed to provision a device on the server-side. An account administrator must create a provision request for the device that is to be provisioned to include the device data and the configuration data using the following parameters:


Provision Target Client ID	Identifies the target device for which the provision request is created. This identifier must match the clientId that is used by a device for the initial connection to the provision broker. The clientId must be unique within an account (preferably within the whole platform), and must follow the naming convention defined by the MQTT v3.1 protocol specification; otherwise, it will be not recognized as a valid clientId and the provision request will be rejected
Provision Username	Defines the username that will be used by the device for the initial connection to the provision broker. A user will be created under the Everyware Cloud Provision account with the defined username, which must be unique across the Everyware Cloud platform. The username must be at least three characters long, and contain only alphanumeric characters and “-” or “_” as special characters; otherwise, the provision request will be rejected. For example, the MAC address of the device or its serial number can be used for a provision request that is specific for each device. Alternatively, an account holder can decide to ship all its devices with the same credentials for the provisioning broker; in that case, it can reuse the same username and password for all its provision requests.
Provision Password	Defines the password that will be used by the device for the initial connection to the provision broker. This password should be paired with the username provided in the provision request. The password must be at least 12 characters long and contain at least one of the following: A lowercase character An uppercase character * A special character
Generate Activation Key (optional)	Defines whether or not the device must provide an activation key as part of its provisioning request message. This key is generated by the system and should be written into the device. This field enhances security particularly in cases where a customer uses devices that have the same factory-supplied username and password, as the device is then also required to provide the activation key. This key acts like an optional password and it may also be used when all devices use a different username and password. If this parameter is not defined, it is set to false and no activation key is generated.
Provision Endpoint	The MQTT endpoint the device has to connect to after the provisioning has been successfully completed.
Activates On	Sets a date that the provision request becomes valid. Prior to this date, a device may connect to a provision broker, but it will not be able to be provisioned. If this parameter is not defined, the current date is used.
Expires On (optional)	Sets a date after which the provision request is no longer valid. Beyond this date, a device may connect to the provision broker, but it will not be able to be provisioned. This date must follow the activation date otherwise the provision request will not be created. If this parameter is not defined, the provision request will never expire.
Reserve User	Defines whether or not the user created on the target account will be reserved to the specific DeviceConnection of the provisioned Device. See Device Registry documentation for more information about.
Device Connection Coupling	Sets the Device User connection couplig that will be assigned to the DeviceConnection of the provisioned Device. See Device Registry documentation for more information about.
Additional Device Configuration	An additional Device Configuration that will be provided to the device during the provisioning process. The given Device Configuration can configure any component, but some MQTT parameters will be overridden by the provisioning process. Parameters overridden are: - broker-url - topic.context.account-name - clientId - username - password

The device will be provisioned in the account that holds the provision request. Basic configuration includes the account's broker URL and MQTT credentials generated by the EC Platform. In fact, a new user will appear under the account that owns the provision request, the system will automatically grant broker:connect permissions to this user.
If an additional Device Configuration is provided, it will be merged with the one generated by the provisioning process.

Device

The device is the device that needs to be provisioned by Everyware Cloud. Since the the process is started by the device itself, it has to be properly configured. An operator gets access to the ESF user interface and configures the ESF Provisioning Service by setting some parameters that will match the provision request created in Everyware Cloud.
Once the provisioning is configured, the operator sets the device in provisioning mode. When device is in provisioning mode the ESF Provisioning Service will automatically contact the provisioning broker in EC thus triggering the provisioning process.
For details regarding how to configure an ESF device to execute the provisioning, please refer to ESF Documentation.