Unifi

Aus FHEMWiki
Wechseln zu: Navigation, Suche
Unifi
Zweck / Funktion
Steuerung des Unifi-Controllers über FHEM
Allgemein
Typ Gerätemodul
Details
Dokumentation EN / DE
Support (Forum) Automatisierung
Modulname 74_Unifi.pm
Ersteller Wuehler (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!


Das Modul Unifi ermöglicht die Steuerung eines Unifi-Controllers durch FHEM. Wenn durch den Unifi-Controller auch ein UnifiSwitch verwaltet wird, so legt das Modul bei aktiviertem autocreate UnifiSwitch-Devices an. Ausserdem gibt es das Unterstützungsmodul UnifiClient, welches alle vorhandenen Informationen zu Clients als Reading bereitstellt und clientspezifische Funktionen zur Verfügung stellt.

Voraussetzungen

Unifi-Controller

Es wird eine dauerhaft laufende Unifi-Controller-Software benötigt. Diese kann z.B. auf dem Unifi-Cloud-Key oder selbst installiert z.B. auf einem RaspberryPi laufen.

Definition

Die Definition erfolgt mittels define <name> Unifi <ip> <port> <username> <password> [<interval> [<siteID>]] . Dabei ist folgendes zu beachten:

  • ip: Der Unifi-Controller muss eine feste IP-Adresse haben
  • port: Port der Adminkonsole des Unifi-Controllers. In der Regel 8443 oder 443.
  • username/password: Username und Passwort eines Unifi-Controller-Users (siehe Unifi-User)
  • interval: Gibt die Zeit in Sekunden an, nach der das Modul erneut die Daten beim Unifi-Controller abfragt. Default: 30 Sekunden. Es ist darauf zu achten, dass das Intervall groß genug ist, so dass auch unter Last nicht vor Ende eines Update-Zyklus ein neuer Update-Zyklus gestartet wird. Dies kann zum Beispiel passieren, wenn FHEM und der Unifi-Controller auf demselben RaspberryPi laufen (interval dann zB auf 90 setzen).
  • siteID: Üblicherweise und als Default default

Damit ist die Installation abgeschlossen. Nach kurzer Zeit sollten die ersten Readings angezeigt werden.

Unifi-User

Bei der Definition des Moduls werden username und passwort mit angegeben. Entweder wird der standardmäßig angelegte Admin des Unifi-Controllers, oder besser ein im Unifi-Controller angelegter eigener User (unter settings-> admins -> add new admin) genutzt. Wenn ein neuer User angelegt wird kann dieser z.B. auch ausschließlich read-only-Berechtigungen bekommen. Dies reicht für die Grundfunktion des Unifi-Moduls )Informationen auslesen und in Readings darstellen) aus. Alle set-Funktionen (Ausnahmen: clear, update und updateClient) sowie das Attribut voucherCache benötigen schreibende Rechte im Unifi-Controller .

Anwendung

Readings

Details siehe Siehe commandref/Unifi

Attribut customClientReadings

Mit dem Attribut customClientReadings können die Readings für Clients individualisiert werden. Eine Liste der möglichen Readings erhält man mittels get <unifi> clientData all.

  • Der state eines clients kann nicht entfernt werden. D.h. für jeden client wird es ein Reading <clientName> geben, das entweder den Wert connected oder disconnected hat.
  • Es werden die Daten, die der Unifi-Controller zu den Clients vorhält 1:1 als Readings zur Verfügung gestellt.
  • Zusätzlich stehen mit dem Präfix _f_ versehen formatierte Werte als Reading zur Verfügung.
  • Wenn der Unifi-Controller einen Wert nicht liefert, so wird auch kein Reading angelegt, selbst wenn dies im Attribut customClientReadings explizit angegeben wird.

Bei der Verwendung des Attributes gibt es teilweise Abweichungen vom Standardverhalten, die bei einer nachträglichen Verwendung des Attributes ggf. berücksichtigt werden müssen:

  • Das Reading <clientName>_last_seen wird nicht als Datum formatiert dargestellt, sondern wie vom Unifi-Controller zurückgegeben als Unix-Timestamp.
  • Das Reading <clientName>_hostname kann ggf. auch fehlen. Ohne das Attribut customClientReadings wird bei fehlendem hostname die ip oder "unknown" angezeigt.
  • Das Reading <clientName>_snr entfällt und lautet <clientName>_rssi.

Beispiele:

  • .:^mac$ : Stellt für alle Clients zusätzlich ein Reading mit der mac-Adresse zur Verfügung
  • .:^mac$|^uptime$ : Stellt für alle Clients zusätzlich ein Reading mit der mac-Adresse und ein Reading mit der uptime (Unix-Timestamp) zur Verfügung
  • ^meinTelefon$:^mac$ : Stellt nur für den Client mit dem Namen "meinTelefon" ein zusätzliches Reading mit der mac-Adresse zur Verfügung
  • ^meinTelefon$:^mac$ ^seinTelefon$:^mac$ : Stellt nur für die Clients mit dem Namen "meinTelefon" oder "seinTelefon" ein zusätzliches Reading mit der mac-Adresse zur Verfügung
  • einTelefon$:^mac$ : Stellt für alle Clients, die auf "einTelefon" enden im Client-Namen haben die mac-Adresse zusätzlich zur Verfügung
  • .:uptime : Stellt für alle Clients zusätzlich einige Readings zur Verfügung, die "uptime" im Namen enthalten. Darunter sind auch formatierte uptimes.

Anwesenheitserkennung

Üblicherweise: siehe PRESENCE

Oder falls man einen UnifiClient definiert hat: define <NAME> PRESENCE event <UnifiClientName>:fhem_state:.disconnected <UnifiClientName>:fhem_state:.connected

Voucher

Das Modul kann automatisiert immer eine ausreichende Anzahl an Voucher-Nummern für den Zugang in ein per GuestPortal mit Voucherzugang konfiguriertes WLAN bereithalten. Dazu wird das Attribut voucherCache genutzt. Mit Komma separiert können mehrere Vouchercaches angegeben werden. Je Vouchercache werden vier Attribute mit Leerzeichen getrennt mitgegeben:

  • expire: Ablaufzeit des Vouchers in Minuten
  • quota: Anzahl der Voucher, die mindestens vorgehalten werden (sinnvoller Wert ist >=2)
  • n: Gibt an, wie oft ein einzelner Voucher genutzt werden kann (sinnvoll ist in der Regel der Wert 1)
  • note: der Name des Vouchers. Er darf keine Leerzeichen enthalten und kann z.B. bei einer Auswahl in ftui angezeigt werden.

Je Vouchercache wird ein Reading -VC_<note> mit dem nächsten noch nicht bzw. am längsten nicht angeforderten Voucher zur Verfügung gestellt. Wenn weniger als "quota"-Voucher zur Verfügung stehen werden "quota" neue Voucher erstellt. Die Maximalanzahl an vorgehaltenen Vouchern beträgt als 2*quota-1.

Voucherverwendung aufzeichnen

Dies geschieht außerhalb des Moduls mit einem dummy und wird in den weiteren Beispielen mit verwendet:

defmod voucherComment dummy
attr voucherComment event-on-change-reading comment
attr voucherComment readingList comment
attr voucherComment setList comment

Über eine ReadingsHistory kann dies festgehalten werden:

defmod voucherCacheRH readingsHistory voucherComment:comment
attr voucherCacheRH nolinks 1
attr voucherCacheRH rows 10
attr voucherCacheRH timestampFormat %Y.%m.%d_%H:%M:%S

Und/oder in einem Log speichern:

defmod voucherCommentLog FileLog ./log/voucher.log voucherComment:.*

Voucher bereitstellen

Die Beispiele gehen davon aus, dass auch die Verwendung aufgezeichnet werden soll.

über Telegram

Voraussetzung in diesem Beispiel ist, dass das Modul msgDialog eingerichtet ist und ein VoucherCache mit der note "2h" konfiguriert wurde:

defmod voucher_Dialog msgDialog {\
  "Voucher": {\
    "commands": [\
      "{fhem('set voucherComment comment '.ReadingsVal('Unifi','-VC_2h','').' (2h): $recipient')}"\
    ],\
    "message": "{return('Code: '.fhem('get Unifi voucher 2h'))}"\
  }\
}
in FTUI

Im head der Seite wird folgender code benötigt:

 
<script>
  var oldcode=0;
  function setComment(){
    var code =document.getElementById('voucherCode').children[0].value;
    if(oldcode!=code){
      oldcode=code;
      ftui.sendFhemCommand('get Unifi voucher ' + document.getElementById('voucherCacheNote').children[0].children[0].options.item(document.getElementById('voucherCacheNote').children[0].children[0].selectedIndex).text);     
      ftui.sendFhemCommand('set voucherComment comment ' + code +' ('+document.getElementById('voucherCacheNote').children[0].children[0].options.item(document.getElementById('voucherCacheNote').children[0].children[0].selectedIndex).text+'): '+document.getElementById('comment').children[0].value);
    }
  }
</script>

Im body der Seite kann der folgende code verwendet werden. Es wird vorausgesetzt, dass es Vouchercaches mit der note 2h und 3h gibt.

FTUI-Darstellung
 
<li data-row="18" data-col="1" data-sizex="2" data-sizey="3" class="semitransparent">
  <header>Voucher</header>
  Typ:
  <div data-type="select" data-items='["-VC_2h","-VC_3h"]' data-alias='["2h","3h"]' id="voucherCacheNote" class="notransmit w3x"></div>
  Kommentar:
  <div data-type="input"
    id="comment"
    class="notransmit"></div>
  Code: 
  <div data-type="input"
    data-device="Unifi"  
    data-get="#voucherCacheNote"
    id="voucherCode"
    class="notransmit w3x"></div>
  <div data-type="link"
    class="round notransmit"
    onclick="setComment()">
   Save</div>
</li>

Erkennung neuer clients

Kleines DOIF mit Telegram-Benachrichtigung:

defmod di_newClients DOIF ([Unifi:-UC_newClients] ne "" ) (set Telegram message unbekannter WLAN Zugriff:[Unifi:-UC_newClients])

FAQ

Warum enthält die DropDown-Liste einiger set-/get-Funktionen nicht alle Clients?

Vom UnifiController werden nur die Geräte mitgesendet, die connected sind / die im UnifiController auf der Seite Clients angezeigt werden. Clients, die connected waren, es aber nicht mehr sind - im UnifiController auf der Seite Insights - werden vom Modul aktuell nicht ausgelesen. Edit: Seid März 2019 wird versucht auch disconnected clients nach einem Neustart aus den Readings wiederherzustellen. Damit sollten die clients in den DropDowns vollständig sein.