The connection between the MultiTech Conduit and scriptr.io is as simple as forwarding the data from the internal gateway MQTT broker to scriptr.io’s MQTT broker.

In this blog post we will demonstrate how to publish MQTT messages from the MultiTech Conduit to scriptr.io, as well from the former to AWS.

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

Summary

This tutorial will go through the following steps:

  1. Setup a LoRa gateway (MultiTech Conduit).
  2. Setup a LoRa device to push messages to a LoRa gateway (MultiTech Conduit).
  3. Setup a scriptr.io account with the appropriate channels and a sample script.
  4. Setup a data forwarder which is a Python code that will shovel the data from the Conduit to scriptr.io.
  5. Learn how to shovel data to AWS.

Pre-requisites

Hardware

  • MultiTech Conduit: we’re using the MTCDT-LEU1-247A Firmware1.4.3, other versions will work as well. This is the AEP software but the code is also tested on the vanilla mLinux too.
  • Along with the MultiTech Conduit, you will also need MTAC-LORA-915 if you’re in the US, or MTAC-LORA-868 if you’re in Europe.
  • LoRa Mote: although the device generating the data doesn’t matter (as long as it knows how to talk LoRa to the MultiTech Conduit) we will use the LoRa Mote since it is a full demo-device with a screen and interface to configure. You can easily use another device like the mDot if you’re comfortable configuring it.
  • Just make sure that the end-device (LoRa Mote in this case) and the gateway speak “the same LoRa” (frequencies should match each other and your country’s specifications).

Software

Configurations: Step by Step

Setting up the Conduit

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

Setting up the 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 Conduit under the new address:

lora-blog-eth0-conf

Setting up LoRa

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

  1. Set the LoRa Mode to “Network Server”.
  2. Select the appropriate frequency based on your hardware and current location (US915 in this example).
  3. 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).
  4. 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).
  5. Select the check box for public mode.
  6. Specify the accepted address range. This will be the list of addresses that will be allowed to join the network.

lora-blog-lora-setup

Setting up the 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).

You can use your preferred tool (screen, TeraTerm, etc.) to access the device or simply use your preferred scripting language (a Python sample code is provided).

  1. Setup your serial communication tool to use the appropriate device:
    1. On linux you can simply plug in the device and check dmesg for the assigned /dev. It will look something like /dev/ttyACM0.
    2. Baudrate 57600.
    3. Disable software and hardware flow control.
  2. Needed commands will be:
    1. sys reset (reset the conf on the lora mote)
    2. mac set devaddr 00000011
    3. mac set deveui 1234123412341234
    4. mac set devappeui 1234123412341234
    5. mac set appkey 12341234123412341234123412341234
    6. mac set adr off
    7. mac set sync 34
    8. mac save
  3. Restart your LoRa Mote and configure it from the hardware buttons. When it boots up, click the left button (S2) and then select Join By Otaa (the button to the right S3).
  4. 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.

Checking Messages on the Local Broker

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 local broker 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).

Forwarding the Data to a Scriptr.io MQTT Endpoint

Configure Scriptr.io
  1. Create a simple script that will echo back what it receives:
    if(request.body.data)
         return atob(request.body.data);
    else
         return "unexpected message format"
  2. Create a “multitech” channel on which data packets will be broadcast:
    lora-blog-create-channel
  3. Subscribe the echo script to the channel in order to be executed for each message on the channel:
    lora-blog-subscription-screen
  4. Get your authentication token – you will need that in a bit to connect the shovel to your account:

lora-blog-account-tokens

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

import paho.mqtt.client as mqtt
import json
localClient = mqtt.Client()
scriptrClient = mqtt.Client()
def on_message(client, userdata, msg):
scriptrMessage = { #message in the format scriptr.io expects
"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("VzE3XXXXXXXXX", json.dumps(scriptrMessage)) # Use your scriptr.io Access Token as shown in the above figure
localClient.connect("localhost", 1883, 60) #local broker on gateway
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. At the moment, there’s a mistake in the configuration of opkg on the gateway, you will need to update the repositories under /etc/opkg/mlinux-feed.conf to match the current mlinux version (default was 3.3 and that returns a 404).

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

Available sources are found here: http://www.multitech.net/mlinux/feeds/

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
Validate Basic Communication

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”.

Development: Building your First Scriptr.io Application

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 notably accelerating your development pace, thanks to a plethora of API and visual development tools, such as our dashboard builder and our decision table editor, etc. You can find a long list of demo applications / modules / connectors under our GitHub account.

Connecting Through Third Party DMPs

Scriptr.io simplifies the integration with the systems your are already using (legacy enterprise applications, third party service providers…). Notably, if you already have assets running on different DMPs such as Watson/Azure/TTN or AWS, and you need your data to go through them before reaching your logic on scriptr.io, you will need to modify the shovel’s code.

Connecting to AWS

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

Connecting Through Third Party DMPs Like Watson/Azure/TTN

The preceding section provided you with the code to deal with AWS. If you are more interested in Watson, Azure or TTN, you can follow the instructions provided here for Watson or here for TTN.

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