Getting Started with mangOH Yellow

This guide teaches you how to get started using the mangOH Yellow 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 the mangOH Yellow’s GPS location, sends the data to the cloud over Wi-Fi, sets its geolocation position on the cloud, and displays the device’s location on a map 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 IoT Studio's Demo Projects section as the mangOH Yellow GPS Demo. Simply open the project to check it out and get started.

Hardware Requirements

Users are expected to have a moderate understanding of working with a mangOH Yellow and embedded Linux systems prior to use with Atmosphere. It's recommended to read the Sierra Wireless Resources for the mangOH Yellow for information on configuring the board and accessing its default user credentials.

Software Requirements

  • Windows systems require drivers for the mangOH Yellow’s CF3 module. This software is towards the bottom of this page and requires a user account which you can register for here.

Although there aren’t any specific software requirements for using the mangOH Yellow with Atmosphere itself, you’ll need to use the terminal of your choice to interface with the board and SCP client of your choice to transfer files to it.

Step 1 of 7: Create a New Project

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

  1. Click the New Project button. This displays a New Project window.
  2. Select the mangOH Yellow project type and give the project a name, then click Create. This opens a new project in IoT Studio.

This guide walks through the step-by-step process to perform actions in IoT Studio, but doesn't cover the in-depth aspects of IoT Studio itself. To learn more about using IoT Studio, its areas and features, and Studio elements, visit the Atmosphere Studio section.

Step 2 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 board’s GPS location.

  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).
    • mangOH GPS Element mangOH GPS element: The mangOH GPS element reads the GPS location of the mangOH Yellow. This is a sensor element exclusive to the mangOH Yellow, and is imported into its project type by default.

    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 mangOH GPS 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 Get 2D Position. This means that when the interval element is triggered (which is every second), it will read the GPS position (latitude and longitude) of the mangOH Yellow.

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 mangOH Yellow’s GPS data.

The Embedded tab canvas should resemble the following image:

mangOH Yellow Embedded Tab

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

The second and last 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 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. Connect the mangOH GPS element to the Device Event element. In the connector’s properties between the two elements, select the 2D Position Received trigger, then add an event with the ability Send Event. This sends the value to Atmosphere when the mangOH GPS position 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 Device 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. Connect the Device Event element to the cloud meta element, which creates an event within the Device Event’s Event Received trigger. In the Ability field within the event, set the ability to Set Geolocation Position. This means that when the GPS data is received, it will set the mangOH Yellow’s geolocation on Atmosphere.
  5. Within the Set Geolocation Position event, modify the event’s Longitude field to value.x and Latitude field to value.y. This sets the longitude and latitude for the geolocation position to the x- and y-coordinate values obtained from the GPS data, respectively.

That’s all for creating the project! With the added cloud connectivity, the project will send the GPS location data from the Embedded tab to the Cloud tab through a Device Event element, where it’s connected to a cloud meta element to set the mangOH Yellow’s geolocation on Atmosphere.

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

Embedded Cloud
mangOH Yellow Embedded Tab mangOH Yellow Cloud Tab

Step 4 of 7: Enable mangOH Yellow Wi-Fi

Prior to putting the project firmware on the mangOH Yellow, its Wi-Fi connectivity needs to be enabled and configured. The mangOH Yellow doesn’t have its Wi-Fi enabled by default, so we need to configure it with your network credentials beforehand.

The following process will initialize the onboard Wi-Fi:

  1. From a terminal of your choice, edit /etc/wpa_supplicant.conf to resemble the following configuration:
     ctrl_interface=/var/run/wpa_supplicant
     ctrl_interface_group=0
     update_config=1
    
     network={
     ssid="YOUR_SSID"
     psk="YOUR_PASSWORD"
     }
    
  2. Run the following commands from the terminal:
    • /legato/systems/current/modules/files/brcmutil/etc/init.d/cywifi.sh init
    • /legato/systems/current/modules/files/brcmutil/etc/init.d/cywifi.sh start
    • wpa_supplicant -B -Dnl80211 -iwlan0 -c /etc/wpa_supplicant.conf
    • udhcpc -R -b -i wlan0

When finished, this will initialize the Cypress Wi-Fi driver on the mangOH Yellow, connect to the specified Wi-Fi network, and obtain an IP address. After this, you can run ping google.com to test receiving a response and verify your device is connected.

This process must be run each time the mangOH Yellow boots. If the board is rebooted, the Wi-Fi will revert to being disabled.

Step 5 of 7: Put Firmware onto the mangOH Yellow

With the project complete and Wi-Fi connectivity enabled, your mangOH Yellow 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 mangOH Yellow, ensure you have the following setup configuration:

  • The mangOH Yellow is powered on.
  • An Internet connection is maintained.
  • You have a method for putting the firmware onto the mangOH Yellow via SCP.

With setup complete, you can program the mangOH Yellow:

  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. Put the zip file onto the mangOH Yellow using SCP, with the SCP client of your choice.

Once the download/transfer is complete, the mangOH Yellow 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 mangOH Yellow.

Step 6 of 7: Register the mangOH Yellow to Atmosphere

Connecting the mangOH Yellow 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 mangOH Yellow will register to Atmosphere automatically as long as the Internet connection is maintained.

To run an Atmosphere application and register the mangOH Yellow:

  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 mangOH Yellow with the credentials to connect to Atmosphere. mangOH Yellow 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 the firmware installer into a directory named atmosphere.
  2. Navigate inside the atmosphere directory.
  3. Run chmod +x ./setup.sh to make the setup script executable.
  4. Run ./setup.sh.
  5. When the 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 mangOH Yellow 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 mangOH Yellow. If the mangOH Yellow 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 mangOH Yellow.

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

root@swi-mdm9x28-wp:~# unzip firmware.zip
Archive:  firmware.zip
   creating: atmosphere/
  inflating: atmosphere/atmosphere.update
  inflating: atmosphere/projectConfiguration.sh
  inflating: atmosphere/setup.sh
root@swi-mdm9x28-wp:~# cd atmosphere/
root@swi-mdm9x28-wp:~/atmosphere# chmod +x setup.sh
root@swi-mdm9x28-wp:~/atmosphere# ./setup.sh
== Atmosphere IoT MangOH Yellow Setup ==

Please enter your API Key:
1ab234c5-6d78-1234-abc1-d23456ef78a9
Registering Project Atmosphere Demo to https://platform.atmosphereiot.com...
Registration Successful...
Stopping all custom apps except for atmosphere...
App 'button' is not installed.
App 'buzzer' is not installed.
App 'helloYellow' is not installed.
App 'imu' is not installed.
App 'leds' is not installed.
App 'light' is not installed.
App 'vegasMode' is not installed.
Installing Atmosphere System Service...
Unpacking package: 100% ++++++++++++++++++++++++++++++++++++++++++++++++++
Applying update: 100% ++++++++++++++++++++++++++++++++++++++++++++++++++
SUCCESS

At this point, the application is running and the mangOH GPS data is sent to Atmosphere through the Internet connection maintained on the mangOH Yellow.

Step 7 of 7: View Device Geolocation

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 device map widget to map the mangOH Yellow’s location. We’ll do this directly on the device’s console page, so click on the newly-added mangOH Yellow 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 Device Map device map widget to add a map to the dashboard.

Once added, the GPS data should populate the device map with the location of the mangOH Yellow. As new GPS data is sent each second, the position of the device will update on the map if the device’s location changes.

mangOH Yellow Guide Dashboard

Congratulations, you just finished a complete mangOH Yellow project with Atmosphere!