HCPBridge Documentation
Troubleshooting & FAQ
Most problems fall into one of the categories below. If you are stuck, open a discussion or an issue and include the output of System information.
Operator and bus
| Symptom | Cause / solution |
|---|---|
| Operator shows error 04 | An accessory was added or removed without a bus scan, or the bridge restarted while the operator expected it. Run the bus scan again. |
Bus scan does not find the bridge (display 00/01) | Check the RJ12 wiring (A/B), the 120 Ω resistor and the RS485 pins under Expert Configuration; swap TX/RX. Make sure the converter switches direction automatically. |
| Web interface shows No bus / greyed garage | No valid bus communication yet – run the bus scan; check the cable. |
| No 24 V on the bus (older hardware) | Some operators switch off the bus supply when no accessory is registered. Trigger the scan with the DIP switch (ON → OFF); if needed power the bridge temporarily from the operator's 24 V terminal for the scan. |
| Vent position shown as "stopped" | The firmware detects the vent position when the door stops at position 0x08. Other operators may use a different vent position. |
| Commands are ignored | Only one command can be pending; send the next one after the door reacted. Stop only works while the door is moving. |
Wi-Fi and web interface
| Symptom | Cause / solution |
|---|---|
| Cannot reach the web interface | Connect to the hotspot HCPBRIDGE (password gifford47) and open http://192.168.4.1. Disable mobile data / captive-portal checks on the phone. |
| Hotspot missing | The access point was disabled. Connect via your Wi-Fi, or do a factory reset (5 × boot button). |
| Drop-outs, slow UI | Check the signal in System information: below −80 dBm is too weak. In mesh / multi-AP networks keep Connect to strongest AP enabled. |
| Wi-Fi does not connect | Check SSID and password (printable ASCII only). 2.4 GHz is required. |
| Login prompt | A web password is set: user admin. Forgot it? Factory reset. |
MQTT and Home Assistant
| Symptom | Cause / solution |
|---|---|
| MQTT shows Disconnected | Check server, port (plain MQTT, default 1883), user and password. Test with mosquitto_sub -h broker -u user -P pass -t 'hormann/#' -v. |
| No entities in Home Assistant | The MQTT integration must be set up with discovery prefix homeassistant. Discovery is sent once after boot – restart the bridge. |
| Entities missing or broken topics | The Device ID must be at most 14 characters. |
| Duplicate / unavailable entities | The Device ID was changed – delete the old entities. With several bridges use unique Device IDs and Device names. |
| Sensor entity missing | The sensor failed at boot (see sensor_error in the Debug entity) or is not enabled. |
Sensors and I/O
| Symptom | Cause / solution |
|---|---|
| Sensor shown as Disabled | No plausible reading at boot or 5 failed readings in a row. Check wiring and GPIOs, then restart. |
| All sensors suddenly off | The ESP32 crashed and the crash protection disabled all sensors. Re-enable them one by one to find the culprit. |
| Parking space always "Free" | The reference distance is learned after each restart – if the car was parked during the restart it becomes the reference. Drive out once. See parking detection. |
| Values update slowly | Lower the Sensor query interval or the thresholds. |
| Input always ON / never changes | On the HCP PCBs the pull mode must be none (external) and Active low off; the input needs ≈5 V. Details: Digital I/O. |
io_error in the debug entity | The configured GPIO cannot be used on this chip; the channel was disabled. |
Firmware and updates
| Symptom | Cause / solution |
|---|---|
| OTA login fails | The update page uses admin / admin, independent of the web password. |
| OTA update fails or the bridge does not start afterwards | Make sure the binary matches the board – e.g. v2 needs HCP_Giffordv2-…bin (ESP32-S3), v3 HCP_Giffordv3-…bin. If the bridge no longer starts, flash it via USB with PlatformIO. |
Old …a/…b firmware | Update to the single firmware per board and enable sensors in the web interface. |
Reset button and recovery
The boot button (GPIO 0) counts presses within 6 seconds:
| Presses | Action | LED (HCP v2/v3) |
|---|---|---|
| 3 × | Disable all sensors and restart – use this when a sensor prevents a normal start | blinks 3 times |
| 5 × | Factory reset: erase all settings and restart with the default hotspot | restarts immediately |
After a crash (panic or watchdog) the bridge disables all sensors automatically on the next boot.
Serial debugging
- Enable Enable serial debug in the basic configuration and save.
- Connect USB and open a terminal at 9600 baud (
pio device monitor). - The log shows Wi-Fi events, MQTT connection, sensor and I/O initialisation and commands.
FAQ
Does the bridge need internet or a cloud?
No. Everything runs locally; only your MQTT broker and browser talk to it.
Can I still use the original Hörmann remote controls and buttons?
Yes. The bridge is an additional bus accessory; state changes from remotes and buttons are reported to it.
Can one bridge control two doors?
No – one bridge per operator. Several bridges can share one broker; see Several doors.
Is the configuration lost after a firmware update?
No. Settings are stored in NVS and survive OTA updates. Only a factory reset clears them.