Getting the Heltec Wireless Lite V3 with SX1262 LoRa Radio Chip to work with LoRaWAN

This article is part 1.5 of the series – Developing a component for ESPHome, for the SX1262 LoRa Radio Chip. The process getting the LoRaWAN functionality of this development board to work with The Things Network proved to be an excercise infrustration management, so the following is a write up of what was required to get it to work. The following is my account of setting up the Heltec Wireless Lite V3 for
connecting to the LoRaWAN network. There were several false starts, but in
the end it was possible to send data and decode it correctly.

Development Environment

ArduinoIDE and the Heltec Board Manager extention

The Heltec boards are defined by the following file (link) which is added through the menu in Preferences…->Additional boards manager URLs

https://github.com/Heltec-Aaron-Lee/WiFi_Kit_series/releases/download/0.0.7/package_heltec_esp32_index.json

This file specifies that esptool 3.3.0 is used for writing the firmware to the Heltec board. There is as issue with usung this version for the Heltec V3 boards, in that the firmware compiles and installs, but puts the ESP32-S3 processor into a boot loop.

The details of this issue is here: https://github.com/Heltec-Aaron-Lee/WiFi_Kit_series/issues/159#issuecomment-1842269504

The fix is to upgrade esptool 4.6.1. The following fix works on Ubuntu, but
it’s a hack. The correct fix would be to change the JSON definition file.

cd ~/.arduino15/packages/Heltec-esp32/tools/esptool_py
mv 3.3.0 3.3.0-bak
wget https://github.com/espressif/esptool/archive/refs/tags/v4.6.1.zip
unzip v4.6.1.zip
rm v4.6.1.zip
mv esptool-4.6.1 3.3.0

LoRaWAN Library

Install the ‘SX126X-Arduino’ library with the library manager (currently version
2.4.0).

A small fix is required. Edit the ‘src/mac/Commissioning.h’ file and comment out the check for whether the LoRaWAN Region has already being set (Line 40).

Example Code – LoRaWAN.ino

From the LoRaWAN library, the LoRaWAN example was copied and modified to get the
system to work.

Modifications:

  • Copy the LoRaWAN.ino file, and remove other unnecessary files. Fix the source to remove the dependancies.
  • Simplify the code. eg. Remove the code sections used for other processors.
  • Set the authentication mode to OTAA, the device type and the Frequency bandplan region to AU915 by adding the optional parameters to ‘lmh_init() – true, CLASS_A and LORAMAC_REGION_AU915.
  • Ensure that the correct LoRaWAN sub-band is being used for AU915 by calling ‘lmh_setSubBandChannels(2)’.
  • Additional Serial.println() output added to trace the execution of the firmware, including the output of the LoRaWAN parameters.

The LoRaWAN parameters (AppEUI, DevEUI and AppKey) are set in the following section.

The Things Network

The Heltec V3 Devices have not been configured as known devices in The Things
Network, and need to be specifically setup.

Select “Enter end device specifics manually”.

Add a new device and set the following Device Parameters

  • Frequency Plan: Australia 915-928 MHz, FSB 2 (used by TTN)
  • LoRaWAN Version: LoRaWAN Specification 1.0.2
  • Regional Parameters version: RP001 Regional Parameters 1.0.2 revision B

Create a JoinEUI (previously known as the AppEUI). This can be freely set any 8-byte value, but cannot be changed once set.

The other parameters that need to be set are:

  • DevEUI
  • AppKey

The easiest way to to get these values is to allow them to be automatically generated by The Things Network interface. They can be specifically set if the manufacturer of a device has preprogrammed a device with a LoRaWAN configuration.

Build and Install Firmware on Device

Update the definitions of the LoRaWAN parameters in the code to reflect the values just generated. It is possible to directly produce the desired strings (in ‘msb’ format) from The Things Network device interface.

Paste these into the code

uint8_t nodeDeviceEUI[8] = {…};
uint8_t nodeAppEUI[8] = {…};
uint8_t nodeAppKey[16] = {…};

Ensure that these parameters are being set in the ‘setup()’ function with the following:

lmh_setDevEui(nodeDeviceEUI);
lmh_setAppEui(nodeAppEUI);
lmh_setAppKey(nodeAppKey);

It is also helpful to also have these values displayed when the board os booted.

The firmware compiles and can be installed onto the Heltec board. On boot, it should
connect to the LoRaWAN network and start transmitting packets of data.

On The Things Network, to check that the uploaded data is correct, the following JavaScript payload filter can be installed for the device, which will decode the data and
(hopefully) display the correct string.

function decodeUplink(input) {
var result;
result = String.fromCharCode.apply(null, input.bytes);
return {
  data: {
    bytes: input.bytes,
    result: result
  },
  warnings: [],
  errors: []
};
}

Notes, Issues and Errors

  • When selecting and playing around with different LoRaWAN Versions and Regonal Parameters, it appears as though The Things Network does not reset LoRaWAN values properly. Changing the LoRaWAN version to 1.1.0 required the additional parameter ‘NwsKey’. If the LoRaWAN version is then set back to 1.0.2, this value becomes the one that is used for the AppKey. There is a note about this in The Things Network interface, but it is not obvious what is required.
  • Care needs to be taken when setting the nodeDevEUI and nodeAppEUI not to set them the wrong way around. If connection packets are being received from the device, but it isn’t able to authenticate, then the nodeDevEUI will be correct, but the other parameters (including LoRaWAN Version) may be wrong.
  • If only intermittent transmitted packets are seen in The Things Network, and the device is not able to authenticate, check that the firmware has selected and is using the correct LoRaWAN sub-band.
  • Selecting other LoRaWAN versions eg. 1.1.0 will require additional parameters to be set., namely NwsKey. This setting is not removed if the LoRaWAN version is set back to 1.0.2, and this value is then used instead of the nodeAppKey. This is a trap. The only way to fix this is to delete the device definition in The Things Network and start over.

Next Steps

  • Convert the Arduino LoRaWAN firmware to ESPHome. This will allow LoRaWAN to be able to be used with the other ESPHome functions, including support for all of the existing supported sensors and outputs, and also operate with Home Assistant. (This will be Part 2 of the “Developing a component for ESPHome, for the SX1262 LoRa Radio Chip” series.)
  • Test with the Helium network. Register the device on the Helium network and check that data is routed correctly.
  • Implement as Class B and Class C LoRaWAN device. The example code currently only
    uploads data. Class B and Class C deviced allow data to be downloaded as well, for device control.