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.
JMRI can communicate with XBee Series 1 and XBee Series 2 modules.
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:
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.
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.
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.
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.
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: 7 | |
| o | 4:3 | ModuleAddress:Pin | ZS4:3 | int : int | pin: 0 | pin: 7 | |
| o (Turnouts) | 4:3:4 | ModuleAddress:Pin1:Pin2 | ZT4:3:4 | int : int : int | pin: 0 | pin: 7 |
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.
Digi Intl. XBee web site
Faites un don à JMRI.org