Skip to content

Files

Latest commit

 

History

History
388 lines (321 loc) · 15 KB

index.rst

File metadata and controls

388 lines (321 loc) · 15 KB
.. seo::
    :description: ESPHome - Smart Home Made Simple. ESPHome turns ESP32, ESP8266, and RP2040 microcontrollers into fully-featured smart home devices.
    :image: logo.svg

Smart Home Made Simple

Turn your ESP32, ESP8266, or RP2040 boards into powerful smart home devices with simple YAML configuration

ESPHome devices

Quick Links

What is ESPHome?

ESPHome is an open-source firmware framework that simplifies the process of creating custom firmware for popular WiFi-enabled microcontrollers. With ESPHome, you can:

  • Create custom smart home devices using simple YAML configuration files
  • Integrate seamlessly with Home Assistant for a unified smart home experience
  • Control and monitor your devices through multiple interfaces (web, API, MQTT)
  • Automate your home with powerful on-device automations
  • Update your devices wirelessly "Over The Air" (OTA) updates without physical access

ESPHome takes care of the complex parts of firmware development, allowing you to focus on what matters - building your smart home exactly how you want it.

No Coding Required

Simple YAML configuration files instead of complex C++ code

Wireless Updates

Update your devices over-the-air without physical access

Modular Design

Support for hundreds of sensors, displays, and other components

Local Control

Devices work locally without cloud dependencies

Who Uses ESPHome?

DIY Enthusiasts

Create custom sensors, switches, and displays tailored to specific needs

Smart Home Hobbyists

Extend their home automation systems with affordable custom devices

Professional Integrators

Deploy reliable, locally-controlled smart devices for clients

Manufacturers

Create Made for ESPHome certified products with standardized firmware

Which microcontrollers does ESPHome support?

Espressif ESP32 and ESP8266

Wide support for ESP32 and ESP8266 microcontrollers, the heart of many IoT projects.

RP2040

Support for Raspberry Pi's RP2040 microcontroller.

Others

Realtek RTL87xx and Beken BK72xx chips are supported.

Desktop

Many ESPHome components can be run on a desktop computer using the host platform!

Getting Started

Getting started with ESPHome is easy. Choose the method that works best for you:

From Home Assistant

The easiest way to get started with ESPHome is through the Home Assistant add-on.

  1. Open Home Assistant
  2. Go to Settings → Add-ons → Add-on Store
  3. Find and install the ESPHome add-on
  4. Open the ESPHome Device Builder and create your first device
Detailed Instructions

Command Line

For advanced users who prefer working with the command line.

  1. Install Python 3.11 or higher
  2. Install ESPHome: pip install esphome
  3. Create a configuration file
  4. Compile and upload: esphome run my_config.yaml
Detailed Instructions

Ready-Made Projects

Start with a pre-configured project for common use cases.

  1. Browse the project library
  2. Select a project that matches your hardware
  3. Follow the installation instructions
  4. Customize as needed
Browse Projects

Basic Configuration Example

Here's a simple example of an ESPHome configuration file:

# Basic configuration for an ESP32 device
esphome:
  name: living-room-sensor
  friendly_name: Living Room Sensor

# Hardware configuration
esp32:
  board: esp32dev
  framework:
    type: esp-idf

# Enable Home Assistant API
api:

# Enable over-the-air updates
ota:
  platform: esphome

# Connect to WiFi
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot if WiFi connection fails
  ap:

# Enable web server
web_server:

# Add a temperature sensor
sensor:
  - platform: dht
    pin: GPIO15
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    update_interval: 60s

Using with Home Assistant

ESPHome and Home Assistant are designed to work together seamlessly, providing a powerful smart home ecosystem.

Automatic Discovery

Home Assistant automatically discovers ESPHome devices on your network. When you add a new ESPHome device:

  1. Make sure your device is connected to the same network as Home Assistant
  2. Home Assistant will show a notification when it discovers the new device
  3. Click "Configure" to add it to your system
  4. The device and all its entities will appear in your Home Assistant dashboard

Dashboard Integration

ESPHome entities appear in Home Assistant just like any other device:

  • Sensors show up in the appropriate cards and graphs
  • Switches and lights can be controlled directly
  • Binary sensors can trigger automations
  • Climate devices integrate with the thermostat controls

Automations

You can create powerful automations using ESPHome devices in Home Assistant:

  • Use sensor readings to trigger actions
  • Control ESPHome devices based on conditions
  • Include ESPHome devices in scenes and scripts
  • Create complex automations using multiple sensors and conditions

Advanced Features

  • ESPHome Device Builder Add-on: Manage all your ESPHome devices directly from Home Assistant
  • Backup Integration: Include ESPHome configurations in your Home Assistant backups
  • Firmware Updates: Update ESPHome devices directly from the Home Assistant interface

Join the Community

Ready to get started?

Join thousands of smart home enthusiasts building custom devices with ESPHome.

.. toctree::
    :hidden:

    web-api/index
    automations/index
    components/index
    cookbook/index
    guides/index
    changelog/index
    images/index
    projects/index