How To Re-Flash the TekOnline 7-Zone HVAC Controller From Home Assistant

If your board shows up in Home Assistant as something like esphome-web-6ad244, only exposes one or two generic entities, and no longer behaves like the zone controller, it is usually running generic ESPHome web firmware instead of the TekOnline zone-control config.

This guide shows how to load the correct YAML back onto the board using Home Assistant and the ESPHome dashboard.

The firmware used in this guide is:

• firmware/esphome/zone_control_from_pcb_v3.yml

What this flash restores

This config restores:

• Eight zone switch entities in Home Assistant
• The GPIO mapping for the v3 relay board
• ESPHome API access
• OTA updates
• The built-in ESPHome web server

Important: this file does not define any binary_sensor, button, or automation for SW1. If your old firmware used the board button to cycle relays locally, that behavior is not present in zone_control_from_pcb_v3.yml.

Before you start

You will need:

• Home Assistant running on the same network as the board
• The ESPHome add-on/dashboard installed in Home Assistant
• The board online on Wi-Fi, or a USB cable available if wireless flashing fails
• The board’s current IP address
• Your Wi-Fi SSID and password

If the board already appears in Home Assistant as esphome-web-xxxxxx, that is a good sign. It means the board is online and can often be recovered over the air.

Step 1: Find the board’s current IP address

In Home Assistant:

1. Go to Settings -> Devices & Services.
2. Open the ESPHome device that currently represents the board.
3. Note the IP address.

Use the IP address, not .local, for the first recovery flash. It is more reliable, especially on Windows networks where mDNS can be inconsistent.

Step 2: Add the zone-control YAML to ESPHome

Open the ESPHome dashboard in Home Assistant and create a new device configuration.

Use the contents of:

• firmware/esphome/zone_control_from_pcb_v3.yml

If you want to keep the default name, leave this section as-is:

esphome:
  name: esp-hvac-base
  friendly_name: ESP HVAC Zone Control

If you want a different final device name, change it now. Just keep the name simple and unique.

Step 3: Add the required secrets

This YAML expects these values in ESPHome secrets.yaml:

wifi_ssid: "YourWiFiName"
wifi_password: "YourWiFiPassword"
fallback_password: "ChooseAStrongFallbackPassword"

In a Home Assistant ESPHome setup, that is usually the file at:

• /config/esphome/secrets.yaml

Step 4: Add use_address for the first recovery flash

This step matters if the board is currently named something like esphome-web-6ad244 but the new config will rename it to esp-hvac-base.

For the first OTA flash only, add the board’s current IP address under the wifi: block:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  use_address: 192.168.x.x
  ap:
    ssid: "ESP-HVAC-Base Fallback"
    password: !secret fallback_password

Replace 192.168.x.x with the board’s current IP from Home Assistant.

Without use_address, ESPHome may try to upload to the new hostname before the board has ever booted with that hostname.

Step 5: Validate and install wirelessly

In the ESPHome dashboard:

1. Save the YAML.
2. Click Validate.
3. Click Install.
4. Choose the wireless install option.

If the board is online and still accepting OTA, the flash should complete without opening the crawl space again.

After the board reboots, it should come back as esp-hvac-base unless you changed the name.

Step 6: Remove use_address after the first successful flash

Once the board has successfully booted the new firmware:

1. Open the YAML again.
2. Remove the temporary use_address line.
3. Save and validate again.

This keeps future OTA updates clean and lets ESPHome use the board’s new normal address.

Step 7: Confirm the correct entities in Home Assistant

After the flash completes, you should see zone entities such as:

• Zone 1
• Zone 2
• Zone 3
• Zone 4
• Zone 5
• Zone 6
• Zone 7
• Zone 8

If you still only see a generic esphome-web-* device with one entity, the zone firmware did not install successfully.

If wireless flashing fails

If the board is online in Home Assistant but OTA will not complete, use USB once to recover it, then go back to OTA later.

From the repo root, the direct flash command is:

python -m esphome run firmware/esphome/zone_control_from_pcb_v3.yml --device COM17

Or with the helper script:

.\scripts\flash\flash_device.ps1 COM17 firmware/esphome/zone_control_from_pcb_v3.yml

Replace COM17 with the actual serial port for the board.

Quick diagnosis summary

If you see this:

• Device name like esphome-web-6ad244
• Only one generic entity
• No zone switches

That usually means the board is alive, on Wi-Fi, and recoverable, but it is not running the TekOnline zone-control YAML yet.

Final note

For most recovery cases, the shortest path is:

1. Find current IP in Home Assistant.
2. Load zone_control_from_pcb_v3.yml into ESPHome.
3. Add use_address for the first flash.
4. Install wirelessly.
5. Remove use_address after the board comes back.

That will restore the zone entities. If you also need local SW1 test-button behavior, that requires a firmware file that explicitly implements it.