An XBee Reactive Extensions API
The xbee-rx Node.js module wraps the xbee-api module with a reactive extensions API for ZigBee modules. It may work with older 802.15.4 modules, but it has not been tested with them. Currently it facilitates local commands, remote commands, and remote transmissions. For remote commands and transmissions, either a address or node ID may be provided, with automatic lookup and caching done for the node ID.
xbee-rx relies on serialport for serial communications.
First, you will need to install the
xbee-rx module (i.e.
npm install xbee-rx or
yarn add xbee-rx).
To create a connection to your module, you will need to know the serial port that
it is connected to. On Windows, this typically has the form
a number. On unix and OS X machines, this will typically be
??? can be anything from
.usbserial-A4013E5P. In addition, you will
need to make sure that the module connected to your machine is in API mode and that
you know the baud rate it is set to. By default, the baud rate is 57600 when API
mode is used. In addition, you will need to know if you are using a ZigBee module,
a ZNet module or a 802.15.4 module. These are sometimes referred to as series 2 for
ZigBee or series 1 for 802.15.4. (Currently there are no differences in how this
library works between the ZigBee and ZNet modules. Older series 2 modules have ZNet
firmware and can typically be upgraded to ZigBee firmware.) Once these details are
known, you can initialize xbee-rx:
var xbeeRx = ;var xbee =;
Note: if you are using API mode 2, you must specify that with the
api_mode: 2). You can give any options
known by serialport inside
serialportOptions (other than
parser as it is used and set by xbee-rx). To see
what the library is doing (during lookups, etc), you can add the debug flag
debug: true). Finally, you can set the default timeout for all commands with
defaultTimeoutMs. The default is 5000 milliseconds.
Local commands may be performed using the
localCommand fuction. They can be query
commands (no parameters) or set commands (with parameters).
Remote commands may be performed using the
remoteCommand fuction. They are similar
to local commands, but must have either a
destination64 64 bit address, a
destination16 16 bit address, a
destinationId node ID to indicate the target of
the command or the
broadcast flag set to
true to broadcast to all nodes.
destinationId is not supported by 802.15.4 modules.
Since there is support for broadcasting commands to multiple nodes, the entire frame is included in the resulting stream.
Data may be transmitted using the
remoteTransmit fuction. The destination is
set in the same manner as for remote commands. The text to send is given with
data parameter. The resulting stream contains a single
true value if
the data was sent out or an error result if the node does not respond or
responds with an error. If you want to capture a response from another node,
you will need to make use of
Monitoring incoming packets
You can subscribe to incoming packets in three ways. You can monitor all incoming
packets by subscribing to
var subscription = xbeeallPackets;
You can monitor incoming IO data sample packets by calling
That returns a stream of all packets filtered on the IO sample type.
var subscription = xbee;
You can also monitor incoming transmission packets by calling
That returns a stream of all packets filtered on the transmission type.
var subscription = xbee;
In all cases, the subscription should be cleaned up when you are done using it by
unsubscribe on the subscription.
Closing the connection
When you are done using the library, you should call the
close method to clean up
xbee-rx module as well as the contained serialport connection.
A note about subscriptions
All of the commands must be subcribed to before they will activate. For example, the following code will have no effect.
Typically, you would want to subscribe to see if the command worked (was acknowledged by the XBee module), so that you could print an error or try again. If you don't care about the result, you will still need to make a dummy subscription to trigger the command, as in the following code.
xbee; // ignore status/result packet
Some more examples can be found in the repository.
Possible future work
Future possible expansion of this module include:
- Adding command line tool to perform all three types of commands (for testing, etc).
- Translating inputs and outputs of commands logically. E.g. ATNI command should return a string, not an array of character codes, ATD1 (and friends) should accept numeric values, and not require them to be in a byte array of the correct length.