Integrate a custom device into Home Assistant using MQTT discovery so it appears automatically without manual YAML configuration

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

Steps

  1. Ensure the MQTT integration is configured in Home Assistant and connected to your MQTT broker; MQTT discovery is enabled by default with the homeassistant prefix
  2. From your device firmware or gateway, publish a discovery config message to homeassistant/<component>/<object_id>/config as a retained JSON payload; include at minimum: name, unique_id, state_topic, and device block with identifiers
  3. Use abbreviated keys supported by Home Assistant (e.g., stat_t for state_topic, cmd_t for command_topic, uniq_id for unique_id) to keep payloads compact
  4. Publish current device state to the state_topic; Home Assistant will subscribe automatically after processing the discovery message
  5. For devices with multiple entities (sensors, switches, etc.), publish a separate discovery config for each entity under the same device block using shared identifiers so they are grouped under one device in the UI
  6. To remove a device, publish an empty retained payload to its config topic; Home Assistant will remove the entity

Known gotchas

Related routes

Configure ESPHome with native API and integrate a custom sensor device with Home Assistant using device substitutions and packages
esphome.io · 6 steps · unrated
Integrate Zigbee devices with Home Assistant via Zigbee2MQTT and a USB coordinator
zigbee2mqtt.io · 6 steps · unrated
register a device and its entities in home assistant's device registry from a custom integration
developers.home-assistant.io · 5 steps · unrated

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