# SensorPulse Companion – Einrichtungsanleitung

Die SensorPulse Companion-App (Android/iOS) zeigt auf dem Smartphone nur Lesezugriff auf Ihren Windows-PC: CPU/GPU/RAM, Temperaturen, Warnungen und kritische Sensoren. Es gibt keine Fernsteuerung (keine Profile, keine Lüfter, kein Overlay).

Sicherheit: Remote-Zugriff ist standardmäßig aus. Aktivieren Sie ihn nur im Heimnetz oder über VPN. Geben Sie den API-Port nicht ins Internet frei (kein Router-Port-Forwarding).

## Übersicht

1. SensorPulse auf dem PC starten (Windows 10/11, 64-Bit)
2. Einstellungen → Automatisierung → Localhost-Sensor-API aktivieren
3. Remote-Zugriff (Companion-App) aktivieren
4. Windows-Firewall: eingehendes TCP auf dem API-Port (Standard 8765) für private Netzwerke erlauben – in den Einstellungen per Button Firewall-Regel anlegen oder manuell
5. Companion-App installieren, QR-Code scannen (empfohlen) oder Pairing-JSON aus den Einstellungen verwenden

## Am PC – Schritt für Schritt

### 1. API aktivieren

Öffnen Sie Einstellungen (Zahnrad) → Bereich Automatisierung:

- Localhost-Sensor-API ankreuzen
- Port belassen (`8765`) oder anpassen (1024–65535)
- Bei Remote-Zugriff wird automatisch ein langer API-Token erzeugt

### 2. Remote-Zugriff aktivieren

Kreuzen Sie Remote-Zugriff (Companion-App) an. SensorPulse lauscht dann zusätzlich auf Ihre LAN-IP-Adressen (z. B. `192.168.1.42`), nicht nur auf `127.0.0.1`.

Im Pairing-Bereich erscheinen:

- QR-Code – zum Scannen in der Companion-App (oder JSON-fähiger Scanner)
- Pairing-JSON – zum Kopieren oder manuellen Einfügen
- LAN-Endpunkte – URLs für Tests mit Browser oder `curl` im Netzwerk

### 3. Windows-Firewall

In den Einstellungen unter Remote-Zugriff zeigt SensorPulse den Firewall-Status und bietet Firewall-Regel anlegen (Administratorbestätigung). Alternativ manuell:

1. Windows-Suche: „Windows Defender Firewall mit erweiterter Sicherheit“
2. Eingehende Regeln → Neue Regel… → Port → TCP → `8765` (oder Ihr Port)
3. Profil: nur Privat (nicht Öffentlich)
4. Name z. B. SensorPulse Companion API

Nach der ersten Verbindung vom Handy fragt Windows ggf. nach – Private Netzwerke erlauben.

### 4. Pairing-JSON verstehen

    {
      "v": 1,
      "name": "GAMING-PC",
      "host": "192.168.1.42",
      "port": 8765,
      "token": "…langer Geheimstring…"
    }

Feld | Bedeutung
--- | ---
`name` | Anzeigename in der App (meist PC-Name)
`host` | LAN-IP des PCs – ändert sich ggf. nach DHCP-Neustart
`port` | API-Port aus den Einstellungen
`token` | Geheimer Schlüssel – wie ein Passwort, nicht teilen

## Companion-App (Smartphone)

1. App SensorPulse Companion starten
2. Tab PCs → PC hinzufügen
3. QR-Code scannen (Android/iOS, empfohlen) oder Pairing-JSON einfügen
4. Verbindung testen → bei Erfolg Speichern
5. Tab Dashboard / Alerts – Pull-to-refresh oder Auto-Refresh (~20 s)

## Szenarien

### Im gleichen WLAN (typisch)

PC und Handy im selben Heim-WLAN. `host` muss die IPv4-Adresse des PCs sein (nicht `127.0.0.1`). Prüfen am PC: `Win`+`R` → `cmd` → `ipconfig` → „IPv4-Adresse“.

### Unterwegs per VPN (empfohlen)

Installieren Sie z. B. Tailscale oder WireGuard auf PC und Handy. Verbinden Sie beide ins gleiche VPN. Als `host` in der App die VPN-IP des PCs verwenden (Tailscale: z. B. `100.x.x.x`).

Kein Port-Forwarding am Router nötig – der Tunnel ersetzt das unsichere Freigeben ins Internet.

### Festes DHCP / reservierte IP

Wenn sich die LAN-IP des PCs oft ändert, reservieren Sie in der FritzBox/Router die MAC-Adresse des PCs auf eine feste IP – dann bleibt Pairing gültig.

### Mehrere PCs

In der Companion-App können mehrere Einträge gespeichert werden. In der PC-Liste tippen Sie den aktiven PC an (Markierung ●).

### Token erneuern

Bei Verdacht auf unbefugten Zugriff: API-Token neu erzeugen in den Einstellungen. Alle Companion-Apps müssen das Pairing mit dem neuen JSON/QR aktualisieren.

## API-Endpunkte (nur Lesen)

Pfad | Verwendung
--- | ---
`GET /api/health` | Verbindungstest
`GET /api/companion` | Dashboard-Daten für die App
`GET /api/quicklook` | Kompakt CPU/GPU/RAM
`GET /api/alerts` | Aktive Warnungen

Header bei gesetztem Token:

    Authorization: Bearer IHR_TOKEN

Test vom PC (LAN):

    curl -H "Authorization: Bearer IHR_TOKEN" http://192.168.1.42:8765/api/companion

## Fehlerbehebung

Problem | Lösung
--- | ---
Verbindung schlägt fehl | SensorPulse läuft? API + Remote aktiv? Gleiches WLAN/VPN? Firewall-Regel?
`401 unauthorized` | Token falsch oder veraltet – Pairing-JSON neu kopieren
Keine LAN-IP im Pairing | Netzwerkkabel/WLAN am PC prüfen; Remote-Zugriff kurz aus/ein
QR wird nicht erkannt | JSON manuell einfügen; Helligkeit erhöhen; alternativ Copy-Paste
Werte veraltet | Monitoring pausiert? PC im Energiesparen? App nach unten ziehen (Refresh)
Funktionierte, dann nicht mehr | DHCP hat IP geändert – neues Pairing oder feste IP am Router

## Was die Companion-App nicht kann

- Kein Start/Stop des Monitorings, keine Profile, keine Lüftersteuerung
- Kein SQL-Admin, keine SNMP-Konfiguration
- Kein Monitoring ohne laufende SensorPulse-Instanz auf dem PC
- Kein Ersatz für die Desktop-App – nur Fern-Anzeige

Localhost-API – technische Referenz (Rainmeter, Skripte) · Drücken Sie `F1` in den Einstellungen beim Companion-Bereich für die Kurzhilfe.