Digi XBee Zigbee Mesh Kit User Manual

Download

Page 1

XBee® Zigbee® Mesh Kit

Radio Frequency (RF) Module

User Guide

Page 2

Revision history—90001942-13

Revision Date Description

B January

2016

C June

2016

D August

2017

E February

2018

Updated the documentation to include support for S2C SMT module.

Updated the document with new Digi branding.

Added information clarifying that the S2D module is international. Added a graphic of the Worldwide kit and delineated the difference in the Kit Contents table.

Added information for XBee3 product line and a few minor edits.

Trademarks and copyright

Digi, Digi International, and the Digi logo are trademarks or registered trademarks in the United States and other countries worldwide. All other trademarks mentioned in this document are the property of their respective owners.

Disclaimers

Information in this document is subject to change without notice and does not represent a commitment on the part of Digi International. Digi provides this document “as is,” without warranty of any kind, expressed or implied, including, but not limited to, the implied warranties of fitness or merchantability for a particular purpose. Digi may make improvements and/or changes in this manual or in the product(s) and/or the program(s) described in this manual at any time.

Warranty

To view product warranty information, go to the following website:

www.digi.com/howtobuy/terms

Customer support

Gather support information: Before contacting Digi technical support for help, gather the following

information:

Product name and model

Product serial number (s)

Firmware version

Operating system/browser (if applicable)

Logs (from time of reported issue)

Trace (if possible)

Description of issue

Steps to reproduce

XBee® Zigbee® Mesh Kit

Page 3

Contact Digi technical support: Digi offers multiple technical support plans and service packages.

Feedback

To provide feedback on this document, email your comments to

Include the document title and part number (XBee® Zigbee® Mesh Kit, 90001942-13 D) in the subject line of your email.

techcomm@digi.com

XBee® Zigbee® Mesh Kit

Page 4

Contents

Change the firmware protocol 12

Kit contents

Introduction to XBee modules

Zigbee in a nutshell

Mesh networking 17 Zigbee stack layers 18 Device types 19

Get started with XBee Zigbee

Assemble the hardware 21

Plug in the XBee module 21

How to unplug an XBee device 22 Download and install XCTU 23 Example: basic communication 23

Step 1:Requirements 23

Step 2:Connect the components 23

Step 3: Add the XBee modules to XCTU 24

Step 4: Configure the XBee modules 25

Step 5: Check the network 27

Step 6: Send messages 27

How XBee devices work

How XBee devices communicate 31 Wireless communication 31

Addressing 31

PAN Addresses 32

Channels 33 Serial communication 33

Operating modes 34

Comparison of transparent and API modes 35

XBee® Zigbee® Mesh Kit

Page 5

XBee transparent mode

XBee transparent mode in detail 38

What have you learned? 38

Extend the basic communication example 39 Command mode 39

AT commands 39

Use AT commands 40

XBee API mode

API mode in detail 43

Advantages of API mode 43 API frame structure 45

Start delimiter 45

Length 45

Frame data 45

Checksum 46 Supported frames 48 Frame examples 49 Operating mode configuration 54

API escaped operating mode (API 2) 56 XBee frame exchange 58

AT Command: configure a local XBee device 58

Transmit Request/Receive Packet: Transmit and receive wireless data 58

Remote AT Command: Remotely configure an XBee module 59

Source routing: Create and obtain the route of a packet 60

Example: Configure your local XBee module 61

Example:Transmit and receive data 64

Libraries 69

Zigbee Mesh Network Setup

Configure the device type of an XBee module 71 Startup operations 71

Coordinator 71

Router 72

End device 72 Explore the network 73 Section summary 73

Wireless data transmission

Transmission methods 74

Broadcast transmission 74

Unicast transmission 75 Example: transmit data 76

Step 1: Requirements 77

Step 2:Connect the components 77

Step 3: Configure the Xbee modules 78

Step 4: Create a Java project 78

Step 5:Link libraries to the project 79

Step 6:Add the source code to the project 80

XBee® Zigbee® Mesh Kit

Page 6

Step 7:Set the port names and launch applications 81

Step 8:Transmit data over the network 81

Step 9:Section summary of wireless data transmission 82

Step 10:Do more with wireless data transmission 82

Low power and battery life

Low power devices and battery life 84

A real world scenario 84

Design considerations for applications using sleep mode 84 Sleep modes 84 Pin sleep 85 Cyclic sleep 86 Example: enable sleep mode 86

Step 1:Requirements 86

Step 2: Connect the components 87

Step 3:Configure the XBee Modules 88

Step 4: Sleep 92

Step 5: What have you learned? 94

Step 6: Extend the example 94

Inputs and outputs

XBee I/O pins 96 Sensors 97

Setting pins for digital and analog sensors 98 Actuators 98 Set pins for digital and analog actuators 98 How XBee devices get sensor data 98

How to configure a pin as an input 99

How to obtain data from a sensor 99 Example: receive digital data 100

Step 1:Requirements 101

Step 2:Connect the components 101

Step 3:Configure the XBee modules 102

Step 4:Create a Java project 106

Step 5:Link libraries to the project 106

Step 6: Add the source code to the project 107

Step 7:Set the port name and launch the application 108

Step 8:Section summary of receiving digital data 109

Step 9:Do more with receiving digital data 109 Lab: receive analog data 110

Step 1: Requirements 110

Step 2:Connect the components 110

Step 3:Configure the XBee modules 112

Step 4: Create a Java project 116

Step 5:Link libraries to the project 116

Step 6:Add the source code to the project 117

Step 7:Set the port name and launch the application 118

Step 8:Section summary of receiving analog data 119

Step 9:Do more with receiving analog data 119 How XBee modules control devices 119

How to configure a pin as an output 120

How to send actuations 120

XBee® Zigbee® Mesh Kit

Page 7

Example: send digital actuations 121

Step 1:Requirements 121

Step 2:Connect the components 121

Step 3:Configure the XBee modules 121

Step 4:Create a Java project 122

Step 5:Link libraries to the project 123

Step 6:Add the source code to the project 124

Step 7:Set the port name and launch the application 125

Step 8:Section summary of sending digital actuations 125

Step 9: Do more with sending digital actuations 125

Security and encryption

Zigbee security model 126

Network layer security 127

APS layer security 127

Network and APS layer encryption 128

Form or join a secure network 128

Security on the XBee

Enable security 130 Set the network security key 130 Set the APS trust center link key 130 Enable APS encryption 130 Use a trust center 131

How to update the network key with a trust center. 131

How to update the network key without a trust center. 131

Example: basic (but secure) communication

Understanding the example 133

Signal strength and radio frequency range

Distance and obstacles 135 Factors affecting wireless communication 136 Signal strength and the RSSI pin 137

Is RSSI the best indication of link quality? 139 Range test 140 Example: perform a range test 142

Step 1:Requirements 143

Step 2:Connect the components 143

Step 3:Configure the XBee Zigbee modules 143

Step 4:Perform a range test 144

Step 5:Section summary of signal strength 145

Zigbee communication in depth

Zigbee Application Framework 147

Application profiles 148

Clusters 151

XBee® Zigbee® Mesh Kit

Page 8

Endpoints 152

Binding 154

Node descriptors 157

Zigbee Cluster Library 158 Zigbee Device Object (ZDO) 158 Explicit Addressing frames 160

Explicit Addressing Command frame 160

Explicit Rx Indicator frame 161

Data payload format 163

Receive Zigbee commands and responses 164 Examples: explicit data and ZDO 164

Example: obtain the neighbor table using the XBee Java Library 165

Example: obtain the neighbor table using the XBee Java Library 170

Large networks routing

Many-to-one routing 178

Enabling many-to-one routing 179

Disabling many-to-one routing 180 Source routing 180

Using source routing 181

Radio firmware

Firmware identification 184 Update radio firmware 184 Download new firmware 185

Troubleshooting

XCTU 186 Wireless data transmission 187 Enable sleep mode 188 XBee Java library 188 Receive digital data 190 Receive analog data 190 Send digital actuations 191 Range test 191

Check cables 192

Check that the XBee module is fully seated in the XBee Grove Development Board 192

Check the XBee module orientation 192

Check that the XBee modules are in the same network 192

Restore default settings 192

Check cables 192

Check that the XBee module is fully seated in the XBee Grove Development Board 192

Check the XBee module orientation 192

Additional resources

XBee buying guide 195

Hardware footprint 195

XBee antennas 196

XBee vs. XBee-PRO 197

XBee® Zigbee® Mesh Kit

Page 9

Frequency 197

Radio communication protocols 198 Where to buy XBee devices 200

Find products from Digi and Digi distributors 200

Find Digi products through resellers 201 XCTU walkthrough 201

XCTU overview 201

Application working modes 204

Add a module 204

Read settings 205

Change settings 206

Save settings 206 Real projects with XBee modules 206

Community 207

Industrial solutions 207 Related products 208

XBee Grove Development Board

Overview

Development board variants 211 XBee THT Grove Development Board 211 XBee SMT Grove Development Board 211 Mechanical 212

XBee THT Grove Development Board variant 212

XBee SMT Grove Development Board variant 212 Power supply 213

XBee THT Grove Development Board power supply 213

XBee SMT Grove Development Board power supply 213

Power supply battery connector 214 XBee connector 214

XBee THT Grove Development Board XBee connector 215

XBee SMT Grove Development Board XBee connector 217 USB 219

XBee THT Grove Development Board USB 219

XBee SMT Grove Development Board USB 220

USB VBUS line 220 Reset button 221

XBee THT Grove Development Board Reset button 221

XBee SMT Grove Development Board Reset button 221 Commissioning button 222

XBee THT Grove Development Board Commissioning button 222

XBee SMT Grove Development Board Commissioning button 222

Commissioning pin and Grove AD0 connection 223 Association led 224

XBee THT Grove Development Board Association LED 224

XBee SMT Grove Development Board Association LED 224 RSSI led 225

XBee THT Grove Development Board RSSI LED 225

XBee SMT Grove Development Board RSSI LED 225

PWM0 RSSI configuration 226 User LED and User button 227

XBee THT Grove Development Board User LED and User button 227

XBee® Zigbee® Mesh Kit

Page 10

XBee SMT Grove Development Board User LED and User button 227

User LED and User Button connection to DIO4 227 On/sleep LED 229

XBee THT Grove Development Board On/Sleep LED 229

XBee SMT Grove Development Board On/Sleep LED 229

On/sleep LED connection to DIO9 230 Potentiometer 231

XBee THT Grove Development Board Potentiometer 231

XBee SMT Grove Development Board Potentiometer 232 I2C 233

XBee THT Grove Development Board I2C bus 233

XBee SMT Grove Development Board I2C bus 233

XBee/XBee-PRO connection to Grove sensor 233

Grove I2C connector pinout 234 Grove Connectors 235

THT board Grove connectors pinout 236

SMT board Grove connectors pinout 238 Loopback jumper 240

XBee THT Grove Development Board Loopback jumper 240

XBee SMT Grove Development Board Loopback jumper 240

Schematic and Gerber files

XBee THT Grove Development Board schematic 241

Gerber files 241 XBee SMT Grove Development Board schematic 242

Gerber files 242

XBee® Zigbee® Mesh Kit

Page 11

XBee Zigbee Mesh Kit User Guide

Digi’s XBee Zigbee Mesh Kit is a great way to learn how to use XBee RF modules for device connectivity and mesh networking. Starting with very simple examples, we provide step-by-step guidance as you assemble the kit components to create reliable device communications, working control systems, and sensing networks with incredible battery life and robust security.

Mesh networking is a powerful way to route data. Range is extended by allowing data to hop from node to node, and reliability is increased by “self healing,” the ability to create alternate paths when one node fails or a connection is lost. Zigbee is one of the most popular mesh networking protocols, specifically designed for low-data rate and low-power applications. The main advantage of Zigbee is that it is an open standard, so any manufacturer's device that fully supports it can communicate with any other company's Zigbee device.

The kit is designed for anyone getting started in the world of Zigbee. Hardware and software engineers, corporate technologists, or educators and students can quickly create wireless mesh networks.

Each point of this guide explains a basic topic related to XBees through a short theoretical introduction and examples that put into practice the concepts you have learned. The topics are arranged according to their complexity, from the most basic to the more powerful features. We recommend that new users work through them in the order they appear.

XBee® Zigbee® Mesh Kit

Page 12

This guide provides step by step examples, and some use the Java programming language. These examples are designed to be easy for anyone to use, and those with some programming background can extend them.

Change the firmware protocol

Although the kit comes pre-loaded with Zigbee firmware, you can change the RF protocol used by the XBee3. To change protocols, use the Update firmware feature in XCTU and select the firmware. See the XCTU User Guide.

The XBee3 hardware can run any of the following protocols:

n DigiMesh

n Zigbee

n 802.15.4

For information on each of these firmwares and instructions for how to get started, see the user guide for each protocol:

n DigiMesh

n Zigbee

n 802.15.4

XBee® Zigbee® Mesh Kit

Page 13

Kit contents

Verify that your kit contains the following components. Then get started by learning about the XBee modules.

Note Some versions of the S2C kit contain three XBee Through-hole technology (THT) Grove

Development boards and three XBee THT modules instead of two THT and one Surface-mount technology (SMT).

S2C Zigbee Kit Qty.

XBee3 Zigbee Kit Qty. Part

XBee Grove Development Board

XBee® Zigbee® Mesh Kit

Page 14

Kit contents

S2C Zigbee Kit Qty.

2 - XBee Zigbee THT modules (S2C)

- 3 XBee3 Zigbee SMT module

XBee3 Zigbee Kit Qty. Part

XBee Zigbee SMT module (S2C)

- 3 Antenna - 2.4 GHz, half-wave

XBee® Zigbee® Mesh Kit

Micro USB cables

dipole, 2.1 dBi, U.FL female, articulating

Page 15

Kit contents

S2C Zigbee Kit Qty.

XBee3 Zigbee Kit Qty. Part

XBee stickers

XBee Meshkit modules come in two hardware footprints: through-hole and surface mount.

n Through-hole technology (THT) XBee modules include the 20-pin socket and require holes for

mounting the component on the printed circuit board (PCB), although it is common for the carrier board to contain a female socket.

n Surface-mount technology (SMT) XBee modules include 37 pads and are placed directly on

the PCB. They do not require holes or sockets for mounting the component.

XBee® Zigbee® Mesh Kit

Page 16

Introduction to XBee modules

XBee modules are small radio frequency (RF)devices that transmit and receive data over the air using radio signals. Wireless capability is essential whenever you want to place sensors where no cables can be installed, or where such tethering is undesirable.

XBee devices are highly configurable and support multiple protocols, which lets you choose the right technology for your application—whether you want to set up a pair of radios to swap data or design a large mesh network with multiple devices.

Here are some of the ways you can use XBee devices:

n Controlling a robot remotely or creating wearable electronics for people, pets, or wildlife,

without hindering movement.

n Making a building smarter and more responsive to human interaction.

n Using XBee technology in industrial solutions. For example, XBee devices are used as sensors

to monitor industrial tanks for liquid levels, temperature, and pressure, and to monitor and control complex machines such as wind turbines.

XBee® Zigbee® Mesh Kit

Page 17

Zigbee in a nutshell

Zigbee is an open global standard for low-power, low-cost, low-data-rate, wireless mesh networking based on the IEEE 802.15.4 standard. It represents a network layer above the 802.15.4 layers to support advanced mesh routing capabilities. The Zigbee specification is developed by a growing consortium of companies that make up the Zigbee Alliance. The Alliance is made up of over 300 members, including semiconductor, module, stack, and software developers.

Through its mesh and routing capabilities, Zigbee allows the transmission of data over long distances by passing the data through a mesh network of intermediate nodes to reach more distant nodes. Transmission distance ranges from 1200 to 3200 line-of-sight meters (5280 to 10560 feet). Zigbee supports multiple network topologies such as point-to-point, point-to-multipoint, and mesh networks and allows up to 65,000 nodes per network.

Zigbee is designed to provide the following features:

n High reliability

n Low power consumption

n Low cost

n High security

n Simple protocol, global implementation

Mesh networking

A mesh network is a topology in which each node in the network is connected to other nodes around it. Each node cooperates in the transmission of information. Mesh networking provides three important benefits:

n Routing. With this technique, the message is propagated along a path by hopping from node to

node until it reaches its final destination.

n Ad-hoc network creation. This is an automated process that creates an entire network of

nodes on the fly, without any human intervention.

n Self-healing. This process automatically figures out if one or more nodes on the network is

missing and reconfigures the network to repair any broken routes.

XBee® Zigbee® Mesh Kit

Page 18

Zigbee in a nutshell Zigbee stack layers

With mesh networking, the distance between two nodes does not matter as long as there are enough nodes in between to pass the message along. When one node wants to communicate with another, the network automatically calculates the best path.

A mesh network is also reliable and offers redundancy. If a node can no longer operate, for example because it has been removed from the network or because a barrier blocks its ability to communicate, the rest of the nodes can still communicate with each other, either directly or through intermediate nodes.

Note Mesh networks use more bandwidth for administration and therefore have less available for

payloads. They can also be more complex to configure and debug in some cases.

Zigbee stack layers

Most network protocols use the concept of layers to separate different components and functions into independent modules that can be assembled in different ways.

Zigbee is built on the Physical (PHY) layer and Medium Access Control (MAC) sub-layer defined in the IEEE 802.15.4 standard. These layers handle low-level network operations such as addressing and message transmission/reception.

The Zigbee specification defines the Network (NWK) layer and the framework for the application layer. The Network layer takes care of the network structure, routing, and security. The application layer framework consists of the Application Support sub-layer (APS), the Zigbee Device Objects (ZDO) and user-defined applications that give the device its specific functionality.

XBee® Zigbee® Mesh Kit

Page 19

Zigbee in a nutshell Device types

For more information about the Zigbee stack layers, read the Zigbee communication in depth section.

Device types

Zigbee defines three different device types: coordinator, router, and end device.

Coordinator

Zigbee networks always have a single coordinator device. This device:

n Starts the network, selecting the channel and PAN ID.

n Distributes addresses, allowing routers and end devices to join the network. Assists in routing

data.

n Buffers wireless data packets for sleeping end device children.

n Manages the other functions that define the network, secure it, and keep it healthy. This

device cannot sleep and must be powered on at all times.

Router

A router is a full-featured Zigbee node. This device:

n Can join existing networks and send, receive, and route information. Routing involves acting as

a messenger for communications between other devices that are too far apart to convey information on their own.

n Can buffer wireless data packets for sleeping end device children. Can allow other routers and

end devices to join the network.

XBee® Zigbee® Mesh Kit

Page 20

Zigbee in a nutshell Device types

n Cannot sleep and must be powered on at all times.

n May have multiple router devices in a network.

End device

An end device is essentially a reduced version of a router. This device:

n Can join existing networks and send and receive information, but cannot act as messenger

between any other devices.

n Cannot allow other devices to join the network.

n Uses less expensive hardware and can power itself down intermittently, saving energy by

temporarily entering a non responsive sleep mode.

n Always needs a router or the coordinator to be its parent device. The parent helps end devices

join the network, and stores messages for them when they are asleep.

Zigbee networks may have any number of end devices. In fact, a network can be composed of one coordinator, multiple end devices, and zero routers.

An example of such a network is shown in the following diagram:

Note Each Zigbee network must be formed by one, and only one, coordinator and at least one other

device (router or end device).

XBee® Zigbee® Mesh Kit

Page 21

Get started with XBee Zigbee

Use the following steps to set up your environment and assemble the hardware to perform your first XBee application.

Assemble the hardware

This guide walks you through the steps required to assemble and disassemble the hardware components of your kit.

n Plug in the XBee module

n How to unplug an XBee device

The kit includes several XBee Grove Development Boards. For more information about this hardware, see the XBee Grove Development Board documentation.

Plug in the XBee module

This kit includes several XBee Grove Development Boards. For more information about this hardware, visit the XBee Grove Development Board documentation.

Follow these steps to connect the XBee devices to the boards included in the kit:

1. Plug one XBee Zigbee Mesh Kit module into the XBee Grove Development Board.

XBee THT modules have a flat edge and a more angular/diagonal edge. Match that footprint with the white lines on your board and carefully insert it, taking care not to bend any of the pins.

XBee® Zigbee® Mesh Kit

Make sure the board is NOT powered (either by the micro USB or a battery) when you plug in the XBee module.

Page 22

Get started with XBee Zigbee Assemble the hardware

For XBee SMT modules, align all XBee pins with the spring header and carefully push the module until it is hooked to the board.

2. Once the XBee module is plugged into the board (and not before), connect the board to your

computer using the micro USB cables provided.

3. Ensure the loopback jumper is in the UART position.

4. Connect an antenna (if applicable).

How to unplug an XBee device

To disconnect your XBee device from the XBee Grove Development board:

1. Disconnect the micro USB cable (or the battery) from the board so it is not powered.

2. Remove the XBee device from the board socket, taking care not to bend any of the pins.

CAUTION! Make sure the board is not powered when you remove the XBee device.

XBee® Zigbee® Mesh Kit

Page 23

Get started with XBee Zigbee Download and install XCTU

Download and install XCTU

XBee Configuration and Test Utility (XCTU) is a multi-platform program that enables users to interact with Digi radio frequency (RF) devices through a graphical interface. The application includes built-in tools that make it easy to set up, configure, and test Digi RF devices.

For instructions on downloading and using XCTU, see the XCTU User Guide.

Once you have downloaded XCTU, run the installer and follow the steps to finish the installation process.

After you load XCTU, a message about software updates appears. We recommend you always update XCTU to the latest available version.

Example: basic communication

The goal of this first example is to learn how to set up a simple Zigbee network and transmit data between the nodes. You will assemble the hardware and connect it to your computer, configure the XBees for wireless communication, create a network, and start sending messages.

Use the steps in this section to set up the XBees and send messages using XCTU.

Note Several steps contain videos to help you successfully complete the example. If you get stuck, see

Troubleshooting.

Step 1:Requirements

For this setup you need the following hardware and software.

Hardware

n Three XBee Zigbee Mesh Kit modules

n Three XBee Grove Development Boards

n Three micro USB cables

n One computer

Software

n XCTU 6.3.1 or later

Tip For more information about XCTU, see the XCTU walkthrough.

Step 2:Connect the components

To get started, connect the components and start XCTU.

1. Plug the XBee modules into the XBee Grove Development Boards and connect them to your

computer using the micro USB cables provided. For more information, see Plug in the XBee

module.

2. After connecting the modules to your computer, open XCTU.

XBee® Zigbee® Mesh Kit

Page 24

Get started with XBee Zigbee Example: basic communication

3. Make sure you are in Configuration working mode.

Step 3: Add the XBee modules to XCTU

Use XCTU to find your XBee modules and add them to the tool.

1. Click Discover radio modules from the toolbar.

2. In the Discover radio modules dialog, select the serial port(s) in which you want to look for

radio modules. If you do not know the serial ports where your modules are attached, select all ports. Click Next.

3. In the Set port parameters window, maintain the default values and click Finish.

4. As XCTU locates radio modules, they appear in the Discovering radio modules… dialog box.

Once the discovery process has finished, click Add selected devices.

5. At this point, assuming you have three modules connected to your computer, you should see

something like this in the Radio Modules section on the left:

Note The function, port number and the MAC address displayed for your modules need not match

those shown in the picture.

XBee® Zigbee® Mesh Kit

Page 25

XBee® Zigbee® Mesh Kit 25

Get started with XBee Zigbee Example: basic communication

Step 4: Configure the XBee modules

To transmit data wirelessly between your XBee modules, you must configure them to be in the same network. Remember that in Zigbee one device must be the coordinator, and the rest can be routers or end devices. In this case, you will have one router and one end device configured to send data to the coordinator.

Restore the default settings of all XBee modules with the Load default firmware settings button at the top of the Radio Configuration section.

2. Use XCTU to configure the following parameters:

Param XBee A XBee B XBee C Effect

ID 2015 2015 2015 Defines the network that a radio will attach to. This must be the same for all radios in your network.

JV — Enabled

[1]

CE Enabled

[1]

DH — 0 0 Defines the destination address (high part) to transmit the data to.

DL — 0 0 Defines the destination address (low part) to transmit the data to. The address 0000000000000000 can be

NI COORD ROUTER END_

SP 1F4 1F4 1F4 Defines the duration of time spent sleeping. 1F4 (hexadecimal) = 500 (decimal) x 10 ms = 5 seconds.

SM — — Cyclic

SO — — 2 Keeps the module awake during the entire period.

— — Sets the device as coordinator.

Enabled [1] Verifies if a coordinator exists on the same channel to join the network or to leave if it cannot be found.

used to address the coordinator.

Defines the node identifier, a human-friendly name for the module.

DEVICE

The default NI value is a blank space. Make sure to delete the space when you change the value.

Enables cyclic sleep mode in the end device.

sleep [4]

Page 26

XBee® Zigbee® Mesh Kit 26

Note The dash (—) in the table means to keep the default value. Do not change the default value.

Write the settings of all XBee modules with the Write radio settings button at the top of the Radio Configuration section.

Get started with XBee Zigbee Example: basic communication

Page 27

Get started with XBee Zigbee Example: basic communication

Step 5: Check the network

Once you have configured your XBee modules, use XCTU to verify that they are in the same network and can see each other.

Click the Discover radio nodes in the same network button of the first radio module.

The device searches for radio modules in the same network.

When the discovery process is finished, XCTU lists discovered devices found within the network in the Discovering remote devices dialog. You do not need to add the remote device that has been discovered.

2. Close the dialog by clicking Cancel.

Step 6: Send messages

In order to send messages to the coordinator, use the XCTU console or any serial port terminal application such as CoolTerm or TeraTerm (for Windows only). In this case, we will use the XCTU console.

To send messages to the coordinator:

XBee® Zigbee® Mesh Kit

Page 28

Get started with XBee Zigbee Example: basic communication

1. If XCTU is not already running, open it.

2. Switch to the Consoles working mode.

This working mode of XCTU allows you to communicate with the radio modules in the devices list. XCTU loads a list of consoles in the working area—one for each module of the devices list, sorted in a tabbed format.

3. If it is not already there, add an XBee to XCTU so it is listed in the Radio Modules list.

4. Then, open the serial connection of the radio module: select the XBee in the Radio Modules section, and click the Open serial connection button.

The background changes to green to indicate that the connection is open.

5. Repeat steps 3 and 4 for the others XBee modules.

6. You will see the consoles in three tabs. Click the Detach view button to see multiple tabs at the same time.

XBee® Zigbee® Mesh Kit

Page 29

Get started with XBee Zigbee Example: basic communication

7. Use the Console log section to type messages.

Type something like Hi, this is XXX! in the ROUTER or END_DEVICE console. The XBee sends every character to COORD and XCTU displays those characters in the corresponding device console.

To disconnect, click the Close serial connection button on for each console.

Note If an END_DEVICE is asleep when you type in its console, the message will not be sent to the

coordinator. To wake up the module, press the Commissioning button of the XBee Grove Development Board the end device is plugged into. To identify the END_DEVICE module, look for the board where the On/Sleep LED is ON for five seconds and OFF for another five seconds.

XBee® Zigbee® Mesh Kit

Page 30

How XBee devices work

This section describes how XBee devices communicate, and introduces two communication methods wireless and serial communication. Both communication types are important in the function of XBee devices.

How XBee devices communicate 31 Wireless communication 31 Serial communication 33

XBee® Zigbee® Mesh Kit

Page 31

How XBee devices work How XBee devices communicate

How XBee devices communicate

XBee devices communicate with each other over the air, sending and receiving wireless messages. The devices only transfer those wireless messages; they cannot manage the received or sent data. However, they can communicate with intelligent devices via the serial interface.

XBee devices transmit data coming from the serial input over the air, and they send anything received wirelessly to the serial output. Whether for communication purposes or simply for configuring the device, a combination of both processes makes XBee communication possible. In this way, intelligent devices such as microcontrollers or PCs can control what the XBee device sends and manage incoming wireless messages.

With this information, you can identify the two types of wireless data transmission in an XBee communication process:

1. Wireless communication: This communication takes place between XBee modules. Modules

that are supposed to work together need to be part of the same network and they must use the same radio frequency. All modules that meet these requirements can communicate wirelessly with each other.

2. Serial communication: This communication takes place between the XBee module and the

intelligent device connected to it through the serial interface.

Wireless communication

XBee modules communicate with each other over the air, transmitting and receiving information via modulation of waves in the electromagnetic spectrum. In other words, they act as radio frequency (RF) devices. For data to transmit from one XBee module to another, both modules must be in the same network.

This section describes the key concepts to understand as you learn how to manage a network and transmit information between XBee modules.

Addressing

XBee device addresses are similar to postal and email addresses for people. Some addresses are unique, like an email address, but others are not. For example, several people can live at the same postal address.

Each XBee device is known by several different addresses, each of which serves a purpose.

Type Example Unique

64-bit 0013A20012345678 Always

16-bit 1234 Yes, but only within a network

Node identifier Bob's module Uniqueness not guaranteed

XBee® Zigbee® Mesh Kit

Page 32

How XBee devices work Wireless communication

64-bit address

Every XBee device has a 64-bit address to distinguish it from others and prevent duplicate information. That address (also called MAC) is assigned to Digi by the IEEE and is guaranteed to be unique, so two devices cannot have the same address.

You can determine the value of the 64-bit address by reading the Serial Number High (SH) and Serial Number Low (SL) parameters on any device. It is also printed on the back of the device.

Note The concatenation of SH + SL forms the 64-bit or MAC address of the device. It is stored in the

device's memory as two 32-bit values: the high part, SH, and the low part, SL. The high part is usually the same for all XBee devices (0013A200), as this is the prefix that identifies Digi devices. The low part is different for every device.

The 64-bit address of 000000000000FFFF is reserved for sending a broadcast message.

16-bit address

A device receives a random 16-bit address when it joins a Zigbee network, so this address is also knows as "network address." This address can only change if an address conflict is detected or if a device leaves the network and later joins (it can receive a different address).

The value of the 16-bit address can be read through the 16-bit Network Address (MY) parameter. The 16-bit address of 0000 is reserved to the coordinator, while a value of FFFE means the device has not joined a PAN.

Node identifier

The node identifier is a short string of text that allows users to address the module with a more human-friendly name. In this case, uniqueness is not guaranteed because you can assign the same node identifier to several modules.

You can read or set the value of the node identifier through the Node Identifier (NI) parameter.

PAN Addresses

Zigbee networks are called personal area networks or PANs. A unique PAN identifier (PAN ID) defines each network and the identifier is common among all devices of the same network. Zigbee devices are either preconfigured with a PAN ID to join, or they can discover nearby networks and select a PAN ID to join.

The value of the personal area network can be set through the PAN ID (ID) parameter. If this value is 0, the XBee automatically selects the PAN ID, so you can read it using the Operating PAN ID (OP) parameter.

XBee® Zigbee® Mesh Kit

Page 33

How XBee devices work Serial communication

Channels

For the devices to be able to communicate, they must operate in the same frequency. XBee S2C/S2D and XBee3 devices support all 16 channels defined in the 802.15.4 physical layer, with the following exceptions:

n Channel 26 has reduced maximum output power on the S2C/S2D parts (~3dBm).

n S2C XBee-PRO device supports 15 of the 16 channels; it does not support channel 26.

n XBee3-PRO parts support channel 26, but at a reduced maximum output power (~8dBm).

To determine the specific channel where the device is operating, you must read the Operating Channel (CH) parameter. Unlike 802.15.4, the CH parameter cannot be written in the Zigbee application. However, you can select the operating channel by setting a single bit in the SC parameter. That single bit forces a coordinator to operate on the channel specified by the single bit. It also prevents routers and end devices from joining a network on any channel but the one specified in SC. If the selected channel is not important, you can use the SC parameter to select multiple channels.

Serial communication

An XBee module can operate as a stand-alone device or it can be attached to an intelligent device. For example, you can place several battery-powered XBee modules in remote locations to gather data such as temperature, humidity, light, or liquid level.

n When operating as a stand-alone device, an XBee module simply sends sensor data to a central

node.

n When an XBee module is connected to an intelligent device (such as a computer, Arduino, or

Raspberry Pi), it uses serial communication:

l The intelligent device sends data through the serial interface to the XBee module to be

transmitted to other devices over the air.

l The XBee module receives wireless data from other devices, and then sends the data

through the serial interface to the intelligent device.

The XBee modules interface to a host device such as a microcontroller or computer through a logiclevel asynchronous serial port. They use a UART for serial communication with those devices.

For additional information about serial communication, go to the XBee/XBee-PRO Zigbee RF Module.

Microcontrollers attached to an XBee module can process the information received by the module and thus monitor or even control remote devices by sending messages through their local XBee module. For prototyping, you can use external microcontrollers such as Arduino or Raspberry Pi, sockets, and breadboards.

The boards included in this kit allow you to use the XBee modules in either mode:

XBee® Zigbee® Mesh Kit

Page 34

How XBee devices work Serial communication

n If you plug the modules into the boards and connect them to a computer or microcontroller

using the micro USB cables, you can configure the XBee modules, test the connection, and send/receive data to/from other modules.

n If you plug the modules into the boards and connect them to a battery, the XBee modules work

autonomously. For example, they can gather data from a sensor and send it to a central node.

Operating modes

XBee devices can use their local serial connection in very different ways. The "operating mode" establishes the way the host device communicates with an XBee module through the serial interface.

XBee modules support two different operating modes:

n Application Transparent ("transparent mode")

n Application Programming Interface ("API mode")

Application Transparent operating mode

This mode is called "transparent" because the radio passes information along exactly as it receives it. All serial data received by the radio module is sent wirelessly to a remote destination XBee module. When the other module receives the data, it is sent out through the serial port exactly as it was received. Transparent mode has limited functionality but is an easy way to get started with XBee devices.

To learn more about transparent mode, see XBee transparent mode.

API operating mode

Application Programming Interface (API) operating mode is an alternative to transparent mode. In API mode, a protocol determines the way information is exchanged. Data is communicated in packets (commonly called API frames). This mode allows you to form larger networks and is more appropriate for creating sensor networks to perform tasks such as collecting data from multiple locations, controlling devices remotely, or automating your home.

XBee® Zigbee® Mesh Kit

Page 35

How XBee devices work Serial communication

To learn more about API mode, see XBee API mode.

Comparison of transparent and API modes

XBee devices can usetransparent or API operating mode to transmit data over the serial interface. You can use a mixture of devices running API mode and transparent mode in a network. The following table provides a comparison of the two modes.

Transparent operating mode API operating mode

When to use:

n Conditions for using API mode do

not apply.

Advantages:

n Provides a simple interface that

makes it easy to get started with XBee devices.

n Easy for an application to

support; what you send is exactly what other modules get, and vice versa.

n Works very well for two-way

communication between XBee devices.

When to use:

n Sends wireless data to multiple destinations.

n Configures remote XBee devices in the network.

n Receives wireless data packets from multiple

XBee devices, and the application needs to identify which devices send each packet.

n Receives I/O samples from remote XBee devices.

n Must support multiple endpoints, clusters, and/or

profiles (for Zigbee modules).

n Uses Zigbee Device Object (ZDO) services (for

Zigbee modules).

Advantages:

n Can set or read the configuration of remote XBee

devices in the network.

n Can transmit data to one or multiple destinations;

this is much faster than transparent mode where the configuration must be updated to establish a new destination.

n Received data includes the sender's address.

n Received data includes transmission details and

reasons for success or failure.

n Several advanced features, such as advanced

networking diagnostics, and firmware upgrades.

XBee® Zigbee® Mesh Kit

Page 36

How XBee devices work Serial communication

Transparent operating mode API operating mode

Disadvantages:

n Cannot set or read the

configuration of remote XBee devices in the network.

n Must first update the

configuration to establish a new destination and transmit data.

n Cannot identify the source of

received data, as it does not include the sender's address.

n Received data does not include

transmission details or the reasons for success or failure.

n Does not offer the advanced

features of API mode, including advanced networking diagnostics, and firmware upgrades.

Disadvantages:

n Interface is more complex; data is structured in

packets with a specific format.

n More difficult to support; transmissions are

structured in packets that need to be parsed (to get data) or created (to transmit data).

n Sent data and received data are not identical;

received packets include some control data and extra information.

XBee® Zigbee® Mesh Kit

Page 37

XBee transparent mode

This section provides additional detail about XBee transparent mode. For a comparison of transparent and API modes, see Serial communication.

XBee transparent mode in detail 38 Command mode 39

XBee® Zigbee® Mesh Kit

Page 38

XBee transparent mode XBee transparent mode in detail

XBee transparent mode in detail

When operating in transparent mode, an XBee module acts as a serial line replacement. All data received through the serial input is immediately transmitted over the air. When the XBee module receives wireless data, it is sent out through the serial interface exactly at it is received. In fact, communication in transparent mode yields the same result as if the two modules were connected by a wire, but wireless communication makes that physical wire unnecessary.

For two XBee modules to communicate, the sending module needs the address of the recipient. When working in transparent mode, you must configure this address in the module that is communicating. XBee modules can store the complete 64-bit address of the destination module. This address must be programmed in two parameters: Destination Address High (DH) and Destination Address Low (DL).

If you want modules A and B to communicate, configure the destination address (DH + DL) of XBee A as the MAC address (SH + SL) of XBee B, and vice versa.

Transparent mode has some limitations. For example, when you are working with several modules, you must configure the destination before sending each message. However, transparent mode provides an easy way to get started with XBee devices for the following reasons:

n Operation is very simple.

n What you send is exactly what the other modules get.

n Compatible with any device that can communicate over a serial interface.

n Works very well when facilitating communication between two XBee modules.

What have you learned?

n An XBee communicates remotely with other XBees via wireless and locally with the intelligent

device (microcontroller, computer) connected to it via the serial interface.

n To communicate wirelessly, your modules must be part of the same network, so the ID and CH

parameters must have identical values for all XBees in the network.

n Every XBee module has a unique 64-bit address called MAC that distinguishes it from the rest

of the devices. This address is formed by the concatenation of the parameters SH (Serial Number High) and SL (Serial Number Low).

n The operating mode of an XBee establishes the way to communicate with the module through

the serial interface.

XBee® Zigbee® Mesh Kit

Page 39

XBee transparent mode Command mode

n There are two different operating modes: Transparent and API (Application Programming

Interface).

n Transparent mode can be used as a serial cable replacement. What is sent through an XBee

serial input is wirelessly received by the destination module and then sent out to its serial output exactly as it was transmitted from the first XBee (and vice versa).

n In order to communicate using transparent mode, you must pre-configure each of your devices

by setting the parameters DH and DL on the first module with the SH and SL values of the other one respectively, and vice versa.

Extend the basic communication example

If you're ready to move beyond this exercise and extend the example, try the following:

n Use Arduino or Raspberry Pi instead of a computer to transmit data wirelessly.

n Use your XBees as a cable replacement for your serially communicating applications. For

example, if you have an Arduino application that controls room lighting via the serial port, replace the serial cable with XBees and move your Arduino around the house.

n Try using XBees to send wireless messages to your friends and neighbors.

Command mode

An XBee device in Transparent mode simply passes information along exactly as it receives it. So, what you send is what other devices get. But sometimes you want to talk directly to the local device without sending data. For example, you may need to modify its configuration or alter the way it behaves. In that case, the XBee device needs to know that this communication should not be transmitted wirelessly.

Command mode is a state in which incoming characters are interpreted as commands. To get a device to switch into this mode, you must issue a unique string of text in a special way: +++. When the device sees a full second of silence in the data stream followed by the string +++ (without Enter or Return) and another full second of silence, it knows to stop sending data through and start accepting commands locally.

Guard time silence Command sequence Guard time silence

One second before +++ One second after

Do not press Return or Enter after typing the +++ because it will interrupt the guard time silence and prevent the module from entering Command mode.

Once the device is in Command mode, it listens for user input for a while. If 10 seconds go by without any user input, the device automatically drops out of Command mode and returns to Transparent mode.

AT commands

The purpose of command mode is to read or change the configuration of the local XBee device. Every module has a number of settings, like channel or network ID, that define its behavior. These settings are identified by two characters, for example, CH for channel, and ID for network ID.

XBee® Zigbee® Mesh Kit

Page 40

XBee transparent mode Command mode

When you want to read or set any setting of the XBee module, you must send it an AT command. Every AT command starts with the letters "AT" followed by the two characters that identify the command being issued and then by some optional configuration values.

For example, to read and set the network ID setting:

// Enter command mode

+++OK

// Read the ID setting

ATID <Enter>

// Change the ID setting

ATID 2015 <Enter>

Basic AT commands

n AT

This command checks the connection with the module. This is like asking "Are you there?" and the device replying "Yes." When you send this command, the module simply replies OK. If you don't see an OK in response, you have probably timed out of command mode. Type the +++ to go back into it.

n ATCN

This command explicitly exits the module from command mode. Remember that if you don't type anything for 10 seconds, the device automatically drops out of Command mode.

n ATWR

This command writes the current configuration to non-volatile memory so that it persists the next time the device powers up. Otherwise, parameters are restored to previously saved values after the device is reset.

Use AT commands

In the first example in this kit, you used XCTU to configure some settings of each of your modules, such as the network ID. XCTU uses AT commands in the background to read and set the settings. For example, when you changed the value of that parameter and clicked the Write button, XCTU went into command mode using +++, changed the value of the setting with the ATID command, wrote the setting with the ATWRcommand, and finally exited command mode with the ATCN command.

XBee® Zigbee® Mesh Kit

Page 41

XBee transparent mode Command mode

XCTU simplifies the configuration of the XBee modules so you don't have to use command mode or AT commands to configure them. However, you can always configure an XBee module through any serial port terminal application or the XCTU console.

The following example demonstrates how you can perform some of the configuration steps outlined in the first lab but via command mode and using AT commands:

1. In the Consoles working mode of XCTU, click the Open the serial connection with the radio

module button.

2. Use +++ to enter into command mode and wait for an OK response.

3. To set a register, type an AT command followed by the value you want to set; for example, ATID

2015; followed by a Return.

4. To read a register, type an AT command; for example, ATID; followed by a Return.

5. Use the ATWR command to write the new configuration to the module's memory.

6. Exit command mode with the ATCN command.

Note You should get an OK response after issuing each command to set parameters, write the

changes, or exit from command mode. If not, you most likely took more than 10 seconds to issue the command and you have dropped out of command mode.

XBee® Zigbee® Mesh Kit

Page 42

XBee API mode

This section provides additional detail about API mode and lets you put your knowledge into practice. For a comparison of transparent and API modes, see Serial communication.

API mode in detail 43 API frame structure 45 Supported frames 48 Frame examples 49 Operating mode configuration 54 XBee frame exchange 58

XBee® Zigbee® Mesh Kit

Page 43

XBee API mode API mode in detail

API mode in detail

API mode provides a structured interface where data is communicated through the serial interface in organized packets and in a determined order. This enables you to establish complex communication between devices without having to define your own protocol.

By default, XBee devices are configured to work in transparent mode: all data received through the serial input is queued up for radio transmission and data received wirelessly is sent to the serial output exactly as it is received, with no additional information.

Because of this behavior, devices working in Transparent mode have some limitations:

1. To read or write the configuration of an device in Transparent mode, you must first transition

the device into Command mode.

2. If a device needs to transmit messages to different devices, you must update its configuration

to establish a new destination. The device must enter Command mode to set up the destination.

3. A device operating in Transparent mode cannot identify the source of a wireless message it

receives. If it needs to distinguish between data coming from different devices, the sending devices must include extra information known by all the devices so it can be extracted later. To do this, you must define a robust protocol that includes all the information you think you need in your transmissions.

To minimize the limitations of the transparent mode, devices provide an alternative mode called Application Programming Interface (API). API mode provides a structured interface where data is communicated through the serial interface in organized packets and in a determined order. This enables you to establish complex communication between modules without having to define your own protocol.

API mode provides a much easier way to perform the actions listed above:

1. Since there are different frames for different purposes (such as configuration and

communication), you can configure a device without entering Command mode.

2. Since the data destination is included as part of the API frame structure, you can use API mode

to transmit messages to multiple devices.

3. The API frame includes the source of the message so it is easy to identify where data is coming

from.

Advantages of API mode

n Configure local and remote XBee devices in the network.

n Manage wireless data transmission to one or multiple destinations.

n Identify the source address of each received packet.

n Receive success/failure status of each transmitted packet.

XBee® Zigbee® Mesh Kit

Page 44

XBee API mode API mode in detail

n Obtain the signal strength of any received packet.

n Perform advanced network management and diagnosis.

n Perform advanced functions such as remote firmware update, ZDO, ZCL and so on.

XBee® Zigbee® Mesh Kit

Page 45

XBee® Zigbee® Mesh Kit 45

API frame structure

The structured data packets in API mode are called frames. They are sent and received through the serial interface of the device and contain the wireless message itself as well as some extra information such as the destination/source of the data or the signal quality.

When a device is in API mode, all data entering and leaving the module through the serial interface is contained in frames that define operations or events within the device.

An API frame has the following structure:

Start delimiter

1 2 3 4 5 6 7 8 9 ... n n+1

0x7E MSB LSB API-specific structure Single byte

Note MSB represents the most significant byte, and LSB represents the least significant byte.

Any data received through the serial interface prior to the start delimiter is silently discarded by the XBee. If the frame is not received correctly, or if the checksum fails, the data is also discarded and the module indicates the nature of the failure by replying with another frame.

Start delimiter

The start delimiter is the first byte of a frame consisting of a special sequence of bits that indicate the beginning of a data frame. Its value is always 0x7E. This allows for easy detection of a new incoming frame.

XBee API mode API frame structure

Length Frame data Checksum

Length

The length field specifies the total number of bytes included in the frame data field. Its two-byte value excludes the start delimiter, the length, and the checksum.

Frame data

This field contains the information received or to be transmitted. Frame data is structured based on the purpose of the API frame:

Page 46

XBee® Zigbee® Mesh Kit 46

Frame data

XBee API mode API frame structure

Start

delimiter Length

1 2 3 4 5 6 7 8 9 ... n n+1

0x7E MSB LSB

Note MSB represents the most significant byte, and LSB represents the least significant byte.

n Frame type is the API frame type identifier. It determines the type of API frame and indicates how the information is organized in the Data field.

n Data contains the data itself. The information included here and its order depends on the type of frame defined in the Frame type field.

Frame type

API frame type

Data

Frame-type-specific data

Checksum

Single byte

Checksum

Checksum is the last byte of the frame and helps test data integrity. It is calculated by taking the hash sum of all the API frame bytes that came before it, excluding the first three bytes (start delimiter and length).

Note Frames sent through the serial interface with incorrect checksums will never be processed by the module and the data will be ignored.

Calculate the checksum of an API frame

1. Add all bytes of the packet, excluding the start delimiter 0x7E and the length (the second and third bytes).

2. From the result, keep only the lowest 8 bits.

3. Subtract this quantity from 0xFF.

Example: Checksum calculation

To calculate the checksum for the given frame:

Frame Data

Start Delimiter Length

7E 00 0F 17 01 00 13 A2 00 40 AD 14 2E FF FE 02 44 42 -

ChecksumFrame type Data

Page 47

XBee® Zigbee® Mesh Kit 47

1. Add all bytes excluding the start delimiter and the length: 17 + 01 + 00 + 13 + A2 + 00 + 40 + AD + 14 + 2E + FF + FE+ 02 + 44 + 42 = 481

2. From the result, keep only the lowest 8 bits: 81.

3. Subtract that result from 0xFF: FF - 81 = 7E

In this example, 0x7E is the checksum of the frame.

XBee API mode API frame structure

Verify the checksum of a given API frame

1. Add all bytes including the checksum (do not include the delimiter and length).

2. If the checksum is correct, the last two digits on the far right of the sum will equal FF.

Example: Checksum verification

In our example above, we want to verify the checksum is 7E.

Frame Data

Start Delimiter Length

7E 00 0F 17 01 00 13 A2 00 40 AD 14 2E FF FE 02 44 42 7E

1. Add all data bytes and the checksum: 17 + 01 + 00 + 13 + A2 + 00 + 40 + AD + 14 + 2E + FF + FE + 02 + 44 + 42 + 7E = 4FF

2. Since the last two far right digits of 4FF are FF, the checksum is correct.

ChecksumFrame type Data

Page 48

XBee API mode Supported frames

Supported frames

Support for API frame types depends on the type of XBee you are using. The 802.15.4 XBee modules included in this kit support the following API frames:

Transmit data frames are sent through the serial input, with data to be transmitted wirelessly to remote XBees:

API ID Frame name Description

0x08 AT Command Queries or sets parameters on the local XBee

0x09 AT Command Queue

Parameter Value

0x10 Transmit Request Transmits wireless data to the specified destination

0x11 Explicit Addressing

Command Frame

0x17 Remote AT Command

Request

0x21

Create Source Route Creates a source route in the module

0x24

Receive data frames are received through the serial output, with data received wirelessly from remote XBees:

API ID Frame name Description

0x88 AT Command Response Displays the response to previous AT command frame

0x8A

Modem Status Displays event notifications such as reset, association,

Queries or sets parameters on the local XBee without applying changes

Allows Zigbee application layer fields (endpoint and cluster ID) to be specified for a wireless data transmission

Queries or sets parameters on the specified remote XBee module

Registers a module with the Trust Center

disassociation, and so on.

0x8B

Transmit Status Indicates wireless data transmission success or failure

0x90

Receive Packet Sends wirelessly received data out the serial interface (AO = 0)

0x91

Explicit Rx Indicator Sends wirelessly received data out the serial interface when

0x92

IO Data Sample Rx Indicator

0x94

XBee Sensor Read Indicator

XBee® Zigbee® Mesh Kit

explicit mode is enabled (AO 0)

Sends wirelessly received IO data out the serial interface

Sends wirelessly received sensor sample (from a Digi 1-wire sensor adapter) out the serial interface

Page 49

XBee API mode Frame examples

API ID Frame name Description

0x95

0x97

Node Identification Indicator

Remote AT Command

Displays received node identification message when explicit mode is disabled (AO = 0)

Displays the response to previous remote AT command requests

Response

0x98

Extended Modem Status Displays what is happening during the association when Verbose

Join is enabled (DC10)

0xA0

0xA1

Over-the-Air Firmware Update Status

Router Record Indicator Displays the multiple route hopes after a Zigbee route record

Provides a status indication of a firmware update transmission attempt

command

0xA3

Many-to-One Route

Indicates a many-to-one route request is received

Request Indicator

0xA5

Join Notification Status Indicates a module attempts to join, rejoin, or leave the network

For more information about the structure of some of these frames, see the XBee/XBee-PRO Zigbee

RF Module User Guide.

Frame examples

The following examples of sent and received API frames are expressed in hexadecimal format.

Example: 0x10 - Transmit Request

The following frame is a Transmit Request frame with the following characteristics:

7E 00 13 10 01 00 13 A2 00 40 DA 9D 23 A6 B9 00 00 48 65 6C 6C 6F 0C

n The frame ID is 0x01, so the sender will receive a Transmit Status frame with the result of the

transmission.

n The destination XBee has a 64-bit address of 00 13 A2 00 40 DA 9D 23 and 16-bit address of

A6 B9.

n It does not specify any option.

n The data to transmit is 'Hello' (48 65 6C 6C 6F).

Frame fields Offset Example Description

Start delimeter

Length

MSB 1

LSB 2

0x7E

0x00

Number of bytes between the length and the checksum

0x13

XBee® Zigbee® Mesh Kit

Page 50

XBee API mode Frame examples

Frame fields Offset Example Description

Frame data

Frame type 3

Frame ID 4

64-bit

MSB 5

Destination address

0x10

0x01

0x10 - Indicates this is a frame

Identifies the data frame for the host to correlate with a subsequent Transmit

Transmit Request

Status (0x8B) frame.

Setting Frame ID to '0' will disable response frame.

0x00

0x13

0xA2

0x00

0x40

Set to the 64-bit address of the destination XBee The following addresses are also supported:

n 0x0000000000000000 - Coordinator

address

n 0x000000000000FFFF - Broadcast

address

n 0xFFFFFFFFFFFFFFFF - Unknown

address if the destination's 64-bit address is unknown

0xDA

0x9D

16-bit Destination address

Broadcast Radius

LSB 12

MSB 13

LSB 14

0x23

0xA6

0xB9

0x00

Set to the 16-bit address of the destination XBee, if known. The following addresses are also supported:

n 0x0000 - Coordinator address

n 0xFFFE - Unknwon address if the

destination's 16-bit address is unknown, or if sending a broadcast

Sets the maximum number of hops a broadcast transmission can occur. If set to '0', the broadcast radius will be set to the maximum hops value.

XBee® Zigbee® Mesh Kit

Page 51

XBee API mode Frame examples

Frame fields Offset Example Description

Options 16

RFData MSB 14

0x00

0x48

0x65

Bitfield of supported transmission options

Supported values include the following:

n 0x01 - Disable retries

n 0x20 - Enable APS encryption (if EE =

n 0x40 - Use the extended

transmission timeout for this destination

All other bits must be set to 0.

Enabling APS encryption decreases the maximum number of RF payload bytes by 4 (below the value reported by NP).

Setting the extended timeout bit causes the stack to set the extended transmission timeout for the destination address.

Up to 255 bytes of data that is sent to the destination XBee

...

0x6C

LSB 18

Checksum

0x6F

0x6E

Hash sum of frame data bytes

Example: 0x91 - Explicit Rx Indicator

The following frame is an Explicit Rx Indicator frame with the following characteristics:

7E 00 17 91 00 13 A2 00 40 DA 9D 05 00 00 E8 E8 00 11 C1 05 01 48 65 6C 6C 6F 61

n The XBee module that sent this data has a 64-bit address of 00 13 A2 00 40 DA 9D 05 and 16-

bit address of 00 00.

n The endpoint of the source that initiated the transmission is E8 and the destination endpoint is

E8.

n The Cluster ID the data is addressed to is 00 11.

n The Profile ID the data is addressed to is C1 05.

n The packet was acknowledged because the Receive options value is 01.

n The received data 'Hello' is (48 65 6C 6C 6F).

XBee® Zigbee® Mesh Kit

Page 52

XBee API mode Frame examples

Frame fields Offset Example Description

Start delimiter

Length

MSB 1

LSB 2

0x7E

0x00

0x17

Number of bytes between the length and the checksum

XBee® Zigbee® Mesh Kit

Page 53

XBee API mode Frame examples

Frame fields Offset Example Description

Frame data

Frame type 3

64-bit Source Address

16-bit Source Network Address

MSB 4

LSB 11

MSB 12

LSB 13

0x91

0x00

0x13

0xA2

0x00

0x40

0xDA

0x9D

0x05

0x00

0x91 - Indicates this is a

Indicator

64-bit address of sender

Set to 0xFFFFFFFFFFFFFFFF (unknown 64-bit address) if the sender's 64-bit address is unknown

16-bit address of sender

frame

Explicit Rx

Source Endpoint

Destination Endpoint

Cluster ID 16

Profile ID 18

0xE8

0x00

0x11

0xC1

0x05

Endpoint of the source that initiated the transmission

Endpoint of the destination the message is addressed to

Cluster ID the message was addressed to

Profile ID the message was addressed to

XBee® Zigbee® Mesh Kit

Page 54

XBee API mode Operating mode configuration

Frame fields Offset Example Description

Receive

Options

ReceivedData MSB 21

LSB 25

0x01

Bitfield of supported transmission options Supported values include the following:

n 0x01 - Packet

Acknowledged

n 0x02 - Packet was a

broadcast packet

n 0x20 - Packet encrypted

with APS encryption

n 0x40 - Packet sent with

extended timeout enabled

0x48

Up to 255 bytes data received from the source XBee

0x65

...

0x6C

0x6F

Checksum

Operating mode configuration

The API Enable (AP) parameter configures the XBee module to operate using a frame-based API instead of the default Transparent mode. It allows you to select between the two supported API modes and the default transparent operation.

Mode AP value Description

Transparent 0 API modes are disabled and the module operates in transparent mode

API 1 1 API mode without escaped characters

API2 2 API mode with escaped characters

The only difference between API 1 and API 2 is that API 2 operating mode requires that frames use escape characters (bytes).

Configuration of the serial XBee communication—whether it is transparent, API non-escaped (API 1), or API escaped (API 2)—does not prevent wireless communication between XBee modules. Since only the payload portion of the API frame is transmitted over the air, the receiving XBee modules will alter the packet information based on their AP setting, allowing an API non-escaped module to successfully communicate with others working in API escaped or Transparent mode.

0x61

Hash sum of frame data bytes

XBee® Zigbee® Mesh Kit

Page 55

XBee API mode Operating mode configuration

Note Devices working in Transparent mode and modules set to API non-escaped (API 1) operation can

communicate with devices configured to work in API escaped mode (API 2).

XBee® Zigbee® Mesh Kit

Page 56

XBee® Zigbee® Mesh Kit 56

XBee API mode Operating mode configuration

API escaped operating mode (API 2)

API non-escaped (API 1) operation relies solely on the start delimiter and length bytes to differentiate API frames. If bytes in a packet are lost, the length count will be off, and the next API frame (packet) will also be lost. API escaped (API 2) operation involves escaping character sequences in an API frame in order to improve reliability, especially in noisy RF environments.

The basic frame structure of both API modes is the same, but in API escaped (API 2) mode, all bytes except for the start delimiter must be escaped if needed. The following data bytes must be escaped in API 2 mode:

n 0x7E: Start delimiter

n 0x7D: Escape character

n 0x11: XON

n 0x13: XOFF

API 2 mode guarantees all the 0x7E bytes received are start delimiters: this character cannot be part of any of the other frame fields (length, data, or checksum) since it must be escaped.

To escape a character:

1. Insert 0x7D, the escape character.

2. Append it with the byte to be escaped, XORed with 0x20.

In API 2 mode, the length field does not include any escape character in the frame and the checksum is calculated with non-escaped data.

Example: Escape an API frame

To express the following API non-escaped frame in API 2 mode:

Frame Data

Start Delimiter Length

7E 00 0F 17 01 00

Frame type Data

A2 00 40 AD 14 2E FF FE 02 4E 49 6D

The 0x13 byte must be escaped:

Checksum

Page 57

XBee® Zigbee® Mesh Kit 57

1. Insert a 0x7D.

2. XOR the byte 0x13 with 0x20: 13 ⊕ 20 = 33.

This is the resulting frame. Note that the length and checksum are the same as the non-escaped frame.

Frame Data

XBee API mode Operating mode configuration

Start Delimiter Length

7E 00 0F 17 01 00

Frame type Data

7D 33

Checksum

A2 00 40 AD 14 2E FF FE 02 4E 49 6D

Page 58

XBee API mode XBee frame exchange

XBee frame exchange

Now that you understand how API mode works and how API frames are structured, the next step is to learn about how frames are exchanged when you perform certain common operations such as configuring an XBee module or transmitting wireless data.

The following section provides examples using XCTU. You can use the Frames interpreter tool of the XCTU console to view detailed API frame structure.

AT Command: configure a local XBee device

To query or set the value of the local XBee—that is, the device directly connected to an intelligent device such as a microcontroller or PC via the serial interface—you must use AT parameters and commands. These are the same AT parameters and commands that are available in Transparent/Command mode, but included in an AT Command (0x08) frame. The response containing the result of the operation is sent back in an AT Command Response (0x88) frame.

The following image shows the API frame exchange that takes place at the serial interface when sending either an AT Command (0x08) or an AT Command Queue Parameter Value (0x09) request.

During an API frame exchange, the following process occurs:

1. An AT Command (0x08) frame is sent to the device through the serial input. This frame contains configuration instructions or queries parameters on the local XBee device.

2. The XBee device processes the command and returns an AT Command Response (0x88) through its serial output. If the frame ID of the AT Command frame is 0, this response is not sent.

Transmit Request/Receive Packet: Transmit and receive wireless data

A Transmit Request frame encapsulates data with its remote destination and some transmission options. The wireless data received by an XBee module is included in a Receive Packet frame along with the remote transmitter and options for receipt.

Two more frames use Explicit addressing. They require that you specify application layer addressing fields (endpoints, cluster ID, profile ID).

For more information about Explicit addressing, see the Zigbee communication in depth chapter.

The following image shows the API exchanges that take place at the serial interface when transmitting wireless data to another XBee module.

XBee® Zigbee® Mesh Kit

Page 59

XBee API mode XBee frame exchange

1. The intelligent device (host) sends a Transmit Request (0x10) or an Explicit Addressing Command Frame (0x11) to XBee A through the serial input to transmit data to XBee B.

2. XBee A wirelessly transmits the data in the frame to the module configured as destination in the same frame; in this case, the destination is XBee B.

3. The remote XBee B module receives the wireless data and sends out through the serial output a Receive Packet (0x90) or an Explicit Rx Indicator (0x91), depending on the value of API Options (AO) setting. These frames contain the data received over the air and the source address of the XBee module that transmitted it, in this case XBee A.

4. The remote XBee B module transmits a wireless acknowledge packet with the status to the sender, XBee A.

5. The sender XBee A module sends out a Transmit Status (0x8B) through its serial output with the status of the transmission to XBee B.

The Transmit Status (0x8B) frame is always sent at the end of a wireless data transmission unless the frame ID is set to '0' in the transmit request. If the packet cannot be delivered to the destination, the transmit status frame will indicate the cause of failure.

To send data using an explicit frame:

n The source and destination endpoints must be E8.

n The cluster ID must be 0011.

n The profile ID must be C105.

To receive an explicit frame, the API Options (AO) parameter must be configured to API Explicit Rx Indicator - 0x91 [1]. If this setting is API Rx Indicator - 0x90 [0], a Receive Packet (0x90) will be received instead of an Explicit Rx Indicator (0x91).

Remote AT Command: Remotely configure an XBee module

Working in API mode also allows you to configure remote XBee modules wirelessly. Any AT command or parameter that can be issued locally can also be sent wirelessly for execution on a remote XBee module.

The following image shows the API frame exchanges that take place at the serial interface when sending a Remote AT Command Request (0x17) to remotely read or set an XBee parameter.

XBee® Zigbee® Mesh Kit

Page 60

XBee API mode XBee frame exchange

1. The intelligent device (host) sends a Remote AT Command Request (0x17) to XBee A through the serial input to configure the remote XBee B.

2. XBee A wirelessly transmits the AT Command in the frame to the module configured as destination in the same frame; in this case, the destination is XBee B.

3. XBee B receives the AT command and processes the command to wirelessly return the result to the sender, XBee A.

4. XBee A sends out a Remote AT Command Response (0x97) through its serial output with the result of the AT command processed by XBee B. If the frame ID of the Remote AT Command frame is '0', this response is not sent.

Source routing: Create and obtain the route of a packet

XBee modules also allow you to create and obtain a source route in the module. A source route specifies the complete route a packet travels to get from source to destination. In this case, before sending the data (a Transmit Request or a Explicit Addressing Command Frame), you must send a a Create Source Route (0x21) with the route of the following packet.

Use source routing with many-to-one routing for best results, so you should set the Many-to-One Route Broadcast Time (AR) parameter to a value other than FF in the sender module.

The following image shows the API exchanges at the serial interface when you are sending a Create Source Route (0x21) frame.

1. The intelligent device (host) sends a Create Source Route (0x21) to XBee A through the serial input to specify the route of the following data to XBee B.

2. The intelligent device (host) sends a Transmit Request (0x10) or an Explicit Addressing Command Frame (0x11) to XBee A through the serial input to transmit data to XBee B.

XBee® Zigbee® Mesh Kit

Page 61

XBee API mode XBee frame exchange

3. The remote XBee B receives the wireless data and sends out through the serial output a Receive Packet (0x90) or an Explicit Rx Indicator (0x91). This frame contains the data received over the air and the source address of the XBee that transmitted it, in this case XBee A.

4. The remote XBee B transmit a route record to the sender, XBee A, with the route the transmitted data followed.

5. The sender XBee A sends out a Route Record Indicator (0xA1) through its serial output with the 16bit addresses of the nodes the received route record traversed.

6. The sender XBee A sends out a Transmit Status (0x8B) through its serial output with the status of the transmission to XBee B.

Example: Configure your local XBee module

This section demonstrates how to read the Node Identifier (NI) of your local XBee module configured in APImode. To do this, you create an AT command frame to read the NI parameter, send it to the XBee module, and analyze the response.

If you get stuck, see Troubleshooting.

Step 1: Configure the XBee module

Before creating and sending the frame, configure the XBee module as follows:

Param Value Effect

XBEE_A

APEnabled [1]

Defines the node identifier, a human-friendly name for the module.

The default NI value is a blank space. Make sure to delete the space

when you change the value.

Enables APImode.

Step 2: Open the XCTU console

Switch to the Consoles working mode .

Open the serial connection with the radio module .

XBee® Zigbee® Mesh Kit

Page 62

XBee API mode XBee frame exchange

Step 3: Generate the AT command frame

These instructions describe how to generate an AT command frame using the XCTUFrame Generator tool.

Click Add new frame to the list .

2. Open the Frames Generator tool.

3. In the Frame type section, select 0x08 - AT Command.

4. In the AT command section, select the ASCII tab and type NI.

5. Click OK.

6. Click Add frame.

Step 4: Send the AT command frame

After you have created an AT command frame, you must send it to the local XBee module to receive a response containing the configured NI value.

XBee® Zigbee® Mesh Kit

Page 63

XBee API mode XBee frame exchange

1. Select the frame in the XCTU Send frames section.

2. Click Send selected packet.

The Frames log indicates that one frame has been sent (blue) and another has been received (red).

Step 5: Analyze the response

Once you have sent the frame, you can analyze the responses on the receiving end.

1. Select the frame received (AT Command Response) to see its details in the Frame details

section.

2. Analyze its details and verify that it contains the NI value of your module.

n Frame type: The received frame is an AT Command Response.

n Frame ID: This AT Command Response frame is the answer to the sent AT Command

request because both have the same value (1).

n Status: The value was successfully read because the status is OK.

n Response: This received frame contains the value of the NI parameter previously

requested in the AT Command frame, XBEE_A

Disconnect the console by clicking Close the serial connection .

XBee® Zigbee® Mesh Kit

Page 64

XBee API mode XBee frame exchange

Example:Transmit and receive data

This section describes how to transmit data to another XBee module using the XCTU console. The steps include creating a Transmit Request frame with the message you want to transmit to the other module and sending the frame serially to the local XBee module. You can then analyze the responses, both in the local and the remote module.

If you get stuck, see Troubleshooting.

Step 1: Configure the XBee modules

Before creating and sending the frame, configure the XBee modules as follows:

Param XBee A XBee B Effect

2015 2015

— Enabled[1] Verifies if a coordinator exists on the same channel to join the

Enabled[1] — Sets the device as coordinator.

SENDER RECEIVER

APIEnabled [1]

APIEnabled [1]

Defines the network that a radio will attach to. This must be the same for all radios on your network.

network or to leave if it cannot be found.

Defines the node identifier, a human-friendly name for the module.

The default NI value is a blank space. Make sure to

delete the space when you change the value.

Enables APImode.

Step 2: Open the XCTU console

Switch to the Consoles working mode .

Open the serial connection with the radio module .

3. Change to the console of the other XBee module.

Open the serial connection with the radio module .

Step 3: Generate the Transmit Request frame

This topic describes how to generate a Transmit Request frame using the XCTU SENDER console.

XBee® Zigbee® Mesh Kit

Page 65

XBee API mode XBee frame exchange

Go to the SENDER console and detach it to see two consoles at the same time.

In the SENDER console, click Add new packet to the list .

3. Open the Frames Generator tool.

4. In the Protocol control, select Zigbee.

5. In the Frame type control, select 0x10 - Transmit Request.

6. In the 64-bit dest. address box, type the 64-bit address of the RECEIVER module.

7. In the RF data box, click the ASCII tab and type the message "Hello, this is SENDER!"

8. Click OK.

XBee® Zigbee® Mesh Kit

Page 66

XBee API mode XBee frame exchange

9. Click Add frame.

Step 4: Send the Transmit Request frame

After you have created a Transmit Request frame, you must send it.

1. Select the frame in the XCTU Send frames section.

2. Click Send selected packet.

XBee® Zigbee® Mesh Kit

Page 67

XBee API mode XBee frame exchange

The Frames log indicates that one frame has been sent (blue) and another has been received (red).

Additionally, the RECEIVER console indicates that another packet has been received.

Step 5:Analyze the responses

Once you have sent the frames, you can analyze the responses on the receiving end.

1. Select the received frame (Transmit Status) in the SENDER console to view the frame details

on the right panel. Verify that the message was sent successfully.

n Frame type: The received frame is a Transmit Status.

n Frame ID: Since both frames have the same Frame ID, this is the response for the

Transmit Request frame.

n Status: The Success status indicates that the message was sent successfully.

XBee® Zigbee® Mesh Kit

Page 68

XBee API mode XBee frame exchange

XBee® Zigbee® Mesh Kit

Page 69

XBee API mode XBee frame exchange

2. Analyze the details of the Receive Packet for RECEIVER. Verify that the message is the one you

typed and the sender's address belongs to SENDER.

n Frame type: The received frame is a Receive Packet

n 64-bit source address: This field displays the 64-bit address of the sender module,

SENDER.

n Receive options:

l The packet was acknowledge (0xC1 = 1100 0001).

n RF data: The message of the packet is "Hello, this is SENDER!".

Disconnect both consoles by clicking Close the serial connection .

Libraries

Let's say you want to write an application to enable an intelligent device to monitor and manage an XBee network. You can write your own code to work with API mode, and you can also take advantage of existing software libraries that already parse the API frames. Depending on your preferred programming language and the intelligent device connected to the serial interface of the XBee, you can choose from a variety of available libraries:

n XBee mbed Library is a ready-to-import mbed extension to develop XBee projects on the

mbed platforms. For more information, go to https://developer.mbed.org/teams/Digi-

International-Inc/code/XBeeLib/.

n Digi XBee Ansi C Library is a collection of portable ANSI C code for communicating with XBee

modules in API mode. For more information, go to https://github.com/digidotcom/xbee_ansic_

library/.

n XBee-arduino is an Arduino library for communicating with XBees in API mode. For more

information, go to https://code.google.com/p/xbee-ard uino/.

n XBee Java Library is an easy-to-use library developed in Java that allows you to interact with

XBee modules working in API mode. For more information, visit the XBee Java Library documentation.

XBee® Zigbee® Mesh Kit

Page 70

XBee API mode XBee frame exchange

In this kit, you use the XBee Java Library to learn about the XBee features and capabilities offered in API operating mode. You can create several Java applications to control and monitor XBees connected to your computer via the XBee Grove Development Board.

XBee® Zigbee® Mesh Kit

Page 71

Zigbee Mesh Network Setup

A Zigbee mesh network is created by a coordinator. Once the network has been created, other nodes can join it. The default device type of the XBee modules is router, so you must configure an XBee to be the coordinator. Note that the rest of the modules should be switched on (or reset) once the network is created so that they can join it properly.

Configure the device type of an XBee module

The device type of an XBee is determined by the value of two parameters: Coordinator Enable (CE) and Sleep Mode (SM). The first setting determines if an XBee module is coordinator or not, and the second one determines if the module is router or end device. Coordinators and routers cannot sleep, so the value for that setting must be always 0 (disabled).

Configuration Description

Coordinator CE = 1

Router CE = 0

End device CE = 0

Startup operations

When you power on an XBee module, it performs several operations depending on the role assigned. The following sections explain the operations and commands performed by coordinators, routers, and end devices to form or join a network.

Coordinator

The coordinator is the only device that can start a network, so each Zigbee network must have one coordinator. It is responsible for selecting an unused operating channel, PAN ID, security policy, and stack profile for a network. To ensure the coordinator starts on a good channel and unused PAN ID, it performs a series of scans to discover any RF activity on different channels (energy scan) and to discover any nearby operating PANs (active scan).

The following commands control the coordinator network formation process:

SM = 0

SM = 1

An XBee module is a coordinator if the CE setting is set to 1. When CE = 1, the value of the SM setting cannot be different than 0.

An XBee module is a router if the CE setting is set to 0 and the sleep mode is disabled.

An XBee module is an end device if it has any sleep mode enabled.

XBee® Zigbee® Mesh Kit

Page 72

Zigbee Mesh Network Setup Startup operations

n PAN ID (ID). Determines the PAN ID. If set to 0 (default), the device selects a random PAN ID.

n Scan Channels (SC). Determines the scan channels bitmask the coordinator uses to form a

network. The coordinator performs an energy scan on all enabled SC channels.

n Scan Duration (SD). Sets the scan duration, which determines how long the coordinator

performs an energy or active scan on a given channel.

After the coordinator has started the network, it can allow new devices to join it (up to 20 devices). The permit joining attribute is configurable with the Node Join Time (NJ) command. The coordinator can also route data packets and communicate with other devices on the network.

Note You can configure it to always allow joining (FF) for up to 254 seconds. However, Digi discourages

this due to the security risk.

Router

Routers must discover and join a valid Zigbee network before they can participate in it. To discover nearby networks, the router performs an active scan, just like the coordinator does when it starts the network. When a router joins a network, it receives a randomly selected 16-bit address from the device that allowed the join .

Once a router joins a Zigbee network, it remains connected to the network on the same channel and PAN ID as long as it is not forced to leave. If the scan channels, PAN ID, and security settings do not change after a power cycle, it remains connected to the network after a power cycle. There are two provisions to automatically detect the presence of a network and leave if the check fails:

n Join Verification (JV). If enabled, the XBee attempts to discover the address of the coordinator

when it first joins a network.

n Network Watchdog Timeout (NW). Used for a powered router to periodically check for the

presence of a coordinator to verify network connectivity.

After a router has joined a network, it can allow new devices to join the network (up to 20 devices each router) with the Node Join Time (NJ) setting. It can also route data packets and communicate with other devices on the network.

End device

Similar to routers, end devices must also discover and join a valid Zigbee network before they can participate in it. End devices also discover networks by issuing an active scan, and when they join a network they receive a randomly selected 16-bit address from the device that allowed the join.

Since an end device may enter low power sleep modes and not be immediately responsive, it relies on the device that allowed the join to receive and buffer incoming messages on its behalf until it is able to wake and receive those messages. The device that allowed an end device to join becomes the parent, and the end device becomes the child. The end device polls its parent when it is awake to query for any new received data packets.

Coordinators and routers maintain a table of all child devices that have joined. This table has a finite size and determines how many end devices can join. You can use the Number of Remaining Children (NC) setting to determine how many additional end devices can join a coordinator or router.

After an end device has joined a network, it can communicate with other devices on that network. Since end devices are intended to be battery powered and therefore support low power (sleep) modes, they cannot allow other devices to join, nor can they route data packets.

XBee® Zigbee® Mesh Kit

Page 73

Zigbee Mesh Network Setup Explore the network

Explore the network

To better understand how a Zigbee mesh network is formed, you can use XCTU's Network view to discover and visualize the topology and interconnections of the network.

To learn more about the Network View, read the How-to: Visualize your network article.

Section summary

To form a Zigbee mesh network, you must configure at least the following settings:

n PAN ID (ID). Every node should have the same value.

n Scan Channels (SC). Every node should have the same value.

n Channel Verification (JV). Enable this setting to ensure there is a coordinator in the network.

n Coordinator Enable (CE). Enable this setting in one module.

n Sleep Mode (SM). If you want to have end devices, set their sleep mode to some other value

than 0.

Note There are other less critical settings under the Networking group in XCTU that also influence

network creation.

XBee® Zigbee® Mesh Kit

Page 74

Wireless data transmission

This section explains data transmission and guides you through an example to illustrate how it works.

If you get stuck, see Troubleshooting.

Transmission methods

An XBee module can communicate with multiple devices or with just one device:

n Broadcast transmissions are sent to many or all modules in the network.

n Unicast transmissions route wireless data from one XBee to one destination module.

Broadcast transmission

Broadcast means to transmit the same data to all nodes on a network. These transmissions are

propagated throughout the entire network so that all possible nodes receive the transmission.

To accomplish this, the coordinator and all routers that receive a broadcast transmission re-transmit the data three times. When a router or coordinator delivers a broadcast transmission to an end device child, it sends the transmission only once, immediately after the end device wakes and polls the parent for new data.

You can address broadcast transmissions using either the 64-bit broadcast address or the 16-bit broadcast address:

n If the 64-bit broadcast address (000000000000FFFF) is used, set the 16-bit address to

unknown address (FFFE).

n If the 16-bit broadcast address (FFFF) form is used, set the 64-bit address to unknown

address (FFFFFFFFFFFFFFFF).

Note Because the XBee modules re-transmit broadcast transmissions by every device in the network,

broadcast messages should be used sparingly.

XBee® Zigbee® Mesh Kit

Page 75

Wireless data transmission Transmission methods

Unicast transmission

A unicast transmission consists of sending messages to a single node on the network identified by a unique address. The destination XBee can be an immediate neighbor of the sender, or be several hops away.

Wireless data may be addressed using either the 64-bit address or the 16-bit address (network address):

n If you use the 64-bit address, set the network address to unknown address (FFFE).

n If you use the 16-bit address, set the 64-bit address must be set to unknown address

(FFFFFFFFFFFFFFFF).

n The 16-bit address 0000 and the 64-bit address 0000000000000000 are reserved for the

coordinator.

The Zigbee network layer uses the 16-bit address of the destination on each hop to route the data.

If you use an invalid 16-bit address as a destination address, and the 64-bit address is unknown (FFFFFFFFFFFFFFFF), the Transmit Status (0x8B) message shows a delivery status code of 0x21 (network ACK failure) and a discovery status of 0x00 (no discovery overhead).

If you use a non-existent 64-bit address as a destination address, and the 16-bit address is unknown (FFFE), the device attempts address discovery and the Transmit Status (0x8B) message shows a delivery status code of 0x24 (address not found) and a discovery status code of 0x01 (address discovery attempted).

XBee® Zigbee® Mesh Kit

Page 76

Wireless data transmission Example: transmit data

Address table

XBee devices use the destination network address to send data in a unicast transmission. Since data can only be sent using the destination's 64-bit address, all Zigbee devices maintain an address table to map 64-bit address to the corresponding 16-bit address. XBee modules can store up to 10 address table entries.

If the destination's 16-bit address is unknown:

1. The Zigbee stack uses its address table to look for an entry with a matching 64-bit address which determines the destination's 16-bit address.

2. If it is not found, the XBee automatically initiates a discovery process to find that address before transmitting the data:

a. First, the sending device broadcasts an address discovery message. This message includes

the 64-bit address of the remote XBee module whose 16-bit address is being requested.

b. All nodes that receive this transmission compare their own 64-bit address to the one

included in the message.

c. If the addresses match, the remote XBee sends a response back to the requester module.

This response includes the remote device's 16-bit address.

d. When the requesting module receives this discovery response with the destination's 16-bit

address, it transmits the data.

Example: transmit data

In the first example of this kit, you transmitted data to other nodes using transparent mode. An XBee module in transparent mode simply passes information along exactly as it receives it. This mode is an easy way to get started with XBees, but it has several limitations:

n You have to configure the address of the receiver in the transmitter module. If you want to

transmit data to other XBees, you must re-configure the sender.

n The receiver module does not know who sent the message.

You can use API mode to avoid these limitations and have more flexibility and reliability in your data transmissions. In API mode, you still send the message to the module. But, you also send other necessary information, such as the destination address or checksum value, all wrapped in a packet

XBee® Zigbee® Mesh Kit

Page 77

Wireless data transmission Example: transmit data

with a defined structure called an API frame. This means that in API mode you don't need to set the destination address (DH + DL) in the module. Similarly, the receiver module receives more information than the message itself, such as the source address, signal strength, or checksum value.

In this example, you will create an application in the Java programming language to transmit data between the nodes of the network. To simplify that application, you will use the XBee Java Library, an easy-to-use API that allows you to interact with XBee modules.

Once you have everything set up, send a message to a specific device (unicast) or to all devices of the network (broadcast).

Several steps contain videos to help you successfully complete the example.

If you get stuck, see Troubleshooting.

Step 1: Requirements

For this setup you need the following hardware and software.

Hardware

n Three XBee Zigbee Mesh Kit modules

n Three XBee Grove Development Boards

n Three micro USB cables

n One computer

Software

n XCTU 6.3.1 or later

n XBee Java Library (XBJL-X.Y.Z.zip release file)

n Java Virtual Machine 6 or later

n A Java IDE (such as Eclipse or NetBeans)

Tip For more information about XCTU, see the XCTU walkthrough.

Step 2:Connect the components

To get started, connect the components and start XCTU.

1. Plug the XBee modules into the XBee Grove Development Boards and connect them to your

computer using the micro USB cables provided. You can find more specific steps in Plug in the

XBee module.

2. After connecting the modules to your computer, open XCTU.

3. Make sure you are in Configuration working mode.

XBee® Zigbee® Mesh Kit

Page 78

Wireless data transmission Example: transmit data

Step 3: Configure the Xbee modules

Configure each of the three XBee modules to work in API mode and assign each a different role. As mentioned before, in this case you don't need to configure the destination address (DH + DL) of the modules.

Restore the default settings of all XBees with the Load default firmware settings button at the top of the Radio Configuration section.

2. Use XCTU to configure the following parameters:

Param XBee A XBee B XBee C Effect

ID 2015 2015 2015 Defines the network a radio will connect to. This

parameter must be the same for all radios on your network.

JV — Enabled

[1]

CE Enabled

[1]

NI COORD ROUTER END_

AP API

enabled [1]

SP 1F4 1F4 1F4 Defines the duration of time spent sleeping. 1F4

SM — — Cyclic

— — Sets the device as coordinator.

API enabled [1]

Enabled [1]

DEVICE

API enabled [1]

sleep [4]

Verifies if a coordinator exists on the same channel to join the network or to leave if it cannot be found.

Defines the node identifier, a human-friendly name for the module.

The default NI value is a blank space. Make sure to delete the space when you change the value.

Enables API mode.

(hexadecimal) = 500 (decimal) x 10 ms = 5 seconds.

Enables the cyclic sleep mode in the end device.

SO — — 2 Keeps the module awake during the entire period.

3. Write the settings of all XBees with the Write radio settings button at the top of the Radio

Configuration section.

Step 4: Create a Java project

Create an empty Java project using Eclipse or NetBeans with the following project name: XBeeTransmitDataCoord.

XBee® Zigbee® Mesh Kit

Page 79

Wireless data transmission Example: transmit data

Option 1: Eclipse

a. Select File > New, and click the Java Project.

b. The New Java Project window appears. Enter the Project name.

c. Click Next.

Option 2: NetBeans

a. Select File > New project....

b. The New Project window appears. In the Categories frame, select Java > Java Application

from the panel on the right, and click Next.

c. Enter the Project name and the Project Location. Clear the Create Main Class option; you will

create this later.

d. Click Finish to create the project. The window closes and the project appears in the Projects

view list on the left side of the IDE.

Step 5:Link libraries to the project

This topic describes how to link the XBee Java Library, the RXTX library (including the native one), and the logger library to the project.

1. Download the XBJL_X.Y.Z.zip library.

2. Unzip the XBJL_X.Y.Z.zip library.

3. Link the libraries using Eclipse or NetBeans:

Option 1:Eclipse

a. Go to the Libraries tab of the New Java Project window.

b. Click Add External JARs....

c. In the JAR Selection window, search the folder where you unzipped the XBee Java Library and

open the xbee-java-library-X.Y.Z.jar file.

d. Click Add External JARs... again.

e. Go to the extra-libs folder and select the following files:

n rxtx-2.2.jar

n slf4j-api-x.y.z.jar

n slf4j-nop-x.y.z.jar

f. Expand the rxtx-2.2.jar file of the Libraries tab list, select Native library location, and click

Edit….

g. Click External folder... to navigate to the extra-libs\native\Windows\win32 folder of the

directory where you unzipped the XBee Java Library file (XBJL_X.Y.Z.zip).

n Replace Windows\win32 with the directory that matches your operating system and

the Java Virtual Machine installed (32 or 64 bits). If you don't know which Java Virtual Machine is installed in your computer, open a terminal or command prompt and execute:

XBee® Zigbee® Mesh Kit

java -version

Page 80

Wireless data transmission Example: transmit data

a. Click OK to add the path to the native libraries.

b. Click Finish.

Option 2:NetBeans

a. From Projects view, right-click your project and go to Properties.

b. In the categories list on the left, go to Libraries and click Add JAR/Folder.

c. In the Add JAR/Folder window, search the folder where you unzipped the XBee Java Library

and open the xbjlib-X.Y.X.jar file.

d. Click Add JAR/Folder again.

e. Go to the extra-libs folder and select the following files:

n rxtx-2.2.jar

n slf4j-api- x.y.z .jar

n slf4j-nop- x.y.z .jar

f. Select Run in the left tree of the Properties dialog.

g. In the VM Options field, add the following option:

-Djava.library.path=<path_where_the_XBee_Java_Library_is_unzipped>\extralibs\native\Windows\win32

where:

n <path_where_the_XBee_Java_Library_is_unzipped> is the absolute path of the

directory where you unzipped the XBee Java Library file (XBJL_X.Y.Z.zip)

n Windows\win32 is the directory that matches your operating system and the Java

Virtual Machine installed (32 or 64 bits). If you don't know which Java Virtual Machine is installed in your computer, open a terminal or command prompt and execute:

java -version

h. Click OK.

Step 6:Add the source code to the project

Follow these steps to add the source to the project.

1. Open the following source code, select all, and copy it to the clipboard: MainApp.

2. Add the Java source file with Eclipse or NetBeans.

Option 1: Eclipse

a. In the Package Explorer view, select the project and right-click.

b. From the context menu, select New > Class. The New Java Class wizard opens.

c. Type the Name of the class: MainApp.

d. Click Finish.

e. The MainApp.java file is automatically opened in the editor. Replace its contents with the

source code you copied in the previous step.

XBee® Zigbee® Mesh Kit

Page 81

Wireless data transmission Example: transmit data

f. A line at the top of the pasted code is underlined in red. Click on that line; a pop-up appears.

Select the first option (Move 'MainApp.java' to package '...') to resolve the error.

Option 2:NetBeans

a. In the Projects view, select the project and right-click.

b. From the context menu, select New > Java Class... The New Java Class wizard opens.

c. Modify the Class Name to be MainApp.

d. Click Finish.

e. The MainApp.java file automatically opens in the editor. Replace its contents with the source

code you copied in the previous step.

f. A line at the top of the pasted code is underlined in red. Click on the light bulb next to that line;

a pop-up appears. Select the first option (Move class to correct folder) to resolve the error.

Step 7:Set the port names and launch applications

For this step, set the port names for all three XBee modules, duplicate the project for the other XBee modules, then launch the applications.

1. Change the port name in the Java source code to match the port COORD is connected to.

// TODO:Replace with the port where your module is connected

private static final String PORT = "COM1";

// TODO:Replace with the baud rate of your module.

private static final int BAUD_RATE = 9600

2. Duplicate the Java project for the other XBee module and rename it to

XBeeTransmitDataRouter.

3. Change the port name in the second project's source code to match the port ROUTER is

connected to.

4. Duplicate the Java project for the last XBee module and rename it to

XBeeTransmitDataEndDevice.

5. Change the port name in the third project's source code to match the port END_DEVICE is

connected to.

6. Before launching each of the three applications, press the Commissioning button of the board

the END_DEVICE is attached to wake it up. To identify the END_DEVICE module, look for the board where the On/Sleep LED is ON for 5 seconds and OFF for another 5 seconds.

7. Launch the three applications.

Step 8:Transmit data over the network

Follow these steps to transmit data to other XBee modules in your network with the unicast or broadcast method.

1. Send messages to a specific XBee module (unicast) or to all (broadcast) using the following

pattern:

n Unicast: NODE_IDENTIFIER: message

XBee® Zigbee® Mesh Kit

For example, to send the message "Hi XBee" to END_DEVICE:

Page 82

Wireless data transmission Example: transmit data

END_DEVICE:Hi XBee

n Broadcast: ALL: message

For example, to send the message "Hi XBee nodes" to all nodes of the network:

ALL: Hi XBee nodes

Step 9:Section summary of wireless data transmission

In this section, you have learned the following:

n An XBee sending a transmission in API mode not only transmits a raw message but also some

extra information—such as the address of the source XBee module—packaged in what is called an API frame.

n In API mode, you don't need to set the DH and DL parameters of the receiver device because

the destination address is already included in the API frame.

n API mode allows you to easily work with multiple destinations without needing to re-configure

the sender module to establish a new destination module before sending the data.

n You can use the XBee Java Library to simplify and improve the use of the API operating mode.

n Depending on the number of devices that will receive the message, there are two types of

transmissions:

l Unicast sends a message to one node identified by a unique address.

l Broadcast sends the same message to all possible nodes on the network.

Step 10:Do more with wireless data transmission

If you're ready to work more extensively with data transmission, try the following:

n Extend the network by adding more XBee Zigbee Mesh Kit modules so you can chat with other

devices.

Note To find the best channel to acquire more modules, see Where to buy XBee devices.

n Use Arduino or Raspberry Pi instead of a computer to transmit data wirelessly.

XBee® Zigbee® Mesh Kit

Page 83

Low power and battery life

This section introduces the key concepts you need to know to take advantage of the power saving capabilities of XBee devices. It also provides a lab that lets you put the concepts to work and see the results.

Low power devices and battery life 84 Sleep modes 84 Pin sleep 85 Cyclic sleep 86 Example: enable sleep mode 86

XBee® Zigbee® Mesh Kit

Page 84

Low power and battery life Low power devices and battery life

Low power devices and battery life

The advantage of a wireless connection is that devices do not require physical wires to communicate, and they also use batteries instead of mains AC power. However, battery life can also be a major limitation. Depending on the location of the device, it can be difficult or expensive to replace the battery.

XBee modules are low-power devices. They can put themselves into a temporary sleep state in which they consume virtually no current. During sleep, the device is almost completely turned off and is sometimes incapable of sending or receiving data until it wakes up.

A real world scenario

Extending battery life is important in many real world scenarios. For example, if you had several greenhouses, each with a temperature sensor connected to an XBee module, battery life would be critical. Fully charged batteries would only power the modules for one day.

There are several ways to maximize battery life. For example:

n Putting the modules into a cycle where they sleep for one second and then wake for one

second before sleeping again can double the battery life to two days.

n Cyclically sleep for 59 seconds and then waking for one second can keep the same batteries

going for 60 days. Taking this further, you can potentially extend the battery life for years.

Design considerations for applications using sleep mode

Before using sleep mode you must take into consideration the structure of your project and your XBee network. Some applications, like the greenhouse example, are particularly suited to sleep mode. In that scenario, the modules only send data periodically and are not expected to receive data. The modules can therefore be sleeping most of the time and wake up only to send the temperature value.

Sleep modes

XBee ZB end devices support three different sleep modes:

XBee® Zigbee® Mesh Kit

Page 85

Low power and battery life Pin sleep

n Pin sleep (SM = 1)

n Cyclic sleep (SM = 4)

n Cyclic sleep with pin wake-up (SM = 5)

An end device in one of these sleep modes polls its parent every 100 milliseconds while it is awake to retrieve buffered data. When the module enters sleep mode:

n The module de-asserts (low) the On/Sleep pin (pin 13) to indicate the module is entering sleep

mode.

n If CTS hardware flow control is enabled, the module de-asserts (high) the CTS pin (pin 12) to

indicate that serial data should not be sent to the module.

n If the Associate pin (pin 15) is configured, it is driven low to avoid using power to light the LED.

n The Sleep_RQ pin (pin 9) is configured as a pulled-down input so that an external device can

drive it high to wake the module (only applies to SM = 1 or SM = 5).

n The module leaves all other pins unmodified during sleep so they can operate as previously

configured by the user.

When the XBee wakes from sleep:

n The device asserts (high) On/Sleep pin to indicate the it is awake.

n If you enable CTS hardware flow control, the CTS pin is asserted (low) indicating that serial

data can be sent to the module.

n The Associate pin resumes its former configured operation.

n All other pins are left unmodified so they can operate as previously configured by the user.

Pin sleep

Pin sleep allows an external microcontroller to determine when the XBee should sleep and when it should wake by controlling the Sleep_RQ pin (pin 9). When Sleep_RQ is asserted (high) by connecting it to 3.3 volts, the module finishes any operation and enters a low power state. The module wakes when the Sleep_RQ pin is de-asserted (low).

Enable pin sleep mode by setting the Sleep Mode (SM) parameter to Pin Hibernate [1].

XBee® Zigbee® Mesh Kit

Page 86

Low power and battery life Cyclic sleep

Cyclic sleep

Cyclic sleep allows the module to sleep for a specified time and wake for a short time to poll its parent for any buffered data messages before returning to sleep again.

Enable cyclic sleep mode by setting the Sleep Mode (SM) parameter to 4 or 5. The cyclic sleep with pin wake up (SM = 5) is a slight variation of the cyclic sleep mode (SM = 4) that allows the module to be woken prematurely by de-asserting the Sleep_RQ pin.

The following parameters control cyclic sleep:

Parameter Name Description

SP Cyclic

Sleep Period

SN Number of

Cyclic Sleep Periods

ST Time

before Sleep

SO Sleep

Options

Press the Commissioning button to wake a sleeping device for 30 seconds.

Configures the sleep period of the module.

Configures the number of sleep periods multiplier.

Defines the period of inactivity of the module (during which no data is sent or received) before returning to cyclic sleep. If the XBee is transmitting or receiving a message, it will not go to sleep.

Defines options for sleep mode behavior:

0x02: Always wake for full ST time. 0x04: Enable extended sleep (sleep for full SP * SN time).

Example: enable sleep mode

This example shows you how to extend the battery life of an XBee Zigbee module. The example uses all three modules included in the kit to demonstrate how a Zigbee network handles messages when some modules are sleeping.

Configure one of the modules as coordinator and the other two as end devices with different sleep modes. An end device periodically sends the value of an ADC to the other end device. Since the receiver is asleep, the coordinator stores all of its messages and forwards them to the destination module once it wakes up.

Tip If you get stuck, see Troubleshooting.

Step 1:Requirements

For this setup you need the following hardware and software.

Hardware

n Three XBee Zigbee Mesh Kitmodules

n Three XBee Grove Development Boards

XBee® Zigbee® Mesh Kit

Page 87

Low power and battery life Example: enable sleep mode

n Three micro USB cables

n One computer

Software

n XCTU 6.3.1 or later

Tip For more information about XCTU, see the XCTU walkthrough.

Step 2: Connect the components

To get started, connect the components and start XCTU.

1. Plug the XBee modules into the XBee Grove Development Boards and connect them to your

computer using the micro USB cables provided. You can find more specific steps in Plug in the

XBee module.

2. After connecting the modules to your computer, open XCTU.

3. Make sure you are in Configuration working mode.

XBee® Zigbee® Mesh Kit

Page 88

XBee® Zigbee® Mesh Kit 88

Low power and battery life Example: enable sleep mode

Step 3:Configure the XBee Modules

To transmit data wirelessly between your XBees, you must configure them to be in the same network. Remember that in the Zigbee protocol, one device must be the coordinator and the rest can be routers or end devices. In this case, you will have two end devices configured to sleep using different sleep modes: one with cyclic sleep (XBee B) and the other with pin hibernate sleep (XBee C).

The coordinator is responsible for storing messages sent from XBee B to XBee C while XBee C is asleep. It forwards the messages once it wakes up.

Page 89

XBee® Zigbee® Mesh Kit 89

Restore the default settings of all XBee modules with the Load default firmware settings button at the top of the Radio Configuration section.

Low power and battery life Example: enable sleep mode

Page 90

XBee® Zigbee® Mesh Kit 90

2. Use XCTU to configure the following parameters:

Low power and battery life Example: enable sleep mode

Param XBee A XBee B XBee C Effect

ID 2015 2015 2015 Defines the network for a radio to attach to. This

must be the same for all radios on your network.

JV — Enabled [1] Enabled [1] Verifies if a coordinator exists on the same channel to

join the network or to leave if it cannot be found.

CE Enabled [1] — — Sets the device as coordinator.

DH — 0013A200 — Defines the destination address (high part) to

transmit the data to.

DL — SL of XBee C — Defines the destination address (low part) to transmit

the data to. Use the address 0000000000000000 to address the coordinator.

NI COORD ED_CYCLIC ED_PIN Defines the node identifier, a human-friendly name for

the module.

The default NI value is a blank space. Make sure to delete the space when you change the value.

AP API enabled [1] API enabled [1] API enabled [1] Enables API operating mode.

SP 384 384 — Defines the duration of time spent sleeping. 384

(hexadecimal) = 900 (decimal) x 10 ms = 9 seconds.

SM — Cyclic sleep [4] Pin Hibernate [1] Enables cyclic sleep mode on XBee B and pin

hibernate sleep mode on XBee C (both end devices).

Page 91

XBee® Zigbee® Mesh Kit 91

Low power and battery life Example: enable sleep mode

Param XBee A XBee B XBee C Effect

ST — 7D0 — Defines the period of inactivity (no serial or RF data

received) before going to sleep. 7D0 (hexadecimal) = 2000 (decimal) x 1 ms = 2 seconds.

SO — 2 — Keeps the module awake during the entire period.

D2/D3 — ADC [2] — Sets the DIO2/AD2 or DIO3/AD3 pin as ADC in XBee B,

depending on if the XBee module is THT or SMT. This pin is connected to a potentiometer.

Configure the D2 parameter as ADC [2] only if XBee B is surface-mount (SMT). However, if XBee B is through-hole (THT), you have to configure the D3 par ameter as ADC [2] instead of the D2.

IR — 3E8 — Configures XBee B to send an IO sample every second

(1000 ms = 3E8 in hexadecimal).

Note The dash (—) in the table means to keep the default value. Do not change the default value.

Write the settings of all XBee modules with the Write radio settings button at the top of the Radio Configuration section.

Page 92

Low power and battery life Example: enable sleep mode

Step 4: Sleep

With this configuration, ED_CYCLIC sends the value of the potentiometer to ED_PIN every time it wakes up. The coordinator stores all the D_CYCLIC samples sent to ED_PIN until it wakes up. To verify, perform the following steps in XCTU:

1. Select ED_PIN module (receiver).

2. Switch to the Consoles working mode.

3. Open the serial connection with the module.

4. To request the module to sleep, click the DTR radio button from the top of the console to

deactivate it (notice that the CTS indicator is also deactivated).

The DTR pin is the same as the Sleep_RQ pin. When the DTR option is deactivated, the module goes to sleep; when DTR is activated, the module wakes up.

5. After 20 seconds or so, activate the DTR button.

XBee® Zigbee® Mesh Kit

Page 93

Low power and battery life Example: enable sleep mode

6. Check that the module receives a series of IO Samples (IO Data Sample RX Indicator).

When the module wakes up, it immediately receives several IO samples instead of receiving one every second (IR parameter). This happens because the coordinator stores the samples that ED_PIN is not able to receive while it is asleep. Once ED_ PIN wakes up, the coordinator sends all IO samples at once.

7. Select one frame and check its details in the right panel. The value of the potentiometer

(DIO3_AD3) and other details related to the frame appear.

8. Repeat step 4 and rotate the potentiometer of the board where ED_CYCLIC is attached. Wait

for another 20 seconds and check that the new packets that arrive contain a different value for the DIO3_AD3 pin.

9. If you leave the receiver module (ED_PIN) awake, ED_PIN receives an IO sample every second

while the ED_CYCLIC is awake (ST val ue is two seconds). After that, ED_CYCLIC goes to sleep for nine seconds (SP parameter). The cycle then starts over again.

XBee® Zigbee® Mesh Kit

Page 94

Low power and battery life Example: enable sleep mode

Note Make sure to close the serial connection with the module when you finish the example.

Step 5: What have you learned?

In this section, you have learned that:

n Modules with Zigbee protocol, as well as others, can go into a temporary sleep state in which

they consume virtually no current. In Zigbee, only the modules configured as End Devices can go to sleep.

n When an end device is asleep its parent (the router or coordinator that allows the end device to

join the network) buffers its data until a timeout expires (SP), or until the end device sends a poll request to retrieve the data.

n Pins 9 and 13 are related to the sleep modes. You can use pin 9 to put the module to sleep, and

pin 13 to determine the sleep state of the device.

n While an XBee is in sleep mode, there is no data transmission or reception. If you try to

communicate with the module when it is asleep, XCTU displays a warning message saying that the module must be reset to wake up.

n To configure your module to go to sleep, you must configure the following parameters:

l Sleep Mode (SM):

Pin sleep mode (SM = 1) pull high pin 9 by connecting it to 3.3 volts to put the module to sleep. The module will wake up when pin 9 is de-asserted (low).

Cyclic sleep modes (SM = 4 and SM = 5) enable the module to sleep and wake up on a fixed schedule. These modes need the ST and SP parameters to be configured.

l Time before Sleep (ST) is the period of time during which no data is sent or received (while

the module is awake) before returning to cyclic sleep. This parameter is only applicable for cyclic sleep modes.

l Cyclic Sleep Period (SP) is the length of time an XBee remains asleep. This parameter is

only applicable for cyclic sleep modes.

Step 6: Extend the example

If you are ready to move beyond this exercise and extend the example, try the following:

n Connect a battery to ED_CYCLIC (XBee B), ED_PIN (XBee C), or both and move the modules

away from COORD (XBee A).

n Combine this feature with a real sensor to create a low-power sensor network.

XBee® Zigbee® Mesh Kit

Page 95

Inputs and outputs

All XBee modules have a set of pins that can be used to connect sensors or actuators and configure them for specific behavior. Each XBee radio has the capability to directly gather sensor data and transmit it without the use of an external microcontroller.

With these pins you can, for example, turn on a light by sending information to an XBee module connected to an actuator, or measure the outside temperature by obtaining data from a temperature sensor attached to your XBee module.

Learn about I/O pins, sensors, actuators in this section, then put your knowledge to work by using sensors.

XBee I/O pins 96 Sensors 97 Actuators 98 Set pins for digital and analog actuators 98 How XBee devices get sensor data 98 Example: receive digital data 100 Lab: receive analog data 110 How XBee modules control devices 119 Example: send digital actuations 121

XBee® Zigbee® Mesh Kit

Page 96

Inputs and outputs XBee I/O pins

XBee I/O pins

The following table shows the I/O pins of the XBee THT and XBee SMT modules:

XBee THT Model

XBee SMTmodel

XBee® Zigbee® Mesh Kit

Page 97

Inputs and outputs Sensors

Pin name Physical pin# Parameter

THT SMT

DIO0, AD0 20 33 D0

DIO1, AD1 19 32 D1

DIO2, AD2 18 31 D2

DIO3, AD3 17 30 D3

DIO4 11 24 D4

DIO5 15 28 D5

DIO6 16 29 D6

DIO7 12 25 D7

DIO8 9 10 D8

DIO9 13 26 D9

DIO10, PWM RSSI 6 7 P0

PWM1, DIO11 7 8 P1

DIO12, PWM2 4 21 P2

DIO13 2 3 P3

DIO14 3 4 P4

DIO15 — 17 P5

DIO16 — 16 P6

DIO17 — 15 P7

DIO18 — 14 P8

DIO19 — 12 P9

(D = digital, I = input, O = output, AD = analog input, PWM = pulse-width modulation, — not available)

Note The number and type of IOs available can vary between different module variants.

Sensors

A sensor is a device that detects events or changes and provides a corresponding output, generally as an electrical signal.

There are two types of sensors: digital and analog. A motion sensor is a digital sensor because it can return two discrete values: movement detected or movement not detected. Other digital sensors might provide a binary value. A digital compass, for example, may provide your current heading by sending a 9-bit value with a range from 0 to 359. On the other hand, a thermometer is an analog sensor because the voltage output changes gradually as the temperature changes.

XBee® Zigbee® Mesh Kit

Page 98

Inputs and outputs Actuators

Setting pins for digital and analog sensors

Configure the pin of your XBee module according to the sensor that is connected to it:

n If you connect a digital sensor, configure the pin as Digital Input.

n If you connect an analog sensor, configure the pin as Analog to Digital Converter (ADC).

Note For more information about sensors, see the How XBee devices get sensor data section.

Actuators

An actuator is a device that is responsible for controlling a mechanism or system. The XBee device offers some simple output functions so that basic actuations can take place. For example, you can send digital information directly to an XBee device and direct it to turn on a light or start up a motor.

Set pins for digital and analog actuators

Configure the pin of your XBee device according to the actuator that is connected to it:

n If you connect a digital actuator, configure the pin as Digital Output.

n If you connect an analog actuator, configure the pin as PWM (analog output).

For more information about sensors, see How XBee modules control devices.

How XBee devices get sensor data

XBee devices are often used to form sensor networks. In a sensor network, the main device—also called the local XBee device—receives data from the sensors attached to the remote XBee devices.

To receive that data, you must configure the remote XBee devices to "listen" on the particular pin where the sensor is connected and to send the data to the main XBee device.

XBee® Zigbee® Mesh Kit

Page 99

Inputs and outputs How XBee devices get sensor data

How to configure a pin as an input

Configure a pin for digital input

You can configure a pin through XCTU. If your sensor reads digital values (like a doorbell) and is connected to the DIO1/AD1 pin, configure the D1 parameter as Digital Input [3]:

Configure a pin for analog input

If your sensor reads analog values (like a temperature sensor) and is connected to the DIO1/AD1 pin, configure the D1 parameter as ADC [2]:

How to obtain data from a sensor

There are two ways to obtain sensor information:

n Queried sampling to immediately read all enabled digital and analog input pins.

n Automatic sampling to transmit the sensor data periodically or whenever a digital pin changes.

In both cases, the information is sent to the other module is called IO sample. It contains which inputs (DIO lines or ADC channels) have sampling enabled and the value of all the enabled digital and analog inputs.

Queried sampling (IS)

The Force Sample (IS) command forces a read of all enabled digital and analog input pins. You can send it locally or to a remote device.

Use the XCTU console or any serial port terminal application to send this command.

When the module sends the IS command, the receiving device reads all enabled digital IO and analog input channels and returns their value. If the module transmits the IS command locally, it sends the IO data out the serial interface. If the module transmits the IS command to a remote XBee module, it sends the remote IO data over the air to the requester module.

Automatic sampling

Once you have set up the pin, the remote module must be configured to automatically transmit the sensor information to the main XBee module. The remote XBee module needs to know:

1. Where to transmit the sensor data: define this information for the module receiving this

information by the destination address (DH + DL) parameters.

2. When to transmit the sensor data:

n Periodically: The XBee can send the information read from the sensor at a specified

interval.

n By change detection: When a pin or several pins change status.

Configure parameters IO Sampling Rate (IR) and Digital IO Change Detection (IC) to automatically transmit the sensor data.

XBee® Zigbee® Mesh Kit

Page 100

Inputs and outputs Example: receive digital data

Note These two features can work in combination with each other, depending on your requirements.

For example, you could choose to receive an IO sample every minute (IR) but also when a certain pin changes state (IC).

IO Sampling Rate (IR)

The IR parameter sets the I/O sample rate: that is, how frequently to report the current pin state and transmit it to the destination address. The rate is set in milliseconds using hexadecimal notation. The value 0 disables the feature.

For example, if you want to transmit the sensor info every minute, set this parameter to EA60 (1 minute = 60 seconds = 60000 ms = EA60 hex).

Use XCTU to configure the sample rate interval.

Note Sleeping devices, configured to send samples periodically, transmit the first sample immediately

after waking up, and then continue sending periodic IO samples at the IR rate, until the Time Before Sleep (ST) timer expires and the device can resume sleeping.

Digital IO Change Detection (IC)

The IC parameter allows you to set which pins to monitor for change detection. When the state of the monitored pin(s) changes, a sample is immediately sent to the destination address.

Use XCTU to set the value of IC parameter.

To select which pins monitor, assign a binary value to IC parameter based on the following pattern:

DIO12 DIO11 DIO10 DIO9 DIO8 DIO7 DIO6 DIO5 DIO4 DIO3 DIO2 DIO1 DIO0

0 0 0 0 0 0 0 0 0 0 0 0 0

For example, if you want to monitor DIO1, the value would be 0000000000010, which is 2 in hexadecimal notation. If you want to monitor DIO12, DIO8, DIO3 and DIO1, the value would be 1000100001010 (binary) = 110A (hexadecimal). The value 0 disables the feature.

The Digital IO Change Detection (IC) feature only works for digital pins, so you will not receive anything if the value of an analog pin changes.

If an XBee module is sleeping, changes in any of the monitored pins will not wake the module.

Example: receive digital data

This section teaches you how to create an XBee digital sensor network. Since the kit does not contain a real sensor, you simulate a digital sensor with the user button of the XBee Grove Development Board.

XBee® Zigbee® Mesh Kit

100