ESPHome IoT Development Assistant

Expert assistant for developing IoT firmware with ESPHome, a system to configure microcontrollers (ESP32, ESP8266, RP2040, LibreTiny chips) using YAML configuration files that generate C++ firmware for home automation.

What This Skill Does

This skill provides expert guidance for:

Writing and validating ESPHome YAML configurations

Developing custom C++ components for ESPHome

Implementing Python code generation and validation logic

Following ESPHome's architectural patterns and coding standards

Creating platform-specific implementations (ESP32, ESP8266, RP2040)

Building and testing ESPHome firmware

Instructions

1. Project Architecture Understanding

When working with ESPHome code:

**Recognize the code-generation architecture**: Python parses YAML configs and generates C++ source code that's compiled with PlatformIO

**Understand the core components**:

- Configuration system (`esphome/config*.py`) - YAML parsing with Voluptuous validation

- Code generation (`esphome/codegen.py`, `esphome/cpp_generator.py`) - Python to C++ generation

- Component system (`esphome/components/`) - Modular hardware/software components

- Core framework (`esphome/core/`) - Application lifecycle and hardware abstraction

- Dashboard (`esphome/dashboard/`) - Web interface for device management

2. Platform-Specific Development

Support the correct platform when developing:

**ESP32** (`components/esp32/`): Multiple variants (Original, C2, C3, C5, C6, H2, P4, S2, S3), ESP-IDF framework (Arduino for subset)

**ESP8266** (`components/esp8266/`): Arduino framework only, memory-constrained

**RP2040** (`components/rp2040/`): Raspberry Pi Pico, Arduino with PIO support

**LibreTiny** (`components/libretiny/`): Realtek and Beken chips

Use platform validation helpers: `cv.only_on_esp32`, `cv.only_on_esp8266`, `cv.only_on_rp2040`, `esp32.only_on_variant(...)`

3. C++ Coding Standards

Follow these strict conventions:

**Naming:**

Functions/methods/variables: `lower_snake_case`

Classes/structs/enums: `UpperCamelCase`

Top-level constants: `UPPER_SNAKE_CASE`

Function-local constants: `lower_snake_case`

Protected/private fields: `lower_snake_case_with_trailing_underscore_`

**Member Access:**

ALWAYS prefix member access with `this->` (e.g., `this->value_` not `value_`)

Use 2 spaces for indentation (never tabs)

Wrap lines at 120 characters max

**Field Visibility:**

PREFER `protected` for most fields to enable extensibility

Use `private` ONLY for safety-critical cases:

- Pointer lifetime issues (setters validate from known lists)

- Invariant coupling (synchronized fields preventing corruption)

- Resource management (cleanup operations)

Provide `protected` accessor methods when needed

**Preprocessor Usage:**

AVOID `#define` for constants (use `const` variables or enums)

Use `#define` ONLY for:

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

- Compile-time sizes from Python code generation

**Type Aliases:**

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

4. Component Development Pattern

When creating a new component:

**Directory Structure:**

```

components/[component_name]/

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

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

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

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

├── __init__.py

├── [platform].h

└── [platform].cpp

```

**Python Configuration Schema:**

```python

import esphome.codegen as cg

import esphome.config_validation as cv

from esphome.const import CONF_ID

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

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_CUSTOM_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_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_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

```

5. Common Component Types

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

```

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

```

6. Configuration Validation

Use appropriate validators:

**Basic:** `cv.int_`, `cv.float_`, `cv.string`, `cv.boolean`, `cv.positive_int`, `cv.percentage`

**Range:** `cv.int_range(min=0, max=100)`

**Complex:** `cv.All(cv.string, cv.Length(min=1, max=50))`, `cv.Any(cv.int_, cv.string)`

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

```

7. Development Workflow

**Environment Setup:**

Use Docker container or Python venv with `requirements_dev.txt`

Run commands via `script/run-in-env.py`: `python3 script/run-in-env.py pre-commit run`

**Testing:**

Python: `pytest`

C++: `clang-tidy` for static analysis

Component tests: `script/test_build_components -c <component> -t <platform>`

All components together: `./script/test_component_grouping.py -e config --all`

**Formatting:**

Python: `ruff` and `flake8` (config in `pyproject.toml`)

C++: `clang-format` (config in `.clang-format`)

8. Component Metadata

Include in `__init__.py`:

```python

DEPENDENCIES = ["required_component"]

AUTO_LOAD = ["auto_loaded_component"]

CONFLICTS_WITH = ["conflicting_component"]

CODEOWNERS = ["@github_username"]

MULTI_CONF = True # Allow multiple instances

```

9. Static Analysis Support

When adding new `#define` directives via `cg.add_define()`, add them to `esphome/core/defines.h`. This file is used exclusively for IDE support and static analysis - it's not compiled into firmware. It helps static analyzers understand the complete codebase across all platforms.

Examples

**Creating a simple sensor component:**

```yaml

sensor:

- platform: my_sensor

name: "My Sensor"

update_interval: 60s

```

**Platform-specific implementation:**

```python

CONFIG_SCHEMA = cv.All(

sensor.sensor_schema().extend({ ... }),

cv.only_on(["esp32", "esp8266"])

)

```

Important Notes

Always use `this->` prefix for member access in C++

Prefer `protected` fields over `private` unless safety-critical

Never use `#define` for constants - use `const` or enums

Test components individually AND together to catch conflicts

Follow the code-generation pattern: Python generates C++

Format code with `clang-format` (C++) and `ruff` (Python)

ESPHome IoT Development Assistant

ESPHome IoT Development Assistant

What This Skill Does

Instructions

1. Project Architecture Understanding

2. Platform-Specific Development

3. C++ Coding Standards

4. Component Development Pattern

5. Common Component Types

6. Configuration Validation

7. Development Workflow

8. Component Metadata

9. Static Analysis Support

Examples

Important Notes

Reviews (0)