Initial commit: Shelly Plug S CLI tool

Local network CLI for managing Shelly Plug S Gen 3 / Plus Plug S smart plugs via the Shelly RPC API (Gen 2/3). Designed as an AI-agent interface with machine-readable JSON output. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-19 22:52:12 +01:00 · 2026-02-19 22:52:12 +01:00 · 00b17c0bb1
commit 00b17c0bb1
3 changed files with 471 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,113 @@
+# Helios Smart Home CLI
+
+CLI-Tool zur lokalen Steuerung von **Shelly Plug S Gen 3** und **Plus Plug S** Steckdosen über die Shelly RPC-API (Gen 2/3). Entwickelt als Schnittstelle für KI-Agenten — alle Ausgaben sind maschinenlesbar (JSON auf stdout, Fehler auf stderr).
+
+## Voraussetzungen
+
+- Python 3.10+
+- `requests` — `pip install requests`
+- Shelly Plugs müssen im selben lokalen Netzwerk erreichbar sein
+
+## Installation
+
+```bash
+git clone https://github.com/Moritz/helios-smart-home.git
+cd helios-smart-home
+pip install requests
+```
+
+## Schnellstart
+
+```bash
+# Gerät hinzufügen (Alias "1" für physisch beschriftete Steckdose)
+python smarthome.py add 192.168.1.50 1
+
+# Einschalten
+python smarthome.py on 1
+
+# Status abfragen
+python smarthome.py status 1
+
+# Alle Geräte auflisten
+python smarthome.py list
+```
+
+## Befehle
+
+### Geräte-Management
+
+| Befehl | Beschreibung |
+|---|---|
+| `add <ip> [alias]` | Gerät per IP hinzufügen, Hardware-ID wird automatisch abgefragt |
+| `remove <ziel>` | Gerät entfernen (auch aus allen Gruppen) |
+| `rename <ziel> <neues_alias>` | Alias eines Geräts ändern |
+
+### Gruppen-Management
+
+| Befehl | Beschreibung |
+|---|---|
+| `group create <name>` | Leere Gruppe anlegen |
+| `group add <name> <ziel>` | Gerät(e) zur Gruppe hinzufügen |
+| `group remove <name> <ziel>` | Gerät(e) aus Gruppe entfernen |
+| `group delete <name>` | Gruppe löschen |
+
+### Aktionen
+
+| Befehl | Beschreibung |
+|---|---|
+| `on <ziel>` | Relais einschalten |
+| `off <ziel>` | Relais ausschalten |
+| `toggle <ziel>` | Relais-Zustand umschalten |
+| `status <ziel>` | Status abfragen (Ein/Aus, Leistung in Watt, Energie) |
+| `led <ziel> <mode>` | LED-Modus setzen: `switch`, `power` oder `off` |
+| `list` | Alle Geräte und Gruppen anzeigen |
+
+## Ziel-Auflösung
+
+Das `<ziel>`-Argument wird automatisch aufgelöst:
+
+1. `all` — alle registrierten Geräte
+2. **Gruppenname** — alle Mitglieder der Gruppe
+3. **Alias** — z.B. `1`, `2`, `Drucker`
+4. **Hardware-ID** — direkte Zuordnung
+
+## Datenstruktur
+
+Geräte und Gruppen werden in `mappings.json` neben dem Skript gespeichert:
+
+```json
+{
+  "devices": {
+    "shellyplugsg3-abc123": { "ip": "192.168.1.50", "alias": "1" }
+  },
+  "groups": {
+    "wohnzimmer": ["1", "2"]
+  }
+}
+```
+
+## Ausgabeformat
+
+- **stdout** — JSON (maschinenlesbar für KI-Agenten)
+- **stderr** — Fehler und Warnungen im Klartext
+
+Beispiel `status`-Antwort:
+
+```json
+[
+  {
+    "hw_id": "shellyplugsg3-abc123",
+    "alias": "1",
+    "online": true,
+    "output": true,
+    "apower": 42.5,
+    "aenergy_total": 1234.56
+  }
+]
+```
+
+## Fehlerbehandlung
+
+- HTTP-Timeout: 5 Sekunden pro Gerät
+- Bei Gruppen-Aufrufen werden fehlerhafte Geräte übersprungen (`"success": false`) statt das Skript abzubrechen
+- Nicht erreichbare Geräte erzeugen Warnungen auf stderr