mangOH Red User manual

mangOH™ Red
Getting Started—WPx5xx +
Linux Dev Machine + CLI
41110481
Rev 3
Contents subject to change

mangOH Red Getting Started
Rev 3 9/21/17 2
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 Red Getting Started—WPx5xx + Linux Dev Machine + CLI
Author: Sierra Wireless
Source: http://mangoh.io/
Copyright © September 21, 2017 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.

Rev 3 9/21/17 3
Revision
History
Revision
number Release date Changes
1August 2017 Document created

Rev 3 9/21/17 4
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Get Started! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Check Out Some Helpful Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Set Up Your mangOH Red Hardware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Hardware Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Prepare Your Linux Dev Machine For Legato Development. . . . . . . . . . . . . . . . . . . . . . . 15
Prepare Dev Machine For Application Development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Build and Install the Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Prepare Your mangOH Red For Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Build and Install Legato Platform and mangOH Red Platform on Target . . . . . . . . . . . . . 20
Connect To Mobile Networks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Connect To a Mobile Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Connect to the IoT Cloud . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Register and connect to AirVantage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Register with AirVantage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Connect to AirVantage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Develop and Test applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Develop using the CLI—Command Line Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Configure the Dev Machine’s Terminal Windows for Development . . . . . . . . . . . . . . .39
Update an Installed Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Update and Install a New Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

Rev 3 9/21/17 5
Update Legato Application Framework. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Update the Legato AF on Your Dev Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Finding your SIM’s APN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Using the Linux Terminal program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Useful commands for this tutorial (and more) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Hardware Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Dipswitch Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Console Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Removing/Inserting a CF3 Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Removing a CF3 module. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Inserting a CF3 module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Quick Reference—Commands in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Rev 3 9/21/17 6
1
1: Introduction
Now that you have your mangOH™ Red, it’s time to start using it!
Use this guide to:
•Assemble your mangOH Red
•Set up your dev machine for mangOH development
•Install and run applications, and send data to the IoT Cloud via AirVantage, Sierra Wireless’ cloud-based
service platform for over-the-air (OTA) device management.
To get started with a Windows dev machine, or for other mangOH Red resources (guides, tutorials, etc.), visit
mangoh.io/mangoh-red-resources.
1.1 Get Started!
Before you begin, make sure your dev machine meets the minimum suggested requirements in Table 1-1 on
page 7 for mangOH Red application development.
Important: Use this guide only if you are using a native Linux computer (dev(elopment) machine)—Ubuntu is
recommended. This guide includes instructions for native Linux® dev machines using CLI (Command Line Inter-
preter).
Important: Follow all steps as described. If you skip, change, or ’jump around’ steps, your device or devel-
opment environment may not work properly.
Note: The instructions in this guide have been tested on Ubuntu 16.04. If you use a different distribution
(e.g. Debian, Fedora, etc.), you may need to adjust commands, set permissions, etc. If you need assistance,
please check out the forum at forum.mangoh.io.
Step 1
Step 2
Step 3
Step n-1
...
Step n
Step 1
Step 2
Step 3
Step n-1
...
Step n

1.1: Get Started!
Rev 3 9/21/17 7
When you are ready to begin, work straight through the rest of this guide:
•STEP 1: Check Out Some Helpful Tips on page 8
•STEP 2: Set Up Your mangOH Red Hardware on page 9
•STEP 3: Prepare Your Linux Dev Machine For Legato Development on page 15
•STEP 4: Prepare Your mangOH Red For Development on page 20
•STEP 5: Connect To Mobile Networks on page 27
•STEP 6: Connect to the IoT Cloud on page 31
Things to check out after you finish the steps above:
•Develop and Test applications on page 39
•Update Legato Application Framework on page 47
•Tips on page 50
•Hardware Tips on page 53
•Console Access on page 54
•Quick Reference—Commands in this Guide on page 58
Note: As you work through this guide, you can refer to Table G-1 on page 58 for descriptions of the
commands you have to use.
Table 1-1: Minimum System Requirements
Linux
O/S Ubuntu 16.04
CPU Dual core @ 2.6 GHz
RAM 4GB
HDD 10 GB free space
USB Ports •Preferred—2 (for full functionality)
•Minimum—1

Rev 3 9/21/17 8
2
2: Check Out Some Helpful Tips
Before you begin, here are a few items that you might find helpful:
•Some terminology:
·"CF3"—The mangOH Red supports CF3 (Common Form Factor) embedded modules, such as the
WP8548 and HL8548.
Throughout this tutorial, "CF3" refers to the module that comes with your mangOH Red kit.
·"Dev(elopment) machine"—Your Linux computer
·"Target"—The CF3 module in your mangOH Red.
•Some symbols:
·’$’, ’#’— Command prompts.
·’$’—Command prompt when you are logged in to a device as a regular user.
·’#’—Command prompt when you are logged in as the ’root’ user.
·’~’, "$HOME"—Your ’home directory’ on your dev machine.
•Command examples—Many steps in this guide require you to enter commands in a terminal window. These
commands are shown like this:
$ ping 192.168.2.2
# cd ~
•CF3 module default credentials and IP address (used to connect to the target from the dev machine):
·USB ECM IP address—192.168.2.2
·User name—root
·Password—<none>
•Terminal window tips:
·Shortcut to open a terminal window (on the default Unity desktop used in Ubuntu Linux)—Ctrl+Alt+T
·Cancel command to break out of a running process—Ctrl+C
·minicom exit command—Ctrl+A, then press X
Note: In the examples in this document, you will be logged in as a regular user on your dev machine
(command prompt will be ’$’), and logged in as the root user on the target (command prompt will be ’#’).
Note: You can copy commands from this guide and paste them in to your terminal window to save time and avoid
typing errors. Copy the command only, do not include the command prompt. (In the first example above, you would
enter "ping 192.168.2.2", not "$ ping 192.168.2.2".)

Rev 3 9/21/17 9
3
3: Set Up Your mangOH Red Hardware
In this chapter, you will set up your mangOH Red to begin developing applications.
A typical mangOH Red kit includes:
•mangOH Red board
•Pre-installed CF3 (Common Form Factor) module and cover, and release tool
•micro-USB cables (2)
•Antenna (main)
•Antenna (diversity)—Included if the CF3 module supports LTE
•Sierra Wireless micro-SIM
The following image summarizes the parts of the mangOH Red that you will set up when you follow the
instructions in Hardware Setup on page 10.
Important: Do not start connecting components until told to in the instructions, otherwise you may
encounter problems later in the guide.
Connect CF3 USB port
on bottom side of board
Optionally, connect CONSOLE USB
Set jumper on Power
Header to select USB
Insert Sierra Wireless (or other) SIM card
in slot on bottom side of board to connect
Set dipswitches to proper
Optionally, attach the
diversity antenna
Attach the
main antenna to
positions for the tasks in
this guide.
to dev machine for
power and to log in to
the device.
port used for input
power supply.
port to dev machine to display
diagnostic messages.
be able to connect to
a mobile network.
for modules that
support Rx diversity
to a mobile network.
(connector beside
header pins)

3.1: Hardware Setup
Rev 3 9/21/17 10
3.1 Hardware Setup
To set up the mangOH Red board:
1. Remove the protective film from the dipswitches:
2. Make sure the dipswitches are set as follows:
·ON—1,3,5,8
·OFF—2,4,6,7
For switch details (not needed for this tutorial), see Dipswitch Settings on page 53.
Remove this film

3.1: Hardware Setup
Rev 3 9/21/17 11
3. Insert a micro-SIM in the slot on the bottom side of the mangOH Red. You can use the Sierra Wireless
micro-SIM that is included in the kit, or another micro-SIM that has been activated by a mobile network
provider.
4. Attach the main antenna and (for LTE CF3 modules) the diversity antenna.
Note: If you do not have an activated micro-SIM, you can still continue with the tutorial, but will not be able to
complete the following sections: Connect To Mobile Networks on page 27 and Connect to the IoT Cloud on page 31.
Note: The main antenna is required if you want to connect the mangOH Red to a mobile network in Connect To
Mobile Networks on page 27.
Tip: If you have trouble connecting an antenna, make sure it is positioned directly on the connector and push straight
down. The antenna will not connect at an angle.
Note the location of the notched corner. Inserted in bottom part of slot
Main
GNSS
Diversity

3.1: Hardware Setup
Rev 3 9/21/17 12
5. Move the power select jumper onto the pins closest to the battery connector to select the CF3 USB connector.
(In this guide, power is supplied from the dev machine’s USB port to this connector when you connect it in a
later step.)
6. Power up the mangOH Red:
a. Use a micro-USB cable to connect the CF3 USB connector to a USB port on the dev machine.
Note: The mangOH Red has two USB connectors:
• CF3 USB is used for SSH connections, AT commands, and firmware downloads.
• CONSOLE_USB is a serial connection used to access the module’s console for diagnostic purposes.
Note: OPTIONALLY, if you want to be able to display the target’s console messages (diagnostic
messages) and have two available USB ports on your dev machine, follow the instructions in Console
Access on page 54. This is NOT a required step for this tutorial.
CF3 USB power (jumper on pins
closest to battery connector)
CF3 USB connector
(bottom side of board)
CONSOLE USB connector
Battery connector
CF3 USB connector
(bottom side of board)

3.1: Hardware Setup
Rev 3 9/21/17 13
When the mangOH Red is powered, the Power LED turns solid green.
Note: For future reference, the mangOH Red’s power supply (USB port on your dev machine, or an AC adapter)
connects to the board via either USB connector—CF3 USB or CONSOLE USB (depending on the jumper position on
the power header). If an AC adapter is connected to CF3 USB, SSH/AT connections are not possible; if it is
connected to CONSOLE USB, serial USB connections are not possible.
7. On the dev machine, open another terminal window.
8. Make sure the modemmanager package is removed from your system (this package causes problems with
mangOH Red if it is not removed):
$ sudo apt-get remove -y modemmanager
9. Wait 10-15 seconds for the mangOH Red to enumerate.
10. Test the CF3_USB connection:
$ ping 192.168.2.2
You should receive ping responses. Press Ctrl+C to cancel the ping request and return to the command
prompt.
Power LED
Ctrl+C pressed to cancel ping
Replies received, connection working

3.1: Hardware Setup
Rev 3 9/21/17 14
Now you are ready to Prepare Your Linux Dev Machine For Legato Development on page 15.

Rev 3 9/21/17 15
4
4: Prepare Your Linux Dev Machine For Legato
Development
In this chapter, you will prepare your dev machine for Legato application development by setting up the
development environment with required applications and packages.
4.1 Prepare Dev Machine For Application Development
After preparing your mangOH Red hardware in Set Up Your mangOH Red Hardware on page 9, you can prepare
your dev machine for application development:
4.2 Build and Install the Development Environment
In this section you will build and install the environment to develop applications for the CF3 module used in your
mangOH Red. The environment includes:
•Legato toolchain—Tools and libraries used to build the Legato Platform for your CF3 module. The Legato
toolchain is module-specific; you must make sure you install the toolchain designed for your module.
•mangOH Red platform—Drivers for on-board components, and a basic device-to-cloud application.
To build and install the development environment on your dev machine:
1. Open a terminal window.
2. Install packages required for the development environment:
a. Display your Ubuntu version:
$ lsb_release -d
3. Check whether your dev machine is 32-bit or 64-bit:
$ uname -m
The dev machine’s hardware type appears —e.g. "x86_64" is a 64-bit system.
Important: To install and use the development environment, your dev machine must meet the requirements in
Table 1-1 on page 7.
Important: Download, installation and use of Legato Application Framework and Platform Services is subject to
the Legato License and Open Source Licenses. (Note: These links automatically download the licenses as PDF
files.)
Note: If the version is less than 16.04, upgrade your operating system to 16.04 or higher, then continue with these
instructions.

4.2: Build and Install the Development Environment
Rev 3 9/21/17 16
4. Install several packages that are required for the Legato Platform and the mangOH Red platform:
$ sudo apt-get install -y build-essential openjdk-8-jre \
libwebkitgtk-1.0-0 python python-jinja2 cmake \
git subversion libsdl-dev diffstat texinfo gawk \
chrpath wget cpio vim zsh bash ninja-build screen \
sshpass bc python-git unzip libxml2-utils gcovr \
libcurl4-gnutls-dev zlib1g-dev libbz2-dev iputils-ping \
bsdiff libssl-dev zip autoconf automake
5. As shown in the previous step, the output you see when you run some commands may be different from the
examples shown. To check if a command succeeded or failed, enter the following command:
$ echo $?
If the value returned is ’0’, the command succeeded. If it is any other value, the command failed.
6. If your dev machine is 64-bit, install additional dependencies:
$ sudo apt-get install -y lib32z1 lib32ncurses5
7. Build the Legato toolchain (SDK):
a. If you have previously installed Legato toolchains, make sure you do not have any old toolchain files
("poky*.sh") in your Downloads directory (e.g. ~/Downloads), and remove any changes that may have
been made to your .bashrc file:
i. Go to your Downloads directory:
$ cd ~/Downloads
Note: The ’\’ at the ends of the lines tells the system that the command continues on the next line. When you run
this command (and any others in this guide that use the ’\’), you can copy and paste the full command (including ’\’
characters) in your terminal window. If you type the command manually all on one line, do not type the ’\’
characters.
If prompted to continue,
type Y and press Enter.
Installation messages
Actual messages displayed will vary
depending on which packages are
already installed
The command worked (value = 0).
Any other value (2, 100, etc.) would
mean the command failed.

4.2: Build and Install the Development Environment
Rev 3 9/21/17 17
ii. Either move or delete any old toolchain files:
Delete files:
$ rm poky*
Move files:
$ mkdir old_toolchains
$ mv poky* old_toolchains
iii. Edit your ~/.bashrc file, comment out any items at the bottom of the file that begin with "LEGATO", and
save and close the file.
b. Go to http://source.sierrawireless.com/resources/legato/downloads and click the latest Legato (32-bit or
64-bit) toolchain download link (the link is to a .sh file).
Note: You must register on the Source for an account before you can download files.
c. Click Download.
d. If prompted, save the file to your Downloads folder. (e.g. ~/Downloads)
e. In the terminal window, open the folder and run the file.
(In the command below, replace <file_name> with the actual file name.
e.g. If the file name is "poky-swi-ext-sample-1.7.3.sh", the command would be "bash poky-swi-ext-sample-
1.7.3.sh"):
$ cd ~/Downloads
$ bash <file_name>
f. When prompted to enter a target directory for the SDK, press Enter to accept the default (/opt/swi/y17-ext).
Click Download on the latest (newest)
32-bit or 64-bit toolchain link

4.2: Build and Install the Development Environment
Rev 3 9/21/17 18
g. When prompted to install or (possibly) replace the SDK, type ’Y’ and press Enter.
When finished, installing, the message "SDK has been successfully set up and is ready to be used." will
appear.
h. Configure the toolchain to make it available for use in generating the mangOH Red platform and the kernel
modules that it references:
$ export PATH=$PATH:/opt/swi/y17-ext/sysroots/\
x86_64-pokysdk-linux/usr/bin/\
arm-poky-linux-gnueabi
$ cd /opt/swi/y17-ext/sysroots/\
armv7a-vfp-neon-poky-linux-gnueabi/usr/\
src/kernel
$ sudo chown -R $USER .
$ ARCH=arm CROSS_COMPILE=arm-poky-linux-gnueabi- \
make scripts
$ sudo chown -R root .
8. Install the repo application, which will be used to clone the Legato file repository:
$ sudo apt-get install -y repo
9. If the install in Step 8 failed because phablet-tools was previously installed:
a. Enter the following command:
$ sudo apt-get remove -y --purge phablet-tools
b. Go back to Step 8.
10. If you have not used git or git-repo to clone a project before, identify yourself as follows:
$ git config --global user.email "[email protected]"
$ git config --global user.name "your.name"
Note: This may take a few minutes to run.

4.2: Build and Install the Development Environment
Rev 3 9/21/17 19
11. Download the mangOH platform files into a working directory—enter the following command and either
replace <mangOH_work_directory> with a new directory name (e.g. "mangOH_work"), or remove it (to use the
default directory name "mangOH").
$ cd ~
$ git clone --recursive https://github.com/mangOH/\
mangOH <mangOH_work_directory>
12. Add an environment variable (shortcut) for the mangoh work directory—this will be available each time you
open a new terminal window:
a. Edit your ~/.bashrc file (the startup script that runs when you open a terminal window) and add the
following line at the end of the file:
export MANGOH_ROOT=~/mangOH_work
b. Save and close the file.
c. Exit the window:
$ exit
d. Open a new terminal window, which automatically executes the .bashrc script, which now sets the
MANGOH_ROOT shortcut automatically.
Now that the Legato development environment is installed, you can Prepare Your mangOH Red For
Development on page 20.
Note: <mangOH_work_directory> is optional—if not used, a working directory is created with the same
name as the repository (in this case, "mangOH").
Note: . If you downloaded into a different directory name in Step 11, replace "mangOH_work" with that name in
the above export statement:
Platform downloads to ~/mangOH_work.
,
If you don’t put a name here, it
downloads to mangOH (the name of the
directory on github).
Returns to command prompt with no
,
error messages.

Rev 3 9/21/17 20
5
5: Prepare Your mangOH Red For Development
In this chapter, you will update the CF3 module on your mangOH Red with the basic mangOH Red Platform
(application suite).
5.1 Build and Install Legato Platform and mangOH Red
Platform on Target
Now that your dev machine has its development environment set up, you will:
•Build the Legato Platform (development applications) on your dev machine.
•Use the Legato Platform to build the mangOH Red Platform (target applications) and install it onto your target
(the CF3 module in your mangOH Red)
1. Get the Legato Application Framework (AF):
a. Go to http://legato.io/legato-docs/latest/aboutReleaseInfo.html to get the version number of the most
recent release.
b. Download the framework files into a working directory (for example, "legato_framework")::
i. Create a working directory below your home directory to hold the framework files (for example,
"legato_framework"):
$ mkdir ~/legato_framework
ii. Download the framework files into the work directory—Replace the release number in the ’repo’
command with the most recent release (this example downloads version 17.07.1):
$ cd ~/legato_framework
$ repo init -u git://github.com/legatoproject/\
manifest -m legato/releases/17.07.1.xml
$ repo sync
Note: Through the rest of this guide, "legato_framework" is assumed to be the file you created. If you used a
different name, make sure to use that name in any commands that refer to legato_framework.
Most recent release