Usage Guide

This guide covers practical ways to use your CeilSense in Home Assistant, including automation examples, LED ring usage, and dashboard tips.

Quick Start

After installation and calibration, your CeilSense provides these key entities:

Entity	Use For
Presence	Room occupancy detection
Moving Target	Active movement detection
Still Target	Stationary person detection
SCD41 CO2	Air quality monitoring (Complete only)
SCD41 Temperature	Room temperature (Complete only)
SCD41 Humidity	Humidity level (Complete only)
BH1750 Illuminance	Light level
CeilSense Status LED	Visual notifications

Automation Examples

1. Turn Lights On When Entering a Room

yaml

alias: "Living Room - Lights on when occupied"
trigger:
  - platform: state
    entity_id: binary_sensor.ceilsense_presence
    to: "on"
condition:
  - condition: numeric_state
    entity_id: sensor.ceilsense_bh1750_illuminance
    below: 100  # Only when it's dark
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room

2. Turn Lights Off When Room is Empty

yaml

alias: "Living Room - Lights off when empty"
trigger:
  - platform: state
    entity_id: binary_sensor.ceilsense_presence
    to: "off"
    for:
      minutes: 5  # Wait 5 minutes to avoid false triggers
action:
  - service: light.turn_off
    target:
      entity_id: light.living_room

3. Ventilation Based on CO₂ Level (Complete Only)

yaml

alias: "Ventilation - High CO2 alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.ceilsense_scd41_co2
    above: 1000
    for:
      minutes: 5
action:
  - service: notify.mobile_app
    data:
      title: "Air Quality Alert"
      message: "CO₂ is {{ states('sensor.ceilsense_scd41_co2') }} ppm. Consider opening a window."
  - service: light.turn_on
    target:
      entity_id: light.ceilsense_status_led
    data:
      rgb_color: [255, 165, 0]  # Orange warning
      brightness: 128

4. Turn On Fan When CO₂ is High

yaml

alias: "Ventilation - Auto fan control"
trigger:
  - platform: numeric_state
    entity_id: sensor.ceilsense_scd41_co2
    above: 1200
action:
  - service: fan.turn_on
    target:
      entity_id: fan.bathroom_ventilation
  - wait_template: "{{ states('sensor.ceilsense_scd41_co2') | float < 800 }}"
  - service: fan.turn_off
    target:
      entity_id: fan.bathroom_ventilation

5. Different Actions for Movement vs. Still Presence

yaml

alias: "Office - Bright lights when working, dim when away"
trigger:
  - platform: state
    entity_id: binary_sensor.ceilsense_moving_target
  - platform: state
    entity_id: binary_sensor.ceilsense_still_target
action:
  - choose:
      # Active movement - bright lights
      - conditions:
          - condition: state
            entity_id: binary_sensor.ceilsense_moving_target
            state: "on"
        sequence:
          - service: light.turn_on
            target:
              entity_id: light.office
            data:
              brightness_pct: 100
      # Still presence only - dimmed lights
      - conditions:
          - condition: state
            entity_id: binary_sensor.ceilsense_still_target
            state: "on"
          - condition: state
            entity_id: binary_sensor.ceilsense_moving_target
            state: "off"
        sequence:
          - service: light.turn_on
            target:
              entity_id: light.office
            data:
              brightness_pct: 50
      # No presence - lights off
      - conditions:
          - condition: state
            entity_id: binary_sensor.ceilsense_presence
            state: "off"
        sequence:
          - service: light.turn_off
            target:
              entity_id: light.office

6. Adaptive Lighting Based on Lux

yaml

alias: "Living Room - Adaptive brightness"
trigger:
  - platform: state
    entity_id: binary_sensor.ceilsense_presence
    to: "on"
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room
    data:
      # Brighter when darker outside
      brightness_pct: >
        {% set lux = states('sensor.ceilsense_bh1750_illuminance') | float %}
        {% if lux < 50 %}100
        {% elif lux < 200 %}75
        {% elif lux < 500 %}50
        {% else %}25{% endif %}

7. Bedroom - No Lights When Sleeping

yaml

alias: "Bedroom - Detect sleeping"
trigger:
  - platform: state
    entity_id: binary_sensor.ceilsense_still_target
    to: "on"
    for:
      minutes: 30  # Still for 30 minutes = likely sleeping
condition:
  - condition: time
    after: "22:00:00"
    before: "08:00:00"
action:
  - service: input_boolean.turn_on
    target:
      entity_id: input_boolean.bedroom_sleeping_mode

LED Ring Usage

The CeilSense has a 16-LED RGB ring that you can use for visual notifications and status indicators.

Control via Home Assistant

yaml

# Turn on with specific color
service: light.turn_on
target:
  entity_id: light.ceilsense_status_led
data:
  rgb_color: [255, 0, 0]  # Red
  brightness: 128

# Turn off
service: light.turn_off
target:
  entity_id: light.ceilsense_status_led

Color Ideas for Status Indicators

Color	RGB Value	Suggested Use
🔴 Red	`[255, 0, 0]`	High CO₂, alarm, error
🟠 Orange	`[255, 165, 0]`	Warning, moderate CO₂
🟡 Yellow	`[255, 255, 0]`	Caution, attention needed
🟢 Green	`[0, 255, 0]`	Good air quality, OK status
🔵 Blue	`[0, 0, 255]`	Information, presence detected
🟣 Purple	`[128, 0, 128]`	Night mode, special status
⚪ White	`[255, 255, 255]`	General lighting, neutral

CO₂ Level LED Indicator Automation

yaml

alias: "CeilSense - CO2 LED indicator"
trigger:
  - platform: state
    entity_id: sensor.ceilsense_scd41_co2
action:
  - choose:
      # Good air quality
      - conditions:
          - condition: numeric_state
            entity_id: sensor.ceilsense_scd41_co2
            below: 800
        sequence:
          - service: light.turn_on
            target:
              entity_id: light.ceilsense_status_led
            data:
              rgb_color: [0, 255, 0]
              brightness: 50
      # Moderate
      - conditions:
          - condition: numeric_state
            entity_id: sensor.ceilsense_scd41_co2
            above: 800
            below: 1200
        sequence:
          - service: light.turn_on
            target:
              entity_id: light.ceilsense_status_led
            data:
              rgb_color: [255, 165, 0]
              brightness: 100
      # Poor
      - conditions:
          - condition: numeric_state
            entity_id: sensor.ceilsense_scd41_co2
            above: 1200
        sequence:
          - service: light.turn_on
            target:
              entity_id: light.ceilsense_status_led
            data:
              rgb_color: [255, 0, 0]
              brightness: 200

mode: restart

Important Notes About LED Ring

⚠️ Heat Warning: Extended use of the LED ring at high brightness generates heat that can affect temperature, humidity, and CO₂ readings. For continuous status indicators, use low brightness (50-100) or implement cooldown periods.

Dashboard Ideas

Recommended Entities for Your Dashboard

Essential:

binary_sensor.ceilsense_presence — Main occupancy indicator
sensor.ceilsense_scd41_co2 — Air quality (Complete only)

Environmental Monitoring:

sensor.ceilsense_scd41_temperature
sensor.ceilsense_scd41_humidity
sensor.ceilsense_bh1750_illuminance
sensor.ceilsense_bmp3xx_pressure

Advanced/Debugging:

binary_sensor.ceilsense_moving_target
binary_sensor.ceilsense_still_target
sensor.ceilsense_detection_distance

Example Dashboard Card (YAML)

yaml

type: entities
title: Living Room Climate
entities:
  - entity: binary_sensor.ceilsense_presence
    name: Occupancy
  - entity: sensor.ceilsense_scd41_co2
    name: CO₂
  - entity: sensor.ceilsense_scd41_temperature
    name: Temperature
  - entity: sensor.ceilsense_scd41_humidity
    name: Humidity
  - entity: sensor.ceilsense_bh1750_illuminance
    name: Light Level

Gauge Card for CO₂

yaml

type: gauge
entity: sensor.ceilsense_scd41_co2
name: Air Quality
min: 400
max: 2000
severity:
  green: 400
  yellow: 800
  red: 1200

Best Practices

Mounting Location

✅ Do:

Mount in the center of the room for even coverage
Keep 2-4 meters above the floor
Position away from direct sunlight
Allow some airflow around the sensor

❌ Don't:

Mount directly above a heat source (radiator, lamp)
Place where ceiling fans will trigger false detections
Install in high-humidity areas without IP protection (bathroom steam)
Mount where radar will see through thin walls into adjacent rooms

Optimizing Detection

Reduce false positives: Lower the Maximum Distance Gate to match your room size
Improve still detection: Increase still sensitivity if people sitting aren't detected
Avoid pet triggers: Raise move thresholds or reduce detection range
Ceiling fan issues: Run Dynamic Background Correction with fan ON

Environmental Sensor Accuracy

Temperature too high? Reduce LED brightness, add temperature offset
CO₂ readings off? Run manual calibration in fresh air, wait for ABC to stabilize
Humidity inaccurate? Calibrate temperature first, then adjust humidity offset

See the Calibration Guide for detailed tuning instructions.

Common Use Cases

Room	Primary Use	Key Entities
Living Room	Light control, occupancy	Presence, Lux
Bedroom	Sleep detection, night mode	Still Target, Presence
Office	Work detection, air quality	Presence, CO₂
Bathroom	Ventilation control	Presence, Humidity
Kitchen	Cooking detection, ventilation	Movement, CO₂
Hallway	Motion-activated lighting	Moving Target

Need Help?

Calibration Guide — Optimize sensor performance
Sensor Definitions — Understand all entities
Troubleshooting — Common issues
FAQ — Frequently asked questions

Usage Guide ​

Quick Start ​

Automation Examples ​

1. Turn Lights On When Entering a Room ​

2. Turn Lights Off When Room is Empty ​

3. Ventilation Based on CO₂ Level (Complete Only) ​

4. Turn On Fan When CO₂ is High ​

5. Different Actions for Movement vs. Still Presence ​

6. Adaptive Lighting Based on Lux ​

7. Bedroom - No Lights When Sleeping ​

LED Ring Usage ​

Control via Home Assistant ​

Color Ideas for Status Indicators ​

CO₂ Level LED Indicator Automation ​

Important Notes About LED Ring ​

Dashboard Ideas ​

Recommended Entities for Your Dashboard ​

Example Dashboard Card (YAML) ​

Gauge Card for CO₂ ​

Best Practices ​

Mounting Location ​

Optimizing Detection ​

Environmental Sensor Accuracy ​

Common Use Cases ​

Need Help? ​

Usage Guide

Quick Start

Automation Examples

1. Turn Lights On When Entering a Room

2. Turn Lights Off When Room is Empty

3. Ventilation Based on CO₂ Level (Complete Only)

4. Turn On Fan When CO₂ is High

5. Different Actions for Movement vs. Still Presence

6. Adaptive Lighting Based on Lux

7. Bedroom - No Lights When Sleeping

LED Ring Usage

Control via Home Assistant

Color Ideas for Status Indicators

CO₂ Level LED Indicator Automation

Important Notes About LED Ring

Dashboard Ideas

Recommended Entities for Your Dashboard

Example Dashboard Card (YAML)

Gauge Card for CO₂

Best Practices

Mounting Location

Optimizing Detection

Environmental Sensor Accuracy

Common Use Cases

Need Help?