Skip to main content

Hardware Support: Digi XBee Network

The Digi International XBee Modules are family of wireless communication devices that have their own microcontroller and IO pins that make them useful for many distributed control networks, including on model railroads.

Supported Hardware

Command Station

JMRI can communicate with XBee Series 1 and XBee Series 2 modules.

Computer Interfaces

JMRI support for XBee devices includes serial interfaces to XBee Networks. The connection to the computer may be made by any USB or RS232 XBee adapter. Tested adapters include:

Connecting

Wiring

JMRI can communicate with XBee Series 1 and XBee Series 2 modules.

In JMRI versions Prior to 4.5.5, Underlying support for communication is provided by Andrew Rapp's xbee-api library for Java.

Starting with JMRI version 4.5.5, the Underlying support for communication is provided by The Digi XBee Java Library.

Both library requires that the XBee module connected to the PC be configured for API mode with escapes (mode 2).

JMRI support for the Digi XBee Modules currently includes the ability to passively read digital sensor inputs, as JMRI Sensors, and triggering digital outputs, through the JMRI Lights and Turnouts.

XBee Module Addressing

Each XBee module has 5 addresses we need to be aware of:

The IEEE 802.15.4 Channel Number is set by configuring the XBee's CH parameter. The value of the CH parameter can be any (hex) value from 0x0B to 0x1A. This corresponds to decimal values 11 to 26. All XBee modules in the network must be set to the same channel number.

The 16 bit PAN (Personal Area Network) address is assigned by setting the XBee's ID parameter. All XBee modules in the network must be set to use the same PAN.

The 16 bit user address is defined by the XBee's MY parameter. Some XBee firmware will automatically set the value of MY to be a unique address on the network, but others do not. If the My parameter is user configurable, it should be a unique address.

The 64 bit globally unique id (GUID) is defined by the factory. This value is the hex string printed on the underside of each XBee module. You can also read the value by reading the SH (Serial Number High) and SL (Serial Number Low) parameters of the XBee. The user cannot change the values of SH and SL.

The free-form Node Identifier is a 20 character text value stored in the XBee's NI parameter. The Node Identifier should be unique, and may be human readable.

Note: You need to be aware of other devices using IEEE 802.15.4 radio networks that may be operating in the same area. Digitrax Duplex throttles and Roco MultiMaus Pro radio throttles both use IEEE 802.15.4 as the underlying network layer protocol. If these devices share a PAN and channel with your XBee modules, the devices are all a part of the same network, and the 16 bit user address must be unique.

Input/Output pin addressing

When creating inputs (Sensors) and outputs (either Lights or Turnouts) in JMRI, the XBee's IO pins can be individually addressed. To access a single bit, you can use the form:

ModuleAddress:Pin

Where ModuleAddress is one of the 16 bit node address, the 64 bit node address, or the Node Identifier string and Pin is an XBee IO pin number.

Turnouts may be created using two bits. To specify a turnout created with two bits, you use the following format:

ModuleAddress:Pin1:Pin2

Where ModuleAddress is one of the 16 bit node address, the 64 bit node address, or the Node Identifier string and Pin1 and Pin2 are XBee IO pin numbers. The Pin numbers do not need to be consecutive.

Automatic Creation of Sensors

When an XBee input status message is received indicating one ( or more ) of the XBee IO Pins is used as an input, JMRI will automatically create a sensor for each input pin if it does not already exist.

When sensors are created automatically, the Node Identifier will be used for the ModuleAddress if it is not blank. If the Node Identifier is blank, the 16 bit MY address field will be used for the ModuleAddress unless the MY address field contains a broadcast address. If neither the Node Identifier or the 16 bit MY Address are used for the ModuleAddress, the 64 bit GUID will be used for the ModuleAddress.

Adding an item to the table

When you add an item to one of the tables, many times you only have to fill in the numbers to have JMRI construct the complete system name.
Here's a summary, split up for outputs (eg. Turnouts) and inputs (eg. Sensors):

In/Out Entry Meaning makes System Name Mask Equivalent Minimum Maximum
i 4:3 ModuleAddress:Pin ZS4:3 int : int pin: 0 pin: 71 (?)
o 4:3:4 ModuleAddress:Pin1:Pin2 ZT4:3:4 int : int : int pin: 0 pin: 71 (?)

Software settings

  1. Connect your XBee adapter using the appropriate cable.
  2. USB-connected XBee adapters may need to have a driver installed. See the documentation provided by the manufacturer of your XBee Adapter.
  3. Make sure you have the latest version of JMRI, then go to the preferences panel of a JMRI-based program. This opens automatically the first time a program is run, or you can select it from the "Edit" menu
  4. Select "IEEE 802.15.4 Network" from the System Manufacturer selection box.
  5. Select "XBee Network" from the System Connection selection box.
  6. You can then select the proper serial port in the Serial port selection box under Settings.
    Note that USB XBee adapters will appear as a serial port.
  7. The "Connection Prefix" is used to help JMRI communicate separately with multiple "connections" to layout hardware. Each "connection" must have a unique identifier, which is specified as the "Connection Prefix". By default, the first XBee connection is given a prefix of "Z", and additional XBee networks are given prefixes like "Z1", "Z2", ... Most users should be able to use the default "Connection Prefix" value provided by the JMRI tools.
  8. When a JMRI tool is configured for more than one connection, each connection gets a menu item on the main JMRI tool window. To help users differentiate between their different connections, each connection has a "Connection Name", which is used as the name of the associated menu item on the main JMRI tool window. Users may change the "Connection Name" for any connection to suit their needs.
  9. The XBee adapter "Additional Connection Settings" provides access to the Baud rate for the connection. Make sure the selected Baud rate matches the port speed setting of your XBee.
  10. The "Configure XBee Nodes" button opens the XBee Node Configuration tool. If you save Preferences after Nodes are created, node address information will be stored with the JMRI Preferences.
  11. Click "Save". You'll be asked if it's OK for the program to quit; click "Yes".
  12. Restart the program. You should be up and running.

JMRI XBee Tools

XBee Node Configuration

The XBee Node Configuration tool can be used to add XBee Nodes to a JMRI configuration. You can access the tool from the Xbee menu when an XBee connection is active. The "Configure XBee Nodes" button at the bottom of the JMRI Preferences Connections tab also opens the XBee Node Configuration tool. If you save Preferences after Nodes are created, node address information will be stored with the JMRI Preferences.

Documentation

Third Party info

Digi Intl. XBee web site