A live-dive handler (real-time front end)

[brunopaes]

Summary

README.md calls out that step(depth, ...) and pressure_at_elevation share one pressure-domain code path "which is also what a future live-dive handler will drive" — but no such handler exists. Every current front end (profile_analyser, altitude_analyser) consumes a complete profile up front, planned or logged, and runs it to completion in one pass. There is no entry point that takes one sample at a time and reports state as a dive happens.

Why it matters

A planned or post-hoc profile is fundamentally different from a live one: there's no "next sample" to derive duration from (README.md:547's "duration is derived from the gap to the next sample" doesn't work when the next sample hasn't happened yet), no ability to clamp an ascent the diver has already started, and no way to surface a CNS/OTU or ceiling violation before the diver has already made the mistake. If this library is ever meant to sit behind an actual dive computer rather than a post-dive log analyser, this is the gap between "decompression calculator" and "decompression monitor."

Design sketch

The pressure-domain primitives (load_gas_at_pressure, DiveState.step_at_pressure) are already sample-at-a-time internally — analyse_profile just calls them in a loop over a known list. A live handler is the same loop driven by an external feed instead of a profile:

class LiveDiveHandler:
    def __init__(self, state: DiveState, gas: GasPlan, gf: tuple[int, int]): ...
    def push_sample(self, depth: float, elapsed: float) -> DiveStatus:
        """One reading in; current ceiling, findings-so-far, and CNS/OTU-to-date out."""

No ascent-walk clamping is possible here — the diver's next depth is not the handler's to choose — so DiveStatus reports rather than corrects.

Scope

• New processors/live_dive.py (or similar): LiveDiveHandler, sample-at-a-time, wrapping the existing pressure-domain primitives.
• Decide what "hardware" actually means here: is this a library API only, or does it define an ingestion contract (poll interval, sensor units, depth/temperature source) that a real device would implement? That's the open question below.
• README.md — replace the line 1018 forward-reference with the real thing, and document the ingestion contract if one exists.

Open questions

• Scope boundary. Is "hardware requisites" in scope for this repo at all, or does it stop at the push_sample API and leave device integration (sensor polling, depth transducer calibration, update rate, battery/latency constraints of an actual embedded target) to whatever consumes this library? The model itself has no hardware dependency today; a live handler is the first thing that would need an opinion about sampling rate and latency.
• Interacts with Support helium as a second inert gas (ZHL-16 for trimix) #1 and Support decompression gas switches #2: a live handler needs a resolved gas plan (switch depths) and, if trimix ships, two inert gases per sample rather than one.
• Whether CNS/OTU (Model CNS clock and OTU accumulation #3) needs to exist before this is useful — a live monitor that can't warn on oxygen loading in real time is missing the failure mode most likely to matter live.

[brunopaes]

Proposed hardware

• Board: Raspberry Pi Zero 2 W — the smallest current official board that still runs full Raspberry Pi OS and CPython 3.11+, which matters because master-splinter's core has zero dependencies and needs nothing more exotic than that to run unmodified.
• Pressure sensor: MS5837-30BA ("Bar30", Blue Robotics) — I2C digital pressure/temperature sensor rated to 300 m, the de facto default in DIY dive computer and ROV builds. MS5837-02BA ("Bar02") is the shallower/higher-resolution alternative if the target range is recreational depths only (<~30 m).
• Battery: single-cell LiPo behind a boost/protection board (e.g. a PiSugar-style HAT, or a discrete boost converter + BMS), sized to sampling rate and target dive duration plus margin, not just runtime under idle.
• Enclosure: waterproof housing rated past the sensor's range, with the sensor's face exposed to ambient water (oil-filled boot or open port) while the board and battery stay dry.

Design sketch

The sensor talks I2C; a driver (smbus2, or Blue Robotics' own ms5837 library) reads raw pressure/temperature and converts to the ambient pressure LiveDiveHandler.push_sample() expects, at the ingestion interval #4 defines. utils/state_store.py already persists tissue pressures to JSON — that's the right mechanism to survive a brownout mid-dive; the reference build's job is confirming a reboot mid-dive resumes from the last written state rather than silently starting fresh.