Pangolin Smart-Home-Integration, kostenlos und Open Source
Überwache Pangolin-Standorte und -Ressourcen und schalte Ressourcen aus Gladys ein oder aus.
Veröffentlicht von prohand
- Geräte
- Version 0.0.1
- Erfordert Gladys >=5.1.0
- ★ 0
Diese Integration verbindet Gladys mit Pangolin, dem Tunnel-Reverse-Proxy, der deine Dienste im Internet erreichbar macht, ohne einen Port am Router zu öffnen. Sie funktioniert mit einem selbst gehosteten Pangolin ebenso wie mit Pangolin Cloud.
Was du in Gladys bekommst:
- ein Gerät pro Standort (ein Newt-Tunnel, ein WireGuard-Standort, der Pangolin-Host selbst), mit seinem Online-Zustand und seinem Datenverkehr (eingehende Daten, ausgehende Daten);
- ein Gerät pro öffentlicher Ressource (eine HTTPS-Seite auf deiner Domain, ein roher TCP/UDP-Port), mit einem Aktiviert-Schalter, den du aus Gladys ausschalten kannst, und ihrem Zustand;
- Szenen-Auslöser, Szenen-Aktionen und ein Dashboard-Widget (Gladys 5.1 oder neuer).
Bevor du beginnst
1. Die Integrations-API aktivieren (nur selbst gehostet)
Pangolin Cloud hat sie bereits. Bei einem selbst gehosteten Pangolin
(Community Edition) ist die Integrations-API standardmäßig aus: Füge dies in
config/config.yml ein und starte Pangolin neu.
flags:
enable_integration_api: true
Die API lauscht dann im Pangolin-Container auf Port 3003 (oder 3004,
je nach Version: Sieh in deiner Konfiguration unter
server.integration_port nach). In der
Pangolin-Dokumentation
steht, wie du sie auf einer Domain wie https://api.example.com/v1
veröffentlichst.
2. Einen API-Schlüssel erstellen
Öffne in Pangolin deine Organisation, dann API-Schlüssel → API-Schlüssel generieren. Gib ihm diese Berechtigungen:
| Berechtigung | Wofür |
|---|---|
| Standorte auflisten | die Standort-Geräte |
| Ressourcen auflisten | die Ressourcen-Geräte |
| Organisation abrufen | den Namen, den „Verbindung testen“ anzeigt (optional) |
| Ressource aktualisieren | eine Ressource aus Gladys ein- oder ausschalten (optional) |
Kopiere den Schlüssel sofort: Pangolin zeigt ihn nur einmal an. Er sieht so
aus: abc123xyz.0123456789abcdef.
Verwende einen eigenen Organisations-Schlüssel für Gladys, nie einen Root-Schlüssel.
3. Die Organisations-ID finden
Sie steht in der Adressleiste, wenn du deine Organisation in Pangolin
aufrufst: https://pangolin.example.com/meine-org/settings → meine-org.
Konfiguration
| Feld | Was eintragen |
|---|---|
| Lokale API-Adresse | Nur selbst gehostet: die Integrations-API in deinem Netzwerk, z. B. http://192.168.1.10:3004/v1. Sonst leer lassen. |
| Internet-API-Adresse | Pangolin Cloud: https://api.pangolin.net/v1. Selbst gehostet: ihre öffentliche Adresse, z. B. https://api.example.com/v1. |
| API-Schlüssel | Der oben erstellte Schlüssel. |
| Organisations-ID | Die oben gefundene ID. |
| Aktualisierungsintervall (s) | Wie oft Pangolin gelesen wird (30 bis 3600 s, standardmäßig 60). Jede Abfrage sind zwei Anfragen, unabhängig von der Anzahl der Geräte. |
Trage mindestens eine der beiden Adressen ein. /v1 wird ergänzt, falls du
es vergisst.
Drücke dann Verbindung testen: Es probiert jede eingetragene Adresse und sagt für jede, was Pangolin geantwortet hat — die Organisation, die Anzahl der Standorte und Ressourcen oder den Grund des Fehlers.
Lokal oder Internet: der Schalter „Lokale Verbindung bevorzugen“
Sind beide Adressen eingetragen, ruft Gladys die auf, auf die der Schalter Lokale Verbindung bevorzugen zeigt, und weicht nur dann auf die andere aus, wenn die erste nicht antwortet (Netzwerk weg, Zeitüberschreitung, ein Proxy, der 502, 503 oder 504 antwortet). Ein falscher Schlüssel oder eine unbekannte Organisation lösen keinen Wechsel aus: Beide Adressen führen zum selben Server, und die Antwort wäre dieselbe.
Jedes Gerät zeigt die verwendete Adresse auf seinem Badge: lokal, Cloud oder nicht erreichbar. Ein oranger Punkt heißt, dass Gladys die Ausweichadresse nutzt: Es funktioniert, aber nicht so, wie du es wolltest — prüfe die bevorzugte Adresse.
Mit nur einer Adresse gibt es keine Ausweichadresse: Das Badge zeigt diese Adresse oder „nicht erreichbar“.
Geräte
Öffne den Tab Entdecken der Integration: Jeder Standort und jede öffentliche Ressource der Organisation ist dort aufgelistet. Lege in Gladys die an, die du möchtest.
Standort
| Funktion | Werte | Hinweise |
|---|---|---|
| Online | 1 = Tunnel aktiv, 0 = Tunnel getrennt | Fehlt bei einem „lokalen“ Standort: Pangolin meldet keinen Zustand |
| Data in | Megabyte | Zähler von Pangolin, bis du ihn dort zurücksetzt |
| Data out | Megabyte | Ebenso |
Öffentliche Ressource
| Funktion | Werte | Hinweise |
|---|---|---|
| Enabled | 1 = bereitgestellt, 0 = deaktiviert | Steuerbar: Ausschalten lässt Pangolin die Ressource nicht mehr bereitstellen, ohne sie zu löschen |
| Healthy | 1 = fehlerfrei, 0 = gestört | Ergebnis der Zustandsprüfungen ihrer Ziele. Leer, wenn die Ressource keine Zustandsprüfung hat |
Private Ressourcen (die über einen Pangolin-Client erreicht werden) werden nicht abgedeckt.
Die Geräte behalten ihre Identität, wenn du einen Standort oder eine Ressource in Pangolin umbenennst: Sie hängen an den internen Nummern von Pangolin, nicht an Namen oder Domains. Ein in Pangolin gelöschter Standort oder eine gelöschte Ressource erscheint nicht erreichbar: Du kannst das Gerät in Gladys löschen.
Szenen und Dashboard (Gladys 5.1)
Auslöser
| Auslöser | Filter | Variablen |
|---|---|---|
| Ein Pangolin-Standort geht online oder offline | Standort, neuer Status (online / offline) | site_name, status |
| Der Zustand einer Pangolin-Ressource ändert sich | Ressource, neuer Zustand | resource_name, address, health, previous_health |
| Pangolin antwortet nicht mehr oder wieder | neuer Status (antwortet / antwortet nicht) | status, reason, organization |
Sie lösen einmal pro Änderung aus, bei der Abfrage, die sie bemerkt — also innerhalb des Aktualisierungsintervalls. Beim Start oder nach einer Konfigurationsänderung löst nichts aus: „Der Standort ist offline“ ist in diesem Moment ein Zustand, kein Ereignis. Die Auslöser funktionieren auch für Standorte und Ressourcen, die du nicht als Geräte angelegt hast.
Verwende die Variablen in einer Szene wie alle anderen, z. B.
{{triggerEvent.data.site_name}} ist {{triggerEvent.data.status}}.
Aktionen
| Aktion | Felder | Ausgaben |
|---|---|---|
| Pangolin-Ressource aktivieren oder deaktivieren | Ressource, aktiviert | enabled |
| Pangolin jetzt aktualisieren | — | connected, sites_online, sites_offline, resources_unhealthy, resources_disabled |
Beispiel: Wenn alle das Haus verlassen, die Ressource „Kameras“ aktivieren; wenn die erste Person zurückkommt, sie deaktivieren.
Widget „Pangolin-Übersicht“
Füge es im Dashboard-Editor hinzu. Es zeigt:
- drei Kacheln: Standorte online, aktive Ressourcen, gestörte Ressourcen;
- die Verbindung (lokal, Internet, orange auf der Ausweichadresse, rot, wenn Pangolin nicht antwortet);
- die Probleme, die schwersten zuerst: Offline-Standorte, gestörte Ressourcen, deaktivierte Ressourcen — so viele, wie die Einstellung Aufgelistete Probleme angibt (0 bis 9);
- eine Schaltfläche Aktualisieren.
Fehlerbehebung
| Meldung | Was tun |
|---|---|
| Pangolin antwortet nicht (…) | Prüfe Adresse und Port und ob die Integrations-API aktiviert ist. Der Grund (ECONNREFUSED, Zeitüberschreitung…) hilft. |
| Pangolin hat den API-Schlüssel abgelehnt | Der Schlüssel ist falsch oder wurde gelöscht: Erstelle einen neuen. |
| Der API-Schlüssel darf die Organisation „…“ nicht lesen | Der Schlüssel gehört zu einer anderen Organisation oder ihm fehlt eine Berechtigung: siehe Einen API-Schlüssel erstellen. |
| Pangolin kennt keine Organisation „…“ | Prüfe die Organisations-ID und ob die Adresse die der API ist (endet auf /v1), nicht die des Dashboards. |
| Eine Ressource lässt sich nicht ausschalten | Dem Schlüssel fehlt Ressource aktualisieren. |
Die Protokolle der Integration nennen jede fehlgeschlagene Abfrage und jeden Wechsel auf die Ausweichadresse. Der API-Schlüssel erscheint nie darin.
Sicherheit
- Der API-Schlüssel wird in einem geheimen Feld gespeichert, nur an die von dir konfigurierten Adressen gesendet und nie protokolliert.
- Wer in Gladys einen Schalter betätigen oder eine Szene starten kann, kann deine öffentlichen Ressourcen öffnen oder schließen: Denk daran, wenn du Gladys teilst.
- Verwende für die Internetadresse
https://.
Konfigurationseinstellungen
Diese Einstellungen fragt Pangolin in seinem Konfigurationsbildschirm in Gladys ab.
| Einstellung | Typ | Pflichtfeld | Beschreibung |
|---|---|---|---|
| Erste Schritte | section | Nein | Gladys liest deine Pangolin-Organisation über ihre Integrations-API: ein Gerät pro Standort (online, Datenverkehr) und eines pro öffentlicher Ressource (aktiviert, fehlerfrei). Erstelle in Pangolin einen Organisations-API-Schlüssel (API-Schlüssel → API-Schlüssel generieren) mit den Berechtigungen Standorte auflisten, Ressourcen auflisten, Ressource aktualisieren und Organisation abrufen. Ein selbst gehosteter Server muss die Integrations-API aktiviert haben (flags: enable_integration_api: true). |
| Lokale API-Adresse | string | Nein | Die Integrations-API eines selbst gehosteten Pangolin, in deinem Netzwerk erreichbar (der Pangolin-Container lauscht je nach Version auf Port 3003 oder 3004). Leer lassen, wenn du nur die Internetadresse verwendest. |
| Internet-API-Adresse | string | Nein | Pangolin Cloud: https://api.pangolin.net/v1. Selbst gehostet: die öffentliche Adresse deiner Integrations-API, z. B. https://api.example.com/v1. Sind beide Adressen eingetragen, wählt der Schalter „Lokale Verbindung bevorzugen“ die zuerst versuchte; die andere springt ein, wenn sie nicht antwortet. |
| API-Schlüssel | secret | Ja | Der API-Schlüssel der Organisation, so wie Pangolin ihn einmalig bei der Erstellung anzeigt (Form: id.secret). |
| Organisations-ID | string | Ja | Die ID der Organisation, wie in der Adressleiste von Pangolin: /meine-org/settings → meine-org. |
| Aktualisierungsintervall (s) | number | Nein | Wie oft Pangolin gelesen wird, in Sekunden. Jede Abfrage sind zwei Anfragen, unabhängig von der Anzahl der Geräte. |
So installierst du Pangolin in Gladys
- Öffne in Gladys Integrationen: Pangolin erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
- Klicke auf Installieren. Gladys lädt das Docker-Image (
ghcr.io/prohand/gladys-pangolin:0.0.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration). - Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
- Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/prohand/gladys-pangolin.
Pangolin benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.
Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.
Über externe Integrationen
Pangolin ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von prohand veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.
- Alle Integrationen durchsuchen, native und aus der Community
- Deine eigene externe Integration bauen und veröffentlichen
- Quellcode auf GitHub — Quelle dieser Dokumentation