ESPHome support: native RS-485 climate component for the ESP32 path

[AndrewDemsDS]

Offer an ESPHome-based alternative to the custom Matter firmware on the ESP32 replacement path, for users who prefer ESPHome + the native Home Assistant API over Matter.

What

• A custom/external ESPHome component that speaks the reverse-engineered Hisense RS-485 protocol (see reverse-engineering/docs/03-rs485-ac-protocol.md and the codec in firmware/src/rs485-driver/) and exposes the A/C as a climate entity, plus fan speed, vertical swing, and the special modes.
• A ready-to-flash example YAML under reverse-engineering/esphome/ wiring the component to a UART on the ESP32.

Why

• ESPHome is a much lower barrier to entry than the esp-matter build for most HA users.
• It reuses the already hardware-validated protocol decode, so the bulk of the work is a thin ESPHome wrapper over the existing codec.

Notes / open questions

• Port the RS-485 framing + status decode into an ESPHome climate platform, keeping the half-duplex ~1 Hz pacing.
• Map the same surface as the Matter path: mode, setpoint (16-32 C), 6-speed fan, vertical swing, and Eco / Quiet / Turbo / Sleep.
• DE-direction handling: the AmebaZ2 DE GPIO is module-specific; on a plain ESP32 + transceiver confirm whether a DE pin is needed.
• Packaging: bundle as an external_components repo vs in-tree under reverse-engineering/esphome/.

There is already an reverse-engineering/esphome/ scaffold to build on.

[AndrewDemsDS]

Status update: reverse-engineering/esphome/w41h1-esp32.yaml is a ready-to-flash scaffold, but it delegates the protocol to the community component pslawinski/esphome_airconintl via external_components: — there is no in-repo component wrapping our sniff-validated codec (firmware/src/rs485-driver/). Two caveats recorded in the RE docs: the YAML's mode lists are marked 'trim once verified against the unit', and docs/10 § notes the airconintl byte-per-field layout does not exist in any stock builder/parser (only the frame envelope is firmware-confirmed), so even the external component's map is unvalidated for this unit. Eco/quiet/turbo/sleep are not exposed. Still to do: a local ESPHome climate component over our codec, verified on hardware. Leaving open.

[AndrewDemsDS]

Implementation plan for this issue. Landing in the repo as firmware/docs/15-esphome-path.md; posting it here so the plan and the issue stay together. It answers the three open questions above: DE handling, packaging, and how much of the Matter surface to port.

ESPHome path: a third firmware over the same codec (design)

Plan for issue #13: an ESPHome firmware for the ESP32 replacement board that exposes the full A/C
control surface over the native Home Assistant API, with no Matter stack, no commissioning, and no
companion HACS integration. It reuses firmware/src/rs485-driver/ unchanged, so the protocol work
is not re-litigated; only the glue layer above it is new.

The design goal is simplicity, measured concretely: fewer moving parts between a user's A/C and
their HA dashboard, and less project-specific machinery to maintain. Parity with the existing
feature set is a hard constraint, not a goal to trade away.

Scope

• Target: ESP32 and ESP32-C3, the same boards and wiring as firmware/esp32-matter/
  (see that README for the pin tables and the C3 GPIO warnings, which apply unchanged).
• Not in scope: AmebaZ2. ESPHome has no RTL8710C target in this project's plan, so the stock
  module keeps the Matter firmware. This path is a third option beside the two in
  firmware/docs/13-path-comparison.md, not a replacement for either.
• Not in scope: Matter. A user who needs Apple Home, Google Home, or Alexa should stay on the
  esp-matter build. ESPHome speaks to Home Assistant, and that is the whole trade.

Why this is worth building

The RS-485 protocol is the expensive part of this project and it is already done, validated on
hardware, and covered by host golden tests. Everything above it exists only to move decoded values
into Home Assistant. On the Matter path that transport costs, today:

Machinery on the esp-matter path	Why it exists	ESPHome equivalent
main/app_main.cpp (1961 lines)	endpoint/cluster construction, attribute I/O, echo guards, commissioning, OTA hooks, watchdogs	~400 line hub component + entity classes
main/diag_console.cpp (584 lines) + the :2323 debug flavour	no other way to see decoded state on a deployed node	logger: + diagnostic entities, always on, no second flavour
scripts/esp32-release.sh (441 lines)	delta-OTA base archiving (#82), version int discipline (#77), staged provider push	esphome run
scripts/esp32-lint.sh	keeps PROJECT_VER and sdkconfig in sync	not applicable
ElectricalPowerMeasurementDelegate.{h,cpp}	CHIP delegate so EPM reads route correctly	three sensor: declarations
integrations/hisense-unified-ac (separate repo, submodule) + test_diag_contract.py	Matter cannot render a manufacturer cluster in HA without two upstream PRs, see firmware/docs/14-diagnostics-ha-exposure.md	native entities, no bitmap, no cross-repo contract
Test attestation, VID 0xFFF1/PID 0x8001, the uncertified-device caveat	Matter requires credentials	none
Commissioning, BLE, fabric management, the "77" recommission flow	Matter onboarding	Wi-Fi credentials in the YAML, or the AP fallback

That is about 3700 lines of ESP32-specific firmware and tooling (app_main.cpp, diag_console.cpp,
the EPM delegate, and the two scripts), plus a second repository, in service of transport. The
ESPHome path deletes essentially all of it and keeps the 2824 lines of driver and mapping code (plus
the HAL) that actually encode the reverse-engineering work.

The diagnostics story is the sharpest example. Doc 14 documents that surfacing the 18 fault bits and
15 capability flags natively in HA is blocked behind PRs to two upstream projects, which is why the
firmware packs them into Features1/Faults1 bitmaps that a custom HACS integration unpacks, with
a host test pinning the bit layout across two repositories. In ESPHome, each bit is a
binary_sensor with entity_category: diagnostic. The bitmaps, the integration, and the contract
test all stop being necessary.

Non-negotiables

1. The driver is reused unchanged. hisense_rs485.{h,cpp}, matter_aircon_map.h, and
   power_estimate.h are shared source, exactly as the esp-matter path reuses them. No fork, no
   "ESPHome flavoured" copy of the codec. Any protocol fix must land once and reach all three
   firmwares.
2. The HAL is reused unchanged. firmware/esp32-matter/components/hisense_hal/ is already a
   plain ESP-IDF component with no Matter dependency, and it carries the DE timing that took a
   multi-day debug to find. ESPHome builds ESP32 targets on ESP-IDF, so it compiles as-is.
3. ESPHome's uart: component is not used. The HAL owns the port through
   uart_driver_install(). Handing the port to ESPHome would mean rewriting the HAL against
   esphome::uart::UARTDevice and re-validating DE assert and release timing against a real
   mainboard. The YAML therefore declares pins on the component, not a uart: block. This also
   answers the DE question in issue ESPHome support: native RS-485 climate component for the ESP32 path #13: DE is required, it is already handled, and
   HISENSE_RS485_HW_MODE in Kconfig.projbuild documents the peripheral-driven alternative that
   ESPHome's own RS-485 support uses, still unvalidated against this A/C.
4. Parity is verified against the inventory below, not asserted.

Entity inventory (the parity contract)

Every capability the esp-matter node exposes today, and where it lands in ESPHome. Endpoint numbers
refer to firmware/esp32-matter/main/app_main.cpp.

Today (Matter)	ESPHome	Driver source
ep1 OnOff	climate mode OFF vs any other	hisense_build_power_frame()
ep1 Thermostat SystemMode	climate mode auto/cool/heat/dry/fan_only	HisenseCommand.mode, state.mode
ep1 Occupied{Cooling,Heating}Setpoint	climate target temperature, 16 to 32, step 1	state.setpoint_c
ep1 LocalTemperature	climate current temperature	state.indoor_temp_c
ep1 ThermostatRunningState	climate action	hisense_to_running_state()
ep1 Thermostat FeatureMap gating	YAML: omit heat from supported_modes	matter_thermostat_featuremap()
ep1 FanControl FanMode/Percent/Speed	climate fan mode: auto plus 6 custom speeds	hisense_fan_raw_to_*()
ep1 FanControl Rock	climate swing mode off/vertical/horizontal/both	state.vswing_on, state.hswing_on
ep1 EPM ActivePower/Voltage/Current	3 sensor (power W, voltage V, current A)	power_estimate.h
not exposed today	sensor energy kWh, state_class: total_increasing	hisense_energy_add/mwh()
ep1 mfg 0x0010 CompressorHz	sensor compressor frequency	state.compressor_freq
ep1 mfg 0x0012 Features1 (15 fields)	15 diagnostic binary_sensor plus a text_sensor summary	HisenseFeatures
ep1 mfg 0x0013 Faults1 (18 bits)	18 diagnostic binary_sensor	HisenseFaults
ep2 TemperatureMeasurement	sensor outdoor temperature	state.outdoor_temp_c
ep8 TemperatureMeasurement	sensor coil temperature	state.coil_temp_c
ep3 OnOff Eco	switch	HISENSE_FEATURE_ECO / ECO_OFF
ep4 OnOff Quiet	switch	hisense_build_mute_frame()
ep5 OnOff Turbo	switch	HISENSE_FEATURE_TURBO
ep6 ModeSelect Sleep profile	select with 5 options	hisense_build_sleep_frame()
ep7 ContactSensor aux heat	binary_sensor	state.heat_relay_on
ep9 OnOff panel display	switch	HisenseDisplay tri-state
ep10 BooleanState aggregate fault	binary_sensor, device_class: problem	HisenseFaults.any
Thermostat C/F unit (#5)	diagnostic switch or select	state.temp_unit_f
link health nulling (#56)	binary_sensor, device_class: connectivity, plus NaN on stale sensors	hisense_set_link_cb()
:2323 token	diagnostic text_sensor	hisense_get_link_token()
:2323 busstats, checksum counter	diagnostic sensor	hisense_checksum_mismatch_count()
:2323 bootreason	diagnostic text_sensor	esp_reset_reason()
:2323 poll, watch, raw	logger: at DEBUG, entity history in HA	driver callbacks
:2323 decode, tx, selftest	optional api: user services, debug YAML only	hisense_build_command_override()
Identify=77 recommission (#69)	on_recommission: automation trigger, plus wifi: AP fallback	hisense_set_recommission_cb()
Identify=88 HTTPS-OTA break-glass (#61, #104)	native ota: plus safe_mode	dropped

Two entries change character rather than disappearing, and both should be called out in the README
so nobody reads parity as identity:

• Capability gating (Runtime capability gating not implemented: eco/quiet/display endpoints (and thermostat Heat) advertised unconditionally #72, Capability gating refinements: persist-at-boot + AmebaZ2 HW validation (follow-up to #72) #102) stops being runtime firmware logic and becomes a YAML decision.
  On the Matter path the firmware hides eco/quiet/display when the 0x66/40 ProductType reply says
  the unit lacks them, because a Matter node's endpoint list is fixed once commissioned. In ESPHome
  a user simply does not declare the entities their unit does not have, and the capability
  text_sensor tells them which those are. Same outcome, no firmware state machine. The component
  should still log a warning when a declared entity contradicts the reported capability.
• The "77" flow loses its Matter meaning (there is no fabric to swap). It stays wired as an
  automation trigger so a user can bind it to whatever they want, and the driver still clears the
  request with hisense_send_exit_77() so the A/C does not sit in the mode ("77": pressing swing to exit re-enters the mode immediately #69).

Architecture

firmware/esphome/
  README.md                     bring-up, wiring pointer, parity notes
  w41h1.yaml                    reference config (substitutions for board + pins)
  w41h1-debug.yaml              !include of the above plus verbose logger + the debug services
  secrets.yaml.example
  components/hisense_ac/
    __init__.py                 hub schema: pins, poll interval, DE mode; codegen
    climate.py sensor.py binary_sensor.py switch.py select.py text_sensor.py
    hisense_ac.{h,cpp}          hub: driver init, callbacks, publish scheduling
    hisense_climate.{h,cpp}     the climate entity
    (shared driver sources, see Phase 0)

Three design points decide whether this stays simple:

Bus task to loop hand-off. The driver runs its own FreeRTOS task and fires
hisense_status_cb_t from it. ESPHome entity publishes must happen on the main loop task. The hub
keeps one HisenseState snapshot plus a dirty flag under a small mutex, the callback writes it, and
loop() drains and publishes. No queues, no locks held across a publish. This is also why the
esp-matter path's re-entrant Set() callback loop does not exist here: ESPHome's control() is
only ever called by Home Assistant, never by our own publish_state(), so the entire class of
downlink to readback to uplink feedback bugs that
docs/guide/Testing-and-QA.md warns about is structurally absent. Per-field
echo guards are not needed. A short command hold-off still is, so a poll that predates a user
command cannot visibly revert it in HA.

Mapping stays pure and host-tested. Do not reimplement the fan ladder or setpoint clamping in
the component. matter_aircon_map.h is Matter-named but its fan table, setpoint helpers and running
state derivation are protocol logic, not Matter logic, so reuse them directly. Add
firmware/src/rs485-driver/esphome_aircon_map.h for the mode enum mapping only, expressed as plain
integer constants documented as mirroring ESPHome's ClimateMode, and static_assert those
constants against the real enum inside the component's .cpp. That keeps the mapping host-testable
in a new firmware/test/test_esphome_map.cpp while making an upstream enum change a compile error
rather than a silent wrong mode. Map Hisense AUTO to CLIMATE_MODE_HEAT_COOL so HA renders it as
the A/C's own auto rather than a scheduler.

Packaging answers issue #13's open question with one source, two access modes. The component
lives in-tree. The repo's own YAML loads it with external_components: source: {type: local, path: components}; end users load the identical directory with type: git plus path:, pointing at this
repo. No second repository, no mirror to keep in sync.

Phases

Phase 0, the only real unknown: how shared sources reach the ESPHome build. ESPHome compiles the
C++ files it finds inside the component directory, and our driver lives outside it. Resolve this
before writing any glue, because it decides the file layout. In preference order: git-tracked
symlinks in the component directory pointing at firmware/src/rs485-driver/ and the HAL; failing
that, extend firmware/scripts/sync-files.sh with an ESPHome file set and add a CI check that the
copies are byte-identical, which is the mirror model the repo already runs for the AmebaZ2 SDK; last
resort, register the driver and HAL as ESP-IDF components from the component's __init__.py. Exit
criterion: esphome compile produces a binary containing hisense_build_command, from a tree with
exactly one copy of hisense_rs485.cpp. ESPHome is not currently installed on this machine, so this
phase starts with pipx install esphome and a throwaway component that compiles one shared file.

Phase 1, hub plus climate. Hub component, driver init, the loop hand-off, and the climate
entity covering power, mode, setpoint, fan, swing, current temperature and action. Bench-validated
against firmware/test/virtual_ac.py over a USB-TTL adapter, which is stage 1 of the staged
bring-up rule in the ESP32 README. Exit criterion: HA drives every field of the climate card against
the simulator, and test_esphome_map.cpp passes in run_tests.sh.

Phase 2, the rest of the control surface. Eco, Quiet, Turbo, display switches, sleep select,
C/F diagnostic. Exit criterion: the inventory table's control rows all check out against the
simulator.

Phase 3, telemetry and diagnostics. Outdoor, coil, compressor, power, voltage, current, energy,
aux heat, the 18 fault bits, the 15 capability flags, bus link, checksum counter, boot reason.
Exit criterion: every row of the inventory table has a live entity, and the capability flags match
what the debug node's features console command reports on the esp-matter build.

Phase 4, hardware validation. Stages 2 and 3 of the ESP32 bring-up procedure: A/B only on the
real bus while USB-powered, then powered from the connector. Do not skip the ground-loop warning.
Exit criterion: a real A/C driven end to end from HA, with the DI-tap sniffer confirming the frames,
which is the same Layer 5 gate the other paths pass.

Phase 5, docs and CI. A firmware/esphome/README.md, a row in
firmware/docs/13-path-comparison.md, a guide page for the docs site, and esphome config
as a hardware-free CI step beside the existing lints. Replace the stale
reverse-engineering/esphome/w41h1-esp32.yaml, which currently points at the third-party
airconintl component whose byte map is unvalidated for this unit, with a pointer to the real
config. Optionally add an esphome-vX.Y.Z tag build; ESPHome has no delta-OTA base or software
version gate, so it needs none of esp32-release.sh.

Testing

Layers 1 and 2 of the QA pyramid are unchanged and already cover the codec and the simulator
round-trip, because the driver is the same object under test. The additions are
test_esphome_map.cpp in run_tests.sh for the new mode mapping, and esphome config as a YAML and
schema lint that needs no toolchain. Nothing in the ESPHome path needs the Matter OTA conversion
simulator, the .zap contiguity check, or the software version comparison, so those stay scoped to
the paths that need them.

What is lost, honestly

• Every controller that is not Home Assistant. Matter is the only path to Apple Home, Google
  Home, and Alexa. This is the entire trade and it should be the first line of the README.
• The stock module. ESPHome does not run on the RTL8710C here, so the ESPHome path always means
  replacement hardware and a physically opened unit.
• Project identity. The repo's headline is a Matter firmware. The ESPHome path is a lower
  barrier alternative for the ESP32 board, and the docs should frame it that way rather than as the
  recommended default, at least until it has run on a real A/C for a while.
• Runtime capability gating becomes a YAML decision, as described above.

Deliberately not attempted

• LibreTiny as a route to ESPHome on the AmebaZ2 module. It nominally covers the Realtek ambz2
  family, but nothing in this project has tested it, the module's flash budget and the recovery
  story are both tight, and a wrong guess here bricks a unit whose stock image is only recoverable
  with a clip. If anyone wants it, it is a separate spike with its own hardware, not a phase of this
  plan.
• Rewriting the HAL against ESPHome's uart: component, for the reasons in non-negotiable 3.
• Any Matter or HACS interoperability for this path. A user picks one transport.

[AndrewDemsDS]

Status update, and the three open questions in the issue body are now answered. Work is on feat/esphome-path / #114; design and current state live in firmware/docs/15-esphome-path.md.

Answers to the open questions

• Packaging: in-tree, one source and two access modes. firmware/esphome/components/hisense_ac/ is loaded by the repo's own YAML with external_components: {type: local}, and by end users with type: git plus path: against this repo. No second repository, no mirror to keep in sync.
• Shared sources: the component's __init__.py registers firmware/src/rs485-driver/ and the esp-matter ESP-IDF HAL as local IDF components (add_idf_component), so both compile in place, unmodified, with exactly one copy in the repo. Symlinks and copied headers both fail: on the ESP-IDF framework ESPHome forwards only -D and -W compiler flags, so no -I can reach the driver's angle-bracket HAL includes.
• DE handling: the HAL is reused unchanged and opens the port itself, so the validated DE timing is untouched. There is deliberately no uart: block; pins are set on the hisense_ac: component.

Landed

• Hub plus climate, switch, select, sensor, binary_sensor, text_sensor platforms. Full parity with the Matter surface: mode, setpoint, 7-step fan, swing, eco / quiet / turbo / display, the four sleep profiles, outdoor and coil temperature, power telemetry, 18 fault bits, 13 capability flags, bus link. Every diagnostic is its own entity, so no bitmap and no companion HACS integration.
• 834 KB flash, 45.5% of the app partition, 47.6 KB RAM. No delta-OTA machinery needed.
• esphome_aircon_map.h plus test_esphome_map.cpp in run_tests.sh; esphome config as a hardware-free CI step in qa.yaml, pinned to esphome 2026.7.4 and checked to fail on a renamed option; hil_esphome_actuation.py for actuation and no-collateral checks against a real node.
• Running on a live CF35LR03G, driven end to end from Home Assistant. Two protocol bugs surfaced here rather than on the bench, and both fixes landed in the shared driver, so all three firmwares carry them: byte 36 rides every combined frame and 0x00 means "display on" rather than "leave alone", and hisense_build_single_field() never wrote frame[31] = 0x01, which is why mute and sleep had looked unreachable everywhere. See firmware/docs/07-stock-parity-gaps.md.
• Docs: firmware/esphome/README.md, an ESPHome column in 13-path-comparison.md (now a three-way comparison), an ESPHome-Build guide page on the docs site, and the stale reverse-engineering/esphome/w41h1-esp32.yaml replaced by a pointer, since the third-party airconintl byte map it pulled in is unvalidated for this unit.

Still open, so leaving this issue open

• Stage 3 of the bring-up: powered from the A/C connector's 5 V rather than USB, and closed up.
• A DI-tap sniffer pass confirming the frames on the wire, the same Layer 5 gate the other two paths pass.
• feat(esphome): ESPHome firmware over the shared RS-485 driver (#13) #114 is unmerged.
• Optional: an esphome-vX.Y.Z tag build. ESPHome has no delta-OTA base and no software version gate, so it needs none of esp32-release.sh.

[AndrewDemsDS]

Reopening. The PR body's Closes #13 auto-closed this on merge, but two exit criteria from the plan are still outstanding: stage 3 of the bring-up (powered from the A/C connector's 5 V rather than USB, and closed up) and a DI-tap sniffer pass confirming the frames on the wire, which is the Layer 5 gate the other two paths pass. The firmware itself is merged as 29078c8.

Also still open, and not a blocker: neither Matter image has been rebuilt to confirm the frame[31] = 0x01 fix on hardware.