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
`Zone 1 Occupancy`	Specific area monitoring
`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

1. Ventilation Based on CO₂

yaml

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

yaml

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

yaml

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

yaml

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

yaml

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

yaml

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

yaml

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

8. People Counter

yaml

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

Dashboard Ideas

Air Quality Card

yaml

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

yaml

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

yaml

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_zone_1_occupancy
    name: Zone 1
  - entity: sensor.ultimatesensor_zone_1_target_count
    name: People in Zone 1

CO₂ Gauge

yaml

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

History Graph

yaml

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 configurable detection zones for mmWave radar.

Understanding Zones

Each zone is a rectangular area defined by X and Y coordinates:

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

Example Zone Setup

Zone 1: Desk Area

Begin X: -1000 mm (1m left of center)
End X: 1000 mm (1m right of center)
Begin Y: 500 mm (0.5m from sensor)
End Y: 2000 mm (2m from sensor)

Configuring Zones

In Home Assistant, find your UltimateSensor device
Look for Zone X Begin/End X/Y number entities
Adjust values to match your room layout
Test by walking through the area and checking Zone X Occupancy

LED Usage

The back LED can be used for status indication:

CO₂ Status Indicator

yaml

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 Dashboard 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:

yaml

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

Temperature Offset Example

If temperature reads high due to internal heat:

yaml

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

Custom Zone Defaults

Change default zone boundaries:

yaml

number:
  - id: !extend zone1_begin_x
    initial_value: -2000
  - id: !extend zone1_end_x
    initial_value: 2000

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

Usage Guide ​

Quick Start ​

Environmental Monitoring ​

Presence Detection ​

Real-Time Monitoring ​

Viewing Sensor Data ​

Historical Data ​

Placement Recommendations ​

Optimal Positioning ​

Avoid These Placements ​

mmWave Considerations ​

Automation Examples ​

1. Ventilation Based on CO₂ ​

2. Lights On When Room Occupied ​

3. Lights Off When Room Empty ​

4. Temperature Alert ​

5. VOC Air Quality Warning ​

6. Motion-Triggered Quick Response ​

7. Zone-Based Automation ​

8. People Counter ​

Dashboard Ideas ​

Air Quality Card ​

Climate Card ​

Presence Card ​

CO₂ Gauge ​

History Graph ​

Zone Configuration ​

Understanding Zones ​

Example Zone Setup ​

Configuring Zones ​

LED Usage ​

CO₂ Status Indicator ​

Calibration Reminder ​

ESPHome Configuration ​

Adopting the Device ​

Using Packages (Recommended) ​

Temperature Offset Example ​

Custom Zone Defaults ​

Common Use Cases ​

Need Help? ​

Usage Guide

Quick Start

Environmental Monitoring

Presence Detection

Real-Time Monitoring

Viewing Sensor Data

Historical Data

Placement Recommendations

Optimal Positioning

Avoid These Placements

mmWave Considerations

Automation Examples

1. Ventilation Based on CO₂

2. Lights On When Room Occupied

3. Lights Off When Room Empty

4. Temperature Alert

5. VOC Air Quality Warning

6. Motion-Triggered Quick Response

7. Zone-Based Automation

8. People Counter

Dashboard Ideas

Air Quality Card

Climate Card

Presence Card

CO₂ Gauge

History Graph

Zone Configuration

Understanding Zones

Example Zone Setup

Configuring Zones

LED Usage

CO₂ Status Indicator

Calibration Reminder

ESPHome Configuration

Adopting the Device

Using Packages (Recommended)

Temperature Offset Example

Custom Zone Defaults

Common Use Cases

Need Help?