Skip to content

v2.6.1 — Single-connection mode: all events over the device channel

Choose a tag to compare

View all tags
@AxelHamburch AxelHamburch released this 01 Sep 14:30
· 17 commits to main since this release
v2.6.1
d52416d

What's new since v2.6.0

Single-connection mode (v2.6.1)

v2.6.0 introduced the device WebSocket channel for Bolt Card taps, but ran it
alongside the core WebSocket — two persistent connections to the same
host:443. On NAT-challenged routers those two connections clobber each other's
tracking entries and both flap in a ~60 s cycle. Observed symptoms: QR
payments rejected with "No active ZapBox connections", invoices paid but the
relay trigger lost, Bolt Card replies arriving while the settlement event
vanished into a half-open socket.

v2.6.1 routes every server→device event through the device channel when it
is connected:

  • New module device_channel.py: registry of connected device channels plus
    push_to_device() — device channel first, automatic fallback to the core
    WebSocket. Either/or per event, so no duplicate relay triggers.
  • All push sites converted (relay triggers in tasks.py, pin_required /
    pin_error, teach and auth events, manual trigger endpoint).
  • The device channel's liveness is proven to the server by the firmware's
    protocol pings every 20 s — unlike the core WebSocket, it cannot sit
    half-open unnoticed.
  • The "No active ZapBox connections" check accepts the device channel too:
    matching firmware deliberately keeps only that one connection open and
    releases the core WebSocket.

Compatibility

Combination Result
Firmware ≥ single-connection build + extension v2.6.1 ✅ intended setup — one persistent connection
Firmware < v2.6.0 (HTTPS taps) + extension v2.6.1 ✅ works via fallback
Firmware v2.6.0 build + extension v2.6.1 ⚠️ broken — triggers pushed to the channel are ignored
Single-connection firmware + extension v2.6.0 ⚠️ broken — triggers pushed to the released core WS are lost

Update firmware and extension together. The v2.6.0 firmware/extension pair
is superseded and should not remain installed.

Component Required version
LNbits ≥ 1.4.0
ZapBox firmware single-connection build (fix/network-stability, commit 5f8949d or later)

Upgrade notes

No database migration. Uninstall the old extension in LNbits, install v2.6.1,
then flash the matching firmware. Expected log lines on the device:

[NFC-WS] Device channel connected – single-connection mode
[NFC-WS] Releasing core WebSocket — device channel carries all events
Assets 2
Loading