set xbee

Purpose

For Digi devices with an embedded XBee RF module, the set xbee command performs several tasks:

Required permissions

For Digi products with two or more users, permissions must be set to set permissions s-mesh=read to display settings, and set permissions s‑mesh=rw to display and configure settings. See set permissions for details on setting user permissions for commands.

Syntax and options

Display available settings for XBee RF module on the gateway

help set xbee

Configure XBee settings on the gateway

These settings control the behavior of the gateway rather than the XBee RF module.

set xbee [state=(on|off)]

Where:

state={off|on}

Enables or disables XBee network communications for the gateway.

Display XBee settings for a node

set xbee [address={node id|network address|extended address}]

Where:

address={node id|network address|extended address}

The address of the node, specified by its node ID, 16-bit network address, or extended address.

To display the node list, enter a display xbee command, or go to this page in the web interface: Configuration > XBee Network. If the address is not specified, the device settings for the local XBee module on the gateway are displayed.

Configure XBee firmware update settings on the gateway

You can update XBee RF moduleswith new firmware over the XBee network. XBee firmware updates are available through Digi Technical Support and are loaded onto the gateway through the web interface.

There are two kinds of XBee firmware updates:

The xbee command controls the actual firmware updates See xbee.

The syntax for configuring XBee firmware update settings on the gateway is:

set xbee [fw_update={on|off}]
  [fw_automatic={on|off}]
  [fw_stop_on_error={on|off}]

Where:

fw_update={on|off}

Enables/disables the XBee firmware update process.

Note fw_update causes extra traffic on the network that might interfere with applications. It is off by default and must be turned on to enable over-the-air (OTA) firmware updates.

fw_automatic={on|off}]

Enables/disables automatic XBee firmware updates.

fw_stop_on_error={on|off}]

Stop on firmware update error.

Uploading and managing XBee firmware files

The command line interface does not have a way to upload and manage XBee firmware files. Uploading and managing firmware files must be done from the gateway’s web interface, as shown in the process below.

Updating XBee ZB firmware on gateway and nodes

The following process applies to OTA firmware updates for XBee ZB module types only. For other module types, or if you want to update the gateway XBee module, you have to use the gateway firmware update page in the web interface. That page uploads a single file and does the update in a single step.

To update XBee firmware on XBee ZB modules, follow these steps:

  1. Load the required XBee firmware files from Digi’s Support page onto a PC. Firmware files for ZB nodes have an .ebl extension. On gateways supporting XBee 3 OTA updates, files with the extensions .ota and .otb are allowed.
  2. Upload the XBee firmware files from the PC to the gateway’s web interface. Go to
    Configuration > XBee Network > Firmware Update Setup
    Multiple files can be uploaded, each containing a different firmware type needed by nodes on the network.
  3. Identify the nodes to be updated, then schedule and monitor updates of individual nodes on the Firmware Update Status page of the web interface, or use the set xbee commands described later in this command description.

Each scheduled update is performed in the background, one node at a time. While a remote node is being updated, it is inaccessible from the XBee network. While the XBee module in the gateway is being updated, the XBee network is inaccessible from the gateway.

Start an XBee firmware update immediately after firmware files are uploaded

The following is the syntax for starting an XBee firmware update immediately after firmware files are uploaded:

set xbee fw_automatic

Where:

fw_automatic

Sets firmware updates to start as soon as the firmware files are uploaded, or as nodes are discovered, without having to schedule them to be updated. An appropriate firmware version is automatically selected from the uploaded files. To restart after an error, schedule another update using the xbee fw_update option or the Configuration > XBee Network > OTA Firmware Update Status page of the web interface.

Settings preserved during firmware updates

If you enable the gateway, most XBee module settings are preserved during the firmware update. Some settings, such as encryption keys, may not be preserved and must be entered again.

XBee Firmware requirements and file naming conventions

XBee firmware updates involve several requirements and follow naming conventions identifying the file by hardware, network, and node type. For details, see the section titled Firmware updates for XBee modules in the User’s Guide for your ConnectPort X gateway.

View the status of XBee firmware updates

To view the status of XBee firmware updates, use the xbee fw_update command. See page 501.

Configure XBee RF module settings on a node

set xbee [address={node id|network address|extended address} [device_settings]

Where:

address={node id|network address|extended address}

The address of the node, specified by its node ID, 16-bit network address, or extended address. If the address is not specified, settings are changed on the local XBee RF module in the gateway.

device_settings

The firmware configuration settings available on the XBee RF module. These settings can vary by XBee RF module type and firmware level. To display available settings:

set xbee ? displays available settings for the XBee RF module in the gateway in the form of help text.

set xbee displays the actual settings for the XBee RF module in the gateway.

set xbee address={node id|extended address} to display settings for the XBee RF module on another node.

For descriptions of the settings, see the Product Manual for the XBee RF module, available from the Support site on digi.com.

Settings are saved to XBee non-volatile RAM (NVRAM) automatically.

Send an AT command to a node

The syntax for sending an AT command to an XBee node is:

set xbee [address={node id|network address|extended address}] CC[=parameter]

Where:

address={node id|extended address}

The address of the node where the device sends the AT command, specified by its node ID, 16-bit network address, or extended address. If the address is not specified, the AT command is sent to the local XBee module on the gateway.

CC[[=]parameter]

The AT command to be sent to the node, where CC is the AT command, specified as two upper-case characters. For example, SM is the command for setting sleep mode.

AT commands vary among node types and the XBee RF module protocol running on the node. To display the available AT commands for both the gateway and remote nodes, enter help set xbee. See the Product Manual on digi.com for the XBee RF module for detailed AT command descriptions.

[[=]parameter]

The associated parameters for the AT command.

Parameters included with the AT command can be:

  • A decimal value, for example, 4
  • A hexadecimal value, specified as 0x<hex>, for example, 0x4
  • A string value, for example, “string”

If no parameter is specified, and the AT command is a settings command, the set xbee command displays the current value for the setting.

Save settings to non-volatile RAM

To save device settings to non-volatile RAM (NVRAM), send the node the AT command WR. The WR command saves settings to the XBee node specified with address=xxx. The WR command is only needed when using AT commands.

Options for backing up and restoring XBee RF module settings

You can save the XBee RF module configuration settings for nodes to a backup file and used them to restore the configuration settings if the need ever arises.

Back up XBee RF module settings for a node to a file

The backup operation saves the node’s XBee RF module configuration settings to a file on a TFTP server. The resulting backup file is a .pro file that is compatible with the XCTU configuration tool. This means that backup files can be saved or loaded from the XBee RF module using XCTU as well as the gateway’s command line or web interfaces.

The syntax for the backup operation is:

set xbee to=server[:filename]

Where:

server

The host name or IP address of the TFTP server.

filename

The name of the backup file. The default filename is address.pro where address is the address of the node, for example: 0013a200403294bb.pro.

Restore XBee RF module settings for a node from a file

The restore operation sets the node’s XBee RF module configuration settings to those in the specified .pro file from a TFTP server.

CAUTION! A restore operation can cause the device to reset its network information, reset, and rejoin a network, meaning it may no longer be accessible from this gateway.

The syntax for the restore operation is

set xbee from=server[:filename]

Where:

server

The host name or IP address of the TFTP server.

filename

The name of the backup file. The default filename is address.pro where address is the address of the node, for example: 0013a200403294bb.pro.

Direct Access communication with the XBee RF module on ConnectPort X2 gateways

On ConnectPort X2 gateways, it is possible to directly communicate with the XBee RF module through its serial port, rather than through the XBee driver software on the gateway. This type of direct access is targeted for applications that require communicating directly with the XBee RF module in the ConnectPort X2 gateway via RealPort, Modbus, or UDP/TCP sockets; to do so, the XBee driver must be disabled. Once disabled, the port used for the XBee driver is open for other services to directly access the XBee RF module, including RealPort, TCP/UDP Sockets, Modbus, and use an open Python serial port.

  1. Disable the XBee driver on the gateway using the set xbee command:
set xbee state=off
  1. Depending on the service used to access the port, enter additional configuration commands or implement additional programming to use the port for direct access to the XBee RF module.

To use RealPort to access the port:

a. Enter a set service command with no options to display all the available network services on the gateway:

set service

b. In the command output, note the index number assigned to the RealPort service. For example:

#> set service
Service Configuration :
index state ipport keepalive nodelay		service
8    on    771       off      na                   	RealPort Service

c. Enter another set service command, specifying the index number assigned to the RealPort service on the range option:

set service range=range state=on

For example:

#> set service range=8 state=on

Once the RealPort service is enabled, the ConnectPort X2 gateway acts as the RealPort server. See the RealPort User’s Guide on digi.com for more details on using the RealPort service.

To use TCP/UDP sockets to access the port:

a. Use the set profile command to configure the port with the settings in the tcp sockets or udp_sockets port profile:

set profile tcp_sockets

Or:

set profile udp_sockets

b. The default baud rate for the XBee RF module is 115200. Use the set serial command to set the baud rate to 115200 and set the flow control to use hardware handshaking.

set serial baudrate=115200 flowcontrol=hardware

To use an open Python serial port to access the port:

Using open Python serial ports to access the port requires additional programming. See the Digi Python Programming Guide and the description of the termios module.

Examples

Disable the XBee gateway

#> set xbee state=off

Enable OTA firmware updates

#> set xbee fw_update=on

Set node ID string on gateway

#> set xbee node_id=”gateway”

Set node ID string on a remote node

#> set xbee address=00:13:a2:00:40:32:94:bb! node_id=”adapter”

Set node ID string on a remote node using AT commands

#> set xbee address=00:13:a2:00:40:32:94:bb! NI=”adapter” WR

Backup remote node's settings

#> set xbee address=adapter to=my_server:config_file.pro

Restore remote node's settings

#> set xbee address=adapter from=my_server:config_file.pro

See also

Digi Python Programming Guide, available on the Digi website.