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:

Built-in LED Features

CeilSense already controls several LED functions in its own firmware. You do not need to create a Home Assistant automation for:

• Motion light: switches on when the radar detects a moving target.
• Night light: switches on at the configured brightness when still presence is detected during the configured night hours.
• CO2 warning: flashes orange three times when the warning threshold is reached (Complete only).
• CO2 critical alert: flashes red three times when the critical threshold is reached (Complete only).

The firmware applies these functions in a fixed priority order, so CO2 alerts, motion light, and night light cannot take control of the LED ring at the same time.

See LED Lighting for the exact priority, available settings, and troubleshooting.

Optional Home Assistant Automation Examples

The examples below are optional additions for controlling other devices or creating behavior beyond the built-in CeilSense LED functions.

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

1. Turn Lights On When Entering a Room

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

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)

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

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

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

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

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.

The motion light, night light, and CO2 warning behavior described in LED Lighting is already built into the firmware. The Home Assistant examples below are only needed when you want to override the ring manually or create a different visual effect.

Control via Home Assistant

# 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

CO₂ Level LED Indicator Automation

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)

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₂

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.5 to 3 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: Lower the still threshold in the HLK Radar Tool app if people sitting aren't detected
• Avoid pet triggers: Raise the move threshold in the HLK Radar Tool app 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. Automatic calibration is off by default
• Humidity inaccurate? Calibrate temperature first, then adjust humidity offset

See the Calibration Guide for detailed tuning instructions.

Common Use Cases

Need Help?

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