Sensor Definitions
This page provides detailed explanations of all sensors, controls, and entities available on the CeilSense. Use this as a reference to understand what each value means and how to use it.
Quick Navigation
- Presence & Motion (LD2412)
- Environmental Sensors (Complete Only)
- Light Sensor
- Pressure Sensor
- LED Ring
- Device Controls
- Diagnostic Entities
Presence & Motion (LD2412)
The CeilSense uses the Hi-Link LD2412 24GHz mmWave radar sensor for presence and motion detection.
📖 ESPHome Documentation: LD2412 Sensor
Binary Sensors
| Entity | Description |
|---|---|
| Presence | true when any target (moving or still) is detected. This is the main occupancy sensor you'll use for automations like turning lights on/off. |
| Moving Target | true when a moving target is detected. Useful for detecting active movement vs. someone sitting still. |
| Still Target | true when a stationary target is detected. Great for detecting someone sleeping, sitting, or lying still. |
Distance Sensors
| Entity | Description | Range |
|---|---|---|
| Moving Distance | Distance in cm to the detected moving target. | 0-900 cm |
| Still Distance | Distance in cm to the detected still target. | 0-900 cm |
| Detection Distance | Distance in cm to the closest detected target (moving or still). | 0-900 cm |
Energy Sensors
| Entity | Description | Range |
|---|---|---|
| Move Energy | Signal strength of the moving target detection. Higher values = stronger/closer target. | 0-100 |
| Still Energy | Signal strength of the still target detection. Higher values = stronger/closer target. | 0-100 |
Gate Configuration
The LD2412 divides its detection range into 14 gates (0-13). Each gate represents a distance segment of approximately 0.75 meters (with default resolution). You can configure the sensitivity for each gate independently.
| Entity | Description | Range |
|---|---|---|
| Minimum Distance Gate | The closest gate where detection begins. Gates before this are ignored. | 1-12 |
| Maximum Distance Gate | The furthest gate where detection ends. Gates after this are ignored. | 2-13 |
| Presence Timeout | Time in seconds that presence remains true after the target is no longer detected. | 0-65535 s |
Gate Distance Reference
| Gate | Distance (0.75m resolution) | Distance (0.5m resolution) | Distance (0.2m resolution) |
|---|---|---|---|
| 0 | 0 - 0.75m | 0 - 0.5m | 0 - 0.2m |
| 1 | 0.75 - 1.5m | 0.5 - 1.0m | 0.2 - 0.4m |
| 2 | 1.5 - 2.25m | 1.0 - 1.5m | 0.4 - 0.6m |
| 3 | 2.25 - 3.0m | 1.5 - 2.0m | 0.6 - 0.8m |
| 4 | 3.0 - 3.75m | 2.0 - 2.5m | 0.8 - 1.0m |
| 5 | 3.75 - 4.5m | 2.5 - 3.0m | 1.0 - 1.2m |
| 6 | 4.5 - 5.25m | 3.0 - 3.5m | 1.2 - 1.4m |
| 7 | 5.25 - 6.0m | 3.5 - 4.0m | 1.4 - 1.6m |
| 8 | 6.0 - 6.75m | 4.0 - 4.5m | 1.6 - 1.8m |
| 9 | 6.75 - 7.5m | 4.5 - 5.0m | 1.8 - 2.0m |
| 10 | 7.5 - 8.25m | 5.0 - 5.5m | 2.0 - 2.2m |
| 11 | 8.25 - 9.0m | 5.5 - 6.0m | 2.2 - 2.4m |
| 12 | 9.0 - 9.75m | - | 2.4 - 2.6m |
| 13 | 9.75 - 10.5m | - | 2.6 - 2.8m |
Gate Threshold Settings
For each gate (0-13), you can set move and still thresholds:
| Entity | Description | Range |
|---|---|---|
| Gate X Move Threshold | Energy level required to detect movement at gate X. Lower = more sensitive, higher = less sensitive. | 0-100 |
| Gate X Still Threshold | Energy level required to detect still presence at gate X. Lower = more sensitive, higher = less sensitive. | 0-100 |
Tip: If a gate shows constant high energy when the room is empty, increase its threshold above that energy level.
Gate Energy Sensors (Engineering Mode)
When Engineering Mode is enabled, you can see real-time energy readings per gate:
| Entity | Description | Range |
|---|---|---|
| Gate X Move Energy | Current movement energy detected at gate X. Compare this to Move Threshold to understand triggers. | 0-100 |
| Gate X Still Energy | Current still energy detected at gate X. Compare this to Still Threshold to understand triggers. | 0-100 |
LD2412 Controls
| Entity | Type | Description |
|---|---|---|
| Engineering Mode | Switch | Enables detailed gate-by-gate energy sensors for tuning. Turn off after tuning to reduce data traffic. |
| Bluetooth | Switch | Enables the LD2412's Bluetooth for connecting with the HLK Radar Tool app. |
| Start Dynamic Background Correction | Button | Calibrates the sensor to the current (empty) room. Room must be empty! |
| Factory Reset | Button | Resets all radar settings to factory defaults. |
| Restart Radar | Button | Restarts the LD2412 sensor without rebooting the entire device. |
| Query Params | Button | Refreshes all sensor values from the radar. |
LD2412 Configuration
| Entity | Type | Description | Options |
|---|---|---|---|
| Distance Resolution | Select | Changes the distance per gate. Smaller = more precision, but shorter range. | 0.75m (default), 0.5m, 0.2m |
| LD2412 Mode | Select | Operating mode of the radar. | Normal, Engineering, Dynamic Background Correction |
LD2412 Diagnostic
| Entity | Description |
|---|---|
| LD2412S FM Version | Firmware version of the LD2412 radar module. |
| LD2412S Mac | Bluetooth MAC address of the LD2412 (for HLK Radar Tool app). |
Environmental Sensors (Complete Only)
The CeilSense Complete includes the Sensirion SCD41 sensor for CO₂, temperature, and humidity measurement.
📖 ESPHome Documentation: SCD4x Sensor
SCD41 Sensors
| Entity | Description | Range | Accuracy |
|---|---|---|---|
| SCD41 CO2 | Carbon dioxide concentration in parts per million (ppm). | 400-5000 ppm | ±(50 ppm + 2.5-5% of reading) |
| SCD41 Temperature | Ambient temperature. Note: Includes offset compensation for heat from electronics. | -10 to +60°C | ±1.5°C |
| SCD41 Humidity | Relative humidity percentage. | 0-100% RH | ±9% RH |
CO₂ Level Reference
| Level | Meaning | Action |
|---|---|---|
| 400-450 ppm | Fresh outdoor air | Excellent |
| 450-600 ppm | Good indoor air | Good |
| 600-800 ppm | Acceptable | Adequate |
| 800-1000 ppm | Moderate | Consider ventilation |
| 1000-1200 ppm | Poor | Ventilation recommended |
| 1200-2000 ppm | Bad | Ventilation necessary |
| >2000 ppm | Very poor | May cause drowsiness, headaches |
SCD41 Controls
| Entity | Type | Description |
|---|---|---|
| CO2 manual calibration (fresh air ≥3min) | Button | Calibrates CO₂ sensor to 426 ppm. Ensure room has fresh air for at least 3 minutes before pressing. |
| SCD4x Extra Temperature Offset (°C) | Number | Additional temperature offset on top of the built-in 10°C compensation. Adjust if readings are consistently off. Range: -20 to +20°C. |
| SCD4x Humidity Offset (%) | Number | Humidity offset to correct readings. Range: -20 to +20%. |
SCD41 Configuration (via ESPHome)
These settings can be changed by adopting the device in ESPHome:
| Substitution | Default | Description |
|---|---|---|
scd4x_measurement_mode | low_power_periodic | Measurement mode. Options: periodic (5s), low_power_periodic (30s) |
scd4x_update_interval | 30s | How often readings are updated. |
scd4x_asc | false | Automatic Self Calibration. Enable only if room regularly gets fresh air. |
scd4x_temperature_offset | 10.0 | Base temperature offset for ESP heat compensation. |
Light Sensor
The CeilSense uses the BH1750 ambient light sensor to measure illuminance (lux).
📖 ESPHome Documentation: BH1750 Sensor
BH1750 Sensors
| Entity | Description | Range |
|---|---|---|
| BH1750 Illuminance | Light intensity in lux. Useful for light-based automations. | 0-65535 lux |
Lux Level Reference
| Lux | Environment |
|---|---|
| 0.0001 | Moonless night sky |
| 0.25 | Full moon on a clear night |
| 1 | Candle at 1m distance |
| 50 | Living room lighting |
| 100 | Very dark overcast day |
| 300-500 | Office lighting |
| 1000 | Overcast day |
| 10000-25000 | Full daylight (indirect sun) |
| 32000-100000 | Direct sunlight |
Pressure Sensor
The CeilSense uses the Bosch BMP388 barometric pressure sensor.
📖 ESPHome Documentation: BMP3XX Sensor
BMP388 Sensors
| Entity | Description | Range | Accuracy |
|---|---|---|---|
| BMP3xx Pressure | Atmospheric pressure in hectopascals (hPa). | 300-1100 hPa | ±0.08 hPa |
| BMP3xx Temperature | Temperature from the pressure sensor (less accurate than SCD41). | -40 to +85°C | ±0.5°C |
Pressure Reference
| Pressure | Weather Indication |
|---|---|
| >1020 hPa | High pressure - generally good weather |
| 1013 hPa | Standard atmospheric pressure at sea level |
| 1000-1013 hPa | Normal pressure |
| <1000 hPa | Low pressure - possible storms or rain |
Note: The BMP388 pressure reading is also used for ambient pressure compensation of the SCD41 CO₂ sensor, improving accuracy.
LED Ring
The CeilSense features a ring of 16 individually addressable RGB LEDs (WS2812B).
📖 ESPHome Documentation: ESP32 RMT LED Strip
LED Controls
| Entity | Type | Description |
|---|---|---|
| CeilSense Status LED | Light | Control the LED ring color, brightness, and effects. |
Built-in Effects
| Effect | Description |
|---|---|
| Circular Loading Effect | Circular loading animation used during startup. Color changes based on boot phase. |
Startup LED Colors
During boot, the LED ring indicates which sensors are being initialized:
| Color | Boot Phase |
|---|---|
| Blue | Initial boot |
| Cyan | Phase 1: LD2412 check |
| Magenta | Phase 2: LD2412 initialization |
| Green | Phase 3: SCD41 check (Complete only) |
| Orange | Phase 4: BH1750 (light sensor) check |
| White (solid, 3s) | All sensors OK - boot complete |
| Red (solid, 20s) | Boot failed - sensor error |
Device Controls
Switches
| Entity | Description |
|---|---|
| LD2412 Debug Mode | Enables debug LED effects showing radar distance detection. |
| Disable Bluetooth After Boot | When enabled, disables Bluetooth after boot to save power. Default: ON. |
Buttons
| Entity | Description |
|---|---|
| Restart Device | Restarts the entire CeilSense device. |
| Factory Reset | Resets all settings to factory defaults. Use with caution! |
Selects
| Entity | Description | Options |
|---|---|---|
| Firmware Type | Switch between WiFi and Ethernet firmware. | WiFi, Ethernet |
About Firmware Type Selector
The CeilSense ships with WiFi firmware by default. You can switch to Ethernet firmware using this selector.
⚠️ Important: Connect your Ethernet cable before switching! WiFi stops working immediately after the switch.
👉 See Network Configuration for detailed instructions and requirements.
Diagnostic Entities
Device Information
| Entity | Description |
|---|---|
| Software Version | Current firmware version of the CeilSense. |
| Hardware Version | Hardware revision of the CeilSense (v1). |
| Device Info | ESPHome device information. |
| ESP Reset Reason | Reason for the last device restart. |
| CPU Temperature | Internal temperature of the ESP32-S3 chip. |
Network
| Entity | Description |
|---|---|
| RSSI | WiFi signal strength in dBm. Values closer to 0 = better signal. |
| Uptime | Time since last reboot. |
Firmware Update
| Entity | Description |
|---|---|
| CeilSense Firmware | Update entity for OTA firmware updates. Shows available updates and allows installation. |
Entity Categories
Entities in Home Assistant are organized into categories:
| Category | Description |
|---|---|
| Sensors | Read-only measurement values (CO₂, temperature, presence, etc.) |
| Binary Sensors | On/off states (presence detected, moving target, etc.) |
| Controls | User-adjustable settings (thresholds, offsets, etc.) |
| Configuration | Device configuration options (usually hidden by default) |
| Diagnostic | Technical information (firmware version, signal strength, etc.) |
Need Help?
- Check the Calibration Guide for tuning instructions
- Check the Troubleshooting page for common issues
- Check the FAQ for frequently asked questions
- Join our Discord community for support