Networking methods

Note: It is important to keep in mind that XBee networks are defined by the networking parameters. Every XBee module within a network must share the same networking parameters. In the case of the XBee DigiMesh, every node in a network must have the same:

• PAN ID

• Channel

• Encryption configuration

Topologies

DigiMesh provides different topologies to create a network:

• Star: a star network has a central node, which is linked to all

  other nodes in the network. The central node gathers all data coming

  from the network nodes.

Figure : Star Topology

• Mesh: all the nodes are connected among them. DigiMesh provides

  a Network Layer to route packets among nodes out of sight.

Figure : Mesh Topology

DigiMesh architecture

Mesh networking allows messages routing through several different nodes to a final destination. In the event that one RF connection between nodes is lost (due to power-loss, environmental obstructions, etc.) critical data can still reach its destination due to the mesh networking capabilities embedded inside the modules.

DigiMesh contains the following features:

• Self-healing: any node may enter or leave the network at any time without causing the network as a whole to fail.

• No hierarchy and no parent-child relationships are needed.

• Quiet Protocol: routing overhead will be reduced by using a reactive protocol similar to AODV.

• Route Discovery: rather than maintaining a network map, routes will be discovered and created only when needed.

• Selective acknowledgments: only the destination node will reply to route requests.

• Reliable delivery: reliable delivery of data is accomplished by means of acknowledgements.

• Sleep Modes: low power sleep modes with synchronized wake up are supported, with variable sleep and wake up times.

Routing

A module within a mesh network is able to determine reliable routes using a routing algorithm and table. The routing algorithm uses a reactive method derived from AODV (Ad-hoc On-demand Distance Vector). An associative routing table is used to map a destination node address with its next hop. By sending a message to the next hop address, either the message will reach its destination or be forwarded to an intermediate node which will route the message on to its destination. A message with a Broadcast address is broadcast to all neighbors. All receiving neighbors will rebroadcast the message and eventually the message will reach all corners of the network. Packet tracking prevents a node from resending a broadcast message twice.

Route discovery process

If the source node does not have a route to the requested destination, the packet is queued to await a route discovery (RD) process. This process is also used when a route fails. A route fails when the source node uses up its network retries without ever receiving an ACK. This results in the source node initiating RD.

RD begins by the source node broadcasting a route request (RREQ). Any node that receives the RREQ that is not the ultimate destination is called an intermediate node. Intermediate nodes may either drop or forward an RREQ, depending on whether the new RREQ has a better route back to the source node. If so, information from the RREQ is saved and the RREQ is updated and broadcast. When the ultimate destination receives the RREQ, it unicasts a route reply (RREP) back to the source node along the path of the RREQ. This is done regardless of route quality and regardless of how many times an RREQ has been seen before.

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 will use for the queued packet and for subsequent packets with the same destination address.

Addressing

Every RF data packet sent over-the-air contains a Source Address and Destination Address field in its header. DigiMesh supports long 64-bit addresses. A unique 64-bit IEEE source address is assigned at the factory.

DigiMesh supports Unicast and Broadcast transmissions:

• Unicast: When transmitting in unicast communications, reliable delivery of data is accomplished using retries and acknowledgements. The number of retries is determined by the Network Retries (NR) parameter, explained in "Node parameters" chapter. RF data packets are sent up to NR + 1 times and ACKs (acknowledgements) are transmitted by the receiving node upon receipt. If a network ACK is not received within the time it would take for a packet to traverse the network twice, a retransmission occurs.

• Broadcast: Broadcast transmissions will be received and repeated by all routers in the network. Because ACKs are not used, the originating node will send the broadcast multiple times. By default a broadcast transmission is sent four times. Essentially the extra transmissions become automatic retries without acknowledgments. This will result in all nodes repeating the transmission four times as well. In order to avoid RF packet collisions, a random delay is inserted before each router relays the broadcast message. This time is specified by Network Delay Slots (NN), explained in "Node Parameters" chapter. Sending frequent broadcast transmissions can quickly reduce the available network bandwidth and as such should be used sparingly.

Maximum payloads

Depending on the addressing mode and encryption mode, a maximum data payload is defined:

	Unicast	Broadcast
Encrypted	73Bytes	73Bytes
Un-Encrypted	73Bytes	73Bytes

Figure: Maximum payloads size

Sending data

Using Waspmote Frame

WaspFrame is a class that allows the user to create data frames with a specified format. It is a very useful tool to set the payload of the packet to be sent. It is recommended to read the Waspmote Frame Programming Guide in order to understand the XBee examples:

https://development.libelium.com/data-frame-guide/

Sending function

The function send() sends a packet via XBee module.

Firstly, the destination address must be defined depending on the addressing mode:

• Define 64-bit addressing unicast mode (must specify the destination

  MAC address). For example:

{
char rx_address[] = "0013A2004030F6BC";
}

• Define broadcast mode:

{
char rx_address[] = "000000000000FFFF";
}

Finally, there are different sending function prototypes depending on the data sent. It is possible to send text messages or binary data:

• Send strings:

{
char data[] = "this_is_the_data_field";
xbeeDM.send( rx_address, data);
}

• Send Waspmote Frames:

{
xbeeDM.send( rx_address, frame.buffer, frame.length );
}

• Send array of bytes (it is mandatory to specify the length of the

  data field):

{
uint8_t data[5] = {0x00, 0x01, 0x54, 0x76, 0x23};
xbeeDM.send( rx_address, data, 5);
}

The sending function implements application-level retries. By default, up to 3 retries are done in the case the sending process fails. If a different number of maximum retries is needed, the setSendingRetries() function permits to do it. This function changes the value of the API variable. When a new send() function is called, the new maximum number of retries will be used.

Keep in mind that using a high number of retries could lead to a longer execution time of the send() function, which means more power consumption on Waspmote and less channel availability for the rest of network nodes. Probably, after 3 or 4 (failed) retries, it does not make sense to keep on trying.

Parameter range: From 0 to 10 Default: 3

Example of use:

{
xbeeDM.setSendingRetries(10);
}

Related variables:

xbeeDM._send_retries // stores the maximum number of application-level retries

Examples

Send packets in unicast mode: https://development.libelium.com/dm-02-send-packets/

Send packets in broadcast mode: https://development.libelium.com/dm-04a-send-broadcast/

Send packets using the expansion board: https://development.libelium.com/dm-06a-expansion-board-send/

Complete example, send packets in unicast mode and wait for a response: https://development.libelium.com/dm-08a-complete-example-send/

Receiving data

Receiving function

The function receivePacketTimeout() waits a period of time trying to receive a packet through the XBee module. The period of time to wait is specified in millisecond units as input when calling the function.

The Waspmote API defines the following variables to store information from the received packets:

Variable	Description
uint8_t _payload[MAX_DATA]	Buffer to store the received packet
uint16_t _length	Specifies the length of the buffer contents
uint8_t _srcMAC[8]	Specifies the source MAC address when a packet is received

When this function is called, several answers might be expected:

‘0’ → OK: The command has been executed with no errors ‘1’ → Error: timeout when receiving answer ‘2’ → Error: Frame Type is not valid ‘3’ → Error: Checksum byte is not available ‘4’ → Error: Checksum is not correct ‘5’ → Error: Error escaping character in checksum byte ‘6’ → Error: Error escaping character within payload bytes ‘7’ → Error: Buffer full. not enough memory space

Example of use:

{
uint8_t error;
error = xbeeDM.receivePacketTimeout( 10000 );
}

Related variables:

xbeeDM._payload[] // Buffer where the received packet is stored
xbeeDM._length // Length of the buffer
xbeeDM._srcMAC[0-7] // Source's MAC address

Examples

Receiving packets example: https://development.libelium.com/dm-03-receive-packets/

Receive packets in broadcast mode (the same procedure as if it was unicast mode): https://development.libelium.com/dm-04b-receive-broadcast/

Receive packets using the expansion board: https://development.libelium.com/dm-06b-expansion-board-reception/

Complete example, receive packets and send a response back to the sender: https://development.libelium.com/dm-08b-complete-example-receive/