feat: short-ASCII family keepers onto main (estimate, junk gates, aux MPPT)

[mikehardy]

Hey Maksym 👋

First — sincere thanks for creating and maintaining EyeBond Local. I just got my first solar kit, I've never really done Python or Home Assistant before, and somehow I still landed in your repo. I've been doing software for about 30 years and public GitHub maintenance for nearly 10, with heavy agent use all this year, so I'm pretty motivated to make this inverter work — and I'm always happy to help a fellow maintainer.

This PR was built agentically (Cursor agents did a lot of the digging, coding, and adversarial review loops), but I'm a human on the other end listening, and I'm ready to iterate until it works for you if that's possible.

Summary

Adds a read-only EyeBond short-ASCII path for OFFG / URTU1920-style collectors (proven live on an Anern SPI-12000W), plus two small shared fixes the driver needs on the callback transport / admission side.

Commits (reviewable one at a time):

1. fix: stop callback identity from leaking shared listeners — admission/callback lifecycle
2. fix: discriminate callback AABB MPPT frames from FC4 — bare aabb side-channel on the callback socket
3. feat: add read-only EyeBond short-ASCII driver for Anern SPI-12000W — driver, schema, catalog, tests

Driver direction and implemented scope

The required driver is not eybond_g_ascii; it is the FC4/short-ASCII family matching APK DevUrtu1920_01 (SmartValue / 19B4.xml).

Implemented here as eybond_short_ascii (read-only):

• FC4 MD / Q1 / F / RB
• Solicited bare TCP 5AA5…02 → aabb0200 for MPPT PV (same elicit path SmartValue/cloud uses)
• Wire framing: device 0x02FF, collector 0xFF, payload CMD+device_addr+CR
• Writes stay rejected; diagnostic ASCII is allowlisted to proven reads only

Live PV proof (example): SmartValue Historical 07:47:17 showed 1.67 kW / 118.5 V / Track; HA after the 5AA5 solicit path showed about 1.59–1.65 kW and 118.7–120.2 V / Track. Re-verified after deploying this rewritten branch to my HA.

Known gaps (documented in the evidence pack):

• Q1 load% is coarse (Kill-A-Watt 1333 W vs HA ~1207 W at firmware 10%); often 0% for smaller / battery-mode loads
• No proven grid-import watts or accumulated grid-import energy on this read surface
• Battery-mode load uses BMS DC while discharging
• RB with pack-voltage raw 0 and SoC 0 = BMS link lost (omit SoC/V/I zeros; trailing fields may be nonzero)

Testing / iteration loop

How this was developed against live hardware:

• SmartValue in a rooted Android emulator — Historical Data list (~5 min snaps; scroll/screencap via adb) as the cloud ground truth
• MITM / collector↔cloud proxy — tee of live cloud sessions to prove FC4 short-ASCII and the 5AA5 → aabb0200 exchange independently of the app UI
• Home Assistant over SSH — Supervisor API entity dumps + tar-install / ha core restart for a fast edit → deploy → correlate loop
• Adversarial review loop — independent GPT review vs main until findings (including nits) were cleared, then history rewritten into the three commits above
• Unit/focused suites for short-ASCII, AABB discrimination, admission/config-flow, and transport boundaries; compileall + quality-gate static checks

Evidence pack

I uploaded a maintainer evidence pack (proxy capture, ValueCloud summaries, APK/19B4 notes, live HA↔SmartValue correlation write-up, sanitized session exports; credentials redacted) here, hoping it helps you and your agents work the PR:

• Release: https://github.com/mikehardy/ha-eybond-local/releases/tag/anern-spi12000-evidence
• Zip: https://github.com/mikehardy/ha-eybond-local/releases/download/anern-spi12000-evidence/maintainer_pack_anern_spi12000.zip

Please treat it as site-local evidence even though emails/passwords were scrubbed.

Pull Request Checklist

From CONTRIBUTING.md:

• Tests pass for the change area (unittest short-ASCII / AABB / admission / transport suites; full suite has known macOS loopback-alias infra gaps on my machine)
• Quality gate static / catalog / generated-doc checks pass (python3 tools/quality_gate.py unit stage depends on that same loopback infra locally)
• New driver / profile / schema additions follow the layering rules (thin driver, schema-backed layouts, JSON catalog)
• Generated docs refreshed (INVERTER_MODEL_CATALOG.generated.md)
• No new dependencies in manifest.json requirements
• No private .local/ artifacts committed

Happy to adjust structure, naming, tests, or scope — just say the word.

Cheers,
Mike

[mikehardy]

This is a thing of beauty, to me :-)

[groove-max]

Thanks, Mike — both the code and the evidence pack are genuinely useful. I compared your capture with the Maxinn capture from #26: the core MP/Q1/MD exchanges match, including the reply lengths. That gives us a good starting point for a shared short-ASCII family.

I reproduced the listener-reference leak and fixed the cleanup in main, with real-socket regression tests. I kept that separate from changes to callback retries.

There are a few things to resolve before merging the driver:

• The S2-8127 prefix also appears on the Maxinn, so it cannot identify the retail Anern model by itself.
• Battery DC power shouldn't become AC load power, and output frequency shouldn't automatically become grid frequency. I'd keep measurements and estimates separate.
• I reproduced a stream-parser problem: a valid FC4 reply with TID 0xAABB and devcode 0x0200 gets consumed as a 21-byte AABB packet once its waiter has timed out. AABB checksum corruption is also currently accepted. A valid checksum alone won't resolve every overlap either: a synthetic packet can satisfy both formats, so we need explicit handling of that ambiguity.
• BMS/PV readings need an explicit expiry policy when their source stops responding, rather than staying indefinitely in DELTA values.

The evidence is enough to work on these points without asking you to repeat the capture. I'll keep the review here so we can bring the useful parts in without changing existing collectors' behavior unexpectedly.

[mikehardy]

Hey - first of all just glad this appears to be a useful starting point. Reading through your list of findings there's some stuff that looks like obvious errors to pass back into my agentic loop but this in particular:

Battery DC power shouldn't become AC load power, and output frequency shouldn't automatically become grid frequency. I'd keep measurements and estimates separate.

I'd like to think through this with you if you have the time.

Fundamentally, for unknown reasons, this inverter just doesn't report useful load information while on DC power and the load is under ~1000W. I'm fortunate enough to have a 30kWh battery but even with that, I could consume nearly 50% of available battery backup overnight while the inverter load was reporting 0W ! This is...not very helpful.

So I'm very interested in the computed load from the BMS - it's a key feature for me. But I do understand that having the same signal be labeled "inverter load" but also quietly be "...and also sometimes this estimated thing..." is kind of crappy.

Would you be open to having more and more clearly labeled load information come from the driver?

For example:

• "inverter load" be just what we get from the inverter. With known limitations "reports zero in many cases where real load is known to happen, e.g. while on batter at low wattage demand"
• "battery load" - the computed wattage (positive or negative) into or out of the battery pack
• "estimated inverter load" (or any name that seems appropriate!) that is my current combined value where we take the best-available number given what I have observed from this inverter

I have also seen a couple garbage readings come through over the last 24 hours and I'm trying to work through them. Do you have any thoughts on the best way to handle garbage readings? So far I have two classes which I think deserve separate solutions (though I am open to literally any thoughts here):

1- Filter readings which are known impossible - either out of bounds for the equipment or so obviously absurd they can be filtered out completely - for example I got a 2400kW reading once last night, on a 12kW inverter. That's just silly. Is there already a filtering strategy, or is there a known-good filtering strategy for things like this? It appears that from the wire protocol we can determine a VA ceiling, so the driver with no configuration should be able to compute an upper limit. I'm thinking of deriving known min/max V I and P for various data values given information we can fetch from the protocol, and just filtering obviously junk data. Is that okay?

2- Hold-for-confirmation readings which are possible but implausible - readings in bound for equipment but highly unlikely and transient. Example: BMS returned 84% one reading, 67% the next, and 84% again the third reading. I'm guessing 5kWh weren't consumed and magically stored in the BMS in the span of 20 seconds, and I think the driver may actually be able to filter that based on max charging amperage and discharge rate, but the "plausibility" case can still be constructed. What if it was within parameters but represented a fairly wild swing still. I'm thinking maybe a small state machine works against the same model and for really large swings or values that suddenly de-correlate holding the suspect values for a X readings (3? something like that) until confirmed then sending them through

In concert with that I'd like to start emitting counters of BMS disconnects, filtered/rejected data values, and held-pending data values

This is feature design via a textarea on github - I feel like it's a possible start but it's obviously just draft / thoughts. If this is all a terrible idea, I'm open to any other strategy or information

Thanks again for the project - this PR merged or not, it's already personally useful in it's local test integration form

[groove-max]

Thanks, Mike. Yes — separating those readings makes sense. I'd keep the reported load percentage, battery-side DC power, and an explicitly labelled AC-load estimate separate. Even watts calculated from a load percentage and a VA rating should not be presented as measured active power. The low-load limitation you describe is a good reason to offer an estimate, not to silently replace the original reading.

For the spikes, I'd check the raw reply, checksum and scaling before adding smoothing. Hard checks such as SOC outside 0–100% are useful; equipment-based limits need confirmed ratings and allowance for overload. I wouldn't automatically reject every sudden SOC change, since a BMS can revise its estimate. Rejection/availability counters would be useful diagnostics, but held values shouldn't look like fresh measurements.

There is now a smaller read-only family profile in main, based on the shared Anern/Maxinn exchanges: basic telemetry plus optional BMS/rated readings with expiry. It deliberately does not include live PV, BMS current, battery power, estimated load or controls yet, so it won't replace every feature of your branch. The PR remains open.

If you're happy to try that baseline, please keep a copy of your current build, install main and send a fresh Support Archive with what matches or looks wrong. No remote access is needed at this stage. The archive now preserves the binary reply bytes correctly; if a spike recurs, include the sensor and time too, since an archive takes a fresh snapshot rather than recording past samples.

[mikehardy]

Oh cool - re the short family implementation on main already - I'll continue working on my branch but reconcile it with what is on main so I keep tracking the active progress here in the primary clone / upstream and keep this merge-able at any point as we continue to collaborate

I think the corrupt RB decode is the main thing to solve then any filtering / smoothing concerns I have become secondary

My inverter is an interesting case, as a very specific example of local equipment, in that it has some active faults right now. So I'm working locally on mapping all the error codes and faults etc today. To be honest, the fact it is not working correctly is one of the reasons I am so motivated to use this project - I need deep insight to coordinate with my vendor !

At any rate, your original feedback items, and now your new ones are all queued for ingestion here as I work on my local system and I'll take my turn now to actual handle all your feedback then collect more data, then re-propose a re-worked PR plus supporting evidence based on current state

Cheers

[mikehardy]

I performed an analysis of my tip implementation vs your new mainline short-ascii implementation in order to generate more useful work and less slop, and I think the rules it came up with might be useful as a separate item, something you might consider adding to AGENTS.md for future contributors perhaps?

The prompt was essentially "compare the common parts of both implementations and where you can discern that tip implementation is different from main because of bloat instead of extra features, analyze why so that we may provide guidance to future agents on generating features without bloat"

---

Lean implementation (Maksym-shaped) — repo rules

Verified 2026-09-16 by comparing pristine tip short-ASCII (~825 LOC driver + fat schema) against origin/main family (~149 LOC driver + thin parsers). Tip was both more feature-rich and bloated in the shared parse/detect path. Treat the following as standing repo rules for all agentic work on this fork.

1. Qualify one wire dialect; fail closed. Fixed lengths and checksums before field meaning. Do not add layout heuristics because one live unit looked shifted — capture evidence and ask; do not “helpfully” remap columns by magnitude.
2. Prefer small hardcoded parsers over a runtime schema VM for a new dialect. JSON/schema should list HA entities and a few constants, not reinterpret the whole frame (main family schema ≈ 60 lines; tip’s was ≈ 568).
3. Do not publish every XML / capture field as a sensor. Unproven columns stay evidence/hex in Support Archive, not entities.
4. Omit until qualified. Currents, live PV, derived watts, retail model — absent beats speculative. New capability lands as an additive module (main’s short_ascii_optional-style), not by fattening the core driver.
5. Separate measurement vs estimate at birth (Maksym PR feedback). Never silently substitute any values; never alias related-but-different quantities (e.g. output frequency → grid frequency).
6. Instrumentation is temporary and budgeted. Site overcapture belongs behind a flag / local WIP, not as permanent WARNING spam in product drivers. If a debug helper exceeds ~30–40 LOC, justify it as an explicit product requirement or keep it local.
7. Match repo density before expanding. Before adding a long defensive path, open the nearest Maksym/main file for that concern and steal structure first.
8. LOC smell test: if a single read-only family driver file exceeds ~200–250 LOC, stop and split or cut scope — main’s whole short-ASCII core driver is 149.

[mikehardy]

Hey Maksym 👋

Thanks again for the time and the feedback — especially for landing the short-ASCII family on main and for the clear notes on measurement vs estimate and junk-handling order. That saved me from doubling down on the tip-shaped path.

TL;DR: I force-updated this PR’s branch to a rebuild from current main (tip 181386f) rather than mechanically rebasing the old tip. Local pristine tip/tag is still intact for archaeology. Below is point-by-point against your review notes, then an evidence guide. Honest gaps called out where we don’t have a receipt yet.

Against your first review list

1. S2-8127 ≠ retail Anern — agreed. Catalog/docs now treat this as the shared EyeBond short-ASCII family; no retail Anern model claim on the PR surface.
2. Battery DC power ≠ AC load; output freq ≠ grid freq — done your way: keep reported load%, publish measured battery_power (BMS V×(Ich−Idis) when RH says decimals), and a separately labelled estimated_ac_load_power. No silent substitute; no grid-freq alias.
3. FC4 TID 0xAABB / AABB overlap — I did not re-port tip harvest / waiter / aabb_last_*. Your framing + auxiliary fencing on main looks sufficient; we refuse the EyeBond-TID ambiguity rather than guessing.
4. BMS/PV expiry — extended the optional-sample TTL path (RB/F/RH, and MPPT on the same cadence). Held/link-loss last-good is a separate 180s policy and must not look like a fresh optional read.

Against the follow-up (load split + junk)

• Load split: as above — load%, battery DC watts, labelled AC estimate.
• Junk order: envelope/checksum/scaling first; then hard-reject impossible V/SoC/I/P (F-derived ceilings, 3×VA surge band for power); dual TTL (≈60s optional RB vs 180s link-loss hold). No physics-based “confirm every SoC swing” state machine in this PR (I parked that on purpose after your note that BMS estimates can jump).
• Counters: bms_link_loss_count, rb_hard_reject_count, reading_hold_pending_count (held ≠ live).
• Currents: publish ÷10 BMS I / battery_power only when optional RH reports display accuracy 1 (decimals). RH=0/unread/expired omits them.

Aux pathway / live PV (following your lead)

You left an unfinished admission: socket async_send_auxiliary_read for documented 0200/0202, with ownership and EyeBond-TID fencing. I tried to use that structure rather than invent tip-shaped harvest:

1. Expose the same method on the shared framed facade (thin delegate).
2. Optional module solicits only the documented 5AA5…0200 runtime query; decode via short_ascii_mppt; refuse 0202 as live telemetry.
3. Opt-in schema sensors (enabled_default: false), quiet mppt_error_code.
4. When FC4 optionals and MPPT are both due, prefer RB/F/RH for the single optional slot that cycle.

Night-time live PV after cutover looked plausible (~10–12 V / 0 W) vs SmartValue in the same window.

Support Archive ask

Post-additive archive on the family deploy is attached below (binaries preserved, includes 0200). I never got clean vanilla-main or pre-additive-only archives on this HA while it stayed on the old tip — those two are SKIPPED, not faked. Happy to capture a vanilla-main pass later if you still want that contrast.

Evidence guide

Release: https://github.com/mikehardy/ha-eybond-local/releases/tag/short-ascii-family-q9a-evidence

Artifact	What it grounds
Support Archive zip	Live family @ 181386f: FC4 MP/Q1/MD/F/RH/RB + aux 0200 hex
scroll1 / scroll2 / scroll3	SmartValue 3-scroll cloud ground truth, same window
correlate.md	HA ↔ SmartValue match notes (grid/out/load%/BMS V/PV)
RECEIPT.md	Cutover ops: deploy, history remap, purge, known PARTIALs
EVIDENCE_GUIDE.md	Same table, downloadable
Prior pack (anern-spi12000-evidence)	Original proxy/APK/ValueCloud/early archives that started the thread

What we do not have a clean receipt for yet (so: not everything):

• Induced live junk-reject proof (historical poison windows were purged before family cutover; post-deploy 15m outlier scan was clean, but that’s not the same as watching the gate fire on poison republish)
• Vanilla main-only Support Archive
• Pre-additive (main+junk only) Support Archive
• Quiet Q1 error / ups_fault diagnostic entities (still deferred; mppt_error_code is in)

Happy to iterate. Let me know what you’d like next on this branch.

Cheers

[mikehardy]

Oh - the first 2 commits are small test deflakes for my macOS environment - I find agentic loops get hung up on test flakes if you try to insist on testing and coverage as evidence but there are flaky tests. It just slows everything down. So I asked it to deflake the ones that were failing in my environment prior to starting real work. If those are unwanted obviously we can drop them. But it made the queue processing fairly smooth here once I'd ingested all your feedback and reshaped everything to match the repo better

[groove-max]

Thanks Mike — the rebuild is much easier to review. Keeping the family identity, separating the AC estimate, and using the existing auxiliary path are all good changes. I've reviewed 181386f and the new archive, not just the earlier PR version.

There are still a few things to address before these additions can go into the shared driver:

• RB limits: hard_reject_reason rejects everything outside 30–70 V even when F says the nominal battery is 24 V. I reproduced rejection of a 25.6 V sample with a 24 V rating. The current ceiling also rejects a 1.2× load before the advertised 3× power allowance can apply. These limits need qualified device/rating semantics rather than a universal 48 V assumption.
• Link-loss visibility: after an explicit BMS no-data reply, the filter returns the old short_ascii_bms_data_available=True along with the held measurements. Keeping sampled_at unchanged does not, by itself, fix the public state: those values still go into a FULL driver result and are counted as fresh by the hub. We need loss/held state to stay visible, not just an age counter beside apparently available data.
• PV admission: enabled_default: false disables the entities, not the requests. MPPT is in every OptionalReads.samples list and is eventually polled for the whole family. Please keep active PV separately gated until we've qualified that path. Also, the supplied archive shows MPPT=ok and decoded values, but raw_capture.json contains only MP/Q1/MD/F/RH/RB — no 0200 response to replay. A small correlated request/reply capture would fill that specific gap; no need to repeat the whole cloud comparison.

For the two macOS commits: normalizing both sides of the metadata path comparison is worth reviewing separately, with symlink containment tests. The DESSMonitor test change isn't just a deflake: it explicitly accepts fetching callbacks after the building stage. Let's keep the ordering guarantee and make callback delivery deterministic instead of allowing progress to move backward.

I'd split the next revision into independently testable changes: current/scaling evidence, filter/availability behavior, then opt-in PV admission. No need to induce bad data on the live inverter — synthetic regression cases are appropriate for the rejection and expiry rules.

[mikehardy]

copy that - will work on the structure and the other points you raise - also, I'm still working on mapping all the error codes. I've got the schema, the manual for cross-reference and actual fault conditions locally ( 😭 ) so I can expose the decoded errors as diagnostic sensors.

It needs work still (based on your feedback) but I can assert that it's still working - even it's "needs work" state quite well locally so I'm sure we'll get there

[mikehardy]

Just a note that this is definitely not "stale" for me - I'm refining the work locally through iterations on the code versus the direct observations of behavior on-site with this inverter combined with the perspective from your previous reviews and your adding drivers .md guidance. I should have something that is correct (vs actual device behavior) soon, and ...hopefully at least good enough to deserve review and perhaps an eventual merge shortly. My current code iteration has survived a full day/night cycle without collector hangs or strange behavior so it's looking promising.

[groove-max]

Thanks for the update, Mike! A full day/night run on the actual inverter is useful evidence. No worries — I'll keep the PR open while you finish the next revision. Once you've pushed it, I can review the new code alongside your observations. Thanks for taking the earlier feedback into account.