SmartHomeShop Docs

Firmwarehandleiding

Lokale werking en GitHub-updatecontrole

De lokale Home Assistant-firmware houdt de metingen van UltimateSensor v1 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.

UltimateSensor v1 zonder internettoegang gebruiken

Je mag internettoegang voor UltimateSensor v1 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 UltimateSensor v1-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 UltimateSensor v1 dan eerst bij via de SmartHomeShop-webflasher.

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

Versie 2.0 vereist eenmalig USB-C: UltimateSensor V1 firmware 2.0 zet het apparaat om van Arduino naar ESP-IDF. Apparaten met firmware 1.13 of ouder moeten versie 2.0 eenmalig via USB-C installeren. Installeer deze frameworkmigratie niet via Home Assistant of OTA. Nadat versie 2.0 via USB-C is geïnstalleerd, werken toekomstige 2.x-updates weer draadloos. Volg de aparte upgradehandleiding voor versie 2.0.

Architectuur van versie 2.0

Versie 2.0 gebruikt ESP-IDF voor alle acht V1-firmwarevarianten en behoudt het native LD2450-trackingplatform dat in firmware 1.11 is ingevoerd:

  • native LD2450-tracking voor maximaal drie personen;
  • vier polygonzones en twee uitsluitingszones;
  • twee virtuele tellijnen en personentelling;
  • Home Assistant-acties om zones vanuit de SmartHomeShop Room Designer naar de sensor te sturen.

Bestaande rechthoekige zone-instellingen uit firmware ouder dan 1.11 worden niet automatisch omgezet. Bewaar je huidige instellingen voor de USB-C- installatie en stel daarna de polygonzones in.

Heb je vragen over de update? Word lid van de SmartHomeShop Discord-community.

Firmware op GitHub

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

🔗 github.com/smarthomeshop/ultimatesensor

De repository bevat:

  • Volledige ESPHome configuraties voor alle varianten
  • Modulair pakket systeem voor eenvoudige aanpassing
  • Release notes voor klanten in CHANGELOG.md
  • Community bijdragen welkom (PRs & issues)

Je kunt de firmware bekijken, wijzigen en aanpassen aan je behoeften: van het aanpassen van sensordrempels tot het toevoegen van volledig nieuwe functies.

Firmwarevarianten

UltimateSensor V1 biedt vier netwerk-/hardwarecombinaties. Iedere combinatie is beschikbaar als lokale Home Assistant-firmware of als cloudfirmware voor de SmartHomeShop-app, voor in totaal 8 firmwarevarianten:

Netwerktypen

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

Sensorniveaus

  • Basic: CO₂, Temp, Vochtigheid, Licht, VOC, NOx, mmWave, PIR
  • Complete: Alle Basic sensoren + Fijnstof (PM) monitoring

Variantnamen:

  • ultimatesensor-wifi-basic - Basic sensoren met WiFi
  • ultimatesensor-wifi-complete - Alle sensoren met WiFi
  • ultimatesensor-ethernet-basic - Basic sensoren met Ethernet/PoE
  • ultimatesensor-ethernet-complete - Alle sensoren met Ethernet/PoE
  • Voeg -cloud aan de variantnaam toe wanneer ondersteuning voor de SmartHomeShop-app nodig is

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

🔍 Hoe te identificeren: Als je apparaat PM1.0, PM2.5, PM4.0, PM10 meet → je hebt Complete. Anders → Basic.

Varianten Wisselen

Elke UltimateSensor V1 met firmware 1.12 of nieuwer heeft in Home Assistant een selector UltimateSensor Firmware Variant met alle acht varianten. Op de instelpagina van WiFi firmware kies je WiFi of Ethernet en SmartHomeShop Cloud aan of uit.

  • Op WiFi firmware: kies de nieuwe variant. Het apparaat downloadt en installeert hem zelf via WiFi en herstart. Reken op minstens 2 minuten en laat het apparaat aan staan. Koos je Ethernet, dan werkt de Ethernet poort na de herstart.
  • Op Ethernet firmware: de selector wijzigt alleen de updatebron. De update-entiteit biedt de andere variant aan als die een nieuwere versie heeft dan de geïnstalleerde. Wil je meteen wisselen, gebruik dan USB-C (Methode 3).

Kies alleen een Complete-variant als je apparaat de PM sensor heeft.

Snelle Update Methodes

Methode 1: Home Assistant (Makkelijkst)

Voor reguliere firmware-updates nadat versie 2.0 via USB-C is geïnstalleerd:

  1. Ga naar Instellingen → Apparaten & Services → Apparaten
  2. Selecteer je UltimateSensor apparaat
  3. Schakel de update-entiteit UltimateSensor Firmware in, die staat standaard uit
  4. Open die entiteit en klik op Controleren op updates
  5. Klik op Installeren om de update te downloaden en toe te passen
  6. Het apparaat zal automatisch herstarten

Methode 2: ESPHome Device Builder

Voor updates met aangepaste configuraties na de USB-C-migratie naar versie 2.0:

⚠️ Belangrijk: Deze methode vereist de ESPHome Device Builder-app, versie 2026.10.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 UltimateSensor apparaat kaart
  3. Klik op Installeren → kies Draadloos
  4. Wacht tot de OTA update voltooid is

Methode 3: USB-C Web Flasher

Verplicht voor de migratie naar versie 2.0, het herstellen van apparaten en om Ethernet firmware te verlaten:

⚠️ Hardwarestap: Voordat je via USB-C flasht, moet je de LD2450 mmWave sensor verwijderen omdat die kan voorkomen dat het apparaat in flashmodus komt. Zie de voorbereidingsstappen hieronder.

Voorbereiding:

  1. Koppel USB-C, Ethernet/PoE en alle andere voeding los
  2. Open de behuizing: zoek de kleine uitsparing aan de onderkant voor een platte schroevendraaier
  3. Noteer de richting van de blauwe LD2450 sensor
  4. Verwijder de blauwe LD2450 sensor: trek hem voorzichtig recht uit de voorkant van de hoofd PCB

Flashstappen:

  1. Verbind UltimateSensor via een USB-C datakabel met je computer
  2. Open de flasher in Chrome of Edge: smarthomeshop.io/firmware?product=ultimatesensor&hardware=v1
  3. Kies hoe je het apparaat gebruikt en daarna je firmware variant (WiFi/Ethernet + Basic/Complete)
  4. Klik op Firmware installeren en kies de USB poort
  5. Wacht tot de website bevestigt dat het flashen klaar is en koppel dan de USB-C kabel los
  6. Monteer opnieuw: plaats de LD2450 sensor in exact dezelfde richting terug en sluit de behuizing

Waarschuwing: De LD2450 verkeerd om plaatsen kan de hardware beschadigen. Verwijder of plaats hem nooit terwijl de UltimateSensor onder spanning staat.

Opmerking: Flashen vanaf deze pagina zet het apparaat terug naar de fabrieksinstellingen. WiFi-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 UltimateSensor firmware aanpassen? Volg deze stap-voor-stap handleiding om je apparaat te adopteren in ESPHome en wijzigingen aan te brengen.

🚨 Kritiek: Het Verschil Begrijpen

Veel gebruikers raken in de war tussen twee verschillende dingen:

  • ESPHome Integratie (Instellingen → Apparaten & Services → Integraties) - Dit is hoe je UltimateSensor communiceert met Home Assistant. Je hebt dit waarschijnlijk al. ✅
  • ESPHome Device Builder-app (Instellingen → Apps) - Dit is de tool die je nodig hebt om firmware te bewerken, bouwen en flashen. Je moet dit 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 op Installeer een app (of Install app)
  3. Zoek naar ESPHome Device Builder
  4. Klik op ESPHome Device Builder → Installeren
  5. Schakel Start bij opstarten en Toon in zijbalk in
  6. Klik op Start

Stap 2: Adopteer Je UltimateSensor

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

  1. Open ESPHome vanuit de Home Assistant zijbalk
  2. Je UltimateSensor zou als een ontdekt apparaat moeten verschijnen
  3. Klik op Take control of Adopt op de UltimateSensor kaart
  4. Geef het een naam (bijv. "Woonkamer UltimateSensor")
  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: ultimatesensor-1a2b3c
  friendly_name: UltimateSensor 1a2b3c

packages:
  smarthomeshop.ultimatesensor: github://smarthomeshop/ultimatesensor/ultimatesensor-v1/ultimatesensor-wifi-complete.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.
  • 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 encryptiesleutel en WiFi gegevens.

Deze modulaire aanpak betekent: ✅ Je krijgt bij elke installatie de nieuwste configuratie van GitHub ✅ Je aanpassingen blijven gescheiden van de basis configuratie ✅ Je hoeft niet de volledige configuratie te kopiëren/plakken

Stap 3: Pas de Configuratie Aan

Na adoptie kun je de YAML configuratie wijzigen:

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

Stap 4: Upload Gewijzigde Firmware

Na het maken van wijzigingen:

  1. Klik op Installeren op je apparaat kaart
  2. Kies Draadloos (aanbevolen) of Sluit aan op deze computer
  3. ESPHome zal je aangepaste firmware compileren en uploaden
  4. Wacht tot het apparaat herstart en opnieuw verbindt

✅ Klaar! Je UltimateSensor draait nu aangepaste firmware.

Geavanceerde Aanpassingen

Voorbeeld 1: Pas CO₂ Sensor Instellingen Aan

Pas het CO₂ meetinterval en de temperatuur offset aan door de bestaande sensor uit te breiden:

sensor:
  - id: !extend scd41
    update_interval: 60s  # Standaard: 30s
    temperature_offset: 4.0  # ESPHome-standaard
    automatic_self_calibration: true  # ESPHome-standaard

Voorbeeld 2: Configureer mmWave Radar Zones

Voor zones heb je geen YAML nodig. Teken polygonzones, uitsluitingszones en tellijnen in de Room Designer van de SmartHomeShop-integratie. Zie de Kalibratiehandleiding.

Voorbeeld 3: Voeg Bluetooth Proxy Toe

Maak van je UltimateSensor een Bluetooth proxy voor andere apparaten:

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

bluetooth_proxy:
  active: true

Voorbeeld 4: Aangepaste Luchtkwaliteit Meldingen

Voeg automatiseringen direct op het apparaat toe:

binary_sensor:
  - platform: template
    name: "Slechte Luchtkwaliteit Waarschuwing"
    lambda: |-
      if (id(scd41_co2).state > 1000 || id(PM_2_5).state > 25) {  // PM_2_5: alleen Complete
        return true;
      }
      return false;

Voorbeeld 5: Pas Omgevingsdruk Aan

Voor verbeterde CO₂ nauwkeurigheid gebaseerd op je hoogte:

# Stel in via een Home Assistant actie:
# Actie: esphome.<jouw_apparaatnaam>_set_ambient_pressure
# Data: { pressure_mbar: 1013 }

# Of stel je hoogte in via YAML:
sensor:
  - id: !extend scd41
    altitude_compensation: 100m

Meer Informatie: Bekijk de ESPHome documentatie voor volledige configuratie referentie.

Modulaire Configuratie Structuur

UltimateSensor firmware gebruikt een modulaire architectuur met herbruikbare pakketten:

ultimatesensor-v1/
├── base.yaml                  # Apparaat, sensoren, display en bediening
├── wifi.yaml                  # WiFi, setup-hotspot en Improv
├── ethernet.yaml              # Ethernet
├── complete.yaml              # SPS30 fijnstofsensor
├── tracking-ld2450.yaml       # LD2450 radar en polygonzones
├── led-lighting.yaml          # Automatische achter-LED
├── firmware-selector.yaml     # Variantkiezer en update-entiteit
├── cloud*.yaml                # Firmware voor de SmartHomeShop-app
├── ultimatesensor-wifi-basic.yaml
├── ultimatesensor-wifi-complete.yaml
├── ultimatesensor-ethernet-basic.yaml
├── ultimatesensor-ethernet-complete.yaml
└── dezelfde vier bestanden eindigend op -cloud.yaml

Dit modulaire ontwerp maakt het gemakkelijk om:

  • Te wisselen tussen WiFi en Ethernet
  • De PM sensor toe te voegen/verwijderen (Basic ↔ Complete)
  • Configuraties te delen tussen apparaten
  • Verbeteringen terug bij te dragen aan de community

Probleemoplossing

Apparaat Wil Niet OTA Updaten

Symptomen: OTA update mislukt of time-out

Oplossingen:

  1. Zorg dat het apparaat is ingeschakeld en verbonden met WiFi/Ethernet
  2. Controleer dat het apparaat sterk netwerksignaal heeft
  3. Verifieer dat ota: is ingeschakeld in je YAML configuratie
  4. Probeer het apparaat te herstarten met de knop Restart UltimateSensor op de apparaatpagina in Home Assistant
  5. Als al het andere faalt, flash via USB-C kabel

Apparaat Niet Ontdekt Na Flashen

Symptomen: UltimateSensor verschijnt niet in Home Assistant na USB flashen

Oplossingen:

  1. Het apparaat heeft mogelijk WiFi gegevens verloren tijdens het flashen
  2. Verbind via USB-C en controleer de logs in ESPHome
  3. Gebruik het captive portal:
    • Apparaat maakt een WiFi hotspot aan genaamd ultimatesensor met wachtwoord ultimatesensor
    • Verbind ermee en configureer WiFi op de instelpagina
  4. Controleer de DHCP client lijst van je router voor het nieuwe apparaat IP

Verkeerde Variant Geflasht

Symptomen: Sensoren ontbreken of werken niet zoals verwacht

Oplossing:

  1. Verifieer dat je de juiste variant voor je hardware hebt geflasht
  2. Controleer of je de PM sensor hebt (Complete) of niet (Basic)
  3. Controleer of je WiFi of Ethernet nodig hebt
  4. Flash de juiste variant met de web flasher

Sensor Metingen Lijken Onnauwkeurig

Oplossingen:

  1. CO₂ sensor: Vereist 1-2 weken automatische zelf-kalibratie voor optimale nauwkeurigheid
  2. Temperatuur: Apparaat genereert interne warmte. Sta 15-30 minuten toe om te stabiliseren na inschakelen
  3. PM sensor (alleen Complete): Reinig de ventilator met perslucht als metingen vast lijken te zitten
  4. mmWave radar: Pas je zones aan in de Room Designer
  5. Zie de Kalibratie Handleiding voor gedetailleerde kalibratie instructies

Compilatie Fouten in ESPHome

Symptomen: Aangepaste YAML compileert niet

Oplossingen:

  1. Controleer op YAML syntax fouten (inspringen moet consistent zijn)
  2. Verifieer dat je ESPHome 2026.10.0 of nieuwer gebruikt, oudere versies weigeren deze firmware
  3. Controleer het 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

Symptomen: Ethernet verbinding mislukt of is instabiel

Oplossingen:

  1. Zorg dat je de Ethernet firmware variant hebt geflasht (niet WiFi)
  2. Verifieer dat je PoE switch voldoende voeding levert (IEEE 802.3af)
  3. Controleer of Ethernet kabel goed is aangesloten aan beide kanten
  4. Test met een bekende goede Ethernet kabel
  5. Controleer of Ethernet poort LED brandt (continu of knipperend)
  6. Zie de Netwerk Configuratie Handleiding voor gedetailleerde probleemoplossing

USB-C Flashen Mislukt

Symptomen: Apparaat niet gedetecteerd of flash mislukt

Oplossingen:

  1. Zorg dat je de LD2450 mmWave sensor hebt verwijderd
  2. Probeer een andere USB-C kabel (sommige zijn alleen voor opladen)
  3. Probeer een andere USB poort
  4. Probeer een andere computer/browser (Chrome/Edge aanbevolen)
  5. Controleer dat geen ander programma de seriële poort gebruikt

Firmware Changelog

Laatste wijzigingen worden aangekondigd naast releases. Belangrijke updates verschijnen hier.

Waar wijzigingen te vinden:

Aanvullende Bronnen

Hulp nodig? Bezoek ons Support Portal of sluit je aan bij onze Discord community!