Usage Guide

This guide helps you get the most out of your UltimateSensor with Home Assistant, including monitoring, automations, and dashboard ideas.

Quick Start

After installation, these are the key entities you'll use most:

Environmental Monitoring

Entity	Use Case
`SCD41 CO2`	Monitor air quality, ventilation needs
`SCD41 Temperature`	Climate control, comfort monitoring
`SCD41 Humidity`	Humidity alerts, HVAC control
`BH1750 Illuminance`	Light-based automations
`VOC Index`	Air quality monitoring

Presence Detection

Entity	Use Case
`Occupancy`	Room occupied (anyone present)
`PIR Sensor`	Quick motion detection
`Polygon Zone 1 Presence`	Specific area monitoring
`Polygon Zone 1 Target Count`	Count people in zone

Real-Time Monitoring

Viewing Sensor Data

Open Home Assistant → Settings → Devices & Services
Find ESPHome integration
Click on your UltimateSensor device
View all entities and their current values

Historical Data

To view trends over time:

Navigate to History in Home Assistant
Select the time period (hour, day, week, month)
Choose the UltimateSensor entities to display

Placement Recommendations

Optimal Positioning

Height: 1-2 meters from the floor
Location: Central in the room, away from walls if possible
Orientation: Front of device facing the area to monitor

Avoid These Placements

❌ Direct sunlight (causes yellowing and inaccurate readings)
❌ Near heat sources (radiators, electronics)
❌ Near air vents or drafts
❌ Behind furniture or obstructions
❌ Enclosed spaces with poor airflow

mmWave Considerations

The LD2450 radar:

Detects through thin walls (may need zone adjustments)
Works best with direct line of sight
Can track up to 3 people simultaneously

Automation Examples

Note: The entity IDs below start with ultimatesensor. In Home Assistant they also contain the six characters of your device, for example sensor.ultimatesensor_1a2b3c_scd41_co2. Copy the real IDs from the device page and replace the examples.

1. Ventilation Based on CO₂

automation:
  - alias: "Ventilate on High CO2"
    trigger:
      - platform: numeric_state
        entity_id: sensor.ultimatesensor_scd41_co2
        above: 1000
        for:
          minutes: 5
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.ventilation_fan
      - service: notify.mobile_app
        data:
          title: "Air Quality Alert"
          message: "CO₂ is {{ states('sensor.ultimatesensor_scd41_co2') }} ppm. Ventilation started."

2. Lights On When Room Occupied

automation:
  - alias: "Lights on when occupied"
    trigger:
      - platform: state
        entity_id: binary_sensor.ultimatesensor_occupancy
        to: "on"
    condition:
      - condition: numeric_state
        entity_id: sensor.ultimatesensor_bh1750_illuminance
        below: 50
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room
        data:
          brightness_pct: 80

3. Lights Off When Room Empty

automation:
  - alias: "Lights off when empty"
    trigger:
      - platform: state
        entity_id: binary_sensor.ultimatesensor_occupancy
        to: "off"
        for:
          minutes: 5
    action:
      - service: light.turn_off
        target:
          entity_id: light.living_room

4. Temperature Alert

automation:
  - alias: "High Temperature Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.ultimatesensor_scd41_temperature
        above: 28
    action:
      - service: notify.mobile_app
        data:
          title: "Temperature Alert"
          message: "Room temperature is {{ states('sensor.ultimatesensor_scd41_temperature') }}°C"

5. VOC Air Quality Warning

automation:
  - alias: "VOC Warning"
    trigger:
      - platform: numeric_state
        entity_id: sensor.ultimatesensor_voc_index
        above: 200
        for:
          minutes: 10
    action:
      - service: notify.mobile_app
        data:
          title: "Air Quality Warning"
          message: "VOC levels are elevated. Consider ventilating the room."

6. Motion-Triggered Quick Response

automation:
  - alias: "Quick motion response"
    trigger:
      - platform: state
        entity_id: binary_sensor.ultimatesensor_pir_sensor
        to: "on"
    action:
      - service: light.turn_on
        target:
          entity_id: light.hallway

7. Zone-Based Automation

automation:
  - alias: "Desk zone occupied"
    trigger:
      - platform: state
        entity_id: binary_sensor.ultimatesensor_polygon_zone_1_presence
        to: "on"
    action:
      - service: light.turn_on
        target:
          entity_id: light.desk_lamp

8. People Counter

automation:
  - alias: "Meeting room full"
    trigger:
      - platform: numeric_state
        entity_id: sensor.ultimatesensor_polygon_zone_1_target_count
        above: 2
    action:
      - service: notify.mobile_app
        data:
          title: "Meeting Room"
          message: "{{ states('sensor.ultimatesensor_polygon_zone_1_target_count') }} people in the room"

Dashboard Ideas

Air Quality Card

type: entities
title: Air Quality
entities:
  - entity: sensor.ultimatesensor_scd41_co2
    name: CO₂
  - entity: sensor.ultimatesensor_voc_index
    name: VOC Index
  - entity: sensor.ultimatesensor_nox_index
    name: NOx Index
  - entity: sensor.ultimatesensor_pm_2_5um_weight_concentration
    name: PM2.5

Climate Card

type: glance
title: Room Climate
entities:
  - entity: sensor.ultimatesensor_scd41_temperature
    name: Temperature
  - entity: sensor.ultimatesensor_scd41_humidity
    name: Humidity
  - entity: sensor.ultimatesensor_bh1750_illuminance
    name: Light

Presence Card

type: entities
title: Room Presence
entities:
  - entity: binary_sensor.ultimatesensor_occupancy
    name: Room Occupied
  - entity: binary_sensor.ultimatesensor_pir_sensor
    name: Motion (PIR)
  - entity: binary_sensor.ultimatesensor_polygon_zone_1_presence
    name: Zone 1
  - entity: sensor.ultimatesensor_polygon_zone_1_target_count
    name: People in Zone 1

CO₂ Gauge

type: gauge
entity: sensor.ultimatesensor_scd41_co2
name: CO₂ Level
min: 400
max: 2000
severity:
  green: 400
  yellow: 800
  red: 1200

History Graph

type: history-graph
title: 24h Air Quality
hours_to_show: 24
entities:
  - entity: sensor.ultimatesensor_scd41_co2
    name: CO₂
  - entity: sensor.ultimatesensor_scd41_temperature
    name: Temperature

Zone Configuration

The UltimateSensor supports 4 polygon zones, 2 exclusion zones and 2 entry lines for the mmWave radar. You draw them in the Room Designer of the SmartHomeShop integration.

Understanding Zones

Each zone is a shape of up to 20 points in the X and Y coordinates of the radar:

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

Example Zone Setup

Zone 1: Desk Area

Draw a shape around your desk
Add an exclusion zone over a mirror or window if the radar sees reflections there
Add an entry line in the doorway if you want to use People Count

Configuring Zones

Open SmartHomeShop in the Home Assistant sidebar and go to the Room Designer
Draw your zones and save
Test by walking through the area and checking Polygon Zone 1 Presence

LED Usage

The back LED can be used for status indication. The firmware already has a motion light, night light and CO₂ warning, see Sensor Definitions. The example below is only needed for your own colors:

CO₂ Status Indicator

automation:
  - alias: "CO2 LED indicator"
    trigger:
      - platform: state
        entity_id: sensor.ultimatesensor_scd41_co2
    action:
      - choose:
          - conditions:
              - condition: numeric_state
                entity_id: sensor.ultimatesensor_scd41_co2
                below: 800
            sequence:
              - service: light.turn_on
                target:
                  entity_id: light.ultimatesensor_back_light
                data:
                  rgb_color: [0, 255, 0]  # Green
          - conditions:
              - condition: numeric_state
                entity_id: sensor.ultimatesensor_scd41_co2
                above: 800
                below: 1200
            sequence:
              - service: light.turn_on
                target:
                  entity_id: light.ultimatesensor_back_light
                data:
                  rgb_color: [255, 165, 0]  # Orange
          - conditions:
              - condition: numeric_state
                entity_id: sensor.ultimatesensor_scd41_co2
                above: 1200
            sequence:
              - service: light.turn_on
                target:
                  entity_id: light.ultimatesensor_back_light
                data:
                  rgb_color: [255, 0, 0]  # Red

Calibration Reminder

For accurate readings:

CO₂: Allow 24+ hours for automatic baseline calibration
Temperature: May need offset adjustment if reading high
Humidity: Generally accurate, offset available if needed

👉 See the Calibration Guide for detailed instructions.

ESPHome Configuration

Adopting the Device

To customize your UltimateSensor:

Open ESPHome Device Builder in Home Assistant
The UltimateSensor should appear as "Discovered"
Click Adopt to add it to your ESPHome
Edit the YAML configuration as needed
Click Install to deploy changes via OTA

Using Packages (Recommended)

For easy updates, use the packages feature:

packages:
  smarthomeshop.ultimatesensor: github://smarthomeshop/ultimatesensor/ultimatesensor-v1/ultimatesensor-wifi-complete.yaml@main

Temperature Offset Example

If temperature reads high due to internal heat:

sensor:
  - id: !extend scd41
    temperature:
      filters:
        - offset: -2.0  # Adjust as needed

Common Use Cases

Room	Key Entities	Automations
Living Room	Occupancy, CO₂, Light	Lights on/off, ventilation
Bedroom	CO₂, Temperature, Humidity	Sleep climate, night light
Office	Zone occupancy, CO₂, Light	Desk lights, meeting detection
Kitchen	VOC, PM, Temperature	Cooking detection, range hood
Bathroom	Humidity, Occupancy	Fan control, lights

Need Help?

Discord: smarthomeshop.io/discord
Troubleshooting: Troubleshooting Guide
FAQ: Frequently Asked Questions