Package layout
Each device has its own manifest at devices/<slug>/packages.yaml. ESPHome merges packages in declaration order; comments in the file document why the sequence matters.
Shared resources (fonts, icons, config templates, generic addons) live under common/ and are included via relative paths.
Load order (summary)
- Device & assets —
device/device.yaml,common/assets/fonts.yaml,common/assets/icons.yaml,device/lvgl_base.yaml,theme/button.yaml - User-configurable templates —
common/config/button.yaml,common/config/display.yaml, twenty ×common/config/button_template.yamlwithvars: { num: "N" } - Addons — connectivity (device-specific), time, backlight, backlight schedule, network, firmware update (from
common/addon/) - LVGL screens — loading first (required first page), then WiFi setup, then button setup
- Main UI —
device/lvgl.yaml,device/sensors.yaml
Folders
| Folder | Role |
|---|---|
common/addon/ | Shared addons: time, backlight, network, OTA update |
common/assets/ | LVGL fonts and Material Design icon font glyphs |
common/config/ | Template entities exposed to HA and the web UI |
devices/<slug>/addon/ | Device-specific addons (e.g. connectivity / page navigation) |
devices/<slug>/device/ | Board pins, display/touch, LVGL pages, scripts |
devices/<slug>/theme/ | Button styles and shared LVGL theming |
The device esphome.yaml only sets substitutions, WiFi, and the remote packages.setup include — everything else comes from this tree.