Simon Dobson (Posts about xbee)

XBee sleeping

Simon Dobson — Fri, 02 Aug 2013 14:41:30 GMT

Clearly saving battery power means getting the XBee radio to sleep at the behest of the Arduino. This turns out to be fairly simple, but does require modifying the XBee shield slightly.

Our previous measurements indicate that the XBee draws about 45mA of current -- something we have to save for battery-powered nodes. Fortunately XBee radios have a hardware-controlled sleep mode, so the Arduino can sleep the radio when not in use.

Since XBees work as a mesh network, it's clearly going to be an issue as to when a radio sleeps, and for how long -- since when asleep the radio can't route packets, and so the network starts to break down. But that's a higher-level concern: for the moment, we'll focus on the mechanics of getting the XBee to sleep.

The basic mechanism is simple, and involves hardware and software. At the hardware level, the XBee uses pin 9 (shown in red right) as a control pin. This pin can be used to sleep the radio: setting it to 3,3V ("high" or "asserted") causes the radio to sleep; setting it to 0V ("low" or "deasserted") wakes the radio up. The XBee only takes account of the pin when in certain sleep modes, however: these are analogous to the Arduino's sleep modes. This is the software part: the XBee needs to be placed into the correct sleep mode, and can then be controlled from the Arduino.

Also note I/O line 7, pin 12 (in green): we'll come back to this later.

We'll deal with the hardware part first, and then the software.

Getting access to the sleep pin

The XBee shield doesn't connect the sleep pin to anything by default, so to control it we have to connect it. There are several ways we could do this, with the simplest being to solder a wire from the pan on pin 9 to an appropriate header on the shield, which is then connected to a digital pin on the Arduino. For simplicity we'll start with a wire that's long enough to reach any header: we'll actually plug it into the header for the Arduino's D7 pin.

There's a slight concern about voltage levels in this approach, as the Arduino operates at 5V while the XBee uses 3.3V. Experimentally this doesn't seem to make a difference; for a production system we'd probably want to create a resistor network to drop the voltage to that needed by the radio, to avoid any risk of damage. We'd also probably want to solder a header to XBee pin 9's pad to make it easier to connect the wiring.

Setting the sleep mode

The XBee's sleep mode is controlled by a single AT command called (unsurprisingly) SM. The default (SM 0) is for the radio to be on all the time; SM 1 selects the pin-sleep mode described above, and is the one we'll be using as it places the radio under the (hardware) control of the Arduino. (There are other sleep modes where the radio sleeps under the control of its own internal timer. Some projects use the radio's timer to wake the Arduino rather than the other way round: we prefer to keep the Arduino in control.)

Setting the sleep mode is simply a matter of issuing the appropriate AT command. However, as with a lot of things to do with hardware, we have to set things up slightly first.

The first issue concerns the setting of the XBee's sleep pin. If we select pin-sleep mode with the pin high, the XBee will sleep immediately, which might not be what we intended. So if we've connected the sleep pin to D7, we need to set things up so that the pin is low to keep the radio awake, and then select its sleep mode:

#define XBEE_SLEEP 7                // Xbee sleep pin on D7

void setup() {
   ...
   pinMode(XBEE_SLEEP, OUTPUT);     // sleep control
   digitalWrite(XBEE_SLEEP, LOW);   // deassert to keep radio awake when sleep mode selected
   ...
}

(Some early mistakes showed that -- contrary to what might be expected -- the sleep pin defaults to high (send radio to sleep) rather than low. So this step is important.)

The next issue concerns the rather intricate behaviour of the XBee's other pins when sleeping. When the radio enters sleep mode, it asserts its I/O 7 line (pin 12) so that external devices know that it's asleep. This could be used to make sure that external peripherals wake up only when the radio is active, but for some reason the XBee shield's designers have connected this pin to the Arduino's reset line, which means that sleeping the radio will reset (and in fact freeze) the Arduino. Some posts suggest that solving this requires cutting lines on the shield, which might have been true for earlier shields but now isn't: we simply need to disable the output of this pin, using another AT command:

atCommand("D7", 0);

This disables the XBee's D7 line (not to be confused with the Arduino's D7 line, which we've attached to the XBee's sleep pin), which is enough to stop the Arduino freezing. on sleep. (Yes, this did take quite a while to work out, since you ask...)

We can now put all this together to place the XBee into SM 1 and let the Arduino sleep it at will:

#define LED 13
#define XBEE_SLEEP 7                // XBee sleep pin on D7

void setup() {
   pinMode(LED, OUTPUT);            // LED signal
   pinMode(XBEE_SLEEP, OUTPUT);     // sleep control
   Serial.begin(9600);
   radio.setSerial(Serial);

   digitalWrite(XBEE_SLEEP, LOW);   // deassert to keep radio awake when sleep mode selected
   if(atCommand("D7", 1) | atCommand("SM", 1)) {
      // AT commands failed, flash frantically
      ...
   }
   ...
}

Note that we've used local AT commands to set the radio's mode. It's also possible to do this statically using X-CTU.

Results

The results of all this hacking are that the Arduino can put the XBee into sleep mode whenever it wants to simply by asserting D7. The voltages on pins are maintained even when the Arduino itself sleeps, so it can put the radio to sleep and then sleep itself, wake up and wake up the radio.

Measuring current shows that the sleeping Arduino and XBee draw abour 35mA, the same as an Arduino alone. This makes sense, as the XBee datasheet suggests that when sleeping it draws current in the microamp range -- far too small for a normal ammeter to measure, and dwarfed by the quiescent current of the Arduino board (which still needs some work).

Waking the radio happens quickly when the sleep pin is deasserted, but it seems to take some time to re-connect to the mesh co-ordinator: around 7s, in fact, which is a little strange and needs some more exploration.

Issuing AT commands

Simon Dobson — Fri, 02 Aug 2013 11:03:54 GMT

Controlling the XBee requires issuing AT commands. The XBee library has the low-level machinery to do this.

AT commands are the basis for controlling almost all modems, and the XBee is no different. In API mode, AT commands are issued in a similar manner to sending data. The Arduino XBee library has the low-level code needed, which can be wrapped into a slightly easier-to-use form.

The basic approach is to send an AT command request packet and then read a returned packet acknowledging the command. For the moment we'll stick to "setting" commands, where the AT command takes an integer parameter: the other are needed less frequently. We construct the request packet, send it, read the response, and check that all went well. This isolates the rest of the program from the message exchange, but also hides the exact nature of any error.

#include <XBee.h>

XBee radio;

int atCommand( char *command, uint8_t param ) {
  // send local AT command
  AtCommandRequest req = AtCommandRequest((uint8_t *) command, (uint8_t *) &amp;param, sizeof(uint8_t));
  radio.send(req);

  // receive response frame
  AtCommandResponse res = AtCommandResponse();
  if(radio.readPacket(500)) {                               // read packet from radio
     if(radio.getResponse().getApiId() == AT_RESPONSE) {    // right type?
       radio.getResponse().getAtCommandResponse(res);
       if(res.isOk()) {                                     // not an error?
         return 0;
       }
     }
  }

  // if we get here, return a failure
  return 1;
}

This function can be used to issue the different control codes for the radio. Some parameters can be set using X-CTU when the radio firmware is installed, but commands are sometimes needed at run-time too.

Basic power measurements

Simon Dobson — Wed, 31 Jul 2013 17:12:55 GMT

Some initial measurements of power consumption.

How much power does Arduino sleep mode save? The simplest way to work this out is to power an Arduino from a battery pack and measure the current being drawn in the different modes. A simple program to demonstrate the different modes is:

Normal delay() loop
Deep sleep for a period (deep sleep)
Flash the LED (awake)
Flash the LED differently while sending out radio messages (awake and transmitting)

We perform these tasks repeatedly, keeping them going for 10s each to let the power draw stabilise.

The results are as follows:

Activity	Power mode	Current
Nothing	`delay()` loop	43mA
Nothing	Deep sleep	33mA
Steady LED	Deep sleep	34mA
Flashing LED	Awake	45mA
Xbee (quiet)	Deep sleep	72mA
Xbee (quiet)	Awake	85mA
Xbee (transmitting)	Awake	87mA

The good news is that SleepySketch makes it very easy to access the deep sleep mode, and to stay in it by default. This is good, as the normal approach of using delay() is quite power-hungry. The bad news is that the "at rest" power consumption of an Arduino even in deep sleep -- the quiescent current being drawn by the voltage regulator and other components on the board, regardless of what the microcontroller is doing -- is about 35mA, with an XBee drawing an additional 40mA.There is very little difference in power whether the radio is transmitting or not (although the current being drawn looked more variable when transmitting, suggesting that there's some variation happening faster than the ammeter's sample time).

The radio isn't put to sleep when the Arduino is asleep, which is clearly something that needs to happen: it draws power even when the Arduino is incapable of using it. Something to explore. Potentially more serious is the power being drawn when the Arduino is asleep. A battery pack with 4 x 1500mAH batteries will be drained in about 7 days (6000mAH / 35mA) even with the system asleep all the time.

[UPDATE 1Aug2013: made the table layout a bit clearer.]

Radio survey

Simon Dobson — Fri, 26 Jul 2013 11:11:52 GMT

A simple radio survey establishes the ranges that the radios can manage.

The 2mW XBee radios we've got have a nominal range of 100m -- but that's in free air, with no obstructions like bushes, ditches, and houses, and not when enclosed in a plastic box to protect them from the elements. There's a reasonable chance that these obstacles will reduce the real range significantly.

A radio survey is fairly simple to accomplish. We load software that talks to a server on the base station -- something as simple as possible, like sending a single packet with a count every ten seconds -- and keep careful track of the return values coming back from the radio library. We then use the only output device we have -- an LED -- to indicate the success or failure of each operation, preferably with an indication of why it failed if it did. (Three flashes for unsuccessful transmission, five for no response received, and so forth.) We then walk away from the base station, watching the behaviour of the radio. When it starts to get errors, we've reached the edge of the effective range.

With two sensor motes, we can also check wireless mesh networking. If we place the first mote in range of the base station, we should then be able to walk further and have the second mote connect via the first, automatically. That's the theory, anyway...

(One extra thing to improve robustness: if the radios lose connection or get power-cycled, they can end up on a different radio channel to the co-ordinator. To prevent this, the radio needs to have an ATJV1 command issued to it. The easiest way to do this is at set-up, through the advanced settings in X-CTU.)

The results are fairly unsurprising. In an enclosure, in the field, with a base station inside a house (and so behind double glazing and suchlike) the effective range of the XBees is about 30--40m -- somewhat less than half the nominal range, and not really sufficient to reach the chosen science site: another 10--20m would be fine. On the other hand, the XBees mesh together seamlessly: taking a node out of range and placing another between it and the base station connects the network with no effort.

This is somewhat disappointing, but that's what this project is all about: the practicalities of sensor networking with cheap hardware.

There are several options to improve matters. A higher-powered radio would help: the 50mW XBee has a nominal range of 1km and so would be easily sufficient (and could probably be run at reduced transmission power). A router node halfway between base station and sensors could extend the network, and the cost of an additional non-sensing component. Better antennas on the 2mW radios might help too, especially if they could be placed outside the enclosure.

It's also worth noting that the radio segment is horrendously hard to debug with only a single LED for signalling. Adding more LEDs might help, but it's still a very poor debugging interface, even compared to printing status messages to the USB port.

API communications now working

Simon Dobson — Sat, 06 Jul 2013 11:12:05 GMT

A small sensor network now working, with two edge devices talking to a base station.

This step of the project accomplishes two things: is gets API networking mode working for the XBee radios, and makes sure the the interaction between software on the Arduinos and software running on the base station work too.

The data stream is simple enough: each Arduino counts up from 0 to 255 every 5s, passing the result up to the co-ordinator radio. A Processing program on the laptop collects the numbers and prints them. Naturally they become somewhat intertwined as their clocks aren't quite synchronised.

Actually this is enough to perform a simple radio survey to check transmission distance: we can move the radios away from the base station until they lose contact (nominally 100m for these 2mW radios, in reality probably substantially less), then move back into range, and then move one of the radios again to check that it meshes with the intermediate node in reaching back to the base station. This will also check that battery power works.

The software is quite straightforward, and the xbee-arduino library handles all the low-level communications -- although it's very low-level, fine for the experienced programmer but probably all but mystifying to anyone not used to this kind of software. The corresponding Java xbee-api library is slightly more friendly, but only slightly: they probably both need wrapping into a framework that hides the radio nastiness.

I think the biggest hurdle for this sort of system is the data format -- or, more precisely, the need (or desire, at least) to to use C at one end and Processing/Java at the other, which means that the data on the wire is being described twice. A framework approach could use (for example) JSON, although there'd still be a need to make sure it was compactly encoded and transmitted.

The xbee-arduino library

Simon Dobson — Wed, 03 Jul 2013 07:30:22 GMT

A library for using XBee radios with Arduinos.

The XBee radio operates in two modes: transparent or text-based, and API or binary-based. The latter (API mode) is generally considered more suitable for computer-to-computer interactions, as it's faster and simpler for computers to manipulate. However, using an XBee in this mode requires additional software.

The xbee-arduino library provides Arduino functions to access the API mode functionality of the various XBee radio modules. The library is quite low-level, but does provide access to all the necessary functions like issuing AT commands to control the modem and sensing and receiving packets of data to other radios in the mesh network.

To use the library you download the latest version from the web page and unpack it into the libraries/ directory of your Arduino IDE. You also need to make sure that the radios you use have the API function set installed using X-CTU, as the library only makes sense for radios in API mode. You also have to set the "AP" parameter to 2 when writing the firmware.

XBee firmware management with X-CTU

Simon Dobson — Tue, 02 Jul 2013 08:00:34 GMT

Managing Digi's XBee radio modules requires using their X-CTU package to upload the correct firmware. In this post we explain how.

This post is slightly depressing: not because it's on an unhappy topic, but because the effort and software needed to manage XBee radios is so complex to set up. In many ways this is just a function of the good design of the XBee: it's so minimal in terms of footprint and power consumption at run-time that it offloads a lot of work to external tools (and the user) at system build-time. But it's still a lot of work to get such a small piece of kit running.

X-CTU is intended to upload firmware to XBee radio modules. This is needed to change the firmware between router and co-ordinator of the Zigbee mesh network, and between the different protocol variants that the XBee radios can support.

One limitation of X-CTU is that it only works on Windows: if you're running Linux, X-CTU will run under Wine. You can download the latest X-CTU from Digi's X-CTU page; alternatively, there's a version installed on the Citizen Sensing VM.

To use X-CTU you need to connect your XBee module to your computer. The easiest way to do this is using an XBee USB breakout board, which provides an XBee socket and a USB socket. Insert the radio into the board, plug in a USB cable, and plug the other end into a USB socket. The light on the breakout board will then come on (see photograph above).

You next need to start up X-CTU and tell it where the XBee is. It hangs off a Windows COM port, and X-CTU will typically find it automatically. You should then be able to press the "Test/Query" button, and X-CTU will interrogate the XBee and display a small window showing some information about it, as shown in the screenshot on the right: the details don't matter, but this shows that the XBee is talking to the computer properly.

Assuming everything is now working correctly, the next step is to decide what firmware to download to the radio. Click on the "Modem configuration" tab, and then click the "Read" button: this reads the firmware that's on the XBee at the moment, and puts the details into the window. Typically this results in a display like that shown on the left. The important things to notice are the two drop-down boxes labelled "Function Set" and "Version". The function set is the description of the firmware, in which case indicating that the XBee is running Zigbee router firmware that responds to AT commands (more on this below).

To download a new firmware, we then select the function set and version we want to use. Suppose we want to make this XBee into the mesh co-ordinator. We change the function set to "Zigbee Coordinator AT" (keeping with Zigbee and the AT command set) in "Function set" the drop-down, then select the most recent version of this function set from the "Version" drop-down. (Versions are identified by hex numbers: the most recent in the screenshot right is "20A7", that being the highest hex number. Unfortunately X-CTU orders the numbers alphabetically, not in hex-numeric order.) Pressing "Write" will update the radio's firmware, and the radio is then ready for use as a co-ordinator.

If you look through the list of function sets, there will be quite a few options, including protocols other than Zigbee. These probably aren't worth too much exploration, but you'll also notice that there are Zigbee AT and API function sets corresponding to the two modes (transparent and API) that the XBee can support. Be sure to select the correct one for your application.

That's it: the radio is now ready for use.

Advanced use: setting optional parameters

There's one more thing that X-CTU can be used for: it can set parameters to the firmware function set, and this is sometimes important when using the radios.

When you've read the firmware from a radio, the main part of the X-CTU window contains a hierarchy of folders and cryptic values, for example "(4) PL - Power level". These are parameters that can be changed to modify the detailed behaviour of the radio. Some can also be set using AT commands. The example we used sets the radio's power level to 4. If you click on this, it will show a drop-down box giving other options. You might, for some applications, choose to reduce the radio power to 1 ("low") to save batteries. If you choose this and then write the firmware to the radio, the module will use this power setting.

In the example shown on the left, we're changing the AP parameter ("API enable") to 2, which is needed for the xbee-arduino library to work properly. If we now write the firmware (with the Zigbee co-ordinator API function set selected as shown), the radio will be ready for use.

XBee radios

Simon Dobson — Mon, 01 Jul 2013 17:23:15 GMT

The XBee is a series of small radio modules that implement the Zigbee protocol and work well with Arduinos.

XBees are made by Digi. The range includes a number of options: you almost certainly want some variant of the Zigbee range. The Series 2 (S2) modules seem to offer good performance, low power, and a useful range of functions. There are several different antenna types and two different radio powers (2mW and 50mW): larger power provides more range (1km nominal as opposed to 100m) at the cost of twenty-five times the power consumption: best avoided unless really needed. A collection of XBee modules co-operate to form a mesh network that's quite robust against partial failure, which makes them great for use in the field.

To get XBees working with an Arduino you need several pieces of hardware and software:

Two or more radios (obvious, but surprisingly easy to only buy one...)
One or more Arduinos
One Arduino XBee shield for each radio-equipped Arduino
One XBee USB breakout board
The X-CTU firmware management software

There are also variations of Arduinos that take XBee modules directly, as well as other sensor mote systems that can work with them: they're not completely Arduino-specific.

When buying radios, buy them all the same series: the different series aren't guaranteed to interwork (although they often do). In the photograph above there are two different XBees: one with a patch antenna and one with a whip antenna.

The Xbee shield fits on top of the Arduino. They're sold without a radio module.

The breakout board is used to connect an XBee to the USB port of a computer, allowing your network to be accessed from the desktop. This is useful for debugging and for data logging, unless you're also going to build a dedicated data logger.

The X-CTU software manages the firmware on the radio module. Because the radios are small and low-power, they don't have room for a sophisticated software stack, and so aren't programmed in the normal way. Instead you download a firmware providing exactly the functions you need. Each network is given an identifier (a personal area network id or PAN) so that several networks can co-exist in the same area without interfering with each other. Each network has exactly one co-ordinator, with the others being routers, Co-ordinator and router use different firmware: you nominate one of your radios as co-ordinator (which will typically live on the base station, or on the data logger) and use X-CTU to load co-ordinator firmware to it; the other radios get router firmware and are placed onto the sensor motes.

XBees actually have two communication modes you can choose between, by choosing different firmware. The simplest is the AT firmware. These provide simple, text-based communications between radios: what one Arduino writes as text comes out on the other. In this mode the XBee also responds to Hayes AT commands, a standard way of controlling a modem (which is what an XBee technically is): we'll explore these commands in another post. This function set -- router and co-ordinator -- sets up what might be called a transparent network, in the sense that it behaves just like a serial pipe. This makes it easy to get things up and running.Text-based interaction isn't great for computer-to-computer communications, however, not least because of the effort (and memory) needed to understand text-based protocols. For this reason, the XBee also supports API function sets that provide binary communications. These are better for computers, and faster when running, but require more programming and more intellectual effort to understand. We'll deal with API communications in another post too.

We'll deal with the details of using X-CTU in another post, as well as explaining how to set up a simple network.