ESPHome Setup Guide — Flash Sonoff Devices & Build Custom Sensors

ESPHome is one of the most powerful tools in the Home Assistant ecosystem. It lets you take cheap WiFi-based ESP8266 and ESP32 devices — including many off-the-shelf Sonoff products — and run completely custom firmware that communicates with HA locally with no cloud involvement whatsoever.

This guide covers the complete workflow: installing ESPHome, flashing existing Sonoff devices over WiFi, and building a custom sensor with an ESP32 dev board.

Installing ESPHome

1. Settings → Add-ons → ESPHome → Install → Start
2. Open the ESPHome dashboard from the sidebar
3. Click "+ New Device" to create your first device configuration

Flashing a Sonoff Basic / S26 Over WiFi (OTA)

Many Sonoff devices can be flashed wirelessly using a temporary WiFi AP they create during initial setup — no soldering or UART adapter needed.

1. Power on a brand new Sonoff device and connect to its WiFi AP (ITEAD-xxxxx)
2. Navigate to 10.10.7.1 in your browser
3. Set the device WiFi to your home network and get its IP address
4. In ESPHome, create a new device config (see YAML below), compile it, and download the binary
5. Use the web flasher at web.esphome.io to flash via the USB OTA method for first flash, or use the ESPHome OTA mechanism if the device already has compatible firmware

esphome:
  name: sonoff-switch-1
  friendly_name: Garden Irrigation Switch

esp8266:
  board: esp01_1m

# WiFi credentials
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  # Fallback AP if WiFi fails
  ap:
    ssid: "Sonoff-Switch-1"
    password: "fallback123"

# Local HA API (no cloud)
api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    password: !secret ota_password

# The relay
switch:
  - platform: gpio
    pin: GPIO12
    name: "Irrigation Zone 1"
    id: relay1

# Status LED
status_led:
  pin:
    number: GPIO13
    inverted: true

Flashing Sonoff SNZB Devices (Requires UART)

Some Sonoff devices require physical flashing via UART the first time. You need:

• A USB to UART adapter (CH340 or CP2102, ~R50)
• 4 jumper wires
• Soldering iron (for test points on some devices)

Connect: TX→RX, RX→TX, GND→GND, 3.3V→3.3V. Hold the flash button while connecting power to enter flash mode. Use esptool.py to flash the compiled binary from ESPHome.

Building a Custom Sensor — DHT22 Temperature & Humidity

An ESP32 dev board (~R80) plus a DHT22 sensor (~R40) gives you a highly accurate temperature and humidity sensor that reports to HA every 30 seconds. This is what's used in the biltong box monitoring setup.

esphome:
  name: biltong-box-sensor

esp32:
  board: esp32dev

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome

# DHT22 sensor on GPIO4
sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Biltong Box Temperature"
      id: box_temp
    humidity:
      name: "Biltong Box Humidity"
      id: box_rh
    update_interval: 30s

  # Calculated absolute humidity (g/m³)
  # Used for drying phase detection in Node-RED
  - platform: template
    name: "Biltong Box Absolute Humidity"
    unit_of_measurement: "g/m³"
    lambda: |-
      float temp = id(box_temp).state;
      float rh   = id(box_rh).state;
      float es = 6.112 * exp((17.67 * temp) / (temp + 243.5));
      return (rh / 100.0) * es * 2.1674 / (temp + 273.15);
    update_interval: 30s

ESPHome Secrets File

Store sensitive values in secrets.yaml at the root of your ESPHome config folder:

wifi_ssid: "YourWiFiName"
wifi_password: "YourWiFiPassword"
api_encryption_key: "your-32-byte-base64-key-here"
ota_password: "your-ota-password"

Generate an API key: in ESPHome dashboard, create a new device and copy the auto-generated key.

Adding ESPHome Devices to HA

Once your device is flashed and online, HA will auto-discover it. Settings → Devices & Services → look for the new ESPHome device → click Configure. If not auto-discovered, click "Add Integration" → ESPHome → enter the device IP address.