Merge branch 'bindphrase' into unified-lua-lsp

Author: jurgelenas

.gitignore

@@ -1,5 +1,6 @@
 *.luac
 src/WIDGETS/ELRSVTXAdmin/presets.txt
+src/SCRIPTS/TOOLS/ExpressLRSBind/history.txt
 bin/
 .claude/plans/
 TODO.md

README.md

@@ -1,6 +1,6 @@
 # ExpressLRS Lua Scripts
 
-Lua configuration tool for ExpressLRS on EdgeTX radios. Works on both black & white LCD and color LCD radios.
+Lua configuration tool and bind phrase manager for ExpressLRS on EdgeTX radios. Both work on black & white LCD and color LCD radios.
 
 The package also includes two color-LCD widgets: the **ELRS Telemetry Widget** and the **VTX Administrator Widget**.
 
@@ -22,6 +22,18 @@ SCRIPTS/
     crsf_params.lua           -- parameter codec (tool, VTX Admin)
     crsf_session.lua          -- stateful parameter client (tool, VTX Admin)
     crsf_elrsinfo.lua         -- TX module info state (telemetry widget)
+    msp.lua                   -- MSP-over-CRSF codec (bind tool)
+    defer.lua                 -- deferred-callback timer (bind tool)
+    loader.lua                -- GC-guarded script loader (both tools)
+    edgetx_version.lua        -- EdgeTX minimum-version gate (both tools)
+    ui/
+      lcd/
+        text_edit.lua         -- BW text editor (bind tool)
+        alert.lua             -- BW alert screen (both tools)
+      lvgl/
+        dialogs.lua           -- color startup dialogs (both tools)
+    sensors.lua               -- telemetry sensor reader
+    file_storage.lua          -- key=value file persistence
     shim.lua                  -- BW compatibility shim
   TOOLS/
     ExpressLRS/
@@ -30,6 +42,12 @@ SCRIPTS/
       ui/
         lvgl.lua              -- color LCD UI (LVGL)
         lcd.lua               -- black & white LCD UI
+    ExpressLRSBind/
+      main.lua                -- entry point
+      history_storage.lua     -- bind phrase history persistence
+      ui/
+        lvgl.lua              -- color LCD UI (LVGL)
+        lcd.lua               -- black & white LCD UI
 WIDGETS/
   ELRSTelemetry/
     main.lua
@@ -44,7 +62,7 @@ WIDGETS/
       ...
 ```
 
-The shared library `SCRIPTS/ELRS/` is required by the configuration tool and both widgets.
+The shared library `SCRIPTS/ELRS/` is required by both tools and both widgets.
 
 ### Install with edgetx-cli
 
@@ -64,6 +82,27 @@ The main tool (`SCRIPTS/TOOLS/ExpressLRS/`) lets you configure your ExpressLRS t
 
 <img src="screenshots/tool_main.png" width="472" alt="ExpressLRS Configuration Tool">
 
+## ExpressLRS Bind Phrase Manager
+
+The bind tool (`SCRIPTS/TOOLS/ExpressLRSBind/`) sets the bind phrase -- or a raw UID entered as
+comma-separated bytes -- on the transmitter, the receiver, or both in one sequence, and can put the
+TX in bind mode or unbind a connected receiver. The last five phrases are kept as a pick-and-send
+history.
+
+The transmitter's UID is read back automatically -- when the tool opens, after every write, and
+whenever you change the target -- so the page always shows the identity the handset is transmitting
+on. The receiver's own UID is not read: a receiver only answers over an active link, and a link only
+exists between devices that already share a UID, so its answer could never differ from the
+transmitter's. What is worth knowing is whether it is there at all, which the link reports for free.
+
+Setting the phrase over MSP requires **ExpressLRS 4.1+** on the device; a pre-4.1 module never
+answers, and the tool says so in the transmitter row rather than retrying forever. Bind and unbind
+are plain CRSF commands and work on every ExpressLRS version.
+
+<img src="screenshots/tool_bind_bw.png" width="256" alt="ExpressLRS Bind Phrase Manager"><br/>
+
+<img src="screenshots/tool_bind.png" width="472" alt="ExpressLRS Bind Phrase Manager">
+
 ## Widgets
 
 Both widgets running side-by-side on the home screen:
@@ -92,3 +131,6 @@ See [docs/development.md](docs/development.md) for the tool's internal architect
 |------------|----------|------------|
 | Black & white LCD | EdgeTX 2.11.6+, 2.12.1+, or 3.0+ | v3.5.4+ |
 | Color LCD | EdgeTX 2.11.6+, 2.12.1+, or 3.0+ | v3.5.4+ |
+
+The bind phrase manager additionally requires **ExpressLRS 4.1+** on the device for its MSP
+configuration support; on older firmware it reports "No response (needs ELRS 4.1+)".

docs/development.md

@@ -1,6 +1,6 @@
 # Development
 
-This document covers the internal architecture of the ExpressLRS configuration tool and the CRSF simulator used for testing inside the EdgeTX simulator without real hardware.
+This document covers the internal architecture of the ExpressLRS tools and the CRSF simulator used for testing inside the EdgeTX simulator without real hardware.
 
 ## Make targets
 
@@ -32,30 +32,61 @@ Run `make help` to list all targets. The Makefile groups them into three categor
 
 ## Architecture
 
+The configuration tool, `SCRIPTS/TOOLS/ExpressLRS/`:
+
 | Module | Purpose |
 |--------|---------|
 | `main.lua` | Entry point, run-loop orchestrator, and the App policy layer (device switching, folder-ready edges, the synthetic "Other Devices" row types) over a `crsf_session.lua` instance |
 | `navigation.lua` | Folder and device navigation stack |
 | `ui/lvgl.lua` | Color LCD interface (LVGL dialogs, command pages, warnings) |
 | `ui/lcd.lua` | BW LCD interface (text cursor, popups) |
 
-The tool builds on the shared `SCRIPTS/ELRS/` library, which the widgets use too:
+The bind phrase manager, `SCRIPTS/TOOLS/ExpressLRSBind/` (sets the bind phrase / UID over MSP;
+the device side requires ExpressLRS 4.1+, and a pre-4.1 device simply never answers -- the tool's
+bounded UID retry reports that instead of polling forever).
+
+Only the transmitter's UID is read, and only on the events that can change it: the tool opening, a
+write completing, and the target selector moving. The receiver is never asked. It answers over the
+link, a link only exists between devices already sharing a UID, so its answer is the transmitter's
+number by construction; the link's presence carries the whole of what asking would have told us, and
+costs no over-air traffic. That is also why there is no manual refresh -- every event a "read UID"
+button existed to cover is one the App observes for itself:
+
+| Module | Purpose |
+|--------|---------|
+| `main.lua` | Entry point and the App layer: target selection (TX/RX/Both), phrase-vs-raw-UID parsing, the two-step Both sequence (RX first -- writing its phrase drops it off the link -- then TX), the bounded transmitter UID probe, and the frame router over `crsf.drain` |
+| `history_storage.lua` | The last five phrases, newest first, persisted through `file_storage.lua` as indexed keys `h1`..`h5` |
+| `ui/lvgl.lua` | Color LCD interface |
+| `ui/lcd.lua` | BW LCD interface (line list, phrase editing through `ui/lcd/text_edit.lua`). Note `popupConfirmation`'s message argument never reaches the screen on BW: EdgeTX's Lua binding sets `warningInfoText` without `warningInfoLength` (`api_general.cpp` `luaPopupConfirmation`), so a confirmation has only its 24-char title (`WARNING_LINE_LEN`) to say what it needs |
+
+Both tools pick their UI chunk at runtime -- `local useLvgl = (lvgl ~= nil)` -- and load exactly one
+of `ui/lvgl.lua` or `ui/lcd.lua`; there are no per-radio builds.
+
+The tools build on the shared `SCRIPTS/ELRS/` library, which the widgets use too:
 
 | Module | Purpose |
 |--------|---------|
 | `SCRIPTS/ELRS/crsf.lua` | CRSF constants, telemetry transport (`pop`/`drain`/`push`), module detection, derived link state (`hasTelemetry`, refreshed as a drain empties the queue), stateless frame decoders (`decodeDeviceInfo`, `decodeElrsStatus`, `isElrsV1Frame`) |
 | `SCRIPTS/ELRS/crsf_params.lua` | Opt-in parameter codec: `PARAMETER_SETTINGS_ENTRY` chunk reassembly over a caller-owned rx table and per-type decode, plus encoders that return `PARAMETER_READ`/`WRITE`, command-step and suppress-critical-errors frames for the caller to push. Loaded by the tool and the VTX Admin widget |
 | `SCRIPTS/ELRS/crsf_session.lua` | Opt-in stateful parameter client (`CRSFSession.new`, multi-instance): field store, load queue and retry scheduler, paced write queue, command state machine, and optional device discovery, link status and ELRS 1.x detection. Loaded by the tool and the VTX Admin widget |
 | `SCRIPTS/ELRS/crsf_elrsinfo.lua` | Opt-in TX-module state: DEVICE_INFO cache, version-keyed RFMOD/RFRSSI tables, per-connection model-match latch. Loaded only by the telemetry widget |
+| `SCRIPTS/ELRS/msp.lua` | Opt-in MSP-over-CRSF codec: stateless encoders returning `(frameType, payload)` for `MSP_REQ`/`MSP_WRITE` and decoders for single-frame v1 `MSP_RESP`, plus the ELRS `RXTX_CONFIG` UID/phrase helpers. Loaded only by the bind tool |
+| `SCRIPTS/ELRS/defer.lua` | Single-slot `setTimeout`/`poll` timer; scheduling replaces the pending callback, which is what cancels a stale retry when a new action starts. Loaded only by the bind tool |
+| `SCRIPTS/ELRS/ui/lcd/text_edit.lua` | BW text editor replicating the firmware's `editName()` model-name semantics (rotary cycles the char, ENTER advances, long ENTER toggles case or commits on a space). Loaded only by the bind tool's BW UI. `ui/<display>/` is the library's home for shared UI components, mirroring the tools' own `ui/` split |
+| `SCRIPTS/ELRS/ui/lcd/alert.lua` | BW full-screen alert (MIDSIZE title, body lines, optional bottom action labels). Loaded by both tools' BW UIs |
+| `SCRIPTS/ELRS/ui/lvgl/dialogs.lua` | The color-LCD startup dialogs a tool can raise before it has a page -- the version gate and the missing-module notice. Both are terminal, so each takes the caller's `onExit` for the close box and the Exit button. Loaded by both tools' LVGL UIs |
+| `SCRIPTS/ELRS/loader.lua` | The tools' GC-guarded script loader: a full collection before each `loadScript` keeps fresh-install compile peaks from stacking. The one part consumers bootstrap with a bare `loadScript` |
+| `SCRIPTS/ELRS/edgetx_version.lua` | The one home of the minimum EdgeTX requirement (2.11.6 / 2.12.1 / 3.0). Each tool's `main.lua` checks it once and hands `deps.versionOk` to its UI chunk, whose `preCheck` owns the presentation. Keep `min_edgetx_version` in `edgetx.yml` in step |
 | `SCRIPTS/ELRS/sensors.lua` | Generic EdgeTX telemetry reader (`getSensorValue` with a cached name-to-ID lookup), not CRSF-specific. Loaded by `crsf.lua`, which exposes it to every consumer as `crsf.getSensorValue` |
-| `SCRIPTS/ELRS/file_storage.lua` | Generic key=value file persistence (`read`/`write`), schema-free. Loaded only by the VTX Admin widget |
+| `SCRIPTS/ELRS/file_storage.lua` | Generic key=value file persistence (`read`/`write`), schema-free. Loaded by the VTX Admin widget and the bind tool |
 | `SCRIPTS/ELRS/shim.lua` | `table.concat` polyfill for BW radios |
 
 Frames are consumed pull-style. `crossfireTelemetryPop()` is destructive per script instance, and
 the firmware delivers every widget instance its own copy of each incoming frame, so **each script
-instance has exactly one draining consumer**: the tool and the VTX Admin widget drain through
-`session:drain()`, the telemetry widget through `elrsinfo:drain()`. A future widget needing two
-consumers must pop once and route the frames itself. `reassemble()` callers pass the field id they
+instance has exactly one draining consumer**: the config tool and the VTX Admin widget drain through
+`session:drain()`, the telemetry widget through `elrsinfo:drain()`, and the bind tool through
+`crsf.drain(App, App.onFrame)`. A future widget needing two consumers must pop once and route the
+frames itself. `reassemble()` callers pass the field id they
 are waiting for (strict), or `data[3]` to accept any field from their device (`acceptUnsolicited`,
 used by VTX Admin so sibling instances stay in sync from each other's answers).
 
@@ -96,6 +127,18 @@ The simulator supports multiple test scenarios, configurable via the `config.sce
 | `no_module` | No CRSF module found. Triggers "No Module Found" error dialog. |
 | `critical_error` | TX + RX connected with a critical baud-rate error flag. Triggers the warning screen; the suppress write clears it. |
 
+### MSP bind traffic
+
+The mock answers the bind tool's MSP `RXTX_CONFIG` traffic: a UID read (`MSP_REQ`) is served from a
+per-device `mspUid` table, and a phrase write (`MSP_WRITE`) rederives the target's UID through a
+deterministic pseudo-hash, so equal phrases give equal UIDs (the property the Both flow
+demonstrates; the bytes need not match the firmware's MD5). Both devices start on the same UID,
+because a reachable receiver whose UID differs from the transmitter's is a state the radios cannot
+be in. The RX answers only while the scenario keeps it reachable, and writes are unacknowledged just
+like the real firmware. `FRAMETYPE_COMMAND` bind requests are log-only -- note that the firmware
+handles that command identically at either address (`EnterBindingModeSafely`), so the "unbind"
+button puts the receiver into bind mode rather than erasing its binding.
+
 `config.maxPacketBytes` (default 64, `CRSF_MAX_PACKET_LEN`) is the largest frame the mock handset
 link carries. Parameter entries longer than `maxPacketBytes - 8` are chunked exactly as
 `CRSFEndpoint::sendParameter` does, so lowering it -- real firmware shrinks it on slow baud rates in

edgetx.yml

@@ -13,6 +13,8 @@ package:
   screenshots:
     - screenshots/tool_main.png
     - screenshots/tool_main_bw.png
+    - screenshots/tool_bind.png
+    - screenshots/tool_bind_bw.png
     - screenshots/widget_telemetry_fullscren.png
     - screenshots/widget_vtxadmin_fullscreen.png
     - screenshots/widgets.png
@@ -38,6 +40,13 @@ tools:
     depends:
       - ELRS
 
+  - name: ExpressLRSBind
+    path: SCRIPTS/TOOLS/ExpressLRSBind
+    depends:
+      - ELRS
+    exclude:
+      - history.txt
+
 widgets:
   - name: ELRSTelemetry
     path: WIDGETS/ELRSTelemetry

screenshots/tool_bind.png

@@ -73,6 +73,16 @@ local CRSF = {
   FRAMETYPE_PARAMETER_READ = 0x2C,
   FRAMETYPE_PARAMETER_WRITE = 0x2D,
   FRAMETYPE_ELRS_STATUS = 0x2E,
+  FRAMETYPE_COMMAND = 0x32,
+  FRAMETYPE_MSP_REQ = 0x7A,
+  FRAMETYPE_MSP_RESP = 0x7B,
+  FRAMETYPE_MSP_WRITE = 0x7C,
+
+  -- MSP-over-CRSF (single-frame v1: version 1 | start-of-frame | seq 0)
+  MSP_HEADER_V1 = 0x30,
+  MSP_ELRS_RXTX_CONFIG = 0x2D,
+  MSP_RXTX_UID = 0x00,
+  MSP_RXTX_BIND_PHRASE = 0x01,
 
   -- Addresses
   ADDRESS_BROADCAST = 0x00,
@@ -723,8 +733,8 @@ local rxDevice = {
       id = 3,
       parent = 0,
       type = CRSF.TEXT_SELECTION,
-      name = "Ant. Mode",
-      options = "Antenna A;Antenna B;Diversity",
+      name = "Antenna Mode",
+      options = "Antenna 1;Antenna 2;Diversity",
       value = 2,
       units = "",
     },
@@ -1244,6 +1254,53 @@ local function handleCommandWrite(device, param, newStatus)
   param.info = state.info
 end
 
+-- ============================================================================
+-- MSP bind UID state
+-- ============================================================================
+
+-- Per-device bind UID, read and written over MSP RXTX_CONFIG. Both start
+-- on the same UID: a receiver only answers over a link, and a link only
+-- exists between devices that already share one, so a reachable RX whose
+-- UID differs from the TX's is a state the radios cannot be in.
+local mspUid = {
+  [CRSF.ADDRESS_TX] = { 13, 213, 105, 32, 0, 1 },
+  [CRSF.ADDRESS_RX] = { 13, 213, 105, 32, 0, 1 },
+}
+
+--- Derive a deterministic 6-byte UID from bind-phrase bytes: the same
+-- phrase always yields the same UID, so a phrase written to both devices
+-- produces matching UIDs. Equality is the property the tool demonstrates;
+-- the bytes themselves need not match the firmware's MD5 derivation.
+local function deriveUid(chars)
+  local uid = { 0, 0, 0, 0, 0, 0 }
+  local acc = 0
+  for i = 1, #chars do
+    acc = (acc + chars[i] * i) % 251
+    local slot = (i - 1) % 6 + 1
+    uid[slot] = (uid[slot] + acc + chars[i]) % 256
+  end
+  return uid
+end
+
+--- Build an MSP_RESP payload answering a RXTX_CONFIG/UID read.
+-- Layout mirrors the request: header, size (subcmd + 6 bytes), fn, subcmd.
+local function encodeMspUidResponse(deviceId, destAddr, uid)
+  return {
+    destAddr,
+    deviceId,
+    CRSF.MSP_HEADER_V1,
+    7,
+    CRSF.MSP_ELRS_RXTX_CONFIG,
+    CRSF.MSP_RXTX_UID,
+    uid[1],
+    uid[2],
+    uid[3],
+    uid[4],
+    uid[5],
+    uid[6],
+  }
+end
+
 -- ============================================================================
 -- mockPush: Processes commands sent by the Lua script
 -- ============================================================================
@@ -1456,6 +1513,46 @@ local function mockPush(command, data)
       end
     end
     return true
+  elseif command == CRSF.FRAMETYPE_MSP_REQ then
+    -- MSP read: data = { deviceId, handsetId, header, size, fn, subcmd }
+    local deviceId = data[1]
+    local replyTo = data[2] or CRSF.ADDRESS_HANDSET
+    if data[5] == CRSF.MSP_ELRS_RXTX_CONFIG and data[6] == CRSF.MSP_RXTX_UID then
+      if deviceId == CRSF.ADDRESS_TX then
+        queuePush(CRSF.FRAMETYPE_MSP_RESP, encodeMspUidResponse(deviceId, replyTo, mspUid[deviceId]))
+      elseif deviceId == CRSF.ADDRESS_RX and isRxAvailable() then
+        -- Relayed over the air: arrives in the next poll cycle. An absent RX
+        -- answers nothing, which is what drives the tool's bounded retry.
+        queuePushDeferred(CRSF.FRAMETYPE_MSP_RESP, encodeMspUidResponse(deviceId, replyTo, mspUid[deviceId]))
+      end
+    end
+    return true
+  elseif command == CRSF.FRAMETYPE_MSP_WRITE then
+    -- MSP write: data = { deviceId, handsetId, header, size, fn, subcmd, ... }.
+    -- The firmware sends no acknowledgement; the tool re-reads the UID.
+    local deviceId = data[1]
+    local reachable = deviceId == CRSF.ADDRESS_TX or (deviceId == CRSF.ADDRESS_RX and isRxAvailable())
+    if data[5] == CRSF.MSP_ELRS_RXTX_CONFIG and reachable then
+      if data[6] == CRSF.MSP_RXTX_BIND_PHRASE then
+        -- size counts subcmd + phrase bytes, so the phrase ends at data[5 + size]
+        local chars = {}
+        for i = 7, 5 + (data[4] or 0) do
+          chars[#chars + 1] = data[i]
+        end
+        mspUid[deviceId] = deriveUid(chars)
+      elseif data[6] == CRSF.MSP_RXTX_UID then
+        local uid = {}
+        for i = 1, 6 do
+          uid[i] = data[6 + i] or 0
+        end
+        mspUid[deviceId] = uid
+      end
+    end
+    return true
+  elseif command == CRSF.FRAMETYPE_COMMAND then
+    -- Bind/unbind requests. Log-only: the push line above already records
+    -- the destination, and the mock has no bound-state to change.
+    return true
   end
 
   -- Unknown command - ignore

screenshots/tool_bind_bw.png

@@ -36,6 +36,14 @@ CRSF.CONST = {
   FRAMETYPE_PARAMETER_READ = 0x2C,
   FRAMETYPE_PARAMETER_WRITE = 0x2D,
   FRAMETYPE_ELRS_STATUS = 0x2E,
+  FRAMETYPE_COMMAND = 0x32,
+  FRAMETYPE_MSP_REQ = 0x7A,
+  FRAMETYPE_MSP_RESP = 0x7B,
+  FRAMETYPE_MSP_WRITE = 0x7C,
+
+  -- COMMAND (0x32) subcommands (crsf_command_e / crsf_subcommand_e)
+  COMMAND_SUBCMD_RX = 0x10,
+  COMMAND_SUBCMD_RX_BIND = 0x01,
 
   -- Field types (for parsing PARAMETER_SETTINGS_ENTRY responses)
   FIELD_UINT8 = 0,
@@ -270,6 +278,19 @@ function CRSF:requestElrsStatus()
   CRSF.push(CRSF.CONST.FRAMETYPE_PARAMETER_WRITE, { CRSF.CONST.ADDRESS_TX, CRSF.CONST.ADDRESS_HANDSET_ELRS, 0, 0 })
 end
 
+--- Send a COMMAND bind request. Addressed to the TX module it enters bind
+-- mode, transmitting to any RX waiting in bind mode; addressed to the RX it
+-- unbinds a connected receiver.
+-- @param dest  CRSF device address (use CRSF.CONST.ADDRESS_*); nil targets the TX
+function CRSF:sendBindCommand(dest)
+  CRSF.push(CRSF.CONST.FRAMETYPE_COMMAND, {
+    dest or CRSF.CONST.ADDRESS_TX,
+    CRSF.CONST.ADDRESS_HANDSET,
+    CRSF.CONST.COMMAND_SUBCMD_RX,
+    CRSF.CONST.COMMAND_SUBCMD_RX_BIND,
+  })
+end
+
 -- ============================================================================
 -- Return singleton
 -- ============================================================================