Skip to content

[LORA] LoRaWAN downlinks: queue, schedules, triggers and confirmed uplink ACK - #2405

Open
pwsh wants to merge 11 commits into
1technophile:developmentfrom
pwsh:feature/lora-lorawan-downlinks
Open

pwsh wants to merge 11 commits into
1technophile:developmentfrom
pwsh:feature/lora-lorawan-downlinks

Conversation

@pwsh

@pwsh pwsh commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Description:

Adds downlinks to the LoRaWAN ABP support of the LoRa gateway, so commands can be sent to class A devices, for example to change their uplink interval.

Builds on #2403. This branch contains the #2403 commits (and #2402, through #2403). The commits specific to this PR are the last five:

  • [LORA] LoRaWAN downlinks: queue, schedules, triggers and confirmed uplink ACK
  • [LORA] LoRaWAN: accept ABP frame counter restarts, selectable receive window
  • [LORA] Document LoRaWAN downlinks
  • [LORA] LoRaWAN: acknowledge repeated confirmed uplinks
  • [LORA] Document confirmed uplink retransmissions

I'll rebase once #2403 is merged.

How it works

  • Queue: each device has a queue of up to 8 commands (LORAWAN_MAX_QUEUE). Commands come from MQTT ("send":{"fport":1,"hex":"…"} in the lorawan device declaration, plus clear_queue) or from the device page of the Configure LoRaWAN WebUI page. One command is sent per uplink, in the receive window that follows it.
  • Timing: windows are timed from a DIO0 RxDone interrupt (esp_timer). RX1 is used, or RX2 if RX1 can no longer be reached.
  • Frames: encrypted with the AppSKey and MIC-signed with the NwkSKey. The downlink frame counter is stored in NVS.
  • Confirmed uplinks are acknowledged, even when no command is queued. Retransmissions (same FCnt, sent after a missed ACK) are acknowledged again without being republished.
  • Per-device rules (downlinks):
    • schedules queue a command every N seconds.
    • triggers answer an uplink matching "uplink" or decoded field values (e.g. {"DOOR_STATE":"open"}), with a cooldown.
    • window is auto, rx1 or rx2.
    • Receive window overrides (rx1_*, rx2_*, rx1_delay) and tx_power.
  • Region-aware windows and power. US915/AU915: RX1 on the matching 500 kHz channel, RX2 on 923.3 MHz SF12/500 kHz, both at 20 dBm, because 500 kHz downlinks are about 6 dB less sensitive than 125 kHz uplinks. EU868: RX1 on the uplink channel at no more than 14 dBm, RX2 on 869.525 MHz SF12/125 kHz at 20 dBm.
  • Reporting: the uplink message reports the downlink that answered it (fcnt, window, power, fport, payload, source) and the number still pending.
  • Frame counter restarts: ABP devices often restart their frame counter when they reboot. A frame whose MIC only verifies with the raw 16-bit counter is now accepted as a restart ("fcnt_reset": true). It was previously rejected as an unknown packet.
  • Docs: a "Downlinks" section in docs/use/lora.md.

Tests were run on a LilyGo LoRa32 V2.1 (915 MHz) with a Dragino LDS02 (firmware v1.8.2, ABP, single channel AT+CHS=903900000, DR0), with the device serial log checked over UART:

  • The device's log shows RX1 computed from its internal channel hopping (923.3 / 923.9 / 924.5 / 925.7 / 926.3 MHz on successive uplinks), so RX1 is unpredictable in this mode. RX2 (923.3 MHz DR8) is fixed, which is why the window rule exists.
  • With "window":"rx2", three downlinks were received (rxDone, device RSSI −59 to −64 dBm) and applied: AA0003E8 (set count), a count restore, and 01000E10 (uplink interval 1 h, confirmed with AT+TDC? → 3600).
  • The device reset its frame counter after a reboot, and its uplinks were accepted with fcnt_reset.
  • Confirmed uplinks (AT+CCONFIRM=1, AT+CNBTRIALS=1,3) were acknowledged in RX2 on the first attempt (rxDone, no retransmission).
  • Retransmissions were tested by forcing missed ACKs: ACKs were sent in RX1 on a fixed 923.3 MHz while the device hops its RX1 channel. One uplink was sent 4 times with the same FCnt. Attempts 1–3 missed. Attempt 4 landed on 923.3 MHz and got its ACK (rxDone), and the retries stopped. The downlink FCnt shows 4 ACKs for that frame. Before this fix, duplicates were dropped without an ACK.
  • Builds without warnings in the new code with the env's -w removed and -Wall added: stock env, LORA_LORAWAN, and LORA_LORAWAN + LORA_LORAWAN_JS. (The default [env] passes -w, which hides all warnings.) The code is clang-format 9 clean.

Limitations

  • Not tested on hardware: schedules, triggers, and the EU868/AU915 window defaults. Their code paths are shared with the tested queue path.
  • Queue in RAM: the queue is lost on reboot. The rules and the downlink frame counter are persisted.
  • Loop blocking: sending a downlink blocks the loop task until the receive window (up to 2 s).

Checklist:

🤖 Generated with Claude Code

pwsh and others added 11 commits October 9, 2026 01:51
TheengsUtils::_rawToHex() formats each byte with "%02X\r", so the last
sprintf writes two bytes past the 2 * size hex digits (the '\r' and the
terminating null). LORAtoX() sized its buffer 2 * packetSize + 1, one
byte short, overflowing the stack for every binary LoRa packet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oders

Lets the LoRa gateway receive LoRaWAN devices using ABP on a single
channel (e.g. Dragino sensors set to a fixed frequency and data rate),
which previously could only be published as encrypted hex.

- Build flag LORA_LORAWAN (ESP32): devices (DevAddr, NwkSKey, AppSKey,
  name, model) are declared at runtime through the "lorawan" key of the
  MQTTtoLORA/config command and stored in NVS with "save":true.
- Uplinks from declared devices have their MIC verified, duplicate
  frame counters dropped and FRMPayload decrypted; they are published
  to LORAtoMQTT/<DEVADDR> with fcnt, fport and the decrypted payload.
  Other packets keep the existing raw hex behaviour.
- Build flag LORA_LORAWAN_JS adds Duktape to run TTN style decoders
  (Decoder(bytes, port) or decodeUplink(input)) uploaded as raw scripts
  to <base><gateway>/LORAWANdecoder/<DEVADDR>, outside /commands/#
  because that subscription only accepts JSON up to JSON_MSG_BUFFER_MAX.
  NTP is started so decoders can timestamp with new Date().
- Optional per device "entities" declarations create Home Assistant
  discovery entities from the published fields.

Without the flags the firmware is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds "Configure LoRaWAN" (/lw) to the configuration menu when built with
LORA_LORAWAN:
- list of the declared devices with their decoder status and last FCnt
- add/edit form for DevAddr, name, model, session keys, Home Assistant
  entities (JSON) and the JavaScript decoder; stored keys are never sent
  back to the browser (only a hint of their last bytes), an empty key
  field keeps the current key
- "Test decoder" runs the decoder being edited on a payload, prefilled
  with the last decrypted payload of the device, without saving
- delete button

LORAWANconfigureDevice() now reports configuration errors to the caller,
decoder storage is shared between MQTT and the WebUI (LORAWANsetDecoder),
and device declarations are serialized with a larger buffer so longer
entity lists are not truncated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Information page builds its table by replacing JSON punctuation and
can't display nested values: the "lorawan" array of the LORA state was
shown as stray rows ("lorawan | [devaddr | ...", "fcnt_down | 12}]").
Show each device as a single row ("LoRaWAN <DEVADDR>" with its fields
joined) on that page; the MQTT state keeps the array.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…link ACK

- Per device downlink queue (MQTT "send" / WebUI), sent one per uplink in
  RX1 (RX2 if RX1 can no longer be reached), timed from a DIO0 RxDone
  interrupt; frames encrypted, MIC signed, FCntDown persisted in NVS.
- Downlink rules per device: "schedules" (every N s, sent after the next
  uplink), "triggers" ("uplink" or decoded field values, with cooldown),
  receive window overrides (rx1_frequency/sf/bw, rx2_*, rx1_delay) and
  tx_power.
- Region aware downlink power: 20 dBm on US915/AU915 (500 kHz downlinks)
  and EU868 RX2, gateway setting (max 14 dBm) on EU868 RX1.
- Confirmed uplinks are acknowledged even without queued data.
- WebUI: downlink rules, queue/clear, pending count and FCntDown.

Status: frames sent in RX1 at 14 dBm were not applied by a Dragino LDS02
at -95..-117 dBm uplink RSSI; to be verified at short range with the
device serial log.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… window

- ABP devices often restart their frame counter when they reboot; a frame
  whose MIC only verifies with the raw 16 bits counter is accepted as a
  counter restart (published with "fcnt_reset": true) instead of being
  dropped as unknown.
- Downlink rule "window": "auto" (RX1, else RX2), "rx1" or "rx2". A
  Dragino LDS02 in single channel mode (AT+CHS) computes its RX1 channel
  from a hopping channel index, so RX1 is unpredictable; RX2 (923.3 MHz
  SF12 500 kHz) is fixed. Verified: downlink received in RX2 (device RSSI
  -64 dBm) and applied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When a device misses the ACK of a confirmed uplink it retransmits the
same frame (same FCnt). The gateway dropped it as a duplicate before the
downlink step, so the retries were never acknowledged and the device
kept retrying until NbTrans was exhausted. Duplicates of confirmed
uplinks are now acknowledged again, without republishing the uplink nor
evaluating schedules and triggers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pwsh
pwsh force-pushed the feature/lora-lorawan-downlinks branch from c5e71f5 to 9ca0032 Compare October 10, 2026 16:04

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant