Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 96 additions & 0 deletions docs/use/lora.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,102 @@ will send binary 0x01C0FFEE
* WiPhone message: `mosquitto_pub -t "home/OpenMQTTGateway/commands/MQTTtoLORA" -m '{"message":"test","type":"WiPhone","to":"123ABC","from":"FFFFFF"}'`\
will send "test" to a WiPhone with chip ID 123ABC

## Decoding LoRaWAN ABP devices

The gateway can decrypt uplinks from LoRaWAN devices using ABP (activation by personalization), such as Dragino sensors switched to ABP mode. It is not a LoRaWAN network server, so this only suits a simple setup:
* The gateway listens on a single frequency, spreading factor and bandwidth. Set each device to send on that same channel (for example `AT+CHS=903900000` and a fixed data rate with ADR off on Dragino devices) and use sync word `0x34`.
* There is no join (OTAA) and no MAC command handling. Downlinks are sent only when you queue them (see below), and confirmed uplinks are acknowledged. Turn off on the device any feature that waits for MAC answers, such as link checks.

This feature is available on ESP32 only. It is not part of the default binaries: build with `'-DLORA_LORAWAN'`. To also decode the payload with a JavaScript decoder, add `'-DLORA_LORAWAN_JS'` and the Duktape library, for example in your `prod_env.ini`:
```ini
[env:ttgo-lora32-v21-lorawan]
extends = env:ttgo-lora32-v21
lib_deps =
${env:ttgo-lora32-v21.lib_deps}
${libraries.duktape}
build_flags =
${env:ttgo-lora32-v21.build_flags}
'-DLORA_LORAWAN'
'-DLORA_LORAWAN_JS'
'-DARDUINO_LOOP_STACK_SIZE=16384'
```

### Declaring a device
The easiest way is the WebUI: open **Configuration > Configure LoRaWAN**, then **Add device**. The page lists the declared devices. It lets you edit their name, model, session keys, Home Assistant entities and decoder, and test a decoder on a payload before saving. Stored keys are never shown, and an empty key field keeps the current key.

You can also add the device with its DevAddr and session keys through the LoRa configuration command. Use `"save":true` to keep it after a restart:

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoLORA/config -m '{"lorawan":{"devaddr":"0187F184","nwkskey":"<32 hex digits>","appskey":"<32 hex digits>","name":"Front door","model":"LDS02"},"save":true}'`

You can declare up to 16 devices (`LORAWAN_MAX_DEVICES`), either one at a time or as an array. To change the name or model later, send only the `devaddr` and the fields to change. To delete a device, send `{"lorawan":{"devaddr":"0187F184","remove":true},"save":true}`. The LoRa state message lists the configured devices, but never their keys.

For each uplink, the gateway checks the message integrity code (MIC) with the NwkSKey, drops repeated frames (same frame counter) and decrypts the payload with the AppSKey. It then publishes to `home/OpenMQTTGateway/LORAtoMQTT/<DEVADDR>`:
```json
{"id":"0187F184","name":"Front door","model":"LDS02","fcnt":67,"fport":10,"payload":"8C6C0100003B00000000","rssi":-34,"snr":10.5,"pferror":-2435,"packetSize":23}
```
Packets from unknown devices, or that fail the MIC check, are published as raw `hex` like any other binary packet.

### JavaScript payload decoders
With `LORA_LORAWAN_JS`, you can attach a decoder to each device. It uses the same formats as The Things Network:
* `function Decoder(bytes, port)` returns an object (TTN v2).
* `function decodeUplink(input)` receives `{bytes, fPort}` and returns `{data, warnings, errors}` (TTN v3).

Publish the script as is, not wrapped in JSON, to `home/OpenMQTTGateway/LORAWANdecoder/<DEVADDR>`. The device must already be declared. The script is stored in flash and can be up to 3800 bytes (`LORAWAN_DECODER_MAX_SIZE`); an empty message removes it:

`mosquitto_pub -t home/OpenMQTTGateway/LORAWANdecoder/0187F184 -f lds02_decoder.js`

The fields of the decoded object are added to the published message:
```json
{"id":"0187F184","name":"Front door","model":"LDS02","fcnt":67,"fport":10,"payload":"8C6C0100003B00000000","BAT_V":3.18,"BAT_PCNT":"88.33","DOOR_OPEN_STATUS":1,"DOOR_STATE":"open","LAST_DOOR_OPEN_DURATION":0,"UTC_TIME":"2026-10-09T06:49:17.000Z","rssi":-34,"snr":10.5,"pferror":-2435,"packetSize":23}
```
If the decoder fails, the message contains `decoder_error` instead. Decoders run on Duktape (ECMAScript 5.1 with some ES6 additions such as `const`), so arrow functions, `let` and template literals are not supported. When a decoder runs, the gateway sets its clock by NTP so that `new Date()` returns the current time.

### Home Assistant entities
Add an `entities` list to the device declaration to create Home Assistant entities from the published fields:
```json
{"lorawan":{"devaddr":"0187F184","entities":[
{"key":"DOOR_STATE","type":"binary_sensor","name":"Door","class":"door","on":"open","off":"close"},
{"key":"BAT_V","name":"Battery voltage","class":"voltage","unit":"V"},
{"key":"rssi","name":"RSSI","class":"signal_strength","unit":"dBm"}]},"save":true}
```
`type` is `sensor` by default. `class` is the Home Assistant device class. Sensors use `state_class` `measurement` unless you set another one. Fields named like the existing LoRa sensors (`tempc`, `hum`, `moi`, `batt`, `count`) are discovered automatically.

### Downlinks
LoRaWAN devices are usually class A: they only listen for a short time 1 s (RX1) and 2 s (RX2) after each of their uplinks. You can't send a command whenever you want. You queue it, and the gateway sends it in the receive window that follows the next uplink of the device. One queued downlink is sent per uplink, and up to 8 can be queued per device (`LORAWAN_MAX_QUEUE`). Downlinks are encrypted and signed with the device keys. The downlink frame counter is kept in flash.

Queue a command with the `send` key, as an object or an array. The payload is the hex FRMPayload, up to 51 bytes:

`mosquitto_pub -t home/OpenMQTTGateway/commands/MQTTtoLORA/config -m '{"lorawan":{"devaddr":"0187F184","send":{"fport":1,"hex":"01000E10"}}}'`

Use `{"lorawan":{"devaddr":"0187F184","clear_queue":true}}` to drop the pending commands. You can also queue and clear commands from the device page of **Configure LoRaWAN**, which shows the pending commands and the downlink frame counter. The uplink message that triggered a downlink reports it:
```json
{"id":"0187F184","fcnt":5,"fport":10,"payload":"8D500100007300000300","downlink":{"fcnt":0,"window":"rx2","power":20,"fport":1,"payload":"01000E10","source":"mqtt"},"downlink_pending":1}
```

Uplinks with a confirmed data type are acknowledged in the same way, even if no command is queued. When a device misses an ACK, it retransmits the same frame. The gateway acknowledges the retransmission again without publishing it twice. Confirmed uplinks (e.g. `AT+CCONFIRM=1` and `AT+CNBTRIALS=1,3` on Dragino devices) help a distant device make sure its events arrive. Keep in mind that the ACK is a downlink, so at the edge of the range the device may miss it and retransmit, which costs battery.

#### Downlink rules
The `downlinks` object of a device declaration holds commands sent automatically, and receive window settings:
```json
{"lorawan":{"devaddr":"0187F184","downlinks":{
"window":"rx2",
"schedules":[{"every":86400,"fport":1,"hex":"01015180"}],
"triggers":[{"when":{"DOOR_STATE":"open"},"fport":1,"hex":"A601","cooldown":3600}]}},"save":true}
```
* `schedules`: queues the command every `every` seconds. It is sent after the first uplink, then after the first uplink following each interval.
* `triggers`: answers an uplink that matches `when`. Use `"uplink"` to match any uplink, or an object of decoded field values that must all be equal. The command is sent in the receive window of that uplink, before the queued ones. `cooldown` (seconds) limits how often it fires.
* `window`: `auto` (default) uses RX1, or RX2 if RX1 can no longer be reached. `rx1` and `rx2` force one window.
* `rx1_frequency`, `rx1_sf`, `rx1_bw`, `rx2_frequency`, `rx2_sf`, `rx2_bw` and `rx1_delay` (seconds, default 1) override the receive windows.
* `tx_power` (dBm) overrides the downlink power.

By default the receive windows follow the region of the configured frequency. For US915 and AU915, RX1 uses the 500 kHz channel matching the uplink channel with the same spreading factor, and RX2 uses 923.3 MHz, SF12, 500 kHz. Both are sent at 20 dBm, because 500 kHz downlinks are about 6 dB less sensitive than 125 kHz uplinks. For EU868, RX1 uses the uplink channel at no more than 14 dBm, and RX2 uses 869.525 MHz, SF12, 125 kHz at 20 dBm. Elsewhere, both windows use the uplink settings and the configured power.

::: tip Dragino devices in single channel mode
With `AT+CHS`, Dragino devices (e.g. LDS02) transmit on the fixed channel, but compute their RX1 channel from their internal channel hopping, so RX1 changes from one uplink to the next. RX2 is fixed: use `"window":"rx2"`. Their downlink commands (e.g. `01000E10` for a 1 hour uplink interval) were accepted on port 1 in testing.
:::

ABP devices usually restart their frame counter when they reboot. The gateway accepts such a restart (the message contains `"fcnt_reset":true`) instead of rejecting the frames.

More info on where the LoRa library is born [@sandeepmistry](https://github.com/sandeepmistry/arduino-LoRa/blob/master/API.md#radio-parameters)

Tutorial on how to leverage LoRa for a mailbox sensor from [PricelessToolkit](https://www.youtube.com/channel/UCz75N6inuLHXnRC5tqagNLw):
Expand Down
64 changes: 64 additions & 0 deletions main/config_LORA.h
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,70 @@ extern void XtoLORA(const char* topicOri, JsonObject& RFdata);

#define repeatLORAwMQTT false // do we repeat a received signal by using MQTT with LORA gateway

/*-------------------LoRaWAN ABP decoding----------------------*/
// Enable with '-DLORA_LORAWAN' (ESP32 only), add '-DLORA_LORAWAN_JS' and ${libraries.duktape} for JavaScript payload decoders
#ifdef LORA_LORAWAN
# ifndef LORAWAN_MAX_DEVICES
# define LORAWAN_MAX_DEVICES 16
# endif
# define LORAWAN_NOT_HANDLED 0 // not a data uplink from a configured device (or MIC check failed)
# define LORAWAN_DECODED 1
# define LORAWAN_DROP 2 // duplicate frame
# include <vector>
struct LoRaWANDownlink {
uint8_t fport;
String hex; // FRMPayload, not encrypted
String source; // "mqtt", "webui", "schedule", "trigger"
};
struct LoRaWANDevice {
uint32_t devAddr = 0;
uint8_t nwkSKey[16] = {0};
uint8_t appSKey[16] = {0};
String name;
String model;
String entities; // serialized JSON array of Home Assistant entity declarations
String downlinks; // serialized JSON object: receive windows overrides, "schedules" and "triggers"
# ifdef LORA_LORAWAN_JS
String decoder;
# endif
uint32_t lastFcnt = 0;
bool seen = false;
String lastPayload; // last decrypted FRMPayload (hex), to test decoders from the WebUI
uint8_t lastPort = 0;
uint32_t fcntDown = 0; // next downlink frame counter, persisted
std::vector<LoRaWANDownlink> queue; // sent one per uplink, in the receive windows following it
std::vector<uint32_t> ruleLast; // millis() of the last schedule/trigger firing, by rule index
};
extern const std::vector<LoRaWANDevice>& LORAWANdevices();
extern bool LORAWANconfigureDevice(JsonObject& device, bool save, String* error);
extern bool LORAWANqueueDownlink(uint32_t devAddr, uint8_t fport, const String& hex, const char* source, String* error);
extern void LORAWANclearQueue(uint32_t devAddr);
# ifndef LORAWAN_MAX_QUEUE
# define LORAWAN_MAX_QUEUE 8 // pending downlinks per device
# endif
# ifndef LORAWAN_MAX_DOWNLINK_SIZE
# define LORAWAN_MAX_DOWNLINK_SIZE 51 // FRMPayload bytes, fits every data rate of the common regions
# endif
extern void LORAWANsetup();
extern int LORAWANtoJson(const uint8_t* packet, int packetSize, JsonObject& LORAdata);
extern void LORAWANConfig_fromJson(JsonObject& LORAdata);
extern void LORAWANState(JsonObject& LORAdata);
# ifdef ZmqttDiscovery
extern void launchLORAWANDiscovery(bool overrideDiscovery);
# endif
# ifdef LORA_LORAWAN_JS
// Decoder scripts are published raw (not JSON) to <base><gateway>/LORAWANdecoder/<DEVADDR>.
// Deliberately outside /commands/#: that subscription only accepts JSON and is limited to JSON_MSG_BUFFER_MAX
# define subjectLORAWANdecoder "/LORAWANdecoder"
# ifndef LORAWAN_DECODER_MAX_SIZE
# define LORAWAN_DECODER_MAX_SIZE 3800 // bytes, NVS strings are limited to ~4000 bytes
# endif
extern void LORAWANdecoderFromMQTT(const char* topic, const char* payload);
extern bool LORAWANsetDecoder(uint32_t devAddr, const String& script);
extern bool LORAWANtestDecoder(const String& script, uint8_t fport, const uint8_t* bytes, size_t len, JsonObject& result);
# endif
#endif

/*-------------------PIN DEFINITIONS----------------------*/

//TTGO LORA BOARD ESP32 PIN DEFINITION
Expand Down
6 changes: 5 additions & 1 deletion main/config_WebContent.h
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,11 @@
#else
# define configure_7
#endif
#define configure_8
#if defined(ZgatewayLORA) && defined(LORA_LORAWAN)
# define configure_8 "<p><form action='lw' method='get'><button>Configure LoRaWAN</button></form></p>"
#else
# define configure_8
#endif

/*------------------- ----------------------*/

Expand Down
39 changes: 30 additions & 9 deletions main/gatewayLORA.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,9 @@ void createOrUpdateDeviceLORA(const char* id, const char* model, uint8_t flags)
// This function always should be called from the main core as it generates direct mqtt messages
// When overrideDiscovery=true, we publish discovery messages of known LORAdevices (even if no new)
void launchLORADiscovery(bool overrideDiscovery) {
# ifdef LORA_LORAWAN
launchLORAWANDiscovery(overrideDiscovery);
# endif
if (!overrideDiscovery && newLORADevices == 0)
return;
if (xSemaphoreTake(semaphorecreateOrUpdateDeviceLORA, pdMS_TO_TICKS(QueueSemaphoreTimeOutLoop)) == pdFALSE) {
Expand Down Expand Up @@ -400,6 +403,9 @@ void LORAConfig_fromJson(JsonObject& LORAdata) {
void setupLORA() {
LORAConfig_init();
LORAConfig_load();
# ifdef LORA_LORAWAN
LORAWANsetup();
# endif
# ifdef ZmqttDiscovery
semaphorecreateOrUpdateDeviceLORA = xSemaphoreCreateBinary();
xSemaphoreGive(semaphorecreateOrUpdateDeviceLORA);
Expand Down Expand Up @@ -454,17 +460,26 @@ void LORAtoX() {
if (deviceId == WIPHONE) {
_WiPhonetoX(packet, LORAdata);
} else if (binary) {
if (LORAConfig.onlyKnown) {
THEENGS_LOG_TRACE(F("Ignoring non identifiable packet" CR));
# ifdef LORA_LORAWAN
int lorawan = LORAWANtoJson(packet, packetSize, LORAdata);
if (lorawan == LORAWAN_DROP)
return;
if (lorawan == LORAWAN_NOT_HANDLED) {
# endif
if (LORAConfig.onlyKnown) {
THEENGS_LOG_TRACE(F("Ignoring non identifiable packet" CR));
return;
}
// We have non-ascii data: create hex string of the data
char hex[packetSize * 2 + 2]; // _rawToHex writes "%02X\r" per byte: needs 2 * size + 2
TheengsUtils::_rawToHex(packet, hex, packetSize);
// Terminate with a null character
hex[packetSize * 2] = 0;

LORAdata["hex"] = hex;
# ifdef LORA_LORAWAN
}
// We have non-ascii data: create hex string of the data
char hex[packetSize * 2 + 1];
TheengsUtils::_rawToHex(packet, hex, packetSize);
// Terminate with a null character
hex[packetSize * 2] = 0;

LORAdata["hex"] = hex;
# endif
} else {
// ascii payload
std::string packetStrStd = (char*)packet;
Expand Down Expand Up @@ -557,6 +572,9 @@ void XtoLORA(const char* topicOri, JsonObject& LORAdata) { // json object decodi

// Load config from json if available
LORAConfig_fromJson(LORAdata);
# ifdef LORA_LORAWAN
LORAWANConfig_fromJson(LORAdata); // LoRaWAN devices are stored separately, "save" applies to them too
# endif
LORAConfig_apply();
stateLORAMeasures();
}
Expand Down Expand Up @@ -594,6 +612,9 @@ String stateLORAMeasures() {
LORAdata["enablecrc"] = LORAConfig.crc;
LORAdata["invertiq"] = LORAConfig.invertIQ;
LORAdata["onlyknown"] = LORAConfig.onlyKnown;
# ifdef LORA_LORAWAN
LORAWANState(LORAdata);
# endif
LORAdata["origin"] = subjectGTWLORAtoMQTT;
enqueueJsonObject(LORAdata);

Expand Down
Loading
Loading