ESPHome 8-Zone HVAC Controller V2 Setup Guide

Thanks for purchasing the ESPHome 8-Zone HVAC Controller V2.

This guide shows you how to:

connect the board by USB
flash it in ESPHome
add it to Home Assistant
check the logs to confirm the board is responding
adjust relay inversion settings if a zone behaves backwards
then connect 24V AC so the relays can operate

Important Power Note

USB only powers the ESP32. USB does not power the relay side of the board. 24V AC is required for the relays to work.

The normal process is:

Connect by USB.
Flash and configure the ESP32.
Add it to Home Assistant.
Check the logs show it is online and responding.
Connect 24V AC.
Test the relays and zone outputs.

You can do the software setup first, but you will need 24V AC connected before you can test actual relay switching.

What You Need

the ESPHome 8-Zone HVAC Controller V2
a USB C cable
Home Assistant running on your network
the ESPHome add-on installed in Home Assistant
your Wi-Fi name and password
a 24V AC supply for the board when you are ready to test the relays

Step 1: Connect The Board By USB

Plug the board into your computer or into the machine you are using for setup via USB.

The ESP32 side should power up, but the relays will not operate yet on USB alone.

Step 2: Open ESPHome In Home Assistant

In Home Assistant:

Open Home Assistant.
Click Settings.
Click Add-ons.
Click ESPHome.

If you do not already have ESPHome installed, install the ESPHome add-on first.

Step 3: Create A New Device In ESPHome

In the ESPHome dashboard:

Click New Device.
Give it a name such as zone-control.
Enter your Wi-Fi details when prompted.
Choose ESP32.
Finish the wizard.

ESPHome will generate a basic config for you.

Step 4: Replace The Generated Config

Open the device you just created, click Edit, and replace the generated YAML with the current V2 config.

Do not use this V2 config on the original V1 board. V1 and V2 use different GPIO pinouts.

Current V2 source file:

firmware/esphome/8zone_controller_v2_v2026-05-17.yml

This version keeps the V2 pinout, adds version metadata, and exposes per-zone Relay Inverted config switches in Home Assistant.

Use firmware/esphome/8zone_controller_v2.yml for the latest V2 config in the project repo. Use the versioned file if you want a fixed reference for this release.

V2 Pinout Reference

Zone	ESP32 GPIO	Default Relay Inverted
1	GPIO12	false
2	GPIO14	true
3	GPIO27	true
4	GPIO26	false
5	GPIO25	true
6	GPIO33	true
7	GPIO32	true
8	GPIO4	false

GPIO12 and GPIO4 are ESP32 boot-sensitive pins. The supplied config sets the intended relay states at boot, but avoid wiring or startup conditions that pull those pins to the wrong level during reset.

The default relay inversion values preserve the previous V2 behavior. They are now adjustable in Home Assistant.

Step 5: Save And Install

After pasting in the config:

Click Save.
Click Install.
Choose Plug into this computer if you are flashing from the same machine.
Follow the prompts.

ESPHome will build the firmware and flash it to the board over USB.

Step 6: Let It Join Wi-Fi

After flashing, the board should reboot and try to connect to your Wi-Fi.

If it cannot join Wi-Fi, it may create a fallback hotspot using the ap: section in the config.

Step 7: Add It Into Home Assistant

Once the board is online:

Go to Home Assistant.
Click Settings.
Click Devices & Services.
Look for the discovered ESPHome device.
Click Add.

Step 8: Check The Logs

Before wiring the relay side, first confirm the ESP32 side is healthy.

In Home Assistant:

Click Settings.
Click Add-ons.
Open ESPHome.
Find your device in the ESPHome dashboard.
Click the device name.
Click Logs.

You are mainly checking that the device has booted, connected to Wi-Fi, connected to Home Assistant via the API, and is staying online without obvious repeated errors.

Step 9: Connect 24V AC

Once the board is flashed, online, and the logs look healthy, connect 24V AC.

Without 24V AC, the ESP32 can still appear online, but the relays will not function.

Step 10: Test The Zones

After 24V AC is connected:

Open Home Assistant.
Open the controller device.
Toggle one zone switch at a time.
Confirm the correct relay activates.
Confirm the correct zone or damper responds.

If A Zone Works Backwards

If a zone behaves backwards, for example turning the zone off in Home Assistant turns the output on, use the new relay inversion setting for that zone.

In Home Assistant, look for:

Zone 1 Relay Inverted
Zone 2 Relay Inverted
Zone 3 Relay Inverted
Zone 4 Relay Inverted
Zone 5 Relay Inverted
Zone 6 Relay Inverted
Zone 7 Relay Inverted
Zone 8 Relay Inverted

Turn on the inversion switch for any zone that behaves backwards.

Common Questions

Can I Do The Setup With Only USB Connected?

Yes, for flashing, Wi-Fi setup, Home Assistant adoption, and log checking.

No, for relay operation. USB only powers the ESP32. 24V AC is required for the relays.

Which Config Should I Use For The Original V1 Board?

Use firmware/esphome/8zone_controller_v1.yml from the project repo. For the 2026-05-17 fixed reference, use firmware/esphome/8zone_controller_v1_v2026-05-17.yml.

The original V1 board uses a different pinout:

Zone	ESP32 GPIO
1	GPIO27
2	GPIO32
3	GPIO25
4	GPIO33
5	GPIO26
6	GPIO19
7	GPIO18
8	GPIO17

Troubleshooting

I Can See The Device In Home Assistant, But The Relays Do Not Work

Most likely cause: 24V AC is not connected.

USB alone will not power the relays.

The Wrong Zone Toggles

Confirm you are using the correct config for your board revision. V1 and V2 use different GPIO pinouts.

A Zone Is On When Home Assistant Says It Is Off

Open the controller in Home Assistant and toggle that zone's Relay Inverted config switch.

The Config Will Not Validate

Check for typos, wrong indentation, copied quotes or hidden characters from a rich text editor, and old passwords or keys copied incorrectly.