The quickest way to create a messy smart home stack is to publish raw topics without a clear model. Home Assistant integration works best when device identity, telemetry, and commands are explicitly designed.

1. Start from device identity

For each physical device define:

  • stable device ID
  • hardware model and firmware version
  • location metadata
  • capability list

Do not use human-readable room names as unique IDs. IDs should remain stable after renaming.

2. Entity boundaries

One device can expose many entities:

  • temperature sensor
  • humidity sensor
  • battery status
  • signal strength
  • control switch

Keep entities single-purpose. Avoid mixed payloads where one topic carries unrelated values.

3. Topic namespace conventions

Use a clear namespace pattern such as:

  • site/<zone>/<device>/state/<entity>
  • site/<zone>/<device>/cmd/<entity>
  • site/<zone>/<device>/availability

Consistent naming improves automation readability and debugging speed.

4. Discovery payload discipline

MQTT discovery is powerful but easy to misuse. Always include:

  • unique ID per entity
  • device object shared across related entities
  • explicit state class and unit metadata
  • availability topic and payloads

Incorrect discovery metadata produces dashboards that look fine but are semantically wrong.

5. State and command contract

For writable entities, define command semantics explicitly:

  • accepted command values
  • acknowledgement behavior
  • timeout and retry rules
  • idempotent handling of repeated commands

Without this contract, automations can create race conditions.

6. Availability and fault reporting

Availability topics should reflect actual operational state, not just network presence. If sensor reads fail repeatedly, report degraded availability rather than pretending healthy operation.

Include diagnostic entities for error counters when possible.

7. Security baseline

Even in a home setup:

  • enable broker authentication
  • isolate IoT network segment
  • restrict topic ACLs by client
  • avoid broad wildcard write permissions

A compromised low-cost device should not control all automations.

8. Migration and versioning

As firmware evolves, entities may be renamed or split. Plan migration:

  • version your discovery schema
  • keep compatibility aliases temporarily
  • remove deprecated entities with clear rollout steps

This prevents duplicate or orphaned entities in Home Assistant.

A minimal discovery example

To make the discovery discipline above concrete, here is a single temperature sensor published under the homeassistant/ discovery prefix. Home Assistant listens on that prefix by default, so publishing a config topic like homeassistant/sensor/greenhouse_bme280/temp/config is enough for the entity to appear:

{
  "name": "Temperature",
  "unique_id": "greenhouse_bme280_temp",
  "state_topic": "site/greenhouse/bme280/state/temperature",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "state_class": "measurement",
  "value_template": "{{ value_json.temperature }}",
  "availability_topic": "site/greenhouse/bme280/availability",
  "payload_available": "online",
  "payload_not_available": "offline",
  "device": {
    "identifiers": ["greenhouse_bme280"],
    "name": "Greenhouse BME280",
    "manufacturer": "Bosch",
    "model": "BME280",
    "sw_version": "1.4.2"
  }
}

The details that matter here are the ones that are easy to skip. unique_id is what lets you rename and customize the entity from the UI without losing history. state_class: measurement is what makes long-term statistics and the energy/history graphs work correctly. The shared device object (keyed on the same identifiers) is what groups temperature, humidity, and battery under one card instead of scattering three orphan entities across the dashboard.

Publish the config topic retained. If it is not retained, the entity vanishes the moment Home Assistant restarts and only reappears when the device next re-announces itself. The availability topic should also be retained and backed by an MQTT last will so the entity flips to offline when the device drops off the network, rather than showing a stale last reading forever.

Final note

Good MQTT modeling makes Home Assistant feel reliable and understandable. Treat entity and topic design as architecture work, not a last-minute mapping step.

Sources

  • Imported from the previous version of the site (gaborl.hu). Original publication around 2024-07-02.