ESPHome Development Assistant

An AI collaboration guide for working with ESPHome - a system to configure microcontrollers (ESP32, ESP8266, RP2040, LibreTiny chips) using YAML configuration files that generate C++ firmware for home automation.

Project Context

ESPHome uses a code-generation architecture: Python parses YAML configs and generates C++ source code, which is compiled via PlatformIO and flashed to microcontrollers. Components are modular, self-contained units with platform-specific implementations.

Core Technologies

Architecture

Directory Structure

Core Systems

1. **Configuration** (`config*.py`) - YAML parsing, Voluptuous validation

2. **Code Generation** (`codegen.py`, `cpp_generator.py`) - Python→C++ generation

3. **Component System** (`components/`) - Modular platform-specific implementations

4. **Core Framework** (`core/`) - Application lifecycle, hardware abstraction

5. **Dashboard** (`dashboard/`) - Web interface for device management

Platform Support

Coding Conventions

Python (PEP 8)

C++ (Google Style)

- Functions/variables: `lower_snake_case`

- Classes/structs/enums: `UpperCamelCase`

- Global constants: `UPPER_SNAKE_CASE`

- Local constants: `lower_snake_case`

- Protected/private fields: `trailing_underscore_`

Field Visibility

1. Pointer lifetime validation needed (e.g., storing pointers from known lists)

2. Fields must stay synchronized (e.g., buffer data/size coupling)

3. Setters perform cleanup/registration operations

Preprocessor Usage

- Conditional compilation (`#ifdef`, `#ifndef`)

- Compile-time sizes from Python codegen (`cg.add_define()`)

Component Development Pattern

File Structure

```

components/[component_name]/

├── __init__.py # Config schema & code generation

├── [component].h # C++ header

├── [component].cpp # C++ implementation

└── [platform]/ # Platform-specific code

├── __init__.py

├── [platform].h

└── [platform].cpp

```

Metadata

```python

DEPENDENCIES = ['component1', 'component2']

AUTO_LOAD = ['auto_component']

CONFLICTS_WITH = ['incompatible_component']

CODEOWNERS = ['@username']

MULTI_CONF = True # Allow multiple instances

```

Configuration Schema Pattern

```python

import esphome.codegen as cg

import esphome.config_validation as cv

from esphome.const import CONF_ID

my_component_ns = cg.esphome_ns.namespace("my_component")

MyComponent = my_component_ns.class_("MyComponent", cg.Component)

CONFIG_SCHEMA = cv.Schema({

cv.GenerateID(): cv.declare_id(MyComponent),

cv.Required(CONF_KEY): cv.string,

cv.Optional(CONF_PARAM, default=42): cv.int_,

}).extend(cv.COMPONENT_SCHEMA)

async def to_code(config):

var = cg.new_Pvariable(config[CONF_ID])

await cg.register_component(var, config)

cg.add(var.set_key(config[CONF_KEY]))

```

C++ Class Pattern

```cpp

namespace esphome::my_component {

class MyComponent : public Component {

public:

void setup() override;

void loop() override;

void dump_config() override;

void set_key(const std::string &key) { this->key_ = key; }

protected:

std::string key_;

int param_{0};

};

} // namespace esphome::my_component

```

Common Component Types

Sensor

```python

from esphome.components import sensor

CONFIG_SCHEMA = sensor.sensor_schema(MySensor).extend(

cv.polling_component_schema("60s")

)

async def to_code(config):

var = await sensor.new_sensor(config)

await cg.register_component(var, config)

```

Binary Sensor / Switch

```python

from esphome.components import binary_sensor, switch

Use binary_sensor.binary_sensor_schema() or switch.switch_schema()

```

Validation Helpers

Development Workflow

Setup

Use Docker or create virtual environment:

```bash

pip install -r requirements_dev.txt

```

Testing

```bash

Python unit tests

pytest

Linting

python3 script/run-in-env.py pre-commit run

Component tests (specific component/platform)

script/test_build_components -c <component> -t <target>

Test all components together (detect conflicts)

./script/test_component_grouping.py -e config --all

C++ static analysis

clang-tidy

```

Key Files

Best Practices

1. **Always** use `this->` for member access in C++

2. **Document** new defines in `esphome/core/defines.h`

3. **Validate** configs with appropriate `cv` helpers

4. **Test** components individually and together (grouping script)

5. **Follow** naming conventions strictly (snake_case in C++ functions)

6. **Prefer** `protected` fields unless safety-critical

7. **Avoid** `#define` for constants - use `const` or `enum`

8. **Run** pre-commit hooks before submitting changes

Component Examples

The `components/` directory contains hundreds of reference implementations. Study similar components when creating new ones. Common patterns: sensors poll data, binary sensors report state changes, switches control outputs.