Sensor Definitions

This page matches the current ultimatesensor-v2 firmware in the SmartHomeShop GitHub repository.

Home Assistant entity IDs include your device name as prefix. The ESPHome ID column below is the internal YAML id when the firmware defines one.

UltimateSensor v2 is the full v2 model with ESP32-S3, PIR, microphone, speaker, media player and local wake word. For the compact ESP32-C6 model without voice hardware or PIR, see UltimateSensor Mini v2.

Standard Hardware

Area	Firmware source	Present on UltimateSensor v2
Main platform	`base.yaml`	ESP32-S3, PSRAM, API, OTA, web server
Environmental sensors	`base.yaml`	SCD41, SGP41, BH1750
Presence fallback	`base.yaml`	LD2412 + PIR
Standard tracking radar	`tracking-ld2450.yaml`	LD2450 on factory hardware
Optional tracking upgrade	`tracking-ld2460.yaml`	LD2460 only after replacing/removing LD2450
Voice assistant	`voice-assistant.yaml` or `cloud-voice.yaml`	Included in every UltimateSensor v2 firmware variant: Home Assistant voice on local builds, Cloud Voice on cloud builds
Particulate matter	`complete.yaml`	SPS30 only on Complete variants

Main Presence Logic

Entity name	ESPHome ID	Description
`Occupancy`	`occupancy`	Combined occupancy. Firmware logic is `PIR Motion OR LD2412 Presence OR Tracking Presence`.
`Occupancy Off Delay`	`occupancy_off_delay`	Delay in seconds before combined occupancy turns off.

PIR

Entity name	ESPHome ID	Description
`PIR Motion`	`pir_motion`	Fast first-motion trigger using heat movement.

LD2412 Presence Radar

Entity name	ESPHome ID	Description
`LD2412 Presence`	`ld2412_presence`	Close-range/still-presence fallback used by combined occupancy.
`LD2412 Moving Target`	-	Moving target status.
`LD2412 Still Target`	-	Still target status.
`LD2412 Dynamic Background Correction`	-	Diagnostic status while background correction runs.
`LD2412 Moving Distance`	-	Distance to moving target.
`LD2412 Still Distance`	-	Distance to still target.
`LD2412 Moving Energy`	-	Moving-target signal strength.
`LD2412 Still Energy`	-	Still-target signal strength.
`LD2412 Detection Distance`	-	Closest detected target distance.
`LD2412 Light`	-	Light value reported by the LD2412.

LD2412 Controls

Entity name	Type	Description
`LD2412 Presence Timeout`	Number	Timeout before LD2412 presence clears.
`LD2412 Minimum Distance Gate`	Number	Closest distance gate used for detection.
`LD2412 Maximum Distance Gate`	Number	Furthest distance gate used for detection.
`LD2412 Light Threshold`	Number	Threshold for LD2412 light behaviour.
`LD2412 Engineering Mode`	Switch	Shows detailed tuning data; disabled by default.
`LD2412 Bluetooth`	Switch	Enables LD2412 Bluetooth configuration.
`LD2412 Output Pin Level`	Select	LD2412 output pin behaviour.
`LD2412 Distance Resolution`	Select	LD2412 distance resolution.
`LD2412 Light Function`	Select	LD2412 light function.
`LD2412 Restart`	Button	Restarts the LD2412 module.
`LD2412 Factory Reset`	Button	Factory resets the LD2412 module; disabled by default.
`LD2412 Query Parameters`	Button	Queries LD2412 parameters; disabled by default.
`LD2412 Dynamic Background Correction`	Button	Starts empty-room background correction; disabled by default.
`LD2412 Firmware`	Text sensor	LD2412 firmware version.
`LD2412 Bluetooth MAC`	Text sensor	LD2412 Bluetooth MAC address.

Standard LD2450 Tracking Radar

The factory firmware uses LD2450. These are the entity names Home Assistant shows on UltimateSensor v2.

Entity name	ESPHome ID	Description
`Tracking Presence`	`tracking_presence`	Tracking radar presence, used by combined occupancy.
`Radar Target Count`	`radar_target_count`	Number of active targets.
`Radar Still Target Count`	`radar_still_target_count`	Still targets currently tracked.
`Radar Moving Target Count`	`radar_moving_target_count`	Moving targets currently tracked.
`Tracking Moving Target`	`tracking_moving_target`	Moving tracking status.
`Tracking Still Target`	`tracking_still_target`	Still tracking status.
`LD2450 Firmware`	-	LD2450 firmware version.
`LD2450 Bluetooth MAC`	-	LD2450 Bluetooth MAC address.

LD2450 Target Entities

Entity pattern	ESPHome ID pattern	Description
`Target 1 X/Y/Speed/Angle/Distance/Resolution`	`radar_target1_x`, `radar_target1_y`, etc.	Target 1 position and movement data.
`Target 2 X/Y/Speed/Angle/Distance/Resolution`	`radar_target2_x`, `radar_target2_y`, etc.	Target 2 position and movement data.
`Target 3 X/Y/Speed/Angle/Distance/Resolution`	`radar_target3_x`, `radar_target3_y`, etc.	Target 3 position and movement data.

LD2450 Zones and Controls

Entity name	Type	Description
`Zone 1 Target Count`	Sensor	Targets inside zone 1.
`Zone 1 Still Target Count`	Sensor	Still targets inside zone 1.
`Zone 1 Moving Target Count`	Sensor	Moving targets inside zone 1.
`Zone 1 X1/Y1/X2/Y2`	Number	Zone 1 boundaries.
`Zone 2 Target Count`	Sensor	Targets inside zone 2.
`Zone 2 Still Target Count`	Sensor	Still targets inside zone 2.
`Zone 2 Moving Target Count`	Sensor	Moving targets inside zone 2.
`Zone 2 X1/Y1/X2/Y2`	Number	Zone 2 boundaries.
`Zone 3 Target Count`	Sensor	Targets inside zone 3.
`Zone 3 Still Target Count`	Sensor	Still targets inside zone 3.
`Zone 3 Moving Target Count`	Sensor	Moving targets inside zone 3.
`Zone 3 X1/Y1/X2/Y2`	Number	Zone 3 boundaries.
`Tracking Presence Timeout`	Number	Timeout before tracking presence clears.
`LD2450 Bluetooth`	Switch	Enables LD2450 Bluetooth configuration.
`LD2450 Multi Target`	Switch	Enables multi-target mode.
`LD2450 Restart`	Button	Restarts the LD2450 module.
`LD2450 Factory Reset`	Button	Factory resets the LD2450 module; disabled by default.

Room Designer Polygon Zones

UltimateSensor v2 firmware adds the shared SmartHomeShop polygon-zone layer on top of the three native LD2450 rectangular zones.

Entity name	Type	Description
`Polygon Zone 1-4`	Text	Polygon coordinates for four detection zones.
`Polygon Exclusion 1-2`	Text	Polygons whose targets are ignored.
`Entry Line 1-2`	Text	Direction-aware entry lines.
`Polygon Zones Enabled`	Switch	Enables the polygon zone engine.
`Polygon Zone 1-4 Presence`	Binary sensor	Occupancy inside each polygon zone.
`Polygon Zone 1-4 Target Count`	Sensor	Number of targets inside each polygon zone.
`People Count`	Sensor	Running room count based on configured entry-line crossings.
`Last Crossing Direction`	Text sensor	Last detected entry-line direction.
`Reset People Count`	Button	Resets the running people count to zero.

Home Assistant actions set_polygon_zone, set_polygon_exclusion, set_entry_line and reset_people_count let the SmartHomeShop Room Designer write this configuration to the device. Diagnostic 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.

Optional LD2460 Upgrade

LD2460 firmware is only for devices where the LD2450 module has been removed/replaced by the LD2460 upgrade. LD2412 stays installed and remains the close-range fallback.

LD2460 uses the same main ID tracking_presence. Its target count is Tracking Target Count (tracking_target_count). It does not expose the LD2450-specific zone, speed or resolution entities, but it does include the shared Room Designer polygon-zone layer. It adds:

Entity name	ESPHome ID	Description
`Tracking Targets`	`tracking_summary`	Text summary of tracked targets.
`Tracking Radar Firmware`	`tracking_firmware`	LD2460 firmware string.
`Tracking Radar Installation Mode`	`tracking_installation_mode`	LD2460 installation mode.
`Tracking Radar Installation Mode`	`tracking_installation_mode_select`	Changes side/top mode on the radar. UltimateSensor v2 firmware requires side mode.
`Tracking Radar Installation Height`	`tracking_installation_height`	Saved wall mounting height in metres.
`Tracking Radar Installation Angle`	`tracking_installation_angle`	Saved downward mounting angle in degrees.
`Tracking Radar Detection Distance`	`tracking_detection_distance`	Hardware detection sector distance in metres.
`Tracking Radar Detection Start Angle`	`tracking_detection_start_angle`	Hardware sector start angle in degrees.
`Tracking Radar Detection End Angle`	`tracking_detection_end_angle`	Hardware sector end angle in degrees.
`Tracking Raw UART`	`tracking_raw_uart`	Raw UART diagnostic; disabled by default.
`Tracking UART Bytes`	`tracking_uart_bytes`	UART byte counter; disabled by default.
`Tracking Target 1-5 X/Y/Distance/Angle`	`tracking_target_1_x`, etc.	LD2460 target coordinates. Targets 4 and 5 are disabled by default.

Current UltimateSensor v2 LD2450 and LD2460 packages both include the shared Room Designer polygon zones. See LD2460 Upgrade before configuring mounting or range values.

Voice Assistant and Audio

Entity name	ESPHome ID	Description
`Media Player`	`media_player_01`	Speaker media player for TTS, alarms and assistant replies.
`Microphone RMS`	-	Microphone sound level RMS.
`Microphone Peak`	-	Microphone sound level peak.
`Use Wake Word`	`use_wake_word`	Local firmware: enables local wake word listening. On by default.
`Voice Assistant Start`	`voice_assistant_start_button`	Local firmware: starts voice assistant manually.
`Cloud Voice`	`use_wake_word`	Cloud firmware: enables listening for Cloud Voice. On by default.
`Cloud Voice Start`	`cloud_voice_start_button`	Cloud firmware: starts Cloud Voice manually.
`Voice Assistant Phase`	`voice_assistant_phase_text`	Diagnostic text: idle, listening, thinking, replying, not_ready, error, muted.

Environmental Sensors

Entity name	ESPHome ID	Description
`SCD41 CO2`	`scd41_co2`	CO2 concentration.
`SCD41 Temperature`	`scd41_temperature`	Temperature from SCD41.
`SCD41 Humidity`	`scd41_humidity`	Relative humidity from SCD41.
`VOC Index`	`voc_index`	SGP41 VOC index.
`NOx Index`	`nox_index`	SGP41 NOx index.
`BH1750 Illuminance`	`illuminance`	Ambient light.

Configuration and Firmware Controls

Entity name	ESPHome ID	Type	Description
`Temperature Offset`	`scd41_temperature_correction`	Number	Per-device correction added to `SCD41 Temperature`.
`Humidity Offset`	`scd41_humidity_correction`	Number	Per-device correction added to `SCD41 Humidity`.
`Boot Sound & Animation`	`boot_sound_switch`	Switch	Turns the startup sound and LED animation on or off. On by default.
`${friendly_name} Firmware Variant`	`firmware_selector`	Select	Chooses Basic/Complete, WiFi/Ethernet and local/cloud update source while retaining the radar hardware family.
`${friendly_name} Firmware`	`firmware_update`	Update	Checks and installs updates from the selected manifest; disabled by default.

The switches and numbers for automatic lighting are listed on Automatic LED Lighting.

Optional SPS30 Complete Variant

Complete firmware adds SPS30 at I2C address 0x69.

Entity name	ESPHome ID
`PM <1um Weight concentration`	`PM_1_0`
`PM <2.5um Weight concentration`	`PM_2_5`
`PM <4um Weight concentration`	`PM_4_0`
`PM <10um Weight concentration`	`PM_10_0`
`PM <0.5um Number concentration`	`PMC_0_5`
`PM <1um Number concentration`	`PMC_1_0`
`PM <2.5um Number concentration`	`PMC_2_5`
`PM <4um Number concentration`	`PMC_4_0`
`PM <10um Number concentration`	`PMC_10_0`
`Typical Particle size`	`pm_size`
`SPS30 Update Interval`	`sps30_update_interval`
`SPS30 Idle Interval`	`sps30_idle_interval`
`PM Sensor`	`pm_sensor_switch`
`SPS30 Quiet Hours`	`sps30_quiet_hours_enabled`
`SPS30 Quiet Start Hour`	`sps30_quiet_start_hour`
`SPS30 Quiet End Hour`	`sps30_quiet_end_hour`
`SPS30 Quiet Hours Active`	`sps30_quiet_hours_active_sensor`

LEDs, Device Controls and Diagnostics

Entity name	ESPHome ID	Availability
`Front LED`	`rgb_front_led`	All variants
`API Connection`	`api_connection`	All variants
`Uptime`	`uptime_sensor`	All variants
`CPU Temperature`	`cpu_temperature`	All variants
`Restart`	`restart_button`	All variants
`Restart in Safe Mode`	`safe_mode_button`	All variants
`Factory Reset`	`factory_reset_button`	All variants, disabled by default
`CO2 Manual Calibration`	`co2_calibration_button`	All variants, disabled by default
`ESPHome Version`	`esphome_version`	All variants
`Software Version`	`software_version`	All variants
`Hardware Version`	`hardware_version`	All variants
`Connection type`	`connection_type`	All variants
`WiFi Signal`	-	WiFi variants only
`IP Address`	`wifi_ip`	WiFi variants only, disabled by default
`ESP MAC`	`wifi_mac`	WiFi variants only, disabled by default
`Connected SSID`	-	WiFi variants only
`Connected BSSID`	-	WiFi variants only, disabled by default
`Ethernet IP Address`	`ethernet_ip_address`	Ethernet variants only
`Ethernet DNS Address`	-	Ethernet variants only
`Ethernet MAC Address`	`ethernet_mac_address`	Ethernet variants only

Optional Cloud Build Entities

Only *-cloud.yaml firmware variants expose these SmartHomeShop cloud diagnostics:

Entity name	ESPHome ID	Availability
`${friendly_name} Reset Cloud`	`cloud_reset_button`	Cloud variants
`${friendly_name} Cloud Connected`	`cloud_connected`	Cloud variants
`${friendly_name} Cloud Sync Failures`	`cloud_sync_failure_count`	Cloud variants
`${friendly_name} Cloud Device ID`	`cloud_device_id_sensor`	Cloud variants
`${friendly_name} Cloud Status`	`cloud_status_text`	Cloud variants

Cloud zone sync exists on LD2450 and LD2460 cloud builds through cloud-zones.yaml.

Not Present on UltimateSensor v2

Barometric pressure sensor
ESP32-C6 hardware and Mini v2 firmware
Mini v2-only Status LED name; regular v2 uses Front LED