Hands-on with The Things Stack v3 Community EditionFollow article
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.
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.
For comprehensive details, see Migrating to The Things Stack.
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.confcontains the radio hardware configuration, along with some additional parameters.
tc.uricontains the URL for the LNS WebSocket endpoint.
cups.uriif present contains the CUPS HTTP endpoint.
cups.trustif 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.
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.
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.
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:
Finally, we need to log in via the CLI.
$ ttn-lw-cli login
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
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.
Important: when creating an API key — e.g. for LNS or CUPS — we must immediately note this as it cannot be later retrieved!
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 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
https:// respectively. We paste a CA certificate and just out of sight, at the bottom of the page, the LNS or CUPS key.
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-networks-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
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.
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.