Getting Started with BeagleBone Green

This guide teaches you how to get started using the BeagleBone Green development board with Atmosphere. This includes creating your first project, putting the project’s firmware onto the board, getting the board registered to Atmosphere, and having its data displayed on a dashboard.

This guide demonstrates how to build a simple project that reads temperature data using a Seeed Studio Grove Temperature Sensor, sends that data to the cloud, and displays the data on a graph on your dashboard.

Prerequisite: You should already have an Atmosphere account.

If you'd like to see the complete demo before attempting this guide, the project created here is available in Atmosphere Studio's Demo Projects section as the Grove Temperature Sensor Demo. Simply open the project to check it out and get started.

Hardware Requirements

In this guide we’re using the standard version of the BeagleBone Green with Ethernet for connectivity, but the wireless variant will work just as well. Note if using the wireless version of the board, visit our BeagleBone Green resource page for information on enabling Wi-Fi on the board.

Users are expected to have a moderate understanding of working with a BeagleBone and embedded Linux systems prior to use with Atmosphere. It's recommended to read the Official BeagleBoard Resources or Seeed BeagleBone Green Documentation for information on configuring the board, user credentials, installing firmware, and usage details.

In addition to the board itself, we also have a Seeed Studio IOT Developer Prototyping Kit to take advantage of the additional hardware that comes in the package, notably the Grove Base Cape and the Grove Temperature Sensor. These accessories can be purchased separately in the event you don’t wish to use the entire kit.

Hardware Setup

The hardware configuration involves connecting the Grove Base Cape to the BeagleBone Green, and then connecting the sensor to the A0 analog input on the cape. This gives us access to the sensor from one of the board’s analog pins.

The finished setup should resemble the following image:

BeagleBone Hardware Setup

Software Requirements

  • None

Although there aren’t any specific software requirements for using the BeagleBone Green with Atmosphere itself, you’ll need the appropriate operating system drivers for working with the board, the terminal of your choice to interface with the board, and SSH client of your choice to transfer files to it.

Step 1 of 7: 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 New Project button. This displays a New Project window.
  2. Select the BeagleBone Green 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 7: 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 Grove temperature element, which isn’t native to BeagleBone Green projects. So we’ll add it through the Studio Embedded tab’s Element Library.

  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. BeagleBone Guide Element Library
  2. In the Element Library, locate the Grove temperature element, and turn on the enable switch in its row. When done click Save, and the element is added into the Embedded tab’s toolbox.

Step 3 of 7: 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 embedded data, and to tell the interval to read the Grove sensor’s temperature data.

  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).
    • Grove Temperature Element Grove temperature element: The Grove temperature element reads data from the Grove Temperature Sensor.

    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 Grove temperature 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 Read Temperature (°C). This means that when the interval element is triggered (which is every second), it will read the temperature data of 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 second, and when run will read the Grove sensor’s temperature data.

The Embedded tab canvas should resemble the following image:

BeagleBone Green Embedded Tab

Step 4 of 7: Enable the Project’s Cloud Connectivity

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

  1. While still in the Embedded tab, add a Cloud Event Element cloud event element to the canvas. The cloud event element is a coupled element between the Embedded and Cloud tabs that enables a project’s data to be sent to Atmosphere.
  2. Connect the Grove temperature element to the cloud event element. In the connector’s properties between the two elements, select the Temperature Read trigger, then add an event with the ability Send Event. This sends the value to Atmosphere when the temperature is read.
  3. Click the Cloud tab to move to the cloud area of the project. Notice how the Element Toolbox has changed, and that the coupled cloud event element is displayed on the canvas. From the Cloud tab, add a Cloud Meta Element cloud meta element to the canvas. This element allows you to change the meta information of a device on Atmosphere, such as its geolocation or status.
  4. Add a Cloud Storage Element cloud storage element to the canvas, and connect the existing cloud event element to it. By default, this creates an event using the Add Data ability within the cloud event’s Event Received trigger, which allows Atmosphere to add (and store) data sent to it from the cloud event element.
  5. Within the Add Data event, modify the event’s Value field to {"Temperature": value}, which will label the dataset as “Temperature” when displayed in the cloud.

That’s all for creating the project! With the added cloud connectivity, the project will send the sensor’s temperature data from the Embedded tab to the Cloud tab through a cloud event element, where it’s connected to a cloud storage element to store the data on Atmosphere.

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

Embedded Cloud
BeagleBone Green Embedded Tab BeagleBone Green Cloud Tab

Step 5 of 7: Put Firmware onto the BeagleBone Green

With the project complete, your BeagleBone Green is ready to have the project firmware put onto it and then running the file as an executable application.

Prior to putting firmware onto the BeagleBone Green, ensure you have the following setup configuration:

  • The BeagleBone Green is powered on.
  • An Internet connection is maintained.
  • A means to interact with the board using the terminal of your choice.
  • A method for putting the firmware onto the board via SSH.

With setup complete, you can program the BeagleBone Green:

  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. This readies the entire project’s source code for deployment.
  2. While the Embedded tab is active, click the Program Firmware button from the tab’s toolbar. This downloads a firmware.zip that contains the project’s compiled firmware.
  3. Login to the BeagleBone Green, then put the zip file onto the BeagleBone Green using the SSH client of your choice.

Once the download/transfer is complete, the BeagleBone Green has the project zip file on it, which hasn’t been unzipped and can’t yet be run. Steps to run the application are included below as part of registering the BeagleBone Green.

Step 6 of 7: Register the BeagleBone Green to Atmosphere

Connecting the BeagleBone Green to Atmosphere involves generating an API token in Atmosphere, and providing that token in a terminal when an application attempts to execute. Once the token is provided, the BeagleBone Green will register to Atmosphere automatically as long as the Internet connection is maintained.

To run an Atmosphere application and register the BeagleBone Green:

  1. While in Atmosphere open the account menu from the navigation bar and click Security.
  2. In the Security section’s Authentication Tokens area, click the Generate Token button to make a new API token. This will be the token you use to provide the BeagleBone Green with the credentials to connect to Atmosphere. BeagleBone Green API Token

Once you’ve created an API token, it then has to be provided once you run the app.

  1. Unzip the firmware by running unzip firmware.zip from a terminal. This extracts a binary firmware file, a device configuration file, and a setup script file. The setup script file runs the application on the BeagleBone Green and initiates communication with Atmosphere, so that’s what we’ll be using.
  2. Run chmod +x ./setup.sh to make the setup script executable, and then execute it using sudo ./setup.sh.
  3. When prompted for a password, enter the password for the board.
  4. When the setup file attemptes to execute, you’ll be prompted to enter an API key. This is the API token you generated earlier; enter the key and submit.

Once the API token is entered, the application executes and initiates communication with Atmosphere, and the BeagleBone Green registers itself as a device and is displayed in the platform’s Devices area. The application then installs itself as a system service on the BeagleBone Green. If the BeagleBone Green is powered off and on again, the application will run on boot with other system services; the above steps only need to be completed once in order to run the application and register the BeagleBone Green.

The complete registration process should resemble the following command line output:

debian@beaglebone:~$ unzip firmware.zip
Archive: firmware.zip
    inflating: Atmosphere_Project.bin
    inflating: projectConfiguration.sh
    inflating: setup.sh
debian@beaglebone:~$ chmod +x setup.sh
debian@beaglebone:~$ sudo ./setup.sh
[sudo] password for debian:
== Atmosphere IoT BeagleBone Green Setup ==

Please enter your API Key:
1ab234c5-6d78-1234-abc1-d23456ef78a9
Registering Project Atmosphere Demo to https://platform.atmosphereiot.com...
Registration Successful...
Installing Atmosphere System Service...
Installing Atmosphere_Project.bin to /usr/bin...
Stopping Atmosphere System Service...

At this point, the application is running and the temperature data is sent to Atmosphere through the Internet connection maintained on the BeagleBone Green.

Step 7 of 7: View Temperature Data

Now that data is being sent to Atmosphere, let’s view it through one of the many dashboard widgets available. In this guide we’ll use a data graph widget to chart the temperature data. We’ll do this directly on the device’s console page, so click on the newly-added BeagleBone Green to enter its console.

  1. To add a widget to the device’s dashboard, click the Configuration button on the right side of the screen. This displays the menu of available widgets. Select the Data Graph data graph widget to add a data graph to the dashboard.
  2. Once on the dashboard, click the widget’s Menu menu icon to display its menu, then click Settings.
  3. Give the data graph a name (such as “BeagleBone Grove Temperature”), then in its Data Source field click Select and choose the following configuration options for the widget:
    • Cloud Storage: Select the cloud storage (TempStorage, or whatever you named your cloud storage) that is storing the temperature data.
    • X-axis Value: Select the timestamp to go along the graph’s x-axis.
    • Y-axis Value: Select the temperature’s dataset to go up the graph’s y-axis (Temperature, unless you provided a custom label for the cloud event data).
  4. When finished click Save. This populates the data graph plotting the temperature value as time progresses. If you’d like to adjust the graph’s timeline, bounds, or colors, you can edit those properties from the data graph’s menu as well.

BeagleBone Green Guide Dashboard

Congratulations, you just finished a complete BeagleBone Green project with Atmosphere!