The MultiTech MultiConnect® Conduit™ is a programmable gateway for industrial IoT applications, supporting the LoRaWAN technology.

This guide demonstrates how to publish messages from the MultiConnect® Conduit™ to scriptr.io, either directly, or through your existing DMP (Data Management Platform).

The connection between the MultiConnect® Conduit™ and scriptr.io is as simple as forwarding the data from the gateway’s internal MQTT broker to scriptr.io’s MQTT broker. And if you already have assets running on different DMPs such as Watson/Azure/AWS/TTN/Orbiwise/etc., and you need your data to go through them before reaching your logic on scriptr.io, this guides shows you how to modify the recipe to accommodate for that.

Note: scriptr.io exposes endpoints with multiple protocols (HTTP, WebSocket, MQTT, AMQP, …) allowing an easy data flow / script invocation from any device.

Pre-requisites

Hardware

  • MultiConnect® Conduit™: we’re using the MTCDT-LEU1-247A Firmware 1.6.4, other versions will work as well. This is the AEP software but the code is also tested on the vanilla mLinux too.
  • MultiConnect® mCard™: along with the MultiConnect® Conduit™, you will also need the MTAC-LORA-H-915 if you’re in the US, or MTAC-LORA-H-868 if you’re in Europe.
  • LoRa device: although the device generating the data doesn’t matter (as long as it knows how to talk LoRa to the MultiConnect® Conduit™), in this guide, we will provide the option to use the MultiTech mDot device, and another option for using the LoRa Mote device since it is a full demo-device with a screen and interface to configure.
    Note that you will either use the 915 MHz RN2903 or the 868MHz RN2483 LoRa Technology Mote depending on whether you’re using the 915 MHz or the 868 MHz frequency respectively.
    Similarly, you will either use the MultiConnect® mDot™ MTDOT-915-X1P-SMA-1 or the MTDOT-868-X1P-SMA-1 depending on whether you’re using the 915 MHz or the 868 MHz frequency respectively.

PS: make sure that the end-device (mDot or LoRa Mote in this case) and the gateway speak “the same LoRa”; i.e. their frequencies should match each other, and should comply with your country’s regulations.

Software

Table of Content

This tutorial will go through the following steps:

  1. Setting up your MultiConnect® Conduit™
    1. Setting up the Ethernet network
    2. Setting up the LoRa network
  2. Setting up your LoRa device to push messages to the MultiConnect® Conduit™
    1. Setting up your sensor device
    2. Checking messages on the local broker
  3. Sending data from the MultiConnect® Conduit™ to scriptr.io
  4. Building your IoT application in scriptr.io and visualizing the data

Recipe: Step by Step

  1. Setting Up Your MultiConnect® Conduit™

    The following assumes that the LoRa MultiConnect® mCard™ is already installed on the conduit. If not, please check this guide from MultiTech.

    1.1. Setting Up the Ethernet Network

    1. Connect your conduit to the network using an ethernet cable.
    2. The conduit will be accessible on a default IP address (192.168.2.1). You might need to manually change your IP to something on the same network (192.168.2.2/255.255.255.0) in order to proceed, in case your network is on a different subnet.
    3. Access the admin interface using that IP and go to Setup -> Network Interfaces where you will be able to configure the network on the conduit to fit your existing network requirements:
      1. The ethernet port we’re trying to configure is eth0, click the edit button on the right.
      2. Configure appropriately (easiest might be to set it to DHCP if your network allows that).
    4. Access the admin interface using the new IPs (either manually provided or from the DHCP) and confirm that you can still access the MultiConnect® Conduit™ under the new address:

    lora-blog-eth0-conf

    1.2. Setting Up the LoRa Network

    Setting up LoRa on the conduit is all done from the admin interface, under Setup -> Lora:

    1. Under LoRaWAN, select Network Settings.
      Network Settings
    2. Set the LoRa Mode to “Network Server”.
    3. Select the appropriate frequency based on your hardware and current location (US915 in this example).
    4. Set the Network Mode to “Public LoRaWAN”.
    5. Specify the accepted address range. This will be the list of addresses that will be allowed to join the network.
    6. Submit your changes and restart the network services.
    7. Under LoRaWAN, navigate to Key Management.
      Key Management
    8. Set a network EUI. This is a unique identifier, you can pick anything you want. The rule is that it should be a 64-bit hexadecimal value, meaning that it should be 8 dual-digit-hexa numbers (eg. 12:34:12:34:12:34:12:34).
    9. Set a network key. This is a unique identifier, you can pick anything you want as well. The rule is that it should be a 128-bit hexadecimal value, meaning that it should be 16 dual-digit-hexa numbers (eg. 12:34:12:34:12:34:12:34:12:34:12:34:12:34:12:34).
    10. Submit your changes and restart the network services.

  2. Setting up your LoRa Device

    Now that the LoRa network server is up and running, we will need to setup your LoRa device to push messages to the MultiConnect® Conduit™. As explained above in the hardware requirements section, any compatible LoRa device will do. For simplicity reasons, we’re going to provide you here with steps to configure 2 popular devices: the mDot that comes with the MultiConnect® ConduitTM IoT Starter Kit for LoRa® Technology, and the LoRa Mote.

    Depending on which device you picked, you can skip the section related to its counterpart device below and move to section 2.2.

    2.1. Setting up Your Device

    Based on your preference, you can opt to either follow the mDot instructions, or the LoRa Mote instructions. Alternatively, you can pick your own device and connect it to the gateway, then move to step 2.2 below.

    Option A: mDot

    To connect the mDot to the gateway, refer to Connecting a MultiConnect® mDot™ to a MultiConnect® Conduit™ by MultiTech.

    Option B: LoRa Mote

    Now that the LoRa network server is up and running, we will need to setup the LoRa Mote.

    The device needs to be configured with similar parameters:

    1. A devaddr that falls in the specified range (we will use 00000011 as device address).
    2. a deveui of 1234123412341234.
    3. An app eui 1234123412341234 (matching the network eui specified on the conduit).
    4. An app key 12341234123412341234123412341234 (matching the network key specified on the conduit).

    Setting up the LoRa Mote will require access to the device over a serial port (provided by the LoRa Mote over USB).

    To configure it, you can use the provided Python script which will do the following for you (which you can do yourself manually using a terminal tool like TeraTerm):

    1. Setup the serial communication tool to use the appropriate device:
      1. Connect to the LoRa Mote over serial (on Linux it will be assigned a device address like /dev/ttyACM0 – you can get this address by checking dmesg)
      2. Set baudrate 57600
      3. Disable software and hardware flow control
    2. Issue the following commands:
      1. sys reset (reset the conf on the LoRa Mote)
      2. mac set devaddr 00000011
      3. mac set deveui 1234123412341234
      4. mac set appeui 1234123412341234
      5. mac set appkey 12341234123412341234123412341234
      6. mac set adr off
      7. mac set sync 34
      8. mac save

    Once done, proceed to the following:

    1. Restart your LoRa Mote and configure it from the hardware buttons.
    2. When it boots up, click the left button (S2) and then select Join By Otaa (the button to the right S3).
    3. Using the S2 and S3 buttons, you should be able to configure a periodic push of the sensors data (temperature and ambient light) to the gateway, or push packets on demand.

    2.2. Checking Messages on the Local Broker

    Now we need to check if the messages sent on the LoRa network are reaching our gateway successfully.

    Since we picked OTAA for joining method, the LoRa network server will negotiate the session keys with the device and will be able to use those in order to decrypt the LoRa packet.

    You can check the result by subscribing to all topics on the conduit’s MQTT broker by typing the command mosquitto_sub -t “#” which will show you packets like the following:

    {"chan":3,"codr":"4/5","data":"MjMxIDAyNAA=","datr":"SF10BW125","freq":912.5,"lsnr":10,"modu":"LORA","rfch":0,"rssi":-18,"size":21,"stat":1,"time":"2017-10-20T10:58:46.451125Z","tmst":1654421788}

    Note that although decrypted, the data packet is Base64-encoded.

    To view the data, you can simply do something like echo “MjMxIDAyNAA=” | base64 –decode which will output “231 024” (AMBIENT_LIGHT SPACE TEMPERATURE).

  3. Sending Data from the MultiConnect® Conduit™ to Scriptr.io

    Now that we’re all set locally, we need to start forwarding the data to scriptr.io, either directly – by following the steps described in 3.1, or through a DMP – steps 3.2 to 3.6 provide links to instructions on how to forward your data to a DMP before it reaches your application on scriptr.io.

    Option A: Configuring the Gateway to Push Data Directly to Scriptr.io

    In this step, we will explain how you can start forwarding the data to a scriptr.io MQTT endpoint.

    1. Configure Scriptr.io
    1. Assuming you already created a scriptr.io account, let’s go to the Workspace
    2. Create a simple script called “echo” that will echo back what it receives 
      try {
    var payload = JSON.parse(request.body.payload);
    if (payload.data && payload.appeui)
        return atob(payload.data);// this is the sensor's data
    else
        return "This is not a data packet, probably a control frame.";
} catch (err) {
    return "Unexpected message format.";
}
    3. Create a “multitech” channel on which data packets will be broadcast:
      lora-blog-create-channel
    4. Subscribe the echo script to the channel in order to be executed for each message on the channel:
      lora-blog-subscription-screen
    5. Get your authentication token – you will need that in a bit to connect the shovel to your account. To do that, go to your Device Directory, create a device for the Conduit if it’s not already created, and copy its token:
      multitech-token
    2. Configure the Gateway to Forward to the Specified Account

    For this, you will need a simple “shovel”, that is a code that will pick up a message from one broker (localhost on the gateway) and publish it to a remote one (mqtt.scriptrapps.io).

    Access to mqtt.scriptrapps.io for demo purposes is available to everyone over 1883 and 8883.

    The following is written in Python and will do exactly that. You will only need to configure it to publish the messages to the mqtt.scriptrapps.io broker under the topic <account_key>. Let’s call it shovel-scriptr.py:

    #start script with token as only parameter
#eg, python shovel-scriptr.py XXXXxxxx== (where XXXXxxxx== is your device token)
import paho.mqtt.client as mqtt
import json
import sys
localClient = mqtt.Client()
scriptrClient = mqtt.Client()
def on_message(client, userdata, msg):
        print "received message" + msg.topic + " " + msg.payload
        scriptrMessage = {
                'method':'Publish',
                'params':{
                        'apsdb.channel': "multitech", #channel on which to publish the message
                        'apsdb.message': json.dumps({'payload': msg.payload, 'topic':msg.topic})
                }
        }
        scriptrClient.publish(sys.argv[1], json.dumps(scriptrMessage)) # Use your scriptr.io Access Token as shown in the above figure
        print "published message" + json.dumps(scriptrMessage)
localClient.connect("localhost", 1883, 60) #local broker on gateway
#access to mqtt.scriptrapps.io for demo purposes is available to everyone over 1883 and 8883. 
#WARNING: DATA SENT OVER THIS BRIDGE IS PUBLIC
#for production endpoints, please contact support@scriptr.io
scriptrClient.connect("mqtt.scriptrapps.io", 1883, 60) #scriptr.io mqtt endpoint
localClient.on_message = on_message
localClient.subscribe("#", 0)
localClient.loop_forever() #forever loop since the on_message is async and we need to leave script running

    Note: To install the Paho MQTT client you will need to install pip. However, at the moment of writing this blog, there was an error in the configuration of opkg on the gateway pointing by default to a non-existing repository (version 3.3). In order to use opkg, you will need to update the repositories list under /etc/opkg/mlinux-feed.conf to match your mlinux version. You can discover your current version by  running the command “cat /etc/mlinux-version” which will output something similar to the following (we’re interested by the part in bold):

    mLinux 3.3.6
    Built from branch: (detachedfrom4dc1cd8)
    Revision: 4dc1cd8d41adde7b96656f848196d55284c1fbc8

    You can check the list of available sources at http://www.multitech.net/mlinux/feeds/ and select the matching version, in our case: http://www.multitech.net/mlinux/feeds/3.3.6/
    Once updated, you will be able to run:

    opkg update
opkg install python-pip
wget https://bootstrap.pypa.io/ez_setup.py
python ez_setup.py
pip install paho-mqtt
    3. Run the Code and Validate Basic Communication

    First, let’s run the shovel code by running the following command on your Conduit (where auth_token is the authentication token associated with your Conduit device and which you retrieved above in Option A – Step 1.5):

    python shovel-scriptr.py auth_token

    Validate that all is working by going to your scriptr.io Logs view and checking the invocations of your echo script and the output of the script. The data should appear in the logs, decoded, in plain, e.g. “280 24”.

    Option B: Configuring the Gateway to Push Data Through AWS IoT

    For detailed steps about connecting the MultiConnect® Conduit™ to AWS IoT, check our previous blog entry.

    Option C: Configuring the Gateway to Push Data Through TTN

    For detailed steps about connecting the MultiConnect® Conduit™ to TTN (The Things Network), you can follow the instructions provided here.

    Once the Gateway is configured and you see the data in TTN, do not forget to create a bridge in scriptr.io to TTN. As already mentioned, you can learn more about this step in our dedicated blog post.

    Option D: Configuring the Gateway to Push Data Through Watson IoT

    For detailed steps about connecting the MultiConnect® Conduit™ to IBM Watson IoT, you can follow the instructions provided here.

    Once the Gateway is configured and you see the data in Watson IoT, do not forget to create a bridge in scriptr.io to Watson. As already mentioned, you can learn more about this step in our dedicated blog post.

    Option E: Configuring the Gateway to Push Data Through Azure IoT

    The instructions for connecting the MultiConnect® Conduit™ to Microsoft Azure will be published here soon.

    Option F: Configuring the Gateway to Push Data Through Orbiwise

    The instructions for connecting the MultiConnect® Conduit™ to Orbiwise will be published here soon.

  4. Building your IoT Application in Scriptr.io and Visualizing the Data

    The data from the end-devices is now flowing into the system, it is time to build your actual application.

    Scriptr.io allows you to reduce the time to market of your IoT applications by accelerating your development pace, thanks to a plethora of API and visual development tools, such as our dashboard builder, our decision table editor, and the multitude of tools at your disposal in the Workspace. In addition to our long list of demo applications / modules / connectors which you can find under our GitHub account, we have built demo apps specifically for the MultiConnect® Conduit™ to help you get started.

    If you’re using a LoRa Mote device, you can install its sample app from the modules list. To do this, click the arrow next to the New Script button, then click Install Module…, then locate the app called MultiTech Conduit / LoRa Mote App in the modules list and click Install. Once installed, follow the steps in the Readme.md file to configure it to work in your account.