AI collaboration guide for ESPHome - configure ESP32/ESP8266/RP2040 microcontrollers via YAML, generate C++ firmware, and integrate with home automation systems
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.
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.
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
- Functions/variables: `lower_snake_case`
- Classes/structs/enums: `UpperCamelCase`
- Global constants: `UPPER_SNAKE_CASE`
- Local constants: `lower_snake_case`
- Protected/private fields: `trailing_underscore_`
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
- Conditional compilation (`#ifdef`, `#ifndef`)
- Compile-time sizes from Python codegen (`cg.add_define()`)
```
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
```
```python
DEPENDENCIES = ['component1', 'component2']
AUTO_LOAD = ['auto_component']
CONFLICTS_WITH = ['incompatible_component']
CODEOWNERS = ['@username']
MULTI_CONF = True # Allow multiple instances
```
```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]))
```
```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
```
```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)
```
```python
from esphome.components import binary_sensor, switch
```
Use Docker or create virtual environment:
```bash
pip install -r requirements_dev.txt
```
```bash
pytest
python3 script/run-in-env.py pre-commit run
script/test_build_components -c <component> -t <target>
./script/test_component_grouping.py -e config --all
clang-tidy
```
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
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.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/esphome-development-assistant/raw