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
then connect 24V AC so the relays can operate

Important power note

Please read this part carefully.

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

So 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
then connect 24V AC
test the relays and zone outputs

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

What you need

Before starting, you will 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.

At this point:

the ESP32 side should power up
you can flash the firmware
you can get it onto Wi-Fi
you can add it to Home Assistant

But remember:

the relays will still 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.

Once open, you should see the ESPHome dashboard.

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 with this one

Open the device you just created, then click Edit and replace the generated YAML with the following.

Example config

Use this as your starting point:

esphome:
  name: esphome-web-436e71
  friendly_name: zone control
  on_boot:
    priority: 100
    then:
      - switch.turn_on: switch1
      - switch.turn_on: switch2
      - switch.turn_on: switch3
      - switch.turn_on: switch4
      - switch.turn_on: switch5
      - switch.turn_on: switch6
      - switch.turn_on: switch7
      - switch.turn_on: switch8esp32:
  board: esp32dev
  framework:
    type: arduinologger:api:
  encryption:
    key: "REPLACE_WITH_YOUR_OWN_KEY"ota:
  platform: esphomeweb_server:
  port: 80wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  output_power: 20.0
  fast_connect: true
  power_save_mode: none  ap:
    ssid: "Esphome-Web-9995A0"
    password: "REPLACE_WITH_YOUR_OWN_PASSWORD"captive_portal:switch:
  - platform: gpio
    name: "Switch 1"
    pin: GPIO27
    id: switch1
    inverted: false  - platform: gpio
    name: "Switch 2"
    pin: GPIO32
    id: switch2
    inverted: true  - platform: gpio
    name: "Switch 3"
    pin: GPIO25
    id: switch3
    inverted: true  - platform: gpio
    name: "Switch 4"
    pin: GPIO33
    id: switch4
    inverted: false  - platform: gpio
    name: "Switch 5"
    pin: GPIO26
    id: switch5
    inverted: true  - platform: gpio
    name: "Switch 6"
    pin: GPIO19
    id: switch6
    inverted: true  - platform: gpio
    name: "Switch 7"
    pin: GPIO18
    id: switch7
    inverted: true  - platform: gpio
    name: "Switch 8"
    pin: GPIO17
    id: switch8
    inverted: truesensor:
  - platform: internal_temperature
    name: "Internal Temperature"  - platform: wifi_signal
    name: "Zone Control WiFi Signal"
    update_interval: 600s  - platform: uptime
    name: "Zone Control Uptime in Days"
    id: uptime_sensor_days
    update_interval: 60s
    on_raw_value:
      then:
        - text_sensor.template.publish:
            id: uptime_human
            state: !lambda |-
              int seconds = round(id(uptime_sensor_days).raw_state);
              int days = seconds / (24 * 3600);
              seconds = seconds % (24 * 3600);
              int hours = seconds / 3600;
              seconds = seconds % 3600;
              int minutes = seconds / 60;
              seconds = seconds % 60;
              return (
                (days ? String(days) + "d " : "") +
                (hours ? String(hours) + "h " : "") +
                (minutes ? String(minutes) + "m " : "") +
                (String(seconds) + "s")
              ).c_str();time:
  - platform: homeassistant
    id: homeassistant_timetext_sensor:
  - platform: version
    name: "Zone Control Version"  - platform: wifi_info
    ip_address:
      name: "Zone Control IP"
    bssid:
      name: "Zone Control BSSID"  - platform: template
    name: "Uptime Human Readable"
    id: uptime_human
    icon: mdi:clock-start

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 the Wi-Fi details are correct, it should join your network automatically.

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

That hotspot is there to help recovery if normal Wi-Fi connection fails.

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

Once added, the controller should appear as a Home Assistant device.

Step 8 – Check the logs

This is the step a lot of people skip, but it is very useful.

Before worrying about the relay side, first confirm the ESP32 side is healthy.

Where to find the logs

In Home Assistant:

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

On some versions you may see a menu button or three dots with a Logs option.

What you want to see

You are mainly checking that:

the device has booted
it has connected to Wi-Fi
it is connected to Home Assistant via the API
it is staying online without obvious repeated errors

You do not need to understand every line.

You are just looking for signs that the board is alive and responding properly.

This is the same process I use myself:

flash over USB
get it adopted into Home Assistant
check the logs show the board is responding

Step 9 – Connect 24V AC

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

This is what powers:

the relay section
the actual zone switching outputs

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 a switch
Confirm the correct relay activates
Confirm the correct zone/damper responds

Test one zone at a time first.

What this config does

This example config includes:

8 GPIO switches for the 8 relay outputs
logger so you can view device logs
Home Assistant API support
OTA updates
web server access
fallback access point
internal temperature sensor
Wi-Fi signal sensor
uptime sensors
IP and BSSID text sensors

It also includes an on_boot section that turns all 8 switches on during boot.

That means all 8 switch entities are intentionally turned on as soon as the ESP boots.

If that is your intended behavior for your board logic, leave it as is. If not, remove that section.

Common questions

Can I do the setup with only USB connected?

Yes, for:

flashing
getting it onto Wi-Fi
adding it to Home Assistant
checking logs

But not for relay operation.

Can I test zone switching with only USB?

No.

USB only powers the ESP32.
24V AC is required for the relays.

Why check logs before connecting the HVAC side?

Because it is the easiest way to confirm the ESP32 side is healthy before moving on to wiring and relay testing.

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.

I cannot find the logs

Go here:

Settings → Add-ons → ESPHome → your device → Logs

Do not look only in the normal device page.

The config will not validate

Check for:

typo in the YAML
wrong indentation
use of ${friendly_name} without substitutions:
old passwords/keys copied incorrectly

ESPHome 8-Zone HVAC Controller V2 Setup Guide