Device Provisioning

The Everyware Cloud Device Provisioning Service is used to enroll new devices into an account. Once successfully provisioned, the enrolled device will be added to the account Device Registry Service and will receive the configuration to connect to it so that it will eventually become a managed device.

Through the Provisioning Service, enrolment of devices can be managed centrally within Everyware Cloud so that policies can be enforced consistently across the fleet of all the devices with a manageable, scalable and secure process. Besides this, the capability to automate the process strengthens security and simplify logistic aspects even further.

Typical scenarios where the provisioning process is used include:

• Devices have to be enrolled into their account for the first time after being produced
• Already enrolled devices have to be moved to a distinct account
  • The the current and the new accounts are in the same Everyware Cloud instance
  • The the current and the new accounts are in distinct Everyware Cloud instances

General Architecture

At high level the provisioning process is divided in three stages:

• Device configuration
• Cloud configuration
• Connection and execution

Device configuration defines the parameters required to connect to the Provisioning Service; these are the only information shared between device and cloud. The cloud configuration defines the parameters required by the device to connect to its final operational account plus any additional configuration required by the specific use case. Device configuration and cloud account configuration can be executed independently by distinct actors in the process.

In a typical scenario, the device configuration is carried out by operations during the manufacturing or delivery phases while the cloud account configuration is carried out by device fleet managers. This process promotes the separation of concerns:

• The operations/delivery team does not need to have any access to the cloud platform
• The operations/delivery team does not need to know the final operational configuration of the device in the target account
• The device management team handles the final operational configuration of the device via Everyware Cloud
• Sharing of information is reduced to minimum

Provisioning Steps

First the device manager user creates a Provision Request in Everyware Cloud that matches the device to be provisioned, the provision request need to be in place when the device will initiate the provisioning process.

Then the operations user configures the Provisioned Device with the parameters required to connect to the Provisioning Service. The device is then ready to be deployed on the field by a deployment operator.

📘

Creation fo the Provision Request and configuration of the device can be executed in any order. However, the connection from the device to the provisioning service will succeed only if there is a provisioning request matching.

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.

At startup the device connects to a well-known Provisioning Endpoint, the device sends a provisioning message to the platform initiating the provisioning flow.

Everyware Cloud validates the message received from the device, and searches for a Provision Request that matches the device. If the request is found, the Everyware Cloud sends the operational configuration to the device.

After all configurations are received and installed by the device, it disconnects from the Provision Service and reconnects to the the operational account configured for the device. An entry for the provisioned device is enlisted in the the Device Registry.

Provisioning Request

The provision request contains all of the information needed to provision a device. The provision request has to be created in the final (target) operational account of the device.

To create a provisioning request goto to the Provisioning view and click the Add button.

If an additional Device Configuration is provided, it will be merged with the one generated by the provisioning.

📘

Re-issue a provisioning request

A provision request that is closed (i.e. either completed or failed and expired) cannot be re-used. If for any reason a device needs to be provisioned again, the previous request has to be deleted and a new request has to be created.

A device cannot have multiple distinct requests associated at the same time. If a provisioning request is in status CREATED then it can be modified otherwise it has to be deleted and created again.

📘

Changing a provisioning request

Be careful when changing or deleting an active provision request since a device may be using it or about to be using it. A provision request is active during the time window defined by Activates On and Expires On timestamps.

Additional Configurations

Additional configurations are defined as XML documents using the device configuration format.

To obtain the XML definitions of the services:

• download the snapshot from the EC Admin Console and isolate the components and the properties that need to be configured for your use case

See section Configuration Snapshots for more details regarding how to download/upload a snapshot.

📘

Additional Configuration Limitations

Some configurations are reserved to the provisioning process and will be overridden by the system even though set differently in the value of this field.

The following parameters of the MQTTDataTransport Service component will be overridden by the provisioning procees:

• broker-url
• topic.context.account-name
• clientId
• username
• password

For example to fully reconfigure the Kura/ESF Command Service the following XML document che be used:

<?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns:ns0="http://www.osgi.org/xmlns/metatype/v1.2.0">
   <configuration>
      <!--
       Fully reconfigure the command service
       -->
      <id>org.eclipse.kura.cloud.app.command.CommandCloudApp</id>
      <properties>
         <property name="command.timeout" array="false" encrypted="false" type="Integer">
            <value>60</value>
         </property>
         <property name="command.enable" array="false" encrypted="false" type="Boolean">
            <value>false</value>
         </property>
         <property name="privileged.command.service.enable" array="false" encrypted="false" type="Boolean">
            <value>false</value>
         </property>
         <property name="kura.service.pid" array="false" encrypted="false" type="String">
            <value>org.eclipse.kura.cloud.app.command.CommandCloudApp</value>
         </property>
         <property name="service.pid" array="false" encrypted="false" type="String">
            <value>org.eclipse.kura.cloud.app.command.CommandCloudApp</value>
         </property>
      </properties>
   </configuration>
</configurations>

To reconfigure just the enablement of the command service just define the value of the "command.enable" property, all the other properties will be remain unchanged:

<?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns:ns0="http://www.osgi.org/xmlns/metatype/v1.2.0">
   <configuration>
      <!--
       Just enable the command service
       -->
      <id>org.eclipse.kura.cloud.app.command.CommandCloudApp</id>
      <properties>
         <property name="command.enable" array="false" encrypted="false" type="Boolean">
            <value>true</value>
         </property>
      </properties>
   </configuration>
</configurations>

The following reconfigures the poll rate of the Diagnostic Service to 15min (900sec) and decrease the threshold of the tmpfs usage percentage to 80 and 90.

<?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns:ns0="http://www.osgi.org/xmlns/metatype/v1.2.0">
   <configuration>
      <!--
       Increase the poll interval to 15min (900sec), decrease the threshold of the tmpfs usage percentage to 80 and 90
       -->
      <id>com.eurotech.framework.diagnostics.DiagnosticsService</id>
      <properties>
         <property name="health.monitor.poll.rate" array="false" encrypted="false" type="Integer">
            <value>900</value>
         </property>
         <property name="fs.usage.threshold.warning.tmpfs.dev" array="false" encrypted="false" type="Integer">
            <value>80</value>
         </property>
         <property name="fs.usage.threshold.critical.tmpfs.dev" array="false" encrypted="false" type="Integer">
            <value>90</value>
         </property>
      </properties>
   </configuration>
</configurations>

Configurations can be concatenated in a list. The following is an example for both change the configuration of the Command Service and the Diagnostic service in the same provisioning request:

<?xml version="1.0" encoding="UTF-8"?>
<configurations xmlns:ns0="http://www.osgi.org/xmlns/metatype/v1.2.0">
   <configuration>
      <!--
       Just enable the command service
       -->
      <id>org.eclipse.kura.cloud.app.command.CommandCloudApp</id>
      <properties>
         <property name="command.enable" array="false" encrypted="false" type="Boolean">
            <value>true</value>
         </property>
      </properties>
   </configuration>
   <configuration>
      <!--
       Increase the poll interval to 15min (900sec), decrease the threshold of the tmpfs usage percentage to 80 and 90
       -->
      <id>com.eurotech.framework.diagnostics.DiagnosticsService</id>
      <properties>
         <property name="health.monitor.poll.rate" array="false" encrypted="false" type="Integer">
            <value>900</value>
         </property>
         <property name="fs.usage.threshold.warning.tmpfs.dev" array="false" encrypted="false" type="Integer">
            <value>80</value>
         </property>
         <property name="fs.usage.threshold.critical.tmpfs.dev" array="false" encrypted="false" type="Integer">
            <value>90</value>
         </property>
      </properties>
   </configuration>
</configurations>

Provisioned Device

The first thing the provisioned device should do is connecting to the Provisioning Service. The parameters required by the device to establish the connection to the Provisioning Service in Everyware Cloud are:

• Provisioning account endpoint (MQTT)
• Provisioning account name
• Device client ID
• Device user Credentials

Setting these parameters require that the user has access to the device and its services.

Accessing an ESF Device

The way the device is accessed to execute the setup of the provisioning configuration depends upon in which phase of the lifecycle the device is.

If the device is in house and a physical access is available via LAN, a direct access through the Web Admin Console can be used. Check the ESF guide for more details about accessing ESF via the Admin Console.

If the device is already provisioned and connected to the cloud it can be reached via Everyware Cloud Admin Console using the Configuration tab in the Device view:

Otherwise, if the device is already provisioned and connected to the cloud and Everyware Cloud Remote Access functionality is active, a direct ssh connection can be established from the user PC/Laptop to the ESF device so that the ESF Web UI can be used to get direct access to the device.

Configure an ESF Device

For details regarding how to configure an ESF device to execute the provisioning, please refer to ESF Documentation.

Provisioning Account

The provision account is a per-instance, reserved account used by the Provisioning Service to execute the process; it is shared across all accounts of the Everyware Cloud instance.

The provisioning account is bound to an MQTT Endpoint that is the endpoint that the device must connect to in order to trigger the start of the provisioning process.

There are two information a device need to know in order to successfully contact the Provisioning Service:

• The provisioning account name
• The provisioning account endpoint (MQTT)

For a device to succeed connecting to the provision account, a provision request with the device data must already exist.

📘

For security reasons, devices connected to the provisioning account have read and write permissions limited to the MQTT topics necessary for the provisioning process; no other message exchanges are allowed.

Account Administration

See the Administration guide for more details regarding activities required to setup and maintain the Provisioning Account.

Provisioning Execution

The process initiates when the device connects to the Provisioning Service. The service identifies if there is a valid Provisioning Request matching the device:

• Same client ID
• Same user identity and valid user credentials
• Connection falls within the time window defined by the Activates On, Expire On values

If a match is not found the connection is refused otherwise the status of the request is set to RUNNING and configuration data is sent down to the device. If everything is ok the status is set to COMPLETED and the provisioning process stops.

📘

Status COMPLETED means that no issue was detected by Everyware Cloud while executing the request. However, device side something may have gone wrong anyway when applying the new configurations and/or reconnecting to the final destination.

Upon request execution a new user will be created if not present in the target account so that each device is assigned its own identity for enforcement of authentication and authorisation; the system will automatically grant broker:connect permissions to this user.

When the request completes successfully the device must disconnect from the Provisioning Service and use the new configurations received to establish the connection to its target operational account.

If an error was detected by the Provisioning Service, the request status is set to FAILED. A device can retry a failed request until the request is valid., i.e. the expiration time is reached. Once this happens the provisioning process stops.

Each provisioning attempt, either successful or failed, is tracked by a provisioning execution. Provisioning executions can be reviewed from the Admin Console or via the RESTful API. From the Provisioning view select the provisioning request and then the Executions tab.

A provision request can have multiple provisioning executions each one corresponding to a provisioning attempt. The execution attempts stop either when the provisioning is successful or when the time window expires (i.e. the Expires On date is passed).

Execute a Job on Provisioning

There is a simple procedure for executing a Job on a device as soon as it connects to the target account after the provisioning process is completed.

1. In the Devices view create the device with the correct clientID
2. In the Batch Jobs view
   1. Create a Job
   2. Add the device to job targets
   3. Add the steps to be executed on the device (multiple steps can be added)
   4. Add the schedule selecting
      1. "Device Connect" if the job has to be executed when device connects after being provisioned
      2. "Interval Job" or "Cron Job" if the job has to be executed in a defined time schedule after the provisioning
3. In the provisioning view create the provision request for the device
4. Configure the device in provisioning mode

Once the device is provisioned, it will reconnect to the target account where the Job will be activated by the device connection event (if schedule is "Device Connect") or by the other schedules defined.

Troubleshooting

Check Provisioning Executions

If a provision request did not succeed, its execution log can be inspected to identify the causes of the error. In the Provisioning view select the failed request, from the executions tab select the execution and then click the Show Log button.

Target (mis)configurations

A recurrent reason for a device not being able to connect to its operational account is the misconfiguration of the target account MQTT endpoint. This mistake may be committed easier when the endpoint is set through the RESTful API where there is no drop-down menu to help the choice.

🚧

By misconfiguring the target account MQTT endpoint the device will likely become unreachable from the cloud.

Cloud unreachable

Check that the endpoints involved in the process are reachable by the device. Sometimes, if the device is behind a firewall or proxy, there might be limits for outgoing connections. MQTT usually use the ports 8883 for encrypted communications and 1883 for plain text communications but they can vary depending on the specific deployment.

🚧

If the provisioning MQTT endpoint or the the target account MQTT endpoint are unreachable by the device the provisioning process cannot take place or the connection to the operational account will fail.

Additional configs invalid

An invalid or inconsistent additional configuration can cause errors that will harm the device and prevent it to reconnect to its target operational account after the provisioning have been executed.

🚧

Verify and test every configuration that will be sent to the device.