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

Creating Connections

It is expected that you have read and understood the samples section before reading this page.

All communications within libxbee are connection-oriented. A connection can be thought of as a queue that is dedicated to a specific type of connection and a specific remote endpoint. The purpose of a connection is so that the data will be collected for you, and so that it is easy to subsequently transmit data - you don't have to keep providing the addressing information.

If you think that you want to deal with connection-less data... you don't. In fact what you probably want is a catch all connection that will collect any connection-less packets for a given connection type. Unless your catch all connection is also a broadcast connection, it makes no sense to try transmitting data using it.

xbee_conNew()

The prototype for xbee_conNew() is shown below:

xbee_err xbee_conNew( struct xbee *xbee,
struct xbee_con **retCon,
const char *type,
struct xbee_conAddress *address);

The type and address parameters are the intersting ones that will be discussed here. Other information about xbee_conNew() can be found in its man page, or the online man page.

What Connection Types Are Available?

The connection types that are available depend from mode to mode. To identify what connection types a given mode supports, you can do one of a few things:

  1. Read the man page
  2. Run a program
  3. Read the source code

Running a Program

The following sample code will give you a list of the supported connection types for the chosen mode.

Download the source: get_conTypes.c

  1. /*
  2.   libxbee - a C/C++ library to aid the use of Digi's XBee wireless modules
  3.             running in API mode.
  4.  
  5.   Copyright (C) 2009 onwards  Attie Grande (attie@attie.co.uk)
  6.  
  7.   libxbee is free software: you can redistribute it and/or modify it
  8.   under the terms of the GNU Lesser General Public License as published by
  9.   the Free Software Foundation, either version 3 of the License, or
  10.   (at your option) any later version.
  11.  
  12.   libxbee is distributed in the hope that it will be useful,
  13.   but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15.   GNU Lesser General Public License for more details.
  16.  
  17.   You should have received a copy of the GNU Lesser General Public License
  18.   along with libxbee. If not, see <http://www.gnu.org/licenses/>.
  19. */
  20.  
  21. #include <stdio.h>
  22. #include <stdlib.h>
  23. #include <string.h>
  24.  
  25. #include <xbee.h>
  26.  
  27. int main(void) {
  28.   struct xbee *xbee;
  29.   char **conTypes;
  30.   xbee_err ret;
  31.   int i;
  32.  
  33.   if ((ret = xbee_setup(&xbee, "xbee1", "/dev/ttyUSB0", 57600)) != XBEE_ENONE) {
  34.     printf("ret: %d (%s)\n", ret, xbee_errorToStr(ret));
  35.     return ret;
  36.   }
  37.  
  38.   if ((ret = xbee_conGetTypes(xbee, &conTypes)) != XBEE_ENONE) {
  39.     printf("ret: %d (%s)\n", ret, xbee_errorToStr(ret));
  40.     return ret;
  41.   }
  42.  
  43.   for (i = 0; conTypes[i]; i++) {
  44.     printf("connection type %d - %s\n", i, conTypes[i]);
  45.   }
  46.  
  47.   free(conTypes);
  48.  
  49.   xbee_shutdown(xbee);
  50.  
  51.   return 0;
  52. }

Reading the Source Code

This is probably more information than the average user wants to know - Show/Hide.

How do I Populate the Address Struct?

Good question! It's fairly straight forward - the struct is shown below.

struct xbee_conAddress {
  unsigned char addr16_enabled;
  unsigned char addr16[2];
 
  unsigned char addr64_enabled;
  unsigned char addr64[8];
 
  unsigned char endpoints_enabled;
  unsigned char endpoint_local;
  unsigned char endpoint_remote;
 
  unsigned char profile_enabled;
  unsigned short profile_id;
 
  unsigned char cluster_enabled;
  unsigned short cluster_id;
};

As you have hopefully picked up from the samples, you must set the *_enabled flags to make libxbee pay attention to the various sections of the struct. For the addr16 and addr64 values, the Most Significant Byte goes into index zero.

So to connect to an XBee that has a 64-bit address of 0x0013A200 0x40081826, you would write the following:

struct xbee_conAddress address;
memset(&address, 0, sizeof(address));
address.addr64_enabled = 1;
address.addr64[0] = 0x00;
address.addr64[1] = 0x13;
address.addr64[2] = 0xA2;
address.addr64[3] = 0x00;
address.addr64[4] = 0x40;
address.addr64[5] = 0x08;
address.addr64[6] = 0x18;
address.addr64[7] = 0x26;

For some of the more complex modes (such as xbeeZB) you may have multiple sections of the address struct enabled. A call to xbee_conNew() will fail if you have provided invalid information.

Addresses are always left-aligned. For example, if you're using a WiFi module (and therefore want to enter a 32-bit IP address), you should use the first 4 bytes of addr64. The IP address 192.168.0.15 would be entered like so:

struct xbee_conAddress address;
memset(&address, 0, sizeof(address));
address.addr64_enabled = 1;
address.addr64[0] = 192;
address.addr64[1] = 168;
address.addr64[2] = 0;
address.addr64[3] = 15;