Basic Station Interface for TTNv3

Basic Station Interface for TTNv3

To download software packages required to support Basic Station interface on Kona Gateways (Micro/Macro/Mega) for TTNv3 along with instructions for installation, please see the attachment below. Attachment section contains three files as described below.

                                            File
                                       File Name
1) Quick Start Guide
Tektelic_Gateways_with_TTNv3_Getting_Started_Guide_v2.pdf
2) Software packages in zip file
Basic-Station-packages-v1.5.1-for-Tektelic-gateways.tar.gz
3) Read Me (captures instructions to install software packages)
README.tektelic-basic-station


Setup Gateway with Basics Station

WARNING: Installing Basics Station in a gateway with BSP older than the major+minor version of the 2021-08 system release will cause the gateway to be CORRUPTED indefinitely. Hence, please make sure that the BSP is updated prior to installing Basics Station. The 2021-08 system releases are listed below. BSP Upgrade instructions can be found in the COMMUNITY section of the Support Portal.
  1. Kona Micro         ->        major+minor version: 3.3.x
  2. Kona Macro        ->        major+minor version: 4.3.x
  3. Kona Mega          ->        major+minor version: 4.3.x
INFO : Either a Linux machine or Windows Subsystem for Linux  (WSL Ubuntu) is required for following along in this guide. For all the terminal commands in this document, please DO NOT enter $. It is used to indicate the beginning of a new command.

Login to the gateway using SSH with the following command:
NOTE: For the commands below, please replace gateway-ip with the IP Address of your gateway.
$      ssh root@gateway-ip
Enter the password of the gateway when requested (9-Digit Serial Number by default).
You can find the current Basics Station version (if installed) on the gateway with the following command:
$      opkg info tektelic-bstn | grep Status
The latest version of Basics Station is v1.5.1. If you are not on the latest version please install to the latest version, run the following commands on the gateway SSH terminal:
$      curl -k --user customer:vU6_ATR3 --ssl-reqd ftp://ftp.tektelic.com/Basic_Station/Basic-Station-packages-v1.5.1-for-Tektelic-gateways.tar.gz -o /lib/firmware/Basic-Station-packages-v1.5.1-for-Tektelic-gateways.tar.gz
$      tar -C /lib/firmware -zxvf /lib/firmware/Basic-Station-packages-v1.5.1-for-Tektelic-gateways.tar.gz
$      echo "src/gz bstn file:///lib/firmware/Basic-Station-packages-v1.5.1-for-Tektelic-gateways" > /etc/opkg/bstn-feed.conf
$      opkg update
$      opkg install tektelic-bstn curl libcurl4
After running the above commands please make sure that in /etc/default/config.json the server_address field has a value of "127.0.0.1". In addition, add report_count: 1, in the gateway-conf section of the file.
Customer with a US gateway, need to make sure that the /etc/default/config.json file is configured for the 2nd sub-band of frequencies in US915

Register the GW on TTNv3

  1. Login to TTNv3 Network Server with a web browser:
    1. If using The Things Stack Community Edition:
      1. https://eu1.cloud.thethings.network/     -    For EU based Customers
      2. https://nam1.cloud.thethings.network/     -    For NA Based Customers
      3. https://au1.cloud.thethings.network/     -    For AU Based Customers
    2. If using  The Things Stack Cloud:
      1. Use the URL for your organization. More information can be found here.
  2. Navigate to the Gateways page and select Add gateway button
  3. Enter the Gateway ID , Gateway EUI and Gateway Name
  4. Select the frequency plan for your region (with used by TTN)
  5.  Select Submit. This will add a new Gateway to TTNv3

Create Gateway (CUPS & LNS) API Keys

Since CUPS automatically configures LNS, you will need two API keys.
WARNING :  Please save the keys in a secure location as you will not be able access them again in the future. If you lose them, you will have to create new keys and replace them in the gateway configuration.

LNS API Key

  1. Go to Gateways page and select your gateway
  2. Select API Keys  from the left side menu
  3. Select Add API key on the right side to add an API Key 
  4. Enter a name for your key
  5. Select  Grant Individual Rights
  6. Select ONLY  the following checkbox:
    1. Link as Gateway to a Gateway Server for traffic exchange, i.e. write uplink and read downlink
  7. Click Create API Key
  8. You will see a screen that shows your newly created API Key. You can now copy it to your clipboard by pressing the copy button. After saving the key in a safe place, press I have copied the key
  9. This is your LNS API Key

CUPS API Key

  1. Go to Gateways page and select your gateway
  2. Select API Keys from the left side menu
  3. Select  Add API key  on the right side to add an API Key
  4. Enter a name for your key
  5. Select  Grant Individual Rights
  6. Select  ONLY  the following checkboxes:
    1. View gateway information
    2. Retrieve secrets associated with a gateway
    3. Edit basic gateway settings
  7. Click  Create API Key
  8. You will see a screen that shows your newly created API Key. You can now copy it to your clipboard by pressing the copy button. After saving the key in a safe place, press I have copied the key
  9. This is your CUPS API Key

Configure CUPS to Send LNS API Key

1. Run the following commands either on a Linux machine or an instance of Windows Subsystem for Linux:
WARNING: Do not run these commands on the gateway, as it will CORRUPT the gateway!
Note : For the commands below, please change thethings.example.com with your TTNv3 Network Server URL. As mentioned  here, the Identity Server APIs are only available in the eu1 cluster. Hence, clusterID must be changed to eu1. This is the case for both Cloud and Community Editions.
$      curl -k -O -L  https://github.com/TheThingsNetwork/lorawan-stack/releases/download/v3.11.3/lorawan-stack_3.11.3_linux_amd64.deb
$      sudo apt install ./lorawan-stack_3.11.3_linux_amd64.deb
$      sudo apt install xdg-utils
$      ttn-lw-cli use thethings.example.com --fetch-ca --user --overwrite
$      ttn-lw-cli login
 2. After logging in to the browser it should display a message saying:  The CLI successfully got an access token. You can now close this window and return to the CLI.

3. Now you can configure CUPS in The Things Stack to transmit the LNS API key when a gateway connects. Run the following commands:
Note: For the commands below, please change the following:
  1. your-gateway-id with your Gateway ID from The Things Stack
  2. your-lns-api-key with the LNS API Key created in the previous 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
4. If successful, you should receive a response as follows:
{
      "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": "<encrypted-base64-lns-api-key>"
      }
}

Files required to configure Gateway

The following files (keys and certificates) are required for the gateway to connect to TTNv3:
  1. tc.uri
  2. tc.trust
  3. cups.uri
  4. cups.trust
  5. tc.key
  6. cups.key

tc.uri: (LNS Server Address)

This file should contain the LNS Server Address: wss://<server-address>:8887
The server address is the network endpoint of The Things Stack LNS. It is a combination of  the protocol (wss) , the server address , and the port.  To create a new folder to keep all files and create this file, run the following commands:
Note: For the commands below, please replace server-address with your TTNv3 Network Server URL
$      mkdir certificates
$      cd certificates
$      echo "wss://server-address:8887" > tc.uri

tc.trust: (LNS Trust)

To create a tc.trust file, you will have to download the complete certificate list (.pem) file from this link. To do so, please run the following command:
$      curl  https://curl.haxx.se/ca/cacert.pem  --output tc.trust -L

tc.key: (LNS Key)

Make sure that you have logged into TTN CLI or followed all steps above before executing the following commands. Run the following commands to create a  tc.key  file.
NOTE: For the commands below, please replace your-lns-api-key with the LNS API key you created above.
$      export LNS_KEY="your-lns-api-key"
$      echo "Authorization: Bearer $LNS_KEY" | perl -p -e 's/\r\n|\n|\r/\r\n/g' > tc.key

cups.trust: (CUPS Trust)

To create a cups .trust  file, you will have to download the complete certificate list (.pem) file from  this link. To do so, please run the following command:
$      curl  https://curl.haxx.se/ca/cacert.pem  --output cups.trust -L

cups.uri: (LNS Server Address)

This file should contain the LNS Server Address: https://<server-address>:443
The server address is the network endpoint of The Things Stack LNS. It is a combination of the  protocol (https) , the  server address , and the  port.  To create this file, run the following command:
Note: For the commands below, please replace server-address with your TTNv3 Network Server URL
$        echo "https://server-address:443" > cups.uri

cups.key

Make sure that you have logged into TTN CLI or followed all steps above before executing the following commands. Run the following commands to create a  cups .key  file:
NOTE: For the commands below, please replace your-cups-api-key with the LNS 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

Transferring Certificates and Keys to the Gateway

Make sure that the gateway is powered on, and you have SSH access to it. SCP can be used to transfer the files to the gateway. Run the following commands to transfer the certificates and keys to the /etc/bstn directory on gateway:
NOTE: For the commands below, please replace  gateway-ip with the IP Address of your gateway
$      scp * root@gateway-ip:/etc/bstn
   
Enter the password of the gateway when requested (9-Digit Serial Number by default).
All certificates and files have now been transferred to the gateway successfully.

SSH back into the gateway, Reboot Basics Station and TEKTELIC Packet Forwarder with the following commands:
$      /etc/init.d/tektelic-bstn restart
$      /etc/init.d/pkt_fwd restart