1. Introduction

The Raspberry Pi is a credit card sized system on a chip running on an ARM processor. This project utilizes the Raspbian operating system and model A+ Raspberry Pis.

The XBee is a radio frequency module produced by Digi International Inc. This project uses the Series 1, IEEE 802.25.4 standard XBees with wire antennas.

The Explorer Dongle from SparkFun is a USB-to-Serial converter and is used to connect the XBees to each Raspberry Pi and to the Master Terminal Unit (laptop).

The main goal of the project is to run a python script that is able to send and receive messages from anything that controls an XBee, including other Raspberry Pis. The sub goal will be to determine the RSSI value from a sent packet of information which will be useful for a future project.

2. Raspberry Pi Configuration

The Raspberry Pi model A+ comes bare out of the box and needs an operating system to be installed. The easiest way to achieve this is to purchase a micro sd card with an operating system boot loader. For this project, an 8GB micro sd card with NOOBS was purchased for each model A+ and was used to install the Raspbian operating system on each Pi. Raspbian is a clone of Debian, a common Linux distribution, optimized to run on the Raspberry Pi hardware. Every time the Pi boots up it requests an ID and password, by default these are “pi” and “raspberry”, respectively.

Because the Raspberry Pi was developed in the UK, it is useful to change the keyboard layout to US standard. This can be done by booting up the Pi and typing the command in the terminal:

sudo raspi-config

While in the command window, make sure that SSH is enabled and then navigate to the “internationalization” options and change the keyboard layout.

In order to download the python libraries needed for this project to work, the Pi’s must be connected to the internet. Because the A+ model only has one USB port, the Pi needs to be configured so that it automatically connects to a wifi network when a USB wifi dongle is connected. In the command line, navigate to the following directory and open the supplicant:

cd /etc/wpa_supplicant
sudo nano wpa_supplicant.conf

This will open up the wpa supplicant. In this file, below the other text, add the lines:

Change the content in the quotations to match your network, keeping the quotations. Save and exit the file. When the wifi dongle is plugged in, your Raspberry Pi should automatically connect to your wifi network. Get the IP address (this shows up on the last line of a successful boot with the wifi dongle plugged in, right before it asks you for the login ID). Use a remote SSH client like PuTTY to run the Pi headless (if you are using a model B you do not need to do this, the model A+ only has one USB port which is taken up by the wifi dongle, so to issue commands you need to run it headless).

When the Pi is successfully connected to the internet, connect to it using an SSH client by inputting the IP address. It should ask you to login on the headless terminal. Login and run these commands to download all the necessary libraries for this project:

sudo apt-get update
sudo apt-get install python-dev
sudo apt-get install python-pip
ssudo shutdown –r now

3. XBee Configuration

Configuration of the Xbees is most easily done using Digis’ XCTU software. Because the Series 1 XBees use the 802.15.4 function set, the out of the box firmware does not have to be changed. Plug the XBee into a laptop using an XBee Explorer Dongle and discover it using the XCTU software. In the configuration window, change and write the appropriate settings. The configuration window is shown in Figure 1.

XBee configuration window
Figure 1. XBee configuration window.

The modified settings for this project were:

  • PAN ID: 1337
  • Destination Address Low: FFFF
  • Node Identifier: Copter-A, Copter-B, Copter-C, Target and MTU
  • All XBees were set to API mode

The XBees were donated as 'copters' in reference to a future project. The only note is that there are only two Xbees needed in this guide compared to three copters, a master terminal unit, and a target in the future project.

4. Writing Python Scripts

To write and run python programs on the Raspberry Pi requires a few commands in the terminal. From the terminal type:

sudo -i

This will invoke full access to the Pi as the superuser. It is wise to create a new directory to save your programs. First, change the directory from the root to “pi”, and then make a new directory called “programs” by issuing the commands:

cd /home/pi
mkdir programs
cd programs

To create and edit files, use the pico command. To edit a file, type “pico” and then the file as a .py file:

pico exsistingPythonScript.py

To create a new file, issue the same command but give the file a unique name- to check what is already in the directory use the “ls” command. Make sure to append the “.py” to specify python.

Run these programs using the “python” command.

An example of how this should look in the terminal:

Hello World Example

root@raspberrypi:/home/pi/programs# pico HelloWorld.py

-------
# This is the file, save by pressing ctr-x
print “Hello World”
-------

root@raspberrypi:/home/pi/programs# python HelloWorld.py
>> Hello World

5. Getting the Raspberry Pis to Talk

Getting the Raspberry Pis to communicate serially through XBees means first understanding how the XBees communicate to each other and then determining how to implement these communications in code. There are many different variations and modes for the XBees to send and receive data but only in API (Application Programming Interface) mode will the Raspberry Pis be able to easily determine the RSSI value of an incoming signal. API mode allows data to be sent and received as packets of data or “frames.” A frame is broken down in the following way:

Start Delimiter
Start delimiter of the API frame. Always set to 0x7E.

Length
Number of Bytes between length and checksum fields.

Frame Type
Indicates the frame type of the API frame. This project uses 0x00- Long Address Transmit Requests that get received as 0x80- Long Address Received Packets.

Frame ID
Identifies the UART data frame for the host to match with a subsequent response. If zero, no response is requested. Set to zero, responses would add unwanted noise to the system and cause program errors.

64-bit Dest. Address
Set to the 64-bit address of the destination device. This is the MAC Address of the XBee.

Options
Bitfield to enable various command options. Ignored.

RF Data
Packet Payload (up to 256 bytes)

Checksum
FF minus 8-bit sum of bytes between the length and the checksum fields.

RSSI
Received Signal Strength Indicator (Receive Packets)

Source Address
Source Address for Receive Packets (00 00 Universal)

Figure 2 shows an example of how packets are sent and received. XBee A sends out a transmit request containing the MAC address of XBee B. XBee B picks up the request, confirms the address and reads the data. The RSSI value is included as part of the “receive packet” frame.

XBee communication example
Figure 2. XBee communication.

The communication between two XBees can be handled in python by use of the XBee library written by Paul Malmsten which, “provides a semi-complete implementation of the XBee binary API protocol and allows a developer to send and receive the information they desire without dealing with the raw communication details” [1]. The library is imported into a python program with the line from xbee import XBee.

Initializing an XBee object requires some information about the XBee (the serial port that the XBee is connected to and the baud rate) and the python serial library:

The function wait_read_frame() for receiving data continuously reads the serial port and converts incoming packets into python dictionaries. If XBee B of Figure 2 were connected to a Raspberry Pi, the received frame would look as follows:

dictionary = xbee.wait_read_frame()
print dictionary

>> {‘rf_data’: ‘Hello’, ‘rssi’: ‘+’, ‘source_addr’: ‘\x00\x00’, ‘id’: ‘rx’, ‘options’: ‘\x00’}

Notice the RSSI value and Frame ID are in ASCII notation.

The function for sending data works the opposite way- converting a python dictionary into a frame and transmitting:

6. Example

Imagine the following python script called "ping" is being executed by a Raspberry Pi. What it does is listens for a "PING" command from another Xbee and then sends the data '\x50\x49\x4E\x47\x42\x41\x43\x4B' (PINGBACK in ASCII) to the XBee with address '\x00\x13\xA2\x00\x40\xD8\x76\x2E'

Using the XCTU software, one can easily send this type of packet to a Raspberry Pi running this script. Or, two raspberry pis can run modified versions of the script to ping each other continuously.

7. References

[1] P. Malmsten, “python-xbee Documentation”, Release 2.1.0, 2013.








Revision History
Revision Date Author Description
1.0 May 10, 2015 Ryan Whitell
  1. Genesis
2.0 August 10, 2015 Ryan Whitell
  1. Added links to future project: TLS
3.0 May 2, 2017 Ryan Whitell
  1. Embedded gist host for ping.py instead of hard coding in HTML
4.0 May 7, 2017 Ryan Whitell
  1. Added Disqus
5.0 May 8, 2017 Ryan Whitell
  1. Changed a few of the panels to blockquotes