Das Modul 57_SSCal steht momentan nur als Download aus dem contrib (DS_Starter) zur Verfügung.

Der aktuelle Stand kann einfach per Download mit diesem Befehl in der FHEM Kommandozeile bezogen werden. Bitte so komplett mit den Ausführungszeichen am Anfang und Ende eingeben:

 "wget -qO ./FHEM/57_SSCal.pm https://svn.fhem.de/fhem/trunk/fhem/contrib/DS_Starter/57_SSCal.pm"

Danach FHEM restarten.

Zweckbeschreibung

SSCal
Zweck / Funktion
	Integration des Synology Calendar Servers
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE
Support (Forum)	Unterstützende Dienste
Modulname	57_SSCal.pm
Ersteller	DS_Starter
	Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

Mit diesem Modul erfolgt die Integration des Synology Calendar Servers in FHEM. Die Verbindung zum Kalenderserver erfolgt über eine Session ID nach erfolgreichem Login. Anforderungen/Abfragen des Servers werden intern in einer Queue gespeichert und sequentiell abgearbeitet. Dadurch gehen Kalenderabfragen auch dann nicht verloren, wenn der Synology Kalender zeitweise nicht zur Verfügung stehen sollte. Die Kalendereinträge werden im Klartext als Blockeinträge in den Readings aufgelistet. Der Synology Calendar Server ist für den Synology Server Besitzer ein Teil einer private Cloud Lösung.

Definition eines Synology Kalenderdevices

initiale Definition

Die Definition erfolgt mit:

define <Name> SSCal <Adresse Synology Server> [Port] [Protokoll]

Die Angaben Port und Protokoll sind optional, per default werden Port=5000 und Protokoll=http verwendet.

Port: Port der Synology Diskstation (default 5000)
Protokoll: Protokoll zur Kommunikation mit dem Kalender-Server, http oder https (default http)

Beispiel mit HTTPS:

define SynChatBot SSChatBot 192.168.2.10 5001 https

Nach der Definition des Devices gibt es zunächst nur den Set-Befehl credentials.

Kalenderabruf durchgeführt

Mit dem Befehl:

set <name> credentials <User> <Passwort>

ist im Kalender-Device der für den Kalenderzugriff verwendete Nutzer und dessen Paßwort zu setzen.

Hinweis:
Der Nutzer muß Mitglied der Administrator-Group auf der Synology sein und muß zusätzlich auch die entsprechend benötigte Berechtigung zum Lesen und/oder Schreiben des/der beabsichtigten Kalender haben. Die Kalenderberechtigungen können direkt in der Synology Kalenderapplikation eingestellt werden.

Sind die Credentials korrekt, werden die auf der Synology verfügbaren (und für den Nutzer freigegeben) Kalender automatisch abgerufen. Dieser Vorgang ist durch den state running und dem OPMODE listcal in den Internals gekennzeichnet. Nach einem erfolgreichen Abruf, der am Anfang etwas dauern kann, springt der Status des Devices auf done. Damit ist das Kalenderdevice grundsätzlich einsatzbereit.

Kalender auswählen und Einträge abrufen

Popup von getCalendars

Nach der initialen Definition des Kalenderdevices muss ein oder mehrere Kalender ausgewählt werden, deren Termine (Events) abgerufen werden sollen. Welche Kalender erkannt wurden, kann mit dem Befehl

get <name> getCalendars

ermittelt werden.

Mit dem Attribut usedCalendars wählt man den/die relevanten Kalender über ein Popup aus. Alternativ kann dem calEventList-Befehl die abzurufende Kalenderliste direkt mitgegeben werden.

Ohne Änderung der Zeitabgrenzung werden die Termine 5 Tage vor und 5 Tage nach dem aktuellen Datum abgerufen. Um diese Zeitgrenzen zu verändern, werden die Attribute cutOlderDays bzw. cutLaterDays verwendet.

Mit dem Befehl:

set <name> calEventList [Kalenderliste]

Kalendereinträge abgerufen

werden Kalendereinträge manuell abgerufen. Die optionale Kalenderliste ist eine durch Komma getrennte Liste von abzurufenden Kalendern. Die Kalendernamen können Leerzeichen enthalten, z.B.:

set <name> calEventList Heikos Kalender,Abfall

Im Standard werden sowohl die einmaligen, als auch wiederkehrenden Events abgerufen und dargestellt. Möchte man die wiederkehrenden Events vom Abruf ausschließen, muss das Attribut showRepeatEvent explizit auf false gestellt werden.

Alle Abrufaufgaben werden zunächst in eine Queue eingestellt, die sequentiell abgearbeitet wird. Sollte der Synology Kalender zum Beispiel während einer Wartung temporär nicht verfügbar sein, erfolgt eine Wiederholung der anstehenden Aufgaben nach einer gewissen Wartezeit. Diese Wartezeit vergrößert sich mit zunehmenden Fehlversuchen.

Wurde für eine Abrufaufgabe ein dauerhafter Fehler diagnostiziert, wird diese Aufgabe von der weiteren Abarbeitung ausgeschlossen und verbleiben zur Dokumentation in der Queue (siehe auch set <name> listSendqueue).

Das Reading QueueLenth zeigt die aktuele Queue-Länge an. Sollten die Einträge nicht auf "0" abgebaut werden, sollte mit set <name> listSendqueue die Queue angeschaut und analysiert werden durch welche Fehlerzustände die Einträge nicht abgearbeitet werden können.

non-blocking Verarbeitung

Das Kalendermodul ist non-blocking implementiert. In der Definition des Devices sollte die IP-Adresse der Synology angegeben werden. Sollte statt dessen ein DNS-Name verwendet werden, ist darauf zu achten im global Device einen validen DNS-Server im Attribut dnsServer zu hinterlegen.

In Abhängigkeit der Menge abgerufener Kalender und Termine kann allerdings die Aufbereitung der Daten sehr aufwändig sein und FHEM dennoch blockieren. Um das zu verhindern, kann das Parsing der Kalenderdaten in einen Hintergrundprozess verlagert werden. Dazu ist das Attribut asyncMode=1 zu setzen.

regelmäßiger automatischer Datenabruf

Über das Attribut interval wird ein regelmäßigen Abruf der Kalendereinträge ermöglicht. Es sind die Sekunden zwischen den Abrufen anzugeben. Mit 0 wird der automatische Datenabruf ausgeschaltet. Gleiches gilt wenn das Attribut wieder gelöscht wird.

Im Reading nextUpdate wird der Modus "Automatic" und die Zeit des nächsten Abrufes dargetellt, z.B.:

 nextUpdate  Automatic - next polltime: 09:49:59

FHEM Eventgenerierung

Je nach Umfang der abgerufenen Daten können sehr viele Readings erstellt werden. Um eine zu umfangreiche Eventgenerierung in FHEM zu verhindern, ist nach der Definition des Kalenderdevices das Attribut event-on-update-reading voreingestellt auf:

.*Summary.*,state

Es werden demzufolge nur Events für die Terminzusammenfassung und für state erzeugt. Der User kann die Einstellung natürlich seinen Erfordernissen entsprechend anpassen. Soll für alle Readings ein Event erstellt werden, muss event-on-update-reading auf .* eingestellt werden.

Schema der erzeugten Readings

Die Termine der abgerufenen Kalender werden in Blöcken erzeugt. Jeder Block steht für einen Termin, dessen einzelne Eigenschaften mit einer laufenden Nummer vor dem Readingsnamen gekennzeichnet ist.

Diese laufende Nummer ist für den jeweiligen Readingnamen immer gleich. Da es für einnen Termin eine oder auch mehrere Erinnerungstermine geben kann, wird das Reading notifyDateTime zusätzlich mit einem laufenden Index angeführt.

Schema der Readings

Das allgemeine Schema der erzeugten Readings ist:

<Blocknummer>_<Readingsnummer>_<Readingsname>

Zum Beispiel für die Anfangszeit und Endezeit eines Termins:

0_02_Begin 2020-01-15 09:30:00
0_03_End   2020-01-15 10:30:00

Das Reading notifyDateTime wird noch um einen Index ergänzt:

<Blocknummer>_<Readingsnummer>_<Index>_<notifyDateTime>

Zum Beispiel:

0_14_0_notifyDateTime 2020-01-15 09:25:00
0_14_1_notifyDateTime 2020-01-15 03:30:00
0_14_2_notifyDateTime 2020-01-14 09:30:00
0_14_3_notifyDateTime 2020-01-12 09:30:00
0_14_4_notifyDateTime 2020-01-11 09:30:00

Set-Befehle

calEventList: Die Termine der ausgewählten Kalender werden abgerufen. Die relevanten Kalender werden im Attribut usedCalendars angegeben. Alternativ kann ein oder mehrere Kalender dem Befehl als eine durch Komma getrennte Liste direkt übergeben werden, z.B.:

set <name> calEventList Heikos Kalender,Abfall

Die Kalendernamen können Leerzeichen enthalten. Welche Kalender erkannt wurden, kann mit dem Befehl

get <name> getCalendars

ermittelt werden.

credentials

Speicherung der Zugangsdaten.

set <name> credentials User Passwort

eraseReadings: Löscht alle Kalenderreadings

listSendqueue: Zeigt alle Einträge in der Sendqueue. Die Queue ist normalerweise nur kurzfristig gefüllt, kann aber im Problemfall dauerhaft Einträge enthalten. Dadurch kann der bei der jeweiligen Abrufaufgabe aufgetretene Fehler ermittelt werden.

logout: Der User wird ausgeloggt und die Session beendet

purgeSendqueue

löscht Einträge in der Sendequeue. Es stehen verschiedene Optionen ja nach Situation zur Verfügung:

-all- = löscht alle in der Sendequeue vorhandenen Einträge

-permError- = löscht alle Einträge, die durch einen permanenten Error von der weiteren Verarbeitung ausgeschlossen sind

-<Index>- = löscht einen eindeutigen Eintrag der Sendequeue

restartSendqueue: Die Abarbeitung der Einträge in der Sendequeue wird manuell neu angestoßen. Dies ist normalerweise nicht notwendig. Die Sendequeue wird bei der Initialisierung jeder neuen Aufgabe implizit neu gestartet.

Get-Befehle

getCalendars: Ruft die auf der Synology vorhandenen Kalender ab und öffnet ein Popup mit Informationen über die jeweiligen Kalender.

storedCredentials: zeigt die gespeicherten User/Passwort Kombination

versionNotes: Zeigt Informationen und Hilfen zum Modul

Attribute

asyncMode: Wenn "1" wird das Datenparsing in einen Hintergrundprozess ausgelagert und vermeidet Blockierungssituationen.

cutOlderDays

Kalendereinträger älter als die angegeben Tage werden von der Verarbeitung ausgeschlossen (default: 5)

attr <name> cutOlderDays 30

cutLaterDays

Kalendereinträger später als die angegeben Tage werden von der Verarbeitung ausgeschlossen (default: 5)

attr <name> cutLaterDays 90

interval

Automatischer Abrufintervall der Kalendereintträge in Sekunden. Ist "0" agegeben, wird kein automatischer Datenabruf ausgeführt. Soll jede Stunde die Einträge der gewählten Kalender abgerufen werden, wird das Attribut wie folgt gesetzt:

attr <name> interval 3600

loginRetries: Anzahl der Versuche für das inititiale User login (default: 3)

showRepeatEvent: Wenn "true", werden neben einmaligen Events ebenfalls wiederkehrende Events ausgewertet. (default: true)

showPassInLog: Wenn "1", wird das Passwort bzw. die SID im Log mit angezeigt. (default: 0)

timeout: Timeout für den Datenabruf in Sekunden. (default: 20)

usedCalendars

Auswahl der abzurufenden Kalender über ein Popup. Die Liste der Kalender wird beim Start des Moduls initial gefüllt, kann danach aber ebenfalls durch den Befehl "get <name> getCalendars" manuell ausgeführt werden. Wurde noch kein erfolgreicher Kalenderabruf ausgeführt, enthält dieses Attribut lediglich den Eintrag

--wait for Calendar list--

Beschränkungen und Known Bugs

Zur Zeit ist nur die Verarbeitung der Terminkalender implementiert. Die Berücksichtigung von Aufgabenlisten erfolgt zu einem späteren Zeitpunkt.

Links

Forumthread zu diesem Modul: https://forum.fhem.de/index.php/topic,106963.0.html
Synology KnowldgeBase: https://www.synology.com/de-de/knowledgebase/DSM/help/Calendar/calendar_desc