This document defines the procedure, from a software perspective, for accesing to a 802.15.4 network from a Raspberry Pi using a Digi Xbee module. This document completes the
analogue document defining the procedure from a hardware perspective.
Once successfully completed the hardware integration between a Raspberry Pi B+ board and a Digi XBee S1 Pro 802.15.4 module, it is necessary to perform some actions addressed to allow the software running on the RPi to access the 802.15.4 network. Since the XBee module is running as PAN coordinator, some of the actions must be addressed to support this additional requirement.
As said in the hardware document, the RPi has a serial port suitable to be used for creating a TTL-level connection with the Xbee module. In the Raspberry versions prior to version 3, this port was
/dev/ttyAMA0, however when Bluetooth functions were added the
AMA0 was used for Bluetooth and the simpler and more troublesome
mini-uart was in charge of the serial connections. So in case of having a RPi 3 and wanting to switch back to the
AMA0 serial port (very recommended), it is necessary to edit the
/boot/config.txt file and add a new line with the directive
dtoverlay=pi3-miniuart-bt.
Another potential problem present in the RPi regarding the usage of the serial ports is the fact that the Linux kernel is configured by default to attach a console to /
dev/ttyAMA0. That means that, when booting, the kernel will write to the serial port what could set (and actually does) the Xbee module in a unstable status. To avoid the kernel using the serial port, edit the file
/boot/cmdline.txt, that contains the argument list passed to the kernel, and remove the argument
console=serial0,115200 or
console=ttyAMA0,155200. Take special care in just removing that argument and its preceding or traling space to keep the agument list format coherent.
At this point the RPi is ready to use the XBee module connected to its
/dev/ttyAMA0 serial port. To do that from a software point of view, the chosen approach is developing Java code due to several reasons:
- Java is supported by Raspbian, specifically the JDK8. To install it, run sudo apt-get install oracle-java8-jdk.
- You can access the serial port from Java using, among other options, the RxTx library. To install it, run sudo apt-get install librxtx-java.
- You can access the GPIO input/outputs from Java by using the Pi4J library. Specifically, you can use a GPIO output to hard-reset the Digi module, a very interesting option when even the soft reset fails (and it does). To know more about how to control de GPIOs check this example, and to know how to install Pi4J, click here. How to reset the XBee from a RPi GPIO output will be covered in future documents.
Last but not least, you can programatically interface with Digi XBee devices by using the Digi XBee Java Library, whose source code and binaries are available on
GitHub and whose complete
documention is available on the Digi site. This library offers a high level interface for managing the XBee modules, both as 802.15.4 end points or coordinators. At least up to the last available release (1.2.1) this library relies on the Java RxTx library for accessing the serial port, so it is necessary to install it to allow the library run (see the previous notes about how to install the RxTx library).
First test
Once the XBee Java library is installed on a development computer (that can or cannot be the RPi), a good starting point is following the “Building your first XBee Java application” tutorial described in the library documentation, and doing it taking as base the
ReceiveDataSample example contained in the
examples/communication subdirectory. This example writes in the standard output all the data (in hex and ASCII format) received from any 802.15.4 end node. To properly run this example, it is necessary to follow these steps once the project has been successfully loaded in the development environment (Eclipse, Netbeans, ...):
- Modify the values of the variables PORT and BAUD_RATE declared in the main function, that store the name of the serial port (set PORT to “/dev/ttyAMA0”) and baud rate (set BAUD_RATE to 115200) used to connect to the XBee module.
- After successfully building the project, copy the contents of the project subdirectory dist (in Netbeans, the subdirectory where the binaries and libraries are stored after building) to a directory in the RPi (for this example we will assume that it will be copied to the destination directory /tmp/receiveDataTest in the Raspberry Pi)
- To run the generated .jar package successfully, It is necessary to tell Java where the native libraries for accesing the serial port (ie, the RxTx libraries) are stored. Specifically, it is necessary to set the system property java.library.path to /usr/lib/jni by calling java with the argument -Djava.library.path=/usr/lib/jni
- Due to a known bug in the RxTx library (at least in version 2.1.2), it will not be able to open /dev/ttyAMA0 by itself when running the generated example. To avoid it, set the Java system property gnu.io.rxtx.SerialPorts to /dev/ttyAMA0 by calling java with the argument -Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0
- It is necessary to grant the user running the example permissions to access the serial port. For that purpose, the user must both belong to the dialout group or run the program with root permissions (sudo).
Overall, run the generated example with the command line:
java -Djava.library.path=/usr/lib/jni \
-Dgnu.io.rxtx.SerialPorts=/dev/ttyAMA0 \
-cp /tmp/receiveDataTest/lib:. \
-jar /tmp/receiveDataTest/Xbee.DataReceive.jar
By running the previous command, the Java application launcher will run the file
/tmp/receiveDataTest/Xbee.DataReceive.jar (or whatever was the name of the jar file generated when building the project) using the libraries stored in the subdirectory
/tmp/receiveDataTest/lib with the suitable values for the system properties
java.library.path and
gnu.io.rxtx.SerialPorts as previously explained.
It is possible to get a warning message telling about a version mismatch between the RxTx installed version and that used when building the example, but it should not be a problem for starting watching frames in the console as soon as any 802.15.4 end node sent information.
