nwp500-python 9.10.0__tar.gz → 9.11.0__tar.gz

{nwp500_python-9.10.0 → nwp500_python-9.11.0}/CHANGELOG.rst

@@ -2,6 +2,40 @@
 Changelog
 =========
 
+Version 9.11.0 (2026-10-22)
+===========================
+
+Added
+-----
+- **The air from a weather entity without a model** (#214). With a
+  weather entity and no ``location_air`` model,
+  ``sim_home_assistant.HomeAssistantEnvironment`` fits one
+  (``sim.location_air.fit``) on the last 3 days
+  (``LOCATION_AIR_WINDOW``) of the air entity's readings, or with
+  ``heater=`` the heater's own air reading while its compressor runs,
+  against the weather entity's outdoor temperature, each reading from
+  the unit it was recorded in (``HomeAssistantClient.outdoor_history``,
+  ``parse_outdoor_history``). It projects the forecast through the fit
+  when the readings the outdoor history covers span a day and follow
+  the outdoor air at r 0.5 or more, and keeps it as ``fitted_air``.
+  ``nwp-cli simulate --sources`` fits one the same way when the sources
+  file has no ``[location_air]``.
+
+Fixed
+-----
+- ``sim.params.params_from_document`` raised ``TypeError`` for a list
+  field given as something else (``unfitted``, the draw domain ranges,
+  readiness ``evidence``), past the ``ValueError`` it documents and
+  that ``sim_live.overlay`` and ``nwp-cli simulate`` handle. It read a
+  string, null or bool in a number field without complaint. Each is
+  now a ``ValueError`` naming the field (#212).
+- ``HomeAssistantEnvironment`` found no inlet plateau for a probe that
+  held one value through a long draw's tail. Home Assistant's history
+  writes a row only when a value changes, so the tail had one reading
+  or none, under the plateau's 3. The probe's history is now read as
+  the value in force every 10 seconds (``held``, ``PROBE_STEP``)
+  (#216).
+
 Version 9.10.0 (2026-10-22)
 ===========================
 

{nwp500_python-9.10.0/src/nwp500_python.egg-info → nwp500_python-9.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.10.0
+Version: 9.11.0
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi

{nwp500_python-9.10.0 → nwp500_python-9.11.0}/docs/how-to/simulate-heater.rst

@@ -159,10 +159,13 @@ give:
 
 - **the air:** the hourly forecast projected through the
   ``[location_air]`` model, shifted to pass through a reading beside the
-  heater that is at most an hour old. Without a model, that reading is
-  held over the span; without a fresh one, the projection is
-  unshifted. Fit a model for your own heater with
-  ``sim.location_air.fit``;
+  heater that is at most an hour old; without a fresh one, the
+  projection is unshifted. Without a ``[location_air]`` model, one is
+  fitted on the last 3 days of the ``air`` entity's readings against
+  the ``weather`` entity's outdoor temperature. It is used when the
+  readings span a day and follow the outdoor air at r 0.5 or more; a
+  note gives the fit. Otherwise, and without a ``weather`` entity, the
+  reading beside the heater is held over the span;
 - **the humidity:** a reading at most an hour old;
 - **the inlet:** the plateau of the long draws (11 minutes or more,
   circulation off) in the last 72 hours, from the inlet probe and the
@@ -182,6 +185,15 @@ in rpm or Hz. A part that can't be read, or is stale, keeps its
 default, and a warning on stderr says why. ``--ambient``, ``--inlet``
 and ``--environment`` override what the sources give.
 
+From Python, ``sim_home_assistant.HomeAssistantEnvironment`` reads the
+same parts. Given ``heater=``, a ``HeaterEntities`` with ``ambient`` and
+``compressor``, it fits the model without an ``air`` entity: on the
+heater's own air reading every 10 minutes while the compressor runs,
+where the reading was taken 2 minutes or more into the run (earlier, or
+idle, it reads the cabinet), and not while the sensor was unavailable.
+The latest such reading, if under an hour old, anchors the projection.
+``fitted_air`` holds the fit once ``read`` has run.
+
 
 Fetch what the heater reports
 =============================

{nwp500_python-9.10.0 → nwp500_python-9.11.0}/docs/reference/python_api/sim.rst

@@ -313,9 +313,11 @@ Home Assistant sources
 
 .. automodule:: nwp500.sim_home_assistant
    :members: HomeAssistantEnvironment, HomeAssistantClient, record_inputs,
-      RecordInputs, INLET_LOOKBACK, Sources, Entities, sources_from, State, parse_state,
+      RecordInputs, INLET_LOOKBACK, PROBE_STEP, held, LOCATION_AIR_WINDOW,
+      LOCATION_AIR_MIN_SPAN, LOCATION_AIR_MIN_R, RUN_SETTLE, Sources,
+      Entities, sources_from, State, parse_state,
       parse_history, parse_outages, parse_states, History, history_for,
-      parse_forecast, read_heater_history, HeaterEntities, HeaterHistory,
+      parse_forecast, parse_outdoor_history, read_heater_history, HeaterEntities, HeaterHistory,
       HISTORY_WINDOW, to_w, to_wh,
       pump_runs, demand_spans, busy, covers_start, percent,
       fresh, to_f, to_gpm, to_gal, to_rpm, HomeAssistantError

{nwp500_python-9.10.0 → nwp500_python-9.11.0}/src/nwp500/sim/params.py

@@ -45,8 +45,8 @@ from collections.abc import Mapping
 from dataclasses import MISSING, dataclass, field, fields, replace
 from datetime import timedelta
 from enum import StrEnum
-from types import MappingProxyType
-from typing import Any
+from types import MappingProxyType, NoneType, UnionType
+from typing import Any, cast, get_args, get_origin, get_type_hints
 
 from nwp500.sim.units import WATER_BTU_PER_GAL_F
 
@@ -1187,10 +1187,49 @@ def unknown_fields(doc: Mapping[str, Any]) -> list[str]:
     out = [k for k in doc if k not in ("schema", "unfitted") and k not in PARTS]
     for name, cls in PARTS.items():
         known = {f.name for f in fields(cls)}
-        out.extend(f"{name}.{k}" for k in doc.get(name, {}) if k not in known)
+        given = doc.get(name, {})
+        if isinstance(given, Mapping):
+            keys = cast(Mapping[str, Any], given)
+            out.extend(f"{name}.{k}" for k in keys if k not in known)
     return out
 
 
+def _check(where: str, hint: Any, value: Any) -> None:
+    """A ``ValueError`` naming ``where`` when ``value`` is not what a
+    document holds for a field of type ``hint``: a number for a float,
+    a list for a tuple, null for None."""
+    args = get_args(hint)
+    if get_origin(hint) is UnionType:
+        if value is None and NoneType in args:
+            return
+        (hint,) = (a for a in args if a is not NoneType)
+        args = get_args(hint)
+    if get_origin(hint) is tuple:
+        if not isinstance(value, list | tuple):
+            raise ValueError(f"{where} is {value!r}, not a list")
+        items: list[Any] | tuple[Any, ...] = value
+        if len(args) == 2 and args[1] is Ellipsis:
+            args = (args[0],) * len(items)
+        elif len(items) != len(args):
+            raise ValueError(
+                f"{where} has {len(items)} values, not {len(args)}"
+            )
+        for i, (h, v) in enumerate(zip(args, items, strict=True)):
+            _check(f"{where}[{i}]", h, v)
+        return
+    if hint is float:
+        ok = isinstance(value, int | float) and not isinstance(value, bool)
+        kind = "a number"
+    elif hint is bool:
+        ok, kind = isinstance(value, bool), "true or false"
+    elif hint is str:
+        ok, kind = isinstance(value, str), "a string"
+    else:
+        return
+    if not ok:
+        raise ValueError(f"{where} is {value!r}, not {kind}")
+
+
 def params_from_document(doc: Mapping[str, Any]) -> HeaterParams:
     """The ``HeaterParams`` ``doc`` holds.
 
@@ -1199,8 +1238,9 @@ def params_from_document(doc: Mapping[str, Any]) -> HeaterParams:
     a ``ValueError``. Parts and fields this code does not know are left
     out (``unknown_fields`` names them): the code reading the document
     runs no rule that could use them. A schema other than
-    ``PARAMS_SCHEMA`` is a ``ValueError``, and so is a ``doc`` that is
-    not an object.
+    ``PARAMS_SCHEMA`` is a ``ValueError``, and so are a ``doc`` that is
+    not an object and a value of the wrong type (a number where a list
+    goes, a string where a number goes).
     """
     if not isinstance(doc, Mapping):  # pyright: ignore[reportUnnecessaryIsInstance]
         raise ValueError("a parameters document is an object")
@@ -1216,10 +1256,14 @@ def params_from_document(doc: Mapping[str, Any]) -> HeaterParams:
         if not isinstance(given, Mapping):
             raise ValueError(f"part {name!r} is not an object")
         values = {}
+        hints = get_type_hints(cls)
         for f in fields(cls):
             if f.name in given:
+                _check(f"{name}.{f.name}", hints[f.name], given[f.name])
                 values[f.name] = given[f.name]
             elif f.default is MISSING and f.default_factory is MISSING:
                 raise ValueError(f"{name}.{f.name} is missing")
         parts[name] = cls(**values)
-    return HeaterParams(**parts, unfitted=tuple(doc.get("unfitted", ())))
+    unfitted = doc.get("unfitted", ())
+    _check("unfitted", tuple[str, ...], unfitted)
+    return HeaterParams(**parts, unfitted=tuple(unfitted))

{nwp500_python-9.10.0 → nwp500_python-9.11.0}/src/nwp500/sim_home_assistant.py

@@ -14,9 +14,9 @@ this module, a ``sim_live`` source:
   ``sim_live.compose()``:
 
   - **the air:** the outdoor forecast projected through a
-    ``location_air`` model, anchored to a fresh reading of the air
-    beside the heater; without a model, that reading held over the
-    span;
+    ``location_air`` model, given or fitted on the recent history,
+    anchored to a fresh reading of the air beside the heater; without
+    a weather entity or a model, that reading held over the span;
   - **the humidity:** a fresh reading;
   - **the inlet:** the plateau of the long draws in the last 72 h, from
     the inlet probe, the household's draws (a demand entity) and the
@@ -37,6 +37,7 @@ from the caller's configuration (``sources_from``).
 import enum
 import logging
 import math
+from bisect import bisect_right
 from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence
 from dataclasses import dataclass, field
 from datetime import UTC, datetime, timedelta
@@ -45,7 +46,12 @@ from typing import Any, cast
 from nwp500 import sim_adapters as sa
 from nwp500.exceptions import Nwp500Error
 from nwp500.sim import Environment
-from nwp500.sim.location_air import LocationAirModel
+from nwp500.sim.location_air import (
+    FIT_LAGS_H,
+    FittedLocationAir,
+    LocationAirModel,
+)
+from nwp500.sim.location_air import fit as fit_air
 from nwp500.sim.location_air import project as project_air
 
 __author__ = "Emmanuel Levijarvi"
@@ -67,6 +73,20 @@ PUMP_ON_RPM = 10.0
 PUMP_STALE = timedelta(seconds=300)
 #: How far back the inlet's plateau looks.
 INLET_LOOKBACK = timedelta(hours=72)
+#: The grid the inlet probe's history is read on (``held``): the
+#: plateau takes readings as samples, and a history keeps only changes.
+PROBE_STEP = timedelta(seconds=10)
+#: How far back the air beside the heater and the outdoor air are read
+#: to fit a ``location_air`` model where none is given.
+LOCATION_AIR_WINDOW = timedelta(days=3)
+#: The least span of readings such a fit is made on: a day, so it sees
+#: the outdoor air's daily swing.
+LOCATION_AIR_MIN_SPAN = timedelta(days=1)
+#: The least r (``FittedLocationAir.r``) such a fit is used at.
+LOCATION_AIR_MIN_R = 0.5
+#: The heater's own air reading is the air it stands in from this far
+#: into a compressor run (about 2.7 °F warm before), and not while idle.
+RUN_SETTLE = timedelta(minutes=2)
 #: How long a request waits, seconds.
 DEFAULT_TIMEOUT = 10.0
 
@@ -98,7 +118,8 @@ class Entities:
     demand: str | None = None
     #: The circulation pump's speed.
     circulation_speed: str | None = None
-    #: A weather entity with an hourly forecast.
+    #: A weather entity with an hourly forecast, its ``temperature``
+    #: attribute the outdoor air.
     weather: str | None = None
 
 
@@ -106,7 +127,8 @@ class Entities:
 class Sources:
     """Where the inputs are: Home Assistant's address and token, the
     entities, and the model that projects the air from the outdoor
-    forecast (None: hold a fresh reading)."""
+    forecast (None: one fitted from the recent history, as
+    ``HomeAssistantEnvironment`` fits it)."""
 
     url: str
     token: str = field(repr=False)
@@ -454,6 +476,45 @@ def parse_forecast(doc: Any, entity: str) -> tuple[list[Reading], str | None]:
     )
 
 
+def parse_outdoor_history(
+    doc: Any, entity: str
+) -> list[tuple[datetime, float, str | None]]:
+    """A weather entity's outdoor air from ``/api/history/period``'s
+    answer: each row's instant, ``temperature`` attribute and the unit
+    it was recorded in (``temperature_unit``, None where the row names
+    none), in time order. Rows without a number are left out."""
+    if not isinstance(doc, list):
+        raise HomeAssistantError("not a history")
+    out: list[tuple[datetime, float, str | None]] = []
+    for series in doc:
+        if not isinstance(series, list):
+            continue
+        for r in series:
+            if not isinstance(r, Mapping):
+                continue
+            row = cast(Mapping[str, Any], r)
+            if row.get("entity_id", entity) != entity:
+                break
+            stamp = row.get("last_updated") or row.get("last_changed")
+            attributes = row.get("attributes")
+            if stamp is None or not isinstance(attributes, Mapping):
+                continue
+            a = cast(Mapping[str, Any], attributes)
+            value = _number(a.get("temperature"))
+            if value is None:
+                continue
+            unit = a.get("temperature_unit")
+            out.append(
+                (
+                    _instant(stamp),
+                    value,
+                    unit if isinstance(unit, str) else None,
+                )
+            )
+    out.sort(key=lambda x: x[0])
+    return out
+
+
 def to_f(value: float, unit: str | None) -> float:
     """A temperature in ``unit`` (°F, °C or K), in °F."""
     u = (unit or "").strip().replace("º", "°")
@@ -490,6 +551,35 @@ def to_rpm(value: float, unit: str | None) -> float:
     raise ValueError(f"{unit!r} is not a rotational speed unit")
 
 
+def held(
+    readings: Sequence[Reading],
+    start: datetime,
+    end: datetime,
+    step: timedelta = PROBE_STEP,
+) -> list[Reading]:
+    """``readings``, a history of changes, as a probe sampled every
+    ``step`` from ``start`` to ``end`` would read them: the value in
+    force at each instant, none before the first reading. A history
+    writes no row for a report of the value it already holds, so a
+    probe steady over a span has one reading there, or none. The grid
+    is in UTC, every ``step`` of elapsed time across a clock change."""
+    if step <= timedelta(0):
+        raise ValueError("step must be positive")
+    # In UTC: two local times in one zone compare, and step, by the wall
+    # clock, which skips or repeats an hour at a daylight-saving change.
+    rows = sorted((t.astimezone(UTC), v) for t, v in readings)
+    out: list[Reading] = []
+    i = -1
+    t, end = start.astimezone(UTC), end.astimezone(UTC)
+    while t <= end:
+        while i + 1 < len(rows) and rows[i + 1][0] <= t:
+            i += 1
+        if i >= 0:
+            out.append((t, rows[i][1]))
+        t += step
+    return out
+
+
 def busy(*spans: Sequence[Span]) -> list[Span]:
     """``spans`` together, overlapping ones joined, in time order, in
     UTC."""
@@ -756,6 +846,36 @@ class HomeAssistantClient:
             unit = (await self._attributes(entity)).get("temperature_unit")
         return hours, unit if isinstance(unit, str) else None
 
+    async def outdoor_history(
+        self, entity: str, start: datetime, end: datetime
+    ) -> list[Reading]:
+        """A weather entity's outdoor air from ``start`` to ``end``, °F,
+        each reading from the unit it was recorded in
+        (``parse_outdoor_history``), the entity's own unit where a row
+        names none. A reading in no unit ``to_f`` reads is left out."""
+        doc = await self._json(
+            "GET",
+            f"/api/history/period/{start.astimezone(UTC).isoformat()}",
+            params={
+                "filter_entity_id": entity,
+                "end_time": end.astimezone(UTC).isoformat(),
+                # Every row, with its attributes: the temperature is one.
+                "significant_changes_only": "0",
+            },
+        )
+        rows = parse_outdoor_history(doc, entity)
+        today: str | None = None
+        if any(u is None for _, _, u in rows):
+            u = (await self._attributes(entity)).get("temperature_unit")
+            today = u if isinstance(u, str) else None
+        out: list[Reading] = []
+        for t, v, u in rows:
+            try:
+                out.append((t, to_f(v, u or today)))
+            except ValueError:
+                continue
+        return out
+
     async def _attributes(self, entity: str) -> Mapping[str, Any]:
         doc = await self._json("GET", f"/api/states/{entity}")
         attributes = doc.get("attributes") if isinstance(doc, dict) else None
@@ -769,11 +889,61 @@ class HomeAssistantClient:
 # ── the environment source ──────────────────────────────────────────
 
 
+def _while_running(
+    air: Sequence[Reading],
+    compressor: Sequence[tuple[datetime, str]],
+    end: datetime,
+    unknown: Sequence[Span] = (),
+    step: timedelta = timedelta(minutes=10),
+) -> tuple[list[Reading], Reading | None]:
+    """``air``'s value in force every ``step`` through each of
+    ``compressor``'s runs (its ``on`` states) to its end, or ``end`` for
+    one still running, where that value was read ``RUN_SETTLE`` or more
+    into the run: one read earlier, or while idle, is not the air the
+    heater stands in. None inside ``unknown``, when the sensor said
+    nothing that was read. The second item is the newest reading those
+    samples rest on, at its own instant."""
+    # A row that repeats the state (an attribute's update) is not a new
+    # run; a change to anything else, ``unavailable`` included, ends one.
+    changes: list[tuple[datetime, str]] = []
+    for at, state in compressor:
+        text = state.strip().lower()
+        if not changes or changes[-1][1] != text:
+            changes.append((at, text))
+    times = [t for t, _ in air]
+    out: list[Reading] = []
+    newest: Reading | None = None
+    for i, (on_at, state) in enumerate(changes):
+        if state != "on":
+            continue
+        stop = changes[i + 1][0] if i + 1 < len(changes) else end
+        settled = on_at + RUN_SETTLE
+        t = settled
+        while t < stop:
+            k = bisect_right(times, t)
+            if (
+                k
+                and times[k - 1] >= settled
+                and not any(a <= t < b for a, b in unknown)
+            ):
+                out.append((t, air[k - 1][1]))
+                if newest is None or air[k - 1][0] > newest[0]:
+                    newest = air[k - 1]
+            t += step
+    return out, newest
+
+
 class HomeAssistantEnvironment:
     """An ``EnvironmentSource``: the air, its humidity and the inlet from
     Home Assistant, over ``start`` to ``until``, as of ``now`` (the
     driver's clock). ``notes`` say what each part rests on, or why it
-    was left to the default, once ``read`` has run."""
+    was left to the default, once ``read`` has run.
+
+    With a weather entity and no ``location_air`` model, ``read`` fits
+    one (``fitted_air``) on the last ``LOCATION_AIR_WINDOW``: the air
+    entity's readings, or without one the heater's own air reading
+    while its compressor runs (``heater``'s ``ambient`` and
+    ``compressor``), against the weather entity's outdoor air."""
 
     def __init__(
         self,
@@ -784,6 +954,7 @@ class HomeAssistantEnvironment:
         until: datetime,
         now: datetime | None = None,
         location_air: LocationAirModel | None = None,
+        heater: HeaterEntities | None = None,
     ) -> None:
         self.client = client
         self.entities = entities
@@ -791,7 +962,13 @@ class HomeAssistantEnvironment:
         self.until = until
         self.now = start if now is None else now
         self.location_air = location_air
+        self.heater = heater
         self.notes: list[str] = []
+        #: The model fitted where none was given, once ``read`` has run;
+        #: None when it was given, or none could be fitted.
+        self.fitted_air: FittedLocationAir | None = None
+        self._fit_notes: list[str] | None = None
+        self._heater_anchor: Reading | None = None
 
     async def read(self) -> Environment:
         """The environment; a part that cannot be read is left to the
@@ -839,15 +1016,23 @@ class HomeAssistantEnvironment:
     async def _air(self) -> float | tuple[Reading, ...]:
         e = self.entities
         weather = e.weather
-        anchor: Reading | None = None
+        held: Reading | None = None
         if e.air is not None:
             state = await self._fresh_state("air", e.air)
             if state is not None and state.value is not None:
                 try:
-                    anchor = (state.at, to_f(state.value, state.unit))
+                    held = (state.at, to_f(state.value, state.unit))
                 except ValueError as err:
                     self.notes.append(f"air: {err}")
-        if weather is not None and self.location_air is not None:
+        model = self.location_air
+        anchor = held
+        if weather is not None and model is None:
+            fitted = await self._fit_air(weather)
+            if fitted is not None:
+                model = fitted.model
+                if anchor is None:
+                    anchor = self._heater_anchor
+        if weather is not None and model is not None:
             hours = await self._guard(
                 "outdoor forecast",
                 lambda: self.client.forecast(weather),
@@ -861,7 +1046,7 @@ class HomeAssistantEnvironment:
                     outdoor = []
                     self.notes.append(f"outdoor forecast: {err}")
                 air = project_air(
-                    self.location_air,
+                    model,
                     outdoor,
                     self.start,
                     self.until,
@@ -871,17 +1056,140 @@ class HomeAssistantEnvironment:
                     self.notes.append(
                         "air: projected from the outdoor forecast, "
                         + (
-                            "anchored to the reading beside the heater"
-                            if anchor
-                            else "unanchored"
+                            "unanchored"
+                            if anchor is None
+                            else "anchored to the reading beside the heater"
+                            if anchor is held
+                            else "anchored to the heater's own reading"
                         )
                     )
                     return air
-        if anchor is not None:
+        if held is not None:
             self.notes.append("air: the reading beside the heater, held")
-            return anchor[1]
+            return held[1]
         return math.nan
 
+    async def _fit_air(self, weather: str) -> FittedLocationAir | None:
+        """The ``location_air`` model fitted on the last
+        ``LOCATION_AIR_WINDOW``, or None (and a note): too little
+        history, or a poor fit. Fitted once; a later ``read`` reuses it."""
+        if self._fit_notes is None:
+            before = len(self.notes)
+            fitted = await self._guard(
+                "air", lambda: self._fit_air_now(weather), None
+            )
+            self.fitted_air = cast("FittedLocationAir | None", fitted)
+            self._fit_notes = self.notes[before:]
+        else:
+            self.notes.extend(self._fit_notes)
+        return self.fitted_air
+
+    async def _fit_air_now(self, weather: str) -> FittedLocationAir | None:
+        now = self.now.astimezone(UTC)
+        since = now - LOCATION_AIR_WINDOW
+        air = await self._air_history(since, now)
+        if air is None:
+            return None
+        readings, what = air
+        if not readings:
+            self.notes.append(f"air: no readings of {what} to fit to")
+            return None
+        if not self._spans_a_day(readings, what, ""):
+            return None
+        lag = timedelta(hours=max(FIT_LAGS_H))
+        # From before the first reading by the longest lag a fit tries.
+        outdoor = await self.client.outdoor_history(weather, since - lag, now)
+        if not outdoor:
+            self.notes.append(f"air: no outdoor air recorded for {weather}")
+            return None
+        # Only readings the outdoor history covers at every lag tried:
+        # past its ends, the model holds the outdoor air flat.
+        first, last = outdoor[0][0] + lag, outdoor[-1][0]
+        readings = [(t, v) for t, v in readings if first <= t <= last]
+        if not readings or not self._spans_a_day(
+            readings, what, " that the outdoor history covers"
+        ):
+            if not readings:
+                self.notes.append(
+                    f"air: no readings of {what} that the outdoor history "
+                    "covers"
+                )
+            return None
+        if len({v for _, v in readings}) < 2:
+            self.notes.append(
+                f"air: {what} held one value, so nothing to fit to"
+            )
+            return None
+        fitted = fit_air(readings, outdoor)
+        days = LOCATION_AIR_WINDOW.total_seconds() / 86400
+        # A steady air has no r (NaN): no fit either.
+        if not fitted.r >= LOCATION_AIR_MIN_R:
+            self.notes.append(
+                f"air: {what} follows the outdoor air too loosely to "
+                f"project it (r {fitted.r:.2f}, under {LOCATION_AIR_MIN_R})"
+            )
+            return None
+        self.notes.append(
+            f"air: the outdoor air fitted to {what} over the last {days:g} "
+            f"days (r {fitted.r:.2f}, "
+            f"{fitted.model.lag.total_seconds() / 3600:g} h late)"
+        )
+        return fitted
+
+    def _spans_a_day(
+        self, readings: Sequence[Reading], what: str, covered: str
+    ) -> bool:
+        """Whether ``readings`` span ``LOCATION_AIR_MIN_SPAN``; a note
+        when they don't."""
+        span = readings[-1][0] - readings[0][0]
+        if span >= LOCATION_AIR_MIN_SPAN:
+            return True
+        self.notes.append(
+            f"air: {span.total_seconds() / 3600:.0f} h of {what}{covered}, "
+            f"under the {LOCATION_AIR_MIN_SPAN.total_seconds() / 3600:g} h "
+            "a fit needs"
+        )
+        return False
+
+    async def _air_history(
+        self, since: datetime, now: datetime
+    ) -> tuple[list[Reading], str] | None:
+        """The air where the heater stands since ``since``, °F, and what
+        it was read from: the air entity, or the heater's own reading
+        every 10 minutes while its compressor runs, from ``RUN_SETTLE``
+        into each run. None (and a note) when neither is recorded."""
+        e, h = self.entities, self.heater
+        if e.air is not None:
+            got = await self.client.read_history([e.air], since, now)
+            unit = (await self.client.state(e.air)).unit
+            readings, _ = got.converted(e.air, unit, to_f, now)
+            return readings, "the air beside the heater"
+        if h is None or h.ambient is None or h.compressor is None:
+            self.notes.append(
+                "air: no air reading to fit the outdoor air to (an air "
+                "entity, or the heater's own air and compressor)"
+            )
+            return None
+        got = await self.client.read_history(
+            [h.ambient, h.compressor], since, now
+        )
+        if got.states is None:
+            self.notes.append(
+                f"air: {h.compressor} not read (no states in the history)"
+            )
+            return None
+        unit = (await self.client.state(h.ambient)).unit
+        ambient, unread = got.converted(h.ambient, unit, to_f, now)
+        samples, newest = _while_running(
+            ambient,
+            got.states.get(h.compressor, []),
+            now,
+            busy(unread, got.outages.get(h.ambient, [])),
+        )
+        if newest is not None and now - newest[0] <= FRESH:
+            self._heater_anchor = newest
+        return samples, "the heater's own air reading"
+
     async def _humidity(self) -> float | None:
         e = self.entities
         if e.humidity is None:
@@ -942,7 +1250,7 @@ class HomeAssistantEnvironment:
             )
             # In °F, as read: no unit preference is read here.
             cold = sa.cold_supply_f(
-                probe,
+                held(probe, since, now),
                 at=now,
                 draws=draws,
                 circulation=busy_spans,

{nwp500_python-9.10.0 → nwp500_python-9.11.0/src/nwp500_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.10.0
+Version: 9.11.0
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi

nwp500_python-9.11.0/src/nwp500_python.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "9.11.0",
+  "distance": 0,
+  "node": "gd8e04f71c9b36d7150efab7eeb2251178c8a8d56",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-23"
+}