Colorado: Accessing to 802.15.4 networks from Raspberry Pi. Software

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, ...):

1. 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.
2. 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)
3. 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
4. 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
5. 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.

Read More

Colorado: Accessing to 802.15.4 networks from Raspberry Pi. Hardware

This document describes the integration between a Raspberry Pi and a Digi Xbee 802.15.4 module from a hardware perspective. The document is completed with the notes about the needed operations from a software perspective available here.

The objective of the Colorado project is developing a STEAM concentrator based on Raspberry PI accessing to a 802.15.4 network by using a Digi XBee module. To do that, it is necessary to connect the Raspberry with the Xbee module using a RS232 link, since both devices integrate at least one 232 serial port.

This document takes as base a Raspberry Pi board with a 40 pin connector (specifically RPi B+) and a Digi Xbee Pro S1 802.15.4 module. The description is suitable to be applied to any Digi Xbee module (S1, S2x, S3, standard or PRO) whenever the module specific power requirements were taken into account (see Powe Supply notes)

Serial connection

The modules connection can be simple, ie just by connecting the Tx-Rx lines, or can be more complex by connecting the hardware synchronization lines (RTS and CTS). In the first case a serial hardware control flow will NOT be feasible. Both wiring methods are covered in the next scheme, in which these connections can be seen:

• Raspberry Tx output (pin 8) is connected to the Xbee DIN input (pin 3)
• Xbee DOUT output (pin 2) is connected to the Raspberry Rx input (pin 10)
• In order to provide hardware flow control support:
• Raspberry RTS output (pin 11) is connected to the Xbee CTS input (pin 12)
• XBee RTS output (pin 16) is connected to the Raspberry CTS input (pin 36)

If the hardware flow control option is being implemented, it will be necessary to allow Raspberry Pi to use its pins as RTS/CTS (disabled by default). To do that, follow the instructions defined in the VMW Productions site.

Power supply

Apart of the serial connection, it will be necessary to power the Xbee module from a supply generating, in case of using a Xbee S1 module, a voltage in the range 2,8V-3,4V and a max. current that will depend on the S1 module used, but that ranges from 50 to 340 mA (see power requirements on page 13 of the Xbee S1 User Manual) .

The Raspberry Pi uses four of its pins as power outputs (check full Raspberry Pi pinout here):

• Pins 1 and 17 outputs 3,3V with a max current of 50mA. Though the voltage is in the Xbee voltage input range, the current is in the higher limit of the smallest module, so using this option is not recommended. Note, however, that in case of using a Xbee S2C (the standard version, NOT the pro version) the max current would be between 33 and 45 mA and therefore taking the power supply from these pins would be feasible.
• Pins 2 and 4 outputs 5V with a max current up to 1500mA (depending on the RPi power supply). This current is suitable to power the Xbee module, but requires a voltage regulation.

In order to perform a voltage regulation, a TI TPS7A4700 regulator configured to output 3,3V is used. As can be seen in the previous schematic, the Raspberry Pi pin 2 output (+5V) is connected to the TPS7A4700 input, and its output (+3,3V) is connected to the Xbee module pin 1. To know more about the TI TPS7A4700, click here.

Read More

Elbert: CC26x2 Launchpad + XBee 802.15.4 integration

The first tests for integrating a TI CC26x2 Launchpad as 802.15.4 end node in a PAN coordinated by a Digi Xbee Pro S1 module have been performed with relative successful results: Though the integration is feasible, there are still some stability issues that must be solved.

The tests have been performed taking as base the TI CC26x2 SDK 802.15.4 "sensor" example program, that implements an end-node able to join to a coordinator and send periodically temperature samples (among other data). On the original code, these changes have been performed:

• Application/2_4g/config.h: macro CONFIG_SECURE set to false to disable network encryption
• Application/2_4g/config.h: macro CONFIG_PAN_ID set to 0x0001 to match the PAN id set on the Coordinator side (Xbee ID parameter)
• Application/2_4g/config.h: macro CONFIG_CHANNEL_MASK bytes 1 & 2 (first byte is byte 0) set to 0xF0 and 0xFF to allow end node using all the channels in which the Xbee Pro module can work (from channel 12, or 0x0C, to channel 23, or 0x17). Note however that this channel usage must match the channels enabled on the Xbee coordinator side (parameter SC)

In the other side, a Xbee Pro S1 module with firmware 10EF (last version available) performs the tasks of PAN coordinator, both being installed on a Connectport X2 with the radio forwarded to a serial port or on a XBIB-U-DEV board. The relevant parameters modified in the Xbee module are:

• Coordinator association (A2) mask set to 0x6, indicating that the coordinator will establish the network in the best of the enabled channels (read on) and that the coordinator allows association of end nodes
• Coordinator enable (CE) set to 1: Module working as coordinator
• Encryption enable (EE) set to 0: Encryption disabled
• Mac Mode (MM) set to 2: Module working on legacy 802.15.4 with ACKs enabled
• Network address (MY) set to 0: The coordinator address will be the address 0
• PAN identifier (ID) set to 0x0001
• Scan channels (SC) set to 0x1FFE, meaning that the coordinator will try to establish the network only on all the XBee Pro available channels (from channel 0x0C, or 12, to channel 0x17, or 23).

With these settings, the CC26x2 joins as end node to the PAN created by the Xbee coordinator and a third party is able to receive the temperature data sent by the CC26x2 via the coordinator. Some issues have to be considered, though:

• It is highly recommended to open a Monitor session to the CC26x2 serial port (on Code Composer Studio, via the JTAG interface) to know exactly what is happening on it. The network changes are reported using these numeric codes:
• 0: Module not started, waiting for user to start
• 1: Module trying to join to a network
• 2: After a reboot, the module has found network information on non-volatile memory and it is trying to join the network it was joined before the reboot
• 3: Module successfully joined to a network
• 4: Module successfully rejoined to a network
• 5: Module has lost the network and right now is orphan
• The CC26x2 will always try to rejoin a previously known network. To avoid it, it is necessary rebooting erasing the non-volatile memory by holding button 2, then pressing and releasing the reset button, then releasing button 2.
• If the CC26x2 channel mask is broad, ie, if it has to search a coordinator in many channels, it is possible that the joining was not instantaneous after rebooting: Finding the coordinator channel will take some time (in the order of tens of seconds).
• If the Xbee module serial port is not open, the module locks after receiving 3-5 frames from the CC26x2. It is the explanation to the fact that, if the Xbee module is set on the XBIB-U-DEV board just powered, but with the USB port not mapped in the computer side, it becomes locked. However it does not happen if the same board is connected to a computer that maps the USB port.
• Even being joined, the X2 coordinator does not show the CC26x2 in the list of detected devices. It is possible that only Xbee devices were shown in that list, with information obtained from the Digi extra header added to the 802.15.4 header when the Xbee MM parameters is set to 1 (that is not this case).

At this point it has been confirmed that the connection is feasible. However some stability issues must be investigated:

• In some circumstances, the CC26x2 is not able to find the coordinator network. This usually happens after resetting/reflashing the CC26x2, with the module staying in state 1 (trying to join) permanently. It is necessary to check if, in these circumstances, a reset with nvmem erase (by holding button 2, as explained before) solves the problem.
• In some circumstances, the CC26x2 joins the network and sends samples, but the coordinator is unable to receive data: Neither data is output in X2 gateway mode, nor the X2 counters increment in non-gateway mode, nor the radio signal strength leds in XBIB or X2 show activity.

Read More

Colorado: Voltage regulator for XBee Pro 802.15.4 module

In order to access/manage the 802.15.4 network, a Digi XBee Pro module is being integrated with a Raspberry Pi, the device where the STEAM gateway will run.

This module has a typical voltage input of 3.3V, with a consumption that depends on many factors (versions, PRO features and running modes). In the case of the Xbee Pro S1 international version with RPSMA antenna connector (Digi part number XBP24-ASI-001J), the consumption when transmitting is 150mA, far from the 50mA that the Raspberry Pi GPIO-40 pin 1 outputs.

Is therefore necessary relying on a external power supply or taking the voltage from the Raspberry Pi GPIO-40 pins 2 or 4, that outputs 5V with currents up to 1,5A (depending on the Raspberry Pi PSU). In this last case, a voltage regulator is necessary.

For that purpose, a good option is using a versatile low noise TI TPS7A4700 that, depending on the pin configuration, can output different voltages with a wide input voltage range (3-36V) and a maximum output current of 1A.

The board shown in the photo supports that flexible output voltage configuration by shorting the numbered solder pads and adding to the default 1.4V the value shown in the pad. For instance, shorting the pads 0.4 and 3.2 you get 1.4 + 0.4 + 3.2 = 5V, or shorting the pads 0.1, 0.2 and 1.6 you get 1.4 + 0.1 + 0.2 + 1.6 = 3.3V. The maximum output voltage is 20V.

The shown board can be bought in the TekDevice online shop or eBay.

Read More

Colorado projects started

A new branch in the project repository addressed to develop two new subprojects has been created. The new subprojects are:

• Litem (Mount) Elbert project, addressed to develop a set of Litems based on the Texas Instruments CC26x2 Lauchpad evaluation board (see evaluation board clicking here), using 802.15.4 as network protocol for communicating with the gateway. The code is localted in the subdirectory SteamProject/software/litems/802.15.4/ti-cc26x2-lp/elbert/ of the GitHub repository (direct access clicking here). Given that Elbert works will be developed on a evaluation board, all the results will be considered as experimental.
• Gateway Colorado (river) project, addressed to develop a gateway running on Raspberry Pi (Raspbian OS) implementing 802.15.4 in the underlying network by integrating a Digi Xbee module as interface. The code is located in the subdirectory SteamProject/software/gateways/802.15.4/raspbian/colorado/ of the GitHub repository (direct access clicking here). Colorado source code will be developed in Java and the expected result will be potentially feasible to be put into production.

These two projects will run in parallel, since it is necessary their mutual integration to have a practical result (litem without gateway and viceversa is nonsense). However, even being closely related, it is important to state that the individual results will be compatible with the STEAM specification, ie, Elbert will be compatible with any STEAM 802.15.4 gateway and Colorado will be compatible with any STEAM 802.15.4 litem.

Since both the Colorado river and the mount Elbert have strong relationship with the Colorado state, the above icon is selected to represent graphically these two projects.

For detailed Elbert project information (description, planning and current status) click here. For detailed Colorado project information (description, planning and current status) click here.

Read More

Upgrading a Digi Connectport X2 from Zigbee to 802.15.4 coordinator

In order to create a star topology XBee/802.15.4 network, a coordinator is necessary. That coordinator will be the responsible of managing some aspects of the network and, optionally, acting as gateway to other networks.

I own an old Digi Connectport X2 with ZB firmware, therefore suitable to act as a coordinator of a Zigbee network. This device has an ethernet port that, properly configured, allows sending and receiving radio network packets to or from a TCP/UDP connection, what is really useful in order to make tests from any computer able to access to the ethernet gateway port.

Since I need to form not a Zigbee but a 802.15.4 network, some changes are necessary in order to convert the Connectport X2 Zigbee coordinator into a 802.15.4 coordinator. These are the steps to be done: Upgrading the X2 gateway and Xbee PRO radio module firmwares or, in the last case, replacing the radio module by a 802.15.4 compliant module.

Upgrading the X2 gateway firmware

In order to get the proper firmware, go to the Digi Support Page, "Firmware updates" section and search "Connectport X2 - 802.15.4 - Ethernet" (link here). In case that the installed version was older than the available versions, the best is updating first the POST firmware and then updating the Connectport X2D (that was the exact name of my gateway firmware) firmware. Both the POST and the gateway installed firmwares can be checked in the Gateway "Administration/System information" page. In this case I updated the firmwares to version 1.1.3 release 82002548_B for POST and version 2.17.1.2 release 82002549_G1 04/20/2017 for gateway firmware.

Upgrading the Xbee PRO radio module

After upgrading the gateway firmware, it is necessary upgrading the radio module. The way to do depends on the installed radio module:

• If the gateway contains a Xbee Pro S2(B) module, it is not compatible with the 802.15.4 firmware and therefore it must be replaced by another, 802.15.4 compatible, radio module. The valid options are two:
• Replacing it by a Xbee Pro S1 module: it is old, expensive and it will become deprecated on December 2018, so it is not a good option to buy one.
• Replacing it by a Xbee Pro S2C module: better and cheaper than the S1 module, it is compatible with Connectport X2D from firmware version 2.17.1.1, so upgrading the gateway firmware to that version (or higher) is necessary.
• If the gateway contains a Xbee Pro S2C module, just upgrade the firmware by downloading the latest from the Digi support page (go to the Digi Support Page, "Firmware updates" section and search "XBee / XBee-PRO S2C 802.15.4 Modules", link here). The usual firmware option should be that containing "TH" (through hole) in its name, that is addressed to the Xbee Pro through hole modules that usually are mounted in the X2 gateways. However, in case of trying to upgrade the module with a wrong firmware, the gateway will generate an error and the process will be aborted, so no risk in this step in case of choosing the wrong firmware.

In order to know the radio module used by the gateway, open a session via the gateway web interface and go to Configuration/Xbee Network/Gateway Firmware Update and check the radio type: If it is "Xbee-PRO XNet 2.5 / ZB / SE (0x1a47)" your gateway contains a Xbee Pro S2 radio module, being 0x1a47 the radio module hardware version. If not sure, the last option is just opening the gateway enclosure and checking the installed radio module.

Read More