docs: README mit Architektur, Installation und Konfiguration

2026-05-20 12:59:53 +02:00
commit c6ffd9c26a
1 changed files with 208 additions and 0 deletions
@@ -0,0 +1,208 @@
+# 🏠 HomeMatic Anwesenheitserkennung via MikroTik
+
+Automatische Anwesenheitserkennung für 2 iPhones im Heimnetz **Ebesch** (192.168.252.0/24).  
+Ein Python-Script läuft minütlich auf `ebesch-docker` und fragt den MikroTik-Router per REST-API ab — sind die iPhones im WLAN eingebucht, werden die HomeMatic-Systemvariablen auf *„zu Hause"* gesetzt.
+
+---
+
+## 🏗️ Architektur
+
+```
+┌─────────────────┐     REST API      ┌──────────────────────────┐
+│  ebesch-docker  │ ────────────────► │  MikroTik RB5009         │
+│  192.168.252.10 │   /caps-man/      │  192.168.252.254         │
+│  (Cronjob 1min) │   registration-   │  CAPsMAN → AP .253       │
+│                 │   table           │  SSID: Aironet           │
+└────────┬────────┘                   └──────────────────────────┘
+         │                                        ▲
+         │ statechange.cgi                        │ WiFi
+         ▼                                        │
+┌─────────────────┐                   ┌──────────┴───────────────┐
+│  HomeMatic CCU2 │                   │  📱 RP iPhone            │
+│  192.168.252.12 │                   │  📱 Kerstins iPhone      │
+│                 │                   └──────────────────────────┘
+│  Systemvariablen│
+│  • Zone RPiPhone (1828)
+│  • Zone Kerstins iPhone (4730)
+│  • Anwesenheit (950)
+└─────────────────┘
+```
+
+---
+
+## 📋 Voraussetzungen
+
+| Komponente | Gerät | IP |
+|---|---|---|
+| Script-Host | ebesch-docker | 192.168.252.10 |
+| Router | MikroTik RB5009UPr+S+ | 192.168.252.254 |
+| WLAN-AP | MikroTik RBcAPGi-5acD2nD (CAPsMAN) | 192.168.252.253 |
+| HomeMatic | CCU2 | 192.168.252.12 |
+
+**Software auf ebesch-docker:**
+- Python 3.8+
+- `requests` Bibliothek (via pip/venv)
+
+---
+
+## ⚙️ Erkennung
+
+### Primär: CAPsMAN Registration Table
+Zeigt alle **aktuell aktiv verbundenen** WLAN-Clients des APs.  
+→ Zuverlässigste Methode, da in Echtzeit.
+
+### Fallback: ARP-Tabelle
+Enthält zuletzt gesehene MAC/IP-Zuordnungen.  
+→ Greift wenn das iPhone kurz vom WLAN getrennt ist (Sleepmode).
+
+### iOS MAC-Randomisierung (iOS 14+)
+iPhones nutzen **pro SSID eine stabile private MAC-Adresse** (nicht die echte Hardware-MAC).  
+Diese bleibt für dieselbe SSID konstant, ist aber netzwerkspezifisch.
+
+**MAC-Adresse herausfinden:**
+```
+iPhone → Einstellungen → WLAN → ⓘ neben "Aironet" → WLAN-Adresse
+```
+Diese Adresse in `config.ini` eintragen.
+
+---
+
+## 🚀 Installation
+
+### 1. Repo auf ebesch-docker klonen
+
+```bash
+ssh ebesch-docker
+cd /opt
+git clone https://git.rwolff.homelinux.net/rpwolff/homematic-anwesenheit.git
+cd homematic-anwesenheit
+```
+
+### 2. MAC-Adressen eintragen
+
+```bash
+nano config.ini
+# [device.rp_iphone]   → mac = XX:XX:XX:XX:XX:XX
+# [device.kerstin_iphone] → mac = XX:XX:XX:XX:XX:XX
+```
+
+### 3. Installation ausführen
+
+```bash
+bash install.sh
+```
+
+Das Script:
+- Legt `/opt/homematic-presence/` an
+- Erstellt ein Python-venv mit `requests`
+- Installiert einen Cronjob (`/etc/cron.d/homematic-presence`)
+- Konfiguriert Log-Rotation
+
+### 4. Testen
+
+```bash
+/opt/homematic-presence/venv/bin/python3 /opt/homematic-presence/presence_check.py \
+    --dry-run --verbose
+```
+
+### 5. Log beobachten
+
+```bash
+tail -f /var/log/homematic-presence.log
+```
+
+---
+
+## 📊 HomeMatic Systemvariablen
+
+| Variable | ISE-ID | Typ | `false` | `true` |
+|---|---|---|---|---|
+| Zone RPiPhone | 1828 | LOGIC | außer Haus | zu Hause |
+| Zone Kerstins iPhone | 4730 | LOGIC | außer Haus | zu Hause |
+| Anwesenheit | 950 | LOGIC | nicht anwesend | anwesend |
+
+Die Variable **Anwesenheit** wird auf `true` gesetzt wenn mindestens eine Person zuhause ist.
+
+---
+
+## 🔧 Konfiguration (`config.ini`)
+
+```ini
+[mikrotik]
+host     = 192.168.252.254
+user     = admin
+password = <siehe Bitwarden / Obsidian>
+
+[homematic]
+host            = 192.168.252.12
+combined_ise_id = 950       # Kombinierte Anwesenheit
+
+[device.rp_iphone]
+mac    = XX:XX:XX:XX:XX:XX  # Private WLAN-MAC für SSID "Aironet"
+ise_id = 1828
+label  = RP iPhone
+
+[device.kerstin_iphone]
+mac    = XX:XX:XX:XX:XX:XX  # Private WLAN-MAC für SSID "Aironet"
+ise_id = 4730
+label  = Kerstins iPhone
+```
+
+---
+
+## 🔍 Troubleshooting
+
+**CAPsMAN zeigt 0 Clients obwohl Gerät verbunden:**
+```bash
+# Router-Seite prüfen:
+curl -u admin:<pw> http://192.168.252.254/rest/caps-man/registration-table
+```
+
+**HomeMatic-Variable ändert sich nicht:**
+```bash
+# XML-API direkt testen:
+curl "http://192.168.252.12/config/xmlapi/statechange.cgi?ise_id=1828&new_val=true"
+```
+
+**Script manuell ausführen:**
+```bash
+/opt/homematic-presence/venv/bin/python3 \
+    /opt/homematic-presence/presence_check.py --verbose
+```
+
+**Cronjob-Status:**
+```bash
+systemctl status cron
+grep homematic /var/log/syslog | tail -20
+```
+
+---
+
+## 📁 Dateien
+
+| Datei | Beschreibung |
+|---|---|
+| `presence_check.py` | Hauptscript: Router abfragen → HomeMatic setzen |
+| `config.ini` | Konfiguration (MACs, IPs, Credentials) |
+| `install.sh` | Einmalige Installation auf ebesch-docker |
+| `README.md` | Diese Dokumentation |
+
+---
+
+## 🔒 Sicherheitshinweise
+
+- `config.ini` enthält Passwörter → **nicht öffentlich committen**
+- Das Repo ist öffentlich — `config.ini` ist in `.gitignore`
+- Passwörter liegen in Bitwarden / Obsidian Firma
+
+---
+
+## 📅 Wartung
+
+- RouterOS-Updates können CAPsMAN-API-Pfade ändern → Script ggf. anpassen
+- iOS-Updates können MAC-Randomisierung beeinflussen → MACs ggf. neu auslesen
+- HomeMatic-Firmware-Updates: ISE-IDs bleiben stabil
+
+---
+
+*Netz: Ebesch · 192.168.252.0/24 · SSID: Aironet · Repo: [git.rwolff.homelinux.net/rpwolff/homematic-anwesenheit](https://git.rwolff.homelinux.net/rpwolff/homematic-anwesenheit)*