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.

Data

Now that you have grasped the basics of libxbee - you've successfully communicated with a remote module - you can start to make something more useful. This sample is designed to help you do this.

This sample will setup a connection that uses callbacks. When data comes in from the module (who's address is configured on lines 52-59), the sample will print the incomming data to the screen, and respond with the message Hello\r\n. This sample will also wait until an '@' is received before it quits. This is achieved by using the connection-specific data pointer.

If you just run this sample, it will appear to do nothing - you must send data from a remote module, this sample will then respond.

Download the source: data.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. void myCB(struct xbee *xbee, struct xbee_con *con, struct xbee_pkt **pkt, void **data) {
  28.   if ((*pkt)->dataLen > 0) {
  29.     if ((*pkt)->data[0] == '@') {
  30.       xbee_conCallbackSet(con, NULL, NULL);
  31.       printf("*** DISABLED CALLBACK... ***\n");
  32.     }
  33.     printf("rx: [%s]\n", (*pkt)->data);
  34.   }
  35.   printf("tx: %d\n", xbee_conTx(con, NULL, "Hello\r\n"));
  36. }
  37.  
  38. int main(void) {
  39.   void *d;
  40.   struct xbee *xbee;
  41.   struct xbee_con *con;
  42.   struct xbee_conAddress address;
  43.   xbee_err ret;
  44.  
  45.   if ((ret = xbee_setup(&xbee, "xbee1", "/dev/ttyUSB0", 57600)) != XBEE_ENONE) {
  46.     printf("ret: %d (%s)\n", ret, xbee_errorToStr(ret));
  47.     return ret;
  48.   }
  49.  
  50.   memset(&address, 0, sizeof(address));
  51.   address.addr64_enabled = 1;
  52.   address.addr64[0] = 0x00;
  53.   address.addr64[1] = 0x13;
  54.   address.addr64[2] = 0xA2;
  55.   address.addr64[3] = 0x00;
  56.   address.addr64[4] = 0x40;
  57.   address.addr64[5] = 0x08;
  58.   address.addr64[6] = 0x18;
  59.   address.addr64[7] = 0x26;
  60.   if ((ret = xbee_conNew(xbee, &con, "64-bit Data", &address)) != XBEE_ENONE) {
  61.     xbee_log(xbee, -1, "xbee_conNew() returned: %d (%s)", ret, xbee_errorToStr(ret));
  62.     return ret;
  63.   }
  64.  
  65.   if ((ret = xbee_conDataSet(con, xbee, NULL)) != XBEE_ENONE) {
  66.     xbee_log(xbee, -1, "xbee_conDataSet() returned: %d", ret);
  67.     return ret;
  68.   }
  69.  
  70.   if ((ret = xbee_conCallbackSet(con, myCB, NULL)) != XBEE_ENONE) {
  71.     xbee_log(xbee, -1, "xbee_conCallbackSet() returned: %d", ret);
  72.     return ret;
  73.   }
  74.  
  75.   for (;;) {
  76.     void *p;
  77.  
  78.     if ((ret = xbee_conCallbackGet(con, (xbee_t_conCallback*)&p)) != XBEE_ENONE) {
  79.       xbee_log(xbee, -1, "xbee_conCallbackGet() returned: %d", ret);
  80.       return ret;
  81.     }
  82.  
  83.     if (p == NULL) break;
  84.  
  85.     sleep(1);
  86.   }
  87.  
  88.   if ((ret = xbee_conEnd(con)) != XBEE_ENONE) {
  89.     xbee_log(xbee, -1, "xbee_conEnd() returned: %d", ret);
  90.     return ret;
  91.   }
  92.  
  93.   xbee_shutdown(xbee);
  94.  
  95.   return 0;
  96. }