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

git clone https://github.com/Moritz/helios-smart-home.git
cd helios-smart-home
pip install requests

Schnellstart

# 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:

{
  "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:

[
  {
    "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