AMAD

AMAD
Zweck / Funktion
Steuern von Adroidgeräten und Anzeige von bestimmten Informationen dieser Geräte
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE
Support (Forum)	Unterstützende Dienste
Modulname	74_AMAD.pm
Ersteller	CoolTux (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Vorwort

Warum AMAD2

Bei der Entwicklung von AMAD musste ich auf Grund meines damaligen Wissenstandes ein einfaches Konzept zum erhalt von Daten wählen. Hierfür wählte ich das Prinzip des pullens. Die Daten wurden alle 3 min vom Gerät angefordert. Mit AMAD2, also der 2. Version von AMAD werden die Daten nun vom Androidgerät selbst nach FHEM gepusht. So kommen Statusänderungen quasi in Echtzeit als Reading ins Device.

Vorstellung

Dieses Modul liefert, in Verbindung mit der Android APP Automagic, diverse Informationen von Android Geräten. Die AndroidAPP Automagic (welche nicht von mir stammt und 2.90 Euro kostet) funktioniert wie Tasker, ist aber bei weitem User freundlicher.

Features / Funktionen

Im Auslieferiungszustand werden folgende Zustände dargestellt:

• installierte Android Version
• Zustand von Automagic auf dem Gerät
• Spracheingabe
• Bluetooth An/Aus
• Zustand einer definierten App (läuft aktiv im Vordergrund oder nicht?)
• verbundene Bluetoothgeräte, inklusive deren MAC Adresse
• aktuell abgespieltes Musikalbum des verwendeten Mediaplayers
• aktuell abgespielter Musikinterpret des verwendeten Mediaplayers
• aktuell abgespielter Musiktitel des verwendeten Mediaplayers
• Status des Androidgerätes - Online/Offline
• nächster Alarmtag
• nächste Alarmzeit
• Batteriestatus in %
• Ladestatus - Netztei angeschlossen / nicht angeschlossen
• Bildschirmstatus An/Aus
• Bildschirmhelligkeit
• Vollbildmodus An/Aus
• Bildschirmausrichtung Auto/Landscape/Portrait
• Standardlautstärke
• Media Lautstärke
• ...

Mit etwas Einarbeitung können jegliche Informationen welche Automagic bereit stellt in FHEM angezeigt werden. Hierzu bedarf es lediglich eines eigenen Flows welcher seine Daten an die AMADCommBridge sendet. Das Modul gibt auch die Möglichkeit Androidgeräte zu steuern.

Das Modul gibt Dir auch die Möglichkeit Deine Androidgeräte zu steuern. So können folgende Aktionen durchgeführt werden:

• Bluetooth Ein/Aus schalten
• zu einem bestimmten Bluetoothgerät wechseln/verbinden
• Status des Gerätes (Online,Offline)
• Mediaplayer steuern (Play, Stop, nächster Titel, vorheriger Titel)
• nächste Alarmzeit setzen
• ein Benachrichtigungston abspielen (Notificationsound)
• eine App auf dem Gerät öffnen
• eine URL im Browser öffnen
• Bildschirm An/Aus machen
• Bildschirmhelligkeit einstellen
• Vollbildmodus einschalten
• eine Nachricht senden welche am Bildschirm angezeigt wird
• Bildschirmausrichtung einstellen (Auto,Landscape,Portrait)
• neuen Statusreport des Gerätes anfordern
• Systembefehle setzen (Reboot)
• eine Nachricht senden welche angesagt wird (TTS)
• Medienlautstärke regeln
• ...

Hinweise zum Betrieb mit Fhem

Für all diese Aktionen und Informationen wird auf dem Androidgerät Automagic und ein so genannter Flow benötigt. Die App Automagic Premium könnt Ihr Euch aus dem App Store installieren, die Flows bekommt Ihr aus dem Flowset 74_AMADautomagicFlowset$VERSION.xml unter $FHEMINSTALL/FHEM/lib/

AutomagicApp Anweisung

• installiert die App
• installiert das Flowset 74_AMADautomagicFlowset$VERSION.xml aus dem Ordner $INSTALLFHEM/FHEM/lib/ auf Eurem Androidgerät. NOCH NICHT die Flows aktivieren

Definition

define <name> AMAD <IP-ADRESSE>

!!! Wichtig - Es dürfen ausschließlich nur IP Adressen verwendet werden, keine FQDN !!!

Beispiel:

define WandTabletWohnzimmer AMAD 192.168.0.23

Diese Anweisung erstellt zwei neues AMAD-Device im Raum AMAD.Der Parameter <IP-ADRESSE> legt die IP Adresse des Android Gerätes fest. Das zweite Device ist die AMADCommBridge welche als Kommunikationsbrücke vom Androidgerät zu FHEM diehnt. !!!Comming Soon!!! Wer den Port ändern möchte, kann dies über das Attribut "port" tun. Ihr solltet aber wissen was Ihr tut, da dieser Port im HTTP Request Trigger der beiden Flows eingestellt ist. Demzufolge muß der Port dort auch geändert werden. Der Port für die Bridge kann ohne Probleme im Bridge Device mittels dem Attribut "port" verändert werden. Der Port für die Bridge kann ohne Probleme im Bridge Device mittels dem Attribut "port" verändert werden.

AMAD Communication Bridge

Beim ersten anlegen einer AMAD Deviceinstanz wird automatisch ein Gerät Namens AMADCommBridge im Raum AMAD angelegt. Dieses Gerät diehnt zur Kommunikation vom Androidgerät zu FHEM ohne das zuvor eine Anfrage von FHEM aus ging. Damit das Androidgerät die IP von FHEM kennt, muss diese sofort nach dem anlegen der Bridge über den set Befehl in ein entsprechendes Reading in die Bridge geschrieben werden. DAS IST SUPER WICHTIG UND FÜR DIE FUNKTION DER BRIDGE NOTWENDIG. Bitte führt hierzu folgenden Befehl aus. set AMADCommBridge fhemServerIP <FHEM-IP>. Als zweites Reading könnt Ihr expertMode setzen. Mit diesem Reading wird eine unmittelbare Komminikation mit FHEM erreicht ohne die Einschränkung über ein Notify gehen zu müssen und nur reine set Befehle ausführen zu können.

JETZT bitte die Flows AKTIVIEREN!!!

Fertig! Nach anlegen der Geräteinstanz und dem eintragen der fhemServerIP in der CommBridge sollten nach spätestens 15 Sekunden bereits die ersten Readings reinkommen. Nun wird alle 15 Sekunden probiert einen Status Request erfolgreich ab zu schließen. Wenn der Status sich über einen längeren Zeitraum nicht auf "activ" ändert, sollte man im Log nach eventuellen Fehlern suchen.

Es gibt die Möglichkeit einer Abfragen vom Status jeglicher Geräte in FHEM über das Androidgerät und Auswertung auf dem Androidgerät.

Beispiel: Erstelle einen Flow mit einer HTTP Request Aktion mit folgendem Inhalt

URL http://{global_fhemip}:8090

REQUEST METHODE POST

CONTENT TYP Genereller Text text/plain

DATEN (hier kommen die drei Werte für ein ReadingsVal Aufruf rein, getrennt durch Leerzeichen) TempFeuchtSensorSchlafzimmer temperature 300

(haken)Setze eigenen Header FHEMDEVICE: {global_fhemdevice} FHEMCMD: readingsval

SPEICHERE ANTWORT ... Variable

VARIABLE response

Du erhälst dann den Rückgabewert in der Response Variablen. Diesen kannst Du dann innerhalb Deines Flows weiter verarbeiten. Z.B. Ansagetext.

Readings

• airplanemode - Status des Flugmodus
• androidVersion - aktuell installierte Androidversion
• automagicState - Statusmeldungen von der AutomagicApp (Voraussetzung Android >4.3). Wer ein Android >4.3 hat und im Reading steht "wird nicht unterstützt", muß in den Androideinstellungen unter Ton und Benachrichtigungen -> Benachrichtigungszugriff ein Haken setzen für Automagic
• bluetooth on/off - ist auf dem Gerät Bluetooth an oder aus
• checkActiveTask - Zustand einer zuvor definierten APP. 0=nicht aktiv oder nicht aktiv im Vordergrund, 1=aktiv im Vordergrund, siehe Hinweis unten
• connectedBTdevices - eine Liste der verbundenen Gerät
• connectedBTdevicesMAC - eine Liste der MAC Adressen aller verbundender BT Geräte
• currentMusicAlbum - aktuell abgespieltes Musikalbum des verwendeten Mediaplayers
• currentMusicApp - aktuell verwendeter Mediaplayers
• currentMusicArtist - aktuell abgespielter Musikinterpret des verwendeten Mediaplayers
• currentMusicTrack - aktuell abgespielter Musiktitel des verwendeten Mediaplayers
• daydream - on/off Daydream gestartet oder nicht
• deviceState - Status des Androidgerätes / unknown, online, offline
• doNotDisturb - aktueller Status des nicht stören Modus
• dockingState - undocked/docked Status ob das Gerät in einer Dockinstation ist oder nicht.
• flow_SetCommands - active/inactive, gibt den Status des SetCommands Flow wieder
• flow_informations - active/inactive, gibt den Status des Informations Flow wieder
• flowsetVersionAtDevice - aktuell installiertes Flowset auf dem Device
• intentRadioName - zu letzt eingestellter Intent Radio Name
• intentRadioState - Status des IntentRadio Players
• keyguardSet - 0/1 Displaysperre gesetzt 0=nein 1=ja, bedeutet nicht das sie gerade aktiv ist
• lastSetCommandError - letzte Fehlermeldung vom set Befehl
• lastSetCommandState - letzter Status vom set Befehl, Befehl erfolgreich/nicht erfolgreich gesendet
• lastStatusRequestError - letzte Fehlermeldung vom statusRequest Befehl
• lastStatusRequestState - letzter Status vom statusRequest Befehl, Befehl erfolgreich/nicht erfolgreich gesendet
• nextAlarmDay - aktiver Alarmtag
• nextAlarmState - aktueller Status des Androidinternen Weckers
• nextAlarmTime - aktive Alarmzeit
• powerLevel - Status der Batterie in %
• powerPlugged - Netzteil angeschlossen? 0=NEIN, 1|2=JA
• screen - on locked/unlocked, off locked/unlocked zeigt an ob der Bildschirm an oder aus ist und gleichzeitig gesperrt oder nicht gesperrt
• screenBrightness - Bildschirmhelligkeit von 0-255
• screenFullscreen - Vollbildmodus (On,Off)
• screenOrientation - (Landscape,Portrait) Bildschirmausrichtung
• screenOrientationMode - (auto, manual) Modus für die Ausrichtung
• state - aktueller Status des Devices
• volume - Media Lautstärkewert
• volumeNotification - Benachrichtigungs Lautstärke

Beim Reading checkActivTask muß zuvor der Packagename der zu prüfenden App als Attribut checkActiveTask angegeben werden. Beispiel: attr Nexus10Wohnzimmer checkActiveTask com.android.chrome für den Chrome Browser.

Befehle

Set

• activateVoiceInput - schaltet die Spracheingabe ein
• bluetooth - Schaltet Bluetooth on/off
• clearNotificationBar - (All,Automagic) löscht alle Meldungen oder nur die Automagic Meldungen in der Statusleiste
• currentFlowsetUpdate - fürt ein Flowset Update auf dem Device aus
• deviceState - setzt den Device Status Online/Offline. Siehe Readings
• installFlowSource - installiert einen Flow auf dem Device, das XML File muss unter /tmp/ liegen und die Endung xml haben. Bsp: set TabletWohnzimmer installFlowSource WlanUebwerwachen.xml
• doNotDisturb - schaltet den nicht stören Modus, always immer Stören, never niemals stören, alarmClockOnly nur Wecker darf stören, onlyImportant nur wichtige Störungen
• mediaPlayer - steuert den Standard Mediaplayer. play, stop, Titel zürück, Titel vor.
• nextAlarmTime - setzt die Alarmzeit. Geht aber nur innerhalb der nächsten 24Std.
• notifySndFile - spielt die angegebende Mediadatei auf dem Androidgerät ab. Die aufzurufende Mediadatei muß sich im Ordner /storage/emulated/0/Notifications/ befinden.
• screenBrightness - setzt die Bildschirmhelligkeit, von 0-255.
• screenMsg - versendet eine Bildschirmnachricht
• sendintent - sendet einen Intentstring Bsp: set $AMADDEVICE sendIntent org.smblott.intentradio.PLAY url http://stream.klassikradio.de/live/mp3-192/stream.klassikradio.de/play.m3u name Klassikradio, der erste Befehl ist die Aktion un der zweite das Extra. Es können immer zwei Extras mitgegeben werden.
• statusRequest - Fordert einen neuen Statusreport beim Device an. Es können nicht von allen Readings per statusRequest die Daten geholt werden. Einige wenige geben nur bei Statusänderung ihren Status wieder.
• timer - setzt einen Timer innerhalb der als Standard definierten ClockAPP auf dem Device. Es können nur Sekunden angegeben werden.
• ttsMsg - versendet eine Nachricht welche als Sprachnachricht ausgegeben wird
• vibrate - lässt das Androidgerät vibrieren
• volume - setzt die Medialautstärke. Entweder die internen Lautsprecher oder sofern angeschlossen die Bluetoothlautsprecher und per Klinkenstecker angeschlossenen Lautsprecher, + oder - vor dem Wert reduziert die aktuelle Lautstärke um den Wert
• volumeNotification - setzt die Benachrichtigungslautstärke.

Set abhängig von gesetzten Attributen

• changetoBtDevice - wechselt zu einem anderen Bluetooth Gerät. Attribut setBluetoothDevice muß gesetzt sein. Siehe Hinweis unten!
• openApp - öffnet eine ausgewählte App. Attribut setOpenApp
• openURL - öffnet eine URL im Standardbrowser, sofern kein anderer Browser über das Attribut setOpenUrlBrowser ausgewählt wurde. Bsp: attr Tablet setOpenUrlBrowser de.ozerov.fully|de.ozerov.fully.MainActivity, das erste ist der Package Name und das zweite der Class Name
• screen - on/off/lock/unlock schaltet den Bildschirm ein/aus oder sperrt/entsperrt ihn, in den Automagic Einstellungen muss "Admin Funktion" gesetzt werden sonst funktioniert "Screen off" nicht. Attribut setScreenOnForTimer ändert die Zeit wie lange das Display an bleiben soll!
• screenFullscreen - Schaltet den Vollbildmodus on/off. Attribut setFullscreen
• screenLock - Sperrt den Bildschirm mit Pinabfrage. Attribut setScreenlockPIN - hier die Pin dafür eingeben. Erlaubt sind nur Zahlen. Es müßen mindestens 4 bis max 16 Zeichen sein.
• screenOrientation - Schaltet die Bildschirmausrichtung Auto/Landscape/Portait. Attribut setScreenOrientation
• setAPSSID - setzt die Acces Point SSID um WLAN Sleeps zu verhindern
• setTtsMsgSpeed - setzt die Sprachgeschwindigkeit bei der Sprachausgabe (Werte zwischen 0.5 bis 4.0 in 0.5er Schritten) default ist 1.0
• setTtsMsgLang - setzt die Sprache der Sprachausgabe, (de-Deutsch - en Englisch) default ist de
• system - setzt Systembefehle ab (nur bei gerootetet Geräen). reboot,shutdown,airplanemodeON (kann nur aktiviert werden) Attribut root, in den Automagic Einstellungen muss "Root Funktion" gesetzt werden
• setNotifySndFilePath - setzt den korrekten Systempfad zur Notifydatei (default ist /storage/emulated/0/Notifications/

Um openApp verwenden zu können, muss als Attribut der Package Name der App angegeben werden.

Um zwischen Bluetoothgeräten wechseln zu können, muß das Attribut setBluetoothDevice mit folgender Syntax gesetzt werden. attr <DEVICE> BTdeviceName1|MAC,BTDeviceName2|MAC Es muss zwingend darauf geachtet werden das beim BTdeviceName kein Leerzeichen vorhanden ist. Am besten zusammen oder mit Unterstrich. Achtet bei der MAC darauf das Ihr wirklich nach jeder zweiten Zahl auch einen : drin habt Beispiel: attr Nexus10Wohnzimmer setBluetoothDevice Logitech_BT_Adapter|AB:12:CD:34:EF:32,Anker_A3565|GH:56:IJ:78:KL:76

STATE

• initialized - Ist der Status kurz nach einem define..
• active - die Geräteinstanz ist im aktiven Status.
• disabled - die Geräteinstanz wurde über das Attribut disable deaktiviert

deviceState

• online - Das Gerät ist online und kann set Befehle entgegennehmen.
• offline - Ein Gerät wird in den folgenden 3 Szenarien in den Status offline gesetzt:
  • Das Gerät wird mittels shutdown über FHEM runtergefahren.
  • Der Airplainmod (Flugmodus) wird über FHEM aktiviert.
  • Es wurde mehr als 5 mal ein statusRequest erfolglos und mehr als 3 mal ein set Command erfolglos abgeschickt.

Es bleibt also dem User überlassen das Gerät nach erneuter Verfügbarkeit wieder in den Status online zu setzen. Das kann z.B. über das Presence Modul erzeugt werden (set DEVICE deviceState online)

Anwendungsbeispiele

Lademanagement

Ich habe die Ladegeräte für meine Androidgeräte an Funkschaltsteckdosen. ein DOIF schaltet bei unter 30% die Steckdose ein und bei über 90% wieder aus.

Hier mal ein einfaches DOIF Beispiel für ein Lademanagment

... DOIF ([Nexus5Handy:powerLevel] < 30) (set LadenetzteilNexus5Handy:FILTER=STATE=off on) DOELSEIF ([Nexus5Handy:powerLevel] > 90) (set LadenetzteilNexus5Handy:FILTER=STATE=on off) DOELSE

Wecker

Morgens lasse ich mich über mein Tablet im Schlafzimmer mit Musik wecken. Verwendet wird hierzu der wakeuptimer des RESIDENTS Modules. Das abspielen stoppe ich dann von Hand. Danach erfolgt noch eine Ansage wie das Wetter gerade ist und wird.

Mediacenter

Mein 10" Tablet im Wohnzimmer ist Mediaplayer für das Wohnzimmer mit Bluetoothlautsprechern. Die Lautstärke wird automatisch runter gesetzt wenn die Fritzbox einen Anruf auf das Wohnzimmer Handgerät signalisiert.

Sprachbefehl - Abfragen von Zuständen diverser Sensoren

Wenn ich die Spracheingabe aktiviere und nach der Temperatur im Wohnzimmer frage, bekomme ich diese angesagt.

Der Teil im Feld Daten ist ein klassisches RadingsVal, halt nur ohne Komma und ohne Anführungszeichen

WIRD GERADE ÜBERARBEITET

Schaltbefehle vom Androidgerät an FHEM senden

Hierfür richte bitte einen eigen Flow ein. Wie das genau geht, verrät Dir die Hilfe. Um einen Schaltbefehl für FHEM zu erstellen, folgt nach dem Trigger eine Aktion als Script (Aktion Type: Script). Hier trägst Du folgendes ein

setcmd = "LichtWohnzimmerLampeRechts on"

fhemcmd = "set"

In der ersten Zeile wird also der Schaltbefehl in der Variablem setcmd eingetragen und in der zweiten Zeile der FHEM Befehl in der Variablen fhemcmd.

Danach müsst Ihr nur noch in einer weiteren Aktion den Flow "Send Data to AMADCommBridge" ausführen (Aktion Type: Flows ausführen). Die Aktion sollte bereits in Eurer Liste Vorhanden sein.

Nun sollte Lampe1 angeschalten werden wenn der Flow ausgeführt wird.

Bekannte Meldungen/Hinweise/Probleme

PERL WARNING: Use of uninitialized value in hash element at /opt/fhem/FHEM/74_AMAD.pm line 14X Ist ab Version 2.2.2 gefixt. Dickes Danke an Andy(gandy)

Wenn auf dem Android-Gerät die Fehlermeldung 'Accessibility service not running' von Automagic kommt, oder im FHEM das reading state 'Flow Informations mit Fehler beendet' steht, dann muss der Accessibility Service auf dem Android-Device aktiviert werden: Einstellungen --> Bedienungshilfen --> Automagic Premium. Hier muss der Schalter auf 'an' stehen. Sollte dies der Fall sein, hilft u.U. ein kurzes Aus- und wieder Einschalten.

Gerät wird oft als offline angezeigt und es können keine set Befehle abgesetzt werden. Mit der AMAD Version 2.2 hielt eine neue Behandlung des deviceState Readings Einzug. Das Reading stellt nun den tatsächlichen Status des Gerätes gegenüber FHEM da. Bei vielen Android 6 Geräten kommt es aber auf Grund vom DeepSleep Modus zum wegfall der WLAN Verbindung. Hier hilft die neue KeepAlive Funktion in AMAD. Dafür muß lediglich unter

• Einstellungen --> Akku --> oben auf die drei Punkte - Akku Leistungsoptimierung --> alle Apps und dann Automagic auswählen und "Nicht optimieren"

ausgewählt werden. Alles andere macht das Modul selbst.

Ich sage Danke

Der größte Dank geht an meinen Mentor Andre (justme1968), er hat mir mit hilfreichen Tips geholfen Perlcode zu verstehen und Spaß am programmieren zu haben.

Auch möchte ich mich bei Jens bedanken (jensb) welcher mir ebenfalls mit hilfreichen Tips bei meinen aller ersten Gehversuchen beim Perlcode schreiben unterstützt hat.

So und nun noch ein besonderer Dank an pah (Prof. Dr. Peter Henning ), ohne seine Aussage "Keine Ahnung hatten wir alle mal, das ist keine Ausrede" hätte ich bestimmt nicht angefangen Interesse an Modulentwicklung zu zeigen :-)

Danke an Jürgen(ujaudio) und Andreas(scooty) die sich um die Übersetzung der Commandref ins Englische gekümmert haben

Danke auch an Ronny(RoBra81) für seine tollte Idee und Umsetzung von eigenen AMAD Readings aus externen Flows.