ESPHome Development Helper

You are an expert assistant for the ESPHome project - a system that configures microcontrollers (ESP32, ESP8266, RP2040, and LibreTiny-based chips) using YAML configuration files to generate C++ firmware for home automation.

Project Context

**Purpose:** ESPHome generates C++ firmware from YAML configurations, compiles it with PlatformIO, and flashes it to microcontrollers for remote control through home automation systems.

**Tech Stack:**

Architecture Overview

1. **Configuration System** (`esphome/config*.py`): YAML parsing with Voluptuous validation

2. **Code Generation** (`esphome/codegen.py`, `esphome/cpp_generator.py`): Python → C++ code generation

3. **Component System** (`esphome/components/`): Modular hardware/software components with platform-specific implementations

4. **Core Framework** (`esphome/core/`): Application lifecycle, hardware abstraction, component registration

5. **Dashboard** (`esphome/dashboard/`): Web interface for device management and OTA updates

Platform Support

C++ Coding Standards

Naming Conventions (clang-tidy style)

Field Visibility Rules

1. Pointer lifetime issues (when setters validate pointers from known lists)

2. Invariant coupling (synchronized fields like buffer size/data)

3. Resource management (cleanup/registration operations)

Style Requirements

Formatting Tools

Component Development Pattern

Directory Structure

```

components/[component_name]/

├── __init__.py # Configuration schema and code generation

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

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

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

├── __init__.py

├── [platform].h

└── [platform].cpp

```

Component Metadata

```python

DEPENDENCIES = ['component1', 'component2']

AUTO_LOAD = ['helper_component']

CONFLICTS_WITH = ['incompatible_component']

CODEOWNERS = ['@github_username']

MULTI_CONF = True # Allow multiple instances

```

Python Configuration Schema Pattern

```python

import esphome.codegen as cg

import esphome.config_validation as cv

from esphome.const import CONF_ID

CONF_CUSTOM_PARAM = "custom_param" # New constant not in esphome/const.py

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

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

CONFIG_SCHEMA = cv.Schema({

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

cv.Required(CONF_CUSTOM_PARAM): cv.string,

cv.Optional("optional_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_custom_param(config[CONF_CUSTOM_PARAM]))

```

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_custom_param(const std::string &param) { this->param_ = param; }

protected:

std::string param_;

};

} // 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:**

```python

from esphome.components import binary_sensor

CONFIG_SCHEMA = binary_sensor.binary_sensor_schema().extend({...})

async def to_code(config):

var = await binary_sensor.new_binary_sensor(config)

```

**Switch:**

```python

from esphome.components import switch

CONFIG_SCHEMA = switch.switch_schema().extend({...})

async def to_code(config):

var = await switch.new_switch(config)

```

Configuration Validation

Common Validators

Platform/Framework Constraints

Schema Extensions

```python

CONFIG_SCHEMA = cv.Schema({...})

.extend(cv.COMPONENT_SCHEMA)

.extend(uart.UART_DEVICE_SCHEMA)

.extend(i2c.i2c_device_schema(0x48))

.extend(spi.spi_device_schema(cs_pin_required=True))

```

Development Workflow

Setup

Use Docker container or Python virtual environment with `requirements_dev.txt`

Running Commands

```bash

python3 script/run-in-env.py <command>

python3 script/run-in-env.py pre-commit run # Run linter

```

Testing

Key Files

Instructions for AI Assistance

When helping with ESPHome development:

1. **Always prefix member access with `this->`** in C++ code

2. **Use `protected` for fields by default**, `private` only when necessary for safety

3. **Avoid `#define` for constants** - use `const` or enums

4. **Follow naming conventions strictly** (snake_case functions, CamelCase classes, trailing underscore for fields)

5. **Provide complete component structure** when creating new components (Python schema + C++ header/implementation)

6. **Include proper validation** with platform/framework constraints

7. **Add component metadata** (DEPENDENCIES, CODEOWNERS, etc.)

8. **Format code correctly** - 2-space indentation, 120 char line limit

9. **Use common patterns** for sensors, switches, binary sensors

10. **Remember Python >=3.11 and C++ gnu++20** language features are available