Calibration Guide for CeilSense

Calibrating your CeilSense ensures accurate detection and measurements. Every installation is unique — ceiling materials, room layout, and environmental factors can all affect sensor performance. Follow this guide to optimize your CeilSense for your specific situation.

This guide covers:

• mmWave Radar Tuning — Available on both Basic and Complete variants
• Environmental Sensor Calibration (CO₂, temperature, humidity) — Complete variant only

Understanding Your Installation

Every CeilSense installation is different. Factors that can affect performance include:

For mmWave detection:

• Room layout: Furniture, walls, and obstacles affect radar coverage
• Adjacent rooms: mmWave can penetrate thin walls, potentially causing false triggers
• Moving objects: Ceiling fans, pets, or curtains may trigger detection
• Mounting height: Detection patterns change based on ceiling height (2-4m recommended)

For environmental sensors (Complete only):

• Ceiling material: Some materials retain more heat than others
• Insulation: Well-insulated ceilings may trap warm air around the sensor
• Airflow: Limited airflow in the ceiling cavity can cause temperature buildup
• LED ring usage: Extended use of the RGB LEDs generates heat
• Mounting depth: How deep the sensor sits in the ceiling affects air circulation

Because of these variables, you may need to tune your mmWave sensor and/or apply calibration offsets to environmental sensors for your specific environment.

mmWave Radar Tuning

The mmWave radar sensor can be tuned to optimize detection for your specific room and use case. Proper tuning helps reduce false positives (detecting movement when there is none) and false negatives (not detecting people who are present).

Initial Setup: Calibrating for Your Room

Important: After installation, the mmWave sensor needs to learn your specific room environment. Without proper calibration, you may experience constant presence detection or high movement energy readings even when the room is empty.

Why calibration is needed:

The LD2412 mmWave radar is extremely sensitive and can detect:

• Movement through walls: The 24GHz radar can penetrate drywall, wood, and thin walls, detecting people in adjacent rooms
• Ceiling fans: Even slow-moving fans create constant radar reflections
• HVAC airflow: Strong air currents can move curtains, plants, or create detectable air turbulence
• Reflective surfaces: Large metal objects or mirrors can cause radar reflections
• Electrical interference: Some electronic devices can interfere with the radar
• Pets: Cats, dogs, or other animals moving in the detection zone
• The sensor itself: If not calibrated, the sensor may be detecting its own reflections or background noise

How to fix this:

Step 1: Run Dynamic Background Correction (MOST IMPORTANT!)

This is the #1 solution for constant false detection:

1. COMPLETELY EMPTY THE ROOM — No people, no pets, nothing moving
2. Turn off ceiling fans and close windows (stop air movement)
3. In Home Assistant, find the "Start Dynamic Background Correction" button
4. Press the button and wait until the process completes (watch the status sensor)
5. The sensor will learn what "empty" looks like and calibrate itself

Critical: If you run Dynamic Background Correction while someone is in the room, the sensor will think a person is "normal background" and detection will not work properly!

Step 2: Reduce Maximum Detection Distance

If you're detecting through walls into adjacent rooms:

1. In Home Assistant, find "Maximum Distance Gate"
2. Reduce it from the default (13) to match your actual room size
3. Each gate is approximately 0.75 meters (with default resolution)
4. For a 4m room, try setting max gate to 5-6

Step 3: Increase Gate Thresholds

If specific distance gates show high energy:

1. Enable Engineering Mode to see real-time energy per gate
2. Identify which gates show constant high energy (these are the problem areas)
3. Increase the Move Threshold and Still Threshold for those gates
4. Higher threshold = less sensitive = fewer false triggers

Example: If Gate 8 shows constant 80% energy with nobody there, set Gate 8 Move Threshold to 85 or higher.

Step 4: Check for Interfering Objects

Walk through this checklist:

• [ ] Ceiling fan off or at minimum speed?
• [ ] No curtains/blinds moving from HVAC?
• [ ] No pets in the room during calibration?
• [ ] No large metal objects directly in sensor path?
• [ ] Is the sensor detecting through a thin wall?

Step 5: Factory Reset (Last Resort)

If nothing else works:

1. Press the "Factory Reset" button in Home Assistant
2. Wait for the sensor to restart
3. Run Dynamic Background Correction again with an empty room
4. Reconfigure your distance gates and thresholds

Why Tune the mmWave Sensor?

Common reasons to adjust sensitivity:

• False triggers: Detecting movement in adjacent rooms through walls
• Detecting pets: Sensor picks up cats, dogs, or other pets
• Ceiling fans: Rotating fans trigger motion detection
• Missing still presence: Not detecting someone sitting or lying still
• Range too far/short: Detection zone doesn't match your room

Tuning Methods

There are two ways to adjust the mmWave radar sensitivity:

Method 1: Via Home Assistant (Recommended)

1. Open Home Assistant and go to Settings → Devices & Services → ESPHome
2. Find and select your CeilSense device
3. Look for the LD2412 controls in the device page:

Distance Settings:

• Minimum Distance Gate: Sets the minimum detection distance (gates 1-12, each gate ≈ 0.75m)
• Maximum Distance Gate: Sets the maximum detection distance (gates 2-13)
• Presence Timeout: Time in seconds presence remains active after no detection

Per-Gate Threshold Settings (Gate 0-13):

• Gate X Move Threshold: Threshold for motion detection at that distance (0-100)
• Gate X Still Threshold: Threshold for still/presence detection at that distance (0-100)

Tip: Lower threshold values = more sensitive (detects weaker signals). Higher values = less sensitive (requires stronger signals to trigger).

4. Adjust the sliders and observe the effect on detection
5. Settings are saved automatically to the sensor

Method 2: Via HLK Radar Tool App

The official Hi-Link app provides a visual interface for tuning:

1. Download the app:

   • iOS: Search "HLK Radar Tool" in the App Store
   • Android: Search "HLK Radar Tool" in Google Play Store

2. Connect to your CeilSense:

   • Enable Bluetooth on the CeilSense (if available via Home Assistant switch)
   • Open the app and connect via Bluetooth

3. Available settings (same as Home Assistant):

   • Move/Still thresholds per gate
   • Min/Max distance gates
   • Presence timeout

4. Save your configuration after making changes

Advanced Tuning: Engineering Mode

For detailed tuning, you can enable Engineering Mode in Home Assistant. This exposes additional sensors:

• Gate X Move Energy: Real-time energy readings for motion at each gate
• Gate X Still Energy: Real-time energy readings for still presence at each gate

Calibration process using Engineering Mode:

1. Enable Engineering Mode (switch in Home Assistant)
2. Monitor the Gate X Move Energy and Gate X Still Energy sensors while moving around
3. Observe which gates show activity and at what energy levels
4. Set thresholds just above the noise floor for each gate
5. Disable Engineering Mode when done

Automatic Calibration: Dynamic Background Correction

The easiest way to calibrate is using Dynamic Background Correction:

1. Ensure the room is empty (no people, pets, or moving objects)
2. In Home Assistant, find the Start Dynamic Background Correction button
3. Press the button and wait for the process to complete
4. The sensor will automatically learn the background noise and set appropriate thresholds

Note: During dynamic background correction, the Dynamic Background Correction Status binary sensor will show true. Wait until it returns to false before using the sensor.

Tuning Tips for Different Scenarios

Scenario	Recommended Adjustment
False triggers through walls	Reduce maximum detection distance, lower sensitivity
Pets triggering sensor	Lower motion sensitivity, adjust still threshold
Not detecting sitting/lying	Increase still sensitivity
Ceiling fan false triggers	Reduce sensitivity in upper detection gates
Multiple rooms detected	Reduce detection range to match room size

Sensor-Specific Tuning

LD2412 (Standard):

• Has separate moving and still sensitivity controls
• 9 distance gates (each ~0.75m)
• Great for tuning still presence detection

LD2450 (Optional):

• Zone-based configuration
• X/Y coordinate boundaries
• Set up detection zones to ignore certain areas

LD6002B (Coming Soon):

• 3D detection zones
• More advanced filtering options

Testing Your Configuration

After adjusting settings:

1. Leave the room completely and verify the sensor shows "unoccupied"
2. Enter the room and check detection speed
3. Sit or lie still and verify presence is maintained
4. Test edge cases (adjacent rooms, pets if applicable)

CO₂ Sensor Calibration (Complete Only)

The CeilSense Complete uses the Sensirion SCD41 sensor.

SCD41 Specifications:

• CO₂ Measurement Range: 400 to 5,000 ppm
• Temperature Measurement Range: -10 to 60°C (14 to 140°F)
• Humidity Measurement Range: 0 to 100% RH

CO₂ Accuracy Specifications:

• 400-1,000 ppm: ±(50 ppm + 2.5% of reading)
• 1,001-2,000 ppm: ±(50 ppm + 3% of reading)
• 2,001-5,000 ppm: ±(40 ppm + 5% of reading)

Automatic Self Calibration (ASC)

By default, Automatic Self Calibration (ASC) is disabled on the CeilSense. This is intentional because ASC requires the sensor to regularly see fresh air (400 ppm) to work correctly, which may not happen in all rooms.

If you want to enable ASC, you can do so by adopting the device in ESPHome and changing the substitution (see Advanced Configuration below).

Manual CO₂ Calibration

To calibrate the CO₂ sensor manually:

1. Prepare the Environment

   • Ensure the room has been well-ventilated with windows open for at least 3 minutes
   • Or place the CeilSense in fresh outdoor air within WiFi range
   • Wait for the sensor readings to stabilize

2. Calibrate via Home Assistant

   • Go to Settings → Devices & Services → ESPHome
   • Find and select your CeilSense device
   • Press the "CO2 manual calibration (fresh air ≥3min)" button
   • The sensor will calibrate to 426 ppm (current average fresh air CO₂ level)

3. Verify Calibration

   • Check that CO₂ readings show approximately 400-430 ppm in fresh air
   • If readings are still off, repeat the calibration process

CO₂ Levels and Health Implications

Understanding what CO₂ levels mean:

• 350-450 ppm: Healthy outdoor air level
• 600 ppm: Good indoor air quality
• 800 ppm: Acceptable indoor air quality
• 1,000 ppm: Ventilation recommended
• 1,200 ppm: Ventilation necessary
• 2,000 ppm: Poor air quality, may cause drowsiness
• 5,000 ppm: Dangerous with prolonged exposure

Temperature Calibration

Temperature readings may vary based on your installation. The LED ring and ceiling cavity can cause higher-than-actual readings.

Note: The CeilSense already has a built-in temperature offset of 10°C plus an additional 5°C by default (15°C total) to compensate for heat from the electronics and ceiling cavity. You can adjust this further if needed.

Method 1: Adjust via Home Assistant (Easy)

The easiest way to calibrate temperature is using the offset entity in Home Assistant:

1. Measure Reference Temperature

   • Use a reliable thermometer placed at the same height as the CeilSense
   • Take multiple readings over time for accuracy

2. Calculate the Offset

   • If CeilSense reads 24°C but actual temperature is 22°C, you need an additional -2°C offset

3. Adjust the Offset in Home Assistant

   • Go to Settings → Devices & Services → ESPHome → CeilSense
   • Find "SCD4x Extra Temperature Offset (°C)"
   • Enter your offset value (can be positive or negative, range -20 to +20)
   • The setting is saved automatically and persists across reboots

Method 2: Adjust via ESPHome Substitutions (Advanced)

For permanent changes, you can adopt the device in ESPHome and modify the substitutions:

1. Adopt the device in ESPHome Dashboard
2. Edit the YAML and change the substitution:

substitutions:
  scd4x_temperature_offset: "12.0"  # Adjust this value (default is 10.0)

3. Save and install the configuration OTA

Tips for Accurate Temperature Readings

• Reduce LED brightness: Lower brightness = less heat
• Use LED cooldown periods: Don't run LEDs continuously at high brightness
• Allow airflow: Ensure the ceiling cavity has some air circulation
• Wait for stabilization: After power-on, wait 15-30 minutes before taking reference readings

Humidity Calibration

Humidity readings can also be affected by temperature offsets and environmental factors.

Method 1: Adjust via Home Assistant (Easy)

1. Measure Reference Humidity

   • Use a calibrated hygrometer near the CeilSense

2. Adjust the Offset in Home Assistant

   • Go to Settings → Devices & Services → ESPHome → CeilSense
   • Find "SCD4x Humidity Offset (%)"
   • Enter your offset value (can be positive or negative, range -20 to +20)
   • The setting is saved automatically and persists across reboots

Method 2: Adjust via ESPHome Substitutions (Advanced)

For permanent changes via ESPHome, the humidity offset is applied via the number entity (there's no substitution for humidity offset by default).

Light Sensor Calibration

The BH1750 light sensor is factory-calibrated, but you can adjust readings if needed by adopting the device in ESPHome and extending the sensor configuration.

1. Measure Reference Light Level

   • Use a lux meter to measure light at ceiling level

2. Apply Calibration Factor via ESPHome

   • Adopt the device in ESPHome Dashboard
   • Add a filter by extending the existing sensor using its id:

sensor:
  - id: !extend illuminance
    filters:
      - multiply: 1.1  # Adjust if readings are consistently off

Note: The !extend directive allows you to add configuration to an existing sensor without redefining it completely.

Barometric Pressure Calibration

The BMP388 pressure sensor is highly accurate and typically doesn't need calibration. However, if you want to adjust readings:

1. Find Your Local Pressure

   • Check a local weather station for current sea-level pressure

2. Apply Offset via ESPHome

   • Adopt the device in ESPHome Dashboard
   • Add a filter by extending the existing sensor:

sensor:
  - id: !extend bmp_pressure
    filters:
      - offset: 5.0  # Adjust if readings are consistently off (in hPa)

Advanced Configuration via ESPHome

For users who want full control over sensor settings, you can adopt the CeilSense in ESPHome Dashboard and modify the configuration.

How to Adopt and Configure

1. Open ESPHome Dashboard in Home Assistant
2. Adopt the CeilSense device (it will appear as a discovered device)
3. Edit the YAML configuration
4. Modify substitutions as needed
5. Save and install OTA (Over-The-Air)

Available SCD41 Substitutions

substitutions:
  # I2C settings (usually no need to change)
  scd4x_i2c_id: "bus_a"
  scd4x_address: "0x62"
  
  # Measurement mode: "periodic" (5s) or "low_power_periodic" (30s)
  scd4x_measurement_mode: "low_power_periodic"
  
  # How often to update readings
  scd4x_update_interval: "30s"
  
  # Automatic Self Calibration (true/false)
  # Set to true only if the room regularly gets fresh air
  scd4x_asc: "false"
  
  # Base temperature offset for ESP heat compensation
  scd4x_temperature_offset: "10.0"

When to Enable Automatic Self Calibration (ASC)

Enable ASC (scd4x_asc: "true") only if:

• The room regularly gets fresh air (windows opened, good ventilation)
• CO₂ levels drop to ~400 ppm at least once every few days
• You don't want to manually calibrate

Keep ASC disabled (scd4x_asc: "false") if:

• The room rarely gets fresh air
• It's a bedroom or office that's always occupied
• You prefer manual calibration control

Calibration Best Practices

• Calibrate in stable conditions: Avoid calibrating during temperature changes or high humidity
• Document your offsets: Keep track of what calibration values you've applied
• Re-calibrate periodically: Check calibration every 6-12 months or after relocating the sensor
• Allow warm-up time: Sensors need 15-30 minutes after power-on to stabilize
• Compare multiple references: Use more than one reference device when possible

Troubleshooting Calibration Issues

Issue	Possible Cause	Solution
Temperature always too high	LED heat / poor airflow	Reduce LED usage, check ceiling cavity
CO₂ never drops below 600 ppm	ABC not calibrated	Ventilate room regularly, or manual calibrate
Humidity seems off	Temperature offset affecting calculation	Calibrate temperature first, then humidity
Readings fluctuate wildly	Sensor not stabilized	Wait longer after power-on

Need Help?

If you're having trouble with calibration:

• Check the Troubleshooting guide
• Join our Discord community for support
• Contact us via our contact page