Getting Started

I've had quite a few people getting in contact asking for support with the initial setup and configuration of libxbee. As a result, I felt that it would be worthwhile writing this guide. libxbee is very straight forward, once you understand the principals involved.

Contents

  1. Is there anything I should know before I dive in?
  2. How do I get the source code?
  3. Can I download compiled binaries?
  4. How do I get it running on my OS?
  5. Which modules should I use?
  6. How should my modules be configured?
  7. Creating connections
  8. Using connections
  9. Advanced connections
  10. Running some samples

Other Resources

It's Not Working!

This page documents some common mistakes that people make while trying to get libxbee running. Please ensure that you read through this page before asking for help.

If you have successfully built libxbee and compiled your program, but you can't seem to get anything to work, this page is for you! Below I have documented the most common issues that people are confronted with while trying to get libxbee working with an XBee module.

#1 - Permission Denied

If you're getting XBEE_EIO returned from xbee_setup(), or you're seeing open(): permissions denied, then you'll probably find that you don't have permission to open the tty that you've specified. On Ubuntu, you need to be a member of the "dialout" group (which you aren't a member of by default), other distributions may have other requirements.

More Detail

If you're trying to access /dev/ttyUSB0, then run the following command to see which group owns the device. stat -c %G /dev/ttyUSB0 Then you need to add yourself to that group: sudo gpasswd -a ${USER} $(stat -c %G /dev/ttyUSB0)

#2 - Baud Rate

The baud rate determines the time that each bit is maintained for. It is necessary to configure the baud rate of both communicating devices to be the same, so the first thing to check is that your XBee module is configured for the same baud rate that you are giving in the call to xbee_setup().

More Detail

A baud rate of 57,600 (which is what I commonly use with XBee modules) gives a bit-time of about 17.36µs. With no parity and when using 8-bit data (referred to as 8N1), a word is transferred using a 1x start bit, 8x bits of data and 1x stop bit (10x bits total), giving a word-time of 173.61µs.

UARTs begin clocking the data in on the start-bit. As there isn't a dedicated clock signal, it is important that the transmitter and receiver are configured to use similar baud rates. As a rule of thumb, an error of up to about ±4% can be tolerated, though obviously you want as close to 0% as possible.

#3 - Hardware Flow Control

By default, libxbee is configured to use hardware flow control. This means that the RTS (Ready to Send) and CTS (Clear to Send) signals must be connected between the XBee module and your device.

Some USB adapter boards don't connect the RTS or CTS pins, meaning that you can't use hardware flow control. If this is the case, you can disable hardware flow control by uncommenting the XBEE_NO_RTSCTS option in config.mk.

Though you can run without flow control, I would always recommend that you do if you can.

#4 - API Mode / Firmware

libxbee has been developed to operate with XBee modules that are running in API mode 1. Some modules series simply require you to configure the AP option to 1, while others require you to install a different firmware image.

For example, the Series 2 (ZigBee) modules, require a special API firmware image to be loaded. Once you have installed this, you should check that the AP option is set to 1.

If you want to use API mode 2 (which escapes the data), you can, though I'd advise against it (some modules don't always escape the data correctly). If you really want to operate in API mode 2, then you should uncomment the XBEE_API2 option in config.mk.

#5 - XBee Series / libxbee Mode

You must run libxbee in the correct mode for the XBee module that you're using. To find out more about the available modes, and which mode you should be using, please see the Which Modules Should I Use? page.

#6 - Addressing

Please check your addresses before asking for help. People often get confused with addresses - which way round they should be and how to populate the address struct.

If you just sit back, draw a diagram and think about it, addressing is very straight forward. Pretend that you're in a super-simple world. You have two XBee modules - #1 has address 1, #2 has address 2. You connect module #1 to libxbee, and you want to communicate with module #2. Therefore you enter the address of module #2 into your application, and you configure the DH and DL options of module #2 to the address of module #1.

#7 - libxbee Logging

libxbee can produce some very useful debug output. You'll need to ensure that the XBEE_DISABLE_LOGGING option isn't active (it isn't by default - check config.mk).

There are three ways to enable the log output. The methods listed below are in order of precedence, starting with the highest.

  1. Calling xbee_logLevelSet() (or libxbee::XBee::setLogLevel() if you're using the C++ interface)
    You can alter the log level at run-time by calling xbee_logLevelSet(). This is a per-libxbee-instance setting.
  2. XBEE_LOG_LEVEL (Environment Variable) - the most flexible method
    If you set the environment variable XBEE_LOG_LEVEL to an integer value before running your program, you can modify the initial log level. A value of zero will typically give no ouput (and is normally the default). As the value increases, the output becomes more verbose - a value of 100 will include all messages from within the library (user messages can be outside this range).
  3. XBEE_LOG_LEVEL (in config.mk)
    You can also set the initial log level at build-time. This will have the same effect as setting XBEE_LOG_LEVEL in the environment.

It's also possible to get libxbee to log more information such as the Tx and Rx frame paylods. Have a look at the functions outlined here.

Logging can also be controlled from the environment (before executing your application). The variable names are as below (see the manual for full details):

  • XBEE_LOG_LEVEL = n
  • XBEE_LOG_RX = 0 or 1
  • XBEE_LOG_TX = 0 or 1
  • XBEE_LOG_COLOR = 0 or 1