Building Wireless Sensor Networks Using Arduino

Here is an overview of all the XBee product families that Digi currently produces and that use the common XBee through-hole pinout (a few other families use a surface-mount design, but these are not discussed here):

Sometimes you will also see the terms Series 1, which is the name originally used for the XBee 802.15.4 family, and Series 2, which is a retired family that used the same hardware as XBee ZB but with a different firmware (ZNet 2.5) and radio protocol. This old naming is still reflected in the names used for individual hardware boards, which use names such as S1, S2, S2B, and so on.

As noted earlier, some modules are available in normal and PRO variants. These PRO modules use the same radio and serial protocol as the regular modules, but feature a more powerful transmitter and more sensitive receiver, allowing for a significantly extended range (and also requiring more power, of course). Since the radio protocol is the same, the normal and PRO modules of the same family can be intermixed.

Most of the XBee modules are available in a few different versions, differing only in the antennae they use. The easiest are the PCB antenna, which uses copper on the circuit board as the antenna, and the wire antenna, where a short piece of wire sticks up from the board. Both have similar performance. There are also modules available with a u.FL or RPSMA antenna connector, allowing them to have an external antenna (useful for projects inside a box, needing maximum reception). When in doubt, get the PCB antenna version, as it is the least fragile and performs well.

For a few more details about the available boards, also see this guide from SparkFun: https://www.sparkfun.com/pages/xbee_guide.

In this book, all examples (and most of the discussion) focus on the XBee ZB modules, but most of the material presented also applies to the other modules. Where significant differences occur, these will be noted and (concise) instructions for other module types will be given. Therefore, if you decide to use the XBee 802.15.4, XBee DigiMesh 2.4, or XBee-PRO 868 modules (or any of the PRO variants), you can still work through this book normally. The XBee-PRO 900HP modules are not discussed in this book, but these are expected to work in a very similar way to the DigiMesh modules.

Instructions for the Wi-Fi modules are not included, since the setup and operation of Wi-Fi are significantly different from the other modules. However, a lot of the more general information (API frame format, XCTU operation, and AT commands) applies equally to these modules.

For each of the XBee module series, Digi publishes a lot of documentation. This documentation can be accessed from the Digi website, through the Support section. The most important document is the Product Manual, which contains info on the hardware, network setup, a full list of commands and API frames supported, and so on.

Even though all the information you need for these examples is included in this book, you are encouraged to get familiar with the product manual for your XBee modules as well. The manual will be a lot more detailed in some areas and is easy to use as reference material for commands, configuration values, frame types, and so on.

Note that, within the ZigBee ZB family, there is a division between older boards (using S2 or S2B hardware) and newer boards (using S2C hardware). These boards are largely compatible, but there are two separate product manuals available with largely identical content (which are both titled Product Manual: XBee / XBee-PRO ZigBee RF Modules). Be sure to get the right one for your boards.

This is by far the easiest way to connect an XBee module: just plug in the XBee module and connect the USB cable:

Be sure to disconnect the power (USB cable) when changing connections, or (un)plugging XBee modules into adapters and shields, to avoid damaging them.

You might have to install drivers for the FTDI USB-to-serial chip used by the Explorer, though this should have been taken care of if you have already installed the Arduino IDE (the older Arduino boards use the same chip and drivers). See the SparkFun site for more information on using the Explorer boards (https://learn.sparkfun.com/tutorials/exploring-xbees-and-xctu) or installing the FTDI drivers (https://learn.sparkfun.com/tutorials/how-to-install-ftdi-drivers).

If the drivers are installed correctly, a new (virtual) serial port will be made available; you can select it in the XCTU program later.

As a first step in preparing your module for operation, you should check, and potentially replace, its firmware. For XBee ZB S2/S2B modules, this is needed to switch between different modes of operation, but for other modules it also makes sense to ensure your module is running the latest available firmware version.

The firmware is a bit of software, written by the manufacturer, that controls the XBee modules internally. It is responsible for operating the radio, taking care of the 802.15.4, ZigBee, and/or DigiMesh protocol processing (as well as any encryption), and communicating the results on the serial port.

For most XBee modules, there are several variants of the firmware, each with a slightly different function set. Some of these provide different features, but others are intended for hardware only. For now, you should just use the function set indicated next, but by the end of this chapter you will know what most of the function sets listed mean exactly.

To replace the firmware, some special commands have to be sent through the serial port to start the boot loader, which is a small piece of low-level software running on the XBee module that takes care of firmware updates. After starting the boot loader, the firmware file can be transferred through the serial port. Fortunately, there is no need to take care of this manually—the XCTU program can mostly handle firmware updates automatically.

To initiate a firmware update, select the module on the left, and click on the Update firmware button:

A window pops up, allowing you to select the Product family, Function set, and Firmware version. The right product family should already be selected (take a note of which one is selected in case you need to do recovery later). The first module will be the coordinator, so select the ZigBee Coordinator AT function set when using an XBee ZB S2 or S2B module, or ZIGBEE Reg function set when using S2C (where Reg is for Regular and indicates that this is not XBee-PRO). Finally, select the highest version listed to use the most recent firmware version.

You should probably also uncheck the Force the module to maintain its current configuration checkbox, in order to ensure you start with a clean factory default configuration.

Your selection should look like this:

By clicking on Update, the XCTU program will start replacing the current firmware with the one selected. This takes around half a minute to complete; be sure not to unplug the board during the process.

Note that, when you replace an existing coordinator's firmware, it will also start a new network. If other XBee modules previously joined the coordinator's network, it is possible that these are now joined to the old network and will no longer talk with the new coordinator. You can check by looking at the OI configuration value, these should be equal on all modules. The easiest way to force the router to leave the old network, is to change its ID configuration value, click the Write button, then change ID back to its previous value and click Write again. Doing this on the router(s) after you change the coordinator's firmware should prevent issues.

For this initial example, only minimal configuration is needed:

For example, to change the destination address:

Setting CE is similar, but the value can be found in the Networking section instead.

Now, to talk to your XBee module, you can use the serial console built into XCTU (using another serial program is also possible, but do not forget to disconnect in XCTU first). To do so, head over to the Consoles working mode by clicking on its button at the top right:

Then click on the Open connection button in the top left of this area to enable the console:

The console is divided into two parts horizontally. The left side shows all data sent (blue) or received (red) as text and lets you type text to be sent. The right shows the same, but shows each byte value in hexadecimal.

Go ahead and type something in the left area. Anything you type there will be sent to the XBee module, which will then directly send the data through the radio again. So, you have sent your first radio message now, even though there is nobody listening yet.

To allow configuring the module, a special command mode is supported too (this is what is used under water when you change a configuration value in XCTU). By default, this command mode can be entered by sending a special sequence to the XBee module: a pause of at least 1 second, three iterations of a plus sign (+++, no Enter), and another pause of at least 1 second. When command mode is entered, the XBee module will reply with OK, and commands can be sent to the XBee module, terminated by a newline. These commands all start with AT, inspired by the Hayes command set originally designed for dial-up modems. Since these commands use normal text, it is easy to interact through AT mode simply by using a serial terminal. When no command is given for a while (10 seconds by default), the module leaves command mode again.

Try entering command mode and giving the ATVR command (do not forget to press Enter), which should retrieve the current firmware version:

The sketch used for receiving data is available in the code bundle as SerialDump.ino. The exact contents of the sketch will not be discussed here, though you are encouraged to look inside to see what happens. Basically, the sketch opens up a serial connection to the XBee module at 9,600 bps (bits per second), and a serial connection to the computer at 115,200 bps. Any data received from the XBee module is forwarded to the computer, both in hexadecimal and readable ASCII format.

This sketch uses the AltSoftSerial library, so be sure to install that through the library manager, or download it from https://www.pjrc.com/teensy/td_libs_AltSoftSerial.html.

To connect the XBee module to your Arduino, you will use the SparkFun XBee shield. To allow talking both to the computer and the XBee at the same time reliably, you will need some trickery to connect the XBee's serial pins to AltSoftSerial's pins 8 and 9. This will be explained in more detail in Chapter 2, Connecting Sensor Data, but for now:

This should look a bit like this:

To actually receive data, open up the serial monitor in the Arduino IDE and configure it for 115200 baud. Now head back to the console in XCTU and type a message to be sent:

It is best to first type the message in a text editor, such as Notepad, and then paste it into XCTU. This makes sure the entire message is sent in a single radio packet. If you type in XCTU directly, each letter will be put into its own packet, which can cause delays and, when broadcasting, even mess up the ordering of letters in some circumstances.

In the serial monitor, you should see the same message being received:

Starting....
48 65 6C 6C 6F 2C 20 77  Hello, w
6F 72 6C 64 21           orld!

As you can see, any data sent to the XBee module on the sending side is reproduced byte-for-byte identically on the receiving side. For this reason, this mode of operation is commonly called transparent mode and can be useful to quickly make an existing serial connection wireless.

The sketch also allows typing a message into the serial monitor, which will be sent to the XBee module and then on to the other XBee module, and is shown in XCTU, so go ahead and try that too.

To take advantage of API mode, you will need to configure your modules to use it. First, try switching your coordinator to API mode:

With this change, the XBee module will no longer allow typing of messages directly into the serial console, but expects to receive properly formatted API frames instead.

Sending data

To send these frames, head over to the Consoles working mode at the top-right again. Click on Open connection like before to connect to your XBee module.

You will notice that the window looks different from before. The screen is still divided into two parts horizontally, where the left part (directly under Frames log) will show all API frames sent to or received from the XBee module. This includes any frames sent by XCTU automatically (for example, when changing configuration parameters or doing a network scan), any replies to frames sent, as well as any data packets received by the radio. The right part shows details for any selected API frame.

Right now, this area should be empty, but you are going to change that by telling the XBee module to send out a message again. To do so, you will create a ZigBee Transmit Request API frame using XCTU and send it to the XBee module. At the bottom of the window, there is a Send frames section, which can be used to send API frames to the module. To prepare an API frame to send, click the Add frame button:

In the first input box, you can input a descriptive name for the frame. In the second input box, you can enter the raw bytes of the API frame. You could dig through the product manual to figure out how to construct a ZigBee Transmit Request API frame manually (which is still a good exercise), but it is easier to use the Frames Generator tool included with XCTU. You can access this tool by clicking the button at the bottom of the window:

In the Frames Generator tool, leave the Protocol value at the default, which should be appropriate for your module. The Frame type drop-down list shows all frame types defined for your particular device and protocol. Note that it also includes frame types that are normally only sent by the module, such as Receive packet. These are included for completeness, but will be ignored by the module when you send them to the module.

Tip

Downloading the example code

You can download the example code files from your account at http://www.packtpub.com for all the Packt Publishing books you have purchased. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

The frame you need looks like this:

This selects the Transmit request frame type (called ZigBee Transmit Request in the product manual). Most of the other parameters are fine at their defaults. Under 64-bit dest. address, enter 00 00 00 00 00 00 FF FF. This is the same broadcast address you configured in DH and DL before. When using API mode, these configuration values are unused; instead, the target address is specified for each outgoing frame individually.

Under RF Data, you can enter the actual message data to be sent.

After confirming with Ok, XCTU now shows the raw bytes of your Hello, world! frame. If you look closely, you can discover the 0x7e start byte, 0x001b as the frame length, 0x10 as the frame type, and the destination addresses:

Click on Apply changes to make the frame show up in the Send frames list. To actually send it to the router module, select it and click on Send selected frame to the right.

Doing this immediately makes two frames show up in the Frames log. The first is the Transmit Request frame sent to the module, followed by a Transmit Status reply. Clicking the frames shows their details to the right. If everything went right, the status frame will show a Delivery status of 00 (Success), indicating that the frame was successfully sent.

Now, head back to the serial monitor that shows the output from your Arduino. This should show the "Hello, world!" message you transmitted:

Starting....
48 65 6C 6C 6F 2C 20 57  Hello, W
6F 72 6C 64 21           orld!

As you can see, you can exchange data between nodes running in AT and API mode just fine; each will just output the received data to the serial port in its own mode. You could try sending a bit of data back from the Arduino to the coordinator as well, to see how that shows up in XCTU.

To complete the transition to API mode, you should switch over the second XBee module, too. For this, plug it into the XBee Explorer module temporarily to replace the firmware if needed and set AP=2.

Then plug the second XBee module back into the Arduino shield and the first one back into the Explorer. If you use XCTU as before to let the first module send the "Hello, World!" message again, the Arduino serial monitor output will look different from before:

Starting....
7E 00 19 90 00 13 A2 00  ~.......
40 D8 5F 9D 00 00 02 48  @._....H
65 6C 6C 6F 2C 20 57 6F  ello, Wo
72 6C 64 21 3B           rld!;

Instead of printing just the message, a full API frame is printed. The message is contained inside, but also the API frame type (0x90), sender address (0x0013A20040D85F9D), message length (0x0019), and so on. Check out the section on API operation in the product manual to figure out exactly what each byte means.

If you try typing some data into the Arduino serial monitor now, you will see that this data no longer shows up in XCTU like before. The XBee module expects to receive a correct binary API frame, which is unlikely to happen if you just type some letters. In the next chapter, you will see how to use an Arduino library to properly format these API frames.

In addition to a PAN ID for the entire network, each module also has two addresses of its own. Using these addresses, modules will only receive data that is intended for them, and they can identify the sender of any data they receive.

The two different addresses for each module are:

To verify that all devices have been connected to the same network properly, or to find out more about how they are connected, you can use the network scanning feature in XCTU. This feature can be accessed in two ways. The most extensive one is by switching to the Network working mode at the top right:

Start a network scan using the Scan the radio module network button:

Alternatively, you can also directly click on the Discover radio nodes button next to a connected module in the list on the left. The former method shows more details about the network, such as a graph containing links, and shows all devices found. The latter method shows detected nodes in a list and only shows XBee modules.

To help identify nodes, the NI (Node Identifier) configuration value in the Addressing section can be used. This is just a human-readable name for this XBee module, which can help you tell them apart (though it is not shown in the network scan with the 6.2.0 version of XCTU, unfortunately).

In addition to discovering remote devices, you can also configure any remote XBee modules, just as if you are connected directly to them. To do so, double-click the device in the graph, or select it in the discovery list, and click on Add selected devices. Go ahead and explore these XCTU features; they might come in handy later.

Some XBee adapters or shields have a commissioning button, which can be used for some limited interaction with the module (such as briefly allowing new devices to join the network or doing a factory reset—see the product manual for details). Such a button simply connects to the AD0/DIO0 pin on one side and GND on the other, shorting them together when the button is pressed. If your setup does not have a button, it is easy to add one, or simply use a jumper wire to briefly make the connection to emulate a button press. Also, note that some adapters have a reset button (to reset the XBee and/or Arduino), so be sure to check what kind of button you have.

More commonly, adapters and shields have a LED connected to the XBee Associate/DIO5 pin (the associate LED) and/or the RSSI/DIO10 pin (the RSSI LED). The associate LED is lit continuously when a device is not joined to a network, but slowly blinks when the XBee module is successfully joined. It can also be used for more advanced diagnostics together with the commissioning button; see the product manual for details. The RSSI LED indicates the signal strength of the most recently received signal (the better the signal, the brighter the LED).

Both LEDs and the commissioning button can be disabled through the XBee configuration (to save power, or allow reusing the pin for a different purpose), but are enabled by default (though there will not always be a button or LED connected, of course).

When a module joins the network, it automatically receives the network key from the so-called trust center. The trust center is responsible for distributing network keys throughout the network when a node joins, or when the key is changed.

In XBee networks, the trust center always runs inside the coordinator, but the ZigBee protocol itself makes provision for running the trust center in another module as well. The ZigBee specification also allows preconfiguring the network key on all nodes, but the XBee firmware does not currently support this.

By default (with the KY configuration value set to its default of 0), the trust center sends the network key to joining nodes without using any encryption. This obviously poses a security risk: if someone can spy on your network traffic while your modules are joining the network, they can see your network key. Even more, an attacker could simply have his own module join the network and the network key would be sent to him, unencrypted.

To reduce this risk, you can configure your network to not allow new nodes to join normally, and only enable joining briefly when you have a new node to add. The network will still be vulnerable during these brief periods, but if the network is not compromised while joining is enabled, it will remain secure while joining is disabled. Refer to the Disabling network joining section for more info on how to disable joining.

To further secure the network and avoid having to send the network key unencrypted, ZigBee defines a second key, called the trust center link key. This key is manually configured in each module (using the KY configuration value) before it creates or joins the network. The trust center then uses this key to encrypt the network key when it is sent to new nodes joining the network. Eavesdroppers, not knowing the trust center link key, will not be able to decrypt the network key and so cannot read any of your data.

On XBee modules, there is a single trust center link key that must be known to all joining modules. The ZigBee protocol also allows for using a different trust center link key for each module, which would require more extensive configuration, but this is not supported by the current XBee ZB firmware.

When selecting a random key, be sure to always select a full-length key. It is possible to enter a shorter key in the KY and NK configuration values and a lot of the examples in the XBee documentation also do this. However, if you enter, for example, ABCD as a key, it will be prepended with zeroes, so the actual key will end up being 0000000000000000000000000000ABCD. This severely limits the security—a four-digit key like this can be brute-forced in a matter of seconds using a regular computer.

A strong key should be properly random and be 32 (hexadecimal) digits long (which is 16 bytes or 128 bits). Keys such as these are effectively impossible to crack using brute force, even when using current supercomputers.

$ openssl rand -hex 16
077ef3b3e5121efa166445c63e18538d

Now that you understand how security works in a ZigBee network, you can go ahead and restart your network with security enabled. To enable optimal security using a trust center link key, make the following configuration changes to both the coordinator and the router node (in either order):

For example:

Note that the KY value can only be set, never read back, so be sure to store the key you set somewhere to allow adding new nodes to your network later.

Changing these values will automatically cause the modules to leave the current network and create a new network (coordinator) or find a new network to join (router).

After a few seconds, the new network should be formed. You can again transfer your Hello, world! message, but in a secure way this time.

By default, XBee modules allow new modules to join the network at any time. If you configured a trust center link key, joining is of course limited to nodes that know this secret key, preventing unauthorized access to your network.

However, as an additional layer of security (or, when not using a trust center link key, the primary layer), you can also disable all join attempts after you started your network and joined your devices. You can briefly re-enable joining later when you intend to add a new device to your network.

When a device wants to join a network, it searches for an existing router (or coordinator) that allows joining. Whether this is allowed depends on the NJ configuration value:

The NJ value is not a global value for the entire network, but each node has its own value and can decide on its own whether to allow new nodes to join. Even if the coordinator has joining disabled, the trust center will still send keys to nodes that joined through another router.

In general, it is a good idea to set NJ=0 on all modules by default, and then change the value on a nearby router or the coordinator (or use the commissioning button) whenever you need to add a node to the network.

Note that, for end devices, there is also a special rejoin procedure; refer to Chapter 6, Finishing Touches and the product manual for more information about this.

If you followed the preceding examples, you should have configured the following values on all your XBee modules:

The changes to DH and DL were only needed for the AT mode examples and are no longer relevant in API mode.