[mgazza]

Draft — not ready to merge. Built with no official vendor specification: every endpoint and field was derived from third-party Home Assistant integrations, and nothing has run against real hardware. Two inferred behaviours would silently produce a wrong plan if they are wrong — see below.

What this adds

A native Hanchu ESS cloud component (HanchuCloud), following the AlphaESS/Sunsynk structure: login + token refresh + reactive re-login, device discovery, tiered polling, sensor publishing, and a batched control path.

File	Lines
apps/predbat/hanchu.py	1,540
apps/predbat/hanchu_const.py	511
templates/hanchu.yaml	444
5 test suites (tests/test_hanchu_*.py)	~2,160, 67 cases
components.py / config.py / unit_test.py	+99

All five Hanchu suites pass; pre-commit (ruff, black, cspell, yaml) clean; 100% docstrings. The existing hanchu_cloud.yaml HACS-bridge template is untouched.

The --quick suite stops later on data_age_metrics (Expected data_age_days=8, got 0). That is pre-existing — reproduced identically at base commit d951201e in a throwaway worktree.

Provenance — read this before trusting anything

There is no published Hanchu API. Sources, all MIT-licensed:

• upton68/hanchu-ess-ha — actively maintained (~281 commits); primary source
• guoxiatech/hanchu-ess-ha — its upstream (~128 commits)
• Blustery7752/hanchu-ess — thinner, but talks to a different endpoint family

Evidence was graded rather than counted: guoxiatech's request layer is a near-copy of upton68's, so agreement between those two is weak. Blustery7752 is independent, so where it agrees the evidence is strong. Every item in hanchu_const.py is annotated OBSERVED / CORROBORATED / INFERRED with its source repo and file.

Licence: all code written fresh in batpred's idiom; nothing ported. Only facts about the API surface were taken.

Corroborated across independent sources: base URL iess3.hanchuess.com; iotGet/iotSet body shape {devType, sn, keys/value}; devType "2" = DTU (as a string); fastChargeDischarge semantics.

⚠️ Inferred — not read in any reference

• Work mode 3 "User-defined" is the mode that honours the timed slots. The biggest guess. hanchu_work_mode_control: False is the escape hatch.
• Slot start == end == 0 means disabled — no per-slot enable key exists among the twelve.
• inverter_limit derived from the discharge-power ceiling, battery_rate_max from the charge-power ceiling — the API reports neither rating.
• 60s default write pacing. Batching is observed (the reference stages changes and flushes once, explicitly to avoid rate limiting); no numeric limit is published anywhere.
• The 25-day token lifetime is upton68's own safety margin, not a documented server figure.

Where the references disagreed

Point	Conflict	Followed
Login	plaintext pwd at identify/auth/token vs Blustery's RSA-encrypted identify/auth/login/account	upton68
Endpoint family	app/ha/* plain JSON vs Blustery's platform/* with AES bodies	app/ha/*
Reauth code	upton68 contradicts itself — docstring 90076, tests use 100	the code
Timeout/retry	15s ×3 vs 10s ×1	upton68

What hardware would most likely disprove

1. The work mode. Symptom: slots written and acknowledged, never acted on.
2. bmsDesignCap being kWh. If it is Ah or Wh, soc_max is wrong by orders of magnitude — and every plan with it.

Two defects the tests caught before commit

• The login/refresh response carries the token as the envelope's bare data, so the debug trace leaked it. redact() now masks data on those two paths.
• _post promised never to raise but let a bare OSError escape. Broadened to match alphaess.py.

Security note

Login sends the customer's account password in the request body (over TLS) — the same shape as Sunsynk's password_legacy path.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NMBtMJ5YeGi9yKRofHxhbR

[upton68]

Thanks for putting this together. I maintain upton68/hanchu-ess-ha and run Predbat against a real Hanchu iESS system, so I can confirm a few of the points listed as inferred:

Work mode 3 ("User-defined") is the mode that honours the timed slots. That matches what I see on my hardware.
Disabling a slot: I disable a slot by setting both its start and end time back to 0:00. Also note that User-defined mode has three timed slots, so the component may want to handle all three rather than just the first.
bmsDesignCap is in kWh. I use it as soc_max in Predbat without any conversion.
Power ratings: the maximum power values returned by the API match the ratings shown in the Hanchu app, and they match the inverter_limit and battery rate values I use in Predbat. So deriving them from the API's power ceilings looks sound on my system.

Provenance: upton68/hanchu-ess-ha is a fork of guoxiatech/hanchu-ess-ha, which is the official Hanchu integration (Hanchu is the trading name of Guoxiatech). So the shared login and request layer comes from the vendor's own code, not from my repo being copied. It isn't two weak sources agreeing, it's one source of truth, and the plaintext-password login at identify/auth/token is the vendor's own flow. I believe Blustery7752's cloud version was reverse-engineered separately, so it's a genuinely independent source. The official version was read-only; the control and write side was added in my fork.

Separately, my own earlier reverse-engineering of the Hanchu cloud API also found AES-encrypted request bodies, so the platform/* family Blustery uses looks real to me, and may be the app's own API, as opposed to the app/ha/* endpoints the official HA integration uses.

Two things from running this in production that may help with the write-pacing and timeout guesses:

Concurrent control calls can fail. I saw the cloud return error 300004 when a charge start was sent right after a discharge stop, or the other way round, as separate control calls with no guaranteed ordering. Serialising all Predbat charge/discharge start and stop calls through a single queued path fixed it. Since then I've had 20+ transitions with no timeouts or 300004 errors. So it's worth making sure the component never has two control writes in flight at once, on top of any pacing.
Response times vary a lot. In my testing, cloud response times ranged from about 7s to 45s. Before I raised the client timeout to 15s per attempt, almost every action needed at least two attempts, so the 15s ×3 retry in the reference is reasonable.

These are from my own system only, so it's worth checking against other models if anyone has them.

[mgazza]

Thanks, this is exactly what we couldn't get from the code alone. Pushed da2f091:

• Every control write now goes through a single lock, so two can never be in flight (the 300004 case). Charge and discharge were already batched into one iotSet, but the schedule button and the reconcile loop could each start one.
• Since User-defined runs all three slot pairs and 00:00–00:00 disables a slot, Predbat now writes every slot it doesn't use as disabled, so a leftover app slot can't run against the plan.
• Provenance updated: work mode 3, slot disabling and bmsDesignCap in kWh are marked as hardware-confirmed (on your system), and GUOXIA is recorded as Hanchu's own integration.

The 15s × 3 retry stays as is. If you're able to try this branch on your system at some point, that would be the best test it could get.

[upton68]

Thanks for the quick turnaround, those changes cover what I raised. A few more points from running this in practice:

Mid-window end-time changes. Predbat can lengthen or shorten a window's end time while it's running. From the code, the rebuilt payload should pick that up. On my system, rewriting a whole slot mid-window works fine, and setting start and end to 00:00 stops a window immediately, both in the integration and in the Hanchu app. I haven't tried stopping by moving the end time to now or earlier. Is a mid-window end-time change covered by a test?

Failed writes. The risky case is a rejected shorten: the inverter keeps the longer end time and carries on past the plan (and a rejected lengthen ends the window early). The code retries, but as far as I can see it only logs a warning. In my integration a write is retried three times, and if it still fails I get a phone notification so I can step in manually. It might be worth surfacing a persistent write failure somewhere more visible, if Predbat has a suitable mechanism. I'm also not sure whether the 60s pacing hold could delay a retry after a failure.

On the power ranges: the 5000 defaults are overridden per device by the menu, which is right, since Hanchu units come in 3.68, 5, 6 and 10 kW. I've only confirmed the 5 kW case, where the menu maximum matches the app. It would be worth logging a warning when the menu doesn't return the power bounds and the 5000 default is in use. It might also be worth asking someone with a 3.68, 6 or 10 kW unit to confirm the menu values, and adding an inverter_limit override alongside the battery_rate_max one.

I'd be glad to help test this. I run Predbat in a couple of setups already, so I'd try the branch as a separate read-only instance to check login, sensors and limits first, and report back before anything writes to the inverter.

[mgazza]

Thanks again, all three taken on board in f208e3f:

• Mid-window changes: there are now tests for shortening, lengthening, moving the end to "now" and cancelling a running window. Each produces one write carrying the new slot times; cancelling writes 00:00–00:00.
• Failed writes: three rejected writes in a row now raise a Predbat notification (once per streak) and flag a non-fatal error, and recovery is logged. You were right about pacing: a failed write was held for the full interval. It's now retried after 30s, so the next cycle picks it up. Successful writes are still paced normally.
• Power ranges: a one-off warning is logged when a unit's menu answers without power bounds and the 5000 W default is in use, and there's a new hanchu_inverter_limit override alongside hanchu_battery_rate_max.

A read-only instance first sounds ideal. Set hanchu_control_enable: false (or keep switch.predbat_set_read_only on) and it won't write anything. Login, sensors and the derived limits are the things I'd most like checked. If anyone you know has a 3.68, 6 or 10 kW unit, the menu power bounds would be very useful too.

[upton68]

Thanks for the quick turnaround in f208e3f. The mid-window tests, the failure notification and the 30s retry all sound right. I'll also ask around for owners of 3.68, 6 and 10 kW units to try the read-only setup and report back on the menu power bounds. I'd still like to try it read-only myself as a separate instance, checking login, sensors and derived limits, and I'll report back before anything writes to the inverter.

The next section slipped my mind previously so I am bringing it your attention now.

AC- vs DC-coupled systems. I run AC-coupled, and I've worked with a DC-coupled contributor on my own integration, so I've seen the two differ. The clearest case was a change that merged status and statistics polling into a single getDeviceStatus call. That was fine on DC but broke the daily energy sensors on AC-coupled. So it's good that this component keeps getDeviceStatus and getDeviceStatistics separate, and I'd keep it that way.
On PV, I can answer the question in hanchu_const.py. On my AC-coupled system, pvTtPwr does not include the AC-coupled PV generation. That is only reported in bypMeterTotalPower. The daily pv figure in getDeviceStatistics, however, does cover both, so on an AC-coupled system the live pv_power will under-report compared with pv_today, unless bypMeterTotalPower is combined with it.
There is also a signal for coupling type: bypMeterSwitch is 1 on AC-coupled systems and 0 on DC-coupled ones. The code currently says there's no such signal, so this could be used to detect it, and to decide whether to add bypMeterTotalPower into the PV figure Predbat sees.
This is from my system only, so it's worth checking on other units.

[upton68]

Tested f208e3f read-only on a real 5 kW AC-coupled system: login, discovery, iotGet, status and statistics all work, and batSoc, bmsDesignCap and the power settings match the app. My existing cloud integration and Predbat instance stayed online throughout, so a second login doesn't seem to disturb them.

I found two problems that together mean the per-device ranges from /gateway/app/ha/menu are never used:

The menu returns code 200, but _post only accepts a response with success true, so it logs "was unsuccessful (code 200)" and refresh_config discards the data. The official Hanchu integration (guoxiatech/hanchu-ess-ha, async_get_menu in api.py) accepts the menu on code == 200 alone.
Even when accepted, _post returns only the inner data, but _parse_menu_ranges looks for a data key inside what it receives, so it finds no ranges.

With both changes (below) the parse found all five ranges: charge and discharge power 0 to 5000, charge SoC 50 to 100, discharge floor 5 to 45 and grid charge SoC 20 to 100. With only the first change it found none.

-            if payload.get("success"):
+            if payload.get("success") or (endpoint_key == "menu" and code == 200):
                 return True, payload.get("data")

-                ranges = self._parse_menu_ranges(menu)
+                ranges = self._parse_menu_ranges({"data": menu})

On my 5 kW unit the menu values equal the built-in defaults, so nothing changes for me. For 3.68, 6 and 10 kW models the defaults would be wrong, so I'd expect this to matter for them. I also noticed _warn_if_default_power runs only inside if ok:, so it can't warn when the menu call itself fails. I haven't looked at the unit tests, but if they pass the whole response to the parser, that may be why this wasn't caught.

[upton68]

Regarding my comment on 30th September re AC vs DC Systems.

Daytime check on the AC-coupled system (f208e3f, read-only): pvTtPwr 0.0 W, bypMeterTotalPower 686.8 W, bypMeterSwitch 1. Load was 278.8 W, the battery was charging at 408.0 W and the grid was 0 W, so load plus battery equals bypMeterTotalPower exactly. The AC-coupled solar is only in bypMeterTotalPower, so pv_power (from pvTtPwr) reads zero while the system generates. The daily pv in getDeviceStatistics was 2.19 kWh, so it does count the AC-coupled generation.

For comparison, on a DC system (a contributor's getDeviceStatus output) bypMeterSwitch is 0, bypMeterTotalPower is 0 and pvTtPwr carries the solar (load 630 W = battery 615 W + 15 W PV, grid 0). So bypMeterSwitch distinguishes the two, and adding bypMeterTotalPower to pvTtPwr gives the right live PV on both, since it adds nothing on DC. The one case I can't speak to is a system with both DC strings and AC-coupled PV, where I don't know whether pvTtPwr already includes the AC part.

[upton68]

Correction to my earlier comment. I said the 5000 W defaults would be wrong for 3.68, 6 and 10 kW models. Having checked Hanchu's user manuals, the picture is:
Single phase, 3.0 to 6.0 kW (HESS-HY-S-3.0-6.0K, section 11.2): max charge and discharge power is 5000 W for all of the 3.0K, 3.68K, 4.0K, 5.0K and 6.0K. The 5000 W defaults are correct for battery power on these. The AC rating varies (section 11.3: 3000/3680/4000/5000/6000 W), so inverter_limit derived from the discharge ceiling (5000 W) overstates the 3, 3.68 and 4 kW units and understates the 6 kW one. Owners of these models should set hanchu_inverter_limit.
Single phase, 7/8/10 kW (HESS-HY-S-7K-10K, section 10.1): max charge and discharge power is 7000/8000/10000 W, equal to the AC rating.
Three phase:
HESS-HY-T-05/06/08/10/12K (section 10.1): 5000/6000/8000/10000/12000 W charge and discharge.
HESS-HY-T-4K-M to 12K-M and T-10K-M4 to 20K-M4 (section 11.1): 4 to 20 kW charge power. Discharge is given only as a current (25 A or 40 A).
Commercial CESS-HY-25K to 50K and 40K-P/50K-P: 25 to 50 kW charge power, 100 A.
In all of these the battery power ceiling equals the rated AC output, so inverter_limit derived from it is correct.
What this means for the defaults: the 5000 W default is right only for the single-phase 3–6 kW units and for 5 kW three-phase. Every larger model, and the T-4K-M, needs the menu values to be read correctly, which depends on the menu-parsing fix from my test report.
Model naming overlaps: S-6.0K (5000 W), T-06K (6000 W) and T-6K-M (6 kW) are all "6 kW", and 10 kW and 12 kW exist in several ranges. Any per-model matching needs the full model string.
(There are also 48 V off-grid-style HESS-HY-S-6K-S/12K-S units. Their datasheets give only charge currents, so I've left them out.)

[springfall2008]

I'm going to merge this, so please raise tickets for new bugs/issues

[springfall2008]

Automated review failed to complete for this PR. Reason: Claude ran out of turns before finishing (--max-turns) (exit status 1). Failed at: triage_daemon.py:1962 in review_pr() (daemon 063549db). Log: pr-5305-review.log in the bot's logs directory. Not retrying automatically; remove BOT_FAILED and re-add BOT_REVIEW to try again.