Interfacing XBee with OpenHAB

Purpose of this article is to provide you a kick start for interfacing XBee modules in to openHAB.

Things you need;

1. Preferably Ubuntu machine for openHAB development

2. WINE setup on Ubuntu machine or Windows machine for running X-CTU (XBee configuration utility)
3. XBee Series 2 modules (Series 1 would also fine. But configurations would slightly differ)

4. XBee Explore USB - 1(and XBee 3.3 v power source) or 2 (Both can be powered up from USB)

5. 1 hour of good time :)

Setting up development environment

For setting up Eclipse IDE for OpenHAB, you could follow the instructions at OpenHAB Eclipse IDE setup. Basically it can be installed using 3 methods; install the required plug-ins in Eclipse, install both Eclipse + required plug-ins from Yoxos installer, download the pre-packaged Eclipse + required plug-ins. I used the 3rd method on 64 bit Ubuntu installation. (Note: All 3 methods failed on 32 bit Windows 7)

Tips in case the build fails:

1. Eclipse > Window > Preferences > Java > Compiler > Compiler compliance level to 1.7.

2. Eclipse > Window > Preferences > Installed JREs > Execution Environments > Set 1.7 as compatible environment for each execution environment.

3. Eclipse > Window > Preferences > Plug-in Development > Target Platform > Select openHAB and Reload it.

4. Make sure you have generated the required code by executing org.openhab.model.codegen. 

5. Do a maven clean install

6. Clean the complete workspace

Binding for XBee modules

Original OpenHAB source tree does not include the bindings required for XBee. So we shall pull it from another branch (diaoulael-xbee).  A checked out modified version can be found at openhab_ext

1. Just download the source code, then copy the content of /bundles/binding/org.openhab.binding.xbee in to previously cloned original source tree's /bundles/binding/.

2. Using a text editor, add following XML tag to /bundles/binding/pom.xml, inside the <modules> element.

<module>org.openhab.binding.xbee</module> 

3. Import the new project into Eclipse workspace (openHAB)

4. In Eclipse Run/Debug configurations, Eclipse Application > openHAB runtime > Plug-ins, set org.openhab.binding.xbee Auto start 'true' and start level 'default'

Configurations of XBee modules

One going to be interfaced with the openHAB server machine has to be configured as a coordinator and other as an End device.

1. Download and install X-CTU Next gen Xbee configuration too. I used a Windows machine for XBee configurations.

2. Mount a XBee module on XBee Exlorer USB and add it in X-CTU.

3. Upload the ZNet Coordinator API latest firmware 

4. Configure following setting

     a) Set AP mode to 2

     b) Set serial settings 9600 bps, No flow control, No parity

5. Mount the next XBee module

6. Upload ZNet router/End device API latest firmware

     a) Set AP mode to 2

     b) Set serial settings 9600 bps, No flow control, No parity

     c) Disable all IO lines except DIO-0 to Digital input

   d) Set IR (sampling interval) to 1388 (5 seconds). So it will sample the DIO-0 (pin number 20) and transmit IOSample packet each 5 seconds.

Letting openHAB know about XBee and how to bind it

1. Connect XBee module which was configured as the coordinator to openHAB server machine (running on Ubuntu).

2. Connect/Disconnect to find out the USB device interface assigned to Xbee Explorer USB. For my case it was /tty/USB0

3. Make sure your user account is provided with dialing out permissions 

sudo adduser $USER dialout 

and logout/login

4. In Eclipse openHAB workspace, distribution/openhabhome/configurations/openhab_default.cfg, add following.

################################ XBee Binding #########################################
# Serial port of XBee interface
# Valid values are e.g. COM1 for Windows and /dev/ttyS0 or /dev/ttyUSB0 for Linux
xbee:serialPort=/dev/ttyUSB0

#Baudrate (optional)
xbee:baudRate=9600

5. In Eclipse openHAB workspace, distribution/openhabhome/configurations/items/demo.items, add following. Here I am going to introduce a contact (binary two state "Open" and "Closed") item named Window_FF_Bed2 under "FF_Bed" location and "Windows" groups. Item would appear in web interface under First floor > Bed Room > Bed Room2.

Contact Window_FF_Bed2            "Bedroom2 [MAP(en.map):%s]"         (FF_Bed, Windows)     { xbee="<znetrxiosampleresponse@0013A20040A2206C#D0:" }

Replace the highlighted 64 bit address with your XBee end device's address which can be queried from API/AT commands or printed in the backside of the module.

Running things together

1. Mount the XBee coordinator on XBee Explorer USB and interface it to the openHAB server machine

2. Mount the XBee end device on another XBee Explorer USB and power it up(or simply provide it 3.3v). No need to provide any signaling interface as XBee modules is programmed to sample DIO 0 (pin 20) and transmit the status each 5 seconds by itself.

In Eclipse > Run > Run configurations > openHAB runtime > Run.

2. Once the openHAB runtime is fully started, you should be able to browse 

http://192.168.0.3:8080/openhab.app?sitemap=demo

Replace highlighted IP with your local machine's IP.

3. Navigate to First floor > Bed room, Observe the Bedroom2 status. Initially this is set to "open"

4. Now short the pin 10 (GND) and pin 20 (DIO 0) to emulate a window being closed. Observe the status of Bedroom2 is changed from "open" to "closed". As you make the DIO pin voltage zero and open, changes are reflected in UI (remember we set the sampling to happen each 5 seconds). Hurray!