🚀 Buy a ready to use kit here
Discussion & orders
Getting started prebuild PCBs
If you like HCPBridge and want to support its development, consider sponsoring me! Your contribution helps cover development, testing and bug-fixing.
Emulates Hörmann UAP1-HCP (HCP2) using an ESP32 + RS485 converter and exposes garage door controls via MQTT and a web UI.
- Quick Start
- Compatibility
- Features
- Installation
- Web Interface
- MQTT & Home Assistant
- Configuration
- OTA Updates
- Sensors (optional)
- Troubleshooting
- Development & Contributing
- License
- Screenshots
- Flash the firmware to an ESP32 (see
docs/for build instructions). - Connect ESP32 TX/RX to an RS485 converter and wire to the HCP bus.
- Power on the motor control board and run a BUS scan (see Installation).
- Connect to the device hotspot or your Wi-Fi and open the web interface (details below).
- Configure Wi-Fi and MQTT via the web UI or
config.json.
If you just want to test: connect to hotspot hormann / password gifford47, open the web UI and set your MQTT broker.
| Supported motors (UAP1-HCP / HCP2-Bus / Modbus) |
|---|
| SupraMatic E/P Serie 4 |
| ProMatic Serie 4 |
| Rollmatic v2 |
Not compatible with E3 series motors (different protocol / layout). For older HCP1 hardware see other projects: hgdo, hoermann_door, hormann-hcp.
- Read door status: open/closed/position, light on/off
- Control: open, close, stop, light toggle, set position (half/vent/custom)
- MQTT with Home Assistant Auto Discovery
- Web Interface for configuration & control
- OTA Updates
- First-use hotspot (for out-of-the-box Wi-Fi setup)
- Support for ESP32-S1/S2/S3 families
- Optional external sensors (DS18x20, BME280, DHT22, HC-SR04, HC-SR501, MQ4)
- Efficient MQTT traffic (only publish on state change)
- Support multiple HCP Bridges for several doors
- Just plug-in the provided RJ12 cable (see Screenshots)
See also: Getting started prebuild PCBs
- Old hardware: trigger BUS scan by flipping the last DIP switch (ON → OFF). Note: BUS power (+24V) may be removed when no devices detected — you can "jump start" using +24V from motor connectors if necessary.
- New hardware: BUS scan via the LC display in menu
37. See:
To access the web interface, first connect to the device’s automatic Wi-Fi hotspot.
By default, the hotspot is named HCPBRIDGE and secured with the password gifford47.
Once connected, open a web browser and go to:
http://[deviceip]
(you can also try http://192.168.4.1 if you are connected directly to the hotspot).
When the login screen appears, use the following default credentials:
- Username:
admin - Password: (leave empty)
After logging in, you will see the main control panel of the device.
For performing OTA (Over-The-Air) updates, authentication uses a different set of credentials:
- Username:
admin - Password:
admin
The Boot button (GPIO 0) supports two reset levels:
| Presses (within 6s) | Action |
|---|---|
| 3x | Disable all sensors and restart (sensor recovery) |
| 5x | Full factory reset (clear all preferences) |
Sensor recovery (3x press): If a faulty sensor causes boot problems, press the button 3 times to disable all sensors. The device will restart normally and you can fix the sensor configuration in the Web UI.
Automatic crash recovery:
If a sensor causes a crash (panic/watchdog), the firmware detects this on the next boot via esp_reset_reason() and automatically disables all sensors.
Full factory reset (5x press): Clears all Wi-Fi, MQTT and sensor configuration. The device will restart with its default hotspot.
hormann/<device_id>/state -> JSON with state/position/light/temperature
hormann/<device_id>/command -> payloads: OPEN, CLOSE, STOP, LIGHT_TOGGLE, SET_POSITION:50
hormann/<device_id>/sensor/
The project publishes Home Assistant discovery messages for:
- cover (shutter) entity with position support
- binary_sensor for light / door open
- sensors for temperature / humidity (if present)
Example configuration.yaml is not required when discovery is enabled.
You can configure:
- Wi-Fi (hotspot or STA)
- MQTT broker settings (host, port, user, password, base topic)
- Device name and ID
- Sensor thresholds and mapping
Configuration can be done via the Web UI.
Sensors are manually enabled via the Web UI under Sensor Configuration. Each sensor can be individually activated with a checkbox — no auto-detection. If an enabled sensor is not connected or fails to initialize, the ESP will continue booting normally and report the error via the debug MQTT entity.
Supported sensors:
- BME280 (I2C) — temperature, humidity, pressure
- DS18x20 (OneWire) — temperature
- DHT22 — temperature, humidity
- HC-SR04 (ultrasonic) — distance / parking space detection
- HC-SR501 (PIR) — motion
- MQ4 (analog) — methane / natural gas
Sensor readings are published to MQTT under hormann/<device_id>/sensor with configurable thresholds. Pins and thresholds are configurable in the Web UI.
The HC-SR04 ultrasonic sensor can be used to detect available parking space. The "Parking" feature (displayed as "free": true/false in MQTT):
- Measures distance to an object (e.g., car in garage)
- Tracks the maximum distance ever measured (represents empty space baseline)
- Compares current distance to max with a proximity threshold (default: 10cm)
- Publishes
truewhen(current_distance + threshold) > max_distance→ space available ✅ - Publishes
falsewhen occupied → no parking space ❌
Configuration:
- Enable sensor: Activate HC-SR04 in Sensor Configuration tab
- Trigger & Echo pins: Set custom GPIO pins for your board
- Max distance: Sensor range limit (default: 150cm)
- Proximity threshold: Distance margin for detection (default: 10cm, configurable as
sen_prox_thresh)
- Each sensor is tested up to 3 times during boot before being marked as failed
- Failed sensors are shown with red text in the Web UI (last known value preserved)
- During normal operation, 5 consecutive poll failures disable a sensor until reboot
- MQTT discovery and publishing skip failed sensors — no stale data sent to Home Assistant
- See Factory Reset & Sensor Recovery for crash recovery options
A small implementation supports a ventilation (vent) position and custom positioning. The vent behaviour uses a configured numeric position value. You can set custom positions with MQTT SET_POSITION.
- No BUS devices found: check wiring, test +24V, try "jump start" with motor connector +24V. For old HW, ensure DIP-based scan is toggled.
- Cannot reach Web UI: connect to hotspot
HCPBRIDGE/ try http://192.168.4.1. Check firewall or captive-portal on client device. - MQTT messages not arriving: verify broker settings, credentials, and that device is connected to Wi-Fi. Use a local MQTT client (mosquitto_sub) to debug.
- OTA fails: confirm OTA credentials (admin/admin) and sufficient flash space. Use serial logs to inspect errors.
If you need help, start a discussion in the repo.
Contributions welcome! Please:
- Fork the repo
- Create a feature branch (
feat/my-change) - Open a PR with a clear description and tests where possible
This project is licensed under the MIT License — see LICENSE for details.
