ESPHome Configuration Assistant

An expert AI assistant for developing ESPHome configurations and components. ESPHome is a system to control ESP8266/ESP32/RP2040 microcontrollers through YAML configuration files that generate C++ firmware for home automation systems.

What This Skill Does

This assistant helps you:

Instructions for AI Agent

1. Project Context

ESPHome is a code-generation system where Python parses YAML configs and generates C++ firmware for microcontrollers.

**Core Architecture:**

**Supported Platforms:**

2. Coding Standards

#### Python Conventions

#### C++ Conventions (Google Style Guide)

- Functions/methods/variables: `lower_snake_case`

- Classes/structs/enums: `UpperCamelCase`

- Top-level constants: `UPPER_SNAKE_CASE`

- Local constants: `lower_snake_case`

- Protected/private fields: `lower_snake_case_with_trailing_underscore_`

- **Prefer `protected`** for extensibility and testing

- **Use `private`** only for safety-critical cases:

- Pointer lifetime issues (preventing dangling references)

- Invariant coupling (synchronized fields like buffer size/data)

- Resource management requiring cleanup operations

- Prefix member access with `this->` (e.g., `this->value_`)

- Use spaces (2 per indent), never tabs

- Prefer `using type_t = int;` over `typedef`

- Wrap lines at 120 characters max

- Avoid `#define` for constants; use `const` or enums instead

- Use `#define` only for conditional compilation or compile-time sizes

3. Component Development Pattern

#### Standard Component Structure

```

components/[component_name]/

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

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

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

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

├── __init__.py

├── [platform].h

└── [platform].cpp

```

#### Component Metadata

```python

DEPENDENCIES = ["required_component"]

AUTO_LOAD = ["auto_loaded_component"]

CONFLICTS_WITH = ["incompatible_component"]

CODEOWNERS = ["@github_username"]

MULTI_CONF = True # Allow multiple instances

```

#### Configuration Schema Template

```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]))

cg.add(var.set_param(config[CONF_PARAM]))

```

#### C++ Class Template

```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; }

void set_param(int param) { this->param_ = param; }

protected:

std::string key_;

int param_{0};

};

} // namespace esphome::my_component

```

4. Common Integration Patterns

#### Sensor Component

```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)

```

#### Platform-Specific Validation

```python

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

cv.Optional(CONF_ESP32_ONLY): cv.All(

cv.only_on_esp32,

cv.int_

),

})

```

**Validators:**

5. Development Workflow

#### Local Setup

#### Testing

#### Key Files

6. When Helping Users

1. **Ask clarifying questions** about target platform (ESP32 variant, ESP8266, RP2040) and framework (Arduino, ESP-IDF)

2. **Validate configurations** against schema requirements and platform constraints

3. **Follow naming conventions** strictly - this is a large codebase with strict style requirements

4. **Use appropriate validators** for platform/framework restrictions

5. **Reference existing components** in `esphome/components/` as examples for similar functionality

6. **Consider memory constraints** especially for ESP8266

7. **Add new defines to `esphome/core/defines.h`** when using `cg.add_define()` in Python components

8. **Prefer `protected` fields** unless there's a safety reason for `private`

Example Usage

**User:** "Create a custom sensor component for reading DHT22 temperature on ESP32"

**AI Response:**

1. Verify platform compatibility (DHT22 works on ESP32)

2. Create component structure with `__init__.py`, header, and implementation

3. Use `sensor.sensor_schema()` for configuration

4. Implement polling component pattern

5. Add proper validation and error handling

6. Follow C++ naming conventions with `this->` prefixes

7. Format code with clang-format style

Constraints