This section provides a simple example showing how to test and deploy OSGi bundles and deployment packages in an ESF environment. These instructions use the “Hello World” OSGi project created in the previous section. In this example, you will learn how to

· Use local OSGi emulation mode in Eclipse

· Deploy a bundle to a remote target running the OSGi Framework

· Install a Deployment Package to a remote target running the OSGi Framework

· Manage OSGi bundles on a target device

· Set bundle Logger levels in ESF

Prerequisites

· Setting up ESF Development Environment

· Hello World Using the ESF Logger

Testing the OSGi Plug-in

Once you have created an OSGi plug-in, you can test it in Local Emulation Mode and/or deploy it to a Remote Target Device.

Local Emulation Mode

The ESF user workspace can be used in Eclipse in local emulation mode (Linux/OS X only; this feature is not currently supported under Windows). To deploy the code to a running system, see the section Remote Target Device.

Run ESF in Emulator Mode

In the Eclipse workspace, locate the com.eurotech.framework.emulator project. Expand it to show the src/main/resources folder.

Right-click the correct ESF_Emulator_[OS].launch file, depending on which operating system you are running (where “[OS]” is “Linux” for a Linux system or “OSX” for a OS X system). In the context menu, select the Run as option, and select the ESF_Emulator_[OS]. This will start ESF running locally and will display a Console window in the bottom pane in Eclipse. The Console window will show the OSGi diagnostics as various bundles start and execute.

Because the com.eurotech.example.hello_osgi bundle is in the workspace with a valid activate() method, it is automatically started with the ESF OSGi framework. Note the DEBUG diagnostic message highlighted below, showing that the bundle’s activate() method was run.

List OSGi Bundles in Local Mode

With the OSGi framework running in the Eclipse console (refer to the previous section), click in the Console window. Type the ‘ss’ command to show a list of installed bundles. Note the bundle ID number for the com.eurotech.example.hello_osgi bundle.

Start/Stop Bundle in Local Mode

In the OSGi Console window in Eclipse, run the ‘start ##’ or ‘stop ##’ commands to start or stop a bundle, where the “##” is either the bundle ID number or the bundle name (such as “start com.eurotech.example.hello_osgi”). Note the INFO messages for both the activate() and deactivate() messages appear in the Console window when the bundle is started or stopped.

Install/Uninstall Bundle in Local Mode

In the OSGi Console window in Eclipse, bundles can be installed or uninstalled. To uninstall the example bundle, issue the command ‘uninstall ##’, where “##” is either the bundle ID number or the bundle name, such as

uninstall 11

or

uninstall com.eurotech.example.hello_osgi

Once the bundle has been uninstalled from the local OSGi console, it cannot be started or installed by number or name. It must be installed by using the plug-in JAR file created earlier. Issue the ‘install’ command to install a bundle into the Emulation environment:

install file:/[path_to_bundle]/[bundle_name].jar

where “[path_to_bundle]/[bundle_name].jar” should be replaced with the name of the bundle exported earlier (the section Hello World Using the ESF Logger). For example,

install file:/Users/admin/Documents/plugins/com.eurotech.example.hello_osgi_1.0.0.201306211010.jar

Then the bundle can be started or stopped, as described in the previous section, Start/Stop Bundle in Local Mode. Or, add the flag ‘-start’ to the ‘install’ command to automatically start the bundle after installation.

Remote Target Device

One or more OSGi bundles can be deployed to a remote device running ESF, either by installing separate bundle files or deployment packages using Eclipse. (Note, these steps require ESF version 2.0 or higher to be running on the target device.) This method of deployment is temporary on the remote target device and is not persistent after a restart. To make the deployment permanent, see Making Deployment Permanent.

Connect to Remote OSGi Framework

To deploy a bundle to the remote target device, you will need to connect Eclipse to the OSGi framework running on the device. This is done using mToolkit. See ESF Setup for instructions on installing mToolkit into the Eclipse development environment.

· Select the Eclipse menu Window | Show View | Other.

· Select mToolkit -> Frameworks entry to open the mToolkit Frameworks view.

· Enter a name for the framework definition and the IP address of the target device. Use the default port 1450.

· You may wish to select the checkbox Auto connect to the remote framework, after it’s creation, to automatically open the connection.

· Then click OK.

Close the dialog by clicking the Connect button.

NOTE: The remote target device must have port 1450 open in its firewall, in order to allow mToolkit to make a connection to its OSGi framework. If it doesn’t, see the section Open Port for OSGi Remote Connection.

If you have selected the Auto connect checkbox, Eclipse will connect to the remote framework immediately. Otherwise, right-click the framework icon name and select Connect Framework. The list of installed bundles and deployment packages should be retrieved shortly. (Use the Disconnect Framework option to disconnect from the remote target framework, once finished.)

Open Port for OSGi Remote Connection

In order to allow mToolkit to make a remote connection to the OSGi framework on the target device, the device must allow the incoming port in its firewall. To set this option, open a Web browser and log into ESF using its current IP address, such as

http://10.11.5.4

Click the Firewall icon and then click the Open Ports tab. If port 1450 is not shown in the list of allowed ports, click the New button under Open Ports.

Enter the port 1450 and select protocol TCP. Then click Submit.

Now, click Apply to apply changes to the remote device.

Install Single Bundle to Target Device

With the Eclipse environment connected to the remote OSGi target framework, a single bundle can be installed on the remote device.

In the mToolkit Frameworks view, right-click the Framework name and select Install Bundle. (This requires that you have exported the bundle as a deployable plug-in JAR file. See the section Hello World Using the ESF Logger.)

Use the Browse button to select the JAR file and click OK to install it to the target device.

The newly installed bundle should be shown in the Frameworks view under Bundles.

To control operation of the bundle through the OSGi Frameworks view, right-click the bundle name. The following actions can be performed:

· Start – start the bundle

· Stop – stop the bundle

· Update – reinstall the bundle

· Install Bundle – install a different bundle

· Uninstall Bundle – remove this bundle from the target device

· Show Bundle IDs / Show Bundle Versions – show additional information about bundles

You can also verify operation of the bundle on the target device itself. See the section Manage Bundles on Target Device.

Install Deployment Package to Target Device

With the Eclipse environment connected to the remote OSGi target framework, a deployment package can be installed on the remote device.

(If you have just installed the individual bundle in the previous section, you should uninstall it before proceeding. This step will avoid confusion of having the same bundle installed twice.)

In the mToolkit Frameworks view, right-click the Framework name and select Install Deployment Package. (This requires that you have exported the bundle as a deployable plug-in JAR file. See the section Hello World Using the ESF Logger for instructions on exporting the OSGi bundle.)

Open the resources/dp folder in the Workspace filesystem directory, select the .dp file (not the “.dpp” file), and click OK.

The deployment package will be installed on the target device and will be shown in the Frameworks view under Deployment Packages. (The deployment package can also be uninstalled from the Framework view.)

The bundle included in the deployment package can also be viewed under Bundles and can be controlled remotely (start/stop) as with other bundles.

You can also verify operation of the bundle on the target device itself. See the section Manage Bundles on Target Device.

Connect to OSGi on Target Device

You can manage the OSGi framework on a target device by logging into a console on the device using a connected keyboard and VGA monitor or over a network connection using SSH (PuTTY in Windows or ‘ssh’ from Linux or Mac).

At the command prompt, display the OSGi diagnostic file (in the background) and log into the OSGi framework by typing the following commands:

tail -F /var/log/esf.log &

telnet localhost 5002

There are many commands available in the OSGi console for managing bundles. Following are just a few useful commands:

ss	list names and ID of bundles
help	show help menu of OSGi commands
getesfloglevel [logger_name]	shows the ESF log level for all loggers, or for a specific logger if specified by name
setesfloglevel (ALL \| <logger_name>) <log_level>	sets the ESF log level for a given logger, or all loggers if 'ALL'. The valid log_level options are: ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF
lb	list all installed bundles and IDs
h (list of bundle IDs)	print bundle headers
exit	Exit the OSGi console and stop ESF
disconnect	Exit the OSGi console, but leave ESF running

After disconnecting from the OSGi console, you can kill the ‘tail’ command (started earlier) with

killall tail

Manage Bundles on Target Device

While in the OSGi command console, you can display a list of bundles with the ‘ss’ command.

ss

Notice the bundle ID is 58 in the example.

You can run the ‘start ##’ or ‘stop ##’ commands to start or stop a bundle, where the “##” is either the bundle ID number or the bundle name (such as “start com.eurotech.example.hello_osgi”). Note the INFO messages for both the activate() and deactivate() messages are shown because of the ‘tail’ command run above, whenever the bundle is started or stopped.

Note that previously when testing in the Emulator within Eclipse, we only received on INFO message on startup of the bundle. This time, we receive two messages on startup, an INFO and a DEBUG message. This is because in the Emulator, the “hello_osgi” bundle was started at the INFO logging level, but within ESF it starts by default at the DEBUG logging level. So both messages are output to the esf.log file. The next section describes how to change the ESF logger level for a bundle.

Set ESF Logger Levels

While in the OSGi command console, you can show the ESF logging level with the command:

getesfloglevel

Or you can display the ESF logging level for a particular class by typing a command using the specific service that has implemented the Logger class, such as

getesfloglevel com.eurotech.example.hello_osgi.HelloOsgi

You can then set the ESF logging level for the logger by using the command: ‘setesfloglevel <logger_name> <log_level>’, as described above, such as

setesfloglevel com.eurotech.example.hello_osgi.HelloOsgi INFO

Now, note that starting the hello_osgi bundle only yields one INFO logger message because we have set the Logger level to “INFO” and are no longer showing the DEBUG (or TRACE) messages.

The preceding instructions only change the logging level for services in the current session of ESF. To make logging levels permanent, you need to modify an ESF configuration file. To do this step, exit from the OSGi console by entering the ‘disconnect’ command.

Then from the Linux command prompt, edit the Logger settings by typing the command

nano /opt/eurotech/esf-[target device]_1.0.0-SNAPSHOT/esf/log4j.properties

where “[target device]” should be replaced with the actual directory name, depending on the target device upon which ESF is installed.

At the bottom of the “log4j.properties” file, there will be one or more “log4j” logger property entries, which determine the Logger level used by the bundles at startup. The Logger levels are hierarchical, so that those in a deeper level of the hierarchy will apply, if present; otherwise, they will be overridden by the more general Logger level.

In the example screen capture shown below, the “log4j.logger.com.eurotech” property has been set to “INFO”, which applies to all bundles starting with “com.eurotech.” But the “log4j.logger.com.eurotech.example” property has been set to “DEBUG”, which means that any deployed bundles that start with the more specific “com.eurotech.example” will take on the “DEBUG” Logger level at startup.

Exit from ‘nano’ and save changes, then restart ESF. Check the log levels in the OSGi console again to make sure the desired levels have taken effect.

Making Deployment Permanent

The mToolkit deployment of a package is a temporary installation and does not make the package permanent. Once a set of bundles has been tested on the remote target device and is ready to be deployed permanently, there are several methods of installing the software on a device using deployment packages. A few of these methods are

· Install through Everyware Device Cloud – See Managing Devices (EC Developer’s Guide).

· Install through ESF Gateway Administration console – See ESF Gateway Administration Guide.

· Install from command line of target device – See instructions below.

To install a deployment package from the command line of a target device, follow these steps:

1. Copy the deployment package file (*.dp) to the target device, into the folder:

/opt/eurotech/esf/esf/packages

2. Edit the dpa.properties file with the following command:

nano /opt/eurotech/esf/esf/dpa.properties

3. Add an entry in the dpa.properties file to include the new package name, such as

package_name=file\:esf/packages/package_filename.dp

where “package_name” and “package_filename” should be replaced with the actual name of the deployment package.

4. Close and save the file (Ctrl-X and follow prompts).

5. Then restart ESF, and the new package should be installed in addition to the default ESF package.

In conclusion, this document has described how to test a bundle in an Emulation environment within the Eclipse IDE and how to install bundles and Deployment Packages to a remote target system running ESF.

Version 2.0 - Legacy

Last: Vers.7.xx - 2022

PART 2. GETTING STARTED
Testing and Deploying Bundles

Overview

Prerequisites

Testing the OSGi Plug-in