LoRa Basics™ Station can regularly connect to a Configuration and Update Server (CUPS) server to check for configuration and software updates. This page contains information about connecting your gateway to The Things Stack to support remote management via the CUPS Protocol.
Note:
CUPS is not required for sending and receiving LoRaWAN data, but it simplifies gateway management.
CUPS support in The Things Stack is in beta and is subject to change.
Warning:
Configuring CUPS automatically retrieves LNS credentials and configures LNS on your gateway. If you configure CUPS, your gateway will override LNS credentials in case of successful CUPS connection.Requirements
- User account on The Things Stack with rights to create gateways.
- A gateway which supports LoRa Basics™ Station.
Create a Gateway
To connect a gateway using the CUPS protocol, you must first add the gateway in The Things Stack. This can be done either in the console, or via the command line. See instructions for Adding Gateways.
Create Separate CUPS and LNS API Keys
Since CUPS automatically configures LNS, you will need two API keys.
CUPS requires an API key for your gateway with the following rights:
- View gateway information
- Edit basic gateway settings
- Retrieve secrets associated with a gateway
LNS requires an API Key with the following rights:
- Link as Gateway to a Gateway Server for traffic exchange, i.e. write uplink and read downlink
To create an API key for your gateway, follow instructions for Creating a Gateway API key in Adding Gateways.
Configure CUPS to Send the LNS API Key
Command-line interface only
The instructions below use the command-line interface (CLI).
We need to configure CUPS in The Things Stack to transmit the LNS API key when a gateway connects. Use the following command to do so, replacing "your-gateway-id" with your gateway ID in The Things Stack and "your-lns-api-key" with the LNS API key you created in the last step:
$ export GTW_ID="your-gateway-id"
$ export LNS_KEY="your-lns-api-key"
$ export SECRET=$(echo -n $LNS_KEY | xxd -ps -u -c 8192)
$ ttn-lw-cli gateways update $GTW_ID --lbs-lns-secret.value $SECRET
Note:
If you receive an error runningttn-lw-cli gateways update, you may need to update the CLI. See instructions in Installing the CLI.
If successful, you should receive a response as follows:
Show CLI output
{
"ids": {
"gateway_id": "<gateway-id>"
},
"created_at": "2020-10-13T10:49:02.730Z",
"updated_at": "2020-11-17T14:52:06.440Z",
"version_ids": {
},
"lbs_lns_secret": {
"key_id": "is/gateway-secrets-encryption-key",
"value": "<encrpyted-base64-lns-api-key>"
}
}
Configure Gateway
All LoRa Basics™ Station gateways support the following configuration options. Consult your gateway documentation for more information about configuring your specific gateway.
CUPS Server Address
The server address is the network endpoint of The Things Stack CUPS. It is a combination of the protocol (https), the server address, and the port:
Enter the following in your gateway as CUPS Server Address: https://<server-address>:443
Note:
The<server-address> is the address of The Things Stack. If you followed the Getting Started guide this is the same as what you use instead of thethings.example.com, e.g https://thethings.example.com:443.
CUPS Server Certificate / CUPS Trust
This is the CA certificate which secures your domain. A .pem file containing common certificates is available in the Root Certificates Reference.
Upload the .pem file in your gateway as the CUPS Server Certificate / CUPS Trust.
CUPS Key File
This is a file which The Things Stack uses to verify the identity of your gateway.
Use the following commands to create a file called cups.key, replacing "your-cups-api-key" with the CUPS API key you created above.
$ export CUPS_KEY="your-cups-api-key"
$ echo "Authorization: Bearer $CUPS_KEY" | perl -p -e 's/\r\n|\n|\r/\r\n/g' > cups.key
Note:
The above command creates a file calledcups.key, terminated with a Carriage Return Line Feed (0x0D0A) character. Upload this file in your gateway as the CUPS key.
If the connection is successful, the CUPS server will send the LNS Server Address, LNS Trust and the LNS API Key to the gateway and it will automatically attempt to connect to the LNS Server.