Roomware XBee mediator whitepapers

Posted on April 24, 2010



About this document

In this document you will find the basis of the Roomware Socket Server XBee clients.

What can you do with it?
You can build your own applications using the API’s as provided and use as many XBee devices as you like to create a cloud of sensors.

What is it written in?
Currently the following languages are supported:

  • C# .NET – The Roomware Socket Server (a Java Server will follow)
  • Java – The Roomware Socket Server clients
  • Java – Several libraries and API’s to build your own stuff
  • Flash – A Roomware Socket Server client and an XBee Mediator Client

What is covered in this whitepaper?

  • Setting up the Roomware Socket Server
  • Finding your IP-address (for the Server)
  • Configuration files for the Active Client (sending the data) and the Remote Client (using that data)
  • Code examples in Java to create your own applocation using Java.
  • An url to the ZIP file containing all the stuff you need (including the Source Code)

What is the status of the project?
At this moment we are in alpha state. The XBee Mediator software was written in the period between April 16 and April 23 for the Music and Bits Music Hack Day.

What is the XBee?

The XBee is a hardware solution using the ZigBee protocol. There are 4 digital ports and 6 analog. Each port can be used for input and output. It broadcast the readings from the analog and digital ports and can receive data to output through the digital and analog output ports.

What is the Roomware XBee Mediator?

The Roomware XBee mediator creates a virtual representation of each XBee device that is wirelessly connected to a XBee hub.

The basic setup
You have a remote client, the Roomware Server, an active client and several XBee devices.

The remote client
The Remote Client can run on any computer connected to the web and able to connect to the Roomware Socket Server.

The Active Client
The Active Client is the one reading the actual XBee devices and sending the data to the Roomware Socker Server. It is a computer with a XBee device connected to the USB port and software running to read the output of the USB port.

The Roomware API, the XBee Mediator Proxies and virtual devices
The Roomware API offers you a XBeeMediatorProxy class. This class allows you to connect to the Roomware Server and to the XBee Mediator located on the Active Client.
For each remote XBee device you instantiate a XBee Proxy Object which gives you the output of the remote XBee devices.
Bridging the gap: using Sockets
All communication is done using Sockets. Sockets are the most simple form of communication over a TCP/IP network and can also be used on a local machine without having to install or use a web-server.

Persistent connection
Both the Active Client as the Remote Client use a persistent connection (“always open“) to allow for speedy communication and avoid time loss by re-connecting any time new events occur.

With the XBee there are 10 ports available. These ports are AD0 to AD5 (analog) and RX, RTS, CTS and D08 (digital). We configured them this way:

[Analog in]
– AD0
– AD1

– AD5

[Digital in]
– RX / DIN

[Digital out]
– D08

Building applications with the XBee Mediator

Finding the source code

Downloading the source
The source is hosted on Google Code: here.

Installing the proper libraries
The XBee Proxy and XBee Roomware Mediator rely on the following JAR files to compile:

  • Log4j.jar – to log what is going on in the xbee-api
  • RXTXcomm.jar – to do the communication with the serial port
  • xbee-api-0.5.5.jar – written by Rapplogic and found here – which contains all the stuff to communicate with the XBee devices
  • RoomwareMediator.jar – which contains everything you need to build your own stuff.

These can be found in the ”xBeeMediator/lib“ folder.

Source code
The code for both the client and the server is here:
”XbeeMediator/src/application/“. The Main-app is the one started. The app runs the Remote and Active client.

The data can be found in ”xBeeMediator/data”

Setting up the Roomware Socket Server

The Roomware Socket Server is an C# .NET application running as an Executable. It runs on port 8000 and is available from the outside via the IP number of the machine it is running on.

Downloading the client
The client is part of the Roomware Development Package you can download from here.

Unzip the package
Unzip it and you will find it in the folder ”xBeeMediator/roomwareserver“.

Windows client only (for now)
We currently only have a Windows client.

Running the server
Double-click the ”roomwareServer.exe“ and it is running.

Defining which IP your machine has
Open the dos-box via ”programs – accessories – Command Prompt“
Type ”ipconfig“. It should give you something like this:


The IP Address is the one via which your Roomware Server will be available. In this case it is

Setting up the Active XBee Client

The active XBee client is a pre-compiled Java app with a simple window showing the streaming data in the window header.
It requires a configuration file stored in the ”data“ folder located in the same directory as the Java app.

The configuration file

The configuration file located in the ”data“ folder contains this text:

[Roomware connection]
[XBee listener]
[XBee publisher]

The Active XBee client reads this file and configures the Mediator between the XBee devices and the Roomware Socket Server according to these settings.

Setting up the Remote Client

Basic setup of the Mediator / Client Proxy

When you setup an XBee proxy, you gain direct access to any of the XBee devices connecting to the Active Client.

Each XBee proxy offers direct connections to the XBee device, using the same naming convention as used on the XBee break out board.
See them described above in this page.

Event based
The Roomware server and the XBee proxy work with events. So every time data is received on the Active Client and sent to the Remote Client an event is triggered

Instantiating the Proxy

Let’s assume:

  • You have 3 XBee devices numbered 101, 102 and 103.
  • Your Roomware Server is located at IP address and port 8000.
To instantiate the client (Java), you use the following:
import roomware.mediator.xbee.XBeeMediatorProxy
XBeeMediatorProxy mediatorProxy;
// Set the file location
String fileLocation="data/mediatorXBeeSettings";

mediatorProxy=new XBeeMediatorProxy();
// Use a file to set each part
if(mediatorProxy.getMediatorGlobals( fileLocation))
   // The mediator connects. Open the Roomware Connection

The configuration file

The configuration file located in the ”data“ folder contains this text:

[Roomware connection]
[XBee listener]
[XBee publisher]

What does it mean?
The roomware connection part contains all parameters to connect to your Roomware Socket Server. You need:

  • roomwareServer: The IP-number and port number of your Roomware Server (the exmple given here is a local address)
  • sandboxName: The sandbox in which your applications runs. (You can run more than 1000 different application clusters on the server)
  • listento: The events you want to have your application listen to

The XBee listener part tells the Mediator which specific events should be handled by which specific XBee. Currently (April 2010) this is not implemented yet.

The XBee publisher part tells the Mediator for each individual XBee device, which event-names to use when an event happens on that (virtual) XBee device. In this example we use ”event10“, ”event2“ and ”event3“. But you can use any name you like.
Note the correspondence between the XBee publisher definitions and the Roomare Connection ”listento“ defintion. The overlap is no coincidence.

IMPORTANT: Referring to XBee devices
As said before, each XBee has it’s own number. We used a range from 100 to 103. As the ID is an hexedecimal number, the XBee returns ”0101” instead of “101“
This makes sense if you understand that an ID from the XBee can also contain letters from A to F. Like this: ”0FA1“.

Naturally you could do a Hexedecimal to Decimal conversion and have the ID of an XBee be represented as a number. We choose not to.

Instantiating a XBee Proxy Object

Once you have set up the connection to the same Roomware Server and the same Sandbox the Active Client is broadcasting on, you can create the XBee Proxy Objects.

// Create the XBee proxy objects
XBeeObject xb0101=XBeeObject.getObject("0101");
XBeeObject xb0102=XBeeObject.getObject("0102");
XBeeObject xb0103=XBeeObject.getObject("0103");

You do not create an XBee Proxy object directly. The reason to do it like this is that your XBee Proxy Object might be already instantiated by something or somewhere else in your application. As the XBee Proxy Object operates as a bridge with two dependent clients (you and the XBee Roomware Server Mediator) leave it up to the Proxy Object to create one for you

Instantiating an Event Listener

The basic setup of using a XBee Proxy Object

To instantiate an Event Listener, you simply address the object and add an eventlistener to it.

// Add eventlisteners
xb0101.addEventListener(MediatorEvent.OBJECT_UPDATE, “myProxyObject1Handler”,this);
xb0102.addEventListener(MediatorEvent.OBJECT_UPDATE, “myProxyObject2Handler”,this);

Java and addEventListeners

This approach to Event Listeners is taken from Flash / Actionscript. What happens with the Event listener is this: on the object itself, a reference is created to the listener (”this“ in this example) and to the function you want to have called. When the event takes place, introspection is used to resolve the Method and to invoke that method on the listener.

Active Client can be Remote Client can be Located anywhere
Active Client can be a Remote Client located anywhere in the world.

Handling the event and the data

The event to handle can be defined by you.
In this case we simply read the values from xb101.

public void myProxy1Handler(IEvent event)
  // Access the data directly
  String ID=xb0101.ID;
  int value0=xb0101.AD0;
  int value1=xb0101.AD1;
  int value2=xb0101.AD2;
  int value3=xb0101.AD3;
  int value4=xb0101.AD4;
  int value5=xb0101.AD5;

Closing notes
In this introduction we showed you how you can set up a client for the XBee using the Roomware Socket Server and the library as we provided.