Networking methods

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 802.15.4, every node in a network must have the same:

• PAN ID

• Channel

• Encryption configuration

Topology

802.15.4 provides a star topology to create a network: it 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

Addressing

Every RF data packet sent wireless contains a Source Address and a Destination Address fields in its header. The RF module conforms to the 802.15.4 specification and supports both short 16-bit addresses and long 64-bit addresses. A unique 64-bit IEEE source address is assigned at the factory. Short addressing must be configured manually.

IEEE 802.15.4 supports unicast and broadcast transmissions:

• Unicast: The unicast mode is the only one that supports acknowledgements (ACKs). When a packet is sent using unicast mode, the receiving module sends an affirmative response to the sending module. If the sending module does not receive the ACK, it will re-send the packet up to ten times or until the ACK is received. Both 16-bit addresses and 64-bit addresses are supported in unicast mode.

  • Short 16-bit addresses: To use 16-bit addresses, the transmitter should set the receiver network address into the transmitted packet.

  • Long 64-bit addresses: To use 64-bit addresses, the transmitter should set the receiver MAC address into the transmitted packet.

• Broadcast: Used to transmit all modules in the same network. Any RF module within range will accept a packet that contains a broadcast address. When a packet is sent using broadcast mode, receiving modules do not send ACKs. All broadcast packets are automatically transmitted four times to ensure it is received. To send a broadcast message, the receiver address must be set to 0x000000000000FFFF.

Maximum payloads

Depends on the addressing mode, a maximum data payload is defined:

	@16bit Unicast	@64bit Unicast	Broadcast
Encrypted	98Bytes	94Bytes	95Bytes
Un-Encrypted	100Bytes	100Bytes	100Bytes

Figure: Maximum payload 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 the 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 16-bit addressing unicast mode (the receiver must be set with

  this configuration). For example:

{
char rx_address[] = "1234";
}

• 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";
xbee802.send( rx_address, data);
}

• Send Waspmote Frames:

{
xbee802.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};
xbee802.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:

{
xbee802.setSendingRetries(10);
}

Related variables:

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

Examples

Send packets in unicast mode. Set 64-bit destination address: https://development.libelium.com/802-02-send-packets/

Send packets in unicast mode. Set 16-bit destination address: https://development.libelium.com/802-04a-send-unicast-16b-address/

Send packets in broadcast mode: https://development.libelium.com/802-06a-send-broadcast/

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

Complete example, send packets in unicast 64-bit addresing mode and wait for a response: https://development.libelium.com/802-11a-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
uint8_t _srcNA[2]	Specifies the source network 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 = xbee802.receivePacketTimeout( 10000 );
}

Related variables:

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

Examples

Receive packets in unicast mode: https://development.libelium.com/802-03-receive-packets/

Receive packets in unicast mode. Get 16-bit source address: https://development.libelium.com/802-04b-receive-unicast-16b-address/

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

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

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

802.15.4 compliance

The Waspmote XBee transceiver is IEEE 802.15.4 compliant when the 'Mac Mode' is set to a value = 2. For other values, this parameter adds an extra header which let some new features to 802.15.4 protocol.

These features are:

• Node Discover: It performs a scan in the network and reports other nodes working on the network.

• Destination Node: It performs a scan in the network to look for a specific node.

• Duplicate Detection: 802.15.4 does not detect duplicate packets. Using Digi extra header, this problem is solved, discarding automatically the duplicate packets. If Digi header is not enabled, the application level will have to deal with this problem.

These features and extra header are enabled by default. Possible values for this parameter are:

• 0: Digi Mode. 802.15.4 header + Digi header. It enables features as Discover Node and Destination Node.

• 1: 802.15.4 without ACKs. It doesn't support DN and ND features. It is 802.15.4 protocol without generating ACKs when a packet is received.

• 2: 802.15.4 with ACKs. It doesn't support DN and ND features. It is the standard 802.15.4 protocol.

• 3: Digi Mode without ACKs. 802.15.4 header + Digi header. It enables features as Discover Node and Destination Node. It doesn't generate ACKs when a packet is received.

Example of use:

{
xbee802.setMacMode(2);
xbee802.getMacMode();
}

Related variables:

xbee802.macMode // stores the Mac Mode selected