Version 2.0 Original-Application Note ads-tec GmbH IRF2000 IWL3000 SRC1000 Application Note - Develop your own Apps with OSGi - getting started Stand: 28.10.2014 ads-tec GmbH 2014
IRF2000 IWL3000 SRC1000 2 1.0 01/08/2013 Initial Version 1.1 03/09/2013 Updated config.ini section 1.2 01/10/2013 Major Update for new Firmwareversion 1.3 25/10/2013 Renamed Log2Eventlog bundle 1.4 13/03/2014 Updated for IRF2000 firmware version 2.5.0 1.5 19/03/2014 Updated for ads-tec environment 1.1 2.0 28/10/2014 New adress Table of Contents Introduction... 3 Getting started... 4 1.1 Java Installation... 4 1.2 Eclipse Installation... 4 1.3 Prepare the Target Platform... 5 1.4 Hello World in Eclipse... 7 1.5 Device Preparations... 10 1.6 Hello World on the Target... 15 1.7 Bundle or data upload using SFTP... 18
IRF2000 IWL3000 SRC1000 3 Introduction The OSGi service platform is a module package and service platform based on Java. It implements a component and service model which is standardized by the OSGi alliance. The Java IDE Eclipse itself is the most popular software based on the OSGi service platform specification as every Eclipse plugin is an OSGi bundle. OSGi technology is in use in automobiles, energy supply, industrial, building automation, cloud and application services or handhelds. With the current firmware version of the IRF2000 ads-tec is providing a OGSi 4.2 service platform specification compliant extension. The ads-tec IWL3000 wireless LAN Access Point/Client and the SRC1000 storage rack battery controller accompany this and share the same API and environment. This enables you to develop your own application to run on the devices. This includes applications like: Custom Condition Monitoring Systems (CMS) based on standard or proprietary protocols with data collection and own web services directly running on the device. Protocol gateways for conversion of different protocols. For example Modbus/TCP to IEC61850 RS232 or RS485 based serial communication by using USB to Serial converters attached to the device. Send and Receive SMS by using the integrated 3G device of the IRF2210 Your own charge and discharge battery control algorithms on the SRC1000 including central control by control station protocols like IEC61850 or IEC60870-5-102 Monitor and record wlan signal strength and access point BSSIDs for location based services on the IWL3000 Custom device configuration Custom device diagnostics In combination with ads-tec Big-LinX a central OSGi service platform cloud service will be available allowing the combination of field applications with central applications based on the same development platform spanning over the complete Big-LinX virtual private network.
IRF2000 IWL3000 SRC1000 4 Getting started In order to get started you need a development workstation like a Windows or Linux based PC. This chapter will guide you through the complete installation process. 1.1 Java Installation In order to run Eclipse you will need an up to date Java JRE Installation on your system. Either a current version of Oracle Java or OpenJDK will suffice. To download and install Oracle Java Standard Edition (SE) you can use the following Link: http://www.oracle.com/technetwork/java/javase/downloads/ 1.2 Eclipse Installation You have to install the Eclipse IDE for Java EE Developers. As the OSGi environment on the target devices it based on Equinox 3.8.2 you should choose the Eclipse Juno Release which has Equinox 3.8.2 as its base too. Open a browser and go to: http://www.eclipse.org/downloads/packages/release/juno/sr2 and download the installation appropriate for your operating system. Eclipse does not have an installation. Just extract the downloaded zip file to a directory you like. Start Eclipse by either double click eclipse.exe (Windows) or type./eclipse (Linux) within the extracted directory. Eclipse will ask you for the workspace directory. This directory will contain all your source code later on. Eclipse should welcome you.
IRF2000 IWL3000 SRC1000 5 1.3 Prepare the Target Platform In order to run and debug an application within Eclipse comparable to the target device you need the right Plug-in Development Target Platform. Mostly this is an OSGi environment with the same bundle set as you will find on the target. Download the latest OSGi environment file from ads-tec GmbH and extract it under a suitable directory on your development system. http://www.big-linx.de/downloads/ads-tec-osgi-env-1-1.zip In Eclipse open the dialog Window -> Preferences Choose Plug-in Development -> Target Platform Click on Add and create an empty target definition Enter a name like ads-tec OSGi environment Click on Add and choose Directory
IRF2000 IWL3000 SRC1000 6 Select the Directory containing the extracted content of the ads-tec download Select Finish. If you change to the register Content you should see the imported bundles: Check the new environment to mark it as (Active) You can close the dialog by clicking OK
IRF2000 IWL3000 SRC1000 7 1.4 Hello World in Eclipse To get familiar with the IDE a Hello World Program is always a good idea. In this chapter the Hello World will run inside the Eclipse Target. Later on in this guide we will deploy it into an IRF2000. 1. Start a new Project by opening the dialog New -> Other 2. Choose Plug-in Project and click Next 3. Name the project Hello Word and edit the Target Platform as an OSGi framework: Equinox and click Next 4. At the line Execution Environment: open the drop down and choose <No Execution Environment> and click Finish at the bottom. 5. Eclipse might ask you to open the associated Plug-in Development Perspective, choose Yes 6. The welcome screen might appear again, close it
IRF2000 IWL3000 SRC1000 8 7. You should be able to open the Activator.java as shown in the screen shot 8. Every OSGi bundle has an Activator class, this is part of the OSGi service platform specification. This class must always have the two methods start() and stop(). 9. We insert a simple System.out.println( Hello Wold ); within start() and a System.out.println( Good bye ); within stop() package hello_world; import org.osgi.framework.bundleactivator; import org.osgi.framework.bundlecontext; public class Activator implements BundleActivator { } private static BundleContext context; static BundleContext getcontext() { return context; } /* * (non-javadoc) * @see org.osgi.framework.bundleactivator#start(org.osgi.framework.bundlecontext) */ public void start(bundlecontext bundlecontext) throws Exception { Activator.context = bundlecontext; System.out.println("Hello World!"); } /* * (non-javadoc) * @see org.osgi.framework.bundleactivator#stop(org.osgi.framework.bundlecontext) */ public void stop(bundlecontext bundlecontext) throws Exception { Activator.context = null; System.out.println("Good bye"); } 10. Click the Debug symbol or Choose Run -> Debug from the menu bar. Choose Debug as OSGi Framework
IRF2000 IWL3000 SRC1000 9 11. The Eclipse Console should output you a Hello World and leave you with the OSGi prompt. With a full size Console this should look like this: To get a list of all running bundles type lb. To stop the Hello Word bundle type stop 3 as the bundle was installed with ID 3 in this case. Restart it again with start 3. You can type help to get a list of all available commands. Please see the Equinox documentation for a complete list of commands for the OSGi console and what it is capable of. You might like to insert a breakpoint in the code and open the Eclipse Debug Perspective to finalize this small example.
IRF2000 IWL3000 SRC1000 10 1.5 Device Preparations Whether you have a preinitialized OSGi framework or not depends on your article number. In general if you already ordered a device with OSGi Extensions enabled you will find the packages already installed and you can directly goto step 3. within this paragraph. If you have an article without preinitialized extensions you will have to do the following steps. The OSGI framework has to be installed as a ads-tec System Extension. Connect the device to your network. The device will need an Internet connection and you should be able to open the web interface of the device. Assure that you have a license regarding Extensions on the device you own. You will have to order this license at ads-tec before you can go on. Open the device web interface, supposed to be under the default IP 192.168.0.254 on the IRF2000 or IWL3000. Open the page System -> Extensions. Your should get a screen with a Request license button on the bottom. Please click the Request license button. Please note: The device will need a working internet connection on TCP Port 80 to reach the license server on www.big-linx.de. If you need a HTTP proxy you can configure it on Configuration Network HTTP Proxy. If everything works well you will get a view like this: Otherwise you will have to check DNS settings and default gateway to make sure the device can reach the license server.
IRF2000 IWL3000 SRC1000 11 Now click on Refresh package list. If you are behind a restrictive firewall but have a working Big-LinX VPN connection up then you can check the checkbox Load extensions by using the Big-LinX VPN channel. Of course the HTTP proxy will be used if it was enabled Note: The extension packages on the server can differ depending on the firmware version or product you are using. Older firmware versions will be provided with older extension versions if there is a compatibility dependency. Note: The installed extensions are stored in the configuration as a list. This list will get loaded if you load a configuration file or start a plain device with either a Big-LinX smartcard or memory card. The device will then try to install the configured extensions from the extension server automatically. You will see a list of available Extensions. For getting started you will need to choose install at the extensions OSGi, OSGi-log2eventlog and OSGi-jsonrpc2. All depending extensions like the Java Virtual Machine will be selected automatically. Click on Apply settings to start the download. Depending on the speed of the internet connection this might take some time to complete.
IRF2000 IWL3000 SRC1000 12 The result should look like this. The row Installed version indicates which extensions are installed. As another effect you might have noticed that the web interface now got a new menu entry on the left called Extensions. Open the new main menu entry Extensions in the left and take a look, there are two pages. The OSGi Configuration File page contains the editable config.ini belonging to the OSGi framework. You will most likely not have to edit it. This page is meant for Java developers who might need it to add own configuration options. The config.ini should only contain lines in the form variable=value. If a line gets too long (>256 characters) you can append a \ at the end to start a multi line definition. For a complete documentation to the config.ini see the Eclipse Equinox documentation.
IRF2000 IWL3000 SRC1000 13 The bundle upload page is more important. If you want to deploy your own OSGi bundle you can use this page for the installation. There is however an alternative method for bundle upload using SFTP. This will be described later on in this guide. The default OSGi config.ini enables the OSGi telnet console on localhost TCP port 5555. This Port can be accessed through the integrated SSH server. To use the OSGi console in a secure way you have enable the special OSGi user account first and configure your own password. Open the page Configuration -> Access control -> User accounts. You will see that the OSGi extension has installed the user OSGi. This is a special username you can not use another user for OSGi console access. Please note that the user account OSGi has full permissions on the system comparable to the admin user. Check the box Activate account and enter a new password for the user OSGi. Click Apply settings
IRF2000 IWL3000 SRC1000 14 Now you can connect to the OSGi console on the target by opening a SSH client. PuTTY is a good choice if you are working with Windows. You can download PuTTY here: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Choose Connection type SSH and enter the IP address 192.168.0.254 and Port 22. Click on Open. If you use this connection for the first time you will be asked to accept the hosts public key fingerprint. You will be asked for username and password. Use osgi as user and enter your new password. You should see the OSGi Console, lb will list the installed bundles.
IRF2000 IWL3000 SRC1000 15 1.6 Hello World on the Target In order to deploy the previously developed Hello World on the target device you have to open the project in Eclipse again. in Eclipse Open the dialog File -> Export 2. Select Deployable plug-ins and fragments and click Next 3. Mark the checkbox for the Hello_World Plug-in and enter a directory for the export. Click Finish Eclipse should export the Plug-in
IRF2000 IWL3000 SRC1000 16 Now you should have a Folder called plugins within the directory you specified. Start a browser and open the Bundle Upload Page. Select your generated Hello_World jar file and click on Upload OSGi bundle The file should now be listed as installed Open a SSH console to TCP Port 22, the Equinox OSGi console should welcome you. Type lb to see in which state your new bundle is. Type start <id> or stop <id> to start or stop it.
IRF2000 IWL3000 SRC1000 17
IRF2000 IWL3000 SRC1000 18 1.7 Bundle or data upload using SFTP If you have a large number of bundles to upload or want to up/download some data files you need for you applications you can use SFTP. SFTP is a secure version of FTP using SSH as transport channel. If you do not already have a SFTP capable program you should download and install WinSCP from: http://winscp.net/eng/download.php To connect using SFTP Start WinSCP and use 192.168.0.254 TCP Port 22 and user ogsi as you already know it from putty. The only supported file protocol is SFTP. SCP is not supported! You will get the following folder structure. The following folders are important: fileinstall: upload all bundle files here. The web interface OSGi fileinstall uses this directory too. The integrated Apache Felix Fileinstall bundle will pick up the file and install it inside the framework. If you delete a file Felix Fileinstall will uninstall the bundle. opkg: bundles which are contained in ads-tec extensions will be put here. This directory is read-only. If you want to remove a bundle from there please use the Extensions web interface. data: you can use this directory for any other data exchange configuration: the Equinox configuration directory. You have full write access here in case you want to remove a broken bundle manually. Equinox installs bundles using the ID as directory. i.e. /usr/local/equinox/configuration/org.eclipse.osgi/bundles/10 is the installation place for bundle ID 10. If you break your framework by deleting the wrong files you will have to reinstall the OSGi extension.
IRF2000 IWL3000 SRC1000 19 Please note that the main framework jars are all read only as they are managed by the extensions system and referenced on boot up from the embedded Linux base system. - OSGi is a trademark or a registered trademark of the OSGi Alliance in the United States, other countries, or both