Quick Round-up on XBee DigiMesh Modules

Written by James Ewe, last modified on May 25 2:46 (GMT+8).

DigiMesh

Digi offers a proprietary mesh networking topology with the XBee-PRO 900HP (XSC S3B) products which I have chances to play with.

The below unit serves as the reference unit of this writeup:

XBee-PRO XSC S3B 900Mhz (XBP9B-XCWT-001 Rev R)
with DigiMesh 900Mhz 200kb/s firmware

Note: Older revisions (<=G) of this module do not support DigiMesh firmware, they use the older P2MP method.

Several main features of DigiMesh (not inclusive):

• Peer-to-peer: One homogenous node class. Every node is a distributed node which may come and go (due to interference or simply moving out of range).
• Self-healing and flexible (Results of above implementation).
• On-demand route discovery
• Simple setup
• Configurability (on both network level and nodes level)

Some specifications (limitations):

• Payload: 256 Bytes (API mode limitation)
• Throughput:
  • ~20kb/s (API mode, 256 Bytes payload, unicast, 115.2k Baud rate)
  • ~90kb/s (Transparent mode, 10k Bytes payload, unicast, 115.2k Baud rate)
  • Note: In modules guide^[2] page 73, a mesh throughput table is provided of n<=3 hops, keep in mind that this is done on Transparent mode which is not mentioned in the text.
• Limited indoor range compared to other modules like LoRA

API mode and Transparent (AT) mode

Digi provides AT mode along with API mode but API mode are far more useful with many features it supports. However, AT mode don't have the 256 Bytes payload limitations so thats something to consider if you need bigger payload size.

In AT mode, the module serves as a bridge as any data sent to the module through UART is sent out to the remote module specified by the Destination Address stored in the memory.

In API mode, data packets are assembled along with Destination Address and options in a frame. API mode allows you to change destination address much more quickly because Command Mode doesn't need to be entered (to change the address in the memory). API mode is also useful if the user needs to change the configuration of a remote module.

This round-up focus on API mode operations.

Meshing Behaviors

General

• MAC layer is responsible for sending and receiving RF frames, and packet acknowledgements (ACKs) and packet tracking (to eliminate duplicates) are also implemented in this layer.
• There are no beacons or master/slave requirements in the design of the MAC/PHY.

Addressing

• IEEE 64-bit address
• Stored in SH SL registers of the modules
• Broadcast address is 0xFFFF

Unicast

The network uses retries and ACK for reliable data delivery. If the transmitting device does not receive an ACK then it re-sends the packet.

Broadcast

Broadcast message is broadcast to all neighbors, then all routers that receive the message rebroadcast the message MT+1 times. Eventually, the message reaches the entire network. Packet tracking of MAC layer will discards duplicate broadcast packet.
MT = Broadcast Multi-transmit. Default = 3.

Routing and Aggregation

• Mesh like topology
• Routing Algo: Ad-hoc On-demand Distance Vector (AODV)

On demand route discovery

Route discovery is performed only when:

1. The source node does not have a route to the requested destination.
2. A route fails. This happens when the source node uses up its network retries without receiving an ACK.

Details provided in the modules guide^[2]:

1. Route discovery begins by the source node broadcasting a route request (RREQ). We call any router that receives the RREQ and is not the ultimate destination, an intermediate node.
2. Intermediate nodes may either drop or forward a RREQ, depending on whether the new RREQ has a better route back to the source node. If so, the node saves, updates and broadcasts the RREQ.
3. When the ultimate destination receives the RREQ, it unicasts a route reply (RREP) back to the source node along the path of the RREQ. It does this regardless of route quality and regardless of how many times it has seen an RREQ before.
4. This allows the source node to receive multiple route replies. The source node selects the route with the best round trip route quality, which it uses for the queued packet and for subsequent packets with the same destination address.

We can see that route discovery is complicated and may take up a lot of time if we have a lot of nodes without the routing information, in the event of this, it is best to initialise our network using the Aggregation command (AG).

STAR-like topology with Aggregation command (AG)

AG: sends a broadcast through the network that has the following effects on nodes that receive the broadcast:

• The receiving node establishes a DigiMesh route back to the originating node, if there is space in the routing table.

The resulting routing network will looks like a STAR topology with the originating node as the central node.

Some useful API frames and commands

AT Commands

• DB - Last Packet RSSI
  • Return RSSI of last packet (last hop).
• ND - Network Discover
  • Discovers and reports all devices found in the network. For each discovered device, a report is returned.
• FN - Find Neighbours
  • Discovers and reports all devices found within immediate (1 hop) RF range. For each device it discovers, a report is returned.
• AG - Aggregator Support
  • Explained above.

API frames

• AT Command Request and Response
  This frame type is used set AT commands on the local device.
  

• TX Request and TX Status

  • This frame type is used to send serial payload data as an RF packet to a remote device with a corresponding 64-bit IEEE address. Has an option to enable traceroute for diagnostic.
  • TX Status frame type is emitted when a transmit request completes. The status field of this frame indicates whether the request succeeded or failed and the reason.
    

• Remote Command Request and Response
  Same as AT Command request frame, but on a remote device.
  

  
  The module will not return the Remote AT frame if the remote module does not received the command.

• Route Information frame
  This frame type is emitted in response to a unicast tx request which has Trace Routing or NACK enabled. It contains the routing information for a remote device on the network. Used for diagnostics.

• Aggregate Addressing Update
  This frame type is emitted on devices that update its addressing information in response to a network aggregator issuing an addressing update (AG command).

Python Library

A Python library^[4] is provided by Digi for using the module in Python scripts.

• Below are a few simple examples for communicating between modules.

#Instantiate a XBee DigiMesh device
    device = DigiMeshDevice("/dev/ttyUSB0", 115200)
    
#Open serial connection
    device.open() #open serial connection
    
#Execute AT commands: eg. Find Neighbour
    device.execute_command("FN")
    
#Unicast: using address or xbee object
    device.send_data(RemoteDigiMeshDevice, String or Bytearray, Integer)
    device.send_data_64(XBee64BitAddress, String or Bytearray, Integer)
    
#Broadcast
    device.send_data_broadcast(String or Bytearray, Integer)
    
#Register callback function for receiving data
    device.add_data_received_callback(callback)

#Close the serial connection
    device.close()

• If you need more advance operations, i.e. frames other than TX/RX, you may interface with the serial port directly using method in xbee.serial module.

device = XBeeSerialPort(baud_rate, port)

#Open serial
    device.open()

#Write frame (bytearray, must be in correct frame format)
    device.write_frame(frame)

#Read frame (blocking)
    device.wait_for_frame(operating_mode)

#Close serial
    device.close()

• You can construct or deconstruct (encode/decode) the frame using method given in xbee.packets module

eg:
digi.xbee.packets.common.TransmitPacket
digi.xbee.packets.common.ReceivePacket
digi.xbee.packets.common.TransmitStatusPacket
digi.xbee.packets.digimesh.RouteInformationPacket

• In any case, you can always encode or decode a frame yourself if the specific frame is not provided as a module in the library. All the needed specifications are given in the modules guide^[3].

Simple 3 node test (max 2 hops)

Disclaimer: This is in no way a serious test nor a fair test as there were many other variables uncontrolled. Also, the location mentioned makes no sense to most people so this only serves as a simple demo and my own reference.

Range Test

Setup:

• In these tests, the stationary receiving node, LONG is placed in EE622. Table A2.
• PI is the mobile source node.
• IDENT is the intermediate node during 2 hops tests.
• Test is done using XCTU^[3]

Note: The above screenshot is took after the tests so the rssi value is not the true representing value.

• 1 hop

Walking from EE622 to EE627: Signal(packet) loss started in front of EE635

In front of the area around the elevator

Inside EE627: No signal at all

• 2 hops

Inside EE627 with intermediate node outside on the corridor (around 3 meter from EE627 door)

• Notice the local RSSI is -40 which is FULL signal, this is because XBee only return RSSI of last hop, which is from outside EE627 to inside EE627.

Throughput Test

• 1 hop

Walking back from EE627 to EE622

• 2 hops

Inside EE627 with intermediate node outside on the corridor (around 3 meter from EE627 door)

Route Discovery after intermediate node exits

Frame 26: Transmit Request: Success
Frame 27: Source to Intermediate: ACK timeout count 1
Frame 28: Source to Intermediate: ACK timeout count 2 (Retry 1)
Frame 29: Source to Intermediate: ACK timeout count 3 (Retry 2)
Frame 30: Source direct to Destination: Success (Retry 3)
Frame 30: Transmit Status: Success
Took ~5.5 seconds in total. ~4 seconds in another try.

Walking from outside EE627 into EE627

• 00:29:45 - Packet loss
• 00:29:49 - Connection loss
• 00:29:55 - Route Rediscovered (With intermediate hops)
  Took ~6 seconds.
  

References

1. Zigbee vs DigiMesh whitepaper
2. XBee-PRO 900HP/XSC RF Modules Guide
3. XCTU Software
4. XBee Python Library

All Digi, XBee, and XCTU brandings and its products are copyrights owned by Digi International, Inc.