ESPHome Practical Guide: Build Reliable Local Devices

When ESPHome is the right tool

Use ESPHome when you need a local sensor, relay, display, controller, or bridge that maps cleanly to Home Assistant. It is ideal for standard ESP32/ESP8266 projects where HA integration, OTA updates, and maintainable configuration matter more than writing firmware from scratch.

Choose Arduino/ESP-IDF instead when you need a custom protocol, unusual timing, specialist library, or full code-level control; see the Embedded C/C++ guide.

Device design before YAML

Answer these first:

Purpose: what decision/action does this device support?
Power: USB, mains PSU, battery, solar?
Failure state: safe on reboot/offline?
Manual fallback: can a person still operate it?
Network: Wi-Fi coverage, static DHCP reservation, credentials path?
Sensors: calibration, noise, update rate, physical placement?
Actuator: current/voltage isolation, relay rating, failsafe?

Never control mains power directly from a hobby microcontroller without appropriate certified isolation, enclosure, protection, and electrical competence.

Minimal ESP32 structure

esphome:
  name: workshop-sensor
  friendly_name: Workshop Sensor

esp32:
  board: esp32dev
  framework:
    type: arduino

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "Workshop Sensor Fallback"

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome

logger:

sensor:
  - platform: uptime
    name: "Workshop Sensor Uptime"

Use secrets.yaml for credentials and keys. Never commit its real contents; commit a secrets.example.yaml only.

Naming and entity quality

• Use a stable node name; changing it can orphan dashboards/automations.
• Give entities a human-friendly name and a meaningful device name.
• Disable diagnostics you will never use; expose diagnostics that help recovery: Wi-Fi signal, uptime, version, reset reason.
• Keep one physical concept per entity.

Sensor design

Example filtering:

sensor:
  - platform: adc
    pin: GPIO34
    name: "Tank level raw"
    update_interval: 10s
    filters:
      - median:
          window_size: 7
          send_every: 4
      - calibrate_linear:
          - 0.20 -> 0
          - 2.80 -> 100
    unit_of_measurement: "%"

Calibration points must come from measured reality, not a guessed datasheet curve.

Switches and relays: safe defaults

switch:
  - platform: gpio
    pin: GPIO23
    name: "Example relay"
    restore_mode: ALWAYS_OFF

Choose restore_mode deliberately. For a pump, heater, or motor, ALWAYS_OFF may be safer after reboot; for a light, a different behaviour may be acceptable. Add interlocks and feedback for mutually exclusive or physical actions.

OTA and recovery

1. Validate config before upload.
2. Flash by USB for first installation.
3. Confirm API/HA connection and Wi-Fi signal.
4. Use OTA for normal updates.
5. Keep physical access or a fallback AP/recovery plan for hard-to-reach devices.

Do not deploy untested YAML to every device at once. Use one pilot device and retain the prior known-good config.

Debugging sequence

Device unavailable
→ power/USB supply and serial logs
→ Wi-Fi association and signal
→ IP/DHCP reservation
→ ESPHome API encryption/key mismatch
→ HA integration entry
→ YAML validation and compile output
→ sensor wiring/calibration

logger: plus serial logs are often the fastest truth source. Hardware problems cannot be solved by YAML edits alone.

Security and lifecycle

• Use encrypted API communication and strong OTA credentials/keys.
• Keep devices on appropriate network segments.
• Patch firmware intentionally, recording major version changes.
• Document GPIO wiring, power supply, enclosure, and manual fallback.
• Back up YAML source before device replacement.

First project sequence

1. Build a temperature/humidity or status sensor.
2. Add Wi-Fi signal and uptime diagnostics.
3. Put it in HA and make a dashboard card.
4. Calibrate it with real observations.
5. Add a non-critical notification.
6. Only then design a relay/actuator project with safety analysis.