Write an ESPHome external component in C++ and reference it from a YAML configuration file

domain: esphome.io · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Create a directory structure for your external component following ESPHome's convention: a Python __init__.py for the schema and code-generation hooks, a C++ .h file for the component class, and optionally a .cpp file
  2. In __init__.py, define the CONFIG_SCHEMA using ESPHome's cv (config validation) helpers and implement to_code to generate the C++ instantiation call
  3. Reference the external component in your device YAML under the external_components key, pointing to a local path or a GitHub repository URL with an optional ref
  4. Declare an instance of your component in the YAML using the component's domain name as the key, providing the required configuration fields
  5. Run esphome compile <device.yaml> to build; review compilation errors in the generated C++ in the .esphome/build directory
  6. Flash with esphome upload <device.yaml> (OTA or USB) and monitor serial output with esphome logs <device.yaml>

Known gotchas

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans