The Things Network on PineDio Stack BL604 RISC-V Board

PineDio Stack BL604 RISC-V Board (foreground) talking to The Things Network via RAKWireless RAK7248 LoRaWAN Gateway (background)

PineDio Stack BL604 RISC-V Board (foreground) talking to The Things Network via RAKWireless RAK7248 LoRaWAN Gateway (background)

📝 21 Sep 2021

What is The Things Network?

The Things Network is a crowd-sourced wireless network. And it works worldwide!

Our IoT Devices may connect to The Things Network and transmit Sensor Data to the Cloud.

How much does it cost?

Nothing! The public community network is Free for Fair Use.

(The network has been free since its launch in 2015)

Totally free! What’s the catch?

Here’s what we need…

  1. LoRa Wireless Module: We’ll use the Semtech SX1232 LoRa Transceiver (Transmitter + Receiver) that’s bundled with our PineDio Stack Board.

    (More about this in a while)

  2. Network Coverage: Check whether our area is covered by the network…

    The Things Network Global Coverage

  3. Fair Use: Because it’s a free network for Sensor Data, we can’t spam it with messages.

    Each device may transmit roughly 10 tiny messages per hour.

    (Assuming 12 bytes per message)

    This varies by region, message size and data rate.

    (More about this in a while)

Darn no coverage here. What now?

Everyone is welcome to join The Things Network and grow the network!

In a while I’ll explain how I added my LoRaWAN Gateway to The Things Network.

(I bought my RAKwireless RAK7248 Gateway for $280)

What is PineDio Stack?

PineDio Stack is a 32-bit RISC-V Microcontroller board…

Which has an onboard LoRa SX1262 Transceiver…

Today we’ll walk through the steps for connecting PineDio Stack to The Things Network

PineDio Stack BL604 talking to The Things Network via LoRaWAN Gateway

§1 Add Gateway to The Things Network

(Skip this chapter if you have The Things Network coverage… You’re so lucky! 👍)

Sadly there’s no The Things Network coverage in my area. Lemme explain how I added my LoRaWAN Gateway (RAKWireless RAK7248) to The Things Network.

RAKwireless docs for The Things Network

This is the official doc for adding RAKWireless RAK7248 (and similar gateways) to The Things Network…

Run sudo gateway-config as described to configure the gateway for The Things Network. (Instead of ChirpStack)

We create a free account on The Things Network…

Log in and select the nearest region. (Either US, Europe or Australia)

Click Gateways and Add Gateway

Add Gateway

  1. Gateway ID needs to be globally unique.

    (Choose wisely!)

  2. Gateway EUI (Extended Unique Identifier) comes from our LoRaWAN Gateway.

    On our RAKwireless Gateway, run this command to get the EUI…

    gateway-version
    
  3. Frequency Plan: See this…

    “Frequency Plans by Country”

Fill in the fields and click Create Gateway

§1.1 Configure Gateway

Take Note: This is missing from the RAKwireless docs…

The Things Network has been upgraded recently and there’s no longer the option for “Legacy Packet Forwarder”.

Instead we set the Server Address like so…

  1. Browse to the Gateway that we have added

  2. Click Download global_conf.json

    Our Gateway in The Things Network

  3. Open the Downloaded global_conf.json with a text editor.

    It should look like this…

    Gateway Config

  4. On our RAKwireless Gateway, run this…

    sudo gateway-config
    
  5. Select “Edit Packet Forwarder Config”

  6. Look for the gateway_conf section…

    Edit Packet Forwarder Config

  7. Replace these values from the Downloaded global_conf.json

    "gateway_conf": {
      "gateway_ID":     ...,
      "server_address": ...,
      "serv_port_up":   ...,
      "serv_port_down": ...,
    
  8. Scroll down and look for the end of the gateway_conf section (just after beacon_power)…

    Edit Packet Forwarder Config

  9. Insert the entire servers section from the Downloaded global_conf.json

    "servers": [ {
      "gateway_ID":     ...,
      "server_address": ...,
      "serv_port_up":   ...,
      "serv_port_down": ...,
    } ]
    

    (Check the trailing commas, especially after beacon_power!)

  10. Our updated file should look like this…

    Packet Forwarded Config

  11. Save the file.

    Select “Restart Packet Forwarder”

(More about Server Address)

§1.2 Gateway Is Up!

How will we know if our Gateway is connected?

In The Things Network, browse to our Gateway and click Live Data (in the left bar)

We should see the Heartbeat Messages (Gateway Status) received from our Gateway…

Gateway Live Data

What are the Uplink Messages?

These are LoRa Messages from nearby devices that our Gateway has helpfully relayed to The Things Network.

Yep we’re officially a contributor to the globally-connected The Things Network!

In case of problems, check the Packet Forwarder Log on our Gateway…

sudo tail /var/log/daemon.log

(See sample Packet Forwarder Log)

§2 Add Device to The Things Network

(If you skipped the previous chapter: Welcome back! We’ll need a free account on The Things Network: Click “Sign Up” here)

Before sending data to The Things Network, we need to add a device

  1. Log in to The Things Network.

    Select the nearest region.

    (Either US, Europe or Australia)

  2. Click Applications and Add Application

    Add Application

    Our devices shall be registered under this Application.

    Fill in any name for the Application ID. (Needs to be globally unique)

    Click Create Application

  3. In the Application, click "End Devices" (in the left bar)

    Click Add End Device

    Click Manually

    Register End Device

  4. Fill in these fields…

    LoRaWAN Version: MAC V1.0.2

    Regional Parameters Version: PHY V1.0.2 REV B

    Frequency Plan: See this…

    “Frequency Plans by Country”

  5. Click Show Advanced Activation

    Register End Device

    Activation Mode should be Over The Air Activation

  6. For DevEUI, JoinEUI, AppKey and NwkKey:

    Click the buttons for Generate and Fill With Zeros

    Register End Device

  7. Click Register End Device

Why did we select LoRaWAN Version 1.0.2 Rev B?

This is the version of LoRaWAN that’s supported by our firmware for PineDio Stack.

(Our firmware is older than the upgraded version of The Things Network)

If you see “Message Integrity Code” Errors later, check the settings above for LoRaWAN Version.

(More about legacy LoRaWAN support)

Legacy LoRaWAN Support

§3 Run the LoRaWAN Firmware

Now we build, flash and run the LoRaWAN Firmware for PineDio Stack!

This is the Source Code for our LoRaWAN Firmware…

Which calls the following LoRaWAN and SX1262 Drivers

Follow these instructions to build, flash and run the firmware…

  1. “Build LoRaWAN Firmware”

  2. “Flash LoRaWAN Firmware”

  3. “Run LoRaWAN Firmware”

We’re ready to…

  1. Join PineDio Stack to The Things Network

    (Because we need to join the network before sending data)

  2. Send data from PineDio Stack to The Things Network

    (And observe the data received by The Things Network!)

(Yep this is the same LoRaWAN Firmware that we ported from Apache Mynewt OS to BL602!)

Tiny tasty treat… PineDio Stack BL604 RISC-V Board

§4 Join Device to The Things Network

Let’s join our PineDio Stack device to The Things Network!

Because we’re doing Over-The-Air Activation, we need to join the network every time we boot our device.

In The Things Network, browse to our Device and copy these values (needed for network activation)…

  1. JoinEUI (Join Extended Unique Identifier)

  2. DevEUI (Device Extended Unique Identifier)

  3. AppKey (Application Key)

Device Overview

Click the icons shown above to reveal, format and copy the values.

Note that the copied values are formatted as…

0xAB, 0xBA, 0xDA, 0xBA, ...

Later we shall convert the comma-delimited values to colon-separated values…

0xAB:0xBA:0xDA:0xBA:...

§4.1 Join Commands

Head over to the Serial Terminal for PineDio Stack.

At the PineDio Stack Command Prompt, enter these commands to join PineDio Stack to The Things Network

  1. First we start the Background Task that will handle LoRa packets…

    create_task
    

    (create_task is explained here)

  2. Next we initialise the LoRa SX1262 and LoRaWAN Drivers

    init_lorawan
    

    (init_lorawan is defined here)

  3. Set the DevEUI

    las_wr_dev_eui 0xAB:0xBA:0xDA:0xBA:0xAB:0xBA:0xDA:0xBA
    

    Change “0xAB:0xBA:...” to your DevEUI

    (Remember to change the , delimiter to :)

  4. Set the JoinEUI

    las_wr_app_eui 0x00:0x00:0x00:0x00:0x00:0x00:0x00:0x00
    

    Change “0x00:0x00:...” to your JoinEUI

    (Yep change the , delimiter to :)

  5. Set the AppKey

    las_wr_app_key 0xAB:0xBA:0xDA:0xBA:0xAB:0xBA:0xDA:0xBA0xAB:0xBA:0xDA:0xBA:0xAB:0xBA:0xDA:0xBA
    

    Change “0xAB:0xBA:...” to your AppKey

    (Again change , to :)

  6. Finally we send a request to join The Things Network

    las_join 1
    

    1” means try only once.

    (las_join is explained here)

(Source)

§4.2 We Are In!

Head back to The Things Network. Browse to our Application and click Live Data (in the left bar)

We should see “Successfully Processed Join Request”

Application Live Data

Yep our PineDio Stack has successfully joined The Things Network!

If we see “Message Integrity Code” Errors, check the Device Settings. The LoRaWAN Version should be 1.0.2 Rev B.

§5 Send Data to The Things Network

Finally we’re ready to send data from PineDio Stack to The Things Network!

At the PineDio Stack Command Prompt, enter these commands…

  1. We open an Application Port that will connect to The Things Network…

    las_app_port open 2
    

    2” is the Application Port Number

    (las_app_port is explained here)

  2. Then we send a Data Packet containing 5 bytes of data (0x00) to The Things Network at Port 2…

    las_app_tx 2 5 0
    

    (“0” means that this is an Unconfirmed Message, we’re not expecting an acknowledgement from The Things Network)

    Watch the demo video on YouTube

    See the output log

(Source)

Switch back to The Things Network. Browse to our Application and click Live Data (in the left bar)

We should see 5 bytes of 0x00 received by The Things Network…

Application Live Data

And we’re done!

§5.1 Doing Better

Sending 5 bytes of data to the network doesn’t sound particularly exciting?

Yep we’re just getting started!

In future articles we shall explore The Thing Network’s Cloud Integration features for processing our sensor data: MQTT, Webhooks, Storage, Downlinks, Payload Formatters, …

We shall visualise our sensor data with MQTT, Prometheus and Grafana

We will store the sensor data in The Things Network and fetch them with Roblox over HTTP

We may decode our sensor data in The Things Network with a Payload Formatter

The Things Network exposes a HTTP POST API for us to push Downlink Messages to our devices…

Which will be useful for Remote Actuation of our devices.

Check this doc for the complete list of Cloud Integration features (including IFTTT and Node-RED)…

Sending messages for free to The Things Network

§6 The Things Network Coverage

Thanks to The Things Network, we’ve just sent a tiny message to the Cloud… For Free!

(Assuming we have The Things Network coverage)

How’s the coverage for The Things Network worldwide?

Depends on the region.

According to the The Things Network Coverage Map, coverage in Singapore is really spotty…

The Things Network coverage in Singapore

Can we extend The Things Network coverage?

We can install our own LoRaWAN Gateways and join them to The Things Network!

Schools could install gateways for The Things Network…

And share free access to The Things Network with homes, workplaces and devices nearby!

Hopefully with affordable, open-source gateways (like Pine64’s PineDio Gateway) we’ll grow The Things Network substantially…

PineDio Gateway, PinePhone Backplate and USB Adapter

PineDio Gateway, PinePhone LoRa Backplate and LoRa USB Adapter

§7 Fair Use of The Things Network

The Things Network is Free for Fair Use…

How many messages can we send in an hour?

Each device may transmit roughly 10 tiny messages per hour.

(Assuming 12 bytes per message)

This varies by region, message size and data rate, as explained here…

TLDR: We can send more messages to the network if we…

  1. Reduce the Message Size

    (Payload should be 12 bytes or smaller)

  2. Select a Higher Data Rate

    (Our LoRaWAN Driver uses DR2, which is 125 kbps)

Why does the message rate vary by region?

The Things Network operates on ISM Radio Bands, which are regulated differently across regions.

To comply with Local Regulations, each device is allowed to transmit data for up to X seconds per day. (Where X depends on the region)

This daily limit is known as the Duty Cycle, as explained here…

How can we optimise our messages?

Encode our message payload with CBOR (Concise Binary Object Representation) instead of JSON.

(CBOR works like a compressed, binary version of JSON)

This JSON Payload occupies 10 bytes

{ "t": 1745 }

While the CBOR version needs only 6 bytes!

To learn more about CBOR…

Wow… Fair Use sounds complicated!

This Airtime Calculator tells us how many messages we can send in an hour…

Select the Region (like US915), enter the Message Payload Size (say 12 bytes), look up the Data Rate (usually DR2) and our answer magically appears…

Airtime Calculator

§8 What’s Next

In the next article, PineDio Stack shall transmit Real-Time Sensor Data from a Temperature Sensor to The Things Network…

And we shall visualise the Sensor Data with Prometheus and Grafana

Stay Tuned!

Got a question, comment or suggestion? Create an Issue or submit a Pull Request here…

lupyuen.github.io/src/ttn.md

§9 Notes

  1. This article is the expanded version of this Twitter Thread

PineDio Stack BL604 RISC-V Board (foreground) talking to The Things Network via RAKWireless RAK7248 LoRaWAN Gateway (background)