Sensor Definitions
This page explains all sensor entities available on your UltimateSensor, their meaning, and links to ESPHome documentation for more details.
Environmental Sensors
CO₂, Temperature & Humidity (SCD41)
| Entity | Description | Unit |
|---|---|---|
SCD41 CO2 |
Carbon dioxide concentration | ppm |
SCD41 Temperature |
Ambient temperature | °C |
SCD41 Humidity |
Relative humidity | % |
The SCD41 is a high-accuracy photoacoustic CO₂ sensor with built-in temperature and humidity measurement.
CO₂ Level Guidelines:
| Level | Meaning |
|---|---|
| 400-450 ppm | Fresh outdoor air |
| 600 ppm | Healthy indoor level |
| 800 ppm | Acceptable indoor |
| 1,000 ppm | Ventilation recommended |
| 1,200 ppm | Ventilation necessary |
| 2,000+ ppm | Poor air quality, health effects |
Light Sensor (BH1750)
| Entity | Description | Unit |
|---|---|---|
BH1750 Illuminance |
Ambient light intensity | lux |
Measures light levels from 1 to 65,535 lux.
📖 ESPHome BH1750 Documentation
Air Quality (SGP4x)
| Entity | Description | Unit |
|---|---|---|
VOC Index |
Volatile Organic Compounds index | index |
NOx Index |
Nitrogen Oxides index | index |
The SGP4x provides air quality indices rather than raw ppm values:
- VOC Index: 0-500 (100 = average baseline, higher = more VOCs)
- NOx Index: 0-500 (1 = clean air, higher = more NOx)
Particulate Matter (SPS30): Complete Only
| Entity | Description | Unit |
|---|---|---|
PM <1µm Weight concentration |
Fine particles <1µm | µg/m³ |
PM <2.5µm Weight concentration |
Fine particles <2.5µm | µg/m³ |
PM <4µm Weight concentration |
Coarse particles <4µm | µg/m³ |
PM <10µm Weight concentration |
Coarse particles <10µm | µg/m³ |
PM <0.5µm Number concentration |
Particle count <0.5µm | #/cm³ |
PM <1µm Number concentration |
Particle count <1µm | #/cm³ |
PM <2.5µm Number concentration |
Particle count <2.5µm | #/cm³ |
PM <4µm Number concentration |
Particle count <4µm | #/cm³ |
PM <10µm Number concentration |
Particle count <10µm | #/cm³ |
Typical Particle size |
Average particle size | µm |
Controls:
| Entity | Type | Description | Default |
|---|---|---|---|
PM Sensor |
Switch | Turns the SPS30 on or off | On |
SPS30 Update Interval |
Number | How often the sensor reads data while active | 60 s |
SPS30 Idle Interval |
Number | Pause between measurement cycles; 0 keeps the sensor always on | 5 min |
SPS30 Quiet Hours |
Switch | Stops the fan and laser during the hours below | Off |
SPS30 Quiet Start Hour, SPS30 Quiet End Hour |
Number | Start and end of the quiet hours | 22, 7 |
SPS30 Quiet Hours Active |
Binary | On while the quiet hours are running | |
Night Mode |
Switch | Turns off the OLED display and the PM sensor together | Off |
PM2.5 Guidelines:
| Level | Air Quality |
|---|---|
| 0-10 µg/m³ | Good |
| 10-25 µg/m³ | Moderate |
| 25-50 µg/m³ | Unhealthy for sensitive |
| 50+ µg/m³ | Unhealthy |
Presence & Motion Detection
PIR Motion Sensor
| Entity | Type | Description |
|---|---|---|
PIR Sensor |
Binary | Motion detected (on/off) |
Traditional infrared motion sensor for quick detection of movement. Has a 1-second off delay built in.
mmWave Radar (LD2450)
The LD2450 is an advanced millimeter-wave radar that can track up to 3 people simultaneously, providing position, distance, speed, and angle data.
Note: Hi-Link specifies the LD2450 up to 6 meters. Detection and zone configuration are limited to that range (6000 mm).
Occupancy Sensors
| Entity | Type | Description |
|---|---|---|
Occupancy |
Binary | Overall room occupancy, follows Tracking Presence |
Tracking Presence |
Binary | The radar sees at least one target |
Tracking Moving Target |
Binary | The radar sees a moving target |
Tracking Still Target |
Binary | The radar sees a still target |
Polygon Zone 1 Presence to Polygon Zone 4 Presence |
Binary | Someone is inside that polygon zone |
Target Tracking (3 Targets)
For each target (1, 2, 3):
| Entity | Description | Unit |
|---|---|---|
Target X X |
Horizontal position | mm |
Target X Y |
Distance from sensor | mm |
Target X Speed |
Movement speed | mm/s |
Target X Distance |
Euclidean distance | mm |
Target X Angle |
Angle from sensor center | ° |
Target X Resolution |
Detection resolution | mm |
Counts
| Entity | Description |
|---|---|
Radar Target Count |
All targets the radar sees |
Radar Moving Target Count |
Moving targets |
Radar Still Target Count |
Still targets |
Polygon Zone 1 Target Count to Polygon Zone 4 Target Count |
Number of people in that polygon zone |
People Count |
Running room count based on your entry lines, kept after a restart |
Last Crossing Direction |
Direction of the last entry-line crossing: in or out |
Zone Configuration
Draw zones in the Room Designer of the SmartHomeShop integration. It stores them in these entities:
| Entity | Type | Description |
|---|---|---|
Polygon Zone 1 to Polygon Zone 4 |
Text | Shape of the zone, up to 20 points |
Polygon Exclusion 1, Polygon Exclusion 2 |
Text | Area where targets are ignored |
Entry Line 1, Entry Line 2 |
Text | Line with an in and out direction for people counting |
Polygon Zones Enabled |
Switch | Turns all polygon zones on or off, on by default |
Reset People Count |
Button | Sets People Count back to zero |
The radar also has three rectangular zones of its own: Zone 1 X1, Y1, X2 and Y2, up to Zone 3. Their counts are Zone 1 Target Count to Zone 3 Target Count, with a still and moving version of each. You do not need them when you use polygon zones.
Understanding the Coordinate System
Sensor (0,0)
|
-X <---+---> +X
|
v
+Y (distance from sensor)
- X-axis: Left (negative) to right (positive), in mm
- Y-axis: Distance from sensor, in mm. The Room Designer uses a range of 6000 mm
Global Settings
| Entity | Description | Range |
|---|---|---|
Tracking Presence Timeout |
Time before presence clears after the last detection | 1-600 s |
LD2450 Multi Target |
Track several targets at the same time | on/off |
LD2450 Bluetooth |
Bluetooth of the radar, for the HLK Radar Tool app | on/off |
Display
The UltimateSensor has a built-in SSD1306 OLED display (128x64 pixels) showing:
- CO₂ level (large)
- Temperature
- Humidity
- Light (lux)
- PIR indicator
The display updates automatically. Turn it off with the LCD Display switch. On a Complete device, Night Mode turns off the display and the PM sensor together.
📖 ESPHome SSD1306 Documentation
LED
| Entity | Type | Description |
|---|---|---|
Back Light |
Light | RGB LED on back of device |
The WS2812B LED can be controlled via Home Assistant for status indication or ambient lighting.
Automatic LED Lighting
Since firmware 2.4 the LED can also work by itself. All of this is off by default and stays saved after a restart. Turn on Automatic LED Lighting first. While it is on, the firmware controls the LED. On cloud firmware you can also set this in the SmartHomeShop App.
| Entity | What it does | Default |
|---|---|---|
Automatic LED Lighting |
Main switch | Off |
Motion Light, Motion Light Brightness |
White light on motion from the PIR or the radar | Off, 70% |
Night Light, Night Light Brightness |
Warm light when someone is present during the night hours | Off, 10% |
Night Light Start Hour, Night Light End Hour |
The night hours | 22, 7 |
CO2 LED Warning |
Three orange flashes at the warning level, three red flashes at the critical level | Off |
CO2 Warning Threshold, CO2 Critical Threshold |
The two CO₂ levels | 1000 ppm, 1500 ppm |
CO2 Alert Cooldown |
Wait time between alerts | 5 min |
Device Controls
| Entity | Type | Description |
|---|---|---|
Restart UltimateSensor |
Button | Restart the device |
CO2 manual calibration |
Button | Trigger CO₂ calibration (outdoor, 419 ppm) |
LCD Display |
Switch | Turns the OLED display on or off |
UltimateSensor Firmware Variant |
Select | Chooses the firmware variant, see the Firmware Guide |
LD2450 Restart |
Button | Restarts only the radar |
LD2450 Factory Reset |
Button | Resets the radar, disabled by default |
Diagnostic Entities
| Entity | Description |
|---|---|
IP Address |
Current IP address, disabled by default |
ESP MAC |
Device MAC address, disabled by default |
Connected SSID |
WiFi network name |
Connected BSSID |
WiFi access point MAC, disabled by default |
CPU Temperature |
Internal temperature of the ESP32 |
ESPHome Version |
ESPHome firmware version |
Software Version |
UltimateSensor software version |
Hardware Version |
Hardware variant (V1-Basic/Complete) |
Connection type |
WiFi or Ethernet |
LD2450 Firmware, LD2450 Bluetooth MAC |
Firmware and Bluetooth address of the radar |
UltimateSensor Firmware |
Update entity, disabled by default |
The entities that start with Radar, such as Radar Model and Radar Mounting Mode, tell the Room Designer how the radar is mounted. You do not need to change them. Ethernet firmware has no WiFi entities.
ESPHome Configuration
The UltimateSensor uses ESPHome with the following key substitutions:
substitutions:
device_name: ultimatesensor
friendly_name: "UltimateSensor"
ultimatesensor_hardware_version: "V1-Complete" # or V1-Basic
ultimatesensor_connection_type: "WiFi" # or Ethernet
GitHub Source Code
All firmware configurations are open source:
- WiFi Basic:
ultimatesensor-wifi-basic.yaml - WiFi Complete:
ultimatesensor-wifi-complete.yaml - Ethernet Basic:
ultimatesensor-ethernet-basic.yaml - Ethernet Complete:
ultimatesensor-ethernet-complete.yaml
👉 github.com/smarthomeshop/ultimatesensor
Adopting in ESPHome
To customize your UltimateSensor:
- Open ESPHome Device Builder in Home Assistant
- Click "Adopt" on the discovered device
- Edit the YAML configuration
- Deploy changes via OTA
See Usage Guide for customization examples.