lora/sx1262: fix intermittent false negatives and hangs on shared SPI bus - #222

Problem

On the Fri3d Camp 2026 badge (and likely any board where drivers/lora/sx1262.py's SPI bus is shared with another device, e.g. a display), the SX1262 LoRa chip can:

1. Intermittently report as absent (getPacketType() reads back 0xFF) even when a module is physically installed and wired correctly, and
2. Occasionally stop responding entirely (BUSY never clears), requiring a full power-cycle of the board to recover — a software reset (machine.reset()) is not enough, since it doesn't power-cycle the external LoRa module.

Both were reproduced independently while testing an app that probes the LoRa chip once per launch (a hardware self-test tool for this badge) — a fresh reboot would sometimes read the chip correctly, and other times fail, with no change to the wiring or module in between.

Root cause

internal_filesystem/lib/drivers/lora/sx1262.py's SPItransfer():

self.cs.value(0)                     # chip selected

start = time.ticks_ms()
while self.gpio.value():             # wait for BUSY, up to `timeout` (default 5000ms)
    yield_()
    if time.ticks_diff(time.ticks_ms(), start) >= timeout:
        self.cs.value(1)
        return _ERR_SPI_CMD_TIMEOUT

for i in range(cmdLen):
    self.spi.write(bytes([cmd[i]]))  # actual command bytes sent only now
...

Chip-select is asserted, and then the code enters a busy-wait loop before a single command byte is sent — and this happens twice per logical command (once here, once again after the transfer via waitForBusy). On the Fri3d 2026 board, this LoRa SPI device and the display share one physical machine.SPI.Bus (see internal_filesystem/lib/mpos/board/fri3d_2026.py): the LoRa device is created with cs=-1 (hardware CS disabled) and manages its own chip-select via a plain GPIO, while the display runs on the same bus at a much higher clock speed.

I traced the SPI transport itself (lvgl_micropython, micropy_updates/esp32/machine_hw_spi.c, machine_hw_spi_device_transfer()): every individual machine.SPI.Device read/write call is wrapped in spi_device_acquire_bus() / spi_device_release_bus(), which correctly serializes that one call against other devices on the same host. But that protection is scoped per-call, not across the whole logical SX126x command (assert CS → wait for BUSY → send bytes → deassert CS). Nothing stops the display's own SPI device from acquiring the bus and running a transaction while the LoRa driver's CS line is still asserted low from a plain GPIO the framework doesn't know about — from the SX1262's point of view, the display's clock/data looks like more command bytes while it's still selected, corrupting the exchange.

This explains both symptoms:

• A corrupted read that happens to land on 0x00/0xFF reads back as "no chip" even though one is present (there's already a comment in this file's getPacketType() caller acknowledging 0xFF is ambiguous between "absent" and "failed").
• A transaction that gets corrupted mid-command can leave the chip waiting for bytes that never arrive in the expected sequence, which can leave BUSY asserted indefinitely — hence the full hangs, since the two timeout=5000 busy-waits per command (one before sending, one after) are both spent with CS held low, and are hit twice more if a caller retries.

This fix

Reorder SPItransfer() so the BUSY wait happens before self.cs.value(0), not after. This means CS is only held low for the actual byte transfer (fast), rather than for up to timeout milliseconds of idle polling. It meaningfully shrinks the collision window from "up to several seconds of idle CS-low" down to "the transfer itself," without changing the command protocol or touching any C code.

This is not a complete fix. The byte-transfer loop right after CS is asserted is still several separate machine.SPI calls, each individually bus-arbitrated but not as a single atomic unit — so the shared bus can still be preempted between those calls while CS is held low, just for a much shorter window than before. A complete fix needs the LoRa driver to hold the entire transfer (CS-low → last byte → CS-high) under one exclusive bus lock shared with every other device on the same machine.SPI.Bus. The primitives for that already exist and are already used in this codebase — spi_device_acquire_bus() / spi_device_release_bus() in lvgl_micropython's machine_hw_spi_device_transfer() — they're just not currently exposed to Python at a granularity a driver like this one can use (only implicitly, once per call). Exposing something like machine.SPI.Device.lock() / .unlock() (thin wrappers around the same two ESP-IDF calls) in lvgl_micropython, and having SPItransfer() hold that lock for the whole CS-low span, would close the remaining gap. Happy to follow up with that change (in lvgl_micropython) if it's a direction maintainers want — flagging it here rather than bundling an unreviewed cross-repo C change into this PR.

Testing

Verified the failure modes (intermittent false-negative reads, and full hangs requiring a power-cycle) on real Fri3d Camp 2026 hardware across many repeated launches. The reorder in this PR is a straightforward, low-risk control-flow change (pure Python, no new APIs) that I'm confident is correct by inspection, but I have not yet been able to get a clean, repeated before/after comparison on hardware in the same session (the same physical chip became increasingly unreliable after a lot of rapid repeated probing during testing — power-cycling recovers it, which is itself consistent with the "chip left mid-command" theory above). Flagging that so this doesn't read as more thoroughly hardware-validated than it is — would appreciate a second pair of eyes/hardware to confirm the improvement, especially for the full-hang case.