About this tutorial

This tutorial will provide an initial overview for the ZigBee 4 OSGi project, enabling the reader to execute the ZigBee 4 OSGi suite for the control of ZBee devices in the network.

Before starting

Before trying to execute ZigBee 4 OSGi, you must check if all the following requirements are satisfied.

Hardware Requirements

ZigBee 4 OSGi requires a PC with a compatible ZigBee dongle plugged, at the time of writing this wiki page only the Texas Instruments USB dongles are supported.

Hardware configuration

Officially Supported Should be working device:

For the case of CC2531 and EZ430-RF2480 it is necessary also to install the right driver in order to install the USB dongle as virtual COM driver. Please refer to the Texas Instruments web site.
In any case, if you have a different hardware and you aim at use ZigBee 4 OSGi, you should get in touch with the community, asking for support. All in all someone could have already developed the prototype that your are looking for. For any question, please refer to the mailing-list

Software Requirements

ZigBee 4 OSGi doesn't require any special software except for:
  • Java 5 (or Java 1.5+)
  • OSGi 3 compliant framework
  • Operating System supporting the RXTX library http://rxtx.qbang.org/wiki/index.php/Main_Page (this library enables the Java interaction with serial port) i.e. Win2k, WinXP, Linux, Solaris, Mac OS X, and others

Nevertheless, if you want to modify the ZigBee 4 OSGi stack you need to install into your OSGi platform an implementation of the "OSGi Configuration Admin". The current ZigBee 4 OSGi release refers to the Pax ConfMan as OSGi Configuration Admin bundle

Obtain the code

From the source repository

The source repository used by ZigBee 4 OSGi is Subversion, you will need SVN tool in order to get the code.
If you download the code from the source repository, you need also to build the whole project. The life-cycle project is managed with Apache Maven tool, so you also need Maven for building it. Of course, also a Java Developer Kit (JDK) is required.
Maven will take care to download all the dependencies, so if it's your first time the building process may a couple of minutes.
The projects are also configured to set-up of running an OSGi environment, by means of Maven. As result, running and testing the projects become easy also for non-OSGi expert. In particular, the creation of the OSGi environment uses the Pax Runner which download on demand all the OSGi bundles related to the execution environment.

Building from the source instructions

  1. Download the development branch from https://svn.aaloa.org/projects/zb4osgi/trunk, for example launching the command
    svn co https://svn.aaloa.org/projects/zb4osgi/trunk zb4osgi-trunk
  2. Move to ZB4OSGi-trunk\ and build the whole project using command
    mvn install
  3. Move to zb4osgi-trunk\zigbee.tester and create the OSGi environment using the command
    mvn pax:run
    A new sub-directory, named 'runner', is created.
  4. Launch zb4osgi-trunk\zigbee.tester\runner\run.bat or run.sh to start-up the OSGi environment (doing a "chmod +x run.sh" will grant execution permissions).
If you encounter trouble with the project build (e.g. trove4j can not be found by ZigBee Base Driver bundle) you can:
  1. Backup your .m2\repository maven directory
  2. Empty your .m2\repository maven directory
  3. Restart the procedure previously described

Early access to bug fixes and improvements

Some bug fixes or improvements may available in SVN developers' sandbox (as SVN branches of the trunk). Users can have early access to those changes by just checkout the desired sandbox (or all the sandboxes).

  1. Download all the sandboxes https://svn.aaloa.org/projects/zb4osgi/sandbox with the command
    svn co https://svn.aaloa.org/projects/zb4osgi/sandbox sandbox
  1. Download the sandbox branch from https://svn.aaloa.org/projects/zb4osgi/sandbox/<directory_name> with the command
    svn co https://svn.aaloa.org/projects/zb4osgi/sandbox/directory_name

where directory_name is a developer directory contained in the sandbox(eg. for downloading the giancarlo.riolo's sandbox you have to execute svn co https://svn.aaloa.org/projects/zb4osgi/sandbox/giancarlo.riolo )

Then build the source as described above ( * )for trunk.

From the release

If you don't want to setup and configure everything by hand you can download the <refer to release> that contains an OSGi enviroment with all the required dependencies for starting with the ZigBee 4 OSGi suite.
The release comes in 2 compression formats: tar.gz and zip archive. Decompress the archive into a custom folder and have a look at the directory structure:
  • bundles: contains the required OSGi bundles
  • cache: OSGi execution environment cache
  • configurations: OSGi bundle configuration.
    Please consider is.cnr.isti.zigbee.driver.configuration.properties containing some important configurations. Edit accordingly the "portname" properties in order to specify the COM port used to communicate with the ZBee USB dongle
    felix: OSGi felix stuff
Also two script file are provided:
  • run.bat: for Win OS
  • run.sh: for Unix OS

Select the one you need and lunch it.

Executing the ZigBee 4 OSGi suite

Without considering how you decided to run ZigBee 4 OSGi, now you own a script file!

A simple start

The script runs the Felix OSGi environment. The OSGi environment will be loaded with a terminal console, with the following bundles:


START LEVEL 6
   ID   State         Level  Name
[   0] [Active     ] [    0] System Bundle (2.0.2)
[   1] [Active     ] [    5] Zigbee Tester (0.5.0.SNAPSHOT)
[   2] [Active     ] [    5] OSGi R4 Core Bundle (4)
[   3] [Active     ] [    5] ZigBee Home Automation Profile Driver (0.8.0.SNAPSHOT)
[   4] [Active     ] [    5] ZigBee Common Cluster Library (0.9.0.SNAPSHOT)
[   5] [Active     ] [    5] ZigBee Base Driver API for OSGi (0.7.0.SNAPSHOT)
[   6] [Active     ] [    5] CC2480 Data Link protocol library (0.9.0.SNAPSHOT)
[   7] [Active     ] [    5] OPS4J Pax Logging - API (1.4)
[   8] [Active     ] [    5] OPS4J Pax Logging - Service (1.4)
[   9] [Active     ] [    5] OSGi and Primitive Types Utility (0.6.0.SNAPSHOT)
[  10] [Active     ] [    5] Apache Felix Configuration Admin Service (1.2.4)
[  11] [Active     ] [    5] OPS4J Pax ConfMan - Properties Loader (0.2.2)
[  12] [Active     ] [    5] Apache Felix File Install (3.2.6)
[  13] [Active     ] [    5] rxtx Bundle Wrapper (2.1.7.SNAPSHOT)
[  14] [Active     ] [    5] net.sf.trove4j Bundle Wrapper (2.0.4.1)
[  15] [Active     ] [    5] ZigBee Interface Controller API (0.8.0.SNAPSHOT)
[  16] [Active     ] [    5] ZigBee Base Driver (0.8.0.SNAPSHOT)
[  17] [Active     ] [    5] ZigBee Health Care Profile Driver (0.1.0.SNAPSHOT)
[  18] [Active     ] [    5] ZigBee Energy@Home Profile Driver (0.1.0.SNAPSHOT)
[  19] [Active     ] [    5] ZigBee Health Care Cluster Library (0.1.0.SNAPSHOT)
[  20] [Active     ] [    5] ZigBee Smart Energy v.1 Cluster Library (0.1.0.SNAPSHOT)
[  21] [Active     ] [    5] Energy@Home Cluster Library (0.1.0.SNAPSHOT)
[  22] [Installed  ] [    5] ZIC for CC253x devices (0.3.0.SNAPSHOT)
[  23] [Installed  ] [    5] ZIC for EZ430-RF2480 dongle (0.8.0.SNAPSHOT)
[  24] [Installed  ] [    5] STUB implementation of:OSGi ZigBee Base Driver (0.2.0.SNAPSHOT)
[  25] [Active     ] [    1] Apache Felix Shell Service (1.4.1)
[  26] [Active     ] [    1] Apache Felix Shell TUI (1.4.1)

 Generally OSGi supports the following syntax in order to start a bundle:

 <pre>start <id></pre>
Where <id> is the number of the bundle. The <id> can be easily obtained listing the bundles:
 <pre>ps (or as alternative lb)</pre>

Finally you can choose to start  _"ZIC for EZ430-RF2480 dongle"_ bundle or _"ZIC CC2530 dongle"_. This depends on you current hardware configuration. If you are using a CC2530 based USB dongle, then: 
 <pre>start 22</pre>

or for the EZ430-RF2480 dongle:
 <pre>start 23</pre>

otherwise for a stub implementation of the driver:
 <pre>start 25</pre>

*NOTE:* The <id> of your bundles can be different from the ones presented here. Do not forget to configure the OSGi environment as described with the following section.

h2. Configure it as you need

At this point, you may expect to see all your devices on the ZigBee Tester user interface, but it is more likely that nothing is going to work ;)
You must apply some configuration to ZB4OSGi. I'm not going to cover the meaning of the parameter, because you can find an [[Configuration parameters|exhaustive description on the wiki]]. 
For can edit the following files:
* it.cnr.isti.zigbee.driver.configuration.properties
* it.cnr.isti.zigbee.ha.configuration.properties
which are locate on these paths:
* *ZB4OSGi/trunk/zigbee.tester/configurations/services* if you are using a release version
* *../configurations/services* if you have built the suite on your own
Edit the file without stop ZB4OSGi, once you finish with the configuration we can simply stop and start again the _"OPS4J Pax ConfMan - Properties Loader"_ bundle in order to apply all the configurations:
 <pre>stop 1
 start 1</pre>
Here an example of ready-to-copy configurations. 

it.cnr.isti.zigbee.driver.configuration.properties
<pre>
it.cnr.isti.zigbee.driver.serial.portname=/dev/ttyUSB0 (change in accordance to your OS eg: under windows the value may be COM4, and type and port number under linux /dev/ttyUSBx or /dev/ttyACMx )
it.cnr.isti.zigbee.pan.channel=22
it.cnr.isti.zigbee.driver.serial.baudrate=115200
it.cnr.isti.zigbee.driver.mode=Coordinator
</pre>

it.cnr.isti.zigbee.ha.configuration.properties
<pre>
it.isti.cnr.zigbee.ha.driver.cluster.discovery.mode=HomeAutomationProfileStrict
it.cnr.isti.zigbee.ha.reporting.min=60
it.cnr.isti.zigbee.ha.reporting.max=0
it.cnr.isti.zigbee.ha.reporting.change=0
it.cnr.isti.zigbee.ha.reporting.overwrite=true
</pre>
In case something goes wrong, stop all the bundles and star them again:
 <pre>stop 0</pre>
and restart the script file.

troubleshooting:
under Linux, if you can't open device getting an exception with cause "Could not find port: /dev/ttyACM0", even if the property is set correctly, you may need to add in pax.args file under zb4osgi-trunk\zigbee.tester, under   <pre>--vmOptions</pre> the flag <pre>-Dgnu.io.rxtx.SerialPorts=/dev/ttyACM0</pre> (or /dev/ttyUSB0 or a list using ":" without quotes as separator /dev/ttyUSB0:/dev/ttyACM0)
In windows, please make sure that this flag is not used, or serial port will not be discovered.

Either another possible issue in Linux that raises an "Could not find port" it's related to the user read/write permits on /dev/ttyACM0 file (the serial port device, in this case, we are using ACM0)
For a One-Time edit just change the permits (remember that disconnecting the dongle or rebooting the system will revert the settings), with root privileges,just type

*chmod o+rw /dev/ttyACM0*

Instead, for a permanent system change, add the user that want to access the serial at dialout group.

*usermod -aG dialout <user-that-wants-access>*

h1. Controlling the ZigBee network

For further description on how to use the [[ZigBee Tester]] we refer to its documentation.

h1. Appendix: Debugging, Developing and Troubleshooting

You can refer to [[FAQ]] for common troubleshooting answer, while you can find a proper way for debugging issue in the [[Posting a bug]] pages. Finally the [[wiki#Developer-Documentation|Developer documentation]] describe how to write code that uses ZigBee 4 OSGi and also how to contribute to ZigBee 4 OSGi.