Sensors

Up to six optional sensors can be connected to the bridge. They are enabled in the web interface – one firmware for all combinations.

Supported sensors

Default GPIOs per board are listed in the configuration reference.

Enable a sensor

1. Connect itwith the board powered off. On the prebuilt PCBs solder pin headers to the sensor pads first.
2. Open Sensor Configurationtick the sensor and check its GPIO numbers.
3. Save & RestartThe sensor is initialised at boot. If it works, it appears as a tile in the web interface and as an entity in Home Assistant.
4. CheckSystem information lists every sensor as Active, Disabled (failed) or Off.

How sensors are read

Start-up detection

Each enabled sensor gets up to 3 attempts at boot. It only becomes active if it delivers a plausible reading:

A sensor that fails is marked Disabled; the bridge keeps booting normally and the reason is published in sensor_error of the debug topic.

Polling, thresholds and publishing

• All sensors except the PIR are read every Sensor query interval (default 120 s). The PIR is checked every 500 ms.
• A new MQTT message is only sent when a value changed by at least its threshold (temperature 0.5 °C, humidity 1 %, pressure 1 hPa, distance 10 cm, gas 50 – configurable), when the parking or gas-alarm state flips, or when the 2-hour forced update is due.
• The web interface receives every changed value immediately via server-sent events.

Fail-safe

• 5 consecutive invalid readings at runtime disable a sensor until the next restart. Its last value stays visible in red in the web interface, but it is no longer published.
• If the ESP32 crashed (panic or watchdog), all sensors are switched off automatically on the next boot, so a faulty sensor cannot cause a boot loop. Re-enable them in the web interface after fixing the cause.
• Pressing the boot button 3 times within 6 seconds also disables all sensors and restarts.

Several temperature sensors

Only one temperature and one humidity value is published. Priority: BME280 → DS18X20 → DHT22. If a BME280 is enabled, DS18X20 and DHT22 values are not used (even when the BME280 failed).

Sensor details

BME280

Connect VCC (3.3 V), GND, SDA and SCL. The address (0x76 or 0x77) is detected automatically. Pressure is shown in mbar in the web interface and published as hPa (same value).

DS18X20

Only the first sensor on the OneWire bus is read. Self-built boards need the usual 4.7 kΩ pull-up between data and 3.3 V.

DHT22

Reads temperature and humidity. If only one of both values is valid, that one is still used; only when both are invalid does it count as a failed reading.

Parking space detection (HC-SR04)

Mount the sensor above the parking space, pointing down (or at the front wall, pointing at the car). It publishes the measured distance (dist, cm) and whether the space is free (free).

• The bridge remembers the largest distance measured since boot – that is the empty floor.
• free = "true" (space available) when distance + proximity threshold > largest distance.
• free = "false" (occupied) when something is closer than that – a car. The web interface then shows the car in the garage.

Readings above twice the SR04 max. distance are treated as invalid. The HC-SR04 is a 5 V module – on self-built boards bring its echo signal down to 3.3 V with a voltage divider.

HC-SR501 motion

Polled every 500 ms; every change is published immediately as {"motion":"true"} / {"motion":"false"}. Hold time and sensitivity are set with the potentiometers on the module.

MQ4 gas

• gas is the raw ADC value (0–4095) of the analog output. Home Assistant labels it with "ppm", but the value is not calibrated – use it for trends and relative thresholds.
• gas_alarm comes from the module's digital output (alarm when the output is LOW). Set MQ4 digital to 0 if it is not connected.
• The heater of the MQ4 needs a warm-up time after power-on before readings are meaningful.