Home Assistant

Mesh-to-HA integration via REST API + Long-Lived Access Token.

What the integration can do

• Smart Home widget with person status, energy consumption, issues
• HA health indicator in the Command Overview banner (shows updates + unresolved issues)
• Z2M auto-discovery via the HA template API (see Zigbee2MQTT)
• ESP auto-discovery when ESP devices are connected via HA

Prerequisites

• Home Assistant 2024.x or newer
• Long-Lived Access Token from the HA profile (Profile → Security → Long-Lived Access Tokens → "Create Token")
• HA must be reachable from the Mesh container (network check: curl -H "Authorization: Bearer $TOKEN" https://home.example.com/api/)

Setup in Mesh

1. Admin → Integrations → Home Assistant
2. Fields:
   • baseUrl — e.g. https://homeassistant.local (no trailing slash)
   • token — the long-lived token
   • esphomeGroupEntity (optional) — if you use legacy ESP via HA group
   • zigbee2mqttGroupEntity (optional) — if Z2M is in ha mode
3. Save → connection is tested immediately

Using the widget

Admin → Content → Widgets → "Home Assistant" or "Smart Home".

• homeassistant — compact sensor list with person status and energy
• smartHome — larger overview with KPIs (lights on, temperature, consumption)

Troubleshooting

• Token invalid → regenerate from HA profile; old tokens are invalidated on password reset
• CORS error in browser console — Mesh calls HA from the server (container), should never be CORS. If it is: check reverse proxy headers
• esphomeGroupEntity shows nothing — the group must exist AND contain devices. Test in HA: Developer Tools → Templates → {{ states.group.esphome.attributes.entity_id }}

API endpoints (for debugging)