Table of Contents
- Solution Architecture
- Supported Hardware
- Installing ChirpStackOS
- First steps into the ChirpStack OS WebUI
- Configure a gateway as a relay gateway
- Configure a gateway as a border gateway
- Checking the data on the LNS
- Troubleshooting
Solution Architecture
The current implementation of the Gateway Mesh Protocol is done over ChirpStack components, in particular these 3:
- chirpstack-concentratord: abstracts the physical concentrator exposing it via a ZeroMQ connection over IPC.
- chirpstack-gateway-mesh: the actual component responsible to pack, unpack and forward the packets from end nodes to the mesh.
- chirpstack-mqtt-forwarder: the custom forwarder used to forward the packets from the border gateway to the LNS.
The first two components are present in all gateways in the mesh, but the gateway-mesh component will behave differently depending on the role the gateway has. In a relay gateway the gateway-mesh component will do one of the following:
- If the message comes from an end device it will wrap the message in a proprietary LoRaWAN packet and forward it to the mesh using one of the concentratord processes available.
- If the message comes from another relay gateway it will check the max hop count and forward it to the mesh again if it’s not yet matched.
But in a border gateway the gateway-mesh component will unpack the proprietary LoRaWAN packet and forward the original message received from the device to the mqtt-forwarder and the LNS as if it was that gateway who had received in the first place.
Supported Hardware
This is the current supported hardware for the ChirpStackOS with mesh functionality:
| Device | Architecture | OS | |
|---|---|---|---|
| WisGate Edge Pro v2 | MIPS | ChirpStackOS 4.5.2+ Relay or border gateway Does not include LNS |
|
| WisGate Edge Lite v2 | MIPS | ChirpStackOS 4.5.2+ Relay or border gateway Does not include LNS |
|
| WisGate Soho Pro | MIPS | ChirpStackOS 4.5.2+ Relay or border gateway Does not include LNS |
|
| WisGate Connect | ARM64 | ChirpStackOS 4.5.2+ Relay or border gateway Includes LNS - or - Debian with docker services |
|
| WisGate Developer | ARM64 | Running ChirpStackOS 4.5.2+ Relay or border gateway Includes LNS - or - Debian with docker services |
Installing ChirpStackOS
The Gateway Mesh protocol is not yet implemented into current production WisGateOS2 version so you will have to flash ChirpStackOS instead into the RAK Edge Gateways. More information can be found in ChirpStack documentation.
The process is reversible so you will be able to go back to WisGateOS2 anytime you want, but you will lose your current configuration. The process cannot be done from the WebUI but fortunately it is not hard to do following some simple commands.
Let’s assume you have a WisGate Edge Pro v2, Lite v2 or Soho powered on and connected to your LAN and the Internet, you know the IP of the gateway in your LAN and you also know the username and password to log into the gateway to configure it.
| 📝 NOTE: Instructions are for WisGate Edge Pro v2 and Lite v2 (using WisGateOS2) but you can actually flash the same image on a WisGate Edge Pro v1 or Lite v1 (with WisGateO2 version 1). Just be careful to flash the proper version of WisGateOS if you want to go back to it (a WisGate Edge version 1 does not support WisGateOS2). |
Open a terminal client (embedded on Linux or Mac, use Putty or WSL under Windows) and SSH into the machine using the known IP, username and password (in yellow what you have to type):
xose@thuban:~$ ssh root@192.168.1.115
The authenticity of host '192.168.1.115 (192.168.1.115)' can't be established.
RSA key fingerprint is SHA256:rcfKi8N32LDQ2qUgUbQ5Crtah9U3Mi9QGBbQ29zKf4.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '192.168.1.115' (RSA) to the list of known hosts.
root@192.168.1.115's password: *****
BusyBox v1.33.1 (2024-04-18 07:51:34 UTC) built-in shell (ash)
-----------------------------------------------------
LoRaWAN Gateway (WisGateOS 2.2.5_RAK WisGateOS b110)
-----------------------------------------------------
root@RAK7268CV2:~# cd /tmp
root@RAK7268CV2:/tmp#> wget https://artifacts.chirpstack.io/downloads/chirpstack-gateway-os/4.5.2/rak/ramips/mt76x8/chirpstack-gateway-os-4.5.2-rak7289v2-ramips-mt76x8-rakwireless_rak636-squashfs-sysupgrade.bin -O chirpstack-gateway-os.bin
Connecting to artifacts.chirpstack.io (188.166.134.65:443)
chirpstack-gateway-os.bin 100% |***********************************************| 14720k 0:00:00 ETA
root@RAK7268CV2:/tmp# sysupgrade -n chirpstack-gateway-os.bin
killall: watchdog: no process killed
Sending TERM to remaining processes ... logd rpcd netifd odhcpd crond uhttpd rteswplugd mosquitto wisdm lua lora_pkt_fwd ntpd mpstat dnsmasq mwan3track sleep ubusd askfirst
Sending KILL to remaining processes ... askfirst
Switching to ramdisk…
Performing system upgrade…
Start upgrading standard image
Unlocking firmware ...
Writing from <stdin> to firmware ...
Upgrade completed
Rebooting system...
After a while the gateway will boot into ChirpStackOS.
Notes: double check you are using the actual IP of your device in your LAN (will likely be different from the one above) and that you are using the latest image of ChirpStackOS, get the link to the image from here here: https://artifacts.chirpstack.io/downloads/chirpstack-gateway-os.
First steps into the ChirpStack OS WebUI
Access via DHCP
Next step is to log into the ChirpStackOS Web UI and configure the basics. Your router will probably assign it the same IP as before since it’s the same MAC (in the example above 192.168.1.115) so open your favorite browser and point to https://192.168.1.115.
Since the WebUI has its own self-signed certificate you will first be presented with a warning page. No worries, click “Advanced…” and “Accept the Risk and Continue”.
Access via WiFi AP
If you don’t have it connected via cable or don’t want or can access to it via cable you can connect to the WiFi Access Point it creates. The SSID will be something like “ChirpStackAP-xxxxxx” and default password is “ChirpStackAP”. Once connected you will join the network created by the gateway and the gateway itself will be at https://192.168.0.1 . Next you will be presented the same warning as in the previous section.
Default credentials
On the login screen default credentials are user “root” and no password.
Change the default credentials
Once logged in, the first time you will be asked to set a more secure password and you certainly should do it. Just follow the button in the yellow banner to go directly to the set password page and choose something hard to break, or even better: use a password manager to generate a random one and store it for you.
Other settings
You might now want to check some other general settings in the “System > System” menu, like gateway name or local time. Many other options are available since ChirpStackOS is based on OpenWRT, a firmware for routers.
Configure a gateway as a relay gateway
You will have to go through the previous steps for every WisGate Edge gateway you want to flash with ChirpStackOS. This section will describe the configuration of the relay gateways in the mesh. These gateways need not backhaul since they will relay messages over LoRaWAN. The only two components involved here are the chirpstack-concentratord (that abstracts the physical concentrator) and the chirpstack-gateway-mesh that packs, unpacks and forwards messages to the mesh.
Configure the concentratord component - relay gateway
Lets head to the “ChirpStack > Concentratord” menu on the left side. The page is divided into two tabs for the two slots the gateway I’m using (RAK7268v2) has. For each slot you can enable it and choose the type of concentrator it hosts: either a Corecell (SX1302/1303) or a 2.4GHz LoRa Concentrator.
Once you select the concentrator, go to the tab for that same type and configure the antenna, shield model, channel plan, GPS and interface.
Finally click “Save & Apply” to save all changes. You can define one or two concentrators this way, depending on the capabilities of your hardware.
If the configuration is correct the Gateway ID will be displayed at the bottom of the page. Note this is the ID for the first concentrator. At the moment there is no feedback on the second concentrator.
Configure the gateway-mesh component - relay gateway
The gateway-mesh component is the responsible for the mesh functionality. In a relay gateway it will check if the message comes from an end-node or another relay gateway. It will check the max hop limit, wrap it if necessary and forward it to the backhaul concentrator.
All these settings can be easily configured in the “ChirpStack > Gateway Mesh” menu. Along with some more specific ones. In general the defaults are OK to got it working but performance will depend on the network topology and the hardware available.
These are all the settings available on the Gateway Mesh menu for each tab:
-
Global configuration
- Enabled: Check to enable the mesh functionality, otherwise the device will behave like a regular LoRaWAN gateway. Defaults no disabled.
- Region: Region the end-devices are using to send messages. At least one of the concentrators must support this setting. Defaults to “EU868”.
-
Mesh configuration
- Region: Region used to relay messages inside the mesh (from gateway to gateway). At least one of the concentrators must support this setting. Defaults to “EU868”.
- Signing key: This is a 16 bytes shared key to sign the messages inside the mesh. This key will be used to calculate a MIC for all messages between gateways to avoid tampering. Must be the same for all gateways in the same mesh. Defaults to all 0s.
- Border gateway: Check to set this gateway as border gateway. For a relay gateway we will leave this unchecked. Defaults to unchecked.
- Ignore direct uplinks: This is a nice feature to prevent direct messages coming from end-devices (not relayed by another gateway) to be processed in this gateway. This can be useful to debug the network (checking it on the border gateway). But usually you want to leave this unchecked. Defaults to unchecked.
- Max. hop count: Limits the number of hops for any message received by this gateway. This applies to relayed messages, if the message has already hopped these many times it will be discarded. This allows you to avoid flooding the mesh further. This setting is very dependent on the gateway position in the mesh topology. Valid values are 1 to 8. Defaults to 1.
- Frequencies: Communication between relay gateways will randomly use one of these frequencies.
- Tx Power (EIRP): TX power EIRP that will be used for communications between relay gateways.
-
Mesh data-rate configuration
- Modulation: You can use FSK for relayed messages but the default is set to LoRa.
- Spreading factor (LoRa): SF to use to send messages to the mesh. This is a fixed setting and the proper value will depend on many factors (max packet size, duty cycle limitations, distance to nearby gateways,…). Please note the gateway does not know in advance the size of the messages from end-nodes so using here a SF higher (slower) than the one used by the nodes might result in too-long messages and therefore they will fail. Defaults to 7.
- Bandwidth: BW to use for relayed messages. Defaults to 125kHz. Use 812kHz for 2.4GHz links.
- Code-rate (LoRa): C/R to use for relayed messages. Defaults to 4/5. Use 4/8 for 2.4GHz links.
- Bitrate (FSK): Bitrate to use with FSK links. Defaults to 50kbps.
-
Backed configuration
- Slot: Concentrator slot to use for communication with end-devices. Concentratord must have been properly configured for this slot.
-
Mesh Backend configuration
- Slot: Concentrator slot to use for communication between gateways in the mes. Concentratord must have been properly configured for this slot. The Mesh Backend slot can be the same as the Backend slot used for end-device communication, but a different one, specially one that uses a different band is recommended.
Once the mesh network has been properly configured click “Save & Apply” to save changes. Now we have a relay gateway ready and we can move to configure another one repeating the same steps or a border gateway (explained in the next section).
Configure a gateway as a border gateway
For the border gateway the configuration includes some changes in the gateway-mesh component and also the configuration of the mqtt-forwarder connected to the ChirpStack LNS. We will go through all the settings in this section and the next one.
You can use any of the gateways listed in the “Supported Hardware” section. But note not all of them support a local LNS. You can either use one that does (like the WisGate Connect we will be using in the next steps) or deploy ChirpStack LNS in a different machine. Note that you will need ChirpStack 4.9.0+ since that’s the first version that supports the mesh functionality.
Configure the concentratord component - border gateway
We will configure the concentrators the same way we did for the relay gateway case. So nothing more to add here.
One note here: we will have to register this gateway later on the LNS. The Gateway EUI will be the Gateway ID provided in this step and shown at the bottom of the UI, so make sure to write it down or know where to get it when you register the gateway later.
Configure the gateway-mesh component - border gateway
Settings for the gateway-mesh are pretty much the same as in a relay gateway with these differences and notes:
-
Mesh configuration
- Region: This setting has to be the same as with the rest of gateways in the mesh.
- Signing key: Again, this key has to be the same as with the rest of gateways in the mesh.
- Border gateway: For a border gateway we want the checked.
- Ignore direct uplinks: Optionally check this setting to make sure all messages you receive have been relayed. This is useful when debugging the configuration in the lab.
Configure the mqtt-forwarder component - border gateway
In a border gateway the messages received by end-device or by other gateways in the mesh are not being rebroadcasted, instead they are sent to the LNS using the mqtt-forwarder component. This component is the equivalent to the UDP Packet Forwarder or BasicStation but using a custom protocol over MQTT.
In a non-mesh gateway, the mqtt-forwarder component will be listening to the concentratord output to forward messages to the LNS. In a border gateway we will set the mqtt-forwarder to listen to the gateway-mesh component that exposes the same API as concentratord.
So to configure it we will go to “ChirpStack > MQTT Forwarder” and choose the “Mesh” tab on top of the page.
There are 3 sub-tabs in this page:
- Global configuration: check the enable checkbox to enable the MQTT forwarder for the gateway-mesh.
- MQTT configuration: the defaults are pretty much OK to forward to a local ChirpStack LNS (double check the prefix matches the band). To forward to a remote LNS you will have to configure the server URL, credentials and certificates. These are the standard settings for an MQTT over TLS connection.
- Filter configuration: these are whitelists for DevAddr (uplinks) and JoinEUI (join requests). If no filters are configured filtering is disabled.
Checking the data on the LNS
Logging into the LNS
ChirpStack LNS 4.9.0+ is compatible with the Gateway Mesh protocol. This version includes information in the message metadata about the relay gateways the message has gone through as well as a specific section with the last seen for each gateway in the mesh.
Since the ChirpStackOS version for the WisGate Connect gateway we are using here includes the ChirpStack LNS we will open it directly from the “Application” menu. But the following steps will be the same for an external ChirpStack LNS instance.
We will be first presented with the login page for the LNS. This is different from the login page for the OS WebUI before. The default credentials here are user “admin” and password “admin”. Again it is strongly recommended to change them as soon as possible.
We will now go through the basics to get a message from an end-device through the mesh and into the LNS. The ChirpStack LNS has many more features we are not going to cover here.
Adding the border gateway
From the LNS point of view, the whole mesh network is just the border gateway since it will receive the messages from it. Therefore, we have to configure the border gateway in the LNS in the usual way, providing the Gateway ID we got when configuring the concentratord component as the Gateway EUI in the “Gateway > Add Gateway” option.
Checking the metadata for a message from an end-device
Now let’s get some random LoRaWAN device. We will be using a device that already has session credentials (from a different LNS) so it will send uplinks straight away. If your device has to first join the network you will have to provision it on the LNS first.
Also, we have the gateway-mesh component in the border gateway configured to ignore direct uplinks, so any messages will actually be received first by another gateway in the mesh and forwarded until they reach the border gateway and finally the LNS.
Go to the gateway “LoRaWAN frames” tab and trigger a message from the end-device.
The message will pop up as an uplink (either confirmed or non confirmed). Click on the blue button for the uplink and the metadata for the message will be displayed in a side panel. You will be able to check the metadata for the message itself (the original message received by one of the relay gateways) and the border gateway metadata too. Under the border gateway metadata you will see a new section with the mesh metadata, including the hop count and the relay ID receiving the message.
Checking the mesh status
Finally you can check the status of the mesh network under the “Gateway Mesh” menu. At the moment the information it provides is the last seen timestamp for each gateway in the mesh.
Troubleshooting
- If the gateways in the mesh do not show up in the “Gateway Mesh” section of ChirpStack LNS double check they have the proper time. Current version of the ChirpStackOS can only retrieve time from the browser or via NTP, but since these gateways are not connected to the Internet the NTP query does not work so the only way is setting the time from the WebUI syncing it with the browser time.
- If the messages are not being sent in the mesh make sure you are using the same settings for the mesh in all the gateways, specially the signing key and band.
-
The Gateway Mesh protocol adds 14 bytes on the uplink and 15 bytes on the downlink. Take this into account when sending long messages. Choose the mesh SF setting carefully based on the original message sizes and SF used.
Updated