Searching...

Matching results

    Getting Ready to Develop Legato Applications

    This tutorials is deprecated. Please have a look to this page .

    Objective

    This tutorial aims to provide setup information to users who want to rapidly get started developing Legato applications using Command-line mode.

    Tutorial on developing Legato application using Developer Studio IDE will be made available in the near future.

    The following steps are described, they are necessary to develop Legato applications:

    1. Interfacing with Legato device, in order to configure device and to control applications
    2. Setting up Legato application Development Environment on your host, in order to compile and install applications onto the target device
    3. Registering your Legato device on AirVantage, so that the device can exchange data with the cloud server

    Although a mangOH board embedding a WP8548 module is used in this tutorial, guidelines provided in this page are also applicable to other Legato-based modules.

    Prerequisite

    1. The mangOH board shall be correctly mounted (WP module, antennas, power, switches, etc) following this user guide
    2. Download appropriate firmware packages (Customer Configuration package and Carrier Configuration package) then follow provided instruction to upgrade the device. Please note that signing up/in source.sierrawireless.com is required to download packages and drivers.
    3. SIM card with data call plan

    4. Linux PC running Ubuntu/Debian OS

      • If you’d like to use your existing Host (e.g. MAC OSX, Windows) to develop Legato applications, you could use Virtual Machine, e.g. VirtualBox
      • If you are using Virtual Machine under Windows then install the USB Drivers
      • Create an Ubuntu/Debian VM image. For instance, you can follow Ubuntu on VirtualBox
      • Then follow this tutorial

    5. Have an account on AirVantage server. If you don’t, sign up here

    Part references used in this tutorial

    1 / Hardware Setup

    2 / Dev Host PC Setup

    3 / Register

    Any issues ?

    If you encounter any issue to set up your device, don’t hesitate to use the developer forum to benefit from the developer community experience.

    Step 1: Hardware Setup

    Your Host PC can interface with the Legato device to gain the following functionalities :

    1. Access to device Linux Console to perform the following basic operations:
      • Retrieve embedded system information
      • Get Radio and Data connection status
      • Set PIN code or remove PIN code
      • Retrieve ethernet IP address
    2. Install Legato Applications (developed on your host) onto the target device

    To access device Linux console, the host can use ONE of the following interfaces:

    1. Serial port
    2. Ethernet
    3. USB

    To install Legato applications onto Legato device, you can only use ONE of the following interfaces:

    1. Ethernet
    2. USB

    How to gain access to device Linux console ?

    There are 3 methods to access device Linux console. The most straighforward is to use device Serial port.

    Access to Legato Linux console over the Serial port

    Legato device’s serial port is configured to be used for console input/output. To login, proceed the following:

    • Use a Serial-to-USB cable to connect your device to your Host (PC/Mac)
    • Setup a terminal emulator program (e.g. minicom, putty) on the host as follow:
      • Baud rate : 115200 bps
      • Bits : 8
      • Parity: None
      • Stop Bits: 1
    • Open the serial connection, using the serial port being mapped to the USB port (e.g. /dev/ttyUSB0 or /dev/ttyS0)
    • Once the serial port is opened, login as root, there is no password by default. It is recommended to secure your platform by setting a password (passwd).
    • Target device USB driver is not required when using Serial-to-USB cable.
    • You can now enter Commands described in the below section Legato Device Setup and Configuration

    Access to Legato Linux console over Ethernet

    This option enables you to access the Linux console remotely using SSH. To login, proceed as follow:

    • Connect your Legato device to your local network using an ethernet cable
    • Your host (PC/Mac) should also be connected to the same network

    • Establish a SSH session from your host using the following command:

      ssh root@<mangOH-ip-addr>

    • Please note that, the IP address of the device must be known prior using this ethernet option

      • It’s easier to figure out the IP address of the device in a small local network. For instance, sudo nmap -sn 192.168.0.0/24
      • You could have your DHCP server to assign a fixed IP address to your device based on his MAC address
      • Use a Serial connection (previous section) to access the Linux console, then use ifconfig command to discover the IP or MAC adressses

    • You can now enter Commands described in the below section Legato Device Setup and Configuration

    Access to mangOH Linux console over USB

    • Connect your device’s microUSB port to your PC using a USB cable

    • USB ECM mode is enabled by default on the target device:

      • ifconfig command shows a new network interface: usb0 along with assigned IP address for your host (default is 192.168.2.3)
      • The device exposes an ECM USB interface (Ethernet over USB) to the host under IP address 192.168.2.2 (default address)

      • Establish a SSH session from your host using the following command

            ssh root@192.168.2.2

      • You can now enter Commands described in the below section Legato Device Setup and Configuration

    • If USB ECM mode is disabled on the target device:

      • Use the Serial interface to access the device Linux console and then enable USB ECM mode. Refer to configEcm command in the next section

    Legato Device Setup and Configuration

    Once you have connected the host to the device using one of the above interface (Serial, Ethernet or USB), as described in previous sections, you can now access device Linux console.

    Although any Linux commands can be used in the device Linux console, you may enter the following commands to discover or to change configuration.

    • System Versions

      • cm info, to display device model, IMEI, Serial Number, firmware and bootloader versions
      • legato version, to display Legato framework version

    • Radio

      • cm radio or cm radio status, to retrieve modem status
      • cm radio on/off, to enable/disable radio
      • refer to cm radio for more information on this command

    • Data Connectivity

      • cm data or cm data info, to retrieve current profile in use
      • cm data apn YourApn, to set APN for profile in use to YourApn
      • cm data connect (optional timeout, secs), to start a data connection for the optionally specified duration
      • refer to cm data for more information on this command.

    • Applications

      • app status, to list applications status
      • app start/stop/remove appName, to start or stop or remove application named appName
      • refer to app for more information on this command

    • SIM

      • cm sim status, to retrieve SIM status
      • cm sim info, to get SIM information
      • cm sim enterpin, to enter SIM PIN code
      • cm sim unlock pin, to disable SIM card security, won’t request a PIN code when inserted or at the next system startup. Although, this is not recommanded for deployment, it is convenient for developers who need to reboot the board and to interact with it remotely using ssh
      • refer to cm sim for more information on this command

    • IP Address

      • ifconfig, Linux command, can be used to discover the IP address associated to the Ethernet (if connected). SSH over ethernet is an interesting option to connect to the device for development. Therefore, all above commands can be issued remotely with SSH. In your local network, you could assign a fixed IP address using the MAC address of eth0 interface.

    • USB mode

      • configEcm show, to check whether the USB ECM mode is enable
      • configEcm on, to activate the USB ECM mode. Device Reboot may be required. This mode enable your host to connect to your device using IP over USB.
      • configEcm off, to deactivate the USB ECM mode. This is useful when you’d need to upgrade the firmware locally using fdt tool

    In Step 1, we’ve covered how to:

    1. Connect your host to the Legato device using different options (Serial port, Ethernet or USB) in order to access device Linux Console
    2. Issue Commands in device Linux Concole in order to Retrieve information (e.g. IP address, software version) and Set basic configurations (e.g. SIM PIN, APN)

    Step 2: Legato Development Environment

    This tutorial only covers development using Command-Line. Tutorial on using Developer Studio IDE will be available in the near future.

    Before you can start developing Legato applications, the following conditions must be met:

    • Development Host should be running Ubuntu/Debian Linux and must have the following packages to be installed:
      • Legato Framework
      • Legato CLI (Linux Command Lines) tools
    • Target Device (Legato-based module)
      • Legato version must be in sync with Legato Framwork version in the Host
      • Firmware version must be compatible with Legato version
      • Underlying dependency such as bootloader, rootfs, os versions are covered by proper firmware package

    The main setup flow to satisfy the aforementioned conditions can be summarized as follow:

    • Make sure the Device firmware is compatible with the Legato framework version (e.g. 16.01), if not proceed to download appropriate firmware package and follow provided instuction to upgrade the device.
    • Prepare the host with the required packages/source/toolchain and Legato Framework.

    Setting Up the Ubuntu/Debian Development Host

    • Minimum Configuration Requested: RAM: 1 GB / HDD: 5 GB free space / Ubuntu 15.04 recommended
    • Legato is providing a complete set of Linux Command Lines (CLI) to develop your Legato applications. The legato-spm tool downloads everything needed to install the Legato CLI and embedded software packages for WP modules.
    • Depending on your target distribution, follow one of these 2 steps to install legato-spm

    Install legato-spm on Ubuntu/Debian distribution

    • Check your Ubuntu version

      lsb_release -d

    • If you are running an Ubuntu version older than 14.10 then install Java 8 as follow, otherwise proceed to Install legato-spm

      sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt-get update
sudo apt-get install openjdk-8-jre-headless
sudo update-alternatives --config java

    • Install legato-spm

      wget http://updatesite.sierrawireless.com/legato-spm/debian/legato-spm.list -O - | sudo tee /etc/apt/sources.list.d/legato-spm.list
wget http://updatesite.sierrawireless.com/legato-spm/debian/legato-spm.key -O - | sudo apt-key add -
sudo apt-get update
sudo apt-get install legato-spm

    Install legato-spm on alternate distributions

    • Install requirements for legato-spm tool: openjdk-8-jre-headless
    • Install requirements to build Legato applications: build-essential python-jinja2 ninja-build

    • Download legato-spm tool archive from this link

    • Extract the archive to the location of your choice (e.g. unzip legato-spm*.zip -d $HOME/legato/spm)

    • Potentially add this location to your user’s path (e.g. echo ‘export PATH=$HOME/legato/spm:$PATH’ >> $HOME/.bashrc)


    • Download and install the latest Legato CLI tools and embedded software packages

      legato-spm --install --module WP85XX --update-link

    • Following packages are now installed in your ~/legato/packages directory:

      legato.framework.*  - Prebuilt Legato framework packages
legato.toolchain.*  - GCC cross compiler Toolchains
legato.devimg.*     - Images to upgrade Legato devices system software
legato.recovery.*   - Tool to recover a bricked Legato device
legato.source.*     - Legato source distribution package

    • Use this script to configure Legato, this script shall be launched once in each new terminal window you’d use for Legato development

      source ~/legato/packages/legato.sdk.latest/resources/configlegatoenv

    Compiling and Installing applications

    Once the Legato CLI tools have been installed in your Ubuntu/Debian host, you are now ready to develop Legato applications.

    Important
    In this Step, your Host needs to be connected to your Legato device over IP (using USB or Ethernet). This IP connection is required to install Legato Applications onto the target.
    Connection over the Serial link cannot be used to install application

    Let’s have a separated Terminal console dedicated to compiling and installing applications. Let’s name it Terminal #1 for referencing convenience.

    • In Ubuntu, open a new Terminal console, #1

    • Launch the following script to setup environment variables for Legato Development

      source ~/legato/packages/legato.sdk.latest/resources/configlegatoenv

    • You are now ready to compile sample applications in the apps/sample directory ($LEGATO_ROOT/apps/sample)

    • Get into the helloWorld directory and compile it for WP8548 (mangOH) target

      cd $LEGATO_ROOT/apps/sample/helloWorld
make wp85

    • helloWorld.wp85 should be generated as the result of the compilation

    • Install it onto mangOH target device

      instapp helloWorld.wp85.update <mangOH-IPaddress>

    Viewing Device logs

    In the Ubuntu Host, let’s have a separated Terminal console dedicated to mangOH log. Let’s name it Terminal #2 for referencing convenience.

    • In Ubuntu, open a new Terminal console, #2
    • SSH onto the device: ssh root@mangOHIPaddress
    • Start the logging: logread -f
    • This terminal console will now display all logs

    Managing Applications on the Device

    In the Ubuntu Host, let’s have a separated Terminal console dedicated to device Linux Console. Let’s name it Terminal #3 for referencing convenience.

    • In Ubuntu, open a new Terminal console, #3
    • SSH onto the device: ssh root@mangOHIPaddress
    • Verify that helloWorld application has been installed: app status
    • Launch the app : app start helloWorld
    • You should be seeing “Hello, world” log in Terminal #2. The helloWorld sample application just simply output this log using LE_INFO macro.

    In Step 2, we’ve covered how to:

    1. Setup your Ubuntu/Debian host for Legato Development usage
    2. Compile applications, install application onto the Target device
    3. Remotely access to Target Device Linux console
    4. View Target device log

    Step 3: Register your Legato device on AirVantage

    Before your Legato applications can exchange data with AirVantage, your Legato-based device must be registered on AirVantage. This step guide you through this registration procedure.

    Device Registration on AirVantage

    Acces mangOH Linux console, using one of the methods described in the first step:

    • Collect Device Identification information: cm info
    • Connect to AirVantage web portal using your personal account.
    • Go to the Register activity
      • Provide device information: Type, Serial Number, IMEI
      • Give it a Name, for searching convenience
    • Proceed to Register to finalize the registration
    • Your device can now connect to AirVantage server.
    • The tutorial exchange asset data with AirVantage will guide you through the connection and data exchange data with AirVantage.

    TOP