📖 Handbuch

Vollständige Dokumentation für BLE Presence v1.0

Voraussetzungen

Master (Raspberry Pi)

• Raspberry Pi Zero 1W/2W / 3/4/5 mit Bluetooth
• DietPi OS (Trixie)
• LAN/WLAN-Zugang
• Python 3.9+
• PHP 8.x mit Apache
• Mosquitto MQTT Broker

Scanner

• ESP32-WROOM, ESP32-S3
• Stromversorgung via USB
• WLAN-Zugang

Zu trackende Geräte

Jedes BLE-Gerät, das regelmäßig Advertisements sendet — z.B. BLE-Tags, Shelly-Geräte, iBeacons. Protokolle: BLE/Eddystone/BTHome.

Button-Events funktionieren aktuell nur mit BTHome Devices, z.B. Shelly BLU Button.

Aufgrund der wechselnden MAC-Adresse eignen sich keine AirTags und AirTag-kompatible Geräte.

Empfehlung: Shelly BLU Button, Feasycom Eddystone Devices.

Geräte-Katalog

Hier findest du eine Übersicht kompatibler BLE-Geräte, die mit BLE Presence getestet wurden. Die Tabelle wird laufend erweitert.

Android App

Für die Einrichtung und Konfiguration von BLE-Tags wird die jeweilige Hersteller-App benötigt.

Hersteller-Apps

UUID konfigurieren

Bei Geräten mit konfigurierbarer UUID (z.B. Feasycom-Tags) wird die UUID über die Hersteller-App geändert:

1. Hersteller-App installieren und Bluetooth aktivieren
2. Tag in der App suchen und verbinden
3. UUID, Major/Minor (iBeacon) oder Namespace/Instance (Eddystone) setzen
4. Änderungen speichern — das Gerät sendet ab sofort mit der neuen Kennung

Android Handy als Beacon

Mit der App Beacon Scope kann jedes Android-Handy (ab Android 5.0) selbst als BLE-Beacon genutzt werden. Das Handy simuliert dann ein iBeacon-, Eddystone- oder AltBeacon-Signal und wird von BLE Presence wie ein normaler Tag erkannt.

1. Beacon Scope aus dem Google Play Store installieren
2. App öffnen und unter Transmit einen neuen Beacon erstellen
3. Protokoll wählen (iBeacon, Eddystone oder AltBeacon)
4. UUID/Namespace konfigurieren und Beacon starten
5. Die App sendet auch im Hintergrund, bis man den Beacon manuell stoppt

Eddystone / UUID

Eddystone ist ein von Google entwickeltes BLE-Beacon-Protokoll. BLE Presence unterstützt Eddystone-UID, das eine feste Kennung bestehend aus Namespace (10 Bytes) und Instance (6 Bytes) sendet.

Aufbau einer Eddystone-UID

Konfiguration am Tag

1. Tag per Hersteller-App verbinden
2. Eddystone-UID-Frame aktivieren
3. Namespace einheitlich für alle Tags setzen (z.B. 0x00112233445566778899)
4. Instance pro Tag eindeutig vergeben (z.B. 0x000000000001, 0x000000000002, …)
5. Sende-Intervall einstellen (empfohlen: 500–1000 ms)

iBeacon UUID

iBeacon ist Apples BLE-Beacon-Protokoll. Es verwendet eine dreiteilige Kennung aus UUID, Major und Minor.

Aufbau einer iBeacon-Kennung

Konfiguration am Tag

1. Tag per App verbinden
2. iBeacon-Frame aktivieren
3. UUID für alle Tags gleich setzen (z.B. 12345678-1234-1234-1234-123456789ABC)
4. Major z.B. pro Etage vergeben (1 = EG, 2 = OG)
5. Minor pro Gerät eindeutig vergeben (1, 2, 3, …)
6. Sende-Intervall einstellen (empfohlen: 500–1000 ms)

Installation

1. DietPi installieren

In den folgenden Links steht, wie man DietPi installiert:

• DietPi Installations-Anleitung
• DietPi Download

Die nachfolgenden Dateien helfen dir, DietPi schnell und einfach für den ersten Start zu konfigurieren:

dietpi.txt — Hier ist soweit alles vorkonfiguriert für den normalen Gebrauch.

dietpi-wifi.txt — Hier müsst ihr, wenn ihr WLAN nutzen wollt, eure SSID (WLAN-Name) und WLAN-Passwort eintragen. Groß-/Kleinschreibung beachten!

Beide Dateien liegen auf der SD-Karte im Boot-Verzeichnis, auf das ihr über z.B. den Windows Explorer zugreifen könnt.

2. DietPi erster Start

Nach dem Einstecken braucht der Pi ein paar Minuten, bis er per SSH erreichbar ist.

Um uns mit dem Pi zu verbinden, nutzen wir SSH. Ich empfehle PuTTY, das es HIER als Portable-Version gibt.

In PuTTY tragen wir den Hostname oder die IP ein und drücken „Open".

Für den ersten Login nutzt ihr:

login as: root
root@master's password: DietPi

DietPi fängt mit der Grundinstallation an.

Ihr werdet aufgefordert, die Passwörter für die User root und dietpi zu ändern. Nutzt sichere Passwörter, auch wenn alles nur im internen Netz läuft.

Die serial/UART-Konsole könnt ihr abgeschaltet lassen. „NO" wählen.

Da wir über die dietpi.txt schon alles vorkonfiguriert haben, kannst du hier ohne Änderung auf „Install" und „Select" gehen.

Kurz noch bestätigen und es wird alles eingerichtet. Das kann je nach Hardware ein paar Minuten dauern.

3. Master installieren

Einfach die untere Zeile kopieren und einfügen, das war es schon:

cd / && rm -rf installer.* && wget http://ble-presence.de/download/installer.sh && bash installer.sh | tee /install.log

Nach dem Reboot ist die Web-Oberfläche mit admin/admin unter eurer IP erreichbar.

Nächste Schritte

1. Web-Interface öffnen: http://[raspberry-ip]
2. Master Konfiguration durchführen
3. ESP32 einrichten (min. 1 Scanner)
4. Unter „Geräte" → „Start Distributed Scan" einen ersten Scan starten
5. Erkannte BLE-Geräte benennen und per Alias zuordnen

Web-Konfiguration Master

Die gesamte Konfiguration erfolgt über Konfiguration > Master im Web-Interface. Änderungen werden in INI-Dateien gespeichert und die entsprechenden Services automatisch neu gestartet.

Konfigurationsgruppen

MQTT Einstellungen

Aggregator

Der Aggregator sammelt Daten aller Scanner, bestimmt den besten Scanner pro Gerät und publiziert das aggregierte Ergebnis.

Aggregator Einstellungen

Aggregator Button Events

Aggregator UDP Export

Statistik

Scanner

Hier kann eingestellt werden ob der Master auch ein Scanner sein soll, und Optionen für alle Scanner eingestellt werden.

Scan Daemon Steuerung

Allgemein

Discovery / Scan

Zeitplan

UDP Einstellungen

Logging

Das System kann Daten sammeln. Um nicht unnötig viele Logs zu schreiben kann man hier das Level einstellen.

Logging Einstellungen

Geräte verwalten

Unter Geräte werden alle bekannten BLE-Devices aufgelistet. Hier kann man:

• Alias vergeben — Geräte erhalten einen lesbaren Namen statt MAC-Adresse
• Batterie scannen — Manueller oder automatischer Battery-Level-Check
• MQTT Monitoring — Live-Status und RSSI pro Gerät
• Gerät löschen — Entfernt das Gerät aus der Datenbank

Distributed Scan

Ein koordinierter Scan über alle verbundenen Scanner (Master + ESP32 Clients). Findet neue BLE-Geräte im gesamten Haus gleichzeitig.

Grundriss einrichten

Unter Position → Grundriss Editor wird der Grundriss konfiguriert:

1. Grundriss hochladen — PNG oder JPG des Grundrisses
2. Maßstab kalibrieren — Pixel pro Meter einstellen (z.B. 68 px/m). Wichtig für korrekte Distanzberechnung!
3. Zonen zeichnen — Räume als farbige Polygone auf dem Grundriss markieren
4. Etagen verwalten — Mehrere Stockwerke mit eigenem Grundriss

Scanner platzieren

Im Grundriss-Editor werden Scanner per Drag & Drop auf dem Plan positioniert. Die Position bestimmt die Trilateration:

• Scanner möglichst gleichmäßig verteilen
• Mindestens 3 Scanner für Trilateration empfohlen
• Wände und Hindernisse beeinflussen die RSSI-Werte
• Scanner auf verschiedenen Etagen getrennt platzieren

Anti-Flapping

Das Anti-Flapping-System verhindert, dass Geräte ständig zwischen Räumen hin- und herspringen.

Wie es funktioniert

1. Für jedes Gerät wird der aktuelle „beste Scanner" (=Raum) gespeichert
2. Ein neuer Scanner wird erst dann Kandidat, wenn er den aktuellen um hysteresis dB übertrifft
3. Der Kandidat muss für stability_time Sekunden konstant besser bleiben
4. Erst dann wird der Raum tatsächlich gewechselt
5. Ein Kandidat bekommt 3 Fehlversuche, bevor er verworfen wird

Live Map

Die Live Map unter Position zeigt alle Geräte in Echtzeit auf dem Grundriss:

• 🟢 Grüne Punkte — Position per Trilateration berechnet
• 🟡 Gelbe Punkte — Fallback: Position beim stärksten Scanner
• 🔵 Blaue Punkte — Scanner-Positionen

Die Karte aktualisiert sich über MQTT WebSocket in Echtzeit. Geräte bewegen sich mit CSS-Transitions sanft über den Plan.

ESP32 Hardware

Folgende ESP32-Varianten werden unterstützt:

Firmware flashen

Erstinstallation (Full-Version)

1. Firmware unter System → ESP32 Firmware Downloads herunterladen (Full-Version)
2. ESP32 per USB an den Computer anschließen
3. Mit dem ESP Flash Tool im Web-Interface flashen
4. Alternativ: esptool.py über Kommandozeile

# Via esptool.py (Alternative)
esptool.py --chip esp32s3 --port /dev/ttyUSB0 \
  write_flash 0x0 firmware_full_esp32s3.bin

Updates (OTA)

Nach der Erstinstallation können Updates kabellos über das Web-Interface oder remote vom Master aus installiert werden. Siehe OTA Updates.

ESP32 Einrichtung

1. Nach dem Flashen öffnet der ESP32 einen WLAN-Hotspot
2. Mit dem Hotspot verbinden und Setup-Seite öffnen
3. WLAN-Zugangsdaten, Master-URL und Scanner-Name konfigurieren
4. ESP32 startet neu und verbindet sich mit dem Master
5. Am Master unter System → Scanner Firmware-Status prüfen

ESP32 Web-UI

Jeder ESP32 Scanner hat ein eigenes Web-Interface unter seiner IP-Adresse mit:

• System-Übersicht (IP, RAM, Uptime, Temperatur, RSSI)
• Geräte-Tabelle mit Status, RSSI und Batterie
• Aktionen: Battery Scan, Device Sync, Logs, Monitor, Update, Reboot

OTA Updates

ESP32-Scanner können remote aktualisiert werden:

Vom Scanner selbst

1. Scanner-WebUI öffnen → Update klicken
2. Update-Firmware (.bin) hochladen
3. Scanner startet automatisch neu

Zentral vom Master

1. System → Scanner Firmware-Status öffnen
2. Veraltete Scanner werden markiert (gelbe Legende)
3. Per Klick auf „Update" wird die neue Firmware übertragen

Loxone

Anbindung an Loxone über UDP-Export:

1. In der Konfiguration Aggregator UDP Export aktivieren
2. Ziel-IP und Port des Loxone Miniservers eintragen
3. In Loxone einen UDP-Monitor-Eingang anlegen

Home Assistant

BLE Presence integriert sich über MQTT Auto-Discovery in Home Assistant:

• Geräte erscheinen automatisch als Sensor-Entitäten
• Status (online/offline), Raum, Batterie und RSSI als Attribute
• Für Automatisierungen nutzbar (z.B. „Wenn Dieter im Wohnzimmer → Licht an")

# Beispiel-Automation (Home Assistant YAML)
automation:
  - trigger:
      platform: state
      entity_id: sensor.ble_dieter
      to: "Wohnzimmer"
    action:
      service: light.turn_on
      target:
        entity_id: light.wohnzimmer

API

Es können alle Daten auch über den API-Server im Json Format ausgelesen werden.

MQTT Topics

BLE Presence verwendet folgende Topic-Struktur (Beispiel mit base_topic = presence):

Aggregated Discovery Payload

{
  "devices": [
    {
      "mac": "DC:0D:30:23:07:69",
      "alias": "Dieter",
      "rssi": -64,
      "scanner": "west",
      "battery": 100,
      "status": "online",
      "room": "Wohnzimmer",
      "last_seen": "2026-02-06T12:45:00"
    }
  ]
}

Statistiken

Unter Statistik werden Anwesenheits- und Batteriedaten aufgezeichnet:

• Anwesenheits-Timeline — Online/Offline-Phasen als Gantt-Chart. Zeigt Dauer und zugeordneten Scanner.
• Batterie-Verlauf — Graphen über 7 Tage bis 2 Jahre. Min/Max/Aktuell-Werte.
• Cleanup — Automatische Bereinigung alter Daten (konfigurierbar).

Logs & Debugging

Logs können über die Web-UI oder direkt via Journal eingesehen werden:

# Aggregator Logs
sudo journalctl -u ble_aggregator -f

# Scan Daemon Logs
sudo journalctl -u ble_tool -f

# ESP32 WebSerial Monitor
# Im ESP32-WebUI: "Monitor" Button

Log-Level

In der Konfiguration unter Logging einstellbar:

System Updates

Unter WebUI → System → Update wird die installierte Version mit der verfügbaren verglichen. Updates können direkt über das Web-UI eingespielt werden.

ESP32 Updates

Unter WebUI → System → Update wird die installierte Version der Scanner mit der verfügbaren verglichen. Updates können per Remote-Update über das Web-UI eingespielt werden.

Troubleshooting

Dashboard zeigt „Nicht verbunden"

• Prüfe ob Mosquitto läuft: sudo systemctl status mosquitto
• WebSocket-Port (9001) muss in der Mosquitto-Konfiguration aktiv sein
• Browser-Konsole auf WebSocket-Fehler prüfen
• Im Browser http://scanner-ip/logs prüfen

Geräte werden nicht erkannt

• BLE muss am Raspberry Pi aktiv sein: hciconfig hci0 up
• Scan Daemon muss laufen: sudo systemctl status ble_tool
• RSSI-Threshold in der Konfiguration prüfen (Default: -99 dBm)
• Browser-Konsole auf WebSocket-Fehler prüfen
• Im Browser http://scanner-ip/logs prüfen

ESP32 verbindet sich nicht

• WLAN-Credentials im ESP32-Setup prüfen
• Master-URL korrekt? (z.B. http://192.168.136.120/ble)
• API Key am Master und ESP32 identisch?
• ESP32 Serial Monitor via WebSerial prüfen
• Im Browser http://scanner-ip/logs prüfen

Geräte springen zwischen Räumen

• Anti-Flapping aktivieren (RoomTracking → antiflapping = true)
• Hysterese erhöhen (8–10 dB)
• Stability Time erhöhen (30+ Sekunden)
• Scanner besser verteilen — ideal: nicht zu nah beieinander

Hoher RAM-Verbrauch am ESP32

• ESP32-S3 hat mehr freien RAM (~90 KB vs ~60 KB)
• Geräteliste reduzieren (nur benötigte Geräte tracken)
• Firmware-Version prüfen — neuere Versionen sind optimiert