Firmware Guide

Local operation and GitHub update checks

The local Home Assistant firmware keeps CeilSense measurements on your own network. Sensor readings go directly to Home Assistant and are not sent to GitHub or the SmartHomeShop cloud.

Wi-Fi and Ethernet firmware includes an ESPHome update entity. It periodically reads a small firmware manifest from SmartHomeShop GitHub Pages to compare the installed version with the latest release. Only firmware metadata is requested; the firmware file is downloaded only when you install an update.

Cloud firmware intentionally communicates with the SmartHomeShop app as part of its cloud features. Disabling the GitHub update check does not convert cloud firmware into local firmware.

Use CeilSense without internet access

You may block internet access for CeilSense; its local measurements and Home Assistant connection continue to work. To prevent a blocked check from triggering the red status LED, take control of the device in the ESPHome Device Builder app/add-on, open its YAML and add this at the bottom:

update:
  - id: !extend firmware_update
    update_interval: never

Save the YAML, select Validate, and install the build using Install > Wirelessly. This disables scheduled checks only; it does not remove the update component or change any CeilSense sensors.

The adopted YAML continues to contain a packages: link to the SmartHomeShop GitHub repository. ESPHome uses that link on the Home Assistant host when it compiles your firmware. The device itself no longer polls for firmware versions after the customized build is installed.

To restore automatic checks, remove the added update: block and install the firmware again. If ESPHome cannot find the firmware_update ID, update CeilSense through the SmartHomeShop web flasher before applying this customization.

CeilSense runs on ESPHome, an open-source firmware platform that works with Home Assistant. ESPHome allows you to customize every aspect of your device's behavior while maintaining full local control, no cloud required.

Firmware on GitHub

All CeilSense firmware is public on GitHub under the CC BY-NC 4.0 license:

🔗 github.com/smarthomeshop/ceilsense

The repository includes:

• Complete ESPHome configurations for all variants
• Modular package system for easy customization
• Automated builds via GitHub Actions
• Community contributions welcome (PRs & issues)

You can view, modify, and customize the firmware to suit your needs, from adjusting sensor thresholds to adding completely new features.

Firmware Variants

CeilSense offers 12 firmware variants, each as a local and as a SmartHomeShop App (cloud) build, so 24 in total:

Network Types

• WiFi: Standard 2.4GHz wireless connectivity
• Ethernet: Wired connection with optional PoE support

Feature Levels

• Basic: Core sensors (light, pressure and the temperature of the pressure sensor)
• Complete: Basic + CO₂ monitoring (SCD41 sensor)

Presence Detection (Optional)

• No presence sensor: Environmental monitoring only
• LD2412: mmWave presence detection, the standard radar
• LD2450: Advanced mmWave with multi-target tracking, positioning, speed, and zone detection

Example variant names:

• ceilsense-basic-wifi - Basic sensors with WiFi
• ceilsense-complete-eth-ld2450 - All sensors + Ethernet + advanced presence tracking
• ceilsense-complete-eth-ld2450-cloud - The same with the SmartHomeShop App

Tip: Use our web flasher at smarthomeshop.io/en/firmware?product=ceilsense to easily select and install the right variant.

Quick Update Methods

Method 1: Home Assistant (Easiest)

For regular firmware updates (recommended):

1. Go to Settings → Devices & Services → Devices
2. Select your CeilSense device
3. Open the CeilSense Firmware update entity
4. Click Check for updates
5. Click Install to download and apply the update
6. The device will reboot automatically

Method 2: ESPHome Device Builder

For updates with custom configurations:

⚠️ Important: This method requires the ESPHome Device Builder app, version 2026.9.0 or newer, not just the ESPHome integration. If you haven't installed it yet, see the ESPHome Integration Guide section below for step-by-step installation instructions.

1. Open the ESPHome Device Builder in Home Assistant (from the sidebar)
2. Click on your CeilSense device card
3. Click Install → choose Wirelessly
4. Wait for the OTA update to complete

Method 3: USB-C Web Flasher

For changing between Basic, Complete and radar variants, or recovering devices. To change only the network or cloud type, use the Firmware Variant selector:

1. Connect CeilSense via USB-C data cable to your computer
2. Open the flasher in Chrome or Edge: smarthomeshop.io/en/firmware?product=ceilsense
3. Choose how you use the device, then your firmware variant
4. Click Install firmware and choose the USB port
5. Follow the on-screen prompts. The website then offers a short hardware test

Note: Flashing from this page returns the device to its factory settings. Wi-Fi variants start the setup hotspot again, Ethernet variants get an IP address through DHCP. You may need to add the device to Home Assistant again.

ESPHome Integration Guide

Want to customize your CeilSense firmware? Follow this step-by-step guide to adopt your device in ESPHome and make modifications.

🚨 Critical: Understanding the Difference

Many users get confused between two different things:

• ESPHome Integration (Settings → Devices & Services → Integrations) - This is how your CeilSense communicates with Home Assistant. You probably already have this. ✅
• ESPHome Device Builder app (Settings → Apps) - This is the tool you need to edit, build, and flash firmware. You need to install this separately! 🔧

To customize firmware, you MUST install the ESPHome Device Builder app below. Having just the integration is not enough!

Step 1: Install ESPHome Device Builder

If you haven't installed the ESPHome Device Builder app yet:

1. Open Home Assistant → Settings → Apps
2. Click Install app
3. Search for ESPHome Device Builder
4. Click ESPHome Device Builder → Install
5. Enable Start on boot and Show in sidebar
6. Click Start

Step 2: Adopt Your CeilSense

Adopting allows ESPHome to manage your device's configuration:

1. Open ESPHome from the Home Assistant sidebar
2. Your CeilSense should appear as a discovered device
3. Click Take control or Adopt on the CeilSense card
4. Give it a name (e.g., "Living Room CeilSense")
5. Confirm

ESPHome now creates a small YAML file that points to the firmware on GitHub.

What does the adopted configuration look like?

After adoption, you'll see a YAML configuration that looks like this:

substitutions:
  name: ceilsense-587c20
  friendly_name: CeilSense 587c20

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

esphome:
  name: ${name}
  name_add_mac_suffix: false
  friendly_name: ${friendly_name}

api:
  encryption:
    key: YOUR_UNIQUE_ENCRYPTION_KEY

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

Understanding this structure:

• substitutions: The name of your device. Add your own values here, such as scd4x_temperature_offset.
• packages: Links to the base configuration on GitHub. ESPHome downloads it each time you install the firmware.
• api/wifi: Your device's unique encryption key and WiFi credentials.

This modular approach means: ✅ You get the latest configuration from GitHub each time you install ✅ Your customizations stay separate in substitutions ✅ You don't need to copy/paste the entire configuration

Step 3: Customize the Configuration

After adoption, you can modify the YAML configuration:

1. Click Edit on your adopted CeilSense device
2. The YAML editor opens with your current configuration
3. Make your desired changes (see examples below)
4. Click Save

Step 4: Upload Modified Firmware

After making changes:

1. Click Install on your device card
2. Choose Wirelessly (recommended) or Plug into this computer
3. ESPHome will compile and upload your custom firmware
4. Wait for the device to reboot and reconnect

✅ Done! Your CeilSense is now running custom firmware.

Advanced Customization

Example 1: Adjust Sensor Update Intervals

Make sensors update more or less frequently:

sensor:
  # Pressure and temperature sensor
  - id: !extend bmp3xx_sensor
    update_interval: 30s  # Default: 60s

  # Light sensor
  - id: !extend illuminance
    update_interval: 5s  # Faster updates for lighting automations

Example 2: Add Custom Presence Timeout

Customize how long presence remains detected after motion stops:

binary_sensor:
  - platform: template
    name: "Extended Presence"
    lambda: |-
      if (id(presence).state) {
        return true;
      }
      return false;
    filters:
      - delayed_off: 5min  # Stay "present" for 5 minutes after motion stops

Example 3: Add Bluetooth Proxy

Turn your CeilSense into a Bluetooth proxy for other devices:

esp32_ble_tracker:
  scan_parameters:
    interval: 1100ms
    window: 1100ms
    active: true

bluetooth_proxy:
  active: true

On Wi-Fi firmware, also turn off the Disable Bluetooth after boot switch. Otherwise Bluetooth stops as soon as Wi-Fi is connected.

Example 4: Custom CO₂ Alerts

You do not need YAML for this. Complete variants with local firmware have a built-in CO₂ warning on the LED ring, see LED Lighting.

Example 5: Add Additional Packages

CeilSense uses a modular package system. Add your own package next to the existing import in your adopted YAML:

packages:
  smarthomeshop.ceilsense: github://smarthomeshop/ceilsense/ceilsense-v1/ceilsense-complete-wifi-ld2412.yaml@main
  my_custom: !include my_custom.yaml

Learn More: Check the ESPHome documentation for complete configuration reference.

Modular Configuration Structure

CeilSense firmware uses a modular architecture with reusable packages:

ceilsense-v1/
├── base.yaml                    # Core device config (all variants)
├── wifi.yaml                    # WiFi connectivity
├── eth.yaml                     # Ethernet connectivity
├── packages/
│   ├── ld2412.yaml              # LD2412 presence detection
│   ├── ld2450.yaml              # LD2450 presence tracking
│   ├── scd4x.yaml               # CO₂ monitoring
│   ├── led_local_*.yaml         # Automatic LED lighting
│   └── cloud_*.yaml             # SmartHomeShop App firmware
└── [24 variant configurations]

This modular design makes it easy to:

• Add/remove sensors
• Share configurations across devices
• Maintain consistency across variants
• Contribute improvements back to the community

Troubleshooting

Device Won't Update OTA

Symptoms: OTA update fails or times out

Solutions:

1. Ensure the device is powered on and connected to WiFi
2. Check that the device is within WiFi range (strong signal)
3. Verify ota: is enabled in your YAML configuration
4. Try restarting the device with the Restart Device button on its device page in Home Assistant
5. If all else fails, flash via USB-C cable

Device Not Discovered After Flashing

Symptoms: CeilSense doesn't appear in ESPHome after USB flashing

Solutions:

1. The device may have lost WiFi credentials during flashing
2. Connect via USB-C and check the logs in ESPHome
3. Use Improv via BLE to reconfigure WiFi:
   • Open Home Assistant companion app
   • Go to Settings → Devices → Add Device
   • Select your CeilSense from the BLE devices list
4. Alternatively, use the setup hotspot:
   • Device creates a WiFi hotspot named ceilsense with password ceilsense
   • Connect to it and configure WiFi on the setup page

Wrong Variant Flashed

Symptoms: Sensors missing or not working as expected

Solution:

1. Verify you flashed the correct variant for your hardware
2. Check the Device Info in Home Assistant: Settings → Devices → CeilSense
3. Flash the correct variant using the web flasher
4. Variants with presence sensors (LD2412/LD2450) require the physical sensor to be installed

Sensor Readings Seem Inaccurate

Solutions:

1. CO₂ sensor: Automatic self-calibration is off by default, so run a manual calibration in fresh air. See the Calibration Guide
2. Pressure/Temperature: Ensure proper ventilation around the device (not in a sealed enclosure)
3. Light sensor: Position away from direct light sources
4. Presence sensor: Adjust detection zones in the sensor settings

Compilation Errors in ESPHome

Symptoms: Custom YAML fails to compile

Solutions:

1. Check for YAML syntax errors (indentation must be consistent)
2. Verify you're using ESPHome 2026.9.0 or newer, older versions refuse this firmware
3. Check the compilation log for specific error messages
4. Compare your changes against the official configuration
5. Ask for help on GitHub Issues or our Discord community

Ethernet Not Working (PoE Variants)

Symptoms: Ethernet connection fails or unstable

Solutions:

1. Ensure you flashed the Ethernet firmware variant (not WiFi)
2. Flash the Ethernet variant before connecting PoE for the first time
3. Verify your PoE switch provides sufficient power (IEEE 802.3af/at)
4. Check Ethernet cable is properly seated in both ends
5. Test with a known-good Ethernet cable

Firmware Changelog

Latest changes are announced alongside releases. Major updates will appear here.

Where to find changes:

• GitHub Releases
• CHANGELOG.md

Additional Resources

• GitHub Repository: github.com/smarthomeshop/ceilsense
• ESPHome Documentation: esphome.io
• Web Flasher: smarthomeshop.io/en/firmware?product=ceilsense
• Community Support: SmartHomeShop Discord

Need help? Visit our Support Portal or join our Discord community!