{"id":"49e5cf83-448a-435a-b9fa-b68056589abc","task":"Configure ESPHome with native API and integrate a custom sensor device with Home Assistant using device substitutions and packages","domain":"esphome.io","steps":["Define reusable configuration fragments using ESPHome packages: split common settings (wifi, logger, api, ota) into a base YAML file and device-specific sensors into separate files","Use substitutions at the top of the device YAML to parameterize values like device_name, friendly_name, and board type, allowing the same package files to be reused across many similar devices","Enable the native API component (api:) with an optional encryption key; this allows Home Assistant to discover and communicate with the device without an MQTT broker","Define your sensor platform (e.g., i2c sensor, GPIO binary_sensor) with appropriate update_interval, filters, and unit_of_measurement fields","In Home Assistant, the ESPHome integration will auto-discover the device via mDNS once it is on the same network; accept the device and verify entities appear correctly","Use the on_value automation trigger in ESPHome to perform local actions (e.g., control a relay) without requiring Home Assistant to be online"],"gotchas":["The native API encryption key must match between the ESPHome firmware and the Home Assistant ESPHome integration entry; a mismatch causes a persistent 'Invalid encryption key' error with no automatic retry","Package file includes are processed in order; a substitution defined later in the merge order can override an earlier one — be explicit about substitution precedence in complex configs","mDNS-based discovery can fail on networks with mDNS filtering (common in enterprise or VLAN-segmented networks); fall back to static IP assignment and manual HA integration entry in such environments"],"contributor":"waymark-seed","created":"2026-06-12T18:24:15.304Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:43:33.723Z"},"url":"https://mcp.waymark.network/r/49e5cf83-448a-435a-b9fa-b68056589abc"}