igloohome Smart-Home-Integration, kostenlos und Open Source

igloohome locks, padlocks and key boxes via the igloohome API: battery, sync, bridge lock.

• Veröffentlicht von LM1LC3N7
• Geräte
• Version 0.1.1
• Erfordert Gladys >=5.1.0
• ★ 0

Auf GitHub ansehenAlle Integrationen

Info

Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.

This integration brings the igloohome devices of your account (locks, padlocks, key boxes, keypads) into Gladys through the official igloohome API (igloodeveloper), the one Home Assistant uses.

Unofficial integration, not affiliated with igloohome.

Never tested with a real device nor a real account: only against a fake igloohome server in the tests. Your feedback is welcome.

What you get

For each device of the account (the bridges are not shown):

• Battery (%), when igloohome gives it;
• Hours since the last sync: the age of the last sync of the device with igloohome (handy for a "lock silent for 48 h" scene).

And for a lock linked to a bridge:

• a Lock button (always allowed);
• an Unlock button (off by default, see below);
• Last command: what igloohome says of the job of the last command ("accepted, waiting for the bridge", "job processed by the bridge (result not read)", "igloohome says the job expired", "result unknown"…).

igloohome gives no locked/unlocked state for a lock: the integration does not invent one (Home Assistant shows an assumed state).

What you need

1. One or more igloohome locks paired in the igloohome app, and an igloohome bridge to command them (without a bridge: battery and sync only).
2. An API client created in the iglooaccess portal (an offer mostly aimed at businesses): it gives a client id and a client secret. The client needs the scopes get-devices, lock-bridge-proxied-job and get-job-status. The unlock-bridge-proxied-job right is needed only if you allow unlocking; without it, igloohome itself refuses every unlock (the rest works, the status says so). igloohome may bill the use of the API (for instance per active device and per month): check the terms of your offer.

Configuration

• Client id and Client secret: those of the API client. The secret is kept by Gladys in its database, never shown again, sent only to igloohome (auth.igloohome.co) to get an access token. The token stays in the memory of the container, never written to disk.
• Allow unlocking the locks from Gladys: off by default. On, a scene, a dashboard or a voice assistant connected to Gladys can open your door. The token carries the unlock right only while the option is on (a new token is asked when you change it).
• Refresh interval: 900 s (15 min) by default, from 300 s to 86,400 s. One request per read for the whole account.
• Language of the feature names.

Save, then add the devices from the Discovery tab.

The commands and their safety

igloohome commands a lock through its bridge, as a "job" the bridge runs later (it takes about 2 a minute). A job igloohome has accepted cannot be cancelled, and the order in which the bridge runs the jobs is not guaranteed.

• Unlock is refused while the option is off; the option is checked again on arrival, after the read and right before sending. Before acting, the device list is read again from igloohome: the lock must still be in it, as a lock, linked to a bridge. One unlock at a time per lock; none while the job of the previous one is watched (until its end, 15 min at most, kept across a restart); none within 30 s of another job on the same bridge.
• Lock is never blocked: no read before, no queue, one try even during a pause asked by igloohome or a stop, and possible right after a restart (the bridge of each lock is kept in /data). It cancels at once every unlock of that lock not sent yet.
• A command leaves within 3.5 s of your click, or is refused without sending anything. It is never answered done: a job accepted by igloohome is "Command sent, without confirmation". Its status is then read (5, 15, 30, 60, 100, 140 s, then every minute) until igloohome says it was processed, or expired (igloohome's own time, the Date header of its answer, past the expiry date: never the clock of Gladys), or 15 min at most (then "result unknown: check the lock"). What igloohome says of the result of a processed job is not read yet (unknown form): check the lock.
• When an unlock sent before a lock is processed too, whatever the order, Last command says so until the next command (a restart included): check the lock and press Lock again (never resent by itself).
• The buttons are never switches: a "turn everything off" of a voice assistant or a scene cannot reach them.

Errors and rate limits

• Credentials refused or rights missing (any refusal of the token endpoint but 429/5xx): a final stop kept in /data, no automatic new try. Saving other credentials lifts it, or a success of the Test the connection button (which tries once).
• HTTP 429 or 5xx: a pause of 1 min to 6 h kept in /data (locking still gets one try). A 5xx on the status of a job only skips that read.
• Other errors: a new try at the interval (5 min at least). The test button (unless read less than an interval ago), the Discovery tab, a reconnection to Gladys or a restart never read sooner than the interval.
• After a restart, the last successful read kept in /data gives the Discovery tab at once, and the "connected" status and the badges when the last read before the restart succeeded (else the status says so), until the next read (its values are not republished as new). A command whose watch ended while stopped shows "result unknown".

What is kept in /data

The file igloohome-state.json (readable by the container user only) keeps: the pauses, the stops (with the salted fingerprint of refused credentials, never of good ones), the time of the last read and of the last success, a bounded summary of the device list (names, types, battery, sync, bridge), the igloohome ids of the locks and their bridges, the jobs watched and the unlock guards (written right after sending). Never the secret nor the token.

Known limits

• No locked/unlocked state (the API gives none without a bridge job), no access log nor PIN code in this version.
• Only the first page of the device list is read (a message says so when igloohome gives more).
• The exact meaning of a "processed" job (succeeded, or only ended) and its life are still to be checked on a real account.

Credits

Logic ported from igloohome-api (MIT) and from the igloohome integration of Home Assistant (Apache-2.0): see THIRD_PARTY_NOTICES.md.

Konfigurationseinstellungen

Diese Einstellungen fragt igloohome in seinem Konfigurationsbildschirm in Gladys ab.

Einstellung	Typ	Pflichtfeld	Beschreibung
Your iglooaccess API client	section	Nein	Brings the igloohome devices of your account into Gladys through the official igloohome API (igloodeveloper): battery and hours since the last sync of each lock, padlock, key box or keypad; for a lock linked to a bridge, Lock and Unlock buttons and the result of the last command. Needs an API client (client id and secret) created in the iglooaccess portal, which igloohome may bill. Read every 15 minutes by default. Locking is always allowed; unlocking stays off until you allow it below. igloohome gives no locked/unlocked state. Never tested with a real device. Not affiliated with igloohome.
Client id	string	Ja
Client secret	secret	Ja	Kept by Gladys in its database, never shown again, sent only to igloohome (auth.igloohome.co) to get a token.
Allow unlocking the locks from Gladys	boolean	Nein	Off by default: Gladys can lock, never unlock. On, a scene, a dashboard or a voice assistant connected to Gladys can open your door.
Refresh interval (s)	number	Nein	Seconds between two reads of the device list (300 to 86400). The battery and the sync change slowly.
Language of the feature names	select	Nein	Used for the feature names of the devices added from now on, and for the last command.

So installierst du igloohome in Gladys

1. Öffne in Gladys Integrationen: igloohome erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/lm1lc3n7/gladys-igloohome:0.1.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/LM1LC3N7/gladys-igloohome.

igloohome 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

igloohome 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 LM1LC3N7 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

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂