Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions custom_components/addhon/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,33 @@ the notes were generated automatically carry a link to their diff instead of a s

**Changes**

- **The air conditioner energy sensor reads the counter in Wh; its value drops 1000 times**
(#147): the appliances that meter report watt-hours and the sensor declared them as kWh,
1000 times too much. It still shows kWh. **Existing installations:** at the update the
value falls to a thousandth, Home Assistant's statistics read that as a meter reset, and
the energy recorded before the update stays 1000 times too high. To correct the past
figures use Developer tools → Statistics on that sensor (adjust the sum). Applied to
every air conditioner; the ones that report 0 are unchanged.
- **New power sensor on the air conditioners that report it** (#147): the power the unit
draws, in W, on the models whose cloud state carries it (seen on the 2026 Flexis and on
other recent series). Updated at most once every 30 seconds while the unit runs.
- **The cleaning counters survive an empty or partial maintenance answer** (#138): each
good answer is laid over the ones before, as the official app's store does, so a
counter missing from one answer keeps its last value instead of going unknown.

- **The maintenance read sends the appliance type too, as the official app does** (#138):
the request for the cleaning counters carried only the appliance's address, the app's
carries the type as well.
- **A statistics answer whose washes counter went down is discarded as stale** (#138): the
cloud alternated the current statistics with an older version that carried no error, and
the washes counter swung between the two every minute. The last statistics are kept, the
diagnostics file says `rejected: stale` and the cycle timeline gets a row. After ten such
answers in a row the lower counter is taken as the new value.
- **A maintenance answer carrying an error is discarded and the last cleaning counters
kept** (#138): the cloud answered the maintenance service with a 200 that carried an
error code and no cleaning counters at alternate polls, the drum, filter and drawer
cleaning binary sensors went unknown and the error fields entered the statistics. The
diagnostics file says `maintenance_rejected` and the cycle timeline gets a row.
- **The Laundry Centre is supported, read-only** (#124): a Haier washer and dryer under one
appliance is set up as one device with a Washer and a Dryer child device. Sensors: state,
remaining time, programme name, phase, errors, totals and energy; binary sensors: remote
Expand Down
177 changes: 164 additions & 13 deletions custom_components/addhon/client/engine/appliance.py
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,17 @@
# swung every minute. Such an answer is discarded and the last good one kept; the
# version does not change (the next poll asks v2 again).
_STATISTICS_ERROR_KEYS = ("errorMessage", "errorType")
# A v2 answer can be stale without saying so: on 2026-11-11 a v5.29.0 dump of an HQD
# washer showed the cloud alternating the fresh statistics (`programsCounter` 41, rows
# dated to the second) with an older version carrying no error key (39, rows dated at
# midnight), and the washes counter swung 41<->39 every minute. The app compares nothing
# (apk2 decomp.txt @4192286-4192419, `apk2/analysis/issue138-beta3/21` section 4) but
# reads once per screen, not every minute. A v2 answer whose counter is lower than the
# last one taken is discarded like an error body, as `stale`. This many in a row and the
# lower counter is believed and becomes the base: a counter that really went back (an
# appliance reset, an account moved) must not freeze the statistics until a reload. At a
# poll a minute that is ten minutes; the alternation seen never got past one in a row.
STALE_STATISTICS_LIMIT = 10


def _statistics_error(answer: Mapping[str, Any]) -> Optional[str]:
Expand All @@ -106,6 +117,53 @@ def _blank(value: Any) -> bool:
return value is None or (isinstance(value, str) and not value.strip())


# A `/maintenance-cycle` answer carrying one of these with a value, or a `resultCode`
# other than zero, is an error body and not the cleaning counters: on 2026-11-11 a
# v5.29.0 dump of an HQD washer showed the cloud answering a 200 whose payload was
# `resultCode "1"`, `errorCode "1003"`, `errorDescription "SQL error: "` and no cleaning
# map, at alternate polls. Merged as it came, the cleaning binaries went unknown and the
# three keys entered the statistics. The app checks none of them and is saved by its
# store, which merges the payload over the maps it holds (`STORE_MAINTENANCE`, apk2
# decomp.txt @1346088-1346113; `apk2/analysis/issue138-beta3/21`); here the answer is
# discarded and the last good one merged in its place.
_MAINTENANCE_ERROR_KEYS = ("errorCode", "errorDescription", "errorMessage", "errorType")


def _maintenance_error(answer: Mapping[str, Any]) -> Optional[str]:
"""Why `answer` is an error body and not the cleaning counters, None when it is
not: `maintenance_<errorCode>` when that is a bare name the dump can print (64
characters, `diagnostics._statistics_reason`), `maintenance` otherwise.

A `resultCode` that is null or blank says nothing, and neither does an error field
that is; "0", 0 and "0.0" are all the zero of a good answer, for the `errorCode`
as for the `resultCode` (an error code of zero names no error)."""
code = answer.get("resultCode")
failed = not _blank(code) and not _zero(code)
error = answer.get("errorCode")
silent = all(
_blank(answer.get(key)) for key in _MAINTENANCE_ERROR_KEYS if key != "errorCode"
) and (_blank(error) or _zero(error))
if not failed and silent:
return None
# A zero or blank `errorCode` names no error even on an answer rejected for its
# `resultCode` or for another error field: that one is plain `maintenance`, never
# `maintenance_0` or a bare `maintenance_`.
named = isinstance(error, (str, int)) and not isinstance(error, bool)
if named and not _blank(error) and not _zero(error):
reason = f"maintenance_{str(error).strip()}"
if reason.isidentifier() and len(reason) <= 64:
return reason
return "maintenance"


def _zero(value: Any) -> bool:
"""Whether a `resultCode` reads as zero, as text or as a number."""
try:
return float(str(value).strip()) == 0
except (TypeError, ValueError):
return False


def _statistics_shaped(answer: Mapping[str, Any]) -> bool:
"""Whether `answer` carries at least one statistics key with a value of its shape."""
for key, shapes in _STATISTICS_SHAPES.items():
Expand Down Expand Up @@ -228,7 +286,19 @@ def __init__(
# body gets instead (`_read_statistics`); a copy, the merge writes into the one
# returned.
self._statistics_kept: dict[str, Any] = {}
# The v2 answers discarded as stale since the last one taken
# (`_statistics_stale`, `STALE_STATISTICS_LIMIT`).
self._statistics_stale_run = 0
self._statistics_v1_only = False
# The good `/maintenance-cycle` answers taken, each laid over the ones before, {}
# before the first: what is merged into the statistics (`_read_maintenance`); and
# why the last answer was discarded, None once a good one came (`statistics_source`).
self._maintenance_kept: dict[str, Any] = {}
self._maintenance_rejected: Optional[str] = None
# Maintenance reads started, and the one whose answer the kept map holds: an
# answer from an earlier read never replaces a later one's.
self._maintenance_reads = 0
self._maintenance_applied = 0
self._attributes: dict[str, Any] = {}
self._zone = zone
self._additional_data: dict[str, Any] = {}
Expand Down Expand Up @@ -445,10 +515,16 @@ def adopt_pushed_parameter(self, name: str, data: Mapping[str, Any]) -> HonAttri
def statistics_source(self) -> Optional[dict[str, Any]]:
"""`{"version": "v2" | "v1", "fallback": None | reason}` of the last statistics
read (issue #138): the reason is `"empty"`, `"shape"` or the class name of what
v2 raised. A v2 answer discarded as an error body adds `"rejected"`, its
`errorType` or `"error"`, until the next answer taken. None before the first
read. Read by the diagnostics dump only."""
return self._statistics_source
v2 raised. A v2 answer discarded adds `"rejected"`, until the next answer taken:
an error body's `errorType` or `"error"`, or `"stale"` for a cycle counter that
went down; a `/maintenance-cycle` answer discarded as an error body adds
`"maintenance_rejected"`, `maintenance_<errorCode>` or `"maintenance"`, until
the next good one. None before the first read. Read by the diagnostics dump
only."""
source = self._statistics_source
if source is None or self._maintenance_rejected is None:
return source
return {**source, "maintenance_rejected": self._maintenance_rejected}

@property
def info(self) -> dict[str, Any]:
Expand Down Expand Up @@ -1267,11 +1343,63 @@ async def load_statistics(self) -> None:
self._statistics = await self._read_statistics()
# The statistics half as it came, before the merge writes into it.
statistics = dict(self._statistics) if isinstance(self._statistics, dict) else {}
maintenance = await self.api.load_maintenance(self)
maintenance = await self._read_maintenance()
self._statistics |= maintenance
if self._cycle_log is not None:
self._log_statistics(self._cycle_log, statistics, maintenance)

async def _read_maintenance(self) -> dict[str, Any]:
"""The `/maintenance-cycle` payload to merge over the statistics.

An answer that is an error body (`_maintenance_error`: seen at alternate polls
with no cleaning map, dump of 2026-11-11) is discarded: the last good answer is
handed back ({} before one), so the cleaning counters stay and the error keys
never enter the statistics; `statistics_source` says `maintenance_rejected` and
the cycle log gets a row. A good answer clears that.

The kept map is the app's store: every good answer is laid over what is held
(`STORE_MAINTENANCE` is an `Object.assign` of the payload over the appliance's
entry, apk2 decomp.txt @1346088-1346113), and what is held is what gets merged.
So an empty answer, or one missing a cleaning map an earlier one carried,
leaves the counters where they were instead of dropping them for that poll;
an empty one says nothing and changes nothing else. As in the app, a map the
cloud stops sending stays until the restart.

Two reads of one appliance can overlap. The answer of the earlier one, coming
back last, is not laid over the later one's.
"""
self._maintenance_reads += 1
read = self._maintenance_reads
answer = await self.api.load_maintenance(self)
if not isinstance(answer, Mapping):
return answer
Comment thread
sourcery-ai[bot] marked this conversation as resolved.
Resolved
if not answer:
return dict(self._maintenance_kept)
rejected = _maintenance_error(answer)
if rejected is None:
if read > self._maintenance_applied:
self._maintenance_applied = read
self._maintenance_kept = {**self._maintenance_kept, **answer}
self._maintenance_rejected = None
return dict(self._maintenance_kept)
_LOGGER.debug(
"Maintenance answered an error body for %s (%s): kept the last",
self.appliance_type,
rejected,
)
self._maintenance_rejected = rejected
self._log_rejected(rejected)
return dict(self._maintenance_kept)

def _log_rejected(self, reason: str) -> None:
"""A statistics or maintenance answer discarded, in the cycle log. Never raises."""
if self._cycle_log is None:
return
try:
self._cycle_log.statistics_rejected(reason=reason)
except Exception: # noqa: BLE001 - the log must never cost the poll
_LOGGER.debug("Cycle log failed", exc_info=True)

def _log_statistics(
self, log: _cycle_log.CycleLog, statistics: Any, maintenance: Any
) -> None:
Expand All @@ -1280,7 +1408,8 @@ def _log_statistics(
of this object seeds the comparison silently. An empty answer is no read: both
halves empty log nothing, and one half empty beside a full one leaves that
half's keys last seen in the comparison (the next read is compared with the last
that said something). Never raises."""
that said something). A discarded maintenance answer comes here as the last
good one, so its cleaning maps do not move. Never raises."""
try:
if statistics:
self._statistics_half_logged = dict(statistics)
Expand Down Expand Up @@ -1308,8 +1437,9 @@ async def _read_statistics(self) -> dict[str, Any]:
answered as a 200 (seen mixed with stale statistics at alternate polls, dump of
2026-11-08): it is discarded, the last v2 answer taken is handed back ({} before
one), the version stays v2, `statistics_source` says `rejected` and the cycle
log gets a row. Checked before the shape. An API without `load_statistics_v2`
reads v1.
log gets a row. Checked before the shape. A shaped answer whose
`programsCounter` is lower than the last one taken is discarded the same way,
as `stale` (`_statistics_stale`). An API without `load_statistics_v2` reads v1.
"""
read_v2 = getattr(self.api, "load_statistics_v2", None)
if (
Expand All @@ -1334,15 +1464,23 @@ async def _read_statistics(self) -> dict[str, Any]:
self._statistics_source = {
"version": "v2", "fallback": None, "rejected": rejected,
}
if self._cycle_log is not None:
try:
self._cycle_log.statistics_rejected(reason=rejected)
except Exception: # noqa: BLE001 - the log must never cost the poll
_LOGGER.debug("Cycle log failed", exc_info=True)
self._log_rejected(rejected)
return dict(self._statistics_kept)
if _statistics_shaped(answer):
if self._statistics_stale(answer):
_LOGGER.debug(
"Statistics v2 answered a lower cycle counter for %s: "
"kept the last",
self.appliance_type,
)
self._statistics_source = {
"version": "v2", "fallback": None, "rejected": "stale",
}
self._log_rejected("stale")
return dict(self._statistics_kept)
self._statistics_source = {"version": "v2", "fallback": None}
self._statistics_kept = dict(answer)
self._statistics_stale_run = 0
return answer
fallback = "shape"
else:
Expand All @@ -1359,6 +1497,19 @@ async def _read_statistics(self) -> dict[str, Any]:
self._statistics_source = {"version": "v1", "fallback": None}
return await self.api.load_statistics(self)

def _statistics_stale(self, answer: Mapping[str, Any]) -> bool:
"""Whether a v2 answer is an older version of the statistics held: both carry a
`programsCounter` that reads as a whole number and the answer's is lower (dump
of 2026-11-11, see `STALE_STATISTICS_LIMIT`). A counter absent or unreadable on
either side is not compared. The `STALE_STATISTICS_LIMIT`th such answer in a row
is not stale: the caller takes it, and it is the base from then on."""
counter = _as_int(answer.get("programsCounter"))
held = _as_int(self._statistics_kept.get("programsCounter"))
if counter is None or held is None or counter >= held:
return False
self._statistics_stale_run += 1
return self._statistics_stale_run < STALE_STATISTICS_LIMIT

async def update(self, force: bool = False) -> Optional[bool]:
"""Read the context, unless the last read is under 5 s old and not `force`d.

Expand Down
11 changes: 8 additions & 3 deletions custom_components/addhon/client/engine/cycle_log.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,10 @@
`loadingPercentage` it did not hold (the load measured and suggested, the start date of
one cycle each) and the scalars that changed, a map's own one level down
(`temperatureUsage.temp40`); the first read of an appliance object only seeds; or a
v2 answer discarded as an error body (`rejected`, its `errorType`), the statistics
held unchanged;
v2 answer discarded as an error body (`rejected`, its `errorType`) or for a cycle
counter that went down (`rejected`, `stale`), the statistics held unchanged, or a
`/maintenance-cycle` answer discarded as an error body (`rejected`,
`maintenance_<errorCode>` or `maintenance`), the cleaning counters held unchanged;
- `entity`: a state one of the entities that show a cycle's options, phase, programme or
machine state published (`key`, the unique_id's suffix), `unknown` and `unavailable`
kept as the text they are; Home Assistant's listener feeds it (`__init__.py`);
Expand Down Expand Up @@ -581,7 +583,10 @@ def statistics(

def statistics_rejected(self, *, reason: str) -> None:
"""A poll whose `/statistics` answer was an error body and was discarded, the
statistics held unchanged: `reason` is its `errorType` or `error`."""
statistics held unchanged: `reason` is its `errorType` or `error`, or `stale`
for an answer whose cycle counter went down. Or one whose
`/maintenance-cycle` answer was, the cleaning counters held unchanged: `reason`
is `maintenance_<errorCode>` or `maintenance`."""
now = self._clock()
fields = {"rejected": _text(reason)}
with self._lock:
Expand Down
13 changes: 12 additions & 1 deletion custom_components/addhon/client/transport/api.py
Original file line number Diff line number Diff line change
Expand Up @@ -612,8 +612,19 @@ async def _load_statistics(self, appliance: Any, version: str) -> dict:
return payload if isinstance(payload, dict) else {}

async def load_maintenance(self, appliance: Any) -> dict:
"""`GET /commands/v1/maintenance-cycle` with the two parameters the hOn app
sends for every appliance, `macAddress` and `applianceType` (apk2 decomp.txt
@1346942-1346975; `apk2/analysis/issue138-beta3/21`), the type as the statistics
read sends it. Only `macAddress` went until v5.29.0.

For a laundry centre the app asks once per unit: `unit` is the `unitName` (WM
or TD) and `applianceType` carries that same name (@1385709-1385760). That is
deliberately not done here: the laundry centre is read-only and no entity of
its reads a cleaning counter, it would take two requests per appliance, and no
dump shows what the cloud answers to either form. To revisit with a dump."""
url = f"{API_URL}/commands/v1/maintenance-cycle"
params = {"macAddress": appliance.mac_address}
# No `unit`: see above.
params = {"macAddress": appliance.mac_address, "applianceType": appliance.appliance_type}
async with self._connection.get(url, params=params) as response:
data = await response.json(content_type=None)
payload = data.get("payload", {}) if isinstance(data, dict) else {}
Expand Down
1 change: 1 addition & 0 deletions custom_components/addhon/const.py
Original file line number Diff line number Diff line change
Expand Up @@ -259,6 +259,7 @@
AC_ATTR_ON_OFF = "settings.onOffStatus"
AC_ATTR_COMPRESSOR_FREQ = "compressorFrequency"
AC_ATTR_TOTAL_ENERGY = "totalElectricityUsed"
AC_ATTR_POWER = "acInput" # Power drawn right now (W), #147
# Air quality (direct attributes, confirmed on Roberto's AC)
AC_ATTR_PM25 = "pm2p5ValueIndoor" # Indoor PM2.5 (µg/m³)
AC_ATTR_CO2 = "co2ValueIndoor" # Indoor CO2 (ppm)
Expand Down
Loading
Loading