FHEMWiki - Benutzerbeiträge [de]

Homebridge User Configs

2020-12-29T15:16:40Z

Moontear: HmIP-BWTH homebridgemapping ergänzt, da es sich vom default unterscheidet und auf ein userReading angewiesen ist

Dieser Eintrag dient zur Sammlung funktionsfähiger Homebridge Configs.

Bitte immer die FHEM Version und Homebridge Version angegeben.

Sehr gute Hinweise gibt es hier: http://www.meintechblog.de/2015/10/mit-siri-und-fhem-das-gesamte-smart-home-per-stimme-steuern/
== Mögliche Mappings ==
Die Möglichen Mappings können hier nachgelesen werden https://github.com/KhaosT/HAP-NodeJS/tree/master/src/lib/gen insbesondere in HomeKit.ts.

Hier ein Beispiel:
Characteristic.Brightness = function() {
Characteristic.call(this, 'Brightness', '00000008-0000-1000-8000-0026BB765291');
this.setProps({
format: Characteristic.Formats.INT,
unit: Characteristic.Units.PERCENTAGE,
maxValue: 100,
minValue: 0,
minStep: 1,
perms: [Characteristic.Perms.READ, Characteristic.Perms.WRITE, Characteristic.Perms.NOTIFY]
});
this.value = this.getDefaultValue();
};

Das Mapping in diesem Fall, hat den Titel Brightness.

Die Werte können in 1er Schritten zwischen 0 und 100 liegen (max und min Value)
== Erstellung eines HomebridgeMappings am Beispiel "Feuchtesensor" ==
Zum Einstieg etwas leicht nachvollziehbares.

Feuchtesensoren haben in der Regel ein "humidity" Reading, im Falle des Opus XT300 Bodenfeuchtesensors auch Temperatur und Batterie Level. Homekit unterstützt einen "HumiditySensor" Service. Dieser ist in homebridge-fhem nicht standardmäßig vorhanden (kann also nicht aus dem dropdown ausgewählt werden, sondern muss über das Befehlsfeld zugewiesen werden):

<code>attr meinSensor genericDeviceType HumiditySensor</code>

Im nächsten Schritt werden die Readings gemappt:

<code>attr meinSensor homebridgeMapping clear CurrentRelativeHumidity=humidity StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW CurrentTemperature=temperature</code>

<code>clear</code>löscht default mappings - das wird in der Regel nicht notwendig sein, schadet aber nicht

<code>CurrentRelativeHumidity</code> ist die relevante Homekit Characteristic - wird mit dem entsprechenden Reading des Sensors gemappt.

<code>StatusLowBattery</code> erwartet entweder BATTERY_LEVEL_NORMAL oder _LOW. Mein Sensor liefert ok zurück, wenn alles gut ist, also wird "ok" auf _NORMAL gemappt, alles andere auf _LOW.

Der Opus XT300 Bodenfeuchtesensors liefert auch noch die Temperatur - der HumiditySensor Service sieht das eigentlich nicht vor, daher wird die Temperatur auch nicht in der Apple "Home" App angezeigt. Bei Eve wird die Temperatur hingegen berücksichtigt.

== BRAVIA Fernseher ==
Ein Beispiel homebridgeMapping für Sony Bravia Fernseher (iOS 12.2 beta!) und genericDeviceType Television:
<pre>
clear
ConfiguredName:model
Active:state,values=off:INACTIVE;on:ACTIVE,cmds=ACTIVE:on;INACTIVE:off
RemoteKey:key,cmds=REWIND:remoteControl+Rewind;FAST_FORWARD:remoteControl+FastForward;NEXT_TRACK:remoteControl+NEXT_TRACK;PREVIOUS_TRACK:remoteControl+PREVIOUS_TRACK;ARROW_UP:remoteControl+Up;ARROW_DOWN:remoteControl+Down;ARROW_LEFT:remoteControl+Left;ARROW_RIGHT:remoteControl+Right;SELECT:remoteControl+Ok;BACK:remoteControl+RETURN;EXIT:remoteControl+Exit;PLAY_PAUSE:remoteControl+Play;INFORMATION:remoteControl+Info
SleepDiscoveryMode:default=ALWAYS_DISCOVERABLE
ClosedCaptions:default=0
DisplayOrder:default=Test1
CurrentMediaState:default=0:currentTitle
TargetMediaState:default=0,cmds=PLAY:remoteControl+play;PAUSE:remoteControl+pause;STOP:remoteControl+stop;
PictureMode:default=1
PowerModeSelection:default=1,cmds=0:remoteControl+options
ActiveIdentifier:input,default=0,values=/tv.dvbt|TV...DVB-T/:1;/HDMI.3/:2,cmds=1:input+TV+/+DVB-T;2:input+HDMI+3/ARC;3:application+Plex
TelevisionSpeaker#Mute=mute
Active:default=ACTIVE
VolumeSelector:volume,cmds=INCREMENT:VolumeUp;DECREMENT:VolumeDown
VolumeControlType:default=RELATIVE_WITH_CURRENT
linkedTo=Television
InputSource(1)#Identifier:default=1
ConfiguredName:default=TV
IsConfigured:default=CONFIGURED
InputSourceType:default=TUNER
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(2)#Identifier:default=2
ConfiguredName:default=APPLE+TV
IsConfigured:default=CONFIGURED
InputSourceType:default=HDMI
CurrentVisibilityState:default=SHOWN
linkedTo=Television
InputSource(3)#Identifier:default=3
ConfiguredName:default=PLEX
IsConfigured:default=CONFIGURED
InputSourceType:default=APPLICATION
CurrentVisibilityState:default=SHOWN
linkedTo=Television
</pre>

damit lässt sich der Fernseher über Siri/Homekit ein- und ausschalten sowie über das appleTV Control-Center Widget steuern.

== EnOcean STM 250 Tür-/Fensterkontakt ==
Der STM 250 liefert als Status in FHEM <code>open</code>, wenn das Fenster offen und damit der Kontakt "offen" ist. Analog liefert er <code>closed</code> wenn das Fenster geschlossen und damit auch der Kontakt geschlossen ist. Diese Statusangaben sind sehr intuitiv zu verstehen und zu interpretieren.

Die characteristic <code>ContactSensorState</code> von HomeKit liefert entweder den Wert <code>CONTACT_DETECTED=0</code> oder <code>CONTACT_NOT_DETECTED=1</code> zurück. Wobei <code>CONTACT_DETECTED</code> bedeutet, dass der Kontakt geschlossen ist. Je nach Darstellung in der HomeKit-fähigen App muss dieses Verhalten bei der Interpretation berücksichtigt werden. Die App Eve von Elgato zum Beispiel liefert für Kontaktsensoren "JA" oder "NEIN" mit der Bedeutung <code>CONTACT_DETECTED=0=JA</code> bzw. <code>CONTACT_NOT_DETECTED=1=NEIN</code> zurück.

Noch ein wichtiger Punkt: Um einen Sensorkontakt sinnvoll einzurichten sollte als zusätzlicher Wert für das Attribut <code>genericdeviceType</code> der Wert <code>ContactSensor</code> hinzugefügt werden. Wie das geht ist im Eintrag [[Homebridge_einrichten#FHEM_konfigurieren | Homebridge einrichten]] ausführlicher beschrieben.

Folgende Attribute dann hinzufügen:
attr STM250 genericDeviceType ContactSensor
attr STM250 homebridgeMapping ContactSensorState=state,values=closed:CONTACT_DETECTED;open:CONTACT_NOT_DETECTED

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

== Modul RESIDENTS für Anwesenheitserkennung und Steuerung der Anwesenheit benutzen ==
[[Datei:Homebridge_bewohner_zu_szene.jpeg|mini|Schaltzustand eines Bewohners zu einer Szene hinzufügen]]
Aus den einzelnen Komponenten des Moduls RESIDENTS, homebridge sowie der characteristic <code>On</code> und der Szenensteuerung lässt sich eine gleichzeitige Steuerung der Anwesenheit und Anwesenheitserkennung basteln.

Dazu müssen folgende Schritte unternommen werden:
* einem Bewohner aus dem Modul ROOMMATE die Steuerung über homebridgeMapping hinzufügen
* Szene für "Ich bin zu Hause" und "Ich gehe jetzt" in einer HomeKit-fähigen App wie z.B. Eve einrichten

Man kann einen beliebigen Bewohner aus dem Modul ROOMMATE nehmen und ihn über die characteristic <code>On</code> in Form eines Schalters sozusagen schaltbar machen. Nur wird das Ein- und Ausschalten des Bewohners über HomeKit in FHEM auf den Status home bzw. absent gemappt. Seit dem 06.02.2016 werden RESIDENTS automatisch als Occupancy Sensor für HomeKit annonciert. Nun noch die Attribute des ROOMMATE wie folgt setzen:
attr <ROOMMATE> genericDeviceType switch
attr <ROOMMATE> homebridgeMapping On=state,valueOn=/home|awoken|asleep|gotosleep/,valueOff=/gone|absent/,cmdOn=home,cmdOff=absent

Natürlich muss der Bewohner noch dem Filter von homebridge hinzugefügt und homebridge neu gestartet werden.

Anschließend geht es in der HomeKit-fähigen App Deiner Wahl weiter. In Eve von Elgato ist von vornherein zum Beispiel vorgesehen, dass man zwei Szenen "Ich bin zuhause" und "Ich verlasse das Haus" hat. Zu diesen Szenen wird eine Aktion hinzugefügt indem der Bewohner, den das ROOMMATE-Modul meldet zur Szene hinzugefügt wird und beim Nachhausekommen "eingeschaltet" wird. Genauso wird mit der Szene "Ich verlasse das Haus" verfahren: Bewohner zur Szene hinzufügen und den Schaltvorgang auf "ausschalten" setzen.

Mit den Sprachbefehlen "Ich bin zuhause" oder "Ich verlasse das Haus" wird die entsprechende Szene eingeschaltet, homebridge schaltet über das <code>homebridgeMapping</code> Attribut dann den Bewohner auf "home" oder "absent".

Getestet mit
FHEM 5.7 Rev. 9893
Homebridge 0.2.16
homebridge-fhem Vorschauversion aus {{Link2Forum|Topic=48558|Message=402024|LinkText=homebridge/homekit}}

Eine noch etwas bessere Schaltmöglichkeit bietet '''genericDeviceType security'''.
Das Mapping für ROOMMATE sieht wie folgt aus:
attr TYPE=ROOMMATE genericDeviceType security
attr TYPE=ROOMMATE homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;gone:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+gone,delay=1
für GUEST:
attr TYPE=GUEST genericDeviceType security
attr TYPE=GUEST homebridgeMapping SecuritySystemCurrentState=state,values=/home|awoken/:0;;absent:1;;/asleep|gotosleep/:2;;none:3 SecuritySystemTargetState=SecuritySystemCurrentState,cmds=0:state+home;;1:state+absent;;2:state+gotosleep;;3:state+none,delay=1

== Homematic Luftfeuchtigkeits- und Temperatursensoren ==

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- HM-WDS10-TH-O
- HM-WDS40-TH-I
- HM-WDS40-TH-I-2

Achtung: Hier wird genericDeviceType "TemperatureSensor" verwendet, um eine history in EVE zu erhalten. Mit einem "HumiditySensor" funktionierte dies bei den Tests (Februar 2019) nicht.

attr <THSensor> genericDeviceType TemperatureSensor

attr <THSensor> CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
history:size=1024

== Homematic SmokeDetector HM-SEC-SD und HM-SEC-SD2 ==
[[Datei:Homebridge-Homematic-Smokedetector-Gen1.jpg|mini|Homebridge-Homematic-Smokedetector-Gen1 in EVE]]
Es sind keine Homebridge Mappings für die Rauch Meldung erforderlich.

Allerdings ist ein Mapping für den Batterie Zustand nötig, siehe Unten.

attr <SmokeDetector> genericDeviceType SmokeSensor
attr <SmokeDetector> subType smokeDetector

attr <SmokeDetector> homebridgeMapping StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW

== Homematic Heizkörperthermostat HM-CC-RT-DN ==
[[Datei:HM-CC-RT-DN-Eve.PNG|mini|Darstellung des HM-CC-RT-DN in der iOS App Eve]]
attr <HMCCRTDN_Channel2_Clima> homebridgeMapping TargetTemperature=desired-temp::desired-temp,minValue=5,maxValue=35,minStep=0.5,nocache=1
CurrentTemperature=BU_Heizung_01_Clima:measured-temp,nocache=1
StatusLowBattery=BU_Heizung_01:battery,values=ok:BATTERY_LEVEL_NORMAL;;/^.*/:BATTERY_LEVEL_LOW
TargetHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:3,cmds=OFF:controlManu+off;;HEAT:controlMode+boost;;AUTO:controlMode+auto;;COOL:controlManu+17.0
CurrentHeatingCoolingState=heatingState,values=OFF:0;;HEAT:1;;COOL:2;;AUTO:0,valud=OFF
attr <HMCCRTDN_Channel2_Clima> siriName Robby
Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HM-CC-RT-DN_Clima> userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}
Global auf alle in FHEM angelegten HM-CC-RT-DN, lässt sich mit folgendem Befehl das ''userReading'' anlegen.
Siehe [https://forum.fhem.de/index.php/topic,59211.msg505986.html#msg505986 Forumsthread].

attr TYPE=CUL_HM:FILTER=model=HM-CC-RT-DN:FILTER=chanNo=04 userReadings heatingState {(ReadingsVal($NAME,"ValvePosition",0) > 0 || ReadingsVal($NAME,"desired-temp","-") eq "on") ? "HEAT" : ReadingsVal($NAME,"desired-temp","-") eq "off" ? "OFF" : ReadingsVal($NAME,"controlMode","auto") eq "auto" ? "AUTO" : (ReadingsVal($NAME,"measured-temp",20) > ReadingsVal($NAME,"desired-temp",20)) ? "COOL" : "AUTO"}

== Homematic IP Wandthermostat mit Schaltausgang HmIP-BWTH ==
attr <HmIP_BWTH_Thermostat> homebridgeMapping TargetTemperature=1.SET_POINT_TEMPERATURE::1.SET_POINT_TEMPERATURE,,minValue=17,maxValue=25,minStep=0.5,cmd=control,nocache=true
CurrentTemperature=1.ACTUAL_TEMPERATURE
CurrentHeatingCoolingState=heatingState,values=HEAT:1;COOL:2;OFF:0;AUTO:0
TargetHeatingCoolingState=heatingState,values=OFF:0;HEAT:1;COOL:2;AUTO:3,cmds=OFF:datapoint+1.CONTROL_MODE+1;HEAT:datapoint+1.BOOST_MODE+1;COOL:datapoint+1.BOOST_MODE+0;AUTO:datapoint+1.CONTROL_MODE+0
CurrentRelativeHumidity=1.HUMIDITY

Dieses Mapping bezieht sich auf ein vorhandenes ''userReading'' mit dem Namen <code>heatingState</code>, womit Homekit die einzelnen Status nachher unterscheidet.
attr <HmIP_BWTH_Thermostat> userReadings heatingState {(ReadingsVal($NAME,"10.STATE",0) eq 1 && ReadingsVal($NAME,"1.HEATING_COOLING",0) eq 0) ? "HEAT" : ReadingsVal($NAME,"1.SET_POINT_TEMPERATURE","-") eq "off" ? "OFF" : ReadingsVal($NAME,"1.SET_POINT_MODE","-") eq 0 ? "AUTO" : (ReadingsVal($NAME,"10.STATE",0) eq 1 && ReadingsVal($NAME,"1.HEATING_COOLING",0) eq 1) ? "COOL" : "OFF"}

== Homematic Wetterstation OC3 HM-WDS100-C6-O-2 ==
[[Datei: homebridge-wetter.jpg|mini|Wetterstation in EVE]]
Mit der EVE und den hier: [https://github.com/naofireblade/homebridge-weather-plus/blob/master/util/characteristics.js] beschriebenen Characteristics lässt sich eine lokale Homematic OC3 Wetterstation aus FHEM einbinden:
<pre>
clear
CurrentTemperature:temperature
CurrentRelativeHumidity:humidity
49C8AE5A-A3A5-41AB-BF1F-12D5654F9F41:windSpeed,name=WINDGESCHWINDIGKEIT,format=FLOAT,unit=kmh,maxValue=250,minValue=0,minStep=1
46f1284c-1912-421b-82f5-eb75008b167e:windDirection,name=WINDRICHTUNG,format=UINT8,unit=ARC_DEGREE,maxValue=360,minValue=0,minStep=1
StatusLowBattery:battery,values=ok:BATTERY_LEVEL_NORMAL;/^.*/:BATTERY_LEVEL_LOW
ccc04890-565b-4376-b39a-3113341d9e0f:RegenmengeLast24Hours:state,name=REGEN_24h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
10c88f40-7ec4-478c-8d5a-bd0c3cce14b7:RegenmengeLast1Hours:state,name=REGEN_1h,format=FLOAT,unit=mm,maxValue=100,minValue=0,minStep=1
0000006B-0000-1000-8000-0026BB765291:brightness,name=BRIGHTNESS,format=FLOAT,unit=LUX,maxValue=10000,minValue=0,minStep=.0001
cd65a9ab-85ad-494a-b2bd-2f380084134c:isRaining,name=BEDINGUNGKATEGORIE,values=0:0;1:2,format=UINT8,maxValue=3,minValue=0,minStep=1
cd65a9ab-85ad-494a-b2bd-2f380084134d:isRaining,name=BEDINGUNG,format=STRING,values=0:-;/.*/:Regen
</pre>

== Roomba über THINKINGCLEANER Modul ==
attr <THINKINGCLEANER> genericDeviceType switch
attr <THINKINGCLEANER> homebridgeMapping clear On=state,valueOn=/^(on|dock)/,cmdOn=on,cmdOff=off,nocache=1 ChargingState=deviceStatus,values=/(_recon|_full|_trickle)$/:CHARGING;/^.*/:NOT_CHARGING
attr <THINKINGCLEANER> siriName Robby

Getestet mit
FHEM 5.7 Rev. 12680
homebridge 0.4.11
homebridge-fhem 0.2.66

== Vallox Belüftungsanlage ==
Die Steuerung der Lüftungsgeschwindigkeit ist nur in Prozent möglich. Die Umrechnung erfolgt im [[Vallox]] Modul.
Hierzu wurde das Reading ''FanSpeedPct'' hinzugefügt.

attr <Vallox> genericDeviceType Fan
attr <Vallox> homebridgeMapping clear
model=Vallox
On=PowerState,valueOn=1,readOnly=1
RotationSpeed=FanSpeedPct,minValue=1,maxValue=100,cmd=FanSpeedPct,delay=1

== Xiaomi Vacuum Cleaner 1. Generation ==
[[Datei:XIAOMI_VACUUM_CLEANER-Gen1.jpg|mini|XIAOMI VACUUM 1. GEN in EVE]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryLevel,maxValue=100,minValue=0,minStep=1
StatusLowBattery=battery,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER

== Roborock S50 (2. Generation des Xiaomi Vacuum Cleaners) ==
[[Datei:Roborock S50.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Staubsauger mit dem Modul 72_XiaomiDevice.

Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Das folgende Mapping für den Roborook S50 beinhaltet neben den Characteristics der 1. Genration des Xiaomi Vacuum Cleaners weitere Custom Mappings. Diese werden auch auf dem Bild dargestellt. Falls das einem zu viele Informationen sind, können diese beim Einfügen einfach weggelassen oder in EVE ausgeblendet werden.

attr <XIAOMI> genericDeviceType switch
attr <XIAOMI> homebridgeMapping On=state,valueOn=Cleaning,cmdOn=start,cmdOff=charge
RotationSpeed=fan_power,minValue=0,maxValue=90,cmd=fan_power,delay=1
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=state,values=Docked:NOT_CHARGING;;Charging:CHARGING;;/.*/:NOT_CHARGEABLE
OccupancyDetected=state,values=/Docked|Charging/:OCCUPANCY_DETECTED;;/.*/:OCCUPANCY_NOT_DETECTED
2af6d0d0-3691-4f0d-9c9c-c1098295b1cb=consumables_sensors,name=Reinigung+Sensoren,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fd11b965-052e-430f-b08f-206287d8bc00=consumables_filter,name=Austausch+Filter,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
fe7a8dac-dff3-4a07-8a5e-0d6abbf0df0c=consumables_main_brush,name=Austausch+Hauptbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
4f9b2a22-b764-4fc1-8cd2-99383924394c=consumables_side_brush,name=Austausch+Seitenbürste,minValue=0,maxValue=100,format=FLOAT,minStep=1,unit=%
FilterLifeLevel=consumables_filter,minValue=0,maxValue=100
FilterChangeIndication=consumables_filter,values=0:CHANGE_FILTER
4896763a-26f7-400b-9734-2ce6564ceba2=total_clean_time,name=Lebenszeitersparnis,format=FLOAT,minStep=1,unit=h
82af5fd7-50a3-4ab3-81d3-1f7903de612a=total_clean_area,name=Gereinigte+Fläche,format=FLOAT,minStep=1,unit=m²
00d2ef14-b429-4569-8af3-c342d41cf383=total_cleans,name=Reinigungsvorgänge,format=FLOAT,minStep=1
e8d1027e-b068-40d5-9efd-f161b1b52774=device_firmware,name=Firmware,format=STRING

== Xiaomi Fan (ältere Generationen mit Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi DC Pedestal Fan.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Die ältere Generation enthält Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese fehlen bei den neueren Generation dieses Ventilators, siehe Bilder. Da anscheinend jedes Jahr neue Generationen dieses Ventilators herausgekommen sind, ist nicht klar bis zu welcher Generation diese Sensoren enthalten waren.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- Xiaomi DC Pedestal Fan (FHEM model fehlt, Default Hostname am Router: zhimi-fan-v3)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
CurrentRelativeHumidity=humidity
CurrentTemperature=temperature
BatteryLevel=batteryPercent,maxValue=100,minValue=0,minStep=1
StatusLowBattery=batteryState,values=ok:BATTERY_LEVEL_NORMAL;;low:BATTERY_LEVEL_LOW
ChargingState=charging,values=complete:NOT_CHARGING;;progress:CHARGING;;/.*/:NOT_CHARGEABLE
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== Xiaomi Fan (neuere Generationen ohne Luftfeuchtigkeits- und Temperatursensor und Battery-Readings) ==
[[Datei:Xiaomi Standing Fan 2 bzw. 2S.png|mini]]
Voraussetzung zur Verwendung der Mappings, ist ein eingebundener Ventilator mit dem Modul 72_XiaomiDevice.
Siehe [https://forum.fhem.de/index.php/topic,73052.0.html Forumsthread]
Das Modul muss manuell installiert werden.

Den neueren Generationen dieses Ventilators fehlen Sensoren und somit Readings für Luftfeuchtigkeit, Temperatur und auch Batteriestatus. Diese sind bei der älteren Generation dieses Ventilators enthalten, siehe vorangegangenes Beispiel.

Dieses Mapping wurde mit dem "2S" erstellt. Es sollte aber mindestens auch mit einem "Xiaomi Standing Fan 2" (ohne Akku) funktionieren, da auch der "Xiaomi Standing Fan 2S" (mit Akku) kein Reading für die Batterie bereitstellt. Ansonsten gibt es wohl auch noch Generationen zwischen dem "Xiaomi DC Pedestal Fan" und den "Xiaomi Standing Fan 2/2S". Es ist davon auszugehen, dass dieses Beispiel genauso auch bei diesen Modellen funktioniert.

Mit folgenden Geräten wurde folgendes Mapping erstellt und somit erfolgreich getestet:

- 2019 Xiaomi Standing Fan 2S (FHEM model bzw. Default Hostname am Router: zhimi-fan-za4)
- 2018 Xiaomi ZhiMiDCVariableFrequencyFan ZRFFS01ZM (FHEM model bzw. Default Hostname am Router: zhimi-fan-za1)
- Liste bitte ergänzen!

Um möglichst viele Funktionen bereitzustellen, wurden auch Characteristics von anderen DeviceTypes verwendet. Erklärung zu den Characteristics:

- Die Kindersicherung (LockPhysicalControls) ist in Eve über das kleine Einstellungssymbol zu finden.
- Mit AudioFeedback/Audio-Bestätigung werden die Töne des Lüfters ein bzw. ausgeschaltet.
- Mit NightVision/Nachtsicht werden die LEDs ein (bright) bzw. ausgeschaltet (off).
- Mit Mute/Audio wird der Windmodus von Straight zu Natural geschaltet.
- Mit TargetTiltAngle/Neigung kann der Schwenkwinkel justiert werden.
- Mit SwingMode/Schwenken kann der Schwenkmodus ein bzw. ausgeschaltet werden.
- Der Rest ist selbsterklärend.

homebridgeMapping:

attr <XIAOMI> genericDeviceType Fan
attr <XIAOMI> homebridgeMapping
clear
On:power,cmdOn=on,cmdOff=off,valueOn=on,valueOff=off
LockPhysicalControls=child_lock,values=on:CONTROL_LOCK_ENABLED;;off:CONTROL_LOCK_DISABLED,cmds=CONTROL_LOCK_ENABLED:child_lock+on;CONTROL_LOCK_DISABLED:child_lock+off
RotationSpeed=level,minValue=0,maxValue=100,cmd=level,delay=1
TargetTiltAngle=angle,minValue=30,maxValue=120,minStep=30,cmd=angle
SwingMode=angle_enable,values=on:SWING_ENABLED;;off:SWING_DISABLED,cmdOn=angle_enable+on,cmdOff=angle_enable+off
AudioFeedback:buzzer,cmdOn=buzzer+on,cmdOff=buzzer+off,valueOn=on,valueOff=off
NightVision:led,cmdOn=led+off,cmdOff=led+bright,valueOn=off,valueOff=bright
Mute:mode,cmdOn=mode+straight,cmdOff=mode+natural,valueOn=straight,valueOff=natural
CurrentFanState:power,values=on:BLOWING_AIR;;off:INACTIVE;;/.*/:IDLE

== ZWave Türschloss Vision ZM1701 einbinden ==
Das ZWave Türschloss ZM1701 von der Firma Vision sendet seinen aktuellen Schließstatus in ein einzelnes Reading wie "lock", sondern schickt eine ganze Reihe von Informationen über den Zustand in das Reading <code>doorLockOperation</code>. Das Schließen und Öffnen der Türschlosses wird auch nicht mit einem Setzen des <code>state</code> erreicht, sondern mit dem Setzen von <code>doorLockOperation</code>. Das macht das Einbinden in homebridge nicht trivial, funktioniert aber über folgendes Homebridge-Mapping:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open

Kurz zur Erklärung: Um ein Schloss über HomeKit steuern zu können braucht es zwei characteristics. LockCurrentState zeigt an, ob das Schloss geöffnet oder geschlossen ist. Und mit LockTargetState wird das Schloss geöffnet oder geschlossen. Damit der aktuelle Status des Schlosses ausgelesen werden kann, muss aus dem FHEM-Reading <code>doorLockOperation</code> die Zeichenfolge <code> secured</code> oder <code>unsecured</code> extrahiert werden, daher die beiden regulären Ausdrücke <code>/\ssecured/</code> und <code>/unsecured/</code>. In der characteristic <code>LockTargetState</code> muss sowohl der aktuelle Status des Schlosses als auch das Kommando angegeben werden, schließlich möchte man ein geschlossenes Schloss nicht nochmal schließen. Daher wird erst aus dem Reading <code>doorLockOperation</code> der aktuelle Status des Schlosses ausgelesen und die damit korrespondierenden Befehle über <code>cmds=SECURED:doorLockOperation+close;UNSECURED:doorLockOperation+open</code> generiert.

Wer es in FHEM über ein webCmd einfacher zu bedienen haben möchte, fügt bitte noch die dafür notwendigen Attribute und die leicht geänderten homebridgeMappings wie folgt ein:
attr <ZM1701> genericDeviceType lock
attr <ZM1701> homebridgeMapping LockCurrentState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED LockTargetState=doorLockOperation,values=/\ssecured/:SECURED;/unsecured/:UNSECURED,cmds=SECURED:close;UNSECURED:open
attr <ZM1701> /doorLockOperation open:open/doorLockOperation close:close
attr <ZM1701> webCmd open:close

Getestet mit
FHEM 5.7 Rev. 12191
homebridge 0.4.6
homebridge-fhem 0.2.48

[[Kategorie:HOWTOS]]

[[Kategorie:Sprachsteuerung]]

[[Kategorie:Code Snippets]]

DeviceOverview anpassen

2020-02-13T16:01:51Z

Moontear: /* STATE */ Beispiel hinzugefügt für Perl-Code

Diese Seite enthält einen systematischen Überblick über die verschiedenen Attribute, mit deren Hilfe das Erscheinungsbild und die Funktionalität eines [[Gerät|Geräts]] in [[FHEMWEB]] eingestellt und verändert werden kann. Dabei geht es im Folgenden um den sogenannten ''deviceOverview'', mit der ein Gerät in der Raumdarstellung erscheint, wobei hier nur das Erscheinungsbild in f18 auf einem großen Bildschirm behandelt wird.

==Überblick==
===Attribute===
Es stehen für alle Geräte in FHEM folgende Attribute zur Verfügung, die sich teilweise wechselseitig beeinflussen und überlagern:
*{{Link2CmdRef|Lang=de|Anker=icon|Label=icon}}
*[[webCmd]]
*[[eventMap]]
*{{Link2CmdRef|Lang=de|Anker=webCmdLabel|Label=webCmdLabel}}
*{{Link2CmdRef|Lang=de|Anker=cmdIcon|Label=cmdIcon}}
*{{Link2CmdRef|Lang=de|Anker=widgetOverride|Label=widgetOverride}}
*{{Link2CmdRef|Lang=de|Anker=stateFormat|Label=stateFormat}}
*[[devStateIcon]]
{{Hinweis|Wer einen schnellen Überblick über die diversen Widgets und webCmdLabel sucht, kann [[FHEMWEB/Widgets|hier]] fündig werden.}}

===Allgemeines zum deviceOverview===
Grundsätzlich ist der deviceOverview in verschiedene '''Bereiche''' eingeteilt, die zum Teil nur mit Inhalten gefüllt werden, wenn auch ein entsprechendes Attribut vorhanden ist.

''icon'' <Gerätename> ''STATE''/''devStateIcon'' ''webCmd''

Beispiele:
* ein ''icon'' wird nur angezeigt, wenn das entsprechende Attribut spezifiziert ist. Ansonsten beginnt der deviceOverview mit dem Gerätenamen.
* ist ein ''devStateIcon'' spezifiziert, verdrängt dieses in der Regel die ''STATE''-Darstellung
* entsprechendes gilt ggf. für eine eventMap
* ist keines der genannten Attribut definiert und vom jeweiligen Modul wird kein ''set'' bereitgestellt, besteht die Ansicht nur aus dem Gerätenamen und dem derzeitigen Inhalt des Internals ''STATE''. ''STATE'' wird dabei mangels stateFormat-Attribut aus dem Reading ''state'' abgeleitet. Ist auch dieses nicht vorhanden, erscheinen drei ???.

==webCmd & Co==
Der rechte Bereich wird mit Hilfe der Attribute webCmd, eventMap, cmdIcon, widgetOverride und webCmdLabel beeinflußt.
Dabei bestimmt webCmd, welche Kommandos angezeigt werden, mit eventMap<ref>dabei sind komplexere Perl-Angaben möglich, z.B. <code> attr tasmota_test eventMap { dev=>{'^(.*)POWER(.?): OFF$'=>'$1POWER$2: off', '^(.*)POWER(.?): ON$'=>'$1POWER$2: on'} }</code> </ref> werden diese intern ggf. in andere (Modul-)Befehle bzw. Reading-Inhalte umgewandelt und cmdIcon ermöglicht es, den Kommando-Text durch Symbole zu ersetzen. Mittels webCmdLabel kann eine Beschriftung vorangestellt werden und widgetOverride ein anderes Widget ausgewählt werden, als das, das für das Setzen eines bestimmten Readings standardmäßig verwendet wird. Weitere Hinweise zu diesen Attributen sind den oben verlinkten Artikeln zu entnehmen.

Hier soll anhand eines virtuellen Tür- oder Fensterkontakts die Funktionsweise der verschiedenen Attribute erläutert werden. Dazu wird zunächst mit <code>define Virtueller_Tuerkontakt CUL_HM 112233</code> ein CUL_HM-Gerät generiert und mit <code>set Virtueller_Tuerkontakt virtual 1</code> ein weiteres CUL_HM-Gerät für dessen ersten Kanal. Diesen <code>Virtueller_Tuerkontakt_Btn1</code> verwenden wir im Folgenden.

[[Datei:Virtueller Btn 1 neu erstellt.png]]

Dieser hat zunächst einen unbekannten STATE (''???'') und ein bereits gesetzes webCMD-Attribut ''press short:press long''. Für die Verwendung als Tuerkontakt soll dieser jedoch nicht kurze oder lange Tastendrücke als Information versenden, sondern soll offen- bzw. geschlossen-Nachrichten senden. Wir ändern das daher und klicken auf eines der angebotenen webCmd.
attr Virtueller_Tuerkontakt_Btn1 webCmd postEvent open:postEvent closed

[[Datei:Virtueller TK postEvent.png]]

Da dies nicht unbedingt optisch ansprechend ist, und wir vielleicht lieber eine Anzeige in unserer Sprache haben wollen, übersetzten wir das zwischen unserer Sprache und der des Türkontakts. Hierfür ändern wir das webCmd-Attribut auf ''offen:geschlossen'' und ergänzen
attr Virtueller_Tuerkontakt_Btn1 eventMap /postEvent open:offen/postEvent closed:geschlossen/
Da hier die zu übersetzenden Befehle Leerzeichen enthalten, muss statt des eigentlich üblichen Leerzeichens als Trenner zwischen den einzelnen Angaben etwas anderes festgelegt werden, hier wird "/" verwendet. Wenn jetzt ''offen'' gedrückt wird, sehen wir, dass sich nicht nur die Anzeige geändert hat:

[[Datei:WebCmd offen geschlossen.png]]

Jetzt sind auch state bzw. STATE und die Anzeige des entsprechenden Bereichs nicht mehr deckungsgleich. In state ist ''set_postEvent open'' enthalten, in der Anzeige erscheint aber ''set_offen''.
Um statt des Texts ein passendes Symbol anzuzeigen, legen wir nun ein cmdIcon-Attribut fest:
attr Virtueller_Tuerkontakt_Btn1 cmdIcon offen:fts_door_slide_open geschlossen:fts_door_slide

[[Datei:Tuerkontakt cmdIcon.png]]

Wer es farbig mag:
attr Virtueller_Tuerkontakt_Btn1 cmdIcon offen:fts_door_slide_open@red geschlossen:fts_door_slide@green
Mit vorangestellter Beschreibung:
attr Virtueller_Tuerkontakt_Btn1 webCmdLabel Auf:Zu

==STATE==
Ist kein ''stateFormat'' und kein ''devStateIcon'' spezifiziert, enthält der Bereich "STATE" den aktuellen Inhalt des Readings ''state''.
===stateFormat===
Mit diesem Attribut kann festgelegt werden, welcher Textinhalt für ''STATE'' verwendet werden soll. Es kann z.B. einfach eine Einheit hinzugefügt werden:
attr Aussentemperatur_Nord stateFormat state °C

[[Datei:DevState Text mit formatiertem state.png]]

Oder es können die Inhalte mehrerer Readings übernommen und formatiert werden:
attr MYSENSOR_97 stateFormat T: temperature2°C, H: humidity3%rH, P: pressure1 hPa, Status: state

[[Datei:MySensors stateFormat.png]]

Es kann für stateFormat auch Perl-Code festgelegt werden. Auf die geschweiften Klammern achten z.B.:
<nowiki>{if (ReadingsVal("MYSENSOR_97","contact","") =~ "open.*") {"open" . ReadingsTimestamp("MYSENSOR_97","contact","")} else {ReadingsVal("MYSENSOR_97","state","")}}</nowiki>
{{Hinweis|Bei Verwendung von Perl-Code in stateFormat sollte jedoch darauf geachtet werden, dass ein lesbarer Text zurückgeliefert wird! Für grafische Ausgaben soll und kann devStateIcon iVm. Perl-Code verwendet werden.}}

===devStateIcon===
Wird ein devStateIcon spezifiziert, verdrängt dies die Anzeige des STATE<ref>vorausgesetzt, in der Perl-Variante wird ein gültiges Ergebnis zurückgeliefert</ref>.

====Text-Variante====
Es kann zum einen einfach ein bestimmter Text jeweils durch ein passendes Icon ersetzt werden.

1. Beispiel:
attr Virtueller_Tuerkontakt devStateIcon set_offen:fts_door_slide_open set_geschlossen:fts_door_slide
Das ganze kann mit einer Farbangaben kombiniert sein:
attr Virtueller_Tuerkontakt devStateIcon set_offen:fts_door_slide_open@red set_geschlossen:fts_door_slide@green
Schließlich kann man auch noch einen Befehl festlegen, der beim Klicken auf das Symbol ausgeführt werden soll:
attr Virtueller_Tuerkontakt devStateIcon set_offen:fts_door_slide_open:geschlossen set_geschlossen:fts_door_slide:offen
bzw. mit Farbangabe:
attr Virtueller_Tuerkontakt devStateIcon set_offen:fts_door_slide_open@red:geschlossen set_geschlossen:fts_door_slide@green:offen
Damit wäre in obigem Beispiel webCmd und webCmdLabel nicht mehr erforderlich und könnte gelöscht werden.
Die folgenden Attribute sind für eine Bedienung ausreichend:
defmod Virtueller_Tuerkontakt_Btn1 CUL_HM 11223301
attr Virtueller_Tuerkontakt_Btn1 cmdIcon offen:fts_door_slide_open@red geschlossen:fts_door_slide@green
attr Virtueller_Tuerkontakt_Btn1 devStateIcon set_offen:fts_door_slide_open@red:geschlossen set_geschlossen:fts_door_slide@green:offen
attr Virtueller_Tuerkontakt_Btn1 eventMap /postEvent open:offen/postEvent closed:geschlossen/
[[Datei:Tuerkontakt defStateIcon only.png]]

2. Beispiel mit Regex<ref>Der Rollladenstatus ist hier invertiert, also 80% entspricht einem leicht geschlossenen Rollladen</ref>:
attr Rollladen devStateIcon 0:fts_shutter_100 100:fts_shutter_10 9\d.*:fts_shutter_10 8\d.*:fts_shutter_20 7\d.*:fts_shutter_30 6\d.*:fts_shutter_40 5\d.*:fts_shutter_50 4\d.*:fts_shutter_60 3\d.*:fts_shutter_70 2\d.*:fts_shutter_80 1\d.*:fts_shutter_90 0\d.*:fts_shutter_100

====Multi-Icon-Variante====
Seit 19.02.2019 ist es möglich, auch mehrere Icons zu nutzen, um den Zustand mehrerer Readings zu visualisieren. Beispiel 1 für den Zustand einer Tür samt Schloß:

[[Datei:Tuer geoeffnet.png]]

[[Datei:Tuer nicht-verschlossen.png]]

[[Datei:Tuer zu.png]]
<pre>defmod keller_flur_tuer ESPEasy 192.168.144.181 80 ESPBridge Keller_Sensoren_flur_holzhalle
attr keller_flur_tuer alias Tür Holzhalle
attr keller_flur_tuer devStateIcon 1.on:fts_door@green 1.off:fts_door_open@red\
2.on:secur_locked@green 2.off:secur_open@red
attr keller_flur_tuer icon hue_room_frontdoor
attr keller_flur_tuer stateFormat 1:mk\
2:rsk
</pre>
Anm.: rsk und mk sind jeweils die Namen der Readings für die Tür bzw. das Schloss

Beispiel 2: holiday-Datei:

[[Datei:Holiday-multiicon.png]]
<pre>defmod ferien holiday
attr ferien alias Ferien Baden-Württemberg
attr ferien devStateIcon [^(none|Heute|Morgen)].*:scene_party none:scene_office
attr ferien icon time_calendar
attr ferien stateFormat Heute: \
state\
Morgen: \
tomorrow
</pre>
Anm.: Die regex beim devStateIcon wandelt alles, das nicht "none", "heute" oder "Morgen" ist in das scene_party-Icon um .

====Perl-Variante====
Schließlich kann in dem Attribut Perl-Code enthalten sein, der dann auch komplexe Anweisungen enthalten kann. Beispiele:

'''Beispiel 1:''' Aufruf von Code aus einem Modul - regelbare Lampe mit toggle beim Klicken:
attr MQTT2_zigbee_0x90fd9ffffe65db16 devStateIcon {zigbee2mqtt_devStateIcon255($name)}

'''Beispiel 2:''' MySensors-Node mit farbiger Anzeige, ob regelmäßig Kontakt besteht<ref>Die Funktion ''FW_makeImage'' ist in der [[DevelopmentFHEMWEB-API]] näher erläutert</ref>:

<pre> attr MYSENSOR_97 devStateIcon {my $alivecolor = 'lan_rs485@red';;$alivecolor='lan_rs485@green' if (ReadingsVal($name, "state", "dead") eq "alive");;"<div>" . FW_makeImage("$alivecolor","lan_rs485") . FW_makeImage("temp_temperature","temp_temperature") . ReadingsVal($name,"temperature2",0) ."°C ". FW_makeImage("humidity","humidity"). ReadingsVal($name,"humidity3",0) . "%rH</div>"}
</pre>[[Datei:MySensors devStateIcon Perl.png]]

'''Beispiel 3:''' 4-Kanaliges Tasmota-Gerät mit Anzeige aller 4 Kanäle und toggle-Funktion auf jedem der Icons:
///tbd

== Weitere Beispiele ==
=== ReadingsProxy für fernotron-Rolladen ===
[[Datei:Fernotron deviceoverview.jpg]]
<pre>defmod Rolladen_Buero readingsProxy Rolladen_Buero
attr Rolladen_Buero alias Büro
attr Rolladen_Buero cmdIcon auf:fts_shutter_up stopp:fts_shutter_manual zu:fts_shutter_down
attr Rolladen_Buero eventMap u:auf d:zu s:stopp
attr Rolladen_Buero room Rolläden
attr Rolladen_Buero setFn { fhem('"sudo /home/pi/fernotron-control/FernotronRemote.sh 2 2 '. $CMD .'"') }
attr Rolladen_Buero setList u d s
attr Rolladen_Buero webCmd auf:stopp:zu</pre>

==Hinweise==
<references />

[[Kategorie:FHEM Frontends]]
[[Kategorie:FHEM-Verwendung]]
[[Kategorie:HOWTOS]]

HM-Sec-SCo Tür-Fensterkontakt, optisch

2020-02-13T14:16:33Z

Moontear: "Sensor" mit einem sprechenden Namen ersetzt, so dass man merkt dass es sich um eine Variable handelt

{{Infobox Hardware
|Bild=HM-SEC-SCo.jpg
|Bildbeschreibung=HomeMatic Tür-Fensterkontakt, optisch
|HWProtocol=HomeMatic
|HWType=Sensor
|HWCategory=HomeMatic
|HWComm=868MHz
|HWChannels=1
|HWVoltage=1,5 V DC
|HWPowerConsumption=max. 100 mA
|HWPoweredBy=Batterie (1x 1,5V LR03/Micro/AAA)
|HWSize=15x100x18mm
|HWDeviceFHEM=[[CUL_HM]]
|HWManufacturer=ELV / eQ-3
}}

== Features ==
[[HomeMatic]] Funk-Tür-/Fensterkontakt zur optischen Erkennung von Tür- bzw. Fensteröffnungen oder -schließungen, z.B. zur Sicherheit oder um automatisch, bei vorhandenem [[HM-CC-RT-DN]], die Heizung herunter zu regeln, sobald ein Fenster oder eine Tür geöffnet wird.

== HM-SEC-SC und HM-SEC-SCo ==
Das meiste zum [[HM-SEC-SC Tür-Fensterkontakt|HM-SEC-SC]] Beschriebene zur Nutzung gilt auch für den HM-Sec-SCo.

Wird mit aktiviertem [[AES Encryption|AES]] ausgeliefert und kann nur mit Gateways, die AES unterstützen, gepaired werden ([[HM-CFG-USB USB Konfigurations-Adapter|HM-LAN-CFG]], [[HM-CFG-LAN LAN Konfigurations-Adapter|HM-USB-CFG]] und [[CUL]] (seit Juli 2015)).

Mindestens bei Benutzung mit einem CUL (vermutlich auch via HM-CFG-USB und HM-CFG-LAN) muss FHEM auf das Perl-Modul Crypt::Rijndael zugreifen können. Wenn es nicht zur Verfügung steht, bleibt das Pairing unvollständig. Siehe auch [[AES_Encryption#IO <-> Gerät|den Abschnitt über AES-Encryption zwischen IO-Device und Gerät]].

== Aufbau ==
Das Gerät ist sowohl nutzungsbereit (ca. € 30) als auch als Bausatz (ca. € 20) verfügbar, letzterer muss selbst gelötet werden. Die Arbeitszeit sollte für erfahrende Personen unter 15 Minuten liegen.
[[Datei:Ansicht1.jpg|200px|thumb|left|Bestückung beider Platinen]]
[[Datei:Ansicht2.png|200px|thumb|right|Bestückung beider Platinen aus anderer Perspektive]]
Es sind nur
* das Funkmodul mit einer 8-poligen Stiftleiste
* der Batteriekontakt (Minuspol) mit einem kurzen Drahtstück
[[Datei:HM-Sec-SCo_Basisplatine.jpg|mini|250px|Markiert: Antennendurchführung (1), Batterieanschluss (2), sehr schmaler Platinensteg (3)]]
an der Basisplatine anzulöten.

Beim Zusammenbau muss darauf geachtet werden das immer das '''zugehörige''' Funkmodul mit der Basisplatine aus der Verpackung zusammen gelötet werden!
Jede Platine für sich enthält die eindeutige ID. Aber nur auf dem Funkmodul ist diese erkennbar. Wenn die Module beim Zusammenbau vermischt werden, sendet das Geräte die Open/Close-Meldungen mit der ID des Funkmoduls. Die Sabotage- und vermutlich Batterie-Meldungen werden mit der ID der Basisplatine gesendet!<br><br>
Zu beachten ist noch, dass die Antenne '''vor''' dem Auflöten des Funkmoduls durch das markierte Loch der Basisplatine geführt werden muss.

Die fertig montierte Platine muss sich leicht in das Gehäuse einsetzen lassen, anderenfalls wird der schmale Platinensteg u.U. zu stark belastet und kann brechen!

== Betrieb mit FHEM ==
=== Event-Monitor ===
Wird z. B. das Fenster geöffnet, übermittelt das Gerät folgendes:
<pre>
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG trigger_cnt: 11
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG trigDst_2573FB: noConfig
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG battery: ok
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG open
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG contact: open (to MyHMLAN)
</pre>

Beim schließen:
<pre>
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG trigger_cnt: 12
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG trigDst_2573FB: noConfig
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG battery: ok
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG closed
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG contact: closed (to MyHMLAN)
</pre>

=== Konfiguration ===
Bei eingeschaltetem [[autocreate]] werden die erforderlichen Definitionen beim Pairen selbstständig erstellt.

<pre>
define HM_Fensterstatus_BadEG CUL_HM 35E390
attr HM_Fensterstatus_BadEG IODev MyHMLAN
attr HM_Fensterstatus_BadEG actCycle 000:50
attr HM_Fensterstatus_BadEG actStatus dead
attr HM_Fensterstatus_BadEG autoReadReg 4_reqStatus
attr HM_Fensterstatus_BadEG expert 2_full
attr HM_Fensterstatus_BadEG firmware 1.0
attr HM_Fensterstatus_BadEG model HM-SEC-SCo
attr HM_Fensterstatus_BadEG peerIDs 00000000,
attr HM_Fensterstatus_BadEG room CUL_HM
attr HM_Fensterstatus_BadEG serialNr LEQxxxxxxx
attr HM_Fensterstatus_BadEG subType threeStateSensor
</pre>

=== Peering ===
Peering wie im Artikel [[Homematic Peering Beispiele]] beschrieben durchführen. Ein Beispiel könnte wie folgt aussehen:

<code>set HM_Fensterstatus_BadEG peerChan 0 HM_Heizung_Bad_WindowRec single</code>

Eine Besonderheit bei den Sensoren ist dass nach dem Ausführen dieses Befehls die Taste auf dem Sensor gedrückt werden muss. Manchmal auch mehrfach nacheinander, da in der kurzen aktiven Zeit nicht alle Befehle empfangen/gesendet werden können. Fertig ist der Sensor sobald die ''peerList'' korrekt gefüllt ist und keine Befehle mehr in der Warteschlange hängen (''protState'' ''= CMDs_done'').

== Beispiele ==
=== Aktionen durchführen, wenn Fenster zu lange geöffnet ist ===
==== DOIF-Variante ====
Mit der nachfolgenden [[DOIF]]-Definition wird ein [[FileLog|Log]]-Eintrag erzeugt. Eine Meldung auf der [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern|Dreambox]] angezeigt, falls diese angeschaltet ist, und eine Nachricht per Prowl (funktioniert vermutlich nur unter Linux) verschickt.

Der Code ist hier so angegeben, wie er in der Weboberfläche nach einem Klick auf das [[Konfiguration|DEF-Feld]] übernommen werden kann. Das DOIF ist vorab zu definieren, zum Beispiel mit:
:<code>def DOIF_FensterOffenMsg DOIF ([HM_Fensterstatus_BadEG])</code>
und kann dann anschließend in den Device-Details vervollständigt werden:
<syntaxhighlight lang="perl">
([HM_Fensterstatus_BadEG] eq "open") ({
Log 1, "Fenster seit mehr als 2 Stunden (7200 Sekunden) offen";;
system( "/path/to/prowl.pl -apikeyfile=/path/to/prowl-apikey -event=Info -notification='Fenster ist noch offen' &" );;
fhem( "set E2_Dreambox showText Fenster ist noch offen" ) if ReadingsVal("E2_Dreambox","state","") eq "on";;
})
DOELSE
</syntaxhighlight>

Damit der Code-Block erst nach 7200 Sekunden getriggert wird, ist noch Folgendes auszuführen:

:<code>attr DOIF_FensterOffenMsg wait 7200:0</code>

==== Watchdog-Variante ====
Alternativ zu der DOIF-Lösung gibt es eine einfache Lösung mit [[Watchdog]]. Dazu legt ihr einen Watchdog an:
:<code>define watchdogBadEG watchdog HM_Fenster_BadEG:open 00:15 HM_Fenster_BadEG:closed set myTelegram message Das Fenster ist seit 15 min offen!</code>
Der Watchdog besagt, dass er beim Status "open" des Gerätes/Devices "HM_Fenster_BadEG" (also dem Fenstersensor) aktiviert wird. Nach 15 Minuten schickt er eine Nachricht über [[Telegram]], es sei denn es kommt zwischenzeitlich der Status "closed".

=== Anzeige des Zeitpunkts der letzten Öffnung im STATE ===
Das Reading ''contact'' beinhaltet die Zustände ''open'' und ''closed''. Und der Zeitstempel der Änderung wird regelmäßig aktualisiert. Aus diesem Grund fällt die Nutzung des Attributs ''showtime'' hier weg. Wenigstens, wenn man nicht den Zeitpunkt des letzten Auslesens wissen will, sondern den der letzten Öffnung.

Folgende Schreibweise ermöglicht es, dass im STATE-Internal der Zeitpunkt des letzten ''open'' verbleibt (zum Übernehmen als Einzeiler kopieren):
:<code><nowiki>attr Sensor stateFormat {if (ReadingsVal("HM_Fensterstatus_BadEG","contact","") =~ "open.*") {"open " . ReadingsTimestamp("HM_Fensterstatus_BadEG","contact","")} else {InternalVal("HM_Fensterstatus_BadEG","STATE","")}}</nowiki></code>

Ein Thread zu diesem Thema findet sich im Forum unter dem Titel {{Link2Forum|Topic=41347|LinkText=HM-SEC-SCo: Letzte Türöffnung im State anzeigen}}.

== Bekannte Probleme ==
* Es kann vorkommen das der HM-Sec-SCo nach aufsetzen der Abdeckung scheinbar keine funktioniert hat.<br>
Unter {{Link2Forum|Topic=37508|LinkText=Forum}} wurde berichtet, das von EQ3/ELV repariert Geräte modifiziert zurück kamen.<br>
Die Reparatur bestand darin, das um den Foto-Sensor eine Abdeckung gelegt wurde.<br>
Dieses Problem gibt es 2019 weiterhin.<br>

* Bei (direkter) Sonneneinstrahlung kann es zu Fehlfunktionen kommen, die sich in schnell wechselnden Statusänderungen äußern.

Teilweise (siehe Diskussion im {{Link2Forum|Topic=33264|LinkText=Forum}}) werden die Fensterkontakte regelmäßig wiederkehrend als "dead" angezeigt.<br>
Grund ist, dass beim Anlernen ein actCycle von 50 Minuten eingetragen wird, während die Kontakte auch gerne mal länger brauchen, um sich bei der Zentrale zu melden.
<pre style="width:505px;">
2015-01-31_17:57:39 Fstr_AusgTerrasse alive: yes
2015-01-31_17:57:39 Fstr_AusgTerrasse battery: ok
2015-01-31_17:57:39 Fstr_AusgTerrasse sabotageError: off
2015-01-31_17:57:39 Fstr_AusgTerrasse closed
2015-01-31_17:57:39 Fstr_AusgTerrasse contact: closed (to HMLAN1)
2015-01-31_18:54:09 Fstr_AusgTerrasse Activity: dead
2015-01-31_18:58:03 Fstr_AusgTerrasse alive: yes
2015-01-31_18:58:03 Fstr_AusgTerrasse battery: ok
2015-01-31_18:58:03 Fstr_AusgTerrasse sabotageError: off
2015-01-31_18:58:03 Fstr_AusgTerrasse closed
2015-01-31_18:58:03 Fstr_AusgTerrasse contact: closed (to HMUSB)
2015-01-31_19:04:09 Fstr_AusgTerrasse Activity: alive
</pre>

Um Abhilfe zu schaffen, den actCycle auf 01:05 setzen:
:<code>attr <HM-SEC-SCo> actCycle 001:05</code>

Save config nicht vergessen.

== Links ==
* Anleitung [http://www.eq-3.de/Downloads/eq3/downloads_produktkatalog/homematic/bda/HM-Sec-SCo_UM_GE_eQ-3_web.pdf PDF]
* Datenblatt [http://www.eq-3.de/service/downloads.html?id=235&download=produkt&pid=1947 PDF] (der direkte Link auf das PDF klappt nicht, vermutlich wegen der Codierung des Umlautes :-( )
[[Kategorie:HomeMatic Components]]
[[Kategorie:Kontaktsensor (optisch)]]

HM-Sec-SCo Tür-Fensterkontakt, optisch

2020-02-13T12:25:46Z

Moontear: peering info hinzugefügt

{{Infobox Hardware
|Bild=HM-SEC-SCo.jpg
|Bildbeschreibung=HomeMatic Tür-Fensterkontakt, optisch
|HWProtocol=HomeMatic
|HWType=Sensor
|HWCategory=HomeMatic
|HWComm=868MHz
|HWChannels=1
|HWVoltage=1,5 V DC
|HWPowerConsumption=max. 100 mA
|HWPoweredBy=Batterie (1x 1,5V LR03/Micro/AAA)
|HWSize=15x100x18mm
|HWDeviceFHEM=[[CUL_HM]]
|HWManufacturer=ELV / eQ-3
}}

== Features ==
[[HomeMatic]] Funk-Tür-/Fensterkontakt zur optischen Erkennung von Tür- bzw. Fensteröffnungen oder -schließungen, z.B. zur Sicherheit oder um automatisch, bei vorhandenem [[HM-CC-RT-DN]], die Heizung herunter zu regeln, sobald ein Fenster oder eine Tür geöffnet wird.

== HM-SEC-SC und HM-SEC-SCo ==
Das meiste zum [[HM-SEC-SC Tür-Fensterkontakt|HM-SEC-SC]] Beschriebene zur Nutzung gilt auch für den HM-Sec-SCo.

Wird mit aktiviertem [[AES Encryption|AES]] ausgeliefert und kann nur mit Gateways, die AES unterstützen, gepaired werden ([[HM-CFG-USB USB Konfigurations-Adapter|HM-LAN-CFG]], [[HM-CFG-LAN LAN Konfigurations-Adapter|HM-USB-CFG]] und [[CUL]] (seit Juli 2015)).

Mindestens bei Benutzung mit einem CUL (vermutlich auch via HM-CFG-USB und HM-CFG-LAN) muss FHEM auf das Perl-Modul Crypt::Rijndael zugreifen können. Wenn es nicht zur Verfügung steht, bleibt das Pairing unvollständig. Siehe auch [[AES_Encryption#IO <-> Gerät|den Abschnitt über AES-Encryption zwischen IO-Device und Gerät]].

== Aufbau ==
Das Gerät ist sowohl nutzungsbereit (ca. € 30) als auch als Bausatz (ca. € 20) verfügbar, letzterer muss selbst gelötet werden. Die Arbeitszeit sollte für erfahrende Personen unter 15 Minuten liegen.
[[Datei:Ansicht1.jpg|200px|thumb|left|Bestückung beider Platinen]]
[[Datei:Ansicht2.png|200px|thumb|right|Bestückung beider Platinen aus anderer Perspektive]]
Es sind nur
* das Funkmodul mit einer 8-poligen Stiftleiste
* der Batteriekontakt (Minuspol) mit einem kurzen Drahtstück
[[Datei:HM-Sec-SCo_Basisplatine.jpg|mini|250px|Markiert: Antennendurchführung (1), Batterieanschluss (2), sehr schmaler Platinensteg (3)]]
an der Basisplatine anzulöten.

Beim Zusammenbau muss darauf geachtet werden das immer das '''zugehörige''' Funkmodul mit der Basisplatine aus der Verpackung zusammen gelötet werden!
Jede Platine für sich enthält die eindeutige ID. Aber nur auf dem Funkmodul ist diese erkennbar. Wenn die Module beim Zusammenbau vermischt werden, sendet das Geräte die Open/Close-Meldungen mit der ID des Funkmoduls. Die Sabotage- und vermutlich Batterie-Meldungen werden mit der ID der Basisplatine gesendet!<br><br>
Zu beachten ist noch, dass die Antenne '''vor''' dem Auflöten des Funkmoduls durch das markierte Loch der Basisplatine geführt werden muss.

Die fertig montierte Platine muss sich leicht in das Gehäuse einsetzen lassen, anderenfalls wird der schmale Platinensteg u.U. zu stark belastet und kann brechen!

== Betrieb mit FHEM ==
=== Event-Monitor ===
Wird z. B. das Fenster geöffnet, übermittelt das Gerät folgendes:
<pre>
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG trigger_cnt: 11
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG trigDst_2573FB: noConfig
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG battery: ok
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG open
2015-02-08 20:04:24 CUL_HM HM_Fensterstatus_BadEG contact: open (to MyHMLAN)
</pre>

Beim schließen:
<pre>
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG trigger_cnt: 12
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG trigDst_2573FB: noConfig
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG battery: ok
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG closed
2015-02-08 20:04:31 CUL_HM HM_Fensterstatus_BadEG contact: closed (to MyHMLAN)
</pre>

=== Konfiguration ===
Bei eingeschaltetem [[autocreate]] werden die erforderlichen Definitionen beim Pairen selbstständig erstellt.

<pre>
define HM_Fensterstatus_BadEG CUL_HM 35E390
attr HM_Fensterstatus_BadEG IODev MyHMLAN
attr HM_Fensterstatus_BadEG actCycle 000:50
attr HM_Fensterstatus_BadEG actStatus dead
attr HM_Fensterstatus_BadEG autoReadReg 4_reqStatus
attr HM_Fensterstatus_BadEG expert 2_full
attr HM_Fensterstatus_BadEG firmware 1.0
attr HM_Fensterstatus_BadEG model HM-SEC-SCo
attr HM_Fensterstatus_BadEG peerIDs 00000000,
attr HM_Fensterstatus_BadEG room CUL_HM
attr HM_Fensterstatus_BadEG serialNr LEQxxxxxxx
attr HM_Fensterstatus_BadEG subType threeStateSensor
</pre>

=== Peering ===
Peering wie im Artikel [[Homematic Peering Beispiele]] beschrieben durchführen. Ein Beispiel könnte wie folgt aussehen:

<code>set HM_Fensterstatus_BadEG peerChan 0 HM_Heizung_Bad_WindowRec single</code>

Eine Besonderheit bei den Sensoren ist dass nach dem Ausführen dieses Befehls die Taste auf dem Sensor gedrückt werden muss. Manchmal auch mehrfach nacheinander, da in der kurzen aktiven Zeit nicht alle Befehle empfangen/gesendet werden können. Fertig ist der Sensor sobald die ''peerList'' korrekt gefüllt ist und keine Befehle mehr in der Warteschlange hängen (''protState'' ''= CMDs_done'').

== Beispiele ==
=== Aktionen durchführen, wenn Fenster zu lange geöffnet ist ===
==== DOIF-Variante ====
Mit der nachfolgenden [[DOIF]]-Definition wird ein [[FileLog|Log]]-Eintrag erzeugt. Eine Meldung auf der [[Enigma2 Receiver (Dreambox, VUplus etc.) steuern|Dreambox]] angezeigt, falls diese angeschaltet ist, und eine Nachricht per Prowl (funktioniert vermutlich nur unter Linux) verschickt.

Der Code ist hier so angegeben, wie er in der Weboberfläche nach einem Klick auf das [[Konfiguration|DEF-Feld]] übernommen werden kann. Das DOIF ist vorab zu definieren, zum Beispiel mit:
:<code>def DOIF_FensterOffenMsg DOIF ([HM_Fensterstatus_BadEG])</code>
und kann dann anschließend in den Device-Details vervollständigt werden:
<syntaxhighlight lang="perl">
([HM_Fensterstatus_BadEG] eq "open") ({
Log 1, "Fenster seit mehr als 2 Stunden (7200 Sekunden) offen";;
system( "/path/to/prowl.pl -apikeyfile=/path/to/prowl-apikey -event=Info -notification='Fenster ist noch offen' &" );;
fhem( "set E2_Dreambox showText Fenster ist noch offen" ) if ReadingsVal("E2_Dreambox","state","") eq "on";;
})
DOELSE
</syntaxhighlight>

Damit der Code-Block erst nach 7200 Sekunden getriggert wird, ist noch Folgendes auszuführen:

:<code>attr DOIF_FensterOffenMsg wait 7200:0</code>

==== Watchdog-Variante ====
Alternativ zu der DOIF-Lösung gibt es eine einfache Lösung mit [[Watchdog]]. Dazu legt ihr einen Watchdog an:
:<code>define watchdogBadEG watchdog HM_Fenster_BadEG:open 00:15 HM_Fenster_BadEG:closed set myTelegram message Das Fenster ist seit 15 min offen!</code>
Der Watchdog besagt, dass er beim Status "open" des Gerätes/Devices "HM_Fenster_BadEG" (also dem Fenstersensor) aktiviert wird. Nach 15 Minuten schickt er eine Nachricht über [[Telegram]], es sei denn es kommt zwischenzeitlich der Status "closed".

=== Anzeige des Zeitpunkts der letzten Öffnung im STATE ===
Das Reading ''contact'' beinhaltet die Zustände ''open'' und ''closed''. Und der Zeitstempel der Änderung wird regelmäßig aktualisiert. Aus diesem Grund fällt die Nutzung des Attributs ''showtime'' hier weg. Wenigstens, wenn man nicht den Zeitpunkt des letzten Auslesens wissen will, sondern den der letzten Öffnung.

Folgende Schreibweise ermöglicht es, dass im STATE-Internal der Zeitpunkt des letzten ''open'' verbleibt (zum Übernehmen als Einzeiler kopieren):
:<code><nowiki>attr Sensor stateFormat {if (ReadingsVal("Sensor","contact","") =~ "open.*") {"open " . ReadingsTimestamp("Sensor","contact","")} else {InternalVal("Sensor","STATE","")}}</nowiki></code>

Ein Thread zu diesem Thema findet sich im Forum unter dem Titel {{Link2Forum|Topic=41347|LinkText=HM-SEC-SCo: Letzte Türöffnung im State anzeigen}}.

== Bekannte Probleme ==
* Es kann vorkommen das der HM-Sec-SCo nach aufsetzen der Abdeckung scheinbar keine funktioniert hat.<br>
Unter {{Link2Forum|Topic=37508|LinkText=Forum}} wurde berichtet, das von EQ3/ELV repariert Geräte modifiziert zurück kamen.<br>
Die Reparatur bestand darin, das um den Foto-Sensor eine Abdeckung gelegt wurde.<br>
Dieses Problem gibt es 2019 weiterhin.<br>

* Bei (direkter) Sonneneinstrahlung kann es zu Fehlfunktionen kommen, die sich in schnell wechselnden Statusänderungen äußern.

Teilweise (siehe Diskussion im {{Link2Forum|Topic=33264|LinkText=Forum}}) werden die Fensterkontakte regelmäßig wiederkehrend als "dead" angezeigt.<br>
Grund ist, dass beim Anlernen ein actCycle von 50 Minuten eingetragen wird, während die Kontakte auch gerne mal länger brauchen, um sich bei der Zentrale zu melden.
<pre style="width:505px;">
2015-01-31_17:57:39 Fstr_AusgTerrasse alive: yes
2015-01-31_17:57:39 Fstr_AusgTerrasse battery: ok
2015-01-31_17:57:39 Fstr_AusgTerrasse sabotageError: off
2015-01-31_17:57:39 Fstr_AusgTerrasse closed
2015-01-31_17:57:39 Fstr_AusgTerrasse contact: closed (to HMLAN1)
2015-01-31_18:54:09 Fstr_AusgTerrasse Activity: dead
2015-01-31_18:58:03 Fstr_AusgTerrasse alive: yes
2015-01-31_18:58:03 Fstr_AusgTerrasse battery: ok
2015-01-31_18:58:03 Fstr_AusgTerrasse sabotageError: off
2015-01-31_18:58:03 Fstr_AusgTerrasse closed
2015-01-31_18:58:03 Fstr_AusgTerrasse contact: closed (to HMUSB)
2015-01-31_19:04:09 Fstr_AusgTerrasse Activity: alive
</pre>

Um Abhilfe zu schaffen, den actCycle auf 01:05 setzen:
:<code>attr <HM-SEC-SCo> actCycle 001:05</code>

Save config nicht vergessen.

== Links ==
* Anleitung [http://www.eq-3.de/Downloads/eq3/downloads_produktkatalog/homematic/bda/HM-Sec-SCo_UM_GE_eQ-3_web.pdf PDF]
* Datenblatt [http://www.eq-3.de/service/downloads.html?id=235&download=produkt&pid=1947 PDF] (der direkte Link auf das PDF klappt nicht, vermutlich wegen der Codierung des Umlautes :-( )
[[Kategorie:HomeMatic Components]]
[[Kategorie:Kontaktsensor (optisch)]]

HomeMatic IP

2020-01-14T13:27:48Z

Moontear: links ergänzt zu Virtualiserungslösungen

Homematic IP (HM-IP) ist eine neue, kommunikationstechnisch stark veränderte Generation des Systems [[HomeMatic|Homematic]] von eQ-3.

Das System basiert auf einer Funkkommunikation auf 868 MHz mit einem bidirektionalen (Aktoren bestätigen Empfang, Verständnis und Ausführung von Nachrichten) und verschlüsselnden (AES-128 im CCM-Modus) Protokoll (IPv6 over BidCos).

Somit sind die Geräte aktuell nur über eine systemeigene Zentrale CCU2 oder neuer (als physisch vorhandenes Interface), oder eine virtualisierte CCU<ref>Hierfür stehen mehrere Virtualisierungsvarianten zur Verfügung; eine kurze Darstellung, wie das mittels [https://github.com/leonsio/YAHM YAHM] funktioniert, ist in diesem {{Link2Forum|Topic=79670|Message=718289|Forenbeitrag}} zu finden. Weitere Alternativen sind [https://github.com/alexreinert/piVCCU piVCCU] und [https://github.com/jens-maus/RaspberryMatic RaspberryMatic].</ref>, jeweils zusammen mit den [[HMCCU|HomeMatic-HMCCU-Modulen]] in FHEM integrierbar und '''''nicht'' unmittelbar als [[HomeMatic|Homematic-Geräte]] ansprechbar'''.

Zur Einbindung von Geräten, die HM-IP verwenden, ist derzeit (Stand Januar 2019) noch zwingend eine (ggf. virtualisierte) CCU2 oder neuer erforderlich.

;Weitere Quellen:
* [http://www.eq-3.de/Downloads/eq3/download%20bereich/handbuecher/Homematic_IP-Anwenderhandbuch.pdf Anwenderhandbuch Homematic IP] bei EQ3

[[Kategorie:HomeMatic Components]]
[[Kategorie:Glossary]]
[[Kategorie:868MHz]]

TRÅDFRI

2020-01-12T14:58:18Z

Moontear: /* Links */

<div style="float:right">{{Infobox Modul
|Name=tradfri
|ModPurpose=Anbindung IKEA TRÅDFRI Gateway
|ModType=d

|ModCmdRef=tradfri
|ModForumArea=Zigbee
|ModTechName=30_tradfri.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

'''TRÅDFRI''' bzw. '''IKEA Home smart''' ist die Serie smarter Beleuchtungslösungen von IKEA auf ZigBee-Basis, ähnlich Phillips Hue.

== tradfri ==

TRÅDFRI (nach Umbennung jetzt '''IKEA Home smart''') ist die Serie smarter Beleuchtungslösungen von IKEA. Ähnlich wie von Phillips [[Hue]] gibt es diverse LEDs in Glühbirnenform, LED-Streifen-Treiber, Flächenleuchten, Wandtaster, Bewegungsmelder, Fernbedienung, Dimmer, etc. und alles via Funk gekoppelt. Außerdem ein Gateway, das sich via Ethernetstecker ins heimische LAN einbinden lässt und die Bedienung via IKEA-App auf dem Handy ermöglicht.
{{Hinweis|Da die Geräte über den [[ZigBee]]-Standard kommunizieren, können auch andere Gateways für diese Leuchtmittel (und andere Geräte wie Rollos) genutzt werden. Dieser Artikel behandelt ausschließlich die Verwendung zusammen mit einem IKEA-Gateway!}}
Mit dem IKEA-Gateway ist auch eine Anbindung in FHEM möglich, dazu funktionieren zwei '''alternative''' Lösungen:

=== alt: IKEA Trådfri Modul ===
IKEA Trådfri Modul (TYPE ''TradfriDevice'' und ''TradfriGateway'', mehr Infos: https://forum.fhem.de/index.php/topic,70653.0.html seit April 2017)
* Erkennt Lampen
* Fernbedienung erscheint zwar in der Geräteliste, lässt sich aber nicht als Gerät anlegen oder Status lesen

Die Weiterentwicklung des Moduls durch den ursprünglichen Entwickler scheint Stand 07.19 eingestellt. Inwieweit andere am Modul weiter arbeiten ist unklar.

=== neu: tradfri-fhem Modul ===
tradfri-fhem Modul (TYPE ''HUEDevice'' und ''tradfri'' Gateway, mehr Infos: https://forum.fhem.de/index.php/topic,96125.0.html seit Januar 2019, Beschreibung folgt auf dieser Seite)
* Unterstützt Lampen (als [[Hue#HUE-Device|HUE-Device]])
* Unterstützt Rollos (Fyrtur und Kadrilj)
* Erkennt Fernbedienung, jedoch zur Zeit Batteriestatus als einziges Reading
* Erstellt (wenn gewünscht) automatisch Gruppen
* Erkennt Bewegungsmelder, jedoch zur Zeit Batteriestatus als einziges Reading
* Erkennt Repeater, nur Erreichbarkeit (reachable) als Reading

====Einrichtung in FHEM====

# node installieren (mindestens version 8)
# sudo npm install -g tradfri-fhem
# <code>define <tradfri> tradfri</code>
# <code>attr <tradfri> tradfriFHEM-securityCode <security code></code>

wenn das gateway nicht automatisch erkannt wird:
<code>attr <tradfri> tradfriFHEM-params --ip <ip></code>

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

==== HUE-Device ====
Alle auf dem Gateway bekannten Geräte automatisch als [[Hue#HUE-Device|HUEDevice]] in FHEM angelegt:
* Lampen, Stecker, Trafos, ...
: Hiermit werden die einzelnen Leuchten gesteuert
* Gruppen
: Hiermit lassen sich ganze Gruppen und Räume steuern
* Fernbedienungen
: aktuell gibt es nur ein Battery-Reading

==== Darstellung im Webfrontend ====
Wenn man die SVG Icons verwendet ist es sinnvoll, das Attribut color-icons zu setzen. Mit <code>attr HUEDevice1 color-icons 2</code> werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt.
Damit das ganze funktioniert, müsst ihr auch noch das <code>attr WEB iconPath fhemSVG:openautomation:default</code> setzen.

== Links ==
* [https://github.com/peterkappelt/Tradfri-FHEM/issues/16#issuecomment-445461242 Githubeintrag über Einstellung der Feature-Entwicklung des IKEA Trådfri Moduls].
* [https://wiki.fhem.de/wiki/Hue#RaspBee_.26_ConBee Betrieb von IKEA smart home Devices mit Dritthersteller Gateway wie ConBee2]
[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

Hue

2020-01-11T11:01:00Z

Moontear: /* Installation von deCONZ auf einem RaspberryPI */

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Zigbee
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Zigbee
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==
=== Einrichtung in FHEM ===
Die Einrichtung ist wirklich einfach. Mit
:<code>define Wiesollesheißen HUEBridge eu.re.ip.1</code>
wird die Bridge eingebunden. Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das pairing erneut durchzuführen, muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man
:<code>attr <HUEBridge_Name> httpUtils 1</code>
setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden, die sich an der Bridge anlernen lassen. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint
*...

Diese sind jeweils über eine Bridge (HueBridge) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren (Taster, Bewegungsmelder) unterstützt. Diese werden aber nicht per [[autocreate]] angelegt, sondern müssen manuell definiert werden. Hier ist auf ein passendes Polling-Intervall zu achten (siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]).

Sensoren (und Aktoren) lassen sich Konfigurieren (parameter Einstellen) und eigene Set- und Get- Kommandos im definieren.

=== Mögliche andere Gateways ===
HUEDevice Client-Devices können (mit leicht unterschiedlichem Funktionsumfang) auch mit den folgenden Gateways anderer Hersteller und dem zugehörigen Bridge-Device verwendet werden:
*[[Hue#RaspBee_.26_ConBee|RaspBee & ConBee mit deCONZ]] von Dresden Elektronik
** inklusive Push-API Erweiterung und Szenen
*[[TRÅDFRI| TRÅDFRI bzw. IKEA Home smart]]
** inklusive Rollos
*[https://github.com/bwssytems/ha-bridge HA-Bridge]
** inklusive aller [https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices unterstützten Geräte] (Lampen, Sensoren, Thermostate, Rollos, ...)
** inklusive Update des HA-Bridge internen Gerätestatus per <code>habridgeupdate</code> Kommando
*[[ZigBee#Lightify_von_Osram|OSRAM LIGHTIFY Gateway]]

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .

Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

'''HA-Bridge:''' In der HA-Bridge können virtuelle Devices definiert werden, welche in FHEM als ''Dimmable light'' eingebunden und verwendet werden können.

Zusätzlich zu den bereits beschriebenen set-Befehlen kann der Zustand der HA-Bridge-Devices mit Hilfe von ''habridgeupdate'' in Kombination mit ''on'', ''off'', ''pct'' und ''bri'' aktualisiert werden, ohne dass die HA-Bridge einen Schaltbefehl versendet. Beispiel: <code>set bulb1 habridgeupdate : on : pct 50</code> Details siehe: [https://github.com/bwssytems/ha-bridge#update-bridge-internal-light-state].

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet, ist es sinnvoll, das Attribut color-icons zu setzen. Mit
:<code>attr HUEDevice1 color-icons 2</code>
werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt. Damit das ganze funktioniert, muss noch
:<code>attr WEB iconPath fhemSVG:openautomation:default</code>
gesetzt werden.

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet, sollten aber auch funktionieren.

Im diesem {{Link2Forum|Topic=80985|LinkText=Forenbeitrag}} wird über Details der HUE Module diskutiert, die das deCONZ PushAPI über Websockets unterstützen (die entsprechenden Modulversionen sind mittlerweile regulär verfügbar). Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in diesem {{Link2Forum|Topic=95288|LinkText=Forenbeitrag}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

=== Installation von deCONZ unter Proxmox auf einem Intel Nuc ===
Folgende Schritte sind notwendig, um unter Proxmox zu installieren:

* Installation einer Ubuntu oder Debian VM:
:<source lang="bash">
cd /var/lib/vz/template/iso/
wget http://releases.ubuntu.com/18.04/ubuntu-18.04.2-desktop-amd64.iso
</source>
:oder
:<source lang="bash">
cd /var/lib/vz/template/iso/
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-9.8.0-amd64-xfce-CD-1.iso
</source>

* Weiterreichen des USB Devices in die VM:
: Auflistung der verfügbaren USB Geräte:
:<source lang="bash">
root@node1:~# lsusb
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
</source>
:Der Conbee meldet sich als "Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)", hier ist die ID wichtig (0403:6015).
:Anschließend kann das USB Gerät an die VM weitergeleitet werden. Der Wert 804 ist durch die ID der VM zu ersetzen.
:<source lang="bash">
qm set 804 -usb0 host=0403:6015
</source>

* Installation von deCONZ:
:<source lang="bash">
apt-get update && apt-get upgrade -y
wget http://www.dresden-elektronik.de/deconz/ubuntu/beta/deconz-2.05.60-qt5.deb
sudo dpkg -i deconz-2.05.60-qt5.deb
sudo apt install -f
sudo systemctl enable deconz
reboot now
</source>

=== Installation von deCONZ unter Docker ===
https://hub.docker.com/r/marthoc/deconz/

=== Installation von deCONZ auf einem RaspberryPI ===
Für den ConBee2 [https://phoscon.de/en/conbee2/install#raspbian kann der guten Installation von Phoscon gefolgt werden]. Entweder ihr installiert deCONZ direkt (wie hier beschrieben) oder über einen Docker Container. Der Docker Container hat ein paar Einschränkungen bzgl. Firmware Updates.

Der ausführende Benutzer muss dialout Rechte haben um auf /dev/tty* zugreifen zu dürfen:
:<source lang="bash">
sudo gpasswd -a pi dialout
</source>
Im Standard wird deCONZ mit dem pi-Benutzer (user id 1000) ausgeführt.

Das deCONZ Repository bei APT hinzufügen (Vorteil davon ist dass später ganz normal mit sudo apt update/upgrade deCONZ aktualisieren könnt):
:<source lang="bash">
wget -O - http://phoscon.de/apt/deconz.pub.key | \
sudo apt-key add -;
sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
$(lsb_release -cs) main' > \
/etc/apt/sources.list.d/deconz.list";
sudo apt update
</source>

deCONZ installieren:
:<source lang="bash">
sudo apt install deconz
</source>

Wenn ihr euren RaspberryPI mit UI betreibt, kann deCONZ über ''Menu > Programming > deCONZ'' aufgerufen werden. Es gibt aber auch den Service-Modus, der ohne X11 funktionert. Hierfür die Datei ''/lib/systemd/system/deconz.service'' anpassen (ich habe z.B. den Port des Webservers geändert) und den Service wie folgt aktivieren:
:<source lang="bash">
systemctl enable deconz.service
</source>

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom <b>lib-Verzeichnis</b> nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=in diesem Forenbeitrag}}.

[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

Hue

2020-01-11T10:59:55Z

Moontear: Installation von deCONZ auf RaspberryPI ergänzt

<div style="float:right">{{Infobox Modul
|Name=HUEBridge
|ModPurpose=Anbindung Bridge des Philips Hue Lighting System
|ModType=d

|ModCmdRef=HUEBridge
|ModForumArea=Zigbee
|ModTechName=30_HUEBridge.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
{{Infobox Modul
|Name=HUEDevice
|ModPurpose=Ansteuerung Geräte des Philips Hue Lighting System über HUEBridge
|ModType=d

|ModCmdRef=HUEDevice
|ModForumArea=Zigbee
|ModTechName=31_HUEDevice.pm
|ModOwner=Andre ([http://forum.fhem.de/index.php?action=profile;u=430 Forum] / [[Benutzer Diskussion:justme|Wiki]])
}}
</div>

== HUE-Bridge ==
=== Einrichtung in FHEM ===
Die Einrichtung ist wirklich einfach. Mit
:<code>define Wiesollesheißen HUEBridge eu.re.ip.1</code>
wird die Bridge eingebunden. Dann einfach auf den runden Knopf in der Mitte der Bridge drücken und sie wird von FHEM erkannt. Die drei Lampen des Starterkits werden automatisch erkannt und sind ansteuerbar -> fertig!

WICHTIG: danach in FHEM einmal die Konfiguration speichern damit der Pairing-Key gesichert wird. Sonst muss beim nächsten FHEM-Neustart das Pairing erneut durchgeführt werden.

Falls die Hue Bridge resetet wurde bleibt der Status auf "paired" und geht nicht mehr auf connected. Um das pairing erneut durchzuführen, muss das Attribut "key" gelöscht werden.

=== Nonblocking ===
Wenn man möchte, dass die Versuche, die HUEBridge zu kontaktieren, FHEM nicht blockieren, sollte man
:<code>attr <HUEBridge_Name> httpUtils 1</code>
setzen.

== HUE-Device ==
Als Gerät können alle Hue und LightLink kompatiblen Modelle verwendet werden, die sich an der Bridge anlernen lassen. Dies sind unter anderem:
*HueBulbs (E27, GU10, Lux, White, ...)
*Hue Beyond und Phoenix
*Friends of Hue LightStrips und LivingColors Bloom
*LivingColors ab gen2
*LivingColors Bloom, Iris und Aura
*LivingWhites Energiesparlampen
*LivingWhites Leuchtenadapter
*LivingWhites Bulbs
*[[HUE_Dimmer_Switch|Hue Tap und Hue Dimmer]] (mit Einschränkungen)
*dresden elektronik Vorschaltgeräte
*OSRAM LIGHTIFY Lampen (an der Hue Bridge angelernt)
*Müller Licht tint
*...

Diese sind jeweils über eine Bridge (HueBridge) steuerbar. Die LivingColors und LivingWhites Geräte sind vorher mit Hilfe einer LivingColors oder LivingWhites Fernbedienung an der Bridge anzulernen.

Es werden auch alle HUE Sensoren (Taster, Bewegungsmelder) unterstützt. Diese werden aber nicht per [[autocreate]] angelegt, sondern müssen manuell definiert werden. Hier ist auf ein passendes Polling-Intervall zu achten (siehe: [[HUE_Dimmer_Switch|HUE Dimmer Switch]]).

Sensoren (und Aktoren) lassen sich Konfigurieren (parameter Einstellen) und eigene Set- und Get- Kommandos im definieren.

=== Mögliche andere Gateways ===
HUEDevice Client-Devices können (mit leicht unterschiedlichem Funktionsumfang) auch mit den folgenden Gateways anderer Hersteller und dem zugehörigen Bridge-Device verwendet werden:
*[[Hue#RaspBee_.26_ConBee|RaspBee & ConBee mit deCONZ]] von Dresden Elektronik
** inklusive Push-API Erweiterung und Szenen
*[[TRÅDFRI| TRÅDFRI bzw. IKEA Home smart]]
** inklusive Rollos
*[https://github.com/bwssytems/ha-bridge HA-Bridge]
** inklusive aller [https://github.com/dresden-elektronik/deconz-rest-plugin/wiki/Supported-Devices unterstützten Geräte] (Lampen, Sensoren, Thermostate, Rollos, ...)
** inklusive Update des HA-Bridge internen Gerätestatus per <code>habridgeupdate</code> Kommando
*[[ZigBee#Lightify_von_Osram|OSRAM LIGHTIFY Gateway]]

=== Grundlagen - Farbmodelle ===
Ein HueDevice kann per set-Befehl über unterschiedliche Farbmodelle gesteuert werden. In der folgenden Tabelle ist dargestellt, welche Werte-Kombinationen sinnvoll sind:
{| class="wikitable"
|-
! Farbmodell !! Bestandteile !! Beispiel
|-
| xyY || x- und y-Koordinate im Farbraum, Y ist die Helligkeit || <code> set bulb1 xy 0.4595,0.4105 : bri 220 </code>
|-
| hue,sat,bri || Farbwert, Sättigung und Helligkeit || <code> set bulb1 hue 14922 : sat 144 : bri 220 </code>
|-
| ct || Farbwert über Farbtemperatur || <code> set bulb1 color 2600 </code>
|-
| rgb || Farbbestandteile rot, grün und blau || <code> set bulb1 rgb FFC698 </code>
|}
'''Hinweis:''' Zur Regelung der Helligkeit sind die Befehle ''bri'' und ''pct'' gleichwertig. ''bri'' hat den Bereich 0..254, ''pct'' 0..100 .

Das Modul lässt die Mischung von Angaben aus unterschiedlichen Farbmodellen technisch zu, jedoch sind diese nicht immer sinnvoll.

'''HA-Bridge:''' In der HA-Bridge können virtuelle Devices definiert werden, welche in FHEM als ''Dimmable light'' eingebunden und verwendet werden können.

Zusätzlich zu den bereits beschriebenen set-Befehlen kann der Zustand der HA-Bridge-Devices mit Hilfe von ''habridgeupdate'' in Kombination mit ''on'', ''off'', ''pct'' und ''bri'' aktualisiert werden, ohne dass die HA-Bridge einen Schaltbefehl versendet. Beispiel: <code>set bulb1 habridgeupdate : on : pct 50</code> Details siehe: [https://github.com/bwssytems/ha-bridge#update-bridge-internal-light-state].

=== Darstellung im Webfrontend ===
Wenn man die SVG Icons verwendet, ist es sinnvoll, das Attribut color-icons zu setzen. Mit
:<code>attr HUEDevice1 color-icons 2</code>
werden z.B. die Farben und der Dimmzustand der Lampe als Icon dargestellt. Damit das ganze funktioniert, muss noch
:<code>attr WEB iconPath fhemSVG:openautomation:default</code>
gesetzt werden.

== RaspBee & ConBee ==
Das HUEBridge Modul unterstützt auch die ZigBee Gateway Module RaspBee und ConBee von Dresden Elektronik über die zugehörige deCONZ Software und die Wireless Light Control WebApp und die Phoscon WebApp (kommt zusammen mit deConz). Die hierzu erhältlichen Funk-Vorschaltgeräte sind noch nicht getestet, sollten aber auch funktionieren.

Im diesem {{Link2Forum|Topic=80985|LinkText=Forenbeitrag}} wird über Details der HUE Module diskutiert, die das deCONZ PushAPI über Websockets unterstützen (die entsprechenden Modulversionen sind mittlerweile regulär verfügbar). Sensoren müssen hier nicht mehr gepollt werden.

Mittlerweile funktioniert die Einbindung der RaspBee und ConBee Module auf einem sehr einfachen Weg. Dieser ist in diesem {{Link2Forum|Topic=95288|LinkText=Forenbeitrag}} zusammengefasst. Zusätzliche Plugins sind nicht mehr nötig.

=== Installation von deCONZ unter Proxmox auf einem Intel Nuc ===
Folgende Schritte sind notwendig, um unter Proxmox zu installieren:

* Installation einer Ubuntu oder Debian VM:
:<source lang="bash">
cd /var/lib/vz/template/iso/
wget http://releases.ubuntu.com/18.04/ubuntu-18.04.2-desktop-amd64.iso
</source>
:oder
:<source lang="bash">
cd /var/lib/vz/template/iso/
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-9.8.0-amd64-xfce-CD-1.iso
</source>

* Weiterreichen des USB Devices in die VM:
: Auflistung der verfügbaren USB Geräte:
:<source lang="bash">
root@node1:~# lsusb
Bus 002 Device 004: ID 0403:6015 Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
</source>
:Der Conbee meldet sich als "Future Technology Devices International, Ltd Bridge(I2C/SPI/UART/FIFO)", hier ist die ID wichtig (0403:6015).
:Anschließend kann das USB Gerät an die VM weitergeleitet werden. Der Wert 804 ist durch die ID der VM zu ersetzen.
:<source lang="bash">
qm set 804 -usb0 host=0403:6015
</source>

* Installation von deCONZ:
:<source lang="bash">
apt-get update && apt-get upgrade -y
wget http://www.dresden-elektronik.de/deconz/ubuntu/beta/deconz-2.05.60-qt5.deb
sudo dpkg -i deconz-2.05.60-qt5.deb
sudo apt install -f
sudo systemctl enable deconz
reboot now
</source>

=== Installation von deCONZ unter Docker ===
https://hub.docker.com/r/marthoc/deconz/

=== Installation von deCONZ auf einem RaspberryPI ===
Für den ConBee2 [https://phoscon.de/en/conbee2/install#raspbian kann der guten Installation von Phoscon gefolgt werden]. Hier einmal kopiert:

Der ausführende Benutzer muss dialout Rechte haben um auf /dev/tty* zugreifen zu dürfen:
:<source lang="bash">
sudo gpasswd -a pi dialout
</source>
Im Standard wird deCONZ mit dem pi-Benutzer (user id 1000) ausgeführt.

Das deCONZ Repository bei APT hinzufügen (Vorteil davon ist dass später ganz normal mit sudo apt update/upgrade deCONZ aktualisieren könnt):
:<source lang="bash">
wget -O - http://phoscon.de/apt/deconz.pub.key | \
sudo apt-key add -;
sudo sh -c "echo 'deb http://phoscon.de/apt/deconz \
$(lsb_release -cs) main' > \
/etc/apt/sources.list.d/deconz.list";
sudo apt update
</source>

deCONZ installieren:
:<source lang="bash">
sudo apt install deconz
</source>

Wenn ihr euren RaspberryPI mit UI betreibt, kann deCONZ über ''Menu > Programming > deCONZ'' aufgerufen werden. Es gibt aber auch den Service-Modus, der ohne X11 funktionert. Hierfür die Datei ''/lib/systemd/system/deconz.service'' anpassen (ich habe z.B. den Port des Webservers geändert) und den Service wie folgt aktivieren:
:<source lang="bash">
systemctl enable deconz.service
</source>

== HUE auf der Fritzbox ==
Da auf der FB standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden: Man lädt das JSON-Paket http://search.cpan.org/CPAN/authors/id/M/MA/MAKAMAKA/JSON-2.53.tar.gz, packt es aus und kopiert den Inhalt vom <b>lib-Verzeichnis</b> nach \fhem\lib\perl5\site_perl\5.12.2

== HUE auf der Synology Diskstation ==
Da auf der DS standardmäßig kein JSON installiert ist, muss dies nachinstalliert werden, die Anleitung dazu {{Link2Forum|Topic=19093|Message=224641|LinkText=in diesem Forenbeitrag}}.

[[Kategorie:ZigBee]]
[[Kategorie:Lichteffektgeräte]]
[[Kategorie:IP Components]]

SONOS

2019-10-14T11:21:22Z

Moontear: Ganzer Artikel kaputt durch fehlende Klammern. Korrigiert.

<div style="float:right">{{Infobox Modul
|ModPurpose=Anbindung des Sonos-Systems via UPnP
|ModType=d

|ModCmdRef=
|ModForumArea=Multimedia
|ModTechName=00_SONOS.pm
|ModOwner=Reinerlein
}}
{{Infobox Modul
|Name=SONOSPLAYER
|ModPurpose=Steuerung eines Sonos Zoneplayer
|ModType=d

|ModCmdRef=SONOSPLAYER
|ModForumArea=Multimedia
|ModTechName=21_SONOSPLAYER.pm
|ModOwner=Reinerlein
}}
</div>

Sonos ist ein Multiroom-Musiksystem der kalifornischen Firma [http://www.sonos.com Sonos].
Es bietet die Möglichkeit der verteilten Musikabspielung und Steuerung, sowie der Verknüpfung von mehreren Playern, um diese dasselbe abspielen zu lassen. Hierfür gibt es verschiedene Abspiel-Komponenten, die in einem eigenen Netzwerk miteinander kommunizieren und für verschiedene Anwendungsfälle konzipiert wurden.

Diese Beschreibung soll den Einstieg in die Steuerung der heimischen Zoneplayer erleichtern. Es werden die Verwendung und Einrichtung der dazugehörenden FHEM-Module '''SONOS''' und '''SONOSPLAYER''' beschrieben, und einige Beispiele für eine mehr oder weniger sinnvolle Nutzung von Events und Steuerungsmöglichkeiten gegeben.

Sollte etwas fehlen oder unklar sein, dann einfach eine kurze Nachricht an den Autor.

<div style="margin: 0; margin-top:10px; margin-right: 315px; border: 1px solid #dfdfdf; padding: 0 1em 0.3em 1em; background-color:#fff0e0;">
<center>'''! Achtung !'''</center>
Obwohl die Module in FHEM mitgeliefert werden, sind trotzdem die Vorbedingungen bzgl. der Perl-Installation unter [[#Softwarevoraussetzungen|Softwarevoraussetzungen]] einzuhalten, da das Modul sonst nicht lauffähig ist.
</div>

== Kurzüberblick ==
Hier soll nur ein kurzer Überblick über die mittlerweile doch recht umfangreichen Möglichkeiten geboten werden:
*Automatisches Erkennen aller ZonePlayer im lokalen Netzwerk. Dabei werden alle Player einer Paarung zusammengehörig benannt und gruppiert
*Automatische Aktualisierung aller aktuellen (und wenn verfügbar: der nächsten) Titelinformationen innerhalb von FHEM
**Dabei wird für jede veränderte Information ein Event erzeugt, man kann also dediziert darauf reagieren
**Bei normalen Abspiellisten werden auch die Informationen zum nächsten Titel ermittelt und angezeigt
**Es können auch verschiedene Zusammenfassungen der bestehenden Informationen zusammengestellt werden
*Anzeige des aktuellen (oder auch nächsten) Covers als Weblink oder [[readingsGroup]]
*Steuern der ZonePlayer: Play, Pause, Nächster Titel, Vorheriger Titel, Lautstärke Lauter/Leiser (auch als vordefinierte Rampe), Stummschalten
*Alle Player auf einen Befehl hin stoppen, pausieren oder stummschalten lassen
*Einstellen und Abfragen der Abspielparameter Repeat, RepeatOne, Shuffle, CrossfadeMode, Loudness, Bass und Treble
*Festlegen einer minimalen und maximalen Lautstärke für jeden ZonePlayer (getrennt zwischen Normalbetrieb und Kopfhörernutzung)
*Laden, Speichern und Löschen von Playlisten (Laden und Speichern: auch M3U-Dateien aus dem Filesystem)
*Abspielen eines Sonos-Favoriten (z.B. Playlist, Spotify-Playlist, Titel, Radiosender, usw.)
*Abspielen beliebiger Titel (auch von Freigaben, die nicht von Sonos indiziert wurden)
*Abspielen beliebiger Radiostationen über deren HTTP-Link
*Hinzufügen beliebiger Titel und Radiostationen zur aktuellen Abspielliste
*Temporäres Abspielen von Dateien, mit nachfolgender Wiederherstellung des vorherigen Titels inkl. genauer Position im vorherigen Titel und der Lautstärke
*Füllen der aktuellen Abspielliste mit nach diversen Kriterien zusammengesuchten Titeln aus der Sonos Bibliothek
*Erzeugen und temporäres Abspielen von Sprachdurchsagen auf Basis von eingegebenen Texten und vorhandenen MP3-Dateien
**Wird standardmäßig über die Google-Übersetzungsmaschine realisiert
**Kann auch über eine eigenständige, lokale Installation eines Text2Speech-Tools realisiert werden
*Auslesen und Setzen/Starten der verfügbaren gespeicherten Playlisten, Radiofavoriten und Sonos-Favoriten
*Erzeugung und Bearbeitung von Alarmen, sowie Event bei Veränderung der Alarme duch andere Controller
*Setzen des Sleeptimer inkl. FHEM-Event bei Veränderung durch andere Controller und Ablauf des Timers
*Setzen und Auslesen der Gruppierungskonfiguration, sowie einzelnes Hinzufügen und Entfernen von Gruppenmitgliedern
*Bildung und Trennung von Stereopaaren
*Erzeugen von Events nach festgelegten Tastensequenzen (am Player)
*Umbenennen der Zonen und festlegen der Zonenicons
*Standardanzeige eines Player als ReadingsGroup mit automatischem Titel- und Coverwechsel sowie einer RemoteControl zum Steuern
*Anzeigemöglichkeit einer Vollbilddarstellung ähnlich dem Original-Controller
*Definitionsmöglichkeit von automatischen Bookmarks, die beim Aufrufen derselben Playliste oder Titel die gespeicherte Position anspringen.

== Kurze Anmerkungen zur Sonos-Landschaftsgestaltung ==
Es ist im allgemeinen besser, die Sonos-Landschaft mit allen Paarungen vor dem Einrichten des Moduls zu erzeugen.
Dieses Modul benennt die FHEM-Playerdevices nach den Zonennamen und der jeweiligen Funktion des Players innerhalb der Paarung.

Das bedeutet aber auch, dass in diesem Augenblick möglichst keine Player gruppiert sein sollten (mehrere Zonen spielen dasselbe ab), da diese sonst komische Namen erhalten könnten (es geht hier ausschliesslich um die FHEM-interne Device-Benennung, natürlich bleiben die Zoneplayer selbst wie sie sind).<br />Insbesondere gilt das für temporäre Stereopaare. Diese nicht ständigen Paare sollten erst getrennt werden, bis das Modul alle Player erkannt und angelegt hat.

Damit man nun eine einigermaßen passende Bezeichnung in FHEM erhält, sollte also die Gestaltung der Sonos-Player abgeschlossen sein. Natürlich funktioniert das System nach einer FHEM-Einrichtung und anschließender Sonos-Umbenennung immer noch, da intern alles mittels der eindeutigen Bezeichner gehandhabt wird, allerdings wird es u.U. etwas unübersichtlich bzgl. der FHEM-Device-Namen. Diese passen dann nicht mehr zu den Zonennamen (die entsprechenden Readings werden aber natürlich korrekt besetzt), was man aber natürlich auch nachträglich wieder anpassen kann.

'''Hinweis:''' Man kann das Attribut ''disable'' am Sonos-Device setzen, um den Subprozess zu beenden. Damit kann man seine Zonenlandschaft später erweitern, ohne FHEM komplett abschalten zu müssen.
Nachdem die Einrichtung des neuen Zoneplayers abgeschlossen ist, löscht man das Attribut ''disable'' einfach wieder - der Subprozess startet und beginnt mit der Erkennung der neuen Komponenten.

== Einbindung von Sonos in FHEM ==
Die Einbindung erfolgt über die beiden Module '''SONOS''' und '''SONOSPLAYER'''. Dabei ist Hauptsächlich das Modul '''SONOS''' einzurichten. Alle Zoneplayer werden automatisch erkannt, und dann entsprechend angelegt:

<pre>define <Devicename> SONOS [<Hostname:Port> [Prüfintervall [WaitTime [DelayTime]]]]</pre>

=== Beispiele für die Einbindung ===
Einfachste Einbindung mit Standardwerten:
<pre>define Sonos SONOS</pre>

Einbindung mit Kontrolle über den verwendeten Port und das IsAlive Prüfintervall:
<pre>define Sonos SONOS localhost:4711 45</pre>

Der Name dieses Devices ist automatisch das Namensprefix beim Anlegen der SonosPlayer. In diesem Fall werden alle erkannten Zoneplayer mit dem Prefix "<code>Sonos_</code>" anfangen. Natürlich kann man das nach dem Anlegen einfach umbenennen.<br />Als Prüfintervall wurde hier 45s angegeben. Wenn kein Intervall angegeben wird, dann werden 30s verwendet.

<pre>define Sonos SONOS localhost:4711 30 1</pre>

Hier wurde eine verkürzte Wartezeit für den Subprozess von einer Sekunde angegeben. Bei schnellen Systemen wird dadurch der gesamte Startmechanismus schneller verarbeitet.<br />Wenn nichts angegeben wird, dann wird 8s verwendet, was einen guten Wert für einen Raspberry Pi darstellt.

<pre>define Sonos SONOS localhost:4711 30 1 5</pre>

Hier wurde noch eine zusätzliche Verzögerung von 5s eingebaut, da manche Systeme bei einem FHEM-Restart oder ähnlichem die belegten Ports nicht schnell genug wieder freigeben.<br />Hier kann diese Verzögerung helfen, da erst nach Ablauf dieser Zeitspanne ein Verbindungsversuch zum SubProzess unternommen wird (und auch erst dann der Versuch einen eigenen Prozess zu Starten unternommen wird).<br />Wenn nichts angegeben wird, dann wird keine Verzögerung durchgeführt.

=== Namensvergabe der automatischen Erkennung ===
Der automatische Erkennungsmechanismus vergibt Devicenamen auf Basis der Zonennamen und der Funktion eines Players innerhalb eines Stereopaares oder einer Surroundkonstellation.
Dabei wird immer ein Player (der Master dieser Konstellationen) nur den Namen der Zone erhalten (ohne Anhängekürzel) und die anderen werden mit Kürzel versehen. Dadurch ist der Master der Zone automatisch dasjenige Playerdevice, welches gesteuert werden muss. Alle anderen Player leiten Steueranfragen automatisch an den Master weiter.
Besteht eine Zone nur aus einem Player, so gibt es natürlich auch nur diesen einen als Master.

Als Anhängekürzel wird immer der Inhalt des Readings '''fieldType''' verwendet.

Bei der Funktion gibt es später dann zwei Fälle zu unterscheiden:
*Stereopaare werden von Sonos intern als Gruppe behandelt. Das bedeutet, dass der zweite Player (der nicht-Master) immer ''PLAYING'' als Status anzeigt, und nur der Master den korrekten Wert. Stereopaare haben, wie normale Gruppen oder Einzelplayer auch, eine Verzögerung von 70ms zu einem Eingangssignal.
*Surroundsysteme werden als Satelliten angebunden, und werden vom Modul nur mit ''intialized'' angegeben, da Sonos für diese nie eine Statusmeldung sendet. Diese Playersysteme haben eine verkürzte Verzögerung von 30ms zu einem Eingangssignal.

Dabei ist ein Eingangsignal so etwas wie ein Line-In- oder SPDIF-Eingang.

==== Beispiel für eine Zonenlandschaft ====
Folgende Landschaft mit Status könnte es geben:
<pre>
Sonos_Schlafzimmer (STOPPED => [Keine Musikdatei])
Sonos_Schlafzimmer_RF (PLAYING => 'Keine Titelinformation bei Gruppenwiedergabe')
Sonos_Kinderzimmer (PAUSED_PLAYBACK => 'Titelinformation')
Sonos_Gaestezimmer (STOPPED => [Keine Musikdatei])
Sonos_Wohnzimmer (STOPPED => [Keine Musikdatei])
Sonos_Wohnzimmer_LR (initialized)
Sonos_Wohnzimmer_RR (initialized)
Sonos_Wohnzimmer_SW (initialized)
</pre>
Dabei wäre Schlafzimmer ein Stereopaar, Kinder- und Gästezimmer jeweils ein einzelner Player und Wohnzimmer z.B. eine Playbar mit zwei Rear-Lautsprechern und Subwoofer. In keiner Zone läuft eine aktive Wiedergabe.
Hier kann man schön die einzelnen Zustände und die erzeugten Namen erkennen.

=== Zusammenfassung der Spracheinrichtung ===
Um die Sprachausgabe des Moduls nutzen zu können, müssen einige Grundvoraussetzungen geschaffen werden.
Hier soll nur eine kurze Übersicht geschaffen werden, was alles getan werden muss. Die einzelnen Themen selbst sind in diesem Wiki-Artikel bereits beschrieben.
*Es muss einen Speicherplatz für Dateien geben, wo das Sonos-Modul (also FHEM) schreibend zugreifen kann, und das Sonos-System selbst lesend zugreifen kann. Das Sonos-System versucht immer ohne Passwort zuzugreifen, FHEM mit seinem Benutzerkontext
**Dafür kann man sich z.B. auf dem lokalen Debian-System (sofern FHEM darauf läuft) eine Samba-Freigabe einrichten. Das ist unter "[[#Einrichtung von Samba für Sprachausgabemöglichkeit|Einrichtung von Samba für Sprachausgabemöglichkeit]]" beschrieben.
**Man kann sich auch auf einem bestehenden NAS-System einen Ordner extra für diesen Zweck anlegen und entsprechend freigeben
**Bei Problemen bitte die Datei-/Ordnerrechte genauestens prüfen, notfalls mit einem Windows-/Macrechner einen direkten Zugriffstest durchführen. Hier sind die häufigsten Fehlerquellen zu suchen.
*Es müssen mindestens die Attribute '''targetSpeakDir''' und '''targetSpeakURL''' am FHEM-Sonos-Device gesetzt werden. Diese Attribute werden bei den "[[#Sprachattribute|Sonos Sprachattributen]]" beschrieben.
*Empfehlenswert ist auch das Setzen eines der Attribute '''targetSpeakFileTimestamp''' oder '''targetSpeakFileHashCache''' am FHEM-Sonos-Device. Damit werden Indizierungsprobleme des Sonos-Systems umgangen. Es ist nicht sinnvoll beide Attribute gleichzeitig zu setzen. Auch diese Attribute werden bei den "[[#Sprachattribute|Sonos Sprachattributen]]" beschrieben.
*Wenn man die Möglichkeit der in den Text eingebetteten MP3-Dateien nutzen möchte, ist es empfehlenswert, das Attribut '''targetSpeakMP3FileDir''' für den Standardpfad der Jingles zu setzen. Damit werden die einzugebenden Texte deutlich übersichtlicher.
*Bei Bedarf kann man sich ein lokales Programm installieren und dem Modul angeben, welches die Sprachausgabedatei erzeugt.<br />Das sollte man nicht als Anfänger tun!
**Unter [[#Beispiel für einen Offline-Sprachsynthetisierer|Beispiel für einen Offline-Sprachsynthetisierer]] ist das am Beispiel von ''espeak'' beschrieben.
**Das Programm kann man dem Modul mit den Attributen ''Speak1'', ''Speak2'', ''Speak3'' und ''Speak4'' einstellen. Also bis zu vier verschiedene. Diese Attribute werden ebenfalls bei den "[[#Sprachattribute|Sonos Sprachattributen]]" beschrieben.
*Mit einem Shell-Skript kann man den Cacheordner für die Sprachausgabe bereinigen lassen. Unter [[#Beispiel für ein Shell-Skript zum Aufräumen eines Speak-Verzeichnisses|Beispiel für ein Shell-Skript zum Aufräumen eines Speak-Verzeichnisses]] gibt es den Code.

=== Zusammenfassung der Bookmarkeinrichtung ===
Da die Möglichkeiten mit den Bookmarks sehr vielfältig sind, soll in dieser kleinen Zusammenfassung ein Überblick gegeben werden.

Grundsätzlich muss zwischen den beiden Grundbereichen für Bookmarks unterschieden werden. Diese können unabhängig voneinander verwendet werden:
*Bookmarks für die aktuelle Abspielliste/Playlisten
*Bookmarks für Titel

Bei den Listen wird über die aktuelle Abspielliste (also alle Titel die gerade so abgespielt werden sollen) ein Hashwert gebildet, und mit diesem der aktuelle Titel (genauer: die Tracknummer) zusammen mit einem Zeitstempel gespeichert.

Bei den Titeln wird für jeden Titel die genaue Position im Titel zusammen mit einem Zeitstempel gespeichert, wenn der Titel gewechselt wird.

Beide Bereiche behandeln also getrennte Situationen und können jeder für sich, aber auch gemeinsam, sinnvoll eingesetzt werden.

Die Konfiguration der Bookmarks wird erst bei einem Neustart des SubProzesses (also durch einen FHEM-Neustart (vorher Speichern nicht vergessen) oder dem Setzen/Zurücksetzen des Attributs '''disable''' am Sonos-Device) berücksichtigt.

Mit den Befehlen ''DisableBookmark'' und ''EnableBookmark'' können Bookmark-Gruppen (temporär) deaktiviert bzw. wieder aktiviert werden.<br />'''Achtung''': Diese Änderung gilt nur bis zum nächsten FHEM Neustart, da dieser Zustand nicht in die Definition (also das Attribut) zurückgeschrieben wird.

Die im Arbeitsspeicher gehaltenen Bookmarks werden beim Starten des SubProzesses aus den vorhandenen Dateien geladen, und beim Beenden entsprechend dort gespeichert.
Man kann mit dem Befehl '''SaveBookmarks''' (oder entsprechend '''LoadBookmarks''') diesen Vorgang selber anstossen.
Bei einem globalen Save-Aufruf (also dem FHEM-Befehl ''''save'''') werden die Bookmark-Daten ebenfalls gesichert.

Die komplette Verarbeitung der Bookmarks erfolgt im SubProzess (zunächst mal ohne FHEM-Interaktion) und damit sehr nah an den Ereignissen des Players.
Im Normalfall hört man z.B. beim Sprung innerhalb eines Titel (nach einem Wechsel des Titels) gerade mal ein kurzes Zucken des Titels, bevor dieser schon ''vorgespult'' wird.
Beim Anspringen eines Titels in der aktuellen Abspielliste (wegen der Hash-Berechnung, je nach Länge der aktuellen Abspielliste) etwas länger, aber bei mir deutlich unter einer Sekunde.
FHEM ist nur insoweit involviert, da die Sprungaktionen abschließend als '''LastActionResult'''-Aktualisierungen gemeldet werden.

==== Attribute für Bookmarks am Sonos-Device ====
*<code>bookmarkSaveDir</code>: Verzeichnis, wo die Bookmarkdateien abgelegt und geladen werden sollen
*<code>bookmarkPlaylistDefinition</code>: Definition für Playlist-Bookmarks
*<code>bookmarkTitleDefinition</code>: Definition für Titel-Bookmarks

==== Readings für Bookmarks am Sonosplayer-Device ====
*<code>QueueHash</code>: Der Hash-Wert für die aktuelle Abspielliste. Damit kann man in eigenen Events bei Bedarf Dinge selber entsprechend verarbeiten.

==== Bookmarks für die aktuelle Abspielliste/Playlisten ====
Attributname am Sonos-Device:<br />
<code>bookmarkPlaylistDefinition</code>

Definition:<br />
<code><Groupname>:<PlayerDeviceRegEx>:<MinListLength>:<MaxListLength>:<MaxAge> [...]</code>

Bedeutung:
*<code>Groupname</code>: Ein beliebiger Name, der auch als Dateiname verwendet werden kann und keinerlei Sonder-/Leerzeichen enthält
*<code>PlayerDeviceRegEx</code>: Ein regulärer Ausdruck, der für das Matching der zu berücksichtigten Player verwendet wird. Das Matching erfolgt auf dem FHEM-Devicenamen. Wenn nicht angegeben, dann wird ''''.*'''' verwendet.
*<code>MinListLength</code>: Eine Zahl die angibt, wieviel Titel eine aktuelle Abspielliste mindestens haben muss, um berücksichtigt zu werden. Wenn nicht angegeben, dann wird ''''0'''' verwendet.
*<code>MaxListLength</code>: Eine Zahl die angibt, wieviel Titel eine aktuelle Abspielliste maximal haben darf, um berücksichtigt zu werden. Wenn nicht angegeben, dann wird ''''99999'''' verwendet.
*<code>MaxAge</code>: Das maximale Alter für die Verwendung eines gespeicherten Bookmarks in Sekunden. Hier kann ein beliebiger Perl-Ausdruck (natürlich ohne Doppelpunkte) verwendet werden, der zu einer Zahl evaluierbar sein muss. Wenn nicht angegeben, dann wird ''''28*24*60*60'''' (also vier Wochen) verwendet.

Nach hinten hin dürfen die Doppelpunkte von leergelassenen Werten ebenfalls weggelassen werden.

Es können beliebig viele Gruppen mit diversen (auch überlappenden) Bereichen gebildet werden. Diese verschiedenen Gruppen werden mit Leerzeichen getrennt, sodass innerhalb einer Bookmarkdefinition selbst keinerlei Leerzeichen vorkommen dürfen.

Die Dateinamen für das Speichern und Laden werden wie folgt gebildet: <bookmarkSaveDir>/BookmarkPlaylist_<BookmarkGroupName>.save

Beispiele
*<code>Eltern:Sonos_(Schlaf|Wohn|Ess)zimmer</code><br />Hiermit wird eine Gruppe mit dem Namen '''Eltern''' definiert, die alle Listen, die auf den drei Playern '''Schlafzimmer''', '''Wohnzimmer''' und '''Esszimmer''' verwendet werden, beachtet.
*<code>Kind1:Sonos_Kind1:0:5</code><br />Hiermit wird eine Gruppe '''Kind1''' definiert, die alle Listen, die mindestens 0 und maximal 5 Titel haben, berücksichtigt.
*<code>All</code><br />Alle Listen aller Player werden berücksichtigt.

==== Bookmarks für Titel ====
Attributname am Sonos-Device:<br />
<code>bookmarkTitleDefinition</code>

Definition:<br />
<code><Groupname>:<PlayerdeviceRegEx>:<TrackURIRegEx>:<MinTitleLength>:<RemainingLength>:<MaxAge>:<ReadOnly> [...]</code>

Bedeutung:
*<code>Groupname</code>: Ein beliebiger Name, der auch als Dateiname verwendet werden kann und keinerlei Sonder-/Leerzeichen enthält
*<code>PlayerDeviceRegEx</code>: Ein regulärer Ausdruck, der für das Matching der zu berücksichtigten Player verwendet wird. Das Matching erfolgt auf dem FHEM-Devicenamen. Wenn nicht angegeben, dann wird ''''.*'''' verwendet.
*<code>TrackURIRegEx</code>: Ein regulärer Ausdruck, der für das Matching der zu berücksichtigten Titel verwendet wird. Wenn nicht angegeben, dann wird '''.*'''' verwendet.
*<code>MinTitleLength</code>: Die minimale Lieddauer in Sekunden, die der Titel lang sein muss, um berücksichtigt zu werden. Wenn nicht angegeben, dann wird ''''60'''' verwendet.
*<code>RemainingLength</code>: Die minimale Restspielzeit in Sekunden, die ein Titel noch haben muss, um berücksichtigt zu werden. Wenn nicht angegeben, dann wird ''''10'''' verwendet.
*<code>MaxAge</code>: Das maximale Alter für die Verwendung eines gespeicherten Bookmarks in Sekunden. Hier kann ein beliebiger Perl-Ausdruck (natürlich ohne Doppelpunkte) verwendet werden, der zu einer Zahl evaluierbar sein muss. Wenn nicht angegeben, dann wird ''''28*24*60*60'''' (also vier Wochen) verwendet.
*<code>ReadOnly</code>: Wenn hier etwas angegeben wird, was von Perl als '''true''' erkannt wird, dann wird diese Gruppe beim Aufruf von '''SaveBookmarks''' (also auch beim Beenden von FHEM) nicht berücksichtigt. Wenn nicht angegeben, dann wird ''''0'''' verwendet (die Gruppe wird also gespeichert).

Nach hinten hin dürfen die Doppelpunkte von leergelassenen Werten ebenfalls weggelassen werden.

Es können beliebig viele Gruppen mit diversen (auch überlappenden) Bereichen gebildet werden. Diese verschiedenen Gruppen werden mit Leerzeichen getrennt, sodass innerhalb einer Bookmarkdefinition selbst keinerlei Leerzeichen vorkommen dürfen.

Die Dateinamen für das Speichern und Laden werden wie folgt gebildet: <bookmarkSaveDir>/Bookmark_<BookmarkGroupName>.save

Beispiele
*<code>Eltern:Sonos_(Schlaf|Wohn|Ess)zimmer</code><br />Hiermit wird eine Gruppe mit dem Namen '''Eltern''' definiert, die alle Titel, die auf den drei Playern '''Schlafzimmer''', '''Wohnzimmer''' und '''Esszimmer''' laufen, beachtet.
*<code>Kind1:Sonos_Kind1:.*?\/Hörspiele\/.*:240:30</code><br />Hiermit wird eine Gruppe '''Kind1''' definiert, die alle Titel, die im Pfad den Teil '''/Hörspiele/''' enthalten, mindestens 240 Sekunden (also vier Minuten) lang und mehr als 30 Sekunden vom Ende entfernt sind, berücksichtigt.
*<code>All</code><br />Alle Titel aller Player werden berücksichtigt.

==== Hinweise ====
*Beim Speichern/Laden kann der Einfachheit halber nur der Gruppenname mitgegeben werden. Gibt es sowohl im Bereich Playlist als auch im Bereich Titel eine Gruppe mit diesem Namen, dann werden beide gespeichert/geladen. Wenn man das verhindern möchte, dann müssen die Gruppennamen global eindeutig sein.

== Hardware-/Betriebssystemvoraussetzungen ==
Diese Liste sollte im Laufe der Zeit fortgeführt werden. Es soll die Hardware-/Softwarevoraussetzungen festhalten, um Probleme im Vorfeld erkennen zu können.

Funktionierende Kombinationen:
*Windows, ActivePerl 32Bit (zusätzliche Pakete sollten dort mit Hilfe des mitgelieferten, grafischen Paketmanagers installiert werden)
*Raspberry Pi, Default-Perl
*Mac Mini, Perl 5.18 mit ''-useThreads'' kompiliert

Problematische Kombinationen:
*FritzBox: Anscheinend ist Perl dort ohne Thread-Möglichkeit kompiliert. Diese sind aber essentiell notwendig für dieses Modul.
*Windows, ActivePerl 64Bit (das Paket SOAP::Lite gibt es momentan nicht für 64Bit)

== Anpassungen bei Nutzung von IPTables als Firewall ==
Benutzt man bereits IPTables, so müssen folgende Regeln hinzugefügt werden. z.B. unter /etc/defauts/iptables

*filter
:INPUT DROP [0:0]
:FORWARD DROP [0:0]
:OUTPUT ACCEPT [0:0]

# Sonos Kommunikation
-A INPUT -m pkttype --pkt-type multicast -j ACCEPT
-A INPUT -s 224.0.0.0/8 -j ACCEPT

# alles im lokalen LAN
-A INPUT -s 192.168.0.0/16 -j ACCEPT

== Softwarevoraussetzungen ==
Für die Verwendung sind Perlmodule notwendig, die unter Umständen noch nachinstalliert werden müssen:
*'''LWP::Simple'''
*'''LWP::UserAgent'''
*'''SOAP::Lite'''
*'''HTTP::Request'''
*('''XML::Parser::Lite''')<br />Ist im Normalfall im Standardpaket von Perl enthalten. Kann aber u.U. fehlen (scheint unter Ubuntu und verschiedenen Debian-Systemen so zu sein), und muss dann manuell nachinstalliert werden.

Die Installation dieser Module geht in der Regel per CPAN. Das bedeutet das zum Beispiel mit
<pre>
sudo cpan LWP::Simple
</pre>
das Modul "<code>LWP::Simple</code>" installiert wird. Wenn man bereits als Benutzer '''root''' arbeitet, dann ist das <code>sudo</code> natürlich nicht nötig.

Sollte es bei der Installation mittels CPAN zu Problemen kommen, dann folgt hier eine Beschreibung der manuellen Installation.

=== Hinweis für Debian-Systeme ===
Bei Debian-basierten Systemen (also auch Raspbian für den Raspberry Pi oder Ubuntu usw.) kann auch mittels
<pre>
sudo apt-get install <paketname>
</pre>
installiert werden. Manchmal ist es etwas schwieriger, die Paketnamen zu ermitteln, aber Google ist da sehr hilfreich.

Hier mal die Liste für die oben genannten Pakete:
*'''LWP::Simple'''-Paketname (inkl. '''LWP::UserAgent''' und '''HTTP::Request'''): <code>libwww-perl</code>
*'''SOAP::Lite'''-Paketname: <code>libsoap-lite-perl</code>
*'''XML::Parser::Lite'''-Paketname: <code>libxml-parser-lite-perl</code> oder falls nicht verfügbar <code>libxml-parser-perl</code>

=== Hinweis für Windows-Systeme mit ActivePerl ===
Bei Windows Systemen mit ActivePerl kann man die Installation über den ActivePerl Packagemanager durchführen:
*Installation von Package LWP (inkl. LWP::UserAgent und HTTP::Request)
*Installation von Package SOAP::Lite
**SOAP::Lite-Besonderheit für Versionen nach 5.18:
***Eine neue Paketquelle aus den Vorschlägen oder manuell hinzufügen: Bribes de Perl (http://www.bribes.org/perl/ppm)
***Installation von Package: SOAP::Lite

'''Hinweis:''' Windows ActivePerl 64Bit kann momentan nicht verwendet werden, da es das Paket SOAP::Lite aktuell nicht gibt.

=== Manuelle Installation LWP::Simple ===
Wenn sich dieses Paket nicht einfach per CPAN-Anweisung installieren läßt, dann hilft folgende Anleitung weiter.
Beim Abbruch der Installation mittels CPAN erscheint mittendrin ein Fehler, das die Datei nicht entpackt werden könne (couldn't untar). Da scheint es einen Fehler im Installationsskript zu geben.

Man kann das aber auch Manuell installieren:
*Am Einfachsten ist ein Wechsel in den Kontext des Benutzers '''root''': "<code>sudo su -</code>"
*Erstellen eines Ordners, z.B. "<code>mkdir lwpsimple</code>"
*Wechsel in diesen Ordner "<code>cd lwpsimple</code>"
*Herunterladen der Datei von [http://search.cpan.org/~gaas/libwww-perl-6.04/ libwww-perl-6.04] oder direkter Link: [http://search.cpan.org/CPAN/authors/id/G/GA/GAAS/libwww-perl-6.04.tar.gz libwww-perl-6.04.tar.gz]: z.B. "<code>wget http://search.cpan.org/CPAN/authors/id/G/GA/GAAS/libwww-perl-6.04.tar.gz</code>"
*Entpacken der Datei: "<code>tar -xzvf libwww-perl-6.04.tar.gz</code>"
*Wechsel in das neu entstandene Verzeichnis: "<code>cd libwww-perl-6.04</code>"
*Nun kann es nach dem Standardvorgehen weitergehen:
**"<code>perl Makefile.PL</code>"
**"<code>make</code>"
**"<code>make install</code>"

=== Manuelle Installation SOAP::Lite ===
Wenn sich dieses Paket nicht einfach per CPAN-Anweisung installieren läßt, dann hilft folgende Anleitung weiter.
Beim Abbruch der Installation mittels CPAN erscheint mittendrin ein Fehler, das die Datei nicht entpackt werden könne (couldn't untar). Da scheint es einen Fehler im Installationsskript zu geben.

Man kann das aber auch Manuell installieren:
*Am Einfachsten ist ein Wechsel in den Kontext des Benutzers '''root''': "<code>sudo su -</code>"
*Erstellen eines Ordners, z.B. "<code>mkdir soaplite</code>"
*Wechsel in diesen Ordner "<code>cd soaplite</code>"
*Herunterladen der Datei von [http://search.cpan.org/~mkutter/SOAP-Lite-0.715/ CPAN-SOAP-Lite-0.715] oder direkter Link: [http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/authors/id/M/MK/MKUTTER/SOAP-Lite-0.715.tar.gz SOAP-Lite-0.715.tar.gz]: z.B. "<code>wget http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/authors/id/M/MK/MKUTTER/SOAP-Lite-0.715.tar.gz</code>"
*Entpacken der Datei: "<code>tar -xzvf SOAP-Lite-0.715.tar.gz</code>"
*Wechsel in das neu entstandene Verzeichnis: "<code>cd SOAP-Lite-0.715</code>"
*Nun kann es nach der [http://www.soaplite.com/2003/06/installation_in.html Anleitung] weitergehen:
**"<code>perl Makefile.PL</code>"
**Dann kommt eine Nachfrage, was zusammengebaut werden soll. An dieser Stelle ist es jetzt wie eine normale CPAN Installation. Einfach mit <Enter> weitermachen lassen.
**"<code>make</code>"
**"<code>make install</code>"

=== Einrichtung von Samba für Sprachausgabemöglichkeit ===
Wenn die Sprachausgabe verwendet werden soll, muss ein lokaler Samba-Daemon (Server für Windowsfreigaben) laufen oder eine für FHEM beschreibbare (Windows-)Freigabe woanders existieren, da Sonos nur auf eine solche lesend zugreifen kann.

Diese Beschreibung soll anhand des Raspberry-Pi (und anderer Debian-Systeme) zeigen, wie man einen solchen lokalen Samba-Server schnell für diesen Zweck einrichten kann:
*Lokales Verzeichnis für die Ablage der Tondateien erzeugen. z.B.:
<pre>
sudo mkdir /mnt/SonosSpeak
sudo chmod 777 /mnt/SonosSpeak/
</pre>
*Installation der notwendigen Pakete für Samba: <pre>sudo apt-get install samba samba-common-bin</pre>
*Starten des Editors zum Anpassen der Konfigurationsdatei: <pre>sudo nano /etc/samba/smb.conf</pre>
*Ist die Datei Original von der Raspbian Installation, muss außer dem Eintrag für das Share nichts geändert werden! Folgende Zeilen am Ende der smb.conf hinzufügen (Pfade müssen natürlich u.U. angepasst werden):
<pre>
[SonosSpeak]
comment = Audio-Files for SonosPlayer to Speak
read only = false
path = /mnt/SonosSpeak
guest ok = yes
</pre>
*Falls der Zugriff nicht funktioniert, ist eventuell die smb.conf nicht im Originalzustand:
**Sicherstellen, dass in der ''Global''-Sektion der Parameter ''Security'' nicht definiert wurde oder auf ''security = user'' steht und der Eintrag ''map to guest = bad user'' noch vorhanden ist.
{{Randnotiz|RNText=Hinweis: Siehe auch https://forum.fhem.de/index.php/topic,79335.msg719716.html#msg719716}}
<pre>
[global]
security = user
map to guest = bad user
</pre>
*Samba-Server neustarten:
<pre>sudo systemctl restart smbd</pre>
Ältere Systeme
<pre>sudo /etc/init.d/samba restart</pre>

Damit wird eine Freigabe mit dem Namen '''SonosSpeak''' erzeugt, die von allen ohne Anmeldung gelesen und beschrieben werden kann.

== Interner Aufbau ==
Um die Kommunikation mit dem UPnP-Netzwerk parallel zum normalen Betrieb von FHEM zu ermöglichen, werden [http://perldoc.perl.org/threads.html Threads] eingesetzt. Dadurch sind manche Hardwareplattformen leider überfordert und können u.U. nicht mit diesem Modul verwendet werden.<br />Das läßt sich aus technologischen Gründen auch nicht umgehen.

Dabei wird der SubThread verwendet um die Callback-Aufrufe, die erfolgen, wenn z.B. eine Statusänderung eines Players erfolgt, zu verarbeiten. Die Aktualisierung der Daten selbst wird dann über eine interne [http://perldoc.perl.org/Thread/Queue.html Queue] "nach oben" zum Hauptthread übertragen, und dann mittels einer bestehenden TCP-Verbindung zur Verarbeitung in FHEM übertragen.<br /> Dadurch wird gewährleistet, dass die Daten immer im Hauptthread (also dem "eigentlichen" FHEM-Thread) verfügbar sind.

Da dieser SubThread auch die Kommandoübergabe an den Player übernimmt, gibt es auch eine Kommando-Queue in die andere Richtung, die dann mittels eines Thread-Signals im SubThread-Kontext ausgeführt wird.

Dieser Aufbau sorgt natürlich dafür, dass man auf die üblichen Nebenläufigskeitsprobleme achten muss (in der Hauptsache sind das Dead-Locks, da man oftmals über drei Ecken aufeinander wartet, ohne das direkt zu sehen). Deswegen wird in allen Log-Ausgaben des Moduls ein Kürzel vorangestellt: "<code>SONOS_</code>", wobei der Unterstrich durch die Nummer des aktiven, loggenden, Threads ersetzt wird. Damit kann man sehr leicht feststellen, auf welcher "Ebene" diese Ausgabe erfolgt ist, und ob das alles so seine Richtigkeit hat.

Der Rest sind nur viele Zeilen, die XML-Strukturen (mittels regulärer Ausdrücke) parsen oder erzeugen, und die entsprechenden Informationen setzen oder abfragen.

== Installation des Moduls selbst ==
Hier wird die Installation des eigentlichen Moduls beschrieben, sowie ein Changelog ausgegeben, damit man nachvollziehen kann, was am Modul so passiert ist. Dieser Changelog steht auch in der Datei 00_SONOS.pm.

=== Installation mittels FHEM-Updatemechanismus ===
Dieses Modul wird seit Dezember 2014 zusammen mit FHEM ausgeliefert. Es sind keine weiteren Schritte zur Installation des Moduls selbst notwendig.

=== Fehlersuche ===
Da das Modul noch in der Entwicklung steht, und natürlich sowieso immer wieder Probleme auftauchen können, hier ein paar Hinweise zur Fehlersuche:
Das Modul besteht zunächst aus zwei Ebenen:
*Eine Ebene, die innerhalb von FHEM selbst läuft
*Eine Ebene, die als eigenständiger Prozess läuft (entweder durch FHEM selbst oder manuell angestartet)

Die Logausgaben der ersten Ebene landen direkt im FHEM-Log, die der zweiten Ebene können dort nicht reingeschrieben werden, und landen dementsprechend auf der Konsole (genauer: auf STDOUT).
Wenn man also die Log-Ausgaben dieses Sub-Prozesses sehen möchte, muss man im Startskript den STDOUT entsprechend umlenken, oder einen manuellen Start ausführen:
<code>sudo perl fhem.pl fhem.cfg</code>
Dazu muss man natürlich vorher in das entsprechende Verzeichnis wechseln.

Die Menge der Logausgaben werden, wie in FHEM üblich, über das Attribut Verbose am Sonos-Device gesteuert (Bis auf wenige Zeilen beim Start des Sub-Prozesses, die nur mit dem globalen Verbose-Attribut gesteuert werden können, da noch keine Verbindung besteht).

'''Hinweis!''': <br />In neueren Versionen von FHEM wird die Konsolenlogausgabe in das normale FHEMlog umgeleitet, sodass man das nicht mehr umständlich selber umlenken und suchen muss.

Im Normalfall sollte Anhand der Ausgabe erkennbar sein, was das jeweilige Problem ist. Bei Unklarheiten am Besten im Forum suchen/posten.

==== Hinweise / Häufige Fehler / FAQ ====
Hier soll mal eine Liste mit häufigen Fehlern, Problemen und Hinweisen entstehen.

*In neueren Versionen von FHEM werden die Konsolen-Logausgaben in das FHEMlog umgeleitet. Dadurch wird die Logdatei in der Standardeinstellung von (3) ziemlich voll. Wenn man das verhindern möchte, dann muss man das Attribut ''verbose'' am Sonos-Device auf einen Wert kleiner 3 setzen (z.B. 0).
*Das Modul wird im Normalfall stets an die aktuelle Sonos-Firmwareversion angepasst. Es empfiehlt sich also im Normalfall bei komischem Verhalten des Moduls, welches auf eine solche Inkompatibilität hindeutet, auf die neueste Sonos-Firmware upzudaten.<br />Ein Beispiel ist hierfür die Verarbeitung der Alarme. Dort wurde bei einem Sonos-Update die Logik verändert, sodass das Modul nun eine Inkompatibilität mit der Vorgängerfirmwareversion hat.
*Allgemein läuft das Modul besser, wenn es im Benutzerkontext ''root'' läuft. Für diverse Funktionalitäten ist das sogar notwendig (z.B. Pingtype auf ''icmp'' konfiguriert).
**Um FHEM als ''root'' laufen lassen zu können, kann es notwendig sein, den Benutzer ''fhem'' in der Datei '''/etc/passwd''' auszumarkieren oder mittels '''deleteuser''' zu löschen. FHEM schaltet in den Benutzerkontext ''fhem'' um, wenn es diesen Benutzer beim Start findet.
*Wenn man das Problem hat, dass Befehle an den falschen Player gesendet werden, sollte man das Reading '''ZoneGroupID''' prüfen. Bei ungruppierten Playern sollte es die eigene UDN enthalten, bei gruppierten Playern die UDN des Gruppenmaster.<br />Sollte das mal nicht der Fall sein, so kann es sein, dass im Sonos-System eine Falschinformation vorliegt. Da es jetzt nicht so einfach ist, die bei Sonos dazu zu bewegen, diesen Fehler zu beseitigen, gibt es u.U. eine Workaround-Möglichkeit mit dem Modul.<br />Wenn wir z.B. zwei Player haben: ''Sonos_Bad'' und ''Sonos_Kueche'', und dort die Steuerung nicht korrekt funktioniert, dann einmal die folgenden Schritte versuchen (bei mehr oder anderen Playern natürlich analog dazu).<br />Dadurch werden die Gruppen gebildet, und nochmal explizit aufgelöst.
**<code>set Sonos Groups [Sonos_Bad, Sonos_Kueche]</code>
**<code>set Sonos Groups [Sonos_Kueche, Sonos_Bad]</code>
**<code>set Sonos Groups [Sonos_Bad], [Sonos_Kueche]</code>
*Es ist wichtig, dass erst das '''Sonos'''-Device definiert wird, und dann erst die entsprechenden '''Sonosplayer'''-Devices dazu. Sonst kann es u.U. zu einer Verdoppelung des SubProzesses kommen.
*Manchmal bleiben 'Reste' beim Beenden von FHEM. Dann kann es sinnvoll sein, erst alle Perl-Prozesse zu beenden. Diese kann man mit <pre>sudo ps -aux | grep perl</pre> finden, und dann einzeln mittels <pre>sudo kill ID</pre> beenden (die ID steht in der ersten Spalte des Ergebnisses des vorherigen Befehls).

Einträge, die mittlerweile behoben wurden:
*'''Fehler'''-Ausgaben beim FHEM-Start: Einige Readings dürfen bei einem Neustart von FHEM nicht bereits vorbelegt sein, da der entsprechende Zoneplayer mittlerweile andere Informationen haben könnte, bzw. einige Events sonst nicht erzeugt werden. Aus diesem Grund werden diese beim Start auch nicht geladen.<br />Folgende Meldung erscheint z.B.:<code>Reading Sonos_Wohnzimmer->AlarmListVersion must not be used out of statefile.</code><br />Diese Meldungen kann man getrost ignorieren, da sie nicht auf einen Fehler hindeuten, sondern nur klarstellen, dass diese Readings eben nicht aus dem Statefile verwendet werden dürfen (was durch Ausgabe dieser Meldung auch nicht passiert).
**Das konnte mittlerweile durch ein Setzen eines "Lademarkers" verhindert werden. Dadurch wird das Laden des Readings nicht mehr unterbunden, sondern auf einen sicher ungültigen Wert gesetzt. Damit funktionieren die folgenden Readings-Update Aufrufe wieder.

=== Changelog ===
{| class="wikitable mw-collapsible mw-collapsed" style="width:100%"
! style="width:10%" | Datum !! style="width:8%" | Version !! style="width:82%" | Änderungen
|-
| colspan="3" style="vertical-align:top" | SVN-History
|-
| colspan="2" style="vertical-align:top;text-align:center" | 25.04.2018
|
*"Deep Recursion"-Warnung beim loggen wird nun verhindert
*Beim Erzeugen der Gruppen-ReadingsGroup ist bei der Verwendung eines Boosts ab und zu ein Fehler aufgetreten
*Beim Erzeugen eines ControlPoint-Objekts kann man nun das Envelope-Prefix angeben (nicht für das Sonos-Modul relevant)
|-
| colspan="2" style="vertical-align:top;text-align:center" | 15.04.2018
|
*Streams über Alexa (z.B. Sonos One) werden nun korrekt als Radiostreams dargestellt
*Es werden nun auch Updateinformationen und die interne Softwareversionsnummer gesucht und als Reading gesetzt: "softwareRevisionAvailable", "softwareRevisionInternal" und "softwareRevisionInternalAvailable"
|-
| colspan="2" style="vertical-align:top;text-align:center" | 24.03.2018
|
*Einige Log-Ausgaben haben bei undefinierten Default-Übergaben Fehlermeldungen verursacht.
*Bei einigen Positionsabfragen an die Player wurden Sonderfälle (wie NOT_IMPLEMENTED) nicht berücksichtigt.
*Slider-Wertebereich für Bass und Treble auf den Bereich -10..10 korrigiert.
*Es gibt jetzt ein Reading "IsZoneGroup", das 0 oder 1 sein kann. Danach wird jetzt auch entschieden, ob eine Playersteuerung dargestellt wird, oder nicht.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 10.03.2018
|
*Die PlayBase kann nun auch den SPDIF-Eingang aktivieren (wie die PlayBar)
*Wenn man über Alexa Musik hört, wird das aktuelle Cover nun auch angezeigt.
*Wenn ein Player nach einem Neustart disabled war, und während des Betriebs enabled wird, wird nun versucht ihn wiederzufinden.
*Wenn ein Player disabled oder disappeared ist, wird ein Proxy-Cover-Zugriffsversuch auf diesen Player unterbunden.
*Ein Modify-Befehlsaufruf wird nun am Vorhandensein von $hash->{OLDDEF} erkannt.
*Bei einigen PERL-Installationen stand im Reading 'currentTrackPositionSimulatedSec' eine Kommazahl (da sie von time() aus berechnet wird). Diese Zahl wird nun gerundet.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 26.02.2018
|
*ComObjectTransportQueue in Client_ReceiveQueue umbenannt.
*If-Abfrage um die can_read-Schleife im SubProzess eingebaut, Um Signalunterbrechungen zu berücksichtigen.
*Neuer Getter "WifiPortStatus". Liefert Active, wenn das WLAN aktiviert ist, sonst Inactive.
*Drei neue (automatisch ermittelte) Readings "Orientation", "WifiEnabled" und "WirelessMode".
*Warnung mit "unescaped left brace" in Tag.pm wurde korrigiert.
*ExportSonosBibliothek wird nun in einem eigenen Thread (LongJobs-Thread) ausgeführt. Dadurch bleibt das System steuerbar, auch wenn gerade ein langwieriger Export läuft.
*Prüfmethode eingebaut, um verlorengegangene Fhem-Prozessverbindungen (aus Sicht des SubProzesses) zu erkennen, und entsprechende Thread-Bereinigungmaßnahmen durchführen zu können.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 07.01.2018
|
*Der Initialwert von LastProcessAnswer (wird beim Start auf 0 gesetzt) wird nun korrekt berücksichtigt
*Bei ignoredIPs und bei usedOnlyIPs kann jetzt für jedes Komma-Getrennte Element auch ein regulärer Ausdruck stehen. Wird mit // umschlossen, und darf keine Doppelpunkte enthalten.
*Logausgabe im UPnP-Modul, welche Devices mit welchen Header-Angaben nun akzeptiert wurden (Ausgabe auf Level 5)
|-
| colspan="2" style="vertical-align:top;text-align:center" | 23.12.2017
|
*Subscriptions-Refresh umgebaut.
*Devicenamen mit Punkt (.) funktionieren nun.
*Fehler mit "undefined value $value" behoben.
*GetTrackProvider liefert bei Nichtfinden in der MusicServicesList nun eine leere Angabe, und keine undefined.
*Die Angabe in LastProcessAnswer ist nicht Zeitumstellungsfest. Der Wert wurde nun umgestellt auf epoch-Zeit.
*Der Verweis auf %intAt wurde entfernt. Die Variable wurde sowieso nie verwendet.
*Warnungsunterdrückung von 'mumpitzstuff' eingebaut.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 28.09.2017
|
*Provider-Icons werden wieder korrekt ermittelt
*Das Verarbeiten der Arbeitsschlange im SubProcess wurde optimiert
*Die Fehlermeldung mit den redundanten Argumenten bei sprintf wurde umgestellt.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 14.07.2017
|
*Änderung in der ControlPoint.pm: Es wurden zuviele Suchantworten berücksichtigt.
*Bei einem Modify wird von Fhem nur die DefFn aufgerufen (und nicht vorher UndefFn). Dadurch blieben Reste, die aber vor einer Definition aufgeräumt werden müssen. Resultat war eine 100%-CPU-Last.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 09.07.2017
|
*BulkUpdate: Beginn und Ende sind nun sicher davor einen vom SubProzess gestarteten BulkUpdate vorzeitig zu beenden.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 05.07.2017
|
*Neue Variante für das Ermitteln der laufenden Favoriten, Radios oder Playlists
|-
| colspan="2" style="vertical-align:top;text-align:center" | 05.07.2017
|
*Veralteten Mechanismus für das Unterbrechen der Sendeschleife aufgeräumt.
*SONOS_ConvertNumToWord kann nun mit undef-Übergaben umgehen.
*Andere Methodik zum Ermitteln von FavouriteName, RadioName und PlaylistName eingebaut.
*Es gibt ein neues Attribut "SubProcessLogfileName". Damit kann die Logausgabe des SubProzesses in eine eigene Datei umgeleitet werden. Unter Windows z.B. gibt es sonst keine saubere Darstellungsmöglichkeit für die Logausgabe, da die beiden Prozesse sich gegenseitig die Ausgaben im Fhem-Log überschreiben. Bei Angabe von '-' wird wie bisher auf STDOUT (und damit im Fhem-Log) geloggt.
*Kleinere Fehler bei einzelnen Reading-Aktualisierungen behoben.
*Beim Zerlegen der MusicServicesList gab es einen Fehler, der z.B. dafür gesorgt hatte, dass Apple Music nicht erkannt wurde.
*Umbau der Verarbeitungslogik in Richtung SubProzess. Das sollte nun schneller und sicher sequentiell verarbeitet werden.
*Die Aktualisierung des Readings "LastProcessAnswer" wird jetzt während eines laufenden Bulkupdates auch als solches durchgeführt, und zerstört damit nicht mehr dieses laufende Update.
*Alle noch vorhandenen ReadingsSingleUpdate-Aufrufe wurden BulkUpdate-Sicher gemacht.
*Die prozentuale Fortschrittsanzeige hat bei Streams negative, hohe Werte angezeigt. Steht jetzt wieder auf 0.
*Beim Löschen blieb noch die automatisch angelegte ReadingsGroup für die aktuelle Abspielliste bestehen.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 21.06.2017
|
*Bei der ersten Verbindung war das Reading für die letzte SubProzess-Antwort eventuell bereits veraltet. Das wird nun durch ein Datum in der Zukunft verhindert.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 20.06.2017
|
*Die Verarbeitung des Notify-Events für die Anzeigeaktualisierung ist in das SONOSPLAYER-Modul umgezogen (wo es auch logisch hingehört).
*Die Zeitkonvertierung hatte einen Sekundenfehler.
*Durch eine fehlerhafte IF-Verschachtelung in der ControlPoint.pm gab es komische Log-Augaben.
*Die lokalen Cover werden nur noch heruntergeladen, wenn das Attribut "getLocalCoverArt" am Sonos-Device gesetzt ist. Normalerweise merkt man davon nichts, da die eingebauten Coveranzeigen diese nicht verwenden. Wenn man diese heruntergeladenen Cover selbst noch verwendet werden, dann muss dieses Attribut gesetzt werden!
*Das Problem mit den Wide-Character bei der Hashwert-Berechnung von ProxyCache und SpeakBuffer wird abgefangen, und ein Versuch mit einem dazwischenliegenden Konverter durchgeführt.
*Das Subscribing für Rendering-Events wird in einem Eval durchgeführt, sodass eine abgefangene Fehlermeldung bei nicht-Erfolg ausgegeben wird. Das passiert z.B. bei einem Sub- oder Surroundlautsprecher.
*Die Simulation der aktuellen TrackPosition lief weiter, wenn der Player vor einem disappeared nicht gestoppt wurde.
*Bei der Verarbeitung eines Befehls im SubProzess wurde in einigen Fällen die Befehlsqueue nicht korrekt verringert, was zu Folgefehlern führte.
*Wenn der RestoreThread einen ungültigen Datensatz in der RestoreQueue vorfindet, überspringt er ihn...
*Bessere Behandlung der TrackProviderermittlung
*Bei MakeCoverURL gab es Logausgaben mit dem falschen Level.
*Es gibt vier neue Attribute am Sonosdevice: "getFavouritesListAtNewVersion", "getPlaylistsListAtNewVersion", "getRadiosListAtNewVersion" und "getQueueListAtNewVersion". In Zusammenarbeit mit "getListsDirectlyToReadings" wird dann bei Änderung der entsprechenden Liste automatisch das entsprechende Reading aller Sonosplayer-Devices aktualisiert. Hierbei entfallen dann etwaige eigene Notifies, die eine Aktualisierung der Readings veranlassen. Diese sollten dann natürlich auch entfernt werden.
*Die Überprüfung, ob der SubProzess noch lebt, wird nun über die bereits bestehende Verbindung abgewickelt. Dadurch entfallen die ständigen Verbindungsversuche zum SubProzess. Dazu wird ein Reading 'LastProcessAnswer' am zentralen Sonos-Device geführt.
*Bei Verlust der Verbindung zum SubProzess wird nun keine 100% Systemlast mehr verursacht.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 14.05.2017
|
*FHEMWEB-Anzeige der Player auf die neu möglichen, nicht quadratischen, Radiocover angepasst.
*In der Datei ControlPoint.pm wurde beim Öffnen des SSDP-Ports das Attribut ReusePort hinzugefügt (sofern das Betriebssystem das unterstützt).
*Es gibt ein neues Reading "currentEnqueuedTransportHandle", welches zur Weitergabe der aktuellen Quelle des aktuellen Titels verwendet werden kann.
*Es gibt zwei neue Readings "currentTrackHandle" und "nextTrackHandle", welche zur Weitergabe der aktuellen bzw. nächsten Wiedergabe geeignet sind.
*Es gibt ein neues Reading "currentSource", welches (wenn beliefert) den Namen der Quelle des Titels angibt. Bei Spotify z.B. die gewählte Playliste oder das Album, oder die gewählte Sonos-Playliste.
*Die Trackprovider werden jetzt über die verfügbaren, von Sonos bereitgestellten, MusicServices ermittelt.
*(Fehlende) Radiocover werden nun über den offiziellen Webservice von Sonos ermittelt, und werden wieder geladen.
*Etwaige, immer noch, fehlende Radiocover werden als Fallback wie bisher geladen. Das sollte aber nicht mehr vorkommen.
*Spotify-Playlisten-Cover werden wieder geladen.
*Teilweise wurden Bibliothekscover nicht geladen, das sollte wieder gehen.
*Die Verbindungsprüfung zwischen Fhem-Modul und SubProzess erfolgt nur noch, wenn nicht sowieso schon Daten übertragen werden, und sollte dementsprechend nicht mehr dazwischenfunken.
*Die Verbindungsprüfung und der grundsätzliche Verbindungsaufbau zum SubProzess wurden umgestellt.
*Fehlermeldungen bei Fhem-Player-Such-Prozeduren verbessert.
*Es gibt zwei (bzw. vier) neue Readings "TrackProviderIconRoundURL" und "TrackProviderIconQuadraticURL" (jeweils für "current" und für "next"). Mit diesen lassen sich die entsprechenden Provider-Icons anzeigen.
*Die Titelanzeige in FhemWeb enthält nun auch die neuen Provider-Icons.
*Detaildarstellung der SonosPlayer-Devices enthält jetzt auch die Coverdarstellung.
*Bug in "SONOS_GetTimeFromString" behoben.
*Es gibt zwei neue Attribute "simulateCurrentTrackPosition" und "simulateCurrentTrackPositionPercentFormat". Mit diesen kann man eine Simulation des Fortschritts von currentTrackPosition im gewählten Intervall aktivieren. Dabei werden die Readings "currentTrackPositionSimulated", "currentTrackPositionSimulatedSec" und "currentTrackPositionSimulatedPercent" (nur bei gelieferter "currentTrackDuration") aktualisiert.
*Es gibt zwei neue Readings "currentTrackDurationSec" und "nextTrackDurationSec", welche die jeweilige Tracklänge in Sekunden angeben.
*Durch ein mittlerweile verändertes Notify-Event-Handling in Fhem wurden die Bookmarks nicht immer zusammen mit dem globalen Save-Befehl gespeichert.
*Die Cover-/Titelanzeige wird nun intern vom Modul durchgeführt. Deshalb ist keine zusätzliche ReadingsGroup für die Anzeige und Aktualisierung mehr notwendig. In der Raumansicht kann man das Verhalten für alle Sonosplayer einheitlich mit dem Attribut "deviceRoomView" beeinflussen. Es kann die Zustände "Both" und "DeviceLineOnly" annehmen.
*Die Steuermöglichkeiten werden nun intern vom Modul dargestellt. Dazu muss die Cover-/Titelanzeige aktiviert sein. Will man die Steuerung ausblenden, kann man das Attribut "suppressControlButtons" für Sonosplayer einzeln setzen setzen.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 09.04.2017
|
*Beim Maskieren der Anzeigelisten für Playlisten, Radios oder Favoriten werden Klammern und andere Sonderzeichen für reguläre Ausdrücke nun auch in Punkte umgewandelt, da diese sonst den regulären Such-Ausdruck stören.
*Beim Starten/Laden von Playlisten, Radios oder Favoriten werden, vor der eigentlichen Suche im Sonossystem, einfache Anführungszeichen (') in die HTML-Schreibweise (') übersetzt, da diese so auch von Sonos verwendet werden.
*Radiocover werden nun in höherer Auflösung von einer TuneIn-API-Schnittstelle geladen (von dort wo auch der Controller selbst die Cover lädt).
|-
| colspan="2" style="vertical-align:top;text-align:center" | 04.04.2017
|
*Es gibt zwei neue Readings "AvailablePlayerList" und "AvailablePlayerListAlias" am Sonosplayer-Device, wenn das Attribut "getListsDirectlyToReadings" am Sonos-Device gesetzt wurde. Diese Reading geben die anderen noch verfügbaren, nicht gebundenen, Player an. Das ist die Grundlage für eine Player-zur-Abspielgruppe-hinzufügen-Funktion als Listendarstellung.
*Es gibt zwei neue Readings "AllPlayerNotBonded" und "AllPlayerNotBondedCount" am Sonos-Device, welche alle Masterplayer angibt, die nicht gebunden sind.
*Es gibt ein neues Reading "IsBonded" am Sonosplayer-Device, welches angibt, ob der Player in einer Bindung zum Masterplayer steht (anstatt ein einfaches Gruppenmitglied zu sein). Gebundene Player sind z.B. der rechte Player im Stereoverbund, sowie die Satellitenplayer in einem 5.1er Surroundsystem (also Subwoofer, hintere Lautsprecher und vordere Lautsprecher).
*Es gibt drei neue Readings "SlavePlayerNotBonded", "SlavePlayerNotBondedList" und "SlavePlayerNotBondedListAlias" am Sonosplayer-Device, wobei die beiden letzteren nur erzeugt werden, wenn das Attribut "getListsDirectlyToReadings" am Sonos-Device gesetzt wurde.
*Es gibt jetzt ein Attribut "getTitleInfoFromMaster" am Sonosplayer-Device, mit welchem man ein Slave-Device (auch gebundene) dazu bringen kann, die wichtigsten Abspielreadings automatisch vom Master zu duplizieren.
*Die Oberflächenauswahl für "AddMember", "RemoveMember" und "CreateStereoPair" wurde auf die nicht bereits gebundenen Player bzw. die Teilnehmer deer Gruppe beschränkt.
*Es gibt zwei neue Readings "AllPlayer" und "AllPlayerCount" am Sonos-Device. Damit erhält man eine komplette Liste aller Player (und deren Anzahl), egal wie sie gerade verwendet werden.
*Die mitgelieferte Prozedur für die ReadingsGroup-Anzeigen wurde für das neue Reading "Queue" erweitert, außerdem wurde ein Darstellungsproblem der Gruppierungsanzeige mit aktuellen Versionen von FHEMWEB behoben
*Es gibt zwei neue Readings "ButtonState" und "ButtonLockState", sowie einen Setter für "ButtonLockState".
*Es gibt ein neues Reading "LineInPlayer" am Sonos-Device, und wenn das Attribut "getListsDirectlyToReadings" gesetzt ist, auch "LineInPlayerList" und "LineInPlayerListAlias". Diese Liste enthält die gültigen LineIn-Eingänge aller Player, die für die Wiedergabe ausgewählt werden können.
*Es gibt zwei neue Attribute "stopSleeptimerInAction" und "saveSleeptimerInAction" am Sonosplayer-Device. Mit "stopSleeptimerInAction" wird das Modul dazu angehalten, bei einem Wechsel des TransportState auf "STOPPED" oder "PAUSED_PLAYBACK" einen etwaig aktivierten SleepTimer zu deaktivieren. Mit dem Attribut "saveSleeptimerInAction" kann man dieses Verhalten (z.B. temporär) wieder unterdrücken.
*Es gibt jetzt ein Reading "ZoneGroupNameDetails" am Sonosplayer-Device, welches die Slavezonen als textuelle Auflistung mittels '+' enthält. Ist leer, wenn es keine Slaveplayer gibt. Enthält den Namen des Gruppenmasters, wenn es einen solchen gibt.
*Interne Aufräumarbeiten: Mittlerweile überflüssige Codeteile wurden entfernt, und einige Single-Readingsupdates zu einem Bulk-Readingsupdate zusammengefasst.
*Die Readings "currentFavouriteNameMasked", "currentPlaylistNameMasked" und "currentRadioNameMasked" werden automatisch gesetzt, wenn das Attribut "getListsDirectlyToReadings" gesetzt ist.
*Tippfehler bei den Readings "RadioList" und "RadioListAlias" korrigiert. Korrekt ist nun "RadiosList" und "RadiosListAlias" (also Mehrzahl bei Radios).
|-
| colspan="2" style="vertical-align:top;text-align:center" | 19.03.2017
|
*Es gibt ein neues Attribut "getListsDirectlyToReadings", mit welchem die UserReadings bzgl. Favourites, Playlists und Radios (sowie currentTrackPosition) obsolet werden, da sie dann direkt in die passenden Readings geschrieben werden. Wenn man selber beeinflussen möchte, auf welche Weise und mit welchem Namen diese Readings gefüllt werden, dann darf dieses Attribut nicht gesetzt werden (es bleibt dann das bisherige Verhalten)
*Es gibt zwei neue Getter "Queue" und "QueueWithCovers", welche die aktuelle Abspielliste liefern. Diese können wieder mit UserReadings oder dem neuen Attribut "getListsDirectlyToReadings" in entsprechende Readings übertragen werden. Hierbei werden auch zwei neue Readings "QueueDuration" und "QueueDurationSec" gefüllt, die die gesamte Abspieldauer der Abspielliste enthalten.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 13.03.2017
|
*Saubere Fehlerbehandlung bei der Verarbeitung von currentFavouriteName, currentPlaylistName und currentRadioName.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 12.03.2017
|
*NotifyFn und NotifyDev werden nun im Define des Moduls festgelegt (anstatt wie vorher im Initialize). Dadurch sollten deutlich weniger Notify-Anfragen beim Modul ankommen.
*Es gibt nun einen Set-Befehl "RefreshShareIndex" zum Aktualisieren der Bibliothek und ein Reading "ShareIndexInProgress", welches angibt, ob eine Aktualisierung gerade in Ausführung ist.
*Die Fehlermeldung beim Verbinden zum Device wurde um die Zieladresse erweitert.
*Es gibt drei neue Readings, die sich auf Spotify-Direct-Play beziehen: DirectControlClientID, DirectControlIsSuspended und DirectControlAccountID
*Man kann beim Setzen der Titelposition nun auch relative Angaben machen, also z.B. '+0:00:15' oder auch '+10%'. Geht natürlich auch mit '-'.
*Man kann beim Setzen der Titelposition nun auch eine ganze Zahl als Sekundenangabe machen. Dabei gehen auch Relativangaben
*Beim Cover-Download wird nun ein Standard_Timeout von 5s verwendet, sodass ein fehlender Player keine Blockade mehr verursachen sollte. Dafür gibt es auch ein neues Attribut 'coverLoadTimeout', womit dieser Wert eingestellt werden kann. Das ganze geht nur für Nicht-Windows-Systeme, da der Timeout über einen Alarm realisiert wird.
*Wenn während eines Subscriptions-Renews ein Timeout-Fehler auftreten sollte, wird nun der Discovery-Prozess neu angestartet, um sicherzustellen, daß der Player wieder gefunden und neu initialisiert wird.
*In der ControlPoint.pm wurde eine Sicherheitsabfrage eingebaut, wenn total verstümmelte Pakete beim SSDP-Recover ankommen.
*Es gibt ein neues Reading "currentEnqueuedTransportURI", welches den TransportURI des hinzugefügten Paketes enthält, aus welchem der Titel gerade abgespielt wird (z.B. der Identifier der Spotify-Playliste)
*Es gibt ein neues Reading "currentFavouriteName", welches versucht den "currentEnqueuedTransportURI" in den Favoriten zu finden, und enthält dann den gefundenen Favoritennamen. Dazu müssen die Favoriten einmal mittels "get FavouritesWithCover" ermittelt worden sein, und im Reading "Favourites" bereitstehen.
*Es gibt ein neues Reading "currentPlaylistName", welches versucht den "currentEnqueuedTransportURI" in den Playlisten zu finden, und enthält dann den gefundenen Playlistnamen. Dazu müssen die Playlisten einmal mittels "get PlaylistsWithCover" ermittelt worden sein, und im Reading "Playlists" bereitstehen.
*Es gibt ein neues Reading "currentRadioName", welches versucht den "currentEnqueuedTransportURI" in den Radios zu finden, und enthält dann den gefundenen Radionamen. Dazu müssen die Radios einmal mittels "get RadiosWithCover" ermittelt worden sein, und im Reading "Radios" bereitstehen.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 19.03.2016
|
*Bei der Alarmbearbeitung kann man nun mehrere Alarm-IDs mit Komma getrennt angeben, und das Schlüsselwort "All" verwenden, um alle Alarme dieses Players anzusprechen.
*Man kann bei der Alarmbearbeitung nun auch zwei neue, direkte und kürzere, Befehle für Standardaufgaben verwenden: "Enable", "Disable".
|-
| colspan="2" style="vertical-align:top;text-align:center" | 06.02.2016
|
*Zusätzlich zu "Mute" (mit Parameter) am Sonos-Device gibt es jetzt auch "MuteOn" und "MuteOff" (jeweils ohne Parameter) zur Verwendung als WebCmd.
*Es gibt ein neues Reading "IsMaster" am Sonosplayer-Device, welches angibt, ob der Player gerade ein Masterplayer ist
*Es gibt ein neues Reading "MasterPlayer" am Sonosplayer-Device, welches angibt, wie der aktuelle MasterPlayer zu diesem Player heißt. Ist der Player selber der Master (also IsMaster = 1), so steht dort der eigene Name drin.
*Es gibt ein neues Reading "SlavePlayer" am Sonosplayer-Device, welches angibt, welche Slaveplayer zu diesem Player zugeordnet sind. Enthält nur Playerdevicenamen, wenn dieser Player ein Masterplayer ist, und dann auch nicht sich selber.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 31.01.2016
|
*Im Modul ControlPoint.pm gab es eine fehlerhafte Bearbeitung des Arrays @LWP::Protocol::http::EXTRA_SOCK_OPTS, welche in manchen Fällen zu der Fehlermeldung "Odd number of elements in hash assignment" geführt hat.
*Der Anbieter SoundCloud wird als Quelle erkannt und angezeigt
*Es gibt drei neue Readings "MasterPlayer", "MasterPlayerPlaying" und "MasterPlayerNotPlaying" am Sonos-Device (zzgl. der jeweiligen Angabe der Anzahl)
*Die Ausgabe von "get Sonos Groups" liefert nun stets eine normalisierte Liste (also sortiert).
|-
| colspan="2" style="vertical-align:top;text-align:center" | 31.12.2015
|
*Das Reading ZoneGroupID wurde immer länger (mit ":__"), wenn Gruppierungen anderer Player verändert wurden.
*Bei den Settern von "SleepTimer" und "SnoozeAlarm" kann man jetzt auch eine Zahl als Dauer in Sekunden angeben. Dazu wurde auch die Doku entsprechend angepasst.
*In der ControlPoint.pm wurde eine Fehlermeldung korrigiert
|-
| colspan="2" style="vertical-align:top;text-align:center" | 24.12.2015
|
*Wenn ein Player ein "ß" (oder auch andere besondere Zeichen, wie Smilies o.ä.) im Namen hatte, funktionierte die Erkennung nicht mehr, und der SubThread verstarb.
*Man kann nun mittels dem Setter "Name" auch "ß" und Smilies o.ä. im Playernamen setzen.
*Bei der Namensvergabe des Sonosplayer-FHEM-Device wird jetzt ein bißchen besser umgewandelt. Erst werden alle Sonderzeichen entfernt, dann Leerzeichen an den Rändern entfernt, und dann die restlichen Leerzeichen in "_" umgewandelt
*Das Attribut "characterDecoding" wurde entfernt, da es keine Funktion mehr hatte.
*Der UPnP-Teil verwendet nun einen beliebigen freien Port für die Kommunikation mit den Playern. Dadurch sind auch mehrere Instanzen auf ein und derselben Maschine möglich.
*Es gibt jetzt einen neuen Setter "RescanNetwork" am Sonos-Device. Damit kann man den Erkennungsprozess des UPnP-Moduls neu anstarten.
*Es gibt jetzt eine Get-Anweisung "SupportLinks" am Playerdevice, die direkte Links (momentan zwei) zu den Player-Support-Seiten liefert.
*Ein Datei-Ordner als Favorit konnte nicht sauber gestartet werden. Es wurde nicht als Album in die aktuelle Abspielliste übertragen, sondern als ein Titel direkt abgespielt. Des Weiteren wurde dafür kein Coverbild ermittelt.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 15.12.2015
|
*Es gibt eine neue Funktionalität an den Sonosplayern: Repeat für einen einzelnen Titel. Durch diese Umstellung wurde der Repeat-Zustand nicht korrekt erkannt. Dafür gibt es jetzt noch einen zusätzlichen Setter und ein zusätzliches Reading: "RepeatOne".
*Es gibt eine neue Funktion "DeleteFromQueue", die Titel aus der aktuellen Abspielliste entfernen kann. Angegeben wird der Index des Elements / der Elemente.
*Das Reading "fieldType" wurde nicht ordnungsgemäß auf Leer gesetzt, wenn die Gruppierung aufgelöst wurde.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 08.12.2015
|
*Bei der Erkennung von Streams beim Restore von PlayURITemp wurde ein neues Format nicht berücksichtigt.
*Bei der Verwendung von "set Sonos Groups Reset" tauchte eine Fehlermeldung wegen eines Leerstrings auf.
*Es wurde ein neuer Setter "LoadFavourite" eingebaut, der einem StartFavourite mit der Angabe von NoStart entspricht.
*Man kann bei LoadSearchList nun auch an das Ende der aktuellen Abspielliste anhängen lassen. Dazu muss man an den Parameter maxElem ein "+" anhängen.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 07.12.2015
|
*Zwei neue Setter "DialogLevel" und "NightMode", die an einer PlayBar ausgeführt werden können.
*"Set Sonos Groups" hat eine neue Option "Reset", mit der alle Gruppen in einem Rutsch aufgelöst werden können.
*ControlPoint.pm: Bei einem Fehler beim Verbindungsaufbau zum Player wurde aus dem "carp" ein "croak" gemacht. Dadurch greifen die Auffangmechanismen.
*Beim Verlieren des Gruppenmaster stand der TransportState bei allen zukünftigen NICHT-Gruppenmastern bis zum nächsten Titelwechsel auf "ERROR".
*Man kann bei einer Speak-Definition nun auch den Parameter %textescaped% verwenden, um den URL-Enkodierten Text einzufügen.
*Die Smartmatch-Fehlermeldung wird nun unterdrückt
*Die Fehlerausgabe bei fehlenden Set- oder Get-Parametern enthält jetzt auch den zulässigen Wertebereich des Parameters (z.B. '(0..100)' für die Lautstärke), sowie die optionalen Parameter
*StartSearchList hat die Wiedergabe immer neu gestartet, obwohl das u.U. gar nicht nötig war.
*Die Attribute für die Lautstärke (minVolume, maxVolume, minVolumeHeadphone und maxVolumeHeadphone) können nun im laufenden Betrieb geändert werden und die neuen Grenzen werden sofort sichergestellt.
*Es gibt einen neuen Setter 'MakeStandaloneGroup', mit dem man einen Player aus seiner Gruppe lösen kann.
*Es wird der Provider Amazon nun mit angezeigt.
*Es gibt nun ein Attribut usedonlyIPs, mit dem man die IP-Adressen der zu verwendenden Player angeben kann. Damit ist man manchmal besser dran, als mit dem Ausschluss von einzelnen Adressen
*Es gibt einen neuen Setter "TruePlay".
*Es gibt ein neues Attribut 'SpeakGoogleURL' für die Definition der zu verwendenden Google-URL für die Sprachausgabe
*Die Standard-Google-URL wurde nach neuen Hinweisen angepasst.
*Es gibt neue Setter "AudioDelayLeftRear" (Abstand hinterer linker Lautsprecher), "AudioDelayRightRear" (Abstand hinterer rechter Lautsprecher) und "SubPolarity" (Sub Aufstellung) bei einem 5.1 Surroundsystem.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 02.08.2015
|
*uri_escape() umgestellt, sodass auch UTF8-Sonderzeichen übersetzt werden
*Google-Translator-URL parametrisiert und um die mittlerweile notwendigen Parameter 'client=t' und 'prev=input' erweitert
|-
| colspan="2" style="vertical-align:top;text-align:center" | 12.07.2015
|
*Es gibt zwei neue Setter "GroupVolumeU" und "GroupVolumeD", um die Gruppenlautstärke um 'VolumeStep'-Einheiten zu erhöhen oder zu verringern.
*Innerhalb des SubProzesses wurden die Devicenamen der bereits in FHEM definierten Player nicht korrekt verwendet. Das machte sich erst mit dem neuen Feature Bookmarks bemerkbar.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 14.06.2015
|
*Zwei weitere Ausnahmen für das Neustarten des SubThreads eingefügt.
*ControlPoint.pm: Beim Renew von Subscription wurde aus dem "carp" ein "croak" gemacht. Dadurch greifen die darüberliegenden Auffangmassnahmen.
*Neues Feature: Bookmarks für Playlisten und Titel
*Changelog in der Quelltextdatei enthält nur noch für die letzten vier Veröffentlichungen. Die komplette Liste ist nur noch im Wiki vorhanden. Dadurch wird die Dateigröße geringer.
*SetEQ eingebaut, um Subwoofer und Surroundeinstellungen vornehmen zu können: "SurroundEnable", "SurroundLevel", "SubEnable", "SubGain" und "AudioDelay"
|-
| colspan="2" style="vertical-align:top;text-align:center" | 02.05.2015
|
*Es gibt drei neue Readings "FavouritesVersion", "RadiosVersion" und "PlaylistsVersion", die bei einer Änderung des jeweiligen Bereichs durch einen Sonos Controller aktualisiert werden, und auf die man mit einem Notify reagieren kann, um z.B. ein "get player FavouritesWithCovers" ausführen zu können. Damit entfällt die Notwendigkeit von zeitgesteuerten Aktualisierungen.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 14.04.2015
|
*Zusätzliche Fehlerüberprüfung und -ausgabe beim Herunterladen der Cover-Bilder eingebaut, sowie relative URLs unterbunden
|-
| colspan="2" style="vertical-align:top;text-align:center" | 07.04.2015
|
*Neues Feature 'ExportSonosBibliothek': Hiermit kann eine Datei mit der textuellen Darstellung eines Struktur- und Titelhashs erzeugt werden, das die komplette Navigationsstruktur aus der Sonos-Bibliothek abbildet. Richtwerte bei ca. 22.000 Titeln auf einem Windows-Server mit Intel Core i5 mit 2.8GHz: Laufzeit: ca. 28Min, Arbeitsspeicher: ca. 1GB, Resultierende Datei: ca. 90MB
*Neues Feature 'DeletePlaylist': Hiermit kann eine Playlist gelöscht werden. Genauso wie bei LoadPlaylist kann man hier URL-Encoded arbeiten, oder einen regulären Ausdruck verwenden
*Neues Feature 'SnoozeAlarm': Hiermit kann ein gerade abspielender Alarm für die übergebene Zeit unterbrochen werden
*Neues Feature bei 'LoadPlaylist': Man kann nun einen Devicenamen angeben, dann wird dessen aktuelle Abspielliste kopiert
*Bei der Titelanzeige wird der Numerische Vergleichsfehler abgefangen, der auftritt, wenn der Player keinerlei aktuelle Abspielinformationen hat
|-
| colspan="2" style="vertical-align:top;text-align:center" | 03.04.2015
|
*IsAlive-Check Anpassungen: Bei einer Antwort wird nun nicht mehr geprüft, ob diese von derselben Netzwerkschnittstelle stammt, an die der Ping gesendet wurde. Damit werden Player besser erkannt, die sowohl am Funknetz als auch am LAN angeschlossen sind.
*IsAlive-Check Anpassungen: Bei der Option 'tcp' wird nun versucht auf den Standard-Webport des Players zu verbinden (1400)
*Callback-Aufrufmethoden: Wenn ein Player eine Nachricht an FHEM sendet und dieser Player in FHEM als 'disappeared' geführt wird, dann wird der Discovery-Process neu angestartet, um diesen Player wieder sauber zu erkennen
*Sonos hat das Verfahren zum Hinzufügen von Spotify-Titeln angepasst. Jetzt kann man diese Titel auch wieder mit dem Modul einfügen und abspielen lassen
*Das Heraussuchen der Spotify-Cover (z.B. für Playlisten) schlug fehl, wenn die API kein Bild mit 640er Höhe angeboten hat. Nun wird das erste Cover verwendet, welches immer das größte sein sollte
|-
| colspan="2" style="vertical-align:top;text-align:center" | 28.03.2015
|
*Die Wiederholungsintervalle (Tage) von Alarmen werden wieder korrekt erkannt, und gesetzt
*Bei PlaylistWithCovers wird nun auch ein Cover angezeigt, wenn der erste Titel ein Spotify-Titel ist
|-
| colspan="2" style="vertical-align:top;text-align:center" | 28.02.2015
|
*Der Speak-Befehl kann jetzt auch eingeschobene MP3-Datei-Verweise verarbeiten. Diese werden im Text mit "|" eingeschlossen, und mit Leerzeichen abgetrennt. z.B.: "Dies ist ein |/path/to/tada.mp3| Test.". Funktioniert nur bei "Speak" (und nicht bei eigenen Programmaufrufen wie "Speak1")
*Es gibt für die einfachere Handhabung der neuen Speakmöglichkeiten zwei neue Attribute "targetSpeakMP3FileDir" und "targetSpeakMP3FileConverter". Mit "targetSpeakMP3FileDir" kann ein Standardverzeichnis für die eingschobenen MP3-Dateien angegeben werden, und mit "targetSpeakMP3FileConverter" kann ein MP3-Konverter definiert werden, der am Ende die zusammengebaute Durchsage-MP3-Datei nochmal sauber durchkodiert (um z.B. Restzeitanzeigeprobleme zu beheben).
*Beim internen Entfernen der Player-Objekte (wenn z.B. die Subscription nicht erneuert werden konnte), werden nun alle Referenzen entfernt. Teilweise wurden Subscription-Referenzen noch aufbewahrt.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 19.02.2015
|
*Das Attribut "verbose" am Sonos-Device wird nun zur Laufzeit an den SubProzess übertragen und wirkt dort sofort.
*Beim initialen Erkennen der wichtigsten Abspielparameter während des Discover-Prozesses gab es einen Fehler, der das Setzen verhindert hat
|-
| colspan="2" style="vertical-align:top;text-align:center" | 14.02.2015
|
*Festen Lib-Pfad für Synology-Stations hinzugefügt.
*Im Modul 21_SONOSPLAYER wurde ein require auf das Modul 00_SONOS eingefügt.
*Es gibt jetzt einen neuen Setter "ResetAttributesToDefault", mit dem man die Attribute eines Devices auf den Standard beim Anlegen zurücksetzen lassen kann. Die notwendigen Informationen werden frisch vom Player angefordert, und können sich somit, auf den ursprünglichen Anlege-Zeitpunkt bezogen, verändert haben.
*Ein Fehler bei der Verarbeitung von Devicebeschreibungen wurde in der Datei "Common.pm" des UPnP-Moduls behoben.
*Es gibt jetzt zwei neue Readings "GroupVolume" und "GroupMute", die automatisch aktualisiert werden. Damit passt jetzt auch die Anzeige des Slider beim Setter "GroupVolume" und die Vorauswahl beim Setter "GroupMute".
*Fehlermeldungen für Speak wurden erweitert.
*Bei der Verwendung von "targetSpeakFileHashCache" wird nun auch Digest::SHA versucht, wenn Digest::SHA1 nicht funktioniert.
*Es gibt zwei neue Reading "currentTrackProvider" und "nextTrackProvider", in dem die 'Quelle' der aktuellen (bzw. nächsten) Wiedergabe abgelegt wird. Damit kann man sich Anzeigen lassen, ob der aktuelle Titel z.B. von Spotify oder aus der hausinternen Bibliothek kommt.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 06.02.2015
|
*Der Getter "EthernetPortStatus" hat jetzt auch die Portnummern 2 und 3 zur Auswahl.
*Es gibt ein neues Reading "OutputFixed" sowie ein zugehöriger Setter zum Setzen des Wertes.
*Es wurde im Standard-RemoteControl-Design ein :blank zwischen den Steuerbefehlen und den drei Umschaltbefehlen ("MuteT", "ShuffleT" und "RepeatT") eingefügt.
*Es gibt ein neues Reading "roomNameAlias", das den Namen enthält, der für das Attribut "alias" beim Erkennen des Players verwendet werden würde (z.B. "Wohnzimmer - Rechts"). Wird zu Laufzeit mit aktualisiert.
*Es gibt zwei neue Setter-Befehle "LoadSearchlist" und "StartSearchlist". Mit diesen kann eine dynamisch erzeugte Playliste mit Titeln aus der Sonos-Bibliothek geladen werden. Nähere Informationen dazu im Wiki.
*Es gibt einen neuen Getter-Befehl "SearchlistCategories", mit dem die möglichen Kategorien für den Aufruf von "LoadSearchlist" oder "StartSearchlist" ermittelt werden können.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 01.02.2015
|
*Es gibt nun zwei neue Befehle "ShuffleT" und "RepeatT", die jeweils den aktuellen Zustand von "Shuffle" und "Repeat" umschalten
*Das angelegte RemoteControl sowie die RemoteControl Vorlagen enthalten nun zwei neue Icons für Shuffle-Umschaltung und Repeat-Umschaltung
|-
| colspan="2" style="vertical-align:top;text-align:center" | 31.01.2015
|
*Es gibt jetzt drei Sonos-Vorlagen für RemoteControl: "Sonos", "SonosSVG_Buttons" und "SonosSVG_Icons".
*Es gibt jetzt ein neues Standardlayout (SonosSVG_Buttons) für die Erzeugung der RemoteControl.
*Es gibt jetzt ein Attribut "ignoredIPs", mit dem man problematische oder unerwünschte IPs bei der UPnP-Erkennung ausschließen kann.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 30.01.2015
|
*Commandref wurde optisch übersichtlicher gestaltet, und die Windows-Hinweise eingefügt.
*Bei der Anzeige des nächsten Titels in der Standard-ReadingsGroup stand "Artist". Das wurde auf "Interpret" korrigiert.
*Es gibt jetzt eine Prozedur "SONOSPLAYER_GetSlavePlayerNames()", mit der man sich die Teilnehmer einer Gruppe liefern lassen kann. Der Master wird nicht mit zurückgegeben. Man kann den Namen eines beliebigen Teilnehmers angeben.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 27.01.2015
|
*Bei den Befehlen "AddMember", "RemoveMember" und "CreateStereoPair" werden nun alle in FHEM verfügbaren Sonosplayer in einer Auswahl angeboten. Das erfolgt allerdings ungeachtet der Gültigkeit eines Players in diesem Kontext (z.B. kann man keinen Player aus der Gruppe entfernen, der nicht in der Gruppe ist, die Auswahl bietet aber alle an).
*Es gibt jetzt eine Prozedur "SONOSPLAYER_GetMasterPlayerName()" mit der man sich den Devicenamen des Masterplayer zu dem übergebenen Playernamen geben lassen kann.
*Es gibt einen neuen Setter "Mute" am Sonos-Device. Damit kann man mit einem Schritt bei allen Playern den Mute-Zustand setzen.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 26.01.2015
|
*Beim Setzen von "disable" am Sonos-Device wurde der "state" und "STATE" der Player nicht korrekt gesetzt.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 24.01.2015
|
*Wenn man seine Player umbenannt hatte, wurde ein Attribut-Kommando (für das Model-Attribut) falsch aufgerufen und hat eine Fehlermeldung im FHEM-Log verursacht (z.B. "Please define Sonos_Wohnzimmer first")
|-
| colspan="2" style="vertical-align:top;text-align:center" | 19.01.2015
|
*Verweise auf die "alte" Wikiseite "Sonos Anwendungsbeispiel" in der commandref durch die "neue" Seite "SONOS" ersetzt.
*Wenn kein Pingtype definiert wurde, dann wurde fälschlicherweise nicht der Standard "syn" verwendet, sondern "none"
|-
| colspan="2" style="vertical-align:top;text-align:center" | 16.01.2015
|
*Speak hatte eine fehlerhafte Überprüfung der Attribute, und konnte nicht ausgeführt werden.
*Bei Streams wird das Reading "currentTrackPosition" nun fest auf "0:00:00" gesetzt, und nicht mehr beim Player angefragt
|-
| colspan="2" style="vertical-align:top;text-align:center" | 15.01.2015
|
*Für die Setter "LoadPlaylist", "StartPlaylist", "LoadRadio", "StartRadio" und "StartFavourite" kann man jetzt anstatt des Namens einen regulären Ausdruck verwenden.
*Beim Erkennen der Player werden einige Abspielreadings ("transportState", "currentTrackURI", "currentTrackDuration", "currentTrackPosition", "currentTrack", "numberOfTracks", "currentStreamAudio" und "currentNormalAudio") nun direkt abgeholt, und werden somit aktuell korrekt gesetzt.
*Beim Anlegen der neuen Devices werden die Aliasnamen nun mit der Funktion im Team erweitert
*Der Mechanismus zum Starten des SubProzesses wurde angepasst, um auf Synology-Begebenheiten Rücksicht zu nehmen
*Die Coverdarstellung für einige Spotify-Titel wurde korrigiert, indem eine andere Spotify-API verwendet wird
*Bei Playlist-Covern wird nun das Cover des ersten Titels mit AlbumArt angezeigt
*Bei Favourite-Covern werden nun Album-Favoriten auch mit Cover dargestellt (das Cover des ersten Titels mit AlbumArt)
*Ein Album aus der lokalen Bibliothek konnte mittels "StartFavourite" nicht korrekt gestartet werden (es wurde nicht als Liste übertragen, sondern als Titel gestartet)
*LogLevel für die "Connection accepted"-Meldungen auf 3 hochgesetzt
*Es gibt jetzt ein Attribut "disable" am Sonos-Device. Wird es auf 1 gesetzt, wird der SubProzess beendet und verarbeitet somit keine Sonos-Nachrichten mehr. Wird es auf 0 gesetzt (oder gelöscht), wird der SubProzess wieder gestartet.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 08.01.2015
|
*Bei der Wiedergabeanweisung "PlayURI" gab es einen Fehler
|-
| colspan="2" style="vertical-align:top;text-align:center" | 05.01.2015
|
*Die Cover beim Abspielen "von diesem Gerät" (also iPad, oder Android-Tablet) wurden nicht angezeigt.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 04.01.2015
|
*Bei der Ermittlung des Readings "AlbumArtist" gab es einen Fehler, wenn dieser von Sonos nicht übermittelt wurde.
*Wenn ein Player einen Dock (iPod) wiedergibt, dann werden die Titelinformationen dort mitgesetzt. Damit entfällt die Anzeige des Titels z.B. mit 'iPod von Reinerlein'.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 03.01.2015
|
*Dokumentation angepasst (commandref und Installationsdoku im Dateiheader)
*Fehler bei der Dockbehandlung behoben
|-
| colspan="2" style="vertical-align:top;text-align:center" | 02.01.2015
|
*Anzeige bei der Wiedergabe eines Docks verbessert. Dort werden nun der Titel und Album/Artist-Informationen und ein Dock-Cover angezeigt.
*Getter/Setter bei Bedarf um ":noArg" erweitert.
*Getter/Setter sind nun nicht mehr CaseSensitive
*Getter/Setter habe nun soweit möglich eine Auswahlliste der möglichen Werte (alle on/off Setter, sowie Wifi und RoomIcon)
*Setter für "Treble" und "Bass" haben nun auch einen Slider
*Setter "Icon" in "RoomIcon" umbenannt, damit die Auswahlliste den aktuellen vorauswählt
*Beim Erzeugen der Sonosplayer-Devices wird nun das Attribut "alias" auf den Sonos-Raumnamen gesetzt.
*Zusätzlich zu "StopAll" oder "PauseAll" gibt es am Sonos-Device nun auch "Stop" und "Pause" mit der gleichen Funktionalität
|-
| colspan="2" style="vertical-align:top;text-align:center" | 01.01.2015
|
*Anzeige in der Player-ReadingsGroup für die Darstellung von disappeared angepasst, dabei auch gleich die Höhenverhältnisse etwas angepasst.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 31.12.2014
|
*Das Bilden von Stereopaaren wird nun unterstützt. Dafür gibt es die Anweisungen 'CreateStereoPair' und 'SeparateStereoPair' an einem Playerdevice.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 28.12.2014
|
*Umlaute: Die Erkennung von Umlauten war wegen der Quelltextumstellung auf UTF8 fehlerhaft. Das betraf nur die Zonennamenumwandlung, wo z.B. aus 'Küche' ein 'Kueche' gemacht wird.
*Sonos-Coverlieferung: Es waren noch ein paar Return-Anweisungen zuviel drin.
|-
| colspan="2" style="vertical-align:top;text-align:center" | 26.12.2014
|
*DeleteFn für Sonos wurde implementiert. Das Sonos-Device löscht erst alle SonosPlayer-Devices und beendet den selbst gestarteten SubProzess. Danach wird das Sonos-Device selber von FHEM abgeräumt.
*DeleteFn für SonosPlayer wurde implementiert. Es werden erst alle automatisch erzeugten Devices (RemoteControl und ReadingsGroups) entfernt, sofern sie noch unter dem Originalnamen existieren.
*ReportUnresponsiveDevice hat manchmal versucht, die Mitteilung an "sich selbst" zu senden, was naturgemäß nicht klappen kann.
|-
| colspan="3" style="vertical-align:top" | Versionen von fhem.lmsoft.de
|-
| style="vertical-align:top;text-align:center" | 17.12.2014
| style="vertical-align:top;text-align:center" | 2.6
|
*Die Zeichenkodierung bei Datenübernahme vom Zoneplayer kann nun über das Attribut characterDecoding eingestellt werden
*Bei Gruppen-/LineIn-/SPDIF-Wiedergabe wird wieder die liefernde Zone angezeigt (als Albumname)
*SetCurrentPlaylist hatte einen Tippfehler, und konnte dementsprechend nicht ausgeführt werden
*Unter Ubuntu gibt es die SHA1-Library nicht mehr, sodass man dort eine andere einbinden muss (SHA)
*Wenn bei den Methoden zum heraussuchen der FHEM-Devices etwas nicht gefunden wurde, dann wird jetzt eine Fehlermeldung mit dem gesuchten Merkmal ausgegeben
*Es können jetzt IP-Adressen von der UPnP-Verarbeitung ausgeschlossen werden
*Es wird nun ein fester Mimetype 'jpg' für Google Music und Simfy festgelegt
*Beim Alarm-Reading-Setzen wurde etwas doppelt gesetzt, was u.U. zu Fehlern führen konnte
*Die Read-Function wurde robuster gegen Übertragungsprobleme gemacht
*Das Wiederherstellen des Playerzustands nach einem PlayURITemp sieht nun auch den PlayBar-Eingang vor
*Es wird nun anstatt der WebCmd-Auflistung ein RemoteControl beim Erstellen der Komponenten erzeugt
*Wenn sich doch noch ein UPnP-Device als Player ausgibt, dann wird dies nun etwas sicherer erkannt
*Der Eingang einer Playbar kann nun auf anderen Playern wiedergegeben werden (mittels des FHEM-Namens)
*Lesen wurde auf DevIo_SimpleRead umgestellt (stand auf DevIo_DoSimpleRead). Dadurch wird das Fehlerhandling vereinfacht.
*Man kann die Zeit für das Warten auf den Subprozess nun beim Define mit angeben. Standardmäßig wird 8 verwendet.
*Es wird nun in regelmäßigen Abständen (Intervall wie bei der Prüfung der Sonosplayer) geprüft, ob die Verbindung zum Subprozess noch funktioniert
*Die Readings, die beim Start nicht geladen werden dürfen, werden beim Start von FHEM nun initialisiert. Damit wird die Fehlermeldung in MOTD verhindert
*Der Zeitstempel in der Konsolenausgabe berücksichtigt nun auch die Global-Angabe, ob Millisekunden mit ausgegeben werden sollen
*Der Start wurde komplett überarbeitet. Nun sind die einzelnen Wartebereiche in Timer ausgelagert, sodass FHEM nicht mit warten blockiert wird.
*Die Wiederherstellung des alten Playerzustands nach einem PlayURITemp (und damit auch bei Speak) wird nun auch bei Dateien gemacht, die mit 0s Dauer ermittelt werden (da sie sehr kurz sind).
*Der Aufruf der Google Text2Speech-Engine wird nun bei mehr als 95 Zeichen in mehrere Aufrufe aufgeteilt. Damit sind nun auch lange Texte über Google möglich, allerdings geht die Textmelodie u.U. verloren.
*Man kann jetzt für die Speak-Erzeugung ein JPG- oder PNG-Bild angeben. Dies kann für jedes Speak-Programm getrennt erfolgen.
*Beim Speak-Aufruf werden Umlaute nun auch korrekt an den Text2Speech-Generator (z.B. Google) übergeben, und korrekt in den MP3-Tag geschrieben
*Spotify-Cover werden nun in größerer Auflösung (meist 640x640 Pixel) direkt von Spotify heruntergeladen, und enthalten dann nicht mehr das Spotify-Logo
*Es gibt zwei neue Readings 'AlbumArtURL' und 'nextAlbumArtURL', die die Originalpfade zum eigenen Download darstellen
*Es gibt nun zwei Prozeduren, die als Grundlage oder Beispiel für die Verwendung von ReadingsGroups dienen können: 'SONOS_getTitleRG' und 'SONOS_getCoverRG'
*Beim automatischen Erzeugen der Sonos-Devices werden nun ReadingsGroups mit mehr Informationen erzeugt. Dies kann (und soll) auch als Vorlage für eigene Ideen Verwendet werden
*Es gibt eine weitere ReadingsGroup-Vorlage (steht auch im Wiki), mit der Listen (Playlisten, Favoriten und Radios) dargestellt werden können
*Es gibt zwei neue Attribute "proxyCacheTime" und "proxyCacheDir", die einen Cache im Proxy aktivieren
*Es gibt drei neue Getter am Sonosplayer-Device: "FavouritesWithCover", "PlaylistsWithCover" und "RadiosWithCovers". Diese geben eine Datenstruktur zurück, die den Titel und das Cover des Elements enthält.
*Die Prozeduren für die Anzeige des aktuellen und nächsten Titels verwenden nun ausschließlich DIV-Container (anstatt Tabellen). Dadurch klappt die Anzeige auch in einem Dashboard.
*Die Standard-ReadingsGroup-Anzeige durch die Prozeduren sind nun Parametrisiert. Man kann die minimale Breite der Anzeige sowie den Abstand zwischen aktuellem und nächstem Titel in Pixel festlegen
*Manche Sender (z.B. Capital Radio Türkiye) haben verbotene Newlines in den Titelinformationen mitgesendet. Diese werden nun entfernt.
*Man kann das Cover nun anklicken (oder antippen), und erhält dann die Coverdarstellung in einer Vollbilddarstellung mit Abspielstatus und Titelinformationen
*Es gibt zwei neue Befehle 'StartPlaylist' und 'StartRadio', die die gleichen Parameter wie ihre Pendants mit 'Load' am Anfang haben, nur dass hier das Abspielen gleich gestartet wird.
*Es gibt jetzt ein Reading 'currentTrackPosition', welches bei jedem Transportstate-Wechsel (neuer Titel, Play/Pause/Stop usw.) gesetzt wird. Damit kann man die verbleibende Restzeit eines laufenden Titels ermitteln, bzw. den Pausezeitpunkt anzeigen.
*Beim Wiedergeben von TV oder sonstigen externen Quellen, wird jetzt nicht mehr das 'leere' Cover angezeigt, sondern ein TV-Cover bzw. ein Default-Input-Cover
*Aufnahme in das offizielle Release von FHEM
|-
| style="vertical-align:top;text-align:center" | 07.03.2014
| style="vertical-align:top;text-align:center" | 2.5
|
*Verwendung und Speicherung der Benutzer-IDs für Spotify und Napster wurden stabiler gegenüber Sonderzeichen gemacht
*Spotify-URLs werden im Reading 'currentTrackURI' und 'nextTrackURI' lesbarer abgelegt
*Ein Fehler beim Öffnen von M3U-Playlistdateien wurde behoben (dafür Danke an John)
*Überholt: Für die Informationsanfragen an FHEM durch den SubProzess wird nun standardmäßig der Telnet-Port von FHEM verwendet. Wenn das fehlschlägt, wird auf den alten Mechanismus zurückgeschaltet
*Neu: Es werden keine Informationsanfragen mehr zwischen FHEM und dem SubProzess ausgetauscht. Notwendige Informationen müssen vorher übertragen werden. Das bedeutet, dass bei einer Attributänderung ein Neustart von FHEM erfolgen muss.
*Es wurde ein Standard-Layout für das RemoteControl-Hilfsmodul angelegt
*Der Verbose-Level des Sonos-Devices wird nun auch an den SubProzess weitergereicht (auch zur Laufzeit), und beim initialen Start des SubProzess-Threads mitgegeben.
*AlbumArt von Napster erhält nun den festen Mimetype 'jpg', da dieser nicht übertragen wird
*Es werden nun die durch FHEM definierten Standard-Attribute mit angeboten
*Es gab ein Problem mit der Befehlsverarbeitung, wenn das Verbose-Attribut an einem Sonos-Device gesetzt war.
*Es wird nun auf Änderungsevents für den Zonennamen und das Zonenicon reagiert, und die entsprechenden Readings aktualisiert
*Es gibt jetzt zwei neue Setter: 'Name' und 'Icon', mit dem der Name und das Icon der Zone eingestellt werden kann
*Es gibt jetzt einen Getter 'PossibleRoomIcons', welcher die möglichen Angaben für den neuen Setter 'Icon' liefert
*Das Reading 'ZoneGroupID' wird nun auf eine andere Weise ermittelt und gesetzt
*Es gib jetzt ein neues Reading 'AlarmRunning', welches auf '1' steht, wenn gerade eine Alarmabspielung aktiv ist
*Die Namens- und Aufgabenerkennung beim Ermitteln der Player wurde angepasst
*Der Aufruf von AddMember und RemoveMember wurde bzgl. des SonosDevice-Namen abgesichert, sodass hier kein Absturz mehr bei einer falschen Deviceangabe erfolgt
*Es gibt jetzt ein neues Reading 'AlarmRunningID', welches bei einer Alarmausführung die ID des aktiven Alarms enthält
*Das Senden von Aktualisierungen an FHEM wurde etwas sicherer gemacht, wenn FHEM auf der anderen Seite gerade nicht zuhören kann
*Die Readings 'AlarmList', 'AlarmListIDs' und 'AlarmListVersion' werden nicht mehr aus dem Statefile geladen, da dort Sonderzeichen wie '#' zum Abschneiden der restlichen Zeile führen
*Anpassung der UPnP-Klasse, damit das Device-Beschreibungsdokument nur noch einmal geladen wird (anstatt wie bisher zweimal)
*Anpassung im Bereich der Cover Aktualisierung über FHEMWeb. Das geht jetzt mit viel weniger Aufwand durch.
*Es gibt jetzt einen Setter 'SnapshotGroupVolume', der das aktuelle Lautstärkenverhältnis der einzelnen Player einer Gruppe für die folgenden Aufrufe des Setter 'GroupVolume' festhält. Die Anweisungen 'PlayURI' und 'PlayURITemp' (sowie darauf aufbauende Aufrufe wie 'Speak') führen diese Anweisung selbsttätig beim Starten durch.
*Wenn beim Auffrischen der Subscriptions ein Fehler auftritt, der darauf schließen läßt, dass der Player weg ist, dann wird die entsprechende Referenz aufgeräumt
*Man kann als relative Angabe bei setVolume nun einen Prozentwert angeben, z.B. '+20%'. Damit wird die Lautstärke um den jeweiligen prozentualen Anteil erhöht oder abgesenkt.
*Es gibt jetzt ein Reading 'LineInConnected', welches eine '1' enthält, wenn der Line-In-Eingang angeschlossen wurde, sonst '0'.
|-
| style="vertical-align:top;text-align:center" | 31.12.2013
| style="vertical-align:top;text-align:center" | 2.4
|
*Initiale Lautstärkenermittlung wurde nun abgesichert, falls die Anfrage beim Player fehlschlägt
*Verbesserte Gruppenerkennung für die Anzeige der Informationen wie Titel usw.
*Fallback (Log) für den Aufruf von Log3 geschaffen, damit auch alte FHEM-Versionen funktionieren
*Es wurde eine Korrektur im verwendetetn UPnP-Modul gemacht, die eine bessere Verarbeitung der eingehenden Datagramme gewährleistet (dafür Danke an Sacha)
*Es werden nun zusätzliche Readings (beginnend mit 'next') mit den Informationen über den nächsten Titel befüllt. Diese können natürlich auch für InfoSummarize verwendet werden
*Es kann nun ein Eintrag aus der Sonos-Favoritenliste gestartet werden (Playlist oder Direkteintrag)
*Das Benennen der Sonos-FHEM-Devices wird nun auf Namensdoppelungen hin überprüft, und der Name eindeutig gemacht. Dabei wird im Normalfall das neue Reading 'fieldType' an den Namen angehangen. Nur der Master einer solchen Paarung bekommt dann den Original-Raumnamen als FHEM-Devicenamen
*Es gibt ein neues Reading 'fieldType', mit dem man erkennen kann, an welcher Position in einer Paarung dieser Zoneplayer steht
*Diverse Probleme mit Gruppen und Paarungen beim neu Erkennen der Sonos-Landschaft wurden beseitigt
*Es gibt jetzt einen Getter 'EthernetPortStatus', der den Status des gewünschten Ethernet-Ports liefert
*Es gibt jetzt einen Setter 'Reboot', der einen Neustart des Zoneplayers durchführt
*Es gibt jetzt einen Setter 'Wifi', mit dem der Zustand des Wifi-Ports eines Zoneplayers gesetzt werden kann
*Wenn ein Player als "Disappeared" erkannt wird, wird dem Sonos-System dies mitgeteilt, sodass er aus allen Listen und Controllern verschwindet
*Kleinere Korrektur, die eine bessere Verarbeitung der Kommunikation zwischen FHEM und dem Subprozess bewirkt
|-
| style="vertical-align:top;text-align:center" | 02.12.2013
| style="vertical-align:top;text-align:center" | 2.3
|
*Die Antwort von 'SetCurrentPlaylist' wurde korrigiert. Dort kam vorher 'SetToCurrentPlaylist' zurück.
*VolumeStep kann nun auch als Attribut definiert werden. Das fehlte in der zulässigen Liste noch.
*Speak kann nun auch für lokale Binary-Aufrufe konfiguriert werden.
*Speak kann nun einen Hash-Wert auf Basis des gegebenen Textes in den Dateinamen einarbeiten, und diese dann bei Gleichheit wiederverwenden (Caching)
*Sonos kann nun ein "set StopAll" oder "set PauseAll" ausführen, um alle Player/Gruppen auf einen Schlag zu stoppen/pausieren
*Beim Discover-Event wird nun genauer geprüft, ob sich überhaupt ein ZonePlayer gemeldet hat
*Die UserIDs für Napster und Spotify werden wieder korrekt ermittelt. Damit kann auch wieder ein Playlistenimport erfolgen.
*Loudness Einstell- und Abfragbar
*Bass Einstell- und Abfragbar
*Treble Einstell- und Abfragbar
*Volume kann nun auch als RampToVolume ausgeführt werden
|-
| style="vertical-align:top;text-align:center" | 12.10.2013
| style="vertical-align:top;text-align:center" | 2.2
|
*Befehlswarteschlange wieder ausgebaut. Dadurch gibt es nur noch das Reading LastActionResult, und alles wird viel zügiger ausgeführt, da FHEM nicht auf die Ausführung warten muss.
*TempPlaying berücksichtigt nun auch die Wiedergabe von Line-In-Eingängen (also auch Speak)
*Veraltete, mittlerweile unbenutzte, Readings werden nun gelöscht
*SetLEDState wurde hinzugefügt
*Die IsAlive-Überprüfung kann mit 'none' abgeschaltet werden
*CurrentTempPlaying wird nicht mehr benötigt
|-
| style="vertical-align:top;text-align:center" | 23.09.2013
| style="vertical-align:top;text-align:center" | 2.1
|
*Neuen Befehl 'CurrentPlaylist' eingeführt
|-
| style="vertical-align:top;text-align:center" | 15.09.2013
| style="vertical-align:top;text-align:center" | 2.0
|
*Neue Konzeptbasis eingebaut
*Man kann Gruppen auf- und wieder abbauen
*Es gibt neue Lautstärke- und Mute-Einstellungen für Gruppen ingesamt
*Man kann Button-Events definieren
|-
| style="vertical-align:top;text-align:center" | 27.05.2013
| style="vertical-align:top;text-align:center" | 1.13
|
*Neuer Abspielzustand 'TRANSITIONING' wird berücksichtigt
*Der Aufruf von 'GetDeviceDefHash' wird nun mit dem Parameter 'undef' anstatt ohne einen Parameter durchgeführt
|-
| style="vertical-align:top;text-align:center" | 23.05.2013
| style="vertical-align:top;text-align:center" | 1.12
|
*TrackURI hinzugefügt
*LoadPlayList und SavePlayList können nun auch Dateinamen annehmen, um eine M3U-Datei zu erzeugen/als Abspielliste zu laden
*Alarme können ausgelesen, gesetzt und gelöscht werden
*SleepTimer kann gesetzt und ausgelesen werden
*Reading DailyIndexRefreshTime hinzugefügt
*Bei AddURIToQueue und PlayURI können jetzt auch (wie bei LoadPlayList) Spotify und Napster-Ressourcen angegeben werden
*Beim Erzeugen des Cover-Weblinks wird nun nur noch die Breite festgelegt, damit Nicht-Quadratische Cover auch korrekt dargestellt werden
*SONOS_Stringify gibt Strings nun in einfachen Anführungszeichen aus (und maskiert etwaig enthaltene im String selbst)
|-
| style="vertical-align:top;text-align:center" | 10.03.2013
| style="vertical-align:top;text-align:center" | 1.11
|
*Ein Transport-Event-Subscribing wird nur dann gemacht, wenn es auch einen Transport-Service gibt. Die Bridge z.B. hat sowas nicht.
*Bei PlayURITemp wird nun der Mute-Zustand auf UnMute gesetzt, und anschließend wiederhergestellt
*Shuffle, Repeat und CrossfadeMode können nun gesetzt und abgefragt werden. Desweiteren wird der Status beim Transport-Event aktualisiert.
*Umlaute bei "generateInfoSmmarize3" durch "sichere" Schreibweise ersetzt (Lautstärke -> Lautstaerke)
|-
| style="vertical-align:top;text-align:center" | 22.02.2013
| style="vertical-align:top;text-align:center" | 1.10
|
*IsAlive beendet nicht mehr den Thread, wenn der Player nicht mehr erreichbar ist, sondern löscht nur noch die Proxy-Referenzen
*FHEMWEB-Icons werden nur noch im Hauptthread aktualisiert
*Getter 'getBalance' und Setter 'setBalance' eingeführt.
*HeadphoneConnected inkl. minVolumeHeadphone und maxVolumeHeadphone eingeführt
*InfoSummarize um die Möglichkeit der Volume/Balance/HeadphoneConnected-Felder erweitert. Außerdem werden diese Info-Felder nun auch bei einem Volume-Event neu berechnet (und triggern bei Bedarf auch!)
*InfoSummarize-Features erweitert: 'instead' und 'emptyval' hinzugefügt
*IsAlive prüft nicht mehr bei jedem Durchgang bis zum Thread runter, ob die Subscriptions erneuert werden müssen
|-
| style="vertical-align:top;text-align:center" | 16.02.2013
| style="vertical-align:top;text-align:center" | 1.9
|
*RTL.it Informationen werden nun schöner dargestellt (Da steht eine XML-Struktur im Titel)
*Wenn kein Cover vom Sonos geliefert werden kann, wird das FHEM-Logo als Standard verwendet (da dieses sowieso auf dem Rechner vorliegt)
*UPnP-Fehlermeldungen eingebaut, um bei einer Nichtausführung nähere Informationen erhalten zu können
|-
| style="vertical-align:top;text-align:center" | 13.02.2013
| style="vertical-align:top;text-align:center" | 1.8
|
*Device-Removed wird nun sicher ausgeführt. Manchmal bekommt man wohl deviceRemoved-Events ohne ein vorheriges deviceAdded-Event. Dann gibt es die gesuchte Referenz nicht.
*Renew-Subscriptions wurden zu spät ausgeführt. Da war alles schon abgelaufen, und konnte nicht mehr verlängert werden.
*ZonePlayer-Icon wird nun immer beim Discover-Event heruntergeladen. Damit wird es auch wieder aktualisiert, wenn FHEM das Icon beim Update verwirft.
*MinVolume und MaxVolume eingeführt. Damit kann nun der Lautstärkeregelbereich der ZonePlayer festgelegt werden
*Umlaute beim Übertragen in das Reading State werden wieder korrekt übertragen. Das Problem waren die etwaigen doppelten Anführungsstriche. Diese werden nun maskiert.
*Sonos Docks werden nun auch erkannt. Dieses hat eine andere Device-Struktur, weswegen der Erkennungsprozess angepasst werden musste.
|-
| style="vertical-align:top;text-align:center" | 04.02.2013
| style="vertical-align:top;text-align:center" | 1.7
|
*Umlaute werden bei Playernamen beim Anlegen des Devices korrekt umgewandelt, und nicht in Unterstriche
*Renew-Subscription eingebaut, damit ein Player nicht die Verbindung zum Modul verliert
*CurrentTempPlaying wird nun auch sauber beim Abbrechen des Restore-Vorgangs zurückgesetzt
*Die Discovermechanik umgebaut, damit dieser Thread nach einem Discover nicht neu erzeugt werden muss.
|-
| style="vertical-align:top;text-align:center" | 30.01.2013
| style="vertical-align:top;text-align:center" | 1.6
|
*Speak hinzugefügt (siehe Doku im Wiki)
*Korrektur von PlayURITemp für Dateien, für die Sonos keine Abspiellänge zur Verfügung stellt
*Korrektur des Thread-Problems welches unter *Nix-Varianten auftrat (Windows war nicht betroffen)
|-
| style="vertical-align:top;text-align:center" | 29.01.2013
| style="vertical-align:top;text-align:center" | 1.5
|
*PlayURI, PlayURITemp und AddURIToQueue hinzugefügt (siehe Doku im Wiki)
|-
| style="vertical-align:top;text-align:center" | 28.01.2013
| style="vertical-align:top;text-align:center" | 1.4
|
*Exception-Handling bei der Befehlsausführung soll FHEM besser vor verschwundenen Playern schützen
*Variable $SONOS_ThisThreadEnded sichert die korrekte Beendigung des vorhandenen Threads, trotz Discover-Events in der Pipeline
*Einrückungen im Code korrigiert
|-
| style="vertical-align:top;text-align:center" | 26.01.2013
| style="vertical-align:top;text-align:center" | 1.3
|
*StopHandling prüft nun auch, ob die Referenz noch existiert
|-
| style="vertical-align:top;text-align:center" | 24.01.2013
| style="vertical-align:top;text-align:center" | 1.2
|
*Proxy-Objekte werden beim Disappearen des Player entfernt, und sorgen bei einem nachfolgenden Aufruf für eine saubere Fehlermeldung
*Probleme mit Anführungszeichen " in Liedtiteln und Artist-Angaben. Diese Zeichen werden nun ersetzt
*Weblink wurde mit fehlendem "/" am Anfang angelegt. Dadurch hat dieser nicht im Floorplan funktionert
*pingType wird nun auf Korrektheit geprüft.
*Play:3 haben keinen Audio-Eingang, deshalb funktioniert das Holen eines Proxy dafür auch nicht. Jetzt ist das Holen abgesichert.
|-
| style="vertical-align:top;text-align:center" | 18.01.2013
| style="vertical-align:top;text-align:center" | 1.1
|
*Ping-Methode einstellbar über Attribut 'pingType'
|-
| style="vertical-align:top;text-align:center" | 16.01.2013
| style="vertical-align:top;text-align:center" | 1.0
|
*Initial Release
|}

== Modul '''SONOS''' ==
Dieses Modul erledigt die eigentliche Kommunikationsarbeit zu den ZonePlayern mittles UPnP.
Es startet (und läßt ihn dauerhaft laufen) einen Discovery Prozess, der alle ZonePlayer auffordert, sich zu melden, und reagiert auf entsprechende Signalisierungen.
Es instantiiert einen Listener und meldet diesen bei allen ZonePlayern für Abspielaktualisierungen an.

Wenn ein Aufruf des Discovery-Prozesses erfolgt, wird geprüft, ob der Player bereits definiert wurde. Wenn nicht, wird eine Definition erzeugt, wenn ja, dann wird die Komponente mit den neu erhaltenen Informationen aktualisiert.

Wenn ein Aufruf der Abspielaktualisierung erfolgt, so wird die entsprechene Zoneplayer-Komponente in FHEM mit den neu erhaltenen Informationen aktualisiert, und entsprechende FHEM-Events generiert.

Wenn das Feature mit <code>minVolume</code> oder <code>maxVolume</code> verwendet wird, wird ein weiterer Listener beim entsprechenden Zoneplayer angemeldet. Mittels diesem werden Lautstärkenänderungen am Zoneplayer gemeldet umd können entsprechend umgehend korrigiert werden.<br >Als Nebeneffekt wird für jede Lautstärkenänderung auch ein Event in FHEM erzeugt (als Folge einer Aktualisierung des Readings <code>Volume</code>).

=== Readings von SONOS ===
*<code>AllPlayer</code>: Enthält alle Player.
*<code>AllPlayerCount</code>: Enthält die Anzahl der Player in "AllPlayer".
*<code>AllPlayerNotBonded</code>: Enhtält alle Masterplayer, die nicht gebunden sind (also keine Stereo- oder Satellitenteilnehmer sind).
*<code>AllPlayerNotBondedCount</code>: Enhtält die Anzahl der Player in "AllPlayerNotBonded".
*<code>LastProcessAnswer</code>: Enthält den letzten Zeitpunkt einer Datenübertragung vom SubProzess zum FHEM-Modul.
*<code>LastProcessRestart</code>: Enthält (falls vorhanden) den Zeitpunkt des letzten Neustarts des SubProzesses.
*<code>LastProcessRestartCount</code>: Enthält (falls vorhanden) die Anzahl der durchgeführten Neustarts des SubProzesses.
*<code>LineInPlayer</code>: Enthält die gültigen LineIn-Eingänge aller Player, die für die Wiedergabe ausgewählt werden können als visualisiertes Perl-Array.
*<code>LineInPlayerList</code>: Enthält die gültigen LineIn-Eingänge aller Player, die für die Wiedergabe ausgewählt werden können als "|"-separierte Liste von Devicenamen, wenn das Attribut "" am Sonos-Device angegeben ist.
*<code>LineInPlayerListAlias</code>: Enthält die gültigen LineIn-Eingänge aller Player, die für die Wiedergabe ausgewählt werden können als "|"-separierte Liste von Raumnamen, wenn das Attribut "" am Sonos-Device angegeben ist.
*<code>MasterPlayer</code>: Hier werden alle Masterplayer in einer per eval zu einem Array umwandelbaren Liste angegeben. z.B.: ['Sonos_Kueche','Sonos_Flur']
*<code>MasterPlayerCount</code>: Hier wird die Anzahl der erkannten Masterplayer angegeben. z.B.: 2
*<code>MasterPlayerNotPlaying</code>: Hier werden alle Masterplayer in einer per eval zu einem Array umwandelbaren Liste angegeben, die gerade keine laufende Wiedergabe haben. z.B.: ['Sonos_Kueche']
*<code>MasterPlayerNotPlayingCount</code>: Hier wird die Anzahl der nicht abspielenden Masterplayer angegeben. z.B.: 1
*<code>MasterPlayerPlaying</code>: Hier werden alle Masterplayer in einer per eval zu einem Array umwandelbaren Liste angegeben, die gerade eine laufende Wiedergabe haben. z.B.: ['Sonos_Flur']
*<code>MasterPlayerPlayingCount</code>: Hier wird die Anzahl der abspielenden Masterplayer angegeben. z.B.: 1
*<code>QueueHash</code>: Der Hash-Wert für die aktuelle Abspielliste. Dieser wird bei jeder Änderung der aktuellen Abspielliste aktualisiert.
*<code>ShareIndexInProgress</code>: Gibt an, ob gerade eine Aktualisierung des Indexes der Freigaben erfolgt.
*<code>UserId_Napster</code>: Speichert die UserId für den Napster-Zugriff. Diese Information ist notwendig, wenn eine M3U-Datei mit Napster-Titeln importiert werden soll, und wird automatisch ermittelt, sobald man mit dem Original-Controller einen einzelnen Titel aus Napster in die aktuelle Abspielliste überträgt.
*<code>UserId_Spotify</code>: Speichert die UserId für den Spotify-Zugriff. Diese Information ist notwendig, wenn eine M3U-Datei mit Spotify-Titeln importiert werden soll, und wird automatisch ermittelt, sobald man mit dem Original-Controller einen einzelnen Titel aus Spotify in die aktuelle Abspielliste überträgt.
*<code>ZoneGroupState</code>: Die Konfigurationsinformationen zu der aktuellen Gruppenlandschaft der Zoneplayer. Der Befehl <code>get SONOS Groups</code> vereinfacht den Zugriff hierauf, indem es eine einfach les- und verarbeitbare Liste erzeugt.

=== Attribute von SONOS ===
'''Hinweis'''<br />Die Attribute werden (bis auf <code>verbose</code> und <code>disable</code>) erst bei einem Neustart von FHEM verwendet, da diese dem SubProzess initial zur Verfügung gestellt werden müssen.

*Grundsätzliches
**<code>coverLoadTimeout(0..10,15,20,25,30)</code>: Definiert den Timeout der für die Abfrage des Covers beim Sonosplayer verwendet wird. Wenn nicht angegeben, dann wird 5 verwendet.
**<code>deviceRoomView(Both,DeviceLineOnly)</code>: Gibt an, was in der Raumansicht zum Sonosplayer-Device angezeigt werden soll. <code>Both</code> bedeutet "normale" Devicezeile zzgl. Cover-/Titelanzeige und u.U. Steuerbereich, <code>DeviceLineOnly</code> bedeutet nur die Anzeige der "normalen" Devicezeile.
**<code>disable(0,1)</code>: Hiermit kann das Modul abgeschaltet werden. Wirkt sofort. Bei 1 wird der SubProzess beendet, und somit keine weitere Verarbeitung durchgeführt. Bei 0 wird der Prozess wieder gestartet.<br />Damit kann das Modul temporär abgeschaltet werden, um bei der Neueinrichtung von Sonos-Komponenten keine halben Zustände mitzubekommen.<br />Des Weiteren kann man damit Attribut-Änderungen an den SubProzess weiterreichen, da ja ein neuer Prozess gestartet wird, dem natürlich zu Beginn wieder alle verfügbaren/notwendigen Attribute zur Verfügung gestellt werden.
**<code>getFavouritesListAtNewVersion(0,1)</code>: Mit diesem Attribut kann das Modul aufgefordert werden, die Favoriten (bei definiertem Attribut <code>getListsDirectlyToReadings</code>) bei Aktualisierung automatisch herunterzuladen.
**<code>getPlaylistsListAtNewVersion(0,1)</code>: Mit diesem Attribut kann das Modul aufgefordert werden, die Playlisten (bei definiertem Attribut <code>getListsDirectlyToReadings</code>) bei Aktualisierung automatisch herunterzuladen.
**<code>getQueueListAtNewVersion <value></code>: Mit diesem Attribut kann das Modul aufgefordert werden, die aktuelle Abspielliste (bei definiertem Attribut <code>getListsDirectlyToReadings</code>) bei Aktualisierung automatisch herunterzuladen.
**<code>getRadiosListAtNewVersion <value></code>: Mit diesem Attribut kann das Modul aufgefordert werden, die Radioliste (bei definiertem Attribut <code>getListsDirectlyToReadings</code>) bei Aktualisierung automatisch herunterzuladen.
**<code>getListsDirectlyToReadings(0,1)</code>: Mit diesem Attribut kann das Modul aufgefordert werden, die Listen für Favoriten, Playlists, Radios und Queue direkt in die entsprechenden Readings zu schreiben. Dafür sind dann keine Userreadings mehr notwendig.
**<code>getLocalCoverArt(0,1)</code>: Mit diesem Attribut kann das Modul aufgefordert werden, die Cover lokal herunterzuladen (bisheriges Standardverhalten).
**<code>ignoredIPs</code>: Mit diesem Attribut können IP-Adressen angegeben werden, die vom UPnP-System ignoriert werden sollen. Z.B.: '''192.168.0.11,192.168.0.37'''. Es sind auch reguläre Ausdrücke pro Element zulässig. Diese dürfen nur keine Kommata oder Doppelpunkte enthalten. Z.B: '''/192.168.0.(1|2|3)/,/192.168.1.\d*/'''. Alle Meldungen und Benachrichtigungen von den angegebenen IP-Adressen werden ignoriert.<br />'''Hinweis''': Dieses Attribut kann hilfreich sein, wenn sich falsche UPnP-Devices melden, obwohl nur Sonos-Devices angefragt waren. Manchmal passiert das mit irgendwelchen NAS oder sonstigen Serverdevices.<br />Folgende Meldungen (z.B.) sind ein Indiz auf falsche Devices: <code>Loading device description failed with error: 500 Can't connect to 192.168.2.29:2869 (timeout) at ./FHEM/00_SONOS.pm line xx thread 1</code>, wenn die angegebene IP-Adresse gar kein Sonos-Devices ist.
**<code>pingType(none,tcp,udp,icmp,syn)</code>: Definiert die Art, wie der Alive-Check eines Zoneplayers erfolgen soll. Die Verfahren funktionieren unterschiedlich gut. Am Ressourcensparsamsten ist ''icmp'', benötigt aber "<code>root</code>"-Rechte. An zweiter Stelle ist ''syn'' zu empfehlen. Die anderen Verfahren melden manchmal fehlerhafte not alives. Einfach probieren. Mittels ''none'' kann dieser Mechanismus auch deaktiviert werden.
**<code>reusePort(0,1)</code>: Eines von (0,1). Gibt an, ob die Portwiederwendung für SSDP aktiviert werden soll, oder nicht. Kann Restart-Probleme lösen. Wenn man diese Probleme nicht hat, sollte man das Attribut nicht setzen.
**<code>SubProcessLogfileName <Pfad></code>: Hiermit kann für den SubProzess eine eigene Logdatei angegeben werden. Unter Windows z.B. überschreiben sich die beiden Logausgaben (von Fhem und SubProzess) sonst gegenseitig. Wenn "-" angegeben wird, wird wie bisher auf STDOUT (und damit im Fhem-Log) geloggt. Der Hauptanwendungsfall ist die mehr oder weniger kurzfristige Fehlersuche. Es werden keinerlei Variablenwerte ersetzt, und der Wert direkt als Dateiname verwendet.
**<code>usedonlyIPs <IP-Adresse>[,IP-Adresse]</code>: Mit diesem Attribut können IP-Adressen angegeben werden, die ausschließlich vom UPnP-System berücksichtigt werden sollen. Z.B.: "192.168.0.11,192.168.0.37". Es sind auch reguläre Ausdrücke pro Element zulässig. Diese dürfen nur keine Kommata oder Doppelpunkte enthalten. Z.B: '''/192.168.0.(1|2|3)/,/192.168.1.\d*/'''.
*Bookmark-Einstellungen<br />'''Hinweis''': Die Konfiguration der Bookmarks wird erst bei einem Neustart des SubProzesses (also durch einen FHEM-Neustart (vorher Speichern nicht vergessen) oder dem Setzen/Zurücksetzen des Attributs '''disable''' am Sonos-Device) berücksichtigt.
**<code>bookmarkSaveDir <path></code>: Das Verzeichnis, in dem die Dateien für die gespeicherten Bookmarks abgelegt werden sollen. Wenn nicht festgelegt, dann wird "." verwendet.
**<code>bookmarkTitleDefinition <Groupname>:<PlayerdeviceRegEx>:<TrackURIRegEx>:<MinTitleLength>:<RemainingLength>:<MaxAge>:<ReadOnly> [...]</code>: Die Definition für die Verwendung von Bookmarks für Titel.
**<code>bookmarkPlaylistDefinition <Groupname>:<PlayerdeviceRegEx>:<MinListLength>:<MaxListLength>:<MaxAge> [...]</code>: Die Definition für die Verwendung von Bookmarks für aktuelle Abspiellisten/Playlisten.
*Proxy-Einstellungen
**<code>generateProxyAlbumArtURLs(0,1)</code>: Wenn aktiviert, werden alle Cover-Links als Proxy-Aufrufe an FHEM generiert. Dieser Proxy-Server wird vom Sonos-Modul bereitgestellt. In der Grundeinstellung erfolgt kein Caching der Cover, sondern nur eine Durchreichung der Cover von den Sonosplayern (Damit ist der Zugriff durch einen externen Proxyserver auf FHEM möglich).
**<code>proxyCacheDir</code>: Hiermit wird das Verzeichnis festgelegt, in dem die Cover zwischengespeichert werden. Wenn nicht festgelegt, so wird '''/tmp''' verwendet.
**<code>proxyCacheTime</code>: Mit einer Angabe ungleich 0 wird der Caching-Mechanismus des Sonos-Modul-Proxy-Servers aktiviert. Dabei werden Cover, die im Cache älter sind als diese Zeitangabe in Sekunden, neu vom Sonosplayer geladen, alle anderen direkt ausgeliefert, ohne den Player zu fragen.
**<code>webname <String></code>: Hiermit kann der zu verwendende Webname für die Cover-Link-Erzeugung angegeben werden. Da vom Modul Links zu Cover u.ä. erzeugt werden, ohne dass es einen FhemWeb-Aufruf dazu gibt, kann das Modul diesen Pfad nicht selber herausfinden. Wenn das Attribut nicht angegeben wird, dann wird 'fhem' angenommen.
*{{Anker|Sprachattribute}}Sprachoptionen
**<code>targetSpeakDir</code>: Das Verzeichnis, in dem dieses Modul die Sprachdateien von <code>Speak</code> (siehe [[#Set-Befehle_an_den_SONOSPLAYER|Set-Befehle an den SONOSPLAYER]]) ablegen soll (also die Adresse für den '''Schreib'''zugriff). Es wird empfohlen, dass dieses Verzeichnis '''nicht''' von Sonos indiziert ist.<br />z.B. Pfade unter *Nix: <code>/home/www/Sonos</code> oder unter Windows: <code>C:\InetPub\Sonos</code>
**<code>targetSpeakMP3FileConverter</code>: Hiermit kann ein MP3-Konverter angegeben werden, der am Ende der Verkettung der Speak-Ansage das resultierende MP3-File nochmal sauber durchkodiert. Damit können Restzeitanzeigeprobleme behoben werden. Dadurch vegrößert sich allerdings u.U. die Ansageverzögerung.<br />z.B. <code>/usr/bin/avconv -i %infile% %outfile%</code>
***'''Hinweis''': Der Platzhalter ''%infile%'' wird durch den Quelldateinamen ersetzt werden.
***'''Hinweis''': Der Platzhalter ''%outfile%'' wird durch den Zieldateinamen ersetzt werden.
***'''Hinweis''': Das Programm ''avconv'' kann unter Debian z.B. mittels <code>sudo apt-get install ffmpeg</code> installiert werden.
**<code>targetSpeakMP3FileDir</code>: Das Verzeichnis, welches als Standard für MP3-Fileangaben in Speak-Texten verwendet werden soll. Wird dieses Attribut definiert, können die Angaben bei Speak ohne Verzeichnis erfolgen.<br />z.B. Pfade unter *Nix: <code>/home/www/Sonos</code> oder unter Windows: <code>C:\InetPub\Sonos</code>
**<code>targetSpeakURL</code>: Die URL, unter der ''von außen'' (also aus Sicht des Zoneplayers) auf die abgelegte Sprachdatei zugegriffen werden kann (also die Adresse für den '''Lese'''zugriff). <br />z.B. <code>\\192.168.178.45\Sonos</code>
***'''Achtung!''': Dabei muss darauf geachtet werden, dass als letztes Zeichen vor dem Zeilenumbruch kein Backslash steht (ist hier für den Pfad auch nicht notwendig). Dieser würde von FHEM als Maskierer für den folgenden Zeilenumbruch interpretiert werden, und die nächste Zeile wäre auch noch Bestandteil dieses Attributs (und damit des Pfades).
**<code>targetSpeakFileTimestamp(0,1)</code>: Definiert, ob in dem Namen der Sprachausgabedatei ein Zeitstempel enthalten sein soll. Das sorgt dafür, dass alle Dateien beibehalten werden (da nicht mit demselben Namen überschrieben wird).<br />Manchmal kann das auch Caching-Probleme beseitigen. In meinen Tests hat die Anzeige der in der Sprachdatei enthaltenen MP3-Tags nur mit dieser aktivierten Option sauber funktioniert, da der ZonePlayer bei mir die Tags gecached hält.<br />Anderseits muss man sich dabei Gedanken über eine Aufräumstrategie machen, da die alten Dateien immer vorhanden bleiben.
**<code>targetSpeakFileHashCache(0,1)</code>: Definiert, ob in dem Namen der Sprachausgabedatei ein Hash-Wert enthalten sein soll. Das sorgt dafür, dass die Dateien bei gleichem Text wiederverwendet werden und nicht neu generiert werden.
***Für diese Funktionalität wird das Perl-Modul '''Digest::SHA1''' für die Berechnung des Hash-Werts benötigt. Am einfachsten kann es bei Bedarf per CPAN installiert werden: <code>sudo cpan install Digest::SHA1</code>.
**<code>Speak1</code>: Hiermit kann ein Systemaufruf definiert werden, der zu Erzeugung einer Sprachausgabe verwendet werden kann. Sobald dieses Attribut definiert wurde, ist ein entsprechender Setter am Sonosplayer verfügbar.<br />Das Format ist:<br /><Ausgabedateiendung>:<Befehlszeile>
***Es dürfen folgende Platzhalter verwendet werden:<br />'''%language%''': Wird durch die eingegebene Sprache ersetzt<br />'''%filename%''': Wird durch den kompletten Dateinamen (inkl. Dateiendung) ersetzt.<br />'''%text%''': Wird durch den zu übersetzenden Text ersetzt.<br />'''%textescaped%''': Wird durch den URL-Enkodierten zu übersetzenden Text ersetzt.<br />Zusätzliche Ersetzungen:<br />'''%textutf8%''': Wird durch den zu übersetzenden Text im UTF8-Format ersetzt.<br />'''%textutf8escaped%''': Wird durch den URL-Enkodierten zu übersetzenden Text im UTF8-Format ersetzt.
**<code>Speak2</code>: Siehe Speak1
**<code>Speak3</code>: Siehe Speak1
**<code>Speak4</code>: Siehe Speak1
**<code>SpeakCover</code>: Hiermit kann ein JPG- oder PNG-Bild als Cover für die Google-Sprachdurchsagen definiert werden.
**<code>Speak1Cover</code>: Analog zu SpeakCover für Speak1.
**<code>Speak2Cover</code>: Analog zu SpeakCover für Speak2.
**<code>Speak3Cover</code>: Analog zu SpeakCover für Speak3.
**<code>Speak4Cover</code>: Analog zu SpeakCover für Speak4.
**<code>SpeakGoogleURL <GoogleURL></code>: Die zu verwendende Google-URL. Wenn dieser Parameter nicht angegeben wird, dann wird ein Standard verwendet. Hier müssen Platzhalter für die Ersetzung durch das Modul eingetragen werden: %1$s -> Sprache, %2$s -> Text
***Die Standard-URL lautet momentan: <code>http://translate.google.com/translate_tts?tl=%1$s&client=tw-ob&q=%2$s</code>

=== Get-Befehle an SONOS ===
*Gruppenbefehle
**<code>Groups</code>: Liefert die aktuelle Gruppierungskonfiguration der Sonos-Systemlandschaft zurück. Das Format ist eine Komma-getrennte Liste von Listen mit Devicenamen, also z.B. <code>[Sonos_Kueche], [Sonos_Wohnzimmer, Sonos_Schlafzimmer]</code>. In diesem Beispiel sind also zwei Gruppen definiert, von denen die erste aus einem Player und die zweite aus Zwei Playern besteht. Dabei ist die Reihenfolge innerhalb der Unterlisten wichtig, da der erste Eintrag der sogenannte Gruppenkoordinator ist (in diesem Fall also <code>Sonos_Wohnzimmer</code>), von dem die aktuelle Abspielliste und der aktuelle Titel auf die anderen Gruppenmitglieder übernommen wird.

=== Set-Befehle an SONOS ===
*Grundsätzliches
**<code>RefreshShareIndex</code>: Startet eine Aktualisierung des Indexes der Freigaben
**<code>RescanNetwork</code>: Startet die Erkennung der im Netzwerk vorhandenen Player erneut.
*Steuerbefehle
**<code>Mute <State></code>: Setzt den Mute-Zustand bei allen Playern. Der Wert kann on oder off sein.
**<code>PauseAll</code>: Pausiert die Wiedergabe in allen Zonen.
**<code>Pause</code>: Synonym für PauseAll.
**<code>StopAll</code>: Stoppt die Wiedergabe in allen Zonen.
**<code>Stop</code>: Synonym für StopAll.
*Bookmark-Befehle
**<code>DisableBookmark <Groupname></code>: Deaktiviert die angegebene Gruppe.
**<code>EnableBookmark <Groupname></code>: Aktiviert die angegebene Gruppe.
**<code>LoadBookmarks [Groupname]</code>: Lädt die angegebene Gruppe (oder alle Gruppen, wenn nicht angegeben) aus den entsprechenden Dateien.
**<code>SaveBookmarks [Groupname]</code>: Speichert die angegebene Gruppe (oder alle Gruppen, wenn nicht angegeben) in die entsprechenden Dateien.
*Gruppenbefehle
**<code>Groups <Gruppendefinition></code>: Setzt die aktuelle Gruppierungskonfiguration der Sonos-Systemlandschaft. Das Format ist jenes, welches auch von dem Get-Befehl ''Groups'' geliefert wird.<br >'''Hinweis''': Hier kann als Gruppendefinition das Wort ''Reset'' verwendet werden, um alle Player aus ihren Gruppen zu entfernen.

== Modul '''SONOSPLAYER''' ==
Dieses Modul dient im großen und ganzen als Platzhalter für FHEM, damit der Anwender FHEM-Konform informiert werden, bzw. steuern kann.

Hier werden die Informationen, die vom '''SONOS'''-Modul erkannt werden, abgelegt, und die Aktualisierungs-Events erzeugt.

=== Readings von SONOSPLAYER ===
Folgende Informationen werden im SONOSPLAYER als Reading abgelegt:
*Systemzustand
**<code>AlarmList</code>: Enthält die textuelle Repräsentation des Hashs mit den aktuell für diesen Player gültigen Alarminformationen. Diese Information wird automatisch aktualisiert, wenn das Attribut '''getAlarms''' auf ''1'' gesetzt wurde, ansonsten steht sie nicht zur Verfügung (und es kann kein Alarm angelegt, verändert und gelöscht werden). Das Format des Hashs entspricht dem, das zum Setzen oder Anpassen eines Alarms notwendig ist.<br />Folgene Schlüssel sind dort zulässig/notwendig:
***'''Enabled(0,1)''': Gibt an, ob der Alarm aktiviert ist.
***'''Volume(0..100)''': Die Lautstärke, mit der der Alarm wiedergegeben werden soll.
***'''StartTime(Timstamp)''': Die Uhrzeit, zu der der Alarm starten soll.
***'''Duration(Timstamp)''': Die Dauer, die der Alarm laufen soll.
***'''Repeat(0,1)''': Gibt an, ob die Wiedergabe wiederholt werden soll.
***'''Shuffle(0,1)''': Gibt an, ob die Wiedergabe zufällig erfolgen soll.
***'''RoomUUID''': Die ID der Zone, in der der Alarm wiedergegeben werden soll. Dieser Wert muss nie mit angegeben werden, da er automatisch befüllt wird (Diese Information ist durch das verwendete FHEM-Zoneplayer-Device klar).
***'''ProgramURI''': Die abzuspielende URI.
***'''ProgramMetaData''': Die Metadaten zu der abzuspielenden URI.
***'''Recurrence_Once(0,1)''': Gibt an, dass der Alarm nur einmal laufen soll. Wenn hier eine ''1'' angegeben wurde, dann werden die anderen ''Recurrence''-Angaben ignoriert.
***'''Recurrence_Monday(0,1)''': Gibt an, dass der Alarm jeden Montag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Tuesday(0,1)''': Gibt an, dass der Alarm jeden Dienstag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Wednesday(0,1)''': Gibt an, dass der Alarm jeden Mittwoch laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Thursday(0,1)''': Gibt an, dass der Alarm jeden Donnerstag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Friday(0,1)''': Gibt an, dass der Alarm jeden Freitag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Saturday(0,1)''': Gibt an, dass der Alarm jeden Samstag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''Recurrence_Sunday(0,1)''': Gibt an, dass der Alarm jeden Sonntag laufen soll. Kann mit den anderen Tagesangaben kombiniert werden.
***'''IncludeLinkedZones(0,1)''': Gibt an, ob die aktuell verlinkten Zonen diesen Alarm ebenfall abspielen sollen.
***'''Beispiel-Hash''': { Enabled => 1, Volume => 12, StartTime => '16:00:00', Duration => '00:15:00', Repeat => 0, Shuffle => 0, ProgramURI => 'x-rincon-buzzer:0', ProgramMetaData => ' ', Recurrence_Once => 0, Recurrence_Monday => 1, Recurrence_Tuesday => 1, Recurrence_Wednesday => 1, Recurrence_Thursday => 1, Recurrence_Friday => 1, Recurrence_Saturday => 0, Recurrence_Sunday => 0, IncludeLinkedZones => 0 }
**<code>AlarmListIDs</code>: Enthält die Hash-Schlüssel der Alarme als kommaseparierte Liste. Dieses Reading gibt es Hauptsächlich zur Vereinfachung des Zugriffs auf das Reading '''AlarmList'''. Damit hat man direkt die Anzahl und Primärschlüssel im Zugriff.
**<code>AlarmListVersion</code>: Dieses Reading enthält die Information über die aktuelle Version der gespeicherten Alarm-Informationen. Diese Information wird Hauptsächlich intern benötigt, um beurteilen zu können, ob die Alarminformationen neu geladen werden müssen.
**<code>AudioDelay</code>: Gibt das AudioDelay des Players an. Der Wert kann zwischen 0 und 5 liegen.
**<code>AudioDelayLeftRear</code>: Gibt den AudioDelayLeftRear des Players an. Der Wert kann zwischen 0 und 2 liegen. Wobei die Werte folgende Bedeutung haben: 0: >3m, 1: >0.6m und <3m, 2: <0.6m
**<code>AudioDelayRightRear</code>: Gibt den AudioDelayRightRear des Players an. Der Wert kann zwischen 0 und 2 liegen. Wobei die Werte folgende Bedeutung haben: 0: >3m, 1: >0.6m und <3m, 2: <0.6m
**<code>ButtonState</code>: Gibt den Zustand des Buttons an.
**<code>ButtonLockState</code>: Gibt den Sperr-Zustand des Buttons an.
**<code>DailyIndexRefreshTime</code>: Enthält die aktuell gültige ''DailyIndexRefreshTime'', zu der der Medienindex neu aufgebaut werden soll. <br />Diese Information wird automatisch aktualisiert, wenn sie bei einem Player verändert wird, wenn das Attribut '''getAlarms''' des Player auf ''1'' gesetzt wurde.
**<code>DialogLevel</code>: Gibt den Zustand der Sprachverbesserung an der Playbar an.
**<code>FavouritesVersion</code>: Dieses Reading enthält die Information über die aktuelle Version der gespeicherten Favoriten. Eine Änderung dieses Readings wird durch eine Anpassung der Favoriten (z.B. durch einen Controller) ausgelöst.
**<code>fieldType</code>: In einer Paarung wird jedem Player vom Sonos-System ein eindeutiger FieldType zugewiesen. Dieser wird von diesem Modul für die Eindeutigkeit des Device-Namen verwendet. Bei einer Stereopaarung z.B. hat ein Player den Type 'LF' (für Left-Front), 'RF' (für Right-Front) oder SW (für Subwoofer); bei Surround-Konfigurationen aber auch RR (für Right-Rear) oder LR (für Left-Rear).
**<code>HeadphoneConnected</code>: Enthält, wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> (oder auch <code>minVolumeHeadphone</code> und <code>maxVolumeHeadphone</code>) gesetzt wurde, den Zustand, ob ein Kopfhörer verwendet wird, oder nicht. <br />Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung dieses Zustands auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>LastActionResult</code>: Enthält den Namen und das Ergebnis der letzten Aktion auf dem Player. Da die Aktionen asyncron übertragen werden, kann nur hier kontrolliert werden, ob das gewünschte Ergebnis erreicht wurde.
**<code>LineInConnected</code>: Gibt an, ob der Line-In-Eingang angeschlossen ist, oder nicht. Wird bei Änderung am Player automatisch aktualisiert, und erzeugt damit auch ein Event.
**<code>location</code>: URL zum Informationsdokument des ZonePlayers
**<code>NightMode</code>: Gibt den Zustand des Nachtsounds an der Playbar an.
**<code>Orientation</code>: Gibt die Lage des Players an.
**<code>playerType</code>: Typbezeichnung des ZonePlayer. z.B. "ZP90"
**<code>PlaylistsVersion</code>: Dieses Reading enthält die Information über die aktuelle Version der gespeicherten Playlists. Eine Änderung dieses Readings wird durch eine Anpassung der Playlists (z.B. durch einen Controller) ausgelöst.
**<code>presence</code>: Erreichbarkeit des Players. Kann "appeared" oder "disappeared" sein
**<code>RadiosVersion</code>: Dieses Reading enthält die Information über die aktuelle Version der gespeicherten Radiofavoriten. Eine Änderung dieses Readings wird durch eine Anpassung der Radios (z.B. durch einen Controller) ausgelöst.
**<code>roomName</code>: Originalname des ZonePlayers. Kann Leer- oder Sonderzeichen enthalten
**<code>roomNameAlias</code>: Originalname des ZonePlayers mit einem angehangenen Funktionsnamen, wie er für das Attribut "alias" verwendet werden würde (z.B. "Wohnzimmer - Rechts"). Wird zur Laufzeit aktualisiert. Kann Leer- oder Sonderzeichen enthalten
**<code>saveRoomName</code>: Sicherer Name des Zoneplayer. Sonderzeichen wurden in Unterstriche umgewandelt. Das Device wird beim Anlegen mit diesem Namen angelegt
**<code>serialNum</code>: Seriennummer des ZonePlayers. Entspricht weitestgehend der MAC-Adresse. z.B. "00-0E-58-28-D0-F4:2"
**<code>softwareRevision</code>: Version der installierten Software. z.B. "8.4"
**<code>softwareRevisionAvailable</code>: Version der verfügbaren Software. z.B. "8.5"
**<code>softwareRevisionInternal</code>: Interne Version der installierten Software. z.B. "41.3-50131"
**<code>softwareRevisionInternalAvailable</code>: Interne Version der verfügbaren Software. z.B. "42.2-51240"
**<code>SubEnable</code>: Gibt den Zustand des Sub-Zustands für diesen Player an.
**<code>SubGain</code>: Gibt den SubGain für diesen Player an. Der Wert kann zwischen -15 und 15 liegen.
**<code>SubPolarity</code> Gibt den SubPolarity für diesen Player an. Der Wert kann zwischen 0 und 2 liegen.
**<code>SurroundEnable</code>: Gibt an, ob für diesen Player die Surround-Wiedergabe aktiviert wurde, oder nicht.
**<code>SurroundLevel</code>: Gibt den Surroundlevel für diesen Player an. Der Wert kann zwischen -15 und 15 sein.
**<code>TruePlay</code>: Gibt an, ob für diesen Player die TruePlay-Wiedergabe aktiviert ist, oder nicht.
**<code>WifiEnabled</code>: Gibt an, ob für diesen Player Wifi aktiviert ist, oder nicht.
**<code>WirelessMode</code>: Gibt den Wirelessmode des Players an.
*Gruppierungsinformationen
**<code>AvailablePlayerList</code>: Wird gesetzt, wenn das Attribut "getListsDirectlyToReadings" am Sonos-Device gesetzt wurde. Es enthält die anderen und noch verfügbaren und nicht gebundenen Player-Devicenamen. Das ist die Grundlage für eine Player-zur-Abspielgruppe-hinzufügen-Funktion als Listendarstellung.
**<code>AvailablePlayerListAlias</code>: Wird gesetzt, wenn das Attribut "getListsDirectlyToReadings" am Sonos-Device gesetzt wurde. Es enthält die anderen und noch verfügbaren und nicht gebundenen Player-Raumnamen. Das ist die Grundlage für eine Player-zur-Abspielgruppe-hinzufügen-Funktion als Listendarstellung.
**<code>IsBonded</code>: Gibt an, ob der Player in einer Bindung zum Masterplayer steht (anstatt ein einfaches Gruppenmitglied zu sein). Gebundene Player sind z.B. der rechte Player im Stereoverbund, sowie die Satellitenplayer in einem 5.1er Surroundsystem (also Subwoofer, hintere Lautsprecher und vordere Lautsprecher).
**<code>IsMaster</code>: Gibt an, ob dieser Player aktuell ein Masterplayer einer Gruppe ist. Dabei kann die Gruppe auch nur einen Teilnehmer haben (wieder dieser Player).<br />Damit kann ermittelt werden, welche Player korrekte Abspielinformationen darstellen können.
**<code>IsZoneBridge</code>: Gibt an, ob dieser Player eine Bridge ist.
**<code>MasterPlayer</code>: Gibt den FHEM-Devicenamen des Masterplayers zu diesem Player an. Wenn dieser Player alleine eine Gruppe darstellt, dann steht in diesem Reading der FHEM-Devicenamen dieses Players.
**<code>SlavePlayer</code>: Gibt eine per '''eval''' umwandelbare Liste von FHEM-Devicenamen der zu diesem Masterplayer gehörenden Slaveplayer an. Diese Liste kann auch leer sein, wenn dieser Player kein Masterplayer ist, oder die Gruppe nur aus einem Mitglied besteht.
**<code>SlavePlayerNotBonded</code>: Enthält alle SlavePlayer, die nicht gebunden sind als visualisiertes Perl-Array.
**<code>SlavePlayerNotBondedList</code>: Enthält alle SlavePlayer, die nicht gebunden sind als "|"-separierte Liste der Devicenamen.
**<code>SlavePlayerNotBondedListAlias</code>: Enthält alle SlavePlayer, die nicht gebunden sind als "|"-separierte Liste der Raumnnamen.
**<code>ZoneGroupID</code>: Die ID des Gruppenkoordinators plus eine laufende Nummer. Sollte die Gruppe nur aus einem Mitglied bestehen, so ist es die eigene ID (=UDN).
**<code>ZoneGroupName</code>: Der Name der aktuellen Gruppe
**<code>ZoneGroupNameDetails</code>: Enthält die Slavezonen als textuelle Auflistung mittels '+'. Ist leer, wenn es keine Slaveplayer gibt. Enthält den Namen des Gruppenmasters, wenn es einen solchen gibt.
**<code>ZonePlayerUUIDsInGroup</code>: Eine Liste der in der aktuellen Gruppe befindlichen Zoneplayer.
*Abspielzustand
**<code>AlarmRunning</code>: Dieses Reading enthält ''1'', wenn gerade ein Alarm abgespielt wird, sonst ''0''
**<code>AlarmRunningID</code>: Dieses Reading enthält die ID des verursachenden Alarms, wenn gerade ein Alarm abgespielt wird, sonst ist es leer.
**<code>Balance</code>: Enthält im Normalfall die am Player eingestellte Balance zum Zeitpunkt der Erkennung. Wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, wird diese Balance bei jeder Änderung am Player mit aktualisiert. <br />Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung der Balance auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>Bass</code>: Enthält im Normalfall den am Player eingestellten Basslevel zum Zeitpunkt der Erkennung. Wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, wird dieser Basslevel bei jeder Änderung am Player mit aktualisiert. <br />Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des Basslevels auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>CrossfadeMode</code>: Enthält den aktuellen Zustand von CrossfadeMode. Wird durch Event des Players aktualisiert (zusammen mit der Titelinformation).
**<code>GroupMute</code>: Enthält den GroupMute-Zustand. Wird automatisch aktualisiert.
**<code>GroupVolume</code>: Enthält den GroupVolume-Zustand. Wird automatisch aktualisiert.
**<code>GroupVolumeD</code>: Verringert die aktuelle Gruppenlautstärke um volumeStep-Einheiten.
**<code>GroupVolumeU</code>: Erhöht die aktuelle Gruppenlautstärke um volumeStep-Einheiten.
**<code>Loudness</code>: Enthält, wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, den aktuellen Zustand des Loudness. <br />Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des Loudness-Zustands auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>Mute</code>: Enthält, wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, den aktuellen Zustand des Mute. <br />Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des Mute-Zustands auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>numberOfTracks</code>: Anzahl der momentan in der Abspielliste befindlichen Titel
**<code>OutputFixed</code>: Enthält, wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, den aktuellen Zustand des OutputFixed. <br />Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des OutputFixed-Zustands auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>QueueDuration</code>: Enthält die Abspieldauer der aktuellen Abspielliste als Zeitangabe. ''Achtung!'': Nicht jeder Titel wird mit Abspiellänge von Sonos geliefert, sodass dieser Wert auch ungenau sein kann.
**<code>QueueDurationSec</code>: Enthält die Abspieldauer der aktuellen Abspielliste in Sekunden. ''Achtung!'': Nicht jeder Titel wird mit Abspiellänge von Sonos geliefert, sodass dieser Wert auch ungenau sein kann.
**<code>QueueHash</code>: Enthält den Hashwert der aktuellen Abspielliste. Dieser wird für die Bookmarkfunktionalität verwendet
**<code>Repeat</code>: Enthält den aktuellen Zustand von Repeat. Wird durch Event des Players aktualisiert (zusammen mit der Titelinformation).
**<code>RepeatOne</code>: Enthält den aktuellen Zustand von RepeatOne. Wird durch Event des Players aktualisiert (zusammen mit der Titelinformation).
**<code>Shuffle</code>: Enthält den aktuellen Zustand von Shuffle. Wird durch Event des Players aktualisiert (zusammen mit der Titelinformation).
**<code>SleepTimer</code>: Enthält die Restzeit des Sleeptimers. Diese Information wird vom Player beim Setzen und Ablaufen gemeldet, und erzeugt somit ein Event zu Beginn und Ende des Timers. Während der Timer läuft, wird hier nichts aktualisiert. Man muss also, falls benötigt, selber die verbleibende Restzeit mittels des Readings-Timestamps und diesem Wert ermitteln.<br />Diese Information wird automatisch aktualisiert, wenn sie bei einem Player verändert wird.<br />Beim Ablaufen des Timers wird vom Player eine Aktualisierung auf den Wert '''off''' gesendet. Darauf kann in einem Notify-Event geprüft werden.
**<code>SleepTimerVersion</code>: Dieses Reading enthält die Information über die aktuelle Version der gespeicherten ''SleepTimer''-Informationen. Diese Information wird Hauptsächlich intern benötigt, um beurteilen zu können, ob das Reading ''SleepTimer'' neu geladen werden muss.
**<code>transportState</code>: Aktueller Abspielstatus. Kann "ERROR", "STOPPED", "PLAYING" oder "PAUSED_PLAYBACK" sein. Wobei ERROR heißt, dass es keine Verbindung zum Player gibt.<br />'''Hinweis'': Bei Gruppen hat nur der Gruppenmaster den korrekten Abspielzustand. Alle Slaveplayer enthalten immer den Zustand "PLAYING", da sie ja gerade den Masterplayer "abspielen", und keine Information dazu haben, ob und was abgespielt wird.
**<code>Treble</code>: Enthält im Normalfall den am Player eingestellten Treblelevel zum Zeitpunkt der Erkennung. Wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, wird dieser Treblelevel bei jeder Änderung am Player mit aktualisiert. <br />Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung des Treblelevels auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
**<code>Volume</code>: Enthält im Normalfall die am Player eingestellte Laustärke zum Zeitpunkt der Erkennung. Wenn eines der beiden Attribute <code>minVolume</code> oder <code>maxVolume</code> gesetzt wurde, wird diese Lautstärke bei jeder Änderung am Player mit aktualisiert. <br />Wenn zusätzlich noch das Attribut <code>generateVolumeEvent</code> gesetzt ist, erzeugt jede Änderung der Lautstärke auch ein FHEM-Event. Standardmäßig ist dies aus Zeitgründen deaktiviert, da FHEM-Events an jeden(!) notify innerhalb FHEM gemeldet werden. Dies kann u.U. zu Verzögerungen bei dem ZonePlayer führen.
*Infos zum aktuellen Titel
**<code>currentTitle</code>: Titelbezeichnung des aktuellen Titels
**<code>currentArtist</code>: Interpret des aktuellen Titels
**<code>currentAlbum</code>: Albumname des aktuellen Titel
**<code>currentAlbumArtist</code>: Interpret des Albums. Kann z.B. auch "(compilations)" sein.
**<code>currentEnqueuedTransportHandle</code>: Handle, welches zur Weitergabe der aktuellen Quelle des aktuellen Titels verwendet werden kann.
**<code>currentEnqueuedTransportURI</code>: Enthält den Identifier der Quelle des aktuellen Titels. Z.B. die ID der Spotify-Playliste
**<code>currentFavouriteName</code>: Enthält den Namen des Quellfavoriten, der den aktuellen Titel zur Liste hinzugefügt hat. Dazu müssen die Favoriten mittels "get FavouritesWithCover" ermittelt worden sein, und die Liste im Reading "Favourites" zur Verfügung stehen.
**<code>currentPlaylistName</code>: Enthält den Namen der Quellplaylist, die den aktuellen Titel zur Liste hinzugefügt hat. Dazu müssen die Playlisten mittels "get PlaylistsWithCover" ermittelt worden sein, und die Liste im Reading "Playlists" zur Verfügung stehen.
**<code>currentRadioName</code>: Enthält den Namen des Quellradios, der den aktuellen Titel zur Liste hinzugefügt hat. Dazu müssen die Radios mittels "get RadiosWithCover" ermittelt worden sein, und die Liste im Reading "Radios" zur Verfügung stehen.
**<code>currentOriginalTrackNumber</code>: Nummer des aktuellen Titels bezogen auf das Album
**<code>currentSource</code>: Enthält die aktuelle Quelle zum aktuellen Titel. Bei Spotify z.B. die gewählte Playliste oder das Album, oder die gewählte Sonos-Playliste.
**<code>currentTrack</code>: Nummer des aktuellen Titels in der Abspielliste
**<code>currentTrackHandle</code>: Handle des aktuellen Titels, welches zur Weitergabe geeignet ist.
**<code>currentTrackURI</code>: Dateipfad des aktuellen Titels in der Abspielliste. Gültige Formate siehe PlayURI.
**<code>currentTrackDuration</code>: Länge des aktuellen Titels im Format H:MM:SS
**<code>currentTrackDurationSec</code>: Länge des aktuellen Titels in Sekunden.
**<code>currentTrackPosition</code>: Position innerhalb des aktuellen Titels im Format H:MM:SS. Wird zum Zeitpunkt einer Änderung des Abspielstatus (Play, Pause, Stop, Nächster Titel, usw.) aktualisiert.
**<code>currentTrackPositionSimulated</code>: Simulierte und laufend aktualisierte Abspielposition des Titels im Format H:MM:SS.
**<code>currentTrackPositionSimulatedSec</code>: Simulierte und laufend aktualisierte Abspielposition des Titels in Sekunden.
**<code>currentTrackPositionSimulatedPercent</code>: Simulierte und laufend aktualisierte Abspielposition des Titels in Prozent.
**<code>currentTrackProvider</code>: 'Quelle' der aktuellen Wiedergabe. Enthält z.B. ''Spotify'' oder ''Bibliothek''
**<code>currentTrackProviderIconQuadraticURL</code>: Enthält eine URL zu einem quadratischen TrackProvider-Icon.
**<code>currentTrackProviderIconRoundURL</code>: Enthält eine URL zu einem runden TrackProvider-Icon.
**<code>currentSender</code>: Senderbezeichnung, wenn es ein Radiostream ist
**<code>currentSenderCurrent</code>: Zusatzinformationen zur Radiosendung, meist der Programmtitel wie 'Pop&Weck'
**<code>currentSenderInfo</code>: Zusatzinformationen zur Radiosendung, meist der Titel des aktuellen Liedes
**<code>currentAlbumArtURI</code>: Relativer Verzeichnis-Pfad im lokalen FHEM (physisch). Beginnt momentan mit "www"
**<code>currentAlbumArtURL</code>: Kompletter Pfad für den eigenen Download der Coverdatei des aktuellen Titels oder für die Angabe in einer HTML-IMG-Source.
*Infos zum nächsten Titel
**<code>nextTitle</code>: Titelbezeichnung des nächsten Titels
**<code>nextArtist</code>: Interpret des nächsten Titels
**<code>nextAlbum</code>: Albumname des nächsten Titel
**<code>nextAlbumArtist</code>: Interpret des Albums des nächsten Titels. Kann z.B. auch "(compilations)" sein.
**<code>nextOriginalTrackNumber</code>: Nummer des nächsten Titels bezogen auf das Album
**<code>nextAlbumArtURI</code>: Relativer Verzeichnis-Pfad im lokalen FHEM (physisch). Beginnt momentan mit "www"
**<code>nextAlbumArtURL</code>: Kompletter Pfad für den eigenen Download der Coverdatei des nächsten Titels oder für die Angabe in einer HTML-IMG-Source.
**<code>nextTrackHandle</code>: Handle des nächsten Titels, welches zur Weitergabe geeignet ist.
**<code>nextTrackURI</code>: Dateipfad des nächsten Titels in der Abspielliste. Gültige Formate siehe PlayURI.
**<code>nextTrackDuration</code>: Länge des nächsten Titels im Format H:MM:SS
**<code>nextTrackDurationSec</code>: Länge des nächsten Titels in Sekunden.
**<code>nextTrackProvider</code>: 'Quelle' der nächsten Wiedergabe. Enthält z.B. ''Spotify'' oder ''Bibliothek''
**<code>nextTrackProviderIconQuadraticURL</code>: Enthält eine URL zu einem quadratischen TrackProvider-Icon.
**<code>nextTrackProviderIconRoundURL</code>: Enthält eine URL zu einem runden TrackProvider-Icon.
*Generierte Informationen
**<code>infoSummarize1</code>: Frei zusammenstellbare Informationszeile. Zum Format siehe [InfoSummarize]
**<code>infoSummarize2</code>: Frei zusammenstellbare Informationszeile. Zum Format siehe [InfoSummarize]
**<code>infoSummarize3</code>: Frei zusammenstellbare Informationszeile. Zum Format siehe [InfoSummarize]
**<code>infoSummarize4</code>: Frei zusammenstellbare Informationszeile. Zum Format siehe [InfoSummarize]
**<code>currentStreamAudio</code>: Boolean. 1 wenn gerade ein Radiostream läuft, sonst 0. Momentan faktisch Negation zu <currentNormalAudio>
**<code>currentNormalAudio</code>: Boolean. 1 wenn gerade ein normaler Titel läuft, sonst 0. Momentan faktisch Negation zu <currentStreamAudio>

=== Attribute von SONOSPLAYER ===
'''Hinweis'''<br />Die Attribute werden meistens erst bei einem Neustart von FHEM verwendet, da diese dem SubProzess initial zur Verfügung gestellt werden müssen.

*Grundsätzliches
**<code>disable(0,1)</code>: Deaktiviert die Verarbeitung von Events dieses Devices
**<code>generateSomethingChangedEvent(0,1)</code>: Bestimmt, ob ein Event mit dem Namen 'SomethingChanged' generiert werden soll, wenn überhaupt ein Event generiert wurde. Das ist nützlich, wenn man auf eine beliebige Änderung des Player reagieren möchte.
**<code>generateVolumeEvent(0,1)</code>: Aktiviert die Generierung eines Events bei Lautstärkeänderungen, wenn mindestens eines der Attribute <code>minVolume</code>, <code>maxVolume</code>, <code>minVolumeHeadphone</code> oder <code>maxVolumeHeadphone</code> definiert ist. Standardmäßig ist dies deaktiviert (=0), um die Zeitverzögerung so gering wie möglich zu halten.
**<code>generateVolumeSlider(0,1)</code>: Aktiviert einen Slider für die Lautstärkeneinstellung auf der Detailansicht. Standardmäßig ist dieser aktiviert (=1).
**<code>getAlarms(0,1)</code>: Meldet sich bei Playern für die Aktualisierung von Alarm-Informationen an. Diese werden bei Änderung direkt aktualisiert, und erzeugen dementsprechend ein FHEM-Event. Gleichzeitig wird hiermit die '''DailyIndexRefreshTime''' mit aktualisiert.
**<code>suppressControlButtons(0,1)</code>: Gibt an, ob die Steuerbuttons unter der Cover-/Titelanzeige angezeigt werden sollen (=1) oder nicht (=0).
**<code>VolumeStep</code>: Definiert die Schrittweite für den Aufruf von <code>VolumeU</code> und <code>VolumeD</code>.
*Informationen generieren
**<code>generateInfoSummarize1</code>: Generiert das Reading 'InfoSummarize1' mit dem angegebenen Format.
**<code>generateInfoSummarize2</code>: Generiert das Reading 'InfoSummarize2' mit dem angegebenen Format.
**<code>generateInfoSummarize3</code>: Generiert das Reading 'InfoSummarize3' mit dem angegebenen Format.
**<code>generateInfoSummarize4</code>: Generiert das Reading 'InfoSummarize4' mit dem angegebenen Format.
**<code>getTitleInfoFromMaster(0,1)</code>: Bringt das Device dazu, seine aktuellen Abspielinformationen vom aktuellen Gruppenmaster zu holen, wenn es einen solchen gibt.
**<code>simulateCurrentTrackPosition(0,1)</code>: Bringt das Device dazu, seine aktuelle Abspielposition simuliert weiterlaufen zu lassen. Dazu werden die Readings <code>currentTrackPositionSimulated</code> und <code>currentTrackPositionSimulatedSec</code> gesetzt. Gleichzeitig wird auch das Reading <code>currentTrackPositionSimulatedPercent</code> (zwischen 0.0 und 100.0) gesetzt.
**<code>simulateCurrentTrackPositionPercentFormat <Format></code>: Definiert das Format für die sprintf-Prozentausgabe im Reading <code>currentTrackPositionSimulatedPercent</code>.
**<code>stateVariable(TransportState,NumberOfTracks,Track,TrackDuration,Title,Artist,Album,<br />
OriginalTrackNumber,AlbumArtist,Sender,SenderCurrent,SenderInfo,StreamAudio,NormalAudio,<br />
AlbumArtURI,nextTrackDuration,nextTrackURI,nextAlbumArtURI,nextTitle,nextArtist,<br />
nextAlbum,nextAlbumArtist,nextOriginalTrackNumber,Volume,Mute,Shuffle,Repeat,RepeatOne,CrossfadeMode,<br />
Balance,HeadphoneConnected,SleepTimer,Presence,RoomName,RoomNameAlias,SaveRoomName,PlayerType,Location,<br />
SoftwareRevision,SerialNum,InfoSummarize1,InfoSummarize2,InfoSummarize3,InfoSummarize4)</code>: Legt fest, welcher Variablenwert in den State geschrieben werden soll.
*Steueroptionen
**<code>maxVolume(0..100)</code>: Legt die obere Grenze für die einstellbare Lautstärke dieses ZonePlayers fest. Diese kann auch mit keinem Controller überschritten werden, da diese überwacht wird.
***Wenn eine untere oder obere Grenze festgelegt wurde, so wird das Reading '''Volume''' am entsprechenden SonosPlayer bei jeder Änderung am Player aktualisiert.<br />Möchte man also immer die aktuelle Lautstärke kennen, aber keine Enschränkung machen, dann sollte der Wert von <code>minVolume</code> auf <code>0</code> oder <code>maxVolume</code> auf <code>100</code> gesetzt werden. Desweiteren werden gleichzeitig auch Änderungen an der Balance aktualisiert, da diese mit übertragen werden.
***'''Achtung!''': Wenn eine untere oder obere Grenze festgelegt wird, werden für Lautstärkenänderungen auch Events erzeugt. Es ist unbedingt darauf zu achten, dass etwaige Notify-Definitionen zügig bearbeitet werden, da sonst das Sonos-System träge werden könnte.
***'''Hinweis''': Dieses Attribut kann auch im laufenden Betrieb angepasst werden. Die Einhaltung der Grenzen wird umgehend sichergestellt.<br />Bedingung ist nur, dass zum Startzeitpunkt des SubProzesses eine Grenze festgelegt sein musste, damit die entsprechenden Listener angemeldet werden.
**<code>minVolume(0..100)</code>: Legt die untere Grenze für die einstellbare Lautstärke dieses ZonePlayers fest. Diese kann auch mit keinem Controller unterschritten werden, da diese überwacht wird.
***Wenn eine untere oder obere Grenze festgelegt wurde, so wird das Reading '''Volume''' am entsprechenden SonosPlayer bei jeder Änderung am Player aktualisiert.<br />Möchte man also immer die aktuelle Lautstärke kennen, aber keine Enschränkung machen, dann sollte der Wert von <code>minVolume</code> auf <code>0</code> oder <code>maxVolume</code> auf <code>100</code> gesetzt werden. Desweiteren werden gleichzeitig auch Änderungen an der Balance aktualisiert, da diese mit übertragen werden.
***'''Achtung!''': Wenn eine untere oder obere Grenze festgelegt wird, werden für Lautstärkenänderungen auch Events erzeugt. Es ist unbedingt darauf zu achten, dass etwaige Notify-Definitionen zügig bearbeitet werden, da sonst das Sonos-System träge werden könnte.
***'''Hinweis''': Dieses Attribut kann auch im laufenden Betrieb angepasst werden. Die Einhaltung der Grenzen wird umgehend sichergestellt.<br />Bedingung ist nur, dass zum Startzeitpunkt des SubProzesses eine Grenze festgelegt sein musste, damit die entsprechenden Listener angemeldet werden.
**<code>maxVolumeHeadphone(0..100)</code>: Legt die obere Grenze für die einstellbare Lautstärke dieses ZonePlayers im Kopfhörerbetrieb fest.
***'''Hinweis!''': Es gelten die gleichen Bedingungen und Hinweise wie bei <code>maxVolume</code>.
**<code>minVolumeHeadphone(0..100)</code>: Legt die untere Grenze für die einstellbare Lautstärke dieses ZonePlayers im Kopfhörerbetrieb fest.
***'''Hinweis!''': Es gelten die gleichen Bedingungen und Hinweise wie bei <code>minVolume</code>.
**<code>buttonEvents <Time:Pattern>[ <Time:Pattern> ...]</code>: Definiert, dass bei einer bestimten Tastenfolge am Player ein Event erzeugt werden soll. Die Definition der Events erfolgt als Tupel: Der erste Teil vor dem Doppelpunkt ist die Zeit in Sekunden, die berücksichtigt werden soll, der zweite Teil hinter dem Doppelpunkt definiert die Abfolge der Buttons, die für dieses Event notwendig sind.
***Folgende Button-Kürzel sind zulässig:
****'''M''': Der Mute-Button ('''Achtung''': Der Mute-Button am SonosPlayer ist seit Firmware 4.2 ein Play/Pause/Next-Button, der kein Mute-Event mehr erzeugt, meine Beschwerde an Sonos, dass es nicht benutzerfreundlich ist, einen Mute-Symbolisierten Button mit Play/Pause zu belegen, wurde im großen und ganzen ignoriert)
****'''H''': Die Headphone-Buchse
****'''U''': Up-Button (Lautstärke Hoch)
****'''D''': Down-Button (Lautstärke Runter)
***Das Event, das geworfen wird, heißt <code>ButtonEvent</code>, der Wert ist die definierte Tastenfolge<br />Z.B.: <code>2:MM</code><br />Hier wird definiert, dass ein Event erzeugt werden soll, wenn innerhalb von 2 Sekunden zweimal die Mute-Taste gedrückt wurde. Das damit erzeugte Event hat dann den Namen <code>ButtonEvent</code>, und den Wert <code>MM</code>.
**<code>saveSleeptimerInAction(0,1)</code>: Wenn gesetzt, wird ein etwaig gesetztes Attribut "stopSleeptimerInAction" ignoriert.
**<code>stopSleeptimerInAction(0,1)</code>: Wenn gesetzt, wird bei einem Wechsel des transportState auf "PAUSED_PLAYBACK" oder "STOPPED" ein etwaig definierter SleepTimer deaktiviert.

=== Get-Befehle an den SONOSPLAYER ===
'''Hinweis!''': Es wurden ein paar Get-Möglichkeiten entfernt. Diese Befehle (wie z.B. ''Volume'') können mittlerweile direkt geliefert werden, und müssen nicht angefordert werden. Übrig geblieben sind nur noch solche Anweisungen, die Informationen beschaffen, die nicht automatisch geliefert werden (können).
*Grundsätzliches
**<code>Alarm <ID></code>: Ausnahmefall. Diese Get-Anweisung liefert direkt ein Hash zurück, in welchem die Informationen des Alarms mit der gegebenen ID enthalten sind. Es ist die Kurzform für <code>eval(ReadingsVal(<Devicename>, 'Alarmlist', ()))->{<ID>};</code>, damit sich nicht jeder ausdenken muss, wie er jetzt am einfachsten an die Alarm-Informationen rankommen kann.
**<code>EthernetPortStatus <PortNumber></code>: Liefert den Ethernet-Portstatus des gegebenen Ports ('0' oder '1'). Kann 'Active' oder 'Inactive' liefern.
**<code>PossibleRoomIcons</code>: Liefert eine Liste aller möglichen RoomIcon-Bezeichnungen zurück.
**<code>SupportLinks</code>: Ausnahmefall. Diese Get-Anweisung liefert eine Liste mit passenden Links zu den Supportseiten des Player.
**<code>WifiPortStatus</code>: Liefert den Wifi-Portstatus. Kann 'Active' oder 'Inactive' liefern.
*Listen
**<code>Favourites</code>: Liefert eine Liste mit den Namen aller gespeicherten Sonos-Favoriten. Das Format der Liste ist eine Komma-Separierte Liste, bei der die Namen in doppelten Anführungsstrichen stehen. z.B. "Liste 1","Eintrag 2","Test"
**<code>FavouritesWithCovers</code>: Liefert die Stringrepräsentation eines Hash mit den Namen und Covern aller gespeicherten Sonos-Favoriten. Z.B.: {'FV:2/22' => {'Cover' => 'urlzumcover', 'Title' => '1. Favorit'}}. Dieser String kann einfach mit '''eval''' in eine Perl-Datenstruktur umgewandelt werden.
**<code>Playlists</code>: Liefert eine Liste aller gespeicherten Playlists. Diese Anfrage liefert bei allen Zoneplayern die gleiche Liste zurück. Das Format ist eine Komma-Separierte Liste, bei der die Einträge in doppelten Anführungszeichen stehen z.B. "Liste 1","Liste 2","Test"
**<code>PlaylistsWithCovers</code>: Liefert die Stringrepräsentation eines Hash mit den Namen und Covern aller gespeicherten Sonos-Playlisten. Z.B.: {'SQ:14' => {'Cover' => 'urlzumcover', 'Title' => '1. Playlist'}}. Dieser String kann einfach mit '''eval''' in eine Perl-Datenstruktur umgewandelt werden.
**<code>Queue</code>: Liefert eine Liste mit den Namen aller Titel in der aktuellen Abspielliste. Das Format der Liste ist eine Komma-Separierte Liste, bei der die Namen in doppelten Anführungsstrichen stehen. z.B. "1. Liste 1 [0:02:14]","2. Eintrag 2 [k.A.]","3. Test [0:14:00]"
**<code>QueueWithCovers</code>: Liefert die Stringrepräsentation eines Hash mit den Namen und Covern aller Titel der aktuellen Abspielliste. Z.B.: {'Q:0/22' => {'Cover' => 'urlzumcover', 'Title' => '1. Titel'}}. Dieser String kann einfach mit '''eval''' in eine Perl-Datenstruktur umgewandelt werden.
**<code>Radios</code>: Liefert eine Liste aller gespeicherten Radiosender (Favoriten). Diese Anfrage liefert bei allen Zoneplayern die gleiche Liste zurück. Das Format ist eine Komma-Separierte Liste, bei der die Einträge in doppelten Anführungszeichen stehen z.B. "Sender 1","Sender 2","Test"
**<code>RadiosWithCovers</code>: Liefert die Stringrepräsentation eines Hash mit den Namen und Covern aller gespeicherten Sonos-Radiofavoriten. Z.B.: {'R:0/0/2' => {'Cover' => 'urlzumcover', 'Title' => '1. Radiosender'}}. Dieser String kann einfach mit '''eval''' in eine Perl-Datenstruktur umgewandelt werden.
**<code>SearchlistCategories</code>: Liefert eine Liste mit allen verfügbaren Kategorien, die beim Set-Befehl '''LoadSearchlist''' verwendet werden können. Diese Liste kann dynamisch durch Sonos erweitert werden.
*Informationen zum aktuellen Titel
**<code>CurrentTrackPosition</code>: Liefert die aktuelle Zeitposition im Lied

=== Set-Befehle an den SONOSPLAYER ===
'''Hinweis!''': Alle Set-Befehle liefern kein direktes Ergebnis zurück. Sollte ein Ergebnis generiert werden (meistens eine Statusmeldung, bzw. was genau getan wurde), so landet dies nach der Ausführung in dem Reading <code>LastActionResult</code>.
*Grundsätzliche Einstellungen
**<code>Alarm <Create|Update|Delete|Enable|Disable> <ID[,ID]|All> <Datenhash></code>: Diese Anweisung wird für die Bearbeitung der Alarme verwendet:
***'''Create''': Erzeugt einen neuen Alarm-Eintrag mit den übergebenen Hash-Daten. Der Rückgabewert ist die ID des neuen Alarms.
***'''Update''': Aktualisiert die Alarme mit den übergebenen IDs und den angegebenen Hash-Daten.
***'''Delete''': Löscht die Alarm-Einträge mit den übergebenen IDs.
***'''Enable''': Aktiviert die Alarm-Einträge mit den übergebenen IDs.
***'''Disable''': Deaktiviert die Alarm-Einträge mit den übergebenen IDs.
***''Hinweis'': Bei Angabe des Worts ''All'' als ID werden alle, diesem Player zugeordneten, Alarme verarbeitet.
***'''Datenhash''': Das Format ist ein Perl-Hash und wird mittels der eval-Funktion interpretiert. Eine Beschreibung befindet sich bei der Dokumentation des Readings '''AlarmList''' oder den folgenden Beispielen.
***'''Beispiele''':
****<code>set Sonos_Wohnzimmer Alarm Create 0 { Enabled => 1, Volume => 35, StartTime => '00:00:00', Duration => '00:15:00', Repeat => 0, Shuffle => 0, ProgramURI => 'x-rincon-buzzer:0', ProgramMetaData => ' ', Recurrence_Once => 0, Recurrence_Monday => 1, Recurrence_Tuesday => 1, Recurrence_Wednesday => 1, Recurrence_Thursday => 1, Recurrence_Friday => 1, Recurrence_Saturday => 0, Recurrence_Sunday => 0, IncludeLinkedZones => 0 }</code>: Erzeugt einen neuen Alarm mit den angegebenen Informationen. Die neue ID wird als Ergebnis zurückgegeben.
****<code>set Sonos_Wohnzimmer Alarm Update 17 { Shuffle => 1 }</code>: Aktualisiert den Alarm mit der ID ''17'', und passt dort Shuffle auf ''Aktiv'' an.
****<code>set Sonos_Wohnzimmer Alarm Delete 17</code>: Löscht den Alarm mit der ID ''17''.
**<code>AudioDelay <Level></code>: Setzt das AudioDelay der Playbar auf den angegebenen Wert. Der Wert kann zwischen 0 und 5 liegen.
**<code>AudioDelayLeftRear <Level></code>: Setzt den AudioDelayLeftRear des Players auf den angegebenen Wert. Der Wert kann zwischen 0 und 2 liegen. Wobei die Werte folgende Bedeutung haben: 0: >3m, 1: >0.6m und <3m, 2: <0.6m
**<code>AudioDelayRightRear <Level></code>: Setzt den AudioDelayRightRear des Players auf den angegebenen Wert. Der Wert kann zwischen 0 und 2 liegen. Wobei die Werte folgende Bedeutung haben: 0: >3m, 1: >0.6m und <3m, 2: <0.6m
**<code>ButtonLockState(0,1)</code>: Setzt den aktuellen Button-Sperr-Zustand.
**<code>DailyIndexRefreshTime <Timestring></code>: Legt die aktuell gültige ''DailyIndexRefreshTime'' fest, zu der der Medienindex neu aufgebaut werden soll. Der Wert muss ein kompletter Zeitstempel sein (HH:MM:SS).
**<code>DialogLevel <Level></code>: Legt den Zustand der Sprachverbesserung an der Playbar fest.
**<code>ExportSonosBibliothek <Filename></code>: Exportiert eine Datei mit der textuellen Darstellung eines Struktur- und Titelhashs, das die komplette Navigationsstruktur aus der Sonos-Bibliothek abbildet. Dieser Prozess braucht viel CPU-Zeit und Arbeitsspeicher zum Ermitteln und wegspeichern der Daten.
***'''Hinweis''': Richtwerte bei ca. 22.000 Titeln auf einem Windows-Server mit Intel Core i5 mit 2.8GHz: Laufzeit: ca. 28Min, Arbeitsspeicher: ca. 1GB, Resultierende Datei: ca. 90MB
**<code>Name</code>: Legt den Namen der Zone fest.
**<code>NightMode <State></code>: Legt den Zustand des Nachtsounds an der Playbar fest.
**<code>OutputFixed <State></code>: Setzt den OutputFixed-Zustand (die Lautstärkepegelsteuerung des Ausgangs des Players) auf den angegebenen Wert. Der Wert kann on oder off sein. Liefert als Ergebnis den neuen Zustand.
**<code>Reboot</code>: Führt für den Zoneplayer einen Neustart durch.
**<code>ResetAttributesToDefault <DeleteAllOtherAttributes></code>: Setzt die Attribute eines Players auf die Voreinstellung zurück, wie sie beim Anlegen des Players gesetzt waren. Wenn der Parameter "DeleteAllOtherAttributes" mit "1" oder "on" angegeben wurde, werden vor dem Setzen alle Attribute gelöscht.
**<code>RoomIcon</code>: Legt das Icon für die Zone fest.
**<code>SnoozeAlarm <Timestring|Seconds></code>: Unterbricht eine laufende Alarmwiedergabe für den übergebenen Zeitraum.
**<code>SubEnable <State></code>: Legt den Zustand des Sub-Zustands fest.
**<code>SubGain <Level></code>: Setzt den SubGain auf den angegebenen Wert. Der Wert kann zwischen -15 und 15 liegen.
**<code>SubPolarity <Level></code> Setzt den SubPolarity auf den angegebenen Wert. Der Wert kann zwischen 0 und 2 liegen.
**<code>SurroundEnable <State></code>: Legt den Zustand des Surround-Zustands fest. Liefert den aktuell gültigen Surround-Zustand.
**<code>SurroundLevel <Level></code>: Setzt den Surroundlevel auf den angegebenen Wert. Der Wert kann zwischen -15 und 15 sein.
**<code>TruePlay <State></code>: Setzt den TruePlay-Zustand.
**<code>Wifi <State></code>: Setzt den WiFi-Zustand des Players. Kann 'off', 'persist-off' oder 'on' sein.
*Abspiel-Steuerbefehle
**<code>CurrentTrackPosition <TimePosition></code>: Setzt die aktuelle Zeitposition im Lied. Man kann hier auch relative Angaben machen wie '+0:00:10' oder nur '+10'. Zusätzlich kann man auch Prozentwerte angeben wie z.B. '+10%'. Natürlich können diese Angaben auch negativ sein.
**<code>Pause</code>: Pausiert die Wiedergabe
**<code>Previous</code>: Springt zum Anfang des vorhergehenden Liedes. Das ist ein anderes Verhalten als mit einem Controller. Der Controller springt zunächst an den Anfang des aktuellen Liedes, und erst beim erneuten Drücken an den Anfang des vorhergehenden Liedes.
**<code>Play</code>: Startet die Wiedergabe
**<code>PlayURI <SongURI> [Volume]</code>: Spielt die angegebene MP3-Datei mit der optional verwendbaren Lautstärke ab. Die Datei muss vom SonosPlayer aus direkt erreichbar (und natürlich auch lesbar) sein, braucht aber nicht indiziert worden zu sein.<br />Folgende Formate werden momentan akzeptiert:
***'''Sonos-Devicenamen''': z.B. <code>Sonos_Wohnzimmer</code>. Der Devicename muss natürlich bereits definiert worden sein. Es wird der Audio(oder AV)-Eingang des gewählten Zoneplayer-Device als Wiedergabestrom gewählt.
****Bei normalen Audio-Eingängen (LineIn) kann man einen beliebigen Player für die Wiedergabe verwenden. Es muss nicht der lokale Player für die Wiedergabe verwendet werden.
****Besonderheit bei Sonos Playbar-Komponenten:<br />Wenn als Quelle eine Playbar ausgewählt wird, so wird erst die Playbar selbst auf den SPDIF-Eingang umgestellt, und anschließend eine Gruppe mit dem gewünschten Player gebildet.<br />Wenn diese Anweisung an die Playbar selbst gegeben wird, dann wird nur der SPDIF-Eingang als Quelle aktiviert.
***'''UNC-Pfade''': z.B. <code>\\Server\Freigabe\Dateiname.mp3</code>. Erkennungsmerkmal ist der Doppelte Backslash am Anfang. Darstellung aller üblichen Informationen inkl. Cover u.ä.
***'''Web-Streams''': z.B. <code>http://www.energyradio.de/hot</code>. Erkennungsmerkmal ist die Angabe von <code>http://</code> am Anfang. Es werden keine Cover aber Streaminformationen dargestellt.
***'''Sonstige URI-Typen''': z.B. <code>x-sonos-spotify:spotify:track:0jkLC0noG4A4i9lob2gSc3?sid=9&flags=0</code>. Darstellung aller üblichen Informationen. Die verfügbaren Formate können durch Sonos erweitert/verändert werden.<br />'''Hinweis''': Das Format der URI, das hier angegeben werden kann, ist stets identisch zum Reading '''currentTrackURI''', das bedeutet, dass die URI, die man dort sieht, hier direkt wieder angegeben werden kann.<br />Es gibt lediglich die oben benannte Vereinfachung für MP3-Dateien und Radio-URLs (aber auch dafür könnte man das offizielle Format angeben).
**<code>PlayURITemp <SongURI> [Volume]</code>: Spielt die angegebene MP3-Datei mit der optional verwendbaren Lautstärke als temporäre Datei ab. Nachdem die Datei abgespielt wurde, werden die vorhergehenden Abspielparameter (Lautstärke, Titel, Position usw.) wiederhergestellt. Im Normalfall geht es also direkt dort weiter, wo die Unterbrechung stattgefunden hat. Die Datei muss vom SonosPlayer aus direkt erreichbar (und natürlich auch lesbar) sein, braucht aber nicht indiziert worden zu sein. Für eine ordnungsgemäße Wiederherstellung ist es notwendig, dass dies eine Datei und kein Stream ist, da die Abspiellänge vorher bekannt sein muss.
***Für Streams (genauer: Für Dateien, deren Abspiellänge nicht ermittelt werden kann) ist dieser Aufruf identisch zu <code>PlayURI</code>, es wird im Anschluß nichts wiederhergestellt.
***Zulässige Formate stehen unter <code>PlayURI</code>.
***'''Achtung!''': Wenn bereits eine temporäre Ausgabe erfolgt, so wird die Aufforderung mit einer entsprechenden Meldung verworfen. Es kann nur eine geben :-)
**<code>Next</code>: Springt zum Anfang des nächsten Liedes
**<code>Speak <Volume> <Language> <Text></code>: Wandelt den angegebenen Text mittels Google in gesprochenen Text um und spielt diesen mittels <code>PlayURITemp</code> ab. An dieser Stelle ist zu berücksichtigen, dass der Text-Parameter auch Leerzeichen enthalten darf (und damit nach FHEM-Regeln eigentlich mehrere Parameter sind). Deswegen steht die Lautstärke vorne als nicht optionaler Parameter.
***'''Hinweis''': Im Text können MP3-File-Verweise eingebettet werden. Diese müssen vorne und hinten mit einem '''|''' und einem Leerzeichen abgetrennt werden. Außerdem darf der Dateiname selbst kein Leerzeichen enthalten.<br />Beispieltexte:
****'''|/path/to/Gong.mp3| Achtung! Achtung! Die Waschmaschine ist fertig.'''
****'''Die Datei kann auch |/path/to/Tada.mp3| mittendrin stehen.'''
****'''|/path/to/Gong.mp3| Es können auch |/path/to/Tada.mp3| mehrere Dateien eingebettet werden.'''
***'''Hinweis''': Es kann ein Standardpfad für diese Jingle-Dateien angegeben werden, dann braucht man im Text nur den Dateinamen anzugeben. Das Attribut am Sonos-Device dafür lautet ''targetSpeakMP3FileDir''. z.B.: '''/path/to'''. Des Weiteren kann die Endung ''.mp3'' auch weggelassen werden.<br />Damit können die Texte z.B. so gekürzt werden:
****'''|Gong| Achtung! Achtung! Die Waschmaschine ist fertig.'''
****'''Die Datei kann auch |Tada| mittendrin stehen.'''
****'''|Gong| Es können auch |Tada| mehrere Dateien eingebettet werden.'''
***'''Hinweis''': Eine Website mit einigen Jingles und kurzen Tönen zur kostenfreien, privaten, Verwendung ist z.B. [http://soundbible.com/tags-gong.html soundbible.com]. Dort gibt es auch Gebell und ähnliches :-)
***'''Achtung!''': Die Verkettung der diversen MP3-Dateien erfolgt durch einfaches hintereinanderschreiben. Bei verschiedenen Formaten (Mono oder Stereo, 16kHz oder 22kHz, usw.) funktioniert zwar die Wiedergabe auf dem Sonos-System fehlerfrei, allerdings werden die Zeitinformationen nicht korrekt dargestellt. Um das zu korrigieren, kann man noch nachträglich einen lokal installierten Konverter (z.B. ''avconv'') drüberlaufen lassen. Diesen kann man mit dem Sonos-Device-Attribut ''targetSpeakMP3FileConverter'' einstellen (z.B. mit ''/usr/bin/avconv -i %infile% %outfile%''). Dabei ist zu beachten, dass dieser Zeit benötigt und somit die Verzögerung der Durchsage vergrößert.
***'''Achtung!''': Für die korrekte Funktionsweise müssen die Attribute <code>targetSpeakDir</code> und <code>targetSpeakURL</code> am Sonos-Device konfiguriert sein (siehe [[#Attribute_von_SONOS|Attribute von SONOS]]).
***Mögliche Sprachparamter können bei Google herausgefunden werden. Diese sind z.B. '''de''', '''en''', '''es''', '''fr''', '''it'''...
***'''Achtung!''': Die Textlänge ist durch Google begrenzt. Wenn die Größe überschritten wird, wird die Tonerzeugung in mehrere Aufrufe unterteilt. Davon merkt man im Prinzip wenig, ausser dass die Wiedergabeverzögerung höher ist, und die Sprachmelodie an der Trennstelle etwas "holprig" wirkt.
***'''Achtung!''': Wenn bereits eine temporäre Ausgabe erfolgt, so wird die Aufforderung mit einer entsprechenden Meldung verworfen. Es kann nur eine geben :-)
**<code>StartFavourite <FavouriteName> [NoStart]</code>: Startet den angegebenen Favoriten. Der Name bezeichnet einen Eintrag in der Sonos-Favoritenliste. Der Parameter sollte/kann URL-Encoded (z.B. mittels '''uri_escape()''' oder manuell) werden um auch Spezialzeichen zu ermöglichen.<br />Siehe auch die Hinweise unter '''LoadFavourite'''.
***Wenn das Wort 'NoStart' als zweiter Parameter angegeben wurde, dann wird der Favorit geladen und fertig vorbereitet, aber nicht explizit gestartet (entspricht dann einem ''LoadFavourite'').
**<code>StartPlaylist <Playlistname> [ListeVorherLeeren]</code>: Lädt die benannte Playlist und startet sofort die Wiedergabe.<br />Zu den Parametern und Bemerkungen bitte unter '''LoadPlaylist''' nachsehen.
**<code>StartRadio <Radiostationname></code>: Lädt den benannten Radiosender, genauer gesagt, den benannten Radiofavoriten und startet sofort die Wiedergabe. Dabei wird die bestehende Abspielliste beibehalten, aber deaktiviert. Der Parameter kann/muss URL-Encoded (z.B. mittels '''uri_escape()''' oder manuell) sein, um auch Leer- und Sonderzeichen angeben zu können.
**<code>StartSearchlist <Kategoriename> <KategorieElement> [[TitelfilterRegEx]/[AlbumfilterRegEx]/[ArtistfilterRegEx] [maxElem]]</code>: Ruft den Befehl '''LoadSearchlist''' auf und startet anschließend die Wiedergabe. Zu den genauen Beschreibungen der Funktion und Parameter bitte den Set-Befehl '''LoadSearchlist''' nachschlagen.
**<code>Stop</code>: Stoppt die Wiedergabe
**<code>Track <TrackNumber></code>: Stellt das Lied an der Position TrackNumber in der Abspielliste als aktuelles Lied ein. Dabei kann als Tracknummer der Wert <code>Random</code> angegeben werden. Dann wird eine zufällige Tracknummer ausgewählt (diese Ermittlung erfolgt nach Setzen der aktuellen Abspielliste, und erfolgt somit korrekt auf die gesamte zur Verfügung stehende Liste).
*Einstellungen zum Abspielen
**<code>Balance</code>: Setzt die Balance auf den angegebenen Wert. Der Wert kann zwischen -100 (voll links) und 100 (voll rechts) liegen. Gibt die wirklich eingestellte Balance als Ergebnis zurück.
**<code>Bass</code>: Setzt den Bass-Level auf den angegebenen Wert. Der Wert kann zwischen -10 und 10 liegen.
**<code>CrossfadeMode</code>: Legt den Zustand des Crossfade-Mode fest. Liefert den aktuell gültigen Crossfade-Mode.
**<code>LEDState</code>: Legt den Zustand der LED fest. Liefert den aktuell gültigen Zustand zurück.
**<code>Loudness</code>: Aktiviert oder deaktiviert das Loudness (Bassanhebung bei geringen Lautstärken). Kann 0 oder 1 sein.
**<code>Mute <State></code>: Setzt den Mute-Zustand auf den angegebenen Wert. Der Wert kann on oder off sein. Liefert als Ergebnis den neuen Zustand.
**<code>MuteT</code>: Schaltet den Mute-Zustand um. Liefert als Ergebnis den neuen Zustand.
**<code>Repeat</code>: Legt den Zustand des Repeat-Zustands fest. Liefert den aktuell gültigen Repeat-Zustand.
**<code>RepeatOne</code>: Legt den Zustand des RepeatOne-Zustands fest. Liefert den aktuell gültigen RepeatOne-Zustand.
**<code>RepeatOneT</code>: Schaltet den Zustand des RepeatOne-Zustands um. Liefert den aktuell gültigen RepeatOne-Zustand.
**<code>RepeatT</code>: Schaltet den Zustand des Repeat-Zustands um. Liefert den aktuell gültigen Repeat-Zustand.
**<code>Shuffle</code>: Legt den Zustand des Shuffle-Zustands fest. Liefert den aktuell gültigen Shuffle-Zustand.
**<code>ShuffleT</code>: Schaltet den Zustand des Shuffle-Zustands um. Liefert den aktuell gültigen Shuffle-Zustand.
**<code>SleepTimer <Timestring|Seconds></code>: Legt den aktuellen SleepTimer fest. Der Wert muss ein kompletter Zeitstempel sein (HH:MM:SS) (oder eine Zahl in Sekunden). Zum Deaktivieren darf der Zeitstempel nur Nullen enthalten oder das Wort 'off'.
**<code>Treble</code>: Setzt den Höhen-Level auf den angegebenen Wert. Der Wert kann zwischen -10 und 10 liegen.
**<code>Volume <VolumeLevel> [RampType]</code>: Setzt die Lautstärke auf den angegebenen Wert. Der kann eine relative Angabe mittels + oder - sein. Dann wird um die entsprechende Höhe erhöht oder verringert. Wird eine relative Lautstärke angegeben, so kann diese mit einem folgenden Prozentzeichen als anteilige Änderung ausgeführt werden (z.B. +20%). Liefert als Ergebnis die neue Lautstärke.<br />Als optionaler Parameter ist ein Ramptype zulässig. Mögliche Werte sind 1 (SLEEP_TIMER_RAMP_TYPE), 2 (AUTOPLAY_RAMP_TYPE) und 3 (ALARM_RAMP_TYPE). Die Werte entsprechen verschiedenen Mustern bei der Geschwindigkeit nach oben oder unten.
**<code>VolumeD</code>: Verringert die Lautstärke um [VolumeStep]-Einheiten (Standardmäßig 7).
**<code>VolumeRestore</code>: Stellt die mittels VolumeSave gespeicherte Lautstärke wieder her.
**<code>VolumeSave <VolumeLevel></code>: Setzt die Lautstärke auf den angegebenen Wert. Der kann eine relative Angabe mittels + oder - sein. Dann wird um die entsprechende Höhe erhöht oder verringert. Liefert als Ergebnis die neue Lautstärke. Zusätzlich wird die alte Lautstärke in einem Reading abgelegt, um sie wiederherstellen zu können.
**<code>VolumeU</code>: Erhöht die Lautstärke um [VolumeStep]-Einheiten (Standardmäßig 7).
*Steuerung der aktuellen Abspielliste
**<code>AddURIToQueue <SongURI></code>: Fügt die angegebene Datei in die aktuelle Abspielliste an die Stelle hinter dem aktuellen Titel hinzu. Ändert nichts am aktuell abgespielten Titel.<br />Zulässige Formate stehen unter <code>PlayURI</code>.
***'''Achtung!''': Es kann auch ein Radio-Stream hinzugefügt werden. Dieser wird auch normal abgespielt, wenn er dran ist. Dabei ist zu beachten, dass dieser Titel nie enden wird, und die Titel- und Interpretinformationen nicht dargestellt werden. Auch nicht die sonst üblichen Streaminformationen. Diese werden nur angezeigt, wenn der Stream mittels <code>PlayURI</code> direkt (ohne Verwendung der Queue) abgespielt wird.
**<code>CurrentPlaylist</code>: Setzt den Abspielmodus auf die aktuelle Abspielliste, startet aber keine Wiedergabe (z.B. nach dem Hören eines Radiostreams, wo die aktuelle Abspielliste zwar noch existiert, aber gerade "nicht verwendet" wird)
**<code>DeleteFromQueue <index_of_elems></code>: Löscht die angegebenen Elemente aus der aktuellen Abspielliste. Die Angabe erfolgt über die Indizies der Titel. Es können die bei Perl-Array-üblichen Formate verwendet werden: "1..12,17,20..22". Die Indizies beziehen sich auf die aktuell angezeigte Reihenfolge (diese unterscheidet sich zwischen der normalen Abspielweise und dem Shufflemodus).
**<code>DeletePlaylist</code>: Löscht die bezeichnete Playliste. Zum möglichen Format des Playlistenamen unter '''LoadPlaylist''' nachsehen.
**<code>EmptyPlaylist</code>: Löscht die aktuelle Abspielliste
**<code>LoadFavourite <FavouriteName></code>: Lädt den angegebenen Favoriten. Der Name bezeichnet einen Eintrag in der Sonos-Favoritenliste. Der Parameter sollte/kann URL-Encoded (z.B. mittels '''uri_escape()''' oder manuell) werden um auch Spezialzeichen zu ermöglichen.
***'''Hinweis''': Man kann anstatt des Namens auch einen regulären Ausdruck verwenden. Es dürfen keine Leerzeichen vorkommen. Der erste Treffer wird verwendet.<br />Beispiele:
****'''/meine.hits/''' - Trifft Case-Sensitive auf z.B. '''meine hits''' zu. Auch '''meineXhits''' oder '''meine-hits''' wird gefunden.
****'''/(?i)meine.hits/''' - Trifft Case-Insensitive auf z.B. '''Meine Hits''' zu. Auch '''Meine-Hits''' wird gefunden.
***Folgende Unterscheidungen werden auf Basis des Typs des Sonos-Favoriten gemacht:
****Bei einem Playlist-Typ (z.B. Sonos-Playlist, Spotify-Playlist, usw.) wird die aktuelle Abspielliste geleert, mit dem neuen Inhalt befüllt und die Wiedergabe gestartet
****Bei einem Einzel-Eintrag (Direkter Titel, Radiosender, Spotify-Titel, usw) wird die aktuelle Abspielliste nicht angetastet, sondern der aktuelle Abspieleintrag entsprechend angepasst und gestartet
**<code>LoadPlaylist <Playlistname|FHEM-Devicename> [ListeVorherLeeren]</code>: Lädt die benannte Playliste in die aktuelle Abspielliste. Der Parameter kann/muss URL-Encoded (z.B. mittels '''uri_escape()''' oder manuell) sein, um auch Leer- und Sonderzeichen angeben zu können. Wenn der Parameter ''ListeVorherLeeren'' mit ''1'' angegeben wurde, wird die aktuelle Abspielliste vor dem Import geleert. Standardmäßig wird hier eine ''1'' angenommen.
***'''Hinweis''': Man kann anstatt des Namens auch einen FHEM-Sonosplayer-Devicenamen angeben. Dann wird dessen aktuelle Abspielliste zum Player übertragen/kopiert.
***'''Hinweis''': Man kann anstatt des Namens auch einen regulären Ausdruck verwenden. Es dürfen keine Leerzeichen vorkommen. Der erste Treffer wird verwendet.<br />Beispiele:
****'''/meine.hits/''' - Trifft Case-Sensitive auf z.B. '''meine hits''' zu. Auch '''meineXhits''' oder '''meine-hits''' wird gefunden.
****'''/(?i)meine.hits/''' - Trifft Case-Insensitive auf z.B. '''Meine Hits''' zu. Auch '''Meine-Hits''' wird gefunden.
***'''Hinweis''': Es kann auch ein Dateiname angegeben werden, um eine übliche M3U-Datei aus dem Filesystem zu laden. Dieser muss mit "'''file:'''" eingeleitet werden. Beispiel: "'''file:c:/Test.m3u'''".<br />Innerhalb der Datei selbst werden bislang folgende Sonderformate unterstützt:
****'''Spotify:''' Titel aus Spotify werden mit dem Kürzel ''x-sonos-spotify:'' begonnen.
****'''Napster/Rhapsody:''' Titel aus Napster/Rhapsody werden mit dem Kürzel ''npsdy:'' begonnen.
****''Hinweise'': Die Benutzernamen für diese Importe, die zum Zeitpunkt des Import bekannt sein müssen, müssen zuvor dem System bekannt gemacht werden. Ansonsten erscheint eine entsprechende Fehlermeldung.<br />So kann der Benutzername für eines der Systeme bekannt gemacht werden:
*****Aktuelle Abspielliste eines Players leeren
*****Einen beliebigen Titel aus dem gewünschten Anbieter in die aktuelle Abspielliste einfügen. Dabei ist zu beachten, dass man das direkt aus der Auswahl des Anbietes heraus macht (also nicht über eine Playliste, Favoriten o.ä. Direktzugriffe)
*****Nun gibt es ein neues Reading am zentralen Sonos-Device, welches den Benutzernamen enthält. Um diesen Dauerhaft bereitzustellen, muss der Zustand mittels ''save'' gespeichert werden.
**<code>LoadRadio <Radiostationname></code>: Lädt den benannten Radiosender, genauer gesagt, den benannten Radiofavoriten. Dabei wird die bestehende Abspielliste beibehalten, aber deaktiviert. Der Parameter kann/muss URL-Encoded sein, um auch Leer- und Sonderzeichen angeben zu können.
***'''Hinweis''': Man kann anstatt des Namens auch einen regulären Ausdruck verwenden. Es dürfen keine Leerzeichen vorkommen. Der erste Treffer wird verwendet.<br />Beispiele:
****'''/NRJ.90s/''' - Trifft Case-Sensitive auf z.B. '''NRJ 90s''' zu. Auch '''NRJx90s''' oder '''NRJ-90s''' wird gefunden.
****'''/(?i)nrj.90s/''' - Trifft Case-Insensitive auf z.B. '''NRJ 90s''' zu. Auch '''NRJ-90s''' wird gefunden.
**<code>LoadSearchlist <Kategoriename> <KategorieElement> [[TitelfilterRegEx]/[AlbumFilterRegEx]/[ArtistfilterRegEx] [[*]maxElem[+|-]]]</code>: Hiermit kann die aktuelle Abspielliste mit Suchergebnissen aus der Sonos-Bibliothek gefüllt werden.<br />Dazu kann man sich im Controller anschauen, wie die Suchstruktur aufgebaut ist:
***'''Kategoriename''': kann "Albums", "Artists", "Composers", "Contributing Artists", "Genres", "Playlists" oder "Tracks" sein. Leerzeichen müssen wie immer URI-Encoded sein (also ''%20''). Diese Liste kann mit dem Get-Befehl ''SearchlistCategories'' ermittelt werden, da Sonos auch neue hinzufügen könnte.<br />Man kann hier einen regulären Ausdruck mit ''/'' eingeschlossen angeben, z.B. ''/Contr.*/''.
***'''KategorieElement''': enthält einen zur Suchkategorie passenden Wert als gesamten Match. Kann/muss URI-Encoded (z.B. mittels '''uri_escape()''' oder manuell) sein.<br />Man kann hier auch einen regulären Ausdruck mit ''/'' eingeschlossen angeben, z.B. ''/(?i)udo.jürgens/''.
***'''Filter''': Man kann reguläre Ausdrücke als Titel-, Album- oder Artistfilter angeben, der als ein Parameter mit ''/'' getrennt angegeben werden muss.<br />Dieser Filter filtert die durch die beiden vorangehenden Werten vorgegebene Liste getrennt nach Titel, Album oder Artist, z.B. ''(?i)haus'' (enthält dann alles, was auf Haus im Titel ohne Berücksichtigung der Groß-/Kleinschreibung passt) oder ''(?i)haus//(?i)udo'' (enhält dann alles, was auf den Titel ''Haus'' und den Interpret ''Udo'' ohne Berücksichtigung der Groß-/Kleinschreibung passt) sowie z.B. ''/(?i)Best.of/'' (enthält dann alle Best-of-Alben beliebiger Interpreten).
****'''Beispiele''' für den Filter-Parameter:
*****<code>//Udo</code>: Filtert nach dem Interpretenbestandteil ''Udo'', der Titel ist beliebig. Alternative Schreibweise: <code>.*/.*/Udo</code>
*****<code>Sahne</code>: Filtert nach dem Titelbestandteil ''Sahne'', das Album und der Interpret sind beliebig. Alternative Schreibweisen: <code>Sahne/.*/.*</code> oder <code>Sahne//</code>.
*****<code>Sahne//Udo</code>: Filtert nach dem Titelbestandteil ''Sahne'' und dem Interpretenbestandteil ''Udo''
*****<code>(?i)sahne//(?i)udo</code>: Filtert nach dem Titelbestandteil ''sahne'' und dem Interpretenbestandteil ''udo'' ohne die Groß-/Kleinschreibung zu berücksichtigen.
*****<code>/(?i)best.of/</code>: Filtert nach dem Albumtitel Best-of. Alternative Schreibweisen: <code>.*/(?i)best.of</code> oder <code>.*/(?i)best.of/.*</code>
***'''maxElem''': Hiermit kann eine Begrenzung der einzutragenden Element angegeben werden. Des Weiteren kann hier durch ein vorangestelltes ''*'' eine Durchmischung der Ausgangsmenge erreicht werden, und durch ein nachgestelltes ''-'' das Leeren der aktuellen Abspielliste erreicht werden. Durch ein nachgestelltes ''+'' wird ein Anhängen der gefundenen Titel an das Ende der aktuellen Abspielliste erreicht (sonst wird hinter dem aktuellen Titel eingefügt).<br />Eine Angabe von 0 übernimmt alle verfügbaren Titel.<br />Diese Mengenbegrenzung erfolgt erst nach Anwendung der Filter auf die Ausgangsmenge (die Durchmischung ebenfalls). z.B. ''*20-'' (es werden nur 20 Titel ausgesucht, die Ausgangsmenge wird zuvor zufällig gemischt, und die aktuelle Abspielliste vor dem Einfügen geleert), ''*10'' (es werden 10 zufällige Titel zu der Abspielliste an der aktuellen Stelle hinzugefügt) oder ''10'' (es werden die ersten 10 Titel zu der Abspielliste an der aktuellen Stelle hinzugefügt).
***'''Hinweis''': Wenn die Kategorie ''Tracks'' verwendet wird, wird der zweite Parameter (''KategorieElement'') nicht verwendet. Dieser muss als Platzhalter trotzdem vorhanden sein, und kann z.B. mit einem Punkt ''.'' angegeben werden.
***'''Achtung''': Wenn die Kategorie ''Tracks'' verwendet wird, werden *alle* Titel, die in der Sonos-Bibliothek enthalten sind, durchsucht. Das kann bei einer Bibliothek mit 20.000 Titeln locker mal 4 Minuten dauern. Dabei wird die Zeit hauptsächlich vom Sonosplayer verbraucht; Es ist also für die Laufzeit nicht relevant, ob das Modul z.B. auf einem Raspberry Pi oder einer leistungsfähigeren Hardware läuft.<br />Bitte beachten, das während dieser Zeit keine Sonos-Nachrichten verarbeitet werden, und keine Befehle an die Player gesendet werden können. FHEM wird währenddessen nicht blockiert.
***'''Beispiele'''<br />Bitte beachten, dass sich die Möglichkeiten nach der zugrundeliegenden Bibliothek richten.
****<code>set Sonos_Wohnzimmer LoadSearchlist Genres Synthpop .*/(?i)pet *20-</code>: Hier wird das Genre ''Synthpop'' als Ausgangsliste verwendet und nach Interpreten mit ''pet'' gefiltert. Von dieser Menge werden 20 zufällige Einträge in die Abspielliste übernommen, die vorher geleert wurde.
****<code>set Sonos_Wohnzimmer LoadSearchlist /(?i)contr.*/ /(?i)pet.*?shop.*?boys/ / *10-</code>: Hier werden die Teilnehmenden Interpreten nach den ''Pet Shop Boys'' durchsucht, und anschließend aus dieser Liste 10 beliebige Titel in die vorher geleerte Abspielliste übertragen. Es erfolgt keine zusätzliche Filterung.
****<code>set Sonos_Wohnzimmer LoadSearchlist Tracks . / *50-</code>: Hier werden 50 beliebige Titel aus der gesamten Bibliothek in die Abspielliste übertragen. Bitte Hinweis zur Laufzeit beachten.
****<code>set Sonos_Wohnzimmer LoadSearchlist Tracks . /(?i)best.of/ *50-</code>: Hier werden 50 zufällige Titel von Best-of-Alben aus der gesamten Bibliothek in die Abspielliste übertragen. Bitte Hinweis zur Laufzeit beachten.
**<code>SavePlaylist <Playlistname></code>: Speichert die aktuelle Abspielliste unter dem angegebenen Namen als Playliste ab. Dabei wird eine etwaig bestehende Liste gleichen Namens überschrieben. Der Parameter kann/muss URL-Encoded (z.B. mittels '''uri_escape()''' oder manuell) sein, um auch Leer- und Sonderzeichen angeben zu können.
***'''Hinweis''': Es kann auch ein Dateiname angegeben werden, um eine übliche M3U-Datei im Filesystem zu erzeugen. Dieser muss mit "'''file:'''" eingeleitet werden. Beispiel: "'''file:c:/Test.m3u'''".<br />''Nähere Informationen zum möglichen Inhalt der Datei siehe unter '''LoadPlayList'''.''
*Gruppenbefehle
**<code>AddMember <Devicename></code>: Fügt dem Device das übergebene Device als Gruppenmitglied hinzu. Die Wiedergabe des aktuellen Devices bleibt erhalten, und wird auf das angegebene Device mit übertragen.
**<code>CreateStereoPair <rightPlayerDevicename></code>: Fügt dem Device das übergebene Device als rechtes Stereopaar-Element hinzu. Die Wiedergabe des aktuellen Devices bleibt erhalten (als linker Lautsprecher), und wird auf das angegebene Device mit übertragen (als rechter Lautsprecher).
**<code>GroupMute <State></code>: Setzt den Mute-Zustand für die komplette Gruppe in einem Schritt. Der Wert kann on oder off sein.
**<code>GroupVolume <VolumeLevel></code>: Setzt die Gruppenlautstärke. Das dafür verwendete Lautstärkenverhältnis muss zuvor einmal mittels der Anweisung '''SnapshotGroupVolume''' festgelegt worden sein.
***''Hinweis'': Wenn man '''GroupVolume''' aufruft, ohne vorher '''SnapshotGroupVolume''' aufgerufen zu haben, wird nur die Lautstärke des Players verändert wird, für den man den Aufruf durchführt.
**<code>MakeStandaloneGroup</code>: Macht diesen Player zu seiner eigenen Gruppe.
**<code>RemoveMember <Devicename></code>: Entfernt dem Device das übergebene Device, sodass die beiden keine Gruppe mehr bilden. Die Wiedergabe des aktuellen Devices läuft normal weiter. Das abgetrennte Device stoppt seine Wiedergabe, und hat keine aktuelle Abspielliste mehr (seit Sonos Version 4.2 hat der Player wieder die Playliste von vorher aktiv).
**<code>SeparateStereoPair</code>: Trennt das Stereopaar wieder auf.
**<code>SnapshotGroupVolume</code>: Legt das Lautstärkeverhältnis der aktuellen Player der Gruppe für folgende '''GroupVolume'''-Aufrufe fest. Dieses festgelegte Verhältnis wird bis zum nächsten Aufruf von '''SnapshotGroupVolume''' beibehalten.
***''Hinweis'': Das einzelne Verstellen von Zoneplayer-Laustärken mittels '''Volume''' wird nicht im bereits gespeicherten Lautstärkenverhältnis aktualisiert/widergespiegelt. Hat man also nachträglich die Lautstärke eines einzelnen Players geändert (auch über den Controller), so muss '''SnapshotGroupVolume''' erneut aufgerufen werden, damit das Verhältnis bei einer weiteren Gruppenlautstärkenänderung wieder erhalten bleibt (ansonsten wird das alte Verhältnis vor der Lautstärkeänderung wiederhergestellt).
***''Hinweis'': Dieser Aufruf muss vor einem eventuellen Aufruf von '''GroupVolume''' erfolgen, da sonst nur die Lautstärke des Players verändert wird, für den man den Aufruf durchführt.
***''Beispiel'' für eine Gruppe mit stark verschiedenen Lautstärken:
****Aufruf von '''SnapshotGroupVolume''' => Aktuelles Lautstärkeverhältnis wird gespeichert
****Aufruf von '''GroupVolume 2''' => Gruppe wird sehr leise gestellt, dabei sieht das relative Lautstärkeverhältnis fast gleich aus, da sich die Abstände immer weiter annähern
****Aufruf von '''GroupVolume 35''' => Gruppe wird laut gestellt, dabei kommt wieder das vorhergehende Lautstärkeverhältnis zum tragen

== Nützliche Hilfs-Prozeduren aus den Modulen ==
Das Modul liefert eine Menge kleiner Hilfs-Prozeduren mit, die teilweise auch für die eigene Verwendung interessant sein können.

*Grundsätzliches
**<code>SONOS_getAllSonosplayerDevices()</code>: Liefert ein Array mit allen Sonosplayerdevices, die in FHEM definiert sind.<br />'''Beispiel''':
***<code>my @allPlayer = SONOS_getAllSonosplayerDevices();</code><br />Liefert alle Sonosplayer.
**<code>SONOSPLAYER_DeleteIfExists($name)</code>: Löscht das Device mit dem übergebenen Namen, wenn es existiert.<br />'''Beispiel''':
***<code>SONOSPLAYER_DeleteIfExists('Sonos_Wohnzimmer');</code><br />Löscht das Device mit dem Namen ''Sonos_Wohnzimmer'', sofern es existiert. Es wird also keine Fehlermeldung erzeugt, wenn das Device nicht existiert.
**<code>SONOS_GetTimeSeconds($timeStr)</code>: Liefert die Anzahl der Sekunden, die vom übergebenen Zeitstring beschrieben werden. Der Zeitstring muss vom Format "H:M:S" sein. Die Zahlen könne auch mehrere Stellen umfassen.<br />'''Beispiel''':
***<code>my $sec = SONOS_GetTimeSeconds('0:04:12')</code><br />Liefert die Anzahl der Sekunden des String '0:04:12', in diesem Fall also ''252''.
**<code>SONOS_LoadExportedSonosBibliothek($fileName, $deviceName, $internalName)</code>: Lädt die angegebene Datei in das übergebene Device in das übergebene Internal. Vorher wird der Dateiinhalt per '''eval()''' in eine interne Datenstruktur umgewandelt. Damit kann eine zuvor mit '''ExportSonosBibliothek''' erzeugte Datei als Hash in ein beliebiges FHEM-Device eingelesen werden.<br />'''Beispiel''':
***<code>SONOS_LoadExportedSonosBibliothek('c:/data.txt', 'MyDummyDevice', 'Bibliothek');</code><br />Lädt die Datei '''c:/data.txt''' zunächst in einen Hash ein, und weist diesen Hash dann dem Device '''MyDummyDevice''' (kann ein beliebiges FHEM-Device sein) dem Internal '''Bibliothek''' zu.
**<code>SONOS_Max($param1, $param2)</code>: Liefert den größeren der beiden übergebenen Parameter zurück.<br />'''Beispiel''':
***<code>my $min = SONOS_Min(15, 23);</code><br />Das Ergebnis ist ''23'', da es der größere der beiden Werte ist.
**<code>SONOS_Min($param1, $param2)</code>: Liefert den kleineren der beiden übergebenen Parameter zurück.<br />'''Beispiel''':
***<code>my $min = SONOS_Min(15, 23);</code><br />Das Ergebnis ist ''15'', da es der kleinere der beiden Werte ist.
**<code>SONOS_isInList($search, @list)</code>: Liefert ''1'', wenn ''$search'' in ''@list'' enthalten ist, sonst ''0''.<br />'''Beispiel''':
***<code>my $exists = SONOS_isInList('Eins', qw(Eins Zwei Drei));</code><br />Das Ergebnis ist ''true'' (bzw. ''1''), da der String ''Eins'' in der Liste enthalten ist.
**<code>SONOS_posInList($search, @list)</code>: Liefert die Position des gefundenen Strings ''$search'' in der Liste ''@list'', wenn ''$search'' in ''@list'' enthalten ist, sonst ''-1''. Zählt 0-basiert.<br />'''Beispiele''':
***<code>my $pos = SONOS_posInList('Eins', qw(Eins Zwei Drei));</code><br />Das Ergebnis ist ''0'', da der String ''Eins'' in der Liste an der ersten Stelle enthalten ist.
***<code>my $pos = SONOS_posInList('Eins', qw(Zwei Eins Drei));</code><br />Das Ergebnis ist ''1'', da der String ''Eins'' in der Liste an der zweiten Stelle enthalten ist.
***<code>my $pos = SONOS_posInList('Vier', qw(Eins Zwei Drei));</code><br />Das Ergebnis ist ''-1'', da der String ''Vier'' in der Liste nicht enthalten ist.
**<code>SONOS_Stringify($elem)</code>: Liefert eine Stringrepräsentation der übergebenen Datenstruktur. Diese Struktur darf nicht rekursiv sein, da sonst eine Endlosschleife auftritt.<br />'''Beispiel''':
***<code>my @list = qw(Eins Zwei Drei); my $string = SONOS_Stringify(\@list);</code><br />Liefert eine Stringrepräsentation des Arrayparameters. In diesem Fall also <code>['Eins', 'Zwei', 'Drei']</code>
*Gruppenfunktionen
**<code>SONOSPLAYER_GetMasterPlayerName($name)</code>: Liefert den Namen des Masterplayerdevices zu einem übergebenen Sonosplayer-Devicenamen. Sollte der Player nicht Bestandteil einer Gruppe sein, dann wird der Name des übergebenen Players zurückgegeben.<br />'''Beispiel''':
***<code>my $groupMasterName = SONOSPLAYER_GetMasterPlayerName('Sonos_Wohnzimmer');</code><br />Liefert den Masterplayernamen der Gruppe, in der sich der Wohnzimmerplayer gerade befindet.
**<code>SONOSPLAYER_GetSlavePlayerNames($name)</code>: Liefert die Teilnehmer einer Gruppe. Der Master wird nicht mit zurückgegeben. Man kann den Namen eines beliebigen Teilnehmers angeben.<br />'''Beispiel''':
***<code>my @member = SONOSPLAYER_GetSlavePlayerNames('Sonos_Wohnzimmer');</code><br />Liefert alle Teilnehmer der Gruppe in der sich der Player ''Sonos_Wohnzimmer'' gerade befindet. Der Master der Gruppe wird nicht mitgeliefert.
**<code>SONOSPLAYER_GetRealTargetPlayerHash($hash)</code>: Liefert den Hash des Masterplayerdevices zu einem übergebenen Sonosplayer-Devicehash. Sollte der Player nicht Bestandteil einer Gruppe sein, dann wird der Hash des übergebenen Players zurückgegeben.<br />'''Beispiel''':
***<code>my $groupMasterHash = SONOSPLAYER_GetRealTargetPlayerHash($defs{'Sonos_Wohnzimmer'});</code><br />Liefert den Masterplayerhash der Gruppe, in der sich der Wohnzimmerplayer gerade befindet.

=== Die Funktionalität "ExportSonosBibliothek" ===
Die Funktionalität ''ExportSonosBibliothek'' ermöglicht einen kompletten Export der Struktur und Titelinformationen wie sie in dem Bereich ''Bibliothek'' des Sonos-Controllers dargestellt wird.
Dabei wird ein großer Perl-Hash erzeugt, der sowohl die Struktur als auch die eigentlichen Titel enthält. Im Bereich ''Struktur'' werden auf unterster (Titel-)Ebene die IDs der zugehörigen Titel als Verweis abgelegt, sodass man diese nicht mehrfach im Hash vorliegen hat.
Im Bereich ''Titel'' werden alle irgendwo referenzierten Titel mit ihren IDs und allen von Sonos übermittelten Informationen abgelegt.

Das Ermitteln dauert einige Zeit. Als Beispiel: Mein WindowsServer mit Intel Core i5 mit 2.8GHz benötigt für meine ca. 22.000 Titel 28 Minuten und 1GB RAM zum Ermitteln. Die resultierende Datendatei ist ca. 90MB groß.

==== Das Grundkonzept ====
Es gibt einen Setter ''ExportSonosBibliothek'' am Sonosplayer-Device, der eine Datei mit dem übergebenen Dateinamen erzeugt. In dieser Datei wird der komplette Datenhash als textuelle, und damit per <code>eval()</code> einlesbare, Darstellung gespeichert.
Die Cover der Titel werden als Aufruf auf den verwendeten Player erzeugt, und es wird berücksichtigt, ob man die Proxy-Einstellung aktiviert hat.

Um diese Datei wieder einzulesen, kann die mitgelieferte Prozedur <code>SONOS_LoadExportedSonosBibliothek($fileName, $deviceName, $internalName)</code> verwendet werden. Diese legt den geladenen Datenhash in einem Internal mit übergebenem Namen im benannten FHEM-Device ab. Das muss kein Sonosplayer-Device sein, sondern kann auch ein Dummy bzw. ein beliebiges FHEM-Device sein.

Von hier aus kann man mit anderen Methodiken auf diese Daten zugreifen. Durch die Dateiablage kann die Datei auch über einen Neustart hinweg verwendet werden, da die Ermittlung ja etwas Zeit in Anspruch nimmt.

'''Hinweis''': Mit Vorsicht ist z.B. der Bereich unter ''Tracks'' zu sehen, da dort alle(!) Titel auftauchen werden. Das kann eine Auswahlmöglichkeit auf einer (Web-)Oberfläche schnell mal sprengen.

==== Das Datenformat ====
Grundsätzlich gibt es zwei Bereiche im Hash: Einen für die Struktur und einen für die Titel.
Die Struktur ist dann mit einem dynamischen Unterbaum ausgestattet, um die nächsten Ebenen zu repräsentieren. Welche Ebenen dort vohanden sind, und wie tief die Verschachtelung geht, kann sich u.U. in Zukunft ändern, wenn Sonos dort Anpassungen vornimmt.
Die Titel sind als eine Liste ohne weitere Verschachtelung abgelegt.

Hier der Hash mit einigen Dummy-Beispieldaten, um den Inhalt zu verdeutlichen:
<pre>
my $hash =
{'Structure' => {
'A:PLAYLISTS' => {
'ID' => 'A:PLAYLISTS',
'Type' => 'Container',
'Title' => 'Playlists',
'Children' => {}
},
'A:GENRE' => {
'ID' => 'A:GENRE',
'Type' => 'Container',
'Title' => 'Genres',
'Children' => {}
},
'A:ALBUM' => {
'ID' => 'A:ALBUM',
'Type' => 'Container',
'Title' => 'Albums',
'Children' => {
'A:ALBUM/Chaos' => {
'ID' => 'A:ALBUM/Chaos',
'Type' => 'Container',
'Title' => 'Chaos',
'Artist' => 'Herbert Grönemeyer',
'Cover' => '/Pfad/zum/Cover/auch/mit/proxy/pfad',
'Children' => {
'TitleID1' => {
'ID' => 'TitleID1',
'Type' => 'Track'
},
'TitleID2' => {
'ID' => 'TitleID2',
'Type' => 'Track'
},
}
},
'A:ALBUM/Testalbum' => {
'ID' => 'A:ALBUM/Testalbum',
'Type' => 'Container',
'Title' => 'Testalbum',
'Artist' => 'Hansi Fischer',
'Cover' => '/Pfad/zum/Cover/auch/mit/proxy/pfad',
'Children' => {
'TitleID1' => {
'ID' => 'TitleID3',
'Type' => 'Track'
},
'TitleID2' => {
'ID' => 'TitleID4',
'Type' => 'Track'
},
}
}
}
},
'A:TRACKS' => {
'ID' => 'A:TRACKS',
'Type' => 'Container',
'Title' => 'Tracks',
'Children' => {}
},
'A:COMPOSER' => {
'ID' => 'A:COMPOSER',
'Type' => 'Container',
'Title' => 'Composers',
'Children' => {}
},
'A:ARTIST' => {
'ID' => 'A:ARTIST',
'Type' => 'Container',
'Title' => 'Contributing Artists',
'Children' => {}
},
'A:ALBUMARTIST' => {
'ID' => 'A:ALBUMARTIST',
'Type' => 'Container',
'Title' => 'Artists',
'Children' => {}
}
},
'Titles' => {
'TitleID1' => {
'ID' => 'TitleID1',
'TrackURI' => '/Pfad/zur/Datei.mp3',
'Title' => 'Titel des Musikstücks',
'Artist' => 'Interpret des Musikstücks',
'Album' => 'Titel des Albums',
'AlbumArtist' => 'Interpret des Albums',
'Cover' => '/Pfad/zum/Cover/auch/mit/proxy/pfad',
'OriginalTrackNumber' => 5
},
'TitleIDn' => {
'ID' => 'TitleIDn',
'TrackURI' => '/Pfad/zur/Datei.mp3',
'Title' => 'Titel des Musikstücks',
'Artist' => 'Interpret des Musikstücks',
'Album' => 'Titel des Albums',
'AlbumArtist' => 'Interpret des Albums',
'Cover' => '/Pfad/zum/Cover/auch/mit/proxy/pfad',
'OriginalTrackNumber' => 5
}
}
}
</pre>

==== Wie kann es angezeigt werden? ====
(Das soll noch erweitert werden...)

== Was wird alles automatisch erzeugt? ==
Hier soll kurz beschrieben werden, welche Elemente der automatische Erkennungsprozess anlegt, und welche Funktion diese haben.

=== Automatische Zoneplayererkennung ===
Erkannte Zoneplayer werden als '''SONOSPLAYER'''-Device angelegt:

<pre>define Sonos_Wohnzimmer SONOSPLAYER RINCON_000E5828D0F401400_MR</pre>

Der Name des Device wird aus dem Namen des SONOS-Device und dem Namen der Zone gebildet. Dabei werden Leer- und Sonderzeichen in "<code>_</code>" umgewandelt.

Beim Anlegen werden automatisch einige Attribute mit angelegt, am Beispiel eines Wohnzimmer-Players:
<pre>
attr Sonos_Wohnzimmer generateInfoSummarize1 <NormalAudio><Artist prefix="(" suffix=")"/>
<Title prefix=" '" suffix="'" ifempty="[Keine Musikdatei]"/>
<Album prefix=" vom Album '" suffix="'"/></NormalAudio>
<StreamAudio><Sender suffix=":"/><SenderCurrent prefix=" '" suffix="' -"/>
<SenderInfo prefix=" "/></StreamAudio>
attr Sonos_Wohnzimmer generateInfoSummarize2 <TransportState/><InfoSummarize1 prefix=" => "/>
attr Sonos_Wohnzimmer generateInfoSummarize3 <Volume prefix="Lautstärke: "/>
<Mute instead=" ~ Kein Ton" ifempty=" ~ Ton An" emptyval="0"/>
~ Balance: <Balance ifempty="Mitte" emptyval="0"/>
<HeadphoneConnected instead=" ~ Kopfhörer aktiv"
ifempty=" ~ Kein Kopfhörer" emptyval="0"/>
attr Sonos_Wohnzimmer icon icoSONOSPLAYER_icon-ZP90.png
attr Sonos_Wohnzimmer room Sonos
attr Sonos_Wohnzimmer stateVariable presence
attr Sonos_Wohnzimmer group Wohnzimmer
</pre>

Dadurch ist dieses Device direkt in der FHEM-Oberfläche steuerbar. Auch hier gilt, dass man das natürlich anpassen kann. Das sollen nur vereinfachende Vorgaben sein.
Das Attribut "<code>room</code>" wird wieder aus dem Namen des SONOS-Device gebildet.
Das Attribut "<code>group</code>" wird aus dem Namen der Zone gebildet

=== Zusätzliche Readingsgroups, die zunächst nichts anzeigen ===
Es werden zusätzliche [[readingsGroup]]s angelegt, die zunächst keine Inhalte anzeigen. Diese lesen das der Readingsgroup entsprechende Reading ''Favourites'', ''Radios'' oder ''Playlists'' aus.
Um diese Readings zu füllen gibt es bereits ein angelegtes '''userReadings''', welches auf die Get-Aufrufe von ''FavouritesWithCovers'', ''RadiosWithCovers'' oder ''PlaylistsWithCovers'' reagiert und die entsprechenden Readings füllt.

Unter [[#Beispiel für eine ReadingsGroup für die Darstellung von Listen (Favoriten, Playlisten und Radios)|Beispiel für eine ReadingsGroup für die Darstellung von Listen (Favoriten, Playlisten und Radios)]] gibt es Beispiele für ein at-Statement, mit dem diese Readings automatisch gefüllt werden können.
Damit werden diese auch in FHEM aktualisiert, wenn man diese am Sonos-Controller verändert.

=== Definition der InfoSummarize ===
<pre>
infoSummarizeX := <NormalAudio>:sumElem:</NormalAudio> <StreamAudio>:sumElem:</StreamAudio>|
:sumElem:
sumElem := <:variable:[ prefix=":text:"][ suffix=":text:"][ instead=":text:"]
[ ifempty=":text:"][ emptyval=":text:"]/>
variable := TransportState|NumberOfTracks|Track|TrackDuration|Title|Artist|Album|
OriginalTrackNumber|AlbumArtist|Sender|SenderCurrent|SenderInfo|StreamAudio|NormalAudio|
AlbumArtURI|nextTrackDuration|nextTrackURI|nextAlbumArtURI|nextTitle|nextArtist|
nextAlbum|nextAlbumArtist|nextOriginalTrackNumber|Volume|Mute|Shuffle|Repeat|RepeatOne|
CrossfadeMode|Balance|HeadphoneConnected|SleepTimer|Presence|RoomName|RoomNameAlias|
SaveRoomName|PlayerType|Location|SoftwareRevision|SerialNum|InfoSummarize1|InfoSummarize2|
InfoSummarize3|InfoSummarize4
text := [Beliebiger Text ohne doppelte Anführungszeichen]
</pre>
Die Unterscheidung zwischen <code><NormalAudio></code> und <code><StreamAudio></code> liegt bei der anliegenden Musikquelle. Gestreamte Audioquellen habe nur einen kleineren Set an Informationen vorliegen, während bei einer "normalen" Musikquelle z.B. eine Unterscheidung zwischen Artist und Title gemacht wird, und im Gegenzug z.B. kein Sendername existiert.<br />
Man kann diese Unterscheidung auch weglassen, und direkt die Variablenausgaben hinschreiben. Dann gilt der Code für beide Musikquellenarten gleichermaßen (u.U. sind dann einige Felder nicht sinnvoll bzw. gar nicht gefüllt).

Die Tag-Erweiterungen <code>prefix</code> und <code>suffix</code> werden jeweils vor bzw. hinter den Feldwert in die Ausgabe gesetzt, wenn es einen Feldwert zum Ausgeben gibt. <br />
Die Erweiterung <code>instead</code> wird anstatt des Feldwerts ausgegeben, wenn normalerweise der Feldwert ausgegeben werden würde (abhängig davon, ob der Feldwert als ''empty'' angesehen wird, oder nicht).<br />
Die Erweiterung <code>ifempty</code> wird eingesetzt, wenn es gerade ''keinen'' Feldinhalt gibt. In diesem Fall werden natürlich auch keine Pre- und Suffixe sowie Instead-Angaben ausgegeben.<br />
Die Erweiterung <code>emptyval</code> legt fest, was neben einem undefinierten Feldwert noch als ''leer'' gelten soll. Dies ist interessant, wenn man z.B. den Zahlwert ''0'' als ''leer'' festlegen möchte.<br />
Beim Definieren dieser Erweiterungen ist zu beachten, dass keine doppelten Anführungszeichen angegeben werden. Diese zerstören die weitere, interne Verarbeitung durch FHEM (Irgendwas ist immer :-)
Desweiteren können Verweise auf andere <code>InfoSummarize</code>-Felder nur in aufsteigender Reihenfolge erfolgen. Es sind also keine Vorwärtsreferenzen oder Rekursionen möglich.

== Fehlende Kommandos ==
Sollte eine Steuerungsmöglichkeit oder Information fehlen, oder anderes gewünscht sein, dann einfach eine Nachricht ins Forum. Meistens läßt sich da was machen :-)

=== Ideenpipeline ===
Folgende Ideen sind bereits in der gedanklichen Pipeline. Aber alles Schritt für Schritt und der Reihe nach:
*'''Momentan Leer'''

Erledigte Ideen:
*'''Zwischendurchsage''': Eine Datei abspielen, und danach wieder an der alten Stelle mit der alten Lautstärke weiterspielen (In Version 1.5 hinzugekommen)
*'''Beliebige MP3s in die Queue legen oder abspielen''': Entgegen dem Controllergefühl kann man sehr wohl völlig frei abspielbare Dateien in der Queue haben. Es kann nur sein, das man kein Cover oder ähnliches angezeigt bekommt (noch zu testen). (In Version 1.5 hinzugekommen, Cover funktionieren wie immer)
*'''Beliebige Radiostationen abspielen''': Hier gilt das gleich wie für die MP3s. (In Version 1.5 hinzugekommen, Cover und Streaminformationen funktionieren beim Direktabspielen, aus der Queue heraus wird nur der Stream abgespielt)
*'''Lautstärkegrenzen festlegen''': Damit soll festgelegt werden können, in welchen Grenzen die Lautstärke überhaupt verändert werden kann. Das soll in der entsprechenden Zone natürlich auch für die normalen Sonos-Controller gelten. Dabei werden explizit ''keine'' Readings im FHEM aktualisiert, da eine Lautstärkeänderung sonst von der Verarbeitungsgeschwindigkeit von FHEM (inkl. seiner Notifies) abhängig wäre. (In Version 1.8 hinzugekommen)
*'''Zonentopologie verwenden/anpassen''': Es soll eine Speichermöglichkeit für die aktuelle Topologie geschaffen werden, und auch eine neue Topologie gesetzt werden können. Ich stelle mir da eine Art von "Szenen" vor die man nach Bedarf setzen und dann natürlich auch steuern kann. Diese Szenen sollen den Gruppierungszustand aller verfügbaren ZonePlayer repräsentieren (können), also wer mit wem in einer Gruppe ist, und wer der jeweilige Koordinator ist (nur dieser kann die Steuerung entgegennehmen, und für die gesamte Gruppe ausführen). (In Version 2.0 hinzugekommen)
*'''Button-Events''': Es soll eine Möglichkeit zum direkten Reagieren auf Tastenevents am Player existieren. Man soll verschiedene Tastensequenzen festlegen können, die dann FHEM-Events erzeugen, auf die man reagieren kann. (In Version 2.0 hinzugekommen)
*'''relatives Spulen''': während einer Wiedergabe soll mit "currentTrackPosition x" mit x festgelegt werden, umwieviel sekunden vorgespult werden soll. Analog dazu das zurückspulen (In Version vom 12.3.2017 hinzugekommen)

== Beispiele ==
Hier können mit der Zeit ein paar Beispiele eingestellt werden, um die Möglichkeiten zu verdeutlichen.

'''Hinweis:''' Die Codebeispiele wurden umgebaut, damit diese für eine Bearbeitung über die FHEMWeb-Oberfläche passend sind. Wenn man die Beispiele direkt in einer Konfigurationsdatei verwenden möchte, so müssen die ''';''' maskiert werden (also verdoppelt).

=== Beispiel zum Loggen aller Aktionen auf allen Playern ===
<pre>define FileLog_Sonos_Actions FileLog /path/to/log/Sonos_Actions-%Y-%m.log \
Sonos_.*:.*LastActionResult.*</pre>
Hiermit wird jede Aktion, die, durch FHEM verursacht, an die Player gesendet wurde, mitgeschrieben. Sehr praktisch für Fehlersuche, bzw. die Kontrolle darüber, was eigentlich von FHEM aus so auf den Playern gesteuert wird.

=== Beispiel zum automatischen Abspielen einer Liste nach dem Einschalten eines Players ===
<pre>define Sonos_Wohnzimmer_Appeared_Notify notify Sonos_Wohnzimmer:presence:.appeared { \
fhem "set Sonos_Wohnzimmer LoadPlaylist R.%20Spielliste" ; \
fhem "set Sonos_Wohnzimmer Volume 15" ; \
fhem "set Sonos_Wohnzimmer Track random" ; \
fhem "set Sonos_Wohnzimmer Play" \
}</pre>

Hier wird auf das Event '''presence: appeared''' reagiert und eine Playlist geladen (hier mit Leerzeichen im Namen, darum mittels "<code>%20</code>" HTML-kodiert, was wiederum bei FHEM-Featurelevel < 5.7 wegen FHEM-Notify auf "<code>%%20</code>" kodiert werden müsste). Anschließend wird die Lautstärke gesetzt, ein Titel ausgewählt (zufällig) und das Abspielen gestartet.

Da dies aber auch bei einem Neustart von FHEM getriggert wird, kann man noch eine zusätzliche Prüfung einbauen:
<pre>define Sonos_Wohnzimmer_Appeared_Notify notify Sonos_Wohnzimmer:presence:.appeared { \
if (ReadingsVal('Sonos_Wohnzimmer', 'numberOfTracks', -1) == 0) {\
fhem "set Sonos_Wohnzimmer LoadPlaylist R.%20Spielliste" ; \
fhem "set Sonos_Wohnzimmer Volume 15" ; \
fhem "set Sonos_Wohnzimmer Track random" ; \
fhem "set Sonos_Wohnzimmer Play" \
}\
}</pre>

Alternativ kann man auch das Reading '''currentTrackURI''' prüfen, je nachdem, was mit dem Player passieren soll.

=== Beispiel für eine Verstärkerschaltung auf Basis des Player-Zustands ===
<pre>define Sonos_Wohnzimmer_GoPlaying_Notify notify Sonos_Wohnzimmer:transportState.*PLAYING { \
fhem "delete wohnzimmer_Sonos_Ton_Off_Timer" ; \
if (Value('wohnzimmer_Sonos_Ton') ne 'on') { \
fhem "set wohnzimmer_Sonos_Ton on" \
} \
}
define Sonos_Wohnzimmer_GoNotPlaying_Notify notify \
Sonos_Wohnzimmer:transportState.*(STOPPED|PAUSED_PLAYBACK) { \
fhem "delete wohnzimmer_Sonos_Ton_Off_Timer" ; \
fhem "define wohnzimmer_Sonos_Ton_Off_Timer at +00:05:00 \
set wohnzimmer_Sonos_Ton off" \
}</pre>

Hier wird beim Wechsel des <code>transportState</code> auf "<code>PLAYING</code>" der Verstärker angeschaltet, und beim Wechsel auf "<code>STOPPED</code>" oder "<code>PAUSED_PLAYBACK</code>" ein Timer zum Ausschalten des Verstärkers in 5 Minuten definiert.<br />Der Timer ist notwendig, da beim Wechsel zwischen einem "normalen" Titel und einem Radiostream ein kurzer Zwischenwechsel auf "<code>STOPPED</code>" erfolgt, und ich nicht den Verstärker innerhalb von ein paar Sekunden aus- und wieder einschalten will.

Das Ganze geht mittlerweile viel kürzer mit dem Modul [[DOIF]]:
<pre>define Sonos_Wohnzimmer_PlayingCheck DOIF ([Sonos_Wohnzimmer:transportState] eq "PLAYING") \
(set wohnzimmer_Sonos_Ton on) DOELSE (set wohnzimmer_Sonos_Ton off)
attr Sonos_Wohnzimmer_PlayingCheck wait 0:300</pre>

=== Beispiel für das Loggen des gerade abgespielten Titels ===
<pre>define FileLog_Sonos_Wohnzimmer FileLog /etc/fhem/log/Sonos_Wohnzimmer-%Y-%m.log \
Sonos_Wohnzimmer:infoSummarize2:.{2,}
attr FileLog_Sonos_Wohnzimmer room Sonos</pre>

Hier wird bei jedem Wechsel des Titels oder des Abspielzustands ein Eintrag ins Log geschrieben. Damit kann man, auch bei einem Radiosender, verfolgen, welche Titel zu welcher Zeit so über den Player gelaufen sind :-)

=== Beispiel für eine Stummschaltung bei einem Anruf ===
<pre>
define fritzBox_anrufstartring_notify notify fritzBox:.*ring set Sonos_Wohnzimmer VolumeSave 15
define fritzBox_anrufstartcall_notify notify fritzBox:.*call set Sonos_Wohnzimmer VolumeSave +0
define fritzBox_anrufende_notify notify fritzBox:.*disconnect set Sonos_Wohnzimmer VolumeRestore
</pre>

Der Trigger auf 'call' existiert nur, damit ausgehende Telefonate beim Beenden nicht die Lautstärke verändern. Das passiert, weil das Disconnected-Event auch nach ausgehenden Anrufen kommt.<br />Das Beispiel kann man natürlich noch beliebig erweitern, vielleicht etwas mit Anrufererkennung usw.

=== Beispiel für eine Anrufsignalisierung per MP3 bei einem Anruf ===
<pre>
define fritzBox_anrufstartringsong_notify notify fritzBox:.*ring set Sonos_Wohnzimmer \
PlayURITemp \\Server\Audio\RingRingRing.mp3 30
</pre>

Hier wird bei Anruf die angegebene MP3-Datei temporär mit der Lautstärke 30 eingeblendet. Wenn die Datei abgespielt wurde, wird der vorherige Zustand im Player wiederhergestellt, und es geht weiter, wo unterbrochen wurde.

=== Beispiel für beide Varianten beim Telefonanruf gleichzeitig ===
<pre>
define fritzBox_anrufstartring_notify notify fritzBox:.*ring set Sonos_Wohnzimmer VolumeSave 15 \
;; set Sonos_Wohnzimmer PlayURITemp \\Server\Audio\RingRingRing.mp3 30
define fritzBox_anrufstartcall_notify notify fritzBox:.*call set Sonos_Wohnzimmer VolumeSave +0
define fritzBox_anrufende_notify notify fritzBox:.*disconnect set Sonos_Wohnzimmer VolumeRestore
</pre>

Dieses Beispiel soll nur die Kombinationsmöglichkeiten verdeutlichen, und hat mehr spielerischen Character.

=== Beispiel für eine Sprachdurchsage auf Basis eines Notify ===
<pre>
define wohnzimmer_Tastenfeld_1_Notify notify wohnzimmer_Tastenfeld_1 set Sonos_Wohnzimmer Speak \
45 de Hier dann die Textnachricht, wie sie auf dem Player ausgegeben werden soll.
define wohnzimmer_Tastenfeld_2_Notify notify wohnzimmer_Tastenfeld_2 set Sonos_Wohnzimmer Speak \
+10 de Hier dann die Textnachricht, wie sie auf dem Player ausgegeben werden soll.
define wohnzimmer_Tastenfeld_3_Notify notify wohnzimmer_Tastenfeld_3 set Sonos_Wohnzimmer Speak \
+0 en Hello, this is a short message.

define wohnzimmer_Tastenfeld_4_doif DOIF ([EnO_switch:?B0] and [?06:00-09:05]) \
({my $temp = "Außentemperatur: " . ReadingsVal("MeinWetter","temperature","unbekannt") . \
" °C. Höchsttemperatur: " . ReadingsVal("MeinWetter","fc1_high_c","unbekannt") . " °.";; \
fhem "set Sonos_Bad Speak 30 de $temp"})
</pre>

1: Hier wird auf Basis eines Notify (hier ein FS20-Taster) eine Textnachricht auf Deutsch mit der Lautstärke 45 auf dem SonosPlayer ausgegeben.<br />
2: Hier wird eine deutsche Textnachricht mit 10 Einheiten lauter als aktuell eingestellt ausgegeben.<br />
3: Hier wird eine englische Textnachricht mit der gleichen Lautstärke wie aktuell eingestellt ausgegeben.<br />
4: Hier wird, wenn der EnOcean-Taster rechts oben ("B0") zwischen 6:00 und 9:05 Uhr gedrückt wird, die aktuelle Außentemperatur und die Tageshöchsttemperatur (vom [[weather]]-Modul) in Lautstärke 30 ausgegeben (nicht mit [[notify]], sondern mit [[DOIF]] realisiert).

=== Beispiel für das Reagieren auf Tastenevents ===
Hier ein Beispiel, wie man die Tasten an einem Play5 (und natürlich auch an jedem anderen Player) zu einer einfachen, autarken Steuerung programmieren kann.

Grundlagen, die ich zur allgemeinen Vereinfachung in meiner <code>99_myUtils.pm</code> habe:
<pre>
# Wird benötigt, da ein reDefine nur einen Befehl aufrufen kann
sub pauseMuteOff($) {
my ($devName) = @_;

if (defined($main::defs{$devName})) {
fhem("set $devName Pause");
fhem("set $devName Mute Off");
}
}

# Löscht ein Define, wenn es existiert. Damit kann man dynamische AT-Defines löschen,
# ohne zu wissen, ob sie überhaupt existieren
sub deleteDefineIfExists($) {
my ($devName) = @_;

if (defined($main::defs{$devName})) {
fhem("delete $devName");
}
}

# Definiert ein define neu; Heisst, es wird, wenn es bereits existiert, gelöscht und neu angelegt
sub reDefine($$) {
my ($devName, $define) = @_;

deleteDefineIfExists($devName);
fhem('define '.$devName.' '.$define);
}
</pre>

Attribut am Sonosplayer-Device:
<pre>
attr Sonos_Schlafzimmer buttonEvents 1:MM
</pre>

Notify-Defines, die die Steuerung übernehmen:
<pre>
define Sonos_Schlafzimmer_WantPlaying_Notify notify Sonos_Schlafzimmer:ButtonEvent:.MM \
set Sonos_Schlafzimmer Play
define Sonos_Schlafzimmer_WantStopPlaying notify Sonos_Schlafzimmer:Mute.*1 \
{ reDefine('Schlafzimmer_Sonos_Stop_Timer', 'at +00:00:30 \
{ pauseMuteOff("Sonos_Schlafzimmer") }') }
define Sonos_Schlafzimmer_WantStopPlayingOff notify Sonos_Schlafzimmer:Mute.*0 \
{ deleteDefineIfExists('Schlafzimmer_Sonos_Stop_Timer') }
</pre>

Hier wird mittels des Attributs <code>buttonEvents</code> ein Event bei zweimaligen Drücken von <code>M</code>ute innerhalb von 1 Sekunde definiert.
Anschließend wird auf dieses Event reagiert, indem der Player mit der Wiedergabe beginnen soll.
Desweiteren wird auf das Ändern von Mute reagiert, indem beim Aktivieren von Mute (also einmal drücken) ein Timer gestartet wird, der nach 30 Sekunden die Wiedergabe anhält, und den Mute-Zustand wieder zurücksetzt. Das letzte notify existiert nur, damit man das Beenden der Wiedergabe innerhalb der 30 Sekunden noch verhindern kann.

Hier ist zu beachten, dass diese Events natürlich nicht unterscheiden können, ob das ganze am Player selbst oder über einen Controller geschaltet wurde. Von beiden Stellen aus kann diese Funktionalität verursacht werden.

=== Beispiel für einen Offline-Sprachsynthetisierer ===
Man kann mit den Attributen ''Speak1'', ''Speak2'', ''Speak3'' und ''Speak4'' am zentralen Sonos-Device Kommandozeilen definieren, die einen Text in eine Sounddatei umwandeln.
Hier soll dies am Beispiel von ''espeak'' verdeutlicht werden.
<pre>
wav:/usr/bin/espeak -v %language% -w %filename% "%text%"
</pre>
Zuerst muss das Ausgabedateiformat definiert werden, damit die internen Funktionen entsprechend reagieren können. Anschließend wird die Befehlszeile mit den entsprechenden Platzhaltern angegeben.
Hier muss beachtet werden, dass der Platzhalter ''%language%'' mit dem zweiten Parameter der FHEM-Befehlseingabe gefüllt wird. In diesem Beispiel muss man dort also ''german'' angeben (anstatt ''de'' bei Google), um eine deutsche Ausgabe zu erhalten.

Dieses Beispiel hat den kleinen Nachteil, dass die Ausgabe in einer WAV-Datei erfolgt, die keinerlei Tag-Informationen tragen kann. Um das zu ändern, kann man einen Konverter nachschalten:
<pre>
mp3:/usr/bin/espeak -v %language% --stdout "%text%" | /usr/bin/avconv -i - %filename%
</pre>
Damit wird die Ausgabe von ''espeak'' direkt in das MP3-Format umgewandelt, und intern mit den entsprechenden Tags versehen. Hier ist allerdings der Nachteil, dass es etwas länger dauert (auf meinem Raspberry Pi ca. 1-3 Sekunden).

Die in diesem Beispiel verwendeten Pakete können unter Debian mittels der Anweisungen
<pre>
sudo apt-get install espeak
sudo apt-get install ffmpeg
</pre>
installiert werden.

=== Beispiel zu InfoSummarize ===
Standard, wie er angelegt wird:
<pre>
InfoSummarize1 = <NormalAudio><Artist prefix="(" suffix=")"/>\
<Title prefix=" '" suffix="'" ifempty="[Keine Musikdatei]"/>\
<Album prefix=" vom Album '" suffix="'"/></NormalAudio> \
<StreamAudio><Sender suffix=":"/>\
<SenderCurrent prefix=" '" suffix="' -"/>\
<SenderInfo prefix=" "/></StreamAudio>
InfoSummarize2 = <TransportState/><InfoSummarize1 prefix=" => "/>
InfoSummarize3 = <Volume prefix="Lautstärke: "/>\
<Mute instead=" ~ Kein Ton" ifempty=" ~ Ton An" emptyval="0"/>\
~ Balance: <Balance ifempty="Mitte" emptyval="0"/>\
<HeadphoneConnected instead=" ~ Kopfhörer aktiv" ifempty=" ~ Kein Kopfhörer" \
emptyval="0"/>
</pre>

Dabei ist zu beachten, dass man auf andere InfoSummarize-Felder verweisen darf, solange man diese nur in aufsteigender Reihenfolge verwendet. Rekursionen oder Vorwärtrsreferenzen werden nicht unterstützt.

Hier noch ein Beispiel, um die Informationen des nächsten Titels zusammenzufassen:
<pre>
InfoSummarize4 = <NormalAudio>Nächster Titel: <nextArtist prefix="(" suffix=")"/>\
<nextTitle prefix=" '" suffix="'" ifempty="[Keine Musikdatei]"/>\
<nextAlbum prefix=" vom Album '" suffix="'"/></NormalAudio>\
<StreamAudio>Kein nächster Titel ermittelbar</StreamAudio>
</pre>

=== Beispiel für eine Cover-Anzeige des nächsten Titels ===
Mit diesem Beispiel wird gezeigt, wie man sich einen Weblink für die Anzeige des Covers des nächsten Titels erzeugen kann:
<pre>
define NextAlbumArt_Wohnzimmer weblink image fhem/icons/SONOSPLAYER/Sonos_Wohnzimmer_NextAlbumArt
attr NextAlbumArt_Wohnzimmer group Wohnzimmer
attr NextAlbumArt_Wohnzimmer htmlattr width="200"
attr NextAlbumArt_Wohnzimmer room Sonos
</pre>

=== Beispiel für das Übertragen eines Titels an einen anderen Player ===
Mein Sohn hat öfter den Wunsch, einen gerade im Wohnzimmer laufenden Titel auch in seine eigene Abspielliste zu bekommen. Der Weg am Sonos-Controller über eine gespeicherte Playliste ist dabei sehr umständlich.
Ich habe ein 8-fach Sensorfeld an der Wohnzimmerwand, wo ich ein Feld dafür programmiert habe, das Reading ''currentTrackURI'' mittels der Set-Anweisung ''AddURIToQueue'' in die aktuelle Abspielliste meines Sohnes zu packen.
Das ist natürlich nichts besonderes, aber vielleicht für den einen oder anderen auch eine nette Idee:
<pre>
define wohnzimmer_Sensorfeld_Notify notify wohnzimmer_Sensorfeld { \
fhem "set Sonos_Sohnemann AddURIToQueue ".\
ReadingsVal("Sonos_Wohnzimmer", "currentTrackURI", "") \
}
</pre>

=== Beispiel für eine eigene ReadingsGroup zur Darstellung der Cover- und Titelinformationen ===
Wenn man das Standarddesign der generierten [[readingsGroup]] überarbeiten möchte, muss man sich einfach eine eigene Prozedur in der '''99_myUtils.pm''' anlegen, die dann in der [[readingsGroup]] verwendet werden kann.

Da die Original-Vorlage wegen des Vollbildmodus sehr umfangreich ist, gibt es hier nur eine abgespeckte Version, die nur die Anzeige selbst übernimmt. Wer gerne den Vollbildmodus anpassen möchte, kann sich die entsprechende Prozedur '''SONOS_getCoverTitleRG''' einfach aus dem Modulcode kopieren (umbenennen nicht vergessen).

Hier die Vorlage der drei Prozeduren:
<pre>
sub getCoverTitleRG($;$$) {
my ($device, $width, $space) = @_;
$width = 500 if (!defined($width));

return '<div style="float: left;">'.getCoverRG($device).\
'</div><div style="margin-left: 150px; min-width: '.$width.\
'px;>'.getTitleRG($device, $space).'</div>';
}

sub getCoverRG($;$) {
my ($device) = @_;

return '<img style="margin-right: 5px; border: 1px solid lightgray; \
height: 175px" src="'.ReadingsVal($device, 'currentAlbumArtURL', '').'" />';
}

sub SONOS_getTitleRG($;$) {
my ($device, $space) = @_;
$space = 20 if (!defined($space));

my $infoString = '';

my $transportState = ReadingsVal($device, 'transportState', '');
$transportState = 'Spiele' if ($transportState eq 'PLAYING');
$transportState = 'Pausiere' if ($transportState eq 'PAUSED_PLAYBACK');
$transportState = 'Stop bei' if ($transportState eq 'STOPPED');

# Läuft Radio oder ein "normaler" Titel
if (ReadingsVal($device, 'currentNormalAudio', 1) == 1) {
$infoString = sprintf('<div style="margin-left: -150px;">%s Titel %s \
von %s<br />Titel: <b>%s</b><br />Interpret: <b>%s</b><br />Album: \
<b>%s</b><div style="height: %dpx;"></div>'.encode('UTF-8', \
'Nächste Wiedergabe:').'</div><div style="float: left; margin-left: \
0px;"><img style="margin: 0px; padding: 0px; margin-right: 5px; \
border: 1px solid lightgray;" height="55" border="0" src="%s" />\
</div><div style="margin-left: 0px;">Titel: %s<br />Artist: %s<br />\
Album: %s</div>',
$transportState,
ReadingsVal($device, 'currentTrack', ''),
ReadingsVal($device, 'numberOfTracks', ''),
ReadingsVal($device, 'currentTitle', ''),
ReadingsVal($device, 'currentArtist', ''),
ReadingsVal($device, 'currentAlbum', ''),
$space,
ReadingsVal($device, 'nextAlbumArtURL', ''),
ReadingsVal($device, 'nextTitle', ''),
ReadingsVal($device, 'nextArtist', ''),
ReadingsVal($device, 'nextAlbum', ''));
} else {
$infoString = sprintf('<div style="margin-left: -150px;">%s Radiostream\
<br />Sender: <b>%s</b><br />Info: <b>%s</b><br />'.encode('UTF-8', \
'Läuft:').' <b>%s</b></div>',
$transportState,
ReadingsVal($device, 'currentSender', ''),
ReadingsVal($device, 'currentSenderInfo', ''),
ReadingsVal($device, 'currentSenderCurrent', ''));
}

return $infoString;
}
</pre>
Diese kann man als Kopiervorlage für eigene Ideen verwenden. Die Backslashs vor den Zeilenumbrüchen sind hauptsächlich der Optik halber hier. Generell empfehle ich die so getrennten Befehle in eine Zeile zu schreiben...

Hier noch eine beispielhafte [[readingsGroup]] dazu:
<pre>
define Sonos_WohnzimmerRG readingsGroup Sonos_Wohnzimmer:\
<{getCoverTitleRG($DEVICE)}@infoSummarize1>
</pre>

=== Beispiel für eine ReadingsGroup für die Darstellung von Listen (Favoriten, Playlisten und Radios) ===
Es gibt eine mitgelieferte Prozedur, die für diese Darstellung verwendet werden kann. Diese stellt die Listen einfach als zweispaltige Tabelle dar (links das Cover, rechts der Titel als ausführbarer Link).
Für die Datenlieferung (z.B. die Favoriten in einem Reading) muss man sich noch ein entsprechendes userReading schaffen.
Beim Generieren der Devices vom Autocreate-Mechanismus werden diese Elemente und Attribute bereits mit erzeugt. Es muss lediglich ein Automatismus zum Aktualisieren des entsprechenden Readings geschaffen werden, oder dieses einmal manuell ausgeführt werden.

Hier die Vorlage für das userReadings:
<pre>
attr Sonos_Wohnzimmer userReadings Favourites:LastActionResult.*?\
GetFavouritesWithCovers.* { if (ReadingsVal($name, \
"LastActionResult", "") =~ m/.*?: (.*)/) { return $1; } }, Radios:\
LastActionResult.*?GetRadiosWithCovers.* { if (ReadingsVal($name, \
"LastActionResult", "") =~ m/.*?: (.*)/) { return $1; } }, Playlists:\
LastActionResult.*?GetPlaylistsWithCovers.* { if (ReadingsVal($name, \
"LastActionResult", "") =~ m/.*?: (.*)/) { return $1; } }
</pre>
Damit wird jeweils ein Reading für Favoriten, Playlisten und Radios angelegt, sobald im Reading '''LastActionResult''' dieses Ergebnis asynchron geliefert wurde.

Die Lieferung selbst kann man mit einem '''at'''-Statement zu bestimmten Zeitpunkten erzeugen/aktualisieren lassen:
<pre>
define refreshFavouritesWohnzimmer at *06:00 get Sonos_Wohnzimmer FavouritesWithCovers
</pre>

Das ganze muss natürlich für jede gewünschte Liste an jedem Player aktualisiert werden. Man kann also auch sowas schreiben:
<pre>
define refreshFavouritesSonos at *06:00 get Sonos_.*.Favourites FavouritesWithCovers
define refreshPlaylistsSonos at *06:01 get Sonos_.*.Playlists PlaylistsWithCovers
define refreshRadiosSonos at *06:02 get Sonos_.*.Radios RadiosWithCovers
</pre>

Möchte man eine andere Darstellung, so muss man sich eine eigene Prozedur in eine '''99_myUtils.pm''' packen. Hier eine Kopiervorlage:
<pre>
sub getListRG($$;$) {
my ($device, $reading, $ul) = @_;
$ul = 0 if (!defined($ul));

my $resultString = '';

# Manchmal ist es etwas komplizierter mit den Zeichensätzen...
my %elems = %{eval(decode('CP1252', ReadingsVal($device, $reading, '{}')))};

for my $key (keys %elems) {
my $command;
if ($reading eq 'Favourites') {
$command = 'cmd.'.$device.uri_escape('=set '.$device.' \
StartFavourite '.uri_escape($elems{$key}->{Title}));
} elsif ($reading eq 'Playlists') {
$command = 'cmd.'.$device.uri_escape('=set '.$device.' \
StartPlaylist '.uri_escape($elems{$key}->{Title}));
} elsif ($reading eq 'Radios') {
$command = 'cmd.'.$device.uri_escape('=set '.$device.' \
StartRadio '.uri_escape($elems{$key}->{Title}));
}
$command = "FW_cmd('/fhem?XHR=1&$command')";

if ($ul) {
$resultString .= '<li style="list-style-type: none; display: inline;">\
<a onclick="'.$command.'"><img style="border: solid 1px lightgray; \
margin: 3px;" width="70" src="'.$elems{$key}->{Cover}.'" /></a></li>';
} else {
$resultString .= '<tr><td><img width="70" src="'.$elems{$key}->{Cover}.\
'" /></td><td><a onclick="'.$command.'">'.$elems{$key}->{Title}."</a>\
</td></tr>\n";
}
}

if ($ul) {
return '<ul style="margin-left: 0px; padding-left: 0px; list-style-type: none; \
display: inline;">'.$resultString.'</ul>';
} else {
return '<table>'.$resultString.'</table>';
}
}
</pre>
Diese Prozedur hat einen optionalen Parameter ($ul). Mit diesem kann man angeben, ob eine Tabelle mit vertikaler Darstellung ($ul=0) oder eine Unordered-List mit horizontaler Darstellung ($ul=1) erzeugt wird.
Die Variante mit den ListItems ist auch für eine Darstellung in einem Dashboard geeignet.
Da bei der horizontalen Darstellung kein Platz für Namen ist, eignet sich diese Darstellung nur für Listen, deren Icon für jeden Eintrag unterschiedlich ist (Playlisten kann man hier also nicht mehr unterscheiden :-).

Die eigentliche [[readingsGroup]] verwendet dann diese Prozedur:
<pre>
define Sonos_WohnzimmerFavouriteListRG readingsGroup Sonos_Wohnzimmer:\
<{getListRG($DEVICE,"Favourites")}@Favourites>
</pre>

oder für die Variante mit den List-Elementen:
<pre>
define Sonos_WohnzimmerFavouriteListRG readingsGroup Sonos_Wohnzimmer:\
<{getListRG($DEVICE,"Favourites",1)}@Favourites>
</pre>

Damit kann man sich dynamische Listen auf Basis der Informationen im Sonosplayer für die Darstellung erzeugen lassen.

Die Backslashs vor den Zeilenumbrüchen sind hauptsächlich der Optik halber hier. Generell empfehle ich die so getrennten Befehle in eine Zeile zu schreiben...

=== Beispiel für die Anzeige der Gruppenkonstellation in einer ReadingsGroup ===
[[Datei:ReadingsGroupSonosGruppierung.png|right|75px|Beispiel der Visualisierung der Gruppenkonstellation im Style "dark"]]
Mit der folgende Prozedur (in die '''99_myUtils.pm''' schreiben) und der [[readingsGroup]] läßt sich auf einfache Weise die Gruppenkonstellation stets aktuell darstellen.

Die Prozedur, die die Zerlegung des Strings und in diesem Fall die Aufbereitung als UL (Unordered-List) übernimmt:
<pre>
sub getGroupsRG() {
my $groups = CommandGet(undef, SONOS_getSonosPlayerByName(undef)->{NAME}.\
' Groups');

my $result = '';
my $i = 0;
while ($groups =~ m/\[(.*?)\]/ig) {
my @member = split(/, /, $1);
@member = map { my $elem = $_; $elem = FW_makeImage('icoSONOSPLAYER_icon-'.\
ReadingsVal($elem, 'playerType', '').'.png', '', '').ReadingsVal($elem,\
'roomNameAlias', $elem); $elem; } @member;

$result .= '<li>'.++$i.'. Gruppe:<ul style="list-style-type: none; \
padding-left: 0px;"><li>'.join('</li><li>', @member).'</li></ul></li>';
}
return '<ul>'.$result.'</ul>';
}
</pre>

Und hier die entsprechende ReadingsGroup dazu:
<pre>
define SonosRG readingsGroup Sonos:<{getGroupsRG()}@ZoneGroupState>
</pre>

Damit wird eine einfache Darstellung der Gruppenkonstellation durchgeführt, die man sich natürlich selber nach Belieben anpassen kann/soll.

Die Backslashs vor den Zeilenumbrüchen sind hauptsächlich der Optik halber hier. Generell empfehle ich die so getrennten Befehle in eine Zeile zu schreiben...

=== Beispiel für eine ReadingsGroup, die die Informationen des Masters anzeigt ===
Wenn Player in einer Gruppe sind, werden keine Titelinformationen des eigentlichten Streams angezeigt. Man kann sich jetzt zu jedem Player eine [[readingsGroup]] bauen, die die Informationen des Gruppenmasters anzeigen.

<pre>
define Sonos_WohnzimmerRG2 readingsGroup Sonos_Wohnzimmer:infoSummarize2@{\
SONOSPLAYER_GetMasterPlayerName($DEVICE)}
attr Sonos_WohnzimmerRG2 valueFormat {" "}
attr Sonos_WohnzimmerRG2 valuePrefix {SONOS_getCoverTitleRG(\
SONOSPLAYER_GetMasterPlayerName($DEVICE))}
attr Sonos_WohnzimmerRG2 noheading 1
attr Sonos_WohnzimmerRG2 nonames 1
attr Sonos_WohnzimmerRG2 notime 1
</pre>

''Hinweis'': Diese ReadingsGroup wird automatisch per longpoll aktualisiert. Lediglich bei einer Umgruppierung muss bislang die Seite neu geladen werden. Es kann aber gut sein, dass man das in Zukunft auch per longpoll hinbekommen kann.

=== Beispiel für ein Shell-Skript zum Aufräumen eines Speak-Verzeichnisses ===
Mit der freundlichen Freigabe von Loredo und CQuadrat hier ein kleines Shell-Skript, mit dem länger nicht abgespielte Dateien gelöscht werden können.
Bei allen Varianten muss berücksichtigt werden, dass der ausführende Benutzer die Dateien auch löschen darf. Bitte die Dateirechte prüfen.

==== Variante mit Ausgabe der gelöschten Dateien ====
<pre>
#!/bin/bash

FILES=`ls /mnt/SonosSpeak/RINCON*.mp3*`
CURRENTTIME=`date +"%s"`
PASTDAYS=75

THESHOLDATIME=`expr $CURRENTTIME - $PASTDAYS \* 24 \* 60 \* 60`

echo -e "Cleaning up all files older than $PASTDAYS days ...\n\n"

for f in $FILES
do

FILEATIME=`stat -c "%X" $f`

if [[ "$FILEATIME" < "$THESHOLDATIME" ]]; then
echo "cleaned up $f: last access on `stat -c "%x" $f`"
rm $f
fi

done
</pre>
Unter Umständen gibt es eine aktuellere Version unter [https://gist.github.com/jpawlowski/689d1cf74334488cd127 cleanupSonosSpeak.sh auf GitHub].

==== Variante für die crontab ====
<pre>
0 4 * * * find /mnt/SonosSpeak -name "RINCON*" ! -atime -75 -delete
</pre>
Hier wird jeden Tag um 4:00 Uhr der Ordner mit den Sprachausgabedateien bereinigt.

=== Betrieb des Sonos an einer Funksteckdose (regelmäßiges Ausschalten) - Verbindungsprobleme ===

Wenn das Sonossystem per Funksteckdose regelmäßig vom Netz genommen wird, bereitet der Neustart und das anschließende
Verbinden mit FHEM oft Probleme. Das Sonosmodul bleibt auf dem Status "disappeared" stehen und das Playerdevice ebenfalls.
Ergo ist eine Bedienung per FHEM oder die Sprachausgabe nicht mehr möglich.

Um diesem Problem Abhilfe zu schaffen reicht ein kleines notify oder DOIF, welches den Player beim Abschalten
das Attribut disable = 1 verschafft und beim Wiedereinschalten dieses Attribut löscht.

<pre>
define RebootSonosDOIF DOIF ([FunksteckerSonos:state] eq "on" )(deleteattr MeinSonosDevice disable) (save)
DOELSEIF ([FunksteckerSonos:state] eq "off" )(attr MeinSonosDevice disable 1)(save)
</pre>

Das Setzen von "disable" sorgt dafür, dass der Sonosthread beendet wird und beim Einschalten ein neuer Prozess erstellt wird.
Diese automatische Änderung an der Konfiguration des Device benötigt ein save config im Nachgang der DOIF- oder notify-Aktion.
Daher wird der jeweilige attr-Befehl mit einem (save) abgeschlossen.

Wichtig hierbei (wie auch in der Überschrift erwähnt) funktioniert das nur, wenn die einzelnen Sonosplayer an einer schaltbaren Steckdose betrieben werden.

Das DOIF triggert nur bei Änderung des "state" der jeweilige Funksteckdose.

=== Beispiele für FTUI-Integrationen ===
Hier können diverse Beispiele für eine FTUI (FHEM Tablet User Interface) Integration aufgeführt werden. Dabei sollten die Beispiele ''vollständig'' sein, und auch alle notwendigen Dummies und/oder Userreadings beschreiben.

==== Beispiel von Reinerlein ====
[[Datei:ReinersSonosFTUIIntegration.jpg|mini|Beispiel der SONOS-FTUI-Integration von Reinerlein]]
[[Datei:ReinersSonosFTUIIntegrationHeadline.jpg|mini|Kopfzeile bei Gruppenwiedergabe]]
Hier gebe ich mal mein Beispiel zum Besten. Es ist eine 3 Spalten x 5 Zeilen Integration mit der Möglichkeit einer Favoriten-, Playlisten- und Radioauswahl, sowie einer Titelauswahl und Gruppierungsanpassung.

Die Formatierung der Listen erfolgt mit einem '''|''' als Trenner der Elemente, da dieses Zeichen hier nie im Titel vorkommt.

Die Maskierung der Leerzeichen für die Schlüsselliste erfolgt auf den Punkt. Damit besteht die Möglichkeit, den Wert direkt als regulären Ausdruck an den entsprechenden Start-Befehl zu übermitteln. Es müssen nur noch die Schrägstriche '''/''' vorne und hinten angefügt werden.

Beim Antippen des Covers wird ein Vollbild-Popup geöffnet, welches das Cover in groß, den Abspielzustand und die Abspielposition darstellt.

Im Header jedes Players wird angezeigt, ob gerade irgendwelche Slaveplayer mitbedient werden, bzw. wer der aktuelle Masterplayer zu dieser Wiedergabe ist. Des Weiteren kann dort direkt ein Player zu der Wiedergabegruppe hinzugefügt oder aus ihr entfernt werden.

Im Header kann jetzt bei einer Gruppenwiedergabe auch der GroupMute-Zustand gesetzt werden.

Über dem Cover wird nun die aktuelle Quelle des Titels angezeigt (Playlist, Album o.ä.)

===== FTUI-Code =====
Der Code ist in zwei Bereiche aufgeteilt, damit die Templatemöglichkeiten für mehrere Player verwendet werden können.

Zunächst die Einbindung des Templates. Hier wird auch der Rahmen festgelegt. In diesem Fall der Gridster-Kasten mit 3x5 Feldgröße:
<pre>
<li data-row="1" data-col="1" data-sizex="3" data-sizey="5" class="border-down-gray lesstransparent">
<div data-template="template_musik_sonos.html" data-parameter='{"Device":"Sonos_Wohnzimmer"}'></div>
</li>
</pre>
Dadurch, dass der Rahmen nicht mit im Template enthalten ist, könnte man z.B. auch mehrere Player nebeneinander in einem Rahmen darstellen, dabei aber nicht den umschließenden DIV-Tag um das Template vergessen, da sonst die Titelanzeigen ''rauswandern'' könnten.
''Hinweis:'' In der vorherigen Version gab es noch einen Parameter für den Raumnamen, und der Header wurde hier bei der Einbindung festgelegt. Das entfällt nun, da der Raumname per Reading ermittelt wird, und im Header nun Gruppierungsinformationen enthalten sind.

Für die Coverdarstellung ist ein neues Widget notwendig (welches momentan noch nicht offiziell ist), da in der neuen Sonosversion größere Radiocover geladen werden, und diese nicht unbedingt quadratisch orientiert sind.

Das Widget kann im Forum heruntergeladen werden: [https://forum.fhem.de/index.php/topic,70265.0.html https://forum.fhem.de/index.php/topic,70265.0.html].

Für die Lauftext-Animation sind eigene CSS-Klassen, eine Javascript-Funktion und (momentan noch) eine Anpassung des JoinedLabel-Widgets notwendig.

Hier die notwendigen Styles und Javascript. Ich habe diese einfach in den Kopfbereich meiner index.html gepackt:
<pre>

<style>
.flowanimation {
position: relative;
white-space: nowrap;
display: inline-block;
animation: floatText 8s infinite alternate ease-in-out;
}

@keyframes floatText {
from {
left: 0px;
}

to {
left: calc(355px - 100%);
}
}

.mycenteredtext {
position: relative;
white-space: nowrap;
display: inline-block;
left: calc(355px / 2 - 50%);
}
</style>

<script type="text/javascript">
function checkFlowAnimation(elemName) {
if ($(elemName).innerWidth() >= 355) {
$(elemName).addClass('flowanimation');
} else {
$(elemName).addClass('mycenteredtext');
}
}
</script>

</pre>

Die Anpassungen in der Datei "widget_joinedlabel.js" beschränken sich auf zwei Zeilen:
*In der Funktion "init_attr()" als letztes Statement vor der abschließenden Log-Ausgabe: <pre>elem.initData('onupdate', '');</pre>
*In der Funktion "update" als letztes Statement nach der "me.update_colorize()"-Anweisung: <pre>eval(elem.data('onupdate'));</pre>

Hier nun der Inhalt der Datei '''template_musik_sonos.html''':
<pre>
<header>
<div data-type="classchanger" data-device="Device" data-get="SlavePlayerNotBonded" data-get-on='["[]"]' data-on-class="hide" data-off-class="mini" class="inline">
<div data-type="switch" data-device="Device" data-get="GroupMute" data-set="GroupMute"
data-icon="fa-deaf" data-background-icon="-"
data-on-color="#aa6900" data-off-color="gray"
data-get-on="1" data-get-off="0"
data-set-on="1" data-set-off="0" class="mini" style="margin-right: -5px;">
</div>
</div>

<div data-type="joinedlabel" data-device="Device" data-mask="[$1][ ($2)]" data-get='["roomName","ZoneGroupNameDetails"]' class="truncate inline"></div>

<div data-type="classchanger" data-device="Device" data-get="MasterPlayer" data-get-on="Device" data-on-class="hide" class="inline left-narrow">
<div data-type="push"
data-device="Device"
data-icon="fa-minus-circle"
data-background-icon="-"
data-set-on="MakeStandaloneGroup"
class="inline mini gray">
</div>
</div>

<div data-type="classchanger" data-device="Device" data-get="MasterPlayer" data-get-on="Device" data-off-class="hide" class="inline left-narrow">
<div data-type="popup" class="" data-width="400px" data-height="110px">
<div data-type="symbol"
data-icon="fa-chevron-circle-down"
class="mini"
style="height: 10px;">
</div>

<div class="dialog">
<header><div data-type="joinedlabel" data-device="Device" data-mask="Wiedergabegruppe[ für $1] anpassen" data-get='["roomName"]' class="inline"></div></header>

<div class="top-space-10 left-align left-space">
<div>
<div class="large middle inline">Player hinzufügen: </div>
<div data-type="select"
data-device="Device"
data-list="AvailablePlayerList"
data-alias="AvailablePlayerListAlias"
data-delimiter="|"
data-get="-"
data-set="AddMember"
class="inline w3x"
onchange="$('.dialog-close').trigger('click');"></div>
</div>

<div>
<div class="large middle inline">Player entfernen: </div>
<div data-type="select"
data-device="Device"
data-list="SlavePlayerNotBondedList"
data-alias="SlavePlayerNotBondedListAlias"
data-delimiter="|"
data-get="-"
data-set="RemoveMember"
class="inline w3x"
onchange="$('.dialog-close').trigger('click');"></div>
</div>
</div>
</div>
</div>
</div>
</header

<div class="">
<div data-type="joinedlabel" data-device="Device" data-mask=" [~ $1 ~] " data-get='["currentSource"]' class="bottom-narrow mini white" style="padding-top: 3px; background: rgba(170, 105, 0, 0.6);"></div>

<div data-type="popup" data-width="100%" data-height="100%">
<div style="margin-bottom: -40px;">
<div data-type="imagecover"
data-device="Device"
data-get="currentAlbumArtURL"
data-opacity="1.0"
data-width="350px"
data-height="350px"
class=""
onclick="$('.dialog-close').trigger('click');"
style="margin-left: 12px; margin-top: 12px; border: 1px solid rgba(170, 105, 0, 0.6);">
</div>

<div data-type="classchanger" data-device="Device" data-get="currentTrackProviderIconRoundURL" data-get-on="" data-on-class="hide">
<div class="inline" style="width: 40px; height: 40px; background: rgba(0, 0, 0, 0.40); position: relative; top: -349px; left: -152px;">
<div data-type="imagecover"
data-device="Device"
data-get="currentTrackProviderIconRoundURL"
data-opacity="1.0"
data-width="30px"
data-height="30px"
class=""
style="margin-left: 5px; margin-top: 5px;">
</div>
</div>
</div>
<div data-type="classchanger" data-device="Device" data-get="currentTrackProviderIconRoundURL" data-get-on="" data-off-class="hide">
<div class="inline" style="width: 40px; height: 40px; position: relative; top: -349px; left: -152px;">
</div>
</div>
</div>

<div class="dialog">
<header><div data-type="joinedlabel" data-device="Device" data-mask="Cover[ für $1]" data-get='["roomName"]' class="inline"></div></header>

<div data-type="imagecover"
data-device="Device"
data-get="currentTrackProviderIconRoundURL"
data-opacity="1.0"
data-width="30px"
data-height="30px"
class=""
style="position: absolute; top: 25px; left: 5px;"
style="margin-left: 5px; margin-top: 5px;">
</div>

<div data-type="switch"
data-device="Device"
data-get="transportState"
data-states='["PLAYING","PAUSED_PLAYBACK","STOPPED"]'
data-background-icon="-"
data-background-colors='["white","white","white"]'
data-colors='["white","white","white"]'
data-icons='["fa-play","fa-pause","fa-pause"]'
class="inline readonly"
style="position: absolute; top: 10px; right: -10px;"
onclick="$('.dialog-close').trigger('click');">
</div>

<div data-type="imagecover"
data-device="Device"
data-get="currentAlbumArtURL"
data-opacity="1.0"
data-width="100%"
data-height="calc(100vh - 60px)"
class=""
onclick="$('.dialog-close').trigger('click');"
style="">
</div>

<div data-type="classchanger" data-device="Device" data-get="currentNormalAudio" data-get-on="1" data-off-class="hide">
<div data-type="slider"
data-device="Device"
data-get="currentTrackPositionSimulatedSec"
data-max="currentTrackDurationSec" data-min="0"
data-step="1"
data-handle-diameter="5"
data-width="68%"
class="horizontal top-narrow readonly centered"></div>
</div>

<div data-type="classchanger" data-device="Device" data-get="currentNormalAudio" data-get-on="1" data-off-class="hide">
<div data-type="joinedlabel" data-device="Device" data-mask="[$1][ ~ $2][ ~ $3]" data-get='["currentTitle","currentArtist","currentAlbum"]' class="truncate top-space"></div>
</div>
<div data-type="classchanger" data-device="Device" data-get="currentStreamAudio" data-get-on="1" data-off-class="hide">
<div data-type="joinedlabel" data-device="Device" data-mask="[$1 ~ ][$2][: $3]" data-get='["currentSenderInfo","currentSender","currentSenderCurrent"]' class="truncate top-space"></div>
</div>
</div>
</div>

<div data-type="classchanger" data-device="Device" data-get="currentNormalAudio" data-get-on="1" data-off-class="hide">
<div data-type="label" data-device="Device" data-get="currentTrackPositionSimulated" class="inline" style="width: 3em;"></div>
<div data-type="slider"
data-device="Device"
data-set="CurrentTrackPosition"
data-get="currentTrackPositionSimulatedSec"
data-max="currentTrackDurationSec" data-min="0"
data-step="1"
data-handle-diameter="5"
data-width="250"
class="horizontal tap inline">
</div>
<div data-type="label" data-device="Device" data-get="currentTrackDuration" class="inline" style="width: 3em;"></div>

<div class="newline">
<div data-type="label" data-device="Device" data-get="currentTrack" class="inline center-align" style="width: 3em;"></div>
<div data-type="slider"
data-device="Device"
data-set="Track"
data-get="currentTrack"
data-max="numberOfTracks" data-min="0"
data-step="1"
data-handle-diameter="5"
data-width="250"
class="horizontal tap inline">
</div>
<div data-type="label" data-device="Device" data-get="numberOfTracks" class="inline center-align" style="width: 3em;"></div>
</div>
</div>

<div data-type="classchanger" data-device="Device" data-get="currentStreamAudio" data-get-on="1" data-off-class="hide">
<div style="height: 40px;"> </div> 
</div>

<div class="large top-space">
<div data-type="classchanger" data-device="Device" data-get="currentNormalAudio" data-get-on="1" data-off-class="hide">
<div style="height: 21px;">
<div style="width: 355px; position: absolute; overflow: hidden; height: 21px; margin-left: 10px; margin-right: 10px;">
<div style="position: absolute;">
<div id="Device_Title" data-type="joinedlabel" data-device="Device" data-mask="[$1]" data-get='["currentTitle"]' data-onupdate="checkFlowAnimation('#Device_Title');" class="bold"></div>
</div>
</div>
</div>

<div style="height: 21px;">
<div style="width: 355px; position: absolute; overflow: hidden; height: 21px; margin-left: 10px; margin-right: 10px;">
<div style="position: absolute;">
<div id="Device_Interpret" data-type="joinedlabel" data-device="Device" data-mask="[$1][ ~ $2]" data-get='["currentArtist","currentAlbum"]' data-onupdate="checkFlowAnimation('#Device_Interpret');" class="">
</div>
</div>
</div>
</div>
</div>
<div data-type="classchanger" data-device="Device" data-get="currentStreamAudio" data-get-on="1" data-off-class="hide">
<div style="height: 21px;">
<div style="width: 355px; position: absolute; overflow: hidden; height: 21px; margin-left: 10px; margin-right: 10px;">
<div style="position: absolute;">
<div id="Device_SenderInfo" data-type="joinedlabel" data-device="Device" data-mask="[$1]" data-get='["currentSenderInfo"]' data-onupdate="checkFlowAnimation('#Device_SenderInfo');" class="bold"></div>
</div>
</div>
</div>

<div style="height: 21px;">
<div style="width: 355px; position: absolute; overflow: hidden; height: 21px; margin-left: 10px; margin-right: 10px;">
<div style="position: absolute;">
<div id="Device_Sender" data-type="joinedlabel" data-device="Device" data-mask="[$1][: $2]" data-get='["currentSender","currentSenderCurrent"]' data-onupdate="checkFlowAnimation('#Device_Sender');"class=""></div>
</div>
</div>
</div>
</div>
</div>

<div class="top-space">
<div data-type="switch" data-device="Device" data-get="Mute" data-set="Mute"
data-icon="fa-deaf" data-background-icon="-"
data-on-color="#aa6900" data-off-color="gray"
data-get-on="1" data-get-off="0"
data-set-on="1" data-set-off="0" class="inline mini">
</div>

<div data-type="classchanger" data-device="Device" data-get="currentNormalAudio" data-get-on="1" data-off-class="hide" class="inline top-space">
<div data-type="switch" data-device="Device" data-get="Repeat" data-set="Repeat"
data-icon="fa-repeat" data-background-icon="-"
data-on-color="#aa6900" data-off-color="gray"
data-get-on="1" data-get-off="0"
data-set-on="1" data-set-off="0" class="inline mini">
</div>

<div data-type="push" data-device="Device"
data-icon="fa-step-backward" data-background-icon="-"
data-off-color="#fff" data-on-color="#aa6900"
data-set-on="Previous" class="inline mini">
</div>

<div data-type="push" data-device="Device"
data-set="CurrentTrackPosition"
data-icon="fa-backward" data-background-icon="-"
data-off-color="#fff" data-on-color="#aa6900"
data-set-on="-30" class="inline mini">
</div>
</div>

<div data-type="switch"
data-device="Device"
data-get="transportState"
data-states='["PLAYING","PAUSED_PLAYBACK","STOPPED"]'
data-set-states='["Pause","Play","Play"]'
data-background-icon="fa-circle-thin"
data-background-colors='["#aa6900","white","white"]'
data-colors='["#aa6900","white","white"]'
data-icons='["fa-pause","fa-play","fa-play"]'
class="inline small">
</div>

<div data-type="classchanger" data-device="Device" data-get="currentNormalAudio" data-get-on="1" data-off-class="hide" class="inline">
<div data-type="push" data-device="Device"
data-set="CurrentTrackPosition"
data-icon="fa-forward" data-background-icon="-"
data-off-color="#fff" data-on-color="#aa6900"
data-set-on="+30" class="inline mini">
</div>

<div data-type="push" data-device="Device"
data-icon="fa-step-forward" data-background-icon="-"
data-off-color="#fff" data-on-color="#aa6900"
data-set-on="Next" class="inline mini">
</div>

<div data-type="switch" data-device="Device" data-get="Shuffle" data-set="Shuffle"
data-icon="fa-random" data-background-icon="-"
data-on-color="#aa6900" data-off-color="gray"
data-get-on="1" data-get-off="0"
data-set-on="1" data-set-off="0" class="inline mini">
</div>
</div>

<div data-type="popup" class="inline" data-width="650px" data-height="210px">
<div data-type="push"
data-icon="fa-list" data-background-icon="-"
data-off-color="#fff" data-on-color="#aa6900"
class="mini">
</div>

<div class="dialog">
<header><div data-type="joinedlabel" data-device="Device" data-mask="Musikauswahl[ für $1]" data-get='["roomName"]' class="inline"></div></header>

<div class="top-space-10 left-align left-space">
<div>
<div class="large middle inline">Favoriten: </div>
<div data-type="select"
data-device="Device"
data-list="FavouritesList"
data-alias="FavouritesListAlias"
data-delimiter="|"
data-quote="/"
data-get="currentFavouriteNameMasked"
data-set="StartFavourite"
class="inline w3x"
onchange="$('.dialog-close').trigger('click');"></div>
</div>

<div>
<div class="large middle inline">Playlists: </div>
<div data-type="select"
data-device="Device"
data-list="PlaylistsList"
data-alias="PlaylistsListAlias"
data-delimiter="|"
data-quote="/"
data-get="currentPlaylistNameMasked"
data-set="StartPlaylist"
class="inline w3x"
onchange="$('.dialog-close').trigger('click');"></div>
</div>

<div>
<div class="large middle inline">Radios: </div>
<div data-type="select"
data-device="Device"
data-list="RadiosList"
data-alias="RadiosListAlias"
data-delimiter="|"
data-quote="/"
data-get="currentRadioNameMasked"
data-set="StartRadio"
class="inline w3x"
onchange="$('.dialog-close').trigger('click');"></div>
</div>

<div>
<div class="large middle inline">Audio-Eingang: </div>
<div data-type="select"
data-device="Device"
data-list="Sonos:LineInPlayerList"
data-alias="Sonos:LineInPlayerListAlias"
data-delimiter="|"
data-get="currentAlbum"
data-set="PlayURI"
class="inline w3x"
onchange="$('.dialog-close').trigger('click');"></div>
</div>

<div>
<div class="large middle inline">Abspielliste: </div>
<div data-type="select"
data-device="Device"
data-list="QueueList"
data-alias="QueueListAlias"
data-delimiter="|"
data-get="currentTrack"
data-set="Track"
class="inline w3x"
onchange="$('.dialog-close').trigger('click');"></div>
</div>
</div>
</div>
</div>
</div>

<div data-type="spinner"
data-device="Device"
data-get="Volume"
data-set="Volume"
data-max="50"
data-step="1"
data-width="350"
data-icon-left="fa-volume-down tall"
data-icon-right="fa-volume-up tall"
data-gradient-color='["orange","red"]'
class="tap value positiononly top-space centered">
</div>
</div>
</pre>

===== Notwendige Userreadings =====

''Vorherige Version der Listenermittlung per Userreading''
<div class="mw-collapsible mw-collapsed">
Für die Funktionalität der Favoriten- / Playlisten- / Radioauswahl werden u.U. Userreadings benötigt, die die entsprechenden Listen ermitteln, und für die Verwendung im FTUI aufbereiten.
Außerdem gibt es ein Userreading für die Anzeige der Position innerhalb des Titels. Dieses kann man selber mittels eines wiederkehrenden AT- oder DOIF-Befehls aktualisieren lassen (ich verwende dafür eine 15 Sekündige Aktualisierung mittels DOIF, solange eine Wiedergabe läuft).

Userreading an jedem Sonosplayer-Device:
<pre>
Favourites:LastActionResult.*?GetFavouritesWithCovers.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
return $1;
}
},

Radios:LastActionResult.*?GetRadiosWithCovers.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
return $1;
}
},

Playlists:LastActionResult.*?GetPlaylistsWithCovers.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
return $1;
}
},

currentTrackPosition:LastActionResult.*?GetCurrentTrackPosition.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
return $1;
}
},

currentTrackPositionSec:currentTrackPosition.* {
return SONOS_GetTimeSeconds(ReadingsVal($name, "currentTrackPosition", "00:00:00"));
},

currentTrackDurationSec:currentTrackDuration.* {
return SONOS_GetTimeSeconds(ReadingsVal($name, "currentTrackDuration", "00:00:00"));
},

FavouritesList:LastActionResult.*?GetFavourites:.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
my @list = map { $_ =~ s/ /./g; $_ } map { substr($_, 1, -1) } split(',', $1);
return join('|', @list);
}
},

FavouritesListAlias:LastActionResult.*?GetFavourites:.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
my @list = map { substr($_, 1, -1) } split(',', $1);
return join('|', @list);
}
},

currentFavouriteNameMasked:currentFavouriteName.* {
my $favouriteName = ReadingsVal($name, "currentFavouriteName", "");
$favouriteName =~ s/ /\./g;
return $favouriteName;
},

PlaylistsList:LastActionResult.*?GetPlaylists:.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
my @list = map { $_ =~ s/ /./g; $_ } map { substr($_, 1, -1) } split(',', $1);
return join('|', @list);
}
},

PlaylistsListAlias:LastActionResult.*?GetPlaylists:.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
my @list = map { substr($_, 1, -1) } split(',', $1);
return join('|', @list);
}
},

currentPlaylistNameMasked:currentPlaylistName.* {
my $name = ReadingsVal($name, "currentPlaylistName", "");
$name =~ s/ /\./g;
return $name;
},

RadiosList:LastActionResult.*?GetRadios:.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
my @list = map { $_ =~ s/ /./g; $_ } map { substr($_, 1, -1) } split(',', $1);
return join('|', @list);
}
},

RadiosListAlias:LastActionResult.*?GetRadios:.* {
if (ReadingsVal($name, "LastActionResult", "") =~ m/.*?: (.*)/) {
my @list = map { substr($_, 1, -1) } split(',', $1);
return join('|', @list);
}
},

currentRadioNameMasked:currentRadioName.* {
my $name = ReadingsVal($name, "currentRadioName", "");
$name =~ s/ /\./g;
return $name;
},

currentFavouriteNameMasked:currentFavouriteName.* {
my $favouriteName = ReadingsVal($name, "currentFavouriteName", "");
$favouriteName =~ s/ /\./g;
return $favouriteName;
},

currentPlaylistNameMasked:currentPlaylistName.* {
my $name = ReadingsVal($name, "currentPlaylistName", "");
$name =~ s/ /\./g;
return $name;
},

currentRadioNameMasked:currentRadioName.* {
my $name = ReadingsVal($name, "currentRadioName", "");
$name =~ s/ /\./g;
return $name;
},

ZoneGroupNameDetails:(MasterPlayer|roomName|SlavePlayer).* {
my $result = ReadingsVal(ReadingsVal($name, 'MasterPlayer', $name), 'roomName', 'k.A.');
$result = '' if ($name eq ReadingsVal($name, 'MasterPlayer', $name));
foreach my $slave (@{eval(ReadingsVal($name, 'SlavePlayer', '[]'))}) {
$result .= ' + '.ReadingsVal($slave, 'roomName', $slave);
}

return $result;
},

SlavePlayerList:SlavePlayer:.* {
my @player = @{eval(ReadingsVal($name, 'SlavePlayer', '[]'))};
return (scalar(@player) ? '-|' : '').join('|', @player);
},

SlavePlayerListAlias:SlavePlayer:.* {
my @player = @{eval(ReadingsVal($name, 'SlavePlayer', '[]'))};
return (scalar(@player) ? 'Auswahl|' : '').join('|', map { $_ = ReadingsVal($_, 'roomName', $_); $_ } @player);
},

AvailablePlayerList:(MasterPlayer|SlavePlayer):.* {
my @player = @{eval(ReadingsVal('Sonos', 'MasterPlayer', '[]'))};

# Selber entfernen...
splice(@player, SONOS_posInList($name, @player), 1);

# Slaveplayer entfernen...
foreach my $elem (@{eval(ReadingsVal($name, 'SlavePlayer', '[]'))}) {
my $pos = SONOS_posInList($elem, @player);
splice(@player, $pos, 1) if ($pos >= 0);

}

return (scalar(@player) ? '-|' : '').join('|', @player);
},

AvailablePlayerListAlias:(MasterPlayer|SlavePlayer):.* {
my @player = @{eval(ReadingsVal('Sonos', 'MasterPlayer', '[]'))};

# Selber entfernen...
splice(@player, SONOS_posInList($name, @player), 1);

# Slaveplayer entfernen...
foreach my $elem (@{eval(ReadingsVal($name, 'SlavePlayer', '[]'))}) {
my $pos = SONOS_posInList($elem, @player);
splice(@player, $pos, 1) if ($pos >= 0);
}

return (scalar(@player) ? 'Auswahl|' : '').join('|', map { $_ = ReadingsVal($_, 'roomName', $_); $_ } @player);
}
</pre>
Damit werden bei einem Abruf der Favoriten / Playlists / Radios mittels entsprechendem Get-Befehl die entsprechenden Listen für alle Features aufbereitet und am Sonosplayer-Device bereitgestellt.
</div>

<br />''Aktuelle Userreading''<br />
Mit der aktuellen Modulversion werden hierfür keinerlei Userreadings mehr benötigt.

Mit dem Attribute ''getListsDirectlyToReadings'' werden alle möglichen Listen zu Favoriten, Playlists, Radios und der aktuellen Abspielliste (= Queue) automatisch in die richtigen Readings geschrieben.

Des Weiteren kann man mit dem Attribut ''simulateCurrentTrackPosition'' eine Simulation der aktuellen Titelposition aktivieren, sodass eine wiederkehrende Aktualisierung durch ein DOIF o.ä. nicht mehr notwendig ist.

===== Automatische Aktualisierung der Favoriten / Playlisten / Radios durch Notifies =====
Mit den folgenden Notifies kann man auf die Mitteilung der Sonosplayer über eine neue Version der jeweiligen Liste reagieren, und diese im Playerdevice automatisch aktualisieren lassen.
Damit hat man stets die aktuellen und zum Sonos-System passenden Listen in den Userreadings.

<pre>
define Sonos_GetNewFavouritesNotify notify Sonos_[^_]+:FavouritesVersion.* { fhem("get $NAME FavouritesWithCovers");; fhem("get $NAME Favourites");; }

define Sonos_GetNewPlaylistsNotify notify Sonos_[^_]+:PlaylistsVersion.* { fhem("get $NAME PlaylistsWithCovers");; fhem("get $NAME Playlists");; }

define Sonos_GetNewRadiosNotify notify Sonos_[^_]+:RadiosVersion.* { fhem("get $NAME RadiosWithCovers");; fhem("get $NAME Radios");; }

define Sonos_GetNewQueueNotify notify Sonos_[^_]+:QueueVersion.* { fhem("get $NAME QueueWithCovers");; fhem("get $NAME Queue");; }
</pre>

[[Category:Examples]]
[[Category:HOWTOS]]
[[Category:Code Snippets]]
[[Category:Unterhaltungselektronik]]
[[Kategorie:Akustische Ausgabe]]

HomeMatic HMInfo TempList/Weekplan

2019-09-29T11:19:16Z

Moontear: Ich halte eine kurze Zusammenfassung sinnvoll, da ich jedes Mal diesen Artikel durchforste welche Befehle ich durchführen muss zum umschalten.

{{Infobox Modul
|ModPurpose=Behandlung von Wochenprogrammen für Thermostate
|ModType=d
|ModCmdRef=HMinfo Weekplan
|ModForumArea=HomeMatic
|ModTechName=98_HMinfo.pm
|ModOwner=martinp876 ({{Link2FU|251|martinp876}} / [[Benutzer Diskussion:Martinp876|Wiki]])
}}

'''HMInfo TempList''' ist eine Funktion des Moduls [[Homematic_HMInfo|HMInfo]], die es erlaubt Temperaturlisten (Wochenprogramme) von [[HomeMatic Type Thermostat|Thermostaten]] zu verwalten.

== Einleitung==
Homematic bietet eine Reihe von Heizkörperthermostaten, welche mit einem Wochenprogramm ausgestattet sind. Die Erstellung und Verwaltung dieser Wochenprogramme ist im Device zumindest umständlich, siehe dazu [[HomeMatic_Type_Thermostat#Templates]]
== Begriffe==
Wir müssen strikt 3 Wochenpläne unterscheiden:
* ''activeList'' Wochenplan im Device. Dieser, und nur dieser ist '''wirksam'''. Er kann nicht direkt in FHEM dargestellt werden. FHEM muss die Daten auslesen um sie verarbeiten zu können. Siehe hierzu kommandos und attribute des Device:getConfig und autoReadReg.
* ''referenceList'' Wochenplan in FHEM. Für jedes Device wird ein Wochenplan (bei einigen Devices können es sogar mehrere sein) dargestellt. Dies ist die aus dem Device gelesene activeList. Es liegt in der Verantwortung des User, die Liste aktuell zu halten.
* ''tempTemplates'' Vorlagen für Wochenpläne. Diese werden in externen Dateien erstellt. Man kann Devices eines der tempTemplates zuweisen um es zu prüfen oder einzuspielen.

== Wochenprogramme ==
=== Datei ===
{{Randnotiz|RNTyp=g|RNText=Ab firmware-Version 1.5 unterstützen die HM-TC-RT-DN nach Angaben eines Forennutzers auch Angaben im 5-Minuten-Raster.}}
Zur Verwendung einer Temperaturliste als Wochenprogramm muss eine Datei erzeugt werden, mit folgendem Inhalt:
* Für jede Temperaturliste eine Namensliste in der Form <code>entities:<name1>,<name2>,...</code>
** ein Name darf in einer Datei '''nicht''' doppelt vorkommen.
** der gleiche Name darf in unterschiedlichen Dateien verwendet werden.
* In jeder Temperaturliste eine Zeile pro Tag, beginnend mit <code>tempList<Wochtentag>> ....</code>
** Es muss eine Zeile je Wochentag vorhanden sein
* In jeder Zeile nach dem Wochentagscode eine Liste von Zeit/Wert-Paaren, diese stellen das jeweilige Tagesprogramm dar, z.B. '''08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0''',
** Jedes Tagesprogramm beginnt um 00:00 Uhr.
** Das erste Paar 08:00 14.0 bedeutet also, dass von 00:00 '''bis 08:00''' eine Temperatur von 14.0 eingestellt werden soll.
** Das zweite Paar 15:00 18.0 bedeutet also, dass von 08:00 bis 15:00 18.0 Grad einzustellen sind
** Es sind immer Paare einzutragen
** der Beginn um 00:00 ist nicht einzutragen
** der letzte Eintrag '''muss''' an jeden Tag 24:00 sein
** Uhrzeiten sind auf halbe Stunden beschränkt. Einträge 08:00 und 08:30 sind gültig. 08:20 ist ungültig.
Beispiel:
entities:tempTmpl1
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_1_tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 17.0
R_2_tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_3_tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
R_4_tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_5_tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_6_tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0
entities:tempTWohnzimmer
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 17.0
R_1_tempListSun>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
R_2_tempListMon>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_3_tempListTue>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 15.0
R_4_tempListWed>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_5_tempListThu>07:00 14.0 16:00 18.0 21:00 19.0 24:00 14.0
R_6_tempListFri>07:00 14.0 13:00 16.0 16:00 18.0 21:00 19.0 24:00 14.0

==== Erstellen der ersten Template-Datei====
Um nicht auf der grünen Wiese beginnen zu müssen, empfiehlt es sich den aktuellen Ist-Zustand (die ''referenceList'') mit dem unten beschriebenen HMInfo-Befehl <code>save</code> in eine Datei zu schreiben. Vorab sollten die HMInfo-Attribute <code>configDir</code> und <code>configTempFile</code> gesetzt sein.
attr <HMInfo> configDir setup
attr <HMInfo> configTempFile myWeekplan.cfg
set <HMInfo> tempList save
Der letzte Befehl speichert die ''referenceList'' jedes Gerät in der Datei <code>setup/myWeekplan.cfg</code>. Als ''Entity'' wird der Name des Thermostaten verwendet – das Attribut ''tempListTmpl'' wird nicht beachtet. Die Datei kann anschließend mit einem Text-Editor bearbeitet werden. Wochenpläne können zusammengefasst und verändert werden.

''Achtung'': bei der Verwendung von [[configdb]] wird die Datei nicht in das Dateisystem, sondern gleich in die configDB geschrieben. Mit Hilfe des Kommandos

configdb filelist
configdb fileexport myWeekplan.cfg

kann diese exportiert, bearbeitet und danach wieder in die configdb eingelesen werden.

=== Templates zuweisen===
tempListTemplates werden immer in Files verwaltet. Man kann Templates in mehreren Files verwalten. Ferner gibt es unterschiedliche Methoden, ein File zu spezifizieren.
* '''attr tempListTmpl im Device''': hier spezifiziert man das Template. Will man sich von templates entkoppeln sollte man '''tempListTmpl none''' unbedingt setzen.
** '''Wohnzimmer''': das template '''Wohnzimmer''' wird im default File gesucht
** '''myWeekplan.cfg:Wohnzimmer''': das template '''Wohnzimmer''' wird im File ''myWeekplan.cfg'' mit relativen Pfad von FHEM home gesucht
** '''./setup/myWeekplan.cfg:Wohnzimmer''': das template '''Wohnzimmer''' wird im File ''myWeekplan.cfg'' mit relativen Pfad ''./setup'' gesucht
** '''/opt/fhem/myWeekplan.cfg:Wohnzimmer''': das template '''Wohnzimmer''' wird im File ''myWeekplan.cfg'' mit absoluten Pfad ''/opt/fhem/'' gesucht
* '''attr configTempFile in HMInfo''': spezifiziert weekplan configurationsfiles. Es ist eine Liste Wochenplan Files welche genutzt werden. Ist das Attribut nicht gesetzt wird als ''default tempList.cfg'' genutzt.
** '''attr hm configTempFile myWeekPlan.cfg''': FHEM kennt ein File mit Wochenplan. Dies ist auch das Default für alle tempListTmpl in denen kein File spezifiziert.
** '''attr hm configTempFile mySummerPlan.cfg,myWinterPlan.cfg,myPartyPlan.cfg''': FHEM sind 3 Files bekannt. Der erste Eintrag ''mySummerPlan.cfg'' ist der Default für tempListTmpl .
* '''attr configDir in HMInfo''': spezifiziert einen Pfad, der ''auch'' für configTemplFile genutzt wird. Es erleichtert Konfigurations-Dateien in einem separaten Verzeichnis anzulegen. ''attr hm configDir setup'' wäre ein sinnvoller Eintrag. Das Verzeichnis ''setup'' unter fhem sollte erstellt werden. Ist das Attribut nicht gesetzt ist fhemHome der default.

=== HMInfo Kommandos ===
Die HMInfo-Befehle, die Temperaturlisten verwalten, folgen dem Schema:
set <HMInfo> tempList <Befehl> [<Dateiname>]
Die verfügbaren Befehle sind:
; <code>save</code>
: Speichert den aktuellen Zustand der Thermostate (''referenceList'') in der ''tempList''-Datei ab. Zu beachten ist, dass die aktuell in FHEM vorhandenen Werte benutzt werden. Der Benutzer muss selbst sicher stellen, dass diese mit den Werten im Gerät übereinstimmen. Alle eventuell vorher in der Datei vorhandenen Werte werden überschrieben.
; <code>verify</code>
: Vergleicht den Ist-Zustand (''referenceList'') mit dem Soll-Zustand (dem Wochenplan aus dem ''tempListTmpl''-Attribut). Abweichungen werden angezeigt, aber nicht behoben. Diese Prüfung ist auch Teil von HMInfos <code>configCheck</code>.
; <code>restore</code>
: Stellt den Soll-Zustand wieder her. Funktioniert im Prinzip wie <code>verify</code>, jedoch werden alle Abweichungen vom Soll-Zustand korrigiert. Zu beachten ist die Verzögerung beim Schreiben (siehe [[HomeMatic HMInfo#protoEvents|HMInfo protoEvents]], Device Status und Beschreibung des Device) und dass nach dem Schreiben die ''referenceList'' neu geladen werden muss. Es wird empfohlen, <code>autoReadReg</code> auf Level 5 zu setzen. Ein Restore kann jederzeit ausgeführt werden. Sind alle Daten aktuell, wird ''keine'' Temperaturliste geschrieben; es erfolgt keinerlei Funkverkehr.
; <code>status</code>
: Gibt eine Übersicht über die genutzten Templates aus.

Das Web-Frontend verwendet den nahezu identischen Befehl <code>tempListG</code>. Da dieser Befehl keine weiteren Argumente zulässt kann das Frontend ein Pulldown-Menü anzeigen. Das "G" steht für "Global" – da keine Filter unterstützt werden, wirken alle Befehle auf alle HomeMatic-Geräte.

==Nutzungsbeispiele==
=== Mehrere Heizkörper in einem Raum===
Wenn sich in einem Raum mehrere Heizkörperthermostate befinden, sollten diese – wie in [[HM-CC-RT-DN]] beschrieben – gepeert werden.
HomeMatic geht davon aus, dass alle HM-CC-RT-DNs den selben Wochenplan haben (gilt ggf. auch für einen zugehörigen [[HM-TC-IT-WM-W-EU]]).

Um dies zu erreichen definiert man einen Wochenplan für das Zimmer, beispielsweise <code>Wohnzimmer.cfg</code>. Anschließend wird dieser Wochenplan allen Teammitgliedern zugewiesen:

attr <HM-CC-RT-DN#1>_Clima tempListTmpl Wohnzimmer
attr <HM-CC-RT-DN#2>_Clima tempListTmpl Wohnzimmer
attr <HM-CC-RT-DN#3>_Clima tempListTmpl Wohnzimmer
attr <HM-TC-IT-WM-W-EU>_Climate tempListTmpl Wohnzimmer
set hm tempListG restore

=== Mehrere Heizkörper mit gleichen Profil===
Will man Wohnräume identisch behandeln im Hinblick auf den Wochenplan weisst man den Thermostaten identische Profile zu.

attr RTSusi_Clima tempListTmpl Kinderzimmer
attr RTjonas_Clima tempListTmpl Kinderzimmer
attr RTwohnzimmer_Clima tempListTmpl Kinderzimmer
set hm tempListG restore
=== Wohnungsnutzung umschalten===
Das Heizprofil kann man Zentral umstellen. Verlässt man die Wohnung zum Urlaub, der Sommer naht, man macht die üblich 3-Woche Party... . Alle Thermostate sollen umgestellt werden, zentral mit wenigen Kommandos, einfach zu prüfen. Sinnvoll ist es mehrere tempList.cfg Files anzulegen. Nehmen wir 4 Files an, Winter, Urlaub zu hause UrlaubIn, Urlaub nicht zu hause UrlaubOut sowie Sommer. Ferner hat man (der Einfachheit halber) 3 RTs: RTwohn, RTschlaf, RTkueche.
Die RTs haben jeweils ihr attr tempListTmpl gesetzt entsprechend ihrem Namen.
Man legt also die 4 Files an mit entities die man zusammenfassen kann (templisten muss man natürlich befüllen:
File Winter.cfg
entity: RTwohn
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...
entity: RTschlaf
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...
entity: RTkueche
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...

File UrlaubIn.cfg
entity: RTwohn,RTkueche
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...
entity: RTschlaf
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...

File UrlaubOut.cfg
entity: RTwohn,RTschlaf,RTkueche
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...

File Sommer.cfg
entity: RTwohn,RTschlaf,RTkueche
R_0_tempListSat>08:00 14.0 15:00 18.0 21:30 19.0 24:00 14.0
...

In HMInfo sollte man nun verwalten:
attr RTwohn_Clima tempListTmpl RTwohn
attr RTkueche_Clima tempListTmpl RTkueche
attr RTschlaf_Clima tempListTmpl RTschlaf
attr hm configTempFile Winter.cfg,Sommer.cfg,UrlaubIn.cfg,UrlaubOut.cfg

Winter.cfg ist nun default. Mit set hm tempListG verify kann man prüfen, dass es entsprechend genutzt ist. Nun will man in Urlaub fahren. Man schaltet das Default durch umstellen der Reihenfolge um und aktiviert es durch ein restore:
attr hm configTempFile UrlaubOut.cfg,Winter.cfg,Sommer.cfg,UrlaubIn.cfg
set hm tempListG restore

UrlaubOut.cfg ist default. Alle notwendigen Änderungen werden in die RTs programmiert.
Unberührt bleibt Opas Zimmer, der nicht das default file sondern ein dediziertes nutzt.

attr RTopa_Clima tempListTmpl Winter.cfg:RTopa

Das template RTopa muss also nur im File Winter.cfg vorhanden sein:

=== Vorgehen Winter/Sommerumstellung ===
Wenn man von dem einen auf das andere Heizprogramm umschalten möchte (ausgehend davon dass es Winter.cfg und Sommer.cfg gibt, und man auf Winter umstellen möchte), sind die typischen Befehle die Folgenden:

attr hm configTempFile Winter.cfg,Sommer.cfg
set hm tempListG restore
set hm tempListG verify

Nach einer kurzen Zeit sollten alle Heizkörper ein ''passed'' per verify wiedergeben. Dass sie sofort nach setzen der neuen Konfiguration per ''restore'' ein fail wiedergeben ist normal.

[[Kategorie:HomeMatic supportDevice]]
[[Kategorie:HOWTOS]]

Dewpoint

2019-02-10T17:35:16Z

Moontear: attribute 'absFeuchte' is deprecated, please use 'absoluteHumidity'

{{SEITENTITEL:dewpoint}}
{{Infobox Modul
|ModPurpose=Berechnung des Taupunkts
|ModType=h

|ModCmdRef=dewpoint
|ModTechName=98_dewpoint.pm
|ModOwner=Willi Herzig}}

Das Modul [[dewpoint]] bietet Funktionen im Zusammenhang mit der Taupunktberechnung an. Die verfügbaren Funktionen, über einen Parameter bei der Definition gesteuert, sind
* dewpoint (Taupunkt)
* fan (erzeugt ein Event, das zur Lüftersteuerung verwendet werden kann)
* alarm (erzeugt einen "Schimmel-Alarm", wenn eine Referenztemperatur unter den Taupunkt fällt)
{{todo|Seite muss noch vervollständigt werden --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 13:49, 14. Mär. 2016 (CET)}}
== Voraussetzungen ==
Es muss ein Device geben, das die zur Berechnung erforderlichen Basisdaten ''Temperatur'' und ''Feuchte'' liefert. Die Namen der entsprechenden Readings können bei der Definition des ''dewpoint'' Device angegeben werden.

== Anwendung ==
=== Define ===
Ein ''dewpoint'' Device (siehe auch {{Link2CmdRef|Anker=dewpoint}}) wird definiert mit:
:<code>define <name> dewpoint <type> ...</code>
Mögliche Werte und Bedeutung von
;type
*dewpoint - aus ''temp_name'' und ''hum_name'' wird der Taupunkt berechnet und als Reading mit dem Namen ''new_name'' an die durch ''devicename-regex'' spezifizierten Devices hinzugefügt
*fan -
*alarm -

Die vollständige Syntax für den Typ ''dewpoint'':
:<code>define <name> dewpoint '''dewpoint''' <devicename-regex> [<temp_name> <hum_name> <new_name>]</code>
wobei die Platzhalter folgende Bedeutung haben:
;name
:der Name des definierten ''dewpoint'' Device
;devicename-regex
:Spezifikation des Geräts / der Geräte, von denen ''temp_name'' und ''hum_name'' gelesen und ''new_name'' geschrieben werden soll
;temp_name
:Name des Readings, das den Temperaturwert enthält; wenn dieser Parameter nicht angegeben ist, wird ''temperature'' angenommen
;hum_name
:Name des Readings, das den Feuchtewert enthält; wenn dieser Parameter nicht angegeben ist, wird ''humidity'' angenommen
;new_name
:Name des Readings, das den berechneten Taupunkt aufnehmen soll; wenn dieser Parameter nicht angegeben ist, wird ''dewpoint'' angenommen

==== Statuszeile ====
Will man den Taupunkt nicht als einzelnes Reading ''dewpoint'', sondern in Kurzform zusammen mit den anderen Werten in der Statuszeile anzeigen lassen, so muss man für ''temp_name'' und ''hum_name'' die Spezialwerte ''T'' und ''H'' angeben:
:<code>define dew_state dewpoint dewpoint .* T H D</code>
Dies bewirkt, dass bei allen abgefragten Geräten die Werte ''T'' und ''H'' aus der Statuszeile ausgelesen werden und selbige dann wie folgt um den Taupunkt mit dem Buchstaben ''D'' erweitert wird:
<pre>T: 18.2 H: 55 D: 9.0</pre>

=== Attribute ===
;absoluteHumidity
:Beim Setzen dieses Attributs wird zusätzlich die absolute Luftfeuchtigkeit (in Gramm Wasser pro Kubikmeter Luft) berechnet und als Reading mit dem Namen ''absoluteHumidity'' ausgegeben. Hat man das Dewpoint-Device vorher so definiert, dass es den Taupunkt an den Status anhängt:

:<code>define dew_state dewpoint dewpoint .* T H D</code>
:<code>attr dew_state absoluteHumidity 1</code>

:dann braucht man nichts weiter zu tun, die absolute Feuchtigkeit wird ab sofort unter dem Buchstaben ''A'' an den Status angehängt:

:<pre>T: 18.2 H: 55 D: 9.0 A: 8.5</pre>

:Für den Taupunkt konnte man mit dem Parameter ''new_name'' einen eigenen Namen für das erzeugten Reading festlegen. Für die absolute Luftfeuchte ist dieser Parameter nicht vorhanden, das Reading hat immer den Standardnamen ''absoluteHumidity'' bzw. ''A'' in der Statuszeile.

== Anwendungsbeispiele ==

== Alternativen zu diesem Modul ==

=== Berechnung direkt im userReading ===

Um den Taupunkt einfach berechnen zu können, kann neben dem Modul ''dewpoint'' auch das Folgende userReading gesetzt werden (der Code dazu wurde direkt aus dem Modul entnommen und ist so über das Webinterface einzugeben).

Das Userreading hat den Vorteil, nicht mit anderen Modulen in Konflikt zu geraten.
<syntaxhighlight lang="perl">attr <Device> userReadings dew:temperature.* {
my $dp;
my $temperature = ReadingsVal($name,"temperature",0);
my $humidity = ReadingsVal($name,"humidity",0);
my $A = 17.2694;
my $B = ($temperature > 0) ? 237.3 : 265.5;
my $es = 610.78 * exp( $A * $temperature / ($temperature + $B) );
my $e = $humidity/ 100 * $es;
if ($e == 0) { Log 1, "Error: dewpoint() e==0: temp=$temperature, hum=$humidity";
return 0;
}
my $e1 = $e / 610.78;
my $f = log( $e1 ) / $A;
my $f1 = 1 - $f;
if ($f1 == 0) {
Log 1, "Error: dewpoint() (1-f)==0: temp=$temperature, hum=$humidity";
return 0;
}
$dp = $B * $f / $f1 ;
sprintf "%.2f", $dp;
}</syntaxhighlight>
(Das obige Beispiel wurde nach Umstellung auf "Source"-Formatierung noch nicht getestet. --[[Benutzer:Ph1959de|Peter]] ([[Benutzer Diskussion:Ph1959de|Diskussion]]) 13:49, 14. Mär. 2016 (CET))

=== Variante über 99_myUtils ===

Noch besser ist es, die im vorigen Abschnitt durchgeführte Berechnung nicht für jedes Device per userReading wieder neu einzugeben, sondern diese einmalig als Funktion in der 99_myUtils zu hinterlegen und diese dann im jeweiligen Device im userReading nur noch aufzurufen.

Dazu ist in der 99_myUtils folgende sub anzulegen:

<syntaxhighlight lang="perl">
sub urDewpoint
{
my ($dname,$tname,$hname) = @_;

#Prüfen, ob überhaupt ein Device(-name) als Parameter übergeben wurde
if(!defined($dname)) {
Log3 undef,1,"Error: urDewpoint - No device specified!";
return 0;
}

#Prüfen, ob das angegebene Device überhaupt existiert
if(!$defs{$dname}) {
Log3 undef,1,"Error: urDewpoint - Device $dname is not defined!";
return 0;
}

#Wenn keine Readingsnamen für die Temperatur oder Luftfeuchtigkeit
#übergebenwurde wird per default temperature oder humidity verwendet
$tname='temperature' if(!defined($tname));
$hname='humidity' if(!defined($hname));

my $dp;

#Auslesen der Readingswerte für Temperatur und Luftfeuchtigkeit aus den
#entsprechenden Readings des Devic
my $temperature = ReadingsVal($dname,$tname,0);
my $humidity = ReadingsVal($dname,$hname,0);

#Magische Berechnung :)
my $A = 17.2694;
my $B = ($temperature > 0) ? 237.3 : 265.5;
my $es = 610.78 * exp( $A * $temperature / ($temperature + $B) );
my $e = $humidity/ 100 * $es;
if ($e == 0) {
Log3 undef,1, "Error: urDewpoint: $dname - e==0: temp=$temperature, hum=$humidity";
return 'ERR';
}
my $e1 = $e / 610.78;
my $f = log( $e1 ) / $A;
my $f1 = 1 - $f;
if ($f1 == 0) {
Log3 undef,1, "Error: urDewpoint: $dname - (1-f)==0: temp=$temperature, hum=$humidity";
return 'ERR';
}
$dp = $B * $f / $f1 ;

#Rückgabe der Taupunkt-Temperatur
return sprintf "%.2f", $dp;
}
</syntaxhighlight>

Anschließend kann dann im jeweiligen Device ganz einfach ein userReading definiert werden:

<syntaxhighlight lang="perl">attr <Device> userReadings dew:temperature.* {urDewpoint($name)}</syntaxhighlight>

Die Readings-Namen für Temperatur und Luftfeuchtigkeit bei Device können bei bedarf auch abweichend angegeben werden. Bei den Homematic-Wandthermostaten heßt das Reading für die tatsächlich gemessene Temperatur measured-temp und nicht temperature, dann würde die definition des userReading wie folgt aussehen:

<syntaxhighlight lang="perl">attr <Device> userReadings dew:measured-temp.* {urDewpoint($name,'measured-temp')}</syntaxhighlight>

== Links ==
* Forendiskussion um {{Link2Forum|Topic=8576|LinkText=Lüften oder nicht}}
* Forendiskussion um {{Link2Forum|Topic=23080|LinkText=Temperaturdifferenz}}

[[Kategorie:HOWTOS]]

Alexa-Fhem

2018-05-14T09:58:47Z

Moontear: node.js 4.3 ist deprecated. Neue Node.JS funktioniert ebenfalls wunderbar in der Lambda Funktion

'''Alexa-Fhem''' ist eine in JavaScript geschriebene und auf NodeJS basierende Software, welche es ermöglicht, der digitalen Amazon Assistentin Alexa zusätzliche Skills für die Heimautomatisierung via FHEM beizubringen. Eine erste funktionierende Version wurde von [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im {{Link2Forum|Topic=60244|LinkText=Forum}} veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==Einführung==
===Glossar===
*Echo bzw. Echo Dot (im Folgenden maskulin bezeichnet) sind die derzeit verfügbaren Geräte des Alexa-Systems '''BILDER EINSTELLEN - Achtung Urheberrecht'''
*AVS ist der Amazon Voice Service, d.h. die Spracherkennungskomponente des Systems.{{Randnotiz|RNTyp=r|RNText=Für die Nutzung der Amazon AWS-Dienste müssen zwingend die Daten einer Kreditkarte angegeben werden. Nach gegenwärtigem Kenntnisstand sollen jedoch keine Kosten für die Nutzung der im Rahmen dieses How To beschriebenen Dienste anfallen, sofern diese in einem Rahmen genutzt werden, der selbst eine intensive private Nutzung nicht überschreitet. Der Benutzer sei an dieser Stelle auf die von Amazon veröffentlichten Preislisten verwiesen. Die Autoren dieser Anleitung und der darin beschriebenen Module übernehmen keine Haftung für eventuelle Kosten, die aus der Nutzung der AWS entstehen. }}
*AWS sind die Amazon Web Services, also per URL erreichbare Dienste zur Ausführung von Berechnungen etc. Im Rahmen von Alexa-Fhem wird bei AWS eine eigene JavaScript-Funktion hinterlegt, die zur Kommunikation mit dem FHEM-Server dient. Im Jargon von Amazon ist dies eine so genannte Lambda-Funktion '''WARUM ? Nachlesen bei Amazon'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fähigkeit) ist die Bezeichnung für eine per Spracherkennung bediente Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, zur Wettervorhersage oder zur Steuerung von FHEM

===Arbeitsweise und Datenfluss===
[[Datei:2gpXyLN.jpg|200px|thumb|right|Grafische Darstellung der beteiligten Komponenten]]
Echo -> AVS -> AWS Lambda -> alexa-fhem -> AWS Lambda -> AVS -> Echo

*Der Echo (oder ein anderes Alexa/AVS fähiges Gerät) nimmt Audiodaten auf und schickt diese an AVS (Amazon Voice Service) zur Erkennung
*AVS führt die Spracherkennung durch und erzeugt ein Event mit Informationen zu den erkannten Daten
:*Beim Alexa SmartHome Skill sind die möglichen Sätze für die Spracherkennung relativ fest vorgegeben
:*Beim Alexa Custom Skill kommen die dazu nötigen Informationen aus dem ''Interaction Model'' der Alexa Skills Configuration
*Das Event wird an den unter ''Configuration'' in der Alexa Skills Configuration hinterlegten Endpoint geschickt
:*Beim Alexa SmartHome Skill ist das zwingend eine AWS Lambda Routine
:*Beim Alexa Custom Skill kann das im Prinzip auch ein eigener Web Service sein
*Das Event wird vom <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> nimmt diese Antwort entgegen und gibt sie an AVS zurück
*AVS sogt dafür das der Echo 'antwortet' und dass die Card in der Alexa App erscheint

===Anmerkungen===
*Ein Skill hat keinen Zugriff auf die Audiodaten
*Mit dem Skill API kann ein Skill zu zu keiner Zeit von sich aus aktiv werden und 'einfach' Daten an den Echo schicken oder ihn dazu bringen irgendetwas zu tun.
*Wenn man berücksichtigt welchen Weg die Daten insgesamt gehen, ist es erstaunlich, wie schnell die Reaktion auf einen gesprochenen Satz erfolgt.

=== Abgrenzung des '''Alexa Smart Home Skills''' und des '''Alexa Custom Skills''' ===

Der [[Alexa-Fhem#Smart_Home|Alexa Smart Home Skill]] ist ein Amazon-Alexa-Standard-Skill, der wesentliche Basisfunktionalitäten bereitstellt. Zu diesen gehört im Wesentlichen die Funktionalität, durch Alexa-FHEM bereitgestellte Devices im Alexa-Account des Benutzers anzulegen. Der Alexa Smart Home Skill reagiert auf gesprochene Interaktion in einem beschränkten Umfang. Beispielsweise genügt ein "Alexa, schalte die Wohnzimmerlampe an" um eine Interaktion zwischen Alexa Smart Home Skill und FHEM-Alexa auszulösen. Nach erfolgreicher Einrichtung wird dieser Skill in der Alexa-App bzw. im Web in der Rubrik "Smart Home" als Skill angezeigt.

Der [[Alexa-Fhem#Custom|Alexa Custom Skill]] ist kein Standard-Smart-Home-Skill, sondern ein individuell entwickelter Skill, so wie alle anderen Skills auch. Er wird daher auch nicht in der Alexa-App unter der Rubrik "Smart Home" angezeigt. Gesprochene Interaktion mit diesem Skill erfolgt dadurch, dass entweder der Skill explizit gestartet wird (z.B. "Alexa, starte [Name des Skills]") oder direkt angesprochen wird (z.B. "Alexa, frage [Name des Skills] wie ist der Status von [Device] "). Der Alexa Custom Skill befindet sich in Entwicklung und wird hinsichtlich seiner Funktionalitäten laufend weiterentwickelt. Die Einrichtung dieses Skills ist grundsätzlich optional, jedoch werden anspruchsvollere Steuerungsmöglichkeiten nur mit diesem realisiert werden können.

==Installation==
{{Randnotiz|RNTyp=[g|Info]|RNText=Da die einzelnen Schritte der Anleitung an verschiedenen Stellen unterbrochen und später fortgesetzt werden müssen, empfiehlt es sich, die Anleitung einmal vollständig gelesen zu haben. Während der Konfiguration sollten alle nachfolgenden Abschnitte parallel in gleichzeitig geöffneten Browserfenstern durchgeführt werden, die jeweils bis zum Abschluss geöffnet bleiben müssen. }}
Grundvoraussetzung für alle folgenden Schritte ist das Vorhandensein eines Amazon-Accounts. Es wird davon ausgegangen, dass die Konten für alle im Folgenden genutzten Amazon-Dienste eingerichtet wurden.

===node.js installieren===
Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<syntaxhighlight lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</syntaxhighlight>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:
<syntaxhighlight lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils {{Link2Forum|Topic=81324|Message=733986|LinkText=hier}} zu finden.
Wer bisher noch keinen Alexa-FHEM Skill angelegt hat, bitte {{Link2Forum|Topic=81324|Message=733986|LinkText=diesen Forumsbeitrag}} beachten!

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben.
===== Linux =====
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).<syntaxhighlight lang="bash" style="width:50%;">tar -xvzf dateiname.tgz</syntaxhighlight>
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <syntaxhighlight lang="bash" style="width:50%;">mv package alexa-fhem</syntaxhighlight>
# Durch <syntaxhighlight lang="bash" style="width:50%;">cd alexa-fhem</syntaxhighlight> in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
{{Randnotiz|RNTyp=[g|Info]|RNText=createKey.sh erzeugt ein Zertifikat, das 365 Tage gültig ist. Dies muss deswegen jedes Jahr erneuert werden }}
# SSL Zertifikat erzeugen durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./createKey.sh</syntaxhighlight> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei wird ggf. bei einem manuellen Start von Alexa-Fhem nicht gefunden.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis kopiert werden.
===== Windows =====
''Vor'' der Installation von Alexa-Fhem muss man folgende Anwendungen installieren:
* Node.js (die aktuelle Version findet man unter https://nodejs.org/en/download/)
* OpenSSL (http://slproweb.com/products/Win32OpenSSL.html oder https://www.heise.de/download/product/win32-openssl-47316/download)
Erst dann fängt man mit Alexa-Fhem an.

# Die tgz-Datei im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. <br/>Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren.<br/> Bei der Fehlermeldung wie "Der Befehl "npm" ist entweder falsch geschrieben oder konnte nicht gefunden werden." ist die Installation von Node.js zu überprüfen.
# SSL Zertifikat erzeugen. Dafür muss man alle Befehle aus dem Skript ''createKey.sh'' nacheinander manuell ausführen. Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken. Der Windows-Welt unbekannter Befehl <code>mv</code> ist durch <code>move /y</code> zu ersetzen:<syntaxhighlight lang="bash" style="width:50%;">openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">openssl rsa -in key.pem -out newkey.pem</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">move /y newkey.pem key.pem</syntaxhighlight> Eventuelle Fehlermeldung "can't open config file: /usr/local/ssl/openssl.cnf" o.Ä. lässt sich durch Befehl <code>set OPENSSL_CONF=<OpenSSL-Verzeichnis>\bin\openssl.cfg</code> beheben, wobei <OpenSSL-Verzeichnis> durch den entsprechenden Installationspfad (typischerweise <code>c:\OpenSSL-Win32</code>) zu ersetzen ist.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Benutzerverzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' In aktuellen Versionen von Windows (ab Windows 7 bzw. ab Windows Server 2008 R2) liegt das Verzeichnis unter <code>C:\Users\<Benutzername></code>, also z.B. für Benutzer "Administrator" - unter <code>C:\Users\Administrator</code>.<br/>Falls Windows sich weigert das Verzichniss mit dem Punkt am Anfang zu erstellen, kann man das aus der Kommandozeile machen:<syntaxhighlight lang="bash" style="width:50%;">cd "C:\Users\<Benutzername>"</syntaxhighlight><syntaxhighlight lang="bash" style="width:50%;">
mkdir ".alexa"</syntaxhighlight>
# Die Datei ''config-sample.json'' nach ''C:\Users\<Benutzername>\.alexa\config.json'' kopieren.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis (<code>"<FHEM-Hauptverzeichis>\alexa-fhem\bin</code>) kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
===== Linux =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.
===== Windows =====
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (z.B. <code>С:\Program Files (x86)\fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version im Hauptverzeichnis von FHEM entpacken.
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen
# Windows-Shell (Kommandozeile, Eingabeaufforderung usw.) öffnen. "Start" -> "Ausführen" (oder [Windows-Taste]+[R]) -> cmd -> Ok. Durch <syntaxhighlight lang="bash" style="width:50%;">cd "<FHEM-Hauptverzeichis>\alexa-fhem"</syntaxhighlight> in das Verzeichnis wechseln. <br/>Dabei ist natürlich das <FHEM-Hauptverzeichis> durch den entsprechenden Pfad aus dem Schritt 1 zu ersetzen. Im o.g. Beispiel wäre es <code>cd "С:\Program Files (x86)\fhem\alexa-fhem"</code>
# Mit <syntaxhighlight lang="bash" style="width:50%;">npm install</syntaxhighlight> alle Abhängigkeiten installieren.
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.

==== Alexa-Fhem konfigurieren ====
Der Inhalt der Datei ''~/.alexa/config.json'' muss an die eigene Umgebung angepasst werden.
# ''nat-pmp'' -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers,
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'',
# ''applicationId''
#:* Wenn man nur den SmartHome-Skill verwenden möchte, kann dieser Eintrag leer bleiben.
#:* Ansonsten ist er mit der SkillID des Alexa Custom Skills zu belegen, siehe Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
# ''server'' -> IP-Adresse des eigenen FHEM-Servers
# ''port'' -> Portnummer des eigenen FHEM-Servers
Beispiel:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <syntaxhighlight lang="bash" style="width:50%;">./bin/alexa</syntaxhighlight> den Dienst starten (kein sudo!)

Unter Windows startet man den Alexa-Dienst durch <syntaxhighlight lang="bash" style="width:50%;">node alexa</syntaxhighlight> aus der <code>alex-fhem/bin</code> (also erst z.B. durch <code>cd "<FHEM-Hauptverzeichis>\alexa-fhem\bin"</code> ins richtige Verzeichnis kommen)

Der Start des Alexa-Dienstes auf der Console ist immer dann zu empfehlen, wenn man auf die Ausgaben des Dienstes angewiesen ist und beispielsweise sehen möchte, welche Devices durch den Dienst bereitgestellt werden oder ob Fehler auftreten. Beendet man die Console-Session wird auch der Dienst wieder beendet. Insofern ist die vorgenannte Vorgehensweise nur für ein Debugging zu empfehlen und nicht im Regelbetrieb. Nachfolgend ist beschrieben, wie man den Alexa-Dienst aus FHEM heraus starten / stoppen und neu starten kann.

==== Alexa-Fhem aus FHEM heraus starten ====
Zunächst das Start-up-Skript aus diesem Post herunterladen {{Link2Forum|Topic=60244|Message=517271|LinkText=https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271}} und unter /etc/init.d/alexa speichern.

Das Script geht davon aus, das der alexa-fhem script unter /opt/fhem/alexa-fhem liegt, und die logfiles später unter /opt/fhem/log. Sollte das nicht der Fall sein, muss das Skript angepasst werden.

Nun folgende Kommandos ausführen:
<syntaxhighlight lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</syntaxhighlight>

In der Datei <code>/etc/sudoers</code> den User fhem für die Nutzung von sudo zulassen (<code>sudo nano /etc/sudoers</code>), z.B. durch Anfügen der nachfolgenden Zeile:
<code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<syntaxhighlight lang="bash" style="width:75%;">define FHEM.Alexa.Status dummy

define FHEM.Alexa dummy
attr FHEM.Alexa event-on-change-reading state
attr FHEM.Alexa webCmd status:start:stop:restart

define FHEM.Alexa.DOIF DOIF ([FHEM.Alexa] eq "start")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa start > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "stop")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa stop > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "restart")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa restart > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "status")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa status > /dev/null 2>&1 &")})</syntaxhighlight>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa
WorkingDirectory=/opt/fhem/alexa-fhem
ExecStart=/opt/fhem/alexa-fhem/bin/alexa -U /home/alexa/.alexa
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Den Pfad <code>/home/alexa/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo.

Im WorkingDirectory wird der alexa Dienst die Zertifikate suchen.

Achtung: Natürlich muss der Benutzer auch Zugriff sowohl auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis und das WorkingDirectory haben.

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== Alexa-Fhem testen ====
Node.Js stellt einen Web-Server am Port 3000 bereit, das oben erzeugte Zertifikat sichert diesen Zugang per SSL ab. Durch Aufruf der Adresse
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== Alexa Device anlegen ===
Das Modul 39_alexa.pm stellt innerhalb von FHEM verschiedene Attribute z.B. alexaName oder alexaRoom zur Verfügung. Manche dieser Attribute (wie z.b. alexaName) werden in beiden Skills verwendet, andere werden ausschließlich bei einer Nutzung des Alexa Custom Skill verwendet.

Die Einrichtung des Alexa Device geschieht durch die nachfolgende Definition:
<syntaxhighlight lang="bash" style="width:70%;">define MyAlexa alexa</syntaxhighlight>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== Security Profile anlegen ====
Die Erzeugung eines Sicherheitsprofils muss nur einmal erfolgen, es wird dann für alle weiteren Skills verwendet.
# Nach der Anmeldung Auswahl von ''APPS & SERVICES''<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles''<br />[[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus<br />[[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen<br />[[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken (https://developer.amazon.com/lwa/sp/overview.html).<br/>[[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up''<br/>[[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen<br/>[[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse'''<br/>[[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen<br/>[[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit''<br/>[[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
.<br/>[[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen ====={{Randnotiz|RNTyp=r|RNText=aktuell lässt sich nur noch das v3 api auswählen. eine test version hierfür gibt es im {{Link2Forum|Topic=81324|LinkText=Forum}}. bitte die hinweise dort lesen und beachten.}}
# Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# Auf der folgenden Seite eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Type'' -> ''SmartHome Skill API''
#:* ''Language'' -> ''German''
#:* ''Name'' -> beliebiger Name, z.B. "MySmartHome Basic")
#:* ''Payload Version'' -> ''v2 (other devices)'' <br/>[[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen<br />[[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# Auf der Seite ''Configuration'' Folgendes eingeben:
#:* ''Service Endpoint Type'' -> ''AWS Lambda'' ist vorausgewählt und kann nicht geändert werden.
#:* ''Geographical Region'' -> ''Europe'' auswählen und im Textfeld die ARN aus Abschnitt [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code><br /><br />
<br />[[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James"<br />[[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also:<br/><blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) in das Feld ''TYPE'' eingetragen werden, das nach dem Anklicken von ''Add Slot Type'' erscheint. In das darunter liegende größere Textfeld kommen die möglichen Werte für diesen Slot, so wie sie aus der FHEM-Ausgabe abzulesen sind. Dann mit ''Save'' sichern. Als Custom Slot Type erscheint dann für diesen Beispiel-Slot
FHEM_article der | die | das | den
d.h., die Zeilenumbrüche bei den möglichen Werten werden als "|" dargestellt.</li>
<li>Hier muss nun ein Bruch im Arbeitsfluss durchgeführt werden, denn bei der Erstellung des Custom Skills kommt es auf die Reihenfolge der Einträge an. Deshalb zunächst diese FHEM-Ausgabe schließen, und für dasselbe FHEM-Device <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren<br />[[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
Beim Sichern dieser Seite mit ''Next'' kann es zu einer Fehlermeldung kommen, wenn man seine Skill-Definitionen mit dem einfachen SmartHome-Skill begonnen hat. Deshalb muss noch der entsprechende Trigger für die [[#AWS_Lambda-Funktion | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
<br />[[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== Testen ====
Hat man den Custom Skill angelegt, bietet dieser auch eine komfortable Testmöglichkeit. Dazu wählt man in der Übersichtsseite ''All Skills'' den Button ''Edit'' des Alexa Custom Skill aus. Auf der nachfolgenden Seite dann links ''Test''.
Die Testseite enthält
* ein Feld ''Voice Simulator'', mit dem man die Sprachsausgabe testen kann,
* ein Feld ''Service Simulator'', mit dem die Verarbeitung von Alexa-Kommandois getestet werden kann. Hier kann man z.B. eintragen
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Siebenundzwanzig Uhr"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken<br />[[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code><br />[[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen<br />[[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen<br />[[Datei:Aws.amazon.com-03-lambda.png|200px]]

==== AWS Lambda Funktion anlegen ===={{Randnotiz|RNTyp=r|RNText=Die AWS Seiten sehen inzwischen etwas anders aus. Eine angepasste Beschreibung findet sich im {{Link2Forum|Topic=81790|Message=739211|LinkText=Forum}}. Bitte auch die Hinweise dort lesen.}}
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen<br />[[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen<br />[[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen<br />[[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## Achtung, es ist möglich, dass dabei ''Alexa Smart Home'' überhaupt nicht angeboten wird. Dann bitte ganz rechts oben in der Ecke nachsehen, welche Region bzw. welches Land ausgewählt ist. Empfohlen wird, ''Ireland'' auszuwählen. Dann erscheint bei den Funktionen auch ''Alexa Smart Home''.
# Bei ''Application Id'' den Wert eintragen, dessen Ermittlung im Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen <br />[[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 6.10 (oder 8.10).
## ''Role'' -> ''Choose an existing role''
### Achtung: wenn es noch keine existing role gibt, zuerst ''Create a custom role'' -> in dem Popup dann ''lambda_basic_execution'' auswählen und auf ''Allow'' klicken sowie bei ''Existing role'' dann ''x'' wählen.
# Auf der Code-Seite ist im großen Textfeld dann der Code aus der Datei ''lambda.js'' im Paket [[#Alexa-Fhem_installieren | Alexa-Fhem]] vollständig einzufügen. Dabei muss der vorhandene Code im Texteil komplett gelöscht, der Teil aus der ''lamda.js'' eingefügt und noch der Hostname im Quellcode an den eigenen Hostnamen angepasst werden.
# Anschließend alles mit ''Next'' bestätigen.<br />[[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken<br />[[Datei:Aws.amazon.com-08-review.png|200px]]

==== Trigger für Custom Skill hinzufügen ====
Editiert man eine Lambda-Funktion, werden auf der Seite ''Triggers'' diejenigen Dienste angezeigt, die diese Funktion aufrufen.
* Hier taucht der Trigger ''Alexa Smart Home'' zusammen mit der ''Application Id'' auf, der bei der Einrichtung des SmartHome-Skills eingetragen wurde.
* Zur Verbindung mit dem Custom Skill ist es nötig, einen zweiten Trigger hinzuzufügen. Durch Anklicken von ''Add Trigger'' wird eine Auswahlseite eingeblendet. Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Skills Kit' auswählen und mit ''Next'' bestätigen

==== ARN der AWS Lambda Funktion bestimmen ====
# Auf der Übersichtsseite oben links den Menüpunkt ''Functions'' aúswählen<br />[[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen<br />[[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird<br />[[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben").

==== Absicherung direkt in Alexa-FHEM ====
Die Kommunikation zwischen Amazon AWS und Alexa-FHEM ist auf die folgenden Arten gesichert:
* Die Verbindung erfolgt per HTTPS
* Es werden nur Verbindung angenommen auf denen ein gültiges Alexa-Event gesendet wird.
* Es werden nur Verbindungen angenommen die ein gültiges und noch nicht abgelaufenes OAuth-Token enthalten. Jedes neue Token wird live bei Amazon auf Gültigkeit geprüft.
* Es werden nur Verbindungen mit lokal konfigurierter Skill-ID angenommen.
* Es ist nicht möglich von außen beliebige FHEM Kommandos zu senden. Die FHEM Kommandos werden nur lokal erzeugt.

Wer möchte kann Alexa-FHEM natürlich noch weiter absichern. Es gilt aber, dass nicht jedes zusätzliche Glied in der Kette die Sicherheit sondern unter Umständen nur die Angriffsfläche erhöht. Ein falsch konfigurierter und nach aussen offener Apache (oder anderer ReverseProxy) ist unter Umständen ein größeres Risiko als Alexa-FHEM alleine.

==== Absicherung per ReverseProxy ====
<s>Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt:</s> Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLProxyCheckPeerCN off
SSLProxyCheckPeerName off
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== Einrichtung in der Alexa App==
Nachdem die Alexa Skills angelegt wurden, müssen diese noch in der Alexa App eingerichtet werden.
Dafür jeweils per Desktop-Browser auf [http://alexa.amazon.de alexa.amazon.de] anmelden, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.

=== Alexa Skill ===
# Auf ''Skills'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen<br />[[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken<br />[[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken<br />[[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen<br />[[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein <br />[[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken<br />[[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# Wurde soweit alles korrekt eingerichtet, werden nun die gefundenen Geräte angezeigt.

Tip: Es macht Sinn, unter ''Meine Gruppen'' Gruppen benannt nach den Räumen einzurichten. Hierdurch kann Alexa die Geräte besser auseinander halten, vor allem wenn die den gleichen Alias (z.B. "Licht") haben.

== Einrichtung unter FHEM ==
Im Folgenden werden exemplarisch ein paar Geräte beschrieben, die man nutzbringend mit FHEM einsetzen kann.

Bei Verwendung des Custom Skills übersetzt die Kombination der Attribute ''alexaMapping'' und ''homebridgeMapping'' Sprachbefehle ("Intents") in gerätespezifische Kommandos.
* Das Attribut alexaMapping wird am Alexa-Device gesetzt und dient dazu, erkannte Sprachkommandos in abstrakte Characteristiken zu überführen. Für den einfacheren SmartHome Skill hat darum das Attribut ''alexaMapping'' keine Bedeutung, sondern nur der ''genericDeviceType'' des zu steuernden Gerätes.
* Das Attribut homebridgeMapping wird für beide Skills am zu steuernden Gerät gesetzt und übersetzt diese Charakteristiken in die konkreten Befehle, die das Gerät versteht. Der inhalt des Attributs wird von links nach rechts ausgewertet und ist wie folgt aufgebaut:
** Das Attribut enthält eine durch Leerzeichen getrennte Liste aus Konfigurationen für jeweils eine Characteristik
** Jede einzelne der Characteristik-Konfigurationen besteht aus dem Namen der Characteristik, gefolgt von "=" und einer kommaseparierten Liste von Parametern.
attr <device> homebridgeMapping <Characteristic1>=<param1.1>,<param1.2>,... <Characteristic2>=<param2.1>,<param2.2>,...
** Jeder Parameter besteht entweder aus
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> kann auch an Stelle einer ganzen Characteristik-Konfiguration stehen
Weiter führende Dokumentation zum homebridgeMapping findet sich unter https://forum.fhem.de/index.php/topic,48558.0.html

=== Einfacher Schalter ===
* Ein einfacher Schalter, der die set-Kommandos ''on'' und ''off'' kennt, kann direkt mit Alexa-Fhem gekoppelt werden
* Für kompliziertere Aktionen, etwa das Übermitteln eines spezifischen Schaltbefehls an FHEM, ist die Einrichtung eines Dummies zu empfehlen.
Ob Dummy oder nicht, wichtig sind die drei fett gedruckten Zeilen
define Alexa.Party dummy
'''attr Alexa.Party alexaName party'''
'''attr Alexa.Party alexaRoom alexaroom'''
'''attr Alexa.Party genericDeviceType switch'''
attr Alexa.Party group AlexaGeräte
attr Alexa.Party room AlexaRoom
attr Alexa.Party setList on off
Selbstverständlich kann man diesen Dummy mit einem notify oder DOIF abfangen, um die gewünschte Schaltaktion auszuführen.

Ein Alternative zum Dummy ist das Anlegen eines readingsProxy, dem die entsprechenden Attribute gegeben werden.

Weil es sich hierbei um eines der einfachen Geräte handelt, die Alexa selbst im SmartHome Skill bearbeiten kann, ist auch der zweite Schritt bei der Einrichtung in der Alexa App sinnvoll: Der Schalter wird dann im Bereich Smart Home der Alexa App erkannt. Wer ihn auch mit dem Custon Skill bedienen möchte, muss natürlich Sorge tragen, dass der Alexa-Name ''party'' bei den FHEM_Devices auftaucht und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sind (siehe Abschnitt [[##Custom_Skill_anlegen | Custom Skill Anlegen]]).

=== Wecker ===
Dieses Gerät kann man nur mit dem Custom Skill bedienen, es wird also '''nicht''' im Bereich Smart Home der Alexa App auftauchen. Wir richten einen Dummy ein, wichtig sind wieder die fett gedruckten Zeilen:
define Alexa.Weckzeit dummy
'''attr Alexa.Weckzeit alexaName weckzeit'''
'''attr Alexa.Weckzeit alexaRoom alexaroom'''
attr Alexa.Weckzeit genericDeviceType clock
attr Alexa.Weckzeit group AlexaGeräte
'''attr Alexa.Weckzeit homebridgeMapping Weckzeit=state,cmd=+'''
attr Alexa.Weckzeit room AlexaRoom
'''attr Alexa.Weckzeit setList Weckzeit:time'''
Das Attribut ''genericDeviceTye'' ist nicht wichtig, weil es ein generisches Device dieser Art gar nicht gibt. Wichtig hingegen ist das Attribut ''homebridgeMapping''

Für das Gerät ''MyAlexa'', das in Abschnitt definiert wurde, muss im Attribut ''alexaMapping'' auftauchen
Weckzeit=verb=stelle,valuePrefix=für;auf,values=AMAZON.TIME,valueSuffix=uhr
Darüber hinaus muss der Alexa-Name ''weckzeit'' bei den FHEM_Devices auftauchen und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sein (siehe Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

Zur weiteren Bearbeitung kann man jetzt mit einem DOIF Statusänderungen des Dummies abfangen und durch eine kleine Helperfunktion ins "echte" FHEM weiterleiten.
define Alexa.Weckzeit.N DOIF (["Alexa.Weckzeit:.*"])({AlexaHelper("Alexa.Weckzeit","$EVENT")})
Die Helperfunktion (z.B. in 99_myUtils.pm) stellt aus der übergebenen Zeit (immer im Format dd:mm) eine sprachkompatible Nachricht $nc und einen mit den FHEM-Zeitangaben kompatiblen String $nt zusammen und reicht beide an eine Routine ''changeWakeTime'' weiter (dokumentiert in den [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html Smart Home Hacks]).
sub AlexaHelper($$){
my ($name,$event)=@_;
if( $name eq "Alexa.Weckzeit" ){
my ($nc,$nt);
#-- volle Stunde----------------------------------------
if( $event =~ /(\d+):00/ ){
$nc=sprintf("%d Uhr",$1);
$nt=sprintf("%02d:00:00",$1);
#-- nicht volle Stunde---------------------------------
}elsif( $event =~ /(\d+):(\d+)/ ){
$nc=sprintf("%d Uhr %d",$1,$2);
$nt=sprintf("%02d:%02d:00",$1,$2);
}
changeWakeTime(\'GalaxyTab.EG\',\'$nc\',\'$nt\');
}
}

<hr>

=== Lichtszene ===
Eine Lichtszene wird mit dem Modul LightScene angelegt. Wir gehen davon aus, dass in der Lichtszene die beiden Szenen Alle_An und Alle_Aus, sowie mindestens eine weitere Szene (hier: Sitzgruppe) definiert wurde.
* Nachfolgend wird ein Beispiel beschrieben, wie man eine Lichtszene mit dem einfachen SmartHome Skill steuern kann. Die verwendeten Kommandos sind dann
<pre>
"Alexa, schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
"Alexa, schalte (die) Beleuchtungsitzgruppe an" -> LightScene Sitzgruppe wird ausgewählt
...
"Alexa, schalte (die) Beleuchtung aus" -> LightScene Alle_Aus wird ausgewählt
</pre>
* Künftig wird man LightScene mit dem Custom Skill eventuell direkt steuern können - allerdings hat das einen geringeren WAF, als die Steuerung über den SmartHome Skill: Der Einschaltsatz muss dann mindestens lauten
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

Im ersten Schritt wird ein Dummy für die Gesamtbeleuchtung eingerichtet:
define Alexa.Beleuchtung dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung alexaName beleuchtung'''
'''attr Alexa.Beleuchtung alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung genericDeviceType switch'''
Anschließend wird für jede vorhandene Lichtszene (außer Alle_An und Alle_Aus) ein weiterer Dummy angelegt:
define Alexa.Beleuchtung.Sitzgruppe dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung.Sitzgruppe alexaName beleuchtungsitzgruppe'''
'''attr Alexa.Beleuchtung.Sitzgruppe alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung.Sitzgruppe genericDeviceType switch'''
Die eigentliche Steuerung übernimmt dann ein DOIF
define Alexa.Beleuchtung.N DOIF
(["Alexa.Beleuchtung.Sitzgruppe:on"])
(set <devicename der Lichtszene> scene Sitzgruppe,
set Alexa.Beleuchtung off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSIF
... <weitere on-Events der anderen Szenen werden abgefangen>
DOELSEIF
(["Alexa.Beleuchtung:on"])
(set <devicename der Lichtszene> scene Alle_An,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSEIF
(["Alexa.Beleuchtung:off"])
(set <devicename der Lichtszene> scene Alle_Aus,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
Mit diesem DOIF wird ein Radiobutton simuliert, d.h. wie bei den Stationstasten vor Uralt-Radios sorgt die Auswahl einer Szene immer dafür, dass alle anderen Dummies ausgeschaltet werden.
Natürlich kann man das auch mit einem kleinen Perl-Programm erreichen.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

=== Harmony Hub ===
Ein [https://forum.fhem.de/index.php/topic,60244.msg550298.html#msg550298 HowTo-Beitrag im Forum] beschreibt die Ansteuerung von Harmony-Aktionen über den Custom Skill, beispielsweise für eine Aktion ''ARD'': „Alexa, sage FHEM stelle Anlage auf ARD“.

== Nutzung ==
Um den Namen zu bestimmen, unter dem ein Gerät mit Alexa angesprochen wird, verwendet Alexa-Fhem mit absteigender Priorität:
* das alexaName Attribut
* das alias Attribut
* das NAME Internal
Damit Alexa ein Gerät eindeutig identifizieren kann, sollten eindeutige Gerätenamen verwendet werden, bestehed möglichst aus einem Wort und ohne Ziffern. Wenn Alexa einen Namen nicht versteht, kann man unter [http://alexa.amazon.de/spa/index.html] nachsehen was tatsächlich verstanden wurde und den Gerätenamen ggf. anpassen.

=== SmartHome Skill ===
Gruppen (Räume) müssen in der Alexa App konfiguriert werden. Über das API lassen sich nur der Name und die Schalteigenschaften übergeben.

Nach erfolgreicher Einrichtung des SmartHome Skills sollte Alexa mit den folgenden Befehlen nutzbar sein:
<pre style="width:50%;">
“alexa, schalte <gerät/gruppe> ein”
“alexa, schalte <gerät/gruppe> aus”
“alexa, stelle <gerät/gruppe> auf <wert> prozent”
“alexa, stelle <gerät/gruppe> auf <anzahl> grad”
“alexa, erhöhe <gerät/gruppe> um <anzahl> prozent”
“alexa, reduziere <gerät/gruppe> um <anzahl> prozent”
“alexa, erhöhe <gerät/gruppe> um <anzahl> grad”
“alexa, reduziere <gerät/gruppe> um <anzahl> grad”
</pre>

=== Custom Skill ===
Der Custom Skill erlaubt im Gegensatz zum SmartHome Skill eine weitreichende Konfiguration der möglichen Kommandos. Die Dokumentation ist aktuell noch über diverse Artikel im Wiki verstreut:

*Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=hier}} beschrieben.
*Die erste Umsetzung ist {{Link2Forum|Topic=60244|Message=540117|LinkText=hier}} beschrieben.
*Mehr zu FHEM-Intents und deren Möglichkeiten gibt es {{Link2Forum|Topic=67490|Message=589378|LinkText=hier}}.
*Wie man die Alexa TTS-Engine bei den Antworten auf FHEM-Intents beeinflussen kann {{Link2Forum|Topic=77421|Message=693631|LinkText=hier}}.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions), alles hier sammeln.

== Troubleshooting ==

====Allgemeiner Hinweis====
Besonders wichtig ist, dass man sich sehr genau an diese Anleitung hält. Ein häufiger Fehler ist, dass die einfachen Anführungszeichen in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 8 einfach weggelassen werden. Diese sind zwingend notwendig. Es darf auch nur der reine Hostname eingetragen werden. Also kein ''http://'' davor. Entweder eine feste IP Adresse oder den Hostnamen, um den Rechner zu erreichen, den ihr über den Port 3000 freigegeben habt. Das sollte dann so aussehen:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=Derzeit müsst ihr über einen echten IPv4 Anschluss verfügen, damit der Amazon Lambda-Server euch erreichen kann. DS-Lite Anschlüsse wie die von <b>UnityMedia</b> z.B. funktionieren derzeit leider nicht. Eine möglicher "Workaround" wird hier beschrieben: https://forum.fhem.de/index.php/topic,60244.msg518276.html#msg518276}}

Auf dem Router muss der Port 3000 Protokoll TCP freigegeben werden. D.h. von außen muss man wenn man den Port 3000 aufruft, auf dem intern laufenden node.js Alexa-Dienst zugreifen können.
Je nach Router gestaltet sich das Portforwarding bzw. die Portumleitung etwas schwieriger.

Bei einem Speedport Router der Telekom beispielsweise, muss der Router komplett neu gestartet werden, wenn die Portfreigabe eingerichtet wurde.

Bei der Fritz!Box ist das nicht nötig, bei dieser finden die Freigabe unter ''Internet -> Freigaben -> Portfreigaben'' statt. Dort wählt man dann den Rechner aus und richtet eine neue Freigabe ein. Wichtig hierbei ist, dass man Portfreigabe auswählt und nicht MyFRITZ!-Freigabe. Bei Port von bis trägt man 3000 ein, bei Port extern ebenfalls.

Um die Portweiterleitung zu testen, solltet ihr euch auch nicht im gleichen Netz befinden. Viele Router blockieren den Netzaufruf aus dem gleichen Netz. Am besten testet ihr es, wenn ihr an eurem Mobiltelefon W-LAN deaktiviert und im Browser folgende Seite aufruft: ''https://mein.hostname:3000''. Wenn ihr im Browser dann einen Quellcode von Alexa seht, funktioniert die Portumleitung.

Wenn bis hier alles funktioniert und es läuft dennoch nicht rund, liegt das Problem woanders. Kommt z.B. bei der Gerätesuche kein Request rein (sichtbar auf dem Bildschirm, wenn bin/alexa gestartet wurden), kann evtl. der Lambda-Dienst falsch konfiguriert sein.

====Probleme mit node.js - npm install====

Falls eine Fehlermeldung auftritt, dass "npm" nicht gefunden werden kann, bitte NodeJS entsprechend der Anleitung im Homebridge-Artikel vorgehen: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|Python, g++, MDNS installieren]], siehe auch folgenden Abschnitt.

====Es kommen diverse Fehlermeldungen beim Starten von alexa-fhem und es beendet sich====
Wenn man auf der Konsole angemeldet ist, den Befehl<syntaxhighlight lang="bash" style="width:50%;">node -v</syntaxhighlight>eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter [[Homebridge_einrichten#NodeJS_installieren]] nachschauen. NodeJS V4 sollte hierbei schon ausreichen. Solange die node.js Version nicht passt, gar nicht groß rum experimentieren! Bitte beachtet, dass alle Voraussetzungen unter [[Alexa-Fhem#Voraussetzungen]] erfüllt sind! Keine Experimente mit Versionen die darunter liegen.

====Fehlermeldung ''NAT-PMP failed: Error: timeout'' Fehler angezeigt beim Start von alexa-fhem====
Wenn ihr dann alexa-fhem über die Konsole startet und bekommt folgenden Fehler: ''NAT-PMP failed: Error: timeout'', lasst euch davon nicht irritieren. Das bedeutet lediglich, dass der Port nicht automatich freigegeben wurde über uPNP. Alternativ prüft, ob die Funktion der Portfreigabe via uPNP auf eurem Router aktiviert ist.

====Nach Start auf der Console beendet sich Alexa-FHEM sofort wieder====
Unmittelbar nach dem Start von Alexa-FHEM werden ein paar UPNP Fehlermeldungen ausgegeben. Unmittelbar danach beendet sich Alexa-FHEM wieder.

Viele scheinen ein Problem mit UPNP auf dem Raspberry Pi zu haben. Wenn dieses Problem auftritt einfach in der <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

Jetzt erneut Alexa-FHEM starten. Sollte nun laufen.

====Was ist zu tun, wenn alexa-fhem keine Geräte findet?====
Zunächst müssen die Geräte, die angesprochen werden wollen, unter FHEM ein neues Attribut zugewiesen bekommen. Dazu das Gerät in FHEM öffnen und das Attribut ''genericDeviceType switch'' hinzufügen, wenn es ein Schalter mit der Funktiona AN/AUS sein soll. Wenn man will, kann man dem Gerät jetzt noch über das Attribut ''alias'' eine besseren Namen geben, mit dem Alexa das Gerät dann auch finden kann.
Anschließend muss alexa-fhem neu gestartet werden und die definierten Geräte sollten nun gefunden werden.

====Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können?====
Zuerst die Informationen zum Datenfluss ganz oben ansehen. Dann am besten von hinten nach vorne vorgehen:
* wenn nichts bei alexa-fhem ankommt: port forwarding prüfen
* wenn lambda.js nichts los wird: im cloudwatch log nachsehen
* wenn bei lambda.js nichts ankommt: den trigger prüfen

Zunächst sollte man sich unter ''http://aws.amazon.com'' das Logfile seiner erstellten Funktion anschauen. Ist überhaupt ein Logfile vorhanden? Falls nicht, liegt es vermutlich am Trigger.
Den solltet ihr überprüfen. Scheinbar kommt es hin und wieder vor, dass dieser nicht gesetzt ist. Dazu einfach auf ''Triggers'' klicken und mit ''Add trigger'' erneut einen anlegen. Hier muss, wie in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 7, die ''Application Id'' stehen und der Haken bei ''Enable trigger'' gesetzt sein. Dann alexa-fhem neu starten.
Wenn ihr Änderungen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt. Fürs Debugging empfiehlt es sich, alexa-fhem in einer Konsole laufen zu lassen, um eingehende Anfragen mitverfolgen zu können.

Es kann sein, dass immer noch keine Log im Cloudwatch ([http://docs.aws.amazon.com/de_de/lambda/latest/dg/monitoring-functions-logs.html]) zu sehen ist. In dem Fall hilft es, eine neue Role Policy anzulegen.
* in der AWS Console [https://console.aws.amazon.com] oben links auf Services klicken, und in der Gruppe "Security, Identity & Compliance" auf IAM klicken
* links auf Roles klicken
* Auf dem Knopf "Create Role" klicken
* AWS Services > Lambda auswählen, unten auf Next:Permissions klicken
* im Filter / Policy Type, "log" eintragen (ohne quotes)
* CloudWatchLogsFullAccess hacken, auf Next:Review unten klicken
* Name vergeben und mit "Create role" bestätigen
* Oben links auf Services klicken, und in der Gruppe "Compute", auf Lambda klicken
* auf den Name der Funktion klicken
* Reiter Configuration auswählen
* in Existing Role, den neukreierten Role auswählen
* oben auf Save (und Testen wenn gewünscht) klicken.
Schon sollte eine neue Gruppe im Cloudwatch sichtbar sein. Die Suche von den Devices in Alexa wiederholen, und die Logs analysieren

====Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?====
{{Randnotiz|RNTyp=[g|Info]|RNText=Der User in der User= Directive von alexa.service muss Ausführungsrecht auf dem alexa binary haben (x), so wie auch mind. Lesezugriff auf dem Verzeichnis nach -U Option in der ExecStart= Directive und auch auf dem WorkingDirectory }}
Schaut bitte in das Unterverzeichnis [alexa-fhem (also dort, wo Ihr Alexa-FHEM instelliert habt]/bin. Die dort befindliche Datei ''alexa'' muss ausführbar sein. Also z.B. so:
<syntaxhighlight lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</syntaxhighlight>
Sollte dies nicht der Fall sein bitte mit:
<syntaxhighlight lang="bash" style="width:70%;">chmod +x alexa</syntaxhighlight>
die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.

Eine lauffähige Konfiguration ist {{Link2Forum|Topic=71612|Message=668383|LinkText=hier}} zu sehen.

Ein Fehler in der Rechtekonfiguration führt in der Regel zu folgendem Ergebnis nach <code>sudo systemctl status alexa</code>:

<syntaxhighlight lang="bash"> Loaded: loaded (/etc/systemd/system/alexa.service; enabled)
Active: activating (auto-restart) (Result: exit-code) since mer. 2017-09-06 02:33:23 CEST; 3s ago
Process: 18332 ExecStart=/opt/fhem/alexa-fhem/bin/alexa -U /home/alexa/.alexa (code=exited, status=217/USER)
Main PID: 18332 (code=exited, status=217/USER)</syntaxhighlight>

====Wie kann ich via Alexa-FHEM auf FHEM zugreifen, wenn der Port mit Benutzername/Kennwort geschützt ist?====

Hierzu muss die Datei <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Withings

2018-03-02T23:32:48Z

Moontear:

==Übersicht==
Das Withings Modul kann mit Withings / Nokia Health Produkten umgehen. Das Modul (32_withings.pm) lässt sich direkt aus dem Forumpost beziehen: {{Link2Forum|Topic=64944|LinkText=Forumsthread}}

==Voraussetzungen==
* es müssen folgende PERL Module installiert sein: JSON, LWP::Simple and Digest::MD5

==Installation==
Withings Device definieren:
define <name> withings [ACCOUNT] <login> <password>
define <name> withings <device>

Falls ein Withings Device angelegt wird, werden automatisch alle Devices im Withings / Nokia Health Account in FHEM angelegt.
===Beispiel===
define withings withings abc@test.com myPassword

==Readings==
Folgende Readings bietet das Modul aktuell an:
height
weight
fatFreeMass
muscleRatio
fatMassWeight
fatRatio
boneMassWeight
boneRatio
hydration

diastolicBloodPressure
systolicBloodPressure
heartPulse
pulseWave
spo2

bodyTemperature
skinTemperature
temperature

dailySteps
dailyDistance
dailyElevation
dailyDescent
dailyDurationLight
dailyDurationModerate
dailyDurationIntense
dailyCaloriesActive
dailyCaloriesPassive

sleepDurationAwake
sleepDurationLight
sleepDurationDeep
sleepDurationREM
wakeupCount

co2
temperature
light
noise
voc
battery
batteryLevel

[[Kategorie:Waagen]]

Withings

2018-03-02T23:32:35Z

Moontear: Neuanlage des kurzes Wiki Artikels für den Withings Forum Post um diesen einfacher finden zu können

==Übersicht==
Das Withings Modul kann mit Withings / Nokia Health Produkten umgehen. Das Modul (32_withings.pm) lässt sich direkt aus dem Forumpost beziehen: {{Link2Forum|Topic=64944|LinkText=Forumsthread}}

==Voraussetzungen==
* es müssen folgende PERL Module installiert sein: JSON, LWP::Simple and Digest::MD5

==Installation==
Withings Device definieren:
define <name> withings [ACCOUNT] <login> <password>
define <name> withings <device>

Falls ein Withings Device angelegt wird, werden automatisch alle Devices im Withings / Nokia Health Account in FHEM angelegt.
===Beispiel:===
define withings withings abc@test.com myPassword

==Readings==
Folgende Readings bietet das Modul aktuell an:
height
weight
fatFreeMass
muscleRatio
fatMassWeight
fatRatio
boneMassWeight
boneRatio
hydration

diastolicBloodPressure
systolicBloodPressure
heartPulse
pulseWave
spo2

bodyTemperature
skinTemperature
temperature

dailySteps
dailyDistance
dailyElevation
dailyDescent
dailyDurationLight
dailyDurationModerate
dailyDurationIntense
dailyCaloriesActive
dailyCaloriesPassive

sleepDurationAwake
sleepDurationLight
sleepDurationDeep
sleepDurationREM
wakeupCount

co2
temperature
light
noise
voc
battery
batteryLevel

[[Kategorie:Waagen]]

Systemübersicht

2018-03-02T23:21:43Z

Moontear: /* Interfaces */

Ein FHEM '''System''' besteht im Prinzip aus den in der nachfolgenden '''Übersicht''' aufgeführten Bestandteilen.
[[Datei:Systemübersicht.png]]

<div style="float: right;">__TOC__</div>

== Server ==
Bei der Komponente '''Server''' muss unterschieden werden zwischen dem eigentlichen '''FHEM''' Hausautomations-Server (implementiert in der Perl-Datei fhem.pl) und der Hardware, auf der dieser Server ausgeführt wird.

Als Server '''Hardware''' sind (z. B.) möglich:
* Windows Rechner
* Linux Rechner
* OS X Rechner
* Router (z. B. [[AVM Fritz!Box|FritzBox]])
* Einplatinencomputer, wie [[:Kategorie:Raspberry Pi|Raspberry Pi]], [[BeagleBone Black]]
* DockStar, PogoPlug, etc.
* diverse NAS Systeme wie Buffalo Linkstation, Synology Diskstation

(Diese Aufstellung ist nur eine unvollständige Auswahl; Details zu unterstützten Server Systemen finden sich in der Kategorie [[:Kategorie:Server Hardware|Server Hardware]]).

== Perl ==
Auf dem Server muss Perl installiert sein. Zur erforderlichen Version gibt es widersprüchliche Aussagen, die vor allem daraus resultieren, dass verschiedene FHEM-Module von verschiedenen Entwicklern stammen und daher unterschiedliche Anforderungen stellen. Laut FHEM-Webseite wird mindestens Version 5.6 benötigt, faktisch setzen aber viele Module 5.10 oder sogar 5.12 voraus. Der Betrieb mit Grundfunktionen ist jedoch zumindest ab Version 5.8.8 mit Einschränkungen möglich.

== Konfiguration ==
Das Hausautomations-System wird definiert über die [[Konfiguration]], die im Regelfall aus der
* reinen Textdatei <code>fhem.cfg</code> (Standard nach der Erstinstallation) oder alternativ einer
* [[configdb|SQL-Datenbank]]
besteht.

Die Konfiguration enthält Definitionen für die Bestandteile (Geräte) und Funktionen des jeweiligen Hausautomations-Systems. Die verfügbaren Befehle und deren Syntax sind in der Befehlsreferenz ({{Link2CmdRef}}) aufgeführt und beschrieben. Zu einigen Hilfsmodulen gibt es [[:Kategorie:Hilfsmodul|detaillierte Beschreibungen]] mit Beispielen.

== Benutzeroberfläche ==
Der Zugriff auf FHEM erfolgt mittels Webbrowser oder App über die verfügbaren '''[[:Kategorie:FHEM Frontends|FHEM Benutzeroberflächen]]'''.

In den FHEM Server integriert ist ein Webserver ([[PGM2]]), der im Prinzip immer zur Verfügung steht. Abhängig vom benutzten Klienten ist PGM2 über
* <code>serverhostnameoderIP:8083/fhem</code> (Desktop-Darstellung = Port 8083),
* <code>serverhostnameoderIP:8084/fhem</code> (Smartphone-Darstellung = Port 8084) oder
* <code>serverhostnameoderIP:8085/fhem</code> (Tablet-Darstellung = Port 8085)
erreichbar.

Eine Auswahl der Benutzeroberflächen:
* PGM2 - das Standardinterface
* [[FLOORPLAN]]
* [[FHEM Tablet UI]]
* [[SmartVISU]]
* diverse Apps für iOS und Android (Auswahl unter: [[:Kategorie:FHEM Frontends|FHEM Benutzeroberflächen]])

Beispielhafte Screenshots diverser Benutzeroberflächen: http://fhem.de/fhem.html#Screenshots

== Module ==
Die Funktionalität von FHEM kann über '''Module''' erweitert werden. Module können die unterschiedlichsten Aufgaben übernehmen vom Anbinden eines Hardwaresystems
über die Bereitstellung eines Frontends bis zur Automatisierung von Aufgaben. Beispiele für Module:
* 00_CUL.pm - Implementierung der Unterstützung für den [[CUL]]
* 11_FHT.pm - Unterstützung der [[:Kategorie:FHT Components|FHT]] Heizungssteuerung
* 95_FLOORPLAN.pm - Grundriss (oder Ähnliches) als Benutzeroberfläche
* uvm.

Module können unterteilt werden in
* [[:Kategorie:FHEM Befehl|Befehlsmodule]] (FHEM-Befehle sind teilweise eigenständige Module)
* [[:Kategorie:Hilfsmodul|Hilfsmodule]]
* [[:Kategorie:Gerätemodul|Gerätemodule]]
Die offiziell in FHEM enthaltenen Module sind in der {{Link2CmdRef}} beschrieben. Sie werden über den [[Update]]-Befehl von FHEM verteilt und aktualisiert. Voraussetzung für die Aufnahme als offizielles Modul sind Supportwille durch den Entwickler und Dokumentation des Moduls.

Zusätzlich existiert eine Vielzahl von [[:Kategorie:Modul (Inoffiziell)|inoffiziellen Modulen]], die manuell in FHEM installiert werden können. Auch die Aktualisierung erfolgt nicht über den Update-Befehl, sondern muss durch den Nutzer selbst erfolgen. Inoffizielle Module sind an den verschiedensten Stellen zu finden:
* [[:Kategorie:Modul (Contrib)|Contrib]]-Verzeichnis im offiziellen FHEM-Sourcecode-SVN [http://svn.fhem.de/trac/browser/trunk/fhem/contrib]
* Beiträge im [https://forum.fhem.de/ FHEM-Forum]
* private Homepages

== Interfaces ==
Die Verbindung zu den angeschlossenen '''Geräten''' der Hausautomation wird im Allgemeinen - geräteabhängig - über [[Interface|Interfaces]] (manchmal auch als '''Gateway''' bezeichnet) hergestellt. Das kann z. B. im Falle von [[HomeMatic]] ein [[HMLAN Konfigurator]] sein, ein mittels LAN mit dem FHEM Server verbundenes Gerät, das die FHEM Steuerbefehle in das HomeMatic Funkprotokoll umsetzt - und auch die Funktelegramme der HomeMatic Komponenten an FHEM zurückgibt. Entsprechende Interfaces gibt es auch für andere Funkprotokolle und für die drahtgebundenen Systeme.

Eine (unvollständige) Liste solcher Interfaces (siehe auch [[:Kategorie:Interfaces|Kategorie Interfaces]]):
* [[CUL]] - je nach Einstellung für die Kommunikation mit [[:Kategorie:FS20 Components|FS20]], [[:Kategorie:FHT Components|FHT]] und andere [[SlowRF]] Protokolle, [[MAX|MAX!]] Heizungssteuerung oder [[:Kategorie:HomeMatic Components|HomeMatic]] und, mit Einschränkungen, InterTechno (nur senden)
* [[CUNO]], ähnlich CUL, jedoch nicht per USB sondern per IP angebunden (z.Zt. -Stand Januar 2014 - nicht für HomeMatic empfohlen)
* [[HMLAN Konfigurator|HomeMatic LAN Konfigurations-Adapter]] - HomeMatic
* [[MAX#MAXLAN|MAX! Cube LAN-Gateway]]
* Schnittstellen(karten) für [[:Kategorie:1-Wire|1-Wire]]
* TCM(120/310) zur Anbindung von [[:Kategorie:EnOcean Components|EnOcean]]
* [[Arduino]] mit Firmata über USB oder Netzwerk
* [[panStamp]] als Möglichkeit Arduinos mit diversen Sensor- und I/O- Boards per 868MHz Funk über das SWAP protokoll anzubinden
* [[JeeLink]], ein weiteres USB-Stick Interface (ebenfalls arduino basiert) für diverse 433MHz und 868MHz Komponenten
* [[RFXtrx]] für InterTechno, RSL, ELRO etc., Wetter-Sensoren (Oregon-Scientific, Cresta, La Crosse, TFA, UPM) und andere 433 Mhz Geräte.
* manche Komponenten ([[:Kategorie:IP Components|IP Komponenten]]) können über TCP/IP (LAN) direkt vom FHEM Server aus angesprochen werden; hier ist dann kein weiteres Interface im eigentlichen Sinne erforderlich. Dies gilt auch für diverse Module die Geräte über WEB Dienste des Herstellers anbinden (z. B. [[Withings]], [[netatmo]]).

== Protokolle ==
Der Kommunikation zwischen Interfaces und Geräten liegt jeweils ein bestimmtes Protokoll zugrunde. Unterstützte Protokolle mit ihren Eigenschaften sind in der folgenden Tabelle aufgelistet.

{| class="wikitable sortable"
|+ Übersicht über unterstützte Funkprotokolle
|-
! Name !! rfMode !! Frequenz !! Modulation !! Datenrate !! class="unsortable" | Interfaces !! class="unsortable" | Modul !! class="unsortable" | Geräte (Beispiel) !! class="unsortable" | Bemerkungen
|-
| [[FS20_Allgemein|FS20]] || SlowRF || 868,35MHz || AM || 1kHz || CU*, FHZ || {{Link2CmdRef|Anker=FS20|Label=FS20}} || - || -
|-
| FHT || SlowRF || 868,35MHz || AM || 1kHz || CU*, FHZ || {{Link2CmdRef|Anker=CUL_FHTTK|Label=FHTTK}}, {{Link2CmdRef|Anker=FHT|Label=FHT}} || Heizungsregelung || -
|-
| S300 || SlowRF || 868,35MHz || AM || 1kHz || CU*, FHZ || {{Link2CmdRef|Anker=CUL_WS|Label=CUL_WS}} || Temperatur-/Feuchtesensoren || -
|-
| HMS || SlowRF || 868,35MHz || AM || 1kHz || CU*O, FHZ || - || ?? || -
|-
| EM || SlowRF || 868,35MHz || AM || 1kHz || CU*, FHZ || {{Link2CmdRef|Anker=CUL_EM|Label=CUL_EM}} || Energiemonitore (Strom, Gas) || -
|-
| [[HomeMatic ]]|| HomeMatic || 868,3MHz || FM || 10kHz || CU*, [[HM-CFG-LAN_LAN_Konfigurations-Adapter|HMLan]], [[HM-CFG-USB_USB_Konfigurations-Adapter|HMUsb]] || {{Link2CmdRef|Anker=CUL_HM|Label=CUL_HM}} || [[:Kategorie:HomeMatic_Components|diverse]] || -
|-
| [[MAX|MAX!]] || MAX || 868,3MHz || FM || 20kHz || CU*, [[MAX#MAXLAN|MAXLAN]] || {{Link2CmdRef|Lang=de|Anker=MAX|Label=MAX}} || [[:Kategorie:MAX|Wandthermostat, Heizkörperthermostate, Fensterkontakt, Zwischenstecker]] || -
|-
| IT || - || 433MHz || AM? || 1kHz || CU*433, || - || - || -
|-
| Firmata WiFi || - || 2,4/5 GHz || || || || {{Link2CmdRef|Anker=FRM|Label=FRM}} || Arduino || -
|-
| SWAP || - || 868 (433/915) MHz || GFSK || 38.3835 Kbps || panStamp (+panStick) || {{Link2CmdRef|Anker=SWAP|Label=SWAP}} || RGB LED Driver, diverse Sensoren und Aktoren || -
|-
| [[:Kategorie:EnOcean Components|EnOcean]] || - || 315 / 868 / 902 / 928MHz || ASK || 125 kbit/s || {{Link2CmdRef|Anker=TCM|Label=TCM}} || {{Link2CmdRef|Anker=EnOcean|Label=EnOcean}} || Batterielose Funksensoren, diverse Aktoren || -
|-
| PCA || - || 868,35MHz || ?? || ?? || [[JeeLink]] || {{Link2CmdRef|Anker=PCA301|Label=PCA301}} || [[PCA301 Funkschaltsteckdose mit Energieverbrauchsmessung|PCA301]] || -
|-
| [[La Crosse]] || - || 868,35MHz || ?? || ?? || [[JeeLink]], LGW || {{Link2CmdRef|Anker=Lacrosse|Label=Lacrosse}} || LaCrosse IT+ (Technoline) Sensoren || -
|-
| ZigBee Light Link || - || 2,4 GHz || || || HUE Bridge (RaspBee) || {{Link2CmdRef|Anker=HUEBridge|Label=HUEBridge}} || Philips HUE und LightLink Lampen (auch Osram LIGHTIFY an der HUE-Bridge)|| [http://www.developers.meethue.com/documentation/how-hue-works]
|-
| [[MySensors]] || - || 2,4 GHz || || || MySensors Gateway || [[MYSENSORS]] || [http://www.mysensors.org/build/ Selbstbau-Sensoren] || -
|-
| [[:Kategorie:Z-Wave Components|Z-Wave]] || - || 868MHz || 2-FSK || 9.600 bit/s oder 40 Kbit/s || {{Link2CmdRef|Anker=ZWDongle|Label=ZWDongle}} || {{Link2CmdRef|Anker=ZWave|Label=ZWave}} || - || -
|-
| [[WMBUS]] || WMBus_T, WMBus_S || 868MHz || ?? || 100 kbit/s / 32.768 kbit/s || CU* || {{Link2CmdRef|Anker=WMBUS|Label=WMBUS}} || Wasseruhren, Wärmezähler, Elektrozähler || -
|-
| colspan="9" | ''Tabelle muss noch vervollständigt werden''
|-
| colspan="2" | '''Legende:'''
| colspan="7" | CU* = CUL, CUN, CUNO /
|}

{| class="wikitable sortable"
|+ Übersicht über drahtgebundene Systeme
|-
! Name !! class="unsortable" | Interfaces (Hardware) !! class="unsortable" | Modul !! class="unsortable" | Geräte (Beispiel) !! class="unsortable" | Bemerkungen
|-
| [[1-Wire]] || [[Interfaces für 1-Wire|diverse]] || {{Link2CmdRef|Anker=OWX|Label=OWX}} || [[:Kategorie:1-Wire|1-Wire]] || -
|-
| [[EIB_/_KNX|EIB/KNX]] || {{Link2CmdRef|Anker=TUL|Label=TUL}} || {{Link2CmdRef|Anker=EIB|Label=EIB}} || [[:Kategorie:EIB/KNX|EIB/KNX]] || -
|-
| Firmata || RS-232, USB, Ethernet || {{Link2CmdRef|Anker=FRM|Label=FRM}} || Arduino || -
|-
| [[HomeMatic Wired]] || [[HomeMatic Wired RS485 LAN Gateway|HM485 LAN Gateway]] || {{Link2CmdRef|Anker=HM485_LAN|Label=HM485_LAN}} || [[:Kategorie:HomeMatic Components|Präfix HMW]] || -
|-
| colspan="5" | ''Tabelle muss noch vervollständigt werden''
|-
| colspan="2" | '''Legende:'''
| colspan="3" | ...
|}

== Komponenten ==
Der eigentliche Zweck eines Hausautomatisierungs-Projekts sind dann letztendlich die '''Geräte''' (Komponenten / Aktoren / [[:Kategorie:Schalter (Empfänger)|Empfänger]]), die automatisch gesteuert werden sollen, bzw. auch Auslöser für Aktionen ([[:Kategorie:Schalter (Sender)|Sender]]) und Lieferant von Datenmaterial ([[:Kategorie:Hardware Typen|Sensoren]]) sind.

Diese Geräte sind, sofern es eine detaillierte Beschreibung dazu gibt, in den jeweiligen Unterseiten der [[:Kategorie:Hardware|Hardwareliste]] aufgeführt.

== Weblinks ==
* [http://www.enocean.com/de/home/ EnOcean] Homepage
* [http://www.elv.de ELV], (Haupt-)Lieferant von FS20, FHT, HomeMatic, MAX!
* [https://github.com/firmata/protocol Firmata] Protokoll
* [http://www.panstamp.com panStamp], panStamp Hersteller
* [http://jeelabs.com/products/jeelink Jeelabs], JeeLink Hersteller
* [http://www.zigbee.org/ Zigbee] Homepage

[[Kategorie:FHEM]]
[[Kategorie:FHEM-Verwendung]]

CUL

2017-03-18T18:22:19Z

Moontear: /* Hinweise zum Betrieb mit FHEM */

'''CUL''' ('''C'''C1101 '''U'''SB '''L'''ite) ist ein RF-Gerät im Formfaktor eines USB-Dongles mit externer [[CUL Ausstattung|Antenne]]. Die über das ISM/SRD Band empfangenen Daten werden durch einen Onboard 8 bit Atmel Prozessor vorverarbeitet. Mit verfügbarer quelloffener [[#FW|Firmware]] kann das CUL verschiedene 868MHz [[CUL HomeMatic und FS20|Protokolle]] empfangen und senden, insbesondere die FS20/FHT/S300/EM/HMS sowie durch kurzfristiges Umschaltung auf 433 MHz Intertechno (z. B. viele Baumarkt Funksteckdosen) Protokolle.

Im Umfeld von FS20/FHT/EM/S300/HMS ("[[Rfmode|rfmode]] - [[SlowRF]]") wird die Dekodierung der per AM in 1 kHz übertragenen Signale per [[#FW|culfw]] auf dem Atmel Prozessor direkt erledigt und dann per USB an den Hostrechner weitergegeben.

Das CUL kann mittels des CULModuls von FHEM angesprochen und somit wie eine FHZ1X00PC verwendet werden.

Das CUL kann auch im HM-Mode als HomeMatic Zentrale alternativ zur CCU oder dem [[HMLAN Konfigurator]] betrieben werden. Bei CULs älter als Version 3 ist jedoch der Speicher zu klein, um die Software für FS20/FHT/S300/EM/HMS und HomeMatic zugleich im Speicher zu halten, hier muss man sich beim [[CUL an einer Fritzbox 7390 flashen|Flashen]] der Firmware für eine Protokollfamilie entscheiden. Mit zwei CULs ist aber auch der Mischbetrieb an einem FHEM Hostrechner möglich.

Ebenso gibt es ein Modul zur Ansteuerung der [[MAX]]! Heizungsteuerung. Auch hier ist ein Mischbetrieb (MAX! und z. B. FS20 gleichzeitig über ein CUL) obwohl technisch nicht unmöglich {{Link2Forum|Topic=10510|LinkText=nicht angeraten}}.

Ferner ist der Einsatz eines CUL als [[RFR CUL]] für den ''SlowRF'' Mode (jedoch nicht für den ''HomeMatic'' Mode) möglich, um die Reichweite zu erhöhen. Die Verbindung erfolgt hierbei über Funk, sodass keine USB Verbindung zum FHEM Hostrechner erforderlich ist.

Alle diese Modi sind in der Original-[[#FW|culfw]] enthalten und werden z.B. durch die Wahl des ''rfmode'' eingestellt.

Obwohl die eigentliche Betriebsfrequenz der FHT und FS20-Komponenten 868,35 MHz ist, ist bei den aktuellen CUL Firmwareversionen zum Betrieb mit FHEM die Frequenz auf 868,30 MHz eingestellt. Dies hat sich als Kompromiss zum besseren Empfang von EM1000EM (Energiemonitor) Geräten bewährt, '''obwohl''' diese nominal mit 868,360 MHz arbeiten. Praktisch ist die Genauigkeit der Sendefrequenz der meisten ''SlowRF'' Geräte wegen der primitiven Sender sehr schlecht und kann deutlich von der nominalen Frequenz abweichen.

Frequenz und Bandbreite können daher im ''SlowRF'' Mode frei angepasst und somit für die örtlichen Empfangsgegebenheiten optimiert werden.

== Hinweise zum Betrieb mit FHEM ==
'''Anmerkung:''' Nachfolgende Beispiele sind so wie dargestellt in die FHEM-Eingabezeile oder per Telnet auf FHEM zu übertragen und per <Taste>Enter</Taste> abzuschicken (nicht "save" klicken); '''''myCUL''''' ist dabei nur ein Platzhalter und durch den Namen '''Ihres''' CUL zu ersetzen. Da diese Funktionen durch die culfw (Firmware) bereitgestellt werden, funktionieren sie auf allen Geräten, die die culfw verwenden ([[CUNO]], [[COC]], CSM:

* Ist Empfang eingeschaltet ?
*: <code> get myCUL raw C35</code> (13 = ja, z. b.: C35 = 0D / 13)
* Auslesen der culfw Version:
*: <code>get myCUL raw V</code>
* LED ausschalten (Achtung: Buchstabe l (L) vorweg für LED, keine Zahl 1)
*: <code>set myCUL raw l00</code>
* LED einschalten
*: <code>set myCUL raw l01</code> Blinkt bei Senden oder Empfangen von Paketen
* LED soll blinken (einmal in der Sekunde)
*: <code>set myCUL raw l02</code>
* Reboot / Reset des CUL:
*: <code>set myCUL raw B00. </code> Andere Werte als 00 starten das CUL im Bootloader-Modus (=> neue Firmware)
* Freie CUL Sendezeit ([[1% Regel]]):
*: <code>get myCUL raw X</code> 2. Wert ist Sendezeit in 10ms Slots, ein FS20 Befehl braucht ca. 210ms (also 21 Slots), eine FHT Kommunikation wesentlich mehr. Alternativ auch <code>get myCUL credit10ms</code> ergibt Sendezeit in 10ms Slots
* Freie Kapazität des FHT Buffers
*: <code> get myCUL raw T03</code> Ergebniss bytes in HEX. Leer = 4a
* Inhalt des FHT Buffers
*: <code> get myCUL raw T02</code> (CUL V2 Buffer ist 74 Bytes gross, Platz für 14 bis 31 FHT Messages). Rückgabe n/a = Buffer ist leer
* Eingestellte [[Was_ist_der_Hauscode%3F|FHT-ID]]
*: <code> get myCUL raw T01</code>
* Eingestellte Frequenz, Bandbreite etc. Ausgeben
*: <code> get myCUL ccconf</code>. <br>Rückgabe z. B.: <br><code><nowiki>myCUL ccconf => freq:868.300MHz bWidth:325kHz rAmpl:42dB sens:4dB</nowiki></code>
* eingestelle Bandbreite erhöhen (z.b. auf 464 kHz, mehr hat meist keinen Sinn):
*:<code>set myCUL bWidth 464</code>
* Einstellen der Sendestärke:
*: <code>set myCUL raw x09</code> Einstellen der Sendeleistung.

Gültige Werte für die Sendeleistung sind 00-09. Verwendet werden sollten nur die Werte 05-09, diese entsprechen
-10/-5/0/5/10 Sendeleistung in db. Default ist x08 = +5db. Bitte im Interesse von Nachbarn und der Abhörsicherheit den kleinsten problemlos funktionierenden Wert einstellen. Dies ist meistens x07 oder x08. Da speziell die Kommunikation mit den FHTs bidirektional ist, kann die Kommunikation durch höhere Werte oft nicht verbessert werden, da die FHTs selber dadurch nicht stärker senden. Besser versuchen, Lage und Antennenausrichtung des CUL zu verändern. Siehe auch Diskussion unter [https://groups.google.com/group/cul-fans/browse_thread/thread/683ca5c892eae1c3/c682a640f1ba863c?lnk=gst&q=bWidth+freq#c682a640f1ba863c GoogleGroups-CUL-Fans]

Werte x00-x04 sind '''mit''' Ramping und führen zum Verlust der Kommunikationsfähigkeit mit anderen CULs, z. B. [[RFR CUL]].

'''Hinweis:''' Beim CUL im HomeMatic-Modus kann man (ohne Firmware-Modifikation) die Empfangs-/Sendeparameter '''nicht''' verstellen. Die üblichen freq/x09 etc. haben hier keine Wirkung ({{Link2Forum|Topic=10203|Message=57191|LinkText=Quelle}}).

Weiterhin kann man zunehmend mehr Debuggingoutput auf dem CUL einschalten mit :
* <code> set CUL1 raw X61</code> Communication wird im Detail angezeigt
* <code>set CUL1 raw X25</code> auch checksum Fehler / unerkannte Protokolle werden gemeldet
* <code>set CUL1 raw X2F</code> alle empfangenen Flanken werden gemeldet
* <code>set CUL1 raw X80</code> RSSI / Signalstaerke jeder Flanke wird gemeldet
* <code>set CUL1 raw X21</code> normal Modus

Achtung: Auf Gross- und Kleinschreibung des "x,X" achten!

Die kompletten Kommandos mit Erklärung für CUL sind in der [http://culfw.de/commandref.html commandref] zu finden.

== Versionen ==
Das CUL gibt es in mehreren Versionen, die sich überwiegend in Prozessor und Speicherkonfiguration unterscheiden.

* CUL V1 - AT90USB162 Prozessor, 0,5Kb RAM, 16Kb Flashmemory, 0,5 kByte EEPROM. Einsatzfähigkeit unbekannt (aber vermutlich wie V2). Wird nicht mehr hergestellt.
* CUL V2 - AT90USB162 Prozessor, 0,5Kb RAM, 16Kb Flashmemory, 0,5 kByte EEPROM. Einsatzfähig. Der Flashspeicher ist jedoch zu klein für eine culfw (CUL Firmware), die Code für ''SlowRF'' Geräte und zugleich ''HomeMatic'' Geräte enthält. Es muss also vor dem Flashen der Firmware zwischen zwei jeweils reduzierten Versionen gewählt werden. Da ein CUL ohnehin nicht beide Sendemodi '''zeitgleich''' betreiben kann, ist dies keine wirkliche Einschränkung. Wird nicht mehr hergestellt.
* CUL V3 - ATMega32U4 Prozessor, 2,5 kB RAM, 32 kB Flashmemory, 1 kByte EEPROM). Voll einsatzfähig.
* CUL V4 - ATMega32U2 Prozessor, 1 kB RAM 32 kB Flashmemory, 1 kByte EEPROM. Voll einsatzfähig. Genau genommen ein "Sparmodell" des V3, um Lieferengpässe des atmega32u4 Prozessors zu umgehen. Der reduzierte RAM-Speicher verursacht (zumindest gegenwärtig) beim Betrieb mit culfw und FHEM keine Einschränkungen oder Nachteile. Achtung: Flashen des CULv4 setzt DFU-Programmer 0.5.4 oder höher voraus.

Die für die aktuellen Modelle lieferbare Abschirmung ist in der Regel nicht notwendig.

== Firmware {{Anker|FW}} ==
Die für den CUL und verwandte Hardware wie [[CUN]] und CUR im Zusammenhang mit FHEM überwiegend eingesetzte Firmware findet sich auf der
* [http://culfw.de CUL Firmware Homepage]
Dort kann die jeweils aktuelle Version nachgesehen und herunter geladen werden.
Alten Stände, Version für Entwickler und ganz aktuelle Änderungen findet man auf der
* [https://sourceforge.net/projects/culfw/ Sourceforge Projektseite der culfw]
Hier kann man sich z.B. mit
<source lang=bash>
svn co svn://svn.code.sf.net/p/culfw/code/trunk/culfw
</source>
die aktuelle Version laden.
Zusätzlich gibt es eine für InterTechno angepasste Version:
* [https://github.com/heliflieger/a-culfw Alternative culfw for cul devices] auf GitHub und im {{Link2Forum|Topic=35064|LinkText=Forum}}
Hier könnte es aber zu Funktionseinschränkungen bei anderen Protokollen kommen.
In dieser Version ist auch ein Portierung auf ARM-Prozessoren enthalten (siehe {{Link2Forum|Topic=38404|LinkText=Forum}}) mit der die CUL-Firmware auch auf dem HM-CFG-USB-2 und dem [[MAX]] Cube betrieben werden kann.

Generell ist das Angebot an Speicherplatz auf dem im CUL verwendeten ATMega32U2 sehr eingeschränkt, wodurch Erweiterungen ohne Abstriche an anderer Stelle kaum mehr möglich sind. Es wird also die optimale CUL-Firmware für alle Zwecke nie geben, so dass man die Auswahl am konkreten Bedarf klären muss. Wer die Firmware selbst compiliert kann gezielt Funktionen die nicht benötigt werden weg lassen und dafür ggf. Funktionen die sonst nicht eingefügt sind hinzufügen.

== Sendefrequenz ==
Das CUL gibt es in Ausführungen für 868 und 433 MHz.
Die Sende- und Empfangsfrequenz des CUL sind in weiten Bereichen einstellbar, im ''SlowRF'' Mode auch durch direkte Befehle aus FHEM (im ''HomeMatic'' Mode derzeit nicht unterstützt). Der wesentliche Unterschied der 868 und 433 MHz CULs ist ein auf die Frequenz richtig abgestimmter HF-Eingangskreis inklusive Antennenlänge.

Es ist es durchaus möglich, ein 868 MHz CUL auf 433 MHz einzustellen. Da dann aber die HF-Eingangskreis-Abstimmung und Antennenlänge nicht korrekt sind, ist Empfangs- und Sendeleistung suboptimal, die Reichweite sinkt. Dennoch wird diese Möglichkeit des freien Einstellens durch das FHEM Intertechnomodul genutzt, da Intertechnokomponenten mit 433 MHz arbeiten. Dazu wird beim Senden eines Intertechno-Befehls die Frequenz eines 868 MHz CULs kurz umgestellt.

== Antenne ==
Der CUL ist mit RP-SMA-Stecker für die Antenne aber auch mit angelöteter Drahtantenne lieferbar.
Funktional besteht kein Unterschied: auch die "richtige" Antenne ist (in diesem Fall) nur ein Draht, jedoch gummiummantelt und eventuell mit einem Knickgelenk und einem Schraubanschluss versehen, d.h. die Drahtantenne sieht nur unschön aus.

Wichtig ist nur die Länge. Diese muss vorteilhafterweise so groß sein wie ein Viertel der Wellenlänge der Frequenz ("Lambda/4"). Die sind bei 868 Mhz ca. 8,6 Zentimeter. Antennenlängen die länger oder kürzer sind verschlechtern in der Regel die Leistung. Daher ist eine z.B. 10 Zentimeter lange Antenne (obwohl länger) schlechter als 1/4 Lambda mit 8,6 Zentimeter.

Über besondere Antennenkonstruktionen (bitte nach Colinear, Jpole, Yagi suchen) oder Antennen die "Lambda/2" oder gar ("Lambda") lang sind (also ca. 17,2 bzw. 34,5 Zentimeter) kann ein höher Gewinn erreicht werden. Einher geht aber gleichzeitig eine stärkere Richtwirkung der Antenne. Je kürzer die Antenne, desto kugelförmiger die Abstrahlung. Bei längeren Antennen wird die Abstrahlung mehr und mehr zylinderähnlich, also mit horizontaler Richtwirkung (und in die Richtung ist das Signal dann stärker, daher der Antennen"gewinn").
Das hat auch Nachteile, speziell wenn man auch "nach oben" funken will. Speziell wenn man Antennen länger als eine λ/4 Antenne (8,6 Zentimeter) in einem mehretagigen Haus verwenden will, muss man diese daher in der Regel waagerecht/horizontal ausrichten, da alles was in Richtung der Spitze (und dem Fuss) der Antenne liegt schlecht Empfangen wird.

Daher: Je mehr Gewinn die Antenne aufweist, desto besser ist die Sende und Empfangsleistung, aber desto mehr Gedanken muss man sich um die Ausrichtung der Antenne machen, um alle Geräte zu empfangen / zu erreichen. "Mehr db" und speziell "länger" ist also nicht automatisch besser.

Zu beachten, ist auch, dass die Sendeleistung der Module gesetzlich geregelt ist und Spezialantennen mit höherem Gewinn ggf. nur an Empfängern erlaubt sind.

Falls man den CUL mit RP-SMA Stecker geordert hat, aber keine passend lange RP-SMA-Antenne verfügbar ist, kann (nur für erste Tests) auch eine abschraubbare Antenne für 802.11b/g WLAN-Geräte (2,4 GHz) benutzt werden, so diese anschlusstechnisch auf den RP-SMA-Stecker des CUL passt (dies funktioniert zumindest mit FS20- und EM-Geräten). Deren Länge ist wie oben diskutiert aber nicht optimal, besser ist auf jeden Fall eine speziell auf den Einsatzzweck (Frequenz) abgestimmte Antenne.

== Antennenlänge ==
Die genauen Antennenlängen sind praktisch schwer zu ermitteln, da auch Zuleitung auf dem CUL zugerechnet werden müssten und ggf Dämpfungen (also z.b. Durchführung der Antenne durch eine Gehäuse, oder gebogene Antennen) die Antennenlänge weiter beeinflussen. Gleichzeitig haben schon Abweichungen von wenigen Millimetern messbaren Einfluss. Die Antennenlänge ist daher immer nur eine Kompromiss.

Exact berechnet ohne Störeinflüsse wären folgende Antennelängen nutzbar:
868,35 Mhz (z.B. HM, FS20, FHT …)
1/4 Lambda = 8,63 Zentimeter
1/2 Lambda = 17,26 Zentimeter
1 Lambda = 34,52 Zentimeter (Bereits sehr hohe Richtwirkung)

433,92 Mhz (z.B. Intertechno …)
1/4 Lambda = 17,27 Zentimeter
1/2 Lambda = 34,54 Zentimeter

Folgende Antennenlängen bieten sich praktisch an, diese sind immer etwas kürzer als die optimale Länge, dies wird z.T. durch Leiterlänge im CUL kompensiert.:

8,6 Zentimeter als 1/4 Lambda für 868,35 Mhz
17,2 Zentimeter als 1/2 Lambda für 868,35 Mhz und zugleich 1/4 Lambda für 433,92 Mhz
34,5 Zentimeter als Lambda für 868,35 Mhz und zugleich 1/2 Lambda für 433,92 Mhz

== Bekannte Probleme ==
Im Gegensatz zu den original FHZ Zentralen ist das CUL recht flankensteil, d.h. die Sende- und Empfangsfrequenz wird genauer eingehalten als z. B. bei einer FHZ1x00PC. Dies kann im Zusammenhang mit den eher ungenauen Sendern z. B. der FHT Raumregler zu Empfangsproblemen führen. Es kann daher mitunter sinnvoll sein, die Sende- und Empfangsbandbreite des CUL etwas zu erhöhen. Dies senkt jedoch gleichzeitig die Empfindlichkeit.

Bei Empfangsproblemen von z. B. HEM-Sensoren oder dem S300TH kann man folgendes testen:

* Man kann die Frequenz des CUL auf genau 868,35 MHz einstellen. Standardmäßig ist hier aus Kompatibilitätsgründen 868,30 MHz eingestellt. Diese Einstellung wird fest im NVRAM gespeichert und braucht nur einmal vorgenommen zu werden.
*: <code>set CUL freq 868.350</code>
* Es ist möglich die "decision boundary" zu vergrößern, frei beschrieben: die "Entscheidungsgrenze" ob die empfangene Signalflanke digital "0" oder "1" darstellte ({{Link2Forum|Topic=8572|Message=44388|LinkText=siehe Diskussion hier}}). Möglich sind die Werte "4", "8" und "16". Default-Einstellung ist hier "4". Zur Steigerung der Empfangsqualität soll es hilfreich sein, hier "8" einzustellen. Mitunter bringt jedoch erst die Einstellung auf "16" signifikante Verbesserungen beim Empfang von S300TH-Sensoren.
*: <code>set CUL sens 8</code>
* Oft hilft auch, die Bandbreite auf z. B. 464 kHz aufzuweiten.
*: <code>set CUL bWidth 464</code>

== Selbstbau-/Bastelprojekte ==
Innerhalb der FHEM-Community werden mittlerweile diverse Bastelprojekte zum Selbstbau eines CUL betrieben. Eine Auswahl dieser Projekte:
* [[Selbstbau CUL]]
* [[FHEMduino]]
* [[SIGNALduino]]
* [[MapleCUN]] mit STM32 Mikrocontroller

== Links ==
* Hersteller / Bezugsquelle für CUL: [http://www.busware.de/tiki-index.php?page=CUL busware.de]
* Google groups [https://groups.google.com/group/cul-fans/ CUL fans], mittlerweile durch das Board {{Link2Forum|Area=cul-fans}} im [http://forum.fhem.de/index.php FHEM Forum] ergänzt/ersetzt

[[Kategorie:Interfaces]]
[[Kategorie:CUL]]

CUL

2017-03-18T18:22:04Z

Moontear: /* Hinweise zum Betrieb mit FHEM */

'''CUL''' ('''C'''C1101 '''U'''SB '''L'''ite) ist ein RF-Gerät im Formfaktor eines USB-Dongles mit externer [[CUL Ausstattung|Antenne]]. Die über das ISM/SRD Band empfangenen Daten werden durch einen Onboard 8 bit Atmel Prozessor vorverarbeitet. Mit verfügbarer quelloffener [[#FW|Firmware]] kann das CUL verschiedene 868MHz [[CUL HomeMatic und FS20|Protokolle]] empfangen und senden, insbesondere die FS20/FHT/S300/EM/HMS sowie durch kurzfristiges Umschaltung auf 433 MHz Intertechno (z. B. viele Baumarkt Funksteckdosen) Protokolle.

Im Umfeld von FS20/FHT/EM/S300/HMS ("[[Rfmode|rfmode]] - [[SlowRF]]") wird die Dekodierung der per AM in 1 kHz übertragenen Signale per [[#FW|culfw]] auf dem Atmel Prozessor direkt erledigt und dann per USB an den Hostrechner weitergegeben.

Das CUL kann mittels des CULModuls von FHEM angesprochen und somit wie eine FHZ1X00PC verwendet werden.

Das CUL kann auch im HM-Mode als HomeMatic Zentrale alternativ zur CCU oder dem [[HMLAN Konfigurator]] betrieben werden. Bei CULs älter als Version 3 ist jedoch der Speicher zu klein, um die Software für FS20/FHT/S300/EM/HMS und HomeMatic zugleich im Speicher zu halten, hier muss man sich beim [[CUL an einer Fritzbox 7390 flashen|Flashen]] der Firmware für eine Protokollfamilie entscheiden. Mit zwei CULs ist aber auch der Mischbetrieb an einem FHEM Hostrechner möglich.

Ebenso gibt es ein Modul zur Ansteuerung der [[MAX]]! Heizungsteuerung. Auch hier ist ein Mischbetrieb (MAX! und z. B. FS20 gleichzeitig über ein CUL) obwohl technisch nicht unmöglich {{Link2Forum|Topic=10510|LinkText=nicht angeraten}}.

Ferner ist der Einsatz eines CUL als [[RFR CUL]] für den ''SlowRF'' Mode (jedoch nicht für den ''HomeMatic'' Mode) möglich, um die Reichweite zu erhöhen. Die Verbindung erfolgt hierbei über Funk, sodass keine USB Verbindung zum FHEM Hostrechner erforderlich ist.

Alle diese Modi sind in der Original-[[#FW|culfw]] enthalten und werden z.B. durch die Wahl des ''rfmode'' eingestellt.

Obwohl die eigentliche Betriebsfrequenz der FHT und FS20-Komponenten 868,35 MHz ist, ist bei den aktuellen CUL Firmwareversionen zum Betrieb mit FHEM die Frequenz auf 868,30 MHz eingestellt. Dies hat sich als Kompromiss zum besseren Empfang von EM1000EM (Energiemonitor) Geräten bewährt, '''obwohl''' diese nominal mit 868,360 MHz arbeiten. Praktisch ist die Genauigkeit der Sendefrequenz der meisten ''SlowRF'' Geräte wegen der primitiven Sender sehr schlecht und kann deutlich von der nominalen Frequenz abweichen.

Frequenz und Bandbreite können daher im ''SlowRF'' Mode frei angepasst und somit für die örtlichen Empfangsgegebenheiten optimiert werden.

== Hinweise zum Betrieb mit FHEM ==
'''Anmerkung:''' Nachfolgende Beispiele sind so wie dargestellt in die FHEM-Eingabezeile oder per Telnet auf FHEM zu übertragen und per <Taste>Enter</Taste> abzuschicken (nicht "save" klicken); '''''myCUL''''' ist dabei nur ein Platzhalter und durch den Namen '''Ihres''' CUL zu ersetzen. Da diese Funktionen durch die culfw (Firmware) bereitgestellt werden, funktionieren sie auf allen Geräten, die die culfw verwenden ([[CUNO]], [[COC]], CSM:

* Ist Empfang eingeschaltet ?
*: <code> get myCUL raw C35</code> (13 = ja, z. b.: C35 = 0D / 13)
* Auslesen der culfw Version:
*: <code>get myCUL raw V</code>
* LED ausschalten (Achtung: Buchstabe l vorweg für LED, keine Zahl 1)
*: <code>set myCUL raw l00</code>
* LED einschalten
*: <code>set myCUL raw l01</code> Blinkt bei Senden oder Empfangen von Paketen
* LED soll blinken (einmal in der Sekunde)
*: <code>set myCUL raw l02</code>
* Reboot / Reset des CUL:
*: <code>set myCUL raw B00. </code> Andere Werte als 00 starten das CUL im Bootloader-Modus (=> neue Firmware)
* Freie CUL Sendezeit ([[1% Regel]]):
*: <code>get myCUL raw X</code> 2. Wert ist Sendezeit in 10ms Slots, ein FS20 Befehl braucht ca. 210ms (also 21 Slots), eine FHT Kommunikation wesentlich mehr. Alternativ auch <code>get myCUL credit10ms</code> ergibt Sendezeit in 10ms Slots
* Freie Kapazität des FHT Buffers
*: <code> get myCUL raw T03</code> Ergebniss bytes in HEX. Leer = 4a
* Inhalt des FHT Buffers
*: <code> get myCUL raw T02</code> (CUL V2 Buffer ist 74 Bytes gross, Platz für 14 bis 31 FHT Messages). Rückgabe n/a = Buffer ist leer
* Eingestellte [[Was_ist_der_Hauscode%3F|FHT-ID]]
*: <code> get myCUL raw T01</code>
* Eingestellte Frequenz, Bandbreite etc. Ausgeben
*: <code> get myCUL ccconf</code>. <br>Rückgabe z. B.: <br><code><nowiki>myCUL ccconf => freq:868.300MHz bWidth:325kHz rAmpl:42dB sens:4dB</nowiki></code>
* eingestelle Bandbreite erhöhen (z.b. auf 464 kHz, mehr hat meist keinen Sinn):
*:<code>set myCUL bWidth 464</code>
* Einstellen der Sendestärke:
*: <code>set myCUL raw x09</code> Einstellen der Sendeleistung.

Gültige Werte für die Sendeleistung sind 00-09. Verwendet werden sollten nur die Werte 05-09, diese entsprechen
-10/-5/0/5/10 Sendeleistung in db. Default ist x08 = +5db. Bitte im Interesse von Nachbarn und der Abhörsicherheit den kleinsten problemlos funktionierenden Wert einstellen. Dies ist meistens x07 oder x08. Da speziell die Kommunikation mit den FHTs bidirektional ist, kann die Kommunikation durch höhere Werte oft nicht verbessert werden, da die FHTs selber dadurch nicht stärker senden. Besser versuchen, Lage und Antennenausrichtung des CUL zu verändern. Siehe auch Diskussion unter [https://groups.google.com/group/cul-fans/browse_thread/thread/683ca5c892eae1c3/c682a640f1ba863c?lnk=gst&q=bWidth+freq#c682a640f1ba863c GoogleGroups-CUL-Fans]

Werte x00-x04 sind '''mit''' Ramping und führen zum Verlust der Kommunikationsfähigkeit mit anderen CULs, z. B. [[RFR CUL]].

'''Hinweis:''' Beim CUL im HomeMatic-Modus kann man (ohne Firmware-Modifikation) die Empfangs-/Sendeparameter '''nicht''' verstellen. Die üblichen freq/x09 etc. haben hier keine Wirkung ({{Link2Forum|Topic=10203|Message=57191|LinkText=Quelle}}).

Weiterhin kann man zunehmend mehr Debuggingoutput auf dem CUL einschalten mit :
* <code> set CUL1 raw X61</code> Communication wird im Detail angezeigt
* <code>set CUL1 raw X25</code> auch checksum Fehler / unerkannte Protokolle werden gemeldet
* <code>set CUL1 raw X2F</code> alle empfangenen Flanken werden gemeldet
* <code>set CUL1 raw X80</code> RSSI / Signalstaerke jeder Flanke wird gemeldet
* <code>set CUL1 raw X21</code> normal Modus

Achtung: Auf Gross- und Kleinschreibung des "x,X" achten!

Die kompletten Kommandos mit Erklärung für CUL sind in der [http://culfw.de/commandref.html commandref] zu finden.

== Versionen ==
Das CUL gibt es in mehreren Versionen, die sich überwiegend in Prozessor und Speicherkonfiguration unterscheiden.

* CUL V1 - AT90USB162 Prozessor, 0,5Kb RAM, 16Kb Flashmemory, 0,5 kByte EEPROM. Einsatzfähigkeit unbekannt (aber vermutlich wie V2). Wird nicht mehr hergestellt.
* CUL V2 - AT90USB162 Prozessor, 0,5Kb RAM, 16Kb Flashmemory, 0,5 kByte EEPROM. Einsatzfähig. Der Flashspeicher ist jedoch zu klein für eine culfw (CUL Firmware), die Code für ''SlowRF'' Geräte und zugleich ''HomeMatic'' Geräte enthält. Es muss also vor dem Flashen der Firmware zwischen zwei jeweils reduzierten Versionen gewählt werden. Da ein CUL ohnehin nicht beide Sendemodi '''zeitgleich''' betreiben kann, ist dies keine wirkliche Einschränkung. Wird nicht mehr hergestellt.
* CUL V3 - ATMega32U4 Prozessor, 2,5 kB RAM, 32 kB Flashmemory, 1 kByte EEPROM). Voll einsatzfähig.
* CUL V4 - ATMega32U2 Prozessor, 1 kB RAM 32 kB Flashmemory, 1 kByte EEPROM. Voll einsatzfähig. Genau genommen ein "Sparmodell" des V3, um Lieferengpässe des atmega32u4 Prozessors zu umgehen. Der reduzierte RAM-Speicher verursacht (zumindest gegenwärtig) beim Betrieb mit culfw und FHEM keine Einschränkungen oder Nachteile. Achtung: Flashen des CULv4 setzt DFU-Programmer 0.5.4 oder höher voraus.

Die für die aktuellen Modelle lieferbare Abschirmung ist in der Regel nicht notwendig.

== Firmware {{Anker|FW}} ==
Die für den CUL und verwandte Hardware wie [[CUN]] und CUR im Zusammenhang mit FHEM überwiegend eingesetzte Firmware findet sich auf der
* [http://culfw.de CUL Firmware Homepage]
Dort kann die jeweils aktuelle Version nachgesehen und herunter geladen werden.
Alten Stände, Version für Entwickler und ganz aktuelle Änderungen findet man auf der
* [https://sourceforge.net/projects/culfw/ Sourceforge Projektseite der culfw]
Hier kann man sich z.B. mit
<source lang=bash>
svn co svn://svn.code.sf.net/p/culfw/code/trunk/culfw
</source>
die aktuelle Version laden.
Zusätzlich gibt es eine für InterTechno angepasste Version:
* [https://github.com/heliflieger/a-culfw Alternative culfw for cul devices] auf GitHub und im {{Link2Forum|Topic=35064|LinkText=Forum}}
Hier könnte es aber zu Funktionseinschränkungen bei anderen Protokollen kommen.
In dieser Version ist auch ein Portierung auf ARM-Prozessoren enthalten (siehe {{Link2Forum|Topic=38404|LinkText=Forum}}) mit der die CUL-Firmware auch auf dem HM-CFG-USB-2 und dem [[MAX]] Cube betrieben werden kann.

Generell ist das Angebot an Speicherplatz auf dem im CUL verwendeten ATMega32U2 sehr eingeschränkt, wodurch Erweiterungen ohne Abstriche an anderer Stelle kaum mehr möglich sind. Es wird also die optimale CUL-Firmware für alle Zwecke nie geben, so dass man die Auswahl am konkreten Bedarf klären muss. Wer die Firmware selbst compiliert kann gezielt Funktionen die nicht benötigt werden weg lassen und dafür ggf. Funktionen die sonst nicht eingefügt sind hinzufügen.

== Sendefrequenz ==
Das CUL gibt es in Ausführungen für 868 und 433 MHz.
Die Sende- und Empfangsfrequenz des CUL sind in weiten Bereichen einstellbar, im ''SlowRF'' Mode auch durch direkte Befehle aus FHEM (im ''HomeMatic'' Mode derzeit nicht unterstützt). Der wesentliche Unterschied der 868 und 433 MHz CULs ist ein auf die Frequenz richtig abgestimmter HF-Eingangskreis inklusive Antennenlänge.

Es ist es durchaus möglich, ein 868 MHz CUL auf 433 MHz einzustellen. Da dann aber die HF-Eingangskreis-Abstimmung und Antennenlänge nicht korrekt sind, ist Empfangs- und Sendeleistung suboptimal, die Reichweite sinkt. Dennoch wird diese Möglichkeit des freien Einstellens durch das FHEM Intertechnomodul genutzt, da Intertechnokomponenten mit 433 MHz arbeiten. Dazu wird beim Senden eines Intertechno-Befehls die Frequenz eines 868 MHz CULs kurz umgestellt.

== Antenne ==
Der CUL ist mit RP-SMA-Stecker für die Antenne aber auch mit angelöteter Drahtantenne lieferbar.
Funktional besteht kein Unterschied: auch die "richtige" Antenne ist (in diesem Fall) nur ein Draht, jedoch gummiummantelt und eventuell mit einem Knickgelenk und einem Schraubanschluss versehen, d.h. die Drahtantenne sieht nur unschön aus.

Wichtig ist nur die Länge. Diese muss vorteilhafterweise so groß sein wie ein Viertel der Wellenlänge der Frequenz ("Lambda/4"). Die sind bei 868 Mhz ca. 8,6 Zentimeter. Antennenlängen die länger oder kürzer sind verschlechtern in der Regel die Leistung. Daher ist eine z.B. 10 Zentimeter lange Antenne (obwohl länger) schlechter als 1/4 Lambda mit 8,6 Zentimeter.

Über besondere Antennenkonstruktionen (bitte nach Colinear, Jpole, Yagi suchen) oder Antennen die "Lambda/2" oder gar ("Lambda") lang sind (also ca. 17,2 bzw. 34,5 Zentimeter) kann ein höher Gewinn erreicht werden. Einher geht aber gleichzeitig eine stärkere Richtwirkung der Antenne. Je kürzer die Antenne, desto kugelförmiger die Abstrahlung. Bei längeren Antennen wird die Abstrahlung mehr und mehr zylinderähnlich, also mit horizontaler Richtwirkung (und in die Richtung ist das Signal dann stärker, daher der Antennen"gewinn").
Das hat auch Nachteile, speziell wenn man auch "nach oben" funken will. Speziell wenn man Antennen länger als eine λ/4 Antenne (8,6 Zentimeter) in einem mehretagigen Haus verwenden will, muss man diese daher in der Regel waagerecht/horizontal ausrichten, da alles was in Richtung der Spitze (und dem Fuss) der Antenne liegt schlecht Empfangen wird.

Daher: Je mehr Gewinn die Antenne aufweist, desto besser ist die Sende und Empfangsleistung, aber desto mehr Gedanken muss man sich um die Ausrichtung der Antenne machen, um alle Geräte zu empfangen / zu erreichen. "Mehr db" und speziell "länger" ist also nicht automatisch besser.

Zu beachten, ist auch, dass die Sendeleistung der Module gesetzlich geregelt ist und Spezialantennen mit höherem Gewinn ggf. nur an Empfängern erlaubt sind.

Falls man den CUL mit RP-SMA Stecker geordert hat, aber keine passend lange RP-SMA-Antenne verfügbar ist, kann (nur für erste Tests) auch eine abschraubbare Antenne für 802.11b/g WLAN-Geräte (2,4 GHz) benutzt werden, so diese anschlusstechnisch auf den RP-SMA-Stecker des CUL passt (dies funktioniert zumindest mit FS20- und EM-Geräten). Deren Länge ist wie oben diskutiert aber nicht optimal, besser ist auf jeden Fall eine speziell auf den Einsatzzweck (Frequenz) abgestimmte Antenne.

== Antennenlänge ==
Die genauen Antennenlängen sind praktisch schwer zu ermitteln, da auch Zuleitung auf dem CUL zugerechnet werden müssten und ggf Dämpfungen (also z.b. Durchführung der Antenne durch eine Gehäuse, oder gebogene Antennen) die Antennenlänge weiter beeinflussen. Gleichzeitig haben schon Abweichungen von wenigen Millimetern messbaren Einfluss. Die Antennenlänge ist daher immer nur eine Kompromiss.

Exact berechnet ohne Störeinflüsse wären folgende Antennelängen nutzbar:
868,35 Mhz (z.B. HM, FS20, FHT …)
1/4 Lambda = 8,63 Zentimeter
1/2 Lambda = 17,26 Zentimeter
1 Lambda = 34,52 Zentimeter (Bereits sehr hohe Richtwirkung)

433,92 Mhz (z.B. Intertechno …)
1/4 Lambda = 17,27 Zentimeter
1/2 Lambda = 34,54 Zentimeter

Folgende Antennenlängen bieten sich praktisch an, diese sind immer etwas kürzer als die optimale Länge, dies wird z.T. durch Leiterlänge im CUL kompensiert.:

8,6 Zentimeter als 1/4 Lambda für 868,35 Mhz
17,2 Zentimeter als 1/2 Lambda für 868,35 Mhz und zugleich 1/4 Lambda für 433,92 Mhz
34,5 Zentimeter als Lambda für 868,35 Mhz und zugleich 1/2 Lambda für 433,92 Mhz

== Bekannte Probleme ==
Im Gegensatz zu den original FHZ Zentralen ist das CUL recht flankensteil, d.h. die Sende- und Empfangsfrequenz wird genauer eingehalten als z. B. bei einer FHZ1x00PC. Dies kann im Zusammenhang mit den eher ungenauen Sendern z. B. der FHT Raumregler zu Empfangsproblemen führen. Es kann daher mitunter sinnvoll sein, die Sende- und Empfangsbandbreite des CUL etwas zu erhöhen. Dies senkt jedoch gleichzeitig die Empfindlichkeit.

Bei Empfangsproblemen von z. B. HEM-Sensoren oder dem S300TH kann man folgendes testen:

* Man kann die Frequenz des CUL auf genau 868,35 MHz einstellen. Standardmäßig ist hier aus Kompatibilitätsgründen 868,30 MHz eingestellt. Diese Einstellung wird fest im NVRAM gespeichert und braucht nur einmal vorgenommen zu werden.
*: <code>set CUL freq 868.350</code>
* Es ist möglich die "decision boundary" zu vergrößern, frei beschrieben: die "Entscheidungsgrenze" ob die empfangene Signalflanke digital "0" oder "1" darstellte ({{Link2Forum|Topic=8572|Message=44388|LinkText=siehe Diskussion hier}}). Möglich sind die Werte "4", "8" und "16". Default-Einstellung ist hier "4". Zur Steigerung der Empfangsqualität soll es hilfreich sein, hier "8" einzustellen. Mitunter bringt jedoch erst die Einstellung auf "16" signifikante Verbesserungen beim Empfang von S300TH-Sensoren.
*: <code>set CUL sens 8</code>
* Oft hilft auch, die Bandbreite auf z. B. 464 kHz aufzuweiten.
*: <code>set CUL bWidth 464</code>

== Selbstbau-/Bastelprojekte ==
Innerhalb der FHEM-Community werden mittlerweile diverse Bastelprojekte zum Selbstbau eines CUL betrieben. Eine Auswahl dieser Projekte:
* [[Selbstbau CUL]]
* [[FHEMduino]]
* [[SIGNALduino]]
* [[MapleCUN]] mit STM32 Mikrocontroller

== Links ==
* Hersteller / Bezugsquelle für CUL: [http://www.busware.de/tiki-index.php?page=CUL busware.de]
* Google groups [https://groups.google.com/group/cul-fans/ CUL fans], mittlerweile durch das Board {{Link2Forum|Area=cul-fans}} im [http://forum.fhem.de/index.php FHEM Forum] ergänzt/ersetzt

[[Kategorie:Interfaces]]
[[Kategorie:CUL]]

Alexa-Fhem

2017-03-14T21:10:51Z

Moontear:

'''Alexa-Fhem''' ist eine in JavaScript geschriebene und auf NodeJS basierende Software, welche es ermöglicht, der digitalen Amazon Assistentin Alexa zusätzliche Skills für die Heimautomatisierung via FHEM beizubringen. Eine erste funktionierende Version wurde von [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im [https://forum.fhem.de/index.php/topic,60244.0.html Forum] veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==Einführung==
===Glossar===
*Echo bzw. Echo Dot (im Folgenden maskulin bezeichnet) sind die derzeit verfügbaren Geräte des Alexa-Systems '''BILDER EINSTELLEN - Achtung Urheberrecht'''
*AVS ist der Amazon Voice Service, d.h. die Spracherkennungskomponente des Systems.{{Randnotiz|RNTyp=r|RNText=Für die Nutzung der Amazon AWS-Dienste müssen zwingend die Daten einer Kreditkarte angegeben werden. Nach gegenwärtigem Kenntnisstand sollen jedoch keine Kosten für die Nutzung der im Rahmen dieses How To beschriebenen Dienste anfallen, sofern diese in einem Rahmen genutzt werden, der selbst eine intensive private Nutzung nicht überschreitet. Der Benutzer sei an dieser Stelle auf die von Amazon veröffentlichten Preislisten verwiesen. Die Autoren dieser Anleitung und der darin beschriebenen Module übernehmen keine Haftung für eventuelle Kosten, die aus der Nutzung der AWS entstehen. }}
*AWS sind die Amazon Web Services, also per URL erreichbare Dienste zur Ausführung von Berechnungen etc. Im Rahmen von Alexa-Fhem wird bei AWS eine eigene JavaScript-Funktion hinterlegt, die zur Kommunikation mit dem FHEM-Server dient. Im Jargon von Amazon ist dies eine so genannte Lambda-Funktion '''WARUM ? Nachlesen bei Amazon'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fähigkeit) ist die Bezeichnung für eine per Spracherkennung bediente Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, zur Wettervorhersage oder zur Steuerung von FHEM

===Arbeitsweise und Datenfluss===
[[Datei:2gpXyLN.jpg|200px|thumb|right|Grafische Darstellung der beteiligten Komponenten]]
Echo -> AVS -> AWS Lambda -> alexa-fhem -> AWS Lambda -> AVS -> Echo

*Der Echo (oder ein anderes Alexa/AVS fähiges Gerät) nimmt Audiodaten auf und schickt diese an AVS (Amazon Voice Service) zur Erkennung
*AVS führt die Spracherkennung durch und erzeugt ein Event mit Informationen zu den erkannten Daten
:*Beim Alexa SmartHome Skill sind die möglichen Sätze für die Spracherkennung relativ fest vorgegeben
:*Beim Alexa Custom Skill kommen die dazu nötigen Informationen aus dem ''Interaction Model'' der Alexa Skills Configuration
*Das Event wird an den unter ''Configuration'' in der Alexa Skills Configuration hinterlegten Endpoint geschickt
:*Beim Alexa SmartHome Skill ist das zwingend eine AWS Lambda Routine
:*Beim Alexa Custom Skill kann das im Prinzip auch ein eigener Web Service sein
*Das Event wird vom <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> nimmt diese Antwort entgegen und gibt sie an AVS zurück
*AVS sogt dafür das der Echo 'antwortet' und dass die Card in der Alexa App erscheint

===Anmerkungen===
*Ein Skill hat keinen Zugriff auf die Audiodaten
*Mit dem Skill API kann ein Skill zu zu keiner Zeit von sich aus aktiv werden und 'einfach' Daten an den Echo schicken oder ihn dazu bringen irgendetwas zu tun.
*Wenn man berücksichtigt welchen Weg die Daten insgesamt gehen, ist es erstaunlich, wie schnell die Reaktion auf einen gesprochenen Satz erfolgt.

=== Abgrenzung des '''Alexa Smart Home Skills''' und des '''Alexa Custom Skills''' ===

Der [[Alexa-Fhem#Smart_Home|Alexa Smart Home Skill]] ist ein Amazon-Alexa-Standard-Skill, der wesentliche Basisfunktionalitäten bereitstellt. Zu diesen gehört im Wesentlichen die Funktionalität, durch Alexa-FHEM bereitgestellte Devices im Alexa-Account des Benutzers anzulegen. Der Alexa Smart Home Skill reagiert auf gesprochene Interaktion in einem beschränkten Umfang. Beispielsweise genügt ein "Alexa, schalte die Wohnzimmerlampe an" um eine Interaktion zwischen Alexa Smart Home Skill und FHEM-Alexa auszulösen. Nach erfolgreicher Einrichtung wird dieser Skill in der Alexa-App bzw. im Web in der Rubrik "Smart Home" als Skill angezeigt.

Der [[Alexa-Fhem#Custom|Alexa Custom Skill]] ist kein Standard-Smart-Home-Skill, sondern ein individuell entwickelter Skill, so wie alle anderen Skills auch. Er wird daher auch nicht in der Alexa-App unter der Rubrik "Smart Home" angezeigt. Gesprochene Interaktion mit diesem Skill erfolgt dadurch, dass entweder der Skill explizit gestartet wird (z.B. "Alexa, starte [Name des Skills]") oder direkt angesprochen wird (z.B. "Alexa, frage [Name des Skills] wie ist der Status von [Device] "). Der Alexa Custom Skill befindet sich in Entwicklung und wird hinsichtlich seiner Funktionalitäten laufend weiterentwickelt. Die Einrichtung dieses Skills ist grundsätzlich optional, jedoch werden anspruchsvollere Steuerungsmöglichkeiten nur mit diesem realisiert werden können.

==Installation==
{{Randnotiz|RNTyp=[g|Info]|RNText=Da die einzelnen Schritte der Anleitung an verschiedenen Stellen unterbrochen und später fortgesetzt werden müssen, empfiehlt es sich, die Anleitung einmal vollständig gelesen zu haben. Während der Konfiguration sollten alle nachfolgenden Abschnitte parallel in gleichzeitig geöffneten Browserfenstern durchgeführt werden, die jeweils bis zum Abschluss geöffnet bleiben müssen. }}
Grundvoraussetzung für alle folgenden Schritte ist das Vorhandensein eines Amazon-Accounts. Es wird davon ausgegangen, dass die Konten für alle im Folgenden genutzten Amazon-Dienste eingerichtet wurden.

===node.js installieren===
Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<source lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</source>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:
<source lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</source>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils [https://forum.fhem.de/index.php/topic,60244.msg540117.html#msg540117 hier] zu finden.

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source>
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# SSL Zertifikat erzeugen durch Aufruf von <source lang="bash" style="width:50%;">./createKey.sh</source> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei wird ggf. bei einem manuellen Start von Alexa-Fhem nicht gefunden.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.

==== Alexa-Fhem konfigurieren ====
Der Inhalt der Datei ''~/.alexa/config.json'' muss an die eigene Umgebung angepasst werden.
# ''nat-pmp'' -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers,
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'',
# ''applicationId''
#:* Wenn man nur den SmartHome-Skill verwenden möchte, kann dieser Eintrag leer bleiben.
#:* Ansonsten ist er mit der SkillID des Alexa Custom Skills zu belegen, siehe Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
# ''server'' -> IP-Adresse des eigenen FHEM-Servers
# ''port'' -> Portnummer des eigenen FHEM-Servers
Beispiel:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> den Dienst starten (kein sudo!)

Der Start des Alexa-Dienstes auf der Console ist immer dann zu empfehlen, wenn man auf die Ausgaben des Dienstes angewiesen ist und beispielsweise sehen möchte, welche Devices durch den Dienst bereitgestellt werden oder ob Fehler auftreten. Beendet man die Console-Session wird auch der Dienst wieder beendet. Insofern ist die vorgenannte Vorgehensweise nur für ein Debugging zu empfehlen und nicht im Regelbetrieb. Nachfolgend ist beschrieben, wie man den Alexa-Dienst aus FHEM heraus starten / stoppen und neu starten kann.

==== Alexa-Fhem aus FHEM heraus starten ====
Zunächst das Start-up-Skript aus diesem Post herunterladen [https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271 https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271] und unter /etc/init.d/alexa speichern.

Das Script geht davon aus, das der alexa-fhem script unter /opt/fhem/alexa-fhem liegt, und die logfiles später unter /opt/fhem/log. Sollte das nicht der Fall sein, muss das Skript angepasst werden.

Nun folgende Kommandos ausführen:
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</source>

In der Datei <code>/etc/sudoers</code> den User fhem für die Nutzung von sudo zulassen (<code>sudo nano /etc/sudoers</code>), z.B. durch Anfügen der nachfolgenden Zeile:
<code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<source lang="bash" style="width:75%;">define FHEM.Alexa.Status dummy

define FHEM.Alexa dummy
attr FHEM.Alexa event-on-change-reading state
attr FHEM.Alexa webCmd status:start:stop:restart

define FHEM.Alexa.DOIF DOIF ([FHEM.Alexa] eq "start")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa start > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "stop")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa stop > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "restart")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa restart > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "status")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa status > /dev/null 2>&1 &")})</source>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst einen neuen Benutzer anlegen unter dem alexa-fhem laufen soll, falls man nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht der Benutzer keine Gruppen, aber man kann den Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa" unter <code>/etc/default</code> anlegen

# Defaults / Konfigurations Optionen für alexa-fhem
# Wo findet alexa-fhem die config.json Datei?
ALEXA_OPTS=-U /opt/fhem/.alexa

Den Pfad <code>/opt/fhem/.alexa</code> an die Systemgegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo. Achtung: Natürlich muss der Benutzer auch Zugriff auf das Verzeichnis mit der config als auch das alexa-fhem Verzeichnis haben.

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa #oder ein anderer Benutzer wie fhem
EnvironmentFile=/etc/default/alexa
# oder wo auch immer eure alexa-fhem liegt
ExecStart=/opt/fhem/alexa-fhem/bin/alexa $ALEXA_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== Alexa-Fhem testen ====
Node.Js stellt einen Web-Server am Port 3000 bereit, das oben erzeugte Zertifikat sichert diesen Zugang per SSL ab. Durch Aufruf der Adresse
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== Alexa Device anlegen ===

Das Modul 39_alexa.pm stellt innerhalb von FHEM verschiedene Attribute z.B. alexaName oder alexaRoom zur Verfügung. Manche dieser Attribute (wie z.b. alexaName) werden in beiden Skills verwendet, andere werden ausschließlich bei einer Nutzung des Alexa Custom Skill verwendet.

Die Einrichtung des Alexa Device geschieht durch die nachfolgende Definition:
<source lang="bash" style="width:70%;">define MyAlexa alexa</source>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== Security Profile anlegen ====
Die Erzeugung eines Sicherheitsprofils muss nur einmal erfolgen, es wird dann für alle weiteren Skills verwendet.
# Nach der Anmeldung Auswahl von ''APPS & SERVICES''<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles''<br />[[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus<br />[[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen<br />[[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken.<br/>[[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up''<br/>[[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen<br/>[[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse'''<br/>[[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen<br/>[[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit''<br/>[[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
.<br/>[[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# Auf der folgenden Seite eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Type'' -> ''SmartHome Skill API''
#:* ''Language'' -> ''German''
#:* ''Name'' -> beliebiger Name, z.B. "MySmartHome Basic") <br/>[[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen<br />[[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# Auf der Seite ''Configuration'' Folgendes eingeben:
#:* ''Service Endpoint Type'' -> ''AWS Lambda'' ist vorausgewählt und kann nicht geändert werden.
#:* ''Geographical Region'' -> ''Europe'' auswählen und im Textfeld die ARN aus Abschnitt [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code><br /><br />
<br />[[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James"<br />[[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also:<br/><blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) in das Feld ''TYPE'' eingetragen werden, das nach dem Anklicken von ''Add Slot Type'' erscheint. In das darunter liegende größere Textfeld kommen die möglichen Werte für diesen Slot, so wie sie aus der FHEM-Ausgabe abzulesen sind. Dann mit ''Save'' sichern. Als Custom Slot Type erscheint dann für diesen Beispiel-Slot
FHEM_article der | die | das | den
d.h., die Zeilenumbrüche bei den möglichen Werten werden als "|" dargestellt.</li>
<li>Hier muss nun ein Bruch im Arbeitsfluss durchgeführt werden, denn bei der Erstellung des Custom Skills kommt es auf die Reihenfolge der Einträge an. Deshalb zunächst diese FHEM-Ausgabe schließen, und für dasselbe FHEM-Device <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren<br />[[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
Beim Sichern dieser Seite mit ''Next'' kann es zu einer Fehlermeldung kommen, wenn man seine Skill-Definitionen mit dem einfachen SmartHome-Skill begonnen hat. Deshalb muss noch der entsprechende Trigger für die [[#AWS_Lambda-Funktion | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
<br />[[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== Testen ====
Hat man den Custom Skill angelegt, bietet dieser auch eine komfortable Testmöglichkeit. Dazu wählt man in der Übersichtsseite ''All Skills'' den Button ''Edit'' des Alexa Custom Skill aus. Auf der nachfolgenden Seite dann links ''Test''.
Die Testseite enthält
* ein Feld ''Voice Simulator'', mit dem man die Sprachsausgabe testen kann,
* ein Feld ''Service Simulator'', mit dem die Verarbeitung von Alexa-Kommandois getestet werden kann. Hier kann man z.B. eintragen
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Siebenundzwanzig Uhr"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken<br />[[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code><br />[[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen<br />[[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen<br />[[Datei:Aws.amazon.com-03-lambda.png|200px]]
==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen<br />[[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen<br />[[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen<br />[[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## Achtung, es ist möglich, dass dabei ''Alexa Smart Home'' überhaupt nicht angeboten wird. Dann bitte ganz rechts oben in der Ecke nachsehen, welche Region bzw. welches Land ausgewählt ist. Empfohlen wird, ''Ireland'' auszuwählen. Dann erscheint bei den Funktionen auch ''Alexa Smart Home''.
# Bei ''Application Id'' den Wert eintragen, dessen Ermittlung im Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen <br />[[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''Role'' -> ''Choose an existing role''
### Achtung: wenn es noch keine existing role gibt, zuerst ''Create a custom role'' -> in dem Popup dann ''lambda_basic_execution'' auswählen und auf ''Allow'' klicken sowie bei ''Existing role'' dann ''x'' wählen.
# Auf der Code-Seite wird bzw. im großen Textfeld ist dann der Code aus der Datei ''lambda.js'' im Paket [[#Alexa-Fhem_installieren | Alexa-Fhem]] vollständig einzufügen. Dabei muss noch der Hostname im Quellcode an den eigenen Hostnamen angepasst werden.
# Anschließend alles mit ''Next'' bestätigen.<br />[[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken<br />[[Datei:Aws.amazon.com-08-review.png|200px]]

==== Trigger für Custom Skill hinzufügen ====
Editiert man eine Lambda-Funktion, werden auf der Seite ''Triggers'' diejenigen Dienste angezeigt, die diese Funktion aufrufen.
* Hier taucht der Trigger ''Alexa Smart Home'' zusammen mit der ''Application Id'' auf, der bei der Einrichtung des SmartHome-Skills eingetragen wurde.
* Zur Verbindung mit dem Custom Skill ist es nötig, einen zweiten Trigger hinzuzufügen. Durch Anklicken von ''Add Trigger'' wird eine Auswahlseite eingeblendet. Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Skills Kit' auswählen und mit ''Next'' bestätigen

==== ARN der AWS Lambda Funktion bestimmen ====
# Auf der Übersichtsseite oben links den Menüpunkt ''Functions'' aúswählen<br />[[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen<br />[[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird<br />[[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben"). Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt: Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== Einrichtung in der Alexa App==
Nachdem die Alexa Skills angelegt wurden, müssen diese noch in der Alexa App eingerichtet werden.
Dafür jeweils per Desktop-Browser auf [http://alexa.amazon.de alexa.amazon.de] anmelden, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.

=== Alexa Skill ===
# Auf ''Skills'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen<br />[[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken<br />[[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken<br />[[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen<br />[[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein <br />[[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken<br />[[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# Wurde soweit alles korrekt eingerichtet, werden nun die gefundenen Geräte angezeigt.

Tip: Es macht Sinn, unter ''Meine Gruppen'' Gruppen benannt nach den Räumen einzurichten. Hierdurch kann Alexa die Geräte besser auseinander halten, vor allem wenn die den gleichen Alias (z.B. "Licht") haben.

== Einrichtung unter FHEM ==
Im Folgenden werden exemplarisch ein paar Geräte beschrieben, die man nutzbringend mit FHEM einsetzen kann.

Bei Verwendung des Custom Skills übersetzt die Kombination der Attribute ''alexaMapping'' und ''homebridgeMapping'' Sprachbefehle ("Intents") in gerätespezifische Kommandos.
* Das Attribut alexaMapping wird am Alexa-Device gesetzt und dient dazu, erkannte Sprachkommandos in abstrakte Characteristiken zu überführen. Für den einfacheren SmartHome Skill hat darum das Attribut ''alexaMapping'' keine Bedeutung, sondern nur der ''genericDeviceType'' des zu steuernden Gerätes.
* Das Attribut homebridgeMapping wird für beide Skills am zu steuernden Gerät gesetzt und übersetzt diese Charakteristiken in die konkreten Befehle, die das Gerät versteht. Der inhalt des Attributs wird von links nach rechts ausgewertet und ist wie folgt aufgebaut:
** Das Attribut enthält eine durch Leerzeichen getrennte Liste aus Konfigurationen für jeweils eine Characteristik
** Jede einzelne der Characteristik-Konfigurationen besteht aus dem Namen der Characteristik, gefolgt von "=" und einer kommaseparierten Liste von Parametern.
attr <device> homebridgeMapping <Characteristic1>=<param1.1>,<param1.2>,... <Characteristic2>=<param2.1>,<param2.2>,...
** Jeder Parameter besteht entweder aus
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> kann auch an Stelle einer ganzen Characteristik-Konfiguration stehen
Weiter führende Dokumentation zum homebridgeMapping findet sich unter https://forum.fhem.de/index.php/topic,48558.0.html

=== Einfacher Schalter ===
* Ein einfacher Schalter, der die set-Kommandos ''on'' und ''off'' kennt, kann direkt mit Alexa-Fhem gekoppelt werden
* Für kompliziertere Aktionen, etwa das Übermitteln eines spezifischen Schaltbefehls an FHEM, ist die Einrichtung eines Dummies zu empfehlen.
Ob Dummy oder nicht, wichtig sind die drei fett gedruckten Zeilen
define Alexa.Party dummy
'''attr Alexa.Party alexaName party'''
'''attr Alexa.Party alexaRoom alexaroom'''
'''attr Alexa.Party genericDeviceType switch'''
attr Alexa.Party group AlexaGeräte
attr Alexa.Party room AlexaRoom
'''attr Alexa.Party setList on off'''
Selbstverständlich kann man diesen Dummy mit einem notify oder DOIF abfangen, um die gewünschte Schaltaktion auszuführen.

Ein Alternative zum Dummy ist das Anlegen eines readingsProxy, dem die entsprechenden Attribute gegeben werden.

Weil es sich hierbei um eines der einfachen Geräte handelt, die Alexa selbst im SmartHome Skill bearbeiten kann, ist auch der zweite Schritt bei der Einrichtung in der Alexa App sinnvoll: Der Schalter wird dann im Bereich Smart Home der Alexa App erkannt. Wer ihn auch mit dem Custon Skill bedienen möchte, muss natürlich Sorge tragen, dass der Alexa-Name ''party'' bei den FHEM_Devices auftaucht und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sind (siehe Abschnitt [[##Custom_Skill_anlegen | Custom Skill Anlegen]]).

=== Wecker ===
Dieses Gerät kann man nur mit dem Custom Skill bedienen, es wird also '''nicht''' im Bereich Smart Home der Alexa App auftauchen. Wir richten einen Dummy ein, wichtig sind wieder die fett gedruckten Zeilen:
define Alexa.Weckzeit dummy
'''attr Alexa.Weckzeit alexaName weckzeit'''
'''attr Alexa.Weckzeit alexaRoom alexaroom'''
attr Alexa.Weckzeit genericDeviceType clock
attr Alexa.Weckzeit group AlexaGeräte
'''attr Alexa.Weckzeit homebridgeMapping Weckzeit=state,cmd=+'''
attr Alexa.Weckzeit room AlexaRoom
'''attr Alexa.Weckzeit setList Weckzeit:time'''
Das Attribut ''genericDeviceTye'' ist nicht wichtig, weil es ein generisches Device dieser Art gar nicht gibt. Wichtig hingegen ist das Attribut ''homebridgeMapping''

Für das Gerät ''MyAlexa'', das in Abschnitt definiert wurde, muss im Attribut ''alexaMapping'' auftauchen
Weckzeit=verb=stelle,valuePrefix=für;auf,values=AMAZON.TIME,valueSuffix=uhr
Darüber hinaus muss der Alexa-Name ''weckzeit'' bei den FHEM_Devices auftauchen und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sein (siehe Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

Zur weiteren Bearbeitung kann man jetzt mit einem DOIF Statusänderungen des Dummies abfangen und durch eine kleine Helperfunktion ins "echte" FHEM weiterleiten.
define Alexa.Weckzeit.N DOIF (["Alexa.Weckzeit:.*"])({AlexaHelper("Alexa.Weckzeit","$EVENT")})
Die Helperfunktion (z.B. in 99_myUtils.pm) stellt aus der übergebenen Zeit (immer im Format dd:mm) eine sprachkompatible Nachricht $nc und einen mit den FHEM-Zeitangaben kompatiblen String $nt zusammen und reicht beide an eine Routine ''changeWakeTime'' weiter (dokumentiert in den [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html Smart Home Hacks]).
sub AlexaHelper($$){
my ($name,$event)=@_;
if( $name eq "Alexa.Weckzeit" ){
my ($nc,$nt);
#-- volle Stunde----------------------------------------
if( $event =~ /(\d+):00/ ){
$nc=sprintf("%d Uhr",$1);
$nt=sprintf("%02d:00:00",$1);
#-- nicht volle Stunde---------------------------------
}elsif( $event =~ /(\d+):(\d+)/ ){
$nc=sprintf("%d Uhr %d",$1,$2);
$nt=sprintf("%02d:%02d:00",$1,$2);
}
changeWakeTime(\'GalaxyTab.EG\',\'$nc\',\'$nt\');
}
}

<hr>

=== Lichtszene ===
Eine Lichtszene wird mit dem Modul LightScene angelegt. Wir gehen davon aus, dass in der Lichtszene die beiden Szenen Alle_An und Alle_Aus, sowie mindestens eine weitere Szene (hier: Sitzgruppe) definiert wurde.
* Nachfolgend wird ein Beispiel beschrieben, wie man eine Lichtszene mit dem einfachen SmartHome Skill steuern kann. Die verwendeten Kommandos sind dann
<pre>
"Alexa, schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
"Alexa, schalte (die) Beleuchtungsitzgruppe an" -> LightScene Sitzgruppe wird ausgewählt
...
"Alexa, schalte (die) Beleuchtung aus" -> LightScene Alle_Aus wird ausgewählt
</pre>
* Künftig wird man LightScene mit dem Custom Skill eventuell direkt steuern können - allerdings hat das einen geringeren WAF, als die Steuerung über den SmartHome Skill: Der Einschaltsatz muss dann mindestens lauten
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

Im ersten Schritt wird ein Dummy für die Gesamtbeleuchtung eingerichtet:
define Alexa.Beleuchtung dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung alexaName beleuchtung'''
'''attr Alexa.Beleuchtung alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung genericDeviceType switch'''
Anschließend wird für jede vorhandene Lichtszene (außer Alle_An und Alle_Aus) ein weiterer Dummy angelegt:
define Alexa.Beleuchtung.Sitzgruppe dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung.Sitzgruppe alexaName beleuchtungsitzgruppe'''
'''attr Alexa.Beleuchtung.Sitzgruppe alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung.Sitzgruppe genericDeviceType switch'''
Die eigentliche Steuerung übernimmt dann ein DOIF
define Alexa.Beleuchtung.N DOIF
(["Alexa.Beleuchtung.Sitzgruppe:on"])
(set <devicename der Lichtszene> scene Sitzgruppe,
set Alexa.Beleuchtung off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSIF
... <weitere on-Events der anderen Szenen werden abgefangen>
DOELSEIF
(["Alexa.Beleuchtung:on"])
(set <devicename der Lichtszene> scene Alle_An,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSEIF
(["Alexa.Beleuchtung:off"])
(set <devicename der Lichtszene> scene Alle_Aus,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
Mit diesem DOIF wird ein Radiobutton simuliert, d.h. wie bei den Stationstasten vor Uralt-Radios sorgt die Auswahl einer Szene immer dafür, dass alle anderen Dummies ausgeschaltet werden.
Natürlich kann man das auch mit einem kleinen Perl-Programm erreichen.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

== Nutzung ==
Um den Namen zu bestimmen, unter dem ein Gerät mit Alexa angesprochen wird, verwendet Alexa-Fhem mit absteigender Priorität:
* das alexaName Attribut
* das alias Attribut
* das NAME Internal
Damit Alexa ein Gerät eindeutig identifizieren kann, sollten eindeutige Gerätenamen verwendet werden, bestehed möglichst aus einem Wort und ohne Ziffern. Wenn Alexa einen Namen nicht versteht, kann man unter [http://alexa.amazon.de/spa/index.html] nachsehen was tatsächlich verstanden wurde und den Gerätenamen ggf. anpassen.

=== SmartHome Skill ===
Gruppen (Räume) müssen in der Alexa App konfiguriert werden. Über das API lassen sich nur der Name und die Schalteigenschaften übergeben.

Nach erfolgreicher Einrichtung des SmartHome Skills sollte Alexa mit den folgenden Befehlen nutzbar sein:
<pre style="width:50%;">
“alexa, schalte <gerät/gruppe> ein”
“alexa, schalte <gerät/gruppe> aus”
“alexa, stelle <gerät/gruppe> auf <wert> prozent”
“alexa, stelle <gerät/gruppe> auf <anzahl> grad”
“alexa, erhöhe <gerät/gruppe> um <anzahl> prozent”
“alexa, reduziere <gerät/gruppe> um <anzahl> prozent”
“alexa, erhöhe <gerät/gruppe> um <anzahl> grad”
“alexa, reduziere <gerät/gruppe> um <anzahl> grad”
</pre>

=== Custom Skill ===
Der Custom Skill erlaubt im Gegensatz zum SmartHome Skill eine weitreichende Konfiguration der möglichen Kommandos.

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=im Forum}} beschrieben.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions)

== Troubleshooting ==

====Allgemeiner Hinweis====
Besonders wichtig ist, dass man sich sehr genau an diese Anleitung hält. Ein häufiger Fehler ist, dass die einfachen Anführungszeichen in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 8 einfach weggelassen werden. Diese sind zwingend notwendig. Es darf auch nur der reine Hostname eingetragen werden. Also kein ''http://'' davor. Entweder eine feste IP Adresse oder den Hostnamen, um den Rechner zu erreichen, den ihr über den Port 3000 freigegeben habt. Das sollte dann so aussehen:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=Derzeit müsst ihr über einen echten IPv4 Anschluss verfügen, damit der Amazon Lambda-Server euch erreichen kann. DS-Lite Anschlüsse wie die von <b>UnityMedia</b> z.B. funktionieren derzeit leider nicht. Eine möglicher "Workaround" wird hier beschrieben: https://forum.fhem.de/index.php/topic,60244.msg518276.html#msg518276}}

Auf dem Router muss der Port 3000 Protokoll TCP freigegeben werden. D.h. von außen muss man wenn man den Port 3000 aufruft, auf dem intern laufenden node.js Alexa-Dienst zugreifen können.
Je nach Router gestaltet sich das Portforwarding bzw. die Portumleitung etwas schwieriger.

Bei einem Speedport Router der Telekom beispielsweise, muss der Router komplett neu gestartet werden, wenn die Portfreigabe eingerichtet wurde.

Bei der Fritz!Box ist das nicht nötig, bei dieser finden die Freigabe unter ''Internet -> Freigaben -> Portfreigaben'' statt. Dort wählt man dann den Rechner aus und richtet eine neue Freigabe ein. Wichtig hierbei ist, dass man Portfreigabe auswählt und nicht MyFRITZ!-Freigabe. Bei Port von bis trägt man 3000 ein, bei Port extern ebenfalls.

Um die Portweiterleitung zu testen, solltet ihr euch auch nicht im gleichen Netz befinden. Viele Router blockieren den Netzaufruf aus dem gleichen Netz. Am besten testet ihr es, wenn ihr an eurem Mobiltelefon W-LAN deaktiviert und im Browser folgende Seite aufruft: ''https://mein.hostname:3000''. Wenn ihr im Browser dann einen Quellcode von Alexa seht, funktioniert die Portumleitung.

Wenn bis hier alles funktioniert und es läuft dennoch nicht rund, liegt das Problem woanders. Kommt z.B. bei der Gerätesuche kein Request rein (sichtbar auf dem Bildschirm, wenn bin/alexa gestartet wurden), kann evtl. der Lambda-Dienst falsch konfiguriert sein.

====Probleme mit node.js - npm install====

Falls eine Fehlermeldung auftritt, dass "npm" nicht gefunden werden kann, bitte NodeJS entsprechend der Anleitung im Homebridge-Artikel vorgehen: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|Python, g++, MDNS installieren]], siehe auch folgenden Abschnitt.

====Es kommen diverse Fehlermeldungen beim Starten von alexa-fhem und es beendet sich====
Wenn man auf der Konsole angemeldet ist, den Befehl<source lang="bash" style="width:50%;">node -v</source>eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter [[Homebridge_einrichten#NodeJS_installieren]] nachschauen. NodeJS V4 sollte hierbei schon ausreichen. Solange die node.js Version nicht passt, gar nicht groß rum experimentieren! Bitte beachtet, dass alle Voraussetzungen unter [[Alexa-Fhem#Voraussetzungen]] erfüllt sind! Keine Experimente mit Versionen die darunter liegen.

====Fehlermeldung ''NAT-PMP failed: Error: timeout'' Fehler angezeigt beim Start von alexa-fhem====
Wenn ihr dann alexa-fhem über die Konsole startet und bekommt folgenden Fehler: ''NAT-PMP failed: Error: timeout'', lasst euch davon nicht irritieren. Das bedeutet lediglich, dass der Port nicht automatich freigegeben wurde über uPNP. Alternativ prüft, ob die Funktion der Portfreigabe via uPNP auf eurem Router aktiviert ist.

====Nach Start auf der Console beendet sich Alexa-FHEM sofort wieder====
Unmittelbar nach dem Start von Alexa-FHEM werden ein paar UPNP Fehlermeldungen ausgegeben. Unmittelbar danach beendet sich Alexa-FHEM wieder.

Viele scheinen ein Problem mit UPNP auf dem Raspberry Pi zu haben. Wenn dieses Problem auftritt einfach in der <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

Jetzt erneut Alexa-FHEM starten. Sollte nun laufen.

====Was ist zu tun, wenn alexa-fhem keine Geräte findet?====
Zunächst müssen die Geräte, die angesprochen werden wollen, unter FHEM ein neues Attribut zugewiesen bekommen. Dazu das Gerät in FHEM öffnen und das Attribut ''genericDeviceType switch'' hinzufügen, wenn es ein Schalter mit der Funktiona AN/AUS sein soll. Wenn man will, kann man dem Gerät jetzt noch über das Attribut ''alias'' eine besseren Namen geben, mit dem Alexa das Gerät dann auch finden kann.
Anschließend muss alexa-fhem neu gestartet werden und die definierten Geräte sollten nun gefunden werden.

====Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können?====
Zuerst die Informationen zum Datenfluss ganz oben ansehen. Dann am besten von hinten nach vorne vorgehen:
* wenn nichts bei alexa-fhem ankommt: port forwarding prüfen
* wenn lambda.js nichts los wird: im cloudwatch log nachsehen
* wenn bei lambda.js nichts ankommt: den trigger prüfen

Zunächst sollte man sich unter ''http://aws.amazon.com'' das Logfile seiner erstellten Funktion anschauen. Ist überhaupt ein Logfile vorhanden? Falls nicht, liegt es vermutlich am Trigger.
Den solltet ihr überprüfen. Scheinbar kommt es hin und wieder vor, dass dieser nicht gesetzt ist. Dazu einfach auf ''Triggers'' klicken und mit ''Add trigger'' erneut einen anlegen. Hier muss, wie in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 7, die ''Application Id'' stehen und der Haken bei ''Enable trigger'' gesetzt sein. Dann alexa-fhem neu starten.
Wenn ihr Änderugen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt.

====Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?====
Schaut bitte in das Unterverzeichnis [alexa-fhem (also dort, wo Ihr Alexa-FHEM instelliert habt]/bin. Die dort befindliche Datei ''alexa'' muss ausführbar sein. Also z.B. so:
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source>
Sollte dies nicht der Fall sein bitte mit:
<source lang="bash" style="width:70%;">chmod +x alexa</source>
die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.

====Wie kann ich via Alexa-FHEM auf FHEM zugreifen, wenn der Port mit Benutzername/Kennwort geschützt ist?====

Hierzu muss die Datei <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

Alexa-Fhem

2017-03-14T14:37:37Z

Moontear: alexa-fhem über systemd als Service registrieren und starten

'''Alexa-Fhem''' ist eine in JavaScript geschriebene und auf NodeJS basierende Software, welche es ermöglicht, der digitalen Amazon Assistentin Alexa zusätzliche Skills für die Heimautomatisierung via FHEM beizubringen. Eine erste funktionierende Version wurde von [https://forum.fhem.de/index.php?action=profile;u=430 justme1968] im [https://forum.fhem.de/index.php/topic,60244.0.html Forum] veröffentlicht.
Das ist eine erste Version der Dokumentation zur Installation und Einrichtung, eine Erweiterung wird sicherlich in nächster Zeit noch folgen.
{{Infobox Modul
|ModPurpose=Anbindung von FHEM an Amazon Assistent Alexa
|ModType=x
|ModTechName=
|ModForumArea=Frontends/Sprachsteuerung
|ModOwner=justme1968
}}

==Einführung==
===Glossar===
*Echo bzw. Echo Dot (im Folgenden maskulin bezeichnet) sind die derzeit verfügbaren Geräte des Alexa-Systems '''BILDER EINSTELLEN - Achtung Urheberrecht'''
*AVS ist der Amazon Voice Service, d.h. die Spracherkennungskomponente des Systems.{{Randnotiz|RNTyp=r|RNText=Für die Nutzung der Amazon AWS-Dienste müssen zwingend die Daten einer Kreditkarte angegeben werden. Nach gegenwärtigem Kenntnisstand sollen jedoch keine Kosten für die Nutzung der im Rahmen dieses How To beschriebenen Dienste anfallen, sofern diese in einem Rahmen genutzt werden, der selbst eine intensive private Nutzung nicht überschreitet. Der Benutzer sei an dieser Stelle auf die von Amazon veröffentlichten Preislisten verwiesen. Die Autoren dieser Anleitung und der darin beschriebenen Module übernehmen keine Haftung für eventuelle Kosten, die aus der Nutzung der AWS entstehen. }}
*AWS sind die Amazon Web Services, also per URL erreichbare Dienste zur Ausführung von Berechnungen etc. Im Rahmen von Alexa-Fhem wird bei AWS eine eigene JavaScript-Funktion hinterlegt, die zur Kommunikation mit dem FHEM-Server dient. Im Jargon von Amazon ist dies eine so genannte Lambda-Funktion '''WARUM ? Nachlesen bei Amazon'''.
*Card bezeichnet einen Eintrag in der Alexa-App, der die erkannte Sprachnachricht sowie weiter gehenden Informationen über die Reaktion von Alexa enzthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fähigkeit) ist die Bezeichnung für eine per Spracherkennung bediente Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, zur Wettervorhersage oder zur Steuerung von FHEM

===Arbeitsweise und Datenfluss===
[[Datei:2gpXyLN.jpg|200px|thumb|right|Grafische Darstellung der beteiligten Komponenten]]
Echo -> AVS -> AWS Lambda -> alexa-fhem -> AWS Lambda -> AVS -> Echo

*Der Echo (oder ein anderes Alexa/AVS fähiges Gerät) nimmt Audiodaten auf und schickt diese an AVS (Amazon Voice Service) zur Erkennung
*AVS führt die Spracherkennung durch und erzeugt ein Event mit Informationen zu den erkannten Daten
:*Beim Alexa SmartHome Skill sind die möglichen Sätze für die Spracherkennung relativ fest vorgegeben
:*Beim Alexa Custom Skill kommen die dazu nötigen Informationen aus dem ''Interaction Model'' der Alexa Skills Configuration
*Das Event wird an den unter ''Configuration'' in der Alexa Skills Configuration hinterlegten Endpoint geschickt
:*Beim Alexa SmartHome Skill ist das zwingend eine AWS Lambda Routine
:*Beim Alexa Custom Skill kann das im Prinzip auch ein eigener Web Service sein
*Das Event wird vom <code>lambda.js</code> code an alexa-fhem weitergeleitet
*alexa-fhem steuert FHEM und sendet ein Antwort-Event zurück
*<code>lambda.js</code> nimmt diese Antwort entgegen und gibt sie an AVS zurück
*AVS sogt dafür das der Echo 'antwortet' und dass die Card in der Alexa App erscheint

===Anmerkungen===
*Ein Skill hat keinen Zugriff auf die Audiodaten
*Mit dem Skill API kann ein Skill zu zu keiner Zeit von sich aus aktiv werden und 'einfach' Daten an den Echo schicken oder ihn dazu bringen irgendetwas zu tun.
*Wenn man berücksichtigt welchen Weg die Daten insgesamt gehen, ist es erstaunlich, wie schnell die Reaktion auf einen gesprochenen Satz erfolgt.

=== Abgrenzung des '''Alexa Smart Home Skills''' und des '''Alexa Custom Skills''' ===

Der [[Alexa-Fhem#Smart_Home|Alexa Smart Home Skill]] ist ein Amazon-Alexa-Standard-Skill, der wesentliche Basisfunktionalitäten bereitstellt. Zu diesen gehört im Wesentlichen die Funktionalität, durch Alexa-FHEM bereitgestellte Devices im Alexa-Account des Benutzers anzulegen. Der Alexa Smart Home Skill reagiert auf gesprochene Interaktion in einem beschränkten Umfang. Beispielsweise genügt ein "Alexa, schalte die Wohnzimmerlampe an" um eine Interaktion zwischen Alexa Smart Home Skill und FHEM-Alexa auszulösen. Nach erfolgreicher Einrichtung wird dieser Skill in der Alexa-App bzw. im Web in der Rubrik "Smart Home" als Skill angezeigt.

Der [[Alexa-Fhem#Custom|Alexa Custom Skill]] ist kein Standard-Smart-Home-Skill, sondern ein individuell entwickelter Skill, so wie alle anderen Skills auch. Er wird daher auch nicht in der Alexa-App unter der Rubrik "Smart Home" angezeigt. Gesprochene Interaktion mit diesem Skill erfolgt dadurch, dass entweder der Skill explizit gestartet wird (z.B. "Alexa, starte [Name des Skills]") oder direkt angesprochen wird (z.B. "Alexa, frage [Name des Skills] wie ist der Status von [Device] "). Der Alexa Custom Skill befindet sich in Entwicklung und wird hinsichtlich seiner Funktionalitäten laufend weiterentwickelt. Die Einrichtung dieses Skills ist grundsätzlich optional, jedoch werden anspruchsvollere Steuerungsmöglichkeiten nur mit diesem realisiert werden können.

==Installation==
{{Randnotiz|RNTyp=[g|Info]|RNText=Da die einzelnen Schritte der Anleitung an verschiedenen Stellen unterbrochen und später fortgesetzt werden müssen, empfiehlt es sich, die Anleitung einmal vollständig gelesen zu haben. Während der Konfiguration sollten alle nachfolgenden Abschnitte parallel in gleichzeitig geöffneten Browserfenstern durchgeführt werden, die jeweils bis zum Abschluss geöffnet bleiben müssen. }}
Grundvoraussetzung für alle folgenden Schritte ist das Vorhandensein eines Amazon-Accounts. Es wird davon ausgegangen, dass die Konten für alle im Folgenden genutzten Amazon-Dienste eingerichtet wurden.

===node.js installieren===
Zunächst wird das Betriebssystem (in diesem Falle Debian oder Ubuntu) auf den aktuellen Stand gebracht:
<source lang="bash" style="width:50%;">
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential libssl-dev</source>

Nun muss NodeJS installiert werden. Leider ist die Version im Debian Repository deutlich zu alt, daher wird mit den folgenden Befehlen das Node Repository hinzugefügt und NodeJS (in der LTS Version) entsprechend installiert:
<source lang="bash" style="width:50%;">
curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -
sudo apt-get install -y nodejs
</source>

=== Alexa-Fhem installieren ===
'''Aus gegebenem Anlass: Dies ist weder eine Einführung in Linux, noch eine Anfängerdokumentation für FHEM.''' Also erst die Grundlagen lernen, und dann mit Alexa beginnen !

Die aktuelle Version ist jeweils [https://forum.fhem.de/index.php/topic,60244.msg540117.html#msg540117 hier] zu finden.

====Erstinstallation====
Hier wird die Erstinstallation von Alexa-Fhem beschrieben
# Die tgz-Datei unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen <source lang="bash" style="width:50%;">mv package alexa-fhem</source>
# Durch <source lang="bash" style="width:50%;">cd alexa-fhem</source> in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# SSL Zertifikat erzeugen durch Aufruf von <source lang="bash" style="width:50%;">./createKey.sh</source> (kein sudo!). Hierbei beachten, dass ein Kennwort vergeben werden muss, das mindestens aus 4 Zeichen besteht, dieses Kennwort bitte merken.
# Das Verzeichnis ''.alexa'' anlegen, ''und zwar im Home-Verzeichnis desjenigen Benutzers, unter dem Alexa-Fhem laufen soll.'' Insbesondere ist zu beachten, dass dieser Nutzer u.U. im Startskript explizit gesetzt wird. Mit dem untenstehenden Skript ist das ''nicht'' der User fhem, sondern der User ''pi''. Das Symbol ''~/'' verweist auf das Home-Verzeichnis des Benutzers, der gerade die Installation vornimmt.
# Die Datei ''config-sample.json'' nach ''.alexa/config.json'' kopieren. Achtung: Installiert man alexa-fhem als root-user, zeigt das Symbol ''~/'' auf ''/root'' - und die Konfigurationsdatei wird ggf. bei einem manuellen Start von Alexa-Fhem nicht gefunden.
# Achtung: Ggf. müssen auch die Dateien key.pem und cert.pem ins entsprechende Verzeichnis kopiert werden.

====Update====
Hier wir das Update auf eine neue Version von Alexa-Fhem beschrieben
# Das Verzeichnis ''alexa-fhem'' im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) umbenennen in ''alexa-fhem.old''.
# Die tgz-Datei der neuen Alexa-Fhem-Version unter Linux im Hauptverzeichnis von FHEM (typischerweise <code>/opt/fhem</code>) entpacken (''nicht'' unter Windows, das zerstört die Rechteeinstellungen).
# Das dabei entstandene Verzeichnis ''package'' in ''alexa-fhem'' umbenennen, in das Verzeichnis wechseln
# Mit <source lang="bash" style="width:50%;">npm install</source> alle Abhängigkeiten installieren (kein sudo!).
# Die Zertifikatsdateien key.pem und cert.pem aus dem alten Verzeichnis ''alexa-fhem.old'' ins neue Verzeichnis ''alexa-fhem'' kopieren.
Natürlich dann den Dienst neu starten, auch müssen selbstredend irgendwelche Modifikationen an der Datei server.js in der neuen Version nachgezogen werden. Wenn alles läuft, kann das alte Verzeichnis ''alexa-fhem.old'' gelöscht werden.

==== Alexa-Fhem konfigurieren ====
Der Inhalt der Datei ''~/.alexa/config.json'' muss an die eigene Umgebung angepasst werden.
# ''nat-pmp'' -> wenn nat-pmp verwendet werden soll: die ip des eigenen routers,
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'',
# ''applicationId''
#:* Wenn man nur den SmartHome-Skill verwenden möchte, kann dieser Eintrag leer bleiben.
#:* Ansonsten ist er mit der SkillID des Alexa Custom Skills zu belegen, siehe Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]]
# ''oauthClientID'' -> ''Client ID'' dem Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
# ''server'' -> IP-Adresse des eigenen FHEM-Servers
# ''port'' -> Portnummer des eigenen FHEM-Servers
Beispiel:
{
"alexa": {
"name": "Alexa TEST",
"keyFile": "./key.pem",
"certFile": "./cert.pem",
"applicationId": "amzn1.ask.skill.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"oauthClientID": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"connections": [
{
"name": "FHEM",
"server": "192.168.0.xxx.xxx",
"port": "8083",
"filter": "room=AlexaRoom"
}
]
}

Mehrere Custom Skills lassen sich mit der folgenden Syntax eintragen
"applicationId": [ "amzn1.ask.skill.1" , "amzn1.ask.skill.2" ],
"oauthClientID": [ "amzn1.application-oa2-client.1" , "amzn1.application-oa2-client.1" ]

Danach durch Aufruf von <source lang="bash" style="width:50%;">./bin/alexa</source> den Dienst starten (kein sudo!)

Der Start des Alexa-Dienstes auf der Console ist immer dann zu empfehlen, wenn man auf die Ausgaben des Dienstes angewiesen ist und beispielsweise sehen möchte, welche Devices durch den Dienst bereitgestellt werden oder ob Fehler auftreten. Beendet man die Console-Session wird auch der Dienst wieder beendet. Insofern ist die vorgenannte Vorgehensweise nur für ein Debugging zu empfehlen und nicht im Regelbetrieb. Nachfolgend ist beschrieben, wie man den Alexa-Dienst aus FHEM heraus starten / stoppen und neu starten kann.

==== Alexa-Fhem aus FHEM heraus starten ====
Zunächst das Start-up-Skript aus diesem Post herunterladen [https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271 https://forum.fhem.de/index.php/topic,60244.msg517271.html#msg517271] und unter /etc/init.d/alexa speichern.

Das Script geht davon aus, das der alexa-fhem script unter /opt/fhem/alexa-fhem liegt, und die logfiles später unter /opt/fhem/log. Sollte das nicht der Fall sein, muss das Skript angepasst werden.

Nun folgende Kommandos ausführen:
<source lang="bash" style="width:50%;">sudo chmod 755 /etc/init.d/alexa
sudo update-rc.d alexa defaults</source>

In der Datei <code>/etc/sudoers</code> den User fhem für die Nutzung von sudo zulassen (<code>sudo nano /etc/sudoers</code>), z.B. durch Anfügen der nachfolgenden Zeile:
<code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Nun folgende Devices anlegen (ggf. einem Raum zuordnen, z.B. AlexaControl):
<source lang="bash" style="width:75%;">define FHEM.Alexa.Status dummy

define FHEM.Alexa dummy
attr FHEM.Alexa event-on-change-reading state
attr FHEM.Alexa webCmd status:start:stop:restart

define FHEM.Alexa.DOIF DOIF ([FHEM.Alexa] eq "start")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa start > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "stop")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa stop > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "restart")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa restart > /dev/null 2>&1 &")})
DOELSEIF ([FHEM.Alexa] eq "status")
(set FHEM.Alexa on, {system ("sudo /etc/init.d/alexa status > /dev/null 2>&1 &")})</source>

==== Alexa-Fhem als Service (systemd) installieren ====
Auf neueren Installationen (z.B. RPi Jessie) wird init.d durch systemd ersetzt. Folgend die Anleitung um alexa-fhem als Service zu installieren auf einem Raspberry Pi mit Jessie.

Zunächst legen wir einen neuen Benutzer an unter dem alexa-fhem laufen soll, falls ihr nicht möchtet dass alexa-fhem z.B. mit dem fhem User ausgeführt wird:

<code lang="bash" style="width:75%;">
sudo useradd -M --system alexa
</code>

Eigentlich braucht er keine Gruppen, aber ihr könnt dem Benutzer auch der Gruppe <code>dialout</code> hinzufügen (<code>sudo usermod -a -G dialout alexa</code>)

Datei "alexa" unter <code>/etc/default</code> anlegen

# Defaults / Konfigurations Optionen für alexa-fhem
# Wo findet alexa-fhem die config.json Datei?
ALEXA_OPTS=-U /opt/fhem/.alexa

Den Pfad <code>/opt/fhem/.alexa</code> müsst ihr an eure Gegebenheiten anpassen. Letztendlich kann die config.json irgendwo liegen, hauptsache alexa-fhem weiß wo. Achtung: Natürlich muss der Benutzer auch Zugriff auf das Verzeichnis als auch das alexa-fhem Verzeichnis haben.

Datei "alexa.service" unter <code>/etc/systemd/system</code> anlegen:

[Unit]
Description=Node.js Alexa Server
After=syslog.target network-online.target

[Service]
Type=simple
User=alexa #oder ein anderer Benutzer wie fhem
EnvironmentFile=/etc/default/alexa
# oder wo auch immer eure alexa-fhem liegt
ExecStart=/opt/fhem/alexa-fhem/bin/alexa $ALEXA_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Um den Service zu aktiveren und zu starten helfen folgende Befehle:
sudo systemctl daemon-reload
sudo systemctl enable alexa
sudo systemctl start alexa

Status abfragen mit
sudo systemctl status alexa

Log einsehen?
sudo journalctl -u alexa

(mit <code>-f</code> kann man den follow Modus aktivieren, wie <code>tail -f</code>).
Bei einen reboot startet alexa-fhem jetzt automatisch.

==== Alexa-Fhem testen ====
Node.Js stellt einen Web-Server am Port 3000 bereit, das oben erzeugte Zertifikat sichert diesen Zugang per SSL ab. Durch Aufruf der Adresse
<code>https://<IP-Adresse des Servers>:3000</code> kann man testen, ob der Alexa-Fhem Service läuft - der Seitenaufruf liefert eine Zeile JSON-Code, beginnend mit
<code>{"header":{"name":"UnsupportedOperationError"...</code>

=== Alexa Device anlegen ===

Das Modul 39_alexa.pm stellt innerhalb von FHEM verschiedene Attribute z.B. alexaName oder alexaRoom zur Verfügung. Manche dieser Attribute (wie z.b. alexaName) werden in beiden Skills verwendet, andere werden ausschließlich bei einer Nutzung des Alexa Custom Skill verwendet.

Die Einrichtung des Alexa Device geschieht durch die nachfolgende Definition:
<source lang="bash" style="width:70%;">define MyAlexa alexa</source>

<hr>

=== Alexa Skills ===
Für folgende Schritte muss man unter der Adresse http://developer.amazon.com angemeldet sein
# Anmeldung auswählen<br />[[Datei:Developer.amazon.com-01-login2.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Developer.amazon.com-02-userpass2.png|200px]]

==== Security Profile anlegen ====
Die Erzeugung eines Sicherheitsprofils muss nur einmal erfolgen, es wird dann für alle weiteren Skills verwendet.
# Nach der Anmeldung Auswahl von ''APPS & SERVICES''<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend auswählen ''Security Profiles''<br />[[Datei:Developer.amazon.com-05-apps_and_services_-_security_profiles.png|200px]]
# Auswählen ''Create a New Security Profile'' aus<br />[[Datei:Developer.amazon.com-06-apps_and_services_-_create_a_new_security_profile.png|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen<br />[[Datei:Developer.amazon.com-07-apps_and_services_-_security_profile_management.png|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# Oben rechts auf ''Login with Amazon'' klicken.<br/>[[Datei:Developer.amazon.com-08-login_with_amazon.png|200px]]
# Auf der neu geladenen Seite auswählen ''Sign up''<br/>[[Datei:Developer.amazon.com-09-login_with_amazon_-_sign_up.png|200px]]
# Anschließend im Dropdown Menü das vorher angelegte Profil auswählen und mit ''Confirm'' bestätigen<br/>[[Datei:Developer.amazon.com-10-login_with_amazon_-_create_new_profile.png|200px]] [[Datei:Developer.amazon.com-11-login_with_amazon_-_create_new_profile2.png|200px]]
# Im folgenden Fenster die Adresse [https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 https://www.amazon.com/gp/help/customer/display.html?nodeId=468496] eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse'''<br/>[[Datei:Developer.amazon.com-12-login_with_amazon_-_enter_consent_screen_information.png|200px]]
# Anschließend bei dem neu angelegten Eintrag auf der rechten Seite auf das Zahnrad klicken und ''Web Settings'' auswählen<br/>[[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]
# Im neu geladenen Fenster anklicken von ''Edit''<br/>[[Datei:Developer.amazon.com-14-login_with_amazon_-_edit.png|200px]]
# Anschließend bei ''Allowed Return URLs'' die folgenden drei Adressen eingeben. ''xxx'' muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten [[#SmartHome_Skill_anlegen | SmartHome Skill anlegen]] bzw. [[#Custom_Skill_anlegen | Custom Skill anlegen]] jeweils unter Punkt 4 (Seite ''Configuration'') bei ''Redirect Urls'' am Ende der URLs angezeigt wird
## [https://layla.amazon.co.uk/api/skill/link/xxx https://layla.amazon.co.uk/api/skill/link/xxx]
## [https://pitangui.amazon.com/api/skill/link/xxx https://pitangui.amazon.com/api/skill/link/xxx]
## [https://layla.amazon.com/api/skill/link/xxx https://layla.amazon.com/api/skill/link/xxx]
.<br/>[[Datei:Developer.amazon.com-15-login_with_amazon_-_allowed_return_urls.png|200px]]

==== Skills bearbeiten ====
# Im Menü den Punkt ''ALEXA'' auswählen<br />[[Datei:Developer.amazon.com-03-apps_and_services.png|200px]]
# Anschließend im Feld ''Alexa Skills Kit'' auf ''Get started'' klicken<br />[[Datei:Developer.amazon.com-17-alexa_-_alex_skills_kit_-_get_started.png|200px]]

===== SmartHome Skill anlegen =====
# Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]
# Auf der folgenden Seite eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Type'' -> ''SmartHome Skill API''
#:* ''Language'' -> ''German''
#:* ''Name'' -> beliebiger Name, z.B. "MySmartHome Basic") <br/>[[Datei:Developer.amazon.com-19-alexa_-_alex_skills_kit_-_skill_information.png|200px]]
# Die folgende Seite einfach mit ''Next'' überspringen<br />[[Datei:Developer.amazon.com-20-alexa_-_alex_skills_kit_-_interaction_model.png|200px]]
# Auf der Seite ''Configuration'' Folgendes eingeben:
#:* ''Service Endpoint Type'' -> ''AWS Lambda'' ist vorausgewählt und kann nicht geändert werden.
#:* ''Geographical Region'' -> ''Europe'' auswählen und im Textfeld die ARN aus Abschnitt [[#ARN_der_AWS_Lambda_Funktion_bestimmen | AWS Lambda Funktion]] eintragen.
#:* ''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code>
#:* ''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)
#:* ''Redirect URLs'' - sollten vorbelegt sein
#:* ''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen
#:* ''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code>
#:* ''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1
#:* ''Client Authentication Scheme'' -> ''HTTP Basic''
#:* ''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code><br /><br />
<br />[[Datei:Developer.amazon.com-21-alexa_-_alex_skills_kit_-_configuration.png|200px]] [[Datei:Developer.amazon.com-22-alexa_-_alex_skills_kit_-_test.png|200px]]

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen<br />[[Datei:Developer.amazon.com-18-alexa_-_alex_skills_kit_-_add_a_new_skill.png|200px]]</li>
<li> Auf der folgenden Seite (''Skill Information'') die nachstehenden Daten eingeben und dann mit ''Next'' bestätigen:
<ul>
<li> ''Skill Type'' -> ''Custom Interaction Model'' </li>
<li> ''Language'' -> ''German''</li>
<li> ''Name'' -> beliebiger Name, z.B. "MySmartHome Advanced". Dieser wird in der Alexa App unter "Meine Skills" angezeigt.</li>
<li> ''Invocation Name'' -> Aufruf des Skills, unter dem dieser später gestartet wird. Z.B. "Alexa, starte James"<br />[[Datei:CustomSkill_2.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Interaction Model'' folgende Eingaben tätigen und mit ''Next'' abschließen
<ul>
<li>In einem separaten Browserfenster FHEM aufrufen, und für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen. Es erscheint ein Popup-Fenster mit ziemlich vielen Zeilen.
<li>In die Box ''Intent Schema'' kopiert man den ersten Teil dieser FHEM-Ausgabe hinein, also:<br/><blockquote>
{
"intents" : [
<hier ziemlich viele Zeilen>
]
}
</blockquote></li>
<li>Nun die ''Custom Slot Types'' einrichten. Dazu muss aus dem zweiten Teil der FHEM-Ausgabe jeweils der Slot-Type (z.B. <code>FHEM_article</code>) in das Feld ''TYPE'' eingetragen werden, das nach dem Anklicken von ''Add Slot Type'' erscheint. In das darunter liegende größere Textfeld kommen die möglichen Werte für diesen Slot, so wie sie aus der FHEM-Ausgabe abzulesen sind. Dann mit ''Save'' sichern. Als Custom Slot Type erscheint dann für diesen Beispiel-Slot
FHEM_article der | die | das | den
d.h., die Zeilenumbrüche bei den möglichen Werten werden als "|" dargestellt.</li>
<li>Hier muss nun ein Bruch im Arbeitsfluss durchgeführt werden, denn bei der Erstellung des Custom Skills kommt es auf die Reihenfolge der Einträge an. Deshalb zunächst diese FHEM-Ausgabe schließen, und für dasselbe FHEM-Device <code>get MyAlexa customSlotTypes</code> ausführen. Auch diese Ausgabe wird, wie oben beschriebeen, in Custom Slot Types eingetragen (erst der TYPE, dann die möglichen Werte)
<li>Anschließend erneut die FHEM-Ausgabe schließen und erneut für das bereits definierte Alexa-Gerät das Kommando <code>get MyAlexa interactionModel</code> aufrufen.
<li>Unter ''Sample Utterances'' nun den Text aus dem dritten Teil dieser FHEM-Ausgabe hineinkopieren<br />[[Datei:CustomSkill_5.PNG|400px]]</li>
</ul></li>
<li>Auf der Seite ''Configuration'' Folgendes eingeben und mit ''Next'' bestätigen:
<ul>
<li>''Service Endpoint Type'' -> ''AWS Lambda'' auswählen</li>
<li>''Geographical Region'' -> ''Europe'' auswählen und im Textfeld den Wert aus Abschnitt [[#AWS_Lambda_Funktion_anlegen | AWS Lambda Funktion anlegen]] (Punkt 12) eintragen. </li>
<li>''Do you allow users to create an account or link to an existing account with you?'' -> ''Yes''</li>
<li>''Authorization URL'' -> <code>https://www.amazon.com/ap/oa</code></li>
<li>''Client ID'' -> ''Client ID'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Scope'' -> <code>profile:user_id</code> (wörtlich 1:1 eintragen)</li>
<li>''Redirect URLs'' - sollten vorbelegt sein</li>
<li>''Authorization Grant Type'' -> ''Auth Code Grant'' auswählen</li>
<li>''Access Token URI'' -> <code>https://api.amazon.com/auth/o2/token</code></li>
<li>''Client Secret'' -> ''Client Secret'' aus Abschnitt [[#Login_with_Amazon | Login with Amazon]], Punkt 1</li>
<li>''Client Authentication Scheme'' -> ''HTTP Basic''</li>
<li>''Privacy Policy URL'' -> <code>https://www.amazon.com/gp/help/customer/display.html?nodeId=468496</code></li>
</ul>
Beim Sichern dieser Seite mit ''Next'' kann es zu einer Fehlermeldung kommen, wenn man seine Skill-Definitionen mit dem einfachen SmartHome-Skill begonnen hat. Deshalb muss noch der entsprechende Trigger für die [[#AWS_Lambda-Funktion | AWS Lambda Funktion]] nachgetragen werden, dies wird in Abschnitt [[#Trigger_f.C3.BCr_Custom_Skill_hinzuf.C3.BCgen | Trigger für Custom Skill hinzufügen]] beschrieben.
<br />[[Datei:CustomSkill_6.PNG|400px]] [[Datei:CustomSkill_7.PNG|400px]]</li>

==== Testen ====
Hat man den Custom Skill angelegt, bietet dieser auch eine komfortable Testmöglichkeit. Dazu wählt man in der Übersichtsseite ''All Skills'' den Button ''Edit'' des Alexa Custom Skill aus. Auf der nachfolgenden Seite dann links ''Test''.
Die Testseite enthält
* ein Feld ''Voice Simulator'', mit dem man die Sprachsausgabe testen kann,
* ein Feld ''Service Simulator'', mit dem die Verarbeitung von Alexa-Kommandois getestet werden kann. Hier kann man z.B. eintragen
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Siebenundzwanzig Uhr"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

==== Skill Id bestimmen ====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo die ''Alexa Skill Id'' zu finden ist}}
Für das [[#AWS_Lamba_Funktion_anlegen | Anlegen einer ''AWS Lambda Funktion'']] bzw für die [[#Alexa-Fhem_konfigurieren | Konfiguration von Alexa-Fhem]] wird die ''Alexa Skill Id'' benötigt. An diese kommt man wie folgt:
# Anmelden wie unter [[#Alexa_Skills | Alexa Skills]] beschrieben.
# Menüpunkt ''ALEXA'' auswählen, wie [[#Skills_bearbeiten | Skills bearbeiten]] erklärt.
# Beim gewünschten Eintrag auf ''Edit'' klicken<br />[[Datei:Developer.amazon.com-23-alexa_-_alex_skills_kit_-_overview.png|200px]]
# Die Id, die nun oben angezeigt wird, ist die gesuchte. Sie hat typischerweise das Format <code>amzn1.ask.skill.[Zahlen und Bindestriche]</code><br />[[Datei:Aws.amazon.com-06-configure_triggers2.png|200px]]

<hr>

=== AWS Lambda Funktion ===
Für folgende Schritte muss man unter der Adresse http://aws.amazon.com angemeldet sein
# Anmeldung auswählen<br />[[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben<br />[[Datei:Aws.amazon.com-02-login.png|200px]]
# Den Punkt ''Lambda'' links auf der Startseite auswählen, bzw. im Menü ''Services'' unter ''Compute'' den Menüpunkt ''Lambda'' auswählen<br />[[Datei:Aws.amazon.com-03-lambda.png|200px]]
==== AWS Lambda Funktion anlegen ====
# Für eine erste Lambda-Funktion den Punkt ''Get Started Now'' auswählen<br />[[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen<br />[[Datei:Aws.amazon.com-05-select_blueprint.png|200px]]
# Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Smart Home'' auswählen und mit ''Next'' bestätigen<br />[[Datei:Aws.amazon.com-06-configure_triggers1.png|200px]]
## Achtung, es ist möglich, dass dabei ''Alexa Smart Home'' überhaupt nicht angeboten wird. Dann bitte ganz rechts oben in der Ecke nachsehen, welche Region bzw. welches Land ausgewählt ist. Empfohlen wird, ''Ireland'' auszuwählen. Dann erscheint bei den Funktionen auch ''Alexa Smart Home''.
# Bei ''Application Id'' den Wert eintragen, dessen Ermittlung im Abschnitt [[#Skill_Id_bestimmen | Skill Id bestimmen]] beschrieben wird, den Haken bei ''Enable trigger'' setzen und mit ''Next'' bestätigen <br />[[Datei:Aws.amazon.com-06-configure_triggers3.png|200px]]
# Auf der Konfigurationsseite eingeben:
## ''Name'' -> ''FHEM''
## ''Runtime'' -> Node.js 4.3.
## ''Role'' -> ''Choose an existing role''
### Achtung: wenn es noch keine existing role gibt, zuerst ''Create a custom role'' -> in dem Popup dann ''lambda_basic_execution'' auswählen und auf ''Allow'' klicken sowie bei ''Existing role'' dann ''x'' wählen.
# Auf der Code-Seite wird bzw. im großen Textfeld ist dann der Code aus der Datei ''lambda.js'' im Paket [[#Alexa-Fhem_installieren | Alexa-Fhem]] vollständig einzufügen. Dabei muss noch der Hostname im Quellcode an den eigenen Hostnamen angepasst werden.
# Anschließend alles mit ''Next'' bestätigen.<br />[[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken<br />[[Datei:Aws.amazon.com-08-review.png|200px]]

==== Trigger für Custom Skill hinzufügen ====
Editiert man eine Lambda-Funktion, werden auf der Seite ''Triggers'' diejenigen Dienste angezeigt, die diese Funktion aufrufen.
* Hier taucht der Trigger ''Alexa Smart Home'' zusammen mit der ''Application Id'' auf, der bei der Einrichtung des SmartHome-Skills eingetragen wurde.
* Zur Verbindung mit dem Custom Skill ist es nötig, einen zweiten Trigger hinzuzufügen. Durch Anklicken von ''Add Trigger'' wird eine Auswahlseite eingeblendet. Im neuen Fenster dann auf den gestrichelten Kasten klicken und ''Alexa Skills Kit' auswählen und mit ''Next'' bestätigen

==== ARN der AWS Lambda Funktion bestimmen ====
# Auf der Übersichtsseite oben links den Menüpunkt ''Functions'' aúswählen<br />[[Datei:Aws.amazon.com-09-go_overview.png|200px]]
# Anschließend den Radiobutton der angelegten Funktion ''FHEM'' markieren und im Menü ''Action'' den Punkt ''Show ARN'' auswählen<br />[[Datei:Aws.amazon.com-10-1-show_arn.png|200px]]
# Es wird nun eine ARN Adresse angezeigt, die für den Abschnitt [[#SmartHome_Skill_anlegen| SmartHome Skill anlegen]] benötigt wird<br />[[Datei:Aws.amazon.com-10-2-arn.png|200px]]

=== Absichern des Zugriffs ===
Natürlich muss der Zugriff auf den von Alexa-Fhem verwendeten Port (default: 3000, Bestandteil des Codes in der AWS Lambda-Funktion) durch die Firewall freigeschaltet werden (auf einer FritzBox unter "Portfreigaben"). Die Kommunikation zwischen Amazon und FHEM ist wegen der Verwendung von SSL schon verschlüsselt - prinzipiell kann aber jeder von außen mit Alexa-Fhem kommunizieren. Man sollte sich deshalb im Klaren darüber sein, dass dies eine Sicherheitslücke darstellt: Jeder offene Port verleitet zu Angriffen, und mit zunehmender Verbreitung von Alexa steigt auch das Risiko. Es wird deshalb empfohlen, vor den eigentlichen Alexa-Server zur Absicherung einen Apache-Webserver als ReverseProxy zu setzen. Nicht nur ist der Apache eine hervorragend stabile und seit Jahrzehnten getestete Software, sondern die Konfiguration als ReverseProxy erlaubt auch, den Zugriff auf den Alexa-Fhem-Rechner auf die Amazon-Maschinen zu beschränken.

'''Achtung: Dies ist keine allgemeine Anleitung in Sachen Computersicherheit.''' Im Folgenden gehen wir davon aus, dass
* Grundbegriffe wie Firewall, IP-Ports, SSL und Dynamic DNS vertraut sind
* Ein Apache Webserver (idealerweise auf einer zweiten Maschine) bereits installiert ist und die Konfiguration verstanden wurde (wenn nicht: Es gibt im Netz ''tausende'' von Anleitungen dafür...)
* Ein Servername von einem DynDNS-Anbieter - sagen wir ''myhome.is-my-castle.com'' - bereits von ''außen'' auf unser SmartHome zeigt.
* Alexa-Fhem in einer der oben beschriebenen Basiskonfigurationen läuft, d.h. der Zugriff auf <code>https://myhome.is-my-castle.com:3000</code> ergibt, wie im Punkt [[#Alexa-Fhem_testen|Alexa-Fhem testen]] beschrieben, eine Antwort des Node.js Servers.

Als erster Schritt zur Absicherung muss das ReverseProxy Modul für den Apache installiert und mit <code>a2enmod</code> aktiviert werden, hierzu sei auf [https://www.digitalocean.com/community/tutorials/how-to-use-apache-http-server-as-reverse-proxy-using-mod_proxy-extension diese Anleitung] verwiesen. Der zweite Schritt besteht darin, den SSL-Zugriff durch ein Passwort abzusichern. Dazu wird auf dem Apache-Rechner das Programm
htpasswd <passwdfile> <username>
ausgeführt, das Programm fragt dann nach dem gewünschten Passwort. Wir nehmen im Folgenden an, dass das Passwortfile ''/etc/apache2/htpasswd'' ist, der gesetzte Username ''alexa'' lautet und das Passwort ''my_smarthome'' ist.

Im dritten Schritt wird nun in das Apache-Konfigurationsfile die Weiterleitung auf den eigentlichen Alexa-Fhem-Rechner eingetragen. Dazu wählen wir, dass von außen der Standard-SSL-Port 443 benutzt werden soll, sowie als Verzeichnisname ''/alexa''. '''Achtung:''' Dieser Code soll '''nicht''' in die Default-Konfiguration des Apache-Webservers. Sondern in eine separate Datei (Dateiname z.B. "fhem"), die ins Unterverzeichnis /etc/apache2/conf.d gestellt wird.

<VirtualHost *:443>
ServerName myhome.is-my-castle.com
SSLEngine on
SSLProxyEngine on
SSLCertificateKeyFile /etc/apache2/mycert/server.key
SSLCertificateFile /etc/apache2/mycert/server.crt
<Location /alexa>
AuthType Basic
AuthName "Authentication Required"
AuthUserFile "/etc/apache2/htpasswd"
Require valid-user
ProxyPass https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
ProxyPassReverse https://<hier IP-Adresse des Alexa-Fhem-Rechners>:3000/
Order deny,allow
Allow from All
</Location>
(... Hier eventuell weitere Umleitungen)
</VirtualHost>
Nach einem Neustart des Apache-Servers, dem Schließen des Ports 3000 in der Firewall sowie dem Öffnen des Ports 443 ist der Alexa-Fhem-Rechner von außen nur noch erreichbar durch den Aufruf von <code>https://myhome.is-my-castle.com/alexa</code> und verlangt unmittelbar die Eingabe von Username und Passwort.

Der vierte Schritt ist nun, den Code der AWS Lambda-Funktion an fünf Stellen zu verändern
'''const PORT=443;'''
const HOST='myhome.is-my-castle.com';
'''const PATH='/alexa';'''
'''const AUTH='alexa:my_smarthome';'''
// entry
exports.handler = function(event, context, callback) {
console.log(`EVENT: ${event}`);
console.log(`CONTEXT: ${context}`);
var post_data = JSON.stringify(event);
var options = {
hostname: HOST,
port: PORT,
//family: 6,
'''path: PATH,'''
method: 'POST',
'''auth: AUTH,'''
rejectUnauthorized: false, // accept self-signed
(etc., Rest des Codes wie gehabt)
Natürlich muss der Zugriff getestet werden. Bei Beachtung aller dieser Schritte werden alle un-autorisierten Zugriffe von außen abgewehrt. Eine noch weiter gehende Sicherung ist möglich, dazu kann in der Serverkonfiguration der Zugriff auf die Amazon-Domains beschränkt werden. Das ganze Alexa-System ist aber noch in konstanter Weiterentwicklung, diese Domain-Namen können sich also noch ändern.

== Einrichtung in der Alexa App==
Nachdem die Alexa Skills angelegt wurden, müssen diese noch in der Alexa App eingerichtet werden.
Dafür jeweils per Desktop-Browser auf [http://alexa.amazon.de alexa.amazon.de] anmelden, nicht die App unter iOS oder Android verwenden. Diese hat Probleme mit der OAuth Verknüpfung.

=== Alexa Skill ===
# Auf ''Skills'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen<br />[[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken<br />[[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken<br />[[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen<br />[[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein <br />[[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken<br />[[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken<br />[[Datei:Alexa.amazon.de-07-Gerätesuche.png|200px]]
# Wurde soweit alles korrekt eingerichtet, werden nun die gefundenen Geräte angezeigt.

Tip: Es macht Sinn, unter ''Meine Gruppen'' Gruppen benannt nach den Räumen einzurichten. Hierdurch kann Alexa die Geräte besser auseinander halten, vor allem wenn die den gleichen Alias (z.B. "Licht") haben.

== Einrichtung unter FHEM ==
Im Folgenden werden exemplarisch ein paar Geräte beschrieben, die man nutzbringend mit FHEM einsetzen kann.

Bei Verwendung des Custom Skills übersetzt die Kombination der Attribute ''alexaMapping'' und ''homebridgeMapping'' Sprachbefehle ("Intents") in gerätespezifische Kommandos.
* Das Attribut alexaMapping wird am Alexa-Device gesetzt und dient dazu, erkannte Sprachkommandos in abstrakte Characteristiken zu überführen. Für den einfacheren SmartHome Skill hat darum das Attribut ''alexaMapping'' keine Bedeutung, sondern nur der ''genericDeviceType'' des zu steuernden Gerätes.
* Das Attribut homebridgeMapping wird für beide Skills am zu steuernden Gerät gesetzt und übersetzt diese Charakteristiken in die konkreten Befehle, die das Gerät versteht. Der inhalt des Attributs wird von links nach rechts ausgewertet und ist wie folgt aufgebaut:
** Das Attribut enthält eine durch Leerzeichen getrennte Liste aus Konfigurationen für jeweils eine Characteristik
** Jede einzelne der Characteristik-Konfigurationen besteht aus dem Namen der Characteristik, gefolgt von "=" und einer kommaseparierten Liste von Parametern.
attr <device> homebridgeMapping <Characteristic1>=<param1.1>,<param1.2>,... <Characteristic2>=<param2.1>,<param2.2>,...
** Jeder Parameter besteht entweder aus
*** <code><cmd>:<device>:<reading></code>, hier können nicht verwendete Elemente von links nach rechts weg gelassen werden.
*** <code><name>=<value></code>, hier kann <code><value></code> entweder ein Wert oder semikolonseparierte Liste sein.
*** Oder dem schlüsselwort <code>clear</code>, welches alle vorhandenen (default) Parameter dieser Characteristik löscht. <code>clear</code> kann auch an Stelle einer ganzen Characteristik-Konfiguration stehen
Weiter führende Dokumentation zum homebridgeMapping findet sich unter https://forum.fhem.de/index.php/topic,48558.0.html

=== Einfacher Schalter ===
* Ein einfacher Schalter, der die set-Kommandos ''on'' und ''off'' kennt, kann direkt mit Alexa-Fhem gekoppelt werden
* Für kompliziertere Aktionen, etwa das Übermitteln eines spezifischen Schaltbefehls an FHEM, ist die Einrichtung eines Dummies zu empfehlen.
Ob Dummy oder nicht, wichtig sind die drei fett gedruckten Zeilen
define Alexa.Party dummy
'''attr Alexa.Party alexaName party'''
'''attr Alexa.Party alexaRoom alexaroom'''
'''attr Alexa.Party genericDeviceType switch'''
attr Alexa.Party group AlexaGeräte
attr Alexa.Party room AlexaRoom
'''attr Alexa.Party setList on off'''
Selbstverständlich kann man diesen Dummy mit einem notify oder DOIF abfangen, um die gewünschte Schaltaktion auszuführen.

Ein Alternative zum Dummy ist das Anlegen eines readingsProxy, dem die entsprechenden Attribute gegeben werden.

Weil es sich hierbei um eines der einfachen Geräte handelt, die Alexa selbst im SmartHome Skill bearbeiten kann, ist auch der zweite Schritt bei der Einrichtung in der Alexa App sinnvoll: Der Schalter wird dann im Bereich Smart Home der Alexa App erkannt. Wer ihn auch mit dem Custon Skill bedienen möchte, muss natürlich Sorge tragen, dass der Alexa-Name ''party'' bei den FHEM_Devices auftaucht und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sind (siehe Abschnitt [[##Custom_Skill_anlegen | Custom Skill Anlegen]]).

=== Wecker ===
Dieses Gerät kann man nur mit dem Custom Skill bedienen, es wird also '''nicht''' im Bereich Smart Home der Alexa App auftauchen. Wir richten einen Dummy ein, wichtig sind wieder die fett gedruckten Zeilen:
define Alexa.Weckzeit dummy
'''attr Alexa.Weckzeit alexaName weckzeit'''
'''attr Alexa.Weckzeit alexaRoom alexaroom'''
attr Alexa.Weckzeit genericDeviceType clock
attr Alexa.Weckzeit group AlexaGeräte
'''attr Alexa.Weckzeit homebridgeMapping Weckzeit=state,cmd=+'''
attr Alexa.Weckzeit room AlexaRoom
'''attr Alexa.Weckzeit setList Weckzeit:time'''
Das Attribut ''genericDeviceTye'' ist nicht wichtig, weil es ein generisches Device dieser Art gar nicht gibt. Wichtig hingegen ist das Attribut ''homebridgeMapping''

Für das Gerät ''MyAlexa'', das in Abschnitt definiert wurde, muss im Attribut ''alexaMapping'' auftauchen
Weckzeit=verb=stelle,valuePrefix=für;auf,values=AMAZON.TIME,valueSuffix=uhr
Darüber hinaus muss der Alexa-Name ''weckzeit'' bei den FHEM_Devices auftauchen und die entsprechenden weiteren Slot Types und Example Utterances in der Konfiguration des Custom Skills vorhanden sein (siehe Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]]).

Der Aufruf dieses Gerätes mit Alexa erfolgt dann z.B. mit den Sätzen
<pre style="width:50%;">
"Alexa, sage <Custom Skill Invocation Name>: Stelle Weckzeit auf Neunzehn Uhr Siebenundzwanzig"
"Alexa, frage <Custom Skill Invocation Name> nach dem Status von Weckzeit"
</pre>
Dabei ist natürlich der ''Custom Skill Invocation Name'' durch den Wert zu ersetzen, den man im Abschnitt [[#Custom_Skill_anlegen | Custom Skill Anlegen]] unter Punkt 2 eingetragen hat.

Zur weiteren Bearbeitung kann man jetzt mit einem DOIF Statusänderungen des Dummies abfangen und durch eine kleine Helperfunktion ins "echte" FHEM weiterleiten.
define Alexa.Weckzeit.N DOIF (["Alexa.Weckzeit:.*"])({AlexaHelper("Alexa.Weckzeit","$EVENT")})
Die Helperfunktion (z.B. in 99_myUtils.pm) stellt aus der übergebenen Zeit (immer im Format dd:mm) eine sprachkompatible Nachricht $nc und einen mit den FHEM-Zeitangaben kompatiblen String $nt zusammen und reicht beide an eine Routine ''changeWakeTime'' weiter (dokumentiert in den [https://www.dpunkt.de/buecher/12387/9783960090120-smarthome-hacks.html Smart Home Hacks]).
sub AlexaHelper($$){
my ($name,$event)=@_;
if( $name eq "Alexa.Weckzeit" ){
my ($nc,$nt);
#-- volle Stunde----------------------------------------
if( $event =~ /(\d+):00/ ){
$nc=sprintf("%d Uhr",$1);
$nt=sprintf("%02d:00:00",$1);
#-- nicht volle Stunde---------------------------------
}elsif( $event =~ /(\d+):(\d+)/ ){
$nc=sprintf("%d Uhr %d",$1,$2);
$nt=sprintf("%02d:%02d:00",$1,$2);
}
changeWakeTime(\'GalaxyTab.EG\',\'$nc\',\'$nt\');
}
}

<hr>

=== Lichtszene ===
Eine Lichtszene wird mit dem Modul LightScene angelegt. Wir gehen davon aus, dass in der Lichtszene die beiden Szenen Alle_An und Alle_Aus, sowie mindestens eine weitere Szene (hier: Sitzgruppe) definiert wurde.
* Nachfolgend wird ein Beispiel beschrieben, wie man eine Lichtszene mit dem einfachen SmartHome Skill steuern kann. Die verwendeten Kommandos sind dann
<pre>
"Alexa, schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
"Alexa, schalte (die) Beleuchtungsitzgruppe an" -> LightScene Sitzgruppe wird ausgewählt
...
"Alexa, schalte (die) Beleuchtung aus" -> LightScene Alle_Aus wird ausgewählt
</pre>
* Künftig wird man LightScene mit dem Custom Skill eventuell direkt steuern können - allerdings hat das einen geringeren WAF, als die Steuerung über den SmartHome Skill: Der Einschaltsatz muss dann mindestens lauten
<pre>
"Alexa, sage <Custom Skill Invocation Name>: schalte (die) Beleuchtung an" -> LightScene Alle_An wird ausgewählt
</pre>
Dafür wird es aber auch möglich sein direkt die SzenenNamen im gesprochenen Kommando zu verwenden und so auf die Umwege über dummys und ähnliches zu verzichten.

Im ersten Schritt wird ein Dummy für die Gesamtbeleuchtung eingerichtet:
define Alexa.Beleuchtung dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung alexaName beleuchtung'''
'''attr Alexa.Beleuchtung alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung genericDeviceType switch'''
Anschließend wird für jede vorhandene Lichtszene (außer Alle_An und Alle_Aus) ein weiterer Dummy angelegt:
define Alexa.Beleuchtung.Sitzgruppe dummy
attr Beleuchtung setList on off
'''attr Alexa.Beleuchtung.Sitzgruppe alexaName beleuchtungsitzgruppe'''
'''attr Alexa.Beleuchtung.Sitzgruppe alexaRoom alexaroom'''
'''attr Alexa.Beleuchtung.Sitzgruppe genericDeviceType switch'''
Die eigentliche Steuerung übernimmt dann ein DOIF
define Alexa.Beleuchtung.N DOIF
(["Alexa.Beleuchtung.Sitzgruppe:on"])
(set <devicename der Lichtszene> scene Sitzgruppe,
set Alexa.Beleuchtung off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSIF
... <weitere on-Events der anderen Szenen werden abgefangen>
DOELSEIF
(["Alexa.Beleuchtung:on"])
(set <devicename der Lichtszene> scene Alle_An,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
DOELSEIF
(["Alexa.Beleuchtung:off"])
(set <devicename der Lichtszene> scene Alle_Aus,
set Alexa.Beleuchtung.Sitzgruppe off,
...<weitere dummies der anderen Szenen werden ebenfalls ausgeschaltet>
)
Mit diesem DOIF wird ein Radiobutton simuliert, d.h. wie bei den Stationstasten vor Uralt-Radios sorgt die Auswahl einer Szene immer dafür, dass alle anderen Dummies ausgeschaltet werden.
Natürlich kann man das auch mit einem kleinen Perl-Programm erreichen.

Zwei andere Ansätze Lichtszenen zu schalten die ohne DOIF auskommen sind im Folgenden beschrieben:

* Wenn es von Interesse ist die Steuerung mit einer Darstellung in FTUI zu verbinden: Statt der oben beschriebenen dummy Devices kann man readingsProxy Devices mit passenden setFn und valueFn analog zum [[Harmony#Button_f.C3.BCr_eine_bestimmte_Activity_im_Frontend_und_Homekit_.C3.BCber_readingsProxy|diesem Beispiel für harmony aktivitäten]] verwenden.

* Für jede zu schaltende Szene wird ein dummy angelegt dessen homebridgeMapping direkt auf das LightScene Device zeigt:

define <dummy> dummy
attr <dummy> setList on off
attr <dummy> genericDeviceType switch
attr <dummy> homebridgeMapping On=<light scene>::state,valueOn=<szene>,cmdOn=scene+<szene>,cmdOff=scene+<szene aus>

Bei der zweiten Variante wird davon ausgegangen das der aktuelle status nicht abgefragt oder angezeigt werden soll. Deshalb gibt es keine direkte RadioButton Funktionalität.

== Nutzung ==
Um den Namen zu bestimmen, unter dem ein Gerät mit Alexa angesprochen wird, verwendet Alexa-Fhem mit absteigender Priorität:
* das alexaName Attribut
* das alias Attribut
* das NAME Internal
Damit Alexa ein Gerät eindeutig identifizieren kann, sollten eindeutige Gerätenamen verwendet werden, bestehed möglichst aus einem Wort und ohne Ziffern. Wenn Alexa einen Namen nicht versteht, kann man unter [http://alexa.amazon.de/spa/index.html] nachsehen was tatsächlich verstanden wurde und den Gerätenamen ggf. anpassen.

=== SmartHome Skill ===
Gruppen (Räume) müssen in der Alexa App konfiguriert werden. Über das API lassen sich nur der Name und die Schalteigenschaften übergeben.

Nach erfolgreicher Einrichtung des SmartHome Skills sollte Alexa mit den folgenden Befehlen nutzbar sein:
<pre style="width:50%;">
“alexa, schalte <gerät/gruppe> ein”
“alexa, schalte <gerät/gruppe> aus”
“alexa, stelle <gerät/gruppe> auf <wert> prozent”
“alexa, stelle <gerät/gruppe> auf <anzahl> grad”
“alexa, erhöhe <gerät/gruppe> um <anzahl> prozent”
“alexa, reduziere <gerät/gruppe> um <anzahl> prozent”
“alexa, erhöhe <gerät/gruppe> um <anzahl> grad”
“alexa, reduziere <gerät/gruppe> um <anzahl> grad”
</pre>

=== Custom Skill ===
Der Custom Skill erlaubt im Gegensatz zum SmartHome Skill eine weitreichende Konfiguration der möglichen Kommandos.

Das Prinzip der Kommandokonfiguration ist {{Link2Forum|Topic=60244|Message=532513|LinkText=im Forum}} beschrieben.

TODO: Abfragen, Attribute (alexaMapping, alexaTypes, fhemIntents, articles, prepositions)

== Troubleshooting ==

====Allgemeiner Hinweis====
Besonders wichtig ist, dass man sich sehr genau an diese Anleitung hält. Ein häufiger Fehler ist, dass die einfachen Anführungszeichen in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 8 einfach weggelassen werden. Diese sind zwingend notwendig. Es darf auch nur der reine Hostname eingetragen werden. Also kein ''http://'' davor. Entweder eine feste IP Adresse oder den Hostnamen, um den Rechner zu erreichen, den ihr über den Port 3000 freigegeben habt. Das sollte dann so aussehen:
<pre style="width:50%;">
const PORT=3000;
const HOST='mein.host.name';
</pre>

====Freigabe von Port 3000====
{{Randnotiz|RNTyp=Fehl|RNText=Derzeit müsst ihr über einen echten IPv4 Anschluss verfügen, damit der Amazon Lambda-Server euch erreichen kann. DS-Lite Anschlüsse wie die von <b>UnityMedia</b> z.B. funktionieren derzeit leider nicht. Eine möglicher "Workaround" wird hier beschrieben: https://forum.fhem.de/index.php/topic,60244.msg518276.html#msg518276}}

Auf dem Router muss der Port 3000 Protokoll TCP freigegeben werden. D.h. von außen muss man wenn man den Port 3000 aufruft, auf dem intern laufenden node.js Alexa-Dienst zugreifen können.
Je nach Router gestaltet sich das Portforwarding bzw. die Portumleitung etwas schwieriger.

Bei einem Speedport Router der Telekom beispielsweise, muss der Router komplett neu gestartet werden, wenn die Portfreigabe eingerichtet wurde.

Bei der Fritz!Box ist das nicht nötig, bei dieser finden die Freigabe unter ''Internet -> Freigaben -> Portfreigaben'' statt. Dort wählt man dann den Rechner aus und richtet eine neue Freigabe ein. Wichtig hierbei ist, dass man Portfreigabe auswählt und nicht MyFRITZ!-Freigabe. Bei Port von bis trägt man 3000 ein, bei Port extern ebenfalls.

Um die Portweiterleitung zu testen, solltet ihr euch auch nicht im gleichen Netz befinden. Viele Router blockieren den Netzaufruf aus dem gleichen Netz. Am besten testet ihr es, wenn ihr an eurem Mobiltelefon W-LAN deaktiviert und im Browser folgende Seite aufruft: ''https://mein.hostname:3000''. Wenn ihr im Browser dann einen Quellcode von Alexa seht, funktioniert die Portumleitung.

Wenn bis hier alles funktioniert und es läuft dennoch nicht rund, liegt das Problem woanders. Kommt z.B. bei der Gerätesuche kein Request rein (sichtbar auf dem Bildschirm, wenn bin/alexa gestartet wurden), kann evtl. der Lambda-Dienst falsch konfiguriert sein.

====Probleme mit node.js - npm install====

Falls eine Fehlermeldung auftritt, dass "npm" nicht gefunden werden kann, bitte NodeJS entsprechend der Anleitung im Homebridge-Artikel vorgehen: [[Homebridge_einrichten#NodeJS_installieren|NodeJS installieren]] sowie [[Homebridge_einrichten#Python.2C_g.2B.2B.2C_MDNS_installieren|Python, g++, MDNS installieren]], siehe auch folgenden Abschnitt.

====Es kommen diverse Fehlermeldungen beim Starten von alexa-fhem und es beendet sich====
Wenn man auf der Konsole angemeldet ist, den Befehl<source lang="bash" style="width:50%;">node -v</source>eingeben. Ist die Version niedriger als die geforderte 0.12, muss eine neuere installiert werden. Hier darf man dann im Wiki unter [[Homebridge_einrichten#NodeJS_installieren]] nachschauen. NodeJS V4 sollte hierbei schon ausreichen. Solange die node.js Version nicht passt, gar nicht groß rum experimentieren! Bitte beachtet, dass alle Voraussetzungen unter [[Alexa-Fhem#Voraussetzungen]] erfüllt sind! Keine Experimente mit Versionen die darunter liegen.

====Fehlermeldung ''NAT-PMP failed: Error: timeout'' Fehler angezeigt beim Start von alexa-fhem====
Wenn ihr dann alexa-fhem über die Konsole startet und bekommt folgenden Fehler: ''NAT-PMP failed: Error: timeout'', lasst euch davon nicht irritieren. Das bedeutet lediglich, dass der Port nicht automatich freigegeben wurde über uPNP. Alternativ prüft, ob die Funktion der Portfreigabe via uPNP auf eurem Router aktiviert ist.

====Nach Start auf der Console beendet sich Alexa-FHEM sofort wieder====
Unmittelbar nach dem Start von Alexa-FHEM werden ein paar UPNP Fehlermeldungen ausgegeben. Unmittelbar danach beendet sich Alexa-FHEM wieder.

Viele scheinen ein Problem mit UPNP auf dem Raspberry Pi zu haben. Wenn dieses Problem auftritt einfach in der <code>~/.alexa/config.json</code> die folgenden Zeilen rauslöschen:

<pre>
"nat-pmp": "10.0.1.1",
"nat-upnp": true,
</pre>

Jetzt erneut Alexa-FHEM starten. Sollte nun laufen.

====Was ist zu tun, wenn alexa-fhem keine Geräte findet?====
Zunächst müssen die Geräte, die angesprochen werden wollen, unter FHEM ein neues Attribut zugewiesen bekommen. Dazu das Gerät in FHEM öffnen und das Attribut ''genericDeviceType switch'' hinzufügen, wenn es ein Schalter mit der Funktiona AN/AUS sein soll. Wenn man will, kann man dem Gerät jetzt noch über das Attribut ''alias'' eine besseren Namen geben, mit dem Alexa das Gerät dann auch finden kann.
Anschließend muss alexa-fhem neu gestartet werden und die definierten Geräte sollten nun gefunden werden.

====Was ist zu tun, wenn Alexa zwar Geräte findet, diese aber nicht angesprochen werden können?====
Zuerst die Informationen zum Datenfluss ganz oben ansehen. Dann am besten von hinten nach vorne vorgehen:
* wenn nichts bei alexa-fhem ankommt: port forwarding prüfen
* wenn lambda.js nichts los wird: im cloudwatch log nachsehen
* wenn bei lambda.js nichts ankommt: den trigger prüfen

Zunächst sollte man sich unter ''http://aws.amazon.com'' das Logfile seiner erstellten Funktion anschauen. Ist überhaupt ein Logfile vorhanden? Falls nicht, liegt es vermutlich am Trigger.
Den solltet ihr überprüfen. Scheinbar kommt es hin und wieder vor, dass dieser nicht gesetzt ist. Dazu einfach auf ''Triggers'' klicken und mit ''Add trigger'' erneut einen anlegen. Hier muss, wie in der Anleitung unter '''AWS Lambda Funktion anlegen''' Punkt 7, die ''Application Id'' stehen und der Haken bei ''Enable trigger'' gesetzt sein. Dann alexa-fhem neu starten.
Wenn ihr Änderugen gemacht habt und den alexa-fhem Dienst noch nicht neu gestartet habt, wäre jetzt der richtige Zeitpunkt.

====Was ist zu tun, wenn sich der Alexa-Service nicht starten lässt?====
Schaut bitte in das Unterverzeichnis [alexa-fhem (also dort, wo Ihr Alexa-FHEM instelliert habt]/bin. Die dort befindliche Datei ''alexa'' muss ausführbar sein. Also z.B. so:
<source lang="bash" style="width:70%;">2755327 4 -rwxr-xr-x 1 pi pi 339 Nov 26 23:20 alexa</source>
Sollte dies nicht der Fall sein bitte mit:
<source lang="bash" style="width:70%;">chmod +x alexa</source>
die Datei ausführbar machen. Sofern der User "pi" Eigentümer ist, ist kein sudo erforderlich.

====Wie kann ich via Alexa-FHEM auf FHEM zugreifen, wenn der Port mit Benutzername/Kennwort geschützt ist?====

Hierzu muss die Datei <code>~/.alexa/config.json</code> geöffnet werden und der Abschnitt "connections" um folgende Zeile ergänzt werden:<pre>
"auth": {"user": "fhem", "pass": "fhempassword"},</pre>
Bei Verwendung von SSL bei FHEM muss auch noch <pre>
"ssl": true,</pre> hinzugefügt werden

[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

HM-LC-Sw2PBU-FM Unterputz-Schaltaktor 2-fach

2017-02-04T21:25:14Z

Moontear: Initiale Version des Artikels

{{Infobox Hardware|Bild=HM-LC-Sw2PBU-FM_Front.jpg
|Bildbeschreibung=HM-LC-Sw2PBU-FM Unterputz-Schaltaktor 2-fach für Markenschalter
|HWProtocol=HomeMatic
|HWType=Aktor / Sender
|HWCategory=HomeMatic
|HWComm=868,3MHz
|HWChannels=2
|HWVoltage=230V
|HWPowerConsumption=0,5W (Standby)
|HWPoweredBy=Netz
|HWSize=71x71x37 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]
|HWManufacturer=eQ-3}}

[[HM-LC-Sw2PBU-FM Unterputz-Schaltaktor 2-fach]] ist ein zweikanaliger Funk-Schaltaktor "für Markenschalter", der mittels entsprechender Installationsadapter mit Tasterwippen diverser renommierter Hersteller versehen werden kann und sich dadurch nahtlos in bestehende Elektroinstallationen einfügt.

== Features ==
Das besondere an diesem Schalter ist, dass er den vorhandenen Unterputzeinsatz vollständig ersetzt. Dabei kann die Wippe des vorhandenen Schalters - je nach Hersteller - mit einer entsprechenden Adapterplatte weiterverwendet werden. Anzumerken ist dass man nicht zwei getrennte Schaltwippen erhält sondern eine große Schaltwippe, wobei der obere Bereich der Schaltwippe im Standard Kanal 1 schaltet, der untere Bereich Kanal 2.

Es handelt sich hierbei nur um einen Aktor. Es ist nicht möglich die Taster mit anderen Homematic Geräten zu peeren.

== Technische Daten ==

{|
| Art
| Unterputz
|-
| Typ
| 2fach
|-
| Stand-by-Verbrauch
| 0,2 W (lt. Bedienungsanleitung, S. 38, Stand 02/2017)
|-
| Versorgungsspannung
| 230 V
|-
| Abmessungen (B x H x T)
| 71 x 71 x 37 mm
|-
| Farbe
| Grau
|-
| Max. Schaltleistung
| 690 W je Kanal, 1150 W Total
|-
| Laststrom
| 3 A je Kanal, 5 A total
|-
| Relaistyp
| Wechsler
|-
| Funkfrequenz
| 868,3 MHz
|-
| Empfängerklasse
| SRD Class 2
|-
| Max. Sendeleistung
| 10 mW
|-
| IP-Schutzgrad
| IP 20
|-
| Umgebungstemperaturbereich
| 5–35 °C
|}

== Hinweise zur Hardware-Installation ==
Der vorhandene Schalter muss ersetzt werden. Dabei sind ein paar Dinge zu beachten:

* Der (neue) Schalter benötigt neben dem L-Leiter auch einen N-Leiter für die Stromversorgung.
* Die Befestigung ist nicht wie bei dem System z.B. von Merten durch spreizen von Klammern möglich. Der Schalter muss in die Löcher in der Dose geschraubt werden (Schrauben im Lieferumfang enthalten).
* Die "Frontplatte" bzw. der Befestigungsrahmen ist etwas dicker, als der Rahmen eines normalen Schalters. Dadurch kann es sein, dass der vorhandene Rahmen des Schalters nicht mehr ganz an der Wand anliegt.
* Um die bereits vorhandene Schalter-Wippe weiter nutzen zu können, muss ein passender Adapter verwendet werden.
* Bestehende Schaltwippen 2-fach können ebenfalls verwendet werden, sind hinterher aber als eine große Schaltwippe zu bedienen. Falls man das nicht mag müsste man eine große Schaltwippe nachkaufen

== Hinweise zum Betrieb mit FHEM ==
Das [[Pairing (HomeMatic)|Pairing]] sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden.

=== FHEM Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration]]:

<pre>
define Licht_Bad CUL_HM xxxxxxx
attr <name> IODev CUL_0
attr <name> autoReadReg 4_reqStatus
attr <name> expert 1_allReg
attr <name> firmware 2.9
attr <name> group Lampen
attr <name> model HM-LC-Sw2PBU-FM
attr <name> serialNr NEQ16xxxxxx
attr <name> subType switch
attr <name> webCmd getConfig:clear msgEvents
define FileLog_<name> FileLog ./log/<name>-%Y.log <name>
attr FileLog_<name> logtype text
attr FileLog_<name> room CUL_HM
define <name>_Sw_01 CUL_HM xxxxxxx
attr <name>_Sw_01 model HM-LC-Sw2PBU-FM
attr <name>_Sw_01 peerIDs 00000000,
attr <name>_Sw_01 webCmd toggle,on:off
define <name>_Sw_02 CUL_HM xxxxxxx
attr <name>_Sw_02 model HM-LC-Sw2PBU-FM
attr <name>_Sw_02 peerIDs 00000000,
attr <name>_Sw_02 webCmd toggle,on:off
</pre>

=== Mögliche Schaltoperationen ===
Der Aktor versteht folgende Aktionen (anzuwenden auf den Channels):

<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-Sw1PBU-FM folgendes Log zu sehen:
<pre>
2017.02.04 17:40:06 3: CUL_HM set <name>_Sw_01 on
2017.02.04 17:40:09 3: CUL_HM set <name>_Sw_01 off
2017.02.04 17:41:03 3: CUL_HM set <name>_Sw_02 off
</pre>

Beim Einrichten des Schalters kommt folgender Auszug:
<pre>
2017.02.04 17:37:00 2: CUL_HM Unknown device HM_50xxx is now defined
2017.02.04 17:37:00 2: autocreate: define HM_50xxx CUL_HM xxxxxxx
2017.02.04 17:37:00 2: autocreate: define FileLog_HM_HM_50xxxFileLog ./log/HM_50xxx-%Y.log HM_50xxx
2017.02.04 17:37:00 3: CUL_HM get HM_50xxx_Sw_01 saveConfig ./temperatureLists/regSave.cfg strict
2017.02.04 17:37:00 3: CUL_HM get HM_50xxx_Sw_02 saveConfig ./temperatureLists/regSave.cfg strict
2017.02.04 17:37:00 3: CUL_HM pair: HM_50xxx switch, model HM-LC-Sw2PBU-FM serialNr
2017.02.04 17:37:05 3: CUL_HM set HM_50xxx getConfig
2017.02.04 17:37:07 3: CUL_HM set HM_50xxx_Sw_01 getConfig
2017.02.04 17:37:09 3: CUL_HM set HM_50xxx_Sw_02 getConfig
</pre>

== Links ==
* Produktwebseite (Bausatz) bei [https://www.elv.de/homematic-funk-schaltaktor-2fach-unterputzmontage-1.html ELV]
* Sehr ähnlich ist der nicht mehr produzierte [[HM-LC-Sw2PB-FM_Schaltaktor_mit_Tasteraufsatz_2fach]]
* Gerne wird diese Komponente auch ersetzt durch normale Taster und dem [[HM-LC-SW2-FM_Schaltaktor_2-fach_UP]]

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

Datei:HM-LC-Sw2PBU-FM Front.jpg

2017-02-04T21:00:42Z

Moontear:

HM-LC-Sw1PBU-FM Unterputz-Schaltaktor 1-fach

2017-02-04T20:59:19Z

Moontear: Frontalansicht des Schalters als Screenshot hinzugefügt

{{Infobox Hardware|Bild=HM-LC-Sw1PBU-FM_Front.jpg
|Bildbeschreibung=HM-LC-Sw1PBU-FM Unterputz-Schaltaktor 1-fach für Markenschalter
|HWProtocol=HomeMatic
|HWType=Aktor / Sender
|HWCategory=HomeMatic
|HWComm=868,3MHz
|HWChannels=1
|HWVoltage=230V
|HWPowerConsumption=0,5W (Standby)
|HWPoweredBy=Netz
|HWSize=71x71x37 mm
|HWDeviceFHEM=[http://fhem.de/commandref.html#CUL_HM CUL_HM]
|HWManufacturer=eQ-3}}

[[HM-LC-Sw1PBU-FM Unterputz-Schaltaktor 1-fach]] ist ein einkanaliger Funk-Schaltaktor "für Markenschalter", der mittels entsprechender Installationsadapter mit Tasterwippen diverser renommierter Hersteller versehen werden kann und sich dadurch nahtlos in bestehende Elektroinstallationen einfügt.

== Features ==
Das besondere an diesem Schalter ist, dass er den vorhandenen Unterputzeinsatz vollständig ersetzt. Dabei kann die Wippe des vorhandenen Schalters - je nach Hersteller - mit einer entsprechenden Adapterplatte weiterverwendet werden.

Es handelt sich hierbei nur um einen Aktor. Es ist nicht möglich die Taster mit anderen Homematic Geräten zu peeren. Man kann nur andere Taster mit dem Aktor peeren und diesen fernsteuern.

== Technische Daten ==

{|
| Art
| Unterputz
|-
| Typ
| 1fach
|-
| Stand-by-Verbrauch
| 0,5 W (lt. Bedienungsanleitung, S. 31, Stand 02/2012, 1 W)
|-
| Versorgungsspannung
| 230 V
|-
| Abmessungen (B x H x T)
| 71 x 71 x 37 mm
|-
| Farbe
| Grau
|-
| Max. Schaltleistung
| 1000 W
|-
| Relaistyp
| Wechsler
|-
| Funkfrequenz
| 868,3 MHz
|-
| Empfängerklasse
| SRD Class 2
|-
| Sicherung (intern)
| Rundsicherung 5 A, träge
|-
| Max. Sendeleistung
| 10 mW
|-
| IP-Schutzgrad
| IP 20
|-
| Umgebungstemperaturbereich
| 5–35 °C
|}

== Hinweise zur Hardware-Installation ==
Der vorhandene Schalter muss ersetzt werden. Dabei sind ein paar Dinge zu beachten:

* Der (neue) Schalter benötigt neben dem L-Leiter auch einen N-Leiter für die Stromversorgung.
* Die Befestigung ist nicht wie bei dem System z.B. von Merten durch spreizen von Klammern möglich. Der Schalter muss in die Löcher in der Dose geschraubt werden (Schrauben im Lieferumfang enthalten).
* Die "Frontplatte" bzw. der Befestigungsrahmen ist etwas dicker, als der Rahmen eines normalen Schalters. Dadurch kann es sein, dass der vorhandene Rahmen des Schalters nicht mehr ganz an der Wand anliegt.
* Um die bereits vorhandene Schalter-Wippe weiter nutzen zu können, muss ein passender Adapter verwendet werden.

{{Randnotiz|RNText='''Info zum Bausatz'''
Das Gerät ist als Bausatz verfügbar, es sind die folgenden bedrahteten Bauteile einzulöten:
* 6 Kondensatoren
* 3 Stiftleisten/Fassungen (insgesamt 16 Pole)
* 1 Spannungsregler, 1 Diode
* 1 Relais (8 Pole)
* 1 Induktivität
* 1 Widerstand, 1 Varistor
Die zu lötenden Bauteile sind relativ unproblematisch, die Lötstellen befinden sich jedoch in drei Fällen sehr nah an bzw. zwischen vorbestückten SMD-Bauteilen.}}
== Hinweise zum Betrieb mit FHEM ==
Das [[Pairing (HomeMatic)|Pairing]] sollte wie in [[HomeMatic Devices pairen]] beschrieben durchgeführt werden.

=== FHEM Config-Auszug ===
Ein exemplarischer Auszug aus der [[Konfiguration]]:

<pre>
define LichtWohnzimmer CUL_HM 197764
attr LichtWohnzimmer devInfo 010100
attr LichtWohnzimmer firmware 2.1
attr LichtWohnzimmer hmClass receiver
attr LichtWohnzimmer model unknown
attr LichtWohnzimmer room Wohnzimmer
attr LichtWohnzimmer serialNr JEQ0xxxxxx
attr LichtWohnzimmer 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>

Zusätzliche Funktionen wie ein direkter Zugriff auf die integrierten Taster (self01 und self02) des Schalters können durch Programmieren der [[HomeMatic_Register_programmieren | HomeMatic Register]] realisiert werden.

Dabei entspricht self01 dem Ausschalter des Wippschalters und self02 dem Einschalter des Wippschalters. Settings, die man also für den self01 Schalter einstellt, werden beim Ausschalten des Lichts (im Standard) angewandt und umgekehrt.

=== Log-Auszug ===
In FHEM ist nach dem Schalten des HM-LC-Sw1PBU-FM folgendes Log zu sehen:
<pre>
2012-06-05_00:09:22 LichtWohnzimmer deviceMsg: off
2012-06-05_00:09:22 LichtWohnzimmer off
2012-06-05_07:40:51 LichtWohnzimmer on
2012-06-05_07:40:51 LichtWohnzimmer deviceMsg: on
</pre>

Beim Einrichten des Schalters kommt folgender Auszug (Stand: 06.2012)
<pre>
2012.06.04 23:12:27 2: CUL_HM pair: CUL_HM_switch_197764 is a switch, model unknown serialNr JEQ0xxxxxx
</pre>

=== Funktion als Treppenlichtschalter ===
Um dafür zu sorgen, dass z.B. ein durch den HM-LC-Sw1PBU-FM eingeschaltetes Licht automatisch von FHEM nach 10 Minuten ausgeschaltet wird, kann folgende Definition verwendet werden:
:<code>define Beleuchtung_an notify Beleuchtung:on* define Beleuchtung_aus at +00:10:00 set Beleuchtung off </code>
Das Licht kann auch direkt über den Schalter nach 10 Minuten ausgeschaltet werden. Dies hat den Vorteil, dass die Funktion auch ohne FHEM funktioniert und keinen Funkverkehr verursacht. Wert ist in Sekunden also 60*10 für 10 Minuten. Es gibt zwei Schaltoperationen long press (lg) und short press (sh), short press ist ein kurzes antippen, long press ist den Schalter für ca. 1 Sekunde oder mehr gedrückt halten.
set <device> regSet shOnTime 600 self01
set <device> regSet lgOnTime 600 self01
set <device> regSet shOnTime 600 self02
set <device> regSet lgOnTime 600 self02

=== Workaround um den Taster in FHEM zu nutzen ===
Man kann den Taster in der Originalfirmware nicht mit anderen Geräten peeren. Allerdings kann man mit folgendem Workaround den Taster in FHEM nutzen. Das hat jedoch eine Verzögerung zwischen drei und acht Sekunden zur Folge. Dabei ist es trotzdem möglich, den Aktor per FHEM oder gepeertem Gerät weiter zu steuern. Der Taster beeinflusst den Aktor nicht mehr. Das ganze funktioniert, weil der HM-LC-Sw1PBU-FM bei jedem Tastendruck das reading für state aktualisiert, auch wenn sich der Wert nicht ändert.

Zuerst setzt man ein event auf event-on-change-reading:

attr HM-LC-Sw1PBU-FM event-on-change-reading state
attr HM-LC-Sw1PBU-FM event-on-update-reading state

Weiterhin wird der Schalter deaktiviert (hier nur für kurzen Tastendruck; mit lgSwJtXXX wird dieser Effekt auch für den langen Tastendruck erzielt):
set HM-LC-Sw1PBU-FM regSet intKeyVisib visib
set HM-LC-Sw1PBU-FM getConfig
set HM-LC-Sw1PBU-FM regSet prep shSwJtOff off self01
set HM-LC-Sw1PBU-FM regSet prep shSwJtOn on self01
set HM-LC-Sw1PBU-FM regSet prep shSwJtOff off self02
set HM-LC-Sw1PBU-FM regSet exec shSwJtOn on self02

Nun setzt man einen Notify auf das Reading:
:<code>define HM-LC-Sw1PBU-FM-TasterPressed notify HM-LC-Sw1PBU-FM {set YourOtherDevice toggle}</code>

=== Alternative Firmware ===
Um die beiden Taster als Remote und den Aktor getrennt zu nutzen gibt es alternative Firmware, deren Funktion und Benutzung auf der Seite [[HM-LC-Sw1PBU-FM Alternative Firmware]] im Detail beschrieben ist.

=== Schalter immer toggeln lassen ===
Im Werkszustand schaltet die Wippe bei Druck auf der einen Seite ein, auf der anderen Seite aus. Möchte man, dass bei jedem Tastendruck einfach der Zustand geändert wird, kann man das wie folgt erreichen (unten nur für den kurzen Tastendruck dargestellt):
set HM-LC-Sw1PBU-FM regSet intKeyVisib visib
set HM-LC-Sw1PBU-FM getConfig
set HM-LC-Sw1PBU-FM regSet shActionType jmpToTarget self01
set HM-LC-Sw1PBU-FM regSet shSwJtOn dlyOff self01
set HM-LC-Sw1PBU-FM regSet shSwJtOff dlyOn self01
set HM-LC-Sw1PBU-FM regSet shSwJtDlyOn on self01
set HM-LC-Sw1PBU-FM regSet shSwJtDlyOff off self01
set HM-LC-Sw1PBU-FM regSet shActionType jmpToTarget self02
set HM-LC-Sw1PBU-FM regSet shSwJtOn dlyOff self02
set HM-LC-Sw1PBU-FM regSet shSwJtOff dlyOn self02
set HM-LC-Sw1PBU-FM regSet shSwJtDlyOn on self02
set HM-LC-Sw1PBU-FM regSet shSwJtDlyOff off self02

Um den Werkszustand bezüglich Schaltwippe wiederherzustellen (eine Seite schaltet aus, die andere wieder ein) entsprechen folgende Einstellungen dem Werkszustand:
set <device> regSet shSwJtOn dlyOff self01
set <device> regSet shSwJtOff off self01
set <device> regSet shSwJtDlyOn off self01
set <device> regSet shSwJtDlyOff off self01
set <device> regSet shSwJtOn on self02
set <device> regSet shSwJtOff dlyOn self02
set <device> regSet shSwJtDlyOn on self02
set <device> regSet shSwJtDlyOff on self02

=== on-for-timer Ersatz ===
Der HM-LC-Sw1PBU-FM kennt kein <code>set on-for-timer</code>. Um den HM-LC-Sw1PBU-FM trotzdem für einige Zeit anschalten zu können (z. B. wenn ein Fensteröffner dranhängt und das Fenster nur für eine gewisse Zeit geöffnet werden soll), muss ein Button der vccu mit dem HM-LC-Sw1PBU-FM gepeered werden:
set vccu_Btn4 peerChan 0 HM-LC-Sw1PBU-FM dual set

Danach wären (in diesem Fall mit vccu_Btn4) die virtuellen Buttons 4 und 5 mit dem HM-LC-Sw1PBU-FM gepeered. Das Fenster könnte dann über <code>set vccu_Btn4 press short</code> für die vorher über <code>set HM-LC-Sw1PBU-FM regSet shOnTime [Dauer] vccu_Btn4</code> die Öffnungszeit eingestellt werden kann.

== Links ==
* Anleitung (PDF {{DocLink|elv|/Assets/Produkte/10/1030/103029/Downloads/103029_FunkSchaltaktor_um.pdf}})
* Produktwebseite bei [http://www.elv.de/output/controller.aspx?cid=74&detail=10&detail2=37991 ELV]
* [[HM-LC-Sw1PBU-FM Alternative_Firmware|Alternative Firmware]]

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

Datei:HM-LC-Sw1PBU-FM Front.jpg

2017-02-04T20:58:02Z

Moontear: HM-LC-Sw1PBU-FM Unterputz-Schaltaktor 1-fach für Markenschalter

HM-LC-Sw1PBU-FM Unterputz-Schaltaktor 1-fach für Markenschalter