Just a second...

UniFi LED API

Nachtmodus-Zeitpläne für UniFi Access Points — das Feature, das Ubiquiti nie gebaut hat. Jetzt auf PyPI verfügbar — mit einem Befehl installieren und loslegen.

pip install GitHub Dokumentation

pip install unifi-led-api| PyPI ↗

Aktiv gepflegt & auf PyPI

Getestet mit UniFi OS 5.1.5, Network 10.2.97 on U7 Pro and U6+. Veröffentlicht auf PyPI und GitHub Container Registry.

Funktionen

Auf PyPI verfügbar

Einfach installieren mit pip install unifi-led-api. Der globale Befehl unifi-led ist sofort nutzbar — kein Klonen oder manuelles Setup nötig.

Auto-Discovery

Findet alle verbundenen UniFi APs und prüft die LED-Kompatibilität. Zeigt Namen, MAC-Adressen, Modelle und Geräte-IDs.

Webhook API Server

Eingebauter HTTP-Server für die Integration mit Node-RED, Home Assistant und mehr. Steuere LEDs per GET/POST-Request.

Gerätegruppen

Erstelle benannte Zonen wie "upstairs" oder "downstairs" in groups.json. Steuere ganze Gruppen mit einem Befehl.

Auto-Konfiguration

Gerätekonfiguration wird bei jedem Lauf live geladen. Payloads sind nie veraltet — auch nach Firmware-Updates oder Konfig-Änderungen.

Interaktives Setup

Der eingebaute Assistent führt durch die Einrichtung: Zugangsdaten eingeben, Geräte entdecken und auswählen — .env wird automatisch erstellt.

LED-Status & Dry-Run

Prüfe den aktuellen LED-Status oder nutze den Dry-Run-Modus um Payloads zu inspizieren, bevor etwas gesendet wird.

Docker-Ready

Vorgebaute Images in der GitHub Container Registry. Mit Docker Compose und ofelia-Scheduler sofort einsatzbereit.

Automatisierungsbereit

Für cron-Jobs und unbeaufsichtigten Betrieb ausgelegt. Die .env-Datei wird automatisch geladen — kein Extra-Setup im Scheduler.

Warum REST statt SSH?

Viele bestehende Lösungen setzen auf SSH-Zugriff auf den AP. Dieser Ansatz hat deutliche Nachteile.

SSH-basierte Steuerung

• Firmware-Korruption und Geräteinstabilität
• Reprovisionierungs-Schleifen und unerwartete Reboots
• Kann nach Fehlern TFTP-Recovery erfordern
• Bricht nach Firmware-Updates oft stillschweigend

REST API (dieses Projekt)

• Nutzt dieselbe API, die der Controller intern verwendet
• Kein direkter Gerätezugriff — sicher und stabil
• Holt Konfiguration bei jedem Lauf neu — nie veraltet
• Geeignet für langfristige, unbeaufsichtigte Automatisierung

Schnellstart

In unter einer Minute startklar. Installiere von PyPI (empfohlen), nutze Docker oder klone den Quellcode.

# Installieren von PyPI
pip install unifi-led-api

# Interaktiver Einrichtungsassistent
unifi-led setup

# LEDs steuern
unifi-led led on
unifi-led led off

# LED-Status prüfen
unifi-led status

# Mit cron planen (Nachtmodus: aus um 22 Uhr, an um 7 Uhr)
0 22 * * * cd /path/to/my/env_folder && unifi-led led off
0 7  * * * cd /path/to/my/env_folder && unifi-led led on

# Aus der GitHub Container Registry ziehen
docker pull ghcr.io/elnino0916/unifi-led-api:main

# Erstelle deine .env-Datei mit Controller-URL, Zugangsdaten und Geräte-ID

# LEDs steuern
docker run --rm --env-file .env ghcr.io/elnino0916/unifi-led-api:main led off
docker run --rm --env-file .env ghcr.io/elnino0916/unifi-led-api:main led on

# LED-Status prüfen
docker run --rm --env-file .env ghcr.io/elnino0916/unifi-led-api:main status

# Mit cron planen (Nachtmodus: aus um 22 Uhr, an um 7 Uhr)
0 22 * * * docker run --rm --env-file /path/to/.env ghcr.io/elnino0916/unifi-led-api:main led off
0 7  * * * docker run --rm --env-file /path/to/.env ghcr.io/elnino0916/unifi-led-api:main led on

# Klonen und installieren
git clone https://github.com/elNino0916/unifi-led-api.git
cd unifi-led-api
pip install -e ".[dev]"

# Interaktiver Einrichtungsassistent
unifi-led setup

# Oder manuell konfigurieren
cp .env.example .env
# Bearbeite .env mit Controller-URL, Zugangsdaten und Geräte-ID

# LEDs steuern
unifi-led led on
unifi-led led off

# Konfiguration ohne Änderungen anzeigen
unifi-led fetch-config

Verwendung

Hier sind die wichtigsten Befehle. Nach der Installation steht der globale Befehl unifi-led zur Verfügung.

💡 LED ein-/ausschalten

unifi-led led on
unifi-led led off
unifi-led led on --color "#0000ff" --brightness 50

Farbe und Helligkeit nur auf älteren APs unterstützt.

🔍 Auto-Discovery

unifi-led discover

Findet alle verbundenen Geräte mit Namen, MAC, Modell und Kompatibilität.

📊 LED-Status prüfen

unifi-led status

Zeigt den aktuellen LED-Override-Status aller Geräte.

🧪 Vorschau (Dry-Run)

unifi-led led on --dry-run

Zeigt das JSON-Payload ohne Änderungen vorzunehmen.

🌐 Webhook-Server

unifi-led serve --port 8080

# Endpunkte:
# GET /led/on
# GET /led/off?group=upstairs
# GET /led/on?device=id1,id2

Perfekt für Node-RED, Home Assistant und andere Plattformen.

🏷️ Gerätegruppen

unifi-led --group upstairs led on
unifi-led --device device_id_3 led off

Definiere Gruppen in groups.json oder nutze --device für spezifische Geräte.

Konfiguration

Alle Einstellungen liegen in einer einzigen .env. Kopiere .env.example und trage deine Werte ein.

Variable	Pflicht	Standard	Beschreibung
UNIFI_USER	Ja	—	Lokaler UniFi-Benutzername (ohne 2FA)
UNIFI_PASS	Ja	—	UniFi-Passwort
UNIFI_CONTROLLER	Ja	—	Controller-URL (z. B. https://192.168.1.1)
UNIFI_DEVICE_ID	Ja	—	Geräte-ID (komma-separiert für mehrere)
UNIFI_SITE	Nein	default	UniFi-Site-Name
UNIFI_VERIFY_SSL	Nein	false	Auf true setzen bei gültigen SSL-Zertifikaten
UNIFI_TIMEOUT	Nein	10	HTTP-Request-Timeout in Sekunden

Für mehrere Geräte setze UNIFI_DEVICE_ID auf eine komma-separierte Liste. Jedes Gerät erhält eigene Konfigurationsdateien.

Definiere Gerätegruppen in einer groups.json Datei und nutze --group upstairs.