https://github.com/xoseperez/basicstation
This project deploys a LoRaWAN gateway with Basics™ Station Packet Forward protocol with balena. It runs on a Raspberry Pi (3/4) or balenaFin with sx1301, sx1302 and sx1303 SPI LoRa concentrators (e.g. RAK833, RAK2245, RAK2287, RAK5146, Seeed WM1302 and IMST iC880a among others).
Deploy a The Things Stack (TTS v3) LoRaWAN gateway running the Basics™ Station Semtech Packet Forward protocol. We are using balena.io and RAK to reduce fricition for the LoRa gateway fleet owners. This project has been tested with The Things Network (TTN v2), The Things Stack (TTS v3) and The Things Industries (TTI) as well.
The Basics™ Station protocol enables the LoRa gateways with a reliable and secure communication between the gateways and the cloud and it is becoming the standard Packet Forward protocol used by most of the LoRaWAN operators.
Disclaimer: At the moment the basicstation project is not compatible with USB LoRa concentrators. Contributions open :)
SX1301
- IMST iC880a
- RAK 2245 pi hat
- RAK833
SX1302
- RAK 2287 Concentrator with RAK 2287 Pi Hat
- Seeed WM1302 with the Pi Hat (this model is compatible with the RAK2287 Pi Hat as well).
SX1303
- RAK 5146 with RAK2287 Pi Hat.
Once all of this is ready, you are able to deploy this repository following instructions below.
Running this project is as simple as deploying it to a balenaCloud application. You can do it in just one click by using the button below:
Follow instructions, click Add a Device and flash an SD card with that OS image dowloaded from balenaCloud. Enjoy the magic 🌟Over-The-Air🌟!
If you are a balena CLI expert, feel free to use balena CLI.
balena push <application-name>
The model is defined depending on the version of the LoRa concentrator: SX1301
, SX1302
and SX1303
.
In case that your LoRa concentrator is a RAK2287
it is using SX1302
. If the concentrator is the RAK2245
or iC880a
it uses the SX1301
. It's important to change the balenaCloud Device Variable with the correct MODEL
. The default MODEL
on the balena Application is the SX1301
.
MODEL
variable to SX1302
if needed.That enables a fleet of LoRa gateways with both (e.g.) RAK2245
and RAK2287
together under the same app.
From now it's important to facilitate the TTN_STACK_VERSION
that you are going to use: 3
(The Things Stack v3) or 2
(The Things Network or TTN V2). The default variable is set into 3
(V3).
Before starting, also check the TTN_REGION
. It needs to be changed if your region is not Europe. In case you use version 3, the European version is eu1
by default. Check here the LoRa frequencies by country.
With these variables TTN_REGION
and TTN_STACK_VERSION
the TC_URI
will be generated automatically. In case that you want to point to another specific TC_URI
, feel free to add this Device Variable on the balenaCloud.
The LoRa gateways are manufactured with a unique 64 bits (8 bytes) identifier, called EUI, which can be used to register the gateway on The Things Network and The Things Stack. To get the EUI from your board it’s important to know the Ethernet MAC address of it (this is not going to work if your device does not have Ethernet port).
The EUI
will be the Ethernet mac address (6 bytes), which is unique, expanded with 2 more bytes (FFFE). This is a standard way to increment the MAC address from 6 to 8 bytes.
To get the EUI
, copy the TAG of the device which will be generated automatically when the device gets provisioned on balenaCloud for first time. Be careful when you copy the tag, as other characters will be copied.
If that does not work, go to the terminal box and click "Select a target", then “HostOS”. Once you are inside the shell, type:
cat /sys/class/net/eth0/address | sed -r 's/[:]+//g' | sed -e 's#\(.\{6\}\)\(.*\)#\1fffe\2#g'
Copy the result and you are ready to register your gateway with this EUI.
TC_KEY
.Once successfully registered:
Alternativelly, you can also set any of them at application level if you want it to apply to all devices in you application.
Variable Name | Value | Description | Default |
---|---|---|---|
GW_GPS |
STRING |
Enables GPS | true or false |
GW_RESET_PIN |
INT |
Pin number that resets (Raspberry Pi header number) | 11 |
GW_RESET_GPIO |
INT |
GPIO number that resets (Broadcom pin number, if not defined, it's calculated based on the GW_RESET_PIN) | 17 |
TTN_STACK_VERSION |
INT |
If using TTN, version of the stack. It can be either 2 (TTNv2) or 3 (TTS) | 3 |
TTN_REGION |
STRING |
Region of the TTN server to use | eu1 (when using TTN v2 use eu ) |
TC_TRUST |
STRING |
Certificate for the server | Automatically retrieved from LetsEncryt based on the TTN_STACK_VERSION value |
MODEL |
STRING |
SX1301 or SX1302 | SX1301 |
|
TC_URI |
STRING |
basics station TC URI to get connected. | |
EUI_ADDRESS |
STRING |
In case you use Raspberry Pi Zero without eth0 you can use this to generate the EUI from wlan0 instead of another network interface. You will need to add wlan0 |
Remember to generate an API Key and copy it. It will be the TC_KEY
.
The TC_URI
and TC_TRUST
values are automatically populated to use wss://eu1.cloud.thethings.network:8887
if you set TTN_STACK_VERSION
to 3.If your region is not EU you can set it using TTN_REGION
. At the moment there is only one server avalable is eu1
.
Variable Name | Value | Description | Default |
---|---|---|---|
TC_KEY |
STRING |
Unique TTN Gateway Key | (Key pasted from TTN console) |
Remember to copy the The Things Network gateway KEY and ID to configure your board variables on balenaCloud.
The GW_ID
and GW_KEY
variables have been generated automatically when the Application has been created with the Deploy with Balena button. Replace the values with the KEY and ID from the TTN console.
The TC_URI
and TC_TRUST
values are automatically populated to use wss://lns.eu.thethings.network:443
if you set TTN_STACK_VERSION
to 2. If your region is not EU you can set it using TTN_REGION
, Possible values are eu
, us
, in
and au
.
Variable Name | Value | Description | Default |
---|---|---|---|
GW_ID |
STRING |
TTN Gateway EUI | (EUI) |
GW_KEY |
STRING |
Unique TTN Gateway Key | (Key pasted from TTN console) |
At this moment your LoRaWAN gateway should be up and running. Check on the TTN or TTS console if it shows the connected status.
It's possible that on the TTN Console the gateway appears as Not connected if it's not receiving any LoRa message. Sometimes the websockets connection among the LoRa Gateway and the server can get broken. However a new LoRa package will re-open the websocket between the Gateway and TTN or TTI. This issue should be solved with the TTN v3.
Feel free to introduce issues on this repo and contribute with solutions.
Initial state: one of more devices connected to TTNv2 stack (The Things Network).
Proposed procedure:
TC_KEY
variable on each device with the TTN Gateway Key pasted from the TTI console.TTN_STACK_VERSION
variable to 3, either at application level or per deviceNow you can move them from TTS to TTNv2 back and forth (using the TTN_STACK_VERSION
variable) as you wish as long as the gateways are defined on both platforms and the TC_KEY
and GW_KEY
do not change.