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.

Components

With EDC 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.

📘

For information on how to configure the cloud connection, please refer to the Configure Everyware Cloud Connection section.

Provision Request

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:

• ClientId - 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.

• 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 this case, the same username and password can be reused for all its provision requests.

• 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

• Maximum number of provision attempts - defines the maximum number of attempts that a device tries to initiate the provisioning process. If this limit is exceeded, the platform will no longer execute the provision process requested by the device. The counter of current provision attempts increases only in the case of errors during the provisioning process. If a failure occurs in the validation of data provided by the device when it connects or sends the provision request message, the error will not count as a provisioning process failure.

• ProvisionSecureURL - checkbox that, if selected, will result in a device configuration a broker url where the connection protocol and port are forced to mqtts and 8883.

• Provisioned Credentials Tight - this field sets the credentials tight strategy assigned to the provisioned device.

• STRICT: means that the provisioned device can only use only one set of credentials and cannot change them.

• LOOSE: means that the provisioned device is not restricted on the credential usage in any way.

• INHERITED: (default) means that the provisioned device will inherit the strategy from the account service plan.
  All strategies requires that credentials on login must be valid.

If no other information is supplied when creating the provision request, the device will be provisioned under the EC account with a basic configuration to include the account's broker URL and MQTT credentials generated by the EC Platform. Also, a new user will appear under the EC account that owns the provision request with broker:connect permissions.

The following optional parameters may also be provided when creating a provision request:

• Generate Activation Key Flag - 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.

• Activation Date - 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.

• Expiration Date - 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.

• Provision attachments - provides additional files that are sent to the target device during the provisioning process. Initially, only configuration attachments are supported:

• Configuration attachments - provides an XML file of the device configuration. This XML file specifies configuration components on the device. The configuration of the mqttDataTransport component has a particular validation process, whereby any values set to the broker-url and topic.context.account-name properties will be overwritten with values from the account that owns the provision request. Username and password are checked using the following logic: if provided, the provisioning process verifies that they are valid credentials on the platform; if not provided, the provisioning process creates a new user under the provision request's target account and writes those credentials into the configuration before sending it to the device. Configuration attachments are optional and are limited to one for each provision request. If configuration attachments are not provided, the provisioning process synthesizes a basic configuration following the logic described above.

Device

The device is the live or simulated device that requires provisioning. For ESF-powered devices, the Provisioning Bundle manages all provisioning operations with the provision broker.

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:

1. Connect to the provision broker

2. Send a message requesting the new configuration and applications to the provision broker

3. Disconnect from the provision broker

4. 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.

Request Configuration

After a successful connection has been made, the following operations may be performed in support of device provisioning:

• Read topic $EDC/eurotech-provision/{client_id}/#

• Write on topic $EDC/eurotech-provision/+/+/REPLY/#

• Write on topic $EDC/eurotech-provision/{clientId}/MQTT/#

To receive the certificate chain that will be used to verify the signature of the messages that will be received from the cloud platform, the device subscribes to the following topic:

• $EDC/eurotech-provision/{clientId}/PROV-V2/PUT/certificate

To receive a new configuration, the device subscribes to the following topic:

• $EDC/eurotech-provision/{clientId}/PROV-V2/PUT/configurations

To request a new configuration, the device publishes a message on the following topic:

• $EDC/eurotech-provision/{clientId}/MQTT/PROV

The following parameters are used in the request message:

• username - (string) sets the username needed to connect to the platform.

• password - (string) sets the password needed to connect to the platform.

• activationkey - (string, optional) sets the activation key, if requested, that is associated with the provision request.

📘

The device should prevent concurrent configuration requests.

Receive Configuration

The request and response message of the provision broker is typically validated within 10 to 40 seconds.

The cloud platform certificates that will be used to verify the message signature are received on the following topic:

• $EDC/eurotech-provision/{clientId}/PROV-V2/PUT/certificate

The new configuration is received on the following topic:

• $EDC/eurotech-provision/{clientId}/PROV-V2/PUT/configurations

The following new connection parameters are contained in the new configuration:

• broker-url - this value always matches the broker-URL that is assigned to the target account.

• topic.context.account-name - this value is the target account name that will be used to publish messages on EC platform (e.g., {topic.contex.account-name}/{clientId}/some/random/topic).

• username - if an attachment was not associated with the provision request, the platform generates a new user within the target account.

• password - if an attachment was not associated with the provision request, the platform generates a new password for the newly created user. This password is Base64 encoded and will therefore require decoding before using it for connection.

Reply Message

After receiving the configuration, the device must send a reply message to the broker so that the broker may update the status of the provision request.

The reply message topic is as follows:

• $EDC/eurotech-provision/{requesterClientID}/PROV-V2/REPLY/{requestID}

The requesterClientID and requestID values may be found in metrics added to the message that contains the newly received configuration.

Metric names are as follows:

• request.id - the value for the topic parameter’s requestID.

• requester.client.id - the value for the topic parameter’s requesterClientID.

At this point, the device determines the appropriate response to the provision process using the following criteria:

• If the configuration is correctly received and there are no other errors, the reply message contains the following metric:

• Metric

  • Name - response.code
  • Type - string
  • Value - 200 (HTTP response-code like)

• If the configuration is not correctly received, or the process encountered other errors, the reply message contains the following metrics:

• Metric

  • Name - response.code
  • Type - string
  • Value - 400 or 404 or 500 (HTTP response-code like)

• Metric

  • Name - response.exception.message
  • Type - string
  • Value - any string with information about the error

If the response.code equals 200, the provision request is marked as COMPLETED; however, if the response.code is not equal to 200, the provision request is marked as FAILED and the response.exception.message is reported on the execution log of the provision request.

Once the reply message is sent, the client may disconnect from the provision broker and reconnect using the newly received connection parameters.