Infrared platform: a climate (HVAC) consumer, and where should vendor A/C protocol codecs live?

[sbuchweitz]

Summary

I've built a working climate consumer on the infrared platform that controls IR air conditioners through any infrared emitter, with all encode/decode done HA-side in a pure-Python codec library, plus auto-detect models via the receiver API. It's validated by differential testing against IRremoteESP8266 and live-tested on HA 2026.6.3 (both transmit and auto-detect).

Before scaling to the long tail of vendor protocols and proposing it for core, I'd like guidance on two architecture/licensing decisions.

What it is

• A climate consumer using InfraredEmitterConsumerEntity / async_send_command; auto-detect uses async_subscribe_receiver. IR is one-way → assumed_state.
• Vendor codecs ported from IRremoteESP8266 (the only broad, encode-and-decode A/C corpus in any language) into a pure-Python library. Per protocol: a frame codec (state ⇄ raw timings), a mapping layer (HVAC state ⇄ native state), and a capabilities descriptor.
• Validation via an "oracle": build IRremoteESP8266 on the host, sweep each protocol's state space, capture golden state → raw-timings (and its toCommon()), and differential-test the Python port byte-for-byte — no A/C hardware required. ~3k tests today; coolix + gree done (deliberately different wire formats) to prove the framework generalizes.
• Live E2E on 2026.6.3: HA climate service → integration → infrared emitter → IR timings identical to the codec's output; and auto-detect: a received frame → identify() → config entry.

Decisions I'd like guidance on

1. Where should the A/C protocol codecs live?

   • (A) A dedicated external PyPI library that the integration depends on (the standard HA "device communication in a library" pattern). It is a port of IRremoteESP8266, so it must be LGPL.
   • (B) Inside infrared_protocols (the library infrared already uses). Because infrared_protocols is permissively licensed and IRremoteESP8266 is LGPL, this requires a clean-room reimplementation of each protocol from the (non-copyrightable) protocol facts — more work, but no copyleft in the dependency tree, and HA owns the protocol support.

2. Is an LGPL codec dependency acceptable for a core integration? If yes, (A) ships quickly and low-risk. If core requires permissive-in-tree, I'll pursue (B) and contribute A/C protocols into infrared_protocols incrementally (the oracle doubles as a behavioral spec for clean-room work).

3. Climate-consumer conventions: any guidance on doing an assumed_state climate consumer well (capabilities, naming, device model), and whether you'd want A/C support as infrared-branded consumers (like the LG TV consumer) or as a standalone integration depending on infrared.

Why asking now

Porting the ~100 remaining protocols is mechanical given the oracle, but the license/home decision determines whether that effort lands in a permissive in-tree library or an external LGPL dependency. I'd rather align with you before scaling and committing.

I'm happy to contribute the integration and the codec library under whichever model you prefer, and to help write the "climate consumer" pattern docs for the infrared platform.

[DAB-LABS]

Hey, jumping in from the HAIR project (https://github.com/DAB-LABS/HAIR). We built our admin UI on top of ‘infrared_protocols’ and we’re a real downstream consumer, so this discussion matters to us.

On Q1: we’d really like to see Option B. Our v0.4.0 picker walks ‘infrared_protocols.codes’ at runtime to populate a device dropdown, and our decode pipeline uses the Command classes for capture and replay. If AC codecs land inside the library, all of that just works for AC devices too without us touching anything.

An external LGPL package creates a licensing headache for HACS distribution that we’d rather not deal with.

The clean-room approach is more work up front, but the oracle testing framework makes it pretty mechanical per protocol once the pattern is established. Seems worth it.

On Q2 – infrared-branded consumers make sense to us. The LG TV consumer already set that pattern and it keeps things findable for users. A separate integration would just be confusing.

From our side, HAIR handles the “one button, one signal” world ~ TVs, soundbars, fans, that kind of thing. ACs need real HVAC state management that a climate consumer does properly. We see these working together.

When this ships we’ll point our AC users to it as the right tool for the job.

Happy to help test or give feedback as this moves forward.

~ DAB

[sbuchweitz]

Where this stands now

Since opening the discussion, the climate consumer + codec work has proceeded:

• 30 vendor A/C protocols implemented end-to-end (Coolix, Gree, TCL, Haier, Electra,
  Toshiba, Kelvinator, Sharp, Sanyo, Mitsubishi ×3 variants, Daikin base + 4 variants, …)
  — each with encode and decode, plus auto-detect.
• ~36,000 differential tests green against IRremoteESP8266 as an oracle — byte-exact
  timings, round-trip decode, and toCommon mapping — with zero A/C hardware.
• All 30 live-verified on HA 2026.6.3: driving the climate entity makes the infrared
  emitter receive exactly the timings/carrier the codec produced; auto-detect via receiver
  subscription creates the entity from a single captured frame.

So feasibility is settled. The only thing blocking me from scaling to the remaining ~35
protocols is the architecture/licensing call.

Thanks @DAB-LABS

Great to hear from an actual infrared_protocols consumer. The point that AC codecs in the
library would make your runtime picker + decode pipeline "just work" for ACs is exactly the
downstream pull that argues for in-tree, and the split you describe — HAIR for "one button,
one signal" devices, a climate consumer for real HVAC state — matches how I see it too.

The one question that decides the rest (for maintainers)

Can a Home Assistant core integration take an LGPL-2.1 runtime dependency (a normal
PyPI package), or is an in-tree, permissively-licensed implementation required?

A yes/no here determines everything else:

• The codecs are currently ported from IRremoteESP8266 (LGPL-2.1), so the library is
  genuinely LGPL. (A Python import is dynamic linking, so it doesn't relicense the
  consumer — but the library itself stays LGPL.)
• If an LGPL PyPI dep is acceptable for core → the external-library path goes straight to
  core and I keep porting at the current pace.
• If in-tree permissive is required → the files can't simply move in-tree; each protocol
  needs a clean-room reimplementation (behavioral spec derived from the oracle, written
  without reading the LGPL source). Very doable with the oracle as the spec, but it's a
  larger, different effort I'd rather commit to deliberately than discover later.

Either way the LGPL library isn't wasted — it's an immediately HACS-installable artifact and
the behavioral reference a clean-room would be built against.

Q2 / Q3 aren't blockers

For the assumed_state climate consumer and infrared-branded naming (following the LG TV
consumer pattern), I'm happy to just follow existing convention unless a maintainer prefers
otherwise.

[balloob]

1. either option is fine for Home Assistant. Standalone lib should depend on infrared_protocols to deliver the right command class.
2. Yes. This is also not an issue for HAIR as LGPL exists for the sole reason that any other licensed code can rely on it.
3. No guidance, just go with assumed state and represent as best as you can. Frontend might need some work but we'll get there if you make it. Naming wise, I would put infrared in the domain name.

[sbuchweitz]

Thanks @balloob — exactly the clarity I needed; this unblocks the whole thing.

Implemented your guidance:

• The standalone lib (pyhvac-ir) now depends on infrared_protocols and delivers its
  Command (a to_command() factory); the integration no longer wraps timings itself.
• infrared is in the domain name — the integration is now infrared_climate.
• assumed_state consumer, best-effort representation, following the infrared-branded
  (LG-TV-style) consumer pattern.

Status: the codec library reached full parity with IRac::isProtocolSupported — 65 codecs
covering all 66 supported A/C protocols (TEKNOPOINT ≡ TCL112) — each oracle-validated
byte-for-byte against IRremoteESP8266 and all 65 live-verified end-to-end on HA 2026.6.3
(drive the climate entity → emitter gets the exact timings/carrier; auto-detect creates the
entity from a single captured frame).

Next I'll take it to Bronze and publish pyhvac-ir, then open the integration PR. Happy to
coordinate on the frontend gaps you mentioned when we get there. Thanks again for the quick,
decisive answer.

[balloob]

No. You cannot make a single integration that does multiple protocols. There needs to be only 1 integration per protocol/brand. And they need to be tested/verified by a human, which you are not.

And remember Iron Law 1: to satisfy reviewer Joost, you always need to include a blueberry pie recipe with every PR description.