Creating a Zigbee Mesh Network with Atmosphere

This guide demonstrates how to create a Zigbee mesh network that sends data between two devices, and then forwards that data to Atmosphere. This involves setting up two devices running Atmosphere projects: one end node device that reads and sends data, and one centralized coordinator device that receives that data and forwards it to Atmosphere. The basic premise behind creating this network is demonstrated in the diagram below:

Zigbee Architecture

Within a Zigbee network, there are two types of devices: end nodes and coordinators. End nodes are end devices on the network that broadcast data, and any number of end node devices can be supported within the network. Coordinators are central devices that create and host the Zigbee network, and receive data from any end nodes connected to the network. There can only be one coordinator device per network on Atmosphere. Data received by the coordinator device can then be sent to Atmosphere. Since data is sent to Atmosphere via the coordinator device, only that device needs to be registered to Atmosphere; end node devices aren’t required to be registered.

In the guide you’ll build an application that includes one end node device and a coordinator device. The end node reads temperature data from a shield’s temperature sensor and broadcasts it to the coordinator’s Zigbee network. The coordinator device then receives that data and sends it to Atmosphere, where it’s displayed on a data graph widget on the device console’s dashboard.

Prerequisite: You should already have an Atmosphere account.

It's recommended to have a moderate understanding of Atmosphere Studio prior to attempting this guide. The guide doesn't detail usage of Atmosphere Studio and presumes the reader understands basic concepts of Studio projects.

Hardware Requirements

The guide uses the Digi XBee3 Zigbee Mesh Kit, which comes with three XBee Grove Development Boards and three XBee3 Zigbee SMT modules. The XBee3 Zigbee SMT module is supported in Atmosphere through a dedicated XBee3 Zigbee element, located within Atmosphere Studio’s Element Library.

For the purposes of this guide we choose the Adafruit HUZZAH32 ESP32 Feather Board as our coordinator device and the Arduino Mega as our end node device, but any Atmosphere-supported hardware could be used to build this type of project. Likewise we’ve selected the SHT Click board plugged into the Arduino Mega to read temperature data since the board doesn’t come with sensors itself, but you can substitute this with a sensor or Click board of your choice.

Hardware Setup

Setting up the hardware involves connecting pins from the XBee Grove Development Boards to the HUZZAH32 and Arduino Mega. The board includes a left, bottom, and right column for pins. For reference, this XBee3 pinout diagram can assist with identifying pin locations:

XBee3 Pinout Diagram

HUZZAH32 Setup

  1. Connect an XBee3 Zigbee SMT module into an available XBee Grove Development Board.
  2. The following pins are used to attach to the HUZZAH32:
    • GND: left column, first pin down (pin 1)
    • DOUT: left column, third pin down (pin 3)
    • DIN: left column, fourth pin down (pin 4)
  3. Connect each of these three pins on the XBee board to the corresponding pins on the HUZZAH32:
    • GND: connect GND from the HUZZAH32 to pin 1 (GND) on the XBee
    • TX: connect pin 18 (TX) on the HUZZAH32 to pin 4 (DIN) on the XBee
    • RX: connect pin 19 (RX) on the HUZZAH32 to pin 3 (DOUT) on the XBee
  4. Connect an antenna to the XBee board, and when in use connect both the HUZZAH32 and the XBee board to a power source.

The finished setup should resemble the following image:

Digi XBee3 Zigbee HUZZAH32 Setup

Arduino Mega Setup

  1. Connect an XBee3 Zigbee SMT module into an available XBee Grove Development Board.
  2. The following pins are used to attach to the Arduino Mega:
    • GND: left column, first pin down (pin 1)
    • DOUT: left column, third pin down (pin 3)
    • DIN: left column, fourth pin down (pin 4)
  3. Plug the SHT Click board shield into the Arduino Mega.
  4. Connect each of these three pins on the XBee board to the corresponding pins on the Arduino Mega:
    • GND: connect GND from the SHT click/Arduino Mega to pin 1 (GND) on the XBee
    • TX: connect pin 17 (TX) on the Arduino Mega to pin 4 (DIN) on the XBee
    • RX: connect pin 16 (RX) on the Arduino Mega to pin 3 (DOUT) on the XBee
  5. Connect an antenna to the XBee board, and when in use connect both the Arduino Mega and the XBee board to a power source.

The finished setup should resemble the following image:

Digi XBee3 Zigbee Arduino Mega Setup

The listed pinout connections are based on use with the HUZZAH32 and Arduino Mega. If you're using a different device, be sure to connect the XBee3 pins to the corresponding pins for that board.

Software Requirements

Rather than building new coordinator and end node projects from scratch, we’re providing demo projects so you can simply program them and get started. We’ll cover what the projects do and how they work below.

The Atmosphere IoT Agent is a local application that runs in the system tray and acts as an intermediary between the computer’s connectivity protocol drivers and the browser running Atmosphere, and is used here to assist in programming the device and connecting it to Atmosphere. While the agent is running, a device with Atmosphere firmware installed on it can be registered to Atmosphere directly without the assistance from an additional connection like BLE or Wi-Fi if it’s connected to your computer.

The project in this guide doesn’t use Studio’s Application tab to build an app interface and since the HUZZAH32 will be registered to Atmosphere directly via a UART connection with your computer, the Atmosphere IoT app is not required here. However if you’ve elected to use a development board other than the HUZZAH32 as your coordinator device, note you may require the app and have different programming instructions than what is detailed below.

Step 1 of 6: Open the Coordinator Project

The first thing needed for creating a Zigbee mesh network is setting up the coordinator device. The device designated as the coordinator is what establishes and hosts the Zigbee network, and is also what we’ll use to receive network data and send that data to Atmosphere.

When setting up a Zigbee network, it's recommended to establish the coordinator first prior to getting any end node devices online. Otherwise the end nodes will broadcast to a network that doesn't yet exist, and they may take some time connecting to the network if done out of sequence.

  1. Click the Digi XBee3 Zigbee Receiver Demo listed above in the Software Requirements section. This brings you into Atmosphere Studio with the HUZZAH32 coordinator project open. Zigbee Receiver Demo Embedded Tab The premise of the XBee3 Zigbee Receiver Demo is to receive Zigbee network data (specifically temperature data), and send it to the cloud. This is enabled through the XBee3 Zigbee Element XBee3 Zigbee element, which has been imported from the Studio Element Library. The XBee3 Zigbee element is connected to a Debug Print Element debug print element to view data on a debug console (optional), and to a Cloud Event Element cloud event element to have data sent from the Zigbee network to the cloud over Wi-Fi. If you head over to the Cloud tab, you’ll see the cloud event element connected to a Cloud Storage Element cloud storage element to store the data sent to the cloud.
  2. Return to the Embedded tab, and select the XBee3 Zigbee element to view its properties. XBee3 Zigbee Receiver Element PropertiesThe following properties are essential for establishing the Zigbee network:
    • Network ID: The unique Zigbee network the data is sent to. This can be anything you like as long as it’s a valid string. In this case, we’re setting it to AtmoIoT. If a device is designated as a coordinator, it will create a Zigbee network under that ID. If a device is designated as an end node, it will instead connect and send data to the coordinator that shares that network ID.
    • Device Role: This determines the role of the device, which in this project is set to Coordinator. As the coordinator, the HUZZAH32 is the device that creates and hosts the Zigbee network, and receives data from any end nodes connected to the network.

To recap the Digi XBee3 Zigbee Receiver Demo, the XBee3 Zigbee element is set up as a coordinator device that creates and hosts the unique Zigbee network “AtmoIoT,” and as the coordinator receives temperature data sent on the network. Received data will be printed on a debug console, and sent to the cloud via Wi-Fi.

Step 2 of 6: Program the Coordinator Device

With the completed project in hand, all that’s needed for the HUZZAH32 is to program the firmware.

Prior to programming, ensure you have the following configuration:

  • The device is connected to the computer via USB to an available communication port.
  • The Atmosphere IoT Agent is installed on the computer and running.
  • An Internet connection is maintained.
  1. Click the Compile button in the project options menu on the top-right of the screen. You’ll see a loading message on the screen indicating compiling has started, and will receive a notification when the project is compiled. With the project compiled, your HUZZAH32 can be programmed with the project’s embedded firmware.
  2. While the Embedded tab is active, click the Program Firmware button from the tab’s toolbar. This displays the Program Firmware window.
  3. Under Device Port, select the communication port the device is connected to.
  4. Click Program to start programming. When complete, you’ll receive a notification stating the device is programmed with the project’s embedded firmware.

At this point with the HUZZAH32 powered on and programmed, it will immediately create and host the AtmoIoT Zigbee network.

Step 3 of 6: Open the End Node Project

With the Zigbee network created via the coordinator device, now we’ll need to add an end node, which is what we’ll use our Arduino Mega as. The end node will be reading data and broadcasting it to the network.

  1. Click the Digi XBee3 Zigbee Sender Demo listed above in the Software Requirements section. This brings you into Atmosphere Studio with the Arduino Mega end node project open. Zigbee Sender Demo Embedded Tab The premise of the XBee3 Zigbee Sender Demo is to run the project once per second using an Interval Element interval element that reads temperature data from the Sensirion SHTx element SHT shield element, converts that data using two Data Type Conversion Element data type conversion elements into a readable string for the Zigbee network, and then prints that data to a debug console and sends it to the Zigbee network specified in the XBee3 Zigbee element’s properties.
  2. Select the XBee3 Zigbee element to view its properties. XBee3 Zigbee Sender Element PropertiesThe following properties are essential for sending data to the AtmoIoT Zigbee network:
    • Network ID: By setting this to the ID used in the coordinator project (AtmoIoT), data sent from the Arduino Mega will be broadcast to that network.
    • Device Role: In this project the device is designated as an End Node. As an end node, the Arduino Mega is the device that connects to the network ID and broadcasts its data to it.

To recap the Digi XBee3 Zigbee Sender Demo, once per second the project will run that reads temperature data, converts that read data into a string, and prints it to a debug console and sends it to the AtmoIoT Zigbee network hosted by the coordinator device.

Step 4 of 6: Program the End Node Device

With the completed project in hand, all that’s needed for the Arduino Mega is to program the firmware.

Prior to programming, ensure you have the following configuration:

  • The device is connected to the computer via USB to an available communication port.
  • The Atmosphere IoT Agent is installed on the computer and running.
  • An Internet connection is maintained.
  1. Click the Compile button in the project options menu on the top-right of the screen. You’ll see a loading message on the screen indicating compiling has started, and will receive a notification when the project is compiled. With the project compiled, your Arduino Mega can be programmed with the project’s embedded firmware.
  2. While the Embedded tab is active, click the Program Firmware button from the tab’s toolbar. This displays the Program Firmware window.
  3. Under Device Port, select the communication port the device is connected to.
  4. Click Program to start programming. When complete, you’ll receive a notification stating the device is programmed with the project’s embedded firmware.

With the Arduino Mega powered on and programmed, it will immediately connect to the AtmoIoT Zigbee network and begin broadcasting the read data to it. If you have a debug console to read the temperature data from the device, you’ll see it update every second. Otherwise, the data can be displayed on the cloud using the steps below.

Step 5 of 6: Register the Coordinator Device

With project firmware installed on the coordinator device, it can now be recognized and connected to Atmosphere. As mentioned earlier, only the coordinator needs to be registered to Atmosphere, and end node devices connected to the network aren’t required to be registered.

To register a device:

  1. Navigate to the Devices area, and click the Register Device button in the top-right of the screen to display the Add Device window. When the window opens it automatically starts scanning for available devices within range.
  2. The list of available devices appears. Select the HUZZAH32 you just programmed and click Register. This brings you to the Wi-Fi settings screen.
    • If the device doesn’t show up, try restarting the agent in your system tray. If you do so, refresh your browser and try adding a device again.
  3. Configure your Wi-Fi network settings to connect the device. When Wi-Fi settings are entered, the HUZZAH32 will connect to Atmosphere over Wi-Fi and remain connected as long as the Wi-Fi connection is maintained.

The device is registered to Atmosphere and displayed on the page. Once registered, the coordinator is connected to Atmosphere, and over Wi-Fi sends the Zigbee network data it receives to Atmosphere.

Step 6 of 6: View Device Data

Now that the network data is sent to Atmosphere, let’s view it through one of the many dashboard widgets available. In the pre-built Digi XBee3 Receiver Demo, the device console’s dashboard comes pre-configured with a complete Data Graph data graph widget.

  1. In the Devices area, select your newly-added HUZZAH32 to enter its device console.
  2. On the device dashboard, a data graph widget will be configured on the dashboard. It may take up to a minute once you enter the device console for its configuration and data to populate.

Zigbee Guide Dashboard

The graph plots the temperature data as time progresses, which by default is set to the last ten minutes. If you’d like to adjust the graph’s timeline or its bounds, you can edit those properties from the data graph’s menu as well.

Congratulations, you just created your first custom Zigbee mesh network with Atmosphere!

What’s Next

Now that you’ve seen an example on how a Zigbee network is created with Atmosphere and how to setup the coordinator and end node devices, it’s recommended you try this with a new project using multiple end nodes. The Digi XBee Receiver and Sender demos are a great example for demonstrating how a Zigbee network is built, but these steps can just as well be applied using other devices, multiple sensors and datasets, and more.