Tutorial: Configure the Tektelic Kona Micro Gateway for use with The Things Network

IMG_20190505_102133

Launching a new technology company is always a challenge.  A company like Conserv with an IoT component is doubly so since we don’t just need to worry about our software, but the hardware side of the business as well.  What that means for me these days is testing out a TON of devices, gateways, network stacks, firmware versions, etc.  One of the devices I had on the bench recently is a LoRaWAN gateway from Tektelic Communications.

The Tektelic Kona Micro is a relatively low cost LoRaWAN gateway with a few features that make it attractive for us.  First, it is available with an internal battery backup option.  That’s not something you often see on gateways in this price range.  Second, it has a cellular backhaul option that we use for failover.  Our customers value reliability even when their internet connection is down and the Kona helps us deliver.  We do a lot of our testing with The Things Network (and Conserv runs the gateways for the Birmingham, AL TTN community), but I couldn’t find a good set of instructions for setting this gateway up with TTN in the US.  There is a TTN tutorial for EMEA, but that option relies on using the Tektelic KonaFT tool for configuring the gateway.  I’m not a fan of visual client configuration applications like this, especially when they are Windows only.  As we’ll see, it is possible to configure it over SSH, but I didn’t see anything in the docs about doing so.  All the instructions seem to rely on KonaFT.

So, let’s get started!  Getting the gateway connected is a straightforward affair.  It has an ethernet port (but no Wifi on this model) and is running a DHCP client.  Plug it in, find the device IP, and ssh to it as the root user.  The password for the device is the serial number.  It is printed on a label on the bottom of the gateway.  It is the text located right above the line describing the power requirements.

Once you are into the gateway, stop the packet forwarder (located in /opt/kona-micro-indoor-pkt-forwarder) service:

/etc/init.d/pkt_fwd stop

Now, we need to collect a little information for The Things Network.  Specifically, we need the Gateway ID.  This nugget of info, along with a lot of other useful things, is stored in the SQLite database the gateway uses for managing its configuration settings and such.  That db is located at /tmp/commissioning.db.  Let’s get the gateway ID.  First, open the SQLite database:

sqlite3 /tmp/commissioning.db

Now take a look at the schema:

.schema

You should see that the schema contains a table called “Configuration” and that table should contain a field called “Customer_Gateway_ID”.  That’s the value that we are after.

SELECT Customer_Gateway_ID from Configuration;

And that should return the gateway ID for you.  Make a note of it,  you’ll need that value in a moment.

Now that we have a gateway ID, we can provision the gateway on The Things Network.  Go to The Things Network console, and create a new gateway.  Make sure to check the box to indicate that this gateway uses the legacy packet forwarder, and enter the gateway ID that we retrieved from the gateway itself into the Gateway EUI field.  Select the US frequency plan, and make sure ttn-router-us-west is selected as the router.  It should look something like this, with a less nonsensical gateway ID:

Screen Shot 2019-05-05 at 11.28.05 AM

OK, almost there!  The last step is to configure the gateway to use The Things Network with the ID provided, and to set it up to use the frequencies of the sub-band used by TTN in the US region.  The Tektelic Micro gateway stores its configuration as a JSON file.  The default configuration that loads up is located at /etc/default/config.json.  Here’s an example that works with The Things Network, configured to use the right channels for the TTN sub-band (1).

{
“SX1301_array_conf”:[
{
“board_freq_band”: “US915”,
“SX1301_conf”:[
{
“chip_enable”: true,
“chan_multiSF_0”: {“chan_rx_freq”: 903900000, “spread_factor”: “7-10” },
“chan_multiSF_1”: {“chan_rx_freq”: 904100000, “spread_factor”: “7-10” },
“chan_multiSF_2”: {“chan_rx_freq”: 904300000, “spread_factor”: “7-10” },
“chan_multiSF_3”: {“chan_rx_freq”: 904500000, “spread_factor”: “7-10” },
“chan_multiSF_4”: {“chan_rx_freq”: 904700000, “spread_factor”: “7-10” },
“chan_multiSF_5”: {“chan_rx_freq”: 904900000, “spread_factor”: “7-10” },
“chan_multiSF_6”: {“chan_rx_freq”: 905100000, “spread_factor”: “7-10” },
“chan_multiSF_7”: {“chan_rx_freq”: 905300000, “spread_factor”: “7-10” },
“chan_LoRa_std” : {“chan_rx_freq”: 904600000, “bandwidth”: 500000, “spread_factor”: 8 }
}],
“loramac_public”:true,
“aes_key”: “ABCDEF0123456789ABCDEF0123456789”
}],
“gateway_conf”: {
“gateway_ID”: “”,
“server_address”: “router.us.thethings.network”,
“serv_port_up”: 1700,
“serv_port_down”: 1700,
“keepalive_interval”: 60,
“stat_interval”: 60,
“push_timeout_ms”: 100,
“forward_crc_valid”: true,
“forward_crc_error”: false,
“forward_crc_disabled”: false
}
}

This config will use the TTN US channels, set the keepalive and stat intervals to 60 seconds (a change from the default of 10/30) and pass your gateway ID to TTN.

A complete configuration requires two things in the JSON above to be changed.  The first is the Gateway ID.  Set that to the value that you pulled from the configuration database on the device, the same value you used when you registered the gateway on The Things Network.  The second thing to set is the AES key.  Set that to the gateway key provided by The Things Network.  Once you have made the appropriate changes to /etc/default/config.json, save the file and start the packet forwarder back up:

/etc/init.d/pkt_fwd start

Assuming everything was done correctly, the gateway should show up on The Things Network console as active and start sending messages along.  If for some reason it doesn’t, or the packet forwarder doesn’t start, a good place to look is the packet forwarder log file, which is located at /var/log/pkt_fwd.log.

So what’s next?  Well, we plan to provision a bunch of these things and whenever there is something boring and repetitive to do automation is the order of the day.  I’m working on a python script to do all of the above, given the gateway IP, the serial number, and a valid set of TTN credentials.  When that’s done I’ll release it as an open source project for anyone else that is planning to use the Tektelic gateways at scale.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s