[gbradham]

Summary

In an RTPP run a Maimu's link dropped whenever the mouse left the stimulation zone, and every outage lasted 15�35 s with the light off. The run log showed four separate problems:

• Slow start, then a give-up. The reconnect loop waited 5 s before its first try, backed off to a minute, and stopped after twelve attempts.
• A scan that could never succeed. Each attempt first scanned 6�8 s for the address that had just dropped. A peripheral using BLE privacy re-advertises at a new address after every disconnect (Zephyr's adv.c clears BT_DEV_RPA_VALID on each legacy advertising start), so that address was always gone.
• The train never came back. On reconnect the Maimu always wrote off, so a 1200 s train cut off by a drop stayed off.
• Stale commands replayed. Zone enter/exit commands sent during the outage blocked the flow behind the reconnect, then replayed in a burst, oldest first.

Changes

BLEDevice (core):

• Retries straight away, then after 0.5 s, 1 s and every 2 s.
• MAX_RECONNECT_ATTEMPTS now defaults to None, meaning never give up. A finite value still ends in ERROR.
• On a reconnect it looks for the advertised name first, but only when that name has been heard on this host. A peripheral whose name never arrives doesn't pay an extra scan per attempt.
• Per-attempt logging thins out after the first five, and a line reports how long the reconnect took.

MaimuDevice (plugin):

• Remembers its last command, and the reconnect hook re-sends it: a train for whatever is left of its duration, on as on, and off if nothing was asked or the train has run out. The log says when a train was resumed.
• Commands sent while the link is down return immediately; only the newest is sent on reconnect.
• A lock makes sure the reconnect hook never sends an older command over a newer one from the flow.
• New train(on_ms, off_ms, duration_s) action, declared in ACTION_ARGS_SCHEMA. The node's duty-cycle path uses it instead of a raw write("p�"), so the device knows a train is running.

Docs: the CHANGELOG, docs-site/reference/devices.md and the plugin README are updated, plus the ERROR wording comment in main_window.py.

Follow-up (3a19351): a link that bounces. On the bench, replugging a DK dropped the link again within 0.25 s of a reconnect, and the resend fell back on write()'s retry-once-inside-the-write path. That held the command lock and stalled the flow for 2.4 s, sent a resend computed before the second drop (2.5 s late, overrunning the train), and showed "disconnected" instead of "reconnecting". BLEDevice.write() now takes retry=False, which sends once over the link as it stands. The Maimu uses it for every command and for the resend. The reconnect loop checks the link after its hook and keeps retrying if it died meanwhile, then runs the hook again with the time left at that moment.

Related firmware (outside this repo)

Firmware 0.1.1 for the units goes after the drops themselves: a 2 s supervision timeout instead of the auto-requested 420 ms, +8 dBm TX instead of 0 dBm, and privacy off for a stable address. Units that haven't been updated get everything above except the stable address.

Test plan

• pytest tests/unit/hal plugins/glider-maimu/tests: 599 passed. New tests cover:
  • the retry never stopping, then reconnecting once the peripheral is back
  • a finite limit still ending in ERROR, and the backoff not overflowing
  • name-first on reconnect, and no extra scan for a name never heard
  • a train resuming with its remaining time (asymmetric and symmetric forms)
  • a train with under a second left coming back off
  • on/off restored as they were
  • commands during an outage not blocking, with the newest winning
  • shutdown forgetting the last command
  • a drop during the reconnect step being retried by the loop
  • a resend after a bounce using the time left at that later moment
  • a command whose write dies with the link being sent on reconnect
• pytest tests/unit/core tests/unit/gui/shell/test_main_window_shell.py tests/unit/gui/test_camera_panel_rehearsal.py: everything passes except test_flow_clock.py::test_the_timing_thread_wakes_within_a_couple_of_ms. That test also fails on this machine without this change and doesn't touch the changed code (5.4 ms wake against a 2 ms bound).
• ruff check . and black --check . clean
• GLIDER launches from the branch and loads the Maimu plugin
• On the rig: confirm the reconnect time in the log ("reconnected after X s") and that a train resumes after a drop