Using the Atmosphere IoT Agent as a Zigbee Gateway

This guide demonstrates how to create a Zigbee mesh network that uses a computer running the Atmosphere IoT Agent as the network gateway, which forwards data to Atmosphere. This involves creating an Atmosphere project for an end node device that reads and sends data, and uses a centralized coordinator device that receives that data, which via the agent has it sent to Atmosphere.

The basic premise behind creating this network is demonstrated in the diagram below:

Agent Gateway Architecture

A Zigbee network consists of 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.

In the guide you’ll build an application that includes one end node device and a coordinator device. The end node records integer data and increments it, and broadcasts it to the Zigbee network where the coordinator device receives that data. The agent operating as a gateway for the network then forwards the data to Atmosphere, where it’s displayed on a data glance widget on the device console’s dashboard.

Prerequisite: You should already have an Atmosphere account.

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 IoT Studio’s Element Library.

For the purposes of this guide we choose the Arduino Due as our end node device, but any Atmosphere-supported hardware that is compatible with the XBee3 Zigbee Mesh Kit could be used to build this type of project.

Hardware Setup

Setting up the hardware involves connecting pins from an XBee Grove Development Board to the Arduino Due. 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

Arduino Due End Node 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 Due:
    • 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 Arduino Due:
    • GND: connect GND from the Arduino Due to pin 1 (GND) on the XBee
    • TX: connect pin 18 (TX) on the Arduino Due to pin 4 (DIN) on the XBee
    • RX: connect pin 19 (RX) on the Arduino Due to pin 3 (DOUT) on the XBee
  4. Connect an antenna to the XBee board, and when in use connect both the Arduino Due and the XBee board to a power source.

The finished setup should resemble the following image:

Digi XBee3 Zigbee Arduino Due Setup

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

XBee Grove Development Board Coordinator Setup

  1. Connect an XBee3 Zigbee SMT module into an available XBee Grove Development Board.
  2. Connect an antenna to the XBee board, and when in use connect the XBee board to your computer.

Software Requirements

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.

In this guide, the Atmosphere IoT Agent will also be configured to operate as a gateway for Zigbee applications. When configured, the agent acts as the gateway for the Zigbee network’s coordinator device as long as the device is connected to the computer running the agent. This enables end node devices on the network to communicate with the Zigbee coordinator, which then has data sent to Atmosphere via the agent through the computer’s Internet connection. Data will be forwarded via the agent to the configured URL as long as the computer’s Internet connection is maintained. If the computer loses its Internet connection, data received from network end node devices during that time will be lost.

Step 1 of 8: Configure the Atmosphere IoT Agent as a Gateway

The first thing needed for creating this Zigbee network is setting up the coordinator device. In this guide, the XBee Grove Development Board connected to the computer assumes the role of coordinator. The coordinator is what establishes and hosts the Zigbee network, and is also what we’ll use to receive network data from the Arduino Due end node.

The coordinator’s network is determined by a configuration provided by the Atmosphere IoT Agent, which also operates as the network gateway to send received data to Atmosphere. To get the network created, we’ll set the configuration for the agent first.

Close the Atmosphere IoT Agent prior to modifying any configurations.

  1. Locate the agent’s user account folder on your system. The folder is located in a path such as C:\Users\Username\.atmosphereiotagent, though the location may vary based on your operating system.
  2. In the .atmosphereiotagent folder, open the settings.json file in a text editor. This file is used to set custom gateway configurations for the agent. The file should resemble the following default configuration:
         "gateway": {}

    Having never been modified, the file includes empty gateway settings.

  3. To configure the agent as a gateway and set the Zigbee network details, modify the file to provide the following:
         "gateway": {
             "url": "",
             "zigbee": {
                 "networkId": "AtmoIoT",
                 "comPort": "YourDeviceCOMPort",
                 "baudRate": 9600
    • URL: The URL the data is sent to. In this case we’re sending it to Atmosphere, so it’s using the Atmosphere IoT Platform URL.
      • If this project is being built on a platform variant that uses a different URL (such as DK IoT Studio), replace the URL with the variant URL.
    • Network ID: The unique Zigbee network the data is sent to. AtmoIoT is what we’ll name the network the coordinator will create and host. This will also be entered in the Atmosphere project for the end node device.
    • COM port: The COM port the coordinator device is connected to. Replace the COM port entry with the port your XBee Grove Development Board is connected to on your computer.
    • Baud rate: The rate data is sent by the coordinator device. The baud rate is recommended to remain at 9600 as this is a tested rate verified to work properly, though advanced users may modify this to a rate of their liking.
  4. When finished, save the updated file. Run the agent for the gateway configurations to take effect, which then initializes the coordinator device to establish the AtmoIoT Zigbee network.

With the Atmosphere IoT Agent configured with the Zigbee settings, it will work alongside a Zigbee application using the specified network ID. Now that the coordinator device is hosting the AtmoIoT Zigbee network, it will receive data from any end nodes connected to the network. The next step is to create the project for the Arduino Due as an end node to send data to the network.

Step 2 of 8: Create a New Project

Navigate to Atmosphere Studio from the side menu. When you visit Studio for the first time in a session, you are brought to the Studio Projects screen.

  1. Click the Add Element button. This displays a New Project window.
  2. Select the Arduino Due project type and give the project a name, then click Create.

This opens a new project in Studio.

Step 3 of 8: Create the Project’s Embedded Firmware

The first aspect of building this sample project is adding elements to the Embedded tab to create the project’s embedded firmware. This involves setting an interval to run every second, and when run initiates a counter to increment an integer value.

  1. Add the following elements to the canvas by clicking them in the Element Toolbox:
    • Interval Element Interval element: The interval element sets the project to run at the time set in the element’s properties, which by default is set to once per second (1000 ms).
    • Counter Element Counter element: The counter element allows you to implement a periodic software counter.

    Each of these elements will work as intended by default, so none of their properties need to be changed.

  2. Connect the interval element to the counter element. This creates an event between them, which can be seen in either the interval element’s properties, or by clicking the connector’s Configuration Button button. The event added is within the Interval trigger. In the Ability field within the event, set the ability to Increment Value. This means that when the interval element is triggered (which is every second), it will increment the integer value. The counter element’s default properties set the Initial Value field to 0, so the increment begins at that number.

That wraps up the first aspect of the project within the Embedded tab. To this point, an interval has been set that will run every second, and when run will increment a value starting at 0 from the counter element. When the counter reaches 10, the counter will rollover back to 0.

The Embedded tab canvas should resemble the following image:

Arduino Due Embedded Tab

Step 4 of 8: Enable the Project’s Zigbee Connectivity

The second aspect of building this sample project is enabling it to communicate to a Zigbee network. This involves adding an XBee3 Zigbee element from the Element Library into the project and configuring it to broadcast to the AtmoIoT network.

  1. From the Embedded tab, click the Add Element Add Element button located in the bottom of the Element Toolbox. This opens the Element Library, which includes numerous elements for sensors and other devices that can be incorporated into a project. Element Library
  2. In the Element Library, locate the XBee3 Zigbee element in the table and turn on its enable switch by clicking it to import it into the Element Toolbox. When done, click Save.
  3. Add an XBee3 Zigbee element to the canvas from the Element Toolbox, then click it to view its properties.

    When the XBee3 Zigbee element is added to the canvas, notice that cloud elements (Device Event and Cloud Event) are then populated into the toolbox. By adding a connectivity aspect to the project, these elements are now accessible for use.

  4. To start, the Zigbee network needs to be defined. In the XBee3 Zigbee element’s Network ID field, change the network ID to AtmoIoT to match the network configured earlier for the Atmosphere IoT Agent.
  5. Next, change the Device Role field to End Node. This determines the role of the device on the AtmoIoT network, which for the Arduino Due is an end node. As an end node, it will connect and send data to the coordinator device that shares the network ID.

With the XBee3 Zigbee element set up, the Arduino Due can identify as an end node device on the AtmoIoT network.

Step 5 of 8: Enable the Project’s Cloud Connectivity

The last aspect of building this sample project is enabling it for cloud connectivity. This is done on both the Embedded and Cloud tabs.

  1. From the Embedded tab, add a Device Event Element Device Event element to the canvas. The Device Event element is a coupled element between the Embedded and Cloud tabs that enables a project’s data to be sent to Atmosphere.
  2. Click the Device Event element, and in its properties change the Cloud Driver Instance field to XBee3 Zigbee. This specifies the HTTP instance the Arduino Due uses to send data to Atmosphere. By selecting the Zigbee instance, it ensures data is sent over the Zigbee network to Atmosphere.
  3. Connect the counter element to the Device Event element. In the connector’s properties between the two elements, select the Value Incremented trigger, then add an event with the ability Send Event. This sends the value to Atmosphere when the integer is incremented.
  4. Click the Cloud tab to move to the cloud area of the project. Notice how the Element Toolbox has changed, and that the coupled Device Event element is displayed on the canvas.
  5. Add a Cloud Storage Element cloud storage element to the canvas, and connect the existing Device Event element to it. By default, this creates an event using the Add Data ability within the Device Event’s Event Received trigger, which allows Atmosphere to add (and store) data sent to it from the Device Event element.
  6. Within the Add Data event, modify the event’s Value field to {"Integer Count": value}, which will label the incrementing value dataset as “Integer Count” when displayed in the cloud.

That’s all for creating the project! With the added cloud connectivity, the project will send the integer value from the Embedded tab to the Cloud tab through a Device Event element, where it’s connected to a cloud storage element to store the data on Atmosphere. Overall, the integer value will be sent by the Arduino Due over the AtmoIoT Zigbee network, where it’s received by the XBee Grove Development Board. The received data is then sent to Atmosphere via the Atmosphere IoT Agent.

The final canvas for each tab should resemble the following images:

Embedded Cloud
Arduino Due Embedded Tab Arduino Due Cloud Tab

Step 6 of 8: Program Firmware into the Device

With the project complete, your Arduino Due is ready to be programmed with its embedded firmware.

Prior to programming, ensure you have the following configuration:

  • The Arduino Due is connected to the computer via USB to an available communication port.
  • The Atmosphere IoT Agent is running.
  • An Internet connection is maintained.

With setup complete, you can program the board:

  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 be notified when the project is compiled. With the project compiled, your Arduino Due can be programmed.
  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 Arduino Due is connected to.
  4. Click Program to start programming. When complete, you’ll be notified that the device is programmed with the project’s embedded firmware.

Step 7 of 8: Register the Device

With firmware installed, the Arduino Due can now be recognized and connected to Atmosphere. Prior to connecting a device, ensure the Atmosphere IoT Agent is running in your system tray. This is needed to check your computer’s communication ports for a device it recognizes, which will find the Arduino Due.

To register the Arduino Due:

  1. Navigate to the Devices area, and click the Register Device Scan button in the top-right to display the Scan window. When the window opens it automatically starts scanning for available devices within range.
  2. The list of available devices appears. Select the Arduino Due you just programmed and click Register.
    • 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.

The device is now registered to Atmosphere and is displayed on the page, and its application starts running. At this point the integer data is being sent from the Arduino Due to the XBee Grove Development board connected to your computer, which is then sent to Atmosphere through the Atmosphere IoT Agent.

Step 8 of 8: View Device Data

Now that the device’s data is sent to Atmosphere, let’s view it through one of the many device dashboard widgets available. In this guide we’ll use a data glance to display the numerical value and view it increment. We’ll do this directly on the device’s console page itself, so click on the newly-added Arduino Due to enter its console.

  1. To add a widget to the device’s dashboard, click the Configuration button on the side of the screen. This displays the menu of available widgets. Select the Data Glance data glance widget to add a data glance to the dashboard.
  2. Once on the dashboard, click the widget’s Menu menu icon to display its menu, then click Settings.
  3. In the data glance’s settings, modify the following properties:
    • Name: Give the widget a name, such as “Zigbee Integer Counter.”
    • Icon: Select an icon that you think best represents the value.
    • Color: Give the widget a color.
  4. In the Data Source field, click Select, then choose the following configuration options for the widget:
    • Select Cloud Storage: Click the cloud storage that is storing the counter element data.
    • Select Value: Select the Integer Count dataset.
  5. When finished click Save. The data glance is then populated with the integer value, which updates every second.

Zigbee Integer Counter Dashboard

Congratulations, you just created a complete custom Zigbee mesh network application with Atmosphere!

What’s Next

Now that you’ve seen an example on how a Zigbee network is created with Atmosphere, it’s recommended you try this approach using multiple end nodes. The Digi XBee3 Zigbee Mesh Kit comes with a third available XBee Grove Development Board, so consider building another project to use that board as an end node that sends data to the network as well.

Alternative Zigbee Network Methods on Atmosphere

In addition to the steps detailed in this guide, a second method for creating and hosting a Zigbee network on Atmosphere is available. This involves connecting the coordinator device to a development board that uses its own connectivity for sending data to Atmosphere.

If you’re interested in building a Zigbee application that sends data between multiple boards, the Creating a Zigbee Mesh Network with Atmosphere guide provides a simple walkthrough for doing so.