Configuration reference

All settings are made in the web interface and stored in the ESP32's flash (NVS). This page lists every field with its key, default and effect.

How settings are stored

Settings live in the NVS namespace hcpbridgeesp32. On the very first boot (and after a factory reset) the defaults from src/configuration.h are written; afterwards only the web interface changes them.
Each form saves only its own fields, then the device restarts.
Password fields are never sent back to the browser – they show * when set. Submitting * keeps the stored password.
The same data is available as JSON via GET /config and can be written with POST /config – see HTTP API.
The Key column is the NVS key and the JSON field name.

Basic configuration

Field	Key	Default	Description
Enable Wi-Fi access point	`wifi_ap_enabled`	on	Runs the hotspot in parallel to the Wi-Fi client. SSID = hostname, channel 1, max. 4 clients, IP `192.168.4.1`.
Wi-Fi SSID	`wifi_ssid`	empty	Network to join. Empty = no client connection (hotspot only).
Wi-Fi password	`wifi_pass`	empty	Printable ASCII only.
Access point password	`wifi_ap_pass`	`gifford47`	Hotspot password. Shorter than 8 characters → the default is used.
Connect to strongest AP	`wifi_best_ap`	on	Scans all channels and joins the access point with the best signal. Turn off on single-AP networks for a slightly faster (but signal-agnostic) connect.
Hostname	`hostname`	`HCPBRIDGE`	Wi-Fi hostname and hotspot SSID.
MQTT server	`mqtt_server`	`192.168.1.100`	Broker host name or IP.
MQTT port	`mqtt_port`	`1883`	Plain MQTT (no TLS).
MQTT user	`mqtt_user`	`mqtt`
MQTT password	`mqtt_pass`	`password`
Device ID	`device_id`	`hcpbridge`	Topic prefix `hormann/<device_id>/` and part of all Home Assistant unique IDs. Max. 14 characters; must be unique per bridge.
Device name	`device_name`	`Garage Door`	Home Assistant device name and name of the cover entity; also used as the device identifier, so use a different name per bridge. Shown as page title in the web interface.
Enable serial debug	`debug_enabled`	off	Log output on the USB serial port at 9600 baud.
Web password	`www_pass`	empty	Empty = no login. Otherwise HTTP basic auth with user `admin`.

MQTT server, user, password and the hostname are held in 64-byte buffers – keep them below 64 characters.

Sensor configuration

Sensor selection

All sensors are off by default.

Field	Key	Sensor
Temperature / humidity / pressure	`sen_bme_en`	BME280 (I²C, address 0x76 or 0x77)
Temperature	`sen_ds18_en`	DS18X20 (OneWire, first sensor on the bus)
Temperature / humidity	`sen_dht_en`	DHT22
Distance / parking space	`sen_sr04_en`	HC-SR04 ultrasonic
Motion	`sen_sr501_en`	HC-SR501 PIR
Gas	`sen_mq4_en`	MQ4 methane / natural gas

Pin definition

Defaults depend on the firmware environment. 0 means "not set".

Field	Key	`esp32` / v1 / M5Stack*	HCP v2	HCP v3
I2C SDA	`sen_i2c_sda`	21	21	21
I2C SCL	`sen_i2c_scl`	22	33	33
DHT data	`sen_dhtdatapin`	27	27	26
DS18X20	`sen_ds18x20pin`	4	4	4
SR04 trigger	`sen_sr04trigpin`	5	5	5
SR04 echo	`sen_sr04echopin`	18	48	27
SR501	`sen_sr501pin`	34	34	32
MQ4 analog	`sen_mq4analog`	0	36	35
MQ4 digital	`sen_mq4digital`	0	15	15

* m5stack-atom-lite uses SDA 25 / SCL 21.

Sensor adjustments

Field	Key	Default	Description
Sensor query interval	`sen_StInterval`	120 s	How often all sensors except the motion sensor are read (the PIR is checked every 500 ms).
Temperature threshold	`sen_temp_thresh`	0.5 °C	Minimum change before a new value is published.
Humidity threshold	`sen_hum_thresh`	1 %	Whole numbers.
Pressure threshold	`sen_pres_thresh`	1 mbar	Whole numbers.
Proximity threshold	`sen_prox_thresh`	10 cm	Distance change that triggers a publish, and the margin of the parking detection.
Gas threshold	`sen_gas_thresh`	50	Change of the raw analog value before publishing.
SR04 max. distance	`sen_sr04maxdist`	150 cm	Expected range; readings above twice this value are treated as invalid.

Regardless of the thresholds, all sensor values are re-published at least every 2 hours. Details: Sensors.

I/O configuration

All four channels are disabled by default. See Digital inputs & outputs for wiring.

Inputs (In1 = `io_in1_`, In2 = `io_in2_`)

Field	Key	Default	Description
Enable Input	`io_in1_en`	off	Activates the channel and its `binary_sensor`.
Name	`io_in1_name`	`Input 1`	Entity name in Home Assistant.
GPIO	`io_in1_pin`	12 / 14 on HCP v2/v3, otherwise 0	0 = not configured.
Pull resistor	`io_in1_pull`	0 – none	0 none (external, correct for the HCP PCBs), 1 internal pull-up, 2 internal pull-down.
Active low	`io_in1_inv`	off	Inverts the input.
Local action	`io_in1_act`	0 – none	0 none, 1 impulse/toggle door, 2 open, 3 close, 4 stop, 5 toggle light, 6 vent, 7 half, 8 toggle Out1, 9 toggle Out2.

Outputs (Out1 = `io_out1_`, Out2 = `io_out2_`)

Field	Key	Default	Description
Enable Output	`io_out1_en`	off	Activates the channel and its `switch`.
Name	`io_out1_name`	`Output 1`	Entity name in Home Assistant.
GPIO	`io_out1_pin`	Out1: 37 (v2) / 25 (v3) · Out2: 35 (v2) / 22 (v3) · otherwise 0	0 = not configured.
Active low	`io_out1_inv`	off	Inverts the GPIO level.
Restore after reboot	`io_out1_rst`	off	On = the last state is stored and restored at boot. Off = always off after a restart.

Expert configuration

Field	Key	Default	Description
RS485 TXD	`rs485_txd`	17 (`esp32`, v1, v2) · 19 (v3) · 13 (StampS3) · 22 (Atom Lite)	UART pins of the RS485 converter (57600 baud, 8E1).
RS485 RXD	`rs485_rxd`	16 (`esp32`, v1) · 18 (v2, v3) · 15 (StampS3) · 19 (Atom Lite)	UART pins of the RS485 converter (57600 baud, 8E1).

Entity names

Names of the Home Assistant entities created by discovery. Changing a name only changes the display name; the unique ID stays the same.

Field	Key	Default
Debug string	`gd_debug_string`	Debug
Restart reason	`gd_dg_rst_reas`	Restart Reason
Temperature	`sensor_temp`	Temperature
Humidity	`sensor_humidity`	Humidity
Pressure	`sensor_atmpress`	Ambient pressure
Free distance	`sensor_freedist`	Free distance
Park availability	`sen_park_avail`	Park available
Motion	`sen_motion`	Motion
Gas level	`sensor_gas`	Gas Level
Gas alarm	`sen_gas_alarm`	Gas Alarm

Compile-time options

A few values are not configurable at runtime and are set in src/configuration.h before building:

Constant	Default	Meaning
`OTA_USERNAME` / `OTA_PASSWD`	`admin` / `admin`	Login of the OTA update page `/update`.
`WWW_USER`	`admin`	User name for the web password.
`GD_LIGHT`, `GD_VENT`, `GD_HALF`, `GD_TOGGLE`, `GD_STATUS`, `GD_DET_STATUS`, `GD_POSITIOM`, `GD_AVAIL`	Light, Vent, Half Open, Toggle, Status, Detailed Status, Position, Available	Names of the remaining Home Assistant entities.
`READ_DELAY`	2000 ms	Interval of the MQTT task that publishes door state changes.
`AlignToOpenHab`	not defined	Uncomment to use openHAB-style cover states (`UP`/`DOWN`/`STOP`) and the position as cover value.
`IO_DEBOUNCE_MS` / `IO_POLL_INTERVAL_MS`	50 ms / 20 ms	Debounce and polling of the digital inputs.
`HA_VERSION`	current version	Firmware version shown in the UI, in Home Assistant and in the release file name.

All other values in configuration.h (Wi-Fi, MQTT, pins, thresholds) are only the first-boot defaults of the settings above.

Resetting the configuration

Web interface: System information → Factory Reset (GET /reset).
Boot button: press it 5 times within 6 seconds (full reset) or 3 times (disable all sensors only) – see Reset button.

Configuration reference

How settings are stored

Basic configuration

Sensor configuration

Sensor selection

Pin definition

Sensor adjustments

I/O configuration

Inputs (In1 = io_in1_*, In2 = io_in2_*)

Outputs (Out1 = io_out1_*, Out2 = io_out2_*)

Expert configuration

Entity names

Compile-time options

Resetting the configuration

Inputs (In1 = `io_in1_`, In2 = `io_in2_`)

Outputs (Out1 = `io_out1_`, Out2 = `io_out2_`)