This guide provides detailed instructions on how to convert an HNT Kerlink Gateway into a private LoRaWAN Gateway and connect it to AWS IoT Core for LoRaWAN.
In the first part, you will learn how to convert your HNT Kerlink Gateway into a private LoRaWAN Gateway and establish a connection between your newly converted gateway and AWS IoT Core.
The second part of this guide explains how to attach your LoRaWAN device to AWS IoT Core LNS (LoRaWAN Network Server) and forward the payload message to an MQTT Bridge. It also covers how a Node-Red flow is used to decode the message and how to forward the decoded message to Home Assistant via an MQTT Topic, enabling the ingestion of the JSON payload into MQTT Sensor entities.
- Kerlink-LoRaWAN-To-AWS-IoT-Core
Before starting this project, I contacted Kerlink Support to ask if it is possible to convert an HNT Wirnet iFemtoCell Kerlink Gateway into a simple Gateway. The support team confirmed that it is possible to replace the HNT firmware with standard firmware. I noticed that many HNT gateways are available on the second-hand market, so I bought one for only €80.
A few days later, I received the gateway and started resetting it to factory configuration. I was able to connect to the local console using the admin account and the default password, but I was unable to connect via SSH to the root account. The password did not seem to follow the default format, which is composed of a prefix and the last 6 digits of the serial number, like pdmk-0507DD.
After many hours of reading the support documentation and performing numerous reset operations, I concluded that the gateway had been wiped, but the root account seemed to be restricted to Kerlink support.
Then, I wrote to the support to ask them what the process is to wipe an HNT Gateway to convert it into a simple gateway. The support team informed me that they can activate a magic link to allow the gateway to retrieve a new firmware version from their servers, but this operation is irreversible. Then, I confirmed that I was aware of the irreversibility and that this is what I wanted.
After a latest physical reset button procedure, the gateway finally retrieved the correct firmware version, and it was possible to connect to it with the root account.
Before proceeding with the Kerlink gateway settings, we need to add the gateway on the AWS side.
Before adding the gateway to AWS, some steps need to be accomplished, such as creating a specific IAM role and retrieving the physical gateway's EUI.
Below is the procedure to retreive the Kerlink gateway's EUI :
- Connect to the gateway via SSH
- Run the command :
cat /tmp/board_info.json- Retreive the value of the attribut EUI64 and keep it for later
Before adding your gateway, you need to create a specific IAM role to allow the Configuration and Update Server (CUPS) to manage gateway credentials. This IAM role will be referenced later when you add the gateway. It is unnecessary to document the procedure in detail here, simply follow the AWS documentation : Add an IAM role to allow the Configuration and Update Server (CUPS) to manage gateway credentials
ℹ️ The Configuration and Update Server (CUPS) is a central service that manages gateway credentials and configurations for AWS IoT Core. It facilitates secure communication between the gateway and AWS IoT Core by handling certificate management and updates. The CUPS server ensures that gateways are properly authenticated and authorized to connect to AWS IoT Core, providing a reliable and secure mechanism for managing IoT devices.
Connect to the management console of your prefered region where you want to handle your gatway and go to AWS IoT Core :
- Navigate to :
Manage > LPWAN Devices > Gateways : - Click
Add gateway - Fill in the
Gateway's EUIwith the value retreived earlier - Set the correct
Frequence bandcorresponding to your Radio Frequence Region (e.g., EU868 for Europe) - Click
Add gatewayto save the settings
In the next section :
- Click
Create certificate - Click
Download certificates files
💡Safely keep the Private Key and the certificate file. The X.509 Certificate will be used by the Gateway to connect to AWS IoT Core via the CUPS Server
- Copy the CUPS endpoint that will be used by the Basic Station to connect to AWS IoT Core :
https://xxxxxxxxxxx.cups.lorawan.eu-west-1.amazonaws.com:443 - In the
Gateway permissionssection, select the IAM Role that you created earlier IoTWirelessGatewayCertManagerRole
ℹ️ The Basic Station is a modern protocol designed for LoRaWAN gateways to ensure secure and reliable communication with network servers. It uses WebSockets for communication, which provides enhanced security and stability. The protocol supports features like remote configuration, firmware updates, and secure authentication, making it easier to manage and maintain gateways. By using Basic Station, gateways can efficiently handle data transmission and ensure that they are always up-to-date with the latest configurations and security measures.
System overview of LoRa Basic Station :
Now that the gateway is correctly referenced by AWS IoT Core, we need to configure some settings on the Kerlink Gateway, such as the CUPS endpoint and the X.509 Certificate, which is used as credentials.
Basic Station only recognize certificates and keys with specific names, so you need to rename the files as follow:
- Rename the *.cert.pem file as cups.crt
- Rename the *.private.key file as cups.key
Upload your credential files by scp in the /user/basic_station/etc folder of the gateway.
To enable your credentials, connect on the gateway by SSH and type the following command :
klk_bs_config --enable --cups-uri "https://xxxxxxxxxxx.cups.lorawan.eu-west-1.amazonaws.com:443"Output of the command :
Set CUPS URI: https://xxxxxxxxxxx.cups.lorawan.eu-west-1.amazonaws.com:443
Stopping lorad 2.3.0
Set default lorad regplan: EU868-FR
Starting lorad 2.3.0
Restarting Basic Station
Now, if you return to the AWS IoT Core Management Console, you can verify that your gateway is successfully connected and operational. In the upcoming section, we will delve into the configuration and attachment of devices to AWS IoT Core, as well as the process for forwarding messages to Home Assistant.
The aim of this project is to progressively migrate all my LoRaWAN devices integrated from Helium to my own private LoRaWAN network. I intend to delegate the management of the LNS to AWS while forwarding messages to my on-premise Home Assistant. Therefore, before moving forward, I recommend reading this post to understand how to connect AWS IoT Core to Home Assistant over MQTT.
Before adding a new device to AWS IoT Core, you should configure the device and service settings that will be associated with your device.
- Now, navigate to :
Manage > LPWAN Devices > Devices > Profiles - Click
Add device profile - Select
Select default profileand chooseEU868-A-OTAA - Click
Add device profile
- Now, navigate to :
Manage > LPWAN Devices > Devices > Profiles - Click
Add service profile - Fill in a
Name - Check the box :
Add gateway meta data - Do not activate the public network roaming if your device is fixed and you do not want to be charged for it.
- Navigate to :
Manage > LPWAN Devices > Devices > Destinations - Click
Add destination - Fill in a
Name - Choose the choose option
Publish to AWS IoT Core message broker - Enter the topic destination :
arn:aws:iot:<region>:<account>:thing/Home_Assistant/ - In the section
PermissionsselectCreate a new service role - click
Save
💡 In my case, I want to forward all messages received from my Gateway to Home Assistant which listens on the same topic that the topic destination.
If you want to use the same IAM Role for other destinations, I advice you to create own. For that, follow the offical AWS IoT Core documentation.
Now that you have all the prerequisite settings, you can add your device :
- Navigate to :
Manage > LPWAN Devices > Devices - Select
Add wireless device - Select
Wireless device specificationvalueOTAA v1.0.x - Enter the same values
DevEUI,AppKeyandAppEUIaccording to your device - Fill in a
Name - Select the device and service profile and destination as defined previously
- Finally, click
Save
Your device is now ready to join your LoRaWAN Network. You can then reboot your device to initiate the join procedure. If everything is correct, you can verify the device traffic in the
Device traffictab within the details of your device.
Now that your device can send payload messages to Home Assistant, you need to configure some settings on the Home Assistant side.
Each data frame retrieved from the Kerlink Gateway is processed by a Node-Red flow.
-
The flow listens the Topic
arn:aws:iot:<region>:<account>:thing/Home_Assistant/. -
The payload is decoded from Base64 to Buffer using the specific module function node-red-node-base64.
-
A
switchnode routes the flow based onmsg.payload.WirelessDeviceId. -
The
msg.payload.PayloadDatais decoded by a specific JavaScript function according to the payload device. -
A
switchnode routes the flow based onmsg.payload.PayloadData.typein order to forward the message to the appropriate JavaScript tranformation function. -
The payload message is transformed into a simple JSON format as expected by the MQTT sensor :
msg.payload = { "temperature": { "value": msg.payload.PayloadData.temperature.values[0] }, "humidity": { "value": msg.payload.PayloadData.humidity.values[0] }, "co2": { "value": msg.payload.PayloadData.co2.values[0] }, "lowBattery": { "value": msg.payload.PayloadData.status.lowBattery }, "hardwareError": { "value": msg.payload.PayloadData.status.hardwareError } } return msg;
-
The message is then published to the topic associated with the MQTT sensor :
/adeunis/confort/co2.
💡 For more information on how to use a LoRaWAN Decoder on Node-Red, you can refer to this tutorial
A MQTT Sensor is configured on Home Assistant to integrate the data from the device as entities, below for the CO2 entity :
mqtt:
sensor:
- name: "Adeunis Confort Co2"
state_topic: "/adeunis/confort/co2"
value_template: "{{ value_json.co2.value }}"
force_update: true
device_class: "carbon_dioxide"
unit_of_measurement: "ppm"
unique_id: "adeunis.confort_co2"Now, you can integrate the CO2 entity into a gauge indicator on a dashboard :
With the following code :
type: gauge
entity: sensor.adeunis_confort_co2
needle: true
min: 200
max: 1500
name: Office CO2
segments:
- from: 200
color: "#43a047"
- from: 1000
color: "#ffa600"
- from: 1300
color: "#db4437"
unit: ppm- Official AWS IoT Core for LoRaWAN documentation
- LoRa Basics Station documentation
- Getting started with Kerlink gateways AWS IoT Core for LoRaWAN
If you appreciate my job, please don’t hesitate to star ⭐ it and feel free to provide your feedback !