XBee API Library for Processing

  • NOTE: This library is no longer supported. In my book I’ve focused on using the more complete XBee-API libraries for Java created by Andrew Rapp. They cover various XBee radios, providing a full suite of API interactions. Code examples that use these libraries are available on the Building Wireless Sensor Networks page. You might also want to check the more newly released official XBee Java Library from Digi International, the makers of XBee.

Dan Shiffman and I developed a Processing library for Digi’s XBee radios. Tom Igoe also contributed code. The library facilitates receiving multiple sample I/O packets in API mode (ATAP1) from both the 802.15.4 and Series 2 XBee radios, and returns an object that contains the analog values, digital values, sender’s address and RSSI values. We started with I/O frames because the only way to receive this information is via API mode. The ability to send remote AT commands is now included. The library has been tested on Mac OS X and Windows platforms.


(posted November 2008)


XBeeReader class

XBeeReader constructor takes the parent PApplet “this” and a reference to a made serial port

start() – takes in the string of your setup commands and returns a string of responses. The first command in the string must begin with AT. Any commands that follow must be separated by commas and do not use AT. There is no comma after the last command.

getXbeeReading() – returns the XBeeDataFrame object

XBeeDataFrame class

Contains the information delivered in an XBee data frame. IN THIS INITIAL EXAMPLE IT IS ONLY I/O DATA. The available methods are:

getAddress16() – returns the 16-bit transmitter address as an integer
getAddress64() – returns the 64-bit transmitter address as an long
getRSSI() – returns the RSSI reading in dBm as an integer (XBee Series 1 only)
getTotalSamples() – returns the total number of samples contained in the data frame
getDigital() – returns an array of integers that represent the current state of each digital channel with -1 indicating that the channel is not configured for digital. Use this when there is only one sample per frame.
getDigital(int n) – returns the nth sample of digital data as an array of integers with -1 indicating that the channel is not configured for digital.

getAnalog() – returns an array of integers that represents the current state of each analog channel with -1 indicating that the channel is not configured for analog. Use this when there is only one sample per frame.
getAnalog(int n) – returns the nth sample of analog data as an array of integers with -1 indicating that the channel is not configured for analog.

XBeeEvent function

This function is similar to SerialEvent. The XBeeEvent is called for you when there is data available from your XBee radio.

35 Comments on “XBee API Library for Processing

  1. getRSSI() is only available for series 1 radios, why is that? Is there anything preventing the series 2 models from responding?



    • I have the same problem Jonathan, I’ve read a lot on Internet but I have still the same problem…Have you solved it?

  2. I’m doing a project. I have 2 Xbee communicating wirelessly. In one, I have a sensor and also I want to measure the voltage of the battery.
    The other is connected via usb to pc.
    As I can, through processing, see the value of the two sensors? (Temperature + battery voltage)
    I can not do it!
    Thanks in advance!!!

    • Anton, I have been having the exact same trouble…I have an XBee S1 connected to an Arduino Lillypad and an XBee S1 shield on an Arduino Uno. I would like to simply view the Serial data stream for temperature data from the Lillypad on the Serial output monitor for the Uno. Is this a problem you have resolved?

  3. When I try this I get The package “xbee” does not exist. You must be missing a library.

    I have tried putting the xbee.jar file in a directory call ed libraries in the sketchbook folder but that does not fix it. Thanks.

  4. Hi Rob;
    I use the ioSample.getSupplyVoltage(); to get the supply voltage of my Xbee sensors, but, unfortunately, it returns:
    I don’t know how I have to interpret this value. When I review the frame using X-CTU, the supply voltage it is: 0x097C = 2428 (dec)…
    I am confused!

    • Hello Anton,
      This value is the equivalent from the Analog / Digital Conversor. You will have values from 0 to 1023 which correspond to 0-5V or to 0-3.3V, depending the Arduino board you are using. To transform the value whtat you will have to do is: supplyVoltage = supplyVoltage * 5 / 1024 or supplyVoltage = supplyVoltage * 3.3 / 1024 . It depends on, how I have said before, in the Arduino board model you were using.

      • This does not make much sense to me. I’ve tried your equation and it does seem to work when power is supplied by arduino board. But when power is from a battery, result is wrong.
        I am not sure what the getSupplyVoltage function is outputting exactly but it would have been much simpler to report the supply voltage contained in the raw xbee io sample.
        Has anyone had success using this function when xbee is on battery?

  5. Congrats for your API… The book too seems to be very usefull, I´m thinking of buying it… Meanwhile… I have a Zigbee network that uses AT Mode… Your API supports it? I´m trying to read the data in the serial port but when I have several routers sending information they get all mixed up in the serial port…

  6. Referring to Matthew’s question on Nov 29th, I have the same problem. I’ve tried with XBee library versions 1.4 and 1.5, no difference. Is the Simple_Sensor_Network processing code supposed to work, am I just doing something wrong…? It keeps complaining “No library found for com.rapplogic.xbee.api”.


  7. Is there any option to get the Rssi for series 2 radios? getRSSI() is only available for series 1 radios, why is that?
    Thanks in advance

  8. Hello!

    I have a problem triggering digital output (like DO0) on the remote ZigBee.

    Case 1:
    I know I can trigger it like this:
    – setting digital input on the base ZigBee
    – setting digital output on the remote ZigBee (DO LOW)
    – and if configured right the input state on the base ZigBee is transferred to the digital output on remote ZigBee

    I managed to do that, but I would like to trigger it via data packets.

    Case 2:
    So I tried with setting API packets that set the digital output on the remote ZigBee. I managed to change the digital output on remote ZigBee with commands ATD0=4 (DO LOW) ATD0=5 (DO HIGH).

    DO LOW API command:
    7E 00 10 17 05 00 13 A2 00 40 08 C9 80 00 02 02 44 30 04 21

    DO HIGH API command:
    7E 00 10 17 05 00 13 A2 00 40 08 C9 80 00 02 02 44 30 05 20

    But the problem I have is that sometime the communication between the base and remote might be lost. And if the digital output on the remote ZigBee is set to 3,3V (DO HIGH) and the communication is lost, the digital output would stay at the 3,3V. I want it to “reset” to 0V. In “case 1” when I tried to trigger the digital output with digital input, you can set the reset timer for that digital output (command ATT0) and it did the work (the digital input reset to value 0V), but you can’t use that in the case 2.

    Does anybody know what is the API format of the packet to simulate case 1 – I/O line passing (case 1 data packets)?
    Do you have any other ideas how to “reset” the digital output to 0V.

  9. Hi, I need a communication among telsob motes and XBee. How to do this. Is there any API is developed for this. Help in this regards is highly appreciated.

  10. having fun using your library although ran into one issue… could be super easy fix that i’m just missing (i’m new to pcomp). reading analog values off the d0, d1, d2 pins happens about once every second. is there a way to increase the rate so that it’s literally streaming the incoming analog values? i started by hacking up the simple sensor network code (which has a small delay in the code) but figured this issue may be a delay on the library side. any help would be greatly appreciated. thanks.

  11. Having an intermittent (frequent) problem with XBEE (Freescale – Series1) communicating with Xstick1. Sending 144 byte packets -> frequent timeout error messages. Any suggestions?

  12. “getRSSI() – returns the RSSI reading in dBm as an integer (XBee Series 1 only).”

    Does this integer value represent the decimal value of the signal strength or is it hexadecimal ?

  13. On xbee.getResponse().getApiId() where do I get a list of codes and what they mean? right now I am getting 91 hex and don’t know what it is.

    Also for xbee.getResponse().isError()) where do I get a list of error codes.

    These are for series 2 API mode.

    • I found a list:

      XBEE Supported Frames:
      Transmit Functions
      – 0x00 Tx(Transmit)Request:64-bit address (Only Serie 1)
      – 0x01 Tx(Transmit)Request:16-bit address (Only Serie 1)
      – 0x08 AT Command
      – 0x09 AT Command-Queue Parameter Value
      – 0x10 ZigBee Transmit Request (Only Serie 2)
      – 0x11 Explicit Addressing ZigBee Command Frame (Only Serie 2)
      – 0x17 Remote AT Command Request
      – 0x21 Create Source Route (Only Serie 2)

      – 0x80 Rx(Receive) Packet : 64-bit Address (Only Serie 1)
      – 0x81 Rx(Receive) Packet : 16-bit Address (Only Serie 1)
      – 0x82 Rx(Receive) Sample Packet : 64-bit Address (Only Serie 1)
      – 0x83 Rx(Receive) Sample Packet : 16-bit Address (Only Serie 1)
      – 0x88 AT Command Response
      – 0x89 Tx(Transmit) Status (Only Serie 1)
      – 0x8A Modem Status
      – 0x8B ZigBee Transmit Status (Only Serie 2)
      – 0x90 ZigBee Receive Packet (Only Serie 2)
      – 0x91 ZigBee Explicit Rx Indicator (Only Serie 2)
      – 0x92 ZigBee IO Data Sample Rx Indicator (Only Serie 2)
      – 0x94 XBee® Sensor Read Indicator (Only Serie 2)
      – 0x95 Node Identification Indicator (Only Serie 2)
      – 0x97 Remote Command Response
      – 0xA1 Route Record Indicator (Only Serie 2)
      – 0xA3 Many-to-One Route Request Indicator (Only Serie 2)

      But I don’t know why I am getting a 91 Explicit Rx Indicator since I set it up as the book says.

      • I found the problem, something weird about coordinator xbee, switched that out and it works.

        Would still like a detailed explanation of the various api codes.

  14. Hi, I am currently working on developing an intelligent car park sysem for my final year project using Wireless Sensor Networks (WSN).

    On one end I have the Arduino+XBee Shield+XBee powered by a 9V adapter. 6 ldr sensors are connected to Arduino, and sensor data will be sent wirelessly to a computer using an XBee connected via USB on the computer.

    What I would like to do now is to have the data displayed on the X-CTU on the receiver end of the XBee (the one connected to the computer) to be sent to the Microsoft SQL database. However, I have searched all over the internet and could not find any relevant answers.

    Thank you in advance for your replies!

  15. hi.
    has anyone had trouble with xbee api library for processing. I have downloaded code as per “building wireless networks book” but when I try to run it it breaks at “xbee xbee = new xbee()” with an error code that says “NoClassDefFoundError:gnu/io/serialportevent listener”
    I have tried loading different versions of processing and java.i am running windows 7 64 bit. another blog/forum somewhere said that java no longer using rxtx and now using jssc is the problem. does anybody know where to go for help with this or know of an equivalent gui developer program. any help would be muchly appreciated.

Leave a Reply

Your email address will not be published. Required fields are marked *