Gateway Management

Everyware Cloud can manage devices that respond to its MQTT device management contract. The MQTT Namespace section provides more details on how such contact is defined and what it allows. This capability allows supported devices to be remotely configured and controlled through Everyware Cloud while they are connected to the broker.

As part of this contract, when a device connects to Everyware Cloud, it provides the list of cloud-enabled applications it supports. A cloud-enabled application allows for the remote management of its resources through simple MQTT messages.

Devices powered by Everyware Software Framework (ESF) or Eclipse Kura implement the remote device management contract and they can be natively managed by Everyware Cloud. ESF comes with several cloud-enabled applications that allow the remote management of certain aspects of the framework.

Based on the cloud-enabled applications installed on the device, the Everyware Cloud Console will enable the remote device management tabs in the Devices section including Packages, Bundles, Configuration, and Command.

Packages

In Devices section of Everyware Cloud, select a device that is currently connected and open the Packages tab. This tab shows a list of installed application packages on the remote device. For ESF and Kura devices, these correspond to OSGi packages.

Click on the arrow next to the package name to list the included libraries. The following operations can be performed on application packages:

• Re-query the list of available packages from the device (Refresh)
• Install or reinstall a package (Install/Upgrade)
• Uninstall a package (Uninstall)

To install or update a package onto the remote device, click the Install/Upgrade button. For ESF device, Packages must have been created as OSGi deployment packages. In install a package, provide a the URL of the package to be installed, its name and version and click on Submit.

The progress of the installation can be monitored from the In Progress tab.

To uninstall an existing package, select the package name and click the Uninstall button and by confirming the operation.

📘

Downloading package files from URL

• Check that the URL is reachable by the devices
• Identify a URL available for the purpose. Consider that Everyware Cloud does not provide the above mentioned URL as part of its services.
• Check ESF documentation for more details regarding the supported protocols for downloading deployment packages.

Bundles

In Devices section of Everyware Cloud, select a device that is currently connected and open the Bundles tab. This tab shows a list of installed application services on the remote device. For ESF and Kura devices, these correspond to OSGi service bundles.

The following operations can be performed on application service:

• Re-query the list of available services from the device (Refresh)
• Start an OSGi bundle (Start)
• Stop an OSGi bundle (Stop)

Running services are shown with an Active state. To stop a service, select the bundle name and click the Stop button. You will be prompted whether to stop the bundle. Click Yes to proceed or No to cancel. When a bundle is present but stopped, it will show a Resolved state.

To start a bundle that is in the Resolved state, select the bundle name and click the Start button. The OSGi framework on the remote device will immediately attempt to start the bundle without further confirmation and will then refresh the Bundles list.

Configurations

In Devices section of Everyware Cloud, select a device that is currently connected and open the Configuration tab. At the bottom of the tab, click on the Services tab. This tab shows the list of services running on the remote device that expose configuration parameters. Click on the name of a service in the lower left panel to display list of configuration parameters in the lower right panel.

The following operations can be performed on the service Configuration:

• Re-query the list of applications and configuration values (Refresh)
• Modify configuration values on the remote device (Save)
• Discard unsaved changes without applying to the remote device (Refresh)

The example below shows the CloudService selected and a portion of the configuration parameters for the CloudService running on the remote device. If the application parameters require changes, make the changes and click the Save button. You will be prompted whether to apply the new configuration to the remote device. Click Yes to continue or No to cancel. If you have made local changes and wish to cancel without applying them, click the Discard button. You will be prompted whether to discard changes. Click Yes to discard changes or No to retain the local changes.

Configuration Snapshots

In Devices section of Everyware Cloud, select a device that is currently connected and open the Configuration tab. At the bottom of the tab, click on the Snapshots tab. This tab shows a list of configuration snapshots stored on the remote device.

Snapshots include all of the networking and application configuration settings stored in a single XML or JSON file. The following operations can be performed on the Configuration snapshots:

• Re-query the list of snapshots from the remote device (Refresh)
• Retrieve from the device a particular snapshot version (Download)
• Select a previous configuration snapshot to apply (Rollback)
• Upload a configuration snapshot to the remote device (Upload and Apply)

To retrieve a configuration snapshot from the remote device, select the Snapshot in the list and click the Download button. The file will be sent to the Web browser as an XML file. You may need to respond to a Web browser prompt to accept the file download.

To apply a previous configuration to the remote device via the Cloud Console, select an earlier snapshot in the list and click the Rollback button. You will be prompted to confirm the rollback. Click Yes to apply the configuration or No to cancel.

To apply a stored configuration snapshot to this remote device, click on the Upload and Apply button. Browse to the location of the stored XML file and click the Upload button.

If the configuration was successfully rolled back and/or applied, you will receive a success message, and the list of Snapshots will be updated from the remote device. The newly applied configuration will be shown as a new Snapshot.

Upload Snapshots using Jobs

Device Jobs allow uploading a snapshot over a fleet of devices running unattended in batch mode. To create and schedule a Job see Automated Management section in this guide, during the step configuration phase you can assign Configuration PUT operation to the step. Open the snapshot file that needs to be distributed to the fleet of devices and copy paste the content into the configuration property of the step, set all the other required parameters and submit.

📘

Partial uploads

The Configuration PUT operation allows to send to the device configuration fragments that are extracted from a snapshot. This is useful when the change targets some services while the others should remain the same.

Configuration Updates

With Snapshots, Jobs and Provisioning a user can change the whole configuration or just a part of it either in the same device or in a different device. To define an configuration update:

1. Download the initial snapshot in JSON or XML format from an existing device as described in the section Configuration Snapshots above
2. Open the snapshot file with a text editor and remove the unnecessary components
3. Change the properties in the remaining relevant components or add new components if required

The resulting set of configuration components can be applied to the device in several ways:

• Configuration Snapshots. Save the new configuration defined at step (3) above to a file, select a new device and then upload the file using the snapshot upload feature.
• Device Provisioning. Copy paste the new configuration defined at step (3) above in to the Additional configurations field of a provisioning request (see provisioning additional configurations section).
• Batch Jobs. Copy paste the new configuration defined at step (3) above into a job step of type Configuration PUT (see add job steps section).

📘

How ESF/Kura handles the update

The existing configuration in ESF/Kura will be merged at the property level with the new one sent by Everyware Cloud and a new snapshot will be created. The merge just adds new components and properties and replace existing properties.

Configuration Updates Examples

• Download Kura Wires graph using REST API
• Update Kura Wires graph using REST API

Certificates

In the Table tab under Devices, select a device that is currently connected to the Everyware Cloud. If the device supports remote management, click on the Certificate tab. This tab shows the information about the certificate installed on the device, if present. The status of the certificate is sourced from the database.

🚧

This is a potential source of desynchronization between device and platform!

If a device with a device management certificate installed changes its clientId, it is likely that the platform won't be able to manage remotely the device since it has no reference that the device has a certificate installed. Be careful when managing configurations of a device.

From this tab is possible to revoke the current Device management certificate or update the current with another. Using the REST API resource also allows to manage SSL certificate installed on the device.

If a device has a Device Management installed, all of the control messages sent to the device will have their content signed with the private key of the certificate. Upon reception, the device verify the signature before accepting the request with the public certificate. This ensures that the message is not tampered and it was sent by the platform.