SmartHomeShop Docs

Firmwarehandleiding

Lokale werking en GitHub-updatecontrole

De lokale Home Assistant-firmware houdt de metingen van CeilSense op je eigen netwerk. Sensorwaarden gaan rechtstreeks naar Home Assistant en worden niet naar GitHub of de SmartHomeShop-cloud gestuurd.

WiFi- en Ethernetfirmware bevat een ESPHome-update-entiteit. Deze leest periodiek een klein firmwaremanifest vanaf SmartHomeShop GitHub Pages om de geïnstalleerde versie met de nieuwste release te vergelijken. Alleen firmwaremetadata wordt opgevraagd; het firmwarebestand wordt pas gedownload wanneer je een update installeert.

Cloudfirmware communiceert voor de cloudfuncties bewust met de SmartHomeShop-app. Het uitschakelen van de GitHub-controle verandert cloudfirmware niet in lokale firmware.

CeilSense zonder internettoegang gebruiken

Je mag internettoegang voor CeilSense blokkeren; de lokale metingen en Home Assistant-verbinding blijven werken. Wil je voorkomen dat een geblokkeerde controle de rode status-led activeert? Neem het apparaat dan over in de ESPHome Device Builder-app/add-on, open de YAML en voeg dit onderaan toe:

update:
  - id: !extend firmware_update
    update_interval: never

Sla de YAML op, kies Validate en installeer de build met Install > Wirelessly. Hiermee schakel je alleen geplande controles uit; het updatecomponent en alle CeilSense-sensoren blijven aanwezig.

De geadopteerde YAML bevat nog steeds een packages:-verwijzing naar de SmartHomeShop GitHub-repository. ESPHome gebruikt die verwijzing op de Home Assistant-host tijdens het compileren. Nadat de aangepaste build is geïnstalleerd, vraagt het apparaat zelf niet meer periodiek de firmwareversie op.

Wil je automatische controles herstellen? Verwijder dan het toegevoegde update:-blok en installeer de firmware opnieuw. Kan ESPHome het ID firmware_update niet vinden, werk CeilSense dan eerst bij via de SmartHomeShop-webflasher.

CeilSense draait op ESPHome, een open-source firmware platform dat werkt met Home Assistant. ESPHome stelt je in staat om elk aspect van je apparaat aan te passen terwijl je volledige lokale controle behoudt: geen cloud vereist.

Firmware op GitHub

Alle CeilSense firmware is openbaar op GitHub onder de licentie CC BY-NC 4.0:

🔗 github.com/smarthomeshop/ceilsense

De repository bevat:

  • Complete ESPHome configuraties voor alle varianten
  • Modulair package systeem voor eenvoudige aanpassingen
  • Geautomatiseerde builds via GitHub Actions
  • Community bijdragen welkom (PRs & issues)

Je kunt de firmware bekijken, aanpassen en personaliseren naar wens: van het aanpassen van sensor drempelwaarden tot het toevoegen van compleet nieuwe functies.

Firmware Varianten

CeilSense biedt 12 firmware varianten, elk als lokale build en als SmartHomeShop-app (cloud) build, dus 24 in totaal:

Netwerk Types

  • WiFi: Standaard 2.4GHz draadloze connectiviteit
  • Ethernet: Bedrade verbinding met optionele PoE ondersteuning

Feature Levels

  • Basic: Basis sensoren (licht, druk en de temperatuur van de druksensor)
  • Complete: Basic + CO₂ monitoring (SCD41 sensor)

Aanwezigheidsdetectie (Optioneel)

  • Geen aanwezigheidssensor: Alleen omgevingsmonitoring
  • LD2412: mmWave aanwezigheidsdetectie, de standaard radar
  • LD2450: Geavanceerde mmWave met multi-target tracking, positionering, snelheid en zone detectie

Voorbeeld variant namen:

  • ceilsense-basic-wifi - Basis sensoren met WiFi
  • ceilsense-complete-eth-ld2450 - Alle sensoren + Ethernet + geavanceerde presence tracking
  • ceilsense-complete-eth-ld2450-cloud - Hetzelfde met de SmartHomeShop-app

Tip: Gebruik onze web flasher op smarthomeshop.io/firmware?product=ceilsense om eenvoudig de juiste variant te selecteren en installeren.

Snelle Update Methodes

Methode 1: Home Assistant (Makkelijkste)

Voor reguliere firmware updates (aanbevolen):

  1. Ga naar Instellingen → Apparaten & Services → Apparaten
  2. Selecteer je CeilSense apparaat
  3. Open de update-entiteit CeilSense Firmware
  4. Klik Controleer op updates
  5. Klik Installeren om de update te downloaden en toe te passen
  6. Het apparaat herstart automatisch

Methode 2: ESPHome Device Builder

Voor updates met aangepaste configuraties:

⚠️ Belangrijk: Deze methode vereist de ESPHome Device Builder-app, versie 2026.9.0 of nieuwer, niet alleen de ESPHome integratie. Als je deze nog niet hebt geïnstalleerd, zie de ESPHome Integratie Handleiding sectie hieronder voor stap-voor-stap installatie instructies.

  1. Open het ESPHome Device Builder in Home Assistant (vanuit de zijbalk)
  2. Klik op je CeilSense apparaat kaart
  3. Klik Install → kies Wirelessly
  4. Wacht tot de OTA update voltooid is

Methode 3: USB-C Web Flasher

Voor het wisselen tussen Basic, Complete en radarvarianten, of herstel van apparaten. Wil je alleen het netwerk- of cloudtype wijzigen, gebruik dan de Firmware Variant selector:

  1. Verbind CeilSense via een USB-C datakabel met je computer
  2. Open de flasher in Chrome of Edge: smarthomeshop.io/firmware?product=ceilsense
  3. Kies hoe je het apparaat gebruikt en daarna je firmware variant
  4. Klik op Firmware installeren en kies de USB poort
  5. Volg de instructies op het scherm. De website biedt daarna een korte hardwaretest aan

Opmerking: Flashen vanaf deze pagina zet het apparaat terug naar de fabrieksinstellingen. Wi-Fi-varianten starten weer de setup-hotspot, Ethernet-varianten krijgen een IP-adres via DHCP. Mogelijk moet je het apparaat opnieuw toevoegen aan Home Assistant.

ESPHome Integratie Handleiding

Wil je je CeilSense firmware aanpassen? Volg deze stap-voor-stap handleiding om je apparaat te adopteren in ESPHome en aanpassingen te maken.

🚨 Belangrijk: Het Verschil Begrijpen

Veel gebruikers verwarren twee verschillende zaken:

  • ESPHome Integratie (Instellingen → Apparaten & Services → Integraties) - Dit is hoe je CeilSense communiceert met Home Assistant. Deze heb je waarschijnlijk al. ✅
  • ESPHome Device Builder-app (Instellingen → Apps) - Dit is de tool die je nodig hebt om firmware te bewerken, builden en flashen. Deze moet je apart installeren! 🔧

Om firmware aan te passen, MOET je de ESPHome Device Builder-app hieronder installeren. Alleen de integratie hebben is niet genoeg!

Stap 1: Installeer ESPHome Device Builder

Als je de ESPHome Device Builder-app nog niet hebt geïnstalleerd:

  1. Open Home Assistant → Instellingen → Apps
  2. Klik Installeer een app (of Install app)
  3. Zoek naar ESPHome Device Builder
  4. Klik ESPHome Device Builder → Installeer
  5. Schakel Start bij opstarten en Toon in zijbalk in
  6. Klik Start

Stap 2: Adopteer je CeilSense

Adopteren stelt ESPHome in staat om de configuratie van je apparaat te beheren:

  1. Open ESPHome vanuit de Home Assistant zijbalk
  2. Je CeilSense verschijnt als een ontdekt apparaat
  3. Klik Take control of Adopt op de CeilSense kaart
  4. Geef het een naam (bijv. "Woonkamer CeilSense")
  5. Bevestig

ESPHome maakt nu een klein YAML-bestand dat naar de firmware op GitHub verwijst.

Hoe ziet de geadopteerde configuratie eruit?

Na adoptie zie je een YAML configuratie die er zo uitziet:

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: JE_UNIEKE_ENCRYPTIE_KEY

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

Deze structuur begrijpen:

  • substitutions: De naam van je apparaat. Voeg hier je eigen waarden toe, zoals scd4x_temperature_offset.
  • packages: Link naar de basis configuratie op GitHub. ESPHome haalt die op elke keer dat je de firmware installeert.
  • api/wifi: Je apparaat's unieke encryptie key en WiFi inloggegevens.

Deze modulaire aanpak betekent: ✅ Je krijgt bij elke installatie de nieuwste configuratie van GitHub ✅ Je customizations blijven gescheiden in substitutions ✅ Je hoeft niet de hele configuratie te kopiëren/plakken

Stap 3: Pas de Configuratie Aan

Na adoptie kun je de YAML configuratie aanpassen:

  1. Klik Edit op je geadopteerde CeilSense apparaat
  2. De YAML editor opent met je huidige configuratie
  3. Maak je gewenste wijzigingen (zie voorbeelden hieronder)
  4. Klik Save

Stap 4: Upload Aangepaste Firmware

Na het maken van wijzigingen:

  1. Klik Install op je apparaat kaart
  2. Kies Wirelessly (aanbevolen) of Plug into this computer
  3. ESPHome compileert en uploadt je aangepaste firmware
  4. Wacht tot het apparaat herstart en opnieuw verbindt

✅ Klaar! Je CeilSense draait nu op aangepaste firmware.

Geavanceerde Aanpassingen

Voorbeeld 1: Pas Sensor Update Intervallen Aan

Laat sensoren vaker of minder vaak updaten:

sensor:
  # Druk- en temperatuursensor
  - id: !extend bmp3xx_sensor
    update_interval: 30s  # Standaard: 60s

  # Licht sensor
  - id: !extend illuminance
    update_interval: 5s  # Snellere updates voor verlichting automaties

Voorbeeld 2: Voeg Custom Aanwezigheid Timeout Toe

Pas aan hoe lang aanwezigheid gedetecteerd blijft na beweging:

binary_sensor:
  - platform: template
    name: "Verlengde Aanwezigheid"
    lambda: |-
      if (id(presence).state) {
        return true;
      }
      return false;
    filters:
      - delayed_off: 5min  # Blijf "aanwezig" voor 5 minuten na beweging

Voorbeeld 3: Voeg Bluetooth Proxy Toe

Maak van je CeilSense een Bluetooth proxy voor andere apparaten:

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

bluetooth_proxy:
  active: true

Zet op Wi-Fi firmware ook de schakelaar Disable Bluetooth after boot uit. Anders stopt Bluetooth zodra Wi-Fi verbonden is.

Voorbeeld 4: Custom CO₂ Alerts

Hiervoor heb je geen YAML nodig. Complete-varianten met lokale firmware hebben een ingebouwde CO₂-waarschuwing op de LED-ring, zie LED-verlichting.

Voorbeeld 5: Voeg Extra Packages Toe

CeilSense gebruikt een modulair package systeem. Voeg je eigen package toe naast de bestaande import in je geadopteerde YAML:

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

Meer info: Bekijk de ESPHome documentatie voor complete configuratie referentie.

Modulaire Configuratie Structuur

CeilSense firmware gebruikt een modulaire architectuur met herbruikbare packages:

ceilsense-v1/
├── base.yaml                    # Basis apparaat configuratie (alle varianten)
├── wifi.yaml                    # WiFi connectiviteit
├── eth.yaml                     # Ethernet connectiviteit
├── packages/
│   ├── ld2412.yaml              # LD2412 aanwezigheidsdetectie
│   ├── ld2450.yaml              # LD2450 aanwezigheid tracking
│   ├── scd4x.yaml               # CO₂ monitoring
│   ├── led_local_*.yaml         # Automatische LED-verlichting
│   └── cloud_*.yaml             # Firmware voor de SmartHomeShop-app
└── [24 variant configuraties]

Dit modulaire ontwerp maakt het makkelijk om:

  • Sensoren toe te voegen/verwijderen
  • Configuraties te delen tussen apparaten
  • Consistentie te behouden over varianten
  • Verbeteringen terug te geven aan de community

Probleemoplossing

Apparaat Wil Niet OTA Updaten

Symptomen: OTA update mislukt of time-out

Oplossingen:

  1. Zorg dat het apparaat aanstaat en verbonden is met WiFi
  2. Controleer dat het apparaat binnen WiFi bereik is (sterk signaal)
  3. Verifieer dat ota: ingeschakeld is in je YAML configuratie
  4. Probeer het apparaat te herstarten met de knop Restart Device op de apparaatpagina in Home Assistant
  5. Als alles faalt, flash via USB-C kabel

Apparaat Niet Ontdekt Na Flashen

Symptomen: CeilSense verschijnt niet in ESPHome na USB flashen

Oplossingen:

  1. Het apparaat heeft mogelijk WiFi inloggegevens verloren tijdens flashen
  2. Verbind via USB-C en bekijk de logs in ESPHome
  3. Gebruik Improv via BLE om WiFi opnieuw te configureren:
    • Open Home Assistant companion app
    • Ga naar Instellingen → Apparaten → Apparaat toevoegen
    • Selecteer je CeilSense uit de BLE apparaten lijst
  4. Alternatief, gebruik de setup-hotspot:
    • Apparaat maakt een WiFi hotspot aan genaamd ceilsense met wachtwoord ceilsense
    • Verbind ermee en configureer WiFi op de instelpagina

Verkeerde Variant Geflasht

Symptomen: Sensoren ontbreken of werken niet zoals verwacht

Oplossing:

  1. Verifieer dat je de juiste variant hebt geflasht voor je hardware
  2. Controleer de Device Info in Home Assistant: Instellingen → Apparaten → CeilSense
  3. Flash de correcte variant met de web flasher
  4. Varianten met aanwezigheidssensoren (LD2412/LD2450) vereisen dat de fysieke sensor geïnstalleerd is

Sensor Metingen Lijken Onnauwkeurig

Oplossingen:

  1. CO₂ sensor: Automatische zelfkalibratie staat standaard uit, voer dus een handmatige kalibratie uit in frisse lucht. Zie de Kalibratie Handleiding
  2. Druk/Temperatuur: Zorg voor goede ventilatie rond het apparaat (niet in een afgesloten behuizing)
  3. Licht sensor: Positioneer weg van directe lichtbronnen
  4. Aanwezigheidssensor: Pas detectie zones aan in de sensor instellingen

Compilatie Fouten in ESPHome

Symptomen: Custom YAML compileert niet

Oplossingen:

  1. Controleer op YAML syntax fouten (inspringingen moeten consistent zijn)
  2. Verifieer dat je ESPHome 2026.9.0 of nieuwer gebruikt, oudere versies weigeren deze firmware
  3. Bekijk de compilatie log voor specifieke foutmeldingen
  4. Vergelijk je wijzigingen met de officiële configuratie
  5. Vraag om hulp op GitHub Issues of onze Discord community

Ethernet Werkt Niet (PoE Varianten)

Symptomen: Ethernet verbinding mislukt of instabiel

Oplossingen:

  1. Zorg dat je de Ethernet firmware variant hebt geflasht (niet WiFi)
  2. Flash de Ethernet variant voordat je voor het eerst PoE aansluit
  3. Verifieer dat je PoE switch voldoende vermogen levert (IEEE 802.3af/at)
  4. Controleer of Ethernet kabel goed vastzit aan beide kanten
  5. Test met een bekende werkende Ethernet kabel

Firmware Changelog

Nieuwste wijzigingen worden bij releases aangekondigd. Grote updates verschijnen hier.

Waar vind je wijzigingen:

Aanvullende Bronnen

Hulp nodig? Bezoek ons Support Portal of join onze Discord community!