PART 2. ADMINISTRATOR’S GUIDE
Managing Devices

 

Devices

·         Devices: Table

·         Devices: Map

·         Remote Management of ESF Devices

o   Packages

o   Bundles

o   Configuration: Services

o   Configuration: Snapshots

o   Command

 

 

 

Devices

The Devices panel in the Everyware Cloud Console provides status information about the devices that are connected to your Everyware Cloud account.  The Devices panel is only available if the user has “devices:view” permission.

 

Upon establishing a connection to the Everyware Cloud, devices publish a Birth Certificate message that contains information on their hardware and software configuration.  Devices will also notify the Everyware Cloud when they disconnect gracefully by publishing a Death Certificate message.  Through the characteristics of the MQTT protocol should a device lose its connection to the Broker, the Everyware Cloud platform is informed through a Last-Will Testament message.  These three life-cycle messages allow the Everyware Cloud to track the current status of each device under the account.

 

See the MQTT Introduction for more information on the MQTT protocol.

 

The Devices panel in the Everyware Cloud Console allows account administrators to monitor the status and review the full life-cycle history of their devices.  When using an Everyware Software Framework version 2.0 (ESF 2.0) enabled device, the Devices panel also allows devices to be remotely configured and controlled while they are connected to the broker.

 

 

 

Devices: Table

The Table tab under Devices lists all devices that have been connected to your Everyware Cloud account.  Devices currently connected and devices that have previously been connected are all displayed as shown in the following screen capture.

 

·         With “devices:manage” permission, you can perform the following tasks using the buttons provided in the Table tab:Refresh status of devices (Refresh)

·         View the status of your devices in real time (Live)

·         Export the device information to Excel or CSV (Export)

·         Delete a device (Delete)

 

Deleting a device only deletes the profile and history information.  It does not delete the data published by the device.

 

 

The following table describes the information displayed for each device in the Table tab.

 

 

Client ID identifies a physical device and its MQTT connection.  The hierarchical nature of the MQTT topic namespace can be leveraged to describe a topology of gateway devices, applications running on the gateways, and/or sensors connected to the gateways.  As described in the Everyware Cloud Protocol, Everyware Cloud refers to the second token of the MQTT data topic as an Asset ID.  By default, the Everyware Cloud client libraries and the Everyware Software Framework follow the convention of passing the Client ID, which identifies the gateway device, as the Asset ID in all the data topics.  Data published by a given Asset can then be queried in the Data by Asset section of the Everyware Cloud Console.

 

You can access profile information using the Profile tab or historical data about your device using the Events tab.  To view profile information, select the device and then click the Profile tab as shown in the following screen capture.

 

 

To view historical data, select the device and then click the Events tab as shown in the following screen capture.  Select the Date Range to control the period over which events will be displayed.  You can export this data in Excel or CSV format by clicking the Export button under the Events tab.

 

 

 

 

Devices: Map

For devices equipped with GPS information, the Birth Certificate message may contain the GPS coordinates of the device at the time of establishing its connection.  For ESF-enabled devices, the bootstrap process will automatically compose a Birth Certificate that includes the GPS coordinates of the device.

 

The Map tab under Devices provides a graphical view of the location of your devices as shown in the following screen capture.  You must click on the device in the Table tab to select it prior to viewing it on the map.

 

 

 

 

Remote Management of ESF Devices

Beginning with Everyware Cloud release 3.0, the Everyware Cloud Console supports remote device management.  This capability allows supported devices to be remotely configured and controlled while they are connected to the broker.

 

Everyware Software Framework (ESF) is a framework to develop M2M applications based on Java and OSGi.  Following the OSGi component model, an M2M application is packaged into a bundle composed of one or more OSGi Services.  The M2M application may manage one or more resources, for example sensors, actuators, or local files.  Applications manage resources by being able to list them, read the latest value, or update them to a new value.  In addition, as with any OSGi Service, M2M applications can provide metadata to describe their configuration properties following the Meta Type Service Specifications, and they can receive new configuration values through the OSGi Configuration Admin Service.

 

With the introduction of the ESF 2.0, a device connecting to the Everyware Cloud provides the list of M2M cloud-enabled applications running on the gateway.  A cloud-enabled application allows for the remote management of its resources through simple MQTT messages.

 

ESF 2.0 comes with three bundled cloud-enabled applications that allow the remote management of certain aspects of the framework through the MQTT connection.  In particular, the following remote operations can be performed on devices enabled with the ESF 2.0:

·         Remote deployment of application bundles (packages)

·         Remote start and stop of services

·         Remote read and update of cloud-enabled service configurations

·         Remote execution of operating system commands for remote diagnostics

 

When a device enabled with ESF 2.0 connects to Everyware Cloud, the Everyware Cloud Console will enable the remote device management tabs in the Devices panel: Packages, Bundles, Configuration, and Command.  The following sections provide more details on how to use these management tabs.

 

Packages

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 Packages tab.  This tab shows a list of installed OSGi packages on the remote device.  Click on the arrow next to the package name to view the list of included services.

 

You can perform the following operations using the buttons provided in the Packages tab:

·         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.  Packages must have been created as ESF 2.0 deployment packages.  They may either be installed from a file on the local computer network or downloaded from an Internet URL. 

 

To install a package from the local computer network, select the Upload tab and click the Browse button to select the local deployment package to install.

 

 

To install a package from an Internet URL, select the Download tab and enter the complete URL pointing to a deployment package to install onto the remote device.

 

 

 

In either case, click the Submit button to install the package.  If the package installation was successful, a success message will be displayed.

 

 

The list of installed packages will be refreshed.

 

 

 

To uninstall an existing package, select the package name and click the Uninstall button.  You will be prompted to confirm whether you wish to proceed with the uninstall.  Click Yes to proceed or No to cancel.

 

WARNING: Uninstalling packages may lead to unexpected effects on the remote system.  In particular, uninstalling the ‘esf’ package will stop the ESF application from running and permanently disconnect the remote device from the Everyware Cloud!  This will require that the remote unit must be physically accessed so it can be reconfigured.

 

 

 

Bundles

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 Bundles tab.  This tab shows a list of OSGi service bundles available on the remote device.  Click on the headings (ID, Name, etc.) to sort the list of services in order or reverse-order for that heading.

 

You can perform the following operations using the buttons provided in the Bundles tab:

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

 

WARNING: Stopping certain bundles may lead to unexpected effects on the remote system, including disconnecting the remote device from the Everyware Cloud!  This will require that the remote unit must be physically accessed so it can be reconfigured.

 

 

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.

 

Configuration: Services

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 Configuration tab.  At the bottom of the tab, click on the Services tab.  This tab shows a list of cloud-enabled applications running on the remote device.  Click on the name of an application in the lower left panel to display list of configuration parameters in the lower right panel.

 

You can perform the following operations using the buttons provided in the Configuration: Service tab:

·         Re-query the list of applications and configuration values (Refresh)

·         Modify configuration values on the remote device (Apply)

·         Discard unsaved changes without applying to the remote device (Reset)

 

The example below shows the CloudService application 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 Apply button.  You will be prompted whether to apply the new configuration to the remote device.  Click Yes to continue or No to cancel.

 

WARNING: Incorrectly configuring an application may result in unexpected operation.  In particular, reconfiguring the CloudService application incorrectly will lead to the remote device losing connection with the Everyware Cloud!  This will require that the remote unit must be physically accessed so it can be reconfigured.

 

 

If you have made local changes and wish to cancel without applying them, click the Reset button.  You will be prompted whether to discard changes.  Click Yes to discard changes or No to retain the local changes.

 

 

 

Configuration: Snapshots

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 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 to be stored in a single file, and previous snapshots of a configuration can be rolled back if necessary.

 

You can perform the following operations using the buttons provided in the Configuration: Snapshots tab:

·         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)

 

The example below shows four device snapshots, including the current (latest) configuration.

 

 

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.

 

The following screen capture shows a portion of the contents of the XML file for an ESF 2.0 device configuration snapshot.  Configuration values are stored in XML tags and elements, most of which are hidden in the sample below.  The top level tags show that this configuration includes properties for the NetworkConfigurationService (networking properties of the device), plus the configuration values for built-in ESF applications (such as ClockService, PositionService, and CloudService).

 

 

 

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.

 

WARNING: Applying an incorrect configuration to a remote device may result in unexpected operation, including loss of connection with the Everyware Cloud!  This will require that the remote unit must be physically accessed so it can be reconfigured.

 

 

 

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.

 

 

 

Command

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 Command tab.  This tab allows commands to be executed on the remote device.

 

You can perform the following operations using the buttons provided in the Command tab:

·         Execute a command on the remote device (Execute)

·         Download a Zip file to the remote device (File)

 

WARNING: Care should be taken in the choice of commands to execute and files to download.  Incorrect application of commands or files may cause unexpected results in the remote device.  This may require that the remote unit must be physically accessed so it can be reconfigured.

 

 

The Command example shown in this section uses a Zip file called cloud.zip that contains the following files in a flat directory format (no subdirectories):

1. A file named test.sh that is intended to reside in the /etc/init.d/

2. A script file named script.sh containing the following installation script:

 

#!/bin/sh

echo -e "Executing command on remote device\n"

mv test.sh /etc/init.d/

ls -l /etc/init.d/test.sh

echo

ifconfig

 

The following screen capture shows the Execute parameter set to sh script.sh.  The file cloud.zip has been selected using the Browse button.  (The File parameter is optional.  You can simply execute a command using the Execute parameter, without also downloading a file.)

 

When you click the Execute button, the cloud.zip file is downloaded to the remote device, its contents are extracted into the /tmp/ directory, and the cloud.zip file is deleted.  Then the command sh script.sh is executed at the remote device’s command line, which runs the script.sh file that was just extracted.  No path is necessary because the /tmp/ directory is assumed by default.

 

The output of the resulting command is returned by the remote device and displayed in the lower portion of the Command panel.  In this example, the script moved the file test.sh from /tmp/ to /etc/init.d/, performed a directory listing to validate that the file was present in its correct location, and then did an ifconfig command on the remote device.

 

 

 

To clear the Execute and File parameters, click the Reset button.