- About this tutorial
- Before starting
- Obtain the code
- Executing the ZigBee 4 OSGi suite
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 trying to execute ZigBee 4 OSGi, you must check if all the following requirements are satisfied.
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
- EZ430-RF2480 (http://focus.ti.com/docs/toolsw/folders/print/ez430-rf2480.html)
- CC2531 (http://focus.ti.com/docs/toolsw/folders/print/cc2531emk.html)
- Any device compliant with the CC2480 Interface Specification
- Any device compliant with the CC2530 Interface Specification
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¶
- 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
- Move to ZB4OSGi-trunk\ and build the whole project using command
- Move to zb4osgi-trunk\zigbee.tester and create the OSGi environment using the command
mvn pax:runA new sub-directory, named 'runner', is created.
- 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).
- Backup your .m2\repository maven directory
- Empty your .m2\repository maven directory
- 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).
- Download all the sandboxes https://svn.aaloa.org/projects/zb4osgi/sandbox with the command
svn co https://svn.aaloa.org/projects/zb4osgi/sandbox sandbox
- 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
- 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 (220.127.116.11) [ 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.