Three Labs GATE-Ware

Fast track your MultiTech Conduit development

5-Minutes to the finish line

GATE-Ware is an application designed to make MultiTech conduit development and deployment simple - 5-minute simple.

The following sections will get you up and running quickly and easily. Please feel free to reach out with any questions or comments about the information in these documents. We’re always interested in hearing from you at: info@threelabs.io.

The feature list keeps growing

If you’re new to GATE-Ware, you may wish to have a look at the Questions & Answers section for a general overview of the Application. If you’re familiar with the product, then the Configuration and Reference sections are a great place to find out about new features.

Chapter 1

Introducing GATE-Ware

Fast track your MultiTech Conduit development

5-Minutes to the finish line

GATE-Ware is an application designed to make MultiTech conduit development and deployment simple - 5-minute simple.

The following sections will get you up and running quickly and easily. Please feel free to reach out with any questions or comments about the information in these documents. We’re always interested in hearing from you at: info@threelabs.io.

The feature list keeps growing

If you’re new to GATE-Ware, you may wish to have a look at the Questions & Answers section for a general overview of the Application. If you’re familiar with the product, then the Configuration and Reference sections are a great place to find out about new features.

Questions & Answers

What is GATE-Ware?

GATE-Ware is an application that connects your Conduit to your cloud within 5 minutes of unboxing.

The application is designed to be a complete solution for cloud integration, device management, and edge processing leveraging LoRaWAN.

What do you mean “connects?”

Your freshly-unboxed Conduit will:

  • Create a broker connection to your cloud via MQTT over TLS.
  • Transmit data via MQTT from new and existing LoRaWAN end nodes to your cloud.
  • Expose MultiTech’s complete mPower API to your cloud via MQTT - for complete remote management.
  • Exercise a pass-through example edge processing routine, which you can then modify with your own logic.

All within 5 minutes.

What form does it take?

GATE-Ware takes the form of a standard MultiTech Custom Application, deployable remotely (DeviceHQ or VPN) or locally.

You can convert your already field-deployed Conduits to using GATE-Ware within minutes.

What cloud does it communicate with?

We support standard MQTT on any cloud. This includes AWS IoT Core, Azure IoT Hub, and Azure IoT Central.

Is configuration part of the 5 minutes?

Yes, GATE-Ware’s configuration file is hyper-simple. Just drop your cloud’s endpoint and credentials into a centralized json configuration, then GATE-Ware does the rest.

Later you can revisit the configuration file and extend functionality.

Are there recurring fees?

None. A one-time license key is all you need to purchase, then a major versioned copy of GATE-Ware is yours for eternity.

The GATE-Ware team believes that LoRaWAN should not be treated as a Telco or a SaaS.

What about data privacy?

GATE-Ware is privacy by design, in that data is securely transferred to your cloud, without involving third parties. The application supports MQTT over TLS. GATE-Ware never sends your data anywhere but to your configured endpoint.

Can I customize GATE-Ware?

Yes, via our easy to use edge-processing frameworks, you can modify, route and even discard data from LoRaWAN end nodes - we’ve found this to be very desirable for selectively transmitting data via costly cell links. Unlike SaaS providers, GATE-Ware transmits only what you want you send, to your endpoint only.

How restrictive are the edge frameworks?

As long as the Conduit’s Linux will run it, and it adheres to the very basic data I/O requirements of GATE-Ware, then you can write your edge processing logic in whatever language you wish.

We provide examples in Python and Bash.

GATE-Ware introduces nothing proprietary and no funky custom languages or schemas.

Who was GATE-Ware made for?

We made GATE-Ware for ourselves at first! Three Labs grew as a consulting business and has deployed MultiTech-based LoRa solutions for clients for several years.

Initially, we were seeking a method for reducing our own engagement and development overhead:

“If we could just spin up each of these engagements in 5 minutes..”

Ultimately the wish became a reality as we designed our very own version of what we wanted from a LoRa application framework.

We decided to package GATE-Ware for end users, along with several features missing from the LoRaWAN SaaS market leaders, like:

  • Edge processing, via what we call “Transforms.”
  • Privacy by design - your data is truly your data. We have no special hooks or requirements… or even servers for consuming any of your data.
  • A One-time license fee! We realize that this is virtually unheard of, but made possible because we don’t have to incur the costs of ingesting your data.
  • Hyper focus on maintaining minimal complexity - GATE-Ware’s config file is a one-stop shop and simple.

GATE-Ware is our very own custom application. We use the exact same product that we make available to customers for end use.

What else should I consider?

Whether you choose GATE-Ware or a SaaS, you haven’t escaped the responsibilities of owning and maintaining the physical LoRaWAN network.

Fortunately, GATE-Ware can assist you with the responsibilities below in ways that a SaaS typically does not:

  1. Deploying the network properly and ensuring link health (i.e. placement and transmission path of Conduit and end devices):

    • We’ve created some best practices guides for our customers. If you’d like additional help, Three Labs can provide consultation.
  2. Paying for data to/from the Conduit (especially on Cellular):

    • Reduce data costs by transmitting only interesting data, using edge processing.
  3. Running a cloud for your own business logic:

    • Reduce compute costs by installing logic in the Conduit and having no third party SaaS costs.
  4. Managing your Conduit’s health:

    • GATE-Ware exposes the complete MultiTech mPower interface, providing full remote configuration. No VPN or local access to the conduit is required.

How do I get started?

‘Getting started’ is easy, and may be all that you need to do if data pass-through and mPower access is all that you need. Head over to the section linked below to quickly complete your setup:

> Click here to visit the Getting Started page

GATE-Ware encourages the use of edge processing:

If you wish to create business logic for acting on your data before transmission, you’ll be able to do so via GATE-Ware’s “Transform” functionality. Head over to the section linked below to see examples and make use of edge processing features.

> Click here to visit the Transforms page

We encourage you to take a complete tour of the GATE-Ware documentation, as we try to keep it simple and effective.

Please do not hesitate to reach out directly if there’s something that we can helop clarify, or something additional that you’d like to see: info@threelabs.io.

Getting Started

1. Complete Pre-Installation Requirements

The requirements below are the base components and infrastructure that one needs for before setting up and running the GATE-Ware application.

  1. Your Conduit must be connected and initial configuration steps according to Multitech’s instructions here.
  2. You must have the GATE-Ware distribution on your computer. *
  3. You must have a valid GATE-Ware license. *
  4. The backend (AWS, Azure or MQTT) must be configured and credentials generated according to the provider’s instructions. GATE-Ware can be run without cloud TLS credentials, but they are strongly recommended.

* For software distributions and licenses, please request an evaluation license at eval.gateware.io or contact us directly at support@threelabs.io.

2. Create a Configuration File

Whether you choose a cloud provider or roll-your-own offline solution, GATE-Ware has you covered with appropriate with “base configurations” for each scenario.

Base configuration step-by-step:

A “base configuration” is nothing more than the minimum set of configuration attributes required by GATE-Ware. For complete information on all configuration options, please see the Attributes section.

  1. Identify your cloud below (or custom/roll-your-own MQTT).
  2. Cut and paste the associated JSON content into a new file named: gateware.json.
  3. Replace the example credentials, endpoint, port and license key with your cloud-specific and purchased key values.

MQTT - Including AWS IoT Core

Click to Expand gateware.json: MQTT Broker - No Authentication
{
  "backend_mqtt_endpoint_host": "broker.example.com",
  "gateware_license_key": "abcd="
}
Click to Expand gateware.json: MQTT Broker - TLS with Username & Password Authentication
Click to Expand gateware.json: MQTT Broker - TLS with Client Certificate Authentication

Microsoft Azure IoT

Click to Expand gateware.json: Azure IOT Hub - DPS Single Device Enrollment
Click to Expand gateware.json: Azure IOT Hub - DPS Group Enrollment
Click to Expand gateware.json: Azure IOT Central - Device Connection Group

3. Install GATE-Ware on your Conduit

There are three options for installing GATE-Ware on your Conduit. Each may be more or less suitable depending on your particular need.

For example, you may decide to use Direct (SSH) for installing during iterative development or manufacturing.

For deployed units, DeviceHQ may be the best option - this method can also be used for converting already deployed Conduits to using GATE-Ware.

Direct (SSH)

The included install-to-conduit.sh script will install the GATE-Ware distribution to the Conduit and automatically start the main application. The script will also configure the Conduit to automatically run GATE-Ware on boot.

  1. Double check that you’ve created your configuration file: gateware.json. See section: Create a Configuration File above.
  2. Copy the gateware.json file to the gateware/config directory in your GATE-Ware distribution.
  3. Substituting your credentials and Conduit IP address, use the following commands to install GATE-Ware to the Conduit:
% export CONDUIT_USER="admin"
% export CONDUIT_PASS="ExamplePassword123"
% ./install-to-conduit.sh gateware 192.168.2.1

Direct (Conduit Web Interface)

  1. Double check that you’ve created your configuration file: gateware.json. See section: Create a Configuration File above.
  2. Copy the gateware.json file to the gateware/config directory in your GATE-Ware distribution.
  3. Use the following command to create a GATE-Ware distribution archive:
cd gateware
tar --hard-dereference -hczf ../gateware.tar.gz *
  1. Browse to the Conduit’s web interface and navigate to the Apps page.
  2. Click the + Add Custom App link on the top-right of the page.
  3. Enter the following information:
    • App ID: GATE-Ware
    • App Name: GATE-Ware
    • Choose File: Select the gateware.tar.gz file you created in step 3.

DeviceHQ

  1. Double check that you’ve created your configuration file: gateware.json. See section: Create a Configuration File above.
  2. Use the following command to create a GATE-Ware distribution archive:
cd gateware
tar --hard-dereference -hczf ../gateware.tar.gz *
  1. Navigate to the DeviceHQ Developer Page and log in.
  2. Click the + Upload App button on the top-right of the page.
  3. Choose File: Select the gateware.tar.gz file you created in step 2.
  4. Click the GATE-Ware app in the list of apps.
  5. Click the Configuration tab.
  6. Click the + Upload Configuration button.
  7. Click the Choose File button and select the gateware.json file you created in step 1.
  8. Enter a helpful description for the configuration file.
  9. Navigate to the DeviceHQ Device Page and select the Conduit you want to install GATE-Ware on.
  10. Click Schedule -> Install App -> GATE-Ware.
  11. Choose the App Configuration you uploaded in step 9.

The next time your device checks into DeviceHQ, GATE-Ware will be installed and start automatically. You can also force a check in to shorten the wait time.

Edge processing

Edge processing via “Transforms”

Transforms are simply code files where you can implement your own edge/business logic. The edge processing framework of GATE-Ware consists of Transforms, which are referenced by your single JSON configuration file and act on specific data.

> Click here to read more about Transforms

Test Servers

Ready to test some data flow over an MQTT server?

Three Labs has created test servers so that you can briefly test your Conduit’s data channel on a known-working MQTT endpoint.

mPower API commands are disabled on test servers (so you don’t reconfigure each other’s conduits).

Three Labs does not believe in exposing your sensitive data to third-parties/telcos, let alone a public test server.

For this reason external data channels will ever be configured by default on GATE-Ware. Be safe with your data!

To use a test server:

  1. Set the endpoint on your GATE-Ware config file as follows:
{
  "backend_mqtt_endpoint_host": "mqtt.gateware.io",
  "gateware_license_key": "your-license-key-here"
}
  1. Refer to section: Install GATE-Ware on your Conduit to install your updated configuration.

  2. After installing, you can use your favorite MQTT client to subscribe to your Conduit’s topic on endpoint: mqtt.gateware.io.

    Example - to see all end device uplink data from your Conduit:

    mosquitto_sub -h mqtt.gateware.io -v -p 1883 -t gateware/your_conduit_serial_number/lora/+/up
    

    NOTE: Make sure to replace your_conduit_serial_number with the serial number of your conduit.

Chapter 2

Configuration

Set up in minutes, fine tune as you wish

GATE-Ware is configured via a single JSON file. Most installations can be completed using just a few configuration lines. You’ll also have the option to further adjust the installation via a complete set of options.

All configuration styles, from the hyper-simple to the power-user playground will be discussed in the following sections.

Attributes

Full list of attributes, with some powerful options

The sections below expose the complete set of GATE-Ware configuration options. Please take note of the (required) vs (optional) markers, as most options exist to extend basic functionality.

It is worth noting that basic functionality is all that most users of the application will ever need to implement in their configuration files. However, Optional values extend the application in some powerful ways.

GATE-Ware Core

Option Values default value Purpose
backend (optional, string) mqtt “Backend” is where we are pushing data from sensors to, acceptable values: mqtt, aws, azureiot, azure
gateware_backend_watchdog_max_interval (optional, int) 120 In seconds, interval we want the backend watchdog waiting before restarting GATE-Ware
gateware_external_command_timeout (optional, int) 60 In seconds, timeout for running system commands for things like app-manager
gateware_license_key (required, string) no license GATE-Ware license key
gateware_log_destination (optional, string) syslog Logging destination, supports: syslog, file, stdout
gateware_log_filename (optional, string) /var/log/gateware.log If log destination is set to file this is where logs go
gateware_log_level (optional, string) info Logging level minimum, supported: trace, debug, warn, error
gateware_uplink_transforms (optional, array of transforms) See: Transforms

Backend: Azure IoT

Option Values default value Purpose
backend_azure_ca (optional, string) DiGiCert Global Root G2 Certificate used for configuring MQTT w/ TLS for connection with Azure, described. here and here. If not specified the DigiCert Global Root G2 certificate is used, per Microsoft recommendation.
backend_azure_dps_group_enrollment_registration (optional, boolean) false This will enable group enrollment via Azure DPS. Individual enrollment is the default
backend_azure_dps_registration_id (optional, string) If backend_azure_dps_registration_id_from_serial is disabled, this string is used for the MQTT client ID
backend_azure_dps_registration_id_from_serial (optional, boolean) true Client ID for MQTT sessions will be derived from the conduit serial
backend_azure_dps_scope_id (required, string) This is unique per DPS configuration
backend_azure_iot_hub_heartbeat_enabled (optional, boolean) true IoT Hub heartbeat publishes an empty message to the device’s topic in an attempt to keep the TCP connection alive
backend_azure_iot_hub_heartbeat_interval (optional, int) 900 In seconds, how often do we send the heartbeat
backend_azure_sas_primary_key (required, string) Primary symmetric key
backend_azure_sas_secondary_key (required, string) Secondary symmetric key

Backend: MQTT / AWS

Option Values default value Purpose
backend_mqtt_ca (optional, string) Certificate used for configuring MQTT w/ TLS for connection
backend_mqtt_client_certificate (optional, string) Client certificate for MQTT
backend_mqtt_endpoint_host (required, string) MQTT broker hostname
backend_mqtt_endpoint_keepalive (optional, int) 60 In seconds, MQTT keep alive via Paho
backend_mqtt_endpoint_port (optional, int) 1883 MQTT port
backend_mqtt_endpoint_qos (optional, int) 1 QoS
backend_mqtt_max_publish_attempts (optional, int) 150 How many times do we attempt to publish a message when failures occur. 0 is infinite
backend_mqtt_password (optional, string) Password for authentication
backend_mqtt_private_key (optional, string) Private key for client certificate
backend_mqtt_use_tls (optional, boolean) false Whether or not to use TLS during connection
backend_mqtt_username (optional, string) Username for authentication

Transforms

Matching Order

GATE-Ware compares the incoming message’s AppEUI and LoRa Port with transforms defined in the configuration, selecting the most specific match. An exact match will always win over a wildcard match.

Wildcards

AppEUI wildcards are defined using the "appeui":"ANY" parameter.

LoRa Port wildcards are defined using the "port":-1 parameter.

Built-In Transform(s) Configuration

A number of Built-In transforms are available to perform common operations on data.

> Click to see general information on Built-In Transforms.

Forward

GATE-Ware can be configured to forward messages in the original form received from edge devices to the backend.

For example, to forward all messages which do not have a more specific transform configured, add the following to your gateware.json:

{
  "gateware_uplink_transforms": [
    {
      "appeui": "ANY",
      "lora_ports": [
        {
          "port": -1,
          "action": "forward"
        }
      ]
    }
  ]
}

Discard

GATE-Ware can be configured to discard messages received from edge devices. This is useful for conserving Internet bandwidth (for example, if you are using a cellular connection).

For example, to discard any messages which do not have a more specific transform configured, add the following to your gateware.json:

{
  "gateware_uplink_transforms": [
    {
      "appeui": "ANY",
      "lora_ports": [
        {
          "port": -1,
          "action": "discard"
        }
      ]
    }
  ]
}

Text

GATE-Ware can be configured convert the LoRa uplink payload to ASCII text.

For example, to convert messages which do not have a more specific transform configured, add the following to your gateware.json:

{
  "gateware_uplink_transforms": [
    {
      "appeui": "ANY",
      "lora_ports": [
        {
          "port": -1,
          "action": "text"
        }
      ]
    }
  ]
}

Custom Transform(s) Configuration

GATE-Ware can be configured to run custom transforms. This is useful for performing edge processing on LoRa uplink payload from your devices.

> Click to see general info on Custom Transforms

Custom Transform Example

For example, to run the transforms/bash_examples/insert_uuid.sh custom transform on any messages to AppEUI 2b-7e-15-16-28-ae-d2-a5 on LoRa Port 5, add the following to your gateware.json:

{
  "gateware_uplink_transforms": [
    {
      "appeui": "2b-7e-15-16-28-ae-d2-a5",
      "lora_ports": [
        {
          "port": 5,
          "action": "external_handler",
          "external_handler": "transforms/bash_examples/insert_uuid.sh",
          "external_handler_timeout_seconds": 1
        }
      ]
    }
  ]
}

Troubleshooting

Configuring Logging

The gateware_log_level configuration option controls the verbosity of GATE-Ware log messages. The default value is info which means that only informational messages are logged.

When troubleshooting, it can be helpful to increase the verbosity of GATE-Ware by changing the gateware_log_level to debug. This will log more information about the internal operations of GATE-Ware.

Steps to Configure Logging:

  1. Edit the gateware.json configuration file and add the following setting: "gateware_log_level": "debug"
  2. Browse to your Conduit UI https://192.168.2.1/administration/debug
  3. Set the Debug Log Level field to DEBUG

Important Notes:

  • It is recommended to use the debug & trace log levels only when troubleshooting and never in production environments.
  • The debug & trace log levels are very verbose and can cause performance issues.
  • The debug & trace log levels may cause GATE-Ware to log sensitive information, such as passwords.

Accessing Logs

Downloading Logs

The GATE-Ware logs can be downloaded from the Conduit management UI page:

https://192.168.2.1/status/statistics/system (replacing 192.168.2.1 with the IP address of your Conduit).

Viewing Logs over SSH

The GATE-Ware logs can be viewed over SSH by running the following command:

tail -F /var/log/messages
Chapter 3

Transforms

Edge processing via “Transforms”

GATE-Ware can be configured to apply custom transforms to the LoRa uplink payload. This is useful for performing custom operations on the LoRa uplink data, and even selectively transmitting only the data that you want to keep.

Why process data in a costly cloud service?

You can use custom transforms to convert the payload to a different format, or to perform calculations on the payload, or even perform actions directly on the gateway.

We’ve even had customers write transforms that perform lengthy calculations and averages, moving most of their business logic out of the cloud and onto the Conduit - reducing backend costs a by a great amount.

Built-In Transforms

Use Transforms without even creating one

GATE-Ware comes packages with common Transforms built right in. The great thing about Built-In transfroms is that using them requires only a configuration change. Built-Ins available to you immediately are:

Forward

Configure selective forwarding of data.

Discard

Configure discarding of data.

Text

Convert LoRa uplink data to ASCII for human readability.

> Click here for steps toward configuring Built-In transforms

Custom Transforms

The Basics

Custom transform can be written in any language that can be executed from the command line. The transform program must be executable and must return a JSON object. In order to implement a Custom Transform, two components are necessary:

  1. The custom transform source itself.
  2. An entry in the GATE-Ware configuration file.

To get you started, some custom transform examples have been placed in the transforms/ directory, with an accompanying configuration example.

Example

For example, to run the transforms/bash_examples/insert_uuid.sh custom transform on any messages to AppEUI 2b-7e-15-16-28-ae-d2-a5 on LoRa Port 5, add the following to your gateware.json:

{
  "gateware_uplink_transforms": [
    {
      "appeui": "2b-7e-15-16-28-ae-d2-a5",
      "lora_ports": [
        {
          "port": 5,
          "action": "external_handler",
          "external_handler": "transforms/bash_examples/insert_uuid.sh",
          "external_handler_timeout_seconds": 1
        }
      ]
    }
  ]
}

The sections below discuss the general I/O behind Custom Transforms, as well as a method for discarding and timing out if processing goes too long.

Input

The input to your custom transform is delivered as a JSON object via stdin.

The JSON object comes directly from the Conduit and follows the specification of the Up Message Format.

Output

The output of your custom transform must be valid JSON returned via stdout.

Discarding A Message

If you wish to discard a message, simply do not return any stdout.

Timeout

The custom transform will be terminated if it does not return a valid JSON object within the specified external_handler_timeout_seconds.

Chapter 4

Examples

GATE-Ware is a malleable solution with no recurring fees:

You may notice a theme here, the avoidance of monthly fees! LoRaWAN is a device protocol, not an ISP. Sending YOUR data to YOUR cloud can and should be accomplished without paying a SaaS or Telco.

To send data to your cloud within 5 minutes, see our quickstart guide:

> Click here to visit the Getting Started page

Add ANY device to GATE-Ware, it’s free to do:

We’ll begin our GATE-Ware examples by showing you just how easy it is to add a custom device. We don’t see any reason why you should pay indefinitely for a one time device addition, so GATE-Ware was designed to help.

Most LoRaWAN devices have a very simple command/data frame set. Adding a custom device to your system is especially painless when using GATE-Ware. Reminder: you can write your integration/transforms in any language you wish!

Bonus! We added some edge processing - running on the MultiTech Conduit’s own CPU, not on a paid cloud service.

> Click here to get started adding a device

Integrate Your Device

Custom Device Example using the IES-2051 Flowmeter

For the custom device integration example we’ll be using the IES-2051 flowmeter. The ION IES-2051 device is a high-accuracy LoRaWAN turbine flowmeter. The device communicates flow information hourly, and upon a button press.

DIY LoRaWAN device integrations are simple, and GATE-Ware makes them even simpler. Let’s IES-2051’s data packet:

IES-2051 Hourly Flow Data Packet:

Byte Location:   Data:              Range & Description:     
Byte  0          Sensor type        0 to 255 - The 2051 is IES product type 4, this never changes
Byte  1          Firmware version   0 to 255 - Represents current firmware version
Byte  2          Transmit count     0 to 255 - Increments for each packet
Bytes 3-6        Total Gallons      0 to 4B  - Counts gallons up to 4 billion
Bytes 7-8        Flow Time          0 to 65K - Counts flow time in seconds
Bytes 9-10       Flow Events        0 to 65K - Counts "events" where water flowed for 3 seconds or more

Create a Transform:

To create an integration let’s use GATE-Ware’s Transform feature, which allows the user to incur the cost of integration just once. Transforms also give the user the added benefit of including any edge processing on the gateway’s hardware, where it doens’t increase your cloud costs.

The transform below is effectively a parser + some simple edge processing. Let’s consider the recipe:

  1. Parse the bytes into variables, according to the device frame
  2. Use a couple of the variables to process a simple leak check at the edge.

The Code, using Python:

Transforms can be written in any language that the MultiTech Conduit’s Linux build will run. Here we chose to use Python for our Transform:

#!/usr/bin/env python3

import json
from base64 import b64decode
from sys import stdin,stdout

def main():
    # Read the last message from a file named /tmp/last_message.json
    try:
        with open('/tmp/last_message.json', 'r') as f:
            last_message = json.loads(f.read())
    except:
        last_message = {}

    # Read the message from stdin
    message = json.loads(stdin.read())

    #--------------------#
    # DEVICE INTEGRATION #
    #--------------------#

    # Decode the base64 encoded payload field into a byte array
    bytes = b64decode(message['data'])

    # The first byte is an integer representing the sensor type
    message['sensorType'] = bytes[0]

    # The second byte is the firmware_version
    message['firmwareVersion'] = bytes[1]

    # The third byte is the transmitCount
    message['transmitCount'] = bytes[2]

    # The next 4 bytes are a float representing the gallons
    message['gallonsOdometer'] = int.from_bytes(bytes[3:7], byteorder='big') / 1000

    # The next 2 bytes are the flowTime (in seconds)
    message['flowTime'] = int.from_bytes(bytes[7:9], byteorder='big')

    # The next 2 bytes are the eventCount
    message['eventCount'] = int.from_bytes(bytes[9:11], byteorder='big')

    # Write the message object to a file named /tmp/last_message-[deviceeui].json
    with open('/tmp/last_message-'+ message.get('deveui') +'.json', 'w') as f:
        f.write(json.dumps(message, 
            ensure_ascii=True, # no unicode
            separators=(',', ':')))

    #------------------------------------------#
    # EDGE PROCESSING EXAMPLE - LEAK DETECTION #
    #------------------------------------------#

    # If the last_message is not an empty object
    if last_message:

        # Let's set the criteria for a detection:
        # - Water flowing for 1 hour without a break 
        # - Consider a button press

        if (last_message.get('eventCount') == message.get('eventCount') and last_message.get('flowTime') + 3600 < message.get('flowTime')):
            message['warning'] = 'Detected a potential leak!'

            # Write the message to stdout
            stdout.write(json.dumps(message, 
                ensure_ascii=True, # no unicode
                separators=(',', ':'))) # no whitespace

if __name__ == "__main__":
    main()

Have a quick scan through the code above - block comments highlight two sections where integration then edge processing take place. This source was written for use with the IES-2051, but can easily be adapted to other devices by simply adjusting the parser for a different data packet.

Transforms are incredibly flexible, can be accomplished in under 50 lines of code (mostly cut and paste), and you avoid paid vendor lock-in.

Not interested in writing code, but still want to avoid a telco style monthly fee? Hit us up at info@threelabs.io and we can help you integrate your device quickly.

Chapter 5

mPower API Access

MPower API Access

Complete Administration via MQTT

The mPower API is a RESTful API that allows you to manage all aspects of the MultiTech Conduit platform.

GATE-Ware exposes the complete mPower API to the user. This allows you to manage the Conduit platform from your existing backend connection.

Single Pane of Glass

GATE-Ware’s API access over MQTT creates a single pane of glass for managing your complete Conduit deployment. The interface removes the requirement for UI configuration of your conduit, and removes and requirement for a VPN - especially beneficial when communicating via cellular, where VPN can consume large amount of data just by remaining connected.

mPower API access also allows you to manage your devices via scripting a series accesses via mPower API, which can then be run across conduits autonomously from your own backend business logic.

> Click to get started with accessing the mPower API via GATE-Ware

Sending Requests

Topic Structure

Requests

mPower API requests should be sent to the topic:

gateware/[conduit_serial|broadcast]/mpower/[method]

The conduit_serial is the serial number of the Conduit. Alternatively, the broadcast topic can be used to send the request to all Conduits.

The method is the HTTP method to use for the request. The following methods are supported:

  • get
  • post
  • put
  • delete

Responses

mPower API responses will be sent to the topic:

gateware/[conduit_serial]/mpower/[method]

Message Format

Requests

Refer to the mPower API documentation for API details: https://www.multitech.net/developer/software/mtr-software/mtr-api-reference/collection-endpoints/

The message payload should be a JSON object with the following fields:

{
  "headers": [],
  "message_id": "unique message id",
  "payload": "{}",
  "query_string": "status",
  "topic": "gateware/21560532/mpower/get"
}
  • headers - An array of HTTP headers to send with the request. Each header is a string, for example: Header: value.
  • message_id - A unique message id. This is used to correlate the request with the response.
  • payload - The payload to send with the request. This is optional and can be an empty string.
  • query_string - The value of query_string will be appended to the URL of the request. For example, if the query_string is status, the URL of the request will be https://127.0.0.1/api/status.
  • topic - only required for Azure, where the MQTT topic is not available. The value of topic will be used as a replacement for the MQTT topic.

Responses

{
  "topic": "gateware/21560532/mpowerresponse/get",
  "payload": {
    "code": 200,
    "result": [],
    "status": "success"
  },
  "message_id": ""
}
Chapter 6

Reference Material

General Topics

In this section you’ll find reference materials such as version histories, further reading and a glossary of application specific terminology.

Please feel free to contact the team at info@threelabs.io for questions and information about this and all content presented on our documentation site.

Version History

v1.2.0

Syslog

Adds a syslogforwarder, capable of:

  • Acting as a local syslog server such that the Conduit can be configured to send logs to via remote syslog server options.
  • Automatically configure system to send syslogs to the syslogforwarder local server.
  • Automatically configuring the loglevel of the Conduit sending logs.
  • All configuration necessary to use the syslogforwarder is done within gateware.json, preserving the single configuration location.

Azure IoT Central Support:

  • A new backend configuration has been created, specifically for IoT Central
  • Implement Conduit and Device template in IoT Central to enable fast telemetry visualization.

ION Energy Systems 2051 Flowmeter Transform Example:

  • The transform is now configured in the default gateware.json file.
  • The transform can perform basic leak detection using only edge processing by: – Storing the most recent uplink – Comparing the incoming message with the previous message – Alerting if the meter has observed non-stop flow for over 1 hour – Always relays uplinks sent as a result of a button press

v1.1.0

General:

  • Moved to semver in support of software license agreement
  • Resolved an error when using app-manager to restart GATE-Ware
  • Process exit codes made more meaningful
  • A number of undocumented configuration options were added to potentially help avoid releases for small changes
  • Watchdog process improved.
  • Improved log message consistency
  • Improved log feedback for formatting errors in gateware.json
  • Adopted https://3musketeers.io/ pattern

Security:

  • Debug and trace log levels produce warning messages indicating that raw data may be logged and could include sensitive data

LoRaWAN Communication:

  • Backend topic structure adjusted to preserve LNS topic structure for better scaling.

Backend:

  • Azure: azure and azureiot values now valid for backend configuration option
  • Azure: Improved connection stability
  • Azure: Rotation of primary & secondary SAS keys on reconnect
  • Azure: Idle heartbeat uplink
  • Standardized the mPower API request structure

Transforms:

  • Resolved issue where Custom Transform evaluation order was incorrect
  • Duplicate Custom Transform matches now produce warning in logs and revert to built-in forward transform
  • Custom Transforms can discard uplinks by producing no stdout
  • Addition of built-in Transform: text, which converts the LoRa payload to ASCII text

Testing:

  • Automated testing implemented using Node-RED and Go Convey

v1.1.0-beta

Prerelease Beta for early access - release notes provided via direct channels.