investigate LED support and 'braid locate' solutions for NAS cases

[danneu]

Scope

Investigate how braid can drive HDD bay LEDs (fault/locate/activity) in NAS cases with hot-swap backplanes. NAS enclosures typically have per-bay LEDs wired through the HBA/backplane over sideband protocols (SGPIO, SES-2). Goal: support common hardware (Supermicro, LSI/Broadcom, prosumer cases) out of the box, with an escape hatch for custom cases.

Key Design Questions

1. What device-state events should braid emit? Missing device, faulted (scrub error), replacing (source/target), locate-requested, cleared
2. How to resolve device identity? Braid's model is LUKS-mapped UUIDs; LED drivers need /dev/sdX paths
3. What's the MVP hardware surface? Standard SGPIO + SES-2 backplanes cover Supermicro, most rackmount, prosumer builds

Three Options

1. Shell out to ledctl (recommended for MVP)

ledmon package ships ledctl — standard one-shot CLI. Covers SGPIO + SES-2.

ledctl failure=/dev/sdc      # set fault LED
ledctl locate=/dev/sdb       # set locate LED  
ledctl normal=/dev/sda       # clear LEDs

Where it's called:

• After missing-device probe → set failure on missing, normal on healthy
• After scrub with uncorrectable errors → set failure on offending device
• During braid replace → set locate on source so user pulls the right drive
• New subcommand: braid locate <device> for manual bay identification

Pros: Battle-tested, standard hardware path, low implementation cost, in nixpkgs.

Cons: Won't work on cases with GPIO-wired LEDs (Jonsbo N-series, ZimaCube, consumer NAS shells). Silently no-ops — needs a startup probe to detect availability and log it.

2. Hook-based escape hatch

braid emits device-state transitions as systemd events or hook scripts (/etc/braid/hooks.d/). Users wire ledctl, gpioset, or custom controllers.

Pros: Handles every hardware variant. Composes beyond LEDs (ntfy, email, beepers). No upstream lock-in.

Cons: Out-of-box experience is "write your own script." Most users won't.

3. Direct SES via sg_ses

Lower-level SES-2 control. Strict subset of ledctl. Not recommended unless ledctl proves unreliable.

Recommendation

Do #1 + #2 together for MVP:

• ledctl as the built-in path (common hardware)
• Hooks as the escape hatch (rare cases, future-proof)

Implementation TODO

• Enumerate all device-state events braid should emit
• Write startup probe to detect LED capability (SGPIOv1/v2, SES-2, none)
• Implement device-to-sdX path translation (resolve disk-map slot → underlying /dev/sdX)
• Wire device-state changes to ledctl calls (missing, faulted, located, cleared)
• Add braid locate <diskname> subcommand
• Verify against real hardware if possible (test with Supermicro backplane)
• Design and document hook interface for custom LED backends
• Add tests covering state-transition sequencing (e.g., replace: locate source → clear locate → locate target → done)

References

• intel/ledmon — GitHub — SGPIO + SES-2 backend, battle-tested
• SFF-8485 (SGPIO spec) — shift-register protocol for direct-attach backplanes
• SES-2 (SCSI Enclosure Services) — used by SAS expanders, more complex

Footnotesconstraints

• This is for a future enhancement; doesn't block any current features
• Start with probing hardware availability, not assuming it exists
• Keep device-to-sdX translation in one place (will be reused across backends)