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

How do I get it running on my OS?

Linux Windows FreeBSD OS X

libxbee has not been developed for use on bare metal systems. Arduino and PIC are bare metal systems.

libxbee supports the most popular operating systems - Linux, Windows, FreeBSD and now OS X too! My operating system of choice is Linux, meaning that it will likely be the most stable and best supported. At the opposite end of the spectrum is OS X, which without the generosity of the community, I have no access to.

Setting up on Windows Windows

libxbee's network sharing is not currently supported under Windows - this includes the 'net' mode and the xbee_netStart() and xbee_netStop() functions.

System Setup

To build libxbee, you will need to have the following software installed on your computer:

To complete the installation of the GNU tools, you'll have to add C:\Program Files (x86)\GnuWin32\bin (or the equivelant for your system) to your system's PATH environment variable.

Getting the source code

You will currently need to use the 'win32' branch when working with Windows.

You'll need to get a copy of the source code. If you aren't comfortable with Git, or would like the easier path, then you can download a ZIP archive of the win32 branch from here. If you'd like to use Git, or want to share the source repository, then please see this page for more information on how to get the source code.

Now that you have the source code, you can proceed with compiling libxbee. You'll need to extract or checkout the source to a directory, that we'll refer to as the 'working directory'. The build happens in a few steps, detailed below.

Common Problems

  • "The program can't start because mspdb100.dll is missing from your computer" - You need to run vcvars32.bat (see above), or a component of MSVS or the Windows SDK is missing.
  • I can't open the serial port - Windows is stupid... If you're using a COM port that is numbered above 8, you'll need to use the following notation: \\\\.\\COM10

Compiling libxbee

I have written some detailed notes that outline how to build libxbee on the following platforms:

Building on Windows 8.1 (32-bit)

System Setup

In addition to the software mentioned above, you'll require the following (these are listed as a known working reference point):

Compiling libxbee

  1. Install the required software, and get the libxbee3 source code, as discussed above.
  2. Open a Command Prompt (cmd.exe), and cd into the working directory.
  3. Run make configure. If this completes successfully, then you should see that a file (config.mk) has appeared in the working directory.
  4. Review config.mk. You will need to setup the following variables (shown with examples):
    • VCPATH - This should point to the Visual Studio installation directory - %VS_INSTALL_DIR%\VC
      For example: C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC (for Visual Studio 2015rc)
    • SDKPATH - This should point to the Microsoft SDK installation directory - %SDK_INSTALL_DIR%\Windows\v7.1
      For example: C:\Program Files (x86)\Microsoft SDKs\Windows\v7.1A
    • CFLAGS - You'll need to add an include path so that the build will complete successfully... Add the following line:
      CFLAGS+="/IC:\Program Files (x86)\Windows Kits\10\Include\10.0.10056.0\ucrt"
    • CLINKS - You'll also need to add a library path... as below:
      CLINKS+="/LIBPATH:C:\Program Files (x86)\Windows Kits\10\Lib\10.0.10056.0\ucrt\x86"
    • Because Microsoft have decided to start including struct timespec, you'll need to uncomment the following OPTIONS line:
      OPTIONS+= SYS_HAS_TIMESPEC
    Other points to mention are:
    • If you want to debug libxbee, you'll need to uncomment both DEBUG and LDBUG.
    • The MODELIST variable will determine which modes are built into the library. If you leave it commented, then the default list containing all of the modes will be used (excluding net as previously mentioned).
    • Additional debugging information can be accessed by using the logging feature - see here for more info.
    • If you are not using hardware flow control (some interfaces don't provide it), then you should uncomment the XBEE_NO_RTSCTS line.
  5. Run make to build the library. This should complete without any issues.