Using Cellular Modems with Atmosphere
This guide demonstrates how to use a cellular modem to send data to Atmosphere. This includes connecting a cellular modem to the project’s hardware, creating an Atmosphere project, using the cellular network to send device data to the cloud, and then viewing the data in Atmosphere.
This guide involves building a simple project that reads temperature data, prints the data onto a debug console, and also sends the data to Atmosphere via the cellular network using the Digi XBee3 Cellular LTE Cat 1 modem.
Prerequisite: You should already have an Atmosphere account.
If you'd like to see the complete demo before attempting this guide, it's available in Atmosphere IoT Studio's Demo Projects section as the TE Weather Shield Cellular Demo. Simply open the project to check it out and get started.
The demo in this guide uses the Digi XBee3 Cellular LTE Cat 1 Development Kit, which comes with the embedded modem attached to a development board, SIM card for AT&T, and free cellular service for six months. This is convenient for testing purposes, and with free data available we can demonstrate the ease of use for getting started with cellular. The cellular modem is supported in Atmosphere through a dedicated XBee3 LTE CAT 1 element, located within Atmosphere IoT Studio’s Element Library.
For the purposes of this guide we used the Arduino Mega as our end device of choice, but any supported device that can manage a high storage of RAM (the XBee3 LTE CAT 1 element uses a high volume for storing HTTP packets) will work. In addition to the Arduino Mega, this includes the following devices supported in Atmosphere:
Likewise, ensure your device has more than one UART port available, as the XBee3 can’t be on the same UART that is used for programming or debug printing.
The Arduino Mega doesn’t include any onboard sensors, so we’re pairing it with the TE Connectivity Weather Shield to read sensor data from it. However if you’re using another supported device that comes with its own selection of sensors, you could use that instead.
Setting up the hardware involves connecting pins from the kit’s development board to your end device. We’re keeping the XBee3 modem attached to the board included in the development kit here and the setup below is based on this, but alternatively you can disconnect the modem if you have another intermediary board that can connect to your end device, such as an Arduino wireless shield.
NOTE: Pin headers don’t typically come included on the Digi XBee3 Development Board, so they may need to be soldered on prior to use.
For reference, this XBee3 pinout diagram can assist with identifying pin locations:
- To the left of the XBee3 modem are two rows of pins located on the development board. The following pins are used to attach to the Arduino Mega:
- Gnd: left column, bottom pin (pin 10)
- TX: left column, second pin down (pin 2)
- RX: left column, third pin down (pin 3)
- Plug the weather shield into the Arduino Mega.
- Connect each of these three pins on the Digi development board to the corresponding pins on the Arduino Mega:
- Gnd: connect gnd from the weather shield/Arduino Mega to gnd on the XBee3
- TX: connect pin 18 (TX1) on the Arduino Mega to pin 3 (RX) on the XBee3
- RX: connect pin 19 (RX1) on the Arduino Mega to pin 2 (TX) on the XBee3
- Connect an antenna to the XBee3 modem, and when in use connect the power supply.
The finished setup should resemble the following image (note the weather shield is not shown):
The listed pinout connections are based on use with the Arduino Mega. If you're using a different device, be sure to connect the XBee pins to the corresponding pins for that board.
- Atmosphere IoT Agent. 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. You can download the Atmosphere IoT Agent from its downloads page.
The project in this guide doesn’t use Studio’s Application tab to build an app interface and since the Arduino Mega (or device you’re working with) will be registered to Atmosphere directly via a UART connection with your computer, the Atmosphere IoT app is not required here.
NOTE: If working with the Rapid IoT for this demo, UART registration is unavailable. However if you have Bluetooth enabled on your computer, you may register the Rapid IoT via BLE while it’s connected to your computer without using the mobile app.
Step 1 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.
- Click the button. This displays a New Project window.
- Select the Arduino Mega (or whichever device you’re using) project type and give the project a name, then click Create.
This opens a new project in Studio.
This guide walks through the step-by-step process to perform actions in Studio, but doesn't cover the in-depth aspects of Studio itself. To learn more about using Studio, its areas and features, and Studio elements, visit the Atmosphere Studio section.
Step 2 of 8: Import Elements from the Element Library
Prior to building the project, the proper elements have to be added into Studio’s Element Toolbox. The project involves integrating the XBee3 modem and a sensor from the weather shield, neither of which are native to Arduino Mega projects. So we’ll add them through the Studio Embedded tab’s Element Library.
- From the Embedded tab, click the 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.
- In the Element Library, locate the XBee3 LTE CAT 1 element in the table and turn on its enable switch by clicking it to import it into the Element Toolbox.
- Next locate the TE Connectivity weather shield element(s), specifically the TSYS01 temperature sensor and enable it. If you’d like to add the other sensors from the shield, you could do so as well. When done click Save, and the elements are added into the Embedded tab’s toolbox.
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 read a temperature value every ten seconds, which will then be printed to a debug console.
- Add the following elements to the canvas by clicking them in the Element Toolbox:
- 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).
- Debug Print element: The debug print element prints data to a device’s primary debug UART console.
- XBee3 LTE CAT 1 element: The XBee3 LTE CAT 1 element is configured to work as intended by default, so none of its properties need to be changed. Likewise, it doesn’t need to be connected to any other element; if it’s included in the project it will work properly so long as the XBee3 modem is connected to the Arduino Mega.
When the XBee3 LTE Cat 1 element is added to the canvas, notice that cloud elements (Device Event and Cloud Event) are then included into the toolbox. By adding a connectivity aspect to the project -- since the Arduino Mega doesn't natively contain a connection option -- these elements are now accessible for use.
- TSYS01 element: The TSYS01 element reads temperature data from the weather shield’s onboard temperature sensor, and is also configured to work as intended by default so none of its properties need to be changed.
- Click the interval element to view its properties. In its properties area, change the Time field to
10000. This means the interval will run every ten seconds when the project starts.
- Click the debug print element, and in its properties change the Prepend Text field to
[TSYS01] Temp. This text, followed by a colon, will be prepended to eventual temperature data that will be printed to the UART console.
- Connect the interval element to the TSYS01 element. This creates an event between them, which can be seen in either the interval element’s properties, or by clicking the connector’s button. The event added is within the
Intervaltrigger. In the TSYS01 element’s ability field within the event, set the ability to
Read Temperature (°C). This means that when the interval element is triggered (which is every ten seconds), it will read the temperature value from the sensor.
- Next, connect the TSYS01 element to the debug print element, and set the event’s ability to
Temperature Readtrigger. This event performs prints read data to the UART console whenever temperature is read from the sensor.
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 ten seconds, and when run will read the temperature data from the weather shield’s temperature sensor via the TSYS01 element, which then has its value printed to a UART console.
The Embedded tab canvas should resemble the following image:
Step 4 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.
- While still in the Embedded tab, add a 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.
- Connect the TSYS01 element to the Device Event element. This adds the
Send Eventability within the event for the
Temperature Readtrigger, which sends data to Atmosphere whenever the temperature is read.
- 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.
- Add a cloud storage element to the canvas, and connect the existing Device Event element to it. By default, this creates an event using the
Add Dataability within the Device Event’s
Event Receivedtrigger, which allows Atmosphere to add (and store) data sent to it from the connected Device Event element.
That’s all for creating the project! With the added cloud connectivity, the project will send the read temperature value from the Embedded tab to the Cloud tab through a Device Event element every ten seconds, where it’s connected to a cloud storage element to store the data on Atmosphere.
Data generated in this demo project is typically sent to Atmosphere in ~1KB requests, so keep this in mind when monitoring your available cellular data. If you want to use less cellular data, it's recommended to slow the interval timer setting within the project to decrease the frequency of data requests.
The final canvas for each tab should resemble the following images:
Step 5 of 8: Compile the Project
Once the project is finished, it needs to be compiled. Compiling readies the entire project’s source code for deployment.
- From any tab, click the 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.
Step 6 of 8: Program Firmware into the Device
With the project compiled, your Arduino Mega can be programmed with the project’s embedded firmware.
Prior to programming a device, 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 and running.
- An Internet connection is maintained.
With setup complete, you can program your board:
- While the Embedded tab is active, click the button from the tab’s toolbar. This displays the Program Firmware window.
- Under Device Port, select the communication port the device is connected to.
- Click Program to start programming. When complete, you’ll be notified that the device is programmed with the project’s embedded firmware.
At this point with the Arduino Mega programmed, it will immediately begin reading temperature data. If you have a debug console to read data from the device, you’ll see it update every ten seconds. Otherwise, the data can be displayed on the cloud using the steps below.
Step 7 of 8: Register the Device
With firmware installed, the device can now be recognized and connected to Atmosphere. Prior to connecting a device, ensure your Atmosphere IoT Agent is running in your system tray. This is needed to check your computer’s communication ports for a device is recognizes, which will find the Arduino Mega.
To register the Arduino Mega:
- Navigate to the Devices area, and click the Scan button in the top-right of the screen to display the Scan window. When the window opens it automatically starts scanning for available devices within range.
- The list of available devices appears. Select the Arduino Mega 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 Arduino Mega will then connect to Atmosphere over the cellular (AT&T) network.
The device is now registered to Atmosphere and is displayed on the page.
Once the device is connected to Atmosphere, it will begin sending data to it. At this point your cellular data starts being consumed.
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 every few seconds. We’ll do this directly on the device’s console page, so click on the newly-added Arduino Mega to enter its console.
- To add a widget to the device’s dashboard, click the button on the right side of the screen. This displays the menu of available widgets. Select the data glance widget to add a data glance to the dashboard.
- Once on the dashboard, click the widget’s menu icon to display its menu, then click Settings.
- In the data glance’s settings, modify the following properties:
- Name: Give the widget a name, such as “Weather Shield Temp Data”
- Units: Enter
°Cfor its unit of measurement.
- Icon: Select an icon that you think best represents the value, such as
- Color: Give the widget a color.
- In the Data Source field, click Select, then choose the following configuration options for the widget:
- Select Cloud Storage: Click the cloud storage (
TempStorage, or whatever you named your cloud storage) that is storing the TSYS01 element’s data.
- Select Value: Select the temperature dataset (
TempEvent, or whatever you named your Device Event).
- Select Cloud Storage: Click the cloud storage (
- When finished click Save. The data glance is then populated with the temperature value, which updates every ten seconds.
Congratulations, you just finished a complete project sending device data to Atmosphere through a cellular modem!