Description
This project details setting up a standalone private TTN (The Things Network) LoRaWAN network server and Machinechat’s JEDI IoT application software on a Dragino LPS8V2-US915 gateway. The LPS8v2 comes with The Things Stack pre-installed and this project discusses adding the JEDI software to the Dragino gateway and configuring it as a standalone private LoRaWAN network server that also runs the JEDI IoT application concurrently. As part of testing the setup, a Seeed S2101 SenseCAP sensor is added to the LoRaWAN network and MQTT integration implemented in The Things Stack to pass sensor data to JEDI.
Hardware
-
Dragino LPS8V2-US915
The LPS8v2 is an open-source LoRaWAN Gateway that bridges a LoRa wireless network to an IP network via WiFi or Ethernet. -
Seeed SenseCAP S2101
A battery-powered IP66 wireless air temperature and humidity sensor, range from -40°C to 85°C and 0 to 100 %RH, equipped with built-in Bluetooth and APP service for OTA configuration and remote device management.
Software
-
JEDI Pro
Applications software for IoT data collection, visualization, monitoring and data storage that can be integrated into IoT solutions. -
The Things Stack
The Things Stack is an enterprise grade LoRaWAN network server, built on an open source core. The Things Stack allows you to build and manage LoRaWAN networks on your own hardware or in the cloud.
Background
LoRa is a long range, low power wireless technology developed by Semtech that utilizes a spread spectrum modulation technique derived from chirp spread spectrum (CSS) technology. LoRaWAN® is a standard for interoperability managed by the LoRa Alliance®. LoRa devices and the LoRaWAN standard provide many benefits and capabilities for wireless sensor network applications including long range, low power consumption and secure data transmission.
Several network operators offer cloud based LoRaWAN networks globally for customers to subscribe and connect to. Another option for customers is to setup up their own private, edge-based, LoRaWAN long-range IoT sensor network. Benefits of a private network include maintaining end-to-end privacy and control over data, control over software and infrastructure updates and upgrades, no requirement for Internet connectivity, and no recurring service/subscription network fees.
Implementation
For this project, LoRa hardware consists of Dragino’s indoor LPS8V2-US915 LoRaWAN gateway and Seeed’s S2101 air temperature / humidity sensor. Dragino’s LPS8V2 includes a built-in LoRaWAN Network Server, The Things Network - Stack (TTN-V3), and the LPS8v2 is configured to use the local host/built-in server as the primary LoRaWAN server. Once the TTN LoRaWAN server is configured, the S2101 sensor is added to the LoRaWAN network and MQTT integration is set up to enable communication with other external systems. The Dragino LPS8v2 needs to be connected to the internet to utilize a timeserver for LoRaWAN and software updates for the server.
Machinechat’s JEDI software is installed on the Dragino LPS8v2 and setup to automatically run as a service. For JEDI to receive data from MQTT, a custom data collector is added and the Sensor Dashboard configured to display the LoRa sensor data. A block diagram of the implemented private LoRaWAN IoT sensor network is shown below.
Set up Dragino LPS8V2 Gateway
1 - Power up the LPS8V2 and connect an ethernet cable to the router so LPS8V2 can obtain an IP address. In this project example ethernet is used to connect to the LPS8V2, for complete instructions and additional connection methods refer to LPS8v2 LoRaWAN Indoor Gateway User Manual.
2 - Determine IP address for LPS8V2 and use browser to login using user: “root” and password: “dragino”. This will bring up the System Overview page.
3 - Select LoRa for configuration settings. Set “Frequency Plan” to “US915 United States 915MHz (902-928)”, set “Frequency Sub Band” to “2: US915 , FSB2 (903.9-905.3)”, set “Mode” to “LoRaWAN Semtech UDP”.
4 - Select LoRaWAN and select “LoRaWAN Semtech UDP” for configuration settings. Note assigned Gateway EUI. Set “Primary LoRaWAN Server” Service Provider to “Local Host/Built-in Server”, set set Uplink and Downlink Port to 1700 and select “Save&Apply” to save settings.
5 - Select Network for configuration settings. Set “Ethernet WAN Settings” Mode to “DHCP” and select “Save&Apply” to save settings.
Set LoRa frequency of the Seeed S2101 Sensor and determine/record the OTAA LoRaWAN parameters
Seeed’s S2101 sensor is configured and OTAA LoRa parameters accessed using a smartphone and their “SenseCAP Mate” app over bluetooth. For this project, frequency plan setting is “United States 902-928 MHz, FSB 2 (used by TTN)” and LoRaWAN version setting is “LoRaWAN Specification 1.0.3”. The S2101 is shipped with its device EUI, APP Key and APP EUI listed in the “settings” tab of the SenseCAP Mate App when it is connected to the S2101 as in below example.
Make sure to record the OTAA parameters as shown below:
Detailed instructions on downloading and using the SenseCAP Mate app are found in the S210XSensorsUserGuide.
Login to built-in Things Stack LoRaWAN server to add S2101 sensor to LoRaWAN network.
1 - Enter IP address of LPS8V2 with port “8080” in browser to access the Things Stack server (example: 192.168.1.5:8080). Login with user: “admin” and password: “dragino”.
2 - Create a device in The Things Stack for the S2101 sensor. First step is to create an Application if one wasn’t created previously. Enter Application ID and select “Create Application” to create. For this project, application ID is “dk3dragino”. Optionally, Application name and Description can be entered for additional information/notes.
Select the Created Application ID (in this project example it is named “dk3dragino”).
3 - In application ID “dk3dragino” select + Add end device.
4 - In Register end device screen, select “Register manually”
For Frequency plan select “United States 902-928 MHz FSB 2(used by TTN)”
For LoRaWAN version select “LoRaWAN Specification 1.0.3”
For Regional Parameters version select “RP001 Regional Parameters 1.0.3”
Enter device EUI, APP Key and APP EUI parameters as determined from SenseCAP Mate app in above previous step.
Once all the data parameters have been entered, select Register end device to complete registration of the S2101.
5 - Next, a payload decoder will need to be set up in The Things Stack to decode the sensor values being sent from the S2101. Seeed provides a reference TTN Javascript payload parser for use with 3rd party LoRaWAN gateways. Information on the payload decoder is provided in Section 9 of the Seeed - S210X Sensors User Guide and can be downloaded at TTN-Payload-Decoder/decoder_new-v3.js at master · Seeed-Solution/TTN-Payload-Decoder · GitHub.
6 - To set up the payload decoder in The Things Stack, go to the End device screen for the S2101 (end devices are listed by eui ID). Select the Payload Formatters tab. Under Formatter type select “Custom Javascript formatter”. Copy the Javascript code at github link and paste in Formatter code window and then select Save changes.
7 - Review LoRaWAN messages for S2101 activity, decoded payload messages will be observable in the Live Data tab. Click on one of the “Forward uplink data messages” to expand and view the payload details.
Example of decoded payload is listed below:
{
"name": "as.up.data.forward",
"time": "2023-05-17T21:21:14.538597557Z",
"identifiers": [
{
"device_ids": {
"device_id": "eui-2cf7f1c0435003ac",
"application_ids": {
"application_id": "dragino3dk"
},
"dev_eui": "2CF7F1C0435003AC",
"join_eui": "6ED5CFFC6BCEDA75",
"dev_addr": "0060A7ED"
}
}
],
"data": {
"@type": "type.googleapis.com/ttn.lorawan.v3.ApplicationUp",
"end_device_ids": {
"device_id": "eui-2cf7f1c0435003ac",
"application_ids": {
"application_id": "dragino3dk"
},
"dev_eui": "2CF7F1C0435003AC",
"join_eui": "6ED5CFFC6BCEDA75",
"dev_addr": "0060A7ED"
},
"correlation_ids": [
"as:up:01H0NSDAQ2PH1JYZVQ4MCW5D8H",
"gs:conn:01H0NN0PB48SMV7PRCX6EB0BDW",
"gs:up:host:01H0NN0PN17KCB6T6CT529HT0K",
"gs:uplink:01H0NSDAENS9C5WXYAVXHWY13F",
"ns:uplink:01H0NSDAEWFJE4DDXRQHQEPPSX",
"rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01H0NSDAESDFG26ZYNXPX73Y4H",
"rpc:/ttn.lorawan.v3.NsAs/HandleUplink:01H0NSDAPY3Z84W1J6CVZS4SBY"
],
"received_at": "2023-05-17T21:21:14.466812258Z",
"uplink_message": {
"session_key_id": "AYgGggaSr4B4Wr2xyRcRCA==",
"f_port": 2,
"f_cnt": 1039,
"frm_payload": "AQEQvFcAAAECEI6ZAADgfw==",
"decoded_payload": {
"err": 0,
"messages": [
{
"measurementId": 4097,
"measurementValue": 22.46,
"type": "report_telemetry"
},
{
"measurementId": 4098,
"measurementValue": 39.31,
"type": "report_telemetry"
}
],
"payload": "010110BC5700000102108E990000E07F",
"valid": true
},
"rx_metadata": [
{
"gateway_ids": {
"gateway_id": "dragino60",
"eui": "A84041FDFE24D195"
},
"time": "2023-05-17T21:21:14.194097Z",
"timestamp": 339583220,
"rssi": -42,
"channel_rssi": -42,
"snr": 9,
"frequency_offset": "-1319",
"uplink_token": "ChcKFQoJZHJhZ2lubzYwEgioQEH9/iTRlRD0wfahARoLCMqKlaMGEPq581wgoPLyhfGGASoLCMqKlaMGEOjexlw=",
"channel_index": 2
}
],
"settings": {
"data_rate": {
"lora": {
"bandwidth": 125000,
"spreading_factor": 7
}
},
"coding_rate": "4/5",
"frequency": "904300000",
"timestamp": 339583220,
"time": "2023-05-17T21:21:14.194097Z"
},
"received_at": "2023-05-17T21:21:14.204346604Z",
"consumed_airtime": "0.066816s",
"network_ids": {
"net_id": "000000"
}
}
},
"correlation_ids": [
"as:up:01H0NSDAQ2PH1JYZVQ4MCW5D8H",
"gs:conn:01H0NN0PB48SMV7PRCX6EB0BDW",
"gs:up:host:01H0NN0PN17KCB6T6CT529HT0K",
"gs:uplink:01H0NSDAENS9C5WXYAVXHWY13F",
"ns:uplink:01H0NSDAEWFJE4DDXRQHQEPPSX",
"rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01H0NSDAESDFG26ZYNXPX73Y4H",
"rpc:/ttn.lorawan.v3.NsAs/HandleUplink:01H0NSDAPY3Z84W1J6CVZS4SBY"
],
"origin": "0204e7fb6077",
"visibility": {
"rights": [
"RIGHT_APPLICATION_TRAFFIC_READ"
]
},
Accessing The Things Stack MQTT Server
The Things Stack exposes an MQTT server to work with streaming events. The following steps describe how to connect an MQTT client and subscribe to uplinks or publish downlinks. Machinechat JEDI will need the MQTT server information in order to receive the streaming S2101 sensor data. Detailed information on The Things Stack MQTT server can be found at MQTT Server | The Things Stack for LoRaWAN .
1 - Creating an API Key. In order to use the MQTT server a new API key needs to be generated to authenticate. The Console provides the required connection information and can be used to create an API key for authentication. In your Applications tab select the MQTT submenu from the Integrations side menu.
2 - Click on the Generate new API key button to generate an API key for use in connecting to the MQTT server. Make note of the MQTT info which is needed for the JEDI data collector configuration file (Public address, Username, Password).
Install Machinechat JEDI Pro software on Dragino LPS8v2
The 32-bit arm7 version of Machinechat JEDI Pro software and license needs to be obtained to run JEDI Pro on the Dragino LPS8v2 gateway hardware. Once the software has been copied over to the LPS8v2 it needs to be installed and setup to automatically run as a service.
1 - Since the LPS8v2 gateway is a headless linux device, a second linux machine on the same network was used to “scp” copy the JEDI software to the LPS8v2. For this project, the second linux device was a Ubuntu box in which the JEDI software mcjedi.bin had been downloaded to it’s Downloads directory and the LPS8v2 was set up with ip address 192.168.11.181.
From the Ubuntu machine terminal, copy mcjedi.bin to the LPS8v2 root directory using below command.
$ scp Downloads/mcjedi.bin root@192.168.11.181:/root/
Use ssh to login to the LPS8v2. Once logged in, create jedi directory, move mcjedi.bin to jedi directory, make it executable, and install it to run as a service per below commands.
$ cd ~
$ mkdir jedi
$ mv mcjedi.bin jedi/
$ cd jedi
$ sudo chmod +x ./mcjedi.bin
$ sudo ./mcjedi.bin -service install
$ sudo ./mcjedi.bin -service start
Setting up Machinechat JEDI Pro MQTT Custom Data Collector
A custom MQTT data collector will be set up on JEDI Pro to subscribe to the sensor data from the S2101 sensor. The data collector consists of two files, “dcollector.bin” is the executable file that is run on the machine running JEDI and “dconfig.yml” is the corresponding configuration file containing the pertinent MQTT and sensor info. For this project, the temperature and humidity values of the S2101 will be subscribed to by editing dconfig.yml with the sensor parameter names. To determine the sensor parameter names, the LoRaWAN data payload for the LHT65N will be reviewed.
1 - Download the 32-bit arm7 version of the LoRaWAN MQTT data collector “dcollector.bin” and configuration file “dconfig.yml” from Machinechat at link https://support.machinechat.io/hc/en-us/articles/13935227926935-TTN-MQTT-LoRaWAN-Collector .
2 - Review the S2101 LoRaWAN payload. As noted above, the payload contains the below data.
The temperature parameter is “TempC_SHT” and humidity parameter is “Hum_SHT”.
3 - The configuration file needs to be modified with the MQTT info and sensor data parameters. The values that need to be modified are:
mQTTBrokerFullURL: this is “Public Address” from above MQTT Integration
mQTTUsername: this is “Username” from above MQTT Integration
mQTTPassword: this is “Password” from above MQTT Integration
cSproperty: this is parameter subscribed to in the LoRa payload
mcProperty: this is the corresponding parameter name mapped in JEDI
Example dconfig.yml file
mQTTBrokerFullURL: "tcp://192.168.1.129:1883"
mQTTUsername: "farm1"
mQTTPassword: "NNSXS.XFQCW3GFJXGC78MPOVKF3M2CUD4HFNSHNZQLRJQ.MB5VAGIGLVQ3F66LFYK2CVY2Z66A4CWRLQJXRIQBNT1A8IH7C6TA"
sendTestSenML: true
# setDebugLevel 0 is no debug, 1 is colorized JSON decode, 2 is 1 plus verbose payload dumps
setDebugLevel: 1
propertyNames:
- cSproperty: "messages.0.measurementValue"
mcProperty: "S2101TempC"
- cSproperty: "messages.1.measurementValue"
mcProperty: "S2101Hum"
4 - Install the data collector “dcollector.bin” and configuration “dconfig.yml” files by copying them to the “jedi/plugins” directory of the machine where JEDI is installed.
5 - Test the data collector by running “./dcollector.bin ./dconfig.yml” on the command line in the jedi/plugins directory. Below is example output data on the terminal when the data collector is working correctly (debug level set to 1).
scottr@scottr-ODYSSEY-X86J4105:~$ cd jedi/plugins
scottr@scottr-ODYSSEY-X86J4105:~/jedi/plugins$ ./dcollector.bin ./dconfig.yml
Connected to tcp://192.168.1.129:1883
metric:id=Test, n=Test, vs=Test, u=-
*** Pretty unmarshalled message:
{
"correlation_ids": [
"as:up:01H0QVRZWXK6HK3711DNQS9ANS",
"gs:conn:01H0NN0PB48SMV7PRCX6EB0BDW",
"gs:up:host:01H0NN0PN17KCB6T6CT529HT0K",
"gs:uplink:01H0QVRZN5N2QKBVJVV5DPXP1W",
"ns:uplink:01H0QVRZN9NWFCFE1N8NTPX43V",
"rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01H0QVRZN8H2K2ZBFGCP98CDHF",
"rpc:/ttn.lorawan.v3.NsAs/HandleUplink:01H0QVRZWTZ1HZBQKFJK3YXD56"
],
"end_device_ids": {
"application_ids": {
"application_id": "dragino3dk"
},
"dev_addr": "0060A7ED",
"dev_eui": "2CF7F1C0435003AC",
"device_id": "eui-2cf7f1c0435003ac",
"join_eui": "6ED5CFFC6BCEDA75"
},
"received_at": "2023-05-18T16:41:02.621469072Z",
"uplink_message": {
"consumed_airtime": "0.066816s",
"decoded_payload": {
"err": 0,
"messages": [
{
"measurementId": 4097,
"measurementValue": 22.64,
"type": "report_telemetry"
},
{
"measurementId": 4098,
"measurementValue": 41.92,
"type": "report_telemetry"
}
],
"payload": "01011070580000010210C0A30000FC22",
"valid": true
},
"f_cnt": 1155,
"f_port": 2,
"frm_payload": "AQEQcFgAAAECEMCjAAD8Ig==",
"network_ids": {
"net_id": "000000"
},
"received_at": "2023-05-18T16:41:02.377463929Z",
"rx_metadata": [
{
"channel_index": 5,
"channel_rssi": -50,
"frequency_offset": "-1321",
"gateway_ids": {
"eui": "A84041FDFE24D195",
"gateway_id": "dragino60"
},
"rssi": -50,
"snr": 13.5,
"time": "2023-05-18T16:41:02.369805Z",
"timestamp": 1555744341,
"uplink_token": "ChcKFQoJZHJhZ2lubzYwEgioQEH9/iTRlRDVjOvlBRoMCJ6qmaMGEJiAjrEBIIj42syj+hAqDAieqpmjBhDIjauwAQ=="
}
],
"session_key_id": "AYgGggaSr4B4Wr2xyRcRCA==",
"settings": {
"coding_rate": "4/5",
"data_rate": {
"lora": {
"bandwidth": 125000,
"spreading_factor": 7
}
},
"frequency": "904900000",
"time": "2023-05-18T16:41:02.369805Z",
"timestamp": 1555744341
}
}
}
***
*** Flattened Object:
{
"err": 0,
"messages.0.measurementId": 4097,
"messages.0.measurementValue": 22.64,
"messages.0.type": "report_telemetry",
"messages.1.measurementId": 4098,
"messages.1.measurementValue": 41.92,
"messages.1.type": "report_telemetry",
"payload": "01011070580000010210C0A30000FC22",
"valid": true
}
***
*** Node name: 2CF7F1C0435003AC ***
metric:id=2CF7F1C0435003AC, n=S2101TempC, vd=22.64, u=-
metric:id=2CF7F1C0435003AC, n=S2101Hum, vd=41.92, u=-
5 - Open JEDI and navigate to “Settings” and then select “Data Collectors”. Click on “Add Collector” to add new data collector.
6 - Add new data collector. Enter data collector name, select “Custom Plug-in” for type, select “dcollector.bin” for Plug-in Executable, add dconfig.yml file location for Plug-in Options, select “Run As Background Process and Monitor”, click on "“VALIDATE PLUG IN” and then select “SAVE” to save settings.
Displaying S2101 LoRa sensor data on JEDI Pro
In JEDI, navigate to “Data Dashboard” and create new charts forS2101 temperature and humidity. Example dashboard is shown below.
Conclusion
Dragino’s LPS8v2 gateway provides a low-cost small footprint private LoRaWAN hardware platform without the need for cloud services. The combination of Machinechat’s JEDI Pro applications software, The Things Stack LoRaWAN network server, and Dragino’s LPS8V2 gateway deliver a very capable and cost-effective standalone private LoRaWAN IoT wireless sensor network solution.
References
- Dragino - LPS8v2 Indoor LoRaWAN Gateway
- Dragino - LPS8v2 LoRaWAN Indoor Gateway User Manual
- Seeed - SenseCAP S2101 LoRaWAN Temperature & Humidity Sensor
- Seeed - S210X Sensors User Guide
- Digi-Key - Getting Started with machinechat’s JEDI One IoT Platform
- Digi-Key - Using The Things Stack private LoRaWAN network server with Dragino’s LPS8V2 and Machinechat JEDI
- Machinechat - Ubuntu Linux - Installing JEDI One as a Service
- Machinechat - Building a private, edge-based LoRaWAN IoT sensor network