Networking methods

Topologies

ZigBee 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

Tree: a tree network has a top node with a branch/leaf structure

• below. To reach its destination, a message travels up the tree (as

  far as necessary) and then down the tree.

Figure: Tree Topology

ZigBee is aimed at working on star or tree topology. Peer-to-Peer topologies does not have sense since only End Devices can sleep. Mesh topologies may be found interesting, but due to only End Devices can sleep, a real mesh can not be done. To work on a pure mesh topology, it is recommended to choose another protocol as DigiMesh.

ZigBee Architecture

There are some concepts that will help to understand ZigBee architecture.

ZigBee Device Objects

ZigBee Device Object (ZDO), a protocol in the ZigBee protocol stack, is responsible for overall device management, and security keys and policies. The ZDO is like a special application object that is resident on all ZigBee nodes. ZDO has its own profile, known as the ZigBee Device Profile (ZDP), where the application end points and other ZigBee nodes can access. ZDO represents the ZigBee node type of the device and has a number of initialization and communication roles.

ZDO Management Plane

This plane spans the Application Support Sub-layer (APS) and NWK layers, and allows ZDO to communicate with these layers when performing its internal tasks. It also allows the ZDO to deal with requests from applications for network access and security functions using ZDP messages.

Application Support Sub-layer (APS)

The APS is responsible of communicating with the relevant application using the endpoint information of the message. The message is passed through the Service Access point (SAP) which exists between the APS layer and each application. It is also responsible of maintaining binding tables.

Network Layer

It handles network addressing and routing invoking actions in the MAC layer. It is controlled using API functions like getOwnMac(), setOwnNetAddress() or getOwnNetAddress().

Security Plane

In addition, a Security Plane spans and interacts with the APS and NWK layers. This provides security services - for example, security key management, data stream encryption and decryption. It may use hardware functions provided in the node to perform the encode and decode functions efficiently. It is controlled using API functions like setEncryptionMode(), setLinkKey(), setNetworkKey() or setEncryptionOptions() (see chapter "Security and Data Encryption" for further information).

Application Framework

The Application Framework (AF) contains the application objects and facilitates interaction between the applications and the APS layer. An application object interacts with the APS layer through an interface known as a Service Access Point (SAP).

Service Access Points

A Service Access Point (SAP) implements a set of operations to pass information and commands between layers.

Application Endpoints

A node may have several applications running on it (several sensors) each of which is an application. These application instances on a node are said to be endpoints, where messages can originate and terminate.

In order to route messages arriving to the node to the appropriate application, each application in the node must be uniquely identified and is given an endpoint address. Endpoint addresses for user applications are numbered from 1 to 240. Therefore, to identify a particular application instance in a ZigBee network, the relevant network address and the endpoint address on the node are needed to be supplied.

Endpoint address 255 can be used to broadcast a message to all the user endpoints on a node.

Endpoint address 0 is reserved for a special application called ZDO (ZigBee Device Objects).

Application Profiles

An Application Profile is associated with a particular stack profile and addresses the needs of a specific application or market; for example, the ZigBee Alliance has defined the Home Controls-Lighting (HCL) application profile. It defines a number of devices and functions which are needed or useful for controlling domestic lighting, such as switches, dimmers, occupancy sensors and load controllers (which control the light sources).

The ZigBee stack in a particular network will use the relevant 'Stack Profile' from the ZigBee Alliance. The stack profile determines the type, shape and features of the network, and depends on the field of application, e.g. the Home Controls profile.

More specifically, in each Application Profile a number of Device Descriptions are defined, describing the types of devices the profile supports. For the HCL profile, devices such as Switch Remote Control (a switch), Light Sensor Monochromatic, Dimmer Remote Control, Occupancy Sensor, Switching Load Controller and Dimming Load Controller are available. Each device in an Application Profile has a Device Identifier associated with it.

As well as defining the device types supported, the Application Profile also specifies the information that a device can generate as output and can use as input, together with the format this information takes.

The individual pieces of information are called attributes, and their possible values and format or type are defined as part of the Device Descriptions in the profile. Attributes are grouped together into clusters for the device, which can be either inputs or outputs.

Attributes

Each data item that passes between devices of a ZigBee network is called an attribute. Each attribute has its own unique identifier. For example, a switch device can have an attribute with identifier 'OnOff' whose value represents the action to be performed: On (0xFF), Off (0x00), Toggle (0xF0).

Clusters

A number of attributes are grouped into a cluster, where each cluster has its own unique identifier.

For example, for an HCL Switch Remote Control (SRC) device, there is a cluster with the identifier 'OnOffSRC' containing the attribute OnOff. Clusters may be mandatory or optional for a device to support.

An Application Profile can have several associated clusters. For example, the Home Controls-Lighting (HCL) profile includes the clusters 'OnOffSRC' and 'ProgramSRC' for an SRC device.

The Application Profile defines which clusters are mandatory and which clusters are optional for the device. The clusters supported by a device determine the other devices to which it can communicate. For example, for two devices operating together in temperature monitoring and control, both of them must support compatible clusters concerned with temperature. The sensor device must have an output cluster containing the monitored temperature, and the controller must support an input cluster which can use a temperature to make control decisions.

Binding

At a high level, binding is the process of establishing a relationship between nodes that can communicate in a meaningful way, for example, linking switches with lights. It therefore determines the overall functionality of the network.

The information is exchanged as clusters - in order to bound two applications, they must have compatible clusters. For example, for two applications in different nodes for temperature control, one must be able to generate an output cluster related to temperature, and the other must be able to consume it as an input cluster. The binding between two applications is specified by:

• The source network address and endpoint of the application where the cluster is generated

• The destination network address and endpoint of the receiving application

• The cluster ID of the cluster being sent between them

Bindings are stored in a binding table. This lists the cluster IDs, the network addresses and application endpoints for each association. The types of binding that can be achieved are one-to-one, one-to-many, many-to-one and many-to-many:

• One-to-one: A binding in which an endpoint is bound to one (and only one) other endpoint.

• One-to-many: A binding in which a source endpoint is bound to more than one destination endpoint.

• Many-to-one: A binding in which more than one source endpoint is bound to a single destination endpoint.

• Many-to-many : A binding in which more than one source endpoint is bound to more than one destination endpoint.

Bindings (the binding entries table) can be stored either on the network Coordinator (indirect binding) or locally on the node generating the source output cluster (direct binding).

Waspmote Application Level

The concepts explained above are used in a special kind of transmission called 'Application Level Addressing'. This kind of transmission is used to send data between two devices using endpoints and clusters.

In order to send data, this transmission uses a packet which is a bit different from the usual .It is explained with an example in chapter 8.6, showing how to include information in the sent packet as Destination Endpoint, Cluster and Profiles.

To receive a packet of this type, an option parameter should be set to notify the module of the incoming special packet. To enable this option:

Example of use:

{
    xbeeZB.setAPIoptions(1); // Set explicit frame used in Application Level Addressing
}

ZigBee Addressing

ZigBee supports device addressing and application layer addressing. Device addressing specifies the destination address of the device a packet is destined to. Application layer addressing indicates a particular application recipient, known as a ZigBee endpoint, along with a message type field called a Cluster ID.

Device Addressing

ZigBee protocol specifies two address types: 16-bit and 64-bit addresses.

• 16-bit Network Address : A 16-bit Network Address is assigned to a node when joining a network. The network address is unique to each node in the network, but it may change. ZigBee requires data to be sent to the 16-bit network address of the destination device. This requires the 16-bit network address to be discovered before transmitting the data, executing a process called 'Address Discovery'.

• 64-bit Address : Each node contains a unique 64-bit address. The 64-bit address uniquely identifies a node and is therefore permanent. It is assigned by the manufacturer and it can not be changed.

Application Layer Addressing

The ZigBee application layers define endpoints and cluster identifiers (cluster IDs) that are used to address individual services or applications on a device. An endpoint is a task or application that runs on a ZigBee device, similar to a TCP port. Each ZigBee device may support one or more endpoints. Cluster IDs define a particular function or action on a device. For example: in the ZigBee home controls lighting profile, Cluster IDs would include actions such as "TurnLightOn", "TurnLightOff", "DimLight", etc.

Connections

All data packets are addressed using both device and application layer addressing fields. Data can be sent as a broadcast, or unicast transmission.

Broadcast

Broadcast transmissions within the ZigBee protocol are intended to be propagated throughout the entire network such that all nodes receive the transmission. To accomplish this, all devices that receive a broadcast transmission will retransmit the packet 3 times.

Each node that transmits the broadcast will also create an entry in a local broadcast transmission table. This entry is used to keep track of each received broadcast packet to ensure the packets are not endlessly transmitted. For each broadcast transmission, the ZigBee stack must reserve buffer space for a copy of the data packet. Since broadcast transmissions are retransmitted by each device in the network, broadcast messages should be used sparingly.

Broadcast transmissions are sent using a 64-bit address of 0x000000000000FFFF. Any RF module in the PAN will accept a packet that contains a broadcast address. When configured to operate in Broadcast Mode, receiving modules do not send ACKs (Acknowledgments).

See examples in chapter "Connectivity" → Sending data for further information.

Unicast

Unicast ZigBee transmissions are always addressed to the fact that 16-bit address of the destination device. However, only the 64-bit address of a device is permanent due to the 16-bit address can change. Therefore, ZigBee devices may employ network address discovery to identify the current 16-bit address that corresponds to a known 64-bit address, and route discovery to establish a route.

See examples in chapter 8.6 for further information.

• Network Address Discovery Data transmissions are always sent to the 16-bit network address of the destination device. However, since the 64-bit address is unique to each device and is generally known, ZigBee devices must discover the network address that was assigned to a particular device when it joined the PAN before they can transmit data. To do this, the device initiating a transmission sends a broadcast network address discovery transmission throughout the network. This packet contains the 64-bit address of the device the initiator needs to send data to. Devices that receive this broadcast transmission check to see if their 64-bit address matches the 64-bit address contained in the broadcast transmission. If the addresses match, the device sends a response packet back to the initiator, supplying the network address of the device with the matching 64-bit address. When this response is received, the initiator can then transmit data.

• Route Discovery ZigBee employs mesh routing to establish a route between the source device and the destination. Mesh routing allows data packets to traverse multiple nodes (hops) in a network to route data from the source to its destination. Routers and coordinators can participate in establishing routes between source and destination devices using a process called route discovery. The Route discovery process is based on the AODV (Ad-hoc On demand Distance Vector routing) protocol.

• Retries and ACKs ZigBee includes acknowledgment packets at both the Mac and Application Support (APS) layers. When data is transmitted to a remote device, it may traverse multiple hops to reach the destination. As data is transmitted from one node to its neighbour, an acknowledgment packet (ACK) is transmitted in the opposite direction to indicate that the transmission was successfully received. If the ACK is not received, the transmitting device will retransmit the data up to 4 times. This ACK is called the Mac layer acknowledgment. In addition, the device that originated the transmission expects to receive an acknowledgment packet (ACK) from the destination device. This ACK will traverse the same path that the data traversed, but in the opposite direction. If the originator fails to receive this ACK, it will retransmit the data, up to 2 times until an ACK is received. This ACK is called the ZigBee APS layer acknowledgment.

Many to one

Since ZigBee unicast transmissions may require some combination of broadcast network address discovery and/or route discovery, having large numbers of devices unicasting data to a single gateway or collector device may not be the best solution for large networks.

To work around this potential problem, ZigBee includes provisions to support many-to-one transmissions, where many devices in a network can all transmit data to a central gateway or collector device without causing a flood of route discoveries. To accomplish this, the collector device sends a periodic broadcast transmission identifying itself as a collector device. All other devices that receive this broadcast transmission create a reverse routing table entry back to the collector. When the remote devices transmit data to the collector, they first transmit a route record frame (that records the entire route from the remote to the collector) before transmitting the data. The route record frame provides the collector with the entire route to each remote it receives data from. The collector can use the information in the route record frames to store return routes. This process effectively establishes routes between the collector and all devices in the network using a single broadcast transmission instead of many route discoveries.

Parameters involved

There are some parameters involved in these explained connections:

• Maximum Unicast Hops It sets the maximum unicast hops limit and the unicast timeout. The timeout is computed as: (50*NH)+100ms. The default value of 0x1E (1,6seconds) is enough to traverse around 8 hops.

Example of use:

{
    xbeeZB.setMaxUnicastHops(0x03); // Set max unicast hops limit
    xbeeZB.getMaxUnicastHops(); // Get max unicast hops limit
}

Related variables:

xbeeZB.maxUnicastHops → stores the max unicast hops limit

• Maximum Broadcast Hops It sets the maximum number of hops for each broadcast data transmission.

Example of use:

{
    xbeeZB.setMaxBroadcastHops(0x10); // Set max broadcast hops limit
    xbeeZB.getMaxBroadcastHops(); // Get max broadcast hops limit
}

Related variables:

xbeeZB.maxBroadcastHops → stores the max broadcast hops limit

• Aggregate Routing Notification (Many to one) Time between consecutive aggregate route broadcast messages. Using this parameter, many to one transmissions will be enabled.

Example of use:

{
    xbeeZB.setAggregateNotification(0x20); // Set time between aggregate messages
    xbeeZB.getAggregateNotification (); // Get time between aggregate messages
}

Related variables:

xbeeZB.aggregateNotification → stores the time between consecutive messages

Maximum payloads

The maximum payload depends on the following settings:

• Message type (broadcast or unicast)

• AP setting

• APS encryption option

• Source-routing

Broadcast messages, which cannot be encrypted with APS or fragmented have a maximum payload of 84 Bytes. Unicast messages where AP is 0, also have a maximum payload of 84 Bytes. Unicast messages where AP is non-zero have a maximum payload of 255 Bytes.

The maximum payload is complicated to estimate for aggregator source-routing. To reduce the

maximum payload, when an aggregator sends a source-routed message it embeds the route into the

message as overhead, or into each fragment of the message, if fragmentation is necessary. If you use

APS encryption, it reduces the number further.

The following table shows the aggregator source-routed payload maximums as a function of hops and APS encryption:

Hops	Maximum encrypted payload	Maximum unencrypted payload
1	255 Bytes	255 Bytes
2	255 Bytes	255 Bytes
3	255 Bytes	255 Bytes
4	255 Bytes	255 Bytes
5	255 Bytes	255 Bytes
6	215 Bytes	255 Bytes
7	205 Bytes	250 Bytes
8	195 Btyes	240 Bytes
9	185 Btyes	230 Bytes
10	175 Bytes	220 Bytes
11	165 Bytes	210 Bytes
12	155 Bytes	200 Bytes
13	145 Bytes	190 Bytes
14	135 Bytes	180 Bytes
15	125 Bytes	170 Bytes
16	115 Bytes	160 Bytes
17	105 Bytes	150 Bytes
18	95 Bytes	140 Bytes
19	85 Bytes	130 Bytes
20	75 Bytes	120 Bytes
21	65 Bytes	110 Bytes
22	55 Bytes	100 Bytes
23	45 Bytes	90 Bytes
24	35 Bytes	80 Bytes
25	25 Bytes	70 Bytes

Figure: Maximum Payloads Size

If the maximum payload is not known when operating in an application, the getPayloadBytes() function stores the maximum payload size into the variable maxPayloadBytes.

Example of use

{
    xbeeZB.getPayloadBytes();
}

Related variables:

xbeeZB.maxPayloadBytes[0-1] → stores the maximum payload is available at the moment

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/waspmote/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";
    xbeeZB.send( rx_address, data);
}

• Send Waspmote Frames:

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

{
    xbeeZB.setSendingRetries(10);
}

Related variables:

xbeeZB._send_retries → stores the maximum number of application-level retries

Examples

• Send packets in unicast mode:

https://development.libelium.com/waspmote/zb-03-send-packets

• Send packets in broadcast mode:

https://development.libelium.com/waspmote/zb-05a-send-broadcast

• Send packets using the expansion board:

https://development.libelium.com/waspmote/zb-07a-expansion-board-send

• Complete example, send packets in unicast mode and wait for a response:

https://development.libelium.com/waspmote/zb-09a-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 = xbeeZB.receivePacketTimeout( 10000 );
}

Related variables:

xbeeZB._payload[] → Buffer where the received packet is stored

xbeeZB._length → Length of the buffer

xbeeZB._srcMAC[0-7] → Source\'s MAC address

Examples

• Receiving packets example:

https://development.libelium.com/waspmote/zb-04-receive-packets

• Receive packets in broadcast mode (the same procedure as if it was unicast mode):

https://development.libelium.com/waspmote/zb-05b-receive-broadcast

• Receive packets using the expansion board:

https://development.libelium.com/waspmote/zb-07b-expansion-board-reception

• Complete example, receive packets and send a response back to the sender:

https://development.libelium.com/waspmote/zb-09b-complete-example-receive