📖 Handbuch

Dokumentation für BLE Presence v1.0

Voraussetzungen

Master (Raspberry Pi)

• Raspberry Pi Zero 2W / 3/4/5
• DietPi OS (Trixie)
• LAN/WLAN-Zugang

Scanner

• ESP32-WROOM, ESP32-S3
• Stromversorgung via USB oder Lötpins
• 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/IRK.

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

Aufgrund der wechselnden MAC-Adresse und properitären Protokollen eignen sich keine Apple AirTags und AirTag-kompatible Geräte, oder Samsung Tags.

iPhone / Android
Über das auslesen des Identity Resolving Key (IRK) können Telefone mit random MAC-Adrersse auch getrackt werden.
Hierzu ist zu sagen das die meisten aktuellen Telefone aggressive Energiespar-Modi nutzen und bei ausgeschaltetem Display oft keine Signale gesndet werden.

Empfehlung: Shelly BLU Button, Feasycom Eddystone Devices.

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 install.* && wget http://ble-presence.de/download/install.sh && bash install.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 / MQTT konfigurieren
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

Geräte-Katalog

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

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)

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

Apple

Content...

Lizenz

BLE Presence verwendet ein Lizenzsystem auf Basis von Ed25519-signierten Schlüsseln. Jeder Lizenz-Key ist kryptografisch an eine bestimmte Hardware-ID gebunden und kann nicht auf andere Geräte übertragen werden.

Sinn der Lizenz ist interne Verschlüsselungen zu generieren um das System jetzt und vor allem in noch kommenden Versionen abzusichern.

Lizenztypen

Hardware-ID

Bei der Installation wird automatisch eine eindeutige Hardware-ID für den Raspberry Pi erzeugt. Sie hat das Format:

BLE-XXXX-XXXX

Die Hardware-ID findest du an folgenden Stellen:

• Im Web-Interface unter Konfiguration → Master → Lizenz
• Auf der Kommandozeile: cat /var/www/html/ble/data/hwid.txt

Die ID basiert auf den Hardware-Eigenschaften des Raspberry Pi und bleibt bei Neuinstallation gleich, solange dieselbe Hardware verwendet wird.

Lizenz erstellen

1. Öffne den Shop: ble-presence.de/shop.php
2. Trage deine Hardware-ID und E-Mail-Adresse ein
3. Der Key wird direkt auf der Seite angezeigt und kann kopiert oder als Datei heruntergeladen werden
4. Zusätzlich erhältst du den Key per E-Mail

Lizenz aktivieren

Nach Erhalt des Lizenz-Keys wird dieser im Web-Interface des Masters aktiviert:

1. Öffne das Web-Interface: http://[raspberry-ip]
2. Gehe zu Konfiguration → Master → Lizenz
3. Im Bereich „Lizenz" siehst du deine Hardware-ID und den aktuellen Status
4. Füge den Lizenz-Key in das Eingabefeld ein
5. Klicke auf „Aktivieren"

Nach erfolgreicher Aktivierung wechselt der Status und die MQTT-Integration wird sofort freigeschaltet. Ein Neustart der Services ist nicht nötig.

Lizenzstatus

Der aktuelle Lizenzstatus wird im Web-Interface unter Konfiguration → Lizenz als farbiger Badge angezeigt:

Lizenz deaktivieren

Falls du den Key entfernen möchtest (z.B. bei Hardware-Wechsel), kannst du über den „Deaktivieren"-Button im Lizenz-Bereich die aktive Lizenz löschen. Die MQTT-Integration wird daraufhin wieder gesperrt.

Troubleshooting Lizenz

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.

ESP32 Hardware

Folgende ESP32-Varianten werden unterstützt:

Firmware flashen

Erstinstallation (Full-Version)

OPTION 1
1. Über den ESP Web Tools Flasher
2. Dieses Tool läuft nur auf Microsoft Edge, Chrome oder Chrome basierenden Browsern
3. Mit dem ESP Flash Tool flashen

OPTION 2
1. Firmware unter WebUI → System → Udapte Firmware Downloads herunterladen (Full-Version)
2. ESP32 per USB an den Computer anschließen
3. Mit dem ESP Flash Tool flashen

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

ESP32 Einrichtung

1. Nach dem Flashen öffnet der ESP32 einen WLAN-Hotspot - NAME: ESP32-BLE-XXXXXX
2. Mit dem Hotspot verbinden - Passwort: 12345678 und Setup-Seite öffnen
3. WLAN-Zugangsdaten, Master-URL und Scanner-Name (muss einzigartig sein) konfigurieren
4. Feste-IP vergeben wenn gewünscht, und speichern
5. Nach dem speichern startet der ESP32
6. Am Master WebUI unter Konfiguartion → ESP32-Clients den Scanner anlegen.

7. Name muss gleich der Scanner ID sein.
8. API-Key kopieren, speichern, und den Key im WebUI des Scanner eintragen.

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

Installieren

Im WebUI des Shelly -> Scripts -> Create Script

1. Script-Name vergeben
2. Skript aus der nächsten Sektion kopieren und einfügen
3. API-Key erstellen Master -> WebUI -> Konfiguration -> Shelly Scanner.
4. IP vom Master und den API Key im Skript eintragen.
5. Skript speichern und starten

Skript

Hier das Skript für den Shelly als Scanner.

Welche Funktionen werden unterstützt

• Device-Scan -> scannt known Devices UUID / MAC
• Discover-Scan -> scannt alle BLE Devices in der nähe und meldet sie zurück an den Master
• Batterie-Scan -> Eddystone und BTHome
• Button-Event -> BTHome Button press / double_press / tripple_press / long_press
• Auto-Kalibration -> min. 3 BLE-Presence ESP32-Scanner müssen aktiv sein, die über nehmen dann die Kalibrierung des Shelly mit.

Welche Funktionen werden NICHT unterstützt

• IRK Device-Scan -> IRK wie z.B. beim iPhone funktionieren aufgrund fehlender Entschlüsselungs-Bibliothken nicht.
• Batterie-Scan BLE -> Der Batteriescan von reinen BLE Geräten wie Gigset-G-Tag funktionieren aufgrund fehlender Entschlüsselungs-Bibliothken nicht.

let C = {
  name: "Scanner - Name",
  host: "IP -> Master",
  api_key: "API-KEY -> Master WEBUI",
  scan_interval: 5,
  hb_interval: 10,
  offline_after: 30,
  debug: false
};

let VERSION="1.0.0";
let BTHOME="fcd2";
let EDDYSTONE="feaa";
let CALIB_UUID_PREFIX="B1E0CA11";
let _P="/shelly/";
let _H="0123456789abcdef";
let _s3="\x04\x05\x0A\x42\x4B\x4C";
let _s4="\x3E\x4D\x4E\x4F\x50";
let _s2="\x02\x03\x06\x07\x08\x0B\x0C\x0E\x12\x13\x14\x3D\x40\x41\x43\x45\x46\x47\x48\x49\x4A\x51\x52";
 
function objSize(id){
  let c=String.fromCharCode(id);
  if(_s3.indexOf(c)>=0)return 3;
  if(_s4.indexOf(c)>=0)return 4;
  if(_s2.indexOf(c)>=0)return 2;
  if(id<=0x53)return 1;
  return -1;
}
 
let known={};
let knownUuid={};
let discMode=false;
let discDevs={};
let discTimer=null;
let devs={};
let pending=[];
let ready=false;
let scanning=false;
let bootTs=0;
let lastPid={};
let calibBuf={};
let batchTimer=null;
let hbTimer=null;
let pollTimer=null;
let retryTimer=null;
let offlineInitTimer=null;
 
function ts(){return Math.floor(Date.now()/1000);}
 
function mem(tag){
  Shelly.call("Sys.GetStatus",{},function(r){
    if(r)print("[MEM] "+tag+" free="+r.ram_free);
  });
}
 
function macKey(a){return a.split(":").join("").toLowerCase();}
 
function toHex(b){return _H[(b>>4)&0xF]+_H[b&0xF];}
 
function url(p){return "http://"+C.host+":8099"+p;}
 
function post(p,body,cb){
  if(C.api_key)body.api_key=C.api_key;
  Shelly.call("HTTP.Request",{
    method:"POST",url:url(p),body:JSON.stringify(body),
    content_type:"application/json",timeout:5
  },function(r,ec){
    if(ec!==0||!r||!r.body){if(cb)cb(null);return;}
    try{if(cb)cb(JSON.parse(r.body));}catch(e){if(cb)cb(null);}
  });
}
 
function get(p,cb){
  let u=url(p);
  if(C.api_key)u+=(u.indexOf("?")>=0?"&":"?")+"api_key="+C.api_key;
  Shelly.call("HTTP.Request",{
    method:"GET",url:u,timeout:5
  },function(r,ec){
    if(ec!==0||!r||!r.body){if(cb)cb(null);return;}
    try{if(cb)cb(JSON.parse(r.body));}catch(e){if(cb)cb(null);}
  });
}
 
function parseBTHome(raw){
  if(!raw||raw.length<2)return null;
  let result={pid:-1,battery:-1,button:-1};
  if(raw.charCodeAt(0)&0x01)return null;
  let i=1;
  while(i=raw.length)break;
      i+=1+raw.charCodeAt(i);
      continue;
    }
    let size=objSize(id);
    if(size<0||i+size>raw.length)break;
    if(id===0x00||id===0x01||id===0x3A){
      let val=0;
      for(let b=0;b100)return 100;
  return pct;
}
 
function parseIBeacon(advData){
  if(!advData)return null;
  let raw=BLE.GAP.ParseManufacturerData(advData);
  if(!raw||raw.length<25)return null;
  if(raw.charCodeAt(0)!==0x4C||raw.charCodeAt(1)!==0x00)return null;
  if(raw.charCodeAt(2)!==0x02||raw.charCodeAt(3)!==0x15)return null;
  let u="";
  for(let i=4;i<20;i++){
    u+=toHex(raw.charCodeAt(i));
    if(i===7||i===9||i===11||i===13)u+="-";
  }
  let txp=raw.charCodeAt(24);
  if(txp>127)txp-=256;
  return {uuid:u,major:(raw.charCodeAt(20)<<8)|raw.charCodeAt(21),minor:(raw.charCodeAt(22)<<8)|raw.charCodeAt(23),txpower:txp};
}
 
function isCalibBeacon(ib){
  if(!ib||!ib.uuid)return false;
  return ib.uuid.substring(0,8).toUpperCase()===CALIB_UUID_PREFIX;
}
 
function handleCalibBeacon(ib,rssi){
  let key=ib.major+":"+ib.minor;
  let e=calibBuf[key];
  if(!e){e={s:0,c:0,t:ib.txpower};calibBuf[key]=e;}
  e.s+=rssi;
  e.c++;
}
 
function sendCalibration(){
  let readings=[];
  for(let key in calibBuf){
    let e=calibBuf[key];
    if(e.c===0)continue;
    let parts=key.split(":");
    let avg=Math.round(e.s/e.c);
    readings.push({major:parseInt(parts[0]),minor:parseInt(parts[1]),rssi:avg,distance:Math.round(Math.pow(10,(e.t-avg)/25)*100)/100});
  }
  calibBuf={};
  if(readings.length===0)return;
  if(C.debug)print("[CAL] "+readings.length);
  post(_P+"calibration",{scanner:C.name,readings:readings},null);
}
 
function sendButtonEvent(mac,event,rssi,pid){
  let names=["none","press","double_press","triple_press","long_press"];
  let name=(event>=1&&event<=4)?names[event]:"unknown";
  if(C.debug)print("[BTN] "+mac+" -> "+name+" pid="+JSON.stringify(pid));
  post(_P+"event",{scanner:C.name,mac:mac,event:name,rssi:rssi,pid:pid,timestamp:ts()},null);
}
 
function loadKnown(macs){
  known={};
  knownUuid={};
  if(!macs)return;
  for(let i=0;i0)knownUuid[m]=true;
  }
}
 
function register(){
  print("[REG] Registering...");
  let info=Shelly.getDeviceInfo();
  let wifi=Shelly.getComponentStatus("wifi");
  post(_P+"register",{
    scanner:C.name,
    ip:(wifi&&wifi.sta_ip)?wifi.sta_ip:"0.0.0.0",
    model:info?(info.model||"Shelly"):"Shelly",
    firmware:info?(info.fw_id||"?"):"?",
    scan_interval:C.scan_interval
  },function(d){
    if(!d||!d.success){
      print("[REG] Failed, retry 10s");
      if(retryTimer)Timer.clear(retryTimer);
      retryTimer=Timer.set(10000,false,register);
      return;
    }
    loadKnown(d.known_macs);
    if(C.debug){
      let cM=0,cU=0;
      for(let k in known)cM++;
      for(let k in knownUuid)cU++;
      print("[REG] OK: "+cM+"M "+cU+"U");
    }else{
      print("[REG] OK");
    }
    mem("post-reg");
    if(d.scan_interval)C.scan_interval=d.scan_interval;
    ready=true;
    startScan();
    startTimers();
  });
}
 
function startScan(){
  if(scanning)return;
  BLE.Scanner.Subscribe(onScan);
  BLE.Scanner.Start({duration_ms:-1,active:true});
  scanning=true;
}
 
function onScan(ev,res){
  if(ev!==BLE.Scanner.SCAN_RESULT||!res||!res.addr)return;
 
  if(discMode){
    let mac=res.addr.toUpperCase();
    let ib=parseIBeacon(res.advData);
    let dk=ib?ib.uuid:macKey(mac);
    if(!discDevs[dk]||res.rssi>discDevs[dk].r){
      let entry={m:mac,n:res.local_name||"",r:res.rssi,tp:"mac"};
      if(ib){
        entry.tp="ibeacon";
        entry.iu=ib.uuid.toUpperCase();
        entry.ima=ib.major;
        entry.imi=ib.minor;
      }else if(res.service_data&&res.service_data[BTHOME]){
        entry.tp="bthome";
      }
      discDevs[dk]=entry;
    }
    return;
  }
 
  let ib=parseIBeacon(res.advData);
  if(ib&&isCalibBeacon(ib)){
    handleCalibBeacon(ib,res.rssi);
    return;
  }
 
  let mac=res.addr.toUpperCase();
  let mk=macKey(mac);
  let isMac=known[mk]===true;
  let isUuid=false;
  let dk=mk;
 
  if(!isMac){
    if(ib&&knownUuid[ib.uuid]){
      isUuid=true;
      dk=ib.uuid;
    }else{
      return;
    }
  }
 
  let t=ts();
  let d=devs[dk];
  if(!d){
    d={o:false,s:0,r:-100,m:mac,t:0,b:-1,u:isUuid,ui:""};
    devs[dk]=d;
  }
 
  d.s=t;
  d.r=res.rssi;
  d.m=mac;
  if(isUuid&&ib)d.ui=ib.uuid;
 
  let bth=null;
  if(res.service_data&&res.service_data[BTHOME]){
    bth=parseBTHome(res.service_data[BTHOME]);
  }
 
  if(bth&&bth.pid>=0){
    if(lastPid[dk]===bth.pid)return;
    lastPid[dk]=bth.pid;
  }
 
  if(bth&&bth.battery>=0&&bth.battery<=100)d.b=bth.battery;
 
  if(d.b<0&&res.service_data&&res.service_data[EDDYSTONE]){
    let eB=parseEddystoneBatt(res.service_data[EDDYSTONE]);
    if(eB>=0)d.b=eB;
  }
 
  if(bth&&bth.button>=1){
    sendButtonEvent(mac,bth.button,res.rssi,bth.pid);
  }
 
  let wasOff=!d.o;
  d.o=true;
 
  let scan={address:mac,rssi:res.rssi,is_online:1,local_name:""};
  if(d.b>=0)scan.battery=d.b;
 
  if(isUuid&&ib){
    scan.ibeacon_uuid=ib.uuid;
    scan.ibeacon_major=ib.major;
    scan.ibeacon_minor=ib.minor;
    scan.ibeacon_txpower=ib.txpower;
  }
 
  if(wasOff){
    if(C.debug){
      let l=isUuid?dk.substring(0,8)+"...":mac;
      print("[ON] "+l+" R:"+res.rssi);
    }
    if(pending.length<20)pending.push(scan);
    d.t=t;
    sendBatch();
  }else if(t-d.t>=C.scan_interval){
    if(pending.length<20)pending.push(scan);
    d.t=t;
  }
}
 
function checkOffline(){
  let t=ts();
  let ct=C.offline_after*3;
  for(let mk in devs){
    let d=devs[mk];
    let age=t-d.s;
    if(d.o&&age>=C.offline_after){
      d.o=false;
      d.t=t;
      if(C.debug){
        let l=d.u?d.ui.substring(0,8)+"...":d.m;
        print("[OFF] "+l);
      }
      let os={address:d.m,rssi:-100,is_online:0,local_name:""};
      if(d.u&&d.ui)os.ibeacon_uuid=d.ui;
      if(pending.length<20)pending.push(os);
    }
    if(!d.o&&age>=ct){
      delete devs[mk];
      delete lastPid[mk];
    }
  }
}
 
function sendBatch(){
  if(!ready)return;
  checkOffline();
  if(pending.length===0)return;
  let scans=pending;
  pending=[];
  if(C.debug)print("[TX] "+scans.length);
  post(_P+"scan",{scanner:C.name,scans:scans,discovery:false},function(d){
    if(!d)print("[ERR] Batch failed");
  });
}
 
function heartbeat(){
  if(!ready)return;
  sendCalibration();
  Shelly.call("Sys.GetStatus",{},function(sr){
    let hb={scanner:C.name,uptime:ts()-bootTs};
    if(sr&&sr.ram_free){
      hb.free_mem=sr.ram_free;
      if(C.debug)print("[MEM] hb free="+sr.ram_free);
    }
    post(_P+"heartbeat",hb,function(d){
      if(!d||!d.success){
        print("[ERR] HB failed");
        ready=false;
        if(retryTimer)Timer.clear(retryTimer);
        retryTimer=Timer.set(5000,false,register);
      }
    });
  });
}
 
function offlineInit(){
  offlineInitTimer=null;
  let cnt=0;
  for(let mk in known){
    if(!devs[mk]){
      if(pending.length<20){
        pending.push({address:mk,rssi:-100,is_online:0,local_name:""});
        cnt++;
      }
    }
  }
  for(let uu in knownUuid){
    if(!devs[uu]){
      let c="";
      for(let j=0;j0)sendBatch();
}
 
function startTimers(){
  if(batchTimer)Timer.clear(batchTimer);
  batchTimer=Timer.set(C.scan_interval*1000,true,sendBatch);
  if(hbTimer)Timer.clear(hbTimer);
  hbTimer=Timer.set(C.hb_interval*1000,true,heartbeat);
  if(offlineInitTimer)Timer.clear(offlineInitTimer);
  offlineInitTimer=Timer.set(C.offline_after*1000,false,offlineInit);
  if(pollTimer)Timer.clear(pollTimer);
  pollTimer=Timer.set(300000,true,pollDevices);
}
 
function startDiscovery(duration){
  if(discMode)return "already running";
  if(!duration||duration<5)duration=15;
  discMode=true;
  discDevs={};
  if(discTimer)Timer.clear(discTimer);
  discTimer=Timer.set(duration*1000,false,discEnd);
  return "started";
}
 
function discEnd(){
  discMode=false;
  discTimer=null;
  sendDiscoveryResults();
}
 
function sendDiscoveryResults(){
  let devices=[];
  for(let k in discDevs){
    let dd=discDevs[k];
    let entry={mac:dd.m,name:dd.n,rssi:dd.r,type:dd.tp};
    if(dd.iu){
      entry.ibeacon_uuid=dd.iu;
      entry.ibeacon_major=dd.ima;
      entry.ibeacon_minor=dd.imi;
    }
    devices.push(entry);
  }
  discDevs={};
  let dUrl="http://"+C.host+"/ble/api.php?action=report_discovery";
  if(C.api_key)dUrl+="&api_key="+C.api_key;
  Shelly.call("HTTP.Request",{
    method:"POST",url:dUrl,
    body:JSON.stringify({client_id:C.name,timestamp:ts(),devices:devices}),
    content_type:"application/json",timeout:15
  },function(r,ec){
    if(ec!==0||!r||r.code!==200)print("[DISC] Send failed");
  });
}
 
function pollDevices(){
  get(_P+"devices?scanner="+C.name,function(d){
    if(!d||!d.success||!d.known_macs)return;
    loadKnown(d.known_macs);
  });
}
 
function status(){
  let kon=0,koff=0,kn=0,ku=0;
  for(let mk in devs){if(devs[mk].o)kon++;else koff++;}
  for(let k in known)kn++;
  for(let k in knownUuid)ku++;
  return JSON.stringify({ready:ready,known_mac:kn,known_uuid:ku,online:kon,offline:koff,uptime:ts()-bootTs,pending:pending.length,discovery:discMode});
}
 
bootTs=ts();
print("=== BLE Presence Shelly v"+VERSION+" ===");
print("[BLE] "+C.name+" -> "+C.host+(C.api_key?" [API]":" [NO KEY]"));
mem("boot");
retryTimer=Timer.set(3000,false,register);

Installieren

Content...

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.

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-Eingang anlegen
4. Im WebUI → Geräte auf das Symbol klicken.
   Hier findet ihr die Befehlserkennung für den UDP Eingang.

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.

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