zackwag/ecobeealerts2mqtt repository overview

⁠ecobeeAlerts2mqtt

Polls ecobee for thermostat alerts/reminders (filter change, maintenance, etc.) and publishes them to Home Assistant via MQTT discovery — one binary_sensor per reminder, on while pending, off once cleared.

Acknowledgement happens on the thermostat itself (or the ecobee app); the next poll picks up that the alert cleared and flips the sensor off. Each reminder gets one stable entity that persists across recurrences (ecobee rotates its internal acknowledgeRef every time the same reminder fires again, but this image keys the entity on the alert's alertNumber instead — a fixed code ecobee documents, e.g. 3140 = HVAC maintenance — so it doesn't spawn a new entity each time). Known maintenance reminders get the same short name ecobee's own app uses (e.g. "HVAC Maintenance", "Furnace Filter", "UV Lamp"); the full alert text is still available as an attribute.

Every enabled configured reminder gets its entity created up front (defaulting to off), not just ones currently due, so you can build a notification against it before it ever fires.

⁠Quick start

services:
  ecobee-alerts-2-mqtt:
    image: zackwag/ecobeealerts2mqtt:latest
    restart: unless-stopped
    environment:
      ECOBEE_API_KEY: "your-ecobee-api-key"
      MQTT_HOST: mqtt.internal
      MQTT_USERNAME: "your-mqtt-username"
      MQTT_PASSWORD: "your-mqtt-password"
    volumes:
      - ./data:/data

1. Register a developer app at ecobee.com → Developer → Create New: Authorization Method ecobee PIN, scope Smart Read. Copy the API key.
2. Run the container with ECOBEE_API_KEY and MQTT_HOST set, /data mounted.
3. docker logs -f it — it'll print a PIN and wait. Go to ecobee.com → My Apps → Add Application, enter the PIN.
4. Once authorized it saves the refresh token to /data/ecobee_token.json and starts polling. Restarts after that are silent — the refresh token rotates on every use and gets re-saved automatically.

⁠Environment variables

⁠Tags

• latest — most recent release
• X.Y.Z — pinned release version

⁠Source

https://github.com/zackwag/ecobeeAlerts2mqtt⁠