This document describes the EDC Device Provisioning feature from a platform-user point of view for users who have an existing account and an understanding of the basic functionality and structure of the platform.

The EDC Device Provisioning feature allows a user to automatically configure a new device without having to directly interact with it 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

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 8883 or 1883.
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.

EDC Device Provisioning requires that a provision request is created in the platform. The device data is required as it is used to identify the device that is to be provisioned, as well as the configuration information that is sent to the device during the provisioning process.

After the provision request is created, the device can be connected to Internet to initiate the provisioning process. Once the device has completed the boot and all the components have been initialized, it tries to connect to the provision broker. The connection is established only if there is a provision request created for that device in the platform. After a 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 certificates that the device will use to verify the signature of the messages received from the cloud platform, 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.

Provisioning Bundle Configuration

The Provision Bundle manages the pre-configuration of a device that needs to be provisioned for Eurotech devices. The following image shows the default configuration settings of the provision bundle:

The provision bundle configuration settings are described below.

enabled - sets whether or not the device tries to execute the provision process. This flag is automatically set to false after a successful provisioning.
provisioned - defines whether or not a device has been provisioned. This flag is set automatically to true after a successful provisioning
ca-authentication - defines whether or not the code has to check if the root CA of the certificate chain received during the provisioning is trusted
broker-url - defines the broker node that a device tries to connect for the provisioning process to start.
account-name - defines the provision account name.

📘
The account-name setting is required and must not be modified; otherwise, the connection to the provision broker will fail.

username - sets the username to be used by the device to connect to the provision broker. If it is not specified, the username will be generated by the MAC address of the main network interface (without “:”) followed by a dash “-” and the serial number. This parameter must match the username on the dedicated provision request that is created on the server side.
password - sets the password to be used by the device to connect to the provision broker. This parameter must match the password on the dedicated provision request that is created on the server side.
activation-key - sets the activation key that the device put into the provision message after provision broker connection is made. This parameter needs to be set when a provision request is being created and the flag generateActivationKey is set to true. This value can be found in the provision request information.
client-id - sets the clientID to be used by the device to connect to the provision broker. If it is not specified, the username will be generated by the MAC address of the main network interface (without “:”). This parameter must match the client-id on the dedicated provision request that is created on the server side.
timeout - defines the period of time in which the device expects to be provisioned after it has sent the provision message.
retry-interval - defines the period of time after a timeout, or after which a failure has occurred in the provisioning process, for the device to retry the provisioning process.
retry-max-attempts - represents the number of retries that a device attempts the provisioning process. If set to -1, the device tries until it succeeds.

After a successful device provision, the device automatically disables the provision bundle and the received configuration will be used to reconnect to the device owner account.

Device Provisioning MQTT Protocol

This section describes the device provisioning messages over the MQTT protocol. It can be used as a reference for developing custom implementations of the provisioning client agent for non-ESF powered devices.

The device provisioning protocol (device-side) is comprised of the following four basic steps:

Connect to the provision broker
Send a message requesting the new configuration and applications to the provision broker
Disconnect from the provision broker
Reconnect to the account broker using the new configuration

Connect to the Provision Broker

The provision broker is responsible for provisioning devices. The provision broker URL for sandbox and production environments is as follows:

Sandbox: broker-sandbox.everyware-cloud.com
Production: broker-eurotech-provision.everyware-cloud.com

📘
With the MQTT protocol, it is recommended to connect to the SSL protected provision broker URL on port 8883 due to the transmission of sensitive data (username and password). If the device does not support SSL secure connections, use 1883 instead.

To connect to the provision account, the following parameters are used:

Broker URL - one of the following depending on your environment:
Sandbox: mqtts://broker-sandbox.everyware-cloud.com:8883
Production: mqtts://broker-eurotech-provision.everyware-cloud.com:8883
ClientID - a unique identifier within the whole account (e.g., the MAC address of the main network card of the device without columns) that follows the naming convention defined by the MQTT v3.1 protocol specification.
Username - username that must match the username defined in the provision request on the platform. If it does not match, the device will not be able to connect to the provision broker.
Password - password that must match the password defined in the provision request on the platform. If it does not match, the device will not be able to connect to the provision broker.