Skip to content
Christopher Piggott edited this page Mar 14, 2015 · 5 revisions

Welcome to the xbee-api-java wiki!

This library is a simple java parser for XBee API messages. It has few dependencies, and doesn't deal with the origin of the byte stream, allowing you to use anything you want - JSSC, RXTX, or 'cat /dev/ttyUSB0'. You feed bytes in either one or more at a time. Or, for performance, you can feed in entire byte buffers at a time. Once a complete message becomes available you'll receive it as a callback through one or more listeners that you register.

The basic usage is like this:

XbeeMessageParser parser = new XbeeMessageParser();

XbeeMessageListener<XbeeExplicitRxMessage> messageListener = new XbeeMessageListener<>() {
    @Override
    public void onXbeeMessage(Object sender, XbeeExplicitRxMessagemessage) {
        System.out.println("Got a message with frame type " + message.getRawFrameType();
    }
}

parser.addListener( XbeeMessageType.EXPLICIT_RX, messageListener );

while( byte b = readFromYourSerialPort ) {
    parser.byteIn( b );  /* can also use bytesIn */
};

You can add listeners for specific message types as well, but there aren't too many yet. I am still working on the interface that lets you specify these messages in a way that will make the library user-extensible (so you will be able to add custom frame types in the future, but not now).

Limitations, Philosophies, and other notes

  • Set API mode to 2, this is not optional at this time. I only plan to support [API mode 2] (http://www.digi.com/support/kbase/kbaseresultdetl?id=2199) which uses a dedicated message start flag and escapes. I'm running this code on small hardware (like beaglebones) whose serial ports occasionally choke or overfow. I'm a big believer in using dedicated flags with escaping to delineate message boundaries - not just byte counting and a relatively weak checksum algorithm. So make sure your radio is in AP=2 mode, or else any message that has a magical control character in it is not going to parse.
  • Set AO mode to 3 if you want to see explicit RX messages
  • I plan to use the [semver] (http://semver.org/) versioning scheme
    • MAJOR revisions MAY break the API (but might just enhance it)
    • MINOR revisions may ADD to the API but won't break it
    • PATCH revisions will be reserved for bug fixes only

Help me!

The Xbee radio has a lot of different messages. I'm going to try to implement as many of the core ones as I can, but I probably will only implement specific AT commands as I need them. I would like to have as complete a set as possible. If you want to contribute, please do - fork this project, try to follow my patterns, then submit a pull request. If you have any questions do not hesitate to ask.