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

Running some samples

If you're new to libxbee, I recommend running and understanding some samples in the following order. These samples are designed for use with XBee Series 1 modules, and therefore the "xbee1" mode.

  1. Local AT - to make sure your setup works.
  2. Remote AT - to make sure you understand addressing, and that your network is operational.
  3. Data - To get something useful working.

Local AT

The Local AT sample is intended to help you get to grips with the fundamentals of libxbee - setup, making a connection, and exchanging data. It is also very useful to use as a test to ensure that your system is correctly configured, and that libxbee can communicate with your XBee module.

Download the source: at_local.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. /*
  22.   This sample has been designed to give you a very basic introduction to
  23.   libxbee. The sample will start libxbee, create a connection to the local
  24.   XBee module, and then request its Node Identifier before shutting down.
  25.   This sample does not use callback functions.
  26. */
  27.  
  28. #include <stdio.h>
  29. #include <stdlib.h>
  30. #include <string.h>
  31.  
  32. #include <xbee.h>
  33.  
  34. int main(void) {
  35.   void *d;
  36.   struct xbee *xbee;
  37.   struct xbee_con *con;
  38.   unsigned char txRet;
  39.   xbee_err ret;
  40.  
  41.   /* setup libxbee, using the USB to Serial adapter '/dev/ttyUSB0' at 57600 baud */
  42.   if ((ret = xbee_setup(&xbee, "xbee1", "/dev/ttyUSB0", 57600)) != XBEE_ENONE) {
  43.     printf("ret: %d (%s)\n", ret, xbee_errorToStr(ret));
  44.     return ret;
  45.   }
  46.  
  47.   /* create a new AT connection to the local XBee */
  48.   if ((ret = xbee_conNew(xbee, &con, "Local AT", NULL)) != XBEE_ENONE) {
  49.     xbee_log(xbee, -1, "xbee_conNew() returned: %d (%s)", ret, xbee_errorToStr(ret));
  50.     return ret;
  51.   }
  52.  
  53.   /* send the AT command 'NI' (request the Node Identifier)
  54.      when the response is recieved, the packet will be directed to the callback function */
  55.   ret = xbee_conTx(con, &txRet, "NI");
  56.   /* print out the return value
  57.      if this is non-zero, then check 'enum xbee_errors' in xbee.h for its meaning
  58.      alternatively look at the xbee_errorToStr() function */
  59.   printf("tx: %d\n", ret);
  60.   if (ret) {
  61.     /* if ret was non-zero, then some error occured
  62.        if ret == XBEE_ETX then it is possible that txRet is now -17 / XBEE_ETIMEOUT
  63.        alternatively, txRet will contain the status code returned by the XBee */
  64.     printf("txRet: %d\n", txRet);
  65.   } else {
  66.     struct xbee_pkt *pkt;
  67.     if ((ret = xbee_conRx(con, &pkt, NULL)) != XBEE_ENONE) {
  68.       printf("Error after calling xbee_conRx(): %s\n", xbee_errorToStr(ret));
  69.     } else {
  70.       int i;
  71.       printf("Response is %d bytes long:\n", pkt->dataLen);
  72.       for (i = 0; i < pkt->dataLen; i++) {
  73.         unsigned char c = (((pkt->data[i] >= ' ') && (pkt->data[i] <= '~'))?pkt->data[i]:'.');
  74.         printf("%3d: 0x%02X - %c\n", i, pkt->data[i], c);
  75.       }
  76.     }
  77.   }
  78.  
  79.   /* shutdown the connection */
  80.   if ((ret = xbee_conEnd(con)) != XBEE_ENONE) {
  81.     xbee_log(xbee, -1, "xbee_conEnd() returned: %d", ret);
  82.     return ret;
  83.   }
  84.  
  85.   /* shutdown libxbee */
  86.   xbee_shutdown(xbee);
  87.  
  88.   return 0;
  89. }