Preserve the device's unknown state on nine status flags

[eman]

Replaces #69.

The device encodes certain flags as 0 = unknown, 1 = OFF, 2 = ON. The library collapsed 0 to False, so a field the device explicitly declined to answer was reported as a definite OFF. Nine status flags now surface that third state as None.

Why this is the device's sentinel, not our guess

Navien's own client settles it. NaviLink 2.03.00 (versionCode 141) decodes exactly this set of status fields through KDEnum.MgppOnOFFFlag:

public enum MgppOnOFFFlag {
    UNKNOWN(0, "Unknown"),
    OFF(1, "OFF"),
    ON(2, "ON");
}

Zero is reserved and real values start at 1. Eight of the app's enums do this, and two render their zero as something a user reads as absent — HPWHHeatSource shows "-" and HPWHDREvent shows "Not Applied".

What changed

operation_busy, comp_use, anti_legionella_use, anti_legionella_operation_busy, heat_upper_use, heat_lower_use, air_filter_alarm_use, recirc_reservation_use become bool | None via a new DeviceTriState annotation.

drOverrideStatus is the ninth field the app decodes this way, but this library exposes it as a raw int rather than a flag, so it is untouched.

OnOffFlag gains the vendor's UNKNOWN = 0 — it previously started at OFF = 1, leaving the reserved value unrepresented.

What deliberately did not change

The rule is not global, because zero is not a global sentinel. #69 assumed it was, and that is why it kept producing bugs in both directions. Three other cases are now documented rather than guessed at:

Zero is a real state in five of the app's enums — MgppOperationMode/OperationMode = STANDBY, HydroOperationMode = STOP, HydroFsmState = INIT, FilterChange = NORMAL. A device idling reports 0 constantly; a blanket rule would blank the operating mode most of the time.

Capability flags mean "not fitted". The app hides a feature's entire UI when its DID Use flag reads 0 — if (feature.getRecirculationUse() == 0) { ...setVisibility(8); return; }. That is a definite answer, so device_bool_to_python keeps collapsing those to False, now documented as correct rather than incidental.

Temperatures carry no sentinel at all. No out-of-band constant anywhere in status handling (no 0xFFFF, -999, -1 — the only 65535s in the app are CRC16 masks and IR remote codes). No zero-guard in any display path: the only == 0 checks on the status screen are errorCode, minorCode, waterSprayStatus and airFilterAlarmPeriod, none of them a temperature. getTempText() formats whatever arrives, so a reported 0 renders as 32 °F.

This one carries a warning in the docs, because it is a mistake already made and reverted once on #69 — zero-as-none on deci_celsius_to_preferred reported working sensors as missing during cold-weather operation. Ambient and tank temperatures reach 0 °C legitimately.

Two things worth knowing

The vendor can't distinguish absent from zero either. All 126 numeric fields in the app's status model are primitive int — not one boxed type — so a field missing from the JSON deserializes to 0. There is no protocol-level "unreported" concept to recover.

"Always 0 in a capture" is not evidence. outsideTemperature, mixingRate, currentInletTemperature, dhwTemperature2, recircTemperature, recircFaucetTemperature and heLowerOnTempSetting all exist as getters with no UI call site — the app never renders them for this device type. #69 read their constant zeros in HAR captures as "sensor not present"; it is equally consistent with the field being unused on this model. The app makes no determination, so neither does this library.

Migration

None is falsy, so truthiness is unaffected:

if status.comp_use:      # unchanged

The risk is identity and negative checks, and anything doing arithmetic or formatting:

if status.comp_use is None:   # device is not reporting
elif status.comp_use:         # compressor running

For Home Assistant this is the wanted shape: None renders as "Unknown" instead of writing a fabricated OFF into the recorder database and skewing history. The CLI renders these as Unknown rather than No.

Testing

• 670 passed, 4 skipped (was 638) on Python 3.14 — 32 new tests covering all three states per field, the falsy-but-distinguishable case, and that capability flags are unaffected
• Existing fixtures all carry 1, so no existing assertion changes meaning
• ruff check + ruff format --check clean, mypy clean across 54 files
• Docs build with no new warnings; explanation/unknown-values.rst records the evidence and the migration

Note the repo requires Python ≥ 3.14 (setup.cfg) — on 3.13 the package does not import at all, unrelated to this branch.

[Copilot]

Pull request overview

This PR updates the status-model decoding pipeline to preserve the device’s “unknown” sentinel (0) for a specific set of on/off status flags by surfacing it as None (instead of collapsing it to False), aligning the library’s behavior with Navien’s own client decoding.

Changes:

• Added a tri-state converter (device_tristate_to_python) and a corresponding model annotation (DeviceTriState) to map 0 → None, 1 → False, 2 → True for selected status flags.
• Updated DeviceStatus field types for the affected flags from bool to bool | None, and extended the CLI to render “Unknown” for tri-state output (partially).
• Added targeted unit tests and documentation (including a new “Unknown Values” explanation page) plus changelog entries.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_models.py	Adds tests asserting 0/1/2 tri-state behavior on selected DeviceStatus flags and that capability flags remain boolean.
tests/test_model_converters.py	Adds unit tests for the new device_tristate_to_python converter.
src/nwp500/models/status.py	Introduces DeviceTriState annotation and applies it to specific DeviceStatus flags.
src/nwp500/enums.py	Extends OnOffFlag with UNKNOWN = 0 and documents the meaning.
src/nwp500/converters.py	Adds device_tristate_to_python and documents the distinction between capability vs status flags.
src/nwp500/cli/presentation.py	Adds _yes_no_unknown() and uses it for operation_busy display.
docs/explanation/unknown-values.rst	Adds a detailed explanation page documenting where 0 is a sentinel vs a real value.
docs/explanation/index.rst	Adds the new explanation page to the docs index.
CHANGELOG.rst	Documents the breaking type change and related behavioral updates.

[eman]

Right, fixed in 825cfdf.

Nine is the app's count — the set NaviLink decodes through MgppOnOFFFlag. The library types eight of them, because the ninth (drOverrideStatus) is exposed here as a raw int rather than a flag. The sentence conflated the two counts. Reworded so they cannot be read as contradicting:

The app decodes nine status fields through MgppOnOFFFlag; eight of them exist here as flags and are typed DeviceTriState […] The ninth is drOverrideStatus, which this library exposes as a raw int rather than a flag, so it is left alone.

The migration section said "Nine fields change type" and is now "Eight".

[eman]

Not making this change — the syntax is valid here.

except TypeError, ValueError: without parentheses is PEP 758, which landed in Python 3.14. This project requires 3.14 (setup.cfg: python_requires = >=3.14), so it does not raise SyntaxError on any interpreter that can install the package:

$ python3.14 -c "import ast; ast.parse(open(f).read())"   # parses
$ python3.13 -c "import ast; ast.parse(open(f).read())"
SyntaxError: multiple exception types must be parenthesized

The full suite imports and passes on 3.14 (702 tests), and ruff 0.16.1 actively normalises the parenthesized form to this one — writing except (TypeError, ValueError): and running ruff format rewrites it back, so keeping parens would mean fighting the formatter that CI enforces.

Worth noting this line has now misled two readers, myself included — I flagged it as corruption before checking PEP 758. But the resolution is the version floor, not a code change.

[eman]

Correct, and this was a real bug — thank you. Fixed in 825cfdf.

build_device_status_rows had a second call site I missed: anti_legionella_operation_busy under ANTI-LEGIONELLA still used the two-way ternary, so an unknown rendered as "No" — exactly the failure this branch exists to remove, reintroduced one screen over. I had grepped only the narrower pattern.

examples/advanced/combined_callbacks.py had the same shape ('On' if status.comp_use else 'Off') and is fixed too.

Added tests/test_cli_tristate_presentation.py so this stops recurring — it exercises all three states end-to-end through build_device_status_rows, plus a structural guard that fails if any tri-state field is rendered with a two-way ternary anywhere in presentation.py. Both were verified to fail when the bug is reintroduced and pass when it is not.

The other two rendered references are the CLI-free device_capabilities.py (that reads DeviceFeature.recirc_reservation_use, a CapabilityFlag, still bool) and examples that print the raw value, where None prints informatively as None.