Skip to main content
Mini PC Lab logo
Mini PC LabMini PCs for Homelabs
tutorials

How to Set Up ESPHome on a Mini PC 2026

By Max · May 2, 2026 · Updated May 5, 2026

This article contains affiliate links. If you purchase through our links, we may earn a commission at no extra cost to you. We only recommend products we’ve thoroughly researched and verified.

How to set up ESPHome on a mini PC hero image

ESPHome turns $5-10 ESP32 modules into custom Home Assistant sensors. A temperature sensor in every room, a door sensor on every window, a CO2 monitor in the bedroom — all running on hardware you built and firmware you control. The ESPHome dashboard compiles firmware and manages OTA updates for your entire sensor fleet from a web browser.

This guide runs ESPHome as a standalone Docker container on a mini PC, covering initial setup, first device configuration, flashing firmware, and OTA update workflow.

What you need:

  • A mini PC running Ubuntu Server 24.04 LTS with Docker installed
  • An ESP32 or ESP8266 development board $5-15 on Amazon
  • A USB cable to flash firmware initially OTA for all subsequent updates

When to Use Standalone ESPHome vs the HAOS Add-on

Use the HAOS ESPHome add-on if:

  • You’re running Home Assistant OS or Home Assistant Supervised
  • You want the simplest setup — add-on management is one click

Use standalone Docker ESPHome if:

  • You’re running Home Assistant Container plain Docker without add-on support
  • You want ESPHome isolated from your HA instance
  • You’re on a different machine than your HA server

This guide covers the Docker standalone setup.

Step 1: Deploy ESPHome Dashboard

mkdir -p ~/esphome/config
nano ~/esphome/docker-compose.yml
services:
  esphome:
    image: esphome/esphome:latest
    container_name: esphome
    ports:
      - "6052:6052"
    volumes:
      - ./config:/config
    environment:
      - HOME=/root
      - TZ=America/New_York
    restart: unless-stopped
    network_mode: host    # Required for ESP device discovery on LAN

Using network_mode: host is necessary — ESPHome discovers ESP devices on the local network via broadcast, which requires access to the host network.

cd ~/esphome
docker compose up -d

Access the ESPHome dashboard at http://192.168.1.100:6052.

Step 2: Create Your First Device Configuration

In the ESPHome dashboard, click + New Device:

  1. Name: living-room-temp
  2. Device type: ESP32 or ESP8266 depending on your board
  3. Skip the automatic network setup — you’ll configure Wi-Fi manually

The dashboard creates a new YAML configuration file. Click Edit to see it.

Example: Temperature and Humidity Sensor DHT22

# living-room-temp.yaml
esphome:
  name: living-room-temp
  friendly_name: Living Room Temp

esp32:
  board: esp32dev
  framework:
    type: arduino

# Wi-Fi configuration
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  # Fallback hotspot (allows connecting if Wi-Fi fails)
  ap:
    ssid: "Living-Room-Temp Fallback"
    password: "fallback-password"

# Over-the-air updates
ota:
  password: !secret ota_password

# API connection to Home Assistant
api:
  encryption:
    key: !secret api_encryption_key

# Logging
logger:

# Web server (optional — provides local HTTP status page)
web_server:
  port: 80

# Sensors
sensor:
  - platform: dht
    model: DHT22
    pin: GPIO4         # Connect DHT22 data pin to GPIO4 on the ESP32
    temperature:
      name: "Living Room Temperature"
    humidity:
      name: "Living Room Humidity"
    update_interval: 30s

  # Wi-Fi signal strength
  - platform: wifi_signal
    name: "Living Room Wi-Fi Signal"
    update_interval: 60s

Create the secrets file:

nano ~/esphome/config/secrets.yaml
wifi_ssid: "YourHomeNetwork"
wifi_password: "your-wifi-password"
ota_password: "your-ota-password"
api_encryption_key: "generate-32-byte-base64-key"

Generate an API encryption key:

python3 -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"

Step 3: Flash the First Firmware

For the initial flash, you need a USB connection. Subsequent updates use OTA no cable needed.

Connect the ESP32 to the mini PC via USB. The device appears as /dev/ttyUSB0 or /dev/ttyACM0.

In the ESPHome dashboard:

  1. Click your device → Install → Plug into this computer
  2. Select the serial port
  3. ESPHome compiles the firmware and flashes the ESP32

Watch the serial output — you should see:

Connected to WiFi "YourHomeNetwork"
API connected to Home Assistant

Step 4: Add to Home Assistant

Once the ESP32 is running with the API enabled, Home Assistant discovers it automatically:

In Home Assistant: Notifications → “ESPHome node ‘living-room-temp’ discovered” → Configure → enter the API encryption key from secrets.yaml.

The temperature and humidity sensors appear as entities in Home Assistant immediately.

Step 5: OTA Updates No USB Required

After the initial flash, all updates are wireless. In the ESPHome dashboard:

  1. Edit the YAML configuration
  2. Click Install → Wirelessly
  3. ESPHome compiles and uploads the new firmware over Wi-Fi

The ESP32 reboots with the new firmware within 30 seconds. Zero USB wiring required.

Common ESPHome Project Recipes

CO2 Monitor SCD40 I2C

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: scd4x
    co2:
      name: "Bedroom CO2"
    temperature:
      name: "Bedroom Temperature"
    humidity:
      name: "Bedroom Humidity"
    update_interval: 60s

Wire: SCD40 SDA → GPIO21, SCL → GPIO22, VCC → 3.3V, GND → GND.

Door/Window Contact Sensor

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO5
      mode:
        input: true
        pullup: true
    name: "Front Door"
    device_class: door
    filters:
      - delayed_on: 50ms    # Debounce
      - delayed_off: 50ms

Wire: Magnetic reed switch between GPIO5 and GND. Open = sensor triggers = “door open” in HA.

Smart Power Switch Relay

switch:
  - platform: gpio
    pin: GPIO23
    name: "Desk Lamp"
    id: desk_lamp

# Optional: physical button to toggle
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      mode: INPUT_PULLUP
    name: "Desk Lamp Button"
    on_press:
      - switch.toggle: desk_lamp

IR Blaster for TV/AC Control

remote_transmitter:
  pin: GPIO4
  carrier_duty_percent: 50%

button:
  - platform: template
    name: "TV Power"
    on_press:
      - remote_transmitter.transmit_samsung:
          data: 0xE0E040BF   # Samsung TV power code

  - platform: template
    name: "AC Cool 24C"
    on_press:
      - remote_transmitter.transmit_raw:
          carrier_frequency: 38kHz
          code: [...]   # Raw IR code captured with an IR receiver

Managing Multiple ESP Devices

As your sensor fleet grows, the ESPHome dashboard manages all devices in ~/esphome/config/:

  • Each YAML file = one device
  • Dashboard shows compile status, last seen, and online/offline status
  • Batch updates: use Update All from the dashboard compiles and flashes all devices sequentially

For organizing large fleets:

~/esphome/config/
├── secrets.yaml
├── living-room-temp.yaml
├── bedroom-co2.yaml
├── front-door.yaml
├── garage-door.yaml
├── plant-monitor-balcony.yaml
└── ir-blaster-lounge.yaml

ESPHome + Home Assistant Automations

Once sensors are in HA, create automations based on their data:

# configuration.yaml automations:
automation:
  - alias: "Bedroom CO2 Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.bedroom_co2
        above: 1200
    action:
      - service: notify.mobile_app_phone
        data:
          message: "Bedroom CO2 is {{ states('sensor.bedroom_co2') }} ppm — open a window"

  - alias: "Close windows if raining and front door opens"
    trigger:
      - platform: state
        entity_id: binary_sensor.front_door
        to: "on"
    condition:
      - condition: state
        entity_id: weather.home
        state: "rainy"
    action:
      - service: notify.family_group
        data:
          message: "Front door opened — it's raining outside"

Who Should Skip This Comparison

Frequently Asked Questions

How many ESP devices can one ESPHome instance manage?

Hundreds. ESPHome compiles firmware on-demand and each device connects to Home Assistant independently — there’s no practical limit from the ESPHome side. The constraint is your Home Assistant instance’s entity count, which HA handles well into the thousands.

What is the difference between ESPHome and Tasmota?

Both are firmware frameworks for ESP8266/ESP32. Tasmota is pre-compiled and flashed via a simple web tool; ESPHome is YAML-configured and compiled for each device. ESPHome integrates more deeply with Home Assistant native API, automatic discovery, encryption and supports a wider range of sensors. Tasmota uses MQTT and is easier for non-technical users to get started with. For HA users: ESPHome is generally preferred.

Can ESPHome work without Home Assistant?

Yes. ESPHome devices expose a local web server, MQTT output, and REST API without HA. But Home Assistant integration is where ESPHome shines — entities appear automatically, no configuration needed.

What is ESPHome and why run it on a mini PC?

ESPHome is firmware framework for ESP32 and ESP8266 microcontrollers that integrates natively with Home Assistant. It turns a $5-10 ESP32 module into a custom sensor — temperature, humidity, motion, door contact, CO2, soil moisture, anything you can wire up. Running the ESPHome dashboard on a mini PC lets you compile firmware and push OTA updates to all your ESP devices from a web browser.

What can I build with ESPHome and an ESP32?

Temperature/humidity sensors using DHT22, BME280, or SHT31. CO2 sensors with the SCD40 or MH-Z19. Motion detection with a PIR sensor. Smart switches and relays. Plant moisture monitors. Custom displays with SSD1306 OLED or ST7789 TFT. Energy monitoring with a PZEM-004T. IR blasters for controlling TVs and air conditioners. Anything with a sensor or actuator and a wire.