Getting-started Guide

In this guide, you will be able to quickly download ExositeReady™ Gateway Engine (GWE), install it onto your gateway, and start using it. Once you have completed this section you will have GWE installed and running on a gateway. If you encounter any issues, please raise a topic on the dedicated GWE Support Forum or comment on an existing one.

Minimum Requirements

Before proceeding to Get Started, you should first verify that your gateway has the minimum requirements for running Gateway Engine.

  • Linux OS
  • Python 2.7.9+
  • Network interface (eth0, wlan0, ppp0, etc.)
  • GNU shell
  • 128 MB Flash
  • 64 MB RAM
  • sqlite3
  • twisted

Note

Some testing has been done on Python 2.7.3, but it has not been tested extensively and is not recommended.

Partner Platforms

MultiTech MultiConnect® Conduit™ - In order to use MultiTech’s Conduit with GWE, end users must install the custom image fixes linked below. Download instructions for these images can be found here.

MultiTech GWE Image 1 (rootfs.jffs1)

MultiTech GWE Image 2 (uImage.bin)

Get Started

This getting-started guide will take you through the various steps to start using Murano and GWE, such as creating and configuring a Murano account, downloading GWE, configuring tools, and installing GWE onto a gateway.

Download and Unpack GWE

To download the latest version of the public release of GWE, navigate to the releases page and choose a method for downloading GWE.

Note

The shell command, below works on most Linux and OSX machines to download and echo the name of the downloaded file to the terminal.

Command (dev machine)

basename $(curl -v -k --remote-name $(curl --silent -k https://s3-us-west-2.amazonaws.com/exosite-client-downloads/gateway-engine-release-area/gmq-master/latest.lnk) 2>&1 | awk '/GET/{print $(NF-1)}')

Once downloaded, copy/move it to a directory on the filesystem of your development machine so its resources can be referenced later on.

Command (dev machine)

mkdir ~/code
cp ~/Downloads/GatewayEngine.v*.tar.gz ~/code

The GWE download contains useful resources and tools you can use outside the context of a gateway. To make these resources available on your development machine, decompress the tarball:

Command (dev machine)

cd ~/code
tar zxvf GatewayEngine.v*.tar.gz

You will be doing more with this download and the newly unpacked directory ~/code/gateway-engine, but for now you can move on to the next step.

Create an Account

Important

Click here to sign up for a Murano Account

Note

When signing up for a new account, there will be emails you will need to take action on in order to activate your account and log in.

Create and Configure a Product

Once your account is set up, add a Product and name it (e.g. “gateway-engine”, “my-product”, etc).

Once you have a product, you must configure it with resources either using the murano command line tool (recommended) or manually by using the Murano web UI.

Configure a Product Using murano

The murano cli tool is a command-line tool you can configure and use with your Murano solutions and products.

Below are some of the steps needed to quickly configure murano for using GWE.

Note

There will be more configuration commands for murano, but information for these commands is not yet available at this step of our getting-started guide.

  1. Configure User Name*

    This is the username or email address with which you use to login to Murano.

    Command (dev machine)

    cd ~/code
    murano config user.name <USER_NAME>
    
  2. Select and Configure your Business Account

    If it is your first time logging into your Murano account with murano on the command line, you will be prompted for your password. Once you have successfully logged in, the following command will show you a listing of all the business accounts you have access to.

    Command (dev machine)

    murano business list
    

    Note

    The murano config dialog stores configuration entries in .muranorc files but treats passwords differently. The first time you log in to an account and are prompted for your password, murano stashes the password in the file ~/.murano/passwords. If you do not want this stored in a local file, run rm ~/.murano/passwords after each session.

    Once you have logged in, choose the right business id and use it in the command below in place of <BUSINESS_ID>:

    Command (dev machine)

    cd ~/code
    murano config business.id <BUSINESS_ID>
    
  3. Configure Product ID

    In your Murano account, navigate to your product and click on the INFO tab. Copy the Product ID (sometimes referred to in this context as the PID) and use it in the commands below in place of <PRODUCT_ID>.

    Command (dev machine)

    cd ~/code
    murano config product.id <PRODUCT_ID>
    

    You can also find the Product ID using the following murano command:

    Command (dev machine)

    murano product list
    
  4. Tell MuranoCLI Where to Find the Spec File

    A “spec” file is a YAML file that describes the resources of a Murano Product. The GWE spec file is available in the release tarball and, now that you have unpacked it on your development machine, can be found at ~/code/gateway-engine/specs. The contents of the file are shown, below.

    Example (dev machine)

    $ cat gateway-engine/specs/gwe.spec
    ---
    resources:
    - alias: usage_report
      format: string
    - alias: engine_report
      format: string
    - alias: engine_fetch
      format: string
    - alias: device_info
      format: string
    - alias: update_interval
      format: string
    - alias: fetch_status
      format: string
    

    The default location murano uses for spec files is $PWD/specs for project directories. The following commands will set up ~/code/gateway-engine directory as a project directory.

    Command (dev machine)

    cd ~/code/gateway-engine
    murano config location.specs specs
    murano config product.spec gwe.spec
    # Verify the path <location.base/location.specs/product.spec>
    murano config --dump
    
  5. Create the Resources

    Command (dev machine)

    murano syncup -V --specs
    

Configure a Product Manually

If you have not configured murano, you can create the GWE resources manually using the Murano web UI.

The table, below, shows the resources you must add to the Product Definition, what to name them, and which format to choose for them.

GWE Resources
Alias Format Description
usage_report string Gateway Engine sends a report of all processes using its resources (gmq, device-client) to send data to Murano. This report contains information about how much network bandwidth is being consumed as well as other meta data about network requests.
engine_report string Gateway Engine reports information about what applications are installed and other meta data like uptime, exit codes, and versions.
device_info string Gateway Engine reports filesystem and OS data like OS and kernel version as well as free memory and disk space usage.
engine_fetch string Gateway Engine regularly checks this dataport for formatted messages containing instructions on new apps and updates to install.
fetch_status string Once an app is installed over-the-air or an update to an app is executed, Gateway Engine reports the STDOUT and STDERR from the app installer. This dataport is also used for uncaught exception logging.
update_interval string This value, in seconds, is the delay between each series of Gateway Engine reports and OTAU checkins.

Once you have finished configuring your Product, you can confirm it has the correct definition either by using the Murano web UI or with murano:

Example (dev machine)

$ murano syncdown --resources --no-update
+-----------------+--------+------------------------------------------+
| Alias           | Format | RID                                      |
+-----------------+--------+------------------------------------------+
| engine_fetch    | string | 584375baa68eb9e3d3c342caa5cf783a24965029 |
| engine_report   | string | d1cdfece4e080c723e7b2d57e0c508f6e4c96c20 |
| device_info     | string | 875c312cf0532a17556a05118374d215cbbfb4ee |
| update_interval | string | ab3885bc85c68fc0290ee1adbf7264671651e816 |
| usage_report    | string | b8405345023bb5dc72488ed072e96a5dc5f3424a |
| fetch_status    | string | 4c237e449a6fdff9e2ca72b3832c89902413eb6b |
+-----------------+--------+------------------------------------------+

Install GWE Onto Your Gateway

If you’re working directly from a gateway, use the following commands to get Gateway Engine onto your gateway.

Command (gateway)

mkdir /opt
cd /opt
basename $(curl -v -k --remote-name $(curl --silent -k https://s3-us-west-2.amazonaws.com/exosite-client-downloads/gateway-engine-release-area/gmq-master/latest.lnk) 2>&1 | awk '/GET/{print $(NF-1)}')

Command (dev machine)

ssh <USER>@<GATEWAY_IP> "mkdir /opt"
scp ~/code/GatewayEngine.v*.tar.gz <USER>@<GATEWAY_IP>:/opt

At this point, you have downloaded the latest release of GWE and copied it to your gateway.

Run the following command to untar the release package and install GWE onto your gateway:

Command (dev machine)

ssh <USER>@<GATEWAY_IP> "cd /opt
tar zxvf GatewayEngine.v*.tar.gz
cd gateway-engine
./install.sh"

Command (gateway)

cd /opt
tar zxvf GatewayEngine.v*.tar.gz
cd gateway-engine
./install.sh

Note

In some Linux environments, you will need to have Super-User permissions to run the installer.

If the type of Linux you are using has both root and non-root users, you will likely need to install GWE as root in order to use it. In this case, replace the ./install.sh from the command, above with sudo ./install.sh.

Note

The Installation Log File

The installation script generates a lot of logging output. In addition to showing the log output on the console’s STDOUT, it is captured to a file named gwe_install_${DATE_TIME}.log in the gateway-engine directory. Take note of the Installation Summary and Self Test at the end of the log. If you see any test failures or exceptions, please visit the Gateway Engine forum and create a new topic with information about your experience.

Configure GWE

Once the installation is complete, you will need to configure GWE for your IoT solution and Exosite account. This will require the PID (Project ID) from your Murano account and the serial number of your gateway.

You can determine the serial number of your gateway in two ways:

  1. The MAC address
  2. Any Custom Serial Number

Note

Custom Serial Numbers

For the purpose of this Getting Started guide, the Custom Serial Number method will not be covered in detail, but can be used via the gwe --set-uuid <UUID> command.

Configure the GWE Serial Number

GWE can be configured to use the MAC address of the Internet interface of your choosing (e.g., eth0, wlan0, ppp0, etc.). Using the MAC address of a piece of hardware like an ethernet port, a Wi-Fi port, or a cellular modem is a great option for deconflicting serial numbers and offers a standard way of identifying hardware between customers, vendors, manufacturers, and most others in the chain of IoT goods and services.

When configured this way, GWE uses the MAC address of the Internet interface (i.e., iface) you specify with ALL CAPS and ‘:’ formatted. To view a list of the available Internet interfaces on your gateway, use the ifconfig command.

The example, below, shows the command for configuring GWE to use the MAC address of iface eth0 as its serial number (a.k.a., uuid). After configuring GWE, it prints the new configuration to the console. GWE doesn’t fill in the uuid value until after it starts for the first time.

Example (gateway)

$ gwe --set-iface eth0 -d DEBUG
Found interface 'eth0' with MAC address (serial/uuid): FF:10:C2:9B:A8:46
[device]
cik = ''
model = ''
vendor = ''
uuid = ''
iface = eth0

To see what the MAC address of any interface is, you can use the following command as a convenience function.

Command (gateway)

gwe --mac-address <IFACE>

Configure the GWE Product ID

Using the PID from a previous step, use the following command to configure GWE for your Murano account:

Command (gateway)

gwe --set-product-id <PRODUCT_ID>

Due to legacy reasons, GWE uses the PROJECT_ID as both the vendor and model entries in the GWE configuration. See the example below:

Example (gateway)

$ gwe --set-product-id dubhxzv0r4e1m7vj
[device]
cik = ''
model = dubhxzv0r4e1m7vj
vendor = dubhxzv0r4e1m7vj
uuid = ''
iface = eth0

Add a Device

Navigate to the Products tab of the Murano web UI, select the GWE product (whatever you named it), and click on the DEVICES tab. When you click the “NEW DEVICE” button, use the serial number GWE is configured for as the serial number for your new Murano GWE device and name it.

You will see this new device appear in the list of available devices in the GWE product of your Murano account. If you are following this getting-started guide in order, the new device should be showing a STATUS of notactivated.

Reboot

To complete the installation, you will need to reboot the gateway.

The installation is incomplete until a gateway reboot because it is the last step in determining whether or not GWE will start on boot. If after rebooting the gateway GWE is not running, then something went wrong with the installation (if this happens, please visit community forum.

To reboot, you can toggle the power or use the following command.

Command (gateway)

reboot

Note

GWE uses supervisord to start itself on boot, and once it starts, it will start GWE as well as all other installed default and custom gateway applications.

Verify

Watch for new data in your new Murano GWE device.

Once the reboot has completed, you will notice that supervisord and gwe processes are running in the output of the ps -ef command. Sometimes there are a lot of processes and the ps -ef command can be too much to read through. You can filter the output with grep (e.g., ps -ef | grep 'super\|gwe\|gmq'). You can also use the supervisorctl status command to view the status of the GWE applications.

Example (gateway)

$ supervisorctl status
gmq                           RUNNING    pid 621, 00:01:38
gwe                           RUNNING    pid 620, 00:01:38

A few seconds after rebooting the gateway you should see two things change on the GWE device in your Murano account.

  • The device’s STATUS should be showing activated
  • Data appears in the aliases/resources of your GWE device

You can also check to see if the gateway has successfully activated by checking for the existence of a CIK in the GWE configuration with the following command:

Command (gateway)

gwe --gateway-cik

Example (gateway)

A non-activated GWE.

$ gwe --gateway-cik
''

Example (gateway)

An activated GWE.

$ gwe --gateway-cik
3803226073f6f2feb51a9010bd1d3e53143214a7

For additional functionality of Exosite products available on your gateway, take a look at the output of the commands in the next section.

Example (gateway)

The supervisorctl cli

The supervisorctl command-line interface is extremely powerful and incredibly useful. It is highly recommended that you run this command (``supervisorctl`` using ``sudo`` if necessary) and then type help when you have entered the interactive cli.

$ supervisorctl
gmq                                RUNNING      pid 1184, uptime 1:02:51
gwe                                RUNNING      pid 1184, uptime 1:02:51
supervisor> help

default commands (type help <topic>):
=====================================
add     clear    fg        open   quit     remove    restart    start   update
avail   exit     maintail  pid    reload   reread    shutdown   stop    version

supervisor>

Example (gateway)

The Device Client cli

The device-client library has a lightweight command-line interface accessible with the callable gdc.

gdc --help

Example (gateway)

The GWE cli

The gwe process seen in ps -ef and supervisorctl status output has a robust command-line interface.

gwe --help

Example (gateway)

The Gateway Message Queue cli

The gmq process has a command-line interface that helps configure some runtime behavior like timers and logging.

gmq --help

Summary

The steps in this guide were designed to get you moving as quickly as possible with GWE and Exosite. If you have questions, concerns, or suggestions on improvements, please visit the community forum.

At this point you are probably ready to start using GWE to host your Custom Applications. Next, take a look at the following sections: