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.

The steps that follow make references to “gateway” and “dev-machine”. In order to get Gateway Engine set up onto your gateway, you will need another computer (i.e. dev-machine) on which to execute some commands as well as an IoT gateway. When a command is provided, a note on where it needs to be run is given.

A command that needs to run on the dev-machine will look like:

Command (dev-machine)

uname -a

A command that needs to be run on the gateway will look like:

Command (gateway)

uname -a

Download and Unpack GWE

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

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

To create an account or login to an exising one, click the link below.

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. If you use the murano command line tool, copy the Product ID down for use later on in this guide.

Configure a Product Using MuranoCLI

The MuranoCLI 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 ../specs/resources.yaml
    ---
    device_info:
      allowed: []
      format: string
      settable: false
      unit: ''
    engine_fetch:
      allowed: []
      format: string
      settable: true
      unit: ''
    engine_report:
      allowed: []
      format: string
      settable: false
      unit: ''
    fetch_status:
      allowed: []
      format: string
      settable: false
      unit: ''
    gwe_debug:
      allowed: []
      format: string
      settable: false
      unit: ''
    update_interval:
      allowed: []
      format: number
      settable: true
      unit: ''
    usage_report:
      allowed: []
      format: string
      settable: false
      unit: ''
    

    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 resources.yaml
    # 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 Using Web UI

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.
gwe_debug string Should gwe encounter an uncaught exception, it will upload details of the error to this resource.

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 |
| gwe_debug       | string | 6c257ed46a7fdef9e9cau2b3e32ad9402d13ab5c |
+-----------------+--------+------------------------------------------+

Install GWE Onto Your Gateway

Use either of 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

Warning

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 PRODUCT_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

Authentication Method (optional)

Note

If your Murano Product Settings are configured for CIK or Token authentication, you can skip this section and proceed to Add a Device.

To verify/change the authentication settings for your Product, use the following commands:

Command (dev-machine)

$ murano setting read Gateway.provisioning auth_type
token

To change this setting so TLS Client Certificates are used when connecting to Exosite:

Command (dev-machine)

$ murano setting write Gateway.provisioning auth_type certificate

Depending on what method of authentication you’ve chosen in your Murano Product Settings (e.g. CIK, Token, TLS Client Certificate), you may need to tell gwe where to find its TLS Private Key and Client Certificate.

To configure gwe for the TLS Client Certificate method of authentication, determine the path on the gateway filesystem to the private key and the client certificate and replace the dummy paths in the commands below.

Command (gateway)

$ gdc cfg set tls_provision keyfile /path/to/key.pem -f gwe
$ gdc cfg set tls_provision certfile /path/to/cert.pem -f gwe

Add a Device

Note

If your Murano Product Settings is configured to allow connecting devices to provision themselves (i.e. Allow devices to register their own identity), which is the default behavior, you can skip this step. To check the configuration setting in your product, the following command is provided for convenience.

Command (dev-machine)

$ murano setting read Gateway.provisioning presenter_identity
true

To turn this feature off and only allow whitelisted devices to connect, use the following command:

Command (dev-machine)

$ murano setting write Gateway.provisioning presenter_identity false

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:

Note

If using TLS Client Certificate authentication method in your product, gwe will not get a CIK/Token. In this case, gwe is assumed to be activated and skips the CIK/Token provisioning sequence.

Command (gateway)

gwe --gateway-cik

Example (gateway)

not activated

$ gwe --gateway-cik
''

Example (gateway)

activated

$ 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)

supervisorctl

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)

gdc

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

gdc --help

Example (gateway)

gwe

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

gwe --help

Example (gateway)

gmq

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: