Sensor Definitions

This page explains all sensor entities available on your UltimateSensor Mini, 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.

Built-in Offsets:

• Temperature: -2.3°C offset applied
• Humidity: +3% offset applied

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. Updates every 60 seconds.

📖 ESPHome BH1750 Documentation

---

Air Quality (SGP41)

Entity	Description	Unit
VOC Index	Volatile Organic Compounds index	index
NOx Index	Nitrogen Oxides index	index

The SGP41 provides air quality indices with temperature/humidity compensation from the SCD41:

• VOC Index: 0-500 (100 = average baseline, higher = more VOCs)
• NOx Index: 0-500 (1 = clean air, higher = more NOx)

📖 ESPHome SGP4x Documentation

---

Presence & Motion Detection (LD2450)

The LD2450 is a millimeter-wave radar that can track up to 3 people simultaneously.

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 (disabled by default)

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 (disabled by default)

📖 Hi-Link LD2450 Datasheet

---

Zone Configuration

Each zone can be configured with these number entities:

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

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	Default
Occupancy Off Delay	Global delay before "no occupancy"	0-600 s	15
Max Distance	Maximum detection distance	0-600 cm	600

---

Voice Assistant & Audio

Media Player

Entity	Type	Description
US Mini Media Player	Media Player	Play audio, TTS, announcements

The media player can:

• Play MP3 files from URLs
• Text-to-speech announcements
• Alarm sounds
• Volume control (0-100%)

📖 ESPHome I2S Audio Documentation

Voice Assistant Controls

Entity	Type	Description
Use wake word	Switch	Enable/disable wake word detection

When enabled, the device continuously listens for the configured wake word and processes voice commands through Home Assistant.

📖 ESPHome Voice Assistant Documentation

---

LEDs

Entity	Type	Description
Front light	Light	RGB LED on front of device
Back light	Light	RGB LED on back of device

Both are WS2812B RGB LEDs controllable via Home Assistant.

Voice Feedback:

• Front LED turns red when wake word is detected
• LED turns off when voice processing starts

📖 ESPHome FastLED Light Documentation

---

Device Controls

Entity	Type	Description
Restart	Button	Restart the device
CO2 manual calibration	Button	Trigger CO₂ calibration (outdoor, 420 ppm)
Factory Reset	Button	Full factory reset (disabled by default)

---

Diagnostic Entities

Entity	Description
IP address	Current IP address
Connected SSID	WiFi network name
Connected BSSID	WiFi access point MAC
MAC Address	Device MAC address
WiFi Signal	Signal strength (dBm)
CPU Temperature	ESP32-S3 internal temperature
ESPHome Version	ESPHome firmware version
Software Version	UltimateSensor Mini software version
Hardware Version	Hardware variant
API Connection	Home Assistant connection status

---

ESPHome Configuration

The UltimateSensor Mini uses ESPHome with the following key substitutions:

substitutions:
  device_name: ultimatesensor-mini
  friendly_name: "UltimateSensor Mini"
  project_version: "2.15"
  ultimatesensor_mini_hardware_version: "V1"  # or specific variant

GitHub Source Code

All firmware configurations are open source:

• Basic: ultimatesensor-mini-basic.yaml
• Complete: ultimatesensor-mini-complete.yaml
• Common: ultimatesensor-mini-common.yaml (shared configuration)

👉 github.com/smarthomeshop/ultimatesensor-mini

Adopting in ESPHome

To customize your UltimateSensor Mini:

1. Open ESPHome Dashboard in Home Assistant
2. The device should appear as "Discovered"
3. Click Adopt to add it to your ESPHome
4. Edit the YAML configuration
5. Deploy changes via OTA

---

Differences from UltimateSensor

Feature	Mini	Regular
PIR Sensor	❌	✅
OLED Display	❌	✅
PM Sensor	❌	✅ (Complete)
Voice Assistant	✅	❌
Ethernet/PoE	❌	✅
Status LED	GPIO19	GPIO14
ESP Chip	ESP32-S3	ESP32

See Usage Guide for customization examples.