FHEMWiki - Benutzerbeiträge [de]

Modul Shelly

2025-10-23T20:48:38Z

Muschelpuster: /* Attribut webhook */ Hinweis eingebracht, dass die Webhooks erzeugt werden müssen

{{Todo|'''Achtung: Diese Seite ist teilweise veraltet, insbesondere unterstützt das Modul weitere Aktoren. Bitte Commandref lesen - diese Seite ist in Überarbeitung'''}}
{{Infobox Modul
|ModPurpose=Das Modul stellt ein Interface zur Bedienung von Shelly Devices zur Verfügung
|ModType=d
|ModCmdRef=Shelly
|ModForumArea=Sonstige Systeme
|ModFTopic=118446
|ModTechName=36_Shelly.pm
|ModOwner=Starkstrombastler ({{Link2FU|3884|Forum}}/[[Benutzer Diskussion:Starkstrombastler|Wiki]])
}}
Auf dieser Seite werden die Aktoren des bulgarischen Herstellers Allterco Robotics beschrieben (Markenname Shelly) sowie deren Ansteuerung mit FHEM und aufgetretene Probleme.
{{Randnotiz|RNTyp=r|RNText='''Achtung''': Einige der auf dieser Seite erwähnten Geräte und Funktionen sind derzeit nur mit {{Link2Forum|Topic=111905|Message=1285498|LinkText=dieser Testversion}} verfügbar, die manuell installiert werden muss!
* Für die Weiterentwicklung des Moduls wurde im Forum ein neues Thema '''({{Link2Forum|Topic=137222|LinkText=Entwicklungs-Thread Modul 36_Shelly.pm}})''' aufgemacht.}}
Bei den Shelly-Geräten handelt es sich um IP-basierte Schalt- und Dimmaktoren, die auf verschiedene Weise angesteuert werden können
*über die Web-Oberfläche des eingebauten Mikro-Webservers,
*über eine proprietäre App des Herstellers (Achtung, Cloud!),
*über das hier beschriebene FHEM-Modul 36_Shelly.pm
*über MQTT
Ein Teil der Aktoren verfügt über eine eingebaute Leistungsmessung (siehe Spalte Messkanäle in unten stehender Tabelle).

==Geräteübersicht==
Übersicht der IP-basierten Produktreihen
{| class="wikitable mw:datatable"
! style="width:15px" |ID
! style="width:100px" | Produktreihe
! style="width:225px" |gemeinsame Merkmale
|-
|SH
|erste Generation
|COIOT (Nutzung mit Shelly-Monitor), kein Bluetooth
|-
|SN
|Shelly Plus
Shelly Plus mini
|
|-
|SP
|Shelly Pro
|Montage auf Hutschiene, zusätzlicher Ethernet-Port (RJ45)
|-
|S3
|Shelly Gen3
Shelly Gen3 mini
|proprietärer Prozessor
|-
|SA
|Control Panel
|Android-System
|}
ID: erste beiden Stellen der Modell-ID

Liste der aktuell unterstützten Geräte
(hier nicht aufgeführte Geräte der ersten Generation können zusammen mit dem Shelly-Monitor genutzt werden):
{| class="wikitable sortable"
! data-sort-type="text" style="width:150px" |Modell
! data-sort-type="text" style="width:75px" |Typ
! data-sort-type="number" style="width:20px;text-align:center;" |Schalt- kanäle
! data-sort-type="number" style="width:20px;text-align:center;" |Dimm- kanäle
! data-sort-type="number" style="width:20px;text-align:center;" |Mess- kanäle
! data-sort-type="number" style="width:20px;text-align:center;" |Digital Eingänge
! |Bemerkungen
|-
! colspan="7" |'''Gen 1'''
|-
|Shelly 1
|Schalter
|1
|
|
|1
|
|
|-
|Shelly 1PM
|Schalter
|1
|
|1
|1
|
|
|-
|Shelly 1L
|Schalter
| 1
|
|1
| 1
|
|
|-
| rowspan="2" |Shelly 2
| Schalter
|2
|
|1
|2
|
|
|-
|Rollladenaktor
|1
|
|1
|2
|
|-
| rowspan="2" |Shelly 2.5
|Schalter
| 2
|
|2
|2
|
|-
|Rollladenaktor
|1
|
|1
|2
|
|-
|Shelly 4Pro
|Schalter
|4
|
|4
|4
|
|-
|Shelly i3
| Digitale Eingänge
|
|
|
|3
|
|-
|Shelly EM
|Leistungsmessung
|1
|
|2
|
|
|-
|'''[[Shelly 3EM]]'''
|Leistungsmessung
|1
|
|3
|
|
|-
|'''[[Shelly Uni]]'''
|Universal
|2
|
|
|*)
|1-Wire, 2 potentialfreie Relaisausgänge
Analogeingänge
|-
|Shelly Plug
Shelly Plug S
|Schaltsteckdose
|1
|
|1
|
|1 Taster
|-
| rowspan="2" |Shelly RGBW2
|Dimmer
|
|4
|4
|1
|4-fach Aktor
|-
|Dimmer
|
|1
| 1
|1
|RGBW Controller
|-
|Shelly Dimmer2
|Dimmer
|
| 1
|1
|2
|
|-
|Shelly Duo
|Leuchte
|
|1
|
|
|E27 oder GU10 Fassung
|-
|Shelly Vintage
|Leuchte
|
|1
|
|
|
|-
|Shelly Bulb
|Leuchte
|
|1
|
|
|Modi: weiß oder farbe
|-
! colspan="7" |'''Shelly Plus'''
|-
|Shelly Plus 1

|Schalter
|1
|
|
|1
|
|-
|'''[[Shelly Plus 1PM]]'''
|Schalter
|1
|
|1
|1
|
|-
| rowspan="2" |'''[[Shelly Plus 2PM]]'''
| Schalter
|2
|
|2
|2
|-
|Rollladenaktor
|1
|
| 1
|2
|-
|Shelly Plus i4
|Digitale Eingänge
|
|
|
| 4
|AC und DC - Variante
|-
| Shelly Plus Plug S
Shelly Plus Plug IT
Shelly Plus Plug UK
Shelly Plus Plug US
|Schaltsteckdose

|1
|
|1
|
|1 Taster;
Varianten V1, V2
|-
|Shelly Plus Uni
|Universal
| 2
|
|
|*)
|1-Wire, 2 potentialfreie Relaisausgänge
Analogeingänge; Neu in 2024
|-
|Shelly Plus 0-10V Dimmer
|Dimmer
|
|1
|1
|2
|0-10 V DC Ausgang
|-
| rowspan="2" |Shelly Plus RGBW
|Dimmer
|
|4
|4
|4
|4-fach Aktor
|-
|Dimmer
|
|1
|1
|1
|RGBW Controller
|-
! colspan="7" | '''Shelly Plus Mini'''
|-
|Shelly Plus 1 Mini
|Schalter
|1
|
|
|1
|
|-
|Shelly Plus 1PM Mini
|Schalter
|1
|
|1
|1
|
|-
|Shelly PM Mini
|Leistungsmessung
|
|
| 1
|
|
|-
! colspan="7" |'''Shelly Pro'''
|-
|Shelly Pro 1
|Schalter
|1
|
|
|2
|
|-
|Shelly Pro 1PM
|Schalter
|1
|
|1
|2
|
|-
|Shelly Pro 2
| Schalter
|2
|
|
| 2
|
|-
|Shelly Pro 2PM
|Schalter
|2
|
|2
|2
|
|-
|Shelly Pro Dual
|Rollladenaktor
|4
|
|
|4
|2 Rolladenaktoren
|-
|Shelly Pro Dimmer 1PM
|Dimmer
|
|1
|1
|2
|
|-
|Shelly Pro Dimmer 2PM
|Dimmer
|
| 2
|2
|4
|
|-
|Shelly Pro 3
|Schalter
|3
|
|
|3
|
|-
|Shelly Pro 3EM
|Leistungsmessung
|
|
|3
|
|1 Schaltkanal mit Addon
|-
|Shelly Pro EM50
|Leistungsmessung

|
|
|
|
|
|-
|Shelly Pro 4PM
|Schalter
|4
|
|4
|4
|
|-
! colspan="7" |'''Shelly Gen3'''
|-
| Shelly 1 Gen3
|Schalter
|1
|
|
|1
|
|-
|Shelly 1PM Gen3
|Schalter
|1
|
|1
|1
|
|-
|Shelly i4 Gen3
|Digitale Eingänge
|
|
|
| 4
|
|-
|Shelly Dimmer 0/1-10V Gen3
|Dimmer
|
| 1
| 1
|2
|0-10V DC oder
1-10V DC Ausgang
|-
! colspan="7" |'''Shelly Gen3 Mini'''
|-
|Shelly 1 Mini Gen3
|Schalter
|1
|
|
|1
|
|-
|Shelly 1PM Mini Gen3
|Schalter
|1
|
|1
|1
|
|-
|Shelly PM Mini Gen3
|Leistungsmessung
|
|
|1
|
|
|-
! colspan="7" | '''Control Panels'''
|-
|Shelly Wall Display
| Control Panel
| 1
|
|
| 1
|
|}

==Einbindung in FHEM==
Vorgehensweise zur Einbindung eines Shelly-Gerätes in FHEM:
*Aktor nach Vorschrift anschließen
*mit einem WLAN-fähigen Gerät (Laptop, Smartphone, Tablet...; im Folgenden als '''Laptop''' bezeichnet) nach dem internen Access Point suchen, der durch das Shelly-Gerät erzeugt wird; typischerweise hat es eine SSID ähnlich wie
:<code>shelly1-..., shellyswitch-..., shelly4pro-..., </code>
*'''Laptop''' mit diesem Access Point verbinden; typischerweise bekommt das Gerät dabei die IP-Adresse 192.168.33.2 zugewiesen.
*im Browser des '''Laptops''' die IP-Adresse 192.168.33.1 aufrufen - das ist der Shelly selbst; in der damit angezeigten Weboberfläche kann das Shelly-Gerät konfiguriert werden
**Shelly ins häusliche WLAN anmelden (mit fester IP-Adresse <shelly-ip> natürlich...)
**Internen Access Point abschalten (kann auch nach dem nächsten Schritt oder noch später erfolgen)
**Testen: '''Laptop''' wieder mit dem häuslichen WLAN verbinden, und im Browser die Adresse <shelly-ip> aufrufen
*In FHEM definieren
:<code>define myShelly Shelly <shelly-ip></code>
*Das Modul setzt bei bekannten Geräten das Attribut <code>model</code> automatisch. Bei nicht unterstützten Geräten wird das Attribut auf den Wert <code>generic</code> gesetzt. In diesen Fällen kann das Attribut <code>model</code> auf der Detailseite des Devices manuell gesetzt werden:
:<code> attr myShelly model shellyrgbw|shellydimmer|shelly2.5|shelly2|shellyem|shelly3em|shelly4|shellyplug|shelly1|shellybulb|shelly1pm|shellyuni|generic</code>

Falls es sich um einen Shelly2 oder 2.5 handelt, muss ferner das Attribut <code>mode</code> auf "roller" oder "relay" gesetzt werden. Mit diesem Modul können alle Daten übertragen und (prinzipiell) alle Konfigurationsänderungen durchgeführt werden, außerdem ist es auf einfachste Weise zu installieren. Das Modul pollt im per Attribut <code>interval</code> einstellbaren Abstand zyklisch den Aktor auf Statusänderungen (Wert 0 => kein Polling). Damit der Aktor im Stande ist, irgendwelche Zustandsänderungen ''von sich aus'' an FHEM zu melden, müssen diese als REST-Befehle (also URL-Aufrufe) in der Konfigurationsoberfläche des Shelly-Aktors eingetragen werden. Siehe CommandRef.

Zum Betrieb ist ferner noch zu bemerken, dass das Modul zwar meldet, ob ein Firmware-Update nötig ist, ausgelöst werden muss dieses aber über die Web-Oberfläche des Shelly selber.

===Actions/Webhooks (nur Testversion)===
Ab Shelly Firmware 1.5.0 werden Actions unterstützt. Damit besteht die Möglichkeit, dass ein Shelly bei Eintreten bestimmter Ereignisse von sich aus Meldungen an andere Shellies und/oder übergeordnete Systeme wie FHEM absetzt. Dies ist nützlich, um Statusänderungen, die z.B. durch lokal betätigte Tasten entstehen, direkt an FHEM zu übermitteln.

Nachfolgende Beispiele zeigen den Code, der im Shelly unter URL einzutragen ist:

Ausgang (Relais) eines Shelly1 schaltet ein:
:<code>http://<FHEM-IP>:<Port>/fhem?cmd=set%20<name>%20out_on</code>
hierbei sind:
:<code><FHEM-IP></code> die IP-Adresse des Servers auf dem FHEM läuft
:<code><Port></code> die Port-Nummer
:<code><name></code> der Name des FHEM-Devices
:<code>%20</code> stellt ein Leerzeichen dar

Beispiel 2: Eingang eines Shelly2 wird betätigt:
<syntaxhighlight lang="html">http://<FHEM-IP>:<Port>/fhem?cmd=set%20<name>%20input_on%20<ch></syntaxhighlight>
:<code><ch></code> die Nummer des Schaltkanals (Nummer des Eingangs), z.B. <code>0</code> oder <code>1</code>

Beispiel 3: Eingang1 eines ShellyDimmers wird betätigt:
<syntaxhighlight lang="html">http://<FHEM-IP>:<Port>/fhem?cmd=set%20<name>%20short_push<nowiki/>%20<inp></syntaxhighlight>
:<code><nowiki><inp></nowiki></code> Nummer des Eingangs, 0 oder 1 (ShellyDimmer verfügen je Schaltkanal über zwei Eingänge)

Beispiel 4: Wirkleistung eines ShellyPro3EM:
<syntaxhighlight lang="html">http://<FHEM-IP>:<Port>/fhem?fwcsrf=csrf_368985985592099&cmd=set%20Y173%20Active_Power_$phase%20$active_power</syntaxhighlight>
:<code>fwcsrf=csrf_368985985592099</code> das CSRF-Token (FHEMWeb)
:<code>$phase</code> wird vom Shelly durch a, b oder c ersetzt
: <code>$active_power</code> wird vom Shelly durch die aktuelle Wirkleistung ersetzt

'''Endpoints'''

In vorstehenden Beispielen stellt der Teil <code>set%20<name>%20<cmd></code> den Endpoint dar, d.h. dies ist der Befehl, der vom Shelly-Device in FHEM verarbeitet werden muss.

=====Liste der Befehle der Set-Endpoints:=====
{| class="wikitable sortable mw-collapsible"
|+
!<cmd>
!Wert
!Reading
!Erläuterung
!Geräte
|-
|<code>out_on</code>
|
| rowspan="2" |<code>relay_<ch></code><code>state</code>
|Ausgang ein
| rowspan="2" |alle Shelly mit Relaisausgang
ShellyBulb
ShellyRGBW
|-
|<code>out_off</code>
|
|Ausgang aus
|-
|<code>button_on</code>
|
| rowspan="2" |<code>button_<ch></code>
|Eingang ein
| rowspan="2" |ShellyPlug
ShellyPlugS
|-
|<code>button_off</code>
|
|Eingang aus
|-
|<code>input_on</code>
|
| rowspan="2" |<code>input_<ch></code>
|Eingang ein
| rowspan="2" |alle Shelly mit HW-Eingang, aber nicht Shelly-I-Geräte
|-
|<code>input_off</code>
|
|Eingang aus
|-
|<code>input_on</code>
|
| rowspan="4" |<code>input_<inp></code>
|Eingang ein
| rowspan="4" |ShellyDimmer
|-
|<code>input_off</code>
|
|Eingang aus
|-
|<code>short_push</code>
|
|kurzer Tastendruck
|-
|<code>long_push</code>
|
|langer Tastendruck
|-
|<code>single_push</code>
|
| rowspan="6" |<code>input_<ch></code><code>input_<ch>_action</code>
|kurzer Tastendruck
| rowspan="4" |ShellyI3
ShellyI4
|-
|<code>long_push</code>
|
|langer Tastendruck
|-
|<code>double_push</code>
|
|zweifacher Tastendruck
|-
|<code>triple_push</code>
|
|dreifacher Tastendruck
|-
|<code>short_long_push</code>
|
|Tastersequenz lang-kurz
| rowspan="2" |ShellyI3
|-
|<code>long_short_push</code>
|
|Tastersequenz kurz-lang
|-
|<code>stopped</code>
|
| rowspan="5" |<code>state</code>
|Rollo angehalten
| rowspan="5" | Shelly2/2.5/Plus2/Pro2 mode=roller
<nowiki>*</nowiki>) nur für Shelly Plus2/Pro2
|-
|<code>opening</code>
|
|Rollo wird geöffnet
|-
|<code>closing</code>
|
|Rollo wird geschlossen
|-
|<code>is_open *)</code>
|
|Rollo offen (in oberer Endlage)
|-
|<code>is_closed *)</code>
|
|Rollo geschlossen (in unterer Endlage)
|-
|<code>temperature_over</code>
|
|<code>temperature_<ch>_range</code>
|Temperatur überschreitet eingestellten Grenzwert
| rowspan="5" |ShellyAddOn
|-
|<code>temperature_under</code>
|
|<code>temperature_<ch>_range</code>
|Temperatur unterschreitet eingestellten Grenzwert
|-
|<code>humidity_over</code>
|
|<code>humidity_<ch>_range</code>
|Luftfeuchtigkeit überschreitet eingestellten Grenzwert
|-
| <code>humidity_under</code>
|
|<code>humidity_<ch>_range</code>
|Luftfeuchtigkeit unterschreitet eingestellten Grenzwert
|-
|<code>tempC</code>
|<code>$temperature</code>
|<code>temperature</code>
|Temperatur in °C
|-
|<code>voltage_over</code>
|
| rowspan="2" |<code>voltage_range</code>
|Spannung überschreitet eingestellten Grenzwert
| rowspan="2" |ShellyUni
|-
|<code>voltage_under</code>
|
|Spannung unterschreitet eingestellten Grenzwert
|-
| Active_Power_$phase
|<code>$active_power</code>
|<code>Active_Power_<ph></code>
|Änderung Wirkleistung
| rowspan="3" |ShellyPro3EM
|-
|Voltage_$phase
|<code>$voltage</code>
|<code>Voltage_<ph></code>
| Änderung Spannung
|-
|Current_$phase
|<code>$current</code>
|<code>Current_<ph></code>
|Änderung Strom
|}
Bei Eintreffen eines Set-Endpoints wird im Shelly-Device das zugeordnete Reading entsprechend gesetzt. Damit kann das Shelly-Ereignis z.B. mit einem <code>notify</code> ausgewertet werden. Im Anschluss daran holt sich das Modul die aktuellen Daten vom Shelly und setzt das Intervall zurück.

Anmerkung zum ShellyPro3EM: Die Action wird erst bei einer gewissen Änderung des jeweiligen Wertes ausgelöst. Bei kleinen Schwankungen kommen also keine Webhooks in FHEM an.

===== Get-Endpoint =====
Eine besondere Form stellt der Get-Endpoint dar, mit dem das Shelly-Device in FHEM aufgefordert wird, den Status des Shelly zu holen. Beispiel:
:<code>http://<FHEM-IP>:<Port>/fhem?cmd=get%20<name>%20status</code>

====Attribut webhook (derzeit nur Gen2)====
Durch Setzten des Attributes <code>webhook</code> werden auf dem Shelly die verfügbaren Webhooks automatisiert angelegt (auf der Shelly Oberfläche unter Actions zu sehen). Als Attribut-Wert muss das empfangende FHEMWeb-Device ausgewählt werden. Wird das FHEMWeb-Device mit einem csrf-Token abgesichert, wird der Token in den Webhook eingebunden. Bei Änderungen des Tokens (z.B. bei Neustart von FHEM) werden die entsprechenden Webhooks mit angepasst.

Nach dem Setzen des Attributes müssen die Webhooks mit <code>set myShellyDevice actions create all</code> angelegt werden.

Die vom Modul angelegten Webhooks erhalten im Shelly einen Namen, beginnend mit einem Unterstrich (<code>_</code>). Wird das Attribut geändert oder gelöscht, dann werden auch zugehörige Actions geändert bzw. gelöscht. Durch Entfernen des Unterstrichs im Namen der Action kann dieser Mechanismus unterbunden werden.

Das Reading <code>webhook_cnt</code> zeigt die Anzahl aller auf dem Shelly hinterlegten Webhooks und <code>webhooks_ver</code> den Versionszähler des Shelly.

Eine Übersicht aller Actions/Webhooks eines Shelly bekommt man für Gen2-Geräte mit:
:<code>http://<ip-des-Shelly>/rpc/Webhook.List</code>

===MQTT===
MQTT (Message Queue Telemetry Transport) ist ein nachrichtenbasiertes Protokoll, bei dem Geräte (Devices) nicht direkt miteinander, sondern mit einem zentralen MQTT-Server (in alter Nomenklatur ''Broker'' genannt) kommunizieren. Eine kurze Einführung in MQTT findet man auf der Seite [[MQTT Einführung]]. Mit entsprechend gesetzten Attributen lassen sich die Shelly-Aktoren auch steuern ([[MQTT2-Module - Praxisbeispiele#Shelly|Praxisbeispiele zu den MQTT2-Modulen]]), für Anfänger ist das allerdings nicht unbedingt zu empfehlen.

==Links==
*{{Link2Forum|Topic=118446|LinkText=Support Thread}} zu diesem Modul
*{{Link2Forum|Topic=137222|LinkText=Entwicklungs Thread}} zur Weiterentwicklung des Moduls, ab Februar 2024
*[http://www.shelly.com Website des Herstellers der Geräte]
*[https://community.shelly.cloud Forum des Herstellers (englischsprachig]

[[Kategorie:Energieverbrauchsmessung]]
[[Kategorie:MQTT]]
[[Kategorie:Bluetooth]]
[[Kategorie:Schalter (Empfänger)]]
[[Kategorie:Shelly]]

Harmony

2020-07-12T11:53:23Z

Muschelpuster: /* Geräteebene */ Hinweis auf EInschränkungen bei Harmony Companion

{{SEITENTITEL:harmony}}
{{Infobox Modul
|ModPurpose=Anbindung Logitech Harmony Hub basierter Fernbedienungen
|ModType=d
|ModCmdRef=harmony
|ModForumArea=Multimedia
|ModTechName=37_harmony.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])}}

Das FHEM-[[:Kategorie:Gerätemodul|Gerätemodul]] [[harmony]] bietet die Möglichkeit Logitech Harmony Hub basierte Fernbedienungen an FHEM anzubinden und so von FHEM aus Aktivitäten zu starten und zu stoppen, in FHEM auf das Starten und Stoppen von Aktivitäten über eine der mit dem Hub verbundenen Fernbedienungen zu reagieren oder auf Geräteebene jedes im Hub konfigurierte Gerät über IR, Bluetooth und/oder einen Smart Keyboard USB Dongle zu steuern.

Unterstützt werden zur Zeit die Modelle Ultimate Hub, Ultimate Smart Control, Ultimate, Smart Keyboard sowie alle darauf basierenden Kombinationen mit Smart Control und Smart Keyboard Add-On.

== Vorbereitung ==
Seit Ende 2018 hat Logitech die undokumentierte Schnittstelle die für die Anbindung der Harmony an FHEM verwendet werden geschlossen. Nach viel Protest aus der Community wurde die XMPP-Schnittstelle als "Entwickler-Option" nach akzeptieren von Haftungsausschlüssen wieder zur Verfügung gestellt. Ab Firmware 4.15.250 und Harmony-App-Version 5.6 für iOS und Android ist die Option zur Aktivierung von XMPP direkt in den Einstellungen der Harmony App zu finden. Die Einstellung versteckt sich unter Menü > Harmony-Einrichtung > Geräte und Aktionen hinzufügen und bearbeiten > Fernbedienung und Hub > XMPP aktivieren.

== Define ==
define <hub> harmony [<username> <password>] <ip>

Hier sind <code>username</code> und <code>password</code> die myharmony Zugangsdaten und <code>ip</code> ist die IP-Adresse des Hub im lokalen Netz.

Für die Firmware-Versionen 3.x ist die volle Funktionalität des Moduls auch ohne Angaben von <code>username</code> und <code>password</code> gegeben. Ab Firmware 4.x muss beides angegeben werden. Sonst ist keine Steuerung auf Geräteebene möglich.

==Allgemeines==
Aktivitäten und Geräte lassen sich an allen Stellen entweder als ID oder als Name angeben. Wenn der Name angegeben wird, müssen hierbei Leerzeichen durch einen Punkt ersetzt werden. Dies kann auch für eventuell andere im Namen vorhandene Sonderzeichen gelten.

== Aktivitäten ==
Das Reading <code>currentActivity</code> enthält die gerade laufende Aktivität. Beim Wechsel zwischen Aktivitäten erzeugt es Events, auf die in FHEM über ''notify'' reagiert werden kann. Das Reading <code>previousActivity</code> enthält die davor laufende Aktivität, sofern diese bekannt ist. Dieses Reading erzeugt keine Events.

In den Internals <code>currentActivityID</code> und <code>previousActivityID</code> stehen die dazu gehörenden IDs der Aktivitäten.

Mögliche Aktivitäten anzeigen geht über
get <hub> activities

Eine der Aktivitäten via FHEM starten über
set <hub> activity <activityname>
Wobei der Activityname zwingend so geschrieben werden muss wie FHEM ihn im Dropdown anzeigt.

Innerhalb einer laufenden Aktivität kann mit
set <hub> command <command>
ein IR-Kommando an eines der beteiligten Geräte gesendet werden.

== Geräteebene ==
Innerhalb und außerhalb einer laufenden Aktivität kann mit
set <hub> command <id|name> <command>
ein IR-Kommando an eines der im Hub bekannten Geräte gesendet werden. Hierbei ist darauf zu achten, dass innerhalb einer Aktivität keine Kommandos verwendet werden sollten, die den Smart-State betreffen.

Die möglichen Kommandos kann man sich über
get <hub> deviceCommands
anzeigen lassen.

Wichtig ist, dass wenn in der so erzeugten Liste ein Gerät mit Leerzeichen geschrieben wird, dass man im FHEM Befehl das Leerzeichen durch einen "." ersetzen muss. Hat man bspw. ein Harmony Device "Samsung TV" ist der Gerätebefehl zum anschalten:
set <hub> command Samsung.TV PowerOn

=== FHEM Devices auf Geräteebene ===
Es ist möglich, sich für einzelne oder alle im Hub konfigurierten Geräte ein zugehöriges FHEM-Device anlegen zu lassen:
set <hub> autocreate [<id|name>]

Beim Umschalten zwischen Aktivitäten wird in diesen FHEM-Devices im Reading power der in der Aktivität konfigurierten Einschaltzustand (on, off oder manual) angezeigt. Mit einem ''notify'' auf <code>power</code> Events lässt sich in FHEM auf einzelne Geräte reagieren.

'''Wichtig:''' Diese FHEM-Device spiegeln nicht den tatsächlichen Gerätezustand wieder, sondern den innerhalb einer Aktivität beabsichtigen Zustand. Der tatsächliche Zustand kann z.B. auf Grund von Empfangsproblemen abweichen.

Das get <code>commands</code> sowie die set <code>command</code>, <code>hidDevice</code>, <code>text</code>, <code>cursor</code> und <code>special</code> Kommandos auf Hub-Ebene stehen hier direkt und ohne Angabe von Device-ID oder Name zur Verfügung.

=== Kommandos an FHEM senden ===
Da es (zur Zeit) nicht möglich ist, Geräte-Kommandos oder einzelne Tasten direkt vom HUB zu empfangen, muss hierzu ein zusätzlicher Empfänger in FHEM eingebunden werden. Dies kann z.B. mit einem MCE-IR Empfänger oder per Bluetooth geschehen. Ein FHEM-Modul hierzu findet sich im in diesem {{Link2Forum|Topic=36257|LinkText=Forenthread}}.

Mit dem in diesem {{Link2Forum|Topic=51619|LinkText=Forenthread}} vorgestellten Modul ist es möglich einzeln belegte Tasten der Harmony über das Roku External Control Protocol per Netzwerk an FHEM zu senden und dort auszuwerten.

Leider ist es bei der Harmony Companion nicht möglich, die für die Heimautomatisierung vorgesehen Tasten beliebig zu belegen. Hier können nur unterstützte Geräte (Phillips Hue Bridge, LIFX Smart Bulls, Hunter Douglas Powerview Hub, PC - Stand 07/2020) zugeordnet werden. Somit ist fakeRoku hier nicht möglich. Hier kann über die Installation von HAbridge eine Hue Bridge emuliert werden, welche dann mit FHEM verbunden werden kann.

== Smart Keyboard ==
Der Harmony Hub kann über Bluetooth oder die zum Smart Keyboard gehörenden USB-Dongle mit einem Rechner, Media PC oder sonstigem Gerät, das Tastatureingabe unterstützt, verbunden werden. FHEM kann diese Verbindung nutzen, um beliebige Tastendrücke an ein solches Gerät zu senden. Das können Texte sein, Cursorbewegungen oder die Power-, Multimedia oder sonstigen Funktionstasten, die das Gerät unterstützt.

Alle gesendeten Tastendrücke beziehen sich normalerweise auf das zur gerade laufenden Aktivität gehörende Tastatureingabegerät. Mit dem <code>hidDevice</code> Kommando lässt sich die Tastatureingabe auf jedes im Hub dafür konfigurierte Gerät umschalten.

'''Wichtig:''' Dieses Umschalten kann einige Sekunden dauern, da hierbei die bestehende Bluetooth-Verbindung getrennt und eine neue aufgebaut wird.

Es stehen die Kommandos <code>text</code>, <code>cursor</code> und <code>special</code> zur Verfügung.

Beispiele:

Gehe in PLEX auf die Library Musik und spiele das erste Item in der OnDeck Liste:
set <hub> text M
set <hub> cursor right
set <hub> text p

== Beispiele ==

=== Vorgeschaltete Funksteckdose ansteuern ===

'''Vorbereitung Harmony'''

Nachdem die Geräte mit Strom versorgt werden, benötigen sie einige Sekunden, bis sie ihre Einschaltsignale verarbeiten können. Diese Verzögerung wird durch ein Dummy Gerät in jeder Aktion erzeugt.

1) In MyHarmony einen Amazon Fire TV anlegen und ihm einen passenden Namen geben (z.B. Pause)

2) Unter "Geräte" dieses markieren und per "Ändern der Betriebseinstellungen" die Einstellungen aufrufen

3) Punkt "Ich möchte dieses Gerät eingeschaltet lassen, wenn Aktionen gewechselt werden und nur durch Drücken der Off-Taste ausschalten" auswählen

4) Einen harmlosen Befehl einfügen ("Search"), danach eine Verzögerung von 5000ms einbauen und dann noch einen Befehl ("Search"). Dies bewirkt eine Verzögerung von 5 Sekunden beim Ein- und Ausschalten

5) Unter Aktionen die Aktion auswählen und per "Einstellung ändern" das neue Gerät hinzufügen

6) Per "Diese Aktion anpassen" das neue Gerät an die erste Stelle schieben

7) Schritte 5-7 für alle Aktionen wiederholen

'''Konfiguration in FHEM'''

1) Der Harmony Hub muss existieren

#Harmony Hub Wohnzimmer definieren
define wz_harmonyhub harmony 192.168.123.123

2) Ihr benötigt eine fertig konfigurierte Funksteckdose (hier "wz_Multimedia")

3) Ihr baut eine Bedingung, die auf den Ein- und Ausschaltvorgang des Harmony Hub (hier wz_harmonyhub) reagiert und die Steckdose (hier wz_Multimedia) schaltet. Es wird eine '''zusätzliche''' Pause genutzt von 0 Sekunden bei der ersten Bedingung (wäre kontraproduktiv) und 10 Sekunden bei der zweiten Bedingung (DOELSEIF). Bei der Nutzung eines Beamers lässt sich hierüber die Abkühlzeit einstellen. Im Beispiel bleiben den Geräten somit 15 Sekunden zum Ausschalten und 5 Sekunden um die Empfangsbereitschaft herzustellen. Die erste Bedingung im DOIF ist eine Regex, da "currentActivity" bei mehrfachem Abschalten hintereinander immer wieder von "PowerOff" auf "Stopping PowerOff" wechselt.

#Auf den Schaltvorgang des Hubs reagieren
define wz_Multimedia_Automatik DOIF ([wz_harmonyhub:currentActivity] !~ /PowerOff/) (set wz_Multimedia on) DOELSEIF ([wz_harmonyhub:activity] eq "PowerOff") (set wz_Multimedia off)
attr wz_Multimedia_Automatik wait 0:10

====Weitere Möglichkeiten====
Statt Fire TV kann jedes andere nicht vorhandene Gerät als Platzhalter in der Harmony verwendet werden. In diesem Gerät kann man auch direkt die Einschaltverzögerung anpassen um die nötige Wartezeit zu erhalten.
Besser als ein notify oder DOIF auf Activity-Ebene ist es über die Harmony autocreate funktion ein FHEM Device für die platzhalter Steckdose anzulegen und dort dann auf das power Event zu reagieren. Damit ist man unabhängig von allen Änderungen bei den Activities.

===Button für eine bestimmte Activity im Frontend und Homekit über readingsProxy ===
In FHEMWEB und Homebridge:
<syntaxhighlight lang="perl">
define Fernsehen readingsProxy <hub>:activity
attr Fernsehen devStateIcon on:control_on_off@green off:control_standby
attr Fernsehen event-on-change-reading .*
attr Fernsehen genericDeviceType switch
attr Fernsehen setFn { return 'activity <meine activity>' if( $CMD eq 'on' );; return 'off';; }
attr Fernsehen setList on off
attr Fernsehen valueFn { return 'on' if( $VALUE eq '<meine activity>' );; return 'off';; }
</syntaxhighlight>

Zusätzlich im TableUI:
<syntaxhighlight lang="xml">
<div class="left">
<div data-type="switch" data-device="Fernsehen" data-icon="fa-tv" class="cell" ></div>
<div data-type="label" class="narrow">FERNSEHEN</div>
</div>
</syntaxhighlight>

== Bekannte Probleme ==
Wenn FHEM den Harmony Hub nicht erreichen kann, blockiert das Modul FHEM für den Timeout von 2 Sekunden im Abstand von nur wenigen Sekunden:

<pre>[...]
2015.12.26 18:25:45 1: Perfmon: possible freeze starting at 18:25:43, delay is 2.794
2015.12.26 18:25:58 1: Perfmon: possible freeze starting at 18:25:56, delay is 2.709
2015.12.26 18:26:11 1: Perfmon: possible freeze starting at 18:26:09, delay is 2.676
2015.12.26 18:26:24 1: Perfmon: possible freeze starting at 18:26:22, delay is 2.686
2015.12.26 18:26:37 1: Perfmon: possible freeze starting at 18:26:35, delay is 2.686
[...]
</pre>

Da dieses Blockieren die Funktionalität von FHEM beeinträchtigen kann, sollte man bei geplanten Auszeiten des Hubs diesen disablen:

set <hub> disable 1

== Weblinks ==
* [http://myharmony.com myHarmony] Logitech Harmony Hersteller
* [http://www.harmony-remote-forum.de/portal.php Harmony Remote Forum] deutsches Harmony Forum
* {{Link2Forum|Topic=14163|LinkText=Thread im FHEM Forum}} Weitere Infos im FHEM Forum Thread

[[Kategorie:Unterhaltungselektronik]]
[[Kategorie:IP Components]]

OWServer & OWDevice

2018-04-30T05:24:17Z

Muschelpuster: Installation einer abweichenden Version von OWNet.pm

==Einleitung==

Bei OWServer handelt es sich um eine 1-Wire Server Komponente und bei OWDevice um eine Geräte-Komponente, die die angeschlossenen Module definiert-
Die Module benötigen die Serverkomponente von [http://www.owfs.org OWFS].

'''Wichtig:'''

Die Module sind eine eigenständige Möglichkeit, den 1-Wire Bus anzusteuern und kommen ohne die Module aus, deren Namen aus Großbuchstaben bestehen (wie OWX, OWSWITCH, OWTHERM, etc.).
Umgekehrt können die Module OWSWITCH, OWTHERM, etc. auch mit dem Backendmodul OWServer zusammenarbeiten, siehe dazu die {{Link2CmdRef}} der betreffenden Module.

==Vorbereitung==

Wie oben erwähnt, setzt OWServer/OWDevice auf OWFS auf. Dazu ist eine funktionierende OWFS Installation notwendig. Die Installation ist auf der selben Plattform (Debian-based) möglich oder auch Remote (zBsp Dockstar oder RPi). Eine gute [http://owfs.org/index.php?page=standard-devices Liste der Standard Devices]auf der Homepage von OWFS einzusehen. Nicht alle Standard Devices sind in OWDevice verfügbar (siehe unten).Wenn OWFS funktioniert kann's weiter gehen...

===owfs Pakete installieren===

====Erste Variante====
Die Pakete sind bereits vorpaketiert und man muss nur das [http://owfs.davromaniak.eu/ Repository] noch in /etc/apt/sources.list eintragen
====Zweite Variante====
Man muss selber kompilieren ([http://www.navitron.org.uk/forum/index.php?topic=12604.msg151750#msg151750 Quelle]). Version 3.1p0 von owfs lässt sich derzeit für den Raspberry Pi mit USB-Unterstützung nur kompilieren, wenn man einiges in den Make-Files patcht, wie [https://www.mail-archive.com/owfs-developers@lists.sourceforge.net/msg11484.html hier] beschrieben. Eine ältere, kompilierte Version für den RaspberryPi kann hier heruntergeladen werden: [http://forum.fhem.de/index.php?action=dlattach;topic=12219.0;attach=2463 owfs_2.8p17-1_all.zip]
<nowiki>sudo apt-get install automake autoconf autotools-dev gcc g++ libtool libusb-dev fuse-utils libfuse-dev swig python-dev tcl-dev php5-dev
sudo apt-get install git git-buildpackage dh-make quilt php5-cli
git clone [git://git.debian.org/collab-maint/owfs.git git://git.debian.org/collab-maint/owfs.git] git
git-buildpackage -uc -us
cd ..
sudo dpkg -i ./owserver_2.8p7+cvs20110310-1_i386.deb ./libow-2.8-7_2.8p7+cvs20110310-1_i386.deb ./owfs-common_2.8p7+cvs20110310-1_all.deb
sudo dpkg -i ./owhttpd_2.8p7+cvs20110310-1_i386.deb</nowiki>
diese Pakete wurden alle gebaut:
<nowiki>libow-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-common_2.8p7+cvs20110310-1_all.deb
libowcapi-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-dbg_2.8p7+cvs20110310-1_i386.deb
libow-dev_2.8p7+cvs20110310-1_i386.deb owfs-doc_2.8p7+cvs20110310-1_all.deb
libownet-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-fuse_2.8p7+cvs20110310-1_i386.deb
libownet-dev_2.8p7+cvs20110310-1_i386.deb owftpd_2.8p7+cvs20110310-1_i386.deb
libownet-perl_2.8p7+cvs20110310-1_all.deb owhttpd_2.8p7+cvs20110310-1_i386.deb
libownet-php_2.8p7+cvs20110310-1_all.deb owserver_2.8p7+cvs20110310-1_i386.deb
libow-perl_2.8p7+cvs20110310-1_i386.deb ow-shell_2.8p7+cvs20110310-1_i386.deb
libow-php5_2.8p7+cvs20110310-1_i386.deb python-ow_2.8p7+cvs20110310-1_i386.deb
libow-tcl_2.8p7+cvs20110310-1_i386.deb python-ownet_2.8p7+cvs20110310-1_all.deb
owfs_2.8p7+cvs20110310-1_all.deb</nowiki>
====Dritte Variante====
*In ältere Versionen von Raspbian (Debian wheezy) sind die notwendigen Pakete für Version 2.8p15 schon in den konfigurierten Quellen vorhanden.
*In der zukünftigen Version (Debian stretch) sind die Pakete ebenfalls (Version 3.1p1-6) enthalten. Zur Installation reicht jeweils ein

sudo apt-get install owserver ow-shell owhttpd owftpd

*Die aktuellen Version von Raspbian (Debian jessie) enthält die Version 2.9p8-6. Diese hat einen Fehler und funktioniert nicht mit Device DS2408. Hier kann alternativ das oben zum Download angegebene Paket owfs_2.8p17-1_all.zip herunter geladen und nach dem Wechsel in das Verzeichnis mit den entpackten Dateien mit
dpkg -i *.deb
installiert werden.

Diese /etc/owfs.conf wurde mit dem Downgrade erfolgreich getestet:

######################## SOURCES ########################
# With this setup, any client (but owserver) uses owserver on the
# local machine...
! server: server = localhost:4304
# ...and owserver uses the real hardware, by default fake devices
# This part must be changed on real installation
#server: FAKE = DS18S20,DS2405
#USB device: DS9490
#server: usb = all
#
#Schnittstelle mit dmesg nach Einstecken ermittelt -> /dev/ttyUSB4
# für Fuchs LinkUSB™ bzw. DS2480B/9097U Emulation
Serial port: DS9097
server: device = /dev/ttyUSB4
#
# owserver tcp address
#server: server = 192.168.10.1:3131
# random simulated device
#server: FAKE = DS18S20,DS2405
######################### OWFS ##########################
#mountpoint = /mnt/1wire
#allow_other
####################### OWHTTPD #########################
http: port = 2121
####################### OWFTPD ##########################
ftp: port = 2120
####################### OWSERVER ########################
server: port = localhost:4304

====Vierte Variante====
*Der in der dritten Variante beschriebene Fehler nach installation aus den offiziellen Quellen kann umgangen werden, indem man /opt/fhem/FHEM/lib/OWNet.pm durch folgende OWNet.pm ersetzt: https://sourceforge.net/p/owfs/code/ci/master/tree/module/ownet/perl5/OWNet/lib/ Dann geht es auch ohne Downgrade (Dank an ak323). Auf der FHEM-Kommandozeile
attr global exclude_from_update lib/OWNet.pm
verhindert das Überschreiben beim FHEM-Update.

====Ermitteln der installierten Version====
*Bei einer bestehenden Installation oder auch einer direkten Installation nach Variante 3 kann es erforderlich sein, die installierte Version zu prüfen. Dies kann über folgenden Befehl erfolgen:
/usr/bin/owhttpd -V

===Unterstütze Geräte===
Eine aktuelle Liste der von OWDevice unterstützen Geräte findet man in der FHEM-{{Link2CmdRef|Anker=OWDevice}}.

==Konfiguration von owserver==

Folgendes ist eine beispielhafte Konfiguration für OWFS mit einem am USB-Port angeschlossenen [http://denkovi.com/usb-to-one-wire-interface-adaptor-converter-thermometer Denkovi-Adapter] (Klon von DS9097U).

Es ist praktisch, dem Adapter ein festes Device zuzuordnen. Als erstes ermittelt man dazu den spezifischen Wert ATTRS{serial} mit:

udevadm info -a -p $(udevadm info -q path -n /dev/ttyUSB0) | grep ATTRS{serial}

Dananach legt man in /etc/udev/rules.d/ eine Datei 11-onewire.rules mit folgendem Inhalt an:

ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="DAE001nq", SUBSYSTEMS=="usb", ACTION=="add", MODE="0660", GROUP="plugdev", SYMLINK+="onewire"

Nach dem Einstöpseln des USB-Kabels vom Adapter wird über die Seriennummer DAE001nq des USB-Wandlers auf dem Adapter das Gerät erkannt und der Symlink /dev/onewire auf das eigentliche USB-Gerät (z.B. /dev/ttyUSB1) erstellt.

Eine Minimalkonfiguration für /etc/owfs.conf ist

server: device = /dev/onewire
http: port = 2121
ftp: port = 2120
server: port = 4304

Es ist sinnvoll, owhttpd installiert und laufen zu haben, um über die URL http://deinRaspberryPi:2121 zu sehen, dass owserver läuft und die Geräte am 1-wire-Bus erkennt.

==Konfiguration in FHEM==
Als erstes definiert man OWServer. Hiermit wird ein logischer OWServer definiert, auf welchem OWFS installiert ist

<nowiki>define <name> OWServer <protocol> [<version>]</nowiki>
<protocol> hat das Format <hostname>:<port>.

zBsp:

<nowiki>define myOWServer OWServer 192.168.14.100:4304</nowiki>
oder wenn sich OWFS auf dem gleichen Server befindet wie FHEM:

<nowiki>define myOWServer OWServer localhost:4304</nowiki>

[<version>] ist seit Mitte März 2018 optional anzugeben. Im Standard verbindet sich OWServer mit V 3.1p5 und versucht die Version des OWFS-Servers zu ermitteln. Wenn dies scheitert, kann die Version gezielt angegeben werden. Dazu muss die komplette Versionsnummer angegeben werden. Beispiel:
<nowiki>define myOWServer OWServer 192.168.14.100:4304 2.8p17</nowiki>

Da OWServer die OWNet.pm von Sourceforge verwendet um sich zu verbinden, muss die passende Version der OWNet.pm unter ../FHEM/lib/ vorhanden sein. Per Default wird FHEM mit der V 3.1p5 und 2.8p17 ausgeliefert, andere Versionen müssen manuell hinzugefügt werden.

Nach erfolgreichem "define" ist ein Klick auf den "Save" Button notwenig. Wenn nun der Status von myOWServer auf "Initialized" steht, ist der Server verbunden. Um sicher zu sein, dass der OWServer funktioniert, kann eine manuelle Abfrage der Device durchgeführt werden mit:

<nowiki>get myOWServer devices</nowiki>
Danach werden sämtliche angeschlossene Geräte angezeigt, inkl. Busmaster

===OWServer Set Befehle===
<nowiki>set <name> <value>
value:
timeout/directory
timeout/ftp
timeout/ha7
timeout/network
timeout/presence
timeout/serial
timeout/server
timeout/stable
timeout/uncached
timeout/usb
timeout/volatile
timeout/w1
units/pressure_scale
units/temperature_scale</nowiki>
Weitere Informationen zu den Set Befehlen sind im [http://owfs.org/uploads/owserver.1.html#sect41 OWServer Manual] zu entnehmen.

===OWServer Get Befehle===
<nowiki>get <name> <value>
value:
/settings/timeout/directory
/settings/timeout/ftp
/settings/timeout/ha7
/settings/timeout/network
/settings/timeout/presence
/settings/timeout/serial
/settings/timeout/server
/settings/timeout/stable
/settings/timeout/uncached
/settings/timeout/usb
/settings/timeout/volatile
/settings/timeout/w1
/settings/units/pressure_scale
/settings/units/temperature_scale</nowiki>
Zusätzlich stehen die FHEM-internen Befehle "errors" und "devices" zur Verfügung.
zBsp:

<nowiki>get <Devicename> errors #listet die Fehler des Device auf
get <Devicename> devices #scan den Server nach Device</nowiki>

===Angeschlossene Geräte auslesen===
Grundsätzlich werden die am Busmaster von OWFS angeschlossenen 1-Wire Geräte durch aktives autocreate nach einem Neustart (erfordert shutdown restart) selber in FHEM definiert.
Der Busmaster (zBsp ein DS9490r) selbst wird ebenfalls eingelesen und angezeigt.

===Definition von Geräten===
Es ist auch möglich, Geräte manuell anzulegen. Dies erfolgt in folgendem Format:

<nowiki>define <name> OWDevice <address> [<interval>]</nowiki>
zBsp:

<nowiki>define Vorlauftemp OWDevice 28.334F2B040000 60</nowiki>
Wobei der Wert 60 als Abfrageintervall in Sekunden zu verstehen ist.

===OWDevice State===
Bei Temperaturfühler wie DS18S20 wird das Reading "state" wie folgt ausgegeben:

<nowiki>temperature: 56.1875 alarm: 1</nowiki>
Um die Temperatur wie bei anderen Temperatur-Sensoren (zBsp. CUL_WS) anzuzeigen, hilft das Attribut "stateFormat". Dies kann wie folgt definiert werden:

<nowiki>attr <Devicename> stateFormat T: <wert></nowiki>
zBsp:

<nowiki>attr Boiler stateFormat T: temperature</nowiki>
alternativ

<nowiki>attr <Devicename> stateFormat {sprintf("%.1f",ReadingsVal("<Devicename>","temperature",0))."°C"}</nowiki>
Zusätzlich rundet das obenstehende Attribut mit "%.1f" die Temperatur auf eine Kommastelle.

==Tipps und Tricks==
1-wire-Geräte sind häufig generische Geräte, wie Zähler und Spannungsmesser (A/D-Wandler), an denen Sensorik hängt. Die rohen Werte vom 1-wire-Gerät (Zählimpulse, Spannungen) sind dann noch in menschenlesbare Werte zu verwandeln. Hier helfen userReadings, z.B.

<nowiki>attr myEnergyMeter userReadings energy { (ReadingsVal("myEnergyMeter","count.A",0)+AttrVal("myEnergyMeter","myBasis",0))/1250.0;; }</nowiki>

==Anwendungsbeispiele==
[[Stromzähler_und_1-Wire,_OWServer,_OWDevice|Hier]] findet man ein Beispiel einer Anbindung zweier Leistungsmesser (aka Stromzähler) mit S0 Ausgang über einen 1-wire-S0-Zähler an FHEM.

==Installation einer abweichenden Version von OWNet.pm==
Die benötigte Datei befindet sich im jeweiligen Paket auf [https://sourceforge.net/projects/owfs/files/owfs/ Sourceforge]. Nach dem Entpacken ist im Ordner ../module/ownet/perl5/OWNet/lib die Datei OWNet.pm. Diese Datei ist nach OWNet-Version.pm umzubenennen und in den FHEM-Ordner ../FHEM/lib/ zu kopieren. Abschließend müssen ggf. die Dateirechte angepasst werden.

== Bekannte Probleme ==
=== FHEM hängt, wenn OWServer nicht erreichbar ist ===
Am Anfang gab es mit OWServer das Problem, dass FHEM immer komplett hing, wenn OWServer nicht erreichbar war (siehe z. B. [http://www.fischer-net.de/hausautomation/haustechnik/1-wire/60-1-wire-integration-in-fhem.html hier am Ende]). Das Problem wurde inzwischen dankenswerterweise für den laufenden Betrieb {{Link2Forum|Topic=16945|LinkText=behoben}} - <code>attr myOWServer nonblocking 1</code> muss dazu gesetzt werden -, aber zumindest beim Start hängt FHEM nach wie vor, wenn OWServer nicht erreichbar ist.

[[Kategorie:1-Wire]]

OWServer & OWDevice

2018-04-30T05:10:31Z

Muschelpuster: optionale Angabe von Version

==Einleitung==

Bei OWServer handelt es sich um eine 1-Wire Server Komponente und bei OWDevice um eine Geräte-Komponente, die die angeschlossenen Module definiert-
Die Module benötigen die Serverkomponente von [http://www.owfs.org OWFS].

'''Wichtig:'''

Die Module sind eine eigenständige Möglichkeit, den 1-Wire Bus anzusteuern und kommen ohne die Module aus, deren Namen aus Großbuchstaben bestehen (wie OWX, OWSWITCH, OWTHERM, etc.).
Umgekehrt können die Module OWSWITCH, OWTHERM, etc. auch mit dem Backendmodul OWServer zusammenarbeiten, siehe dazu die {{Link2CmdRef}} der betreffenden Module.

==Vorbereitung==

Wie oben erwähnt, setzt OWServer/OWDevice auf OWFS auf. Dazu ist eine funktionierende OWFS Installation notwendig. Die Installation ist auf der selben Plattform (Debian-based) möglich oder auch Remote (zBsp Dockstar oder RPi). Eine gute [http://owfs.org/index.php?page=standard-devices Liste der Standard Devices]auf der Homepage von OWFS einzusehen. Nicht alle Standard Devices sind in OWDevice verfügbar (siehe unten).Wenn OWFS funktioniert kann's weiter gehen...

===owfs Pakete installieren===

====Erste Variante====
Die Pakete sind bereits vorpaketiert und man muss nur das [http://owfs.davromaniak.eu/ Repository] noch in /etc/apt/sources.list eintragen
====Zweite Variante====
Man muss selber kompilieren ([http://www.navitron.org.uk/forum/index.php?topic=12604.msg151750#msg151750 Quelle]). Version 3.1p0 von owfs lässt sich derzeit für den Raspberry Pi mit USB-Unterstützung nur kompilieren, wenn man einiges in den Make-Files patcht, wie [https://www.mail-archive.com/owfs-developers@lists.sourceforge.net/msg11484.html hier] beschrieben. Eine ältere, kompilierte Version für den RaspberryPi kann hier heruntergeladen werden: [http://forum.fhem.de/index.php?action=dlattach;topic=12219.0;attach=2463 owfs_2.8p17-1_all.zip]
<nowiki>sudo apt-get install automake autoconf autotools-dev gcc g++ libtool libusb-dev fuse-utils libfuse-dev swig python-dev tcl-dev php5-dev
sudo apt-get install git git-buildpackage dh-make quilt php5-cli
git clone [git://git.debian.org/collab-maint/owfs.git git://git.debian.org/collab-maint/owfs.git] git
git-buildpackage -uc -us
cd ..
sudo dpkg -i ./owserver_2.8p7+cvs20110310-1_i386.deb ./libow-2.8-7_2.8p7+cvs20110310-1_i386.deb ./owfs-common_2.8p7+cvs20110310-1_all.deb
sudo dpkg -i ./owhttpd_2.8p7+cvs20110310-1_i386.deb</nowiki>
diese Pakete wurden alle gebaut:
<nowiki>libow-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-common_2.8p7+cvs20110310-1_all.deb
libowcapi-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-dbg_2.8p7+cvs20110310-1_i386.deb
libow-dev_2.8p7+cvs20110310-1_i386.deb owfs-doc_2.8p7+cvs20110310-1_all.deb
libownet-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-fuse_2.8p7+cvs20110310-1_i386.deb
libownet-dev_2.8p7+cvs20110310-1_i386.deb owftpd_2.8p7+cvs20110310-1_i386.deb
libownet-perl_2.8p7+cvs20110310-1_all.deb owhttpd_2.8p7+cvs20110310-1_i386.deb
libownet-php_2.8p7+cvs20110310-1_all.deb owserver_2.8p7+cvs20110310-1_i386.deb
libow-perl_2.8p7+cvs20110310-1_i386.deb ow-shell_2.8p7+cvs20110310-1_i386.deb
libow-php5_2.8p7+cvs20110310-1_i386.deb python-ow_2.8p7+cvs20110310-1_i386.deb
libow-tcl_2.8p7+cvs20110310-1_i386.deb python-ownet_2.8p7+cvs20110310-1_all.deb
owfs_2.8p7+cvs20110310-1_all.deb</nowiki>
====Dritte Variante====
*In ältere Versionen von Raspbian (Debian wheezy) sind die notwendigen Pakete für Version 2.8p15 schon in den konfigurierten Quellen vorhanden.
*In der zukünftigen Version (Debian stretch) sind die Pakete ebenfalls (Version 3.1p1-6) enthalten. Zur Installation reicht jeweils ein

sudo apt-get install owserver ow-shell owhttpd owftpd

*Die aktuellen Version von Raspbian (Debian jessie) enthält die Version 2.9p8-6. Diese hat einen Fehler und funktioniert nicht mit Device DS2408. Hier kann alternativ das oben zum Download angegebene Paket owfs_2.8p17-1_all.zip herunter geladen und nach dem Wechsel in das Verzeichnis mit den entpackten Dateien mit
dpkg -i *.deb
installiert werden.

Diese /etc/owfs.conf wurde mit dem Downgrade erfolgreich getestet:

######################## SOURCES ########################
# With this setup, any client (but owserver) uses owserver on the
# local machine...
! server: server = localhost:4304
# ...and owserver uses the real hardware, by default fake devices
# This part must be changed on real installation
#server: FAKE = DS18S20,DS2405
#USB device: DS9490
#server: usb = all
#
#Schnittstelle mit dmesg nach Einstecken ermittelt -> /dev/ttyUSB4
# für Fuchs LinkUSB™ bzw. DS2480B/9097U Emulation
Serial port: DS9097
server: device = /dev/ttyUSB4
#
# owserver tcp address
#server: server = 192.168.10.1:3131
# random simulated device
#server: FAKE = DS18S20,DS2405
######################### OWFS ##########################
#mountpoint = /mnt/1wire
#allow_other
####################### OWHTTPD #########################
http: port = 2121
####################### OWFTPD ##########################
ftp: port = 2120
####################### OWSERVER ########################
server: port = localhost:4304

====Vierte Variante====
*Der in der dritten Variante beschriebene Fehler nach installation aus den offiziellen Quellen kann umgangen werden, indem man /opt/fhem/FHEM/lib/OWNet.pm durch folgende OWNet.pm ersetzt: https://sourceforge.net/p/owfs/code/ci/master/tree/module/ownet/perl5/OWNet/lib/ Dann geht es auch ohne Downgrade (Dank an ak323). Auf der FHEM-Kommandozeile
attr global exclude_from_update lib/OWNet.pm
verhindert das Überschreiben beim FHEM-Update.

====Ermitteln der installierten Version====
*Bei einer bestehenden Installation oder auch einer direkten Installation nach Variante 3 kann es erforderlich sein, die installierte Version zu prüfen. Dies kann über folgenden Befehl erfolgen:
/usr/bin/owhttpd -V

===Unterstütze Geräte===
Eine aktuelle Liste der von OWDevice unterstützen Geräte findet man in der FHEM-{{Link2CmdRef|Anker=OWDevice}}.

==Konfiguration von owserver==

Folgendes ist eine beispielhafte Konfiguration für OWFS mit einem am USB-Port angeschlossenen [http://denkovi.com/usb-to-one-wire-interface-adaptor-converter-thermometer Denkovi-Adapter] (Klon von DS9097U).

Es ist praktisch, dem Adapter ein festes Device zuzuordnen. Als erstes ermittelt man dazu den spezifischen Wert ATTRS{serial} mit:

udevadm info -a -p $(udevadm info -q path -n /dev/ttyUSB0) | grep ATTRS{serial}

Dananach legt man in /etc/udev/rules.d/ eine Datei 11-onewire.rules mit folgendem Inhalt an:

ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="DAE001nq", SUBSYSTEMS=="usb", ACTION=="add", MODE="0660", GROUP="plugdev", SYMLINK+="onewire"

Nach dem Einstöpseln des USB-Kabels vom Adapter wird über die Seriennummer DAE001nq des USB-Wandlers auf dem Adapter das Gerät erkannt und der Symlink /dev/onewire auf das eigentliche USB-Gerät (z.B. /dev/ttyUSB1) erstellt.

Eine Minimalkonfiguration für /etc/owfs.conf ist

server: device = /dev/onewire
http: port = 2121
ftp: port = 2120
server: port = 4304

Es ist sinnvoll, owhttpd installiert und laufen zu haben, um über die URL http://deinRaspberryPi:2121 zu sehen, dass owserver läuft und die Geräte am 1-wire-Bus erkennt.

==Konfiguration in FHEM==
Als erstes definiert man OWServer. Hiermit wird ein logischer OWServer definiert, auf welchem OWFS installiert ist

<nowiki>define <name> OWServer <protocol> [<version>]</nowiki>
<protocol> hat das Format <hostname>:<port>.

zBsp:

<nowiki>define myOWServer OWServer 192.168.14.100:4304</nowiki>
oder wenn sich OWFS auf dem gleichen Server befindet wie FHEM:

<nowiki>define myOWServer OWServer localhost:4304</nowiki>

[<version>] ist seit Mitte März 2018 optional anzugeben. Im Standard verbindet sich OWServer mit V 3.1p5 und versucht die Version des OWFS-Servers zu ermitteln. Wenn dies scheitert, kann die Version gezielt angegeben werden. Dazu muss die komplette Versionsnummer angegeben werden. Beispiel:
<nowiki>define myOWServer OWServer 192.168.14.100:4304 2.8p17</nowiki>

Da OWServer die OWNet.pm von Sourceforge verwendet um sich zu verbinden, muss die passende Version der OWNet.pm unter ../FHEM/lib/ vorhanden sein. Per Default wird FHEM mit der V 3.1p5 und 2.8p17 ausgeliefert, andere Versionen müssen manuell hinzugefügt werden.

Nach erfolgreichem "define" ist ein Klick auf den "Save" Button notwenig. Wenn nun der Status von myOWServer auf "Initialized" steht, ist der Server verbunden. Um sicher zu sein, dass der OWServer funktioniert, kann eine manuelle Abfrage der Device durchgeführt werden mit:

<nowiki>get myOWServer devices</nowiki>
Danach werden sämtliche angeschlossene Geräte angezeigt, inkl. Busmaster

===OWServer Set Befehle===
<nowiki>set <name> <value>
value:
timeout/directory
timeout/ftp
timeout/ha7
timeout/network
timeout/presence
timeout/serial
timeout/server
timeout/stable
timeout/uncached
timeout/usb
timeout/volatile
timeout/w1
units/pressure_scale
units/temperature_scale</nowiki>
Weitere Informationen zu den Set Befehlen sind im [http://owfs.org/uploads/owserver.1.html#sect41 OWServer Manual] zu entnehmen.

===OWServer Get Befehle===
<nowiki>get <name> <value>
value:
/settings/timeout/directory
/settings/timeout/ftp
/settings/timeout/ha7
/settings/timeout/network
/settings/timeout/presence
/settings/timeout/serial
/settings/timeout/server
/settings/timeout/stable
/settings/timeout/uncached
/settings/timeout/usb
/settings/timeout/volatile
/settings/timeout/w1
/settings/units/pressure_scale
/settings/units/temperature_scale</nowiki>
Zusätzlich stehen die FHEM-internen Befehle "errors" und "devices" zur Verfügung.
zBsp:

<nowiki>get <Devicename> errors #listet die Fehler des Device auf
get <Devicename> devices #scan den Server nach Device</nowiki>

===Angeschlossene Geräte auslesen===
Grundsätzlich werden die am Busmaster von OWFS angeschlossenen 1-Wire Geräte durch aktives autocreate nach einem Neustart (erfordert shutdown restart) selber in FHEM definiert.
Der Busmaster (zBsp ein DS9490r) selbst wird ebenfalls eingelesen und angezeigt.

===Definition von Geräten===
Es ist auch möglich, Geräte manuell anzulegen. Dies erfolgt in folgendem Format:

<nowiki>define <name> OWDevice <address> [<interval>]</nowiki>
zBsp:

<nowiki>define Vorlauftemp OWDevice 28.334F2B040000 60</nowiki>
Wobei der Wert 60 als Abfrageintervall in Sekunden zu verstehen ist.

===OWDevice State===
Bei Temperaturfühler wie DS18S20 wird das Reading "state" wie folgt ausgegeben:

<nowiki>temperature: 56.1875 alarm: 1</nowiki>
Um die Temperatur wie bei anderen Temperatur-Sensoren (zBsp. CUL_WS) anzuzeigen, hilft das Attribut "stateFormat". Dies kann wie folgt definiert werden:

<nowiki>attr <Devicename> stateFormat T: <wert></nowiki>
zBsp:

<nowiki>attr Boiler stateFormat T: temperature</nowiki>
alternativ

<nowiki>attr <Devicename> stateFormat {sprintf("%.1f",ReadingsVal("<Devicename>","temperature",0))."°C"}</nowiki>
Zusätzlich rundet das obenstehende Attribut mit "%.1f" die Temperatur auf eine Kommastelle.

==Tipps und Tricks==
1-wire-Geräte sind häufig generische Geräte, wie Zähler und Spannungsmesser (A/D-Wandler), an denen Sensorik hängt. Die rohen Werte vom 1-wire-Gerät (Zählimpulse, Spannungen) sind dann noch in menschenlesbare Werte zu verwandeln. Hier helfen userReadings, z.B.

<nowiki>attr myEnergyMeter userReadings energy { (ReadingsVal("myEnergyMeter","count.A",0)+AttrVal("myEnergyMeter","myBasis",0))/1250.0;; }</nowiki>

==Anwendungsbeispiele==
[[Stromzähler_und_1-Wire,_OWServer,_OWDevice|Hier]] findet man ein Beispiel einer Anbindung zweier Leistungsmesser (aka Stromzähler) mit S0 Ausgang über einen 1-wire-S0-Zähler an FHEM.

== Bekannte Probleme ==
=== FHEM hängt, wenn OWServer nicht erreichbar ist ===
Am Anfang gab es mit OWServer das Problem, dass FHEM immer komplett hing, wenn OWServer nicht erreichbar war (siehe z. B. [http://www.fischer-net.de/hausautomation/haustechnik/1-wire/60-1-wire-integration-in-fhem.html hier am Ende]). Das Problem wurde inzwischen dankenswerterweise für den laufenden Betrieb {{Link2Forum|Topic=16945|LinkText=behoben}} - <code>attr myOWServer nonblocking 1</code> muss dazu gesetzt werden -, aber zumindest beim Start hängt FHEM nach wie vor, wenn OWServer nicht erreichbar ist.

[[Kategorie:1-Wire]]

OWServer & OWDevice

2018-04-30T04:44:50Z

Muschelpuster: /* Vierte Variante */

==Einleitung==

Bei OWServer handelt es sich um eine 1-Wire Server Komponente und bei OWDevice um eine Geräte-Komponente, die die angeschlossenen Module definiert-
Die Module benötigen die Serverkomponente von [http://www.owfs.org OWFS].

'''Wichtig:'''

Die Module sind eine eigenständige Möglichkeit, den 1-Wire Bus anzusteuern und kommen ohne die Module aus, deren Namen aus Großbuchstaben bestehen (wie OWX, OWSWITCH, OWTHERM, etc.).
Umgekehrt können die Module OWSWITCH, OWTHERM, etc. auch mit dem Backendmodul OWServer zusammenarbeiten, siehe dazu die {{Link2CmdRef}} der betreffenden Module.

==Vorbereitung==

Wie oben erwähnt, setzt OWServer/OWDevice auf OWFS auf. Dazu ist eine funktionierende OWFS Installation notwendig. Die Installation ist auf der selben Plattform (Debian-based) möglich oder auch Remote (zBsp Dockstar oder RPi). Eine gute [http://owfs.org/index.php?page=standard-devices Liste der Standard Devices]auf der Homepage von OWFS einzusehen. Nicht alle Standard Devices sind in OWDevice verfügbar (siehe unten).Wenn OWFS funktioniert kann's weiter gehen...

===owfs Pakete installieren===

====Erste Variante====
Die Pakete sind bereits vorpaketiert und man muss nur das [http://owfs.davromaniak.eu/ Repository] noch in /etc/apt/sources.list eintragen
====Zweite Variante====
Man muss selber kompilieren ([http://www.navitron.org.uk/forum/index.php?topic=12604.msg151750#msg151750 Quelle]). Version 3.1p0 von owfs lässt sich derzeit für den Raspberry Pi mit USB-Unterstützung nur kompilieren, wenn man einiges in den Make-Files patcht, wie [https://www.mail-archive.com/owfs-developers@lists.sourceforge.net/msg11484.html hier] beschrieben. Eine ältere, kompilierte Version für den RaspberryPi kann hier heruntergeladen werden: [http://forum.fhem.de/index.php?action=dlattach;topic=12219.0;attach=2463 owfs_2.8p17-1_all.zip]
<nowiki>sudo apt-get install automake autoconf autotools-dev gcc g++ libtool libusb-dev fuse-utils libfuse-dev swig python-dev tcl-dev php5-dev
sudo apt-get install git git-buildpackage dh-make quilt php5-cli
git clone [git://git.debian.org/collab-maint/owfs.git git://git.debian.org/collab-maint/owfs.git] git
git-buildpackage -uc -us
cd ..
sudo dpkg -i ./owserver_2.8p7+cvs20110310-1_i386.deb ./libow-2.8-7_2.8p7+cvs20110310-1_i386.deb ./owfs-common_2.8p7+cvs20110310-1_all.deb
sudo dpkg -i ./owhttpd_2.8p7+cvs20110310-1_i386.deb</nowiki>
diese Pakete wurden alle gebaut:
<nowiki>libow-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-common_2.8p7+cvs20110310-1_all.deb
libowcapi-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-dbg_2.8p7+cvs20110310-1_i386.deb
libow-dev_2.8p7+cvs20110310-1_i386.deb owfs-doc_2.8p7+cvs20110310-1_all.deb
libownet-2.8-7_2.8p7+cvs20110310-1_i386.deb owfs-fuse_2.8p7+cvs20110310-1_i386.deb
libownet-dev_2.8p7+cvs20110310-1_i386.deb owftpd_2.8p7+cvs20110310-1_i386.deb
libownet-perl_2.8p7+cvs20110310-1_all.deb owhttpd_2.8p7+cvs20110310-1_i386.deb
libownet-php_2.8p7+cvs20110310-1_all.deb owserver_2.8p7+cvs20110310-1_i386.deb
libow-perl_2.8p7+cvs20110310-1_i386.deb ow-shell_2.8p7+cvs20110310-1_i386.deb
libow-php5_2.8p7+cvs20110310-1_i386.deb python-ow_2.8p7+cvs20110310-1_i386.deb
libow-tcl_2.8p7+cvs20110310-1_i386.deb python-ownet_2.8p7+cvs20110310-1_all.deb
owfs_2.8p7+cvs20110310-1_all.deb</nowiki>
====Dritte Variante====
*In ältere Versionen von Raspbian (Debian wheezy) sind die notwendigen Pakete für Version 2.8p15 schon in den konfigurierten Quellen vorhanden.
*In der zukünftigen Version (Debian stretch) sind die Pakete ebenfalls (Version 3.1p1-6) enthalten. Zur Installation reicht jeweils ein

sudo apt-get install owserver ow-shell owhttpd owftpd

*Die aktuellen Version von Raspbian (Debian jessie) enthält die Version 2.9p8-6. Diese hat einen Fehler und funktioniert nicht mit Device DS2408. Hier kann alternativ das oben zum Download angegebene Paket owfs_2.8p17-1_all.zip herunter geladen und nach dem Wechsel in das Verzeichnis mit den entpackten Dateien mit
dpkg -i *.deb
installiert werden.

Diese /etc/owfs.conf wurde mit dem Downgrade erfolgreich getestet:

######################## SOURCES ########################
# With this setup, any client (but owserver) uses owserver on the
# local machine...
! server: server = localhost:4304
# ...and owserver uses the real hardware, by default fake devices
# This part must be changed on real installation
#server: FAKE = DS18S20,DS2405
#USB device: DS9490
#server: usb = all
#
#Schnittstelle mit dmesg nach Einstecken ermittelt -> /dev/ttyUSB4
# für Fuchs LinkUSB™ bzw. DS2480B/9097U Emulation
Serial port: DS9097
server: device = /dev/ttyUSB4
#
# owserver tcp address
#server: server = 192.168.10.1:3131
# random simulated device
#server: FAKE = DS18S20,DS2405
######################### OWFS ##########################
#mountpoint = /mnt/1wire
#allow_other
####################### OWHTTPD #########################
http: port = 2121
####################### OWFTPD ##########################
ftp: port = 2120
####################### OWSERVER ########################
server: port = localhost:4304

====Vierte Variante====
*Der in der dritten Variante beschriebene Fehler nach installation aus den offiziellen Quellen kann umgangen werden, indem man /opt/fhem/FHEM/lib/OWNet.pm durch folgende OWNet.pm ersetzt: https://sourceforge.net/p/owfs/code/ci/master/tree/module/ownet/perl5/OWNet/lib/ Dann geht es auch ohne Downgrade (Dank an ak323). Auf der FHEM-Kommandozeile
attr global exclude_from_update lib/OWNet.pm
verhindert das Überschreiben beim FHEM-Update.

====Ermitteln der installierten Version====
*Bei einer bestehenden Installation oder auch einer direkten Installation nach Variante 3 kann es erforderlich sein, die installierte Version zu prüfen. Dies kann über folgenden Befehl erfolgen:
/usr/bin/owhttpd -V

===Unterstütze Geräte===
Eine aktuelle Liste der von OWDevice unterstützen Geräte findet man in der FHEM-{{Link2CmdRef|Anker=OWDevice}}.

==Konfiguration von owserver==

Folgendes ist eine beispielhafte Konfiguration für OWFS mit einem am USB-Port angeschlossenen [http://denkovi.com/usb-to-one-wire-interface-adaptor-converter-thermometer Denkovi-Adapter] (Klon von DS9097U).

Es ist praktisch, dem Adapter ein festes Device zuzuordnen. Als erstes ermittelt man dazu den spezifischen Wert ATTRS{serial} mit:

udevadm info -a -p $(udevadm info -q path -n /dev/ttyUSB0) | grep ATTRS{serial}

Dananach legt man in /etc/udev/rules.d/ eine Datei 11-onewire.rules mit folgendem Inhalt an:

ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="DAE001nq", SUBSYSTEMS=="usb", ACTION=="add", MODE="0660", GROUP="plugdev", SYMLINK+="onewire"

Nach dem Einstöpseln des USB-Kabels vom Adapter wird über die Seriennummer DAE001nq des USB-Wandlers auf dem Adapter das Gerät erkannt und der Symlink /dev/onewire auf das eigentliche USB-Gerät (z.B. /dev/ttyUSB1) erstellt.

Eine Minimalkonfiguration für /etc/owfs.conf ist

server: device = /dev/onewire
http: port = 2121
ftp: port = 2120
server: port = 4304

Es ist sinnvoll, owhttpd installiert und laufen zu haben, um über die URL http://deinRaspberryPi:2121 zu sehen, dass owserver läuft und die Geräte am 1-wire-Bus erkennt.

==Konfiguration in FHEM==
Als erstes definiert man OWServer. Hiermit wird ein logischer OWServer definiert, auf welchem OWFS installiert ist

<nowiki>define <name> OWServer <protocol></nowiki>
<protocol> hat das Format <hostname>:<port>.

zBsp:

<nowiki>define myOWServer OWServer 192.168.14.100:4304</nowiki>
oder wenn sich OWFS auf dem gleichen Server befindet wie FHEM:

<nowiki>define myOWServer OWServer localhost:4304</nowiki>
Nach erfolgreichem "define" ist ein Klick auf den "Save" Button notwenig. Wenn nun der Status von myOWServer auf "Initialized" steht, ist der Server verbunden. Um sicher zu sein, dass der OWServer funktioniert, kann eine manuelle Abfrage der Device durchgeführt werden mit:

<nowiki>get myOWServer devices</nowiki>
Danach werden sämtliche angeschlossene Geräte angezeigt, inkl. Busmaster

===OWServer Set Befehle===
<nowiki>set <name> <value>
value:
timeout/directory
timeout/ftp
timeout/ha7
timeout/network
timeout/presence
timeout/serial
timeout/server
timeout/stable
timeout/uncached
timeout/usb
timeout/volatile
timeout/w1
units/pressure_scale
units/temperature_scale</nowiki>
Weitere Informationen zu den Set Befehlen sind im [http://owfs.org/uploads/owserver.1.html#sect41 OWServer Manual] zu entnehmen.

===OWServer Get Befehle===
<nowiki>get <name> <value>
value:
/settings/timeout/directory
/settings/timeout/ftp
/settings/timeout/ha7
/settings/timeout/network
/settings/timeout/presence
/settings/timeout/serial
/settings/timeout/server
/settings/timeout/stable
/settings/timeout/uncached
/settings/timeout/usb
/settings/timeout/volatile
/settings/timeout/w1
/settings/units/pressure_scale
/settings/units/temperature_scale</nowiki>
Zusätzlich stehen die FHEM-internen Befehle "errors" und "devices" zur Verfügung.
zBsp:

<nowiki>get <Devicename> errors #listet die Fehler des Device auf
get <Devicename> devices #scan den Server nach Device</nowiki>

===Angeschlossene Geräte auslesen===
Grundsätzlich werden die am Busmaster von OWFS angeschlossenen 1-Wire Geräte durch aktives autocreate nach einem Neustart (erfordert shutdown restart) selber in FHEM definiert.
Der Busmaster (zBsp ein DS9490r) selbst wird ebenfalls eingelesen und angezeigt.

===Definition von Geräten===
Es ist auch möglich, Geräte manuell anzulegen. Dies erfolgt in folgendem Format:

<nowiki>define <name> OWDevice <address> [<interval>]</nowiki>
zBsp:

<nowiki>define Vorlauftemp OWDevice 28.334F2B040000 60</nowiki>
Wobei der Wert 60 als Abfrageintervall in Sekunden zu verstehen ist.

===OWDevice State===
Bei Temperaturfühler wie DS18S20 wird das Reading "state" wie folgt ausgegeben:

<nowiki>temperature: 56.1875 alarm: 1</nowiki>
Um die Temperatur wie bei anderen Temperatur-Sensoren (zBsp. CUL_WS) anzuzeigen, hilft das Attribut "stateFormat". Dies kann wie folgt definiert werden:

<nowiki>attr <Devicename> stateFormat T: <wert></nowiki>
zBsp:

<nowiki>attr Boiler stateFormat T: temperature</nowiki>
alternativ

<nowiki>attr <Devicename> stateFormat {sprintf("%.1f",ReadingsVal("<Devicename>","temperature",0))."°C"}</nowiki>
Zusätzlich rundet das obenstehende Attribut mit "%.1f" die Temperatur auf eine Kommastelle.

==Tipps und Tricks==
1-wire-Geräte sind häufig generische Geräte, wie Zähler und Spannungsmesser (A/D-Wandler), an denen Sensorik hängt. Die rohen Werte vom 1-wire-Gerät (Zählimpulse, Spannungen) sind dann noch in menschenlesbare Werte zu verwandeln. Hier helfen userReadings, z.B.

<nowiki>attr myEnergyMeter userReadings energy { (ReadingsVal("myEnergyMeter","count.A",0)+AttrVal("myEnergyMeter","myBasis",0))/1250.0;; }</nowiki>

==Anwendungsbeispiele==
[[Stromzähler_und_1-Wire,_OWServer,_OWDevice|Hier]] findet man ein Beispiel einer Anbindung zweier Leistungsmesser (aka Stromzähler) mit S0 Ausgang über einen 1-wire-S0-Zähler an FHEM.

== Bekannte Probleme ==
=== FHEM hängt, wenn OWServer nicht erreichbar ist ===
Am Anfang gab es mit OWServer das Problem, dass FHEM immer komplett hing, wenn OWServer nicht erreichbar war (siehe z. B. [http://www.fischer-net.de/hausautomation/haustechnik/1-wire/60-1-wire-integration-in-fhem.html hier am Ende]). Das Problem wurde inzwischen dankenswerterweise für den laufenden Betrieb {{Link2Forum|Topic=16945|LinkText=behoben}} - <code>attr myOWServer nonblocking 1</code> muss dazu gesetzt werden -, aber zumindest beim Start hängt FHEM nach wie vor, wenn OWServer nicht erreichbar ist.

[[Kategorie:1-Wire]]

Raspberry Pi und 1-Wire

2017-05-03T17:50:48Z

Muschelpuster: Link zum RPI2-Modul hat sich geändert

Der [[:Kategorie:Raspberry Pi|Raspberry Pi]], abgekürzt RPi ist ein Einplatinencomputer der [http://www.raspberrypi.org/ Raspberry Pi Foundation], der unter Linux läuft und über eine Vielzahl von Anschlüssen verfügt.

FHEM läuft auf allen Modell des Raspberry Pi. Während [[:Kategorie:Raspberry Pi|hier]] die Installation von FHEM beschrieben wird, soll sich diese Seite nur mit dem Anschluss von 1-Wire Devices an den RPi befassen.

== Hardware ==
Bereits von der Hardware her bietet der RPi verschiedene Möglichkeiten zum Anschluss von 1-Wire-Devices

=== USB-Port ===
Über einen der USB-Ports des RPi mit entsprechendem Adapter. Hierbei sollte, wenn es sich nicht nur um wenige 1-Wire-Devices handelt, ein USB-Hub mit eigener Stromversorgung zwischengeschaltet werden. Mit USB-Extendern lässt sich dies bequem auch bis zu 20m entfernt vom RPi bewerkstelligen.

Alle bekannten USB/1-Wire Adapter arbeiten mit dem RPi. Allerdings ist es möglicherweise (nur, wenn Fehler auftreten !) nötig, dafür ein Kernel-Update durchzuführen, da in manchen älteren Versionen des Linux-Kernels für den RPi Fehler im USB-Stack enthalten sind.

=== COC-Modul ===
Anschluss über ein COC-Modul des Herstellers [http://busware.de busware.de]. Siehe hierzu im Detail [[COC und 1-wire]]].

=== RPI2-Modul ===
Anschluss über ein RPI2-Modul des Herstellers [http://www.sheepwalkelectronics.co.uk/product_info.php?products_id=30 Sheepwalk Electronics]. Dieses Modul wird direkt auf den internen I2C-Bus des RPi aufgesteckt. Im Kaufzustand bietet es für den 1-Wire-Bus sowohl eine RJ45-Buchse, als auch einen Schraubklemmenanschluss. Diese sind leider beide so hoch, dass das Modul nicht mehr in das RPi-Gehäuse passt. Hier kann aber leicht abgeholfen werden (to be continued).

Zur Ansteuerung ist auf dem RPi zunächst das Starten zweier Kernelmodule nötig, dazu als root ausführen

<nowiki>modprobe i2c-bcm2708
modprobe i2c-dev</nowiki>
Der automatische Start dieser beiden Module kann in der Datei /etc/modules eingetragen werden.

Zudem muss beim aktuellen Raspian noch die Datei /boot/config.txt angepasst werden:
<nowiki>dtparam=i2c_arm=on</nowiki>

Die oben genannten Schritte können auch über (sudo) raspi-config durchgeführt werden. Damit wird sichergestellt, dass die für die jeweilige Kernelversion notwendigen Schritte durchgeführt werden ('8 Advanced Options' -> 'A7 I2C').

Bei Vorhandensein des Paketes i2c-tools wird dann die korrekte Erkennung des Adapters mit dem Befehl

<nowiki>i2cdetect -y 1</nowiki>
überprüft, der 1-Wire-Busmaster DS2482-100 sollte als I2C-Device mit der ID 0x18 gefunden werden.

=== GPIO4-Port ===
1-wire-Komponenten können direkt an den GPIO-Port des RPi angeschlossen und in FHEM konfiguriert werden.

==== Software-Installation ====
Die Software-Installation des GPIO im RPi erfolgt je nach Kernelversion unterschiedlich:

===== vor 2015 bzw. Kernelversion 3.18.3 =====
Zur Ansteuerung ist auf dem RPi zunächst das Starten zweier Kernelmodule nötig, dazu als root ausführen

<nowiki>modprobe w1-gpio pullup=1</nowiki>
<nowiki>modprobe w1-therm</nowiki>

Waren die Schritte erfolgreich, gibt es jetzt im Verzeichnis ''/sys/bus/w1/devices/'' für jeden Sensor ein Unterverzeichnis mit seiner Kennung, z.B. ''28-000004e147d6''. Die dort stehende Datei ''w1_slave'' enthält das Ergebnis der Datenübertragung vom Sensor. Um die Module dauerhaft zu laden, sind sie noch in die Datei ''/etc/modules'' einzutragen:

<nowiki>
# /etc/modules
w1-gpio pullup=1
w1-therm </nowiki>

Um den 1-Wire Bus in FHEM einzubinden, muss noch das Modul 58_GPIO4.pm aus dem Verzeichnis ''/opt/fhem/contrib'' in das Hauptverzeichnis ''/opt/fhem/FHEM/'' kopiert werden und mit
:<code>define RPi GPIO4 BUSMASTER</code>
bekannt gemacht werden. Nach einem Neustart von FHEM werden die Sensoren automatisch erkannt (FHEM-Forum-Beitrag {{Link2Forum|Topic=10431}}).

Das beschriebene Kernelmodul unterstützt momentan die IDs 10- (DS1820 u. DS18S20) sowie 28- (DS18B20). Im "Auslieferungszustand" können maximal 10 Sensoren angeschlossen werden.
Unter [http://www.raspiprojekt.de/anleitungen/schaltungen/9-1wire-mit-temperatursensor-ds18b20.html?showall=&start=4] ist beschrieben, wie man die Anzahl erhöhen kann. Anschließend ist nur noch ein Neustart des RPi nötig.

===== ab 2015 bzw. Kernelversion 3.18.3 =====
Da sich mit Kernelversion 3.18.3 die Handhabung der Module geändert hat (vgl. [[#1-wire am GPIO4-Port funktioniert nicht mehr nach Systemupdate]] - die Datei <code>/etc/modules</code> wird im Prinzip garnicht mehr benötigt (Details s. [[#Links]]). Somit ist hier eine andere (einfachere) Konfiguration nötig:
* Am besten erst einmal ein ordentliches System-Update durchführen:
<pre>
sudo apt-get update
sudo apt-get dist-upgrade -f
sudo rpi-update
sudo reboot
</pre>
* Kernelversion kontrollieren (muss jetzt mind. v3.18.3 sein):
<pre>
uname -r
</pre>
* Dann fügt man den folgende Zeile in <code>/boot/config.txt</code> ein:
<pre>
# activating 1-wire with pullup
dtoverlay=w1-gpio-pullup
</pre>
* Und startet das System neu
<pre>
sudo reboot
</pre>

Zusätzlich kann man gleich eine '''Debugging-Funktion''' aktivieren:
* Dazu fügt man den folgende Zeile in <code>/boot/config.txt</code> ein:
<pre>
# activating device tree debugging (use: sudo vcdbg log msg)
dtdebug=on
</pre>
* Abrufen kann man die Debug-Informationen dann mit:
<pre>
sudo vcdbg log msg
</pre>

==== Elektrische Installation ====
Eine gute Einführung zum Thema geben die Links von RaspiProjekt.de (s. [[#Links]]).

Dazu wird im ersten Schritt der 1-Wire Bus (bzw. zum Test nur ein einzelner Sensor) mit dem GPIO-Port des RPi verbunden, und zwar
*1-Wire GND an GND vom Pi (Pin 6)
*1-Wire Datenleitung an GPIO04 (Pin 7)
*1-Wire VDD an +3,3V vom Pi (Pin 1)
*Ausserdem ist noch ein Pullup-Widerstand von z.B. 4,7kOhm zwischen Pin1 und Pin7 zu schalten.

Obwohl die nominale Spannung für 1-Wire Devices 5V beträgt, ist hier die verringerte Spannung nötig, weil die GPIO-Ports des RPi nur 3,3, V vertragen und durch höhere Spannungen zerstört werden. Als Alternative kann man den 1-Wire Bus auch 5V (Pin 2) anschließen, dann '''muss''' aber zwingend das Signal der 1-Wire Datenleitung durch einen Spannungsteiler (z.B. 10 kOhm und 6.8 kOhm) auf 3,3 V begrenzt werden. Besser man verwendet einen aktiven Pegelwandler der sich mit einem einfachen MOS-FET realisieren lässt : [[1-Wire Pegelwandler]]

==== Konfiguration von 1-wire-Komponenten am GPIO ====
Im Folgenden sind für verschiedene 1-wire-Komponenten die grundlegenden fhem-Konfigurationen beschrieben.

===== Konfiguration des Busmasters =====
Um 1-wire-Komponenten auslesen zu können muss zuerst der Busmaster im FHEM konfiguriert werden:
<pre>
define RPi GPIO4 BUSMASTER
</pre>

===== Temperatursensor DS18B20 =====
Ist der Temperatursensor richtig elektrisch installiert (vgl. [[#Links]] von RaspiProjekt.de), so wird automatisch ein eigenes Verzeichnis mit der ID des Sensors im 1-wire-Pfad des RPi angelegt:
<pre>
# 1-wire-Pfad des RPi:
/sys/bus/w1/devices/

# Bsp.:
$ ls /sys/bus/w1/devices/
28-001451df14ff # ID des Temperatursensors
w1_bus_master1 # Standardeintrag des 1-wire-Bus
</pre>
Am besten schliesst man mehrere Sensoren nacheinander an, damit man die ID dem richtigen Sensor zuordnen kann.

Mit der ID wird der Sensor jetzt im FHEM konfiguriert:
<pre>
define EG_Balkon GPIO4 28-001451df14ff
attr EG_Balkon model DS18B20
attr EG_Balkon room GPIO-Devices
attr EG_Balkon group 1-wire

define FileLog_EG_Balkon FileLog ./log/EG_Balkon-%Y-%W.log EG_Balkon
attr FileLog_EG_Balkon logtype text
</pre>

Den zugehörigen Plot erstellt man am einfachsten über die WebGUI des FHEM:
* ggf. FHEM neu starten (falls die Komponente und der FileLog nicht auftauchen)
* FileLog aufrufen
* "Create SVG Plot" auswählen
* ggf. Einstellungen anpassen (geht auch im Nachhinein)
* "Write .gplot file" auswählen
* weiter unten <code>attr SVG_FileLog_EG_Balkon room Balkon</code> eingeben

=== UART-Schnittstelle ===
Der RPi verfügt auch über eine UART-Schnittstelle, an diese kann direkt ein Serielles 1-Wire Interface angeschlossen werden (IN VORBEREITUNG)

== Software ==
Die Ansteuerung des 1-Wire Bus auf dem RPi kann durch unterschiedliche Software-Systeme erfolgen. Verbreitet mit FHEM sind

* '''OWX''' sowie die zugehörigen Frontendmodule OWAD, [[OWCOUNT]], OWID, OWLCD, OWMULTI, OWSWITCH und OWTHERM. Das '''OWX'''-Modul operiert direkt auf der jeweiligen Hardware (USB bzw. Seriell) oder liest die Daten über Netzwerk (COC/CUNO/Arduino) und reicht sie an spezialisierte Frontendmodule weiter.
* '''OWServer''', ein Modul, welches die vorhergehende Installation des Softwarepaketes [http://www.owfs.org OWFS] erfordert. OWFS startet einen speziellen Server, der die Kommunikation mit der Hardware übernimmt und die Daten dann an '''OWServer''' weiterleitet. Die Installtion bzw Kompilierung vom OWServer auf dem Rasperry ist unter [[OWServer & OWDevice#owfs Pakete installieren|owfs Pakete installieren]] beschrieben. Zu OWServer passt ein generisches Frontendmodul OWDevice, siehe [[OWServer & OWDevice]].

Nachfolgend ist die Kompatibilität dieser Softwaresysteme mit den einzelnen Hardware-Möglichkeiten aufgeführt.

{| class="wikitable"
! Anschluss
! Gerät
! Unterstützte 1-Wire Devices
! Besonderheit
! Stromversorgung 1-Wire Bus
|-
| Direkt an USB
| DS9490 Adapter
|
| funktioniert (DS9490R) auf dem Raspi mit OWServer ({{Link2Forum|Topic=59900}})
funktioniert nicht mit OWX, weil der enthaltene Chip DS2490 derzeit nur über libusb ansteuerbar ist. Abhilfe ist in Arbeit.
|  ??
|-
| Direkt an USB
| USB9097 Adapter
| rowspan="8" | Alle von OWX unterstützten Devices, d.h. DS18x20, DS1822 Temperatursensor DS2406, DS2408, DS2413 Schalter DS2423 Zähler DS2438 Multisensor DS2450 4 Kanal ADC LCD-Controller von [http://www.fuchs-shop.com/de/shop/6/1/13372316/ Louis Swart] Alle anderen 1-Wire Devices: Nur ID

| funktioniert auf der FB7390, das Kernelmodul ch341.ko findet man [https://sites.google.com/site/fhemarduino/file-cabinet/ch341.ko?attredirects=0&d=1 hier]
| Ja, 5V
|-
| Direkt an USB
| Eigenbau, mit FT232RL und DS2480 Bus-Master
| funktioniert, Fertiggeräte eventuell bei EBay erhältlich, siehe auch [[Interfaces für 1-Wire]]
| Ja, 5V
|-
| Direkt an USB
| LinkUSBi Adapter
| funktioniert, verwendet das FTDI Kernelmodul. Achtung: Es kann zu Timing-Problemem kommen. Erhältlich z.B. [http://www.fuchs-shop.com/de/shop/17/1/13372210/ hier]
| Ja, 5V an Pin2 (limited to 50mA)
|-
| Über USB-zu-Seriell-Konverter 9- oder 25-polig mit Winchiphead CH341-Chip
| Konverter + DS9097U-(009/S09, E25)
| funktioniert auf der FB7390, das Kernelmodul ch341.ko findet man [https://sites.google.com/site/fhemarduino/file-cabinet/ch341.ko?attredirects=0&d=1 hier]
| Nur bei den 25-poligen Modellen als Standard, bei den 9-poligen Modellen externe Versorgung oder Modifikation des DS9097 nötig
|-
| Über USB-zu-Seriell-Konverter 9- oder 25-polig mit Prolific PL2303-Chip
| Konverter + DS9097U-(009/S09, E25)
| funktioniert auf der FB7390, das Kernelmodul pl2303.ko findet man [https://groups.google.com/group/fhem-users/attach/1c0530caa5d8a864/pl2303.ko?part=2&authuser=0 hier]
| Nur bei den 25-poligen Modellen als Standard, bei den 9-poligen Modellen externe Versorgung oder Modifikation des DS9097 nötig
|-
| Über USB-zu-Seriell-Konverter 9- oder 25-polig mit FTDI RL232-Chip
| Konverter + DS9097U-(009/S09, E25)
| funktioniert auf der FB7390, das Kernelmodul ftdi_sio.ko ist auf der FritzBox vorhanden
| Nur bei den 25-poligen Modellen als Standard, bei den 9-poligen Modellen externe Versorgung oder Modifikation des DS9097 nötig
|-
| Direct an USB
| Arduino mit USB-Anschluss (UNO, Mega, Nano...)
| rowspan="2"| 1-Wire Bus direkt am Arduino (reine Softwarelösung) oder (stabiler im Betrieb) in Verbindung mit DS2482-Busmaster (am I2C des Arduinos). Mit DS2482-100 ist 1 1-Wire-Bus (optional mit Strong-pullup über externen MosFET), mit DS2482-800 sind 8 busse (nur mit internem Strong-pullup) an 1 Arduino gleichzeitig möglich.
| rowspan="2"| Ja, 3,3V oder 5V je nach Arduino-modell.
|-
| Über Netzwerk
| Arduino mit Ethernetshield, Arduino mit ENC28J60-shield, Arduino Ethernet
|-
| Über Netzwerk und CUNO
| CUNO
| Mit OWX: Alle von OWX unterstützten Devices Ohne OWX: Nur DS18x20, DS1822 Temperatursensor
| funktioniert mit gewissen Einschränkungen, siehe [[CUNO und 1-wire]]
| Ja, aber nur 3,3 V. Kann allerdings zu 5V modifiziert werden
|-
| Über Netzwerk und Ethersex-Gerät
| AVR-Net-IO oder ähnliches
| DS18x20, DS1822 Temperatursensor DS2502 EEPROM DS2450 4 Kanal ADC
| funktioniert, siehe [[FHEM und 1-Wire]]und [[AVR-NET-IO]] 
|  ??
|}

== Problembehebung ==
=== 1-wire am GPIO4-Port funktioniert nicht mehr nach Systemupdate ===
'''Problem'''

Es kann passieren, dass nach einem Systemupdate (apt-get update oder apt-get dist-upgrade) die 1-wire-Geräte am GPIO4-Port plötzlich nicht mehr funktionieren. Dies hat dann aller Wahrscheinlichkeit die Ursache, dass ein Kernel-Upgrade von "vor 3.18.3" auf "danach" gemacht wurde. Mit Kernelversion 3.18.3 ist die Handhabung der Kernelmodule umgestellt worden (vgl. auch [[#GPIO4-Port]]):
* vor v3.18.3: hier wurden Module in die /etc/modules eingetragen. Dieses Vorgehen ist fast überall beschrieben.
* ab v3.18.3: jetzt wurde das sog. Device-Tree-Verfahren eingeführt, das anders arbeitet - und erst einmal die alte Konfiguration blockiert (!). (Details s. unter [[#Links]])
Auch ein Aufruf von <code>sudo rpi-update</code> hilft allein nicht weiter (ist aber immer sinnvoll).

'''Lösung'''

Die "korrekte" Lösung wäre die Umstellung auf Device-Tree-Konfiguration:
* Dazu fügt man den folgende Zeile in <code>/boot/config.txt</code> ein:
<pre>
# activating 1-wire with pullup
dtoverlay=w1-gpio-pullup
</pre>
* Entfernt die Module <code>w1-gpio</code> und <code>w1-therm</code> aus das <code>/etc/modules</code> (oder kommentiert sie aus)
* Und startet das System neu

Zusätzlich kann man gleich eine '''Debugging-Funktion''' aktivieren:
* Dazu fügt man den folgende Zeile in <code>/boot/config.txt</code> ein:
<pre>
# activating device tree debugging (use: sudo vcdbg log msg)
dtdebug=on
</pre>
* Abrufen kann man die Debug-Informationen dann mit:
<pre>
sudo vcdbg log msg
</pre>

'''Alternativer Workaround'''

Alternativ zur "korrekten" Lösung kann man die Device-Tree-Funktionalität auch einfach deaktivieren - dann bleibt alles wie bisher.

* Dazu fügt man den folgende Zeile in <code>/boot/config.txt</code> ein:
<pre>
# disabling device tree functionality:
device_tree=
</pre>
* Und startet das System neu.

== Links ==
Zu GPIO:
* [http://neubert-volmar.de/Hausautomation/RaspberryPi/index.html Beispiel zur Nutzung von 1-wire am GPIO-Port & eines Eigenbau-Adapters]
* [https://raspiprojekt.de/anleitungen/hardware/147-gpio-grundlagen.html RaspiProjekt.de - GPIO-Grundlagen]
* [http://www.raspberrypi.org/documentation/usage/gpio/ RaspberryPi.org - GPIO-Grundlagen]
* [http://pi.gadgetoid.com/pinout/pin7_gpio4 Pin-Belegungen des Raspi]
* [https://www.raspiprojekt.de/anleitungen/schaltungen/9-1wire-mit-temperatursensor-ds18b20.html RaspiProjekt.de - Anbindung von Temperatursensoren]

Zu Device-Tree:
* [https://www.raspiprojekt.de/21-blog/153-neuer-kernel-neues-glueck.html RaspiProjekt.de - Neuer Kernel neues Glück]
* [http://www.raspberrypi.org/documentation/configuration/device-tree.md RaspberryPi.org - Device Trees, Overlays and Parameters]
* [https://raspiprojekt.de/anleitungen/hardware/154-geraetetreiber-und-device-tree.html RaspiProjekt.de - Gerätetreiber und Device Tree]
* [https://github.com/raspberrypi/linux/tree/rpi-3.18.y/arch/arm/boot/dts Liste aller verfügbaren Device-Tree Module]

[[Kategorie:Raspberry Pi]]
[[Kategorie:1-Wire]]
[[Kategorie:Interfaces]]

DOIF/do always Alternative am Beispiel einer Batteriewarnung via Telegram

2016-12-30T15:34:29Z

Muschelpuster: Erstellung des Beitrages - leider ohne Labor-Import, da zu viele Abhängigkeiten erfüllt sein müssten

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Alarm bei Battery low eines Homematic-Gerätes==
Würde ohne das Attribut do always gearbeitet werden, so würde das DOIF genau eine Meldung verschicken. Selbst, wenn die Batterie getauscht wurde und eine eine andere Batterie zur Neige geht, käme keine Meldung mehr, da DOIF noch auf ein 'Rücksetzen' der Meldung wartet. Das Attribut do always würde jedoch wiederum bei jedem Event eine Meldung erzeugen (z.B. alle 30 Min.), was doch etwas zu sehr nerven könnte. Das Ziel ist es also, 1x täglich die Meldung zu versenden.
===Beschreibung===
Mittels einer strikten Namensvergabe der Devices kann man sehr einfach alle Homatic-Geräte greifen. Hierbei ist es auch erst einmal unerheblich, ob sie eine Batterie haben, denn netzbetriebene Geräte werden nie das passende Event schicken. Im Beispiel wird nun davon ausgegangen, dass alle Homematic-Geräte mit dem Namenspräfix HM_ beginnen. 
Der reguläre Ausdruck sichert alle Events, unabhängig davon, ob der Battery groß oder klein geschrieben ist, oder auch Batterie dort steht. 
Zum täglichen 'Rücksetzen' des DOIF wird eine 2., zeitbasierte Bedingung definiert, welche das DOIF von state cmd1 (nach einer ausgelösten Warnung) auf cmd2 wechseln lässt. So wird führt das nächste Event wieder zu einer Warnung. 
===Definition===
<pre>
define di_HM_Batt_Warn DOIF (["HM_.*:[Bb]atte.*[Ll]ow"]) (set telegramBot message @xxxxxxx Batterie eines Homematic-Gerätes leer!)
DOELSEIF ([10:00])
attr di_HM_Batt_Warn room CUL_HM
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-12-01T17:05:20Z

Muschelpuster: /* Laborgruppe zum Import mit Raw definition */

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natürlich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben werden. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|8])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|7])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]
and
[?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])
(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
attr du_Labor_Rollladen setList state:slider,0,1,100
attr du_Labor_Rollladen stateFormat state%
attr du_Labor_Rollladen webCmd state
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]\
and\
[?du_Labor_Rollladen:state] > 75\
and\
[?06:15-11:00|8])\
(set du_Labor_Rollladen 0)\
DOELSEIF\
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]\
and\
[?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|7])\
(set du_Labor_Rollladen 0)\
DOELSEIF\
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]\
and\
[?du_Labor_Rollladen:state] < 10\
and\
[?15:00-22:00])\
(set du_Labor_Rollladen 100)\
DOELSEIF\
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-12-01T17:04:48Z

Muschelpuster: /* Definition */

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natürlich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben werden. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|8])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|7])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]
and
[?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])
(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
attr du_Labor_Rollladen setList state:slider,0,1,100
attr du_Labor_Rollladen stateFormat state%
attr du_Labor_Rollladen webCmd state
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]\
and\
[?du_Labor_Rollladen:state] > 75\
and\
[?06:15-11:00|12345])\
(set du_Labor_Rollladen 0)\
DOELSEIF\
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]\
and\
[?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06])\
(set du_Labor_Rollladen 0)\
DOELSEIF\
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]\
and\
[?du_Labor_Rollladen:state] < 10\
and\
[?15:00-22:00])\
(set du_Labor_Rollladen 100)\
DOELSEIF\
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-11-25T12:32:19Z

Muschelpuster: Fehler beim Import korrigiert (Umbrüche)

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natürlich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben werden. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|12345])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|06])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]
and
[?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])
(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
attr du_Labor_Rollladen setList state:slider,0,1,100
attr du_Labor_Rollladen stateFormat state%
attr du_Labor_Rollladen webCmd state
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]\
and\
[?du_Labor_Rollladen:state] > 75\
and\
[?06:15-11:00|12345])\
(set du_Labor_Rollladen 0)\
DOELSEIF\
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]\
and\
[?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06])\
(set du_Labor_Rollladen 0)\
DOELSEIF\
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]\
and\
[?du_Labor_Rollladen:state] < 10\
and\
[?15:00-22:00])\
(set du_Labor_Rollladen 100)\
DOELSEIF\
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-11-25T12:12:15Z

Muschelpuster: Rollladen Dummy auch als Slider macht das Testen im Labor einfacher

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natürlich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben werden. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|12345])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|06])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]
and
[?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])
(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
attr du_Labor_Rollladen setList state:slider,0,1,100
attr du_Labor_Rollladen stateFormat state%
attr du_Labor_Rollladen webCmd state
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|12345]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state] and [?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])(set du_Labor_Rollladen 100)
DOELSEIF
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-11-25T08:36:08Z

Muschelpuster: Halbsatz ergänzt

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natürlich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben werden. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|12345])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|06])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]
and
[?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])
(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|12345]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state] and [?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])(set du_Labor_Rollladen 100)
DOELSEIF
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-11-25T08:33:50Z

Muschelpuster: Rechtschreibfehler

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natürlich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|12345])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|06])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]
and
[?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])
(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|12345]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state] and [?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])(set du_Labor_Rollladen 100)
DOELSEIF
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-11-25T08:24:38Z

Muschelpuster: Umbrüche zur besseren Lesbarkeit

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natülich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|12345])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state]
and
[?du_Labor_Rollladen:state] > 75
and
[?06:15-11:00|06])
(set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state]
and
[?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])
(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|12345]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state] and [?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])(set du_Labor_Rollladen 100)
DOELSEIF
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-11-25T08:08:01Z

Muschelpuster: Rechtschreibung

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natülich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|12345]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state] and [?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|12345]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state] and [?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])(set du_Labor_Rollladen 100)
DOELSEIF
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

DOIF

2016-11-25T08:07:19Z

Muschelpuster: Link zu Beispiel Rollladen ergänzt

{{Infobox Modul
|ModPurpose=Do ... if ...
|ModType=h
|ModForumArea=Automatisierung/DOIF
|ModTechName=98_DOIF.pm
|ModOwner=Damian}}

[[DOIF]] ist ein universelles Modul, welches sowohl ereignis- als auch zeitgesteuert arbeitet. Es vereinigt die Funktionalität eines [[notify]]-, [[at]]-, [[watchdog]]-Befehls in Kombination mit logischen Abfragen unter einem Dach. Damit können insb. komplexere Problemstellungen innerhalb eines DOIF-Moduls gelöst werden, die sonst nur mit Hilfe einzelner Module an mehreren Stellen in FHEM vorgenommen werden müssten. Es ermöglicht, Aktionen ("do") unter bestimmten Bedingungen ("if") auszuführen. Bedingungen umfasst auch Konstrukte wie "wenn Zustand x für y Minuten... (Zeitsteuerung)".

== Voraussetzungen ==
keine

== Anwendung ==
=== Define ===
Siehe Commandref [http://fhem.de/commandref_DE.html#DOIF Define]

=== Attribute ===
Siehe Commandref [http://fhem.de/commandref_DE.html#DOIF_Attribute Attribute]

===Kurzreferenz===
Siehe Commandref [http://fhem.de/commandref_DE.html#DOIF_Kurzreferenz Kurzreferenz]

== Anwendungsbeispiele ==
Der Modulautor hat im deutschen Teil der [http://fhem.de/commandref_DE.html#DOIF Commandref] eine Vielzahl von einfachen und auch komplexeren Beispielen zur Nutzung von DOIF aufgenommen. Darum wird hier auf weitere Beispiele zu DOIF verzichtet. Ausführliche Code-Beispiele zu DOIF bitte gegebenenfalls als eigene Wiki-Seite unter [[:Kategorie:Code Snippets|Code Snippets]] aufnehmen.

== Links ==
* [[DOIF/Tools und Fehlersuche]]
* [[DOIF/Tipps zur leichteren Bedienung]] Erstellung, Bearbeitung, Syntaxhervorhebung, Klammerprüfung, Suchen&Ersetzen, uvm. (nicht nur) von DOIF
* [[DOIF/Labor - ausführbare, praxisnahe Beispiele als Problemlösung zum Experimetieren]]
* [[DOIF/Import von Code Snippets]]
* [[DOIF/Operatorenrangfolge]]
* [[DOIF/Ein- und Ausgabe in FHEMWEB und Tablet-UI am Beispiel einer Schaltuhr]]
* [[DOIF/Mehrfachnutzung eines Tasters]]
* [[DOIF/Zeitgeber]] Wecker, Kurzzeitwecker, Tageszeitgeber
* [[DOIF/Zeitspanne zwischen zwei Terminen schalten]]
* [[DOIF/do always Alternative am Beispiel einer Rollladenautomatik]]

===Entwicklungshistorie===
* {{Link2Forum|Topic=58556|LinkText=Forenthread}} neue Features: Ereignisfilter, Attribut checkall, setList, readingList
* {{Link2Forum|Topic=56851|LinkText=Forenthread}} Stati, Readings in Zeitfunktionen, set enable
* {{Link2Forum|Topic=55785|LinkText=Forenthread}} neue Features: disablecondition, Stati bei Zeitfunktionen (Anm.: disablecondition nicht eingeführt)
* {{Link2Forum|Topic=51117|LinkText=Forenthread}} Möglichkeit auf passende Events zu beschränken
* {{Link2Forum|Topic=51060|LinkText=Forenthread}} Neue Features - $SELF, $self, cmd-Reading, timerevent, selftrigger ...
* {{Link2Forum|Topic=49109|LinkText=Forenthread}} DOIF als endlicher Automat (finite state maschine)
* {{Link2Forum|Topic=48925|LinkText=Forenthread}} serialisierte Timer
* {{Link2Forum|Topic=46327|LinkText=Forenthread}} neue Features: Generalisierung, $DEVICE, $EVENT, Attribut notexist
* {{Link2Forum|Topic=43638|LinkText=Forenthread}} Attribut repeatcmd
* {{Link2Forum|Topic=41859|LinkText=Forenthread}} unabsichtliche Loops unterbunden
* {{Link2Forum|Topic=39070|LinkText=Forenthread}} wait als sleep Alternative
* {{Link2Forum|Topic=36889|LinkText=Forenthread}} mehrere DOIF-Zweige (Anm.: nicht eingeführt)
* {{Link2Forum|Topic=35638|LinkText=Forenthread}} neue Zeit-Features
* {{Link2Forum|Topic=35045|LinkText=Forenthread}} Zeitraster
* {{Link2Forum|Topic=34767|LinkText=Forenthread}} indirekten Zeitangaben, readingFnAttributes
* {{Link2Forum|Topic=34365|LinkText=Forenthread}} indirekten Zeitangaben
* {{Link2Forum|Topic=30847|LinkText=Forenthread}} relative Zeitangaben, Attribute: do resetwait, cmdpause, repeatsame, uvm.
* {{Link2Forum|Topic=23833|LinkText=Forenthread}} zur Entstehung dieses Moduls

DOIF/do always Alternative am Beispiel einer Rollladenautomatik

2016-11-25T08:04:40Z

Muschelpuster: Die Seite wurde neu angelegt: „DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geeändert werden, doch manchmal ist ei…“

DOIF führt die Anweisungen einer Bedingung nur 1x aus. Das kann durch Setzen des Attributes 'do' mit dem Wert 'always' geeändert werden, doch manchmal ist eine Mix aus beiden Situationen interessant, wie dieses Beispiel zeigen soll.
==Rollladensteuerung mittels Twilight==
Die Rollläden sollen bei einstellbaren Twilight-Werten hoch, bzw. runter gefahren werden. Natürlich passt diese Automatik nicht immer und es wird manuell eingegriffen. Diese manuellen Eingriffe sollen natülich erkannt werden und Vorrang genießen.
===Beschreibung===
Der Rollladen wird in diesem Beispiel durch das Dummy du_Labor_Rollladen ersetzt. Der Wert 0 entspricht einer kompletten Öffnung, 100 ist komplett zu. 
Zur Prüfung eines manuellen Eingriffs wird die Rolladenposition im DOIF heran gezogen. Im echten Leben könnte gleichzeitig noch geprüft werden, ob z.B. die Terrassentür offen ist, denn wenn man auf der Terrasse ist und die Automatik zuschlägt ist das auch kontraproduktiv. Ebenso ist es schlecht, wenn das Fenster hinter dem geschlossenen Rollladen zum Lüften im Sommer auf ist und der Rollladen unbeaufsichtigt öffnet. 
Wenn nun morgens der Rollladen geöffnet wird, dann geht das DOIF auf State=cmd1 und führt die morgendliche Anweisung erst wieder aus, wenn der State ungleich cmd1 ist. Werden Abends die Rollläden nun aber manuell vor der automatischen Zeit geschlossen, würde dieser Statuswechsel nicht erfolgen und am nächsten Morgen die Automatik auch nicht funktionieren. 
Auf den ersten Blick erscheint das 'do always' hier ein gutes Mittel zu sein. Dies kann jedoch im umgekehrten Fall stören. Werden die automatisch geschlossenen Rollläden nochmals manuell geöffnet, dann würden sie beim nächsten Event vom Twilight erneut herunter fahren. Also muss der Status vom DOIF auf einem anderen Weg geändert werden. Dazu kann als letzte Bedingung einfach ein zeitlicher Trigger (Mittags und Nachts, wenn die Automatik sozusagen die Richtung umkehrt) ohne Kommando angegeben. Damit geht der Status im Beispiel auf cmd4 und das DOIF ist wieder 'scharf' für den nächsten Einsatz.

===Definition===
<pre>
define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|12345]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state] and [?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])(set du_Labor_Rollladen 85)
DOELSEIF
([00:15] or [12:00])
</pre>

===Laborgruppe zum Import mit [[DOIF/Import von Code Snippets|Raw definition]]===
<pre>
define TL_Labor_Berlin Twilight 52.522297 13.413140 1 638242
attr TL_Labor_Berlin alias Twilight Wetter
attr TL_Labor_Berlin group Rollläden
attr TL_Labor_Berlin room DOIF_Labor
attr TL_Labor_Berlin sortby 4
attr TL_Labor_Berlin stateFormat twilight_weather%

define du_Labor_Rollo_TL_auf dummy
attr du_Labor_Rollo_TL_auf alias Rollläden nach %-Licht auf (Mo-Fr -> 100=aus)
attr du_Labor_Rollo_TL_auf group Rollläden
attr du_Labor_Rollo_TL_auf room DOIF_Labor
attr du_Labor_Rollo_TL_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_auf webCmd state
setstate du_Labor_Rollo_TL_auf 40

define du_Labor_Rollo_TL_WE_auf dummy
attr du_Labor_Rollo_TL_WE_auf alias Rollläden nach %-Licht auf (Sa/So -> 100=aus)
attr du_Labor_Rollo_TL_WE_auf group Rollläden
attr du_Labor_Rollo_TL_WE_auf room DOIF_Labor
attr du_Labor_Rollo_TL_WE_auf setList state:slider,0,1,100
attr du_Labor_Rollo_TL_WE_auf webCmd state
setstate du_Labor_Rollo_TL_WE_auf 50

define du_Labor_Rollo_TL_zu dummy
attr du_Labor_Rollo_TL_zu alias Rollläden nach %-Licht zu (Mo.-So. -> 0=aus)
attr du_Labor_Rollo_TL_zu group Rollläden
attr du_Labor_Rollo_TL_zu room DOIF_Labor
attr du_Labor_Rollo_TL_zu setList state:slider,0,1,100
attr du_Labor_Rollo_TL_zu webCmd state
setstate du_Labor_Rollo_TL_zu 20

define du_Labor_Rollladen dummy
attr du_Labor_Rollladen alias Simmulation Rollladen
attr du_Labor_Rollladen group Rollläden
attr du_Labor_Rollladen room DOIF_Labor
setstate du_Labor_Rollladen 0

define di_Labor_Rollo_TL DOIF ([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|12345]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] > [?du_Labor_Rollo_TL_WE_auf:state] and [?du_Labor_Rollladen:state] > 75 and [?06:15-11:00|06]) (set du_Labor_Rollladen 0)
DOELSEIF
([TL_Labor_Berlin:twilight_weather] < [?du_Labor_Rollo_TL_zu:state] and [?du_Labor_Rollladen:state] < 10 and [?15:00-22:00])(set du_Labor_Rollladen 100)
DOELSEIF
([00:15] or [12:00])

attr di_Labor_Rollo_TL alias DOIF Rollläden Twilight
attr di_Labor_Rollo_TL group Rollläden
attr di_Labor_Rollo_TL room DOIF_Labor

save
</pre>

[[Kategorie:HOWTOS]]
[[Kategorie:Code Snippets]]

HM-LC-Sw1PB-FM Schaltaktor mit Tasteraufsatz 1fach

2016-09-15T09:32:13Z

Muschelpuster: Problemehandling ergänzt

Funk-Schaltaktor mit Tasteraufsatz 1fach Unterputz

= Features =

Wandtaster im Peha Aura Gehäuse, mit Unterputz Funk-Schaltaktor , der in eine typische Installationsdose passt. Dadurch Austausch eines Wandschalters beim Erhalt der lokalen Schaltfunktion und gleichzeitiger Fernsteuerbarkeit.

= Hinweise zur Hardware-Installation =

Der Taster Ersetzt einen bisherigen Schalter komplett und kombiniert die Funktion eines Unterputzaktors mit dem notwendigen Taster, sodass nicht erst passende Taster gesucht werden müssen. Der Taster selber baut sehr flach, sodass der Aktor mit Taster meist besser in vorhandene Unterputzdosen passt als normale Taster mit einem seperaten Unterputztaktor wie z.b. dem [[HM-LC-SW1-FM]]. Allerdings ist der HM-LC-Sw1PB-FM auch vergleichsweise teuer.

= Hinweise zum Betrieb mit FHEM =

Problemlos verwendbar. Das [[Pairing (HomeMatic)|Pairing]] sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden.

= Probleme =
Wenn das Pairing nicht komplett durchläuft (Device zeigt als Status MissingACK und kann nicht von FHEM aus gesteuert werden), dann hilft ggf. ein weiteres Pairing über hmPairSerial.

= Links =

Anleitung [http://www.elv-downloads.de/Assets/Produkte/8/855/85522/Downloads/85522_HM_LC_Sw1PB_FM_UM.pdf] PDF

[[Kategorie:HomeMatic Components]]
[[Kategorie:Schalter (Empfänger)]]

HM-LC-SW1-FM Schaltaktor 1-fach UP

2016-09-15T09:29:23Z

Muschelpuster: /* Probleme */

Homematic Funk-Schaltaktor 1-fach (Unterputz)

== Features ==

Schalten eines angeschlossenen Verbrauchers mittels [[CUL]]/[[CUN]]/[[HMLAN Konfigurator]] und über einen mechanischen spannungsfesten Taster.

'''Technische Daten:'''
* Schaltvermögen: 16A bei 230V/50Hz (ohmsche Last)
* Relais: 1x Schließer
* Standby Verbrauch: 0,5W
* Maße(BxHxT): 53x53x30mm

== Hinweise zur Hardware-Installation ==

Will man die Funk-Schaltaktoren auch manuell betreiben, d.h. man upgradet eine vorhandene Elektroinstallation, so sind Taster notwendig. Schalter können notfalls mittels einer zusätzlichen Feder zu Taster umgebaut werden, Tastschalter sind leider nicht geeignet. Schalter und Tastschalter führen dazu, dass der Aktor nach Betätigung des Schalters in den Anlernmodus versetzt wird und auch in diesem verbleibt.

Je nach vorhandenen Schalterdosen empfiehlt es sich bestehende Schalterdosen nach hinten auszuweiten, d.h. die Abdeckung nach hinten heraus zu brechen, da die Aktoren und Kabel nicht gerade sparsam mit dem Platz umgehen. Alternativ könnte man den Aktor auch in eine zusätzliche Schalterdosen unterbringen und diese mit einem Federdeckel abschließen. Dies hat den Vorteil, dass man auch durch relativ dicke Tapete die LED und somit den Zustand des Aktors ablesen kann.

Der Aktor kann auch gänzlich ohne Taster, also nur per ''set''-Befehlen durch Fhem oder per gepeerten Geräten gesteuert werden, jedoch muss zumindest für das Anlernen zeitweise ein Taster angeschlossen werden.

== Hinweise zum Betrieb mit FHEM ==

Das [[Pairing (HomeMatic)|Pairing]] sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Hierfür wird ein am Aktor temporär angeschlossener spannungsfester Taster zwingend benötigt.

# Sicherstellen, dass ''autocreate'' aktiv ist
# Am CUL/HMLAN o.ä. <code>set HMLAN hmPairForSec 60</code>
# Binnen 60 Sekunden Aktor in Anlernmodus bringen (Taster 4s festhalten bis LED blinkt) -> Device wird in fhem angelegt, z.B. als CUL_HM_HM_LC_SW1_FM_2BAD45
# <code>rename <Aktor> <AktorNameNeu></code> -> richtigen Namen zuordnen

=== FHEM Config-Auszug ===

Ein exemplarischer Auszug aus der fhem.cfg:

<pre>
define LichtTerasse CUL_HM 17AEA6
attr LichtTerasse devInfo 010100
attr LichtTerasse firmware 1.9
attr LichtTerasse hmClass receiver
attr LichtTerasse model HM-LC-SW1-FM
attr LichtTerasse room Terasse
attr LichtTerasse serialNr IEQ00xxxx
attr LichtTerasse subType switch
</pre>

=== Mögliche Schaltoperationen ===

Der Aktor versteht folgende Aktionen:
<pre>
set <name> on -> Schaltet den Aktor ein
set <name> off -> Schaltet den Aktor aus
set <name> toggle -> Ändert den Zustand des Aktors, d.h. ein eingeschalteter Aktor wird ausgeschaltet
</pre>

=== Log-Auszug ===

In FHEM ist nach dem Schalten des HM-LC-SW1-FM folgendes Log zu sehen:
<pre>
2012.02.05 16:51:44 2: CUL_HM set LichtTerasse on
2012.02.05 16:52:14 2: CUL_HM set LichtTerasse off
2012.02.05 16:52:15 2: CUL_HM set LichtTerasse toggle
</pre>

== Nützliches Zubehör ==

Wer den Schaltaktor im Sicherungskasten selbst einbauen möchte, z.B. um einen Stromstossschalter zu ersetzen, dem kann folgendes Zubehör empfohlen werden: Hutschienengehäuse CNMB-4V-Kit, Bestellnr. 532659 bei conrad. Das ist zwar sicher auch nicht VdE-konform, aber besser wie ohne. Alternativ kann auch der [[HM-LC-Sw1-DR 1fach Schaltaktor Hutschiene]] zur direkten Montage auf Hutschienen eingesetzt werde.

== Probleme ==

Um den HM-LC-SW1-FM in den Anlernmodus zu versetzen, soll man lt. Anleitung den (temporär) angeschlossenen Taster für 4 Sekunden gedrückt halten. Falls dies bei Ihnen nicht funktioniert, so versuchen Sie den Taster einfach mal ca. 7 bis 8 Sekunden gedrückt zu halten (bis die LED des SW1-FM kurz aufleuchtet).

Wenn das Pairing nicht komplett durchläuft (Device zeigt als Status MissingACK und kann nicht von FHEM aus gesteuert werden), dann hilft ggf. ein weiteres Pairing über hmPairSerial.

== Links ==

Ein Integrationsbeispiel ist in [[Jalousie und Beleuchtung in mehreren Räumen]] zu finden.

[http://files.elv.de/Assets/Produkte/7/767/76793/Downloads/76793_HM_LC_Sw1_FM_um.pdf Anleitung (PDF)]

[[Kategorie:HomeMatic Components]]
[[Kategorie:Schalter (Empfänger)]]

HM-LC-SW1-FM Schaltaktor 1-fach UP

2016-09-15T09:28:57Z

Muschelpuster: /* Probleme */ -> https://forum.fhem.de/index.php/topic,57708.0.html

Homematic Funk-Schaltaktor 1-fach (Unterputz)

== Features ==

Schalten eines angeschlossenen Verbrauchers mittels [[CUL]]/[[CUN]]/[[HMLAN Konfigurator]] und über einen mechanischen spannungsfesten Taster.

'''Technische Daten:'''
* Schaltvermögen: 16A bei 230V/50Hz (ohmsche Last)
* Relais: 1x Schließer
* Standby Verbrauch: 0,5W
* Maße(BxHxT): 53x53x30mm

== Hinweise zur Hardware-Installation ==

Will man die Funk-Schaltaktoren auch manuell betreiben, d.h. man upgradet eine vorhandene Elektroinstallation, so sind Taster notwendig. Schalter können notfalls mittels einer zusätzlichen Feder zu Taster umgebaut werden, Tastschalter sind leider nicht geeignet. Schalter und Tastschalter führen dazu, dass der Aktor nach Betätigung des Schalters in den Anlernmodus versetzt wird und auch in diesem verbleibt.

Je nach vorhandenen Schalterdosen empfiehlt es sich bestehende Schalterdosen nach hinten auszuweiten, d.h. die Abdeckung nach hinten heraus zu brechen, da die Aktoren und Kabel nicht gerade sparsam mit dem Platz umgehen. Alternativ könnte man den Aktor auch in eine zusätzliche Schalterdosen unterbringen und diese mit einem Federdeckel abschließen. Dies hat den Vorteil, dass man auch durch relativ dicke Tapete die LED und somit den Zustand des Aktors ablesen kann.

Der Aktor kann auch gänzlich ohne Taster, also nur per ''set''-Befehlen durch Fhem oder per gepeerten Geräten gesteuert werden, jedoch muss zumindest für das Anlernen zeitweise ein Taster angeschlossen werden.

== Hinweise zum Betrieb mit FHEM ==

Das [[Pairing (HomeMatic)|Pairing]] sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden. Hierfür wird ein am Aktor temporär angeschlossener spannungsfester Taster zwingend benötigt.

# Sicherstellen, dass ''autocreate'' aktiv ist
# Am CUL/HMLAN o.ä. <code>set HMLAN hmPairForSec 60</code>
# Binnen 60 Sekunden Aktor in Anlernmodus bringen (Taster 4s festhalten bis LED blinkt) -> Device wird in fhem angelegt, z.B. als CUL_HM_HM_LC_SW1_FM_2BAD45
# <code>rename <Aktor> <AktorNameNeu></code> -> richtigen Namen zuordnen

=== FHEM Config-Auszug ===

Ein exemplarischer Auszug aus der fhem.cfg:

<pre>
define LichtTerasse CUL_HM 17AEA6
attr LichtTerasse devInfo 010100
attr LichtTerasse firmware 1.9
attr LichtTerasse hmClass receiver
attr LichtTerasse model HM-LC-SW1-FM
attr LichtTerasse room Terasse
attr LichtTerasse serialNr IEQ00xxxx
attr LichtTerasse subType switch
</pre>

=== Mögliche Schaltoperationen ===

Der Aktor versteht folgende Aktionen:
<pre>
set <name> on -> Schaltet den Aktor ein
set <name> off -> Schaltet den Aktor aus
set <name> toggle -> Ändert den Zustand des Aktors, d.h. ein eingeschalteter Aktor wird ausgeschaltet
</pre>

=== Log-Auszug ===

In FHEM ist nach dem Schalten des HM-LC-SW1-FM folgendes Log zu sehen:
<pre>
2012.02.05 16:51:44 2: CUL_HM set LichtTerasse on
2012.02.05 16:52:14 2: CUL_HM set LichtTerasse off
2012.02.05 16:52:15 2: CUL_HM set LichtTerasse toggle
</pre>

== Nützliches Zubehör ==

Wer den Schaltaktor im Sicherungskasten selbst einbauen möchte, z.B. um einen Stromstossschalter zu ersetzen, dem kann folgendes Zubehör empfohlen werden: Hutschienengehäuse CNMB-4V-Kit, Bestellnr. 532659 bei conrad. Das ist zwar sicher auch nicht VdE-konform, aber besser wie ohne. Alternativ kann auch der [[HM-LC-Sw1-DR 1fach Schaltaktor Hutschiene]] zur direkten Montage auf Hutschienen eingesetzt werde.

== Probleme ==

Um den HM-LC-SW1-FM in den Anlernmodus zu versetzen, soll man lt. Anleitung den (temporär) angeschlossenen Taster für 4 Sekunden gedrückt halten. Falls dies bei Ihnen nicht funktioniert, so versuchen Sie den Taster einfach mal ca. 7 bis 8 Sekunden gedrückt zu halten (bis die LED des SW1-FM kurz aufleuchtet).
Wenn das Pairing nicht komplett durchläuft (Device zeigt als Status MissingACK und kann nicht von FHEM aus gesteuert werden), dann hilft ggf. ein weiteres Pairing über hmPairSerial.

== Links ==

Ein Integrationsbeispiel ist in [[Jalousie und Beleuchtung in mehreren Räumen]] zu finden.

[http://files.elv.de/Assets/Produkte/7/767/76793/Downloads/76793_HM_LC_Sw1_FM_um.pdf Anleitung (PDF)]

[[Kategorie:HomeMatic Components]]
[[Kategorie:Schalter (Empfänger)]]

AMAD

2016-05-03T21:08:56Z

Muschelpuster: Accessibility service not running

{{Infobox Modul
|ModPurpose=Steuern von Adroidgeräten und Anzeige von bestimmten Informationen dieser Geräte
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModTechName=74_AMAD.pm
|ModOwner=CoolTux ([http://forum.fhem.de/index.php?action=profile;u=13684 Forum] / [[Benutzer:CoolTux|Wiki]])
}}

==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 oder Ihr holt Euch die Testversion von [https://automagic4android.com/de/testversion hier], 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==
<code>define <name> AMAD <IP-ADRESSE> <WLANAP-SSID('s)></code>
'''!!! Wichtig - Es dürfen ausschließlich nur IP Adressen verwendet werden, keine FQDN !!!'''

'''Beispiel:'''

<code>define WandTabletWohnzimmer AMAD 192.168.0.23 TuxNetAP,Opa@@Zu@@Hause</code>

Diese Anweisung erstellt zwei neues AMAD-Device im Raum AMAD.Der Parameter <IP-ADRESSE> legt die IP Adresse des Android Gerätes fest und der Parameter WLANAP-SSID die SSID Deines WLAN's. Es können mehrere SSID's mit angegeben werden, welche dann durch Komma getrennt sein müssen. Haben die SSID's Leerzeichen im Namen werde die Leerzeichen durch 2 @ aufgefüllt. Gibt es Androidgeräte welche nicht über WLAN sondern USB-Ethernet angeschlossen sind, ist die WLANAP-SSID mit "usb-ethernet" zu benennen
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

<code>
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
</code>

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
* 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. !!!Gibt nicht den tatsächlichen Status des Gerätes wieder!!! deviceState muss von Hand selbst gesetzt werden. (set DEVICE deviceState) z.B. über die Anwesenheitskontrolle. Ist Offline gesetzt, können keine set Befehle abgesetzt werden.
* 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
* 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
* 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'''
* 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/'''
* setTtsMsgSpeed - setzt die Sprachgeschwindigkeit bei der Sprachausgabe '''(Werte zwischen 0.5 bis 4.0 in 0.5er Schritten) default ist 1.0'''

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

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

=== 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

[[Datei:Screenshot 2016-01-13-17-11-19.png|200px]]

=== Schaltbefehle vom Androidgerät an FHEM senden ===
Hierfür richte bitte einen eigen Flow ein. Wie das genau geht, verrät Dir die Hilfe.
Du kannst einen ersten Eindruck bekommen wenn Du Dir den Flow VoiceControl an schaust, speziell die HTTP Request Aktion.
Als Aktion für Deinen eigenen Flow wählst Du HTTP Request mit folgendem Inhalt

[[Datei:Screenshot 2016-01-13-17-22-16.png|200px]]

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

PS: Screenshots werden folgen

== Bekannte Meldungen/Hinweise/Probleme ==
<code>PERL WARNING: Use of uninitialized value in hash element at /opt/fhem/FHEM/74_AMAD.pm line 145</code>

Diese Meldung/Hinweis ist bekannt und es wird daran gearbeitet!

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.

==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.''

TelegramBot

2016-04-26T16:16:27Z

Muschelpuster: /* Favoriten für Kommandos anlegen */

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das perl JSON modul installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

Der Versand ist nicht direkt über das Device möglich, jedoch über den Perl-Befehl 'TelegramBot_ExecuteCommand':

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

Hierbei ist die Ziel-ID ohne das @-Zeichen, Anführungszeichen o.ä. anzugeben. Das Ziel kann auch eine Gruppen-ID (beginnend mit dem Minus-Zeichen) sein. Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message \@meine_ZielID Mein Text" ;; TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

==== Favoriten für Kommandos anlegen ====

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

/short1 = set TYPE=ROLLADEN pos 100

/short2 = set TYPE=ROLLADEN pos 0

</pre>

Die Antworten werden als Schaltflächen dargestellt (Telegram inline Keyboard) und können am Mobile-Client direkt angeklickt werden um sie auszuführen.
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:

<code>[Rollaeden zu ]=set TYPE=ROLLADEN pos 100;[Rollaeden auf]=set TYPE=ROLLADEN pos 0</code>

Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:

<pre>
Favorites

/short1 = Rollaeden zu

/short2 = Rollaeden auf

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2016-04-26T15:37:53Z

Muschelpuster: Favoritenbeschreibung auf den aktuellen Funktionsumfang angepasst

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das perl JSON modul installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

Der Versand ist nicht direkt über das Device möglich, jedoch über den Perl-Befehl 'TelegramBot_ExecuteCommand':

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

Hierbei ist die Ziel-ID ohne das @-Zeichen, Anführungszeichen o.ä. anzugeben. Das Ziel kann auch eine Gruppen-ID (beginnend mit dem Minus-Zeichen) sein. Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message \@meine_ZielID Mein Text" ;; TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

/short1 = set TYPE=ROLLADEN pos 100

/short2 = set TYPE=ROLLADEN pos 0

</pre>

Die Antworten werden als Schaltflächen dargestellt (Telegram inline Keyboard) und können am Mobile-Client direkt angeklickt werden um sie auszuführen.
Um die Beschriftung der Schaltflächen zu optimieren, können die Befehle im Attribut favorites mit Beschreibungen versehen werden:

<code>[Rollaeden zu ]=set TYPE=ROLLADEN pos 100;[Rollaeden auf]=set TYPE=ROLLADEN pos 0</code>

Nun antwortet der Bot auf das Schlüsselwort für die Favoriten mit:

<pre>
Favorites

/short1 = Rollaeden zu

/short2 = Rollaeden auf

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2016-04-21T08:29:04Z

Muschelpuster: /* Versand von SVG-Plots */

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das perl JSON modul installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

Der Versand ist nicht direkt über das Device möglich, jedoch über den Perl-Befehl 'TelegramBot_ExecuteCommand':

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

Hierbei ist die Ziel-ID ohne das @-Zeichen, Anführungszeichen o.ä. anzugeben. Das Ziel kann auch eine Gruppen-ID (beginnend mit dem Minus-Zeichen) sein. Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message \@meine_ZielID Mein Text" ;; TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2016-04-21T08:17:26Z

Muschelpuster: Ergänzung um SVG-Versand basierend auf Diskussion dazu: https://forum.fhem.de/index.php/topic,38328.msg441787.html#msg441787

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das perl JSON modul installiert sein.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Versand von SVG-Plots ===

Der Versand ist nicht direkt über das Device möglich, jedoch über den Perl-Befehl 'TelegramBot_ExecuteCommand':

<code>{TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

Hierbei ist die Ziel-ID ohne das @-Zeichen, Anführungszeichen o.ä. anzugeben. Das Ziel kann jedoch auch eine Gruppen-ID (beginnend mit dem Minus-Zeichen) sein. Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am Einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message \@meine_ZielID Mein Text" ;; TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, '{plotAsPng("mein_SVG")}');; return;;}</code>

==== Voraussetzungen für den Versand von SVG-Plots ====
Es muss das Modul libimage-librsvg-perl installiert sein:

<code>sudo apt-get install libimage-librsvg-perl</code>

Evtl. sind weitere Module erforderlich:

<code>sudo apt-get install libgd-graph-perl

sudo apt-get install libgd-text-perl</code>

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2016-04-06T20:24:00Z

Muschelpuster: /* Supergroups / Supergruppen */ - Ergänzung um allgemeines Gruppen-Handling

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Gruppen ===

Um eine Nachricht von FHEM an eine Gruppe zu senden, muss der BOT in die Gruppe aufgenommen werden. Nach dem Senden einer Nachricht an die Gruppe kann im Modul die Gruppen-ID ermittelt werden und zum Senden von Nachrichten verwendet werden. Wenn die Privacy-Einstellungen nicht auf 'Disabled' gesetzt wurden, muss die Nachricht mit einem Slash (/) beginnen.

==== Supergroups / Supergruppen ====

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2016-04-06T18:40:43Z

Muschelpuster: /* Privacyeinstellungen */ Ergänzung Beispielchat

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden. Beispielchat:<pre>Client:
/setprivacy
----------------
BotFather:
Choose a bot to change group messages settings.
----------------
Client:
@fhem1234_bot
----------------
BotFather:
'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
'Disable' - your bot will receive all messages that people send to groups.
Current status is: ENABLED
----------------
Client:
Disable
----------------
BotFather:
Success! The new status is: DISABLED. /help</pre>

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Supergroups / Supergruppen ===

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2016-04-06T17:26:09Z

Muschelpuster: neuer Abschnitt Registrierung

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Registrierung eines neuen Bot ==
Zur Registrierung wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm)benötigt. Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.
Hier ein Beispiel, wie so ein Chat aussehen könnte:
<pre>Client:
/newbot
----------------
BotFather:
Alright, a new bot. How are we going to call it? Please choose a name for your bot.
----------------
Client:
Mein Name
----------------
BotFather:
Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot.
----------------
Client:
fhem_bot
----------------
BotFather:
Sorry, this username is already taken. Think of something different.
----------------
Client:
fhem1234_bot
----------------
BotFather:
Done! Congratulations on your new bot.
You will find it at telegram.me/fhem1234_bot.
You can now add a description, about section and profile picture for your bot, see /help for a list of commands.
----------------
Use this token to access the HTTP API:
1234567890:AbCdefgHIJklmnOPQRst-uvwxyz

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden.

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Supergroups / Supergruppen ===

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2016-04-06T17:10:59Z

Muschelpuster: /* Hinweise zum Betrieb mit Fhem */

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden. 
Dazu wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm). Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden.

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Supergroups / Supergruppen ===

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

TelegramBot

2016-04-06T17:10:16Z

Muschelpuster: Ergänzung der Registrierung eines neuen Bot

{{Infobox Modul
|ModPurpose=Senden und Empfangen von Nachrichten (Text und Fotos) mit dem freien Messagingdienst Telegram
|ModType=d
|ModForumArea=Unterstützende Dienste
|ModFTopic=38328
|ModTechName=[https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm]
|ModOwner=[[Benutzer:Viegener|Viegener]] ({{Link2FU|12772|Forum}} / [[Benutzer Diskussion:Viegener|Wiki]])}}

Das [[TelegramBot]]-Modul ermöglicht das Senden und Empfangen von Nachrichten über den Telegram-instant messaging Dienst (https://telegram.org/).
Es entsteht eine Möglichkeit Benachrichtungen aus Fhem zu versenden, zum Beispiel Alarmmeldungen.
Ausserdem können auch Kommandos über Telegram an Fhem gesendet werden um Steuerungsbefehle in Fhem auszulösen.

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem Fhem-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe.

== Über Telegram Instant Messaging ==
Telegram-IDs und Versand/Empfang von Nachrichten sind kostenfrei.
Clients sind für gängige Smartphonesysteme erhältlich (iOS iPhone und Tablet, Android, Windows Phone) und
können auch aus dem WebBrowser verwendet werden.
Es gibt auch einen Kommandozeilen-Client für Linux, der die Grundlage dieses Moduls darstellt.
Mehrfachanmeldungen, auch parallel mit verschiedenen Geräten (z.B. Tablet und Smartphone), sind möglich.
Gruppenchats und Chats mit End-2-End-Verschlüsselung werden ebenfalls unterstützt.

Für die Unterstützung von ''WhatsApp'' siehe Modul [[yowsup]].

== Features ==
Unterstützt werden:

* Versand von Textnachrichten
* Versand und Empfang von Bildern/Audio/etc
* Empfang von Textnachrichten von beliebigen Kontakten
* Kommandos in Fhem über Telegram-Nachrichten von aussen auslösen
* Ergebnisse der Kommandos zusenden lassen

Eine detaillierte Beschreibung des Moduls ist im Fhem Forum und in der (englischen) Dokumentation zum Modul in der Commandref diesem {{Link2Forum|Topic=38328|LinkText=Diskussionsthread}} zu finden. Seit Oktober 2015 wird das Modul offiziell über Fhem-Update verteilt.

Die jeweils aktuellste Entwicklungs-Version des Moduls ist in Github [https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm 50_TelegramBot.pm] verfügbar.

== Hinweise zum Betrieb mit Fhem ==
{{Randnotiz|RNTyp=Warn|RNText=Achtung: Dieses Authtoken ist die einzige Authentifizierung für den Bot und sollte deshalb nicht aus der Hand gegeben werden. Die verwendeten Urls sind deshalb auch in den Log-Files nicht enthalten, da diese das Authtoken in Klartext enthalten. Auch im Forum sollte dieses Token nicht aufgenommen werden.
}}

Für die Anlage eines TelegramBot Devices in Fhem ist ein Authtoken erforderlich. Dieses Token wird über Anlegen eines neuen Bots im [https://core.telegram.org/bots#botfather BotFather] erzeugt. Dort mit dem Telegram-Befehl <code>/newbot</code> einen neuen Bot anlegen und mit einem Namen versehen. Hinweis: Die Namen für Bots müssen auf "Bot" enden.
Dazu wird ein funktionierender Telegram-Client (egal ob Web, App oder Programm). Hier wird ein Chat zum BotFather gestartet und der Befehl /newbot gesendet. Nun fragt der BotFather die benötigten Angaben ab und liefert am Ende des Dialogs die Informationen für den neuen Bot.

Das Anlegen eines TelegramBot devices erfolgt durch die Angabe dieses Tokens:

<code>define <name> TelegramBot <token> </code>

Beispiel: <code>define teleBot TelegramBot 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw</code>

'''Das Empfangen von Nachrichten (polling) erfordert die Einstellung des Attributes'''
<code>pollingTimeout</code> '''auf einen Wert der grösser als Null ist. Beim Wert 0 oder ohne Setzen des Attributes findet kein Polling und damit auch kein Empfang statt.'''

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''

{{Randnotiz|RNTyp=Warn|RNText=TelegramBot setzt eine aktuelle Version von FHEM voraus, insbesondere Versionen weit vor der Umstellung auf 5.7 (also vor Herbst 2015) können mit einem TelegramBot-Modul nicht funktionieren, da insbesondere das HTTPSRV-Modul dann veraltet ist. Am besten auch den TelegramBot über den offiziellen Update mit dem Rest von FHEM installieren/aktualisieren.
}}

== Tipps ==

=== Privacyeinstellungen ===

Damit der TelegramBot auch Meldungen in Gruppen sieht, müssen über den BotFather die Privacy-Einstellungen geändert werden.

=== Kontakte ===

Der Bot merkt sich die bereits bekannten Kontakte im Reading <code>Contacts</code>. Dabei werden die einzelnen Kontakte jeweils als 3-teilige Einträge bestehend aus UserID, Vor- und Nachname des Benutzers (mit _ verbunden) und dem Username (mit vorangestelltem @).

Beispiel: <code>123456:Ralf_Mustermann:@ralf</code>

Verschiedene Einträge werden durch Leerzeichen getrennt.

Man kann die Kontakte auch manuell überschreiben (z.B. wenn das Reading fehlerhaft oder verloren sein sollte). Dazu gibt es den Set-Befehl <code>replaceContacts</code>. Dieser nimmt die Kontakte ebenfalls in der gleichen Form wie oben beschrieben entgegen.

Die Kontaktliste wird ansonsten nur durch den Empfang von Nachrichten erweitert, da es im TelegramBot-API keine Möglichkeit gibt Kontaktdaten von Telegram abzufragen (siehe auch pollingTimeout)

=== Reset ===

Es ist möglich den Bot im laufenden Betrieb zurückzusetzen (Set-Befehl <code>reset</code>). Dabei werden noch nicht abgeschlossene Übetragungen entfernt und die internen Zustände des Devices zurückgesetzt.

=== Supergroups / Supergruppen ===

Auch die neuen Supergruppen werden mit dem Bot unterstützt, es ist allerdings zu beachten, dass bei der Umwandlung einer Gruppe in eine Supergruppe eine neue ID in den Kontakten von Telegram vergeben wird. Wenn man also wie empfohlen IDs zur Identifikation von Benutzern einsetzt, muss entsprechend angepasst werden.

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

Das einfachste Szenario für die Integration von Messaging-Diensten mit Fhem ist zur Benachrichtigung über Ereignisse. Diese Funktion kann zum Beispiel verwendet werden, um über einen erfolgten Neustart von Fhem zu informieren:

<code>define notify_fhem_reload notify global:INITIALIZED set telebotdevice message fhem newly started - just now !</code>

In diesem Beispiel wird der Nachrichtentext "fhem newly started - just now !" an den als default eingestellten Kontakt (Attribut: defaultPeer) gesendet, sobald Fhem neu gestartet wurde. Natürlich kann man auch beliebige andere Benachrichtigungen einführen.

=== Versand von Bildern ===

Es ist auch möglich Bilder auf dem Fhem-Server, die zum Beispiel von einer Kamera oder einem Wettermodul stammen über Telegram zu versenden. So wäre es z.B. möglich jeweils morgens die aktuelle Wetterkarte zu erhalten.

ACHTUNG: TelegramBot verwendet das HTTPUtils-Modul zur Kommunikation mit dem TelegramBot-API. Erst mit der Version, die seit 22.10.2015
([r9576] HttpUtils.pm: Async write for POST Requests {{Link2Forum|Topic=41583|LinkText=Fhem-Forum}}) verteilt wird, erlaubt auch den Transfer grösserer Bilder. Die Grenze liegt ansonsten bei ca. 14kb auf Raspberries (Plattformspezifische Grenze).

<code>define notify_fhem_reload notify wetter:report set telebotdevice sendPhoto /opt/fhem/wetter.jpg</code>

Bei Erreichen des entsprechenden Status am Wetter-Modul wird ein Image über Telegram versendet. Hier sind lokale Pfade (relativ zu fhem) oder absolute Pfade wie oben möglich.

=== Empfang von Bildern oder ähnlichem ===

Beim Empfang von Bildern wird zuerst nur eine ID vom Telegram-Server empfangen, diese befindet sich im Reading <code>msgFileId</code> angelegt (<code>123456:xxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx</code>) und im Reading <code>msgText</code> steht dann so etwas wie
<code>received photo # Size: 107701</code>

Über das Get-Kommando <code>urlForFile</code> mit der ID aus dem msgFileId Reading lässt sich dann daraus ein URL ableiten, der dann zur eigentlichen Datei führt:

<code>https://api.telegram.org/file/bot123456:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/photo/file_25.jpg</code>

=== Versand von Emojis (Smileys) ===

Es ist auch möglich Emojis mit den (Text-)Nachrichten zu versenden. Die entsprechenden (Unicode-)Zeichen werden einfach direkt mit in den Text der Nachricht aufgenommen. Um das zu vereinfachen kann man das einfach per Copy und Paste von dieser Seite

http://apps.timwhitlock.info/emoji/tables/unicode (Spalte "Native")

übernehmen und mit der Nachricht verschicken.

Die Emojis können auch empfangen werden und werden so auch in FHEM / FHEMWeb angezeigt. Plattformspezifische (z.B. von iOS oder Android) Emojis werden dabei nicht unterstützt (gerade mit iOS sind viele neue farbige Emojis hinzugekommen, die wohl leider nur auf Apple-devices funktionieren).

=== Kommandos auslösen ===

Ein wichtiges Szenario ist die Möglichkeit Kommandos in Fhem ausführen zu können, ohne einen Zugang durch die Firewall einrichten zu müssen. Dazu ist die Definition eines Schlüsselwortes (Attribut: "cmdKeyword")erforderlich, mit dem man die Nachrichten beginnen muss, damit der TelegramBot die Kommandos erkennt.

<code>attr telebotdevice cmdKeyword doit</code>

Somit kann man dann durch Nachrichten die mit "doit" beginnen Kommandos an Fhem senden, die ähnlich wie im Kommandoeingabefeld von Fhemweb dann von Fhem ausgeführt werden. Das Ergebnis der Ausführung wird zurück an den Sender (und an den definierten defaultPeer) geschickt.

Somit können nicht nur Aktionen angestossen werden, sondern auch Infos abgefragt werden.

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

{{Randnotiz|RNTyp=Warn|RNText=Achtung: Bei den Kommandos sollten man unbedingt das Attribut "cmdRestrictedPeer" setzen, damit nicht jeder Kommandos auf dem Fhem-Server ausführen kann. Dazu sollten die BenutzerIDs der erlaubten Benutzer (durch Leerzeichen getrennt angeben). Da Benutzernamen selber vergeben werden und nicht unbedingt eindeutig sind, sollten hier auch NUR BenutzerIDs verwendet werden.
}}

=== Favoriten für Kommandos anlegen ===

Grundidee bei den Favoriten ist, dass man lange Befehle, die man häufig braucht auf "Kurzwahl" legt.

Beispiel-Kommandos wie z.B. <code>set TYPE=ROLLADEN pos 100</code> und <code>set TYPE=ROLLADEN pos 0</code>, die man immer wieder braucht. Um nicht jedes mal dieses Kommando eintippen zu müssen auf dem Smartphone, kann man auch dafür Favoriten anlegen.

Dazu gibt man erst mal die beiden Kommandos getrennt durch Semikolon im Attribut favorites an:

<code>attr telegrambotdevice favorites set TYPE=ROLLADEN pos 100;set TYPE=ROLLADEN pos 0</code>

Um die Favorites jetzt ausführen zu können braucht man noch ein Schlüsselwort dafür.
Nehmen wir mal an man möchte die Favoriten mit <code>/short</code> ausführen können. Dazu muss dann das Attribut "cmdFavorites" setzen

<code>attr telegrambotdevice cmdFavorites /short</code>

Wenn man nun im Telegram Client
<code>/short 1</code> an den Bot schickt führt der Bot den ersten Favoriten aus und das Ergebnis der Ausführung wird zurückgeschickt.

Ausserdem kann man im Telegram Client
<code>/short</code> an den Bot schicken, dann antwortet der Bot mit

<pre>
Favorites

1
set TYPE=ROLLADEN pos 100
2
set TYPE=ROLLADEN pos 0

</pre>

== Links ==
* Github Repository für die Telegram-Fhem Entwicklung: https://github.com/viegener/Telegram-fhem
* Infos zum Telegram BotFather: https://core.telegram.org/bots#botfather

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm
* Source code für das modifizierte HTTPUtils-Modul zur Übertragung grosser Bilder: https://github.com/viegener/Telegram-fhem/blob/master/HttpUtils.pm

* Forum-Thread in dem das Modul vorgestellt wurde {{Link2Forum|Topic=38328|LinkText=Fhem-Forum}}
* Telegram messaging system https://telegram.org/
* TelegramBot API https://core.telegram.org/bots/api

--[[Benutzer:Viegener|Viegener]] ([[Benutzer Diskussion:Viegener|Diskussion]]) 22:49, 11. Okt. 2015 (CEST)

Yowsup

2016-04-06T15:32:08Z

Muschelpuster: Update eingefügt

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden. Nachrichten können sein:
* '''Text''': senden und empfangen, z.b.: Infonachrichten senden, FHEM-Kommandos empfangen
* '''Bilder''': senden und emfangen, z.b.: Webcambilder nach Bewegungserkennung versenden
* '''Audio''': empfangen, z.b.: Sprachdurchsagen empfangen und über SONOS abspielen

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen.

=== Yowsup Installation ===
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist:
<code>sudo apt-get update</code>
<code>sudo apt-get upgrade</code>
<code>sudo apt-get dist-upgrade</code>

Los gehts mit den Paketen:
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential</code>

Nun erstmal pip updaten:
<code>sudo pip install --upgrade pip</code>

Und dann axolotl installieren (das dauert ne Weile):
<code>sudo pip install python-axolotl</code>
 
Zudem wird neben den Python Modulen noch eine Lib von tgalal benötigt:<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/python-axolotl/archive/master.zip
sudo unzip master.zip
cd python-axolotl-master
sudo python setup.py install</pre>

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
* PIP:<code>sudo pip install pillow</code>

Vor den weiteren Schritten sollte geprüft werden, ob dem User fhem eine Loginshell zugewiesen ist:
:<code>getent passwd fhem</code>
Wird hier am Ende /bin/false ausgegeben, so muss dies angepasst werden:
:<code>sudo chsh -s /bin/bash fhem</code>

Mittels ''getent passwd fhem'' kann auch bereits das Home-Verzeichnis ausgelesen werden, dies steht in der ausgegebenen Doppelpunkt-separierten Liste an vorletzter Stelle.

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen werden die vom fhem-Setup-Script generierten Defaults verwendet: User=fhem , home=/opt/fhem Gruppe=dialout) und liest dort die $HOME-Variable aus und prüft das Home-Verzeichnis:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Desweiteren muss man nun yowsup installieren. Hierfür stehen zwei Möglichkeiten zur Verfügung:

Erstens:
<pre>
cd /opt
sudo mkdir yowsup-config
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
#alternativ sudo wget https://github.com/jlguardi/yowsup/archive/master.zip (Stand März 2016 aktueller)
sudo unzip -o master.zip
rm master.zip
cd yowsup-config
sudo nano yowsup.config
</pre>

Wie bemerkt, ist man nun im Editor für die yowsup.config gelandet. Diese wird nun wie folgt gefüllt:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=</pre>
Ersetze die Nummer 498912345678 gegen eine Festnetz oder Handynummer welche derzeit nicht mit WhatsApp verwendet wird. Mittels STRG+o wird die Datei nun gespeichert und mittels STRG+x verlässt man den Editor.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die Anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, bei Festnetzanschlüssen sollte voice gewählt werden, wenn man sich nicht sicher ist, dass der Anschluss die Funktion 'SMS im Festnetz' unterstützt. Dann wird der Bestätigungscode zwar auf Englisch vorgelesen, dafür ist die Zuverlässigkeit des Registrierungsvorganges zuverlässiger. Bei Festnetznummern sollte man unbedingt etwas zum schreiben bereit halten!
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -r sms</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>Detected cc: 49
status: sent
retry_after: 1805
length: 6
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein:
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>status: ok
kind: free
pw: bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx
price: 0,89 €
price_expiration: 1432127524
currency: EUR
cost: 0.89
login: 498912345678
type: existing
expiration: 1460832553</pre>
Den Text hinter dem Zeilenanfang <code>pw: </code> benötigt man nun für die Konfigurationsdatei, wo dieser eingefügt werden muss:
<pre>nano /opt/yowsup-config/yowsup.config</pre>
Sodass die Datei beispielhaft dann so aussieht:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx</pre>

Wie man schon gesehen hat, ist der Account nur begrenzt gültig - die Gültigkeit kann man anhand der als <code>expiration: </code> bezeichneten Zeile ablesen, welche einen Unix-Timestamp beinhaltet. Diese kann man [http://elmar-eigner.de/tstamps.html?zeichen=1444570276&timeformat=2 HIER] umrechnen lassen.

Nun mal ein schneller test an die eigene Nummer (im Beispiel 491751234567):
<pre>python yowsup-cli demos -c /opt/yowsup-config/yowsup.config -s 491751234567 "Das ist ein Test"</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* Fhem Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home PWD</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass Fhem online ist
* Zum Senden aus Fhem kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

== Attribute ==
Bitte sehe immer in der [[http://fhem.de/commandref.html#yowsup Commandref]] nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>. Wenn die ab yowsup-Version 2.4 standartmässig aktivierte Verschlüsselung abgeschaltet werden muss weil die entsprechenden Libs nicht installiert sind: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/yowsup-config --yowsup -M</code>.
* <code>accept_from</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als Fhem-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

== Befehle ==
* image -> Über diesen Befehl können Bilder gesendet werden.

* raw -> Status ändern :
<code>set WhatsApp raw /profile setStatus 'mein Status' <--- die ' ' müssen bleiben</code>

Name der angezeigt werden soll, wenn eine Nachricht z.B. ans iPhone geschickt wird:

<code>set WhatsApp raw /presence name <DeinNick></code>

Anzeige online :

<code>set WhatsApp raw /presence available</code>

Profilbild ändern :

<code>set WhatsApp raw /profile setPicture '/opt/fhem/fhem_logo.png'</code>
<--- der gesamte Pfad zum Bild muss angegeben werden und Rechte müssen ggfs. bei fhem liegen

Falls es nicht funktioniert disconnect/connect probieren.

== Update ==
Da am WhatsApp ständig geschraubt wird, bedarf es eines Updates des Yowsup, wenn keine Funktion mehr gegeben ist:
<pre>cd /opt
sudo rm master.zip
sudo mv yowsup-master yowsup-master-alt
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
#alternativ sudo wget https://github.com/jlguardi/yowsup/archive/master.zip (Stand März 2016 aktueller)
sudo unzip master.zip
sudo chown fhem yowsup-master -R
sudo chgrp dialout yowsup-master -R</pre>Danach muss FHEM mittels 'shutdown restart' neu gestartet werden.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein Fhem Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppen müssen über die App (Smartphone / Tablet) angelegt werden. Nach dem Empfang einer entsprechenden Nachricht werden Gruppen genauso behandelt, wie einfache Teilnehmer.

=== Broadcast ===
Beim Senden über das Masterdevice lassen sich mehrere Empfänger mit Komma (und ohne Leerzeichen) getrennt angeben. Die entsprechenden Nachrichten werden dann per Broadcast an alle Teilnehmer gesendet. Die Broadcastempfänger müssen zuvor mindestens eine normale Nachricht erhalten haben.

=== Komponenten steuern ===
Um ein [[notify]] anlegen zu können, müssen wir zuerst eine Nachricht vom Handy an FHEM senden. Dadurch wird ein Device mit der Nummer als Namen angelegt. Danach sollte das Device umbenannt werden, da einige Befehle einen Namen ausschließlich aus Ziffern nicht akzeptieren. Dies geschieht wie folgt:

:<code>rename 49123456789 HandySeppel</code>

Danach kann ein ''notify'' angelegt werden:

<source lang="perl">
define notifySeppelLicht notify HandySeppel:message.* {
if( $EVENT eq 'message: Licht an' ) {
fhem "set HandySeppel send Licht ist nun an...";
fhem "set FS20_a5d800 dim100%";

} elsif( $EVENT eq 'message: Licht aus' ) {
fhem "set HandySeppel send Licht ist nun aus...";
fhem "set FS20_a5d800 dim0%";

} else {
fhem "set HandySeppel send Wie bitte?"

}
}</source>

Natürlich ist dieses ''notify'' noch auf die eigenen Wünsche anzupassen.

=== Autoresponder ===
Nachdem man nun seine Festnetznummer bei WhatsApp registriert hat, wird auch diese natürlich als erreichbares Ziel auf jedem Gerät angezeigt, auf dem sie gespeichert ist. So kann es passieren, dass WhatsApp nicht gelesen werden. Hier schafft ein Autoresponder Abhilfe:
:<code>define not_WhatsApp_Autoresponder notify 491.*:message.* set $NAME send Hallo, Du hast eine Nachricht an unsere Festnetznummer geschickt. Da ist aber nur ein kleiner Computer auf Empfang, der Dir nur diese Antwort schicken kann. Bitte benutze unsere Mobilnummern, wenn Du willst, dass Deine Nachricht auch gelesen wird!</code>
Das Problem hierbei ist, dass noch nicht bekannt ist, wer etwas sendet und so der Kontakt u.U. noch nicht angelegt ist. Daher wird im obigen Beispiel auf 491*:message.* reagiert. So bekommen nur deutsche Mobilrufnummern die Antwort. Um das noch globaler zu fassen, könnte z.B. auf \d*.*:message.* reagiert werden, was aber voraussetzt, dass keine weiteren Modulnamen (die das Reading message haben) mit einer Ziffer beginnen.
Alle Kontakte, welche nicht den Autoresponder erhalten sollen, müssen wie oben beschrieben entspr. umbenannt werden:
:<code>rename 49123456789 HandySeppel</code>

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]
* Imagehandling Bugfix [https://github.com/tgalal/yowsup/issues/901 github]

Yowsup

2016-04-06T15:25:10Z

Muschelpuster: /* Yowsup Installation */ Hinweis auf yowsup-Version von jlguardi entspr. https://forum.fhem.de/index.php/topic,27543.msg429821.html#msg429821

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden. Nachrichten können sein:
* '''Text''': senden und empfangen, z.b.: Infonachrichten senden, FHEM-Kommandos empfangen
* '''Bilder''': senden und emfangen, z.b.: Webcambilder nach Bewegungserkennung versenden
* '''Audio''': empfangen, z.b.: Sprachdurchsagen empfangen und über SONOS abspielen

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen.

=== Yowsup Installation ===
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist:
<code>sudo apt-get update</code>
<code>sudo apt-get upgrade</code>
<code>sudo apt-get dist-upgrade</code>

Los gehts mit den Paketen:
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential</code>

Nun erstmal pip updaten:
<code>sudo pip install --upgrade pip</code>

Und dann axolotl installieren (das dauert ne Weile):
<code>sudo pip install python-axolotl</code>
 
Zudem wird neben den Python Modulen noch eine Lib von tgalal benötigt:<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/python-axolotl/archive/master.zip
sudo unzip master.zip
cd python-axolotl-master
sudo python setup.py install</pre>

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
* PIP:<code>sudo pip install pillow</code>

Vor den weiteren Schritten sollte geprüft werden, ob dem User fhem eine Loginshell zugewiesen ist:
:<code>getent passwd fhem</code>
Wird hier am Ende /bin/false ausgegeben, so muss dies angepasst werden:
:<code>sudo chsh -s /bin/bash fhem</code>

Mittels ''getent passwd fhem'' kann auch bereits das Home-Verzeichnis ausgelesen werden, dies steht in der ausgegebenen Doppelpunkt-separierten Liste an vorletzter Stelle.

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen werden die vom fhem-Setup-Script generierten Defaults verwendet: User=fhem , home=/opt/fhem Gruppe=dialout) und liest dort die $HOME-Variable aus und prüft das Home-Verzeichnis:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Desweiteren muss man nun yowsup installieren. Hierfür stehen zwei Möglichkeiten zur Verfügung:

Erstens:
<pre>
cd /opt
sudo mkdir yowsup-config
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
#alternativ sudo wget https://github.com/jlguardi/yowsup/archive/master.zip (Stand März 2016 aktueller)
sudo unzip -o master.zip
rm master.zip
cd yowsup-config
sudo nano yowsup.config
</pre>

Wie bemerkt, ist man nun im Editor für die yowsup.config gelandet. Diese wird nun wie folgt gefüllt:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=</pre>
Ersetze die Nummer 498912345678 gegen eine Festnetz oder Handynummer welche derzeit nicht mit WhatsApp verwendet wird. Mittels STRG+o wird die Datei nun gespeichert und mittels STRG+x verlässt man den Editor.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die Anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, bei Festnetzanschlüssen sollte voice gewählt werden, wenn man sich nicht sicher ist, dass der Anschluss die Funktion 'SMS im Festnetz' unterstützt. Dann wird der Bestätigungscode zwar auf Englisch vorgelesen, dafür ist die Zuverlässigkeit des Registrierungsvorganges zuverlässiger. Bei Festnetznummern sollte man unbedingt etwas zum schreiben bereit halten!
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -r sms</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>Detected cc: 49
status: sent
retry_after: 1805
length: 6
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein:
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>status: ok
kind: free
pw: bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx
price: 0,89 €
price_expiration: 1432127524
currency: EUR
cost: 0.89
login: 498912345678
type: existing
expiration: 1460832553</pre>
Den Text hinter dem Zeilenanfang <code>pw: </code> benötigt man nun für die Konfigurationsdatei, wo dieser eingefügt werden muss:
<pre>nano /opt/yowsup-config/yowsup.config</pre>
Sodass die Datei beispielhaft dann so aussieht:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx</pre>

Wie man schon gesehen hat, ist der Account nur begrenzt gültig - die Gültigkeit kann man anhand der als <code>expiration: </code> bezeichneten Zeile ablesen, welche einen Unix-Timestamp beinhaltet. Diese kann man [http://elmar-eigner.de/tstamps.html?zeichen=1444570276&timeformat=2 HIER] umrechnen lassen.

Nun mal ein schneller test an die eigene Nummer (im Beispiel 491751234567):
<pre>python yowsup-cli demos -c /opt/yowsup-config/yowsup.config -s 491751234567 "Das ist ein Test"</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* Fhem Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home PWD</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass Fhem online ist
* Zum Senden aus Fhem kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

== Attribute ==
Bitte sehe immer in der [[http://fhem.de/commandref.html#yowsup Commandref]] nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>. Wenn die ab yowsup-Version 2.4 standartmässig aktivierte Verschlüsselung abgeschaltet werden muss weil die entsprechenden Libs nicht installiert sind: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/yowsup-config --yowsup -M</code>.
* <code>accept_from</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als Fhem-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

== Befehle ==
* image -> Über diesen Befehl können Bilder gesendet werden.

* raw -> Status ändern :
<code>set WhatsApp raw /profile setStatus 'mein Status' <--- die ' ' müssen bleiben</code>

Name der angezeigt werden soll, wenn eine Nachricht z.B. ans iPhone geschickt wird:

<code>set WhatsApp raw /presence name <DeinNick></code>

Anzeige online :

<code>set WhatsApp raw /presence available</code>

Profilbild ändern :

<code>set WhatsApp raw /profile setPicture '/opt/fhem/fhem_logo.png'</code>
<--- der gesamte Pfad zum Bild muss angegeben werden und Rechte müssen ggfs. bei fhem liegen

Falls es nicht funktioniert disconnect/connect probieren.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein Fhem Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppen müssen über die App (Smartphone / Tablet) angelegt werden. Nach dem Empfang einer entsprechenden Nachricht werden Gruppen genauso behandelt, wie einfache Teilnehmer.

=== Broadcast ===
Beim Senden über das Masterdevice lassen sich mehrere Empfänger mit Komma (und ohne Leerzeichen) getrennt angeben. Die entsprechenden Nachrichten werden dann per Broadcast an alle Teilnehmer gesendet. Die Broadcastempfänger müssen zuvor mindestens eine normale Nachricht erhalten haben.

=== Komponenten steuern ===
Um ein [[notify]] anlegen zu können, müssen wir zuerst eine Nachricht vom Handy an FHEM senden. Dadurch wird ein Device mit der Nummer als Namen angelegt. Danach sollte das Device umbenannt werden, da einige Befehle einen Namen ausschließlich aus Ziffern nicht akzeptieren. Dies geschieht wie folgt:

:<code>rename 49123456789 HandySeppel</code>

Danach kann ein ''notify'' angelegt werden:

<source lang="perl">
define notifySeppelLicht notify HandySeppel:message.* {
if( $EVENT eq 'message: Licht an' ) {
fhem "set HandySeppel send Licht ist nun an...";
fhem "set FS20_a5d800 dim100%";

} elsif( $EVENT eq 'message: Licht aus' ) {
fhem "set HandySeppel send Licht ist nun aus...";
fhem "set FS20_a5d800 dim0%";

} else {
fhem "set HandySeppel send Wie bitte?"

}
}</source>

Natürlich ist dieses ''notify'' noch auf die eigenen Wünsche anzupassen.

=== Autoresponder ===
Nachdem man nun seine Festnetznummer bei WhatsApp registriert hat, wird auch diese natürlich als erreichbares Ziel auf jedem Gerät angezeigt, auf dem sie gespeichert ist. So kann es passieren, dass WhatsApp nicht gelesen werden. Hier schafft ein Autoresponder Abhilfe:
:<code>define not_WhatsApp_Autoresponder notify 491.*:message.* set $NAME send Hallo, Du hast eine Nachricht an unsere Festnetznummer geschickt. Da ist aber nur ein kleiner Computer auf Empfang, der Dir nur diese Antwort schicken kann. Bitte benutze unsere Mobilnummern, wenn Du willst, dass Deine Nachricht auch gelesen wird!</code>
Das Problem hierbei ist, dass noch nicht bekannt ist, wer etwas sendet und so der Kontakt u.U. noch nicht angelegt ist. Daher wird im obigen Beispiel auf 491*:message.* reagiert. So bekommen nur deutsche Mobilrufnummern die Antwort. Um das noch globaler zu fassen, könnte z.B. auf \d*.*:message.* reagiert werden, was aber voraussetzt, dass keine weiteren Modulnamen (die das Reading message haben) mit einer Ziffer beginnen.
Alle Kontakte, welche nicht den Autoresponder erhalten sollen, müssen wie oben beschrieben entspr. umbenannt werden:
:<code>rename 49123456789 HandySeppel</code>

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]
* Imagehandling Bugfix [https://github.com/tgalal/yowsup/issues/901 github]

Yowsup

2016-04-06T15:22:00Z

Muschelpuster: /* Yowsup Installation */

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden. Nachrichten können sein:
* '''Text''': senden und empfangen, z.b.: Infonachrichten senden, FHEM-Kommandos empfangen
* '''Bilder''': senden und emfangen, z.b.: Webcambilder nach Bewegungserkennung versenden
* '''Audio''': empfangen, z.b.: Sprachdurchsagen empfangen und über SONOS abspielen

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen.

=== Yowsup Installation ===
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist:
<code>sudo apt-get update</code>
<code>sudo apt-get upgrade</code>
<code>sudo apt-get dist-upgrade</code>

Los gehts mit den Paketen:
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential</code>

Nun erstmal pip updaten:
<code>sudo pip install --upgrade pip</code>

Und dann axolotl installieren (das dauert ne Weile):
<code>sudo pip install python-axolotl</code>
 
Zudem wird neben den Python Modulen noch eine Lib von tgalal benötigt:<pre>cd /opt/fhem/yowsup
sudo wget https://github.com/tgalal/python-axolotl/archive/master.zip
sudo unzip master.zip
cd python-axolotl-master
sudo python setup.py install</pre>

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
* PIP:<code>sudo pip install pillow</code>

Vor den weiteren Schritten sollte geprüft werden, ob dem User fhem eine Loginshell zugewiesen ist:
:<code>getent passwd fhem</code>
Wird hier am Ende /bin/false ausgegeben, so muss dies angepasst werden:
:<code>sudo chsh -s /bin/bash fhem</code>

Mittels ''getent passwd fhem'' kann auch bereits das Home-Verzeichnis ausgelesen werden, dies steht in der ausgegebenen Doppelpunkt-separierten Liste an vorletzter Stelle.

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen werden die vom fhem-Setup-Script generierten Defaults verwendet: User=fhem , home=/opt/fhem Gruppe=dialout) und liest dort die $HOME-Variable aus und prüft das Home-Verzeichnis:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Desweiteren muss man nun yowsup installieren. Hierfür stehen zwei Möglichkeiten zur Verfügung:

Erstens:
<pre>
cd /opt
sudo mkdir yowsup-config
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip -o master.zip
rm master.zip
cd yowsup-config
sudo nano yowsup.config
</pre>

Wie bemerkt, ist man nun im Editor für die yowsup.config gelandet. Diese wird nun wie folgt gefüllt:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=</pre>
Ersetze die Nummer 498912345678 gegen eine Festnetz oder Handynummer welche derzeit nicht mit WhatsApp verwendet wird. Mittels STRG+o wird die Datei nun gespeichert und mittels STRG+x verlässt man den Editor.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die Anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, bei Festnetzanschlüssen sollte voice gewählt werden, wenn man sich nicht sicher ist, dass der Anschluss die Funktion 'SMS im Festnetz' unterstützt. Dann wird der Bestätigungscode zwar auf Englisch vorgelesen, dafür ist die Zuverlässigkeit des Registrierungsvorganges zuverlässiger. Bei Festnetznummern sollte man unbedingt etwas zum schreiben bereit halten!
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -r sms</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>Detected cc: 49
status: sent
retry_after: 1805
length: 6
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein:
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>status: ok
kind: free
pw: bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx
price: 0,89 €
price_expiration: 1432127524
currency: EUR
cost: 0.89
login: 498912345678
type: existing
expiration: 1460832553</pre>
Den Text hinter dem Zeilenanfang <code>pw: </code> benötigt man nun für die Konfigurationsdatei, wo dieser eingefügt werden muss:
<pre>nano /opt/yowsup-config/yowsup.config</pre>
Sodass die Datei beispielhaft dann so aussieht:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx</pre>

Wie man schon gesehen hat, ist der Account nur begrenzt gültig - die Gültigkeit kann man anhand der als <code>expiration: </code> bezeichneten Zeile ablesen, welche einen Unix-Timestamp beinhaltet. Diese kann man [http://elmar-eigner.de/tstamps.html?zeichen=1444570276&timeformat=2 HIER] umrechnen lassen.

Nun mal ein schneller test an die eigene Nummer (im Beispiel 491751234567):
<pre>python yowsup-cli demos -c /opt/yowsup-config/yowsup.config -s 491751234567 "Das ist ein Test"</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* Fhem Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home PWD</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass Fhem online ist
* Zum Senden aus Fhem kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

== Attribute ==
Bitte sehe immer in der [[http://fhem.de/commandref.html#yowsup Commandref]] nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>. Wenn die ab yowsup-Version 2.4 standartmässig aktivierte Verschlüsselung abgeschaltet werden muss weil die entsprechenden Libs nicht installiert sind: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/yowsup-config --yowsup -M</code>.
* <code>accept_from</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als Fhem-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

== Befehle ==
* image -> Über diesen Befehl können Bilder gesendet werden.

* raw -> Status ändern :
<code>set WhatsApp raw /profile setStatus 'mein Status' <--- die ' ' müssen bleiben</code>

Name der angezeigt werden soll, wenn eine Nachricht z.B. ans iPhone geschickt wird:

<code>set WhatsApp raw /presence name <DeinNick></code>

Anzeige online :

<code>set WhatsApp raw /presence available</code>

Profilbild ändern :

<code>set WhatsApp raw /profile setPicture '/opt/fhem/fhem_logo.png'</code>
<--- der gesamte Pfad zum Bild muss angegeben werden und Rechte müssen ggfs. bei fhem liegen

Falls es nicht funktioniert disconnect/connect probieren.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein Fhem Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppen müssen über die App (Smartphone / Tablet) angelegt werden. Nach dem Empfang einer entsprechenden Nachricht werden Gruppen genauso behandelt, wie einfache Teilnehmer.

=== Broadcast ===
Beim Senden über das Masterdevice lassen sich mehrere Empfänger mit Komma (und ohne Leerzeichen) getrennt angeben. Die entsprechenden Nachrichten werden dann per Broadcast an alle Teilnehmer gesendet. Die Broadcastempfänger müssen zuvor mindestens eine normale Nachricht erhalten haben.

=== Komponenten steuern ===
Um ein [[notify]] anlegen zu können, müssen wir zuerst eine Nachricht vom Handy an FHEM senden. Dadurch wird ein Device mit der Nummer als Namen angelegt. Danach sollte das Device umbenannt werden, da einige Befehle einen Namen ausschließlich aus Ziffern nicht akzeptieren. Dies geschieht wie folgt:

:<code>rename 49123456789 HandySeppel</code>

Danach kann ein ''notify'' angelegt werden:

<source lang="perl">
define notifySeppelLicht notify HandySeppel:message.* {
if( $EVENT eq 'message: Licht an' ) {
fhem "set HandySeppel send Licht ist nun an...";
fhem "set FS20_a5d800 dim100%";

} elsif( $EVENT eq 'message: Licht aus' ) {
fhem "set HandySeppel send Licht ist nun aus...";
fhem "set FS20_a5d800 dim0%";

} else {
fhem "set HandySeppel send Wie bitte?"

}
}</source>

Natürlich ist dieses ''notify'' noch auf die eigenen Wünsche anzupassen.

=== Autoresponder ===
Nachdem man nun seine Festnetznummer bei WhatsApp registriert hat, wird auch diese natürlich als erreichbares Ziel auf jedem Gerät angezeigt, auf dem sie gespeichert ist. So kann es passieren, dass WhatsApp nicht gelesen werden. Hier schafft ein Autoresponder Abhilfe:
:<code>define not_WhatsApp_Autoresponder notify 491.*:message.* set $NAME send Hallo, Du hast eine Nachricht an unsere Festnetznummer geschickt. Da ist aber nur ein kleiner Computer auf Empfang, der Dir nur diese Antwort schicken kann. Bitte benutze unsere Mobilnummern, wenn Du willst, dass Deine Nachricht auch gelesen wird!</code>
Das Problem hierbei ist, dass noch nicht bekannt ist, wer etwas sendet und so der Kontakt u.U. noch nicht angelegt ist. Daher wird im obigen Beispiel auf 491*:message.* reagiert. So bekommen nur deutsche Mobilrufnummern die Antwort. Um das noch globaler zu fassen, könnte z.B. auf \d*.*:message.* reagiert werden, was aber voraussetzt, dass keine weiteren Modulnamen (die das Reading message haben) mit einer Ziffer beginnen.
Alle Kontakte, welche nicht den Autoresponder erhalten sollen, müssen wie oben beschrieben entspr. umbenannt werden:
:<code>rename 49123456789 HandySeppel</code>

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]
* Imagehandling Bugfix [https://github.com/tgalal/yowsup/issues/901 github]

Yowsup

2016-04-06T15:16:43Z

Muschelpuster: /* Installation */ python-axolotl-master ergänzt etspr. https://forum.fhem.de/index.php/topic,27543.msg431955.html#msg431955

{{SEITENTITEL:yowsup}}
{{Infobox Modul
|ModPurpose=Schnittstelle, um WhatsApp-Nachrichten empfangen und senden zu können.
|ModType=d
|ModCmdRef=yowsup
|ModFTopic=27543
|ModForumArea=Unterstuetzende Dienste
|ModTechName=32_yowsup.pm
|ModOwner=André / justme1968 ({{Link2FU|430|Forum}} / [[Benutzer Diskussion:justme|Wiki]])
}}

Das Modul [[yowsup]] dient dazu, WhatsApp-Nachrichten zu empfangen und zu senden. Nachrichten können sein:
* '''Text''': senden und empfangen, z.b.: Infonachrichten senden, FHEM-Kommandos empfangen
* '''Bilder''': senden und emfangen, z.b.: Webcambilder nach Bewegungserkennung versenden
* '''Audio''': empfangen, z.b.: Sprachdurchsagen empfangen und über SONOS abspielen

== Voraussetzungen ==
* Die Funktionalität ist vermutlich auf Linux/Unix Systeme beschränkt.
* Nach der Erstinstallation/-einrichtung '''muss''' zwingend das ''cmd'' Attribut korrekt gesetzt werden.

== Installation ==
Die ursprüngliche Einrichtung wurde {{Link2Forum|Topic=27543|Message=204426|LinkText=hier beschrieben}}, jedoch sind noch einige wichtige Dinge zu setzen.

=== Yowsup Installation ===
Bevor man loslegt sollte man wie immer sicherstellen, dass Debian auf dem aktuellen Stand ist:
<code>sudo apt-get update</code>
<code>sudo apt-get upgrade</code>
<code>sudo apt-get dist-upgrade</code>

Los gehts mit den Paketen:
<code>sudo apt-get install python-soappy python-dateutil python-pip python-dev build-essential</code>

Nun erstmal pip updaten:
<code>sudo pip install --upgrade pip</code>

Und dann axolotl installieren (das dauert ne Weile):
<code>sudo pip install python-axolotl</code>

Zudem wird neben den Python Modulen noch eine Lib von tgalal benötigt: 
<code>cd /opt/fhem/yowsup</code> 
<code>sudo wget https://github.com/tgalal/python-axolotl/archive/master.zip</code> 
<code>sudo unzip master.zip</code> 
<code>cd python-axolotl-master</code> 
<code>sudo python setup.py install</code> 

Will man Bilder verarbeiten, so braucht man noch ein paar Pakete mehr:
* Paketinstallationen:
** Unter Debian Wheezy: <code>sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
** Unter Debian Jessie: <code>sudo apt-get install libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk</code>
* PIP:<code>sudo pip install pillow</code>

Vor den weiteren Schritten sollte geprüft werden, ob dem User fhem eine Loginshell zugewiesen ist:
:<code>getent passwd fhem</code>
Wird hier am Ende /bin/false ausgegeben, so muss dies angepasst werden:
:<code>sudo chsh -s /bin/bash fhem</code>

Mittels ''getent passwd fhem'' kann auch bereits das Home-Verzeichnis ausgelesen werden, dies steht in der ausgegebenen Doppelpunkt-separierten Liste an vorletzter Stelle.

Nun loggt man sich unter dem User ein, unter dem fhem läuft (in den folgenden Beispielen werden die vom fhem-Setup-Script generierten Defaults verwendet: User=fhem , home=/opt/fhem Gruppe=dialout) und liest dort die $HOME-Variable aus und prüft das Home-Verzeichnis:
<pre>sudo su - fhem
echo $HOME
cd $HOME
logout</pre>
Diesen Wert braucht man später - gut merken. Sollte hier ein Fehler auftreten (z.B. das home nicht vorhanden), so muss dies zuerst korrigiert werden.

Desweiteren muss man nun yowsup installieren. Hierfür stehen zwei Möglichkeiten zur Verfügung:

Erstens:
<pre>
cd /opt
sudo mkdir yowsup-config
sudo wget -N https://github.com/tgalal/yowsup/archive/master.zip
sudo unzip -o master.zip
rm master.zip
cd yowsup-config
sudo nano yowsup.config
</pre>

Wie bemerkt, ist man nun im Editor für die yowsup.config gelandet. Diese wird nun wie folgt gefüllt:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=</pre>
Ersetze die Nummer 498912345678 gegen eine Festnetz oder Handynummer welche derzeit nicht mit WhatsApp verwendet wird. Mittels STRG+o wird die Datei nun gespeichert und mittels STRG+x verlässt man den Editor.

Vor den weiteren Schritten sollte man nun erstmal die yowsup Verzeichnisse dem fhem-user zugängig machen:
<pre>sudo chown -R fhem:dialout /opt/yowsup-master /opt/yowsup-config</pre>

Für die folgenden Schritte würde ich auf den FHEM-Nutzer wechseln:
<pre>sudo su - fhem
cd /opt/yowsup-master</pre>

Nun erfolgt die Anmeldung am WhatsApp-Server. Dies kann man nun via <code>voice</code> oder <code>sms</code> machen. Bei einem Handy bietet sich SMS an, bei Festnetzanschlüssen sollte voice gewählt werden, wenn man sich nicht sicher ist, dass der Anschluss die Funktion 'SMS im Festnetz' unterstützt. Dann wird der Bestätigungscode zwar auf Englisch vorgelesen, dafür ist die Zuverlässigkeit des Registrierungsvorganges zuverlässiger. Bei Festnetznummern sollte man unbedingt etwas zum schreiben bereit halten!
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -r sms</pre>

Die Rückmeldung ist nun entscheidend. Wenn man diese zurückbekommt:
<pre>de sms
status: fail
retry_after: 3600
reason: no_routes</pre>
Dann ist die Nummer so nicht kompatibel. Was man dann noch probieren kann, ist die registration via voice - meistens ist das aber vergebene Liebesmüh'.

Wenn man folgende Rückmeldung bekommt:
<pre>Detected cc: 49
status: sent
retry_after: 1805
length: 6
method: sms</pre>

So ist alles gut gelaufen und man sollte kurz später eine SMS bekommen. Darin ist ein Text, der am Ende z.B. 123-456 lautet. Diesen fügt man ohne Bindestrich am Ende des folgenden Befehls ein:
<pre>python yowsup-cli registration -c /opt/yowsup-config/yowsup.config -R 123456</pre>

Dann kommt ein Text der etwa so aussehen sollte:
<pre>status: ok
kind: free
pw: bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx
price: 0,89 €
price_expiration: 1432127524
currency: EUR
cost: 0.89
login: 498912345678
type: existing
expiration: 1460832553</pre>
Den Text hinter dem Zeilenanfang <code>pw: </code> benötigt man nun für die Konfigurationsdatei, wo dieser eingefügt werden muss:
<pre>nano /opt/yowsup-config/yowsup.config</pre>
Sodass die Datei beispielhaft dann so aussieht:
<pre>## Actual config starts below ##

#cc ist wichtig ansonsten funktioniert es nicht aus dem Script
cc=49
phone=498912345678
id=0000000000
password=bfGA9wPWWNeHcSBxxxxxxxxxxxxxxxxx</pre>

Wie man schon gesehen hat, ist der Account nur begrenzt gültig - die Gültigkeit kann man anhand der als <code>expiration: </code> bezeichneten Zeile ablesen, welche einen Unix-Timestamp beinhaltet. Diese kann man [http://elmar-eigner.de/tstamps.html?zeichen=1444570276&timeformat=2 HIER] umrechnen lassen.

Nun mal ein schneller test an die eigene Nummer (im Beispiel 491751234567):
<pre>python yowsup-cli demos -c /opt/yowsup-config/yowsup.config -s 491751234567 "Das ist ein Test"</pre>

Das sollte dir eine Nachricht einbringen. Wenn du darauf antwortest, kommt diese allerdings noch nicht an - der Client hat sich nach dem Befehl sofort beendet. Damit dieser dauerhaft im Hintergrund läuft legen wir nun in FHEM ein Gerät an, welches dies steuert.

=== FHEM Define ===
* Fhem Device anlegen: <code> define <name> yowsup</code>, also z.B. <code>define WhatsApp yowsup</code>
* Nun muss man den Pfad zu yowsup anpassen: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>
* Und das Home directory mit dem Pfad zum Home des fhem users: <code>attr WhatsApp home PWD</code>
* Wenn alles gut geht, gibt es danach im Device ein internal PID und das Reading ''state''
* Im Whatsapp Client auf dem Handy sollte man sehen, dass Fhem online ist
* Zum Senden aus Fhem kann man das Kommando <code>set WhatsApp send <nummer> <text></code> verwenden

== Attribute ==
Bitte sehe immer in der [[http://fhem.de/commandref.html#yowsup Commandref]] nach - diese hier könnten veraltet sein.

* <code>cmd</code> komplettes Kommando, um den yowsup Client zu starten. z.B.: <code>attr WhatsApp cmd /opt/yowsup-master/yowsup-cli demos -c /opt/yowsup-config/yowsup.config --yowsup</code>. Wenn die ab yowsup-Version 2.4 standartmässig aktivierte Verschlüsselung abgeschaltet werden muss weil die entsprechenden Libs nicht installiert sind: <code>attr WhatsApp cmd /opt/local/bin/yowsup-cli demos -c /root/yowsup-config --yowsup -M</code>.
* <code>accept_from</code> kommagetrennte Liste von Kontakten (Nummern), von denen Nachrichten akzeptiert werden. Ist das Attribut nicht gesetzt, so werden die Nachrichten von jedem akzeptiert.
* <code>commandPrefix</code> nicht gesetzt -> es werden keine Befehle akzeptiert. 0 -> es werden keine Befehle akzeptiert. 1 -> erlaubt Befehle, jede Nachricht wird als Fhem-Befehl interpretiert. alles andere -> Wenn die Nachricht mit diesem Prefix startet, wird alles weitere als Befehle interpretiert.
{{Randnotiz|RNTyp=Warn|RNText='''allowedCommands''' should work as intended, but no guarantee can be given, that there is no way to circumvent it.}}
* <code>allowedCommands</code> Eine Komma-getrennte Liste von zulässigen Befehlen für diesen Kontakt. Wenn die Liste leer ist (z.B. nur ein Komma), dann werden keine Befehle akzeptiert.
* <code>home</code> Setzt das Home-directory welches für yowsup verwendet werden soll.

== Befehle ==
* image -> Über diesen Befehl können Bilder gesendet werden.

* raw -> Status ändern :
<code>set WhatsApp raw /profile setStatus 'mein Status' <--- die ' ' müssen bleiben</code>

Name der angezeigt werden soll, wenn eine Nachricht z.B. ans iPhone geschickt wird:

<code>set WhatsApp raw /presence name <DeinNick></code>

Anzeige online :

<code>set WhatsApp raw /presence available</code>

Profilbild ändern :

<code>set WhatsApp raw /profile setPicture '/opt/fhem/fhem_logo.png'</code>
<--- der gesamte Pfad zum Bild muss angegeben werden und Rechte müssen ggfs. bei fhem liegen

Falls es nicht funktioniert disconnect/connect probieren.

== Anwendungsbeispiele ==
=== Beispielnachricht ===
Beim Empfang einer Nachricht wird automatisch ein Fhem Device für diesen Kontakt angelegt. In diesem Device gibt es das Reading '''message''' für die empfangene Nachricht und ab der ersten Nachricht auch das Reading '''chatstate''', in dem zu sehen ist, ob gerade getippt wird.
Nachdem ein Device für einen Kontakt angelegt ist, lässt sich auch direkt dieses Device zum Senden verwenden:
:<code>set <device> send <text></code>,
d.h., man spart sich die Angabe der Nummer.

=== Gruppen ===
Gruppen müssen über die App (Smartphone / Tablet) angelegt werden. Nach dem Empfang einer entsprechenden Nachricht werden Gruppen genauso behandelt, wie einfache Teilnehmer.

=== Broadcast ===
Beim Senden über das Masterdevice lassen sich mehrere Empfänger mit Komma (und ohne Leerzeichen) getrennt angeben. Die entsprechenden Nachrichten werden dann per Broadcast an alle Teilnehmer gesendet. Die Broadcastempfänger müssen zuvor mindestens eine normale Nachricht erhalten haben.

=== Komponenten steuern ===
Um ein [[notify]] anlegen zu können, müssen wir zuerst eine Nachricht vom Handy an FHEM senden. Dadurch wird ein Device mit der Nummer als Namen angelegt. Danach sollte das Device umbenannt werden, da einige Befehle einen Namen ausschließlich aus Ziffern nicht akzeptieren. Dies geschieht wie folgt:

:<code>rename 49123456789 HandySeppel</code>

Danach kann ein ''notify'' angelegt werden:

<source lang="perl">
define notifySeppelLicht notify HandySeppel:message.* {
if( $EVENT eq 'message: Licht an' ) {
fhem "set HandySeppel send Licht ist nun an...";
fhem "set FS20_a5d800 dim100%";

} elsif( $EVENT eq 'message: Licht aus' ) {
fhem "set HandySeppel send Licht ist nun aus...";
fhem "set FS20_a5d800 dim0%";

} else {
fhem "set HandySeppel send Wie bitte?"

}
}</source>

Natürlich ist dieses ''notify'' noch auf die eigenen Wünsche anzupassen.

=== Autoresponder ===
Nachdem man nun seine Festnetznummer bei WhatsApp registriert hat, wird auch diese natürlich als erreichbares Ziel auf jedem Gerät angezeigt, auf dem sie gespeichert ist. So kann es passieren, dass WhatsApp nicht gelesen werden. Hier schafft ein Autoresponder Abhilfe:
:<code>define not_WhatsApp_Autoresponder notify 491.*:message.* set $NAME send Hallo, Du hast eine Nachricht an unsere Festnetznummer geschickt. Da ist aber nur ein kleiner Computer auf Empfang, der Dir nur diese Antwort schicken kann. Bitte benutze unsere Mobilnummern, wenn Du willst, dass Deine Nachricht auch gelesen wird!</code>
Das Problem hierbei ist, dass noch nicht bekannt ist, wer etwas sendet und so der Kontakt u.U. noch nicht angelegt ist. Daher wird im obigen Beispiel auf 491*:message.* reagiert. So bekommen nur deutsche Mobilrufnummern die Antwort. Um das noch globaler zu fassen, könnte z.B. auf \d*.*:message.* reagiert werden, was aber voraussetzt, dass keine weiteren Modulnamen (die das Reading message haben) mit einer Ziffer beginnen.
Alle Kontakte, welche nicht den Autoresponder erhalten sollen, müssen wie oben beschrieben entspr. umbenannt werden:
:<code>rename 49123456789 HandySeppel</code>

== Links ==
* {{Link2Forum|Topic=27543|LinkText=Forenthread}}, in dem die Whatsapp Anwendung beschrieben wird
* {{Link2Forum|Topic=27543|Message=299292|LinkText=Foreneintrag}}, ab dem das yowsup Modul beschrieben wird
* Die Python Whatsapp Library auf [https://github.com/tgalal/yowsup github]
* Imagehandling Bugfix [https://github.com/tgalal/yowsup/issues/901 github]

Diskussion:DUOFERNSTICK

2016-04-04T06:36:04Z

Muschelpuster:

Ich empfehle statt der fehlerträchtigen ttyUSB-Zuordnung die auch in der commandref empfohlene Zuordnung per ID. Das funktioniert nachhaltig und kann auch bei nachträglicher Änderung der USB-Geräte in keinem Fall zu Verwechslungen führen. Durch die relativ eindeutige ID klappt das auch ohne Vorher-Nachher-Vergleich.

<code>define myDuoFernStick DUOFERNSTICK /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR03R9WD-if00-port0@115200 6F....</code>

Der Code ist nur ein Beispiel, die genaue Bezeichnung ist von Stick zu Stick verschieden, aber eindeutig. Den Link kann man aber sogar über einen FTP-Fernzugriff und den Ordnerbaum erfragen.

Ich schlage vor, das nachzutragen.--[[Benutzer:Pfriemler|Pfriemler]] ([[Benutzer Diskussion:Pfriemler|Diskussion]]) 22:30, 29. Mär. 2016 (CEST)

:Dem stimme ich zu und habe es angepasst--[[Benutzer:Muschelpuster|Muschelpuster]] ([[Benutzer Diskussion:Muschelpuster|Diskussion]]) 08:29, 4. Apr. 2016 (CEST)

DUOFERNSTICK

2016-04-04T06:33:32Z

Muschelpuster: /* Definition */

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERNSTICK
|ModTechName=10_DUOFERNSTICK.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

IO-Device für DuoFern-Module

=== Allgemeines ===
Das Modul stellt über den Rademacher USB Stick 70000093 Typ 9495-UW das IO-Device für Geräte dar, die mit dem Modul [[DUOFERN]] definiert werden.

=== Hardware ===
Als Schnittstelle zu den DuoFern-Geräten wird ein Rademacher USB Stick 70000093 Typ 9495-UW benötigt.

==== Hardwareidentifikation ====
Der Stick sollte über seine ID definiert werden. Um diese zu ermitteln werden die vorhandenen Sticks nach dem Stecken des Sticks abgefragt:
:<code>/dev/serial/by-id/*</code>
Hier sollte nun der Stick angezeigt werden:
:<code>lrwxrwxrwx 1 root root 13 Jan 1 1970 /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR03R9U4-if00-port0 -> ../../ttyUSB0</code>
Die so ermittelte ID wird nun zur Definition des Sticks verwendet.

=== Definition ===
Die Definition des Gerätes erfolgt via:
:<code>define '''meinModulname''' DUOFERNSTICK '''USB-Stick'''@115200 '''DuoFern_COde'''</code>
Der DuoFern-Code des Gerätes muss mit 6F beginnen, die folgenden 4 Stellen können frei gewählt werden (hexadezimal 0-F). 

==== Beispieldefinition ====
:<code>define Rademacher DUOFERNSTICK /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR03R9U4-if00-port0@115200 6F1A2B</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERNSTICK

2016-04-04T06:30:11Z

Muschelpuster: /* Beispieldefinition */

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERNSTICK
|ModTechName=10_DUOFERNSTICK.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

IO-Device für DuoFern-Module

=== Allgemeines ===
Das Modul stellt über den Rademacher USB Stick 70000093 Typ 9495-UW das IO-Device für Geräte dar, die mit dem Modul [[DUOFERN]] definiert werden.

=== Hardware ===
Als Schnittstelle zu den DuoFern-Geräten wird ein Rademacher USB Stick 70000093 Typ 9495-UW benötigt.

==== Hardwareidentifikation ====
Der Stick sollte über seine ID definiert werden. Um diese zu ermitteln werden die vorhandenen Sticks nach dem Stecken des Sticks abgefragt:
:<code>/dev/serial/by-id/*</code>
Hier sollte nun der Stick angezeigt werden:
:<code>lrwxrwxrwx 1 root root 13 Jan 1 1970 /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR03R9U4-if00-port0 -> ../../ttyUSB0</code>
Die so ermittelte ID wird nun zur Definition des Sticks verwendet.

=== Definition ===
Die Definition des Gerätes erfolgt via:
:<code>define '''meinModulname''' DUOFERNSTICK '''USB-Stick'''@115200 '''DuoFern_COde'''</code>
Der DuoFern-Code des Gerätes muss mit 6F beginnen, die folgenden 4 Stellen können frei gewählt werden (hexadezimal 0-F). 

==== Beispieldefinition ====
:<code>define Rademacher DUOFERNSTICK /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR03R9U4-if00@115200 6F1A2B</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

Diskussion:DUOFERNSTICK

2016-04-04T06:29:10Z

Muschelpuster:

Ich empfehle statt der fehlerträchtigen ttyUSB-Zuordnung die auch in der commandref empfohlene Zuordnung per ID. Das funktioniert nachhaltig und kann auch bei nachträglicher Änderung der USB-Geräte in keinem Fall zu Verwechslungen führen. Durch die relativ eindeutige ID klappt das auch ohne Vorher-Nachher-Vergleich.

<code>define myDuoFernStick DUOFERNSTICK /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR03R9WD-if00-port0@115200 6F....</code>

Der Code ist nur ein Beispiel, die genaue Bezeichnung ist von Stick zu Stick verschieden, aber eindeutig. Den Link kann man aber sogar über einen FTP-Fernzugriff und den Ordnerbaum erfragen.

Ich schlage vor, das nachzutragen.--[[Benutzer:Pfriemler|Pfriemler]] ([[Benutzer Diskussion:Pfriemler|Diskussion]]) 22:30, 29. Mär. 2016 (CEST)

Dem stimme ich zu und habe es angepasst--[[Benutzer:Muschelpuster|Muschelpuster]] ([[Benutzer Diskussion:Muschelpuster|Diskussion]]) 08:29, 4. Apr. 2016 (CEST)

DUOFERNSTICK

2016-04-04T06:28:00Z

Muschelpuster: Anpassung entspr. Commandref entspr. Hinweis vom Pfriemler

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERNSTICK
|ModTechName=10_DUOFERNSTICK.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

IO-Device für DuoFern-Module

=== Allgemeines ===
Das Modul stellt über den Rademacher USB Stick 70000093 Typ 9495-UW das IO-Device für Geräte dar, die mit dem Modul [[DUOFERN]] definiert werden.

=== Hardware ===
Als Schnittstelle zu den DuoFern-Geräten wird ein Rademacher USB Stick 70000093 Typ 9495-UW benötigt.

==== Hardwareidentifikation ====
Der Stick sollte über seine ID definiert werden. Um diese zu ermitteln werden die vorhandenen Sticks nach dem Stecken des Sticks abgefragt:
:<code>/dev/serial/by-id/*</code>
Hier sollte nun der Stick angezeigt werden:
:<code>lrwxrwxrwx 1 root root 13 Jan 1 1970 /dev/serial/by-id/usb-Rademacher_DuoFern_USB-Stick_WR03R9U4-if00-port0 -> ../../ttyUSB0</code>
Die so ermittelte ID wird nun zur Definition des Sticks verwendet.

=== Definition ===
Die Definition des Gerätes erfolgt via:
:<code>define '''meinModulname''' DUOFERNSTICK '''USB-Stick'''@115200 '''DuoFern_COde'''</code>
Der DuoFern-Code des Gerätes muss mit 6F beginnen, die folgenden 4 Stellen können frei gewählt werden (hexadezimal 0-F). 

==== Beispieldefinition ====
:<code>define Rademacher DUOFERNSTICK /dev/ttyUSB0@115200 6F1A2B</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERN

2016-04-04T06:15:55Z

Muschelpuster: /* Pairing bei Erstinbetriebnahme des Gerätes */

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERN
|ModTechName=30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

DuoFern-Module

=== Allgemeines ===
Das Modul definiert DuoFern-Geräte, welche über das Modul [[DUOFERNSTICK]] angesteuert werden können. Dieses muss zuvor definiert werden.

=== Definition ===
Die Aktoren senden nach einer Zustandsänderung automatisch eine Statusnachricht aus - auch wenn sie noch mit keinem anderen Gerät gepaart sind. Empfängt FHEM eine solche Nachricht, wird der Aktor per [[Autocreate]] angelegt und erscheint im Ordner DUOFERN (wenn in FHEM kein anderer Ordner für Neugeräte definiert wurde).
Ohne [[Autocreate]] muss das Gerät manuell definiert werden: 
:<code>define '''meinModulname''' DUOFERN '''DUOFERNCODE'''</code>
Wenn der Code des Gerätes nicht bekannt ist, kann dieser mittels des Event-Monitors ermittelt werden, indem an dem DuoFern-Gerät eine Aktion ausgeführt wird.

==== Beispieldefinition ====
:<code>define Rolladen1 DUOFERN 49A1F9</code>

=== Pairing ===
Zusätzlich zur Definition muss das Gerät mit dem Stick gepairt werden. Ohne Pairing kann FHEM zwar den Status des Gerätes lesen, es aber nicht steuern.

==== Pairing bei Erstinbetriebnahme des Gerätes ====
Während der ersten zwei Stunden nach Aktivierung der Stromzufuhr ist der Aktor bereit, das remotePair/remoteUnpair Kommando auch von nicht gepairten Geräten zu akzeptieren. Nach Ablauf dieser Zeit muss das Gerät manuell in den Pairing-Mode gebracht werden (s.u.).
Abschließend muss dann noch der Stick mittels Pair-Kommando in den Pairing-Mode versetzt werden.
 
Beispiel
:<code>set DUOFERN_4989AB set remotePair</code>
:<code>set mein_DuoFern_Stick pair</code>

==== Pairing über Pairing-Funktion des Gerätes ====
Das Gerät wird entspr. seiner Bedienungsanleitung in den Pairing-Modus versetzt. Dann wird das Pair-Kommando auf dem Stick ausgeführt werden:
:<code>set mein_DuoFern_Stick pair</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERN

2016-04-04T06:15:13Z

Muschelpuster: /* Pairing bei Erstinbetriebnahme des Gerätes */

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERN
|ModTechName=30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

DuoFern-Module

=== Allgemeines ===
Das Modul definiert DuoFern-Geräte, welche über das Modul [[DUOFERNSTICK]] angesteuert werden können. Dieses muss zuvor definiert werden.

=== Definition ===
Die Aktoren senden nach einer Zustandsänderung automatisch eine Statusnachricht aus - auch wenn sie noch mit keinem anderen Gerät gepaart sind. Empfängt FHEM eine solche Nachricht, wird der Aktor per [[Autocreate]] angelegt und erscheint im Ordner DUOFERN (wenn in FHEM kein anderer Ordner für Neugeräte definiert wurde).
Ohne [[Autocreate]] muss das Gerät manuell definiert werden: 
:<code>define '''meinModulname''' DUOFERN '''DUOFERNCODE'''</code>
Wenn der Code des Gerätes nicht bekannt ist, kann dieser mittels des Event-Monitors ermittelt werden, indem an dem DuoFern-Gerät eine Aktion ausgeführt wird.

==== Beispieldefinition ====
:<code>define Rolladen1 DUOFERN 49A1F9</code>

=== Pairing ===
Zusätzlich zur Definition muss das Gerät mit dem Stick gepairt werden. Ohne Pairing kann FHEM zwar den Status des Gerätes lesen, es aber nicht steuern.

==== Pairing bei Erstinbetriebnahme des Gerätes ====
Während der ersten zwei Stunden nach Aktivierung der Stromzufuhr ist der Aktor bereit, das remotePair/remoteUnpair Kommando auch von nicht gepairten Geräten zu akzeptieren. Nach Ablauf dieser Zeit muss das Gerät entspr. seiner Bedienungsanleitung in den Pairing-Mode gebracht werden (s.u.).
Abschließend muss dann noch der Stick mittels Pair-Kommando in den Pairing-Mode versetzt werden.
 
Beispiel
:<code>set DUOFERN_4989AB set remotePair</code>
:<code>set mein_DuoFern_Stick pair</code>

==== Pairing über Pairing-Funktion des Gerätes ====
Das Gerät wird entspr. seiner Bedienungsanleitung in den Pairing-Modus versetzt. Dann wird das Pair-Kommando auf dem Stick ausgeführt werden:
:<code>set mein_DuoFern_Stick pair</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERN

2016-04-04T06:13:53Z

Muschelpuster: /* Pairing bei Erstinbetriebnahme des Gerätes */

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERN
|ModTechName=30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

DuoFern-Module

=== Allgemeines ===
Das Modul definiert DuoFern-Geräte, welche über das Modul [[DUOFERNSTICK]] angesteuert werden können. Dieses muss zuvor definiert werden.

=== Definition ===
Die Aktoren senden nach einer Zustandsänderung automatisch eine Statusnachricht aus - auch wenn sie noch mit keinem anderen Gerät gepaart sind. Empfängt FHEM eine solche Nachricht, wird der Aktor per [[Autocreate]] angelegt und erscheint im Ordner DUOFERN (wenn in FHEM kein anderer Ordner für Neugeräte definiert wurde).
Ohne [[Autocreate]] muss das Gerät manuell definiert werden: 
:<code>define '''meinModulname''' DUOFERN '''DUOFERNCODE'''</code>
Wenn der Code des Gerätes nicht bekannt ist, kann dieser mittels des Event-Monitors ermittelt werden, indem an dem DuoFern-Gerät eine Aktion ausgeführt wird.

==== Beispieldefinition ====
:<code>define Rolladen1 DUOFERN 49A1F9</code>

=== Pairing ===
Zusätzlich zur Definition muss das Gerät mit dem Stick gepairt werden. Ohne Pairing kann FHEM zwar den Status des Gerätes lesen, es aber nicht steuern.

==== Pairing bei Erstinbetriebnahme des Gerätes ====
Während der ersten zwei Stunden nach Aktivierung der Stromzufuhr ist der Aktor bereit, das remotePair/remoteUnpair Kommando auch von nicht gepairten Geräten zu akzeptieren. Nach Ablauf dieser Zeit muss das Gerät entspr. seiner Bedienungsanleitung in den Pairing-Mode gebracht werden.
Abschließend muss dann noch der Stick mittels Pair-Kommando in den Pairing-Mode versetzt werden.
 
Beispiel
:<code>set DUOFERN_4989AB set remotePair</code>
:<code>set mein_DuoFern_Stick pair</code>

==== Pairing über Pairing-Funktion des Gerätes ====
Das Gerät wird entspr. seiner Bedienungsanleitung in den Pairing-Modus versetzt. Dann wird das Pair-Kommando auf dem Stick ausgeführt werden:
:<code>set mein_DuoFern_Stick pair</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERN

2016-04-04T06:11:45Z

Muschelpuster: /* Pairing bei Erstinbetriebnahme des Gerätes */

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERN
|ModTechName=30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

DuoFern-Module

=== Allgemeines ===
Das Modul definiert DuoFern-Geräte, welche über das Modul [[DUOFERNSTICK]] angesteuert werden können. Dieses muss zuvor definiert werden.

=== Definition ===
Die Aktoren senden nach einer Zustandsänderung automatisch eine Statusnachricht aus - auch wenn sie noch mit keinem anderen Gerät gepaart sind. Empfängt FHEM eine solche Nachricht, wird der Aktor per [[Autocreate]] angelegt und erscheint im Ordner DUOFERN (wenn in FHEM kein anderer Ordner für Neugeräte definiert wurde).
Ohne [[Autocreate]] muss das Gerät manuell definiert werden: 
:<code>define '''meinModulname''' DUOFERN '''DUOFERNCODE'''</code>
Wenn der Code des Gerätes nicht bekannt ist, kann dieser mittels des Event-Monitors ermittelt werden, indem an dem DuoFern-Gerät eine Aktion ausgeführt wird.

==== Beispieldefinition ====
:<code>define Rolladen1 DUOFERN 49A1F9</code>

=== Pairing ===
Zusätzlich zur Definition muss das Gerät mit dem Stick gepairt werden. Ohne Pairing kann FHEM zwar den Status des Gerätes lesen, es aber nicht steuern.

==== Pairing bei Erstinbetriebnahme des Gerätes ====
Während der ersten zwei Stunden nach Aktivierung der Stromzufuhr ist der Aktor bereit, das remotePair/remoteUnpair Kommando auch von nicht gepairten Geräten zu akzeptieren. Danach muss dann noch der Stick mittels Pair-Kommando in den Pairing-Mode versetzt werden.
 
Beispiel
:<code>set DUOFERN_4989AB set remotePair</code>
:<code>set mein_DuoFern_Stick pair</code>

==== Pairing über Pairing-Funktion des Gerätes ====
Das Gerät wird entspr. seiner Bedienungsanleitung in den Pairing-Modus versetzt. Dann wird das Pair-Kommando auf dem Stick ausgeführt werden:
:<code>set mein_DuoFern_Stick pair</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERN

2016-03-26T21:04:14Z

Muschelpuster: /* Definition */

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERN
|ModTechName=30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

DuoFern-Module

=== Allgemeines ===
Das Modul definiert DuoFern-Geräte, welche über das Modul [[DUOFERNSTICK]] angesteuert werden können.

=== Pairing ===
Vor der Definition des Gerätes muss dieses mit dem Stick gepairt werden (auch wenn es bereits durch [[Autocreate]] im Raum Duofern erscheint.

==== Pairing mit Autocrate bei Erstinbetriebnahme des Gerätes ====
Die Aktoren senden nach einer Zustandsänderung automatisch eine Statusnachricht aus - auch wenn sie noch mit keinem anderen Gerät gepaart sind. Empfängt FHEM eine solche Nachricht, wird der Aktor per [[Autocreate]] angelegt. Gepaart ist er deshalb noch nicht. Man sieht seinen Status, kann ihn aber ohne Pairing nicht fernsteuern. 
Während der ersten zwei Stunden nach Aktivierung der Stromzufuhr ist der Aktor bereit, das remotePair/remoteUnpair Kommando auch von nicht gepairten Geräten zu akzeptieren. Danach muss dann noch ein pair/unpair Kommando vom Stick kommen.
 
Beispiel
:<code>set DUOFERN_4989AB set remotePair</code>
:<code>set mein_DuoFern_Stick pair</code>

==== Pairing über Pairing-Funktion des Gerätest ====
Das Gerät wird entspr. seiner Bedienungsanleitung in den Pairing-Modus versetzt. Dann wird das Pair-Kommando auf dem Stick ausgeführt werden:
:<code>set mein_DuoFern_Stick pair</code>

=== Definition ===
Ohne [[Autocreate]] muss das Gerät nach dem Pairing manuell definiert werden 
:<code>define '''meinModulname''' DUOFERN '''DUOFERNCODE'''</code>
Wenn der Code des Gerätes nicht bekannt ist, kann dieser mittels des Event-Monitors ermittelt werden, indem an dem DuoFern-Gerät eine Aktion ausgeführt wird.

==== Beispieldefinition ====
:<code>define Rolladen1 DUOFERN 49A1F9</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERN

2016-03-26T21:01:58Z

Muschelpuster: /* Pairing */ - Erweiterung um Vorgänge beim Autocreate entspr. Beschreibung von Telekatz

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=Sonstige Systeme
|ModType=d
|ModCmdRef=DUOFERN
|ModTechName=30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

DuoFern-Module

=== Allgemeines ===
Das Modul definiert DuoFern-Geräte, welche über das Modul [[DUOFERNSTICK]] angesteuert werden können.

=== Pairing ===
Vor der Definition des Gerätes muss dieses mit dem Stick gepairt werden (auch wenn es bereits durch [[Autocreate]] im Raum Duofern erscheint.

==== Pairing mit Autocrate bei Erstinbetriebnahme des Gerätes ====
Die Aktoren senden nach einer Zustandsänderung automatisch eine Statusnachricht aus - auch wenn sie noch mit keinem anderen Gerät gepaart sind. Empfängt FHEM eine solche Nachricht, wird der Aktor per [[Autocreate]] angelegt. Gepaart ist er deshalb noch nicht. Man sieht seinen Status, kann ihn aber ohne Pairing nicht fernsteuern. 
Während der ersten zwei Stunden nach Aktivierung der Stromzufuhr ist der Aktor bereit, das remotePair/remoteUnpair Kommando auch von nicht gepairten Geräten zu akzeptieren. Danach muss dann noch ein pair/unpair Kommando vom Stick kommen.
 
Beispiel
:<code>set DUOFERN_4989AB set remotePair</code>
:<code>set mein_DuoFern_Stick pair</code>

==== Pairing über Pairing-Funktion des Gerätest ====
Das Gerät wird entspr. seiner Bedienungsanleitung in den Pairing-Modus versetzt. Dann wird das Pair-Kommando auf dem Stick ausgeführt werden:
:<code>set mein_DuoFern_Stick pair</code>

=== Definition ===
Wenn [[Autocreate]] aktiv ist, sollte das Gerät nach dem Pairing bereits im Raum Duofern angelegt sein. 
Die manuelle Definition des Gerätes erfolgt via:
:<code>define '''meinModulname''' DUOFERN '''DUOFERNCODE'''</code>
Wenn der Code des Gerätes nicht bekannt ist, kann dieser mittels des Event-Monitors ermittelt werden, indem an dem DuoFern-Gerät eine Aktion ausgeführt wird.

==== Beispieldefinition ====
:<code>define Rolladen1 DUOFERN 49A1F9</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERN

2016-03-26T19:14:20Z

Muschelpuster: Hinweis auf Autocreate

DUOFERN

2016-03-25T22:20:36Z

Muschelpuster:

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=FHEM - Hausautomations-Systeme
|ModType=d
|ModCmdRef=DUOFERN
|ModTechName=30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

DuoFern-Module

=== Allgemeines ===
Das Modul definiert DuoFern-Geräte, welche über das Modul [[DUOFERNSTICK]] angesteuert werden können.

=== Pairing ===
Vor der Definition des Gerätes muss dieses entspr. seiner Bedienungsanleitung mit dem Stick gepairt werden. Dazu wird zuerst der Pairing-Modus des Gerätes aktiviert und dann im Modul [[DUOFERNSTICK]] der Befehl 'set pair' ausgeführt. 
Beispiel
:<code>set mein_DuoFern_Stick pair</code>

=== Definition ===
Die Definition des Gerätes erfolgt via:
:<code>define '''meinModulname''' DUOFERN '''DUOFERNCODE'''</code>
Wenn der Code des Gerätes nicht bekannt ist, kann dieser mittels des Event-Monitors ermittelt werden, indem an dem DuoFern-Gerät eine Aktion ausgeführt wird.

==== Beispieldefinition ====
:<code>define Rolladen1 DUOFERN 49A1F9</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

DUOFERNSTICK

2016-03-25T22:19:46Z

Muschelpuster:

{{Infobox Modul
|ModPurpose=IO-Device für DuoFern-Module
|ModForumArea=FHEM - Hausautomations-Systeme
|ModType=d
|ModCmdRef=DUOFERNSTICK
|ModTechName=10_DUOFERNSTICK.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

IO-Device für DuoFern-Module

=== Allgemeines ===
Das Modul stellt über den Rademacher USB Stick 70000093 Typ 9495-UW das IO-Device für Geräte dar, die mit dem Modul [[DUOFERN]] definiert werden.

=== Hardware ===
Als Schnittstelle zu den DuoFern-Geräten wird ein Rademacher USB Stick 70000093 Typ 9495-UW benötigt.

==== Hardwareidentifikation ====
Um den Stick einwandfrei identifizieren zu können, empfiehlt es sich, vor dem Stecken des Sticks bereits vorhandene Device abzufragen:
:<code>ls -l /dev/ttyUSB*</code>
Ggf. vorhandene USB-Devices werden hier aufgelistet. Nun kann der Stick gesteckt werden und der og.g Befehl erneut ausgeführt werden. Das nun in der Liste hinzugekommene Device wird nun für die Definition des Sticks in FHEM benötigt.

=== Definition ===
Die Definition des Gerätes erfolgt via:
:<code>define '''meinModulname''' DUOFERNSTICK '''USB-Stick'''@115200 '''DuoFern_COde'''</code>
Der DuoFern-Code des Gerätes muss mit 6F beginnen, die folgenden 4 Stellen können frei gewählt werden (hexadezimal 0-F). 

==== Beispieldefinition ====
:<code>define Rademacher DUOFERNSTICK /dev/ttyUSB0@115200 6F1A2B</code>

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

Rademacher DuoFern

2016-03-25T22:18:11Z

Muschelpuster:

{{Infobox Modul
|ModPurpose=Ansteuerung von Rademacher DuoFern-Modulen
|ModForumArea=FHEM - Hausautomations-Systeme
|ModTechName=10_DUOFERNSTICK.pm 30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

Ansteuerung von Rademacher DuoFern-Komponenten

=== Allgemeines ===
Mit den Modulen [[DUOFERNSTICK]] und [[DUOFERN]] können Geräte des Herstellers Rademacher angesteuert werden, die auf dem DuoFern-Standard von Rademacher basieren. primär wurde die Modulgruppe für die Ansteuerung von Rademacher Rolladenmotoren und Gurtwicklern entwickelt - inzwischen sind aber weitere Module implementiert.
Alle Duofern-Geräte haben einen 6-stelligen hexadezimalen DuoFern-Code, der das Gerät identifiziert. Die führenden beiden Stellen definieren hierbei den Gerätetyp.

=== Hardware ===
Als Schnittstelle zu den DuoFern-Geräten wird ein Rademacher USB Stick 70000093 Typ 9495-UW benötigt. Eine Liste der unterstützten Geräte gilt es an dieser Stelle noch zu ergänzen.

=== Module ===
[[DUOFENSTICK]] definiert den Stick als IO-Device 
[[DUOFERN]] definiert die DuoFern-Geräte

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}

Rademacher DuoFern

2016-03-25T20:47:49Z

Muschelpuster: /* Allgemeines */

{{Infobox Modul
|ModPurpose=Ansteuerung von Rademacher DuoFern-Modulen
|ModForumArea=FHEM - Hausautomations-Systeme
|ModType=d
|ModTechName=10_DUOFERNSTICK.pm 30_DUOFERN.pm
|ModOwner=Telekatz ({{Link2FU|10183|Forum}})
}}

Ansteuerung von Rademacher DuoFern-Komponenten

=== Allgemeines ===
Mit den Modulen [[DUOFERNSTICK]] und [[DUOFERN]] können Geräte des Herstellers Rademacher angesteuert werden, die auf dem DuoFern-Standard von Rademacher basieren. primär wurde die Modulgruppe für die Ansteuerung von Rademacher Rolladenmotoren und Gurtwicklern entwickelt - inzwischen sind aber weitere Module implementiert.
Alle Duofern-Geräte haben einen 6-stelligen hexadezimalen DuoFern-Code, der das Gerät identifiziert. Die führenden beiden Stellen definieren hierbei den Gerätetyp.

=== Hardware ===
Als Schnittstelle zu den DuoFern-Geräten wird ein Rademacher USB Stick 70000093 Typ 9495-UW benötigt. Eine Liste der unterstützten Geräte gilt es an dieser Stelle noch zu ergänzen.

=== Module ===
[[DUOFENSTICK]] definiert den Stick als IO-Device 
[[DUOFERN]] definiert die DuoFern-Geräte

=== Links ===
* {{Link2Forum|Topic=40076|LinkText=Forenthema}}