Smart Home & IoT KI-gestützt erstellt · redaktionell geprüft

Briefkastenmelder mit Zigbee selbst bauen: ESP32-C5, Home Assistant, Firmware und Code-Review

2026-11-22 · 22 Min. Lesezeit · Benjamin Kaulfuss
Briefkastenmelder mit Zigbee selbst bauen: ESP32-C5, Home Assistant, Firmware und Code-Review

Ist die Post schon da? Wer einen Briefkasten an der Straße oder im Hausflur hat, läuft oft umsonst. Und wer Päckchen erwartet, möchte sie abholen, bevor es jemand anderes tut. In diesem Projekt baust du einen Briefkastenmelder, der Einwürfe und das Öffnen der Klappe erkennt und per Zigbee an Home Assistant meldet. Das Herzstück ist ein winziges Board mit ESP32-C5, dazu kommen zwei Sensoren für zusammen wenige Euro.

Projektübersicht

  • Zeitaufwand: 1 bis 2 Stunden
  • Kosten: rund 25 bis 35 Euro ohne Zigbee-Koordinator
  • Schwierigkeit: Einsteiger mit Lötkolben
  • Board: Seeed Studio XIAO ESP32-C5
  • Sensoren: BH1750 (Licht), SW-420 (Vibration)
  • Funk: Zigbee 3.0 zu Home Assistant

Vorab zur Einordnung: Die Firmware in diesem Beitrag haben wir neu geschrieben und an den offiziellen Beispielen der Zigbee-Bibliothek von Espressif ausgerichtet. Sie lässt sich mit dem ESP32-Paket 4.0.0 für das XIAO ESP32-C5 fehlerfrei und ohne Warnungen kompilieren. Auf echter Hardware im Briefkasten durchgetestet ist sie zum Zeitpunkt der Veröffentlichung noch nicht. Rechne also damit, an der einen oder anderen Stelle nachzujustieren, und schreib uns, wenn dir etwas auffällt.

Funktionsprinzip: Vibrations- und Lichterkennung

Zwei einfache Sensoren ergänzen sich:

  • Der Vibrationssensor SW-420 spürt die Erschütterung, wenn ein Brief oder Päckchen in den Kasten fällt oder die Klappe zuschlägt.
  • Der Lichtsensor BH1750 misst die Helligkeit im Inneren. Im geschlossenen Kasten ist es dunkel. Sobald jemand die Entnahmeklappe öffnet, fällt Licht hinein.

Aus der Kombination liest Home Assistant ab, was passiert ist:

EreignisVibrationLichtBedeutung
Einwurfjakurz oder gar nichtPost ist da
Klappe geöffnetmeist jadeutlich und längerJemand entnimmt die Post
Lkw fährt vorbeimöglichneinFehlalarm, über die Empfindlichkeit abstellen

Nachts funktioniert die Lichterkennung nur, wenn eine Laterne oder das Flurlicht in den Kasten scheint. Die Vibration meldet sich in jedem Fall.

Zigbee als Funkprotokoll: Mesh, Reichweite, Verschlüsselung

Zigbee ist ein Funkstandard für das Smart Home, gemacht für kleine Datenmengen und sparsame Geräte. Für einen Sensor, der nur gelegentlich ein paar Bytes meldet, bringt er drei Vorteile mit:

  • Mesh-Netz: Geräte am Stromnetz wie Lampen oder Zwischenstecker reichen Nachrichten weiter. Der Briefkasten muss also nicht bis zur Zentrale funken, sondern nur bis zur nächsten Zigbee-Lampe im Flur. Fällt ein Gerät aus, suchen sich die anderen selbst einen neuen Weg.
  • Reichweite: Bei freier Sicht sind bis zu 100 Meter möglich, durch Wände und Decken meist 10 bis 20 Meter. Jedes weitere Gerät am Stromnetz verlängert das Netz.
  • Verschlüsselung: Zigbee 3.0 verschlüsselt mit AES-128, und das lässt sich nicht abschalten.

Geräte mit Akku wie unser Melder sind sogenannte End Devices. Sie senden und empfangen, leiten aber nichts für andere weiter.

Physical Layer: DSSS nach IEEE 802.15.4

Zigbee funkt im 2,4-GHz-Band auf den Kanälen 11 bis 26 mit 250 Kilobit pro Sekunde. Dass die Übertragung trotz WLAN und Bluetooth in der Nachbarschaft zuverlässig klappt, liegt an einem Verfahren namens Direct Sequence Spread Spectrum, kurz DSSS.

Die Idee dahinter: Statt jedes Bit einzeln zu senden, zerlegt der Sender die Daten in Häppchen zu je vier Bit. Vier Bit können 16 verschiedene Werte annehmen. Für jeden dieser 16 Werte ist im Standard ein festes Muster aus 32 Zeichen hinterlegt, die sogenannten Chips. Gesendet wird nicht der Wert selbst, sondern sein Muster. Aus vier Bit werden so 32.

Das klingt nach Verschwendung, macht die Sache aber robust. Der Empfänger kennt alle 16 Muster. Kommen unterwegs ein paar Chips verfälscht an, vergleicht er das Empfangene mit den 16 Möglichkeiten und nimmt die ähnlichste. Einzelne Störungen verschwinden damit einfach. Zusätzlich hängt an jedem Datenpaket eine Prüfsumme aus zwei Byte. Passt sie nicht, verwirft der Empfänger das Paket, die Bestätigung bleibt aus, und der Sender schickt es noch einmal.

Hardware

ESP32-Varianten mit IEEE 802.15.4

Zigbee setzt einen Funkteil nach IEEE 802.15.4 voraus. Den haben nur drei Familien. Der klassische ESP32, der ESP32-S3 und der ESP32-C3 beherrschen nur WLAN und Bluetooth und scheiden aus.

ChipZigbeeWLANEinordnung
ESP32-H2jakeinesam sparsamsten, nur Zigbee, Thread und Bluetooth LE
ESP32-C6ja2,4 GHz, Wi-Fi 6bewährter Allrounder
ESP32-C5ja2,4 und 5 GHz, Wi-Fi 6neuester Chip, Dualband

Board-Empfehlung: Seeed Studio XIAO ESP32-C5

Seeed Studio XIAO ESP32-C5 von oben mit USB-C-Buchse, Antennenanschluss und den Tastern Reset und Boot

Das XIAO ESP32-C5 ist kaum größer als eine Briefmarke und bringt alles mit, was ein Sensor im Briefkasten braucht:

MerkmalXIAO ESP32-C5
ProzessorESP32-C5, RISC-V mit 240 MHz
Speicher8 MB Flash, 8 MB PSRAM
FunkZigbee, WLAN mit 2,4 und 5 GHz, Bluetooth 5 LE
Antenneexterne Antenne am U.FL-Anschluss, liegt bei
StromversorgungUSB-C oder LiPo-Akku mit 3,7 V
AkkuLadeschaltung und Spannungsmessung eingebaut
Anschlüsse11 nutzbare Pins, I2C, SPI, UART
Maße21 x 17,8 mm

Drei Dinge machen das Board für dieses Projekt besonders passend. Die Ladeschaltung erspart ein eigenes Lademodul. Die eingebaute Spannungsmessung meldet den Akkustand an Home Assistant. Und die externe Antenne lässt sich aus einem Metallbriefkasten herausführen, der Funkwellen sonst kräftig dämpft.

Hardware-Empfehlung · Amazon-Partnerlink
Seeed Studio XIAO ESP32-C5

Achte darauf, dass die Antenne im Lieferumfang ist.

Bei Amazon ansehen

Preis & Verfügbarkeit auf Amazon prüfen. Als Amazon-Partner verdienen wir an qualifizierten Käufen. Für dich entstehen dadurch keine Mehrkosten. Alternativ gibt es das Board direkt bei Seeed Studio.

Stückliste

TeilAufgabePreis ca.
XIAO ESP32-C5Rechnet und funkt8 bis 12 Euro
BH1750 auf PlatineMisst die Helligkeit3 bis 5 Euro
SW-420 auf PlatineErkennt Erschütterungen2 bis 4 Euro
LiPo-Akku 3,7 V mit SchutzschaltungStromversorgung ohne Kabel6 bis 10 Euro
Litze, Schrumpfschlauch, GehäuseAufbau und Schutzwenige Euro
Zigbee-KoordinatorEmpfänger an Home AssistantUSB-Stick ab 20 Euro, unsere Empfehlung rund 80 Euro

Als Koordinator empfehlen wir den SMLIGHT SLZB-06P7. Er hängt nicht per USB am Server, sondern wird per Netzwerkkabel angeschlossen und über PoE gleich mit Strom versorgt. Dadurch kannst du ihn dort montieren, wo das Zigbee-Netz ihn braucht, zum Beispiel im Flur nahe der Haustür statt im Technikraum. USB und WLAN beherrscht er zusätzlich, und er arbeitet mit ZHA ebenso wie mit Zigbee2MQTT. Wer es günstiger mag, nimmt einen einfachen USB-Stick: Das Home-Assistant-Projekt empfiehlt den hauseigenen Home Assistant Connect ZBT-2, verbreitet sind auch die Sonoff-Sticks der Reihe Zigbee 3.0 USB Dongle Plus.

Werbung · Amazon-Partnerlink
BH1750 Lichtsensor und SW-420 Vibrationssensor
Bei Amazon ansehen

Preis & Verfügbarkeit auf Amazon prüfen. Als Amazon-Partner verdienen wir an qualifizierten Käufen. Für dich entstehen dadurch keine Mehrkosten.

SMLIGHT SLZB-06P7 Zigbee-Koordinator
Unsere Empfehlung · Amazon-Partnerlink
SMLIGHT SLZB-06P7, Zigbee-Koordinator mit LAN und PoE
Bei Amazon ansehen

Preis & Verfügbarkeit auf Amazon prüfen. Als Amazon-Partner verdienen wir an qualifizierten Käufen. Für dich entstehen dadurch keine Mehrkosten.

Schaltung und Pinbelegung

Verdrahtungsplan: BH1750 an 3V3, GND, D4 und D5 des XIAO ESP32-C5, SW-420 an 3V3, GND und D0, LiPo-Akku an den Lötpunkten BAT auf der Rückseite
SensorPin am SensorPin am XIAO ESP32-C5
BH1750VCC3V3
BH1750GNDGND
BH1750SDAD4, das ist GPIO23
BH1750SCLD5, das ist GPIO24
BH1750ADDRbleibt frei
SW-420VCC3V3
SW-420GNDGND
SW-420DOD0, das ist GPIO1
LiPo-AkkuPlus und MinusLötpunkte BAT auf der Rückseite

D4 und D5 sind beim XIAO die vorgesehenen Pins für den I2C-Bus. Der Pin D0 ist bewusst gewählt: Er kann das Board später auch aus dem Deep Sleep wecken. Den Anschluss ADDR am BH1750 brauchst du nur, wenn zwei Lichtsensoren am selben Bus hängen sollen.

Pinbelegung des Seeed Studio XIAO ESP32-C5 von oben mit den Bezeichnungen D0 bis D10, GPIO-Nummern und Funktionen Anschluss eines LiPo-Akkus an die Lötpunkte BAT auf der Rückseite des XIAO ESP32-C5

Beim Akku gilt besondere Sorgfalt. Achte auf die Polung und darauf, dass sich Plus und Minus beim Löten nie berühren. Nimm einen Akku mit eingebauter Schutzschaltung.

To-do-Liste: Aufbau in neun Schritten

  1. Teile besorgen und prüfen, ob in Home Assistant bereits ein Zigbee-Koordinator läuft.
  2. Arduino IDE einrichten: Board-Paket für den ESP32 und die Bibliothek für den BH1750 installieren.
  3. Sensoren fliegend verdrahten, am besten zuerst auf einem Steckbrett.
  4. Firmware übertragen und im seriellen Monitor prüfen, ob der Lichtsensor gefunden wird.
  5. In Home Assistant anlernen und kontrollieren, ob Vibration, Helligkeit und Akku erscheinen.
  6. Empfindlichkeit einstellen: das Poti am SW-420 und den Lichtschwellwert in der Firmware.
  7. Verlöten und einhausen, Akku anschließen.
  8. Im Briefkasten montieren und die Funkverbindung vor Ort testen.
  9. Automationen anlegen: Benachrichtigung, Helfer und Rücksetzen.

Toolchain: Arduino IDE und ESP32-Core

Wir verwenden die Arduino IDE, weil Seeed die nötigen Einstellungen für Zigbee dort dokumentiert.

  1. Im Boardverwalter nach esp32 suchen und das Paket von Espressif installieren. Seeed nennt Version 3.3.5 als Minimum, wir haben mit 4.0.0 kompiliert.
  2. Unter Werkzeuge das Board XIAO_ESP32C5 wählen.
  3. Unter Werkzeuge bei Zigbee Mode den Eintrag Zigbee ED (End Device) wählen.
  4. Unter Werkzeuge bei Partition Scheme den Eintrag Zigbee 8MB with spiffs wählen.
  5. In der Bibliotheksverwaltung die Bibliothek BH1750 von Christopher Laws installieren.

Die beiden Zigbee-Einstellungen sind entscheidend. Ohne sie bricht das Kompilieren mit einer Fehlermeldung ab, die unser Code absichtlich auslöst.

Wer lieber mit PlatformIO arbeitet: Seeed stellt eine eigene Plattform für das Board bereit. Wie dort die Zigbee-Partition gesetzt wird, dokumentiert der Hersteller bislang nicht. Für den Einstieg ist die Arduino IDE deshalb der sichere Weg.

Firmware

Hier ist der vollständige Sketch. Darunter gehen wir die wichtigen Stellen durch.

/*
 * Briefkastenmelder mit Zigbee
 * Board:   Seeed Studio XIAO ESP32-C5
 * Sensoren: BH1750 (Licht, I2C) und SW-420 (Vibration)
 *
 * Arduino IDE: Werkzeuge > Zigbee Mode > "Zigbee ED (End Device)"
 *              Werkzeuge > Partition Scheme > "Zigbee 8MB with spiffs"
 */
#include <Arduino.h>
#include <Wire.h>
#include <BH1750.h>
#include "Zigbee.h"

#ifndef ZIGBEE_MODE_ED
#error "Bitte unter Werkzeuge > Zigbee Mode den Eintrag 'Zigbee ED (End Device)' waehlen."
#endif

// ---------- Anschluesse ----------
// SDA (D4), SCL (D5), LED_BUILTIN, BAT_VOLT_PIN und BAT_VOLT_PIN_EN
// kennt das Board-Paket bereits.
const uint8_t PIN_VIBRATION = D0;        // SW-420, Ausgang DO
const uint8_t PIN_TASTER    = BOOT_PIN;  // Taster "B" auf dem Board

// Die gelbe LED des Boards leuchtet bei LOW. Leuchtet sie bei dir
// verkehrt herum, tausche die beiden Werte.
const uint8_t LED_AN  = LOW;
const uint8_t LED_AUS = HIGH;

// ---------- Verhalten ----------
const uint8_t  VIBRATION_PEGEL        = HIGH;   // Pegel des SW-420 bei Erschuetterung
const uint32_t VIBRATION_HALTEZEIT_MS = 5000;   // so lange bleibt "Vibration" gesetzt
const uint32_t LICHT_INTERVALL_MS     = 2000;   // Abstand der Lichtmessungen
const float    KLAPPE_OFFEN_LUX       = 15.0f;  // ab hier gilt die Klappe als offen
const uint16_t LICHT_MINDESTAENDERUNG = 3000;   // Zigbee-Rohwert, entspricht etwa Faktor 2
const uint32_t AKKU_INTERVALL_MS      = 10UL * 60UL * 1000UL;
const uint32_t NETZ_WARTEZEIT_MS      = 60000;  // danach Neustart und neuer Versuch
const uint32_t ANMELDE_WARTEZEIT_MS   = 15000;
const uint8_t  ZIGBEE_KANAL           = 0;      // 0 = alle Kanaele, sonst 11 bis 26

// ---------- Zigbee-Endpunkte ----------
ZigbeeVibrationSensor   zbVibration(10);
ZigbeeIlluminanceSensor zbLicht(11);

BH1750 lichtmesser;

// ---------- Zustand ----------
volatile bool vibrationGemeldet = false;  // wird im Interrupt gesetzt
bool     vibrationAktiv     = false;
bool     lichtsensorBereit  = false;
bool     klappeOffen        = false;
int32_t  letzterLichtwert   = -1;         // -1 = noch nichts gesendet
uint32_t letzteVibration    = 0;
uint32_t letzteLichtmessung = 0;
uint32_t letzteAkkumessung  = 0;

// Der Interrupt merkt sich nur, DASS etwas passiert ist.
// Gefunkt wird spaeter in loop().
void IRAM_ATTR beiVibration() {
  vibrationGemeldet = true;
}

void neustart(const char *grund) {
  Serial.println(grund);
  Serial.println("Neustart in 2 Sekunden");
  delay(2000);
  ESP.restart();
}

// Zigbee uebertraegt Helligkeit als 10000 * log10(Lux) + 1.
uint16_t luxZuZigbee(float lux) {
  if (lux < 1.0f) {
    return 0;  // dunkler als 1 Lux: unterhalb des Messbereichs
  }
  float roh = 10000.0f * log10f(lux) + 1.0f;
  return (uint16_t)constrain(roh, 1.0f, 50000.0f);
}

// Akkuspannung ueber den eingebauten Spannungsteiler (1:2) messen.
uint16_t akkuMillivolt() {
  digitalWrite(BAT_VOLT_PIN_EN, HIGH);
  delay(10);
  uint32_t summe = 0;
  for (int i = 0; i < 16; i++) {
    summe += analogReadMilliVolts(BAT_VOLT_PIN);
  }
  digitalWrite(BAT_VOLT_PIN_EN, LOW);
  return (uint16_t)((summe / 16) * 2);
}

// Einfache Naeherung: 3,3 V = leer, 4,2 V = voll.
uint8_t akkuProzent(uint16_t millivolt) {
  long prozent = map(millivolt, 3300, 4200, 0, 100);
  return (uint8_t)constrain(prozent, 0L, 100L);
}

void akkuMelden() {
  uint16_t mv = akkuMillivolt();
  zbLicht.setBatteryVoltage((uint8_t)(mv / 100));  // Einheit: 100 mV
  zbLicht.setBatteryPercentage(akkuProzent(mv));
  zbLicht.reportBatteryPercentage();
  Serial.printf("Akku: %u mV\n", mv);
}

void lichtMessen() {
  lichtmesser.configure(BH1750::ONE_TIME_HIGH_RES_MODE);
  uint32_t start = millis();
  while (!lichtmesser.measurementReady(true)) {
    if (millis() - start > 500) {
      Serial.println("Licht: Sensor antwortet nicht");
      return;
    }
    delay(10);
  }
  float lux = lichtmesser.readLightLevel();
  if (lux < 0) {
    Serial.println("Licht: Messfehler");
    return;
  }

  uint16_t roh   = luxZuZigbee(lux);
  bool     offen = lux >= KLAPPE_OFFEN_LUX;
  bool zustandGewechselt = (offen != klappeOffen);
  bool deutlichAnders    = (letzterLichtwert < 0) ||
                           (abs((int32_t)roh - letzterLichtwert) >= LICHT_MINDESTAENDERUNG);

  if (zustandGewechselt || deutlichAnders) {
    klappeOffen      = offen;
    letzterLichtwert = roh;
    zbLicht.setIlluminance(roh);
    zbLicht.report();
    Serial.printf("Licht: %.1f Lux gesendet, Klappe %s\n", lux, offen ? "offen" : "zu");
  }
}

// Taster 3 Sekunden halten: Zigbee-Daten loeschen und neu anlernen.
void tasterPruefen() {
  if (digitalRead(PIN_TASTER) != LOW) {
    return;
  }
  uint32_t start = millis();
  while (digitalRead(PIN_TASTER) == LOW) {
    delay(50);
    if (millis() - start > 3000) {
      Serial.println("Werkseinstellungen, Geraet startet neu");
      delay(500);
      Zigbee.factoryReset();
    }
  }
}

void setup() {
  Serial.begin(115200);

  pinMode(LED_BUILTIN, OUTPUT);
  digitalWrite(LED_BUILTIN, LED_AUS);
  pinMode(PIN_TASTER, INPUT_PULLUP);
  pinMode(PIN_VIBRATION, INPUT);
  pinMode(BAT_VOLT_PIN_EN, OUTPUT);
  digitalWrite(BAT_VOLT_PIN_EN, LOW);

  Wire.begin(SDA, SCL);
  lichtsensorBereit = lichtmesser.begin(BH1750::ONE_TIME_HIGH_RES_MODE);
  if (!lichtsensorBereit) {
    Serial.println("BH1750 nicht gefunden, bitte Verkabelung pruefen");
  }

  // Der Kanal muss VOR Zigbee.role() gesetzt werden.
  if (ZIGBEE_KANAL >= 11 && ZIGBEE_KANAL <= 26) {
    Zigbee.setPrimaryChannelMask(1UL << ZIGBEE_KANAL);
  }
  if (!Zigbee.role(ZIGBEE_END_DEVICE)) {
    neustart("Zigbee liess sich nicht einrichten");
  }

  zbVibration.setManufacturerAndModel("KC-NetFox", "Briefkastenmelder");
  zbLicht.setManufacturerAndModel("KC-NetFox", "Briefkastenmelder");
  zbLicht.setPowerSource(ZB_POWER_SOURCE_BATTERY, 100, 40);
  zbLicht.setMinMaxValue(0, 50000);
  zbLicht.setTolerance(1);

  Zigbee.addEndpoint(&zbVibration);
  Zigbee.addEndpoint(&zbLicht);

  if (!Zigbee.begin()) {
    neustart("Zigbee liess sich nicht starten");
  }

  // Auf das Netz warten, die LED blinkt dabei.
  Serial.println("Suche Zigbee-Netz");
  uint32_t start = millis();
  while (!Zigbee.connected()) {
    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
    delay(250);
    tasterPruefen();
    if (millis() - start > NETZ_WARTEZEIT_MS) {
      neustart("Kein Zigbee-Netz gefunden");
    }
  }
  digitalWrite(LED_BUILTIN, LED_AUS);
  Serial.println("Mit dem Zigbee-Netz verbunden");

  // Der Vibrationssensor ist eine IAS-Zone und muss sich anmelden.
  if (zbVibration.restoreIASZoneEnroll()) {
    Serial.println("IAS-Anmeldung wiederhergestellt");
  } else {
    Serial.println("IAS-Anmeldung wird angefragt");
    zbVibration.requestIASZoneEnroll();
  }
  start = millis();
  while (!zbVibration.enrolled() && millis() - start < ANMELDE_WARTEZEIT_MS) {
    delay(100);
  }
  if (!zbVibration.enrolled()) {
    Serial.println("IAS-Anmeldung fehlgeschlagen, Vibration evtl. nicht sichtbar");
  }

  // Helligkeit zusaetzlich mindestens einmal pro Stunde melden.
  zbLicht.setReporting(5, 3600, 2000);
  zbVibration.setVibration(false);
  akkuMelden();
  letzteAkkumessung = millis();

  attachInterrupt(digitalPinToInterrupt(PIN_VIBRATION), beiVibration,
                  VIBRATION_PEGEL == HIGH ? RISING : FALLING);
}

void loop() {
  const uint32_t jetzt = millis();

  // ----- Vibration -----
  if (vibrationGemeldet) {
    vibrationGemeldet = false;
    letzteVibration   = jetzt;
    if (!vibrationAktiv) {
      vibrationAktiv = true;
      zbVibration.setVibration(true);
      digitalWrite(LED_BUILTIN, LED_AN);
      Serial.println("Vibration erkannt und gesendet");
    }
  }
  if (vibrationAktiv && jetzt - letzteVibration >= VIBRATION_HALTEZEIT_MS) {
    vibrationAktiv = false;
    zbVibration.setVibration(false);
    digitalWrite(LED_BUILTIN, LED_AUS);
    Serial.println("Vibration beendet");
  }

  // ----- Licht -----
  if (lichtsensorBereit && jetzt - letzteLichtmessung >= LICHT_INTERVALL_MS) {
    letzteLichtmessung = jetzt;
    lichtMessen();
  }

  // ----- Akku -----
  if (jetzt - letzteAkkumessung >= AKKU_INTERVALL_MS) {
    letzteAkkumessung = jetzt;
    akkuMelden();
  }

  tasterPruefen();
  delay(20);
}

Sketch herunterladen

Konfigurationsparameter

Alles, was du anpassen möchtest, steht oben im Abschnitt Verhalten:

EinstellungBedeutungStartwert
Pegel bei ErschütterungManche Module melden mit HIGH, andere mit LOWHIGH
Haltezeit der VibrationSo lange zeigt Home Assistant die Erschütterung an5 Sekunden
Abstand der LichtmessungWie oft die Helligkeit geprüft wird2 Sekunden
Schwelle Klappe offenAb dieser Helligkeit gilt der Kasten als geöffnet15 Lux
MindeständerungErst ab dieser Änderung wird neu gesendetetwa Faktor 2
Zigbee-Kanal0 sucht alle Kanäle ab, sonst 11 bis 260

Zigbee-Endpoints: IAS Zone und Illuminance Measurement

Ein Zigbee-Gerät kann mehrere Funktionen anbieten, jede auf einem eigenen Endpoint. Unser Melder hat zwei: einen Vibrationssensor auf Endpoint 10 und einen Helligkeitssensor auf Endpoint 11. Die Nummern sind frei wählbar, sie müssen sich nur unterscheiden. Home Assistant legt daraus automatisch die passenden Entitäten an.

Vibrationserkennung per GPIO-Interrupt

Der SW-420 meldet eine Erschütterung nur für Sekundenbruchteile. Würde das Programm den Pin nur gelegentlich abfragen, ginge der Impuls leicht verloren. Deshalb löst der Pin einen Interrupt aus. Die zugehörige Funktion setzt nur ein Flag und kehrt sofort zurück. Gefunkt wird erst in loop(). In einer Interrupt-Funktion haben längere Aktionen wie Funken oder Ausgaben nichts zu suchen.

IAS Zone Enrollment

Vibrationssensoren gehören bei Zigbee zu den Sicherheitsgeräten, den IAS Zones. Ein solches Gerät muss sich nach dem Beitritt zum Netz zusätzlich bei der Zentrale anmelden. Die Bibliothek merkt sich diese Anmeldung dauerhaft. Beim Start versucht der Sketch deshalb zuerst, eine vorhandene Anmeldung wiederherzustellen, und fragt nur dann neu an, wenn es keine gibt. Scheitert die Anmeldung, läuft das Programm weiter und meldet das Problem im seriellen Monitor.

Umrechnung von Lux in den ZCL-Messwert

Lux ist die Einheit der Beleuchtungsstärke. Eine Vollmondnacht bringt rund 0,2 Lux, ein Wohnzimmer 100 bis 300, ein Büroarbeitsplatz 500 und pralle Mittagssonne bis zu 100.000 Lux. Diese riesige Spanne überträgt Zigbee nicht direkt, sondern gestaucht über einen Logarithmus:

Zigbee-Wert = 10000 x log10(Lux) + 1

Aus 1 Lux wird so der Wert 1, aus 100 Lux 20.001 und aus 100.000 Lux 50.001. Home Assistant rechnet für die Anzeige wieder zurück. Die Funktion im Sketch fängt außerdem den Fall ab, dass es dunkler als 1 Lux ist. Der Logarithmus würde dort negative Werte liefern.

Reporting: Schwellwerte und Intervalle

Die Helligkeit wird alle zwei Sekunden gemessen, aber nicht jedes Mal gesendet. Gefunkt wird in zwei Fällen: wenn die Schwelle für die offene Klappe über- oder unterschritten wird, und wenn sich die Helligkeit etwa verdoppelt oder halbiert hat. Das hält das Zigbee-Netz ruhig. Zusätzlich meldet sich der Sensor mindestens einmal pro Stunde, damit Home Assistant merkt, dass er noch lebt.

Code-Review: zehn Prüfpunkte

Ein Sensor, der wochenlang unbeaufsichtigt läuft, verzeiht keine Nachlässigkeit. Diese Punkte haben wir beim Schreiben geprüft. Sie sind auch eine gute Liste für eigene Zigbee-Projekte.

Nr.PrüfpunktUmsetzung im Sketch
1Zeitrechnung ohne ÜberlaufZeitstempel sind vorzeichenlose 32-Bit-Zahlen. Mit einem normalen int würde die Rechnung nach knapp 25 Tagen negativ und der Sensor verstummen.
2Flag aus dem InterruptDie Variable ist als volatile markiert. Sonst darf der Compiler die Abfrage in loop() wegoptimieren.
3Kurze Interrupt-FunktionSie setzt nur das Flag. Kein Funk, keine Ausgabe, keine Wartezeit.
4Reihenfolge beim StartDer Kanal wird vor der Rollenwahl gesetzt, die Endpoints vor dem Start des Funkteils. So verlangt es die Bibliothek.
5Keine EndlosschleifenFindet das Board 60 Sekunden lang kein Netz, startet es neu, statt für immer zu blinken.
6Ehrliche StromquelleDas Gerät meldet sich als akkubetrieben und überträgt Spannung und Füllstand. Wer es als netzbetrieben anmeldet, sieht keinen Akkustand.
7Fehler der Sensoren abfangenFehlt der Lichtsensor oder liefert er einen Messfehler, läuft die Vibrationserkennung trotzdem weiter.
8Rechenfehler vermeidenWerte unter 1 Lux und über dem Messbereich werden begrenzt, bevor sie gesendet werden.
9Funkverkehr begrenzenGesendet wird bei Ereignissen und deutlichen Änderungen, nicht bei jeder Messung.
10Zurücksetzen ohne RechnerDrei Sekunden auf den Taster B löschen die Zigbee-Daten. Das Gerät lässt sich danach neu anlernen.

Was der Sketch bewusst noch nicht macht: schlafen. Dazu mehr im Abschnitt zur Stromversorgung.

Einbindung in Home Assistant

Dashboard von Home Assistant mit Karten für Räume, Sensoren und Geräte

Zigbee-Koordinator einrichten

Home Assistant bringt mit Zigbee Home Automation, kurz ZHA, eine eigene Zigbee-Zentrale mit. Einen Koordinator mit Netzwerkanschluss wie den SLZB-06P7 verbindest du per LAN-Kabel mit deinem Netz und richtest ihn nach der Anleitung des Herstellers in ZHA ein. Einen USB-Stick steckst du an den Server, am besten über ein kurzes USB-Verlängerungskabel und nicht direkt neben einen USB-3.0-Anschluss. Beides verringert Störungen. In der Regel erkennt Home Assistant den Koordinator selbst und bietet ihn unter Einstellungen bei Geräte & Dienste zum Einrichten an. Die vorgeschlagenen Werte kannst du übernehmen.

Pairing des Melders in ZHA

  1. In Home Assistant die Zigbee-Verwaltung öffnen und Gerät hinzufügen wählen. Je nach Version liegt sie unter Einstellungen im Bereich Konnektivität oder bei Geräte & Dienste in der ZHA-Integration.
  2. Den Melder mit Strom versorgen. Die LED blinkt, solange er ein Netz sucht.
  3. Nach kurzer Zeit erscheint das Gerät mit dem Namen Briefkastenmelder. Vergib einen Bereich, zum Beispiel Eingang.

Danach findest du drei Entitäten: einen binären Sensor für die Vibration, einen Sensor für die Helligkeit in Lux und den Akkustand. Taucht das Gerät nicht auf, halte den Taster B drei Sekunden gedrückt und starte die Suche erneut.

Home Assistant: Dialog zum Ändern des Zigbee-Kanals in den Netzwerkinformationen von ZHA

Ein Wort zum Funkkanal: Home Assistant rät, den voreingestellten Zigbee-Kanal nicht ohne Not zu ändern. Stört das WLAN, ist es meist besser, dem WLAN-Router einen festen Kanal zuzuweisen.

Automation 1: Benachrichtigung beim Einwurf

Lege unter Einstellungen bei Geräte & Dienste im Reiter Helfer einen Schalter mit dem Namen Post im Briefkasten an. Die folgende Automation setzt ihn bei einer Erschütterung und schickt eine Nachricht aufs Handy. Die Namen der Entitäten passt du an deine Installation an.

alias: Briefkasten - Post eingeworfen
triggers:
  - trigger: state
    entity_id: binary_sensor.briefkastenmelder_vibration
    to: "on"
conditions:
  - condition: state
    entity_id: input_boolean.post_im_briefkasten
    state: "off"
actions:
  - action: input_boolean.turn_on
    target:
      entity_id: input_boolean.post_im_briefkasten
  - action: notify.mobile_app_dein_handy
    data:
      title: Briefkasten
      message: Es wurde etwas eingeworfen.
mode: single

Automation 2: Zurücksetzen bei der Entnahme

Bleibt es im Kasten länger als fünf Sekunden hell, hat jemand die Klappe geöffnet. Dann wird der Helfer wieder ausgeschaltet.

alias: Briefkasten - geleert
triggers:
  - trigger: numeric_state
    entity_id: sensor.briefkastenmelder_helligkeit
    above: 15
    for: "00:00:05"
conditions:
  - condition: state
    entity_id: input_boolean.post_im_briefkasten
    state: "on"
actions:
  - action: input_boolean.turn_off
    target:
      entity_id: input_boolean.post_im_briefkasten
mode: single

Wer mag, legt noch eine dritte Automation an: Wird der Kasten geöffnet, während niemand zu Hause ist, kommt eine Warnung aufs Handy. Das ist die einfache Antwort auf Langfinger am Briefkasten.

Montage und HF-Aspekte im Briefkasten

  • Antenne nach außen: Ein Metallbriefkasten schirmt Funk stark ab. Führe die mitgelieferte Antenne durch eine vorhandene Öffnung oder klebe sie an ein Sichtfenster aus Kunststoff.
  • Lichtsensor zur Klappe: Der BH1750 soll dorthin zeigen, wo beim Öffnen Licht einfällt, nicht auf den Einwurfschlitz.
  • Vibrationssensor fest verbinden: Klebe den SW-420 direkt an die Wand oder den Boden des Kastens. Lose baumelnd erkennt er wenig.
  • Empfindlichkeit vor Ort einstellen: Drehe am Poti, bis ein eingeworfener Brief auslöst, ein vorbeifahrendes Auto aber nicht.
  • Vor Feuchtigkeit schützen: In Briefkästen bildet sich Kondenswasser. Ein kleines Gehäuse mit einer Öffnung für den Lichtsensor schützt die Elektronik.
  • Nichts verdecken: Die Elektronik gehört an die Seitenwand oder unter den Deckel, damit die Post frei fallen kann.

Passendes Gehäuse drucken lassen

Für den Melder fehlt noch ein Gehäuse oder eine Halterung? Über unseren 3D-Druck-Service lädst du dein Modell als STL oder 3MF hoch und siehst sofort den Festpreis. Für den Außeneinsatz eignet sich PETG. Gedruckt wird bei uns im Taunus, geliefert per Versand oder zur Abholung in Neu-Anspach.

Preis berechnen Mehr zum 3D-Druck

Stromversorgung und Akkulaufzeit

Hier ist Ehrlichkeit angebracht. Der Sketch oben hält das Board dauerhaft wach. Er misst alle zwei Sekunden und hat das Funkteil ständig an. Das ist ideal zum Entwickeln und für den Betrieb an einem USB-Netzteil. Am Akku hält diese Fassung aber nur Tage, nicht Monate.

Daraus ergeben sich drei Wege:

  1. Dauerstrom: Gibt es am Briefkasten eine Steckdose oder eine Klingelleitung mit passendem Netzteil, ist das die sorgenfreie Lösung.
  2. Akku mit regelmäßigem Laden: Für einen Briefkasten im Hausflur reicht ein größerer Akku, den du alle paar Tage per USB-C nachlädst.
  3. Deep Sleep: Für echten Akkubetrieb muss das Board schlafen und nur bei einem Ereignis aufwachen.

Für den dritten Weg ist die Hardware schon vorbereitet. Der Vibrationssensor hängt an D0, und dieser Pin kann das Board aus dem Deep Sleep wecken. Der Ablauf sieht dann so aus: Das Board schläft, eine Erschütterung weckt es, es verbindet sich neu mit dem Zigbee-Netz, meldet Vibration und Helligkeit und schläft wieder ein. Ein Timer weckt es zusätzlich einmal pro Stunde für einen Heartbeat. Espressif liefert dafür mit der Bibliothek ein Beispiel für ein Sleepy End Device mit, das als Vorlage dient. Der Preis dieser Lösung: Das reine Öffnen der Klappe ohne Erschütterung bemerkt ein schlafendes Board nicht, und jede Meldung braucht nach dem Aufwachen ein paar Sekunden.

Noch zwei Hinweise zum Akku im Freien. Lithium-Akkus dürfen bei Frost nicht geladen werden, nimm den Melder zum Laden also mit ins Haus. Und bei Kälte sinkt die nutzbare Kapazität spürbar.

Troubleshooting

ProblemMögliche UrsacheLösung
Kompilieren bricht mit Hinweis auf Zigbee Mode abZigbee-Modus nicht gewähltUnter Werkzeuge Zigbee ED und die Zigbee-Partition wählen
Lichtsensor wird nicht gefundenSDA und SCL vertauscht oder kalte LötstelleVerdrahtung an D4 und D5 prüfen
LED blinkt dauerhaftKein Netz in Reichweite oder Anlernen nicht aktivNäher an ein Zigbee-Gerät gehen, Suche in Home Assistant starten
Gerät erscheint nicht erneutAlte Netzdaten gespeichertTaster B drei Sekunden halten
Vibration erscheint nicht in Home AssistantAnmeldung als IAS Zone fehlgeschlagenZurücksetzen und in der Nähe des Koordinators neu anlernen
Vibration löst ständig ausPoti zu empfindlich oder Pegel vertauschtPoti drehen, sonst den Pegel im Sketch auf LOW stellen
Im Briefkasten bricht die Verbindung abMetallgehäuse schirmt abAntenne nach außen führen, Zigbee-Zwischenstecker in der Nähe einsetzen

Fazit

Für rund 30 Euro und einen Nachmittag Arbeit weiß dein Smart Home, wann die Post da ist und wann jemand den Kasten öffnet. Das Projekt zeigt nebenbei, wie gut sich die neuen ESP32-Chips mit Zigbee für eigene Sensoren eignen: kein WLAN-Passwort im Gerät, kein eigener Server, und dank des Mesh-Netzes reicht der Funk auch bis an die Grundstücksgrenze. Wer einmal einen eigenen Zigbee-Sensor gebaut hat, findet schnell die nächsten Einsatzorte, von der Gartentür bis zur Regentonne.

Du willst Sensorik, Türen oder Technikräume im Betrieb überwachen und suchst eine Lösung, die dauerhaft läuft? Wir planen und betreuen Smart-Home- und IoT-Installationen. Sprich uns an.

Häufige Fragen

Welcher ESP32 unterstützt Zigbee?
Nur Chips mit einem Funkteil nach IEEE 802.15.4: der ESP32-H2, der ESP32-C6 und der ESP32-C5. Der klassische ESP32, der ESP32-S3 und der ESP32-C3 können nur WLAN und Bluetooth.

Brauche ich für den Briefkastenmelder WLAN am Briefkasten?
Nein. Der Melder funkt per Zigbee. Es genügt, wenn ein netzbetriebenes Zigbee-Gerät wie eine Lampe oder ein Zwischenstecker in Reichweite ist. Diese Geräte leiten die Meldung an die Zentrale weiter.

Wie lange hält der Akku?
Mit der Firmware aus diesem Beitrag nur einige Tage, weil das Board dauerhaft wach bleibt. Für monatelangen Betrieb muss es im Deep Sleep liegen und nur bei einer Erschütterung aufwachen. Alternativ versorgst du den Melder per USB-Netzteil.

Funktioniert der Melder in einem Briefkasten aus Metall?
Ja, wenn die Antenne nach außen geführt wird. Metall schirmt Funk stark ab. Das XIAO ESP32-C5 hat dafür einen Anschluss für eine externe Antenne, die dem Board beiliegt.

Welchen Zigbee-Koordinator brauche ich für Home Assistant?
Jeden von ZHA unterstützten Koordinator. Wir empfehlen den SMLIGHT SLZB-06P7 mit LAN und PoE, weil er sich frei im Haus platzieren lässt. Günstiger sind USB-Sticks wie der Home Assistant Connect ZBT-2 oder die Sonoff-Sticks der Reihe Zigbee 3.0 USB Dongle Plus.

Warum zwei Sensoren statt einem?
Die Erschütterung zeigt den Einwurf, das einfallende Licht das Öffnen der Klappe. Erst beide zusammen unterscheiden, ob Post gekommen ist oder ob jemand den Kasten geleert hat.

Funktioniert das Projekt auch mit Zigbee2MQTT?
Grundsätzlich ja, weil der Melder die genormten Zigbee-Funktionen für Vibration, Helligkeit und Akku nutzt. Beschrieben und vorgesehen ist in diesem Beitrag die Einbindung über ZHA in Home Assistant.

Quellen

  1. Espressif: Zigbee-Bibliothek des Arduino-Pakets für den ESP32, Quelltext und Beispiele für Vibrations-, Helligkeits- und schlafende Sensoren
  2. Seeed Studio Wiki: Getting Started with XIAO ESP32-C5, Zigbee mit Arduino und PlatformIO
  3. Home Assistant: Dokumentation zur Integration Zigbee Home Automation und zu Automationen
  4. Christopher Laws: Arduino-Bibliothek BH1750
  5. Make-Magazin bei heise online: Smart Home Bastelprojekt Briefkastenmelder mit Zigbee und ESP32, 13. November 2026 (Projektidee)

Produktfotos und Pinbelegung: Seeed Studio. Bildschirmfotos: Home Assistant. Verdrahtungsplan: K&C NetFox.


Fragen zu diesem Thema?

Nutze den KI-Assistenten unten rechts oder vereinbare ein Gespräch.

Termin vereinbaren

Weitere Artikel

SenseCAP MeshTracker X1: Meshtastic-Tracker im Kartenformat mit Dualband-GPS
Smart Home & IoT
SenseCAP MeshTracker X1: Meshtastic-Tracker im Kartenformat mit Dualband-GPS

Der SenseCAP MeshTracker X1 bringt Meshtastic ins Kartenformat: Dualband-GPS, IP66, 5 Tage Akku. Technik, Einrichtung und Grenzen im Überblick.

2026-11-2112 Min. Lesezeit
LoRaWAN in der Praxis: Anwendungsbeispiele aus Landwirtschaft, Stadt und Industrie
Smart Home & IoT
LoRaWAN in der Praxis: Anwendungsbeispiele aus Landwirtschaft, Stadt und Industrie

Von der intelligenten Bewässerung bis zur vorausschauenden Wartung: LoRaWAN zeigt seine Stärken überall dort, wo Sensoren über große Flächen verteilt sind.

2025-04-184 Min. Lesezeit
Home Assistant in der Praxis: Sinnvolle Automationen für den Alltag
Smart Home & IoT
Home Assistant in der Praxis: Sinnvolle Automationen für den Alltag

Von der Morgenroutine bis zur Sprachsteuerung: So lässt sich Home Assistant im echten Alltag konkret und komfortabel einsetzen.

2024-08-125 Min. Lesezeit