MQTT & Home Assistant

The bridge publishes everything under hormann/<device_id>/ and announces itself to Home Assistant via MQTT discovery. No YAML configuration is needed.

Quick start

1. Have an MQTT brokere.g. the Mosquitto add-on in Home Assistant, with the MQTT integration set up.
2. Enter the brokerin the bridge's Basic Configuration (server, port, user, password) and save.
3. DoneAfter the restart the device Garage Door (your Device name) appears under Settings → Devices & services → MQTT.

State topics

Published by the bridge. <id> is the Device ID (default hcpbridge).

* Motion changes are published immediately as a separate retained {"motion":"true"} message on the same topic.

state

{
  "valid": true,
  "doorposition": 100,
  "lamp": "false",
  "doorstate": "open",
  "detailedState": "open",
  "vent": "close",
  "half": "close"
}

sensor

{"temp":"21.4","hum":"48.0","pres":"1013.2","dist":"142","free":"true","motion":"false","gas":"412","gas_alarm":"false"}

Only enabled, working sensors are included. Values are strings. free is "true" when the parking space is available. The message is published when a value changes by more than its threshold, after each MQTT connect and at least every 2 hours.

io

{"in1":"true","in2":"false","out1":"false","out2":"true"}

debug

{"restart_reason":1,"debug":"initial","sensor_error":"HC-SR04: no valid response","io_error":"out1: invalid pin 34"}

restart_reason is the ESP-IDF reset reason (1 power-on, 3 software, 4 panic, 5–7 watchdog, 9 brownout). sensor_error and io_error only appear when something failed.

Command topics

Subscribed by the bridge (hormann/<id>/command/#).

# watch everything
mosquitto_sub -h broker -u mqtt -P password -t 'hormann/hcpbridge/#' -v

# open the door, drive to 50 %, toggle the light
mosquitto_pub -h broker -u mqtt -P password -t 'hormann/hcpbridge/command/door' -m 'open'
mosquitto_pub -h broker -u mqtt -P password -t 'hormann/hcpbridge/command/set_position' -m '50'
mosquitto_pub -h broker -u mqtt -P password -t 'hormann/hcpbridge/command/lamp' -m 'toggle'

Home Assistant entities

Discovery topics follow homeassistant/<component>/<device_id>/<key>/config. All entities belong to one device and use availability.

Sensor and I/O entity names can be changed in the web interface (Expert and I/O Configuration). The device page links back to the bridge's web interface.

Several doors

Use one bridge per operator and give each a unique Device ID and Device name (the name is used as the Home Assistant device identifier), e.g. garage_left / Garage left and garage_right / Garage right.

Automation examples

Entity IDs depend on your names – check them under Settings → Entities.

Close the door in the evening

automation:
  - alias: "Close the garage door at 22:00"
    triggers:
      - trigger: time
        at: "22:00:00"
    conditions:
      - condition: state
        entity_id: cover.garage_door
        state: "open"
    actions:
      - action: cover.close_cover
        target:
          entity_id: cover.garage_door

Notify when the door was left open

automation:
  - alias: "Garage door open for 15 minutes"
    triggers:
      - trigger: state
        entity_id: cover.garage_door
        to: "open"
        for: "00:15:00"
    actions:
      - action: notify.notify
        data:
          message: "The garage door has been open for 15 minutes."

openHAB and other systems

Any MQTT client can use the topics above. For openHAB the firmware can be built with #define AlignToOpenHab in src/configuration.h: the cover then reports UP / DOWN / STOP and uses the position as its value.

ESPHome instead of MQTT

If you prefer the native Home Assistant API, use the ESPHome configuration esphome_hcpbridge.yaml with the esphome-hcpbridge component instead of this firmware. It provides cover, light, vent/half switches and buttons, a state text sensor and the position, and contains ready-to-uncomment blocks for the I/O terminals and sensors.