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

📖 ESPHome SCD4x Documentation

---

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)

📖 ESPHome SGP4x Documentation

---

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

PM2.5 Guidelines (WHO):

Level	Air Quality
0-10 µg/m³	Good
10-25 µg/m³	Moderate
25-50 µg/m³	Unhealthy for sensitive
50+ µg/m³	Unhealthy

📖 ESPHome SPS30 Documentation

---

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.

📖 ESPHome GPIO Binary Sensor

---

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.

Occupancy Sensors

Entity	Type	Description
Occupancy	Binary	Overall room occupancy
Zone 1 Occupancy	Binary	Zone 1 occupied
Zone 2 Occupancy	Binary	Zone 2 occupied
Zone 3 Occupancy	Binary	Zone 3 occupied
Zone 4 Occupancy	Binary	Zone 4 occupied

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	m/s
Target X Distance	Euclidean distance	mm
Target X Angle	Angle from sensor center	°
Target X Resolution	Detection resolution	mm
Target X Active	Target currently detected	on/off

Zone Target Counts

Entity	Description
Zone 1 Target Count	Number of people in Zone 1
Zone 2 Target Count	Number of people in Zone 2
Zone 3 Target Count	Number of people in Zone 3
Zone 4 Target Count	Number of people in Zone 4

📖 Hi-Link LD2450 Datasheet

---

Zone Configuration

Each zone can be configured with these number entities:

Entity	Description	Range
Zone X Begin X	Left boundary	-4000 to 4000 mm
Zone X End X	Right boundary	-4000 to 4000 mm
Zone X Begin Y	Near boundary	0 to 6000 mm
Zone X End Y	Far boundary	0 to 6000 mm
Zone X Occupancy Off Delay	Delay before reporting empty	0-600 s

Understanding the Coordinate System

        Sensor (0,0)
           |
    -X <---+---> +X
           |
           v
          +Y (distance from sensor)

• X-axis: Left (-4000mm) to Right (+4000mm)
• Y-axis: Distance from sensor (0 to 6000mm)

---

Global Settings

Entity	Description	Range
Occupancy Off Delay	Global delay before "no occupancy"	0-600 s
Max Distance	Maximum detection distance	0-600 cm

---

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 and cannot be controlled via Home Assistant.

📖 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.

📖 ESPHome NeoPixelBus Light

---

Device Controls

Entity	Type	Description
Restart UltimateSensor	Button	Restart the device
CO2 manual calibration	Button	Trigger CO₂ calibration (outdoor, 419 ppm)

---

Diagnostic Entities

Entity	Description
IP address	Current IP address
Connected SSID	WiFi network name
Connected BSSID	WiFi access point MAC
ESPHome Version	ESPHome firmware version
Software Version	UltimateSensor software version
Hardware Version	Hardware variant (V1-Basic/Complete)
Connection type	WiFi or Ethernet

---

ESPHome Configuration

The UltimateSensor uses ESPHome with the following key substitutions:

substitutions:
  device_name: ultimatesensor
  friendly_name: "UltimateSensor"
  ultimatesensor_software_version: "1.2"
  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:

1. Open ESPHome Dashboard in Home Assistant
2. Click "Adopt" on the discovered device
3. Edit the YAML configuration
4. Deploy changes via OTA

See Usage Guide for customization examples.