Usage Guide

This guide helps you get the most out of your UltimateSensor Mini with Home Assistant, including monitoring, voice assistant, 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)
`Zone 1 Occupancy`	Specific area monitoring
`Zone 1 Target Count`	Count people in zone

Voice & Audio

Entity	Use Case
`US Mini Media Player`	TTS announcements, alarms
`Use wake word`	Voice command activation
`Front light` / `Back light`	Visual feedback

Real-Time Monitoring

Viewing Sensor Data

Open Home Assistant → Settings → Devices & Services
Find ESPHome integration
Click on your UltimateSensor Mini 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 Mini entities to display

Voice Assistant Setup

The UltimateSensor Mini has built-in voice assistant capabilities.

Basic Setup

Configure Voice Assistant in Home Assistant
- Go to Settings → Voice Assistants
- Set up your preferred assistant (e.g., Home Assistant Cloud, local Whisper)
Enable Wake Word
- Find the Use wake word switch in Home Assistant
- Turn it ON
Configure Wake Word
- In Home Assistant, configure your preferred wake word
- The device will listen continuously when enabled

Voice LED Feedback

Red: Wake word detected, listening
Off: Processing voice command

Media Player Usage

The US Mini Media Player can be used for:

yaml

# Text-to-speech announcement
service: tts.speak
target:
  entity_id: media_player.us_mini_media_player
data:
  message: "Welcome home!"

# Play audio file
service: media_player.play_media
target:
  entity_id: media_player.us_mini_media_player
data:
  media_content_id: "https://example.com/sound.mp3"
  media_content_type: "music"

# Set volume
service: media_player.volume_set
target:
  entity_id: media_player.us_mini_media_player
data:
  volume_level: 0.5

👉 See the Voice Assistant Guide for detailed setup.

Placement Recommendations

Optimal Positioning

Height: 1-2 meters from the floor
Location: Central in the room, good line of sight
Voice: Position where voice commands can be heard clearly
mmWave: Front of device facing the area to monitor

Avoid These Placements

❌ Direct sunlight (causes yellowing and inaccurate readings)
❌ Near heat sources (radiators, electronics)
❌ Near loud noise sources (affects voice recognition)
❌ Behind furniture or obstructions
❌ In enclosed spaces with poor airflow

Automation Examples

1. Ventilation Based on CO₂

yaml

automation:
  - alias: "Ventilate on High CO2"
    trigger:
      - platform: numeric_state
        entity_id: sensor.ultimatesensor_mini_scd41_co2
        above: 1000
        for:
          minutes: 5
    action:
      - service: switch.turn_on
        target:
          entity_id: switch.ventilation_fan
      - service: tts.speak
        target:
          entity_id: media_player.us_mini_media_player
        data:
          message: "CO2 levels are high. Ventilation started."

2. Welcome Home Announcement

yaml

automation:
  - alias: "Welcome Home"
    trigger:
      - platform: state
        entity_id: binary_sensor.ultimatesensor_mini_occupancy
        from: "off"
        to: "on"
    condition:
      - condition: state
        entity_id: input_boolean.away_mode
        state: "on"
    action:
      - service: input_boolean.turn_off
        target:
          entity_id: input_boolean.away_mode
      - service: tts.speak
        target:
          entity_id: media_player.us_mini_media_player
        data:
          message: "Welcome home!"

3. Lights On When Occupied

yaml

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

4. CO₂ LED Indicator

yaml

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

5. Alarm Sound

yaml

automation:
  - alias: "Security Alarm"
    trigger:
      - platform: state
        entity_id: binary_sensor.ultimatesensor_mini_occupancy
        to: "on"
    condition:
      - condition: state
        entity_id: alarm_control_panel.home
        state: "armed_away"
    action:
      - service: media_player.play_media
        target:
          entity_id: media_player.us_mini_media_player
        data:
          media_content_id: "https://smarthomeshop.io/products/ultimatesensor-mini/v1/audio/alarm.mp3"
          media_content_type: "music"

6. Temperature Alert

yaml

automation:
  - alias: "High Temperature Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.ultimatesensor_mini_scd41_temperature
        above: 28
    action:
      - service: tts.speak
        target:
          entity_id: media_player.us_mini_media_player
        data:
          message: "Temperature is {{ states('sensor.ultimatesensor_mini_scd41_temperature') }} degrees"

7. Zone-Based Presence

yaml

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

Dashboard Ideas

Air Quality Card

yaml

type: entities
title: Air Quality
entities:
  - entity: sensor.ultimatesensor_mini_scd41_co2
    name: CO₂
  - entity: sensor.ultimatesensor_mini_voc_index
    name: VOC Index
  - entity: sensor.ultimatesensor_mini_nox_index
    name: NOx Index

Climate Card

yaml

type: glance
title: Room Climate
entities:
  - entity: sensor.ultimatesensor_mini_scd41_temperature
    name: Temperature
  - entity: sensor.ultimatesensor_mini_scd41_humidity
    name: Humidity
  - entity: sensor.ultimatesensor_mini_bh1750_illuminance
    name: Light

Presence Card

yaml

type: entities
title: Room Presence
entities:
  - entity: binary_sensor.ultimatesensor_mini_occupancy
    name: Room Occupied
  - entity: binary_sensor.ultimatesensor_mini_zone_1_occupancy
    name: Zone 1
  - entity: sensor.ultimatesensor_mini_zone_1_target_count
    name: People in Zone 1

Voice Assistant Card

yaml

type: entities
title: Voice Assistant
entities:
  - entity: switch.ultimatesensor_mini_use_wake_word
    name: Wake Word Active
  - entity: media_player.us_mini_media_player
    name: Media Player
  - entity: light.ultimatesensor_mini_front_light
    name: Front LED

CO₂ Gauge

yaml

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

Zone Configuration

The UltimateSensor Mini 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 Mini 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

Both LEDs can be used for visual feedback:

Status Indicator Example

yaml

automation:
  - alias: "Status LED"
    trigger:
      - platform: state
        entity_id: binary_sensor.ultimatesensor_mini_occupancy
    action:
      - choose:
          - conditions:
              - condition: state
                entity_id: binary_sensor.ultimatesensor_mini_occupancy
                state: "on"
            sequence:
              - service: light.turn_on
                target:
                  entity_id: light.ultimatesensor_mini_back_light
                data:
                  rgb_color: [0, 255, 0]
                  brightness: 50
          - conditions:
              - condition: state
                entity_id: binary_sensor.ultimatesensor_mini_occupancy
                state: "off"
            sequence:
              - service: light.turn_off
                target:
                  entity_id: light.ultimatesensor_mini_back_light

Calibration Reminder

For accurate readings:

CO₂: Allow 24+ hours for automatic baseline calibration (calibrates to 420 ppm)
Temperature: Built-in offset of -2.3°C, may need further adjustment
Humidity: Built-in offset of +3%, may need adjustment

👉 See the Calibration Guide for detailed instructions.

ESPHome Configuration

Adopting the Device

To customize your UltimateSensor Mini:

Open ESPHome Dashboard in Home Assistant
The device 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_mini: github://smarthomeshop/ultimatesensor-mini/ultimatesensor-mini-v1/ultimatesensor-mini-basic.yaml@main

Temperature Offset Example

If temperature still reads high:

yaml

sensor:
  - id: !extend my_scd41
    temperature:
      filters:
        - offset: -1.0  # Additional offset if needed

Common Use Cases

Room	Key Entities	Features
Living Room	Occupancy, CO₂, Light	Lights, TTS announcements
Bedroom	CO₂, Temperature, Voice	Sleep climate, wake alarms
Office	Zone occupancy, CO₂, Voice	Desk presence, meeting alerts
Kitchen	VOC, Temperature, Voice	Cooking alerts, timers
Hallway	Occupancy, Voice	Welcome announcements

Need Help?

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

Usage Guide ​

Quick Start ​

Environmental Monitoring ​

Presence Detection ​

Voice & Audio ​

Real-Time Monitoring ​

Viewing Sensor Data ​

Historical Data ​

Voice Assistant Setup ​

Basic Setup ​

Voice LED Feedback ​

Media Player Usage ​

Placement Recommendations ​

Optimal Positioning ​

Avoid These Placements ​

Automation Examples ​

1. Ventilation Based on CO₂ ​

2. Welcome Home Announcement ​

3. Lights On When Occupied ​

4. CO₂ LED Indicator ​

5. Alarm Sound ​

6. Temperature Alert ​

7. Zone-Based Presence ​

Dashboard Ideas ​

Air Quality Card ​

Climate Card ​

Presence Card ​

Voice Assistant Card ​

CO₂ Gauge ​

Zone Configuration ​

Understanding Zones ​

Example Zone Setup ​

Configuring Zones ​

LED Usage ​

Status Indicator Example ​

Calibration Reminder ​

ESPHome Configuration ​

Adopting the Device ​

Using Packages (Recommended) ​

Temperature Offset Example ​

Common Use Cases ​

Need Help? ​

Usage Guide

Quick Start

Environmental Monitoring

Presence Detection

Voice & Audio

Real-Time Monitoring

Viewing Sensor Data

Historical Data

Voice Assistant Setup

Basic Setup

Voice LED Feedback

Media Player Usage

Placement Recommendations

Optimal Positioning

Avoid These Placements

Automation Examples

1. Ventilation Based on CO₂

2. Welcome Home Announcement

3. Lights On When Occupied

4. CO₂ LED Indicator

5. Alarm Sound

6. Temperature Alert

7. Zone-Based Presence

Dashboard Ideas

Air Quality Card

Climate Card

Presence Card

Voice Assistant Card

CO₂ Gauge

Zone Configuration

Understanding Zones

Example Zone Setup

Configuring Zones

LED Usage

Status Indicator Example

Calibration Reminder

ESPHome Configuration

Adopting the Device

Using Packages (Recommended)

Temperature Offset Example

Common Use Cases

Need Help?