EZ-Homelab/wiki/service-docs/esphome.md

ESPHome - ESP Device Firmware

Table of Contents

• Overview
• What is ESPHome?
• Why Use ESPHome?
• Configuration in AI-Homelab
• Official Resources
• Docker Configuration
• Device Examples

Overview

Category: IoT Device Firmware
Docker Image: esphome/esphome
Default Stack: homeassistant.yml
Web UI: http://SERVER_IP:6052
Ports: 6052

What is ESPHome?

ESPHome is a system for controlling ESP8266/ESP32 microcontrollers through simple YAML configuration files. It generates custom firmware for your ESP devices that integrates natively with Home Assistant. Create custom sensors, switches, lights, and more without writing code.

Key Features

• YAML Configuration: No programming needed
• Native HA Integration: Auto-discovered
• OTA Updates: Update wirelessly
• 200+ Components: Sensors, switches, displays
• Local Control: No cloud required
• Fast: Compiled C++ firmware
• Cheap: ESP8266 ~$2, ESP32 ~$5

Why Use ESPHome?

1. Cheap Custom Devices: $2-5 per device
2. No Programming: YAML configuration
3. Home Assistant Native: Seamless integration
4. Local Control: Fully offline
5. OTA Updates: Update over WiFi
6. Reliable: Compiled firmware, very stable
7. Versatile: Sensors, relays, LEDs, displays

Configuration in AI-Homelab

/opt/stacks/homeassistant/esphome/config/
  device1.yaml
  device2.yaml

Official Resources

• Website: https://esphome.io
• Documentation: https://esphome.io/index.html
• Devices: https://esphome.io/devices/index.html

Docker Configuration

esphome:
  image: esphome/esphome:latest
  container_name: esphome
  restart: unless-stopped
  network_mode: host
  environment:
    - TZ=America/New_York
  volumes:
    - /opt/stacks/homeassistant/esphome/config:/config

Device Examples

Temperature Sensor (DHT22):

esphome:
  name: bedroom-temp
  platform: ESP8266
  board: d1_mini

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

api:
  encryption:
    key: !secret api_key

ota:
  password: !secret ota_password

sensor:
  - platform: dht
    pin: D2
    temperature:
      name: "Bedroom Temperature"
    humidity:
      name: "Bedroom Humidity"
    update_interval: 60s

Smart Plug (Sonoff):

esphome:
  name: living-room-plug
  platform: ESP8266
  board: esp01_1m

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

api:
ota:

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      mode: INPUT_PULLUP
      inverted: True
    name: "Living Room Plug Button"
    on_press:
      - switch.toggle: relay

switch:
  - platform: gpio
    name: "Living Room Plug"
    pin: GPIO12
    id: relay

ESPHome turns cheap ESP modules into powerful smart home devices!