Skip to main content

Hands-on with The Things Stack v3 Community Edition

The Things Stack v3 architecture

A first look at The Things Stack v3 and connecting a gateway to Community Edition.

Back in 2017, I wrote about the new The Things Network (TTN) v2 infrastructure — a.k.a. “backend” or core — which sported a great user interface and many highly useful features, providing excellent foundations for significant community growth over the years to come.

Earlier this year TTN announced that the public v2 infrastructure would be permanently shut down and users would need to migrate to the latest and greatest, The Things Stack v3. This is once again available as a free-to-use service, without any direct support or SLAs, as the “Community Edition”.

Subscription plans are also available for commercial users and options include fully managed SaaS, hosting on AWS and Enterprise hosting, with multiple support levels. However, this post is concerned with the Community Edition and while the functionality provided is largely the same, there will be some differences, such as administration options that are not available.

Major changes

The Things Stack v3 architecture can be seen pictured above and some of the key changes are:

  • LoRaWAN v1.0.4 and v1.1 support and support for all classes (A, B & C)
  • RX1 delay
  • MAC commands
  • New application data (uplink/downlink traffic) formats
  • Integrations changes, e.g. new MQTT server addresses
  • API differences

LoRaWAN v1.0.4 was released in October 2020 and for details see the article, What’s new in LoRaWAN 1.04. This is in fact more recent than v1.1, which was introduced in October 2017, hence there are two specification series. For details of v1.1, see What’s new in LoRaWAN 1.1.

One of the reasons that a LoRaWAN Class A device may operate on battery power for an extended period of time is that it only turns its receiver on for brief periods after uplink (transmitting). The first such receive window is called RX1 and the delay after uplink can be configured for 1 to 15 seconds. This delay may be tuned — e.g. to accommodate a high latency backhaul connection — and set per device, with details provided in the MAC Settings guide. End devices are also expected to be fully LoRaWAN standards-compliant and it is possible that additional non-default MAC settings may need to be configured for those which are not.

Other important documentation includes that for data formats (e.g. uplink, downlink and join), payload formatters (e.g. Javascript), integrations, MQTT broker, and the gRPC and HTTP APIs.

For comprehensive details, see Migrating to The Things Stack.

LoRa Basics Station

Block diagram showing LoRa Basics Station

Gateways may still be connected via the legacy UDP Packet Forwarder, but use of this protocol is highly discouraged in favour of LoRa Basics Station (LBS), which is much more advanced and, amongst other things, authenticates gateways to the network and vice versa.

LBS is comprised of two sub-protocols: LoRaWAN Network Server (LNS), and Configuration and Update Server (CUPS). The LNS protocol handles uplink/downlink frames and while it is only strictly necessary to configure this, use of CUPS instead simplifies network management, by taking care of LNS credentials, gateway configuration and for supported hardware, firmware updates.

An LBS system overview is pictured above and a good basic understanding of how this works is important when it comes to troubleshooting. So we can see here that CUPS protocol is based on HTTPS, hence when configuring this our gateways will use a https:// endpoint. However, if we simply use LNS by itself, the endpoint will start wss:// as this uses WebSocket.

With a gateway using LBS we will have the following files:

  • station.conf contains the radio hardware configuration, along with some additional parameters.
  • tc.uri contains the URL for the LNS WebSocket endpoint.
  • cups.uri if present contains the CUPS HTTP endpoint.
  • cups.trust if present contains the certificate for the CA that signed the CUPS endpoint cert.

The LBS specification supports client certificate based authentication, in addition to token. However, TTN only supports the latter. With implementations that support client certificate-based authentication, there would be additional cups.cert and cups.key files.

Administration options

As with v2, administration may be carried out via a feature rich web interface or powerful command line interface (CLI). The benefit of the latter being that this can be scripted and used with configuration management tooling, plus certain advanced settings are available via CLI only.

Web Interface

Screen showing web interface of the things network

Above we can see the web console display the overview information for a gateway. At a first glance, this doesn’t look drastically different to the v2 console — it has a nice clean layout, with important information readily available and links to the various settings, such as for managing collaborators.

Next, we’ll take a look at installing the CLI and using this instead to add a gateway.

CLI

installing the CLI

The command line interface is available for Linux, Mac and Windows. On Linux this can be installed with:

$ sudo snap install ttn-lw-stack

$ sudo snap alias ttn-lw-stack.ttn-lw-cli ttn-lw-cli

Following which we need to configure it to use a particular cluster, which at the time of writing is one of Europe 1 (Ireland), North America 1 (California, USA) or Australia 1 (Sydney). Each cluster has a different web console address and set of API endpoints. For further details, see Getting Started – Addresses.

$ ttn-lw-cli use eu1.cloud.thethings.network --u

Which gives us the following output:

Output of CLI

Finally, we need to log in via the CLI.

$ ttn-lw-cli login

Adding a gateway

Adding a gateway

Amongst other things gateways must be configured for a particular frequency plan and this will vary depending upon where in the world you are. We can list the options with:

$ ttn-lw-cli gateways list-frequency-plans

We then also need to specify a unique ID, the factory configured EUI, and the user ID of its owner. For example:

$ ttn-lw-cli gateways create wainhouse-tower --user-id 9600 --frequency-plan-id EU_863_870 --gateway-eui 00800000A0008232 --enforce-duty-cycle

Note here how we also configured the duty cycle limit to be enforced. There are actually quite a few parameters that can be set at the time of creation, or alternatively, we can configure these later.

Important: if a gateway is deleted the ID cannot be reused and if re-creating a gateway a different ID must be used instead! This is a security measure to prevent the recycling of old gateway IDs to receive their traffic. This limitation is not present with commercial plans, since these are dedicated to a single organisation and hence the ability to purge old IDs is enabled for admins.

$ ttn-lw-cli gateways set wainhouse-tower --antenna.location.latitude 53.7122886 --antenna.location.longitude -1.8833771 --antenna.location.altitude 255 --antenna.add --location-public

For example, setting the location and whether this should be public.

Next, we’ll take a look at CUPS and regardless of whether using this or just LNS, it will be necessary to configure LNS, as CUPS still uses this underneath.

We can create API keys with arbitrary names and configure these with a custom set of permissions. The LNS protocol requires the Gateway Link permission in order to allow receiving uplink and sending downlink. To create such a key using the API we would enter:

$ ttn-lw-cli gateways api-keys create --name LNS --gateway-id wainhouse-tower --right-gateway-link

Edit API key through interface

Alternatively, the web console may be used instead.

Next, we will need a CUPS key and this will require the View Gateway Information, Retrieve Secrets Associated with a Gateway, and Edit Basic Gateway Settings permissions. The first and last so that CUPS can be used to manage the gateway and the second to retrieve the LNS key details.

CUPS key require to View Gateway Information

Important: when creating an API key — e.g. for LNS or CUPS — we must immediately note this as it cannot be later retrieved!

Enter key in basic settings screen

Finally, if using the web interface we would then navigate to General settings and in the LoRa Basics Station LNS Authentication Key, enter the first key that we had created. This is so that when the gateway connects using CUPS, this is then able to send a key to use for connecting via LNS.

It would obviously be simpler to configure LNS only, but as previously mentioned, CUPS offers certain more advanced features and it is better to configure this if possible. For further details, see the Adding Gateways documentation.

Gateway configuration

Gateway configuration

Gateway configuration will vary depending on the vendor and particular model. Above can be seen the main part of the settings page for a Multitech Conduit gateway. Here we select whether we are using simply LNS or CUPS and then enter a URI starting either wss:// or https:// respectively. We paste a CA certificate and just out of sight, at the bottom of the page, the LNS or CUPS key.

For further details, see the Multitech Conduit specific documentation, and also the Multitech provided documentation for LBS. Note that the latter assumes connecting via LNS.

Troubleshooting

The aforementioned Multitech page has some notes on troubleshooting, however we can specify an additional option to the station executable in order to provide more debug output. Then the sequence of commands becomes:

$ /etc/init.d/lora-network-server stop

$ cd /var/run/lora/1

$ sudo ./station -l0

If a gateway is failing to connect using CUPS, we should look for clues here and we are likely to see a HTTP error as it is unable to connect to the CUPS API endpoint. If this is (401) Unauthorized, it may be one of:

  • The CUPS key is incorrect/badly formatted
  • The CUPS key does not have sufficient permissions
  • The CUPS URI is incorrect

Whereas (404) Not Found might indicate one of:

  • The CUPS URI is incorrect
  • The frequency plan is not configured

Most gateways will use LBS reference software from Semtech and so it should be possible to debug these in a similar manner. In this case the Multitech web UI simply updates the files mentioned earlier in the article and restarts the station executable.

Note that we initially experienced difficulty connecting using CUPS and it may have been due to a typo in the documentation which is now fixed, or possibly even that we had to connect first by configuring for LNS, then reconfiguring to use CUPS. If similarly experiencing difficulty connecting with CUPS, it is worth trying this, but if switching from LNS to CUPS be sure to confirm that CUPS is indeed being used and it is not just using the previously configured LNS key.

Wrapping up

In this article, we’ve taken a look at the new TTN architecture, LoRa Basics Station and how we connect a gateway using this. We’ve not covered creating applications and configuring end devices, but this is something that we may look at in a future post, together with updated integrations.

It should be noted that there is a tool for migrating applications and end devices, so this need not all be done by hand. In addition to which, the Packet Broker is configured between v2 and v3 infrastructure, meaning that once a gateway is migrated to v3, applications and end devices that are still on v2 should be able to continue using migrated gateways, until they are also migrated to v3.

Andrew Back

Open source (hardware and software!) advocate, Treasurer and Director of the Free and Open Source Silicon Foundation, organiser of Wuthering Bytes technology festival and founder of the Open Source Hardware User Group.
DesignSpark Electrical Logolinkedin