Moritz 00b17c0bb1 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

2.7 KiB

Raw Blame History

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:

all — alle registrierten Geräte
Gruppenname — alle Mitglieder der Gruppe
Alias — z.B. 1, 2, Drucker
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

2.7 KiB Raw Blame History