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.

Remote AT

Now that you have confirmed communication between libxbee and your XBee module, you should confirm communication with a remote XBee. To help with this step, I have developed the Remote AT sample. This sample is intended to help you understand how to populate the xbee_conAddress struct, and to ensure correct network configuration. This sample also graduates to using callback functions with the connection.

Download the source: at_remote.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 is very similar to the simple AT sample, instead of
  23.    communicating with the local XBee, an attempt is made to communicate
  24.    with a remote XBee. You should change the address below to match your
  25.    remote XBee.
  26. */
  27.  
  28. #include <stdio.h>
  29. #include <stdlib.h>
  30. #include <string.h>
  31.  
  32. #include <xbee.h>
  33.  
  34. void myCB(struct xbee *xbee, struct xbee_con *con, struct xbee_pkt **pkt, void **data) {
  35.   if ((*pkt)->dataLen == 0) {
  36.     printf("too short...\n");
  37.     return;
  38.   }
  39.   printf("rx: [%s]\n", (*pkt)->data);
  40. }
  41.  
  42. int main(void) {
  43.   void *d;
  44.   struct xbee *xbee;
  45.   struct xbee_con *con;
  46.   struct xbee_conAddress address;
  47.   unsigned char txRet;
  48.   xbee_err ret;
  49.  
  50.   if ((ret = xbee_setup(&xbee, "xbee1", "/dev/ttyUSB0", 57600)) != XBEE_ENONE) {
  51.     printf("ret: %d (%s)\n", ret, xbee_errorToStr(ret));
  52.     return ret;
  53.   }
  54.  
  55.   /* this is the 64-bit address of the remote XBee module
  56.      it should be entered with the MSB first, so the address below is
  57.      SH = 0x0013A200    SL = 0x40081826 */
  58.   memset(&address, 0, sizeof(address));
  59.   address.addr64_enabled = 1;
  60.   address.addr64[0] = 0x00;
  61.   address.addr64[1] = 0x13;
  62.   address.addr64[2] = 0xA2;
  63.   address.addr64[3] = 0x00;
  64.   address.addr64[4] = 0x40;
  65.   address.addr64[5] = 0x08;
  66.   address.addr64[6] = 0x18;
  67.   address.addr64[7] = 0x26;
  68.   if ((ret = xbee_conNew(xbee, &con, "Remote AT", &address)) != XBEE_ENONE) {
  69.     xbee_log(xbee, -1, "xbee_conNew() returned: %d (%s)", ret, xbee_errorToStr(ret));
  70.     return ret;
  71.   }
  72.  
  73.   if ((ret = xbee_conCallbackSet(con, myCB, NULL)) != XBEE_ENONE) {
  74.     xbee_log(xbee, -1, "xbee_conCallbackSet() returned: %d", ret);
  75.     return ret;
  76.   }
  77.  
  78.   ret = xbee_conTx(con, &txRet, "NI");
  79.   printf("tx: %d\n", ret);
  80.   if (ret) {
  81.     printf("txRet: %d\n", txRet);
  82.   } else {
  83.     sleep(1);
  84.   }
  85.  
  86.   if ((ret = xbee_conEnd(con)) != XBEE_ENONE) {
  87.     xbee_log(xbee, -1, "xbee_conEnd() returned: %d", ret);
  88.     return ret;
  89.   }
  90.  
  91.   xbee_shutdown(xbee);
  92.  
  93.   return 0;
  94. }