Sierra Wireless mangOH Green Operation instructions

mangOH™ Green
Tutorial—Arduino-compatible
Shield to AirVantage
4119370
Rev 1
Contents subject to change

mangOH Green Tutorial—Arduino-compatible Shield to AirVantage
Rev 1 6/18/16 2 4119370
Important
Notice Due to the nature of wireless communications, transmission and reception of data can
never be guaranteed. Data may be delayed, corrupted (i.e., have errors) or be totally
lost. Although significant delays or losses of data are rare when wireless devices such
as the Sierra Wireless modem are used in a normal manner with a well-constructed
network, the Sierra Wireless modem should not be used in situations where failure to
transmit or receive data could result in damage of any kind to the user or any other
party, including but not limited to personal injury, death, or loss of property. Sierra
Wireless accepts no responsibility for damages of any kind resulting from delays or
errors in data transmitted or received using the Sierra Wireless modem, or for failure
of the Sierra Wireless modem to transmit or receive such data.
Limitation of
Liability The information in this manual is subject to change without notice and does not
represent a commitment on the part of Sierra Wireless. SIERRA WIRELESS AND ITS
AFFILIATES SPECIFICALLY DISCLAIM LIABILITY FOR ANY AND ALL DIRECT,
INDIRECT, SPECIAL, GENERAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR
EXEMPLARY DAMAGES INCLUDING, BUT NOT LIMITED TO, LOSS OF PROFITS
OR REVENUE OR ANTICIPATED PROFITS OR REVENUE ARISING OUT OF THE
USE OR INABILITY TO USE ANY SIERRA WIRELESS PRODUCT, EVEN IF
SIERRA WIRELESS AND/OR ITS AFFILIATES HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES OR THEY ARE FORESEEABLE OR FOR
CLAIMS BY ANY THIRD PARTY.
Notwithstanding the foregoing, in no event shall Sierra Wireless and/or its affiliates
aggregate liability arising under or in connection with the Sierra Wireless product,
regardless of the number of events, occurrences, or claims giving rise to liability, be in
excess of the price paid by the purchaser for the Sierra Wireless product.
Patents This product may contain technology developed by or for Sierra Wireless Inc.
This document contains information which is proprietary to Sierra Wireless Inc. and is
licensed pursuant to Creative Commons Attribution 4.0 International License.
Document
details Title: mangOH Green User Guide
Author: Sierra Wireless
Source: http://mangoh.io/
Copyright © June 18, 2016 Sierra Wireless. Licensed under the Creative Commons Attribution
4.0 license, http://creativecommons.org/licenses/by/4.0/
Disclaimer Indicate any modifications made to the original document.
Trademarks mangOH™ and the mangOH logo are trademarks of Sierra Wireless.
Other trademarks are the property of their respective owners.

Preface
Rev 1 6/18/16 3 4119370
Revision
History
Revision
number Release date Changes
1June 2016 Document created

Rev 1 6/18/16 4 4119370
Contents
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Set up your mangOH Green. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Prepare your mangOH Green for Arduino development. . . . . . . . . . . . . . . . . . . . . . . . . . 10
Install mangOH Green Platform Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Prepare for Arduino development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Download Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Prepare the Sketch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Add Required Libraries to Arduino Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Connect to the IoT Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Configure AirVantage To Receive Sensor Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Rev 1 6/18/16 5 4119370
1
1: Getting Started
This tutorial will take you through the process of setting up your mangOH Green to
allow Arduino sketches to transmit data to the cloud, and configuring AirVantage to
receive that data.
The tutorial builds on basics covered in the mangOH Green Fundamentals tutorial
and the mangOH Green User Guide. To work through this tutorial:
•You must have already set up your mangOH Grene hardware and registered your
device on your AirVantage account. See the mangOH Green Fundamentals
tutorial for details.
•You must have an IDE loaded on your computer for Arduino sketch development.
The examples in this tutorial reflect the use of the Arduino IDE, v.16.9 (available
from http://arduino.cc).
•You should have a working understanding of sketch development. (This is not a
coding tutorial.)
When you finish this tutorial, you will have git-cloned the mangOH platform, used the
Arduino IDE to build and install a sketch on the mangOH Green, and configured your
AirVantage account to receive data sent by sensors installed on an Arduino shield.
Tip: If you have only one monitor, you may want to print this document and use it when you
don’t want to switch back and forth between the PDF and the various windows/applications
you’ll be opening during the tutorial.
This tutorial includes:
•Set up your mangOH Green on page 6
•Prepare your mangOH Green for Arduino development on page 10
•Prepare for Arduino development on page 12
Important: To get maximum benefit from this tutorial, you are strongly recommended to
carefully follow the procedures as described, since the tutorial continually builds on earlier
procedures and results. If you skip steps or use alternate methods, you may encounter difficulty
completing the tutorial.

Rev 1 6/18/16 6 4119370
2
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
2: Set up your mangOH Green
This chapter details how to prepare your mangOH Green to receive and run sketches
on its ATmega32U4 chipset.
For this tutorial, you need the following materials:
•mangOH Green with (at least):
·main antenna connected
·activated SIM inserted
·power supplied via USB or the DC jack
•AirVantage account with your mangOH Green registered on it
Note: The mangOH Green Fundamentals tutorial (available at http://mangoh.io) describes the
basic device setup, Arduino account creation, and device registration.
•Mini-USB cable
•Grove Base Shield V2
•Grove sensors (one or more):
·Temperature and Humidity Sensor
·Dust Sensor
·Gas Sensor(O2)
·Light Sensor
·Sound Sensor
·Water Sensor
Note: Grove shield and sensors are available from www.seeedstudio.com.

Rev 1 6/18/16 7 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
To set up the mangOH Green for use with Arduino sketches:
1. Make sure your mangOH Green is set up with (at least) an activated SIM, the
main antenna, and USB or DC power selected (but not connected). In this
example, DC power is selected.
2. Hold the Grove shield by its edges, position it above the headers, and press it
straight down. (Note that the two rows of headers have different numbers of
pins—make sure to position the shield correctly.)
Figure 2-1: Installing an Arduino-compatible Shield
1—18-pin header
2—14-pin header

Rev 1 6/18/16 8 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
Figure 2-2: Grove Shield Installed on mangOH Green
3. Attach the DHT sensor(s) to the Grove shield connector pins as follows:
·Temperature and Humidity sensor—Pin A0
·Dust sensor—Pin D8
·Oxygen sensor—Pin A3
·Light sensor—Pin A1
·Sound sensor—Pin A2
·Water sensor—Pin D6
Figure 2-3: Grove Shield With Temperature and Humidity Sensor on Pin A0
4. Plug in your power source (micro-USB cable or DC power cable).
Temperature/Humidity
sensor connected to pin A0

Rev 1 6/18/16 9 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
5. Connect the mini-USB cable between your computer and the mangOH Green
(use connector CN330).
Figure 2-4: mangOH Green connected via mini-USB
Now you are ready to Prepare your mangOH Green for Arduino development on
page 10.

Rev 1 6/18/16 10 4119370
3
Set up your
mangOH
Green
Prepare your
mangOH Green
for Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
3: Prepare your mangOH Green for Arduino
development
In this chapter, you will update the CF3 module on your mangOH Green with (among
others) applications that allow the mangOH Green’s ATmega32U4 chipset to
communicate with AirVantage.
3.1 Install mangOH Green Platform
Applications
The CF3 module used in your mangOH Green (e.g. AirPrime WP8548) must be
loaded with the mangOH Green platform.
To load the mangOH Green platform onto your CF3 module:
1. Download the Project mangOH manifest from http://github.com/mangoh as
follows:
Note: These steps are summarized in the “manifests” link on the project page, but are shown
here with extra details for clarity.)
a. In your Linux environment (Linux system, or Linux Virtual Machine), open a
terminal window.
b. If you have not used git or git-repo to clone a project before, you must identify
yourself:
$ git config --global user.email “[email protected]”
$ git config --global user.name “your.name”
c. In your home directory, get the repo tool, which you will use to clone the
Project mangOH repository. In the terminal window, enter:
$ cd ~
$ git clone https://gerrit.googlesource.com/git-repo
The repo tool is copied into a subdirectory named git-
repo.
Note: You can clone the repo tool to any directory you prefer. This tutorial assumes it is cloned
to your home directory (~, or $HOME).
d. Add the git-repo directory to your PATH environment variable.
$ echo “export PATH=$PATH:~/git-repo” >> .bashrc
$ . ~/.bashrc
e. Create a directory that you will use to build the mangOH Green platform
applications, and go to that directory:
$ mkdir ~/mangOH
$ cd ~/mangOH

Rev 1 6/18/16 11 4119370
Set up your
mangOH
Green
Prepare your
mangOH Green
for Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
f. Download (clone) the Project mangOH files:
$ repo init -u “https://github.com/mangOH/manifests” -m
mangOH.xml && repo sync
(Note: The ‘repo init’ command gets the list of files to copy, and ‘repo sync’
duplicates them onto your system.)
2. Build (compile) the mangOH Green platform:
$ cd ~/mangOH/legato
$ make wp85
(Note: This creates a ‘build’ directory for the wp85’s platform installation file.)
When the project finishes building, the command prompt reappears.
3. Go to the build directory:
$ cd build/wp85
4. Install the Project mangOH applications on your mangOH Green:
instsys system.wp85.update 192.168.2.2
All of the applications for the mangOH Green platform (defined in the git manifest)
are installed and begin running, including three that the ATmega32U4 chipset
uses to communicate with AirVantage:
·mqttClient
·dataRouter
·arduinoBridge
Now you are ready to Prepare for Arduino development on page 12.

Rev 1 6/18/16 12 4119370
4
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
4: Prepare for Arduino development
When you install a sketch on the mangOH Green’s ATmega32U4 chipset, its output is
pushed over the arduinoBridge to the dataRouter, where it is is then sent to
applications (including AirVantage) that are configured to receive the data.
Figure 4-1: mangOH Green Arduino to AirVantage Communication
In this chapter, you will download, install, and run a sample multi-sensor sketch that
accesses Grove sensor(s) that are attached to the Grove Base Shield (see Set up
your mangOH Green on page 6).
Note: The sketch can be run with any combination of the sensors. You can modify the sketch
to ignore any sensors that are not used (or leave the sketch as-is, and ignore the readings
reported from missing sensors).
Note: The tutorial covers the compilation and installation of a working sketch to the mangOH
Green’s ATmega32U4 chipset, and the collection of output by an AirVantage account; it does
not cover Arduino coding.
4.1 Download Sample Project
Download the sample project (“ArduinoBridge”, which includes the sample multi-
sensor sketch, a required library, and other files):
1. Go to http://github.com/mangOH/ArduinoBridge.
mangOH Green
ATmega32u4
Greenhouse
(Sketch)
Base Shield v2
Sensors
(Temperature/Humidity, Dust,
etc.)
CF3 (WP85xx)
mqttClient
(Application)
dataRouter
(Application)
arduinoBridge
(Application)
Other Device that will receive
sensor data pushed from the
mangOH
Other Device that will receive
sensor data pushed from the
mangOH

Rev 1 6/18/16 13 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
2. Click Clone or Download.
3. Click Download ZIP
4. When the download finishes, extract the zip file (ArduinoBridge-master.zip) to a
working folder (referred to as $WORK_DIR for the remainder of this tutorial).
4.2 Prepare the Sketch
Note: These instruction describe steps for the Arduino IDE. Adjust them accordingly if you use
a different development environment.
1. In the Arduino IDE, open the sample sketch
$WORK_DIR\ArduinoBridge-master\arduino\examples\multisensor\mangoh-
multisensor-example.ino

Rev 1 6/18/16 14 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
If you are prompted to automatically create a folder to work on the sketch, click
OK.)
2. In the sketch, set the AV_URL variable to the server that hosts your AirVantage
account. For example, “na.airvantage.net” or “eu.airvantage.net”.
3. (Optional step) If desired, modify the sketch to report only the sensors that you
have installed on the shield. (When the sketch is run, any sensors that are not
installed will be reported as ‘noise’ (random) values. You can modify the sketch,
or just ignore them when you view the results.)
4.3 Add Required Libraries to Arduino
Environment
The sample sketch uses the following libraries that must be loaded in your Arduino
environment.
•swibridge
•DHT (library for the Grove Temperature and Humidity Sensor)
If you do have not previously added the libraries to your environment, add them now
(Note: libraries can be installed manually or through the IDE. The following procedure
demonstrates both methods.):

Rev 1 6/18/16 15 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
1. Add the swibridge library (this example shows how to manually add the library):
a. Copy the swibridge library folder from the sample project to your Arduino
libraries folder (If you installed the Arduino IDE to a different location, use the
appropriate path.)
Note: In this example, the swibridge library folder is in $WORK_DIR\ArduinoBridge-
master\arduino\libraries) and the Arduino libraries folder is in C:\Program Files (x86)\Arduino)
2. Get the DHT library (this example shows how to use the Arduino IDE to install the
library):
a. Go to http://github.com/Seeed-Studio/Grove_Temperature_And_Humidity_-
Sensor.
b. Click Clone or Download.
c. Click Download ZIP.
d. In the Arduino IDE, select Sketch > Include Library > Add .ZIP library.
e. Navigate to your downloads directory and select file you just downloaded.

Rev 1 6/18/16 16 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
f. Click Open and it installs to your ‘contributed’ arduino libraries folder.
3. (Optional step) Depending on the IDE you are using, you might have to restart the
IDE to use the contributed library.
4. Verify/compile the sketch—Click the Compile icon or press Ctrl+R.

Rev 1 6/18/16 17 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
5. (Optional step) It may take a long time to upload your first sketch. If you want to
be sure there are no issues during the upload, you can turn on ‘verbose’ output
which shows detailed status messages (File > Preferences):
6. When the sketch has successfully compiled, upload it to the ATmega32U4 chipset
on the mangOH Green—Click the Upload icon or press Ctrl+U.
The sketch will begin running automatically.
Note: The ATmega32U4 chipset stores and runs only one sketch at a time. Each time you
upload a sketch, it replaces the currently running sketch.

Rev 1 6/18/16 18 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect to
the IoT
Cloud
7. Check that the sketch is running and whichever sensors you are using are
working properly (showing reasonable values)—Open a serial monitor in the IDE
(Tools > Serial Monitor)
Note: In the example above, only the Temperature and Humidity sensor is connected. Other
values are random.
Now you are ready to Connect to the IoT Cloud on page 19.

Rev 1 6/18/16 19 4119370
5
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect
to the IoT
Cloud
5: Connect to the IoT Cloud
Now that your mangOH Green is transmitting sensor data, you must configure your
AirVantage account to receive it.
5.1 Configure AirVantage To Receive Sensor
Data
Before AirVantage can receive the sensor data, it needs to be configured to
understand which messaging protocol is used for the data, and what the data
represents. To do this, you must load a ‘model’ file containing this information.
1. In a web browser, log in to your AirVantage account.
2. Select Develop > My Apps.
3. Click the Release button.
4. Click Select a file.
5. Navigate to the multisensor directory ($WORK_DIR\ArduinoBridge-
master\arduino\examples\multisensor).

Rev 1 6/18/16 20 4119370
Set up your
mangOH
Green
Prepare your
mangOHGreenfor
Arduino
development
Prepare for
Arduino
development
Connect
to the IoT
Cloud
6. Make a zip file of the mqttapplicationmodel folder.
7. Select the zip file and click Open.
8. Select Advanced settings.
9. Select I want to publish my application after releasing it.
Note: If you do not want to publish immediately, do not set this option. You can release now,
then publish later by clicking the Publish button (in the same row of buttons as the Release
button).