This section explains the prepackaged heater demo bundle that comes with the ESF development environment. This document demonstrates how to perform the following functions:

• Run the ESF emulator

• Connect to the Everyware Cloud

• Gain a better understanding of ESF ConfigurableComponents

• Modify configurations of custom bundles

Prerequisites

• Everyware Cloud account credentials. (If you do not have an account, click here to create a free trial account.)

• Setting up ESF Development Environment

• ESF development environment running on a computer with Internet access so it can publish to the Everyware Cloud

Introduction

The org.eclipse.kura.demo.heater bundle is a simple OSGi bundle that represents a thermostat and heater combination. The application utilizes the ESF ConfigurableComponent interface to be able to receive configuration updates both via the local ESF Gateway Administration Console as well as the Everyware Cloud console. In addition, this bundle utilizes OSGi declarative services and the ESF CloudClientListener. This tutorial demonstrates how to modify configurations of custom bundles and shows how those configuration changes can dynamically impact the behavior of the bundle. Configuration changes are shown both through the ESF Gateway Administration Console and the Everyware Cloud Console.

Run the Bundle

By default, the header demo bundle does not run automatically. To run the bundle and ESF in the Emulator, locate the org.eclipse.kura.emulator project. Expand it to show the src/main/resources folder.

Right-click the correct ESFEmulator[OS].launch file, depending on which operating system you are running. In the context menu, select the Run As option, and click on Run Configurations.

Under OSGi Framework, click on the ESFEmulator[OS] entry. Select the Bundles tab and enable the org.eclipse.kura.demo.heater checkbox in the Workspace area as shown below.

Click the Apply and Run buttons to start the ESF Emulator.

Once this setting has been made, you only need to right-click on the launch file and select Run As and the ESFEmulator[OS] option to run with the same settings.

ESF starts locally and displays a Console window in Eclipse. The Console window shows the OSGi diagnostics as various bundles start and execute.

Configure the MQTT Client

After the bundle is started, open a web browser on the computer running the emulator and browse to http://127.0.0.1:8080/. Once connected to the web UI, a log in window appears prompting you to enter the Name and Password as shown below:

Enter the appropriate name and password (default is admin/admin) and click Log In. The ESF Gateway Administration Console appears as shown below:

From the ESF Gateway Administration Console, select Cloud Services in the System area, then select the MqttDataTransport tab. A window is displayed similar to the one shown in the following screen capture:

Use your Everyware Cloud account credentials to fill in the following fields, and then click Apply:

Now that the account credentials are set in the MqttDataTransport service, the DataService needs to be configured to connect by default. To do so, select DataService in the Services area and set the connect.auto-on-startup parameter to true as shown in the screen capture below. Then click Apply to allow the MQTT client to connect to the Everyware Cloud.

Modify Bundle Configuration Using the Everyware Cloud Console

With the MQTT client connected to the Everyware Cloud, you should be able to see the emulated device in the Everyware Cloud Console and see the published data as you view and modify the configuration of this bundle. Start by logging into the Everyware Cloud Console through a web browser and using your account credentials. The URL is one of the following depending on whether you have a Sandbox or Production account:

• Sandbox Account: https://console-sandbox.everyware-cloud.com/

• Production Account: https://console.everyware-cloud.com/

After logging in, select Devices in the left pane and choose the device based on the client identifier that was previously specified in the MqttDataTransport service configuration. You should see your device listed similar to the screen capture below where the client identifier of the device is “edcdemo-emulator”.

To view the configuration of the device and the bundles that are actively running on the system and implementing the use of ConfigurableComponent Java interface, select the Configuration tab in the Devices area. Select the Heater service to change the configuration of the heater demo bundle.

By default, the heater demo is configured according to the following characteristics and assumptions about its operational environment:

• Start operation is at 6:00am (06:00).

• End operation is at 10:00pm (22:00).

• It is colder outside than inside the heated chamber (hard-coded to 5 degrees in the application).

• Output of the heater is constant at 30 degrees (hard-coded).

• When in operational mode, the temperature drops inside if the heater is off.

• The heater turns off when it is about to exceed the setPoint defined in the configuration.

• After the temperature drops to four times the increment point (a made-up value to show dropping temperature, hard-coded in the application), the heater turns on again, and the temperature starts to increment at the ‘temperature.increment’ rate.

Using the default values supplied by the heater demo, you can view the heater temperature output of this application in the Data by Asset view of the Everyware Cloud Console.

Select Data by Asset in the left pane, and then select your emulated device in the Available Assets table as shown in the screen capture that follows. This view shows four metrics in the Available Metrics table. Select the temperatureExhaust, temperatureExternal, and temperatureInternal check boxes, and click Query. All of the data that has been transmitted from this device to the Everyware Cloud within the last 24 hours is displayed with these three metrics.

To view the results in graphical form, select the Results Chart tab. Optionally, you can click the Live button to see the data published in real-time.

At this point, you can dynamically change the configuration from the Everyware Cloud Console to see how it affects the data and graph. Browse back to the Devices area and select your emulated device. In the Configuration tab, select the Heater service and change some of the parameters to see the behavior changes in the remote device. The Results Chart in the following screen capture shows a configuration change from the defaults to the following settings:

• program.setPoint = 25

• temperature.increment = 1

After making this change in the Everyware Cloud Console and applying it, an MQTT message is published to the device. The ESF ConfigurationService receives and pushes the new configuration to the heater demo bundle using ConfigurationAdmin. This operation in turn calls the updated() method of the heater demo bundle, which then causes the bundle to change its behavior based on the new configuration.

Modify Bundle Configuration Using the ESF Gateway Administration Console

In addition to changing parameters through the Everyware Cloud Console, you can also make changes directly in the emulator web UI. For emulated devices running in Eclipse, browse to http://127.0.0.1:8080. (This URL was also used to configure the MQTT client previously in this tutorial.) For live devices with network access, browse to http://[ip_address_of_device].

From the ESF Gateway Administration Console, select the Heater bundle from the Services area and modify the parameters as needed (see screen capture below).

Similar to the process that occurs when modifying the configuration from the Everyware Cloud Console, the updated() method is called after settings are applied and the new configuration takes effect. Once changes are made in the local web UI, the new settings are also reflected in the Everyware Cloud bundle configuration menus.

After completing this tutorial, it is highly recommended that you look at the heater demo source code in Eclipse to see how it is put together. ESF automatically generates the user configuration interface through implementation of the ConfigurableComponent interface and some small additions to the component.xml file (called heater.xml). This powerful feature provides both a local and remote configuration user interface with no additional development requirements for either the local device or the Everyware Cloud Console.

Another feature that could be implemented (beyond the scope of this document) is to allow configuration updates via the REST API of the Everyware Cloud. These updates may be accomplished following the rules defined in this example (that is, by implementing the configurableComponent interface and creating the proper component.xml and metatype XML files).