nwp500-python 9.12.0__py3-none-any.whl → 9.12.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. nwp500/api_client.py +39 -43
  2. nwp500/auth.py +9 -9
  3. nwp500/ble/client.py +5 -5
  4. nwp500/ble/protocol.py +55 -68
  5. nwp500/cli/__main__.py +20 -8
  6. nwp500/cli/calibration.py +2 -2
  7. nwp500/cli/presentation.py +4 -4
  8. nwp500/cli/simulate.py +125 -7
  9. nwp500/converters.py +10 -12
  10. nwp500/encoding.py +1 -1
  11. nwp500/enums.py +21 -27
  12. nwp500/models/account.py +3 -3
  13. nwp500/models/device.py +20 -25
  14. nwp500/models/diagnostics.py +8 -9
  15. nwp500/models/energy.py +6 -6
  16. nwp500/models/feature.py +4 -8
  17. nwp500/models/maintenance.py +5 -6
  18. nwp500/models/mqtt_models.py +16 -19
  19. nwp500/models/schedule.py +10 -14
  20. nwp500/models/status.py +12 -19
  21. nwp500/models/tou.py +1 -2
  22. nwp500/mqtt/_control_commands.py +2 -2
  23. nwp500/mqtt/_device_subscriptions.py +1 -1
  24. nwp500/mqtt/client.py +12 -15
  25. nwp500/mqtt/control.py +36 -48
  26. nwp500/mqtt/subscriptions.py +3 -3
  27. nwp500/mqtt/types.py +1 -1
  28. nwp500/mqtt/utils.py +7 -11
  29. nwp500/sim/api.py +31 -50
  30. nwp500/sim/attribution.py +5 -2
  31. nwp500/sim/book.py +322 -454
  32. nwp500/sim/calibration.py +328 -653
  33. nwp500/sim/circulation.py +50 -15
  34. nwp500/sim/cold_supply.py +3 -4
  35. nwp500/sim/controller.py +140 -59
  36. nwp500/sim/decay.py +72 -101
  37. nwp500/sim/defaults.py +50 -36
  38. nwp500/sim/delivery.py +74 -164
  39. nwp500/sim/draw_forecast.py +11 -3
  40. nwp500/sim/engine.py +118 -472
  41. nwp500/sim/extensions.py +13 -38
  42. nwp500/sim/heat_pump_recovery.py +3 -1
  43. nwp500/sim/heating_trajectory.py +3 -1
  44. nwp500/sim/inputs.py +3 -2
  45. nwp500/sim/params.py +184 -118
  46. nwp500/sim/physics/compressor.py +42 -17
  47. nwp500/sim/physics/draw.py +171 -139
  48. nwp500/sim/physics/refrigerant.py +43 -34
  49. nwp500/sim/physics/tank.py +2 -2
  50. nwp500/sim/ready.py +35 -89
  51. nwp500/sim/tank_physics.py +9 -12
  52. nwp500/sim/tou_triggers.py +116 -15
  53. nwp500/sim_adapters.py +86 -25
  54. nwp500/sim_calibrate.py +64 -93
  55. nwp500/sim_home_assistant.py +67 -21
  56. nwp500/temperature.py +2 -2
  57. nwp500/topic_builder.py +4 -5
  58. {nwp500_python-9.12.0.dist-info → nwp500_python-9.12.2.dist-info}/METADATA +6 -17
  59. nwp500_python-9.12.2.dist-info/RECORD +114 -0
  60. nwp500_python-9.12.0.dist-info/RECORD +0 -114
  61. {nwp500_python-9.12.0.dist-info → nwp500_python-9.12.2.dist-info}/WHEEL +0 -0
  62. {nwp500_python-9.12.0.dist-info → nwp500_python-9.12.2.dist-info}/entry_points.txt +0 -0
  63. {nwp500_python-9.12.0.dist-info → nwp500_python-9.12.2.dist-info}/licenses/LICENSE.txt +0 -0
  64. {nwp500_python-9.12.0.dist-info → nwp500_python-9.12.2.dist-info}/top_level.txt +0 -0
nwp500/api_client.py CHANGED
@@ -125,8 +125,8 @@ class NavienAPIClient:
125
125
  """The signed-in user's type, defaulting to owner (``"O"``).
126
126
 
127
127
  The sign-in response carries ``userInfo.userType`` (``"O"`` owner,
128
- ``"M"`` member, or an installer type) and the NaviLink app sends
129
- that value on the TOU endpoints. It is empty when the auth client
128
+ ``"M"`` member, or an installer type), and the TOU endpoints take
129
+ that value. It is empty when the auth client
130
130
  restored a session without a sign-in response.
131
131
  """
132
132
  user = self._auth_client.current_user
@@ -398,7 +398,7 @@ class NavienAPIClient:
398
398
  additional_value: Additional device identifier
399
399
  controller_id: Controller serial number from the device feature
400
400
  user_type: User type; defaults to the signed-in user's type
401
- (``"O"`` when unknown), as the NaviLink app sends
401
+ (``"O"`` when unknown)
402
402
 
403
403
  Returns:
404
404
  TOUInfo object
@@ -593,15 +593,14 @@ class NavienAPIClient:
593
593
  """
594
594
  Remove the TOU rate plan from a device.
595
595
 
596
- Sends ``DELETE /device/tou``. The NaviLink app serialises the same
597
- ``TouRequest`` it uses for ``PUT`` and appends it to the URL as a
598
- query string (a DELETE carries no body), so this method passes the
599
- fields as query parameters.
596
+ Sends ``DELETE /device/tou``. The cloud takes the same fields as
597
+ the ``PUT`` request, as a query string (a DELETE carries no body),
598
+ so this method passes them as query parameters.
600
599
 
601
- The app identifies the device by ``controllerId`` when the plan was
602
- registered over Bluetooth (``registerPath == "bt"``) and by
603
- ``macAddress``/``additionalValue`` otherwise; both are sent here
604
- when ``controller_id`` is given.
600
+ A plan registered over Bluetooth (``registerPath == "bt"``) is
601
+ identified by ``controllerId``, any other plan by
602
+ ``macAddress``/``additionalValue``; both are sent here when
603
+ ``controller_id`` is given.
605
604
 
606
605
  Args:
607
606
  mac_address: Device MAC address
@@ -645,8 +644,8 @@ class NavienAPIClient:
645
644
  """
646
645
  Look up the manufacture ID the TOU service knows for a device.
647
646
 
648
- Sends ``GET /device/tou/manufacture-id``. The NaviLink app treats
649
- ``"000000000000000"`` as "not available".
647
+ Sends ``GET /device/tou/manufacture-id``.
648
+ ``"000000000000000"`` means "not available".
650
649
 
651
650
  ``controller_id`` is the controller serial number reported in the
652
651
  device feature (``DeviceFeature.controller_serial_number``), the
@@ -736,10 +735,10 @@ class NavienAPIClient:
736
735
  Enable or disable push notifications for a device.
737
736
 
738
737
  Sends ``POST /user/set-push-settings``. Flags are encoded 1 (on)
739
- or 2 (off). The app always sends every flag the account has, so a
738
+ or 2 (off). The request carries every flag the account has, so a
740
739
  flag left ``None`` keeps its current value, read first with
741
740
  :meth:`get_push_settings`; one the cloud does not report (a member
742
- account's descaling flag) is omitted, as the app omits it.
741
+ account's descaling flag) is omitted.
743
742
 
744
743
  Args:
745
744
  mac_address: Device MAC address
@@ -826,7 +825,7 @@ class NavienAPIClient:
826
825
  Record the date the air filter was replaced.
827
826
 
828
827
  Sends ``POST /device/filter/change-info``. The date is formatted
829
- ``YYYY-M-D`` without zero padding, as the NaviLink app sends it.
828
+ ``YYYY-M-D`` without zero padding.
830
829
  This only updates the cloud's maintenance log; to reset the
831
830
  device's own filter timer use
832
831
  :meth:`nwp500.NavienMqttClient.reset_air_filter`.
@@ -982,12 +981,12 @@ class NavienAPIClient:
982
981
  Read the unit display preferences stored for a device.
983
982
 
984
983
  Sends ``GET /device/preferences/format``. The cloud answers with
985
- a list; the NaviLink app uses the first entry.
984
+ a list; the first entry is the one in use.
986
985
 
987
986
  Not accepted for the NWP500: the cloud answers
988
987
  ``400 COMMON_BAD_REQUEST`` for device type 52 whatever the
989
- parameters (checked live). The app only calls it for the
990
- IoT-module hydro unit (device type 8).
988
+ parameters (checked live). The endpoint is for the IoT-module
989
+ hydro unit (device type 8).
991
990
 
992
991
  Args:
993
992
  mac_address: Device MAC address
@@ -1033,14 +1032,13 @@ class NavienAPIClient:
1033
1032
  """
1034
1033
  Store the unit display preferences for a device.
1035
1034
 
1036
- Sends ``POST /device/preferences/format``. The NaviLink app writes
1037
- ``"F"``/``"C"`` for temperature and ``"P"`` (psi)/``"M"`` (metric)
1038
- for pressure.
1035
+ Sends ``POST /device/preferences/format``. Temperature is
1036
+ ``"F"``/``"C"`` and pressure ``"P"`` (psi)/``"M"`` (metric).
1039
1037
 
1040
1038
  Not accepted for the NWP500: the cloud answers
1041
1039
  ``400 COMMON_BAD_REQUEST`` for device type 52 whatever the
1042
- parameters (checked live). The app only calls it for the
1043
- IoT-module hydro unit (device type 8).
1040
+ parameters (checked live). The endpoint is for the IoT-module
1041
+ hydro unit (device type 8).
1044
1042
 
1045
1043
  Args:
1046
1044
  mac_address: Device MAC address
@@ -1108,9 +1106,9 @@ class NavienAPIClient:
1108
1106
  """
1109
1107
  Describe a firmware image by its code and version.
1110
1108
 
1111
- Sends ``POST /firmware/info``. The NaviLink app passes
1112
- ``cur_sw_code`` with ``downloaded_version`` (when one is pending and
1113
- differs from the current one) or ``cur_version`` from
1109
+ Sends ``POST /firmware/info``. Pass ``cur_sw_code`` with
1110
+ ``downloaded_version`` (when one is pending and differs from the
1111
+ current one) or ``cur_version`` from
1114
1112
  :class:`~nwp500.models.FirmwareInfo`.
1115
1113
 
1116
1114
  Args:
@@ -1148,9 +1146,9 @@ class NavienAPIClient:
1148
1146
  """
1149
1147
  List the faults the cloud has recorded for a device.
1150
1148
 
1151
- Sends ``POST /device/error/list``. The NaviLink app calls this from
1152
- its installer-only error list and sends the signed-in user's ID as
1153
- ``installerId``. An owner account is rejected with
1149
+ Sends ``POST /device/error/list``. This is an installer-level
1150
+ call, with the signed-in user's ID sent as ``installerId``. An
1151
+ owner account is rejected with
1154
1152
  ``404 COMMON_NOT_AUTHORIZED`` (checked live), so this only works
1155
1153
  when signed in as the device's installer. Pass ``continuous_key``
1156
1154
  (the last entry's ``error_occurred_time``) to fetch the next page.
@@ -1210,8 +1208,8 @@ class NavienAPIClient:
1210
1208
  """
1211
1209
  Rename a device or update its installation details.
1212
1210
 
1213
- Sends ``POST /device/change-info``. Following the NaviLink app,
1214
- ``installType`` is omitted when empty, the ``location`` object is
1211
+ Sends ``POST /device/change-info``. ``installType`` is omitted
1212
+ when empty, the ``location`` object is
1215
1213
  omitted when it has no state, city or address, and within it empty
1216
1214
  strings and zero coordinates are left out.
1217
1215
 
@@ -1244,7 +1242,7 @@ class NavienAPIClient:
1244
1242
  body: dict[str, Any] = {"userId": user_email, "deviceInfo": device_info}
1245
1243
 
1246
1244
  if location and (location.state or location.city or location.address):
1247
- # The app drops empty strings and 0.0 coordinates.
1245
+ # Empty strings and 0.0 coordinates are left out.
1248
1246
  body["location"] = {
1249
1247
  key: value
1250
1248
  for key, value in (
@@ -1272,9 +1270,8 @@ class NavienAPIClient:
1272
1270
  """
1273
1271
  List devices in the trimmed ``/device/simple-list`` form.
1274
1272
 
1275
- The NaviLink app uses this for its product-management list (with
1276
- ``targetUserId`` equal to the signed-in user) and for an installer
1277
- viewing an owner's devices (``targetUserId`` = the owner).
1273
+ ``targetUserId`` is the signed-in user for their own devices, or
1274
+ the owner when an installer lists an owner's devices.
1278
1275
 
1279
1276
  Args:
1280
1277
  target_user_id: Whose devices to list (default: the signed-in
@@ -1314,14 +1311,14 @@ class NavienAPIClient:
1314
1311
 
1315
1312
  async def get_app_version(self, os: str = "A") -> AppVersionInfo:
1316
1313
  """
1317
- Query the NaviLink app versions the cloud expects.
1314
+ Query the client versions the cloud expects.
1318
1315
 
1319
1316
  Sends ``POST /app/version`` without authentication, on this
1320
1317
  client's session. Before sign-in, use the module-level
1321
1318
  :func:`get_app_version`, which needs no client.
1322
1319
 
1323
1320
  Args:
1324
- os: Platform code; the app sends ``"A"`` (Android)
1321
+ os: Platform code, ``"A"`` for Android
1325
1322
 
1326
1323
  Returns:
1327
1324
  AppVersionInfo object
@@ -1370,16 +1367,15 @@ async def get_app_version(
1370
1367
  base_url: str = API_BASE_URL,
1371
1368
  ) -> AppVersionInfo:
1372
1369
  """
1373
- Query the NaviLink app versions the cloud expects, before sign-in.
1370
+ Query the client versions the cloud expects, before sign-in.
1374
1371
 
1375
- Sends ``POST /app/version`` without authentication, as the app does on
1376
- its splash screen. A 403 whose data carries ``serverCheckText`` is a
1377
- maintenance notice and is returned as an
1372
+ Sends ``POST /app/version`` without authentication. A 403 whose data
1373
+ carries ``serverCheckText`` is a maintenance notice and is returned as an
1378
1374
  :class:`~nwp500.models.AppVersionInfo` with ``server_check_text`` set;
1379
1375
  any other failure raises.
1380
1376
 
1381
1377
  Args:
1382
- os: Platform code; the app sends ``"A"`` (Android)
1378
+ os: Platform code, ``"A"`` for Android
1383
1379
  session: Session to send on; a temporary one is opened if omitted
1384
1380
  base_url: Base URL for the API
1385
1381
 
nwp500/auth.py CHANGED
@@ -677,8 +677,8 @@ class NavienAuthClient:
677
677
  Posts the current access token to ``/auth/session/refresh``. The
678
678
  response carries only the AWS credential fields (``accessKeyId``,
679
679
  ``secretKey``, ``sessionToken``, ``authorizationExpiresIn``); any
680
- field the server omits keeps its stored value, as the NaviLink app
681
- does. The JWT tokens are untouched.
680
+ field the server omits keeps its stored value. The JWT tokens are
681
+ untouched.
682
682
 
683
683
  Serialized with ``refresh_token()`` on the same lock so concurrent
684
684
  callers cannot stampede the endpoint.
@@ -712,8 +712,8 @@ class NavienAuthClient:
712
712
  ) -> tuple[AuthTokens, set[str]]:
713
713
  """Overlay the token fields the server sent onto ``current``.
714
714
 
715
- Only keys present and non-empty in ``data`` are overwritten, as
716
- the app does. A renewed access token re-stamps ``issued_at``;
715
+ Only keys present and non-empty in ``data`` are overwritten. A
716
+ renewed access token re-stamps ``issued_at``;
717
717
  renewed AWS credentials re-stamp ``aws_credentials_issued_at``
718
718
  without touching the JWT's expiry. A renewed access token without
719
719
  AWS credentials pins the kept credentials' issue time, so their
@@ -777,7 +777,7 @@ class NavienAuthClient:
777
777
  if not isinstance(data, dict):
778
778
  raise ValueError("'data' is not an object")
779
779
 
780
- # Overwrite only the keys the server sent (mirrors the app).
780
+ # Overwrite only the keys the server sent.
781
781
  new_tokens, updated = self._merge_token_fields(current, data)
782
782
  if not updated & self._AWS_KEYS:
783
783
  raise TokenRefreshError(
@@ -811,8 +811,8 @@ class NavienAuthClient:
811
811
  The response carries user info, legal notices and a ``token``
812
812
  object. Only the token fields the server sends are overwritten;
813
813
  in practice that is the AWS credentials, so the current JWT access
814
- and refresh tokens are kept. The app uses this on auto-login and
815
- falls back to the password only if it fails.
814
+ and refresh tokens are kept. Use this on auto-login and fall back
815
+ to the password only if it fails.
816
816
 
817
817
  Serialized with ``refresh_token()`` and ``refresh_session()`` by the
818
818
  refresh lock, so an in-flight refresh cannot merge stale tokens over
@@ -1131,8 +1131,8 @@ class NavienAuthClient:
1131
1131
  def default_headers() -> dict[str, str]:
1132
1132
  """Headers sent on every request, authenticated or not.
1133
1133
 
1134
- The NaviLink app sends its User-Agent on sign-in and refresh calls
1135
- too, so the library identifies itself on those as well.
1134
+ The library identifies itself with its User-Agent on every call,
1135
+ sign-in and refresh included.
1136
1136
  """
1137
1137
  return {
1138
1138
  "User-Agent": f"nwp500-python/{__version__}",
nwp500/ble/client.py CHANGED
@@ -345,8 +345,8 @@ class NavienBleClient:
345
345
  async def read_sub_status(self) -> SubStatus:
346
346
  """Read and decode the ``SSD`` block: two DIP-switch settings.
347
347
 
348
- The layout is from Navien's boiler service toolkit and is
349
- unconfirmed on the NWP500; see :class:`SubStatus`.
348
+ The layout is the boilers' and is unconfirmed on the NWP500; see
349
+ :class:`SubStatus`.
350
350
 
351
351
  Raises:
352
352
  CrcMismatchError: The reply failed its checksum.
@@ -446,7 +446,7 @@ class NavienBleClient:
446
446
  async def read_parameter_blocks(self) -> dict[ClassCode, bytes]:
447
447
  """Read the four boiler parameter blocks (classes 51-54).
448
448
 
449
- These are the blocks Navien's service app reads on boilers. An
449
+ These blocks carry the installer parameters on boilers. An
450
450
  NWP500 did not answer them (see
451
451
  :data:`~nwp500.ble.NWP500_RESPONDING_CLASSES`), so on the heat
452
452
  pump expect a :class:`TimeoutError`; the classes it does answer
@@ -518,8 +518,8 @@ class NavienBleClient:
518
518
  ) -> Packet:
519
519
  """EXPERIMENTAL: write a whole block and return the device's reply.
520
520
 
521
- The service app writes installer parameters as a full class-54
522
- block. Only send bytes read from the same class with a deliberate
521
+ Installer parameters are written as a full class-54 block. Only
522
+ send bytes read from the same class with a deliberate
523
523
  change; an unknown layout written blindly can misconfigure the
524
524
  heater.
525
525
  """
nwp500/ble/protocol.py CHANGED
@@ -1,19 +1,18 @@
1
1
  """Framing for the NWP500's Bluetooth LE service.
2
2
 
3
- The water heater exposes a GATT service that carries the controller's
4
- native class-code protocol: one request packet is written to the write
5
- characteristic and one reply packet arrives as a notification. The framing
6
- below mirrors what the NaviLink app sends to the heater in Bluetooth
7
- pairing mode (with the heater off, hold Back and Power for five seconds; it
8
- then advertises as ``HPWH1…``). In its Wi-Fi setup mode the heater
9
- advertises as ``HPWH4610`` instead, and accepts a connection but answers
10
- nothing.
3
+ The water heater exposes a GATT service that carries the controller's native
4
+ class-code protocol: one request packet is written to the write
5
+ characteristic and one reply packet arrives as a notification. The heater
6
+ answers the framing below in Bluetooth pairing mode (with the heater off,
7
+ hold Back and Power for five seconds; it then advertises as ``HPWH1…``). In
8
+ its Wi-Fi setup mode the heater advertises as ``HPWH4610`` instead, and
9
+ accepts a connection but answers nothing.
11
10
 
12
11
  Packet layout (all single bytes unless noted)::
13
12
 
14
13
  header 0xF7
15
14
  system 0x20
16
- source 0x01 (the app)
15
+ source 0x01 (the client)
17
16
  dest 0x03 (the controller)
18
17
  command 3 = read, 16 = write; replies are 131 and 144
19
18
  length payload length + 2 (+5 for the firmware classes 210/211,
@@ -67,9 +66,9 @@ class Command(IntEnum):
67
66
  class ClassCode(IntEnum):
68
67
  """Data classes the controller serves over Bluetooth.
69
68
 
70
- Names are the app's abbreviations. The parameter blocks 51-54 are what
71
- the Navien service app reads before showing installer parameters and
72
- writes back (class 54) after a change.
69
+ Names are the protocol's abbreviations. The parameter blocks 51-54
70
+ carry installer parameters: they are read before a change and class
71
+ 54 is written back after it.
73
72
  """
74
73
 
75
74
  SSD = 17 # status data
@@ -95,10 +94,10 @@ class ClassCode(IntEnum):
95
94
  MSWD = 244
96
95
 
97
96
 
98
- #: Expected reply length sent with each read request. The first six are
99
- #: what the apps send; the rest were confirmed to answer on an NWP500
100
- #: (the device returns its real block size regardless, e.g. 192 bytes for
101
- #: ``TOU_PLAN``).
97
+ #: Expected reply length sent with each read request. The first six are the
98
+ #: protocol's lengths for those classes; the rest were confirmed to answer
99
+ #: on an NWP500 (the device returns its real block size regardless, e.g. 192
100
+ #: bytes for ``TOU_PLAN``).
102
101
  DEFAULT_READ_LENGTHS: dict[int, int] = {
103
102
  ClassCode.DID: 58,
104
103
  ClassCode.MSCD: 40,
@@ -137,9 +136,9 @@ NWP500_WRITABLE_CLASSES: frozenset[int] = frozenset({ClassCode.TOU_PLAN})
137
136
  #: Bytes in a ``SAPCD`` (class 50) session command.
138
137
  SESSION_COMMAND_LENGTH = 30
139
138
 
140
- #: The session command that starts the ``RTMD`` status stream. Navien's
141
- #: service apps send it on connecting; on an NWP500 the heater then pushes
142
- #: an ``RTMD`` block about every 300 ms until the connection closes.
139
+ #: The session command that starts the ``RTMD`` status stream. On an NWP500
140
+ #: the heater then pushes an ``RTMD`` block about every 300 ms until the
141
+ #: connection closes.
143
142
  START_STATUS_STREAM = 200
144
143
 
145
144
 
@@ -148,10 +147,7 @@ class CrcMismatchError(ValueError):
148
147
 
149
148
 
150
149
  def crc16(data: bytes) -> int:
151
- """CRC-16/MODBUS: reflected polynomial 0xA001, initial value 0xFFFF.
152
-
153
- Identical to the table-driven ``CRC16Checker`` in the NaviLink app.
154
- """
150
+ """CRC-16/MODBUS: reflected polynomial 0xA001, initial value 0xFFFF."""
155
151
  crc = 0xFFFF
156
152
  for byte in data:
157
153
  crc ^= byte
@@ -169,8 +165,8 @@ def build_packet(
169
165
  command: :attr:`Command.READ` or :attr:`Command.WRITE`.
170
166
  class_code: Data class (:class:`ClassCode` or raw int).
171
167
  payload: Request data. For a read, one byte: the expected length.
172
- address: Block address; 0 for every class the apps use except the
173
- firmware classes, which take a byte offset.
168
+ address: Block address; 0 for every class except the firmware
169
+ classes, which take a byte offset.
174
170
  """
175
171
  wide = class_code in _WIDE_ADDRESS_CLASSES
176
172
  length = len(payload) + (5 if wide else 2)
@@ -201,21 +197,17 @@ def build_packet(
201
197
  def build_session_command(code: int) -> bytes:
202
198
  """Frame a ``SAPCD`` (class 50) session command.
203
199
 
204
- The command is a write of a 30-byte block whose first byte is
205
- ``code`` and whose other bytes are zero, as Navien's service apps
206
- send it. The heater sends no reply to it. On an NWP500 (2026-10-19,
207
- 2026-10-20):
200
+ The command is a write of a 30-byte block whose first byte is ``code``
201
+ and whose other bytes are zero. The heater sends no reply to it. On an
202
+ NWP500 (2026-10-19, 2026-10-20):
208
203
 
209
204
  * 200 (:data:`START_STATUS_STREAM`) starts the ``RTMD`` stream, a
210
205
  block about every 300 ms.
211
- * 202, the service app's Stop on its monitoring graph, starts the
212
- stream at about one block a second, or slows a running one.
206
+ * 202 starts the stream at about one block a second, or slows a
207
+ running one.
213
208
  * 201 stops the stream, after one more block. A read or write does too.
214
- * 210, which the service app sends other models on connecting, pushed
215
- one block after a 201 and nothing otherwise.
216
-
217
- * 220, the service app's error-history reset, left the ``EHD`` block
218
- unchanged.
209
+ * 210 pushed one block after a 201 and nothing otherwise.
210
+ * 220, the error-history reset code, left the ``EHD`` block unchanged.
219
211
 
220
212
  Each of 201, 202, 210 and 220 drew one ``RTMD`` block in reply.
221
213
  """
@@ -230,8 +222,8 @@ def build_read(
230
222
  ) -> bytes:
231
223
  """Frame a read request for ``class_code`` at ``address``.
232
224
 
233
- ``expected_length`` defaults to the length the apps use for that class
234
- (:data:`DEFAULT_READ_LENGTHS`) and must be given for other classes.
225
+ ``expected_length`` defaults to the class's length in
226
+ :data:`DEFAULT_READ_LENGTHS` and must be given for other classes.
235
227
  """
236
228
  if expected_length is None:
237
229
  try:
@@ -313,12 +305,11 @@ class DeviceInfoBlock:
313
305
  """The 58-byte ``DID`` block.
314
306
 
315
307
  Fields checked against the same heater's MQTT device-info report
316
- (:class:`~nwp500.models.DeviceFeature`) carry that model's names and
317
- raw encodings: ``dhw_temperature_max_raw`` and
318
- ``dhw_temperature_min_raw`` (bytes 16 and 17, half-degrees Celsius),
319
- ``model_type_code`` (byte 21) and ``country_code`` (byte 24). The
320
- others keep the names of the NaviLink app's ``DeviceInfo`` class, which
321
- was written for boilers. Unlisted bytes are kept in ``raw``. Not to be
308
+ (:class:`~nwp500.models.DeviceFeature`) carry that model's names and raw
309
+ encodings: ``dhw_temperature_max_raw`` and ``dhw_temperature_min_raw``
310
+ (bytes 16 and 17, half-degrees Celsius), ``model_type_code`` (byte 21)
311
+ and ``country_code`` (byte 24). The others keep the names of this
312
+ block's boiler layout. Unlisted bytes are kept in ``raw``. Not to be
322
313
  confused with :class:`nwp500.models.DeviceInfo`, the cloud's device
323
314
  record.
324
315
  """
@@ -483,16 +474,14 @@ class SubStatus:
483
474
  """The ``SSD`` block (class 17): two DIP-switch settings.
484
475
 
485
476
  This is not live status, which comes in the ``RTMD`` stream
486
- (:class:`RealTimeStatus`). The
487
- layout comes from Navien's UK service toolkit, which names the block
488
- "DeviceSubStatusInfo" and reads two little-endian 16-bit words from
489
- it, labelled DIP switch 1 (bytes 16-17) and DIP switch 2 (bytes
490
- 18-19). That toolkit was written for boilers and expects a 60-byte
491
- block, while an NWP500 sends 59, so on the heat pump the layout is
492
- unconfirmed and what each bit means is not known. On the unit
493
- checked (2026-10-16) the words were 0x0004 and 0x0000; every other
494
- byte was zero. The NWP500 does have DIP switches (error E593,
495
- "Abnormal DIP switch settings"). The whole block is kept in ``raw``.
477
+ (:class:`RealTimeStatus`). The block's boiler layout holds two
478
+ little-endian 16-bit words, labelled DIP switch 1 (bytes 16-17) and DIP
479
+ switch 2 (bytes 18-19), in a 60-byte block, while an NWP500 sends 59, so
480
+ on the heat pump the layout is unconfirmed and what each bit means is
481
+ not known. On the unit checked (2026-10-16) the words were 0x0004 and
482
+ 0x0000; every other byte was zero. The NWP500 does have DIP switches
483
+ (error E593, "Abnormal DIP switch settings"). The whole block is kept in
484
+ ``raw``.
496
485
  """
497
486
 
498
487
  dip_switch_1: int
@@ -692,10 +681,9 @@ def parse_tou_record(data: bytes) -> TOUPeriod:
692
681
 
693
682
  Checked on an NWP500 (2026-10-16): the intervals read equal the plan
694
683
  the cloud holds for that heater, field for field. Price max and min
695
- were equal in every interval checked, so their order is taken from the
696
- NaviLink app. The controller takes the same layout in a write
697
- (:func:`build_tou_write`); the app's own encoder writes the season
698
- differently, which the controller does not read back as written.
684
+ were equal in every interval checked, so their order is not confirmed
685
+ on a device. The controller takes the same layout in a write
686
+ (:func:`build_tou_write`).
699
687
 
700
688
  Raises:
701
689
  ValueError: If ``data`` is not 16 bytes.
@@ -741,8 +729,7 @@ def parse_tou_records(data: bytes) -> list[TOUPeriod]:
741
729
 
742
730
 
743
731
  #: Slots in the controller's ``TOU_PLAN`` table. Reads past the last slot
744
- #: return other data. The NaviLink app also refuses plans of more than 40
745
- #: intervals.
732
+ #: return other data.
746
733
  TOU_PLAN_SLOTS = 40
747
734
 
748
735
  #: Most records one ``TOU_PLAN`` read returns. Fifteen (240 bytes) do not
@@ -817,13 +804,13 @@ def build_tou_write(
817
804
  ) -> bytes:
818
805
  """Frame a ``TOU_PLAN`` write of ``periods`` into slots 0 onward.
819
806
 
820
- The payload is the NaviLink app's: an 8-byte clock header (year
821
- little-endian, month, day, weekday with Sunday = 1, hour, minute,
822
- second), then the records. The address is always 0. On an NWP500
823
- (2026-10-19, 2026-10-20) any other address was answered with ``04``
824
- and cleared the whole table, and a second write at address 0
825
- overwrites the first instead of continuing it. So one write sets
826
- slots ``0`` to ``len(periods) - 1`` and leaves the rest as they were.
807
+ The payload is an 8-byte clock header (year little-endian, month, day,
808
+ weekday with Sunday = 1, hour, minute, second), then the records. The
809
+ address is always 0. On an NWP500 (2026-10-19, 2026-10-20) any other
810
+ address was answered with ``04`` and cleared the whole table, and a
811
+ second write at address 0 overwrites the first instead of continuing it.
812
+ So one write sets slots ``0`` to ``len(periods) - 1`` and leaves the
813
+ rest as they were.
827
814
 
828
815
  Args:
829
816
  periods: One to :data:`TOU_WRITE_MAX_RECORDS` intervals.
@@ -839,7 +826,7 @@ def build_tou_write(
839
826
  f"a TOU write carries 1-{TOU_WRITE_MAX_RECORDS} intervals, "
840
827
  f"got {len(periods)}"
841
828
  )
842
- # The heater's clock is local time, as the app sends it.
829
+ # The heater's clock is local time.
843
830
  now = now or datetime.datetime.now().astimezone()
844
831
  header = now.year.to_bytes(2, "little") + bytes(
845
832
  [
nwp500/cli/__main__.py CHANGED
@@ -352,8 +352,7 @@ async def reset_filter(mqtt: NavienMqttClient, device: Any) -> None:
352
352
  async def filter_life(mqtt: NavienMqttClient, device: Any, hours: int) -> None:
353
353
  """Set the air filter service interval in fan hours.
354
354
 
355
- HOURS is 0 to disable the alarm, or 1000-10000 in steps of 500 (the
356
- values the NaviLink app offers).
355
+ HOURS is 0 to disable the alarm, or 1000-10000 in steps of 500.
357
356
  """
358
357
  await handlers.handle_set_air_filter_life_request(mqtt, device, hours)
359
358
 
@@ -367,7 +366,7 @@ async def diagnostics(
367
366
  """Show the installer diagnostics counters.
368
367
 
369
368
  Lifetime energy and fault counters, hot-water draw statistics and
370
- component run times, as shown on the NaviLink app's installer screen.
369
+ component run times.
371
370
  """
372
371
  await handlers.handle_diagnostics_request(mqtt, device, output_json)
373
372
 
@@ -375,7 +374,7 @@ async def diagnostics(
375
374
  @cli.command() # type: ignore[attr-defined]
376
375
  @async_command
377
376
  async def reset_condenser_fault(mqtt: NavienMqttClient, device: Any) -> None:
378
- """Clear a condenser fault (installer-level in the NaviLink app)."""
377
+ """Clear a condenser fault (an installer-level control)."""
379
378
  await handlers.handle_reset_condenser_fault_request(mqtt, device)
380
379
 
381
380
 
@@ -494,7 +493,7 @@ async def vacation_duration(
494
493
  ) -> None:
495
494
  """Set the vacation day count without entering vacation mode.
496
495
 
497
- Sends the app's goout-day command. Use ``vacation`` to enter vacation
496
+ Sends the goout-day command. Use ``vacation`` to enter vacation
498
497
  mode for a number of days.
499
498
  """
500
499
  await handlers.handle_set_vacation_duration_request(mqtt, device, days)
@@ -1132,6 +1131,18 @@ _tz_option = click.option(
1132
1131
  help="A HeaterParams document (default the tank size's defaults)",
1133
1132
  )
1134
1133
  @_sources_option
1134
+ @click.option(
1135
+ "--bath",
1136
+ type=float,
1137
+ help="The bath readiness is judged against, delivered, preferred unit "
1138
+ "(default the parameters', 28.7 gal)",
1139
+ )
1140
+ @click.option(
1141
+ "--shower",
1142
+ type=float,
1143
+ help="A shower, delivered, preferred unit (default the parameters', "
1144
+ "12 gal)",
1145
+ )
1135
1146
  @click.option(
1136
1147
  "--format",
1137
1148
  "output_format",
@@ -1146,9 +1157,9 @@ def simulate_run(ctx: click.Context, output_format: str, **given: Any) -> None:
1146
1157
  inputs = _read_inputs(sim_cli, **given)
1147
1158
  now = datetime.now(UTC)
1148
1159
 
1149
- def walk(live: Any) -> None:
1160
+ def walk(live: Any, keeper: Any = None) -> None:
1150
1161
  try:
1151
- sim_cli.run(inputs, live, now, output_format)
1162
+ sim_cli.run(inputs, live, now, output_format, keeper=keeper)
1152
1163
  except sim_cli.InputError as e:
1153
1164
  raise click.UsageError(str(e)) from None
1154
1165
 
@@ -1163,9 +1174,10 @@ def simulate_run(ctx: click.Context, output_format: str, **given: Any) -> None:
1163
1174
  live = await sim_cli.compose_live(
1164
1175
  mqtt, ctx.obj["api"], device, inputs, now
1165
1176
  )
1177
+ keeper = await sim_cli.read_book(inputs, now)
1166
1178
  except sim_cli.InputError as e:
1167
1179
  raise click.UsageError(str(e)) from None
1168
- walk(live)
1180
+ walk(live, keeper)
1169
1181
 
1170
1182
  ctx.exit(asyncio.run(_with_device(ctx, command)))
1171
1183
 
nwp500/cli/calibration.py CHANGED
@@ -159,8 +159,8 @@ def print_report(done: Calibrated, console: Console) -> None:
159
159
  "readings": "Air: the readings given",
160
160
  "constant": "Air: the constant given",
161
161
  "source": "Air: the sources' record beside the heater",
162
- "heater": "Air: none given; the heater's own reading while its "
163
- "compressor runs",
162
+ "heater": "Air: none given; the heater's own reading, the "
163
+ "cabinet's less its warmth while the compressor is idle",
164
164
  None: "Air: none given; recoveries use the heater's own reading",
165
165
  }[done.air]
166
166
  )
@@ -1053,10 +1053,10 @@ def build_yearly_energy_report(
1053
1053
  def build_diagnostics_rows(diagnostics: Any) -> list[StatusRow]:
1054
1054
  """Build presentation-neutral rows for installer diagnostics.
1055
1055
 
1056
- Labels follow the NaviLink app's installer screen. All values are raw
1057
- device counters; ``cumulated_op_time_*`` are hours and the two
1058
- ``cumulated_pwr_*`` values are watt-hours (both cross-checked against
1059
- the energy query), everything else is a count with no documented unit.
1056
+ All values are raw device counters; ``cumulated_op_time_*`` are hours
1057
+ and the two ``cumulated_pwr_*`` values are watt-hours (both
1058
+ cross-checked against the energy query), everything else is a count
1059
+ with no documented unit.
1060
1060
 
1061
1061
  Args:
1062
1062
  diagnostics: DeviceDiagnostics object