FHEMWiki - Benutzerbeiträge [de]

DbRep - Reporting und Management von DbLog-Datenbankinhalten

2024-05-26T09:13:41Z

Dora71: /* (regelmäßiges) Löschen von Datenbanksätzen */ at Befehl auf täglich geändert

{{Infobox Modul
|ModPurpose=Reporting und Management von DbLog-Datenbankinhalten
|ModType=h
|ModCmdRef=DbRep
|ModForumArea=Automatisierung
|ModTechName=93_DbRep.pm
|ModOwner=DS_Starter ({{Link2FU|16933|Forum}}/[[Benutzer Diskussion:DS Starter|Wiki]])}}

== Zweck und Einsatz des Moduls ==
Zweck des Moduls ist es, den Inhalt von [[DbLog]]-Datenbanken nach bestimmten Kriterien zu durchsuchen, zu managen, das Ergebnis hinsichtlich verschiedener Aggregationen auszuwerten und als Readings darzustellen. Die Abgrenzung der zu berücksichtigenden Datenbankinhalte erfolgt durch die Angabe von Device, Reading und die Zeitgrenzen für Auswertungsbeginn bzw. Auswertungsende.

Alle Datenbankoperationen werden nichtblockierend ausgeführt. Die Ausführungszeit der (SQL)-Hintergrundoperationen kann optional ebenfalls als Reading bereitgestellt werden (siehe Attribute).
Alle vorhandenen Readings werden vor einer neuen Operation gelöscht. Durch das Attribut "readingPreventFromDel" kann eine Komma separierte Liste von Readings angegeben werden die nicht gelöscht werden sollen.

'''Zur Zeit ist das Modul durch folgende Leistungsmerkmale gekennzeichnet:'''

* Selektion und Anzeige aller Datensätze innerhalb einstellbarer Zeitgrenzen.
* Darstellung der Datensätze einer Device/Reading-Kombination innerhalb einstellbarer Zeitgrenzen.
* Selektion der Datensätze unter Verwendung von dynamisch berechneter Zeitgrenzen zum Ausführungszeitpunkt.
* Dubletten-Hervorhebung bei Datensatzanzeige (fetchrows)
* Berechnung der Anzahl von Datensätzen einer Device/Reading-Kombination unter Berücksichtigung von Zeitgrenzen und verschiedenen Aggregationen.
* Die Berechnung von Summen-, Differenz-, Maximum-, Minimum- und Durchschnittswerten numerischer Readings in Zeitgrenzen und verschiedenen Aggregationen.
* Speichern von Summen-, Differenz- , Maximum- , Minimum- und Durchschnittswertberechnungen in der Datenbank
* Löschung von Datensätzen. Die Eingrenzung der Löschung kann durch Device und/oder Reading sowie fixer oder dynamisch berechneter Zeitgrenzen zum Ausführungszeitpunkt erfolgen.
* Export von Datensätzen in ein File im CSV-Format.
* Import von Datensätzen aus File im CSV-Format.
* Umbenennen von Device/Readings in Datenbanksätzen
* Änderung von gespeicherten Reading-Werten (VALUES) in der Datenbank (changeValue)
* automatisches Umbenennen (Autorename) von Device-Namen in Datenbanksätzen und DbRep-Definitionen nach FHEM "rename" Befehl (siehe [[#DbRep_Agent_-_automatisches_.C3.84ndern_von_Device-Namen_in_Datenbanken_und_DbRep-Definitionen_nach_FHEM_.22rename.22 | DbRep-Agent]])
* Ausführen von beliebigen benutzerspezifischen SQL-Kommandos
* Backups der FHEM-Datenbank im laufenden Betrieb erstellen (MySQL, SQLite) mit/ohne Komprimierung der Dumpfiles
* senden und versionieren Dumpfiles nach dem Backup an einen FTP-Server
* Restore von SQLite-Dumps und MySQL serverSide-Backups
* Optimierung der angeschlossenen Datenbank (optimizeTables, vacuum)
* Ausgabe der existierenden Datenbankprozesse (MySQL)
* leeren der current-Tabelle
* Auffüllen der current-Tabelle mit einem (einstellbaren) Extrakt der history-Tabelle
* Bereinigung sequentiell aufeinander folgender Datensätze (sequentielle Dublettenbereinigung)
* Reparatur einer korrupten SQLite Datenbank ("database disk image is malformed")
* Übertragung von Datensätzen aus der Quelldatenbank in eine andere (Standby) Datenbank (syncStandby)
* Reduktion der Anzahl von Datensätzen in der Datenbank (reduceLog)
* Löschen von doppelten Datensätzen (delDoublets)
* Löschen und (Wieder)anlegen der für DbLog und DbRep benötigten Indizes (index)

Zur Aktivierung der Funktion "Autorename" wird dem definierten DbRep-Device mit dem Attribut "role" die Rolle "Agent" zugewiesen. Die Standardrolle nach Definition ist "Client". Mehr ist dazu im Abschnitt [[#DbRep_Agent_-_automatisches_.C3.84ndern_von_Device-Namen_in_Datenbanken_und_DbRep-Definitionen_nach_FHEM_.22rename.22 | DbRep-Agent]] beschrieben.

DbRep stellt dem Nutzer einen UserExit zur Verfügung. Über diese Schnittstelle kann der Nutzer in Abhängigkeit von frei definierbaren Reading/Value-Kombinationen (Regex) eigenen Code zur Ausführung bringen. Diese Schnittstelle arbeitet unabhängig von einer Eventgenerierung. Weitere Informationen dazu ist unter [[#Attribute | Attribut]] "userExitFn" beschrieben.

FHEM-Forum:
{{Link2Forum|Topic=53584|Message=452567|LinkText=Modul 93_DbRep - Reporting und Management von Datenbankinhalten (DbLog)}}

== Voraussetzungen und Abgrenzungen ==
Das Modul setzt den Einsatz einer oder mehrerer DBLog-Instanzen voraus (bisher getestet mit PostgreSQL, MySQL und SQLite). Es werden die Zugangsdaten dieser Datenbankdefinition aus der Konfiguration des entsprechenden DbLog-Device genutzt.
Es werden nur Inhalte der Tabelle "history" berücksichtigt (Ausnahme Kommando "sqlCmd").

Überblick, welche anderen Perl-Module DbRep verwendet:

::POSIX
::Time::HiRes
::Time::Local
::Scalar::Util
::DBI
::Blocking (FHEM-Modul)
::Encode

== Definition ==
<pre>
define <name> DbRep <Name der DbLog-instanz>
</pre>

(*) '''<Name der DbLog-Instanz>:''' Es wird der Name der auszuwertenden DbLog-Datenbankdefinition angegeben, '''NICHT''' die Datenbank selbst.

Aus Performancegründen sollte der Index "Report_Idx" in der Datenbank (Tabelle history) angelegt sein. Ab der DbRep-Version 8.20.0 kann dieser Index, sowie die für DbLog benötigten Indizes, verwaltet werden.
Der Index "Report_Idx" wird einfach mit dem DbRep-Befehl:

<pre>
set <name> index recreate_Report_Idx
</pre>

auf der Datenbank angelegt. Ist er bereits vorhanden, wird er gelöscht und erneut angelegt.

== Set ==
Siehe {{Link2CmdRef|Lang=de|Anker=DbRep-set}}

== Get ==
Siehe {{Link2CmdRef|Lang=de|Anker=DbRep-get}}

== Attribute ==
Siehe {{Link2CmdRef|Lang=de|Anker=DbRep-attr}}

== DbRep Agent - automatisches Ändern von Device-Namen in Datenbanken und DbRep-Definitionen nach FHEM "rename" ==

Mit dem Attribut "role" wird die Rolle des DbRep-Device festgelegt. Die Standardrolle ist "Client". Mit der Änderung der Rolle in "Agent" wird das Device veranlasst auf Umbenennungen von Geräten in der FHEM Installation zu reagieren.

Durch den DbRep-Agenten werden folgende Features aktiviert wenn ein Gerät in FHEM mit "rename" umbenannt wird:

* in der dem DbRep-Agenten zugeordneten Datenbank (Internal Database) wird nach Datensätzen mit dem alten Gerätenamen gesucht und dieser Gerätename in allen betroffenen Datensätzen in den neuen Namen geändert.

* in dem DbRep-Agenten zugeordneten DbLog-Device wird in der Definition das alte durch das umbenannte Device ersetzt. Dadurch erfolgt ein weiteres Logging des umbenannten Device in der Datenbank.

* in den existierenden DbRep-Definitionen vom Typ "Client" wird ein evtl. gesetztes Attribut "device = alter Devicename" in "device = neuer Devicename" geändert. Dadurch werden Auswertungsdefinitionen bei Geräteumbenennungen automatisch konsistent gehalten.

Mit der Änderung in einen Agenten sind folgende Restriktionen verbunden, die mit dem Setzen des Attributes "role = Agent" eingeschaltet und geprüft werden:

* es kann nur einen Agenten pro Datenbank in der FHEM-Installation geben. Ist mehr als eine Datenbank mit DbLog definiert, können ebenso viele DbRep-Agenten eingerichtet werden

* mit der Umwandlung in einen Agenten wird nur noch das Set-Komando "renameDevice" verfügbar sein sowie nur ein eingeschränkter Satz von DbRep-spezifischen Attributen zugelassen. Wird ein DbRep-Device vom bisherigen Typ "Client" in einen Agenten geändert, werden evtl. gesetzte und nun nicht mehr zugelassene Attribute glöscht.

Die Aktivitäten wie Datenbankänderungen bzw. Änderungen an anderen DbRep-Definitionen werden im Logfile mit verbose=3 protokolliert. Damit die renameDevice-Funktion bei großen Datenbanken nicht in ein timeout läuft, sollte das Attribut "timeout" entsprechend dimensioniert werden. Wie alle Datenbankoperationen des Moduls wird auch das Autorename nonblocking ausgeführt.

'''Beispiel''' für die Definition eines DbRep-Device als Agent:

<pre>
define Rep.Agent DbRep LogDB
attr Rep.Agent devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.Agent icon security
attr Rep.Agent role Agent
attr Rep.Agent room DbLog
attr Rep.Agent showproctime 1
attr Rep.Agent stateFormat { ReadingsVal("$name","state", undef) eq "running" ? "renaming" : ReadingsVal("$name","state", undef). " » ProcTime: ".ReadingsVal("$name","sql_processing_time", undef)." sec"}
attr Rep.Agent timeout 86400
</pre>

== hilfreiche SQL Statements ==

In dieser Rubrik werden SQL-Statements zusammengetragen, die User für ihre Auswertungen hilfreich fanden und anderen Anwendern zur Verfügung stellen.

Im Folgenden wird MySQL auch stellvertretend für MariaDB verwendet.

Die Statements können mit dem Befehl:

set <DbRep> sqlCmd <SQL-Statement>

ausgeführt werden. Für die Anpassung der Ergebnisdarstellung ist das Attribut '''sqlResultFormat''' verfügbar.

'''Hinweis: '''
Die Statements sind durch den DbRep-Modulautor nicht in jedem Fall getestet und dem Anwender obliegt vor Anwendung der Statements eine Datenbanksicherung durchzuführen um im Fehlerfall diese wieder herstellen zu können.

 
=== Den ersten und den letzten Wert eines Zeitraums selektieren bzw. deren Differenz (MySQL) ===
Beispiel 1:

Den ersten und letzten Wert der durch die DB-Variablen bestimmten Parameter ausgegeben.

Verwendete DB-Variablen (@) : begin_time, end_time, device und reading
SET @begin_time='2020-06-02 12:30:00';SET @end_time='2020-06-02 18:00:00';
SET @device='shelly02';SET @reading='energy_0';

SELECT TIMESTAMP,READING,round(VALUE/1000,0) AS VALUE
FROM (
(SELECT TIMESTAMP,READING,VALUE FROM history WHERE DEVICE = @device AND READING = @reading AND TIMESTAMP >= @begin_time and TIMESTAMP <= @end_time ORDER BY TIMESTAMP LIMIT 1)
UNION ALL
(SELECT TIMESTAMP,READING,VALUE FROM history WHERE DEVICE = @device AND READING = @reading AND TIMESTAMP >= @begin_time and TIMESTAMP <= @end_time ORDER BY TIMESTAMP DESC LIMIT 1)
) AS X1;

+---------------------+----------+-------+
| TIMESTAMP | READING | VALUE |
+---------------------+----------+-------+
| 2020-06-02 12:31:01 | energy_0 | 69 |
| 2020-06-02 16:31:05 | energy_0 | 73 |
+---------------------+----------+-------+
Beispiel 2:

Berechnung der Differenz vom 1. Beispiel

Verwendete DB-Variablen (@) : begin_time, end_time, device und reading

Hierbei ist zu beachten, dass die einzelnen Selects vertauscht wurden um den TIMESTAMP des ersten Select zu bekommen.

Die Subtraktion wurde durch "mal Minus Eins" des kleineren Wertes erreicht.<pre>
SET @begin_time='2020-06-02 12:30:00';SET @end_time='2020-06-02 18:00:00';
SET @device='shelly02';SET @reading='energy_0';

SELECT TIMESTAMP,READING,round(sum(VALUE)/1000,0) AS VALUE
FROM (
(SELECT TIMESTAMP,READING,VALUE FROM history WHERE DEVICE = @device AND READING = @reading AND TIMESTAMP >= @begin_time and TIMESTAMP <= @end_time ORDER BY TIMESTAMP DESC LIMIT 1)
UNION ALL
(SELECT TIMESTAMP,READING,(VALUE * -1) AS VALUE FROM history WHERE DEVICE = @device AND READING = @reading AND TIMESTAMP >= @begin_time and TIMESTAMP <= @end_time ORDER BY TIMESTAMP LIMIT 1)
) AS X1;

+---------------------+----------+-------+
| TIMESTAMP | READING | VALUE |
+---------------------+----------+-------+
| 2020-06-02 16:31:05 | energy_0 | 4 |
+---------------------+----------+-------+
</pre>
Die Formatierung

<pre>
round(sum(VALUE)/1000,0) AS VALUE
</pre>

sollte eventuell angepasst werden, da diese natürlich zum zu erwartenden Ergebnis passen muss.

=== Wieviel PV-Leistung wird von einem Starkverbraucher verwendet (MySQL) ===
Hier wurde versucht aus der Datenbank zu ermitteln, wieviel PV-Leistung für z.B. eine Wärmepumpe übrig bleibt.
Dabei wurde der grundlegenden Hausverbrauch als erstes in Abzug gebracht und der Rest mit dem Starkverbraucher verrechnet.
Natürlich kann man solch einen Report nur für einen Verbraucher verwenden, da man ja den Überschuss nur einem zuordnen kann.
Auch wird hier mit einem Stundendurchschnitt gerechnet, was somit als Näherung angesehen werden muss.
<pre>
1) Zuerst werden die einzelnen Daten für einen Tag zusammen gesucht
2) Jeder Datenteil wird mit einem Durchschnitt auf Stundenbasis berechnet
3) Im JOIN werden alle Datenteile für die relevanten Stunden zusammen geführt. Maßgeblich hierbei ist der Betrieb des Starkverbrauchers
zu dem Zeitpunkt wo auch PV-Leistung verfügbar war. Alle anderen Stunden tauchen danach nicht mehr auf. Ist es ein Hybrid WR mit
Speicher, dann kann auch in der Nacht eine Unterstützung erfolgen, was im Winter jedoch recht selten sein wird.
4) Es wird der restliche Hausverbrauch ermittelt. Achtung, der Starkverbraucher ist ein Verbraucher, weshalb die Leistung im Zähler
negativ summiert wird. Ein "+consumer_P" ist somit eine Summe mit einem negativen Wert ;-)
5) Im letzten SELECT werden dann die Daten final aufbereitet und formatiert, auch der prozentuale Anteil der PV-Leistung am gesamten
Starkverbrauch wird noch berechnet.
</pre>
<pre>
consumer = Das Zähler Device des Starkverbrauchers
consumer_P = negative Leistungsanzeige in Watt, da es ein Verbraucher ist!
generator = Das Wechselrichter Device
generator_P = Die AC Ausgangsleistung in Watt
Home_consumtion_P = Der Hausverbrauch inklusive des Starkverbrauchers in Watt (ebenfalls im generator Device)
</pre>
Die verwendeten Variablen lassen sich im DbRep als Attribut setzen
<pre>
sqlCmdVars
SET @date:='2022-12-07', @consumer:='StromZaehler_Heizung', @consumer_P:='SMAEM1901401955_Saldo_Wirkleistung', @generator:='WR_1', @generator_P:='SW_Total_AC_Active_P', @Home_Consumtion_P:='SW_Home_own_consumption';
</pre>
Hier nun das SELECT Statement
<pre>
SET @date:='2022-12-07',
@consumer:='StromZaehler_Heizung', @consumer_P:='SMAEM1901401955_Saldo_Wirkleistung',
@generator:='WR_1', @generator_P:='SW_Total_AC_Active_P', @Home_Consumtion_P:='SW_Home_own_consumption';

SELECT
X.HOUR,
cast(X.generator_P AS decimal(7,2)) AS generator_P,
cast(X.Home_Consumption AS decimal(7,2)) AS Home_Consumption,
cast(X.PV_after_Home_Consumtion AS decimal(7,2)) AS PV_after_Home_Consumtion,
cast(X.consumer_P AS decimal(7,2)) AS consumer_P,
if(consumer_P+PV_after_Home_Consumtion <= 0,cast(round(abs(consumer_P+PV_after_Home_Consumtion),2) AS decimal(7,2)),0) AS from_Grid,
if(round(consumer_P+PV_after_Home_Consumtion,2) <= 0,round(abs(PV_after_Home_Consumtion*100/consumer_P),0),100) AS Percent
FROM (
SELECT
X1.HOUR,
generator_P,
round(Home_Consumtion_P+consumer_P,2) AS Home_Consumption,
if(Home_Consumtion_P+consumer_P-generator_P < 0,round(abs(Home_Consumtion_P+consumer_P-generator_P),2),0) AS PV_after_Home_Consumtion,
consumer_P
FROM (
SELECT
hour(TIMESTAMP) AS HOUR,
round(avg(value),2) AS consumer_P
FROM history
WHERE
TIMESTAMP > @date and TIMESTAMP < DATE_ADD(@date,INTERVAL 1 DAY) AND
DEVICE = @Consumer AND
READING = @consumer_P
GROUP BY 1
) X1
JOIN (
SELECT
hour(TIMESTAMP) AS HOUR,
round(avg(value),2) AS generator_P
FROM history
WHERE
TIMESTAMP > @date AND TIMESTAMP < DATE_ADD(@date,INTERVAL 1 DAY) AND
DEVICE = @generator AND
READING = @generator_P AND
VALUE > 10
GROUP BY 1
) X2
JOIN (
SELECT
hour(TIMESTAMP) AS HOUR,
round(avg(value),2) AS Home_Consumtion_P
FROM history
WHERE
TIMESTAMP > @date and TIMESTAMP < DATE_ADD(@date,INTERVAL 1 DAY) AND
DEVICE = @generator AND
READING = @Home_Consumtion_P AND
VALUE > 10
GROUP BY 1
) X3
ON X1.HOUR = X2.HOUR
AND X1.HOUR = X3.HOUR
) X;
</pre>

=== Temperaturdifferenz eines Pufferspeichers über die Zeit ermitteln (MySQL) ===
Beispiel 1:

Temperaturdifferenz des Pufferspeichers über die Zeit in Minuten

<nowiki>Referenz zum DBRep : set [device] sqlSpecial readingsDifferenceByTimeDelta</nowiki>

Verwendete DB-Variablen (@) : device und reading, diff und delta werden für Berechnungen benötigt und sind bei erneutem Aufruf zurück zu setzen

Anmerkungen:

- Der Zeitraum wird in diesem Beispiel als die letzten 24 Stunden festgelegt

- Die Zeitdifferenz für die Änderung steht in der Spalte DELTA in Minuten

- In FHEM wurde mit event-on-change-reading ins DBLog geschrieben

- Bei dieser Ausgabe kann man erkennen, dass die Temperaturänderung im Wärmespeicher oft sehr klein ist, was ja auch so gewollt ist

- Um 14:00 Uhr beginnt die Wärmepumpe das Warmwasser wieder aufzuheizen<pre>
SET @device='Heizung';SET @reading='hotWaterTemperature';
SET @diff=0;SET @delta=NULL;

SELECT t1.TIMESTAMP,t1.READING,t1.VALUE,t1.DIFF,t1.DELTA
FROM
(
SELECT TIMESTAMP,READING,VALUE,
if(@diff = 0,NULL, cast((VALUE-@diff) AS DECIMAL(3,1))) AS DIFF,
@diff:=VALUE AS curr_V,
TIMESTAMPDIFF(MINUTE,@delta,TIMESTAMP) AS DELTA,
@delta:=TIMESTAMP AS curr_T
FROM history
WHERE DEVICE = @device AND
READING = @reading AND
TIMESTAMP >= NOW() - INTERVAL 1 DAY
ORDER BY TIMESTAMP
) t1;
+---------------------+---------------------+-------+------+-------+
| TIMESTAMP | READING | VALUE | DIFF | DELTA |
+---------------------+---------------------+-------+------+-------+
| 2020-06-04 10:05:20 | hotWaterTemperature | 46.5 | NULL | NULL |
| 2020-06-04 10:35:31 | hotWaterTemperature | 46.4 | -0.1 | 30 |
| 2020-06-04 11:00:31 | hotWaterTemperature | 46.2 | -0.2 | 25 |
snip...
| 2020-06-04 13:50:42 | hotWaterTemperature | 44.5 | -1.0 | 5 |
| 2020-06-04 13:55:42 | hotWaterTemperature | 44.0 | -0.5 | 5 |
| 2020-06-04 14:00:42 | hotWaterTemperature | 43.9 | -0.1 | 5 |
| 2020-06-04 14:10:42 | hotWaterTemperature | 41.7 | -1.8 | 5 |
snip...
| 2020-06-04 14:51:05 | hotWaterTemperature | 51.3 | 0.1 | 5 |
| 2020-06-04 17:01:15 | hotWaterTemperature | 51.2 | -0.1 | 130 |
snip...
| 2020-06-04 22:10:30 | hotWaterTemperature | 50.5 | -0.2 | 5 |
snip...
| 2020-06-05 11:30:45 | hotWaterTemperature | 46.1 | -0.1 | 25 |
+---------------------+---------------------+-------+------+-------+

</pre>Beispiel 2:

Summieren der Temperaturdifferenz auf Stundenbasis

Verwendete DB-Variablen (@) : device und reading, diff und delta werden für Berechnungen benötigt und sind bei erneutem Aufruf zurück zu setzen

Anmerkungen:

- Der Zeitraum wird in diesem Beispiel als die letzten 24 Stunden festgelegt

- Die Zeitdifferenz wird bei diesem Beispiel nicht ausgegeben

- Alle Differenzen nach der Vollen Stunde werden der nächsten Stunde zugeschlagen

- In FHEM wurde mit event-on-change-reading ins DBLog geschrieben

- Um 14:00 Uhr beginnt die Wärmepumpe das Warmwasser wieder aufzuheizen

- Bei diesem Wärmespeicher sind Temperaturschwankungen im Bereich von Null Komma irgendwas, als Messwert recht ungenau, was im Beispiel 1 zu der Vielzahl an Messwerten geführt hat. Durch Beispiel 2 auf Stundenbasis lässt sich bereits mehr erkennen. Hier wäre der Wärmepumpeneinsatz um 14:00 Uhr mit dem Pumpenvorlauf (-1.8) und der Lauf der Zirkulationspumpe um 8:00 und 8:30 Uhr zu sehen, was den Wärmespeicher um 1,2 Grad abgekühlt hat.<pre>
SET @device='Heizung';SET @reading='hotWaterTemperature';
SET @diff=0;SET @delta=NULL;

SELECT xTIMESTAMP AS TIMESTAMP,READING,xVALUE AS VALUE,xDIFF AS DIFF
FROM
(SELECT DATE_FORMAT(DATE_ADD(t1.TIMESTAMP,INTERVAL (IF(MINUTE(t1.TIMESTAMP) > 0, 60, 0)-MINUTE(t1.TIMESTAMP)) MINUTE),'%Y-%m-%d %H:00:00') AS xTIMESTAMP,
t1.READING,
round(t1.VALUE) AS xVALUE,
sum(t1.DIFF) AS xDIFF,
sum(t1.DELTA) AS xDELTA
FROM
(SELECT TIMESTAMP,READING,VALUE,
if(@diff = 0,NULL, cast((VALUE-@diff) AS DECIMAL(3,1))) AS DIFF,
@diff:=VALUE AS curr_V,
TIMESTAMPDIFF(MINUTE,@delta,TIMESTAMP) AS DELTA,
@delta:=TIMESTAMP AS curr_T
FROM history
WHERE DEVICE = @device AND
READING = @reading AND
TIMESTAMP >= NOW() - INTERVAL 1 DAY
ORDER BY TIMESTAMP
) t1
GROUP BY xTIMESTAMP WITH ROLLUP) x1

WHERE xDELTA IS NOT NULL AND
xTIMESTAMP IS NOT NULL;
+---------------------+---------------------+-------+------+
| TIMESTAMP | READING | VALUE | DIFF |
+---------------------+---------------------+-------+------+
| 2020-06-04 12:00:00 | hotWaterTemperature | 46 | -0.1 |
| 2020-06-04 13:00:00 | hotWaterTemperature | 46 | -0.4 |
| 2020-06-04 14:00:00 | hotWaterTemperature | 44 | -1.8 |
| 2020-06-04 15:00:00 | hotWaterTemperature | 51 | 7.4 |
| 2020-06-04 18:00:00 | hotWaterTemperature | 51 | -0.1 |
snip...
| 2020-06-05 07:00:00 | hotWaterTemperature | 48 | -0.3 |
| 2020-06-05 08:00:00 | hotWaterTemperature | 48 | -0.2 |
| 2020-06-05 09:00:00 | hotWaterTemperature | 48 | -1.2 |
| 2020-06-05 10:00:00 | hotWaterTemperature | 47 | -0.3 |
snip...
+---------------------+---------------------+-------+------+
</pre>

=== Alle aktuellsten readings eines Device im letzten Tagesverlauf (MySQL) ===
Beispiel :

Verwendete DB-Variablen (@) : device

Anmerkungen:

- Der Zeitraum wird in diesem Beispiel als die letzten 24 Stunden festgelegt

- In FHEM wurde mit event-on-change-reading ins DBLog geschrieben, wodurch nicht alle readings immer zeitlich in der DB aufeinander folgen oder einige im Zeitraum mehrfach geschrieben wurden. Mit diesem Aufruf erscheinen immer die letzten Aktualisierungen.

- Sollten einige readings nicht erscheinen, so wurden diese vor dem Zeitraum letztmalig aktualisiert. Mit "INTERVAL [n] DAY könnten diese eventuell auch noch gefunden werden. Bitte hier die Laufzeit beachten!<pre>
SET @device = 'Heizung';

SELECT t1.TIMESTAMP,t1.DEVICE,t1.READING,t1.VALUE
FROM history t1
INNER JOIN
(select max(TIMESTAMP) AS TIMESTAMP,DEVICE,READING
from history
where DEVICE = @device and
TIMESTAMP > NOW() - INTERVAL 1 DAY
group by READING) x
ON x.TIMESTAMP = t1.TIMESTAMP AND
x.DEVICE = t1.DEVICE AND
x.READING = t1.READING;
</pre>

 
=== Device / Reading Daten in eine CSV-Datei exportieren (MySQL) ===

Grundsätzlich gibt es für diesen Zweck das eingebaute Set-Kommando '''exportToFile'''.

Eine weitere Möglichkeit ist die Verwendung von spezifischen Datenbankkommandos, die mit Set '''sqlCmd''' ausgeführt werden können.

Im Beispiel wird ein CSV File geschrieben, welches die Daten des Devices 'SMA_Energymeter' enthält.
Wichtig ist, nicht zur Trennung von SQL-Befehlen dienende Semikolons durch Verdopplung zu escapen (z.B. im String "...TERMINATED BY ';;'...").

<pre>
SET @TS = DATE_FORMAT(NOW(),'_%Y_%m_%d');

SET @FOLDER = '/volume1/ApplicationBackup/';
SET @PREFIX = 'export';
SET @EXT = '.csv';

SET @CMD = CONCAT(" SELECT *
FROM `fhemtest`.`history`
WHERE `DEVICE`='SMA_Energymeter' AND TIMESTAMP > DATE_SUB(CURRENT_DATE(),INTERVAL 1 DAY)
INTO OUTFILE '",@FOLDER,@PREFIX,@TS,@EXT,"'
FIELDS ENCLOSED BY '\"'
TERMINATED BY ';;'
ESCAPED BY '\"'","
LINES TERMINATED BY '\r\n';;
");

PREPARE statement FROM @CMD;

EXECUTE statement;
</pre>

'''Hinweis:''' der verwendete Datenbank-User benötigt das '''FILE''' Recht.

 
=== Gewichtete Mittelwerte von Zeitreihen (MySQL) ===
Zeitreihen in FHEM sind Messwerte (z.B. Temperatur, Stromverbrauch, PV-Produktion ...), die i.A. nicht zu äquidistanten Zeitpunkten ermittelt und protokolliert werden, sondern nur bei Änderung der Messgröße. Für eine Zusammenfassung ("Aggregation") zum Zwecke statistischer Auswertung oder einfach zur Datenreduktion sollte daher bei einer Mittelwertbildung auf zeitlich gewichtete Mittelung zurückgegriffen werden. Ein interessierender Gesamtzeitraum wird dazu in einzelne Mittelungsintervalle (sogen. ''bins'') aufgeteilt, für die dann der gewichtete Mittelwert berechnet wird.

Die (non-blocking) DbRep-Funktion 'set averageValue' macht, in Verbindung mit den Attributen 'aggregation' (Auswahl einer Aggregationsperiode) und 'averageCalcForm'='avgTimeWeightMean' genau das. Dabei hat man als ''bin''-Länge 'minute', 'hour', 'day', 'week', 'month' und 'year' zur Verfügung.

Der folgende ''SQL-Query 1'' kennt als ''bin''-Längen auch Viertelstunden ('qhour'), Vierteltage ('qday') und Quartal ('qyear'). Die Parameter @sortformat=["minute"|"qhour"|"hour"|"qday"|"day"|"week"|"month"|"qyear"|"year"] und @weighted=["yes"|"no"] müssen vor Ausführung des Codes mit dem Attribut sqlCmdVars gesetzt werden, z.B.
set <Your_DbRep_device> sqlCmdVars SET @sortformat="hour", @weighted="yes", @count=<n>;

<div class="mw-customtoggle-query1 wikia-menu-button">'''''SQL-Query 1'' ein/ausblenden'''</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-query1>
SELECT
avgtim,
CASE @weighted
WHEN "yes" THEN
CAST((SUM(val * weight)/SUM(weight)) AS DECIMAL(12,4))
ELSE
CAST(sum(val) / count(val) AS DECIMAL(12,4))
END AS avrg
FROM (
SELECT
tim,
avgtim,
CASE @sortformat
WHEN "week" THEN
date_format(tim, "%Y-%u 00:00:00")
ELSE
avgtim
END AS grouptim,
CASE
WHEN avgtim!=nextavgtim THEN
to_seconds(nextavgtim)-to_seconds(tim)
WHEN avgtim!=preavgtim THEN
to_seconds(nexttim)-to_seconds(avgtim)
ELSE
to_seconds(nexttim)-to_seconds(tim)
END AS weight,
CASE
WHEN avgtim!=preavgtim THEN
CASE @weighted WHEN "yes"
THEN
CASE
WHEN avgtim!=nextavgtim THEN
(preval*(to_seconds(tim)-to_seconds(avgtim)) + val*(to_seconds(nextavgtim)-to_seconds(tim)))/
(to_seconds(nextavgtim)-to_seconds(avgtim))
ELSE
(preval*(to_seconds(tim)-to_seconds(avgtim)) + val*(to_seconds(nexttim)-to_seconds(tim)))/
(to_seconds(nexttim)-to_seconds(avgtim))
END
ELSE
val
END
ELSE
val
END AS val
FROM (
SELECT
tim,
nexttim,
val,
preval,
avgtim,
LAG(avgtim) OVER (ORDER BY tim) AS preavgtim,
LEAD(avgtim) OVER (ORDER BY tim) AS nextavgtim
FROM (
SELECT
timestamp AS tim,
LEAD(timestamp) OVER (ORDER BY timestamp) AS nexttim,
value AS val,
LAG(value) OVER (ORDER BY timestamp) AS preval,
CASE @sortformat
WHEN "minute" THEN
date_format(timestamp, "%Y-%m-%d %H:%i:00")
WHEN "qhour" THEN
concat(date_format(timestamp, "%Y-%m-%d %H:"),LPAD(15*(date_format(timestamp,"%i") div 15),2,"0"),":00")
WHEN "hour" THEN
date_format(timestamp, "%Y-%m-%d %H:00:00")
WHEN "qday" THEN
concat(date_format(timestamp, "%Y-%m-%d "),LPAD(6*(date_format(timestamp, "%H") div 6),2,"0"),":00:00")
WHEN "day" THEN
date_format(timestamp, "%Y-%m-%d 00:00:00")
WHEN "week" THEN
date_format(timestamp, "%Y-%m-%d 00:00:00")
WHEN "month" THEN
date_format(timestamp, "%Y-%m-01 00:00:00")
WHEN "qyear" THEN
concat(date_format(timestamp, "%Y-"),LPAD(3*(date_format(timestamp, "%m") div 3),2,"0"),"-01 00:00:00")
ELSE
date_format(timestamp, "%Y-01-01 00:00:00")
END AS avgtim
FROM
history WHERE TIMESTAMP BETWEEN §timestamp_begin§ AND §timestamp_end§ AND §device§ AND §reading§ ORDER BY timestamp
) select3
) select2
) select1 GROUP BY grouptim
</div>

Die Auswahl von ''device'', ''reading'' und Zeitraum erfolgt über die üblichen Attribute. Es darf nur ein ''device'' und ein ''reading'' gewählt werden. Für den Zeitraum btte nur ''timestamp_begin'' und ''timestamp_end'' nutzen.

Will man keine festen Zeitraster, kann man den Gesamtzeitraum auch einfach in eine Anzahl ''count'' von bins aufteilen. Dafür steht der Parameter @count im obigen sqlCmdVars statement (für Query 1 hat er keine Bedeutung).

<div class="mw-customtoggle-query2 wikia-menu-button">'''''SQL-Query 2'' ein/ausblenden'''</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-query2>
SELECT
tim,
CASE
WHEN @weighted="yes" THEN
CAST(sum(val * (to_seconds(nexttim)-to_seconds(tim))) / sum((to_seconds(nexttim)-to_seconds(tim))) AS DECIMAL(12,4))
ELSE CAST(sum(val) / count(val) AS DECIMAL(12,4))
END AS avrg
FROM (
SELECT
timestamp as tim,
value as val,
LEAD(timestamp) over (order by timestamp) nexttim,
truncate(@count * (to_seconds(timestamp)-to_seconds(§timestamp_begin§)) / (to_seconds(§timestamp_end§)-to_seconds(§timestamp_begin§)),0)/@count as avgtim
FROM
history WHERE TIMESTAMP BETWEEN §timestamp_begin§ AND §timestamp_end§ AND §device§ AND §reading§
) select1 group by avgtim
</div>

Zur Ausführung der Queries den Code entweder ins Eingabefeld hinter set sqlCmd (bzw. sqlCmdBlocking) kopieren und dann mit ''set'' ausführen, oder per ''set <Your_DbRep_device> sqlCmd <kopierter Code>'' in der FHEM Kommandozeile ausführen.

Getestet wurden diese MySQL Beispiele mit MariaDB 10.3

Siehe auch im Forum: https://forum.fhem.de/index.php/topic,53584.msg1254036.html#msg1254036

 

== Praxisbeispiele / Hinweise und Lösungsansätze für verschiedene Aufgaben ==
=== Definieren eines DbRep-Devices ===
[[Bild:DbRep_initialized.PNG|right|thumb|400px|]]

Das DbRep-Device wird bei der Definition mit der DbLog-Instanz verbunden, in deren angeschlossener Datenbank später die Auswertungen und Operationen stattfinden sollen. Es ist also nicht die Datenbank selbst, sondern das vorher definierte DbLog-Device anzugeben.
Die Definition erfolgt z.B. durch:

<pre>
define Rep.Energy DbRep LogDB #LogDB ist das zu verbindende DbLog-Device
</pre>

Bei der Definition werden die Zugangsdaten aus der DbLog-Instanz gelesen und das DbRep-Device mit der Datenbank verbunden. Nach der Definition ist der Status "initialized". Die Verbindung zur Datenbank wird mit der ersten abzuarbeitenden Aufgabe hergestellt. Das Verhalten kann mit dem '''Attribut fastStart''' beeinflusst werden.
Zu welcher Datanbank das DbRep-Device sich verbunden hat, zeigt das ''Internal'' DATABASE.

Damit ist das DbRep-Device grundsätzlich einsatzbereit, aber noch nicht praxistauglich. Werden keine weiteren Eingrenzungen angegeben, kann mit dem so definierten Device mit dem Befehl

<pre>
set Rep.Energy countEntries
</pre>

die gesamte Anzahl der Datensätze in der Datenbank ermittelt werden.
Für eine weitere Verwendung sind weitere ''Attribute'' zu setzen.
Um die Funktionen von "Rep.Energy" nur auf z.B. Datensätze in der Datenbank anzuwenden die "STP_5000" im Feld "DEVICE" enthalten, wird das '''Attribut''':

<pre>
attr Rep.Energy device STP_5000
</pre>

gesetzt. Weitere Begrenzungen der gerätespezifischen Selektion erfolgt durch das '''Attribut''' "reading". So wird durch

<pre>
attr Rep.Energy reading etotal
</pre>

[[Bild:Rep_configured.PNG|right|thumb|300px|]]
festgelegt, dass sich die (allermeisten) Operationen auf die Kombination aus dem "device STP_5000" und dem "reading etotal" beziehen.
Eine zeitliche Eingrenzung der Ergebnisse erfolgt durch die '''Attribute''' "timeDiffToNow", "timeOlderThan", "timestamp_begin", "timestamp_end".
In dem Beispiel sollen sich die Selektionsergebnisse immer auf die letzten 120 Minuten beziehen.
Dazu wird das Attribut

<pre>
attr Rep.Energy timeDiffToNow 7200 #Der Wert für timeDiffToNow ist in Sekunden anzugeben
</pre>

gesetzt. Es wird dynamisch bei jeder Operation "<Selektionsbeginn> = <aktuelle Zeit> - 3600s" berechnet und die Datensätze bis zu <aktuelle Zeit> berücksichtigt.
Die gesamten Datenbankoperationen und teilweise auch Auswertungen von Selektionen erfolgt mit Blockingcall im Hintergrund. Der Timeout für die Operationen ist per Default auf 86400 Sekunden gesetzt. Über das ''Attribut'' "timeout" kann es den eigenen Bedingungen angepasst werden. In dem Beispiel wird timeout auf 300s geändert um auch bei sehr großen Selektionen und Auswertungen nicht in einen timeout zu laufen.

<pre>
attr Rep.Energy timeout 300
</pre>

Um auch die Verarbeitungszeiten im Hintergrund als Reading anzeigen zu lassen wird mit mit dem ''Attribut''

<pre>
attr Rep.Energy showproctime 1
</pre>

erreicht.
Mit diesen Einstellungen ist das Device für den konfiguriert und man kann sich zum Beispiel mit

<pre>
set Rep.Energy fetchrows
</pre>

die Datensätze mit der Gesamtenergierzeugung "etotal" des Wechselrichters "STP_5000" die in den letzten 2 Stunden in die DB geschrieben wurden.
Nachdem der Befehl in der Gerätedetailsicht ausgeführt wurde, wechselt der state im DeviceOverview auf "running". Sobald im DeviceOverview "done" angezeigt wird sieht man die Ergebnisse nach einem Browserrefresh.
Bei der Ausführung einer erneuten Operation werden alle Readings gelöscht. Sollen bestimmte Readings davon ausgenommen werden, kann dem ''Attribut'' eine kommaseparierte Liste von zu schützenden Readings übergeben werden.

Allgemein wird empfohlen sich für jede Aufgabe eine separates DbRep-Device anzulegen und entsprechend zu konfigurieren anstatt die Einstellungen ständig den neuen Aufgaben anzupassen.
Um den Prozess zu vereinfachen, kann das einmal angelegte Device für eine neue Selektionsaufgabe (zum Beispiel die Datensätze eines SMA Energymeters anzuzeigen bzw. auszuwerten) auf ein neues DbRep-Device kopiert

<pre>
copy Rep.Energy Rep.SMAMeter
</pre>

und entsprechend angepasst werden.

'''Hinweis zur Eventgenerierung:''' 
Je nach genutzter Funktion können sehr viele Readings als Ergebnis generiert werden. Zum Beispiel können mit "fetchrows", wobei jedes Reading einer selektierte Zeile aus der Datenbank entspricht, durchaus mehrere hundert Readings entstehen.
Sollte man nicht durch die Attribute "event-on-update-reading" bzw. "event-on-change-reading" die Eventerzeugung auf nur relevante Readings begrenzt haben, können in diesem Fall ebenso viele Events enstehen die das System entsprechend belasten können. 
Deswegen wird empfohlen die '''Eventerzeugung sofort''' auf z.B. "state" zu '''begrenzen'''.

 
=== Ermittlung des monatlichen und durchschnittlichen Gasverbrauches mit Vaillant und eBusd MQTT ===

Es soll der monatliche Gasverbrauch in m3, kWh und Euro sowie der Durchnschnitt in Euro über die gewählten Monate ermittelt werden.

Die auswertenden Daten liegen als "Tics" vor. Es ist eine stetig steigende Zahl ohne Einheit. Sie wird als Reading aus einem Vaillant eBus-MQTT Device geloggt. eBusd liefert PrEnergySumHc2 und PrEnergySumHwc1.
Beide Werte werden als Summe im Reading '''1_Brenner_Energy_Summe''' zusammengeführt und geloggt.

[[Bild:Screenshot_2022-12-25_143631.png|right|thumb|400px|]]

Für die Bereitstellung diverser Hilfswerte zur Berechnung existiert ein Dummy-Device '''VaillantControlDummy'''.

Dieses Device enthält in User-Attributen folgende Werte:

* '''Brennwert_kWh/m3''' -> den Brennwert in kWh pro m3 lt. Angaben des Lieferanten
* '''Zustandszahl''' -> die Zustandszahl lt. Angaben des Lieferanten
* '''Multiplikator''' -> ein Faktor zur Umrechnung der geloggten Tics (1_Brenner_Energy_Summe) in m3
* '''Tarif''' -> der persönliche Tarif (Brutto) in €/kWh

Der Multiplikator wurde empirisch als Quotient aus den real verbrauchten m3 und den Tics über einem längeren Zeitraum ermittelt.
Das Ergebnis der Multiplikaktion von geloggten Tics und und Multiplikator ergibt die jeweilig verbrauchten m3. Dieser Wert
ist Toleranz/Fehler behaftet, hat sich aber in der Praxis als hinreichend genau zur Ermittlung des Gasverbrauchs erwiesen.

Das DbRep Device wird wie weiter oben beschrieben angelegt:

define Rep.gas.allmonths DbRep <DbLog-Devicename>

[[Bild:Screenshot_2022-12-25_143912.png|right|thumb|400px|]]

Die folgenden Attribute werden gesetzt um den auszuwertenden Zeitraum, sowie das auszuwertende Device und Reading in der Datenbank auszuwerten.
Die Werte für die Attribute sind natürlich dem persönlichen Umfeld anzupassen:

* '''device''' -> auszuwertendes Device (MQTT2_ebusd_bai)
* '''reading''' -> auszuwertendes Reading (1_Brenner_Energy_Summe)
* '''timestamp_begin''' -> Auswertungszeitraum Beginn (2022-10-01 00:00:00)
* '''timestamp_end''' -> Auswertungszeitraum Ende (current_year_end)
* '''aggregation''' -> month, d.h. der Auswertungszeitraum wird in Monatsscheiben aufgeteilt
* '''numDecimalPlaces''' -> die gwünschte Anzahl der Nachkommastellen im Ergebnis (0)
* '''diffAccept''' -> die akzeptierte Differenz von Diffenzwerten (1000000000), den Wert sehr hoch setzen um keine Datensätze von der Berechnung auszuschließen
* '''event-on-update-reading''' -> state,gas_.*
* '''eventMap''' -> /diffValue display:diffValuedisplay/ (für Verwendung in webCmd)
* '''webCmd''' -> diffValuedisplay

Wird das Device mit diesen Einstellungen gestartet, werden Readings der Form:

2022-10-31_07-05-03__MQTT2_ebusd_bai__1_Brenner_Energy_Summe__DIFF__2022-10
2022-11-30_08-38-18__MQTT2_ebusd_bai__1_Brenner_Energy_Summe__DIFF__2022-11
2022-12-25_12-29-47__MQTT2_ebusd_bai__1_Brenner_Energy_Summe__DIFF__2022-12

generiert. Sie liefern die Anzahl der Tics im jeweiligen Monat.

"Herzstück" zur Ermittlung der Zielwerte ist eine Perl Routine die im Attribut '''userExitFn''' hinterlegt wird:

<syntaxhighlight lang="perl">
{
if ($READING =~ /1_Brenner_Energy_Summe__DIFF/ && $VALUE ne '-') {
my $date = (split '__', $READING)[0];
my ($y,$m,$d) = $date =~ /^(\d{4})-(\d{2})-(\d{2})/x;

my $cdd = "VaillantControlDummy"; # Steuerungsdummy Device
my $mpk = AttrVal($cdd, 'Multiplikator', '0');
my $zz = AttrVal($cdd, 'Zustandszahl', '0'); # Zustandszahl lt. Lieferant
my $bw = AttrVal($cdd, 'Brennwert_kWh/m3', '0'); # Brennwert kWh/m3 lt. Lieferant
my $tarf = AttrVal($cdd, 'Tarif', '0'); # Kosten €/kWh
my $ndp = AttrVal($NAME, 'numDecimalPlaces', '3');
my $m3 = sprintf "%.${ndp}f", $VALUE/10000 * $mpk; # verbrauchte m3
my $kwh = sprintf "%.${ndp}f", $m3 * $zz * $bw; # Umrechnung m3 -> kWh
my $cost = sprintf "%.${ndp}f", $kwh * $tarf; # Kosten = kWh * Tarif
my $hash = $defs{$NAME};

readingsBulkUpdate ($hash, $date.'_gas_consumption_m3', $m3);
readingsBulkUpdate ($hash, $date.'_gas_consumption_kwh', $kwh);
readingsBulkUpdate ($hash, 'gas_cost_euro_'.$y.'-'.$m.'-'.$d, $cost);
}

if ($READING eq 'state' && $VALUE eq 'done') {
my $n = 0;
my $v = 0;
my $avg = 0;

for my $rdg ( grep { /gas_cost_euro_/x } keys %{$hash->{READINGS}} ) {
$n++;
$v += ReadingsNum ($name, $rdg, 0);
}

if ($n) {
my $ndp3 = AttrVal($NAME, 'numDecimalPlaces', '3');
$avg = sprintf "%.${ndp3}f", $v / $n;
readingsBulkUpdate ($hash, 'gas_cost_euro_average', $avg);
}
}
}
</syntaxhighlight>

Sobald ein Reading erstellt wird welches auf den Regex /1_Brenner_Energy_Summe__DIFF/ matcht, werden die User-Attribute aus dem Steuerungsdummy
''VaillantControlDummy'' abgerufen und damit die Berechnung der resultierenden m3 ($m3), kWh ($kwh) und Euro ($cost) durchgeführt.
Die User-Attribute können natürlich auch im DbRep Device selbst hinterlegt werden. Im vorliegenden Fall wird der Steuerungsdummy noch zu weiteren Aufgabe der Heizungssteuerung verwendet, sodass sich die Verwendung auch für diesen Use Case anbietet.

Es werden die Readings

* <Datum>_<Zeit>_gas_consumption_m3
* <Datum>_<Zeit>_gas_consumption_kwh
* gas_cost_euro_<Datum>

erzeugt.

Hat das Device den Report erfolgreich beendet, wird "state" mit dem Wert "done" erzeugt.
Dieser Wert wird ebenfalls in der Routine überwacht und dann der Durchschnittswert ($avg) aus den ermittelten Monatsergebnissen berechnet.
Mit dem Ergebnis wird das Reading:

* gas_cost_euro_average

erstellt.

Zur Gestaltung des Device Overwiew wird im Attribut '''stateFormat''' ebenfalls eine Perl Routine hinterlegt:

<syntaxhighlight lang="perl">
{
my $state = ReadingsVal($name, 'state', '');
my $gca = ReadingsVal($name, 'gas_cost_euro_average', undef);

my $show = '';
$show .= defined $gca ? 'Durchschnittskosten Gas: '.$gca.' €' :
$state;
$show .= ' ';
$show .= $state =~ /connected/xs ? FW_makeImage('10px-kreis-gelb') :
$state =~ /initialized/xs ? FW_makeImage('control_3dot_hor_s') :
$state =~ /disconnect/xs ? FW_makeImage('10px-kreis-rot') :
$state =~ /done/xs ? FW_makeImage('10px-kreis-gruen') :
$state =~ /Warning/xs ? FW_makeImage('info_warning@darkorange') :
$state =~ /running/xs ? '' :
FW_makeImage('10px-kreis-rot');

"<div>".$show."</div>"
}
</syntaxhighlight>

 

=== Datensätze (Devices) von einer Datenbank in eine andere umziehen (Export/Import)===
==== Zweck ====

Oft ist es so, dass man zunächst eine DbLog-Datenbank anlegt um alle zu loggenden Events dort aufzuzeichnen. Mit zunehmender Größe bzw. mit dem Wunsch nach einer höheren Strukturierung werden weitere DbLog-Instanzen angelegt.
Die bereits geschriebenen Datensätze eines Gerätes müssen nun in eine andere Datenbank verlagert werden, weil das Device nunmehr in dieser Datenbank geloggt und ausgewertet werden soll.

Für das Beispielszenario gilt folgendes:

* Quelldatenbank aus der das Device entfernt werden soll ist "fhem" mit der DbLog-Instanz "LogDB"
* Zieldatenbank ist "fhemshort" mit der DbLog-Instanz "LogDBShort"
* das umzuziehende Device ist "MelderCP1"
* das definierte DbRep-Device ist "Rep.MelderCP1"

==== Vorbereitung ====

Zunächst wird ein DbRep-Device definiert (falls es noch nicht existiert) und für den Verwendungszweck vorbereitet (zur Definition siehe [[#Definieren_eines_DbRep-Devices | Definieren eines DbRep-Devices]]).

Das Attribut "reading" bzw. eventuell gesetzte Attribute zur Zeiteingrenzung werden gelöscht, damit alle Datensätze des Devices erfasst werden können.
Für den bevorstehenden Export wird mit dem Attribut "expimpFile" der (beschreibbare) Pfad und Dateiname festgelegt, hier im Beispiel ist es "/media/sf_Backup_FHEM/meldercp1.txt".

[[Datei:Rep_MelderCP1_count.PNG|right|thumb|200px|Anzahl Einträge von MelderCP1]]

Mit

<pre>
set Rep.MelderCP1 countEntries
</pre>

kann man sich nun einen Überblick verschaffen, wie viele Datensätze in der Quelldatenbank für "MelderCP1" enthalten sind und wie viele auch exportiert werden müssen. In dem Beispiel sind es, wie in dem Screenshot zu sehen, 1144 Datensätze.

Falls noch nicht geschehen, wird in der bisherigen DbLog-Definition das zu loggende Device entfernt und in der neuen DbLog-Definition aufgenommen, damit nun keine neuen Datensätze mehr für "MelderCP1" in die bisherige Datenbank geschrieben werden. Hierzu siehe die {{Link2CmdRef|Lang=de|Anker=DbLog}} zu DbLog.

==== Export ====
Nun werden die Datensätze des Devices "MelderCP1" mit dem folgenden set-Kommando in die Datei "/media/sf_Backup_FHEM/meldercp1.txt" exportiert.

<pre>
set Rep.MelderCP1 exportToFile
</pre>

Nach dem Export sollte natürlich im Reading von "Rep.MelderCP1" die gleiche Anzahl von exportierten Datensätzen ausgegeben werden wie vorher mit "countEntries" ermittelt wurde (siehe Screenshot).

[[Datei:Rep_MelderCP1_exported.PNG|right|thumb|300px|Anzahl exportierter Dataensätze]]

In der Export-Datei sind nun die Datensätze im CVS-Format enthalten.

Ein Ausschnitt:

<pre>
............
"2016-07-04 17:32:03","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 07:47:50","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 08:27:57","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 08:28:25","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 10:23:42","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 10:27:35","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 17:26:30","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-06 07:46:31","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-06 11:24:04","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-06 11:25:43","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-06 11:26:52","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
...........
</pre>

In der bisherigen Datenbank "fhem" können die Datensätze nun gelöscht werden. Dazu versehen wir das DbRep-Device "Rep.MelderCP1" mit dem Attribut "allowDeletion" um die Löschfunktion des Moduls freizuschalten.
Nun werden die vorher exportierten Datensätze gelöscht mit:

[[Bild:Rep_MelderCP1_delrows.PNG|right|thumb|300px|Anzahl gelöschter Datensätze]]

<pre>
set Rep.MelderCP1 delEntries
</pre>

Auch jetzt ist wieder sicherzustellen dass in der Ausgabe der gelöschten Rows dieselbe Anzahl (1144) der exportierten Datensätze enthalten ist.

==== Import ====
Im nächsten Schritt werden die exportierten Daten in die neue Datenbank importiert. Dazu wird in unserem DbRep-Device "Rep.MelderCP1" zunächst das "allowDeletion"-Attribut sicherheitshalber gelöscht.
Zur Umstellung des DbRep-Devices auf die neue Datenbank wird die Definition von "Rep.MelderCP1" editiert und dort die neue DbLog-Instanz "LogDBShort" angegeben.

<pre>
modify Rep.MelderCP1 LogDBShort
</pre>

Nach einem kurzen Moment wird der state von "Rep.MelderCP1" sich wieder von "initialized" auf "connected" ändern sofern die Umstellung funktioniert hat. Mit einem Vergleichslauf durch
[[Datei:Rep_MelderCP1_Vergleichslauf.PNG|right|thumb|300px|Anzahl Einträge von MelderCP1 in neuer Datenbank nach Umstellung]]

<pre>
set Rep.MelderCP1 countEntries
</pre>

wird ersichtlich, dass sich in dieser Datenbank noch keine (oder vllt. bereits neu geloggte) Einträge von "MelderCP1" befinden.

Nun kann der Import erfolgen. Mit

<pre>
set Rep.MelderCP1 importFromFile
</pre>

werden die Daten aus der immer noch im Attribut "expimpFile" hinterlegten Datei "/media/sf_Backup_FHEM/meldercp1.txt" in die Datenbank "fhemshort" importiert. Dieser Vorgang wird als Transaktion ausgeführt. Es werden immer alle Daten oder, im Falle eines Fehlers, '''KEINE''' Daten importiert. Damit ist sichergestellt dass der Datenimport immer einen definierten Zustand hat. Sollte der Datenimport sehr umfangreiche Datensätze enthalten und somit schon absehbar sein dass der voreingestellte timeout-Wert von 86400 Sekunden nicht ausreichen wird, kann man vorsorglich das Attribut "timeout" höher setzen, z.B. auf das Doppelte).

Hier in dem Beispiel sind es lediglich 1144 Datensätze die sehr schnell importiert werden. Somit ist keine Anpassung des timeout-Parameters notwendig.
Auch nach dem Import wird wieder die Anzahl der verarbeiteten Dataensätze ausgegeben. Sie sollte natürlich ebenfalls mit den vorab ermittelten Zahlen der exportierten Datensätze übereinstimmen.

[[Datei:Rep_MelderCP1_importedrows.PNG|right|thumb|300px|Anzahl importierter Datensätze]]

==== Abschluss ====

Nach dem erfolgreichen Import sollte das Attribut "expimpFile" wieder entfernt werden damit man nicht versehentlich einen erneuten Import durchführt.
Das verwendete Rep.MelderCP1 kann nun wieder mit Zeitbegrenzungsattributen usw. versehen werden um die ursprüngliche Verwendung wieder herzustellen.

Die dargestellte Prozedur stellt einen Komplettumzug eines Devices dar, kann jedoch durch die Angabe der bekannten Attribute auch auf bestimmte Readings in der Datenbank oder Zeitgrenzen eingeschränkt werden. Dadurch würden nur bestimmte Datensätze exportiert und wieder importiert werden. Weiterhin sollte man daran denken die vorhandenen Auswertungsszenarien mit DbRep-Devices bzw. SVG-Diagrammen usw. auch auf die neue Datanbank umzustellen.

 
=== Inhalte einer primären Datenbank in eine andere Standby-Datenbank übertragen (syncStandby) ===

==== Zweck ====

Mit dem Export/Import Verfahren kann man, wie oben beschrieben, Daten zwischen verschiedenen Datenbanken austauschen. Mit dem Befehl "syncStandby" ist es aber mit relativ wenig Aufwand möglich, ein regelmäßig automatisch laufendes Übertragungsverfahren zwischen zwei Datenbanken zu etablieren.

Im vorliegenden Beispiel werden Datenbanken des gleichen Typs verwendet. Das Verfahren ist aber auch zwischen Datenbanken unterschiedlichen Typs anwendbar.

Anwendungsfälle dafür sind zum Beispiel:

* die Einrichtung eines Archivsystems
* die längerfristge Datenhaltung von Datensätzen eines bestimmten Devices/Readings in einer weiteren Datenbank um sie dort für umfangreiche Auswertungen zu nutzen (z.B. Daten einer PV-Anlage)
* Wechsel des Datenbanksystems, z.B. von SQLite zu MySQL/MariaDB
* säubern der Quelldaten von doppelten Datensätzen und nicht mehr benötigten Daten, Weiternutzung der aufgebauten Standbydatenbank als primäre Datenbank nach der Syncronisierung

Für das hier gezeigte Beispielszenario sollen Daten einer MariaDB-Quelldatenbank in einer andere MariaDB-Datenbank regelmäßig übertragen werden. Auf der Quelldatenbank werden die Daten aber nicht gelöscht, d.h. es entstehen zwei Datenbanken mit gleicher Datenbasis.

* Quelldatenbank ist eine MariaDB "fhemtest1" mit der DbLog-Instanz "LogDB1"
* Zieldatenbank ist eine MariaDB "fhemtest" mit der DbLog-Instanz "LogStby"

 

==== Die Quelldatenbank ====

Im vorliegenden Beispiel sind die Quelldatenbank und die Standby-Datenbank vom gleichen Typ MariaDB. Das Verfahren funktioniert ebenso zwischen Datenbanken unterschiedlichen Typs, also z.B. zur Übertragung von SQLite Daten in eine MariaDB.

Die Quelldatenbank ist im normalen Kontext die produktive FHEM-Logdatenbank. D.h. sie ist bereits eingerichtet und läuft mit einem entsprechenden DbLog-Device.
Die hier verwendete Quelldatenbank heißt "fhemtest1". Die Definition des dazu gehörenden DbLog-Devices "LogDB1" sei der Vollständigkeit halber hier erwähnt, wird aber natürlich bei jedem Nutzer individuell aussehen:

<pre>
define LogDB1 DbLog ./fhemtest1maria10.conf .*:(?!done).*
attr LogDB1 DbLogInclude CacheUsage
attr LogDB1 DbLogSelectionMode Exclude/Include
attr LogDB1 DbLogType History
attr LogDB1 addStateEvent 0
attr LogDB1 asyncMode 1
attr LogDB1 bulkInsert 1
attr LogDB1 cacheEvents 2
attr LogDB1 cacheLimit 2000
attr LogDB1 dbSchema fhemtest1
attr LogDB1 devStateIcon .*active:10px-kreis-gelb connected:10px-kreis-gruen .*disconnect:10px-kreis-rot
attr LogDB1 disable 0
attr LogDB1 room DbLog
attr LogDB1 showproctime 1
attr LogDB1 syncInterval 120
attr LogDB1 useCharfilter 1
attr LogDB1 verbose 2
</pre>

 

==== Die Standby Datenbank ====

Die Standby Datenbank ist das Synchronisationsziel.
Die Erstellung der Datenbank und die nachfolgende Definition des dazu gehörigen DbLog-Devices erfolgt weitgehend wie für eine "normale" Log-Datenbank wie in der Commandref beschrieben mit geringfügigen Anpassungen.

; 1. Anlegen der DB und Tabellen: wie in diesem [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/dblog Link] hinterlegt, erfolgt die Erstellung mit den Befehlen für MySQL:
::: CREATE DATABASE `fhemtest` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
::: CREATE USER 'fhemuser'@'%' IDENTIFIED BY 'fhempassword';
::: CREATE TABLE `fhemtest`.`history` (TIMESTAMP TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
::: ALTER TABLE `fhemtest`.`history` ADD PRIMARY KEY(TIMESTAMP, DEVICE, READING);
::: CREATE TABLE `fhemtest`.`current` (TIMESTAMP TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
::: GRANT SELECT, INSERT, DELETE, UPDATE ON `fhemtest`.* TO 'fhemuser'@'%';

Es wird zusätzlich zu der normalen Erstellung der history-Tabelle ein primary Key für die Tabelle erstellt. Dieser Key verhindert dass Duplikate in der Tabelle erstellt werden und erleichtert dadurch sehr das Verfahren der Datenübertragung in der Folge.

[[Datei:stb1.PNG|right|thumb|300px|DbLog-Device für Standby-Datenbank]]
; 2. Erstellung der Konfigurationsdatei und Definition des DbLog-Devices für die Standby-Datenbank: Die Konfigurationsdatei (mariastby.conf) beinhaltet die Verbindunginformationen für das DbLog-Device und wird genau wie in der DbLog-Commandref beschrieben angelegt. Das DbLog-Device für die Standby-Datenbank wird nur für die nachfolgende Definition des benötigten DbRep-Devices gebraucht und wird so definiert, dass keinerlei Events geloggt werden. Das kann auf verschiedenen Wegen erreicht werden. Im Beispiel wird der Regex im DEF entsprechend aufgebaut.
::: define LogStby DbLog ./mariastby.conf aaaaaa:bbbbbb
::: attr LogStby DbLogType History
::: attr LogStby asyncMode 1
::: attr LogStby bulkInsert 1
::: attr LogStby cacheEvents 2
::: attr LogStby devStateIcon .*active:10px-kreis-gelb connected:10px-kreis-gruen .*disconnect:10px-kreis-rot
::: attr LogStby disable 0
::: attr LogStby room DbLog
::: attr LogStby showNotifyTime 1
::: attr LogStby showproctime 1
::: attr LogStby syncEvents 1

Die Erstellung der current-Tabelle ist für den vorgesehenen Zweck eigentlich nicht nötig, wird der Vollständigkeit halber mit dokumentiert.
Ist das DbLog-Device definiert und erfolgreich verbunden, ist dessen state "connected".

 

==== Definition des DbRep-Devices zur Synchronisation Quell- und Standby-Datenbank ====

Es existieren nun das DbLog Device "LogDB1" für die produktive Quelldatenbank und das DbLog Device "LogStby" für die Standby-Datenbank.
Für die Synchronisation wird ein DbRep-Device erstellt, welches mit dem DbLog-Device der '''produktiven Quelldatenbank''', also LogDB1, verbunden wird.
Wie üblich, wird im DEF der Name des entsprechenden DbLog-Devices angegeben, hier "LogDB1".

<pre>
defmod Rep.LogDB1.syncStandby DbRep LogDB1
attr Rep.LogDB1.syncStandby aggregation no
attr Rep.LogDB1.syncStandby event-on-update-reading state
attr Rep.LogDB1.syncStandby fastStart 1
attr Rep.LogDB1.syncStandby role Client
attr Rep.LogDB1.syncStandby room DbLog
attr Rep.LogDB1.syncStandby showproctime 1
attr Rep.LogDB1.syncStandby stateFormat { (ReadingsVal($name,"state", ""))." : SQL-Zeit: ".(ReadingsVal($name,"sql_processing_time", "")) }
attr Rep.LogDB1.syncStandby timeDiffToNow d:6
attr Rep.LogDB1.syncStandby verbose 3
</pre>

Mit den verschiedenen möglichen Zeitattributen ('''time.*''') und den Attributen '''device''' und '''reading''' wird abgegrenzt, welche Datensätze in die Standby-Datenbak übertragen werden sollen. In dem vorliegenden Beispiel werden mit jedem Synchronisationslauf alle in der DB vorhandenen Datensätze, die nicht älter als 6 Tage Tage sind, in die Standby-Datenbank übertragen.

'''Hinweis:''' 
Würde man einen solchen Lauf z.B. alle 4 Stunden durchführen, würden viele doppelte Datensätze in der Datenbank entstehen. Der bei der Tabellenerstellung für die history-Tabelle angelegte primary Key verhindert das !
[[Datei:stb2.PNG|right|thumb|300px|syncStandby gestartet]]

Ein Synchronisationslauf wird nun gestartet mit:

<pre>
set <DbRep-Name> syncStandby <DbLog-Device Standby>
</pre>

In dem vorliegenden Beispiel ist das:

<pre>
set Rep.LogDB1.syncStandby syncStandby LogStby
</pre>

[[Datei:stb3.PNG|right|thumb|300px|syncStandby erfolgreich ausgeführt]]
Der Fortschritt der Datenübertragung sowie die evtl. eingefügten Datensätze (number of lines inserted) ist im Logfile mit verbose 3 ersichtlich:

<pre>
2020.01.24 17:12:41.186 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 6177
2020.01.24 17:12:46.411 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 23957
2020.01.24 17:12:51.710 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 24048
2020.01.24 17:12:57.733 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 24092
2020.01.24 17:13:03.505 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 24059
2020.01.24 17:13:08.891 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 23969
2020.01.24 17:13:13.420 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 17871
2020.01.24 17:13:13.421 3: DbRep Rep.LogDB1.syncStandby - number of lines inserted into "LogStby": 104
</pre>

[[Datei:stb4.PNG|right|thumb|300px|nur Daten der Devices SMA_Energymeter,MySTP_5000 werden übertragen]]
Nach dem erfolgreichen Sync-Lauf wird die benötigte Laufzeit und die Anzahl der übertragenen Datensätze in Readings angezeigt.

Mit dem Attribut '''aggragation''' wird gesteuert, in welchen '''Zeitscheiben''' die Selektion der Daten aus der Quelldatenbank und die Übertragung ausgeführt wird. Im Standard ohne gesetztes aggregation-Attribut ist es ein Tag. Stehen genügend Ressourcen zur Verfügung, kann dieser Wert auch auf "week" oder "month" gesetzt werden. Der Wert "hour" zur Verkleinerung des Datenpaketes ist ebenfalls möglich.

Bei jedem Lauf wird die Anzahl der eingefügten Datensätze im Reading '''number_lines_inserted_Standby''' angezeigt.

Die zu übertragenden Daten können natürlich sehr granular bestimmt werden. Sollen zum Beispiel nur die Daten der Devices SMA_Energymeter und MySTP_5000 übertragen werden, wird das Attribut '''device''' entsprechend gesetzt:

attr Rep.LogDB1.syncStandby SMA_Energymeter,MySTP_5000

Weiterhin bietet das Attribut '''reading''' eine Eingrenzung auf die gewünschten Readings und mit dem Attribut '''valueFilter''' kann eine Eingrenzung nur auf bestimmte vorkommende Werte vorgenommen werden.

Der Erfolg der Synchronisationsläufe kann sehr einfach mit einem separaten DbRep-Device (mit dem '''fetchrows''' Kommando) oder dem Tool phpMyAdmin (nebenstehend) überprüft werden.

 

==== regelmäßige Ausführung der Synchronisation ====

Ein einfaches AT kann dazu dienen den Synchronisationslauf mit dem Device '''Rep.LogDB1.syncStandby''' regelmäßig alle x-Stunden/Minuten auszuführen.

<pre>
define At.Sync.Stby at +*04:00:00 set Rep.LogDB1.syncStandby syncStandby LogStby
attr At.Sync.Stby room DbLog
</pre>

 

=== Ermittlung und Darstellung der täglichen Energieerzeugung eines Wechselrichters ===

Gegeben sei dass die Energiedaten eines Wechselrichters (STP_5000) mit SMAUtils in Verbindung mit SBFSpot in die Datenbank geschrieben werden.
Neben vielen anderen Werten liefert SMAUtils die Tageserzeugung in kWh als Reading "etoday". Der Wert dieses Readings wird alle paar Minuten in der Datenbank gespeichert.

Zur Auswertung wird ein DbRep-Device angelegt wie unter [[#Definieren_eines_DbRep-Devices | Definieren eines DbRep-Devices]]) beschrieben (z.B. Rep.etoday.STP_5000).

[[Datei:Rep.STP_5000.configured.PNG|right|thumb|300px|Rep.STP_5000 konfiguriert]]

Es soll die täglich erzeugte Energiemenge beginnend ab dem 01.10.2016 0 Uhr bis zum 13. Oktober angezeigt werden.

<pre>
attr Rep.etoday.STP_5000 timestamp_begin 2016-10-01 00:00:00
attr Rep.etoday.STP_5000 timestamp_end 2016-10-13 23:59:59
</pre>

Da es sich um eine tägliche Aggregation handelt (es soll pro Auswertung der Tag von 00:00:00 bis 23:59:59 betrachtet werden) und die Hintergrundverarbeitungszeit dargestellt werden soll, wird eingestellt:

<pre>
attr Rep.etoday.STP_5000 aggregation day
attr Rep.etoday.STP_5000 showproctime 1
</pre>

Die Eingrenzung der auszuwertenden Devices und der dazu gehörigen Readings wird durch die entsprechenden Attribute gewährleistet.
Es soll nur das Device "STP_5000" mit dem Reading "etoday" berücksichtigt werden. Dazu stellen wir ein:

<pre>
attr Rep.etoday.STP_5000 reading etoday
attr Rep.etoday.STP_5000 device STP_5000
</pre>

DbRep ist nun grundsätzlich zur Auswertung konfiguriert (siehe Screenshot).

Zur Selektion und Berechnung von numerischen Daten stehen die Funktionen average-, max-, min-, sum- und diffValue zur Verfügung.
Bei den in diesem Beispiel verwendeten Daten handelt es sich um einen täglich neu erzeugten und über 24 Stunden stetig steigenden Wert.
Demnach ist für diese Art Daten die Funktion "maxValue" geeignet. Sie gibt den maximalen Wert des Readings im eingestellten Aggregationszeitraum (day) aus.

[[Datei:Rep.STP_5000.max.PNG|right|thumb|300px|Rep.STP_5000 maxValue]]

Die Berechnung wird ausgeführt durch:

<pre>
set Rep.etoday.STP_5000 maxValue
</pre>

Danach kurzer Zeit ist die Berechnung erfolgt (state=done in DeviceOverview). Nach einem Browserrefresh in der Detailansicht sind die erzeugten Readings sichtbar.

Jedes Reading hat einen bestimmten Aufbau. Die Funktion "maxValue" erzeugt Readings folgenden Aufbaus.

<pre>
2016-10-07_18-19-03__STP_5000__etoday__MAX__2016-10-07
</pre>

Zunächst wird der Timestring "2016-10-07_18-19-03" ausgegeben der in diesem Kontext den höchsten (d.h. letzten) Wert von "etotal" an dem Tag markiert.
Bei dem Wechselrichter ist es damit auch der Zeitpunkt zu dem die Energieerzeugung eingestellt wurde (in dem Fall 07.10.2016 um 18:19:03).

'''Anmerkung:''' Die Notation des Timestrings wurde so gewählt, um die Regeln für in Readings erlaubte Zeichen einzuhalten. Wenn keine auswertbaren Daten vorliegen und berechnet werden konnten, werden Readings mit "-" ausgegeben. Im Beispiel sind es die Tagesaggregate 10.10.-13.10. da diese Tage in der Zukunft liegen.

Danach folgt im Reading die Angabe des Devices (STP_5000), des augewerteten Readings (etoday) und der Funktion die dieses Ergebnis ermittelt hat (MAX für maxValue).
Die letzte Angabe, hier "2016-10-07" definiert den Auswertungszeitraum. In dem Beispiel ist es der 07.10.2016. Würde die Berechnung mit aggregation=week durchgeführt werden, würde man als an dieser Stelle den Auswertungszeitraum "week_39" erhalten, also die Kalenderwoche 39.

Um die Auswertungsergebniss etwas benutzerfreundlicher zu gestalten, steht das Attribut "readingNameMap" zur Verfügung. [[Datei:Rep.STP_5000.max.namemap.PNG|right|thumb|300px|Rep.STP_5000 maxValue mit readingNameMap]]
Im Beispiel setzen wir es auf:

<pre>
attr Rep.etoday.STP_5000 readingNameMap Tageserzeugung_kWh
</pre>

Ein erneuter maxValue-Lauf erzeugt Readings des folgenden Aufbaus:

<pre>
2016-10-01_18-03-13__Tageserzeugung_kWh__2016-10-01 4.9870
</pre>

 

=== (regelmäßiges) Löschen von Datenbanksätzen ===

Dieses DbRep-Device dient dazu einmalig oder verbunden mit einem AT-Device Einträge aus einer Datenbank zu löschen.
Zunächst wird das Device wie im Abschnitt [[#Definieren_eines_DbRep-Devices | "Definieren eines DbRep-Devices"]] beschrieben definiert.
Dadurch wird das DbRep-Device mit einem DbLog-Device assoziiert und mit der Datenbank des DbLogs verbunden. Alle weiteren Operationen werden mit dieser Datenbank durchgeführt. In diesem Beispiel heißt das DbRep-Device "Rep.Del.DbShort" und das DbLog-Device "LogDBShort".

In diesem Beispiel sollen alle Datensätze gelöscht werden die älter als 180 Tage sind. Die Löschfunktion des Moduls ist standardmäßig ausgeschaltet und muß per Attribut enabled werden.
Dazu werden die Attribute [[Datei:Rep.Del.DbShort.PNG|right|thumb|300px|Rep.Del.DbShort konfiguriert]]

<pre>
attr Rep.Del.DbShort timeOlderThan d:180
attr Rep.Del.DbShort allowDeletion 1
</pre>

gesetzt. Die Zeitangabe erfolgt in Sekunden.

Insbesondere bei SQLite sollte während des Löschens kein paralleler Schreibprozess in Form des normalen Eventloggings stattfinden. MySQL/MariaDB kann es durchaus parallel verarbeiten. Um einen parallelen Zugriff durch DbLog-Loggging zu verhindern, kann das Logging vor der Löschung geschlossen und danach wieder geöffnet werden.
Dafür werden die Attribute mit z.B. diesen Werten gesetzt:

<pre>
attr Rep.Del.DbShort executeBeforeProc set LogDBShort reopen 7200
attr Rep.Del.DbShort executeAfterProc set LogDBShort reopen
</pre>

Dabei ist "LogDBShort" das mit dem DbRep-Device assoziierte DbLog-Device.

Der Löschvorgang wird mit

<pre>
set Rep.Del.DbShort delEntries
</pre>

gestartet. Nach Abschluß der Datenlöschung wird die Anzahl der deleted rows als Reading ausgegeben und auch im Log mit verbose=3 geschrieben.

Müssen sehr viele Datensätze gelöscht werden, könnte nach 86400 Sekunden der Standardtimeout erreicht werden und der Vorgang mit "error" enden.
In diesem Fall ist der timeout mit dem Attribut:

<pre>
attr Rep.Del.DbShort timeout <timeout in Sekunden>
</pre>

entsprechend angepasst werden.

Ein fhem.cfg Eintrag für das beschriebene Beispieldevice sieht folgendermaßen aus:

<pre>
define Rep.Del.DbShort DbRep LogDBShort
attr Rep.Del.DbShort allowDeletion 1
attr Rep.Del.DbShort comment löschen aller Einträge in LogDBShort älter als 180 Tage
attr Rep.Del.DbShort devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.Del.DbShort event-on-update-reading state
attr Rep.Del.DbShort room DbLog
attr Rep.Del.DbShort timeOlderThan 15552000
</pre>

Die Löschung der relevanten Datensätze kann weiterhin über Attribute "device" bzw. "reading" kann selektiv auf bestimmte Device- und/oder Readingloggings beschränkt werden. Wird keine Zeitbeschränkung (z.B. durch "timeOlderThan") vorgenommen, erfolgt die Löschung aller Datensätze der durch "device" bzw. "reading" spezifizierten Datenbankinhalte.

Als Argument der Attribute "device" bzw. "reading" kann SQL-Wildcard "%" verwendet werden.

<pre>
% substituiert ein oder mehrere Zeichen
_ Platzhalter für ein einzelnes Zeichen
</pre>

Beispiel:

<pre>
attr Rep.Del.DbShort device %5000
</pre>

Mit dieser Spezifikation werden alle Devices gelöscht die auf "5000" enden, also z.B. STP_5000 und MySTP_5000.
(siehe auch Attribut "reading" in der {{Link2CmdRef|Anker=DbRepattr|Lang=de|Label=Commandref}}).

Ein einfaches AT kann dazu dienen den Löschjob über das Device Rep.Del.DbShort regelmäßig alle x-Stunden/Minuten auszuführen. Dadurch werden nicht mehr benötigte Datenbankeinträge automatisiert und nicht FHEM blockierend im Hintergrund entfernt.

<pre>
define At.Del.DbShort at *23:45:00 set Rep.Del.DbShort delEntries
attr At.Del.DbShort room DbLog
</pre>

==== erweiterte Anwendung von Selektionsbedingungen zur Löschung ====

Wie bei allen selektiven Funktionen im DbRep kann auch bei der Löschfunktion über die Attribute '''device''' und '''reading''' eine Beschränkung der zu löschenden Datensätze erfolgen. D.h. es werden nur Datensätze gelöscht, wenn die Selektionskriterien dieser Attribute erfüllt sind.

Im Attribut '''device''' können einzelne Geräte, Geräte-Spezifikationen ({{Link2CmdRef|Anker=devspec|Lang=de|Label=devspec}}) sowie Geräte mit Wildcards angegeben werden.
Ist eine devspec angegeben, werden die Devicenamen vor der Selektion aus der Geräte-Spezifikationen und den aktuell in FHEM vorhandenen Devices aufgelöst sofern möglich.
Wird dem Device bzw. der Device-Liste oder Geräte-Spezifikation ein "EXCLUDE=" vorangestellt, werden diese Devices von der Selektion und damit von dem Löschvorgang ausgeschlossen.

<pre>
attr <name> device TYPE=DbRep # es werden nur Datensätze der Geräte vom Modul-Typ "DbRep"
eingeschlossen
attr <name> device MySTP_5000 # nur Datensätze des Gerätes "MySTP_5000" werden selektiert/gelöscht
attr <name> device SMA.*,MySTP.* # Daten von Geräten die mit "SMA" oder "MySTP" beginnen, werden
selektiert/gelöscht
attr <name> device SMA_Energymeter,MySTP_5000 # nur Daten der beiden angegebenen Geräten werden selektiert/gelöscht
attr <name> device %5000 # Daten von Geräten die mit "5000" enden werden in die Operation
eingeschlossen
attr <name> device TYPE=SSCam EXCLUDE=SDS1_SVS # es werden Datensätze der Geräte vom Modul-Typ "SSCam" eingeschlossen,
aber das Gerät "SDS1_SVS" (auch vom Typ SSCam) wird ausgeschlosssen
attr <name> device EXCLUDE=SDS1_SVS # Datensätze aller Geräte mit Ausnahme des Gerätes "SDS1_SVS" werden
selektiert/gelöscht
attr <name> device EXCLUDE=TYPE=SSCam # Datensätze aller Geräte mit Ausnahme der Geräte vom Typ "SSCam" werden
selektiert/gelöscht
</pre>

Ähnlich erfolgt die Abgrenzung der DB-Selektionen auf ein bestimmtes oder mehrere Readings sowie exkludieren von Readings. Mehrere Readings werden als Komma separierte Liste angegeben. Es können SQL Wildcard (%) verwendet werden, aber '''keine Perl-Regex'''.
Wird dem Reading bzw. der Reading-Liste ein "EXCLUDE=" vorangestellt, werden diese Readings von der Selektion ausgeschlossen.

<pre>
attr <name> reading etotal # Datensätze mit dem Reading "etotal" werden eingeschlossen
attr <name> reading et% # Datensätze deren Reading mit "et" beginnt werden
eingeschlossen
attr <name> reading etotal,etoday # Datensätze mit den Readings "etotal" und "etoday" werden
in die Selektion eingeschlossen
attr <name> reading eto%,Einspeisung EXCLUDE=etoday # Datensätze mit Readings beginnend mit "eto" sowie das
Reading "Einspeisung" werden selektiert, aber das Reading
"etoday" wiederum ausgeschlossen
attr <name> reading etotal,etoday,Ein% EXCLUDE=%Wirkleistung # Datensätze mit Readings beginnend mit "Ein" sowie die
Readings "etotal" und "etoday" werden selektiert, wobei
Readings, die auf "Wirkleistung" enden, von der Löschung
ausgeschlossen werden
</pre>

Natürlich werden die Selektionsbedingungen durch eventuell gesetzte Zeiteingrenzungen mit den time*- Attributen ergänzt.
Die time*- Attribute sind mehrere im DbRep vorhandene Attribute, die alle mit "time" beginnen, z.B. timeOlderThan.

=== Auffinden von alten Devicenamen in der DB und versenden/loggen einer Negativliste ===

Wenn eine Datenbank längere Zeit gelaufen ist, Devices in FHEM hinzugefügt, geändert oder gelöscht wurden oder auch das DEF des DbLog-Devices angepasst wurde, befinden sich aller Wahrscheinlichkeit nach nicht mehr gewünschte/gebrauchte Datensätze von nicht mehr bestehenden Devices in der Datenbank.

Dieses Beispiel soll einen Weg zeigen, wie man mit Hilfe der DbRep-sqlCmd Funktion (ab Version 4.14.0) alle in der DB enthältenen Devicenamen ermitteln und mit einer Positivliste vergleichen kann.
Die Negativliste der nicht gewünschten Devices wird im Logfile ausgegeben bzw. mit TelegramBot versendet.

Zunächst wird das Device wieder wie im Abschnitt [[#Definieren_eines_DbRep-Devices | "Definieren eines DbRep-Devices"]] beschrieben definiert.
Dadurch wird das DbRep-Device mit einem DbLog-Device assoziiert und mit der Datenbank des DbLog-Device verbunden. In diesem Beispiel heißt das DbRep-Device "Report".

Nach der Definition setzen wir die Attribute:

<pre>
attr Report event-on-update-reading state
attr Report sqlResultFormat separated
</pre>

Es werden nun nur noch Events für "state" generiert. Das Attribut "sqlResultFormat = separated" bewirkt, dass das Ergebnis des SQL-Statements zeilenweise in Einzelreadings zur Verfügung gestellt wird.

Nun kann getestet werden, ob die Abfrage grundsätzlich funktioniert. Dazu wird das benutzerspezifische Kommando "sqlCmd" verwendet.

<pre>
set Report sqlCmd select device, count(*) from history group by DEVICE;
</pre>

Es sollte nun eine entsprechende Anzahl von Readings erzeugt werden (Browserrefresh), die als Wert eine Kombination aus <Device>|<Anzahl Datensätze in DB> enthalten wie im nebenstehenden Screenshot ersichtlich.

[[Datei:sqlCmd.PNG|right|thumb|300px|sqlCmd ausgeführt]]

Wenn das Ergebnis wie gewünscht vorliegt, wird nun die Benutzerschnittstelle aktiviert.

<pre>
attr Report userExitFn NaDevs .*:.*
</pre>

"NaDevs" ist die Funktion in 99_myUtils.pm die aufgerufen werden soll. Die Angabe des Regex ".*:.*" ist optional. Nähere Informationen zur Funktionsweise sind in der {{Link2CmdRef|Lang=de|Anker=DbRep}} zu finden.

Die "Positivliste" der in der Datenbank erlaubten Devices wird für das Beispiel in dem Attribut "comment" für den späteren Vergleich als String angegeben. Es ist natürlich auch z.B. eine Ableitung der im DEF-Regex des zugeordneten DbLog-Devices enthaltenen Device-Definitionen vorstellbar, sodass immer der aktuelle Stand dieser Definition als Grundlage für den Vergleich herangezogen wird.

<pre>
attr Report comment (sysmon|MyWetter|SMA_Energymeter|STP_5000|Cam.*)
</pre>

Somit werden die Devices "sysmon", "MyWetter", "SMA_Energymeter", "STP_5000" und alle Cam-Devices als in der DB erlaubt definiert.
Alle anderen gefundenen Devices sollen in einer Negativliste aufgeführt werden.

Im weiteren Schritt wird die aufzurufende Funktion in der vorhandenen 99_myUtils.pm ergänzt.

<syntaxhighlight lang="perl">
############################################################################
# $Id: myUtilsTemplate.pm 7570 2015-01-14 18:31:44Z rudolfkoenig $
#
# Save this file as 99_myUtils.pm, and create your own functions in the new
# file. They are then available in every Perl expression.

package main;

use strict;
use warnings;

sub
myUtils_Initialize($$)
{
my ($hash) = @_;
}

# Enter you functions below _this_ line.

my @dna;

...

######################################################
######## Not allowed Devs in DB ermitteln
######## UserExitFn in DbRep
######################################################
sub NaDevs {
my ($name,$reading,$value) = @_;
my $hash = $defs{$name};

# DB Namen ermitteln
my $dbconn = $hash->{dbloghash}{dbconn};
my $db = (split("=",(split(";",$dbconn))[0]))[1];

# Liste der erlaubten Devices aus Attribut "comment" lesen
my $adevs = AttrVal($name, "comment","-");

if($reading eq "state" && $value eq "running") {
# der Select wurde gestartet
Log3 $name, 1, "UserExitFn called by $name - new Select has been startet. Allowed devices in database are: $adevs";
@dna=();
return;
}

my $d = (split("\\|",$value))[0];

# das Selektionsergebnis bewerten und ggf. dem Ergebnisarray hinzufügen
if ( $reading =~ m/SqlResultRow.*/ && $d !~ m/$adevs/) {
push(@dna,$d."\n")
}

if ($reading eq "state" && $value eq "done") {
# Ergebnis versenden bzw. loggen
Log3 $name, 1, "UserExitFn called by $name - Devices not allowd found in $db: @dna";
fhem("set teleBot message Devices are not allowed found in $db: \n @dna");
}

return;
}

....
1;
</syntaxhighlight>

Die Schnittstelle übergibt der aufgerufenen Funktion den Namen des DbRep-Devices, den Namen des erstellten Readings und dessen Wert.
Der Aufruf erfolgt nach jeder Readingserstellung. Die Schnittstelle arbeitet OHNE Eventgenerierung bzw. benötigt keine Events.
Über den Namen des DbRep-Devices kann auf dessen Hash zugegriffen werden bzw. über $hash->{dbloghash}{...} ebenfalls auf den Hash des angeschlossenen DbLog-Devices.

In der Funktion "NaDevs" wird der Device-Teilstring des erzeugten Readings mit dem Wertevorrat aus dem "comment"-Attribut verglichen und bei einem negativen Ergebnis der Negativliste @dna hinzugefügt.

Nach Abschluss der Operation (signalisiert durch Reading "state = done") wird die erzeugte Liste im Logfile ausgegeben bzw. ein TelgramBot-Device versendet.

=== Größe der FHEM-Datenbank ermitteln ===

Zunächst wird das Device wie im Abschnitt [[#Definieren_eines_DbRep-Devices | "Definieren eines DbRep-Devices"]] beschrieben definiert.
Dadurch wird das DbRep-Device mit einem DbLog-Device assoziiert und mit der Datenbank des DbLogs verbunden. Alle weiteren Operationen werden mit dieser Datenbank durchgeführt. In diesem Beispiel heißt das DbRep-Device "Rep.Fhem.Size".

Um die Größe der Datenbank beziehungsweise der Tabellen "history" und "current" zu ermitteln steht das Kommando:
[[Datei:tableinfo.PNG|right|thumb|300px|get Rep.Fhem.Size tableinfo]]
<pre>
get Rep.Fhem.Size tableinfo (MySQL, PostgreSQL)
get Rep.Fhem.Size svrinfo (SQLite)
</pre>

zur Verfügung.

Mit diesem Befehl werden sehr viele Informationen bezüglich der Tabellen des FHEM-Schemas (MySQL) als Readings ausgegeben.

Um nur die relevanten bzw. interessierenden Selektionsergebnisse auszugeben, kann mit dem Attribut showTableInfo (MySQL, PostgreSQL) bzw. showSvrInfo (SQLite) eine kommaseparierte Liste der relevanten Tabellen angegeben werden.

<pre>
attr Rep.Fhem.Size showTableInfo %history%,%current% (MySQL, PostgreSQL)
</pre>

So wie in diesem Beispiel gesetzt, werden nur Informationen der Tabellen "history" und "current" ausgegeben.
Diese Ausgabe ich bereits recht übersichtlich, kann aber durch die Verwendung des Attributs suppressReading
weiter eingegrenzt werden.

Beispiele:

<pre>
attr Rep.Fhem.Size suppressReading ^(?!.*INFO_history.data_index_length_MB).*$
attr Rep.Fhem.Size suppressReading ^(?!.*(INFO_history.data_index_length_MB)|(state)).*$
attr Rep.Fhem.Size suppressReading ^(?!.*(INFO_history.data_index_length_MB)|(background_processing_time)|(state)).*$
</pre>

Mit diesen Attributwerten wird nur das Reading "INFO_history.data_index_length_MB" oder aber "INFO_history.data_index_length_MB"
und "state" bzw. "INFO_history.data_index_length_MB", "state" und "background_processing_time" dargestellt.

Die Datenbankgröße (MB) ist je nach DB-Typ in den Readings:

<pre>
INFO_current.data_index_lenth_MB
INFO_history.data_index_lenth_MB
SQLITE_FILE_SIZE_MB
</pre>

enhalten.

Wird z.B. über ein AT dieser Befehl regelmäßig durch Rep.Fhem.Size ausgeführt und die Ergebnisse wiederum in DbLog gespeichert kann die Größenentwicklung der Datenbank mittels SVG-Diagrammen dargestellt werden. [[Datei:tableinfo_SVG.PNG|left|thumb|300px|get Rep.Fhem.Size tableinfo]]

 
=== Readingwerte von DbRep in ein anderes Device übertragen ===

Um Readings aus DbRep in einen Dummy zu übertragen, können verschiedene Verfahren angewendet werden. Allen Verfahren ist gemeinsam, dass sie auf die Arbeitsweise der Funktionen von DbRep Rücksicht nehmen. Alle Funktionen von DbRep arbeiten, von Ausnahmen abgesehen, asynchron (non-blocking). Das hat den Vorteil, dass die Datenbankverarbeitungszeit bzw. eine Nichtverfügbarkeit der DB nicht hemmend auf FHEM wirkt, hat andererseits aber den Nachteil, dass die Ergebnisse einer Funktion nicht direkt nach dem Funktionsaufruf zur Verfügung stehen und somit nicht trivial innerhalb der FHEM-Hauptschleife weiterverarbeitet werden können.

 
==== Werte automatisch durch DbRep übertragen lassen (ab Version 8.40.0) ====

Ab DbRep Version 8.40.0 gibt es das Attribut '''autoForward''' mit dem eine integrierte Übertragung der DbRep-Ergebnissreadings in andere Devices (z.B. Dummy) eingerichtet werden kann. Diese Variante wird hier beschrieben.

Die weiteren manuellen Varianten werden in den nachfolgenden Abschnitten behandelt.

Um die integrierte Reading-Weiterleitung zu aktivieren wird des Attribut autoForward nach folgender Systematik gesetzt:
[[Datei:aforw1.PNG|right|thumb|300px|Übertragung aller Readings nach Dum.Rep.all]]
<pre>
{
"<source-reading> => "<destination device> [=> <destination-reading>]",
"<source-reading> => "<destination device> [=> <destination-reading>]",
...
}
</pre>
[[Datei:aforw2.PNG|right|thumb|300px|Übertragung Readings mit "SUM" nach Dum.Rep.Sum]]
In der Spezifikation von '''<source-reading>''' können Wildcards (.*) verwendet werden um nur eine Auswahl der erzeugten Readings an das Zieldevice '''<destination device>''' weiterzuleiten. Ist der optionale Zusatz '''<destination-reading>''' angegeben, erfolgt die Speicherung der übertragenen Readings im Zieldevice mit dem angegebenen Namen. 
Der angegebene Readingname muss den Regularien zur Namensgebung von Readings genügen. Eventuell vorhandene nicht erlaubte Zeichen werden durch "_" ersetzt.

Fehlt der Zusatz <destination-reading>, werden die in DbRep erzeugten Readings 1:1 in das Zieldevice übertragen.

'''Beispiel:'''

<pre>
attr DbRepDev autoForward {
".*" => "Dum.Rep.All",
".*AVGAM.*" => "Dum.Rep => average",
".*SUM.*" => "Dum.Rep.Sum => summary",
}
</pre>

Die Spezifikation erfüllt folgende Ziele:

# alle Readings werden zum Device "Dum.Rep.All" übertragen, der ursprüngliche Readingname bleibt im Ziel erhalten (Screenshot 1)
# Readings mit "AVGAM" im Namen werden zum Device "Dum.Rep" in das Reading "average" übertragen
# Readings mit "SUM" im Namen werden zum Device "Dum.Rep.Sum" in das Reading "summary" übertragen (Screenshot 2)

 
==== Werte mittels Event übetragen ====

Es sollen zum Beispiel die erzeugten Readings aus einem DbRep-Device in einen Dummy übetragen werden, die den Term "Grid" im Wortstamm tragen.

Ein Reading-Name der fetchrows-Funktion in DbRep ist immer nach folgendem Schema aufgebaut:

<Datum>_<Zeit>__<Unique-Index>__<Device>__<Reading>__<Dopplerindex>
z.B.: 2018-10-14_18-30-25__1__MyWetter__humidity

Datum und Zeit entsprechen dem Timestamp des gespeicherten Events in der Datenbank. Der Unique-Index identifiziert eventuell vorhandene Doubletten in der DB und der Dopplerindex ist ein Hilfsmittel, Datensätze die sich allein durch den Value-Wert unterscheiden, auch als unterschiedliche Readings erstellen zu können. Dieser Index wird nur bei Bedarf erstellt.

Im folgenden Beispiel werden alle erzeugten Readings mit "Grid" im Namen des DbRep-Devices "Rep.SMAEM" in den Dummy übertragen und heißen dann genauso. Zunächst wird der Dummy angelegt.

<pre>
define Dum.Rep dummy
attr Dum.Rep room DbLog
</pre>

Mit dem nachfolgend angelegten Notify wird auf die z.B. von fetchrows erzeugten Events reagiert, der Event entsprechend gesplittet und verarbeitet in den Dummy übertragen.

<pre>
define N.Dum.Rep notify Rep.SMAEM:(\d).*Grid.* { fhem "setreading Dum.Rep ".(split(":",$EVTPART0))[0]." $EVTPART1"}
attr N.Dum.Rep room DbLog
</pre>

Soll im Dummy ein Reading mit eigenem Namen gefüllt werden, sieht das Notify z.B. so aus:

<pre>
define N.Dum.Rep notify Rep.SMAEM:(\d).*Grid.* { fhem "setreading Dum.Rep DeinReading"." $EVTPART1"}
</pre>

==== Werte mittels Funktion DbReadingsVal übertragen ====

Sobald ein DbRep-Device definiert ist, wird die Funktion DbReadingsVal zur Verfügung gestellt. Mit dieser Funktion läßt sich, ähnlich dem allgemeinen ReadingsVal, der Wert eines Readings aus der Datenbank abrufen. Die Befehlssyntax ist:

DbReadingsVal("<name>","<device:reading>","<timestamp>","<default>")

Mit dieser Funktion kann ein Device/Reading-Wert aus der Datenbank gelesen und in einen Dummy gesetzt werden. "Name" ist dabei das abzufragende DbRep-Device.
Der Timestamp muss nicht genau bekannt sein. Es wird der zeitlich zu <timestamp> passendste Readingwert zurück geliefert, falls kein Wert exakt zu dem angegebenen Zeitpunkt geloggt wurde.
Um den aktuellsten in der Datenbank gespeicherten Wert eines Readings abzurufen, kann als Timestamp die aktuelle Zeit entsprechend formatiert verwendet werden.

Es soll z.B. der aktuellste Datenbankwert des Readings "etoday" vom Device "MySTP_5000" ausgelesen und im Dummy "Dum.Rep" als Reading "EnergyToday" gespeichert werden. Das beteilgte DbRep-Device heißt "Rep.Energy".

Für die Formatierung des aktuellen Timestamps kann die FHEM-Funktion FmtDateTime verwendet werden, welcher der aktuelle UNIX-Timestamp übergeben wird:

FmtDateTime(time)

Der Datenabruf aus der Datenbank sieht dann folgendermaßen aus:

DbReadingsVal("Rep.Energy","MySTP_5000:etoday",FmtDateTime(time),"")

Mit dem Befehl setreading kann der abgerufene Wert in dem Dummy-Device gespeichert werden:

{ fhem "setreading Dum.Rep EnergyToday ".DbReadingsVal("Rep.Energy","MySTP_5000:etoday",FmtDateTime(time),"") }

Damit der Datenabruf regelmäßig erfolgt und immer der aktuellste Wert von "etoday" in den Dummy eingtragen wird, kann dieses AT verwendet werden:

<pre>
define set.Dum.Rep_EnergyToday at +*00:01:00 { fhem "setreading Dum.Rep EnergyToday ".DbReadingsVal("Rep.Energy","MySTP_5000:etoday",FmtDateTime(time),"") }
</pre>

Somit erfogt eine Aktualisierung des Readings "EnergyToday" im Dummy "Dum.Rep" jede Minute.
Es ist zu beachten, dass die Funktionsausführung von DbReadingsVal blockierend erfolgt. Sollte die Datenbank nicht verfügbar sein oder lange Antwortzeiten besitzen, hat dies negative Auswirkungen auf FHEM, was sich in Blockierungszuständen äußert.
Möchte man solche eventuell möglichen Zustände vermeiden, kann die Befehlsausführung in die 99_myUtils unter Verwendung von [[Blocking_Call | Blocking Call]] ausgelagert werden.

Diese non-blocking Variante der Verwendung von DbReadingsVal wird nachfolgend skizziert.
In der 99_myUtils wird dazu der nachfolgende Code eingefügt, der drei kleine Subroutinen enthält:

<syntaxhighlight lang="perl">
############################################################################################################
# DumRepEnergyToday (Reading mittels DbReadingsVal non-blocking setzen)
############################################################################################################
sub DumRepEnergyToday ($$$$$) {
# initiale Routine zum Aufruf von BlockingCall unter Berücksichtigung von "RUNNING_SET_READING"
my ($name,$device,$reading,$destdev,$destread) = @_;
my $hash = $defs{$name};

return if($hash->{HELPER}{RUNNING_SET_READING});
$hash->{HELPER}{RUNNING_SET_READING} = BlockingCall("DumRepEnergyTodayNbl", "$name|$device|$reading|$destdev|$destread", "DumRepEnergyTodayNblDone");

return;
}

sub DumRepEnergyTodayNbl($) {
# die eigentliche Routine in der die potentiell blockierende Funktion ausgeführt wird
my ($string) = @_;
my ($name,$device,$reading,$destdev,$destread) = split("\\|", $string);
my $hash = $defs{$name};

my $val = DbReadingsVal($name,"$device:$reading",FmtDateTime(time),"");
$val = encode_base64($val,"");

return "$name|$val|$destdev|$destread";
}

sub DumRepEnergyTodayNblDone($) {
# Rückkherfunktion zur Ergebnisauswertung und Löschen von "RUNNING_SET_READING"
my ($string) = @_;
my @a = split("\\|",$string);
my $hash = $defs{$a[0]};
my $name = $hash->{NAME};
my $val = decode_base64($a[1]);
my $destdev = $a[2];
my $destread = $a[3];

fhem "setreading $destdev $destread $val";
delete $hash->{HELPER}{RUNNING_SET_READING};

return;
}
</syntaxhighlight>

Der oben gezeigte Code stellt die einfachste Form der BlockingCall-Implementierung dar. Weitere Informationen dazu sind im weiter oben angegebenen Link zum BlockingCall-Wiki enthalten.

Um non-blocking Funktion aufzurufen, ist das bereits beschriebene AT-Device wie folgt zu ändern:

<pre>
define set.Dum.Rep_EnergyTodayNbl at +*00:01:00 { DumRepEnergyToday("Rep.Energy","MySTP_5000","etoday","Dum.Rep","EnergyToday") }
</pre>

Der aufgerufenen Funktion "DumRepEnergyToday" werden hierbei der Name des abzufragenden DbRep-Devices, der Name des auszuwertenden Devices, der Name des auszuwertenden Readings sowie das Ziel-Device und das Ziel-Reading als Argumente mitgegeben. Dieser Aufruf kann dadurch universell zum Abruf und Setzen verschiedener auszuwertender Device/Reading-Kombinationen verwendet werden.

=== Ein Userreading anlegen und für stateformat verwenden ===

Eine Besonderheit beim Modul DbRep besteht darin, dass sich die Namen der generierten Readings ändern können. Dadurch kann man für die Erstellung eines eigenen Userreading nicht einfach den Namen eines erstellten Readings, z.B. in der Funktion ReadingsVal, verwenden um dessen Wert zu ermitteln.

Eine Möglichkeit besteht darin eine Funktion in 99_myUtils anzulegen und mit dem Attribut "userExitFn" diese Funktion zu aktivieren/zu verwenden.

Für das Beispiel soll ein Reading "power_max" für den erreichten Maximalwert im Monat und der Timestamp des Maximalwertes aus einem Beispielreading "2018-06-01_13-23-02__STP_5000__total_pac__MAX__no_aggregation" (Name kann sich durch das jeweilige Datum ändern) extrahiert werden.

Zunächst wird die Funktion "calcpomax" in 99_myUtils angelegt.

<syntaxhighlight lang="perl">
############################################################################################################
######## power_max in DbRep erstellen
############################################################################################################
sub calcpomax {
my ($name,$reading,$value) = @_;
my $hash = $defs{$name};

if($reading =~ /^.*total_pac__MAX.*$/) {
$reading =~ /^(\d+)-(\d+)-(\d+)_(\d+)-(\d+)-(\d+)_.*$/;
my $pmts = "$3.$2.$1 $4:$5:$6";
my $fmtDateTime = FmtDateTime(gettimeofday());
setReadingsVal($hash,"power_max",$value,$fmtDateTime);
setReadingsVal($hash,"power_max_ts",$pmts,$fmtDateTime);
}
return;
}
</syntaxhighlight>

Wie in der Commandref zu {{Link2CmdRef|Anker=DbRep|Lang=de|Label=DbRep}} zu lesen ist, werden der im Attribut "userExitFn" hinterlegten Funktion jeweils der Name des aufrufenden Devices, das Reading und dessen Wert übergeben. Mit ein paar Zeilen Code wird der übergebene Readingsname auf das Vorhandensein des statischen Namensteils (total_pac__MAX) geprüft und dementsprechend der Readingname "power_max" mit dem Wert angelegt, wenn der Regex auf den Readingnamen matched.
Gleiches gilt für das Reading "power_max_ts", welches den Zeitpunkt des erreichten Maximalwertes enthalten soll.

Die Aktivierung der Schnittstelle erfolgt im DbRep-Device mit

<pre>
attr <name> userExitFn calcpomax .*:.*
</pre>

Mit jedem Lauf von

<pre>
set <name> maxvalue
</pre>

wird nun das neue Reading mit angelegt und kann z.B. in einem stateformat verwendet werden:
[[Datei:Rep.powmax.PNG|right|thumb|500px|]]

<pre>
attr <name> stateformat
{
if(ReadingsVal($name,"power_max",0)) {
(ReadingsVal($name,"power_max",0)*1000)." Watt (erreicht am ".ReadingsVal($name,"power_max_ts","").")";
} else {
ReadingsVal($name,"state","done");
}
}
</pre>

Nachfolgend noch die Definition des verwendeten DbRep-Devices für diese Auswertung:

<pre>
defmod Rep.total_pac.currmonth DbRep LogDB
attr Rep.total_pac.currmonth aggregation no
attr Rep.total_pac.currmonth alias Peak WR-Leistung aktueller Monat
attr Rep.total_pac.currmonth allowDeletion 0
attr Rep.total_pac.currmonth devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.total_pac.currmonth device STP_5000
attr Rep.total_pac.currmonth disable 0
attr Rep.total_pac.currmonth event-on-update-reading state
attr Rep.total_pac.currmonth group SMA Inverter
attr Rep.total_pac.currmonth reading total_pac
attr Rep.total_pac.currmonth room Energie
attr Rep.total_pac.currmonth showproctime 1
attr Rep.total_pac.currmonth stateFormat { \
if(ReadingsVal($name,"power_max",0)) {\
(ReadingsVal($name,"power_max",0)*1000)." Watt (erreicht am ".ReadingsVal($name,"power_max_ts","").")";;\
} else {\
ReadingsVal($name,"state","done");;\
}\
}
attr Rep.total_pac.currmonth timestamp_begin current_month_begin
attr Rep.total_pac.currmonth timestamp_end current_month_end
attr Rep.total_pac.currmonth userExitFn calcpomax .*:.*
attr Rep.total_pac.currmonth verbose 2
</pre>

 

=== datenbankgestützte Erstellung der Energiebilanz einer SMA PV-Anlage mit Überschußeinspeisung ===
[[datenbankgestützte Erstellung der Energiebilanz einer SMA PV-Anlage mit Überschußeinspeisung | Hier]] geht's zum Beitrag.

 
=== DbRep-Kommandos regelmäßig mit einem at-Device ausführen ===

Sollen DbRep-Kommandos regelmäßig zu bestimmten Zeiten bzw. Intervallen ausgeführt werden, kann ein at-Device (alternativ z.B. DOIF) dafür definiert und verwendet werden.

Als Beispiel soll die regelmäßige Ausführung des SQL-Statements

select device, count(*) from history group by DEVICE

über das Set-Kommando '''sqlCmd''' dienen.

Zunächst wird das DbRep-Device definiert welches zur Ausführung des Kommandos dienen soll.

<pre>
define Rep.LogDB.sqlResult DbRep LogDB
attr Rep.LogDB.sqlResult devStateIcon initialized:control_3dot_hor_s connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.LogDB.sqlResult event-on-update-reading state
attr Rep.LogDB.sqlResult fastStart 1
attr Rep.LogDB.sqlResult room Datenbank
attr Rep.LogDB.sqlResult showproctime 1
attr Rep.LogDB.sqlResult sqlResultFormat table
attr Rep.LogDB.sqlResult verbose 2
</pre>

Die Definition Syntax wurde bereits weiter oben erläutert. Das Attribut '''sqlResultFormat''' legt fest in welcher Art und Weise das Ergebnis präsentiert werden soll. Auch andere Formate wie JSON sind implementiert.

Um das oben angegbene SQL-Statement zum Beispiel alle 6 Stunden 20 Minuten auszuführen, dient die folgende at-Definition:

<pre>
define At.LogDB.sqlResult at +*06:20:00 set Rep.LogDB.sqlResult sqlCmd select device, count(*) from history group by DEVICE
attr At.LogDB.sqlResult icon clock
attr At.LogDB.sqlResult room Datenbank->Produktiv
</pre>

Weitere Informationen sind in der [https://fhem.de/commandref_DE.html#at at-CommandRef] beschrieben.

Natürlich sind alle verfügbaren DbRep Set/Get-Befehle über diesen Weg ausführbar.
Es wird empfohlen das definierte DbRep-Device nur für Auswertungsaufgaben zu verwenden die eine gleiche Attributierung des Devices verlangen.
Für weitere Aufgaben sollten weitere DbRep-Devices definiert und entsprechend eingestellt werden.

 

=== DbRep Chain - die Kommandokette ===

Für regelmäßig auszuführende Aufgaben erstellt man sich je ein separates DbRep-Device und setzt die Attribute wie es für die spezifische Aufgabe erforderlich ist.
Zu diesem Zweck kopiert man sich einfach ein vorhandenes DbRep-Device mit dem FHEM ''copy'' Kommando und passt es danach entsprechend an. Es können beliebig viele DbRep-Devices angelegt werden.

Häufig besteht der Wunsch, verschiedene Datenbankaktionen nacheinander ablaufen zu lassen, z.B. erst ''minValue writeToDB'' danach ''maxValue writeToDB'' sowie ''averageValue writeToDB'' nacheinander auszuführen.
Eine solche Verkettung kann durch die Nutzung des ''executeAfterProc'' Attributes erstellt werden.

Für das Beispiel werden 3 DbRep-Devices angelegt:

* Rep_Min
* Rep_Max
* Rep_Avg

Das erste Device (Rep_Min) soll für ''minValue writeToDB'' genutzt werden. In diesem Device wird das Attribut gesetzt:

attr Rep_Min executeAfterProc set Rep_Max maxValue writeToDB

Dieses Attribut zeigt auf das zweite Device (Rep_Max), welche für ''maxValue writeToDB'' verwendet werden soll.
In diesem Device wird wiederum das Attribut gesetzt:

attr Rep_Min executeAfterProc set Rep_Avg averageValue writeToDB

Die gesamte Chain startet mit einem at-Device, notify oder dergleichen mit dem Kommando:

set Rep_Min minValue writeToDB

'''Funktionsweise:''' 
Die Attribute executeBeforeProc und executeAfterProc führen jeweils das in ihnen hinterlegte FHEM-Kommando oder Perl-Funktion vor bzw. nach der Ausführung des gestarteten DbRep-Kommandos aus. 
In dem dargestellten Beispiel startet das at-Device mit

set Rep_Min minValue writeToDB

die Funktion ''minValue writeToDB'' im Device ''Rep_Min''. Wenn das DbRep ''Rep_Min'' mit seiner Aufgabe fertig ist, startet es automatisch über executeAfterProc das DbRep ''Rep_Max'' die Ausführung von '''maxValue writeToDB'''. Hat DbRep ''Rep_Max''seine Aufgabe beendet, startet es wiederum im letzten Device ''Rep_Avg'' das Kommando ''averageValue writeToDB''. 
Mit diesem Verfahren läuft immer nur ein Kommando der Reihe nach über die Datenbank.

Natürlich kann diese Chain beliebig erweitert werden, oder im ersten DbRep vor dem Start der Chain das angeschlossene DbLog-Device pausiert werden mit:

attr Rep_Min executeBeforeProc set <DbLog-Device> reopen 7200

Die Beendigung der Pause des DbLog kann das letzte DbRep ''Rep_Avg'' übernehmen durch Setzen des Attributes:

attr Rep_Avg executeAfterProc set <DbLog-Device> reopen

 
=== Abarbeitung einer sequentiellen Befehlskette mittels non-blocking sqlCmd-Kommandos ===

('''Hinweis:''' In der aktuellen DbRep-Version kann die seqientielle Kommandoabarbeitung über die [[#DbRep_Chain_-_die_Kommandokette|Chain-Funktionalität]] realisiert werden.)

Ein Vorteil von DbRep ist die nicht blockierende Arbeitsweise fast aller DbRep-Befehle (auf Ausnahmen wird in der Commandref hingewiesen).
Daraus ergibt sich aber auch das Merkmal, dass nach dem Funktionsaufruf nicht auf das Ergebnis gewartet wird und die FHEM-Schleife
unmittelbar nach dem Start des Befehls weiterläuft. Um mehrere voneinander abhängige Befehle, die eine festgelegte Reihenfolge erfüllen müssen, abzuarbeiten, kann die nachfolgend beschriebene Technik zur Kettenbildung angewendet werden. Diese Technik wird anhand einer einfachen Demo erläutert.

Das konstruierte Ziel der Kette ist folgendes:

* Es soll nacheinander der Insert eines Datensatzes durchgeführt, danach ein Select dieses Datensatzes, ein Update auf ein Feld und zuletzt ein delete dieses Datensatzes in dieser Reihenfolge ausgeführt werden

Demnach sich insgesamt vier SQL-Befehle nacheinander auszuführen (Insert, Select, Update, Delete).
Zunächst werden vier identische DbRep-Devices angelegt, die sich lediglich durch ihren Namen unterscheiden. Das wären die Devices:

<pre>
Rep.insert, Rep.select, Rep.update, Rep.delete
</pre>

Zur Anlage kann ein DbRep-Device als Vorlage erstellt und nachfolgend dreimal kopiert werden.

<pre>
define Rep.insert DbRep LogDB
attr Rep.insert allowDeletion 1
attr Rep.insert showproctime 1
attr Rep.insert userExitFn chain

copy Rep.insert Rep.select
copy Rep.insert Rep.update
copy Rep.insert Rep.delete
</pre>

Das wichtige Detail dieser Devices ist das gesetzte Attribut "userExitFn = chain". Dieses Attribut aktiviert eine Schnittstelle zum Aufruf von benutzereigenem Code nach dem Abschluß eines Datenbank-Calls (siehe Commandref).

Der benutzereigene Code wird nach folgendem Schema in die 99_myUtils.pm eingebaut:

<syntaxhighlight lang="perl">
#############################################################################################
# sqlCmd Commandchain zur sequentiellen Abarbeitung von non-blocking DbRep-Befehlen
#
# genutzte werden vier DbRep-Devices: Rep.insert, Rep.select, Rep.update, Rep.delete
#
#############################################################################################
sub chain {
my ($name,$reading,$value) = @_;
my $hash = $defs{$name};
my $device = "Testdevice";
my $model = "Testmodel";
my $rc;

if ($name eq "Rep.insert" && $reading eq "chainstart") {
# Start der 1. Operation (insert)
CommandSet(undef,"Rep.insert sqlCmd insert into history (DEVICE, TYPE, EVENT, READING, VALUE, UNIT)
values (\"$device\", \"$model\", \"definition\", \"DEF\", \"Hugo\", \"Emma\")");
Log3 $name, 1, "$name - Start chain with insert";
return;
}

if($reading eq "state" && $value eq "done") {
if ($name eq "Rep.insert") {
# Auswertung der 1. Operation (insert)
$rc = ReadingsVal($name, "SqlResultRow_1", "");
Log3 $name, 1, "$name - number of inserts: $rc";

# Start der 2. Operation (select)
CommandSet(undef,"Rep.select sqlCmd select VALUE from history where device=\"$device\" and READING=\"DEF\" LIMIT 1;");
}

if ($name eq "Rep.select") {
# Auswertung der 2. Operation (select)
$rc = ReadingsVal($name, "SqlResultRow_1", "");
Log3 $name, 1, "$name - return of select: $rc";

# Start der 3. Operation (update)
CommandSet(undef,"Rep.update sqlCmd update history set UNIT=\"neu\" where DEVICE=\"$device\";");
}

if ($name eq "Rep.update") {
# Auswertung der 3. Operation (update)
$rc = ReadingsVal($name, "SqlResultRow_1", "");
Log3 $name, 1, "$name - number of updates: $rc";

# Start der 4. Operation (delete)
CommandSet(undef,"Rep.delete sqlCmd delete from history where device = \"$device\" and UNIT = \"neu\";");
}

if ($name eq "Rep.delete") {
# Auswertung der 4. Operation (delete)
$rc = ReadingsVal($name, "SqlResultRow_1", "");
Log3 $name, 1, "$name - number of deletes: $rc";
}
}

return;
}
</syntaxhighlight>

Die gesamte Abarbeitung wird gestartet mit dem Aufruf:

<pre>
chain("Rep.insert", "chainstart")
</pre>

bzw. in der Kommandozeile im FHEMWEB mit:

<pre>
{chain("Rep.insert", "chainstart")}
</pre>

Nach dem initialen Aufruf des Insert wird die sub "chain" beendet und nach dem insert-Befehl durch das Device "Rep.insert" wieder aufgerufen. Dabei wird diese sub nach jedem erstellten Reading aufgerufen und dabei neben dem eigenen Devicenamen auch der Readingname sowie dessen Wert zur Auswertung übergeben.
Durch die if-Zweige wird bei jedem Durchlauf der richtige Entrypoint für den nachfolgenden Funktionsaufruf ermittelt und ausgeführt.

Nach der Abarbeitung aller vorgesehenen SQL-Statements ist die erfolgreiche Chainverkettung anhand der Ergebnisse im Logfile ersichtlich:

<pre>
2018.10.24 23:57:37.602 1: Rep.insert - Start chain with insert
2018.10.24 23:57:37.815 1: Rep.insert - number of inserts: 1
2018.10.24 23:57:37.901 1: Rep.select - return of select: Hugo
2018.10.24 23:57:38.033 1: Rep.update - number of updates: 1
2018.10.24 23:57:38.176 1: Rep.delete - number of deletes: 1
</pre>

=== Summe aller Einschaltzeiten eines Gerätes ===

[[Summe aller Einschaltzeiten eines Gerätes | Hier]] geht's zum Beitrag.

=== Eine Device spezifische Aufbewahrungszeit (Retention Time) in der Datenbank realisieren ===

In der DbLog Datenbank gespeicherte Daten müssen bzw. sollten regelmäßig gelöscht werden sofern sie nicht mehr für Auswertungen verwendet werden. Über DbRep Kommandos gibt es dafür viele Möglichkeiten.

Vorgestellt wird hier die Möglichkeit, bereits beim Logging des Events mittels Attribut eine Device spezifische Aufbewahrungszeit festzulegen. Diese Möglichkeit ist ab der DbLog Version 5.9.4 gegeben. Die einzelnen Schritte zur Umsetzung werden nachfolgend beschrieben.

* im global Device das userattr '''retentionPeriod''' definieren. Der Name des Attributes ist natürlich frei wählbar. Das Attribut steht in allen Devices zur Verfügung und bestimmt die Aufbewahrungszeit in Sekunden wenn im Device oder im DbLog Device gesetzt.
<pre>
attr global userattr retentionPeriod
</pre>

* Für die Speicherung des Verfallzeitpunktes in der Datenbank wird die Tabellenspalte EVENT in der Tabelle history verwendet. Normalerweise wird der komplette zu loggende Event in dieser Spalte gespeichert, was im Allgemeinen nicht benötigt wird. Dazu wird in dem relevanten DbLog Device das Attribut '''valueFn''' gesetzt um in jedem zu loggenden Datensatz die Spalte EVENT die spezifische Verfallszeit zu speichern:
<pre>
{
my $def = AttrVal ($NAME, 'retentionPeriod', 9999999999);
$EVENT = int(time) + AttrVal ($DEVICE, 'retentionPeriod', $def);
}
</pre>

* Im gleichen DbLog Device wird das Attribut '''retentionPeriod''' auf einen Default Wert gesetzt der gelten soll, wenn im zu loggenden Datensatz kein retentionPeriod-Attribut im Quellen-Device hinterlegt ist. Wenn kein retentionPeriod-Attribut im DbLog Device gesetzt ist, erfolgt mit dem Wert 'int(time) + 9999999999' de facto eine zeitlich unbegrenzte Speicherung.

<pre>
attr <DbLog> retentionPeriod 7776000 (Beispiel für Haltezeit von 90 Tagen = 7776000 Sekunden)
</pre>

[[Bild:Screenshot 2024-01-03 210126.png|right|thumb|400px|]]
* In jedem relevanten Device wird nun die gewünschte Aufbewahrungszeit in Sekunden gesetzt:
<pre>
attr <Device> retentionPeriod xxxxxxxxx
</pre>

Im Cache des DbLog Devices findet man jetzt in jedem Datensatz den Verfallszeitpunkt des Datensatzes. Er wird in der EVENT-Spalte der Tabelle gespeichert.

Vor den nächsten Schritten ist sicherzustellen, dass EVENT bei bereits vorhandenen Datensätzen auf einen passenden Verfallszeitpunkt upgedated werden.
Dazu eignet sich sqlCmd im DbRep oder ein SQL Editor deiner Wahl:

<pre>
UPDATE history SET TIMESTAMP=TIMESTAMP, EVENT="1704353074"; (setzt den Verfall auf 04.01.2024 08:24:34)
</pre>

Damit die Datenlöschungen über eine Auswertung von EVENT später performant ausgeführt werden, sollte ein ensprechender Index angelegt werden und der Datentyp von EVENT in Integer geändert werden. Beide SQL Statements können mit einem DbRep-Device mit gesetzten '''adminCredentials''' über "set ... sqlCmd" ausgeführt werden:

<pre>
CREATE INDEX Retention_Idx ON `history` (EVENT);
ALTER TABLE history MODIFY COLUMN EVENT INT(15);
</pre>

Die veränderte Spaltenbreite von EVENT wird im DbLog-Device nachgezogen und das Attribut '''colEvent''' gesetzt:

<pre>
attr <DbLog> colEvent 15
</pre>

Zur regelmäßigen Löschung der Datensätze mit einer abgelaufenen Aufbewahrungszeit dient ein at-Device in Verbindung mit einem DbRep-Device (z.B. Rep.fhemtest1) welches täglich abgelaufene Datensätze sucht und löscht.
Die Definition des at-Devices:

<pre>
define At.RetentionDel at *23:15:00 {
my $t = int(time);
fhem "set Rep.fhemtest1 sqlCmd delete from history where EVENT<'$t'";
}
</pre>

Das DbRep-Device benötigt keine besonderen Einstellungen außer einem gesetzten Attribut '''allowDeletion=1'''.

<pre>
define Rep.fhemtest1 DbRep <DbLog-Device>
attr Rep.fhemtest1 allowDeletion 1
attr Rep.fhemtest1 event-on-update-reading state
attr Rep.fhemtest1 room DbLog
attr Rep.fhemtest1 showproctime 1
</pre>

 

=== Welche Device/Reading-Kombinationen gibt es in der Datenbank ? ===
'''Hinweis:''' Im aktuellen DbRep-Release kann die nachfolgend beschriebene Auswertung alternativ durch die eingebauten Kommmandos:
set <DbRep-Device> sqlSpecial allDevCount
set <DbRep-Device> sqlSpecial allDevReadCount
ausgeführt werden.

Wenn eine Datenbank längere Zeit gelaufen ist und die zu loggenden Devices bzw. Readings immer mal wieder geändert wurden, wächst der Wunsch einen Überblick über die in der DB enthaltenen Devices/Reading-Kombinationen zu erhalten.
Dadurch können wiederum gezielt Auswertungen auf eine bestimmte Device/Reading-Kombination durchgeführt werden.

Um dieses Ziel zu erreichen, wird ein DbRep-Device erstellt welches für die Verwendung eines User-Command eingerichtet wird.
Je nach dem gewünschten Ergebnis wird eines der nachfolgenden SQL-Kommandos verwendet.

Selektion aller Device/Reading-Kombinationen in der Datenbank:
select device, reading, count(*) from history group by DEVICE, READING

Nur die geloggten Devices in der Datenbank reporten:
select device, count(*) from history group by DEVICE

Zur Einrichtung wird zunächst das DbRep-Device definiert:

define Rep.LogDB.sqlResult DbRep LogDB

Dabei ist "LogDB" '''nicht''' die Datenbank, sondern das DbLog-Device mit dem das DbRep-Device assoziiert und derüber mit der Datenbank verbunden wird !

Um die Ausgabe des späteren Ergebnisses zu formatieren wird das Attribut "sqlResultFormat" auf "table" gesetzt. Dadurch wird das Selektergebnis als Tabelle mit den Spalten Device, Reading und der Anzahl der enthaltenen Datensätze der jeweiligen Kombination erzeugt.

attr Rep.LogDB.sqlResult sqlResultFormat table

Natürlich kann auch ein anderes Ausgabeformat gewählt werden wenn gewünscht oder benötigt. Bei großen Ergebnismengen ist zur Erhöhung der Übersichtlichkeit das Attribut "sqlResultFormat = separated" wahrscheinlich eher geeignet.

Das Attribut stateFormat wird entsprechend gesetzt um nach einem erfolgten Selektionslauf die erzeugte Tabelle in der Raumansicht bzw. im DeviceOverview anzuzeigen:

<pre>
attr Rep.LogDB.sqlResult stateFormat { if (defined($defs{$name}{READINGS}{SqlResult})) {
ReadingsVal($name,"SqlResult",undef);
} else {
ReadingsVal($name,"state",undef);
}
}
</pre>

Damit ist das DbRep-Device vorbereitet und der Auswertungslauf kann gestartet werden mit:

set Rep.LogDB.sqlResult sqlCmd select device, reading, count(*) from history group by DEVICE, READING;

bzw. wenn nur die in der Datenbank enthaltenen Devices zu erhalten:

set Rep.LogDB.sqlResult sqlCmd select device, count(*) from history group by DEVICE;

[[Datei:sqlResult.PNG|right|thumb|600px|set Rep.LogDB.sqlResult sqlCmd select device, count(*) from history group by DEVICE;]]

Nebenstehender Screenshot zeigt das Ergebnis der Auswertung aller in der Datenbank enthalteten Devices und deren Anzahl von Datensätzen.

Zum leichteren Nachnutzung hier noch die Raw-Definition des fertigen DbRep-Devices:

<pre>
defmod Rep.LogDB.sqlResult DbRep LogDB
attr Rep.LogDB.sqlResult aggregation no
attr Rep.LogDB.sqlResult comment Device zum freien Report mit sqlCmd.\
- Auswahl von Statements -\
\
Device/Reading-Kombinationen in der Datenbank:\
select device, reading, count(*) from history group by DEVICE, READING\
\
geloggte Devices in der Datenbank:\
select device, count(*) from history group by DEVICE\

attr Rep.LogDB.sqlResult devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.LogDB.sqlResult disable 0
attr Rep.LogDB.sqlResult event-on-update-reading state
attr Rep.LogDB.sqlResult group Datenbankauswertungen
attr Rep.LogDB.sqlResult room DbLog
attr Rep.LogDB.sqlResult showproctime 1
attr Rep.LogDB.sqlResult sqlResultFormat table
attr Rep.LogDB.sqlResult stateFormat { if (defined($defs{$name}{READINGS}{SqlResult})) {\
ReadingsVal($name,"SqlResult",undef);;\
} else {\
ReadingsVal($name,"state",undef);;\
} \
}
attr Rep.LogDB.sqlResult timeout 1000
attr Rep.LogDB.sqlResult verbose 2
</pre>

=== Die current-Tabelle mit einem Extrakt der history-Tabelle füllen (tableCurrentFillup) ===

Diese Funktion erweitert die Möglichkeiten der Verwendung der current-Tabelle des DbLog-Devices. In den meisten Fällen wird im DbLog das Attribut "DbLogType = Current/History" gesetzt sein um bei der Erstellung von SVG's entsprechende Vorschläge in der DropDown-Liste des Editors zur Verfügung zu haben.

Bei dieser Betriebsart werden in der current-Tabelle neu auftretende Events von Device/Reading-Kombinationen eingetragen, sofern sie noch nicht enthalten sind. Werden neue Geräte definiert, erscheinen deren Events in der current-Tabelle, auch wenn man später nicht benötigte Readings mit den Attributen "event-on-change-reading" oder "event-on-update-reading" ausgrenzt.
Die einmal gespeicherten Werte bleiben in der current Tabelle erhalten. Sicherlich wird deswegen der eine oder andere User den Inhalt der current Tabelle löschen um wieder eine leere und saubere current-Tabelle zu haben. Das führt dann natürlich dazu, dass nur die ab diesem Zeitpunkt auftretenden Events in der Vorschlagsliste aufgenommen werden und nur selten auftretende Device/Reading-Kombinationen erst nach längerer Zeit wieder in der Tabelle current gespeichert werden.

Darüber hinaus möchte man vielleicht nur für SVG-Diagramme relevante Device/Reading-Einträge in der Vorschagsliste vorfinden oder dort nur Einträge vorhalten, die in den letzten drei Monaten aufgetreten sind. Die Beweggründe können sehr vielfältig sein.
Um diesem Wunsch zu entsprechen, gibt es im DbRep die Funktion "set <DbRep-Device> tableCurrentFillup", die eng mit dem dem DbLog-Attribut "DbLogType = SampleFill/History" zusammenarbeitet.

Nachfolgend wird an einem Beispiel erläutert, welche Konfigurationen vorgenommen werden können, um aus der history-Tabelle alle vorhandenen Device/Reading-Kombinationen zu extrahieren und sie zur Verwendung als SVG-Vorschlagsliste in die current-Tabelle einzufügen.

Für das Beispiel wird folgendes angenommen:

* es gibt ein definiertes DbLog-Device "LogDB" welches in die Datenbank "fhem" loggt
* das DbRep-Device zur Ausführung der Funktion wird "Rep.FillCurr.fhem" genannt
* es sollen alle in der history-Tabelle vorkommenden Device/Reading-Kombinationen extrahiert und in die current-Tabelle eingetragen werden (Einschränkungen auf bestimmte Devices / Readings oder zeitliche Abgrenzungen werden nicht vorgenommen, aber es wird darauf hingewiesen, wie es gemacht werden kann)

==== a) Anlegen des DbRep-Devices ====

Die Definition des DbRep-Devices erfolgt unter Angabe des zu verbindenden DbLog-Devices (nicht der Datenbank selbst):

define Rep.FillCurr.fhem DbRep LogDB

In dem so definierten neuen Device sind die Attribute zu setzen, die für die beabsichtigte Funktion wichtig sind.
Da dieses Device auch für die Löschung der in der current-Tabelle gespeicherten Datensätze verwendet wird, muss das Attribut "allowDeletion = 1" gesetzt werden.

attr Rep.FillCurr.fhem allowDeletion 1

Ebenfalls wichtig ist die Erzeugung eines Events sobald der Löschvorgang der current-Tabelle abgeschlossen ist. Dazu wird im Beispiel "event-on-update-reading" verwendet:

attr Rep.FillCurr.fhem event-on-update-reading state,--DELETED_ROWS_CURRENT--

[[Datei:currdelete.PNG|right|thumb|300px|set Rep.FillCurr.fhem tableCurrentPurge]]
Für die Funktion nicht wichtig, aber durchaus interessant zu wissen wie lange die Laufzeit der Funktionen ist, wird noch das Attribut "showproctime = 1" gesetzt. Damit werden die Readings "background_processing_time" und "sql_processing_time" erzeugt welche die jeweilige Bearbeitungszeit in Sekunden darstellen.

attr Rep.FillCurr.fhem showproctime 1

Mit dem so vorbereiteten Device können schon die Funktionen "tableCurrentPurge" und "tableCurrentFillup" manuell getestet werden. Mit dem Kommando:

set Rep.FillCurr.fhem tableCurrentPurge

wird der gesamte aktuelle Inhalt der current-Tabelle gelöscht. Wie im nebenstehenden Screenshot sichtbar, wurden in dem Beispiel 170 Datensätze gelöscht und dazu rund 30ms benötigt. Mit Abschluß der Operation wird der Delete-Event erzeugt:

2018-01-05 13:38:14.596 DbRep Rep.FillCurr.fhem --DELETED_ROWS_CURRENT--: 170

[[Datei:currfillup.PNG|right|thumb|300px|set Rep.FillCurr.fhem tableCurrentFillup]]
Dieser Event wird später in einem Notify für die automatisierte Current-Auffüllung verwendet.
Eine Zählug der current-EInträge mit "set Rep.FillCurr.fhem countEntries current" ergibt "-", d.h. der Löschbefehl war erfolgreich. Im jetzigen Zustand würde bei der Erstellung eines SVG keine DropDown-Liste angezeigt werden und statt dessen die Felder im SVG-Editor frei bearbeitbar sein, weil die current-Tabelle keine Werte enthält.
Gleichermaßen kann bereits die Auffüllung der current-Tabelle getestet werden mit dem Befehl:

set Rep.FillCurr.fhem tableCurrentFillup

Je nach Größe der Datenbank kann diese Operation einige Zeit in Anspruch nehmen. Da dieser Befehl wie bei DbRep üblich non-blocking abgearbeitet wird, hat die Laufzeit keinen Einfluss auf die sonstige FHEM-Verfügbarkeit.

[[Datei:svgfillup.PNG|left|thumb|300px|set Rep.FillCurr.fhem tableCurrentFillup]]
Wie bereits erwähnt, wird in dem Beispiel die gesamte history-Tabelle ausgewertet. Sollen zum Beispiel nur die letzten 90 Tage zur Auswertung herangezogen werden, kann das '''Attribut "timeDiffToNow = d:90"''' gesetzt werden.

Weitere Eingrenzungen bzgl. der auszuwertenden Devices bzw. Readings können über die '''Attribute "device" und "reading"''' vorgenommen werden. Die Syntax für die genannten Attribute und deren Auswirkung entnehme bitte der {{Link2CmdRef|Lang=de|Anker=DbRepattr}}.

In unserem Beispiel wurde die current-Tabelle mit 170 Datensätzen aufgefüllt. Dazu wurden 291 Sekunden benötigt (die Tabelle history enthält insgesamt rund 11 Mio. Einträge)

Wird jetzt ein neues SVG erstellt, erscheinen alle in selektierten Device/Reading-Kombinationen alphabetisch sortiert als DopDown-Liste im SVG-Editor.

==== b) Konfiguration des DbLog-Devices ====

In dem bestehen DbLog-Device "LogDB" ist zur Vorbereitung lediglich das Attribut "DbLogType = SampleFill/History" zu setzen:

attr LogDB DbLogType SampleFill/History

Entgegen der Arebeitsweise mit "Current/History" wird die current-Tabelle nicht mehr durch die Logging-Engine aktiv mit jedem relevanten Event gefüllt, sondern kann durch externe Tools, in dem Fall dem DbRep-Device, beschrieben werden.
Die current-Tabelle wird aber, ob leer oder gefüllt, bei der Erstellung eines SVG-Devices ausgewertet und in Abhängigeit des Ergebnisses eine DropDown-Liste zur Verfügung gestellt, oder frei editierbare Felder angeboten falls die current-Tabelle leer ist.

==== c) Definition der at/notify-Devices zum automatisierten Ablauf ====

Die Löschung des Inhaltes der current-Tabelle und die erneute Ausffüllung soll natürlich autmatisiert regelmäßig erfolgen. Zu diesem Zweck wird ein at-Device (At.LogDB.currentPurge) und ein notify-Device angelegt. Das AT-Device soll alle 8 Stunden und 15 Minuten das Löschen des current-Inhaltes steuern und nach Abschluß der Löschung soll getriggert durch das "--DELETED_ROWS_CURRENT--"-Event die Neubefüllung der current-Tabelle veranlasst werden.

Zur Definition dieser Devices gibt es nicht viel zu erläutern. Die entsprechende Syntax kann bei {{Link2CmdRef|Lang=de|Anker=at|Label=at}} bzw. {{Link2CmdRef|Lang=de|Anker=notify|Label=notify}} in der {{Link2CmdRef|Lang=de}} nachgelesen werden.

'''at-Device:'''

define At.LogDB.currentPurge at +*08:15:00 set Rep.FillCurr.fhem tableCurrentPurge

'''notify-Device:'''

define N.LogDB.Fillup notify Rep.FillCurr.fhem:.*DELETED_ROWS_CURRENT.* sleep 5;set Rep.FillCurr.fhem tableCurrentFillup

Das nichtblockierende FHEM-sleep (sleep gefolgt von einem weiteren Befehl) wird lediglich dazu verwendet, um zwischen der Delete- und Auffüll-Operation eine kleine Pause einzufügen.

==== d) Arbeitsweise und Raw-Definitionen ====

Durch das "At.LogDB.currentPurge"-Device wird alle 8 Stunden und 15 Minuten ein Löschlauf der current-Tabelle gestartet. Dadurch wird dem darauf folgenden Auffüllprozess immer eine saubere leere current-Tabelle zur Verfügung gestellt. Nach dem Löschlauf wird durch das "N.LogDB.Fillup"-Device, getriggert durch den Event "Rep.FillCurr.fhem:.*DELETED_ROWS_CURRENT.*", die erneute Auffüllung der current-Tabelle gestartet.
Die Daten werden aus der histrory-Tabelle gelesen, wobei der Zeitraum der Selektion und die zu betrachtenden Devices / Readings durch die Zeit-Attribute bzw. device / reading-Attribute des DbRep-Devices "Rep.FillCurr.fhem" individuell beeinflußt werden können.

Hilfreich ist es auch, wenn das DbLog-Device "LogDB" im asynchronen Modus betrieben wird.

Abschließend sind hier noch die Raw-Definitionen der beteiligten Devices (außer LogDB) angehängt, um das Beispiel leicht nachvollziehbar zu gestalten.

'''DbRep-Device "Rep.FillCurr.fhem":'''

<pre>
defmod Rep.FillCurr.fhem DbRep LogDB
attr Rep.FillCurr.fhem allowDeletion 1
attr Rep.FillCurr.fhem comment Current Fillup für DB fhem
attr Rep.FillCurr.fhem devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.FillCurr.fhem event-on-update-reading state,--DELETED_ROWS_CURRENT--
attr Rep.FillCurr.fhem icon icoTool
attr Rep.FillCurr.fhem room DbLog
attr Rep.FillCurr.fhem showproctime 1
attr Rep.FillCurr.fhem verbose 3
</pre>

'''at-Device "At.LogDB.currentPurge":'''

<pre>
defmod At.LogDB.currentPurge at +*08:15:00 set Rep.FillCurr.fhem tableCurrentPurge
attr At.LogDB.currentPurge comment Zeitgesteuertes Löschen der Current Tabelle. Nach dem Löschen wird \
Eventgesteuert (Notify N.LogDB.Fillup) ein tableCurrentFillup gestartet.
attr At.LogDB.currentPurge room DbLog
</pre>

'''notify-Device "N.LogDB.Fillup":'''

<pre>
defmod N.LogDB.Fillup notify Rep.FillCurr.fhem:.*DELETED_ROWS_CURRENT.* sleep 5;;set Rep.FillCurr.fhem tableCurrentFillup
attr N.LogDB.Fillup disable 1
attr N.LogDB.Fillup room DbLog
attr N.LogDB.Fillup verbose 2
</pre>

=== Backup/Restore einer SQLite Datenbank im laufenden Betrieb ===

In diesem Beitrag wird erläutert, wie man mit DbRep ein Backup der SQLite-Datenbank erstellen kann, welche Möglichkeiten es dabei gibt und wie man eine Datenbank aus einem Backup wieder herstellen kann.
Die Backup-Funktion nutzt die SQLite Online Backup API und ermöglicht es, konsistente Backups der SQLite-DB in laufenden Betrieb zu erstellen ohne die Datenbank schließen zu müssen.

Neben dem eigentlichen Backup kann optional einstellt werden, dass:

* vor dem Backup eine Datenbankoptimierung (Vacuum) ausgeführt werden soll. Dadurch wird Plattenplatz freigegeben sofern möglich.
* vor und nach dem Backup kann ein FHEM-Kommando oder eine Perl-Routine ausgeführt werden (eine Perl-Routine ist in {} einzuschließen)
* das erstellte Dumpfile kann über FTP(S) an einen FTP-Server übertragen werden
* über die interne Versionsverwaltung kann festgelegt werden, wieviele erstellte Backups auf dem Datenträger erhalten bleiben sollen (default: 3)

Für die Erläuterung des Beispiels soll ein DbRep-Device erstellt werden, welches:

* die SQLite Datenbank im Betrieb (Online) sichert
* vor dem Dump einen Vacuum-Lauf durchführt
* das erstellte Dumpfile auf einen FTP-Server überträgt
* 2 Versionen (Dumpfiles) nach einem erfolgreichen Backuplauf im Dumpverzeichnis verbleiben sollen

==== 1. Anlegen des DbRep-Devices ====

Das anzulegende Device wird sowohl für das (regelmäßige) Backup als auch für einen eventuellen Restore verwendet.
Die Definition des DbRep-Devices erfolgt unter Angabe des zu verbindenden DbLog-Devices (nicht der Datenbank selbst):

define Rep.SQLite DbRep LogSQLITE

Ist das Device definiert, verbindet es sich zu der Datenbank und wechselt in den state "connected", sofern die Verbindung erfolgreich verlief.
Prinzipiell funktioniert der hier beschriebene Backup-Prozess mit einem im synchronous Mode betriebenen DbLog-Device, aber es ist dringend angeraten das DbLog-Device (LogSQLITE) in den asynchronen Modus umzuschalten. Dadurch werden Blockierungen von FHEM und Verluste von Daten verhindert.

==== 2. Einstellungen des DbRep-Devices (Attribute) ====

Für die gewünschte Funktion müssen in diesem neu definierten Device einige relevante Attribute gesetzt werden.

:'''a) dumpDirLocal'''

Das zu erstellende Backupfile wird per default im log-Verzeichnis ./log (meist /opt/fhem/log) des FHEM-Rechners gespeichert. Um es an einer anderen Stelle zu speichern kann das Attribut "dumpDirLocal" gesetzt werdden. Dieses Verzeichnis kann sich auf dem lokalen Datenträger befinden, oder ein per NFS gemountetes Verzeichnis sein. In jedem Fall muss der User unter dem FHEM läuft Schreibrechte auf dieses Verzeichnis besitzen.

Für das Beispiel sollen die Dump-Files auf einen NFS-Mount einer Synology Diskstation gespeichert werden. Dazu wurde ein Mount in /etc/fstab erstellt um den Pfad "/sds1/backup" lokal verfügbar zu machen:

sds1.<fqdn>:/volume1/ApplicationBackup /sds1/backup nfs auto,defaults,tcp,intr 0 0

In diesem Verzeichnis exsitiert das Directory "dumps_FHEM", in dem die Backup-Files gespeichert werden sollen. Das Attribut wird entsprechend gesetzt auf:

attr Rep.SQLite dumpDirLocal /sds1/backup/dumps_FHEM

:'''b) dumpFilesKeep'''

Dieser Parameter stellt die Anzahl der aufzubewahrenden Backup-Files ein. Es werden immer die "x" neuesten bzw. letzten Files im Verzeichnis gehalten, wobei nur die zu der jeweiligen Datenbank gehörenden Files betrachtet werden.
Die Zugehörigkeit des Dump-Files zur Quelldatenbank wird anhand des Filenamens ermittelt, der sich zusammensetzt aus <DB-Name ohne Endung>_<Erstellungsdatum und Uhrzeit>.sqlitebkp

Beispiel: fhem_2018_01_12_17_15.sqlitebkp

Ist dieses Attribut nicht gesetzt, werden die 3 neuesten Backup-Files im Verzeichnis behalten.
Um nur 2 Files zu behalten wird das Attribut gesetzt auf:

attr Rep.SQLite dumpFilesKeep 2

:'''c) Aktionen vor und nach dem Backup ausführen'''

Vor und nach der Dump-Ausführung kann ein FHEM-Kommando bzw. Perl-Befehle ausgeführt werden. Perl-Befehle müssen in {} eingeschlossen werden.
Für das Beispiel soll vor dem Backup die Verbindung des DbLog-Devices LogSQLITE zur Datenbank getrennt werden. Dadurch werden keine neuen Daten in die Datenbank geschrieben. Wenn das DbLog-Device LogSQLITE im asynchronen Modus wie empfohlen betrieben wird, tritt auch kein Datenverlust ein, da die zu loggenden Daten im Cache verbleiben bis die Verbindung zur DB wieder hergestellt wird.

Es sei noch einmal darauf hingewiesen, dass das Backup-Verfahren ebenso im synchronen Modus und ohne das DbLog-Device von der Datenbank zu trennen, funktioniert und nur im Beispiel zur Demonstation der Möglichkeiten dient.

Um die Verbindung zu trennen wird ein "set LogSQLITE reopen <Zeit in Sekunden>" verwendet. Die Zeitspanne wird sehr großzügig gewählt und soll sicherstellen, dass innerhalb dieser Zeit das Backup abgeschlossen ist. Nach dem Backup wird sofort ein "set LogSQLITE reopen" ausgeführt, was die Verbindung des DbLog-Devices LogSQLITE zur Datenbank unmittelbar wieder herstellt..

attr Rep.SQLite executeBeforeProc set LogSQLITE reopen 3600
attr Rep.SQLite executeAfterProc set LogSQLITE reopen

:'''d) vor dem Backup Datenbank verkleinern (vacuum)'''

Diese optionale Funktion wird durch das Attribut "optimizeTablesBeforeDump" eingeschaltet. Dadurch die Vacuum-Funktion wird Platz innerhalb der Datenbank freigegeben der durch Löschvorgänge entstanden ist und dadurch die Größe des Datenbankfiles verringert.

attr Rep.SQLite optimizeTablesBeforeDump 1

:'''e) das Dump-File nach dem Backup zum FTP-Server übertragen'''

DbRep bietet die Möglichkeit, das erstellte Dump-File per FTP oder verschlüsselt per FTP(S) zum Server zu übertragen. Dazu gibt es einen Satz von Attributen um dem Device alle notwendigen Angaben für den FTP-Transfer zur Verfügung zu stellen. Es gibt dafür folgende Attribute:

* ftpUse : FTP Transfer nach dem Dump wird eingeschaltet (bzw. ftpUseSSL mit SSL Verschlüsselung)
* ftpUser : User zur Anmeldung am FTP-Server, default: anonymous
* ftpPwd : Passwort des FTP-Users, default nicht gesetzt
* ftpDir : Verzeichnis auf dem FTP-Server in welches das File übertragen werden soll (default: FTP-root)
* ftpPort : FTP-Port, default: 21
* ftpServer : Name oder IP-Adresse des FTP-Servers
* ftpTimeout : Timeout für die FTP-Verbindung in Sekunden (default: 30)
* ftpPassive : setzen wenn passives FTP verwendet werden soll
* ftpDebug : Debugging des FTP Verkehrs zur Fehlersuche

Gemäß dieser Beschreibung und dem Ziel dieses Beispiels werden die für FTP-Transfer relevanten Attribute wie folgt gesetzt:

attr Rep.SQLite ftpDir /ftp # Subdirectory ftp unter FTP-root als Zielverzeichnis
attr Rep.SQLite ftpPwd ftpftp1
attr Rep.SQLite ftpServer sds1.<fqdn>
attr Rep.SQLite ftpUse 1
attr Rep.SQLite ftpUser ftpuser

Der FTP-Server muss natürlich vorab eingerichtet und funktionsfähig sein. Sollten beim FTP-Transfer Fehler auftreten, kann das Attribut ftpDebug = 1 gesetzt werden um entsprechende Ausgaben zur Analyse des Problems im Log zu erhalten.

[[Datei:repsqlite_defined.PNG|right|thumb|300px|Fertig definiertes Device Rep.SQLite]]

:'''f) Hilfsattribute'''

Für die Funktion nicht relevant aber informativ ist das Attribut "showproctime = 1". Ist das Attribut gesetzt, wird das Reading "background_processing_time" angelegt. Es enthält nach der Ausführung die verbrauchte Prozesszeit.

Das fertig konfigurierte Device hier als RAW-Definition zur einfachen Nachnutzung. Die Angaben sind natürlich anzupassen:

<pre>
define Rep.SQLite DbRep LogSQLITE
attr Rep.SQLite devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.SQLite dumpDirLocal /sds1/backup/dumps_FHEM
attr Rep.SQLite dumpFilesKeep 2
attr Rep.SQLite event-on-update-reading state
attr Rep.SQLite executeAfterProc set LogSQLITE reopen
attr Rep.SQLite executeBeforeProc set LogSQLITE reopen 3600
attr Rep.SQLite ftpDir /ftp
attr Rep.SQLite ftpPwd ftpftp1
attr Rep.SQLite ftpServer sds1.<fqdn>
attr Rep.SQLite ftpUse 1
attr Rep.SQLite ftpUser ftpuser
attr Rep.SQLite optimizeTablesBeforeDump 1
attr Rep.SQLite room DbLog
attr Rep.SQLite showproctime 1
attr Rep.SQLite verbose 3
</pre>

 

==== 3. Backup durchführen ====

Mit dem wie beschrieben eingerichteten DbRep-Device kann das Buckup gestartet werden mit:

set Rep.SQLite dumpSQLite

[[Datei:logsqlite_closeduntil.PNG|right|thumb|500px|LogSQLITE ist geschlossen bis ...]]

Zu Beginn des Vorgangs wird sofort die Verbindung des DbLog-Devices zur Datenbank getrennt.
Ein laufendes Backup kann mit "set Rep.SQLite cancelDump" abgebrochen werden.
Das laufende Backup wird im state angezeigt mit "SQLite Dump is running - be patient and see Logfile !". Dieser Satz ist ernst gemeint, wobei der Dump über die Online-API sehr schnell arbeitet. Im Logfile mit (mindestens) verbose 3 werden die relevanten Informationen zur Verfügung gestellt:

<pre>
2018.01.13 08:35:10.745 3: DbRep Rep.SQLite - ################################################################
2018.01.13 08:35:10.746 3: DbRep Rep.SQLite - ### New SQLite dump ###
2018.01.13 08:35:10.747 3: DbRep Rep.SQLite - ################################################################
2018.01.13 08:35:10.748 3: DbRep Rep.SQLite - execute command before dump: 'set LogSQLITE reopen 3600'
2018.01.13 08:35:10.883 2: DbLog LogSQLITE: Connection closed until 09:35:10 (3600 seconds).
2018.01.13 08:35:10.917 3: DbRep Rep.SQLite - Size of database /opt/fhem/fhem.db before optimize (MB): 2554
2018.01.13 08:35:10.918 3: DbRep Rep.SQLite - VACUUM database /opt/fhem/fhem.db....
2018.01.13 08:44:04.216 3: DbRep Rep.SQLite - Size of database /opt/fhem/fhem.db after optimize (MB): 2554
2018.01.13 08:44:04.280 3: DbRep Rep.SQLite - Starting dump of database 'fhem.db'
2018.01.13 08:45:03.810 3: DbRep Rep.SQLite - Size of backupfile: 2553.64 MB
2018.01.13 08:45:04.579 3: DbRep Rep.SQLite - FTP: transferring /sds1/backup/dumps_FHEM/fhem_2018_01_13_08_44.sqlitebkp
2018.01.13 08:45:48.838 3: DbRep Rep.SQLite - FTP: fhem_2018_01_13_08_44.sqlitebkp transferred successfully to sds1.myds.me into dir /ftp
2018.01.13 08:45:48.844 3: DbRep Rep.SQLite - Deleting old dumpfile 'fhem_2018_01_13_08_13.sqlitebkp'
2018.01.13 08:45:49.273 3: DbRep Rep.SQLite - Finished backup of database fhem - total time used: 638 seconds
2018.01.13 08:45:49.358 2: DbRep Rep.SQLite - command after dump message: "Reopen executed."
2018.01.13 08:45:49.370 3: DbRep Rep.SQLite - Database dump finished successfully.
</pre>

[[Datei:repsqlite_dumprunning.PNG|right|thumb|400px|das Backup läuft]]

Setzt man das Attribut "ftpDebug=1", erhält man im Log zusätzliche Informationen zum FTP-Transfer:

<pre>
2018.01.13 08:50:22.385 3: DbRep Rep.SQLite - Size of backupfile: 2553.82 MB
Net::FTP>>> Net::FTP(2.79)
Net::FTP>>> Exporter(5.72)
Net::FTP>>> Net::Cmd(2.30)
Net::FTP>>> IO::Socket::INET(1.35)
Net::FTP>>> IO::Socket(1.38)
Net::FTP>>> IO::Handle(1.35)
Net::FTP=GLOB(0xb12ed20)<<< 220 SDS1 FTP server ready.
Net::FTP=GLOB(0xb12ed20)>>> USER ftpuser
Net::FTP=GLOB(0xb12ed20)<<< 331 Password required for ftpuser.
Net::FTP=GLOB(0xb12ed20)>>> PASS ....
Net::FTP=GLOB(0xb12ed20)<<< 230 User ftpuser logged in, access restrictions apply.
Net::FTP=GLOB(0xb12ed20)>>> TYPE I
Net::FTP=GLOB(0xb12ed20)<<< 200 Type set to I.
Net::FTP=GLOB(0xb12ed20)>>> CWD /ftp
Net::FTP=GLOB(0xb12ed20)<<< 250 CWD command successful.
2018.01.13 08:50:22.880 3: DbRep Rep.SQLite - FTP: transferring /sds1/backup/dumps_FHEM/fhem_2018_01_13_08_49.sqlitebkp
Net::FTP=GLOB(0xb12ed20)>>> PORT 192,168,2,45,145,42
Net::FTP=GLOB(0xb12ed20)<<< 200 PORT command successful.
Net::FTP=GLOB(0xb12ed20)>>> ALLO 2677867520
Net::FTP=GLOB(0xb12ed20)<<< 202 ALLO command ignored.
Net::FTP=GLOB(0xb12ed20)>>> STOR fhem_2018_01_13_08_49.sqlitebkp
Net::FTP=GLOB(0xb12ed20)<<< 150 Opening BINARY mode data connection for 'fhem_2018_01_13_08_49.sqlitebkp'.
Net::FTP=GLOB(0xb12ed20)<<< 226 Transfer complete.
2018.01.13 08:51:06.859 3: DbRep Rep.SQLite - FTP: fhem_2018_01_13_08_49.sqlitebkp transferred successfully to sds1.myds.me into dir /ftp
</pre>

[[Datei:repsqlite_dumpfinished.PNG|right|thumb|500px|Backup ist erfolgreich abgeschlossen]]

In vorliegenden Beispiel wird nach einem erfolgreichen Backup im state "Warning - dump finished, but command after dump message appeared" angezeigt. Diese Warnung rührt daher, dass das Reopen-Kommando eine Rückkehrinfo mitteilt, die als Problem gewertet und im Reading "afterdump_message" ausgegeben wird. In diesem Fall ist es nur eine Information.

In den erstellten Readings wird zusammengetragen welches File mit welcher Größe ertsellt wurde, welche alten Files gelöscht wurden, Informationen zum FTP-Transfer und welche Zeit der Gesamtprozess benötgt hat.

Das so vorbereitete Backup kann nun z.B. täglich oder auch mit einer wesentlich kürzeren Wiederholungsperiode (alle x Stunden) über ein at-Device eingeplant werden:

define At.SQLite.Dump at *23:52:00 set Rep.SQLite dumpSQLite

==== 4. Restore ====

Sollte es einmal zur Korruption des Datenbankfiles kommen (database disk image is malformed) und Reparaturversuche erfolglos bleiben, kann ein Restore die einzigste oder vielleicht auch einfachste Möglichkeit sein die Datenbank wieder herzustellen.

Das kann mit dem angelegten DbRep-Device im laufenden Betrieb geschehen. Auch hier ist wieder wichtig, dass das DbLog-Device LogSQLITE im asynchronen Modus betrieben wird und die Reopen-Zeit (siehe Einstellung Attribut "executeBeforeProc") sehr großzügig eingestellt ist.

Zum Restore gibt es den Befehl "set ... restoreSQLite <File>".

[[Datei:sqliterestore_auswahl.PNG|right|thumb|500px|Auswahlmenü Files für Restore ]]

Im FHEMWEB öffnet sich dazu eine DropDown-Liste die alle vorhandenen und zur Quelldatenbank passenden Dumpfiles auflistet. Das herzustellende File
kann so bequem ausgewählt werden. Die Dumpfiles müssen sich in dem Verzeichnis befinden, welches durch das Attribut "dumpDirLocal" festgelegt wurde (default (./log). [[Datei:sqliterestore_running.PNG|left|thumb|500px|Restore läuft]]

Der restore wird demzufolge gestartet mit:

set Rep.SQLite restoreSQLite <File>

Wieder wird zu Beginn des Vorgangs das verbundene DbLog-Device von der Datenbank abgekoppelt und nach dem Restore wieder automatisch verbunden. Eine Datenbankoptimierung bzw. FTP-Transfer wird bei diesem Vorgang natürlich nicht ausgeführt.

Das Log zeigt den Prozessverlauf:

<pre>
2018.01.13 09:21:55.435 3: DbRep Rep.SQLite - ################################################################
2018.01.13 09:21:55.437 3: DbRep Rep.SQLite - ### New database Restore/Recovery ###
2018.01.13 09:21:55.437 3: DbRep Rep.SQLite - ################################################################
2018.01.13 09:21:55.438 3: DbRep Rep.SQLite - execute command before restore: 'set LogSQLITE reopen 3600'
2018.01.13 09:21:55.448 2: DbLog LogSQLITE: Connection closed until 10:21:55 (3600 seconds).
2018.01.13 09:21:55.477 3: DbRep Rep.SQLite - Starting restore of database 'fhem.db'
2018.01.13 09:30:12.533 3: DbRep Rep.SQLite - Restore of /sds1/backup/dumps_FHEM/fhem_2018_01_13_08_49.sqlitebkp into 'fhem.db' finished - total time used: 497 seconds.
2018.01.13 09:30:12.685 2: DbRep Rep.SQLite - command after restore message: "Reopen executed."
2018.01.13 09:30:12.700 3: DbRep Rep.SQLite - Database restore finished successfully.
</pre>

Der Restore wurde erfolgreich abgeschlossen und die Verbindung des DbLog-Device LogSQLITE zur Datenbank wiederhergestellt. Das Logging wird nahtlos fortgeführt.

[[Datei:sqliterestore_finished.PNG|right|thumb|300px|Restore erfolgreich abgeschlossen]]

Es ist natürlich zu beachten, dass die Daten zwischen dem Erstellungszeitpunkt des eingespielten Backups und der aktuellen Zeit verloren sind !
Die bestehende (korrupte) Datenbank wird überschrieben. Deswegen ist es ratsam immer ein aktuelles (zeitnahes) Backup zu haben um den Datenverlust möglichst gering zu halten.

==== 5. Links ====
* Diskussion im Forum: "{{Link2Forum|Topic=82674|LinkText=Erstellung konsistentes Online-Backup im laufenden Betrieb}}"

=== Backup/Restore einer MySQL/MariaDB Datenbank im laufenden Betrieb ===

Das Backup einer MySQL/MariaDB Datenbank (im Folgenden stellvertretend als MySQL bezeichnet) kann als Varianten

* clientSide
* serverSide

Beim '''clientSide''' Backup werden die Daten über SQL-Statements aus der Datenbank gelesen, auf dem Client (dem FHEM-Server) verarbeitet und das Dumpfile geschrieben. Es werden history- und current-Tabelle gesichert, sowie eventuell weitere angelegte Tabellen und Views. Allerdings benötigt dieser Modus umfangreichere RAM und CPU-Ressorcen auf dem Client.

Die '''serverSide''' Option wird nachfolgend beispielhaft genauer erläutert.

==== serverSide Backup Option ====

Neben dem eigentlichen Backup kann optional einstellt werden, dass:

* vor dem Backup eine Tabellenoptimierung (optimizeTables) ausgeführt werden soll. Dadurch wird Plattenplatz freigegeben sofern möglich.
* vor und nach dem Backup kann ein FHEM-Kommando oder eine Perl-Routine ausgeführt werden (eine Perl-Routine ist in '''{ }''' einzuschließen)
* das erstellte Dumpfile kann komprimiert werden
* das erstellte Dumpfile kann über FTP(S) an einen FTP-Server übertragen werden
* über die interne Versionsverwaltung kann die Anzahl der im Backupverzeichnis zu verbleibenden Backup-Files festgelegt werden (default: 3)

Für die Erläuterung des Beispiels soll ein DbRep-Device erstellt werden, welches:

* die MySQL Datenbank im Betrieb (Online) sichert
* vor dem Dump die history-Tabelle optimiert
* das erstellte Dumpfile auf einen FTP-Server überträgt
* drei Versionen (Dumpfiles) nach der Übertragung auf dem FTP-Server belässt, ältere Files werden vom FTP-Server gelöscht
* eine Version (Dumpfile) nach einem erfolgreichen Backuplauf im Dumpverzeichnis verbleiben sollen

 

===== 1. Anlegen des DbRep-Devices =====

Das anzulegende Device wird sowohl für das (regelmäßige) Backup als auch für ein eventuelles Restore verwendet.
Die Definition des DbRep-Devices erfolgt unter Angabe des zu verbindenden DbLog-Devices (nicht der Datenbank selbst):

define Rep.fhemtest.Dump.ServerSide DbRep LogDB

Ist das Device definiert, verbindet es sich zu der Datenbank und wechselt in den state "connected", sofern die Verbindung erfolgreich verlief.
Prinzipiell funktioniert der hier beschriebene Backup-Prozess mit einem im synchronous Mode betriebenen DbLog-Device, aber es ist dringend angeraten das DbLog-Device (LogDB) in den asynchronen Modus umzuschalten. Dadurch werden FHEM-Blockierungen vermieden.

 

===== 2. Einstellungen des DbRep-Devices (Attribute) =====

Für die gewünschte Funktion müssen in diesem neu definierten Device einige relevante Attribute gesetzt werden.

:'''a) dumpDirRemote'''

Der Dump wird durch den MySQL-Server erstellt und per default im Home-Verzeichnis des MySQL-Servers gespeichert.
Es wird die gesamte history-Tabelle (nicht current-Tabelle) im '''CSV-Format''' ohne Einschränkungen exportiert.

Um es an einer anderen Stelle zu speichern, wird das Attribut "dumpDirRemote" gesetzt.

Auch wenn der MySQL-Server mit auf dem FHEM-Server läuft, also lokal, wird dieses Attribut zur Veränderung des Zielverzeichnisses verwendet.

 

:'''b) dumpDirLocal'''

Soll die interne Versionsverwaltung und die Dumpfilekompression des Moduls genutzt, sowie die Größe des erzeugten Dumpfiles ausgegeben werden, ist das Verzeichnis "dumpDirRemote" des MySQL-Servers auf dem Client zu mounten und im Attribut "dumpDirLocal" dem DbRep-Device bekannt zu machen.
Gleiches gilt wenn der FTP-Transfer nach dem Dump genutzt werden soll (Attribut "ftpUse" bzw. "ftpUseSSL").

Im Beispiel läuft der MySQL-Server auf einem entfernten Server und die Dump-Files werden dort im Verzeichnis

/volume1/ApplicationBackup

angelegt. Dieses Verzeichnis soll auf dem FHEM-Server als Verzeichnis "/sds1/backup" gemountet werden.
Wenn noch nicht passiert, den NFS Client auf dem FHEM Server installieren:

sudo apt-get update
sudo apt-get install nfs-common

Auf dem entfernten Server wird das Verzeichnis freigegeben/exportiert.
Wenn noch nicht vorhanden, ist zunächst das notwendige Paket zu installieren:

sudo apt-get install nfs-kernel-server

Ist das Paket vorhanden, existiert die Datei '''/etc/exports'''.
In der Datei '''/etc/exports''' wird das zu exportierende Verzeichnis hinzugefügt. Aus Gründen der Sicherheit wird nur die IP-Adresse des FHEM Servers für den Zugriff zugelassen:

/volume1/ApplicationBackup 192.168.50.33(rw,root_squash,async,no_subtree_check)

Soll ein Netzwerk freigegeben werden, kann der Eintrag in in dieser Form erfolgen:

/volume1/ApplicationBackup 192.168.XXX.0/24(rw,root_squash,async,no_subtree_check)

Danach Datei /etc/exports neu einlesen:

sudo exportfs -ra

Auf dem Client Rechner wird der Mountpoint für das einzuhängende Verzeichnus erstellt:

sudo mkdir /sds1/backup

Einen Eintrag in '''/etc/fstab''' erstellen:

<IP-Adresse>:/volume1/ApplicationBackup /sds1/backup nfs auto,defaults,tcp,intr 0 0

Ausführen:

mount /sds1/backup

In diesem Verzeichnis existiert das Directory "dumps_FHEM", in dem die Backup-Files gespeichert werden sollen. Das Attribut wird entsprechend gesetzt auf:

attr Rep.fhemtest.Dump.ServerSide dumpDirLocal /sds1/backup/dumps_FHEM

'''Hinweis:''' 
Läuft der MySQL-Server mit FHEM lokal auf dem gleichen Server, zeigen die Attribute '''dumpDirRemote und dumpDirLocal''' auf das '''identische Verzeichnis'''. Trotzdem sind beide Attribute zu definieren.

 
:'''b) dumpFilesKeep'''

Dieser Parameter stellt die Anzahl der aufzubewahrenden Backup-Files ein. Es werden immer die "x" neuesten bzw. letzten Files im Verzeichnis gehalten, wobei nur die zu der jeweiligen Datenbank gehörenden Files betrachtet werden.
Die Zugehörigkeit des Dump-Files zur Quelldatenbank wird anhand des Filenamens ermittelt.

Er setzt sich zusammen aus <Datenbankname>_history_<Erstellungsdatum_Uhrzeit>.csv

Beispiel: fhemtest_history_2020_05_14_03_42.csv (+.gzip falls Dumpfiles komprimiert werden)

Ist dieses Attribut nicht gesetzt, werden die 3 neuesten Backup-Files im Verzeichnis behalten.
Um nur 2 Files zu behalten wird das Attribut gesetz:

attr Rep.fhemtest.Dump.ServerSide dumpFilesKeep 2

:'''c) Aktionen vor und nach dem Backup ausführen'''

Vor und nach der Dump-Ausführung kann ein FHEM-Kommando bzw. Perl-Befehle ausgeführt werden. Perl-Befehle müssen in '''{ }''' eingeschlossen werden.

Für das Beispiel soll vor dem Backup die Verbindung des DbLog-Devices LogDB zur Datenbank getrennt werden. Dadurch werden keine neuen Daten in die Datenbank geschrieben. Wenn das DbLog-Device LogDB im asynchronen Modus wie empfohlen betrieben wird, tritt auch kein Datenverlust ein, da die zu loggenden Daten im Cache verbleiben bis die Verbindung zur DB wiederhergestellt wird.

Um die Verbindung zu trennen wird ein

set LogDB reopen <Zeit in Sekunden>

verwendet. Die Zeitspanne wird sehr großzügig gewählt und soll sicherstellen, dass innerhalb dieser Zeit das Backup abgeschlossen ist. Nach dem Backup wird sofort

set LogDB reopen

ausgeführt, was die Verbindung des DbLog-Devices LogDB zur Datenbank unmittelbar wiederherstellt.

attr Rep.fhemtest.Dump.ServerSide executeBeforeProc set LogDB reopen 3600
attr Rep.fhemtest.Dump.ServerSide executeAfterProc set LogDB reopen

:'''d) vor dem Backup Datenbank verkleinern (optimizeTables)'''

Diese optionale Funktion wird durch das Attribut "optimizeTablesBeforeDump" eingeschaltet. Dadurch diese Funktion wird Platz innerhalb der Datenbank freigegeben der durch Löschvorgänge entstanden ist und dadurch die Größe des Datenbankfiles verringert.

attr Rep.fhemtest.Dump.ServerSide optimizeTablesBeforeDump 1

Durch die Tabellenoptimierung verlängert sich die Dumpzeit.

:'''e) das angelegte Dump-File nach dem Backup zum FTP-Server übertragen'''

DbRep bietet die Möglichkeit, das erstellte Dump-File per FTP oder verschlüsselt per FTPS zum FTP-Server zu übertragen. Dazu gibt es einen Satz von Attributen um dem Device alle notwendigen Angaben für den FTP-Transfer zur Verfügung zu stellen. Es gibt dafür folgende Attribute:

* ftpUse : FTP Transfer nach dem Dump wird eingeschaltet (bzw. ftpUseSSL mit SSL Verschlüsselung)
* ftpUser : User zur Anmeldung am FTP-Server, default: anonymous
* ftpPwd : Passwort des FTP-Users, default nicht gesetzt
* ftpDir : Verzeichnis auf dem FTP-Server in welches das File übertragen werden soll (default: FTP-root)
* ftpPort : FTP-Port, default: 21
* ftpServer : Name oder IP-Adresse des FTP-Servers
* ftpTimeout : Timeout für die FTP-Verbindung in Sekunden (default: 30)
* ftpPassive : setzen wenn passives FTP verwendet werden soll
* ftpDebug : Debugging des FTP Verkehrs zur Fehlersuche

Gemäß dieser Beschreibung und dem Ziel dieses Beispiels werden die für FTP-Transfer relevanten Attribute wie folgt gesetzt:

attr Rep.fhemtest.Dump.ServerSide ftpDir /ftp # Subdirectory ftp unter FTP-root als Zielverzeichnis
attr Rep.fhemtest.Dump.ServerSide ftpPwd ftpftp1
attr Rep.fhemtest.Dump.ServerSide ftpServer sds1.<fqdn>
attr Rep.fhemtest.Dump.ServerSide ftpUse 1
attr Rep.fhemtest.Dump.ServerSide ftpUser ftpuser

Der FTP-Server muss natürlich vorab eingerichtet und funktionsfähig sein. Sollten beim FTP-Transfer Fehler auftreten, kann das Attribut ftpDebug = 1 gesetzt werden um entsprechende Ausgaben zur Analyse des Problems im Log zu erhalten.

[[Datei:dumpmysql1.PNG|right|thumb|300px|Fertig definiertes Device Rep.fhemtest.Dump.ServerSide]]

 
:'''f) Hilfsattribute'''

Für die Funktion nicht relevant aber informativ ist das Attribut "showproctime = 1". Ist das Attribut gesetzt, wird das Reading "background_processing_time" angelegt. Es enthält nach der Ausführung die verbrauchte Prozesszeit.

Im Attribut "userExitFn" kann eine Perl-Routine hinterlegt werden, um zum Beispiel nach dem Backup eine Mail oder Telegram-Message mit dem Erfolgsstatus zu versenden.

Das fertig konfigurierte Device hier als RAW-Definition zur einfachen Nachnutzung. Die Angaben sind natürlich anzupassen:

<pre>
define Rep.fhemtest.Dump.ServerSide DbRep LogDB
attr Rep.fhemtest.Dump.ServerSide devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen .*Dump.*is.*running.*:remotecontrol/black_btn_PLAYgreen Database.*backup.*finished.*:remotecontrol/black_btn_GREEN tn_GREEN error.*:remotecontrol/black_btn_RED
attr Rep.fhemtest.Dump.ServerSide dumpCompress 1
attr Rep.fhemtest.Dump.ServerSide dumpDirLocal /sds1/backup/dumps_FHEM
attr Rep.fhemtest.Dump.ServerSide dumpDirRemote /volume1/ApplicationBackup/dumps_FHEM
attr Rep.fhemtest.Dump.ServerSide dumpFilesKeep 1
attr Rep.fhemtest.Dump.ServerSide event-on-update-reading state
attr Rep.fhemtest.Dump.ServerSide executeAfterProc set LogDB reopen
attr Rep.fhemtest.Dump.ServerSide executeBeforeProc set LogDB reopen 3600
attr Rep.fhemtest.Dump.ServerSide fastStart 1
attr Rep.fhemtest.Dump.ServerSide ftpDebug 0
attr Rep.fhemtest.Dump.ServerSide ftpDir /ftp
attr Rep.fhemtest.Dump.ServerSide ftpDumpFilesKeep 3
attr Rep.fhemtest.Dump.ServerSide ftpPwd ftpftp1
attr Rep.fhemtest.Dump.ServerSide ftpServer sds1.<fqdn>
attr Rep.fhemtest.Dump.ServerSide ftpUse 0
attr Rep.fhemtest.Dump.ServerSide ftpUser ftpuser
attr Rep.fhemtest.Dump.ServerSide optimizeTablesBeforeDump 1
attr Rep.fhemtest.Dump.ServerSide showproctime 1
attr Rep.fhemtest.Dump.ServerSide userExitFn doafterdump
</pre>

 

===== 3. Backup durchführen =====

Voraussetzung ist, dass der verwendete Datenbankuser das globale Privileg '''FILE''' besitzt.
Falls der User dieses Recht nicht hat, kann man es mit dem definierten DbRep-Device wie folgt erledigen.

:'''(optional) dem Datenbankuser das FILE Privileg zuweisen'''

Da die Rechtezuweisung nur mit einem administrativen DB-User (i.A. root) funktioniert, wird dieser User im DbRep-Device angelegt und aktiviert:

<pre>
set Rep.fhemtest.Dump.ServerSide adminCredentials <Admin-User> <Passwort>
attr Rep.fhemtest.Dump.ServerSide useAdminCredentials 1
</pre>

Nun kann dem verwendeten Datenbankuser das FILE Privileg zugeordnet werden:

<pre>
set Rep.fhemtest.Dump.ServerSide sqlCmd GRANT FILE ON *.* TO '<DB-User>'@'%';
</pre>

Dabei ist '''<DB-User>''' durch den in der DbLog-Konfiguration angegebenen User zu ersetzen da die gesamte Datenbankarbeit mit diesem User erfolgt.

Nach der Ausführung schaltet man die Nutzung des administrativen Users wieder ab mit:

<pre>
attr Rep.fhemtest.Dump.ServerSide useAdminCredentials 0
</pre>

Die Rechte können nun überprüft werden mit

<pre>
set Rep.fhemtest.Dump.ServerSide sqlCmd show grants;
</pre>

und werden im Ergebnis dargestellt (z.B. für den DB-User fhemtest):

<pre>
SqlResultRow_1 GRANTS FOR FHEMTEST@%
SqlResultRow_2 GRANT PROCESS, FILE, INDEX ON *.* TO 'fhemtest'@'%' IDENTIFIED BY PASSWORD '*...............'
SqlResultRow_3 GRANT SELECT, INSERT, UPDATE, DELETE, ALTER, EXECUTE, SHOW VIEW ON `fhemtest`.* TO 'fhemtest'@'%'
SqlResultRow_4 GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX ON `fhemtest`.`fhemtest` TO 'fhemtest'@'%'
</pre>

 
:'''Backup starten'''

[[Datei:dumpmysql2.PNG|right|thumb|400px|Backup läuft ...]]
Mit dem wie beschrieben eingerichteten DbRep-Device kann das Backup gestartet werden mit:

set Rep.fhemtest.Dump.ServerSide dumpMySQL serverSide

Zu Beginn des Vorgangs wird sofort die Verbindung des DbLog-Devices zur Datenbank getrennt.
Ein laufendes serverSide Backup kann mit FHEM-Mitteln nicht abgebrochen werden !

Das laufende Backup wird im state angezeigt mit "serverSide Dump is running - be patient and see Logfile !".

Im Logfile mit (mindestens) verbose 3 werden die relevanten Informationen zur Verfügung gestellt:

<pre>
2020.05.14 22:59:18.610 3: DbRep Rep.fhemtest.Dump.ServerSide - ########################################
2020.05.14 22:59:18.611 3: DbRep Rep.fhemtest.Dump.ServerSide - ### New database serverSide dump ###
2020.05.14 22:59:18.611 3: DbRep Rep.fhemtest.Dump.ServerSide - ########################################
2020.05.14 22:59:18.612 3: DbRep Rep.fhemtest.Dump.ServerSide - execute command before dump: 'set LogDB reopen 3600'
2020.05.14 22:59:18.613 2: DbLog LogDB: Connection closed until 23:59:18 (3600 seconds).
2020.05.14 22:59:18.660 3: DbRep Rep.fhemtest.Dump.ServerSide - Searching for tables inside database fhemtest....
2020.05.14 22:59:18.664 3: DbRep Rep.fhemtest.Dump.ServerSide - Size of database fhemtest before optimize (MB): 8298.98
2020.05.14 22:59:18.665 3: DbRep Rep.fhemtest.Dump.ServerSide - Optimizing tables
2020.05.14 22:59:18.665 3: DbRep Rep.fhemtest.Dump.ServerSide - Optimizing table `current` (INNODB). It will take a while.
2020.05.14 22:59:19.560 3: DbRep Rep.fhemtest.Dump.ServerSide - Table 1 `current` optimized successfully.
2020.05.14 22:59:19.560 3: DbRep Rep.fhemtest.Dump.ServerSide - Optimizing table `history` (INNODB). It will take a while.
2020.05.14 23:30:09.183 3: DbRep Rep.fhemtest.Dump.ServerSide - Table 2 `history` optimized successfully.
2020.05.14 23:30:09.186 3: DbRep Rep.fhemtest.Dump.ServerSide - 2 tables have been optimized.
2020.05.14 23:30:09.253 3: DbRep Rep.fhemtest.Dump.ServerSide - Size of database fhemtest after optimize (MB): 8298.98
2020.05.14 23:30:09.254 3: DbRep Rep.fhemtest.Dump.ServerSide - Starting dump of database 'fhemtest', table 'history'
2020.05.14 23:39:47.566 3: DbRep Rep.fhemtest.Dump.ServerSide - compress file /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_14_23_30.csv
2020.05.14 23:42:33.138 3: DbRep Rep.fhemtest.Dump.ServerSide - file compressed to output file: /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_14_23_30.csv.gzip
2020.05.14 23:42:34.784 3: DbRep Rep.fhemtest.Dump.ServerSide - input file deleted: /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_14_23_30.csv
2020.05.14 23:42:34.785 3: DbRep Rep.fhemtest.Dump.ServerSide - Number of exported datasets: 49032159
2020.05.14 23:42:34.787 3: DbRep Rep.fhemtest.Dump.ServerSide - Size of backupfile: 419.73 MB
2020.05.14 23:42:37.082 3: DbRep Rep.fhemtest.Dump.ServerSide - FTP: transferring /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_14_23_30.csv.gzip
2020.05.14 23:42:47.511 3: DbRep Rep.fhemtest.Dump.ServerSide - FTP: fhemtest_history_2020_05_14_23_30.csv.gzip transferred successfully to sds1.myds.me into dir /ftp
2020.05.14 23:42:47.558 3: DbRep Rep.fhemtest.Dump.ServerSide - Deleting old dumpfile 'fhemtest_history_2020_05_14_22_12.csv.gzip'
2020.05.14 23:42:47.857 3: DbRep Rep.fhemtest.Dump.ServerSide - Finished backup of database fhemtest - total time used (hh:mm:ss): 00:43:29
2020.05.14 23:42:47.948 2: DbRep Rep.fhemtest.Dump.ServerSide - command message after dump: "Reopen executed."
2020.05.14 23:42:47.973 3: DbRep Rep.fhemtest.Dump.ServerSide - Database dump finished successfully.
</pre>

[[Datei:dumpmysql3.PNG|right|thumb|500px|Backup ist erfolgreich abgeschlossen]]

In vorliegenden Beispiel wird nach einem erfolgreichen Backup im state '''"Warning - dump finished, but command after dump message appeared"''' angezeigt.

Diese Warnung rührt daher, dass das Reopen-Kommando eine Rückkehrinfo mitteilt, die als Issue gewertet und im Reading "afterdump_message" ausgegeben wird. In diesem Fall ist es nur eine Information.

In den erstellten Readings wird zusammengetragen welches File mit welcher Größe erstellt wurde, welche alten Files gelöscht wurden, Informationen zum FTP-Transfer und welche Zeit der Gesamtprozess benötgt hat.

Das so vorbereitete Backup kann nun z.B. täglich oder auch mit einer wesentlich kürzeren Wiederholungsperiode (alle x Stunden) über ein at-Device eingeplant werden:

define At.MySQL.Dump at *23:52:00 set Rep.fhemtest.Dump.ServerSide dumpMySQL serverSide

 

===== 4. Restore =====

Voraussetzung für das Restore ist, dass der verwendete Datenbankuser das globale Privileg '''FILE''' besitzt.
Falls der User dieses Recht nicht hat, kann man es mit dem definierten DbRep-Device wie folgt erledigen.

:'''(optional) dem Datenbankuser das FILE Privileg zuweisen'''

Da die Rechtezuweisung nur mit einem administrativen DB-User (i.A. root) funktioniert, wird dieser User im DbRep-Device angelegt und aktiviert:

<pre>
set Rep.fhemtest.Dump.ServerSide adminCredentials <Admin-User> <Passwort>
attr Rep.fhemtest.Dump.ServerSide useAdminCredentials 1
</pre>

Nun kann dem verwendeten Datenbankuser das FILE Privileg zugeordnet werden:

<pre>
set Rep.fhemtest.Dump.ServerSide sqlCmd GRANT FILE ON *.* TO '<DB-User>'@'%';
</pre>

Dabei ist '''<DB-User>''' durch den in der DbLog-Konfiguration angegebenen User zu ersetzen da die gesamte Datenbankarbeit mit diesem User erfolgt.

Nach der Ausführung schaltet man die Nutzung des administrativen Users wieder ab mit:

<pre>
attr Rep.fhemtest.Dump.ServerSide useAdminCredentials 0
</pre>

'''Alternativ''' kann die Rechtezuweisung auf der Konsole des MySQL-Servers ausgeführt werden:

<pre>
sudo mysql -u root -p
GRANT File ON *.* TO '<DB-User>'@'%';
exit
</pre>

Die Rechte können nun überprüft werden mit

<pre>
set Rep.fhemtest.Dump.ServerSide sqlCmd show grants;
</pre>

Nun kann der Restore ausgeführt werden.

Ein mit der Option '''serverSide''' erstellter Dump enthält ausschließlich die Daten der history-Tabelle.
Der Restore kann nur in eine bestehende Datenabank und entsprechend angelegte history Tabelle erfolgen.
Ist nach einem Datenbankfehler die Tabelle/Datenbank zerstört, must sie zunächst mit den vorbereiteten Befehlen in den
[https://svn.fhem.de/trac/browser/trunk/fhem/contrib/dblog/db_create_mysql.sql SVN-Skripten] bereitgestellt werden.

Ist die history-Tabelle noch intakt und soll nur der Inhalt ersetzt werden, muss die Tabelle vorab geleert werden da sonst unter Umständen doppelte Datensätze enstehen wenn kein primary Key verwendet ist.
Das kann einfach mit dem Befehl

set <Name> sqlCmd truncate table history

erreicht werden. Damit werden '''alle''' Daten der history-Tabelle hochperformant gelöscht. Die Tabelle selbst bleibt erhalten.

Sollte der truncate Befehl wegen nicht ausreichender Rechte des DB-Users mit Fehler enden, kann ein administrativer Datenbankuser (i.A. 'root') mit dem Kommando und Attribut

set <Name> adminCredentials <Name> <Passwort>
attr <Name> useAdminCredentials 1

hinterlegt und aktiviert werden.

Ein Restore kann mit dem angelegten DbRep-Device im laufenden Betrieb geschehen. Auch hier ist wieder wichtig, dass das DbLog-Device im asynchronen Modus betrieben wird und die Reopen-Zeit (siehe Einstellung Attribut "executeBeforeProc") sehr großzügig eingestellt ist.

Zum Restore dient der Befehl

set <Name> restoreMySQL <File>

[[Datei:dumpmysql4.PNG|right|thumb|500px|Auswahlmenü Files für Restore ]]

Im FHEMWEB öffnet sich dazu eine DropDown-Liste die alle vorhandenen und zur Quelldatenbank passenden Dumpfiles auflistet.
Das herzustellende File kann so bequem ausgewählt werden. Die Dumpfiles müssen sich in dem Verzeichnis befinden, welches durch das Attribut '''dumpDirLocal''' festgelegt wurde (default (./log). [[Datei:dumpmysql5.PNG|left|thumb|500px|Restore läuft]]

Der restore wird demzufolge gestartet mit:

set Rep.fhemtest.Dump.ServerSide restoreMySQL <File>

Der Restore der history-Tabelle kann nun online im laufenden FHEM-Betrieb erfolgen.
Wieder wird zu Beginn des Vorgangs das verbundene DbLog-Device von der Datenbank abgekoppelt und nach dem Restore wieder automatisch verbunden. Eine Datenbankoptimierung bzw. FTP-Transfer wird bei diesem Vorgang natürlich nicht ausgeführt.

[[Datei:dumpmysql6.PNG|left|thumb|500px|Fortschrittsanzeige in einem zweiten DbRep Device]]
In einem zweiten (z.B. kopierten) DbRep Device kann mit Hilfe des Befehls

get Rep.fhemtest.Dump.ServerSide procinfo

der Fortschritt des Restores überwacht werden. In der Spalte '''PROGRESS''' wird der Fortschritt in '''%''' angegeben.

Das Log zeigt den Ablauf des Restores:

<pre>
2020.05.15 13:07:24.369 3: DbRep Rep.fhemtest.Dump.ServerSide - #######################################
2020.05.15 13:07:24.370 3: DbRep Rep.fhemtest.Dump.ServerSide - ### New database Restore/Recovery ###
2020.05.15 13:07:24.371 3: DbRep Rep.fhemtest.Dump.ServerSide - #######################################
2020.05.15 13:07:24.371 3: DbRep Rep.fhemtest.Dump.ServerSide - execute command before restore: 'set LogDB reopen 3600'
2020.05.15 13:07:24.429 3: DbRep Rep.fhemtest.Dump.ServerSide - uncompress file /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_15_11_47.csv.gzip
2020.05.15 13:09:31.152 3: DbRep Rep.fhemtest.Dump.ServerSide - file uncompressed to output file: /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_15_11_47.csv
2020.05.15 13:09:31.237 3: DbRep Rep.fhemtest.Dump.ServerSide - Size of uncompressed file: 5511.52 MB
2020.05.15 13:09:31.242 3: DbRep Rep.fhemtest.Dump.ServerSide - Starting restore of database 'fhemtest', table 'history'.
2020.05.15 14:42:28.566 2: DbLog LogDB: Connection closed until 16:42:28 (7200 seconds).
2020.05.15 14:46:22.391 3: DbRep Rep.fhemtest.Dump.ServerSide - Restore of /volume1/ApplicationBackup/dumps_FHEM/fhemtest_history_2020_05_15_11_47.csv into 'fhemtest', 'history' finished - total time used (hh:mm:ss): 01:38:57
2020.05.15 14:46:22.457 2: DbRep Rep.fhemtest.Dump.ServerSide - command message after restore: "Reopen executed."
2020.05.15 14:46:22.481 3: DbRep Rep.fhemtest.Dump.ServerSide - Database restore finished successfully.
</pre>

[[Datei:dumpmysql7.PNG|right|thumb|300px|Restore erfolgreich abgeschlossen]]

Der Restore wurde erfolgreich abgeschlossen und die Verbindung des DbLog-Device LogDB zur Datenbank wiederhergestellt. Das Logging wird nahtlos fortgeführt.

Es ist natürlich zu beachten, dass die Daten zwischen dem Erstellungszeitpunkt des eingespielten Backups und der aktuellen Zeit verloren sind !
Eventuell in der Tabelle '''history''' noch vorhandene Daten werden '''nicht''' überschrieben.

 

=== Speichern von Berechnungswerten in der Datenbank und Erstellen eines Plots (ab Version 7.5.1) ===

Es sollen aus in der Datenbank vorhandenen minütlichen Leistungswerten eines Wechselrichters die maximal-, minimal- und durchschnittlichen Leistungswerte pro Tag berechnet werden und diese Ergebnisse wieder in die Datenbank geschrieben werden um daraus einen Plot zu erstellen.
Diese Berechnung soll immer aktuell für den laufenden Monat erfolgen.

Die Ausgangswerte liegen in der Datenbank als minütliche kW-Einträge vor (Auszug DbRep fetchrows):

<pre>
2018-01-18_15-55-49__MySTP_5000__total_pac 0.200
2018-01-18_15-56-50__MySTP_5000__total_pac 0.218
2018-01-18_16-00-14__MySTP_5000__total_pac 0.209
2018-01-18_16-00-39__MySTP_5000__total_pac 0.198
2018-01-18_16-01-39__MySTP_5000__total_pac 0.142
2018-01-18_16-02-39__MySTP_5000__total_pac 0.130
2018-01-18_16-03-39__MySTP_5000__total_pac 0.117
2018-01-18_16-05-39__MySTP_5000__total_pac 0.087
2018-01-18_16-06-39__MySTP_5000__total_pac 0.071
2018-01-18_16-07-39__MySTP_5000__total_pac 0.076
2018-01-18_16-08-39__MySTP_5000__total_pac 0.065
2018-01-18_16-09-39__MySTP_5000__total_pac 0.069
2018-01-18_16-10-39__MySTP_5000__total_pac 0.060
2018-01-18_16-12-39__MySTP_5000__total_pac 0.065
2018-01-18_16-13-39__MySTP_5000__total_pac 0.068
2018-01-18_16-14-39__MySTP_5000__total_pac 0.054
2018-01-18_16-15-39__MySTP_5000__total_pac 0.041
2018-01-18_16-16-39__MySTP_5000__total_pac 0.027
2018-01-18_16-17-39__MySTP_5000__total_pac 0.026
2018-01-18_16-18-39__MySTP_5000__total_pac 0.021
2018-01-18_16-19-39__MySTP_5000__total_pac 0.018
2018-01-18_16-20-39__MySTP_5000__total_pac 0.012
</pre>

Für die Berechnung der Ergenisse stehen in DbRep die Kommandos maxValue, minValue und averageValue zur Verfügung.

 
==== 1. Anlegen des DbRep-Devices ====

Das anzulegende Device wird für alle notwendigen Berechnungen verwendet.
Die Definition des DbRep-Devices erfolgt unter Angabe des zu verbindenden DbLog-Devices (nicht der Datenbank selbst):

define Rep.total_pac DbRep LogDB

Ist das Device definiert, verbindet es sich zu der Datenbank und wechselt in den state "connected", sofern die Verbindung erfolgreich verlief.
Prinzipiell funktioniert der hier Ablauf mit einem im synchronous Mode betriebenen DbLog-Device, aber es ist dringend angeraten das DbLog-Device (LogDB) in den asynchronen Modus umzuschalten. Dadurch werden Blockierungen von FHEM verhindert.

 

==== 2. Einstellungen des DbRep-Devices (Attribute) ====
[[Datei:Rep.total_pac.PNG|right|thumb|400px|Device definiert]]
Für die gewünschte Funktion müssen in diesem neu definierten Device einige relevante Attribute gesetzt werden.

Da die Berechnungen immer für den aktuellen Monat erstellt werden sollen, wird das Attribut "timestamp_begin" so definiert, dass immer der Beginn des aktuellen Monats dynamisch ermittelt wird. Das ist gegeben durch den Eintrag:

attr Rep.total_pac timestamp_begin current_month_begin

Es soll ein Ergebniswert pro Tag erzeugt werden. Damit dies erreicht werden kann, wird das Attribut "aggregation" verwendet und auf den Wert "day" eingestellt. Würde zum Beispiel ein stündlicher Ergebniswert gewünscht sein, hätte "aggregation = hour" den benötigten Effekt.

attr Rep.total_pac aggregation day

Die Attribute "device" und "reading" legen das auszuwertende Device und Reading fest. Dabei ist zu beachten, dass im Gegensatz zur allgemein gültigen Möglichkeit devspec bzw. SQL-Wildcards zu verwenden bei dieser speziellen Detailfunktion dies nicht der Fall ist. Das heißt. es muß immer ein eindeutiges Device und ein eindeutiges Reading angegeben werden. Der Grund liegt in der Notwendigkeit, bei der Speicherung der Ergebnisdaten der Datenbank ebenfalls ein eindeutiges Device und Reading zu übergeben. In dem Beispiel wird das Device "MySTP_5000" und das Reading "total_pac" ausgewertet.

attr Rep.total_pac device MySTP_5000
attr Rep.total_pac reading total_pac

Hilfreiche Attribute sind noch "event-on-update-reading" zur Begrenzung der Events, "showproctime" zur Bestimmung der Prozesszeiten und "allowDeletion" um die Möglichkeit zu haben, irrtümlich gespeicherte Berechnungsergebnisse wieder über das DbRep-Device zu löschen.

attr Rep.total_pac event-on-update-reading state
attr Rep.total_pac showproctime 1
attr Rep.total_pac allowDeletion 1

Das so vorbereitete Device ist für die benötigten Funktionen ausreichend eingestellt.
Zur einfachen Nachnutzung nochfolgend die Raw-Definition des DbRep-Devices:

<pre>
define Rep.total_pac DbRep LogDB
attr Rep.total_pac aggregation day
attr Rep.total_pac allowDeletion 1
attr Rep.total_pac device MySTP_5000
attr Rep.total_pac event-on-update-reading state
attr Rep.total_pac reading total_pac
attr Rep.total_pac room DbLog
attr Rep.total_pac showproctime 1
attr Rep.total_pac timestamp_begin current_month_begin
attr Rep.total_pac verbose 3
</pre>

 
==== 3. Berechnung ausführen und Speicherung der Ergebnisse ====
[[Datei:average.PNG|right|thumb|300px|Average Berechnung]]
Die benötigten Funktionen sind:

averageValue - Berechnung des täglichen Durchschnittswert der Wechselrichterleistung (kW)
maxValue - Berechnung des täglichen Maximalwertes der Wechselrichterleistung (kW)
minValue - Berechnung des täglichen Minimalwertes der Wechselrichterleistung (kW)

[[Datei:minval.PNG|right|thumb|300px|MinVal Berechnung]]
Für jede dieser Kommandos stehen im DbRep die Optionen "display" und "writeToDB" zur Verfügung. Die Option "display" stellt die Ergenisse lediglich im Browser dar und kann dazu die Ergebnisse vor der Speicherung zu bewerten.
So ergeben die Kommandos:

set Rep.total_pac minValue display
set Rep.total_pac maxValue display
set Rep.total_pac avarageValue display

die täglichen Min-, Max- und Durchschnittswerte der WR-Leistung.

[[Datei:maxval.PNG|right|thumb|300px|MaxVal Berechnung]]
Entsprechen die Ergebnisse den Erwartungen bzw. dem Ziel, können die folgenden Kommandos verwendet werden um die Berechnung durchzuführen und dabei gleichzeitig in die Datenbank zu schreiben.

set Rep.total_pac minValue writeToDB
set Rep.total_pac maxValue writeToDB
set Rep.total_pac avarageValue writeToDB

Die Daten werden in der history-Tabelle gespeichert und, sofern das DbLog-Device das Attribut "DbLogType = Current..." gestzt hat, auch in der current-Tabelle gespeichert. Im letzteren Fall kann das Ergebnisreading bei der Erstellung des Plots sofort aus der DropDown-Liste ausgewählt werden.

Bei der Datenspeicherung wird der neue Readingnamen aus einem Präfix und dem originalen Readingnamen gebildet. Der Präfix setzt sich aus der Bildungsfunktion und der gewählten Aggregation zusammen, d.h. im Fall des Beispiels aus "min","max","avg" und "day".
Der Timestamp der neuen Readings in der Datenbank wird von der eingestellten Aggregationsperiode abgeleitet, sofern kein eindeutiger Zeitpunkt des Ergebnisses bestimmt werden kann. So kann der Zeitpunkt des Maximalwertes eines Tages wertes genau bestimmt werden und der resultierende Datensatz wird mit diesem Timestamp gespeichert.

Die resultierende Readingnamen werden somit wie folgt in der Datenbank gespeichert:

max_day_total_pac
min_day_total_pac
avg_day_total_pac

Die Berechnungen können regelmäßig über ein at eingeplant werden. Die Funktionen vermeiden dabei die Speicherung von doppelten Datensätzen. Wurde bei einem Berechnungslauf der Datensatz bereits gespeichert, wird dieser Datensatz beim nächsten Durchlauf nicht noch einmal gespeichert.

==== 4. Erstellung des Plots ====
[[Datei:dropdown.PNG|right|thumb|300px|Drop-Down Liste SVG]]
Wird durch das DbLog-Device die current-Tabelle genutzt, das Attribut "DbLogType = Current..." ist gesetzt, können die Ergebnisreadings max_day_total_pac, min_day_total_pac und avg_day_total_pac im SVG-Editor ausgewählt werden (siehe {{Link2CmdRef|Lang=de|Anker=SVG}} bei SVG).

Durch die Wahl des Plot-Typ "bars" und dem SVG-Attribut "fixedrange = month" entsteht der gewünschte Tageswert-Plot über den aktuellen Monat.

[[Datei:svg_calc.PNG|right|thumb|300px|Ergebnis SVG]]
Hier wiederum die Raw-Definition des SVG-Device:

<pre>
defmod SVG_LogDB_16 SVG LogDB:SVG_LogDB_16:HISTORY
attr SVG_LogDB_16 fixedrange month
attr SVG_LogDB_16 room Energie,SVG_MySQL
attr SVG_LogDB_16 title "Max Leistung: $data{max1} kW, Min Leistung: $data{min3} kW,Max. Durchschnittsleistung: $data{max2} kW "
</pre>

sowie des gplot-Files:

<pre>
# Created by FHEM/98_SVG.pm, 2018-01-18 21:45:27
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<TL>'
set ytics
set y2tics
set grid
set ylabel "kW"
set y2label "kW"
set yrange [0:6]
set y2range [0:6]

#LogDB MySTP_5000:max_day_total_pac
#LogDB MySTP_5000:avg_day_total_pac
#LogDB MySTP_5000:min_day_total_pac

plot "<IN>" using 1:2 axes x1y2 title 'Max-Leistung / Tag' ls l0fill lw 1 with bars,\
"<IN>" using 1:2 axes x1y2 title 'Average / Tag' ls l2fill lw 1 with bars,\
"<IN>" using 1:2 axes x1y2 title 'Min-Leistung / Tag' ls l1fill lw 1 with bars
</pre>

 
=== Öffnungszeiten von Fenster/Türen aus der Datenbank ermitteln ===

Ziel ist es, die Öffnungszeit eines Fensters oder einer Tür zu ermitteln sobald es wieder geschlossen wird und ein Reading mit der Zeit in dem entsprechenden Device (Fensterkontakt) zu setzen.

Für das Beispiel wird angenommen dass:

* der Status der Sensoren als "open" und "close" in der Datenbank gespeichert ist
* das verwendetet DbRep-Device "Rep.WindowOpenTime" heißt
* das verwendete DbLog-Device "LogDBShort" heißt (wird mit dem DbRep-Device bei der Definition assoziiert)

Zunächst wird zur Auswertung von closed-Events ein entsprechendes Notify definiert (Raw-Format):

<pre>
defmod N.WindowClosed notify (.*fenster.*|.*terrasse.tuer.*):closed \
{ \
if($NAME =~ /(.*fenster.*|.*terrasse.tuer.*)/) {\
fhem("set LogDBShort commitCache;; defmod calcse at +00:00:10 {SwitchEvent(\"$NAME\")};;");; \
}\
}
attr N.WindowClosed alias Starte Ermittlung der Fenster Öffnungszeiten
attr N.WindowClosed comment Wird verwendet um die letzte Öffnungszeit der Fenster aus der Datenbank zu ermitteln und im Reading "LastOpenTime" abzulegen.
attr N.WindowClosed room Datenbank->Produktiv
</pre>

Die zusätzlich if-Abfrage im Notify behob ein Problem bei den Fensterkontakten die mit einem Thermostat gepeert sind, da in diesem Fall der Event mehrfach auftrat. Der Teil '''"set LogDBShort commitCache"''' speichert den Cache der Datenbank vor der Berechnung sofern sie im asynchronen Modus betrieben wird (kann entfallen wenn im synchronen Mode betrieben). Um der DB Zeit zur Abspeicherung zu geben, wird die Berechnung über ein AT mit einer entsprechenden Verzögerung (hier 10 Sekunden) angestartet. Die Zeit im AT bitte entsprechend der eigenen Systembedingungen anpassen.

Im Notify wird die Funktion '''SwitchEvent($NAME)''' aufgerufen. Diese Funktion wird in der 99_myUtils.pm eingefügt:

<syntaxhighlight lang="perl">
##########################################################################################################
# This function is used to start an SQL query for the given device "$name" and check
# how much time the device was in state defined by $usedVal1 today.
# The query is done by a DbRep device.
#
# In this example the name of the DbRep device is "Rep.WindowOpenTime"
##########################################################################################################
sub SwitchEvent($) {
my ($name) = @_;

Log3 $name , 5, "$name - SwitchEvent called";

my $usedReading = "\"state\""; # name of the reading which holds the state which has to be checked
my $usedVal1 = "\"open\""; # reading value which starts the time measuerement
my $usedVal2 = "\"closed\""; # reading value which stops the time measurement
my $device = "\"$name\""; # name of the device which state has to be checked
my $dbRepDevice = "Rep.WindowOpenTime"; # name of the DbRep device

# The query will check for the current day the cumulated time difference between $usedVal1 and $usedVal2
# the example here is a homemetic threeStateSensor (window contact) and the result of the query is
# the cumulated time which the window was open (in seconds) and the name of the device whic is
# used by the function SwitchQueryResult()
# Example: AZ_Fensterkontakt|433.2
my $sql = "SET \@topen = NULL,\@closed = NULL, \@popen = NULL;;".
" SELECT DEVICE ,SUM(TIMEDIFF(tclosed, topen)) AS duration FROM (".
" SELECT TIMESTAMP, VALUE, DEVICE,".
" \@topen := \@popen AS topen,".
" \@closed := IF(VALUE = $usedVal2, TIMESTAMP, NULL) AS tclosed,".
" \@popen := IF(VALUE = $usedVal1, TIMESTAMP, NULL) AS prev_open".
" FROM history WHERE".
" DATE(TIMESTAMP) = CURDATE() AND".
" DEVICE = $device AND".
" READING = $usedReading AND ".
" (VALUE = $usedVal1 OR VALUE = $usedVal2)".
" ORDER BY TIMESTAMP".
" ) AS tmp";

Log3 $name , 5, "$name - SwitchEvent start query: $sql";

fhem("set $dbRepDevice sqlCmd $sql"); # start the query now. Result will be processed in the function SwitchQueryResult() below

return;
}
</syntaxhighlight>

Die Funktion '''SwitchEvent()''' bekommt den Namen des Gerätes übergeben welches Event ausgelöst hat. Damit wird eine SQL-Abfrage für dieses Gerät gestartet und ermittelt, wieviel Zeit (in Sekunden) für das übergebene Gerät zwischen dem Zustand "open" und "closed" verbracht wurde.

Das verwendete DbRep-Device wird wie folgt definiert:

<pre>
define Rep.WindowOpenTime DbRep LogDBShort
attr Rep.WindowOpenTime aggregation no
attr Rep.WindowOpenTime comment Öffnungszeit der Fenster ermitteln
attr Rep.WindowOpenTime initialized:control_3dot_hor_s connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.WindowOpenTime reading state
attr Rep.WindowOpenTime showproctime 1
attr Rep.WindowOpenTime sqlResultFormat sline
attr Rep.WindowOpenTime event-on-update-reading state
attr Rep.WindowOpenTime userExitFn SwitchQueryResult
</pre>

Ganz wichtig ist die Zeile '''attr Rep.powerOnTime userExitFn SwitchQueryResult'''. Hier ist die Funktion '''SwitchQueryResult()''' angegeben, die nach erfolgreicher Bearbeitung der SQL-Query aufgerufen wird. Diese Funktion wird ebenfalls in der 99_myUtils.pm eingefügt:

<syntaxhighlight lang="perl">
##########################################################################################################
# This function will be called from the DbRep device if the attribute
# attr Name_of_your_DbRep_device userExitFn SwitchQueryResult is set.
# This function create a new reading "LastOpenTime" at the device for which the query is done and
# set the cumulated time difference in seconds to the reading.
##########################################################################################################
sub SwitchQueryResult($$$) {
my ($name,$reading,$value) = @_; # $name is the name of the DbRep device which is calling this function
my $hash = $defs{$name};

# DbRep calls this function several times with different informations.
# if $reading is SqlResult, $value will hold the result of the query
if ($reading eq "SqlResult") {
my ($dev,$val) = split('\|',$value); # split the result in two parts
$dev = $dev?$dev:"";
$val = $val?$val:"";
if (!$val) {
$val = 0;
}
$val = DbRep_sec2hms($val); # calculate seconds to hms
Log3 $name , 5, "DbRep $name - SwitchQueryResult splitted result: $dev $val";

fhem("setreading $dev LastOpenTime $val") if($dev); # set the reading "LastOpenTime" with the time if device-Log was found
}

return;
}
</syntaxhighlight>

Die Funktion SwitchQueryResult() rechnet das Ergebnis der query aus dem DbRep Device von Sekunden in das Format hh:mm:ss um und trägt die berechnete Zeit als Reading "'''LastOpenTime'''" im jeweiligen Fensterkontakt ein.

So kann man z.B. im Device mit dem Namen "eg.bad.fenster" das Reading "'''LastOpenTime 00:03:58'''" finden.
Die vorliegende Berechnung liefert immer die Zeit des letzten Öffnungszyklus des aktuellen Tages. Möchte man die Zeiten des gesamten Tages akkumulieren, kann nach der Beschreibung "[[Summe aller Einschaltzeiten eines Gerätes]]" verfahren werden.

=== Grünlandtemperatursumme ermitteln und in SVG-Grafik darstellen ===
Nachfolgendes Beispiel zeigt, wie die Grünlandtemperatursumme ermittelt werden kann und die Ermittlungsergebnisse in der Datenbank gespeichert werden, um sie in einer SVG-Grafik darzustellen. Das beschriebene Verfahren kann natürlich auch für andere Anwendungsfälle angewendet werden.

Was ist die Grünlandtemperatursumme?

Hier die Definition aus [https://de.wikipedia.org/wiki/Grünlandtemperatursumme Wikipedia]:

: ''Die Grünlandtemperatursumme (GTS) ist eine Spezialform der Wachstumsgradtage, die in der Agrarmeteorologie verwendet wird. Sie wird herangezogen, um in Mitteleuropa den Termin für das Einsetzen der Feldarbeit nach dem Winter zu bestimmen.''
: ''Eine Wärmesumme ist allgemein eine gewisse Lufttemperatur eines Tages über die Tage einer Periode summiert. Dabei verwendet man besonders die kumulierte korrigierte GTS, die nach Monat gewichtet wird.''
: ''Wird im Frühjahr die Summe von 200 überschritten, ist der nachhaltige Vegetationsbeginn erreicht. Hintergrund ist die Stickstoffaufnahme und -verarbeitung des Bodens, welcher von dieser Temperatursumme abhängig ist. In mittleren Breiten wird das meist im Laufe des März, an der Wende von Vorfrühling zu Mittfrühling erreicht. ''

Zur Bestimmung der GTS benötigt man zunächst die Aufzeichnung der örtlichen Temperaturwerte in einer DbLog-Datenbank.
Im Beispiel wird dazu das Reading '''temperature''' des Device '''MyWetter''' (Device vom Typ [[Weather]]) genutzt. Die Einrichtung des Weather- und DbLog-Devices wird an dieser Stelle nicht beschrieben und als bekannt vorausgesetzt.

Es wird angenommen, dass:
* das definierte DbLog-Device im asynchronen Mode betrieben wird
* das Reading '''temperature''' des Device '''MyWetter''' in der DbLog-Datenbank gespeichert wird

Zur Ermittlung des GTS wird ein DbRep-Device mit gesetztem [[Attribut]] '''avgDailyMeanGWSwithGTS''' verwendet. Dieses Attribut legt die Berechnung der täglichen Durchschnittstemperatur nach den Regularien des Deutschen Wetterdienstes fest und aktiviert auf dieser Grundlage weiterhin die Berechnung der Grünlandtemperatursumme.

[[Datei:gts1.PNG|right|thumb|400px|GTS Ermittlung]]
Die RAW-Definition des verwendeten DbRep-Devices:
<pre>
define Rep.GTS DbRep LogDB
attr Rep.GTS averageCalcForm avgDailyMeanGWSwithGTS
attr Rep.GTS device MyWetter
attr Rep.GTS fastStart 1
attr Rep.GTS reading temperature
attr Rep.GTS room DbLog
attr Rep.GTS showproctime 1
attr Rep.GTS timestamp_begin current_year_begin
attr Rep.GTS timestamp_end previous_day_end
attr Rep.GTS userExitFn saveGTS
</pre>

'''LogDB''' ist der Name des angeschlossenen DbLog-Devices und ist natürlich entsprechend anzupassen. Unbedingt wichtig ist es, den Start der Auswertung auf den Beginn des Jahres zu setzen. Das Attribut '''timestamp_begin = current_year_begin''' erfüllt diese Bedingung. Das Attribut '''userExitFn''' wird noch erläutert.

Die Berechnung wird gestartet mit dem Befehl:
:<code>set Rep.GTS averageValue display</code>

Im Ergebnis entstehen Readings die auszugsweise nachfolgend aufgelistet sind:
<pre>
2021-02-26 22:32:08 2021-02-11__MyWetter__temperature__AVGDMGWS__2021-02-11 -5.1
2021-02-26 22:32:08 2021-02-11__MyWetter__temperature__GrasslandTemperatureSum 40.1
2021-02-26 22:32:08 2021-02-12__MyWetter__temperature__AVGDMGWS__2021-02-12 -6.8
2021-02-26 22:32:08 2021-02-12__MyWetter__temperature__GrasslandTemperatureSum 40.1
2021-02-26 22:32:08 2021-02-13__MyWetter__temperature__AVGDMGWS__2021-02-13 insufficient values - execute get Rep.GTS versionNotes 2 for further information
2021-02-26 22:32:08 2021-02-14__MyWetter__temperature__AVGDMGWS__2021-02-14 -8.2
2021-02-26 22:32:08 2021-02-14__MyWetter__temperature__GrasslandTemperatureSum 40.1
2021-02-26 22:32:08 2021-02-15__MyWetter__temperature__AVGDMGWS__2021-02-15 -3.2
2021-02-26 22:32:08 2021-02-15__MyWetter__temperature__GrasslandTemperatureSum 40.1
</pre>

Die Meldung "insufficient values - execute get Rep.GTS versionNotes 2 for further information" ist ein Hinweis darauf, dass die für die Ermittlung der Durchschnittstagestemperaturen nach den Regularien des Deutschen Wettederdienstes geforderten Werte nicht (komplett) in der DB vorhanden sind.

Um die Grünlandtemperatursumme im SVG-Diagramm anzuzeigen, muss dieser Wert für jeden Tag in der DB gespeichert werden. Alle benötigten Informationen sind in den DbRep-Readings, z.B.:

<pre>
2021-02-12__MyWetter__temperature__GrasslandTemperatureSum 40.1
</pre>

vorhanden. Der Präfix enthält das Datum, für das die jeweilige Grünlandtemperatursumme gilt, d.h., es muß nur noch ein neuer Wert zu diesem korrespondierenden Datum in die DB geschrieben werden. Das wird durch eine kleine Routine in 99_myUtils.pm erreicht, die im Attribut '''userExitFn''' des DbRep-Devices hinterlegt wird.

'''Routine in 99_myUtils.pm einfügen:'''
<syntaxhighlight lang="perl">
##############################################################
# speichern GTS in Datenbank
##############################################################
sub saveGTS {
my $name = shift;
my $reading = shift;
my $value = shift;
my $device = "MyWetter"; # Weather-Device -> anpassen !
my $logdev = "LogDB"; # DbLOg Device -> anpassen !

# 2021-02-14__MyWetter__temperature__GrasslandTemperatureSum 40.1
if($reading =~ /GrasslandTemperatureSum/x) {
my ($date) = (split "__", $reading)[0];
my ($y,$m,$d) = split "-", $date;
my $ts = "$y-$m-$d 12:00:00";

CommandSet(undef, "$logdev addCacheLine $ts|$device|calculated|calculated|GrasslandTemperatureSum|$value|");
}

return;
}
</syntaxhighlight>

In der Routine sind die Variablen '''$device''' und '''$logdev''' mit den realen Devices Weather und DbLog zu ersetzen.

;Funktionsweise
:Ist der Auswertungslauf beendet, werden alle Readings, die "GrasslandTemperatureSum" enthalten, in ihre Bestandteile aufgesplittet, der Timestamp zum Speichern in der Datenbank formatiert und der neu in der DB zu erstellende Datensatz in den Cache des DbLog-Devices eingefügt. Der nächste Sync-Lauf in DbLog fügt die im Cache erstellten Datensätze in die Datenbank ein.

==== Definition des SVG-Devices ====
[[Datei:gts2.PNG|right|thumb|400px|GTS SVG Darstellung]]
In der Datenbank befinden sich nun Datensätze mit dem '''Device MyWetter''' und dem '''Reading GrasslandTemperatureSum''' die im SVG Diagramm ausgewertet werden können.

RAW-Definition des SVG-Devices:
<pre>
defmod SVG_GTS SVG LogDB:SVG_GTS:HISTORY
attr SVG_GTS fixedrange month
attr SVG_GTS label "aktuelle Grünlandtemperatur $data{max1}"
attr SVG_GTS room SVG
</pre>

Die dazugehörige GPLOT-Datei (SVG_GTS.gplot):
<pre>
# Created by FHEM/98_SVG.pm, 2021-02-27 08:08:30
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'
set ytics
set y2tics
set grid
set ylabel "Score"
set y2label "Score"

#LogDB MyWetter:GrasslandTemperatureSum::

plot "<IN>" using 1:2 axes x1y2 title 'GTS' ls l1fill lw 1 with ibars
</pre>

[[Kategorie:Logging]]

DbRep - Reporting und Management von DbLog-Datenbankinhalten

2024-05-26T08:41:13Z

Dora71: /* (regelmäßiges) Löschen von Datenbanksätzen */ Typo behoben Datenbankdevice angepasst

{{Infobox Modul
|ModPurpose=Reporting und Management von DbLog-Datenbankinhalten
|ModType=h
|ModCmdRef=DbRep
|ModForumArea=Automatisierung
|ModTechName=93_DbRep.pm
|ModOwner=DS_Starter ({{Link2FU|16933|Forum}}/[[Benutzer Diskussion:DS Starter|Wiki]])}}

== Zweck und Einsatz des Moduls ==
Zweck des Moduls ist es, den Inhalt von [[DbLog]]-Datenbanken nach bestimmten Kriterien zu durchsuchen, zu managen, das Ergebnis hinsichtlich verschiedener Aggregationen auszuwerten und als Readings darzustellen. Die Abgrenzung der zu berücksichtigenden Datenbankinhalte erfolgt durch die Angabe von Device, Reading und die Zeitgrenzen für Auswertungsbeginn bzw. Auswertungsende.

Alle Datenbankoperationen werden nichtblockierend ausgeführt. Die Ausführungszeit der (SQL)-Hintergrundoperationen kann optional ebenfalls als Reading bereitgestellt werden (siehe Attribute).
Alle vorhandenen Readings werden vor einer neuen Operation gelöscht. Durch das Attribut "readingPreventFromDel" kann eine Komma separierte Liste von Readings angegeben werden die nicht gelöscht werden sollen.

'''Zur Zeit ist das Modul durch folgende Leistungsmerkmale gekennzeichnet:'''

* Selektion und Anzeige aller Datensätze innerhalb einstellbarer Zeitgrenzen.
* Darstellung der Datensätze einer Device/Reading-Kombination innerhalb einstellbarer Zeitgrenzen.
* Selektion der Datensätze unter Verwendung von dynamisch berechneter Zeitgrenzen zum Ausführungszeitpunkt.
* Dubletten-Hervorhebung bei Datensatzanzeige (fetchrows)
* Berechnung der Anzahl von Datensätzen einer Device/Reading-Kombination unter Berücksichtigung von Zeitgrenzen und verschiedenen Aggregationen.
* Die Berechnung von Summen-, Differenz-, Maximum-, Minimum- und Durchschnittswerten numerischer Readings in Zeitgrenzen und verschiedenen Aggregationen.
* Speichern von Summen-, Differenz- , Maximum- , Minimum- und Durchschnittswertberechnungen in der Datenbank
* Löschung von Datensätzen. Die Eingrenzung der Löschung kann durch Device und/oder Reading sowie fixer oder dynamisch berechneter Zeitgrenzen zum Ausführungszeitpunkt erfolgen.
* Export von Datensätzen in ein File im CSV-Format.
* Import von Datensätzen aus File im CSV-Format.
* Umbenennen von Device/Readings in Datenbanksätzen
* Änderung von gespeicherten Reading-Werten (VALUES) in der Datenbank (changeValue)
* automatisches Umbenennen (Autorename) von Device-Namen in Datenbanksätzen und DbRep-Definitionen nach FHEM "rename" Befehl (siehe [[#DbRep_Agent_-_automatisches_.C3.84ndern_von_Device-Namen_in_Datenbanken_und_DbRep-Definitionen_nach_FHEM_.22rename.22 | DbRep-Agent]])
* Ausführen von beliebigen benutzerspezifischen SQL-Kommandos
* Backups der FHEM-Datenbank im laufenden Betrieb erstellen (MySQL, SQLite) mit/ohne Komprimierung der Dumpfiles
* senden und versionieren Dumpfiles nach dem Backup an einen FTP-Server
* Restore von SQLite-Dumps und MySQL serverSide-Backups
* Optimierung der angeschlossenen Datenbank (optimizeTables, vacuum)
* Ausgabe der existierenden Datenbankprozesse (MySQL)
* leeren der current-Tabelle
* Auffüllen der current-Tabelle mit einem (einstellbaren) Extrakt der history-Tabelle
* Bereinigung sequentiell aufeinander folgender Datensätze (sequentielle Dublettenbereinigung)
* Reparatur einer korrupten SQLite Datenbank ("database disk image is malformed")
* Übertragung von Datensätzen aus der Quelldatenbank in eine andere (Standby) Datenbank (syncStandby)
* Reduktion der Anzahl von Datensätzen in der Datenbank (reduceLog)
* Löschen von doppelten Datensätzen (delDoublets)
* Löschen und (Wieder)anlegen der für DbLog und DbRep benötigten Indizes (index)

Zur Aktivierung der Funktion "Autorename" wird dem definierten DbRep-Device mit dem Attribut "role" die Rolle "Agent" zugewiesen. Die Standardrolle nach Definition ist "Client". Mehr ist dazu im Abschnitt [[#DbRep_Agent_-_automatisches_.C3.84ndern_von_Device-Namen_in_Datenbanken_und_DbRep-Definitionen_nach_FHEM_.22rename.22 | DbRep-Agent]] beschrieben.

DbRep stellt dem Nutzer einen UserExit zur Verfügung. Über diese Schnittstelle kann der Nutzer in Abhängigkeit von frei definierbaren Reading/Value-Kombinationen (Regex) eigenen Code zur Ausführung bringen. Diese Schnittstelle arbeitet unabhängig von einer Eventgenerierung. Weitere Informationen dazu ist unter [[#Attribute | Attribut]] "userExitFn" beschrieben.

FHEM-Forum:
{{Link2Forum|Topic=53584|Message=452567|LinkText=Modul 93_DbRep - Reporting und Management von Datenbankinhalten (DbLog)}}

== Voraussetzungen und Abgrenzungen ==
Das Modul setzt den Einsatz einer oder mehrerer DBLog-Instanzen voraus (bisher getestet mit PostgreSQL, MySQL und SQLite). Es werden die Zugangsdaten dieser Datenbankdefinition aus der Konfiguration des entsprechenden DbLog-Device genutzt.
Es werden nur Inhalte der Tabelle "history" berücksichtigt (Ausnahme Kommando "sqlCmd").

Überblick, welche anderen Perl-Module DbRep verwendet:

::POSIX
::Time::HiRes
::Time::Local
::Scalar::Util
::DBI
::Blocking (FHEM-Modul)
::Encode

== Definition ==
<pre>
define <name> DbRep <Name der DbLog-instanz>
</pre>

(*) '''<Name der DbLog-Instanz>:''' Es wird der Name der auszuwertenden DbLog-Datenbankdefinition angegeben, '''NICHT''' die Datenbank selbst.

Aus Performancegründen sollte der Index "Report_Idx" in der Datenbank (Tabelle history) angelegt sein. Ab der DbRep-Version 8.20.0 kann dieser Index, sowie die für DbLog benötigten Indizes, verwaltet werden.
Der Index "Report_Idx" wird einfach mit dem DbRep-Befehl:

<pre>
set <name> index recreate_Report_Idx
</pre>

auf der Datenbank angelegt. Ist er bereits vorhanden, wird er gelöscht und erneut angelegt.

== Set ==
Siehe {{Link2CmdRef|Lang=de|Anker=DbRep-set}}

== Get ==
Siehe {{Link2CmdRef|Lang=de|Anker=DbRep-get}}

== Attribute ==
Siehe {{Link2CmdRef|Lang=de|Anker=DbRep-attr}}

== DbRep Agent - automatisches Ändern von Device-Namen in Datenbanken und DbRep-Definitionen nach FHEM "rename" ==

Mit dem Attribut "role" wird die Rolle des DbRep-Device festgelegt. Die Standardrolle ist "Client". Mit der Änderung der Rolle in "Agent" wird das Device veranlasst auf Umbenennungen von Geräten in der FHEM Installation zu reagieren.

Durch den DbRep-Agenten werden folgende Features aktiviert wenn ein Gerät in FHEM mit "rename" umbenannt wird:

* in der dem DbRep-Agenten zugeordneten Datenbank (Internal Database) wird nach Datensätzen mit dem alten Gerätenamen gesucht und dieser Gerätename in allen betroffenen Datensätzen in den neuen Namen geändert.

* in dem DbRep-Agenten zugeordneten DbLog-Device wird in der Definition das alte durch das umbenannte Device ersetzt. Dadurch erfolgt ein weiteres Logging des umbenannten Device in der Datenbank.

* in den existierenden DbRep-Definitionen vom Typ "Client" wird ein evtl. gesetztes Attribut "device = alter Devicename" in "device = neuer Devicename" geändert. Dadurch werden Auswertungsdefinitionen bei Geräteumbenennungen automatisch konsistent gehalten.

Mit der Änderung in einen Agenten sind folgende Restriktionen verbunden, die mit dem Setzen des Attributes "role = Agent" eingeschaltet und geprüft werden:

* es kann nur einen Agenten pro Datenbank in der FHEM-Installation geben. Ist mehr als eine Datenbank mit DbLog definiert, können ebenso viele DbRep-Agenten eingerichtet werden

* mit der Umwandlung in einen Agenten wird nur noch das Set-Komando "renameDevice" verfügbar sein sowie nur ein eingeschränkter Satz von DbRep-spezifischen Attributen zugelassen. Wird ein DbRep-Device vom bisherigen Typ "Client" in einen Agenten geändert, werden evtl. gesetzte und nun nicht mehr zugelassene Attribute glöscht.

Die Aktivitäten wie Datenbankänderungen bzw. Änderungen an anderen DbRep-Definitionen werden im Logfile mit verbose=3 protokolliert. Damit die renameDevice-Funktion bei großen Datenbanken nicht in ein timeout läuft, sollte das Attribut "timeout" entsprechend dimensioniert werden. Wie alle Datenbankoperationen des Moduls wird auch das Autorename nonblocking ausgeführt.

'''Beispiel''' für die Definition eines DbRep-Device als Agent:

<pre>
define Rep.Agent DbRep LogDB
attr Rep.Agent devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.Agent icon security
attr Rep.Agent role Agent
attr Rep.Agent room DbLog
attr Rep.Agent showproctime 1
attr Rep.Agent stateFormat { ReadingsVal("$name","state", undef) eq "running" ? "renaming" : ReadingsVal("$name","state", undef). " » ProcTime: ".ReadingsVal("$name","sql_processing_time", undef)." sec"}
attr Rep.Agent timeout 86400
</pre>

== hilfreiche SQL Statements ==

In dieser Rubrik werden SQL-Statements zusammengetragen, die User für ihre Auswertungen hilfreich fanden und anderen Anwendern zur Verfügung stellen.

Im Folgenden wird MySQL auch stellvertretend für MariaDB verwendet.

Die Statements können mit dem Befehl:

set <DbRep> sqlCmd <SQL-Statement>

ausgeführt werden. Für die Anpassung der Ergebnisdarstellung ist das Attribut '''sqlResultFormat''' verfügbar.

'''Hinweis: '''
Die Statements sind durch den DbRep-Modulautor nicht in jedem Fall getestet und dem Anwender obliegt vor Anwendung der Statements eine Datenbanksicherung durchzuführen um im Fehlerfall diese wieder herstellen zu können.

 
=== Den ersten und den letzten Wert eines Zeitraums selektieren bzw. deren Differenz (MySQL) ===
Beispiel 1:

Den ersten und letzten Wert der durch die DB-Variablen bestimmten Parameter ausgegeben.

Verwendete DB-Variablen (@) : begin_time, end_time, device und reading
SET @begin_time='2020-06-02 12:30:00';SET @end_time='2020-06-02 18:00:00';
SET @device='shelly02';SET @reading='energy_0';

SELECT TIMESTAMP,READING,round(VALUE/1000,0) AS VALUE
FROM (
(SELECT TIMESTAMP,READING,VALUE FROM history WHERE DEVICE = @device AND READING = @reading AND TIMESTAMP >= @begin_time and TIMESTAMP <= @end_time ORDER BY TIMESTAMP LIMIT 1)
UNION ALL
(SELECT TIMESTAMP,READING,VALUE FROM history WHERE DEVICE = @device AND READING = @reading AND TIMESTAMP >= @begin_time and TIMESTAMP <= @end_time ORDER BY TIMESTAMP DESC LIMIT 1)
) AS X1;

+---------------------+----------+-------+
| TIMESTAMP | READING | VALUE |
+---------------------+----------+-------+
| 2020-06-02 12:31:01 | energy_0 | 69 |
| 2020-06-02 16:31:05 | energy_0 | 73 |
+---------------------+----------+-------+
Beispiel 2:

Berechnung der Differenz vom 1. Beispiel

Verwendete DB-Variablen (@) : begin_time, end_time, device und reading

Hierbei ist zu beachten, dass die einzelnen Selects vertauscht wurden um den TIMESTAMP des ersten Select zu bekommen.

Die Subtraktion wurde durch "mal Minus Eins" des kleineren Wertes erreicht.<pre>
SET @begin_time='2020-06-02 12:30:00';SET @end_time='2020-06-02 18:00:00';
SET @device='shelly02';SET @reading='energy_0';

SELECT TIMESTAMP,READING,round(sum(VALUE)/1000,0) AS VALUE
FROM (
(SELECT TIMESTAMP,READING,VALUE FROM history WHERE DEVICE = @device AND READING = @reading AND TIMESTAMP >= @begin_time and TIMESTAMP <= @end_time ORDER BY TIMESTAMP DESC LIMIT 1)
UNION ALL
(SELECT TIMESTAMP,READING,(VALUE * -1) AS VALUE FROM history WHERE DEVICE = @device AND READING = @reading AND TIMESTAMP >= @begin_time and TIMESTAMP <= @end_time ORDER BY TIMESTAMP LIMIT 1)
) AS X1;

+---------------------+----------+-------+
| TIMESTAMP | READING | VALUE |
+---------------------+----------+-------+
| 2020-06-02 16:31:05 | energy_0 | 4 |
+---------------------+----------+-------+
</pre>
Die Formatierung

<pre>
round(sum(VALUE)/1000,0) AS VALUE
</pre>

sollte eventuell angepasst werden, da diese natürlich zum zu erwartenden Ergebnis passen muss.

=== Wieviel PV-Leistung wird von einem Starkverbraucher verwendet (MySQL) ===
Hier wurde versucht aus der Datenbank zu ermitteln, wieviel PV-Leistung für z.B. eine Wärmepumpe übrig bleibt.
Dabei wurde der grundlegenden Hausverbrauch als erstes in Abzug gebracht und der Rest mit dem Starkverbraucher verrechnet.
Natürlich kann man solch einen Report nur für einen Verbraucher verwenden, da man ja den Überschuss nur einem zuordnen kann.
Auch wird hier mit einem Stundendurchschnitt gerechnet, was somit als Näherung angesehen werden muss.
<pre>
1) Zuerst werden die einzelnen Daten für einen Tag zusammen gesucht
2) Jeder Datenteil wird mit einem Durchschnitt auf Stundenbasis berechnet
3) Im JOIN werden alle Datenteile für die relevanten Stunden zusammen geführt. Maßgeblich hierbei ist der Betrieb des Starkverbrauchers
zu dem Zeitpunkt wo auch PV-Leistung verfügbar war. Alle anderen Stunden tauchen danach nicht mehr auf. Ist es ein Hybrid WR mit
Speicher, dann kann auch in der Nacht eine Unterstützung erfolgen, was im Winter jedoch recht selten sein wird.
4) Es wird der restliche Hausverbrauch ermittelt. Achtung, der Starkverbraucher ist ein Verbraucher, weshalb die Leistung im Zähler
negativ summiert wird. Ein "+consumer_P" ist somit eine Summe mit einem negativen Wert ;-)
5) Im letzten SELECT werden dann die Daten final aufbereitet und formatiert, auch der prozentuale Anteil der PV-Leistung am gesamten
Starkverbrauch wird noch berechnet.
</pre>
<pre>
consumer = Das Zähler Device des Starkverbrauchers
consumer_P = negative Leistungsanzeige in Watt, da es ein Verbraucher ist!
generator = Das Wechselrichter Device
generator_P = Die AC Ausgangsleistung in Watt
Home_consumtion_P = Der Hausverbrauch inklusive des Starkverbrauchers in Watt (ebenfalls im generator Device)
</pre>
Die verwendeten Variablen lassen sich im DbRep als Attribut setzen
<pre>
sqlCmdVars
SET @date:='2022-12-07', @consumer:='StromZaehler_Heizung', @consumer_P:='SMAEM1901401955_Saldo_Wirkleistung', @generator:='WR_1', @generator_P:='SW_Total_AC_Active_P', @Home_Consumtion_P:='SW_Home_own_consumption';
</pre>
Hier nun das SELECT Statement
<pre>
SET @date:='2022-12-07',
@consumer:='StromZaehler_Heizung', @consumer_P:='SMAEM1901401955_Saldo_Wirkleistung',
@generator:='WR_1', @generator_P:='SW_Total_AC_Active_P', @Home_Consumtion_P:='SW_Home_own_consumption';

SELECT
X.HOUR,
cast(X.generator_P AS decimal(7,2)) AS generator_P,
cast(X.Home_Consumption AS decimal(7,2)) AS Home_Consumption,
cast(X.PV_after_Home_Consumtion AS decimal(7,2)) AS PV_after_Home_Consumtion,
cast(X.consumer_P AS decimal(7,2)) AS consumer_P,
if(consumer_P+PV_after_Home_Consumtion <= 0,cast(round(abs(consumer_P+PV_after_Home_Consumtion),2) AS decimal(7,2)),0) AS from_Grid,
if(round(consumer_P+PV_after_Home_Consumtion,2) <= 0,round(abs(PV_after_Home_Consumtion*100/consumer_P),0),100) AS Percent
FROM (
SELECT
X1.HOUR,
generator_P,
round(Home_Consumtion_P+consumer_P,2) AS Home_Consumption,
if(Home_Consumtion_P+consumer_P-generator_P < 0,round(abs(Home_Consumtion_P+consumer_P-generator_P),2),0) AS PV_after_Home_Consumtion,
consumer_P
FROM (
SELECT
hour(TIMESTAMP) AS HOUR,
round(avg(value),2) AS consumer_P
FROM history
WHERE
TIMESTAMP > @date and TIMESTAMP < DATE_ADD(@date,INTERVAL 1 DAY) AND
DEVICE = @Consumer AND
READING = @consumer_P
GROUP BY 1
) X1
JOIN (
SELECT
hour(TIMESTAMP) AS HOUR,
round(avg(value),2) AS generator_P
FROM history
WHERE
TIMESTAMP > @date AND TIMESTAMP < DATE_ADD(@date,INTERVAL 1 DAY) AND
DEVICE = @generator AND
READING = @generator_P AND
VALUE > 10
GROUP BY 1
) X2
JOIN (
SELECT
hour(TIMESTAMP) AS HOUR,
round(avg(value),2) AS Home_Consumtion_P
FROM history
WHERE
TIMESTAMP > @date and TIMESTAMP < DATE_ADD(@date,INTERVAL 1 DAY) AND
DEVICE = @generator AND
READING = @Home_Consumtion_P AND
VALUE > 10
GROUP BY 1
) X3
ON X1.HOUR = X2.HOUR
AND X1.HOUR = X3.HOUR
) X;
</pre>

=== Temperaturdifferenz eines Pufferspeichers über die Zeit ermitteln (MySQL) ===
Beispiel 1:

Temperaturdifferenz des Pufferspeichers über die Zeit in Minuten

<nowiki>Referenz zum DBRep : set [device] sqlSpecial readingsDifferenceByTimeDelta</nowiki>

Verwendete DB-Variablen (@) : device und reading, diff und delta werden für Berechnungen benötigt und sind bei erneutem Aufruf zurück zu setzen

Anmerkungen:

- Der Zeitraum wird in diesem Beispiel als die letzten 24 Stunden festgelegt

- Die Zeitdifferenz für die Änderung steht in der Spalte DELTA in Minuten

- In FHEM wurde mit event-on-change-reading ins DBLog geschrieben

- Bei dieser Ausgabe kann man erkennen, dass die Temperaturänderung im Wärmespeicher oft sehr klein ist, was ja auch so gewollt ist

- Um 14:00 Uhr beginnt die Wärmepumpe das Warmwasser wieder aufzuheizen<pre>
SET @device='Heizung';SET @reading='hotWaterTemperature';
SET @diff=0;SET @delta=NULL;

SELECT t1.TIMESTAMP,t1.READING,t1.VALUE,t1.DIFF,t1.DELTA
FROM
(
SELECT TIMESTAMP,READING,VALUE,
if(@diff = 0,NULL, cast((VALUE-@diff) AS DECIMAL(3,1))) AS DIFF,
@diff:=VALUE AS curr_V,
TIMESTAMPDIFF(MINUTE,@delta,TIMESTAMP) AS DELTA,
@delta:=TIMESTAMP AS curr_T
FROM history
WHERE DEVICE = @device AND
READING = @reading AND
TIMESTAMP >= NOW() - INTERVAL 1 DAY
ORDER BY TIMESTAMP
) t1;
+---------------------+---------------------+-------+------+-------+
| TIMESTAMP | READING | VALUE | DIFF | DELTA |
+---------------------+---------------------+-------+------+-------+
| 2020-06-04 10:05:20 | hotWaterTemperature | 46.5 | NULL | NULL |
| 2020-06-04 10:35:31 | hotWaterTemperature | 46.4 | -0.1 | 30 |
| 2020-06-04 11:00:31 | hotWaterTemperature | 46.2 | -0.2 | 25 |
snip...
| 2020-06-04 13:50:42 | hotWaterTemperature | 44.5 | -1.0 | 5 |
| 2020-06-04 13:55:42 | hotWaterTemperature | 44.0 | -0.5 | 5 |
| 2020-06-04 14:00:42 | hotWaterTemperature | 43.9 | -0.1 | 5 |
| 2020-06-04 14:10:42 | hotWaterTemperature | 41.7 | -1.8 | 5 |
snip...
| 2020-06-04 14:51:05 | hotWaterTemperature | 51.3 | 0.1 | 5 |
| 2020-06-04 17:01:15 | hotWaterTemperature | 51.2 | -0.1 | 130 |
snip...
| 2020-06-04 22:10:30 | hotWaterTemperature | 50.5 | -0.2 | 5 |
snip...
| 2020-06-05 11:30:45 | hotWaterTemperature | 46.1 | -0.1 | 25 |
+---------------------+---------------------+-------+------+-------+

</pre>Beispiel 2:

Summieren der Temperaturdifferenz auf Stundenbasis

Verwendete DB-Variablen (@) : device und reading, diff und delta werden für Berechnungen benötigt und sind bei erneutem Aufruf zurück zu setzen

Anmerkungen:

- Der Zeitraum wird in diesem Beispiel als die letzten 24 Stunden festgelegt

- Die Zeitdifferenz wird bei diesem Beispiel nicht ausgegeben

- Alle Differenzen nach der Vollen Stunde werden der nächsten Stunde zugeschlagen

- In FHEM wurde mit event-on-change-reading ins DBLog geschrieben

- Um 14:00 Uhr beginnt die Wärmepumpe das Warmwasser wieder aufzuheizen

- Bei diesem Wärmespeicher sind Temperaturschwankungen im Bereich von Null Komma irgendwas, als Messwert recht ungenau, was im Beispiel 1 zu der Vielzahl an Messwerten geführt hat. Durch Beispiel 2 auf Stundenbasis lässt sich bereits mehr erkennen. Hier wäre der Wärmepumpeneinsatz um 14:00 Uhr mit dem Pumpenvorlauf (-1.8) und der Lauf der Zirkulationspumpe um 8:00 und 8:30 Uhr zu sehen, was den Wärmespeicher um 1,2 Grad abgekühlt hat.<pre>
SET @device='Heizung';SET @reading='hotWaterTemperature';
SET @diff=0;SET @delta=NULL;

SELECT xTIMESTAMP AS TIMESTAMP,READING,xVALUE AS VALUE,xDIFF AS DIFF
FROM
(SELECT DATE_FORMAT(DATE_ADD(t1.TIMESTAMP,INTERVAL (IF(MINUTE(t1.TIMESTAMP) > 0, 60, 0)-MINUTE(t1.TIMESTAMP)) MINUTE),'%Y-%m-%d %H:00:00') AS xTIMESTAMP,
t1.READING,
round(t1.VALUE) AS xVALUE,
sum(t1.DIFF) AS xDIFF,
sum(t1.DELTA) AS xDELTA
FROM
(SELECT TIMESTAMP,READING,VALUE,
if(@diff = 0,NULL, cast((VALUE-@diff) AS DECIMAL(3,1))) AS DIFF,
@diff:=VALUE AS curr_V,
TIMESTAMPDIFF(MINUTE,@delta,TIMESTAMP) AS DELTA,
@delta:=TIMESTAMP AS curr_T
FROM history
WHERE DEVICE = @device AND
READING = @reading AND
TIMESTAMP >= NOW() - INTERVAL 1 DAY
ORDER BY TIMESTAMP
) t1
GROUP BY xTIMESTAMP WITH ROLLUP) x1

WHERE xDELTA IS NOT NULL AND
xTIMESTAMP IS NOT NULL;
+---------------------+---------------------+-------+------+
| TIMESTAMP | READING | VALUE | DIFF |
+---------------------+---------------------+-------+------+
| 2020-06-04 12:00:00 | hotWaterTemperature | 46 | -0.1 |
| 2020-06-04 13:00:00 | hotWaterTemperature | 46 | -0.4 |
| 2020-06-04 14:00:00 | hotWaterTemperature | 44 | -1.8 |
| 2020-06-04 15:00:00 | hotWaterTemperature | 51 | 7.4 |
| 2020-06-04 18:00:00 | hotWaterTemperature | 51 | -0.1 |
snip...
| 2020-06-05 07:00:00 | hotWaterTemperature | 48 | -0.3 |
| 2020-06-05 08:00:00 | hotWaterTemperature | 48 | -0.2 |
| 2020-06-05 09:00:00 | hotWaterTemperature | 48 | -1.2 |
| 2020-06-05 10:00:00 | hotWaterTemperature | 47 | -0.3 |
snip...
+---------------------+---------------------+-------+------+
</pre>

=== Alle aktuellsten readings eines Device im letzten Tagesverlauf (MySQL) ===
Beispiel :

Verwendete DB-Variablen (@) : device

Anmerkungen:

- Der Zeitraum wird in diesem Beispiel als die letzten 24 Stunden festgelegt

- In FHEM wurde mit event-on-change-reading ins DBLog geschrieben, wodurch nicht alle readings immer zeitlich in der DB aufeinander folgen oder einige im Zeitraum mehrfach geschrieben wurden. Mit diesem Aufruf erscheinen immer die letzten Aktualisierungen.

- Sollten einige readings nicht erscheinen, so wurden diese vor dem Zeitraum letztmalig aktualisiert. Mit "INTERVAL [n] DAY könnten diese eventuell auch noch gefunden werden. Bitte hier die Laufzeit beachten!<pre>
SET @device = 'Heizung';

SELECT t1.TIMESTAMP,t1.DEVICE,t1.READING,t1.VALUE
FROM history t1
INNER JOIN
(select max(TIMESTAMP) AS TIMESTAMP,DEVICE,READING
from history
where DEVICE = @device and
TIMESTAMP > NOW() - INTERVAL 1 DAY
group by READING) x
ON x.TIMESTAMP = t1.TIMESTAMP AND
x.DEVICE = t1.DEVICE AND
x.READING = t1.READING;
</pre>

 
=== Device / Reading Daten in eine CSV-Datei exportieren (MySQL) ===

Grundsätzlich gibt es für diesen Zweck das eingebaute Set-Kommando '''exportToFile'''.

Eine weitere Möglichkeit ist die Verwendung von spezifischen Datenbankkommandos, die mit Set '''sqlCmd''' ausgeführt werden können.

Im Beispiel wird ein CSV File geschrieben, welches die Daten des Devices 'SMA_Energymeter' enthält.
Wichtig ist, nicht zur Trennung von SQL-Befehlen dienende Semikolons durch Verdopplung zu escapen (z.B. im String "...TERMINATED BY ';;'...").

<pre>
SET @TS = DATE_FORMAT(NOW(),'_%Y_%m_%d');

SET @FOLDER = '/volume1/ApplicationBackup/';
SET @PREFIX = 'export';
SET @EXT = '.csv';

SET @CMD = CONCAT(" SELECT *
FROM `fhemtest`.`history`
WHERE `DEVICE`='SMA_Energymeter' AND TIMESTAMP > DATE_SUB(CURRENT_DATE(),INTERVAL 1 DAY)
INTO OUTFILE '",@FOLDER,@PREFIX,@TS,@EXT,"'
FIELDS ENCLOSED BY '\"'
TERMINATED BY ';;'
ESCAPED BY '\"'","
LINES TERMINATED BY '\r\n';;
");

PREPARE statement FROM @CMD;

EXECUTE statement;
</pre>

'''Hinweis:''' der verwendete Datenbank-User benötigt das '''FILE''' Recht.

 
=== Gewichtete Mittelwerte von Zeitreihen (MySQL) ===
Zeitreihen in FHEM sind Messwerte (z.B. Temperatur, Stromverbrauch, PV-Produktion ...), die i.A. nicht zu äquidistanten Zeitpunkten ermittelt und protokolliert werden, sondern nur bei Änderung der Messgröße. Für eine Zusammenfassung ("Aggregation") zum Zwecke statistischer Auswertung oder einfach zur Datenreduktion sollte daher bei einer Mittelwertbildung auf zeitlich gewichtete Mittelung zurückgegriffen werden. Ein interessierender Gesamtzeitraum wird dazu in einzelne Mittelungsintervalle (sogen. ''bins'') aufgeteilt, für die dann der gewichtete Mittelwert berechnet wird.

Die (non-blocking) DbRep-Funktion 'set averageValue' macht, in Verbindung mit den Attributen 'aggregation' (Auswahl einer Aggregationsperiode) und 'averageCalcForm'='avgTimeWeightMean' genau das. Dabei hat man als ''bin''-Länge 'minute', 'hour', 'day', 'week', 'month' und 'year' zur Verfügung.

Der folgende ''SQL-Query 1'' kennt als ''bin''-Längen auch Viertelstunden ('qhour'), Vierteltage ('qday') und Quartal ('qyear'). Die Parameter @sortformat=["minute"|"qhour"|"hour"|"qday"|"day"|"week"|"month"|"qyear"|"year"] und @weighted=["yes"|"no"] müssen vor Ausführung des Codes mit dem Attribut sqlCmdVars gesetzt werden, z.B.
set <Your_DbRep_device> sqlCmdVars SET @sortformat="hour", @weighted="yes", @count=<n>;

<div class="mw-customtoggle-query1 wikia-menu-button">'''''SQL-Query 1'' ein/ausblenden'''</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-query1>
SELECT
avgtim,
CASE @weighted
WHEN "yes" THEN
CAST((SUM(val * weight)/SUM(weight)) AS DECIMAL(12,4))
ELSE
CAST(sum(val) / count(val) AS DECIMAL(12,4))
END AS avrg
FROM (
SELECT
tim,
avgtim,
CASE @sortformat
WHEN "week" THEN
date_format(tim, "%Y-%u 00:00:00")
ELSE
avgtim
END AS grouptim,
CASE
WHEN avgtim!=nextavgtim THEN
to_seconds(nextavgtim)-to_seconds(tim)
WHEN avgtim!=preavgtim THEN
to_seconds(nexttim)-to_seconds(avgtim)
ELSE
to_seconds(nexttim)-to_seconds(tim)
END AS weight,
CASE
WHEN avgtim!=preavgtim THEN
CASE @weighted WHEN "yes"
THEN
CASE
WHEN avgtim!=nextavgtim THEN
(preval*(to_seconds(tim)-to_seconds(avgtim)) + val*(to_seconds(nextavgtim)-to_seconds(tim)))/
(to_seconds(nextavgtim)-to_seconds(avgtim))
ELSE
(preval*(to_seconds(tim)-to_seconds(avgtim)) + val*(to_seconds(nexttim)-to_seconds(tim)))/
(to_seconds(nexttim)-to_seconds(avgtim))
END
ELSE
val
END
ELSE
val
END AS val
FROM (
SELECT
tim,
nexttim,
val,
preval,
avgtim,
LAG(avgtim) OVER (ORDER BY tim) AS preavgtim,
LEAD(avgtim) OVER (ORDER BY tim) AS nextavgtim
FROM (
SELECT
timestamp AS tim,
LEAD(timestamp) OVER (ORDER BY timestamp) AS nexttim,
value AS val,
LAG(value) OVER (ORDER BY timestamp) AS preval,
CASE @sortformat
WHEN "minute" THEN
date_format(timestamp, "%Y-%m-%d %H:%i:00")
WHEN "qhour" THEN
concat(date_format(timestamp, "%Y-%m-%d %H:"),LPAD(15*(date_format(timestamp,"%i") div 15),2,"0"),":00")
WHEN "hour" THEN
date_format(timestamp, "%Y-%m-%d %H:00:00")
WHEN "qday" THEN
concat(date_format(timestamp, "%Y-%m-%d "),LPAD(6*(date_format(timestamp, "%H") div 6),2,"0"),":00:00")
WHEN "day" THEN
date_format(timestamp, "%Y-%m-%d 00:00:00")
WHEN "week" THEN
date_format(timestamp, "%Y-%m-%d 00:00:00")
WHEN "month" THEN
date_format(timestamp, "%Y-%m-01 00:00:00")
WHEN "qyear" THEN
concat(date_format(timestamp, "%Y-"),LPAD(3*(date_format(timestamp, "%m") div 3),2,"0"),"-01 00:00:00")
ELSE
date_format(timestamp, "%Y-01-01 00:00:00")
END AS avgtim
FROM
history WHERE TIMESTAMP BETWEEN §timestamp_begin§ AND §timestamp_end§ AND §device§ AND §reading§ ORDER BY timestamp
) select3
) select2
) select1 GROUP BY grouptim
</div>

Die Auswahl von ''device'', ''reading'' und Zeitraum erfolgt über die üblichen Attribute. Es darf nur ein ''device'' und ein ''reading'' gewählt werden. Für den Zeitraum btte nur ''timestamp_begin'' und ''timestamp_end'' nutzen.

Will man keine festen Zeitraster, kann man den Gesamtzeitraum auch einfach in eine Anzahl ''count'' von bins aufteilen. Dafür steht der Parameter @count im obigen sqlCmdVars statement (für Query 1 hat er keine Bedeutung).

<div class="mw-customtoggle-query2 wikia-menu-button">'''''SQL-Query 2'' ein/ausblenden'''</div>
<div class="mw-collapsible mw-collapsed" id="mw-customcollapsible-query2>
SELECT
tim,
CASE
WHEN @weighted="yes" THEN
CAST(sum(val * (to_seconds(nexttim)-to_seconds(tim))) / sum((to_seconds(nexttim)-to_seconds(tim))) AS DECIMAL(12,4))
ELSE CAST(sum(val) / count(val) AS DECIMAL(12,4))
END AS avrg
FROM (
SELECT
timestamp as tim,
value as val,
LEAD(timestamp) over (order by timestamp) nexttim,
truncate(@count * (to_seconds(timestamp)-to_seconds(§timestamp_begin§)) / (to_seconds(§timestamp_end§)-to_seconds(§timestamp_begin§)),0)/@count as avgtim
FROM
history WHERE TIMESTAMP BETWEEN §timestamp_begin§ AND §timestamp_end§ AND §device§ AND §reading§
) select1 group by avgtim
</div>

Zur Ausführung der Queries den Code entweder ins Eingabefeld hinter set sqlCmd (bzw. sqlCmdBlocking) kopieren und dann mit ''set'' ausführen, oder per ''set <Your_DbRep_device> sqlCmd <kopierter Code>'' in der FHEM Kommandozeile ausführen.

Getestet wurden diese MySQL Beispiele mit MariaDB 10.3

Siehe auch im Forum: https://forum.fhem.de/index.php/topic,53584.msg1254036.html#msg1254036

 

== Praxisbeispiele / Hinweise und Lösungsansätze für verschiedene Aufgaben ==
=== Definieren eines DbRep-Devices ===
[[Bild:DbRep_initialized.PNG|right|thumb|400px|]]

Das DbRep-Device wird bei der Definition mit der DbLog-Instanz verbunden, in deren angeschlossener Datenbank später die Auswertungen und Operationen stattfinden sollen. Es ist also nicht die Datenbank selbst, sondern das vorher definierte DbLog-Device anzugeben.
Die Definition erfolgt z.B. durch:

<pre>
define Rep.Energy DbRep LogDB #LogDB ist das zu verbindende DbLog-Device
</pre>

Bei der Definition werden die Zugangsdaten aus der DbLog-Instanz gelesen und das DbRep-Device mit der Datenbank verbunden. Nach der Definition ist der Status "initialized". Die Verbindung zur Datenbank wird mit der ersten abzuarbeitenden Aufgabe hergestellt. Das Verhalten kann mit dem '''Attribut fastStart''' beeinflusst werden.
Zu welcher Datanbank das DbRep-Device sich verbunden hat, zeigt das ''Internal'' DATABASE.

Damit ist das DbRep-Device grundsätzlich einsatzbereit, aber noch nicht praxistauglich. Werden keine weiteren Eingrenzungen angegeben, kann mit dem so definierten Device mit dem Befehl

<pre>
set Rep.Energy countEntries
</pre>

die gesamte Anzahl der Datensätze in der Datenbank ermittelt werden.
Für eine weitere Verwendung sind weitere ''Attribute'' zu setzen.
Um die Funktionen von "Rep.Energy" nur auf z.B. Datensätze in der Datenbank anzuwenden die "STP_5000" im Feld "DEVICE" enthalten, wird das '''Attribut''':

<pre>
attr Rep.Energy device STP_5000
</pre>

gesetzt. Weitere Begrenzungen der gerätespezifischen Selektion erfolgt durch das '''Attribut''' "reading". So wird durch

<pre>
attr Rep.Energy reading etotal
</pre>

[[Bild:Rep_configured.PNG|right|thumb|300px|]]
festgelegt, dass sich die (allermeisten) Operationen auf die Kombination aus dem "device STP_5000" und dem "reading etotal" beziehen.
Eine zeitliche Eingrenzung der Ergebnisse erfolgt durch die '''Attribute''' "timeDiffToNow", "timeOlderThan", "timestamp_begin", "timestamp_end".
In dem Beispiel sollen sich die Selektionsergebnisse immer auf die letzten 120 Minuten beziehen.
Dazu wird das Attribut

<pre>
attr Rep.Energy timeDiffToNow 7200 #Der Wert für timeDiffToNow ist in Sekunden anzugeben
</pre>

gesetzt. Es wird dynamisch bei jeder Operation "<Selektionsbeginn> = <aktuelle Zeit> - 3600s" berechnet und die Datensätze bis zu <aktuelle Zeit> berücksichtigt.
Die gesamten Datenbankoperationen und teilweise auch Auswertungen von Selektionen erfolgt mit Blockingcall im Hintergrund. Der Timeout für die Operationen ist per Default auf 86400 Sekunden gesetzt. Über das ''Attribut'' "timeout" kann es den eigenen Bedingungen angepasst werden. In dem Beispiel wird timeout auf 300s geändert um auch bei sehr großen Selektionen und Auswertungen nicht in einen timeout zu laufen.

<pre>
attr Rep.Energy timeout 300
</pre>

Um auch die Verarbeitungszeiten im Hintergrund als Reading anzeigen zu lassen wird mit mit dem ''Attribut''

<pre>
attr Rep.Energy showproctime 1
</pre>

erreicht.
Mit diesen Einstellungen ist das Device für den konfiguriert und man kann sich zum Beispiel mit

<pre>
set Rep.Energy fetchrows
</pre>

die Datensätze mit der Gesamtenergierzeugung "etotal" des Wechselrichters "STP_5000" die in den letzten 2 Stunden in die DB geschrieben wurden.
Nachdem der Befehl in der Gerätedetailsicht ausgeführt wurde, wechselt der state im DeviceOverview auf "running". Sobald im DeviceOverview "done" angezeigt wird sieht man die Ergebnisse nach einem Browserrefresh.
Bei der Ausführung einer erneuten Operation werden alle Readings gelöscht. Sollen bestimmte Readings davon ausgenommen werden, kann dem ''Attribut'' eine kommaseparierte Liste von zu schützenden Readings übergeben werden.

Allgemein wird empfohlen sich für jede Aufgabe eine separates DbRep-Device anzulegen und entsprechend zu konfigurieren anstatt die Einstellungen ständig den neuen Aufgaben anzupassen.
Um den Prozess zu vereinfachen, kann das einmal angelegte Device für eine neue Selektionsaufgabe (zum Beispiel die Datensätze eines SMA Energymeters anzuzeigen bzw. auszuwerten) auf ein neues DbRep-Device kopiert

<pre>
copy Rep.Energy Rep.SMAMeter
</pre>

und entsprechend angepasst werden.

'''Hinweis zur Eventgenerierung:''' 
Je nach genutzter Funktion können sehr viele Readings als Ergebnis generiert werden. Zum Beispiel können mit "fetchrows", wobei jedes Reading einer selektierte Zeile aus der Datenbank entspricht, durchaus mehrere hundert Readings entstehen.
Sollte man nicht durch die Attribute "event-on-update-reading" bzw. "event-on-change-reading" die Eventerzeugung auf nur relevante Readings begrenzt haben, können in diesem Fall ebenso viele Events enstehen die das System entsprechend belasten können. 
Deswegen wird empfohlen die '''Eventerzeugung sofort''' auf z.B. "state" zu '''begrenzen'''.

 
=== Ermittlung des monatlichen und durchschnittlichen Gasverbrauches mit Vaillant und eBusd MQTT ===

Es soll der monatliche Gasverbrauch in m3, kWh und Euro sowie der Durchnschnitt in Euro über die gewählten Monate ermittelt werden.

Die auswertenden Daten liegen als "Tics" vor. Es ist eine stetig steigende Zahl ohne Einheit. Sie wird als Reading aus einem Vaillant eBus-MQTT Device geloggt. eBusd liefert PrEnergySumHc2 und PrEnergySumHwc1.
Beide Werte werden als Summe im Reading '''1_Brenner_Energy_Summe''' zusammengeführt und geloggt.

[[Bild:Screenshot_2022-12-25_143631.png|right|thumb|400px|]]

Für die Bereitstellung diverser Hilfswerte zur Berechnung existiert ein Dummy-Device '''VaillantControlDummy'''.

Dieses Device enthält in User-Attributen folgende Werte:

* '''Brennwert_kWh/m3''' -> den Brennwert in kWh pro m3 lt. Angaben des Lieferanten
* '''Zustandszahl''' -> die Zustandszahl lt. Angaben des Lieferanten
* '''Multiplikator''' -> ein Faktor zur Umrechnung der geloggten Tics (1_Brenner_Energy_Summe) in m3
* '''Tarif''' -> der persönliche Tarif (Brutto) in €/kWh

Der Multiplikator wurde empirisch als Quotient aus den real verbrauchten m3 und den Tics über einem längeren Zeitraum ermittelt.
Das Ergebnis der Multiplikaktion von geloggten Tics und und Multiplikator ergibt die jeweilig verbrauchten m3. Dieser Wert
ist Toleranz/Fehler behaftet, hat sich aber in der Praxis als hinreichend genau zur Ermittlung des Gasverbrauchs erwiesen.

Das DbRep Device wird wie weiter oben beschrieben angelegt:

define Rep.gas.allmonths DbRep <DbLog-Devicename>

[[Bild:Screenshot_2022-12-25_143912.png|right|thumb|400px|]]

Die folgenden Attribute werden gesetzt um den auszuwertenden Zeitraum, sowie das auszuwertende Device und Reading in der Datenbank auszuwerten.
Die Werte für die Attribute sind natürlich dem persönlichen Umfeld anzupassen:

* '''device''' -> auszuwertendes Device (MQTT2_ebusd_bai)
* '''reading''' -> auszuwertendes Reading (1_Brenner_Energy_Summe)
* '''timestamp_begin''' -> Auswertungszeitraum Beginn (2022-10-01 00:00:00)
* '''timestamp_end''' -> Auswertungszeitraum Ende (current_year_end)
* '''aggregation''' -> month, d.h. der Auswertungszeitraum wird in Monatsscheiben aufgeteilt
* '''numDecimalPlaces''' -> die gwünschte Anzahl der Nachkommastellen im Ergebnis (0)
* '''diffAccept''' -> die akzeptierte Differenz von Diffenzwerten (1000000000), den Wert sehr hoch setzen um keine Datensätze von der Berechnung auszuschließen
* '''event-on-update-reading''' -> state,gas_.*
* '''eventMap''' -> /diffValue display:diffValuedisplay/ (für Verwendung in webCmd)
* '''webCmd''' -> diffValuedisplay

Wird das Device mit diesen Einstellungen gestartet, werden Readings der Form:

2022-10-31_07-05-03__MQTT2_ebusd_bai__1_Brenner_Energy_Summe__DIFF__2022-10
2022-11-30_08-38-18__MQTT2_ebusd_bai__1_Brenner_Energy_Summe__DIFF__2022-11
2022-12-25_12-29-47__MQTT2_ebusd_bai__1_Brenner_Energy_Summe__DIFF__2022-12

generiert. Sie liefern die Anzahl der Tics im jeweiligen Monat.

"Herzstück" zur Ermittlung der Zielwerte ist eine Perl Routine die im Attribut '''userExitFn''' hinterlegt wird:

<syntaxhighlight lang="perl">
{
if ($READING =~ /1_Brenner_Energy_Summe__DIFF/ && $VALUE ne '-') {
my $date = (split '__', $READING)[0];
my ($y,$m,$d) = $date =~ /^(\d{4})-(\d{2})-(\d{2})/x;

my $cdd = "VaillantControlDummy"; # Steuerungsdummy Device
my $mpk = AttrVal($cdd, 'Multiplikator', '0');
my $zz = AttrVal($cdd, 'Zustandszahl', '0'); # Zustandszahl lt. Lieferant
my $bw = AttrVal($cdd, 'Brennwert_kWh/m3', '0'); # Brennwert kWh/m3 lt. Lieferant
my $tarf = AttrVal($cdd, 'Tarif', '0'); # Kosten €/kWh
my $ndp = AttrVal($NAME, 'numDecimalPlaces', '3');
my $m3 = sprintf "%.${ndp}f", $VALUE/10000 * $mpk; # verbrauchte m3
my $kwh = sprintf "%.${ndp}f", $m3 * $zz * $bw; # Umrechnung m3 -> kWh
my $cost = sprintf "%.${ndp}f", $kwh * $tarf; # Kosten = kWh * Tarif
my $hash = $defs{$NAME};

readingsBulkUpdate ($hash, $date.'_gas_consumption_m3', $m3);
readingsBulkUpdate ($hash, $date.'_gas_consumption_kwh', $kwh);
readingsBulkUpdate ($hash, 'gas_cost_euro_'.$y.'-'.$m.'-'.$d, $cost);
}

if ($READING eq 'state' && $VALUE eq 'done') {
my $n = 0;
my $v = 0;
my $avg = 0;

for my $rdg ( grep { /gas_cost_euro_/x } keys %{$hash->{READINGS}} ) {
$n++;
$v += ReadingsNum ($name, $rdg, 0);
}

if ($n) {
my $ndp3 = AttrVal($NAME, 'numDecimalPlaces', '3');
$avg = sprintf "%.${ndp3}f", $v / $n;
readingsBulkUpdate ($hash, 'gas_cost_euro_average', $avg);
}
}
}
</syntaxhighlight>

Sobald ein Reading erstellt wird welches auf den Regex /1_Brenner_Energy_Summe__DIFF/ matcht, werden die User-Attribute aus dem Steuerungsdummy
''VaillantControlDummy'' abgerufen und damit die Berechnung der resultierenden m3 ($m3), kWh ($kwh) und Euro ($cost) durchgeführt.
Die User-Attribute können natürlich auch im DbRep Device selbst hinterlegt werden. Im vorliegenden Fall wird der Steuerungsdummy noch zu weiteren Aufgabe der Heizungssteuerung verwendet, sodass sich die Verwendung auch für diesen Use Case anbietet.

Es werden die Readings

* <Datum>_<Zeit>_gas_consumption_m3
* <Datum>_<Zeit>_gas_consumption_kwh
* gas_cost_euro_<Datum>

erzeugt.

Hat das Device den Report erfolgreich beendet, wird "state" mit dem Wert "done" erzeugt.
Dieser Wert wird ebenfalls in der Routine überwacht und dann der Durchschnittswert ($avg) aus den ermittelten Monatsergebnissen berechnet.
Mit dem Ergebnis wird das Reading:

* gas_cost_euro_average

erstellt.

Zur Gestaltung des Device Overwiew wird im Attribut '''stateFormat''' ebenfalls eine Perl Routine hinterlegt:

<syntaxhighlight lang="perl">
{
my $state = ReadingsVal($name, 'state', '');
my $gca = ReadingsVal($name, 'gas_cost_euro_average', undef);

my $show = '';
$show .= defined $gca ? 'Durchschnittskosten Gas: '.$gca.' €' :
$state;
$show .= ' ';
$show .= $state =~ /connected/xs ? FW_makeImage('10px-kreis-gelb') :
$state =~ /initialized/xs ? FW_makeImage('control_3dot_hor_s') :
$state =~ /disconnect/xs ? FW_makeImage('10px-kreis-rot') :
$state =~ /done/xs ? FW_makeImage('10px-kreis-gruen') :
$state =~ /Warning/xs ? FW_makeImage('info_warning@darkorange') :
$state =~ /running/xs ? '' :
FW_makeImage('10px-kreis-rot');

"<div>".$show."</div>"
}
</syntaxhighlight>

 

=== Datensätze (Devices) von einer Datenbank in eine andere umziehen (Export/Import)===
==== Zweck ====

Oft ist es so, dass man zunächst eine DbLog-Datenbank anlegt um alle zu loggenden Events dort aufzuzeichnen. Mit zunehmender Größe bzw. mit dem Wunsch nach einer höheren Strukturierung werden weitere DbLog-Instanzen angelegt.
Die bereits geschriebenen Datensätze eines Gerätes müssen nun in eine andere Datenbank verlagert werden, weil das Device nunmehr in dieser Datenbank geloggt und ausgewertet werden soll.

Für das Beispielszenario gilt folgendes:

* Quelldatenbank aus der das Device entfernt werden soll ist "fhem" mit der DbLog-Instanz "LogDB"
* Zieldatenbank ist "fhemshort" mit der DbLog-Instanz "LogDBShort"
* das umzuziehende Device ist "MelderCP1"
* das definierte DbRep-Device ist "Rep.MelderCP1"

==== Vorbereitung ====

Zunächst wird ein DbRep-Device definiert (falls es noch nicht existiert) und für den Verwendungszweck vorbereitet (zur Definition siehe [[#Definieren_eines_DbRep-Devices | Definieren eines DbRep-Devices]]).

Das Attribut "reading" bzw. eventuell gesetzte Attribute zur Zeiteingrenzung werden gelöscht, damit alle Datensätze des Devices erfasst werden können.
Für den bevorstehenden Export wird mit dem Attribut "expimpFile" der (beschreibbare) Pfad und Dateiname festgelegt, hier im Beispiel ist es "/media/sf_Backup_FHEM/meldercp1.txt".

[[Datei:Rep_MelderCP1_count.PNG|right|thumb|200px|Anzahl Einträge von MelderCP1]]

Mit

<pre>
set Rep.MelderCP1 countEntries
</pre>

kann man sich nun einen Überblick verschaffen, wie viele Datensätze in der Quelldatenbank für "MelderCP1" enthalten sind und wie viele auch exportiert werden müssen. In dem Beispiel sind es, wie in dem Screenshot zu sehen, 1144 Datensätze.

Falls noch nicht geschehen, wird in der bisherigen DbLog-Definition das zu loggende Device entfernt und in der neuen DbLog-Definition aufgenommen, damit nun keine neuen Datensätze mehr für "MelderCP1" in die bisherige Datenbank geschrieben werden. Hierzu siehe die {{Link2CmdRef|Lang=de|Anker=DbLog}} zu DbLog.

==== Export ====
Nun werden die Datensätze des Devices "MelderCP1" mit dem folgenden set-Kommando in die Datei "/media/sf_Backup_FHEM/meldercp1.txt" exportiert.

<pre>
set Rep.MelderCP1 exportToFile
</pre>

Nach dem Export sollte natürlich im Reading von "Rep.MelderCP1" die gleiche Anzahl von exportierten Datensätzen ausgegeben werden wie vorher mit "countEntries" ermittelt wurde (siehe Screenshot).

[[Datei:Rep_MelderCP1_exported.PNG|right|thumb|300px|Anzahl exportierter Dataensätze]]

In der Export-Datei sind nun die Datensätze im CVS-Format enthalten.

Ein Ausschnitt:

<pre>
............
"2016-07-04 17:32:03","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 07:47:50","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 08:27:57","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 08:28:25","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 10:23:42","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 10:27:35","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-05 17:26:30","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-06 07:46:31","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-06 11:24:04","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-06 11:25:43","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
"2016-07-06 11:26:52","MelderCP1","FS20","on-old-for-timer 60","state","on-old-for-timer 60",""
...........
</pre>

In der bisherigen Datenbank "fhem" können die Datensätze nun gelöscht werden. Dazu versehen wir das DbRep-Device "Rep.MelderCP1" mit dem Attribut "allowDeletion" um die Löschfunktion des Moduls freizuschalten.
Nun werden die vorher exportierten Datensätze gelöscht mit:

[[Bild:Rep_MelderCP1_delrows.PNG|right|thumb|300px|Anzahl gelöschter Datensätze]]

<pre>
set Rep.MelderCP1 delEntries
</pre>

Auch jetzt ist wieder sicherzustellen dass in der Ausgabe der gelöschten Rows dieselbe Anzahl (1144) der exportierten Datensätze enthalten ist.

==== Import ====
Im nächsten Schritt werden die exportierten Daten in die neue Datenbank importiert. Dazu wird in unserem DbRep-Device "Rep.MelderCP1" zunächst das "allowDeletion"-Attribut sicherheitshalber gelöscht.
Zur Umstellung des DbRep-Devices auf die neue Datenbank wird die Definition von "Rep.MelderCP1" editiert und dort die neue DbLog-Instanz "LogDBShort" angegeben.

<pre>
modify Rep.MelderCP1 LogDBShort
</pre>

Nach einem kurzen Moment wird der state von "Rep.MelderCP1" sich wieder von "initialized" auf "connected" ändern sofern die Umstellung funktioniert hat. Mit einem Vergleichslauf durch
[[Datei:Rep_MelderCP1_Vergleichslauf.PNG|right|thumb|300px|Anzahl Einträge von MelderCP1 in neuer Datenbank nach Umstellung]]

<pre>
set Rep.MelderCP1 countEntries
</pre>

wird ersichtlich, dass sich in dieser Datenbank noch keine (oder vllt. bereits neu geloggte) Einträge von "MelderCP1" befinden.

Nun kann der Import erfolgen. Mit

<pre>
set Rep.MelderCP1 importFromFile
</pre>

werden die Daten aus der immer noch im Attribut "expimpFile" hinterlegten Datei "/media/sf_Backup_FHEM/meldercp1.txt" in die Datenbank "fhemshort" importiert. Dieser Vorgang wird als Transaktion ausgeführt. Es werden immer alle Daten oder, im Falle eines Fehlers, '''KEINE''' Daten importiert. Damit ist sichergestellt dass der Datenimport immer einen definierten Zustand hat. Sollte der Datenimport sehr umfangreiche Datensätze enthalten und somit schon absehbar sein dass der voreingestellte timeout-Wert von 86400 Sekunden nicht ausreichen wird, kann man vorsorglich das Attribut "timeout" höher setzen, z.B. auf das Doppelte).

Hier in dem Beispiel sind es lediglich 1144 Datensätze die sehr schnell importiert werden. Somit ist keine Anpassung des timeout-Parameters notwendig.
Auch nach dem Import wird wieder die Anzahl der verarbeiteten Dataensätze ausgegeben. Sie sollte natürlich ebenfalls mit den vorab ermittelten Zahlen der exportierten Datensätze übereinstimmen.

[[Datei:Rep_MelderCP1_importedrows.PNG|right|thumb|300px|Anzahl importierter Datensätze]]

==== Abschluss ====

Nach dem erfolgreichen Import sollte das Attribut "expimpFile" wieder entfernt werden damit man nicht versehentlich einen erneuten Import durchführt.
Das verwendete Rep.MelderCP1 kann nun wieder mit Zeitbegrenzungsattributen usw. versehen werden um die ursprüngliche Verwendung wieder herzustellen.

Die dargestellte Prozedur stellt einen Komplettumzug eines Devices dar, kann jedoch durch die Angabe der bekannten Attribute auch auf bestimmte Readings in der Datenbank oder Zeitgrenzen eingeschränkt werden. Dadurch würden nur bestimmte Datensätze exportiert und wieder importiert werden. Weiterhin sollte man daran denken die vorhandenen Auswertungsszenarien mit DbRep-Devices bzw. SVG-Diagrammen usw. auch auf die neue Datanbank umzustellen.

 
=== Inhalte einer primären Datenbank in eine andere Standby-Datenbank übertragen (syncStandby) ===

==== Zweck ====

Mit dem Export/Import Verfahren kann man, wie oben beschrieben, Daten zwischen verschiedenen Datenbanken austauschen. Mit dem Befehl "syncStandby" ist es aber mit relativ wenig Aufwand möglich, ein regelmäßig automatisch laufendes Übertragungsverfahren zwischen zwei Datenbanken zu etablieren.

Im vorliegenden Beispiel werden Datenbanken des gleichen Typs verwendet. Das Verfahren ist aber auch zwischen Datenbanken unterschiedlichen Typs anwendbar.

Anwendungsfälle dafür sind zum Beispiel:

* die Einrichtung eines Archivsystems
* die längerfristge Datenhaltung von Datensätzen eines bestimmten Devices/Readings in einer weiteren Datenbank um sie dort für umfangreiche Auswertungen zu nutzen (z.B. Daten einer PV-Anlage)
* Wechsel des Datenbanksystems, z.B. von SQLite zu MySQL/MariaDB
* säubern der Quelldaten von doppelten Datensätzen und nicht mehr benötigten Daten, Weiternutzung der aufgebauten Standbydatenbank als primäre Datenbank nach der Syncronisierung

Für das hier gezeigte Beispielszenario sollen Daten einer MariaDB-Quelldatenbank in einer andere MariaDB-Datenbank regelmäßig übertragen werden. Auf der Quelldatenbank werden die Daten aber nicht gelöscht, d.h. es entstehen zwei Datenbanken mit gleicher Datenbasis.

* Quelldatenbank ist eine MariaDB "fhemtest1" mit der DbLog-Instanz "LogDB1"
* Zieldatenbank ist eine MariaDB "fhemtest" mit der DbLog-Instanz "LogStby"

 

==== Die Quelldatenbank ====

Im vorliegenden Beispiel sind die Quelldatenbank und die Standby-Datenbank vom gleichen Typ MariaDB. Das Verfahren funktioniert ebenso zwischen Datenbanken unterschiedlichen Typs, also z.B. zur Übertragung von SQLite Daten in eine MariaDB.

Die Quelldatenbank ist im normalen Kontext die produktive FHEM-Logdatenbank. D.h. sie ist bereits eingerichtet und läuft mit einem entsprechenden DbLog-Device.
Die hier verwendete Quelldatenbank heißt "fhemtest1". Die Definition des dazu gehörenden DbLog-Devices "LogDB1" sei der Vollständigkeit halber hier erwähnt, wird aber natürlich bei jedem Nutzer individuell aussehen:

<pre>
define LogDB1 DbLog ./fhemtest1maria10.conf .*:(?!done).*
attr LogDB1 DbLogInclude CacheUsage
attr LogDB1 DbLogSelectionMode Exclude/Include
attr LogDB1 DbLogType History
attr LogDB1 addStateEvent 0
attr LogDB1 asyncMode 1
attr LogDB1 bulkInsert 1
attr LogDB1 cacheEvents 2
attr LogDB1 cacheLimit 2000
attr LogDB1 dbSchema fhemtest1
attr LogDB1 devStateIcon .*active:10px-kreis-gelb connected:10px-kreis-gruen .*disconnect:10px-kreis-rot
attr LogDB1 disable 0
attr LogDB1 room DbLog
attr LogDB1 showproctime 1
attr LogDB1 syncInterval 120
attr LogDB1 useCharfilter 1
attr LogDB1 verbose 2
</pre>

 

==== Die Standby Datenbank ====

Die Standby Datenbank ist das Synchronisationsziel.
Die Erstellung der Datenbank und die nachfolgende Definition des dazu gehörigen DbLog-Devices erfolgt weitgehend wie für eine "normale" Log-Datenbank wie in der Commandref beschrieben mit geringfügigen Anpassungen.

; 1. Anlegen der DB und Tabellen: wie in diesem [https://svn.fhem.de/trac/browser/trunk/fhem/contrib/dblog Link] hinterlegt, erfolgt die Erstellung mit den Befehlen für MySQL:
::: CREATE DATABASE `fhemtest` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
::: CREATE USER 'fhemuser'@'%' IDENTIFIED BY 'fhempassword';
::: CREATE TABLE `fhemtest`.`history` (TIMESTAMP TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
::: ALTER TABLE `fhemtest`.`history` ADD PRIMARY KEY(TIMESTAMP, DEVICE, READING);
::: CREATE TABLE `fhemtest`.`current` (TIMESTAMP TIMESTAMP, DEVICE varchar(64), TYPE varchar(64), EVENT varchar(512), READING varchar(64), VALUE varchar(128), UNIT varchar(32));
::: GRANT SELECT, INSERT, DELETE, UPDATE ON `fhemtest`.* TO 'fhemuser'@'%';

Es wird zusätzlich zu der normalen Erstellung der history-Tabelle ein primary Key für die Tabelle erstellt. Dieser Key verhindert dass Duplikate in der Tabelle erstellt werden und erleichtert dadurch sehr das Verfahren der Datenübertragung in der Folge.

[[Datei:stb1.PNG|right|thumb|300px|DbLog-Device für Standby-Datenbank]]
; 2. Erstellung der Konfigurationsdatei und Definition des DbLog-Devices für die Standby-Datenbank: Die Konfigurationsdatei (mariastby.conf) beinhaltet die Verbindunginformationen für das DbLog-Device und wird genau wie in der DbLog-Commandref beschrieben angelegt. Das DbLog-Device für die Standby-Datenbank wird nur für die nachfolgende Definition des benötigten DbRep-Devices gebraucht und wird so definiert, dass keinerlei Events geloggt werden. Das kann auf verschiedenen Wegen erreicht werden. Im Beispiel wird der Regex im DEF entsprechend aufgebaut.
::: define LogStby DbLog ./mariastby.conf aaaaaa:bbbbbb
::: attr LogStby DbLogType History
::: attr LogStby asyncMode 1
::: attr LogStby bulkInsert 1
::: attr LogStby cacheEvents 2
::: attr LogStby devStateIcon .*active:10px-kreis-gelb connected:10px-kreis-gruen .*disconnect:10px-kreis-rot
::: attr LogStby disable 0
::: attr LogStby room DbLog
::: attr LogStby showNotifyTime 1
::: attr LogStby showproctime 1
::: attr LogStby syncEvents 1

Die Erstellung der current-Tabelle ist für den vorgesehenen Zweck eigentlich nicht nötig, wird der Vollständigkeit halber mit dokumentiert.
Ist das DbLog-Device definiert und erfolgreich verbunden, ist dessen state "connected".

 

==== Definition des DbRep-Devices zur Synchronisation Quell- und Standby-Datenbank ====

Es existieren nun das DbLog Device "LogDB1" für die produktive Quelldatenbank und das DbLog Device "LogStby" für die Standby-Datenbank.
Für die Synchronisation wird ein DbRep-Device erstellt, welches mit dem DbLog-Device der '''produktiven Quelldatenbank''', also LogDB1, verbunden wird.
Wie üblich, wird im DEF der Name des entsprechenden DbLog-Devices angegeben, hier "LogDB1".

<pre>
defmod Rep.LogDB1.syncStandby DbRep LogDB1
attr Rep.LogDB1.syncStandby aggregation no
attr Rep.LogDB1.syncStandby event-on-update-reading state
attr Rep.LogDB1.syncStandby fastStart 1
attr Rep.LogDB1.syncStandby role Client
attr Rep.LogDB1.syncStandby room DbLog
attr Rep.LogDB1.syncStandby showproctime 1
attr Rep.LogDB1.syncStandby stateFormat { (ReadingsVal($name,"state", ""))." : SQL-Zeit: ".(ReadingsVal($name,"sql_processing_time", "")) }
attr Rep.LogDB1.syncStandby timeDiffToNow d:6
attr Rep.LogDB1.syncStandby verbose 3
</pre>

Mit den verschiedenen möglichen Zeitattributen ('''time.*''') und den Attributen '''device''' und '''reading''' wird abgegrenzt, welche Datensätze in die Standby-Datenbak übertragen werden sollen. In dem vorliegenden Beispiel werden mit jedem Synchronisationslauf alle in der DB vorhandenen Datensätze, die nicht älter als 6 Tage Tage sind, in die Standby-Datenbank übertragen.

'''Hinweis:''' 
Würde man einen solchen Lauf z.B. alle 4 Stunden durchführen, würden viele doppelte Datensätze in der Datenbank entstehen. Der bei der Tabellenerstellung für die history-Tabelle angelegte primary Key verhindert das !
[[Datei:stb2.PNG|right|thumb|300px|syncStandby gestartet]]

Ein Synchronisationslauf wird nun gestartet mit:

<pre>
set <DbRep-Name> syncStandby <DbLog-Device Standby>
</pre>

In dem vorliegenden Beispiel ist das:

<pre>
set Rep.LogDB1.syncStandby syncStandby LogStby
</pre>

[[Datei:stb3.PNG|right|thumb|300px|syncStandby erfolgreich ausgeführt]]
Der Fortschritt der Datenübertragung sowie die evtl. eingefügten Datensätze (number of lines inserted) ist im Logfile mit verbose 3 ersichtlich:

<pre>
2020.01.24 17:12:41.186 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 6177
2020.01.24 17:12:46.411 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 23957
2020.01.24 17:12:51.710 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 24048
2020.01.24 17:12:57.733 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 24092
2020.01.24 17:13:03.505 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 24059
2020.01.24 17:13:08.891 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 23969
2020.01.24 17:13:13.420 3: DbRep Rep.LogDB1.syncStandby - total lines transfered to standby database: 17871
2020.01.24 17:13:13.421 3: DbRep Rep.LogDB1.syncStandby - number of lines inserted into "LogStby": 104
</pre>

[[Datei:stb4.PNG|right|thumb|300px|nur Daten der Devices SMA_Energymeter,MySTP_5000 werden übertragen]]
Nach dem erfolgreichen Sync-Lauf wird die benötigte Laufzeit und die Anzahl der übertragenen Datensätze in Readings angezeigt.

Mit dem Attribut '''aggragation''' wird gesteuert, in welchen '''Zeitscheiben''' die Selektion der Daten aus der Quelldatenbank und die Übertragung ausgeführt wird. Im Standard ohne gesetztes aggregation-Attribut ist es ein Tag. Stehen genügend Ressourcen zur Verfügung, kann dieser Wert auch auf "week" oder "month" gesetzt werden. Der Wert "hour" zur Verkleinerung des Datenpaketes ist ebenfalls möglich.

Bei jedem Lauf wird die Anzahl der eingefügten Datensätze im Reading '''number_lines_inserted_Standby''' angezeigt.

Die zu übertragenden Daten können natürlich sehr granular bestimmt werden. Sollen zum Beispiel nur die Daten der Devices SMA_Energymeter und MySTP_5000 übertragen werden, wird das Attribut '''device''' entsprechend gesetzt:

attr Rep.LogDB1.syncStandby SMA_Energymeter,MySTP_5000

Weiterhin bietet das Attribut '''reading''' eine Eingrenzung auf die gewünschten Readings und mit dem Attribut '''valueFilter''' kann eine Eingrenzung nur auf bestimmte vorkommende Werte vorgenommen werden.

Der Erfolg der Synchronisationsläufe kann sehr einfach mit einem separaten DbRep-Device (mit dem '''fetchrows''' Kommando) oder dem Tool phpMyAdmin (nebenstehend) überprüft werden.

 

==== regelmäßige Ausführung der Synchronisation ====

Ein einfaches AT kann dazu dienen den Synchronisationslauf mit dem Device '''Rep.LogDB1.syncStandby''' regelmäßig alle x-Stunden/Minuten auszuführen.

<pre>
define At.Sync.Stby at +*04:00:00 set Rep.LogDB1.syncStandby syncStandby LogStby
attr At.Sync.Stby room DbLog
</pre>

 

=== Ermittlung und Darstellung der täglichen Energieerzeugung eines Wechselrichters ===

Gegeben sei dass die Energiedaten eines Wechselrichters (STP_5000) mit SMAUtils in Verbindung mit SBFSpot in die Datenbank geschrieben werden.
Neben vielen anderen Werten liefert SMAUtils die Tageserzeugung in kWh als Reading "etoday". Der Wert dieses Readings wird alle paar Minuten in der Datenbank gespeichert.

Zur Auswertung wird ein DbRep-Device angelegt wie unter [[#Definieren_eines_DbRep-Devices | Definieren eines DbRep-Devices]]) beschrieben (z.B. Rep.etoday.STP_5000).

[[Datei:Rep.STP_5000.configured.PNG|right|thumb|300px|Rep.STP_5000 konfiguriert]]

Es soll die täglich erzeugte Energiemenge beginnend ab dem 01.10.2016 0 Uhr bis zum 13. Oktober angezeigt werden.

<pre>
attr Rep.etoday.STP_5000 timestamp_begin 2016-10-01 00:00:00
attr Rep.etoday.STP_5000 timestamp_end 2016-10-13 23:59:59
</pre>

Da es sich um eine tägliche Aggregation handelt (es soll pro Auswertung der Tag von 00:00:00 bis 23:59:59 betrachtet werden) und die Hintergrundverarbeitungszeit dargestellt werden soll, wird eingestellt:

<pre>
attr Rep.etoday.STP_5000 aggregation day
attr Rep.etoday.STP_5000 showproctime 1
</pre>

Die Eingrenzung der auszuwertenden Devices und der dazu gehörigen Readings wird durch die entsprechenden Attribute gewährleistet.
Es soll nur das Device "STP_5000" mit dem Reading "etoday" berücksichtigt werden. Dazu stellen wir ein:

<pre>
attr Rep.etoday.STP_5000 reading etoday
attr Rep.etoday.STP_5000 device STP_5000
</pre>

DbRep ist nun grundsätzlich zur Auswertung konfiguriert (siehe Screenshot).

Zur Selektion und Berechnung von numerischen Daten stehen die Funktionen average-, max-, min-, sum- und diffValue zur Verfügung.
Bei den in diesem Beispiel verwendeten Daten handelt es sich um einen täglich neu erzeugten und über 24 Stunden stetig steigenden Wert.
Demnach ist für diese Art Daten die Funktion "maxValue" geeignet. Sie gibt den maximalen Wert des Readings im eingestellten Aggregationszeitraum (day) aus.

[[Datei:Rep.STP_5000.max.PNG|right|thumb|300px|Rep.STP_5000 maxValue]]

Die Berechnung wird ausgeführt durch:

<pre>
set Rep.etoday.STP_5000 maxValue
</pre>

Danach kurzer Zeit ist die Berechnung erfolgt (state=done in DeviceOverview). Nach einem Browserrefresh in der Detailansicht sind die erzeugten Readings sichtbar.

Jedes Reading hat einen bestimmten Aufbau. Die Funktion "maxValue" erzeugt Readings folgenden Aufbaus.

<pre>
2016-10-07_18-19-03__STP_5000__etoday__MAX__2016-10-07
</pre>

Zunächst wird der Timestring "2016-10-07_18-19-03" ausgegeben der in diesem Kontext den höchsten (d.h. letzten) Wert von "etotal" an dem Tag markiert.
Bei dem Wechselrichter ist es damit auch der Zeitpunkt zu dem die Energieerzeugung eingestellt wurde (in dem Fall 07.10.2016 um 18:19:03).

'''Anmerkung:''' Die Notation des Timestrings wurde so gewählt, um die Regeln für in Readings erlaubte Zeichen einzuhalten. Wenn keine auswertbaren Daten vorliegen und berechnet werden konnten, werden Readings mit "-" ausgegeben. Im Beispiel sind es die Tagesaggregate 10.10.-13.10. da diese Tage in der Zukunft liegen.

Danach folgt im Reading die Angabe des Devices (STP_5000), des augewerteten Readings (etoday) und der Funktion die dieses Ergebnis ermittelt hat (MAX für maxValue).
Die letzte Angabe, hier "2016-10-07" definiert den Auswertungszeitraum. In dem Beispiel ist es der 07.10.2016. Würde die Berechnung mit aggregation=week durchgeführt werden, würde man als an dieser Stelle den Auswertungszeitraum "week_39" erhalten, also die Kalenderwoche 39.

Um die Auswertungsergebniss etwas benutzerfreundlicher zu gestalten, steht das Attribut "readingNameMap" zur Verfügung. [[Datei:Rep.STP_5000.max.namemap.PNG|right|thumb|300px|Rep.STP_5000 maxValue mit readingNameMap]]
Im Beispiel setzen wir es auf:

<pre>
attr Rep.etoday.STP_5000 readingNameMap Tageserzeugung_kWh
</pre>

Ein erneuter maxValue-Lauf erzeugt Readings des folgenden Aufbaus:

<pre>
2016-10-01_18-03-13__Tageserzeugung_kWh__2016-10-01 4.9870
</pre>

 

=== (regelmäßiges) Löschen von Datenbanksätzen ===

Dieses DbRep-Device dient dazu einmalig oder verbunden mit einem AT-Device Einträge aus einer Datenbank zu löschen.
Zunächst wird das Device wie im Abschnitt [[#Definieren_eines_DbRep-Devices | "Definieren eines DbRep-Devices"]] beschrieben definiert.
Dadurch wird das DbRep-Device mit einem DbLog-Device assoziiert und mit der Datenbank des DbLogs verbunden. Alle weiteren Operationen werden mit dieser Datenbank durchgeführt. In diesem Beispiel heißt das DbRep-Device "Rep.Del.DbShort" und das DbLog-Device "LogDBShort".

In diesem Beispiel sollen alle Datensätze gelöscht werden die älter als 180 Tage sind. Die Löschfunktion des Moduls ist standardmäßig ausgeschaltet und muß per Attribut enabled werden.
Dazu werden die Attribute [[Datei:Rep.Del.DbShort.PNG|right|thumb|300px|Rep.Del.DbShort konfiguriert]]

<pre>
attr Rep.Del.DbShort timeOlderThan d:180
attr Rep.Del.DbShort allowDeletion 1
</pre>

gesetzt. Die Zeitangabe erfolgt in Sekunden.

Insbesondere bei SQLite sollte während des Löschens kein paralleler Schreibprozess in Form des normalen Eventloggings stattfinden. MySQL/MariaDB kann es durchaus parallel verarbeiten. Um einen parallelen Zugriff durch DbLog-Loggging zu verhindern, kann das Logging vor der Löschung geschlossen und danach wieder geöffnet werden.
Dafür werden die Attribute mit z.B. diesen Werten gesetzt:

<pre>
attr Rep.Del.DbShort executeBeforeProc set LogDBShort reopen 7200
attr Rep.Del.DbShort executeAfterProc set LogDBShort reopen
</pre>

Dabei ist "LogDBShort" das mit dem DbRep-Device assoziierte DbLog-Device.

Der Löschvorgang wird mit

<pre>
set Rep.Del.DbShort delEntries
</pre>

gestartet. Nach Abschluß der Datenlöschung wird die Anzahl der deleted rows als Reading ausgegeben und auch im Log mit verbose=3 geschrieben.

Müssen sehr viele Datensätze gelöscht werden, könnte nach 86400 Sekunden der Standardtimeout erreicht werden und der Vorgang mit "error" enden.
In diesem Fall ist der timeout mit dem Attribut:

<pre>
attr Rep.Del.DbShort timeout <timeout in Sekunden>
</pre>

entsprechend angepasst werden.

Ein fhem.cfg Eintrag für das beschriebene Beispieldevice sieht folgendermaßen aus:

<pre>
define Rep.Del.DbShort DbRep LogDBShort
attr Rep.Del.DbShort allowDeletion 1
attr Rep.Del.DbShort comment löschen aller Einträge in LogDBShort älter als 180 Tage
attr Rep.Del.DbShort devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.Del.DbShort event-on-update-reading state
attr Rep.Del.DbShort room DbLog
attr Rep.Del.DbShort timeOlderThan 15552000
</pre>

Die Löschung der relevanten Datensätze kann weiterhin über Attribute "device" bzw. "reading" kann selektiv auf bestimmte Device- und/oder Readingloggings beschränkt werden. Wird keine Zeitbeschränkung (z.B. durch "timeOlderThan") vorgenommen, erfolgt die Löschung aller Datensätze der durch "device" bzw. "reading" spezifizierten Datenbankinhalte.

Als Argument der Attribute "device" bzw. "reading" kann SQL-Wildcard "%" verwendet werden.

<pre>
% substituiert ein oder mehrere Zeichen
_ Platzhalter für ein einzelnes Zeichen
</pre>

Beispiel:

<pre>
attr Rep.Del.DbShort device %5000
</pre>

Mit dieser Spezifikation werden alle Devices gelöscht die auf "5000" enden, also z.B. STP_5000 und MySTP_5000.
(siehe auch Attribut "reading" in der {{Link2CmdRef|Anker=DbRepattr|Lang=de|Label=Commandref}}).

Ein einfaches AT kann dazu dienen den Löschjob über das Device Rep.Del.DbShort regelmäßig alle x-Stunden/Minuten auszuführen. Dadurch werden nicht mehr benötigte Datenbankeinträge automatisiert und nicht FHEM blockierend im Hintergrund entfernt.

<pre>
define At.Del.DbShort at +*23:45:00 set Rep.Del.DbShort delEntries
attr At.Del.DbShort room DbLog
</pre>

==== erweiterte Anwendung von Selektionsbedingungen zur Löschung ====

Wie bei allen selektiven Funktionen im DbRep kann auch bei der Löschfunktion über die Attribute '''device''' und '''reading''' eine Beschränkung der zu löschenden Datensätze erfolgen. D.h. es werden nur Datensätze gelöscht, wenn die Selektionskriterien dieser Attribute erfüllt sind.

Im Attribut '''device''' können einzelne Geräte, Geräte-Spezifikationen ({{Link2CmdRef|Anker=devspec|Lang=de|Label=devspec}}) sowie Geräte mit Wildcards angegeben werden.
Ist eine devspec angegeben, werden die Devicenamen vor der Selektion aus der Geräte-Spezifikationen und den aktuell in FHEM vorhandenen Devices aufgelöst sofern möglich.
Wird dem Device bzw. der Device-Liste oder Geräte-Spezifikation ein "EXCLUDE=" vorangestellt, werden diese Devices von der Selektion und damit von dem Löschvorgang ausgeschlossen.

<pre>
attr <name> device TYPE=DbRep # es werden nur Datensätze der Geräte vom Modul-Typ "DbRep"
eingeschlossen
attr <name> device MySTP_5000 # nur Datensätze des Gerätes "MySTP_5000" werden selektiert/gelöscht
attr <name> device SMA.*,MySTP.* # Daten von Geräten die mit "SMA" oder "MySTP" beginnen, werden
selektiert/gelöscht
attr <name> device SMA_Energymeter,MySTP_5000 # nur Daten der beiden angegebenen Geräten werden selektiert/gelöscht
attr <name> device %5000 # Daten von Geräten die mit "5000" enden werden in die Operation
eingeschlossen
attr <name> device TYPE=SSCam EXCLUDE=SDS1_SVS # es werden Datensätze der Geräte vom Modul-Typ "SSCam" eingeschlossen,
aber das Gerät "SDS1_SVS" (auch vom Typ SSCam) wird ausgeschlosssen
attr <name> device EXCLUDE=SDS1_SVS # Datensätze aller Geräte mit Ausnahme des Gerätes "SDS1_SVS" werden
selektiert/gelöscht
attr <name> device EXCLUDE=TYPE=SSCam # Datensätze aller Geräte mit Ausnahme der Geräte vom Typ "SSCam" werden
selektiert/gelöscht
</pre>

Ähnlich erfolgt die Abgrenzung der DB-Selektionen auf ein bestimmtes oder mehrere Readings sowie exkludieren von Readings. Mehrere Readings werden als Komma separierte Liste angegeben. Es können SQL Wildcard (%) verwendet werden, aber '''keine Perl-Regex'''.
Wird dem Reading bzw. der Reading-Liste ein "EXCLUDE=" vorangestellt, werden diese Readings von der Selektion ausgeschlossen.

<pre>
attr <name> reading etotal # Datensätze mit dem Reading "etotal" werden eingeschlossen
attr <name> reading et% # Datensätze deren Reading mit "et" beginnt werden
eingeschlossen
attr <name> reading etotal,etoday # Datensätze mit den Readings "etotal" und "etoday" werden
in die Selektion eingeschlossen
attr <name> reading eto%,Einspeisung EXCLUDE=etoday # Datensätze mit Readings beginnend mit "eto" sowie das
Reading "Einspeisung" werden selektiert, aber das Reading
"etoday" wiederum ausgeschlossen
attr <name> reading etotal,etoday,Ein% EXCLUDE=%Wirkleistung # Datensätze mit Readings beginnend mit "Ein" sowie die
Readings "etotal" und "etoday" werden selektiert, wobei
Readings, die auf "Wirkleistung" enden, von der Löschung
ausgeschlossen werden
</pre>

Natürlich werden die Selektionsbedingungen durch eventuell gesetzte Zeiteingrenzungen mit den time*- Attributen ergänzt.
Die time*- Attribute sind mehrere im DbRep vorhandene Attribute, die alle mit "time" beginnen, z.B. timeOlderThan.

=== Auffinden von alten Devicenamen in der DB und versenden/loggen einer Negativliste ===

Wenn eine Datenbank längere Zeit gelaufen ist, Devices in FHEM hinzugefügt, geändert oder gelöscht wurden oder auch das DEF des DbLog-Devices angepasst wurde, befinden sich aller Wahrscheinlichkeit nach nicht mehr gewünschte/gebrauchte Datensätze von nicht mehr bestehenden Devices in der Datenbank.

Dieses Beispiel soll einen Weg zeigen, wie man mit Hilfe der DbRep-sqlCmd Funktion (ab Version 4.14.0) alle in der DB enthältenen Devicenamen ermitteln und mit einer Positivliste vergleichen kann.
Die Negativliste der nicht gewünschten Devices wird im Logfile ausgegeben bzw. mit TelegramBot versendet.

Zunächst wird das Device wieder wie im Abschnitt [[#Definieren_eines_DbRep-Devices | "Definieren eines DbRep-Devices"]] beschrieben definiert.
Dadurch wird das DbRep-Device mit einem DbLog-Device assoziiert und mit der Datenbank des DbLog-Device verbunden. In diesem Beispiel heißt das DbRep-Device "Report".

Nach der Definition setzen wir die Attribute:

<pre>
attr Report event-on-update-reading state
attr Report sqlResultFormat separated
</pre>

Es werden nun nur noch Events für "state" generiert. Das Attribut "sqlResultFormat = separated" bewirkt, dass das Ergebnis des SQL-Statements zeilenweise in Einzelreadings zur Verfügung gestellt wird.

Nun kann getestet werden, ob die Abfrage grundsätzlich funktioniert. Dazu wird das benutzerspezifische Kommando "sqlCmd" verwendet.

<pre>
set Report sqlCmd select device, count(*) from history group by DEVICE;
</pre>

Es sollte nun eine entsprechende Anzahl von Readings erzeugt werden (Browserrefresh), die als Wert eine Kombination aus <Device>|<Anzahl Datensätze in DB> enthalten wie im nebenstehenden Screenshot ersichtlich.

[[Datei:sqlCmd.PNG|right|thumb|300px|sqlCmd ausgeführt]]

Wenn das Ergebnis wie gewünscht vorliegt, wird nun die Benutzerschnittstelle aktiviert.

<pre>
attr Report userExitFn NaDevs .*:.*
</pre>

"NaDevs" ist die Funktion in 99_myUtils.pm die aufgerufen werden soll. Die Angabe des Regex ".*:.*" ist optional. Nähere Informationen zur Funktionsweise sind in der {{Link2CmdRef|Lang=de|Anker=DbRep}} zu finden.

Die "Positivliste" der in der Datenbank erlaubten Devices wird für das Beispiel in dem Attribut "comment" für den späteren Vergleich als String angegeben. Es ist natürlich auch z.B. eine Ableitung der im DEF-Regex des zugeordneten DbLog-Devices enthaltenen Device-Definitionen vorstellbar, sodass immer der aktuelle Stand dieser Definition als Grundlage für den Vergleich herangezogen wird.

<pre>
attr Report comment (sysmon|MyWetter|SMA_Energymeter|STP_5000|Cam.*)
</pre>

Somit werden die Devices "sysmon", "MyWetter", "SMA_Energymeter", "STP_5000" und alle Cam-Devices als in der DB erlaubt definiert.
Alle anderen gefundenen Devices sollen in einer Negativliste aufgeführt werden.

Im weiteren Schritt wird die aufzurufende Funktion in der vorhandenen 99_myUtils.pm ergänzt.

<syntaxhighlight lang="perl">
############################################################################
# $Id: myUtilsTemplate.pm 7570 2015-01-14 18:31:44Z rudolfkoenig $
#
# Save this file as 99_myUtils.pm, and create your own functions in the new
# file. They are then available in every Perl expression.

package main;

use strict;
use warnings;

sub
myUtils_Initialize($$)
{
my ($hash) = @_;
}

# Enter you functions below _this_ line.

my @dna;

...

######################################################
######## Not allowed Devs in DB ermitteln
######## UserExitFn in DbRep
######################################################
sub NaDevs {
my ($name,$reading,$value) = @_;
my $hash = $defs{$name};

# DB Namen ermitteln
my $dbconn = $hash->{dbloghash}{dbconn};
my $db = (split("=",(split(";",$dbconn))[0]))[1];

# Liste der erlaubten Devices aus Attribut "comment" lesen
my $adevs = AttrVal($name, "comment","-");

if($reading eq "state" && $value eq "running") {
# der Select wurde gestartet
Log3 $name, 1, "UserExitFn called by $name - new Select has been startet. Allowed devices in database are: $adevs";
@dna=();
return;
}

my $d = (split("\\|",$value))[0];

# das Selektionsergebnis bewerten und ggf. dem Ergebnisarray hinzufügen
if ( $reading =~ m/SqlResultRow.*/ && $d !~ m/$adevs/) {
push(@dna,$d."\n")
}

if ($reading eq "state" && $value eq "done") {
# Ergebnis versenden bzw. loggen
Log3 $name, 1, "UserExitFn called by $name - Devices not allowd found in $db: @dna";
fhem("set teleBot message Devices are not allowed found in $db: \n @dna");
}

return;
}

....
1;
</syntaxhighlight>

Die Schnittstelle übergibt der aufgerufenen Funktion den Namen des DbRep-Devices, den Namen des erstellten Readings und dessen Wert.
Der Aufruf erfolgt nach jeder Readingserstellung. Die Schnittstelle arbeitet OHNE Eventgenerierung bzw. benötigt keine Events.
Über den Namen des DbRep-Devices kann auf dessen Hash zugegriffen werden bzw. über $hash->{dbloghash}{...} ebenfalls auf den Hash des angeschlossenen DbLog-Devices.

In der Funktion "NaDevs" wird der Device-Teilstring des erzeugten Readings mit dem Wertevorrat aus dem "comment"-Attribut verglichen und bei einem negativen Ergebnis der Negativliste @dna hinzugefügt.

Nach Abschluss der Operation (signalisiert durch Reading "state = done") wird die erzeugte Liste im Logfile ausgegeben bzw. ein TelgramBot-Device versendet.

=== Größe der FHEM-Datenbank ermitteln ===

Zunächst wird das Device wie im Abschnitt [[#Definieren_eines_DbRep-Devices | "Definieren eines DbRep-Devices"]] beschrieben definiert.
Dadurch wird das DbRep-Device mit einem DbLog-Device assoziiert und mit der Datenbank des DbLogs verbunden. Alle weiteren Operationen werden mit dieser Datenbank durchgeführt. In diesem Beispiel heißt das DbRep-Device "Rep.Fhem.Size".

Um die Größe der Datenbank beziehungsweise der Tabellen "history" und "current" zu ermitteln steht das Kommando:
[[Datei:tableinfo.PNG|right|thumb|300px|get Rep.Fhem.Size tableinfo]]
<pre>
get Rep.Fhem.Size tableinfo (MySQL, PostgreSQL)
get Rep.Fhem.Size svrinfo (SQLite)
</pre>

zur Verfügung.

Mit diesem Befehl werden sehr viele Informationen bezüglich der Tabellen des FHEM-Schemas (MySQL) als Readings ausgegeben.

Um nur die relevanten bzw. interessierenden Selektionsergebnisse auszugeben, kann mit dem Attribut showTableInfo (MySQL, PostgreSQL) bzw. showSvrInfo (SQLite) eine kommaseparierte Liste der relevanten Tabellen angegeben werden.

<pre>
attr Rep.Fhem.Size showTableInfo %history%,%current% (MySQL, PostgreSQL)
</pre>

So wie in diesem Beispiel gesetzt, werden nur Informationen der Tabellen "history" und "current" ausgegeben.
Diese Ausgabe ich bereits recht übersichtlich, kann aber durch die Verwendung des Attributs suppressReading
weiter eingegrenzt werden.

Beispiele:

<pre>
attr Rep.Fhem.Size suppressReading ^(?!.*INFO_history.data_index_length_MB).*$
attr Rep.Fhem.Size suppressReading ^(?!.*(INFO_history.data_index_length_MB)|(state)).*$
attr Rep.Fhem.Size suppressReading ^(?!.*(INFO_history.data_index_length_MB)|(background_processing_time)|(state)).*$
</pre>

Mit diesen Attributwerten wird nur das Reading "INFO_history.data_index_length_MB" oder aber "INFO_history.data_index_length_MB"
und "state" bzw. "INFO_history.data_index_length_MB", "state" und "background_processing_time" dargestellt.

Die Datenbankgröße (MB) ist je nach DB-Typ in den Readings:

<pre>
INFO_current.data_index_lenth_MB
INFO_history.data_index_lenth_MB
SQLITE_FILE_SIZE_MB
</pre>

enhalten.

Wird z.B. über ein AT dieser Befehl regelmäßig durch Rep.Fhem.Size ausgeführt und die Ergebnisse wiederum in DbLog gespeichert kann die Größenentwicklung der Datenbank mittels SVG-Diagrammen dargestellt werden. [[Datei:tableinfo_SVG.PNG|left|thumb|300px|get Rep.Fhem.Size tableinfo]]

 
=== Readingwerte von DbRep in ein anderes Device übertragen ===

Um Readings aus DbRep in einen Dummy zu übertragen, können verschiedene Verfahren angewendet werden. Allen Verfahren ist gemeinsam, dass sie auf die Arbeitsweise der Funktionen von DbRep Rücksicht nehmen. Alle Funktionen von DbRep arbeiten, von Ausnahmen abgesehen, asynchron (non-blocking). Das hat den Vorteil, dass die Datenbankverarbeitungszeit bzw. eine Nichtverfügbarkeit der DB nicht hemmend auf FHEM wirkt, hat andererseits aber den Nachteil, dass die Ergebnisse einer Funktion nicht direkt nach dem Funktionsaufruf zur Verfügung stehen und somit nicht trivial innerhalb der FHEM-Hauptschleife weiterverarbeitet werden können.

 
==== Werte automatisch durch DbRep übertragen lassen (ab Version 8.40.0) ====

Ab DbRep Version 8.40.0 gibt es das Attribut '''autoForward''' mit dem eine integrierte Übertragung der DbRep-Ergebnissreadings in andere Devices (z.B. Dummy) eingerichtet werden kann. Diese Variante wird hier beschrieben.

Die weiteren manuellen Varianten werden in den nachfolgenden Abschnitten behandelt.

Um die integrierte Reading-Weiterleitung zu aktivieren wird des Attribut autoForward nach folgender Systematik gesetzt:
[[Datei:aforw1.PNG|right|thumb|300px|Übertragung aller Readings nach Dum.Rep.all]]
<pre>
{
"<source-reading> => "<destination device> [=> <destination-reading>]",
"<source-reading> => "<destination device> [=> <destination-reading>]",
...
}
</pre>
[[Datei:aforw2.PNG|right|thumb|300px|Übertragung Readings mit "SUM" nach Dum.Rep.Sum]]
In der Spezifikation von '''<source-reading>''' können Wildcards (.*) verwendet werden um nur eine Auswahl der erzeugten Readings an das Zieldevice '''<destination device>''' weiterzuleiten. Ist der optionale Zusatz '''<destination-reading>''' angegeben, erfolgt die Speicherung der übertragenen Readings im Zieldevice mit dem angegebenen Namen. 
Der angegebene Readingname muss den Regularien zur Namensgebung von Readings genügen. Eventuell vorhandene nicht erlaubte Zeichen werden durch "_" ersetzt.

Fehlt der Zusatz <destination-reading>, werden die in DbRep erzeugten Readings 1:1 in das Zieldevice übertragen.

'''Beispiel:'''

<pre>
attr DbRepDev autoForward {
".*" => "Dum.Rep.All",
".*AVGAM.*" => "Dum.Rep => average",
".*SUM.*" => "Dum.Rep.Sum => summary",
}
</pre>

Die Spezifikation erfüllt folgende Ziele:

# alle Readings werden zum Device "Dum.Rep.All" übertragen, der ursprüngliche Readingname bleibt im Ziel erhalten (Screenshot 1)
# Readings mit "AVGAM" im Namen werden zum Device "Dum.Rep" in das Reading "average" übertragen
# Readings mit "SUM" im Namen werden zum Device "Dum.Rep.Sum" in das Reading "summary" übertragen (Screenshot 2)

 
==== Werte mittels Event übetragen ====

Es sollen zum Beispiel die erzeugten Readings aus einem DbRep-Device in einen Dummy übetragen werden, die den Term "Grid" im Wortstamm tragen.

Ein Reading-Name der fetchrows-Funktion in DbRep ist immer nach folgendem Schema aufgebaut:

<Datum>_<Zeit>__<Unique-Index>__<Device>__<Reading>__<Dopplerindex>
z.B.: 2018-10-14_18-30-25__1__MyWetter__humidity

Datum und Zeit entsprechen dem Timestamp des gespeicherten Events in der Datenbank. Der Unique-Index identifiziert eventuell vorhandene Doubletten in der DB und der Dopplerindex ist ein Hilfsmittel, Datensätze die sich allein durch den Value-Wert unterscheiden, auch als unterschiedliche Readings erstellen zu können. Dieser Index wird nur bei Bedarf erstellt.

Im folgenden Beispiel werden alle erzeugten Readings mit "Grid" im Namen des DbRep-Devices "Rep.SMAEM" in den Dummy übertragen und heißen dann genauso. Zunächst wird der Dummy angelegt.

<pre>
define Dum.Rep dummy
attr Dum.Rep room DbLog
</pre>

Mit dem nachfolgend angelegten Notify wird auf die z.B. von fetchrows erzeugten Events reagiert, der Event entsprechend gesplittet und verarbeitet in den Dummy übertragen.

<pre>
define N.Dum.Rep notify Rep.SMAEM:(\d).*Grid.* { fhem "setreading Dum.Rep ".(split(":",$EVTPART0))[0]." $EVTPART1"}
attr N.Dum.Rep room DbLog
</pre>

Soll im Dummy ein Reading mit eigenem Namen gefüllt werden, sieht das Notify z.B. so aus:

<pre>
define N.Dum.Rep notify Rep.SMAEM:(\d).*Grid.* { fhem "setreading Dum.Rep DeinReading"." $EVTPART1"}
</pre>

==== Werte mittels Funktion DbReadingsVal übertragen ====

Sobald ein DbRep-Device definiert ist, wird die Funktion DbReadingsVal zur Verfügung gestellt. Mit dieser Funktion läßt sich, ähnlich dem allgemeinen ReadingsVal, der Wert eines Readings aus der Datenbank abrufen. Die Befehlssyntax ist:

DbReadingsVal("<name>","<device:reading>","<timestamp>","<default>")

Mit dieser Funktion kann ein Device/Reading-Wert aus der Datenbank gelesen und in einen Dummy gesetzt werden. "Name" ist dabei das abzufragende DbRep-Device.
Der Timestamp muss nicht genau bekannt sein. Es wird der zeitlich zu <timestamp> passendste Readingwert zurück geliefert, falls kein Wert exakt zu dem angegebenen Zeitpunkt geloggt wurde.
Um den aktuellsten in der Datenbank gespeicherten Wert eines Readings abzurufen, kann als Timestamp die aktuelle Zeit entsprechend formatiert verwendet werden.

Es soll z.B. der aktuellste Datenbankwert des Readings "etoday" vom Device "MySTP_5000" ausgelesen und im Dummy "Dum.Rep" als Reading "EnergyToday" gespeichert werden. Das beteilgte DbRep-Device heißt "Rep.Energy".

Für die Formatierung des aktuellen Timestamps kann die FHEM-Funktion FmtDateTime verwendet werden, welcher der aktuelle UNIX-Timestamp übergeben wird:

FmtDateTime(time)

Der Datenabruf aus der Datenbank sieht dann folgendermaßen aus:

DbReadingsVal("Rep.Energy","MySTP_5000:etoday",FmtDateTime(time),"")

Mit dem Befehl setreading kann der abgerufene Wert in dem Dummy-Device gespeichert werden:

{ fhem "setreading Dum.Rep EnergyToday ".DbReadingsVal("Rep.Energy","MySTP_5000:etoday",FmtDateTime(time),"") }

Damit der Datenabruf regelmäßig erfolgt und immer der aktuellste Wert von "etoday" in den Dummy eingtragen wird, kann dieses AT verwendet werden:

<pre>
define set.Dum.Rep_EnergyToday at +*00:01:00 { fhem "setreading Dum.Rep EnergyToday ".DbReadingsVal("Rep.Energy","MySTP_5000:etoday",FmtDateTime(time),"") }
</pre>

Somit erfogt eine Aktualisierung des Readings "EnergyToday" im Dummy "Dum.Rep" jede Minute.
Es ist zu beachten, dass die Funktionsausführung von DbReadingsVal blockierend erfolgt. Sollte die Datenbank nicht verfügbar sein oder lange Antwortzeiten besitzen, hat dies negative Auswirkungen auf FHEM, was sich in Blockierungszuständen äußert.
Möchte man solche eventuell möglichen Zustände vermeiden, kann die Befehlsausführung in die 99_myUtils unter Verwendung von [[Blocking_Call | Blocking Call]] ausgelagert werden.

Diese non-blocking Variante der Verwendung von DbReadingsVal wird nachfolgend skizziert.
In der 99_myUtils wird dazu der nachfolgende Code eingefügt, der drei kleine Subroutinen enthält:

<syntaxhighlight lang="perl">
############################################################################################################
# DumRepEnergyToday (Reading mittels DbReadingsVal non-blocking setzen)
############################################################################################################
sub DumRepEnergyToday ($$$$$) {
# initiale Routine zum Aufruf von BlockingCall unter Berücksichtigung von "RUNNING_SET_READING"
my ($name,$device,$reading,$destdev,$destread) = @_;
my $hash = $defs{$name};

return if($hash->{HELPER}{RUNNING_SET_READING});
$hash->{HELPER}{RUNNING_SET_READING} = BlockingCall("DumRepEnergyTodayNbl", "$name|$device|$reading|$destdev|$destread", "DumRepEnergyTodayNblDone");

return;
}

sub DumRepEnergyTodayNbl($) {
# die eigentliche Routine in der die potentiell blockierende Funktion ausgeführt wird
my ($string) = @_;
my ($name,$device,$reading,$destdev,$destread) = split("\\|", $string);
my $hash = $defs{$name};

my $val = DbReadingsVal($name,"$device:$reading",FmtDateTime(time),"");
$val = encode_base64($val,"");

return "$name|$val|$destdev|$destread";
}

sub DumRepEnergyTodayNblDone($) {
# Rückkherfunktion zur Ergebnisauswertung und Löschen von "RUNNING_SET_READING"
my ($string) = @_;
my @a = split("\\|",$string);
my $hash = $defs{$a[0]};
my $name = $hash->{NAME};
my $val = decode_base64($a[1]);
my $destdev = $a[2];
my $destread = $a[3];

fhem "setreading $destdev $destread $val";
delete $hash->{HELPER}{RUNNING_SET_READING};

return;
}
</syntaxhighlight>

Der oben gezeigte Code stellt die einfachste Form der BlockingCall-Implementierung dar. Weitere Informationen dazu sind im weiter oben angegebenen Link zum BlockingCall-Wiki enthalten.

Um non-blocking Funktion aufzurufen, ist das bereits beschriebene AT-Device wie folgt zu ändern:

<pre>
define set.Dum.Rep_EnergyTodayNbl at +*00:01:00 { DumRepEnergyToday("Rep.Energy","MySTP_5000","etoday","Dum.Rep","EnergyToday") }
</pre>

Der aufgerufenen Funktion "DumRepEnergyToday" werden hierbei der Name des abzufragenden DbRep-Devices, der Name des auszuwertenden Devices, der Name des auszuwertenden Readings sowie das Ziel-Device und das Ziel-Reading als Argumente mitgegeben. Dieser Aufruf kann dadurch universell zum Abruf und Setzen verschiedener auszuwertender Device/Reading-Kombinationen verwendet werden.

=== Ein Userreading anlegen und für stateformat verwenden ===

Eine Besonderheit beim Modul DbRep besteht darin, dass sich die Namen der generierten Readings ändern können. Dadurch kann man für die Erstellung eines eigenen Userreading nicht einfach den Namen eines erstellten Readings, z.B. in der Funktion ReadingsVal, verwenden um dessen Wert zu ermitteln.

Eine Möglichkeit besteht darin eine Funktion in 99_myUtils anzulegen und mit dem Attribut "userExitFn" diese Funktion zu aktivieren/zu verwenden.

Für das Beispiel soll ein Reading "power_max" für den erreichten Maximalwert im Monat und der Timestamp des Maximalwertes aus einem Beispielreading "2018-06-01_13-23-02__STP_5000__total_pac__MAX__no_aggregation" (Name kann sich durch das jeweilige Datum ändern) extrahiert werden.

Zunächst wird die Funktion "calcpomax" in 99_myUtils angelegt.

<syntaxhighlight lang="perl">
############################################################################################################
######## power_max in DbRep erstellen
############################################################################################################
sub calcpomax {
my ($name,$reading,$value) = @_;
my $hash = $defs{$name};

if($reading =~ /^.*total_pac__MAX.*$/) {
$reading =~ /^(\d+)-(\d+)-(\d+)_(\d+)-(\d+)-(\d+)_.*$/;
my $pmts = "$3.$2.$1 $4:$5:$6";
my $fmtDateTime = FmtDateTime(gettimeofday());
setReadingsVal($hash,"power_max",$value,$fmtDateTime);
setReadingsVal($hash,"power_max_ts",$pmts,$fmtDateTime);
}
return;
}
</syntaxhighlight>

Wie in der Commandref zu {{Link2CmdRef|Anker=DbRep|Lang=de|Label=DbRep}} zu lesen ist, werden der im Attribut "userExitFn" hinterlegten Funktion jeweils der Name des aufrufenden Devices, das Reading und dessen Wert übergeben. Mit ein paar Zeilen Code wird der übergebene Readingsname auf das Vorhandensein des statischen Namensteils (total_pac__MAX) geprüft und dementsprechend der Readingname "power_max" mit dem Wert angelegt, wenn der Regex auf den Readingnamen matched.
Gleiches gilt für das Reading "power_max_ts", welches den Zeitpunkt des erreichten Maximalwertes enthalten soll.

Die Aktivierung der Schnittstelle erfolgt im DbRep-Device mit

<pre>
attr <name> userExitFn calcpomax .*:.*
</pre>

Mit jedem Lauf von

<pre>
set <name> maxvalue
</pre>

wird nun das neue Reading mit angelegt und kann z.B. in einem stateformat verwendet werden:
[[Datei:Rep.powmax.PNG|right|thumb|500px|]]

<pre>
attr <name> stateformat
{
if(ReadingsVal($name,"power_max",0)) {
(ReadingsVal($name,"power_max",0)*1000)." Watt (erreicht am ".ReadingsVal($name,"power_max_ts","").")";
} else {
ReadingsVal($name,"state","done");
}
}
</pre>

Nachfolgend noch die Definition des verwendeten DbRep-Devices für diese Auswertung:

<pre>
defmod Rep.total_pac.currmonth DbRep LogDB
attr Rep.total_pac.currmonth aggregation no
attr Rep.total_pac.currmonth alias Peak WR-Leistung aktueller Monat
attr Rep.total_pac.currmonth allowDeletion 0
attr Rep.total_pac.currmonth devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.total_pac.currmonth device STP_5000
attr Rep.total_pac.currmonth disable 0
attr Rep.total_pac.currmonth event-on-update-reading state
attr Rep.total_pac.currmonth group SMA Inverter
attr Rep.total_pac.currmonth reading total_pac
attr Rep.total_pac.currmonth room Energie
attr Rep.total_pac.currmonth showproctime 1
attr Rep.total_pac.currmonth stateFormat { \
if(ReadingsVal($name,"power_max",0)) {\
(ReadingsVal($name,"power_max",0)*1000)." Watt (erreicht am ".ReadingsVal($name,"power_max_ts","").")";;\
} else {\
ReadingsVal($name,"state","done");;\
}\
}
attr Rep.total_pac.currmonth timestamp_begin current_month_begin
attr Rep.total_pac.currmonth timestamp_end current_month_end
attr Rep.total_pac.currmonth userExitFn calcpomax .*:.*
attr Rep.total_pac.currmonth verbose 2
</pre>

 

=== datenbankgestützte Erstellung der Energiebilanz einer SMA PV-Anlage mit Überschußeinspeisung ===
[[datenbankgestützte Erstellung der Energiebilanz einer SMA PV-Anlage mit Überschußeinspeisung | Hier]] geht's zum Beitrag.

 
=== DbRep-Kommandos regelmäßig mit einem at-Device ausführen ===

Sollen DbRep-Kommandos regelmäßig zu bestimmten Zeiten bzw. Intervallen ausgeführt werden, kann ein at-Device (alternativ z.B. DOIF) dafür definiert und verwendet werden.

Als Beispiel soll die regelmäßige Ausführung des SQL-Statements

select device, count(*) from history group by DEVICE

über das Set-Kommando '''sqlCmd''' dienen.

Zunächst wird das DbRep-Device definiert welches zur Ausführung des Kommandos dienen soll.

<pre>
define Rep.LogDB.sqlResult DbRep LogDB
attr Rep.LogDB.sqlResult devStateIcon initialized:control_3dot_hor_s connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.LogDB.sqlResult event-on-update-reading state
attr Rep.LogDB.sqlResult fastStart 1
attr Rep.LogDB.sqlResult room Datenbank
attr Rep.LogDB.sqlResult showproctime 1
attr Rep.LogDB.sqlResult sqlResultFormat table
attr Rep.LogDB.sqlResult verbose 2
</pre>

Die Definition Syntax wurde bereits weiter oben erläutert. Das Attribut '''sqlResultFormat''' legt fest in welcher Art und Weise das Ergebnis präsentiert werden soll. Auch andere Formate wie JSON sind implementiert.

Um das oben angegbene SQL-Statement zum Beispiel alle 6 Stunden 20 Minuten auszuführen, dient die folgende at-Definition:

<pre>
define At.LogDB.sqlResult at +*06:20:00 set Rep.LogDB.sqlResult sqlCmd select device, count(*) from history group by DEVICE
attr At.LogDB.sqlResult icon clock
attr At.LogDB.sqlResult room Datenbank->Produktiv
</pre>

Weitere Informationen sind in der [https://fhem.de/commandref_DE.html#at at-CommandRef] beschrieben.

Natürlich sind alle verfügbaren DbRep Set/Get-Befehle über diesen Weg ausführbar.
Es wird empfohlen das definierte DbRep-Device nur für Auswertungsaufgaben zu verwenden die eine gleiche Attributierung des Devices verlangen.
Für weitere Aufgaben sollten weitere DbRep-Devices definiert und entsprechend eingestellt werden.

 

=== DbRep Chain - die Kommandokette ===

Für regelmäßig auszuführende Aufgaben erstellt man sich je ein separates DbRep-Device und setzt die Attribute wie es für die spezifische Aufgabe erforderlich ist.
Zu diesem Zweck kopiert man sich einfach ein vorhandenes DbRep-Device mit dem FHEM ''copy'' Kommando und passt es danach entsprechend an. Es können beliebig viele DbRep-Devices angelegt werden.

Häufig besteht der Wunsch, verschiedene Datenbankaktionen nacheinander ablaufen zu lassen, z.B. erst ''minValue writeToDB'' danach ''maxValue writeToDB'' sowie ''averageValue writeToDB'' nacheinander auszuführen.
Eine solche Verkettung kann durch die Nutzung des ''executeAfterProc'' Attributes erstellt werden.

Für das Beispiel werden 3 DbRep-Devices angelegt:

* Rep_Min
* Rep_Max
* Rep_Avg

Das erste Device (Rep_Min) soll für ''minValue writeToDB'' genutzt werden. In diesem Device wird das Attribut gesetzt:

attr Rep_Min executeAfterProc set Rep_Max maxValue writeToDB

Dieses Attribut zeigt auf das zweite Device (Rep_Max), welche für ''maxValue writeToDB'' verwendet werden soll.
In diesem Device wird wiederum das Attribut gesetzt:

attr Rep_Min executeAfterProc set Rep_Avg averageValue writeToDB

Die gesamte Chain startet mit einem at-Device, notify oder dergleichen mit dem Kommando:

set Rep_Min minValue writeToDB

'''Funktionsweise:''' 
Die Attribute executeBeforeProc und executeAfterProc führen jeweils das in ihnen hinterlegte FHEM-Kommando oder Perl-Funktion vor bzw. nach der Ausführung des gestarteten DbRep-Kommandos aus. 
In dem dargestellten Beispiel startet das at-Device mit

set Rep_Min minValue writeToDB

die Funktion ''minValue writeToDB'' im Device ''Rep_Min''. Wenn das DbRep ''Rep_Min'' mit seiner Aufgabe fertig ist, startet es automatisch über executeAfterProc das DbRep ''Rep_Max'' die Ausführung von '''maxValue writeToDB'''. Hat DbRep ''Rep_Max''seine Aufgabe beendet, startet es wiederum im letzten Device ''Rep_Avg'' das Kommando ''averageValue writeToDB''. 
Mit diesem Verfahren läuft immer nur ein Kommando der Reihe nach über die Datenbank.

Natürlich kann diese Chain beliebig erweitert werden, oder im ersten DbRep vor dem Start der Chain das angeschlossene DbLog-Device pausiert werden mit:

attr Rep_Min executeBeforeProc set <DbLog-Device> reopen 7200

Die Beendigung der Pause des DbLog kann das letzte DbRep ''Rep_Avg'' übernehmen durch Setzen des Attributes:

attr Rep_Avg executeAfterProc set <DbLog-Device> reopen

 
=== Abarbeitung einer sequentiellen Befehlskette mittels non-blocking sqlCmd-Kommandos ===

('''Hinweis:''' In der aktuellen DbRep-Version kann die seqientielle Kommandoabarbeitung über die [[#DbRep_Chain_-_die_Kommandokette|Chain-Funktionalität]] realisiert werden.)

Ein Vorteil von DbRep ist die nicht blockierende Arbeitsweise fast aller DbRep-Befehle (auf Ausnahmen wird in der Commandref hingewiesen).
Daraus ergibt sich aber auch das Merkmal, dass nach dem Funktionsaufruf nicht auf das Ergebnis gewartet wird und die FHEM-Schleife
unmittelbar nach dem Start des Befehls weiterläuft. Um mehrere voneinander abhängige Befehle, die eine festgelegte Reihenfolge erfüllen müssen, abzuarbeiten, kann die nachfolgend beschriebene Technik zur Kettenbildung angewendet werden. Diese Technik wird anhand einer einfachen Demo erläutert.

Das konstruierte Ziel der Kette ist folgendes:

* Es soll nacheinander der Insert eines Datensatzes durchgeführt, danach ein Select dieses Datensatzes, ein Update auf ein Feld und zuletzt ein delete dieses Datensatzes in dieser Reihenfolge ausgeführt werden

Demnach sich insgesamt vier SQL-Befehle nacheinander auszuführen (Insert, Select, Update, Delete).
Zunächst werden vier identische DbRep-Devices angelegt, die sich lediglich durch ihren Namen unterscheiden. Das wären die Devices:

<pre>
Rep.insert, Rep.select, Rep.update, Rep.delete
</pre>

Zur Anlage kann ein DbRep-Device als Vorlage erstellt und nachfolgend dreimal kopiert werden.

<pre>
define Rep.insert DbRep LogDB
attr Rep.insert allowDeletion 1
attr Rep.insert showproctime 1
attr Rep.insert userExitFn chain

copy Rep.insert Rep.select
copy Rep.insert Rep.update
copy Rep.insert Rep.delete
</pre>

Das wichtige Detail dieser Devices ist das gesetzte Attribut "userExitFn = chain". Dieses Attribut aktiviert eine Schnittstelle zum Aufruf von benutzereigenem Code nach dem Abschluß eines Datenbank-Calls (siehe Commandref).

Der benutzereigene Code wird nach folgendem Schema in die 99_myUtils.pm eingebaut:

<syntaxhighlight lang="perl">
#############################################################################################
# sqlCmd Commandchain zur sequentiellen Abarbeitung von non-blocking DbRep-Befehlen
#
# genutzte werden vier DbRep-Devices: Rep.insert, Rep.select, Rep.update, Rep.delete
#
#############################################################################################
sub chain {
my ($name,$reading,$value) = @_;
my $hash = $defs{$name};
my $device = "Testdevice";
my $model = "Testmodel";
my $rc;

if ($name eq "Rep.insert" && $reading eq "chainstart") {
# Start der 1. Operation (insert)
CommandSet(undef,"Rep.insert sqlCmd insert into history (DEVICE, TYPE, EVENT, READING, VALUE, UNIT)
values (\"$device\", \"$model\", \"definition\", \"DEF\", \"Hugo\", \"Emma\")");
Log3 $name, 1, "$name - Start chain with insert";
return;
}

if($reading eq "state" && $value eq "done") {
if ($name eq "Rep.insert") {
# Auswertung der 1. Operation (insert)
$rc = ReadingsVal($name, "SqlResultRow_1", "");
Log3 $name, 1, "$name - number of inserts: $rc";

# Start der 2. Operation (select)
CommandSet(undef,"Rep.select sqlCmd select VALUE from history where device=\"$device\" and READING=\"DEF\" LIMIT 1;");
}

if ($name eq "Rep.select") {
# Auswertung der 2. Operation (select)
$rc = ReadingsVal($name, "SqlResultRow_1", "");
Log3 $name, 1, "$name - return of select: $rc";

# Start der 3. Operation (update)
CommandSet(undef,"Rep.update sqlCmd update history set UNIT=\"neu\" where DEVICE=\"$device\";");
}

if ($name eq "Rep.update") {
# Auswertung der 3. Operation (update)
$rc = ReadingsVal($name, "SqlResultRow_1", "");
Log3 $name, 1, "$name - number of updates: $rc";

# Start der 4. Operation (delete)
CommandSet(undef,"Rep.delete sqlCmd delete from history where device = \"$device\" and UNIT = \"neu\";");
}

if ($name eq "Rep.delete") {
# Auswertung der 4. Operation (delete)
$rc = ReadingsVal($name, "SqlResultRow_1", "");
Log3 $name, 1, "$name - number of deletes: $rc";
}
}

return;
}
</syntaxhighlight>

Die gesamte Abarbeitung wird gestartet mit dem Aufruf:

<pre>
chain("Rep.insert", "chainstart")
</pre>

bzw. in der Kommandozeile im FHEMWEB mit:

<pre>
{chain("Rep.insert", "chainstart")}
</pre>

Nach dem initialen Aufruf des Insert wird die sub "chain" beendet und nach dem insert-Befehl durch das Device "Rep.insert" wieder aufgerufen. Dabei wird diese sub nach jedem erstellten Reading aufgerufen und dabei neben dem eigenen Devicenamen auch der Readingname sowie dessen Wert zur Auswertung übergeben.
Durch die if-Zweige wird bei jedem Durchlauf der richtige Entrypoint für den nachfolgenden Funktionsaufruf ermittelt und ausgeführt.

Nach der Abarbeitung aller vorgesehenen SQL-Statements ist die erfolgreiche Chainverkettung anhand der Ergebnisse im Logfile ersichtlich:

<pre>
2018.10.24 23:57:37.602 1: Rep.insert - Start chain with insert
2018.10.24 23:57:37.815 1: Rep.insert - number of inserts: 1
2018.10.24 23:57:37.901 1: Rep.select - return of select: Hugo
2018.10.24 23:57:38.033 1: Rep.update - number of updates: 1
2018.10.24 23:57:38.176 1: Rep.delete - number of deletes: 1
</pre>

=== Summe aller Einschaltzeiten eines Gerätes ===

[[Summe aller Einschaltzeiten eines Gerätes | Hier]] geht's zum Beitrag.

=== Eine Device spezifische Aufbewahrungszeit (Retention Time) in der Datenbank realisieren ===

In der DbLog Datenbank gespeicherte Daten müssen bzw. sollten regelmäßig gelöscht werden sofern sie nicht mehr für Auswertungen verwendet werden. Über DbRep Kommandos gibt es dafür viele Möglichkeiten.

Vorgestellt wird hier die Möglichkeit, bereits beim Logging des Events mittels Attribut eine Device spezifische Aufbewahrungszeit festzulegen. Diese Möglichkeit ist ab der DbLog Version 5.9.4 gegeben. Die einzelnen Schritte zur Umsetzung werden nachfolgend beschrieben.

* im global Device das userattr '''retentionPeriod''' definieren. Der Name des Attributes ist natürlich frei wählbar. Das Attribut steht in allen Devices zur Verfügung und bestimmt die Aufbewahrungszeit in Sekunden wenn im Device oder im DbLog Device gesetzt.
<pre>
attr global userattr retentionPeriod
</pre>

* Für die Speicherung des Verfallzeitpunktes in der Datenbank wird die Tabellenspalte EVENT in der Tabelle history verwendet. Normalerweise wird der komplette zu loggende Event in dieser Spalte gespeichert, was im Allgemeinen nicht benötigt wird. Dazu wird in dem relevanten DbLog Device das Attribut '''valueFn''' gesetzt um in jedem zu loggenden Datensatz die Spalte EVENT die spezifische Verfallszeit zu speichern:
<pre>
{
my $def = AttrVal ($NAME, 'retentionPeriod', 9999999999);
$EVENT = int(time) + AttrVal ($DEVICE, 'retentionPeriod', $def);
}
</pre>

* Im gleichen DbLog Device wird das Attribut '''retentionPeriod''' auf einen Default Wert gesetzt der gelten soll, wenn im zu loggenden Datensatz kein retentionPeriod-Attribut im Quellen-Device hinterlegt ist. Wenn kein retentionPeriod-Attribut im DbLog Device gesetzt ist, erfolgt mit dem Wert 'int(time) + 9999999999' de facto eine zeitlich unbegrenzte Speicherung.

<pre>
attr <DbLog> retentionPeriod 7776000 (Beispiel für Haltezeit von 90 Tagen = 7776000 Sekunden)
</pre>

[[Bild:Screenshot 2024-01-03 210126.png|right|thumb|400px|]]
* In jedem relevanten Device wird nun die gewünschte Aufbewahrungszeit in Sekunden gesetzt:
<pre>
attr <Device> retentionPeriod xxxxxxxxx
</pre>

Im Cache des DbLog Devices findet man jetzt in jedem Datensatz den Verfallszeitpunkt des Datensatzes. Er wird in der EVENT-Spalte der Tabelle gespeichert.

Vor den nächsten Schritten ist sicherzustellen, dass EVENT bei bereits vorhandenen Datensätzen auf einen passenden Verfallszeitpunkt upgedated werden.
Dazu eignet sich sqlCmd im DbRep oder ein SQL Editor deiner Wahl:

<pre>
UPDATE history SET TIMESTAMP=TIMESTAMP, EVENT="1704353074"; (setzt den Verfall auf 04.01.2024 08:24:34)
</pre>

Damit die Datenlöschungen über eine Auswertung von EVENT später performant ausgeführt werden, sollte ein ensprechender Index angelegt werden und der Datentyp von EVENT in Integer geändert werden. Beide SQL Statements können mit einem DbRep-Device mit gesetzten '''adminCredentials''' über "set ... sqlCmd" ausgeführt werden:

<pre>
CREATE INDEX Retention_Idx ON `history` (EVENT);
ALTER TABLE history MODIFY COLUMN EVENT INT(15);
</pre>

Die veränderte Spaltenbreite von EVENT wird im DbLog-Device nachgezogen und das Attribut '''colEvent''' gesetzt:

<pre>
attr <DbLog> colEvent 15
</pre>

Zur regelmäßigen Löschung der Datensätze mit einer abgelaufenen Aufbewahrungszeit dient ein at-Device in Verbindung mit einem DbRep-Device (z.B. Rep.fhemtest1) welches täglich abgelaufene Datensätze sucht und löscht.
Die Definition des at-Devices:

<pre>
define At.RetentionDel at *23:15:00 {
my $t = int(time);
fhem "set Rep.fhemtest1 sqlCmd delete from history where EVENT<'$t'";
}
</pre>

Das DbRep-Device benötigt keine besonderen Einstellungen außer einem gesetzten Attribut '''allowDeletion=1'''.

<pre>
define Rep.fhemtest1 DbRep <DbLog-Device>
attr Rep.fhemtest1 allowDeletion 1
attr Rep.fhemtest1 event-on-update-reading state
attr Rep.fhemtest1 room DbLog
attr Rep.fhemtest1 showproctime 1
</pre>

 

=== Welche Device/Reading-Kombinationen gibt es in der Datenbank ? ===
'''Hinweis:''' Im aktuellen DbRep-Release kann die nachfolgend beschriebene Auswertung alternativ durch die eingebauten Kommmandos:
set <DbRep-Device> sqlSpecial allDevCount
set <DbRep-Device> sqlSpecial allDevReadCount
ausgeführt werden.

Wenn eine Datenbank längere Zeit gelaufen ist und die zu loggenden Devices bzw. Readings immer mal wieder geändert wurden, wächst der Wunsch einen Überblick über die in der DB enthaltenen Devices/Reading-Kombinationen zu erhalten.
Dadurch können wiederum gezielt Auswertungen auf eine bestimmte Device/Reading-Kombination durchgeführt werden.

Um dieses Ziel zu erreichen, wird ein DbRep-Device erstellt welches für die Verwendung eines User-Command eingerichtet wird.
Je nach dem gewünschten Ergebnis wird eines der nachfolgenden SQL-Kommandos verwendet.

Selektion aller Device/Reading-Kombinationen in der Datenbank:
select device, reading, count(*) from history group by DEVICE, READING

Nur die geloggten Devices in der Datenbank reporten:
select device, count(*) from history group by DEVICE

Zur Einrichtung wird zunächst das DbRep-Device definiert:

define Rep.LogDB.sqlResult DbRep LogDB

Dabei ist "LogDB" '''nicht''' die Datenbank, sondern das DbLog-Device mit dem das DbRep-Device assoziiert und derüber mit der Datenbank verbunden wird !

Um die Ausgabe des späteren Ergebnisses zu formatieren wird das Attribut "sqlResultFormat" auf "table" gesetzt. Dadurch wird das Selektergebnis als Tabelle mit den Spalten Device, Reading und der Anzahl der enthaltenen Datensätze der jeweiligen Kombination erzeugt.

attr Rep.LogDB.sqlResult sqlResultFormat table

Natürlich kann auch ein anderes Ausgabeformat gewählt werden wenn gewünscht oder benötigt. Bei großen Ergebnismengen ist zur Erhöhung der Übersichtlichkeit das Attribut "sqlResultFormat = separated" wahrscheinlich eher geeignet.

Das Attribut stateFormat wird entsprechend gesetzt um nach einem erfolgten Selektionslauf die erzeugte Tabelle in der Raumansicht bzw. im DeviceOverview anzuzeigen:

<pre>
attr Rep.LogDB.sqlResult stateFormat { if (defined($defs{$name}{READINGS}{SqlResult})) {
ReadingsVal($name,"SqlResult",undef);
} else {
ReadingsVal($name,"state",undef);
}
}
</pre>

Damit ist das DbRep-Device vorbereitet und der Auswertungslauf kann gestartet werden mit:

set Rep.LogDB.sqlResult sqlCmd select device, reading, count(*) from history group by DEVICE, READING;

bzw. wenn nur die in der Datenbank enthaltenen Devices zu erhalten:

set Rep.LogDB.sqlResult sqlCmd select device, count(*) from history group by DEVICE;

[[Datei:sqlResult.PNG|right|thumb|600px|set Rep.LogDB.sqlResult sqlCmd select device, count(*) from history group by DEVICE;]]

Nebenstehender Screenshot zeigt das Ergebnis der Auswertung aller in der Datenbank enthalteten Devices und deren Anzahl von Datensätzen.

Zum leichteren Nachnutzung hier noch die Raw-Definition des fertigen DbRep-Devices:

<pre>
defmod Rep.LogDB.sqlResult DbRep LogDB
attr Rep.LogDB.sqlResult aggregation no
attr Rep.LogDB.sqlResult comment Device zum freien Report mit sqlCmd.\
- Auswahl von Statements -\
\
Device/Reading-Kombinationen in der Datenbank:\
select device, reading, count(*) from history group by DEVICE, READING\
\
geloggte Devices in der Datenbank:\
select device, count(*) from history group by DEVICE\

attr Rep.LogDB.sqlResult devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.LogDB.sqlResult disable 0
attr Rep.LogDB.sqlResult event-on-update-reading state
attr Rep.LogDB.sqlResult group Datenbankauswertungen
attr Rep.LogDB.sqlResult room DbLog
attr Rep.LogDB.sqlResult showproctime 1
attr Rep.LogDB.sqlResult sqlResultFormat table
attr Rep.LogDB.sqlResult stateFormat { if (defined($defs{$name}{READINGS}{SqlResult})) {\
ReadingsVal($name,"SqlResult",undef);;\
} else {\
ReadingsVal($name,"state",undef);;\
} \
}
attr Rep.LogDB.sqlResult timeout 1000
attr Rep.LogDB.sqlResult verbose 2
</pre>

=== Die current-Tabelle mit einem Extrakt der history-Tabelle füllen (tableCurrentFillup) ===

Diese Funktion erweitert die Möglichkeiten der Verwendung der current-Tabelle des DbLog-Devices. In den meisten Fällen wird im DbLog das Attribut "DbLogType = Current/History" gesetzt sein um bei der Erstellung von SVG's entsprechende Vorschläge in der DropDown-Liste des Editors zur Verfügung zu haben.

Bei dieser Betriebsart werden in der current-Tabelle neu auftretende Events von Device/Reading-Kombinationen eingetragen, sofern sie noch nicht enthalten sind. Werden neue Geräte definiert, erscheinen deren Events in der current-Tabelle, auch wenn man später nicht benötigte Readings mit den Attributen "event-on-change-reading" oder "event-on-update-reading" ausgrenzt.
Die einmal gespeicherten Werte bleiben in der current Tabelle erhalten. Sicherlich wird deswegen der eine oder andere User den Inhalt der current Tabelle löschen um wieder eine leere und saubere current-Tabelle zu haben. Das führt dann natürlich dazu, dass nur die ab diesem Zeitpunkt auftretenden Events in der Vorschlagsliste aufgenommen werden und nur selten auftretende Device/Reading-Kombinationen erst nach längerer Zeit wieder in der Tabelle current gespeichert werden.

Darüber hinaus möchte man vielleicht nur für SVG-Diagramme relevante Device/Reading-Einträge in der Vorschagsliste vorfinden oder dort nur Einträge vorhalten, die in den letzten drei Monaten aufgetreten sind. Die Beweggründe können sehr vielfältig sein.
Um diesem Wunsch zu entsprechen, gibt es im DbRep die Funktion "set <DbRep-Device> tableCurrentFillup", die eng mit dem dem DbLog-Attribut "DbLogType = SampleFill/History" zusammenarbeitet.

Nachfolgend wird an einem Beispiel erläutert, welche Konfigurationen vorgenommen werden können, um aus der history-Tabelle alle vorhandenen Device/Reading-Kombinationen zu extrahieren und sie zur Verwendung als SVG-Vorschlagsliste in die current-Tabelle einzufügen.

Für das Beispiel wird folgendes angenommen:

* es gibt ein definiertes DbLog-Device "LogDB" welches in die Datenbank "fhem" loggt
* das DbRep-Device zur Ausführung der Funktion wird "Rep.FillCurr.fhem" genannt
* es sollen alle in der history-Tabelle vorkommenden Device/Reading-Kombinationen extrahiert und in die current-Tabelle eingetragen werden (Einschränkungen auf bestimmte Devices / Readings oder zeitliche Abgrenzungen werden nicht vorgenommen, aber es wird darauf hingewiesen, wie es gemacht werden kann)

==== a) Anlegen des DbRep-Devices ====

Die Definition des DbRep-Devices erfolgt unter Angabe des zu verbindenden DbLog-Devices (nicht der Datenbank selbst):

define Rep.FillCurr.fhem DbRep LogDB

In dem so definierten neuen Device sind die Attribute zu setzen, die für die beabsichtigte Funktion wichtig sind.
Da dieses Device auch für die Löschung der in der current-Tabelle gespeicherten Datensätze verwendet wird, muss das Attribut "allowDeletion = 1" gesetzt werden.

attr Rep.FillCurr.fhem allowDeletion 1

Ebenfalls wichtig ist die Erzeugung eines Events sobald der Löschvorgang der current-Tabelle abgeschlossen ist. Dazu wird im Beispiel "event-on-update-reading" verwendet:

attr Rep.FillCurr.fhem event-on-update-reading state,--DELETED_ROWS_CURRENT--

[[Datei:currdelete.PNG|right|thumb|300px|set Rep.FillCurr.fhem tableCurrentPurge]]
Für die Funktion nicht wichtig, aber durchaus interessant zu wissen wie lange die Laufzeit der Funktionen ist, wird noch das Attribut "showproctime = 1" gesetzt. Damit werden die Readings "background_processing_time" und "sql_processing_time" erzeugt welche die jeweilige Bearbeitungszeit in Sekunden darstellen.

attr Rep.FillCurr.fhem showproctime 1

Mit dem so vorbereiteten Device können schon die Funktionen "tableCurrentPurge" und "tableCurrentFillup" manuell getestet werden. Mit dem Kommando:

set Rep.FillCurr.fhem tableCurrentPurge

wird der gesamte aktuelle Inhalt der current-Tabelle gelöscht. Wie im nebenstehenden Screenshot sichtbar, wurden in dem Beispiel 170 Datensätze gelöscht und dazu rund 30ms benötigt. Mit Abschluß der Operation wird der Delete-Event erzeugt:

2018-01-05 13:38:14.596 DbRep Rep.FillCurr.fhem --DELETED_ROWS_CURRENT--: 170

[[Datei:currfillup.PNG|right|thumb|300px|set Rep.FillCurr.fhem tableCurrentFillup]]
Dieser Event wird später in einem Notify für die automatisierte Current-Auffüllung verwendet.
Eine Zählug der current-EInträge mit "set Rep.FillCurr.fhem countEntries current" ergibt "-", d.h. der Löschbefehl war erfolgreich. Im jetzigen Zustand würde bei der Erstellung eines SVG keine DropDown-Liste angezeigt werden und statt dessen die Felder im SVG-Editor frei bearbeitbar sein, weil die current-Tabelle keine Werte enthält.
Gleichermaßen kann bereits die Auffüllung der current-Tabelle getestet werden mit dem Befehl:

set Rep.FillCurr.fhem tableCurrentFillup

Je nach Größe der Datenbank kann diese Operation einige Zeit in Anspruch nehmen. Da dieser Befehl wie bei DbRep üblich non-blocking abgearbeitet wird, hat die Laufzeit keinen Einfluss auf die sonstige FHEM-Verfügbarkeit.

[[Datei:svgfillup.PNG|left|thumb|300px|set Rep.FillCurr.fhem tableCurrentFillup]]
Wie bereits erwähnt, wird in dem Beispiel die gesamte history-Tabelle ausgewertet. Sollen zum Beispiel nur die letzten 90 Tage zur Auswertung herangezogen werden, kann das '''Attribut "timeDiffToNow = d:90"''' gesetzt werden.

Weitere Eingrenzungen bzgl. der auszuwertenden Devices bzw. Readings können über die '''Attribute "device" und "reading"''' vorgenommen werden. Die Syntax für die genannten Attribute und deren Auswirkung entnehme bitte der {{Link2CmdRef|Lang=de|Anker=DbRepattr}}.

In unserem Beispiel wurde die current-Tabelle mit 170 Datensätzen aufgefüllt. Dazu wurden 291 Sekunden benötigt (die Tabelle history enthält insgesamt rund 11 Mio. Einträge)

Wird jetzt ein neues SVG erstellt, erscheinen alle in selektierten Device/Reading-Kombinationen alphabetisch sortiert als DopDown-Liste im SVG-Editor.

==== b) Konfiguration des DbLog-Devices ====

In dem bestehen DbLog-Device "LogDB" ist zur Vorbereitung lediglich das Attribut "DbLogType = SampleFill/History" zu setzen:

attr LogDB DbLogType SampleFill/History

Entgegen der Arebeitsweise mit "Current/History" wird die current-Tabelle nicht mehr durch die Logging-Engine aktiv mit jedem relevanten Event gefüllt, sondern kann durch externe Tools, in dem Fall dem DbRep-Device, beschrieben werden.
Die current-Tabelle wird aber, ob leer oder gefüllt, bei der Erstellung eines SVG-Devices ausgewertet und in Abhängigeit des Ergebnisses eine DropDown-Liste zur Verfügung gestellt, oder frei editierbare Felder angeboten falls die current-Tabelle leer ist.

==== c) Definition der at/notify-Devices zum automatisierten Ablauf ====

Die Löschung des Inhaltes der current-Tabelle und die erneute Ausffüllung soll natürlich autmatisiert regelmäßig erfolgen. Zu diesem Zweck wird ein at-Device (At.LogDB.currentPurge) und ein notify-Device angelegt. Das AT-Device soll alle 8 Stunden und 15 Minuten das Löschen des current-Inhaltes steuern und nach Abschluß der Löschung soll getriggert durch das "--DELETED_ROWS_CURRENT--"-Event die Neubefüllung der current-Tabelle veranlasst werden.

Zur Definition dieser Devices gibt es nicht viel zu erläutern. Die entsprechende Syntax kann bei {{Link2CmdRef|Lang=de|Anker=at|Label=at}} bzw. {{Link2CmdRef|Lang=de|Anker=notify|Label=notify}} in der {{Link2CmdRef|Lang=de}} nachgelesen werden.

'''at-Device:'''

define At.LogDB.currentPurge at +*08:15:00 set Rep.FillCurr.fhem tableCurrentPurge

'''notify-Device:'''

define N.LogDB.Fillup notify Rep.FillCurr.fhem:.*DELETED_ROWS_CURRENT.* sleep 5;set Rep.FillCurr.fhem tableCurrentFillup

Das nichtblockierende FHEM-sleep (sleep gefolgt von einem weiteren Befehl) wird lediglich dazu verwendet, um zwischen der Delete- und Auffüll-Operation eine kleine Pause einzufügen.

==== d) Arbeitsweise und Raw-Definitionen ====

Durch das "At.LogDB.currentPurge"-Device wird alle 8 Stunden und 15 Minuten ein Löschlauf der current-Tabelle gestartet. Dadurch wird dem darauf folgenden Auffüllprozess immer eine saubere leere current-Tabelle zur Verfügung gestellt. Nach dem Löschlauf wird durch das "N.LogDB.Fillup"-Device, getriggert durch den Event "Rep.FillCurr.fhem:.*DELETED_ROWS_CURRENT.*", die erneute Auffüllung der current-Tabelle gestartet.
Die Daten werden aus der histrory-Tabelle gelesen, wobei der Zeitraum der Selektion und die zu betrachtenden Devices / Readings durch die Zeit-Attribute bzw. device / reading-Attribute des DbRep-Devices "Rep.FillCurr.fhem" individuell beeinflußt werden können.

Hilfreich ist es auch, wenn das DbLog-Device "LogDB" im asynchronen Modus betrieben wird.

Abschließend sind hier noch die Raw-Definitionen der beteiligten Devices (außer LogDB) angehängt, um das Beispiel leicht nachvollziehbar zu gestalten.

'''DbRep-Device "Rep.FillCurr.fhem":'''

<pre>
defmod Rep.FillCurr.fhem DbRep LogDB
attr Rep.FillCurr.fhem allowDeletion 1
attr Rep.FillCurr.fhem comment Current Fillup für DB fhem
attr Rep.FillCurr.fhem devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.FillCurr.fhem event-on-update-reading state,--DELETED_ROWS_CURRENT--
attr Rep.FillCurr.fhem icon icoTool
attr Rep.FillCurr.fhem room DbLog
attr Rep.FillCurr.fhem showproctime 1
attr Rep.FillCurr.fhem verbose 3
</pre>

'''at-Device "At.LogDB.currentPurge":'''

<pre>
defmod At.LogDB.currentPurge at +*08:15:00 set Rep.FillCurr.fhem tableCurrentPurge
attr At.LogDB.currentPurge comment Zeitgesteuertes Löschen der Current Tabelle. Nach dem Löschen wird \
Eventgesteuert (Notify N.LogDB.Fillup) ein tableCurrentFillup gestartet.
attr At.LogDB.currentPurge room DbLog
</pre>

'''notify-Device "N.LogDB.Fillup":'''

<pre>
defmod N.LogDB.Fillup notify Rep.FillCurr.fhem:.*DELETED_ROWS_CURRENT.* sleep 5;;set Rep.FillCurr.fhem tableCurrentFillup
attr N.LogDB.Fillup disable 1
attr N.LogDB.Fillup room DbLog
attr N.LogDB.Fillup verbose 2
</pre>

=== Backup/Restore einer SQLite Datenbank im laufenden Betrieb ===

In diesem Beitrag wird erläutert, wie man mit DbRep ein Backup der SQLite-Datenbank erstellen kann, welche Möglichkeiten es dabei gibt und wie man eine Datenbank aus einem Backup wieder herstellen kann.
Die Backup-Funktion nutzt die SQLite Online Backup API und ermöglicht es, konsistente Backups der SQLite-DB in laufenden Betrieb zu erstellen ohne die Datenbank schließen zu müssen.

Neben dem eigentlichen Backup kann optional einstellt werden, dass:

* vor dem Backup eine Datenbankoptimierung (Vacuum) ausgeführt werden soll. Dadurch wird Plattenplatz freigegeben sofern möglich.
* vor und nach dem Backup kann ein FHEM-Kommando oder eine Perl-Routine ausgeführt werden (eine Perl-Routine ist in {} einzuschließen)
* das erstellte Dumpfile kann über FTP(S) an einen FTP-Server übertragen werden
* über die interne Versionsverwaltung kann festgelegt werden, wieviele erstellte Backups auf dem Datenträger erhalten bleiben sollen (default: 3)

Für die Erläuterung des Beispiels soll ein DbRep-Device erstellt werden, welches:

* die SQLite Datenbank im Betrieb (Online) sichert
* vor dem Dump einen Vacuum-Lauf durchführt
* das erstellte Dumpfile auf einen FTP-Server überträgt
* 2 Versionen (Dumpfiles) nach einem erfolgreichen Backuplauf im Dumpverzeichnis verbleiben sollen

==== 1. Anlegen des DbRep-Devices ====

Das anzulegende Device wird sowohl für das (regelmäßige) Backup als auch für einen eventuellen Restore verwendet.
Die Definition des DbRep-Devices erfolgt unter Angabe des zu verbindenden DbLog-Devices (nicht der Datenbank selbst):

define Rep.SQLite DbRep LogSQLITE

Ist das Device definiert, verbindet es sich zu der Datenbank und wechselt in den state "connected", sofern die Verbindung erfolgreich verlief.
Prinzipiell funktioniert der hier beschriebene Backup-Prozess mit einem im synchronous Mode betriebenen DbLog-Device, aber es ist dringend angeraten das DbLog-Device (LogSQLITE) in den asynchronen Modus umzuschalten. Dadurch werden Blockierungen von FHEM und Verluste von Daten verhindert.

==== 2. Einstellungen des DbRep-Devices (Attribute) ====

Für die gewünschte Funktion müssen in diesem neu definierten Device einige relevante Attribute gesetzt werden.

:'''a) dumpDirLocal'''

Das zu erstellende Backupfile wird per default im log-Verzeichnis ./log (meist /opt/fhem/log) des FHEM-Rechners gespeichert. Um es an einer anderen Stelle zu speichern kann das Attribut "dumpDirLocal" gesetzt werdden. Dieses Verzeichnis kann sich auf dem lokalen Datenträger befinden, oder ein per NFS gemountetes Verzeichnis sein. In jedem Fall muss der User unter dem FHEM läuft Schreibrechte auf dieses Verzeichnis besitzen.

Für das Beispiel sollen die Dump-Files auf einen NFS-Mount einer Synology Diskstation gespeichert werden. Dazu wurde ein Mount in /etc/fstab erstellt um den Pfad "/sds1/backup" lokal verfügbar zu machen:

sds1.<fqdn>:/volume1/ApplicationBackup /sds1/backup nfs auto,defaults,tcp,intr 0 0

In diesem Verzeichnis exsitiert das Directory "dumps_FHEM", in dem die Backup-Files gespeichert werden sollen. Das Attribut wird entsprechend gesetzt auf:

attr Rep.SQLite dumpDirLocal /sds1/backup/dumps_FHEM

:'''b) dumpFilesKeep'''

Dieser Parameter stellt die Anzahl der aufzubewahrenden Backup-Files ein. Es werden immer die "x" neuesten bzw. letzten Files im Verzeichnis gehalten, wobei nur die zu der jeweiligen Datenbank gehörenden Files betrachtet werden.
Die Zugehörigkeit des Dump-Files zur Quelldatenbank wird anhand des Filenamens ermittelt, der sich zusammensetzt aus <DB-Name ohne Endung>_<Erstellungsdatum und Uhrzeit>.sqlitebkp

Beispiel: fhem_2018_01_12_17_15.sqlitebkp

Ist dieses Attribut nicht gesetzt, werden die 3 neuesten Backup-Files im Verzeichnis behalten.
Um nur 2 Files zu behalten wird das Attribut gesetzt auf:

attr Rep.SQLite dumpFilesKeep 2

:'''c) Aktionen vor und nach dem Backup ausführen'''

Vor und nach der Dump-Ausführung kann ein FHEM-Kommando bzw. Perl-Befehle ausgeführt werden. Perl-Befehle müssen in {} eingeschlossen werden.
Für das Beispiel soll vor dem Backup die Verbindung des DbLog-Devices LogSQLITE zur Datenbank getrennt werden. Dadurch werden keine neuen Daten in die Datenbank geschrieben. Wenn das DbLog-Device LogSQLITE im asynchronen Modus wie empfohlen betrieben wird, tritt auch kein Datenverlust ein, da die zu loggenden Daten im Cache verbleiben bis die Verbindung zur DB wieder hergestellt wird.

Es sei noch einmal darauf hingewiesen, dass das Backup-Verfahren ebenso im synchronen Modus und ohne das DbLog-Device von der Datenbank zu trennen, funktioniert und nur im Beispiel zur Demonstation der Möglichkeiten dient.

Um die Verbindung zu trennen wird ein "set LogSQLITE reopen <Zeit in Sekunden>" verwendet. Die Zeitspanne wird sehr großzügig gewählt und soll sicherstellen, dass innerhalb dieser Zeit das Backup abgeschlossen ist. Nach dem Backup wird sofort ein "set LogSQLITE reopen" ausgeführt, was die Verbindung des DbLog-Devices LogSQLITE zur Datenbank unmittelbar wieder herstellt..

attr Rep.SQLite executeBeforeProc set LogSQLITE reopen 3600
attr Rep.SQLite executeAfterProc set LogSQLITE reopen

:'''d) vor dem Backup Datenbank verkleinern (vacuum)'''

Diese optionale Funktion wird durch das Attribut "optimizeTablesBeforeDump" eingeschaltet. Dadurch die Vacuum-Funktion wird Platz innerhalb der Datenbank freigegeben der durch Löschvorgänge entstanden ist und dadurch die Größe des Datenbankfiles verringert.

attr Rep.SQLite optimizeTablesBeforeDump 1

:'''e) das Dump-File nach dem Backup zum FTP-Server übertragen'''

DbRep bietet die Möglichkeit, das erstellte Dump-File per FTP oder verschlüsselt per FTP(S) zum Server zu übertragen. Dazu gibt es einen Satz von Attributen um dem Device alle notwendigen Angaben für den FTP-Transfer zur Verfügung zu stellen. Es gibt dafür folgende Attribute:

* ftpUse : FTP Transfer nach dem Dump wird eingeschaltet (bzw. ftpUseSSL mit SSL Verschlüsselung)
* ftpUser : User zur Anmeldung am FTP-Server, default: anonymous
* ftpPwd : Passwort des FTP-Users, default nicht gesetzt
* ftpDir : Verzeichnis auf dem FTP-Server in welches das File übertragen werden soll (default: FTP-root)
* ftpPort : FTP-Port, default: 21
* ftpServer : Name oder IP-Adresse des FTP-Servers
* ftpTimeout : Timeout für die FTP-Verbindung in Sekunden (default: 30)
* ftpPassive : setzen wenn passives FTP verwendet werden soll
* ftpDebug : Debugging des FTP Verkehrs zur Fehlersuche

Gemäß dieser Beschreibung und dem Ziel dieses Beispiels werden die für FTP-Transfer relevanten Attribute wie folgt gesetzt:

attr Rep.SQLite ftpDir /ftp # Subdirectory ftp unter FTP-root als Zielverzeichnis
attr Rep.SQLite ftpPwd ftpftp1
attr Rep.SQLite ftpServer sds1.<fqdn>
attr Rep.SQLite ftpUse 1
attr Rep.SQLite ftpUser ftpuser

Der FTP-Server muss natürlich vorab eingerichtet und funktionsfähig sein. Sollten beim FTP-Transfer Fehler auftreten, kann das Attribut ftpDebug = 1 gesetzt werden um entsprechende Ausgaben zur Analyse des Problems im Log zu erhalten.

[[Datei:repsqlite_defined.PNG|right|thumb|300px|Fertig definiertes Device Rep.SQLite]]

:'''f) Hilfsattribute'''

Für die Funktion nicht relevant aber informativ ist das Attribut "showproctime = 1". Ist das Attribut gesetzt, wird das Reading "background_processing_time" angelegt. Es enthält nach der Ausführung die verbrauchte Prozesszeit.

Das fertig konfigurierte Device hier als RAW-Definition zur einfachen Nachnutzung. Die Angaben sind natürlich anzupassen:

<pre>
define Rep.SQLite DbRep LogSQLITE
attr Rep.SQLite devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.SQLite dumpDirLocal /sds1/backup/dumps_FHEM
attr Rep.SQLite dumpFilesKeep 2
attr Rep.SQLite event-on-update-reading state
attr Rep.SQLite executeAfterProc set LogSQLITE reopen
attr Rep.SQLite executeBeforeProc set LogSQLITE reopen 3600
attr Rep.SQLite ftpDir /ftp
attr Rep.SQLite ftpPwd ftpftp1
attr Rep.SQLite ftpServer sds1.<fqdn>
attr Rep.SQLite ftpUse 1
attr Rep.SQLite ftpUser ftpuser
attr Rep.SQLite optimizeTablesBeforeDump 1
attr Rep.SQLite room DbLog
attr Rep.SQLite showproctime 1
attr Rep.SQLite verbose 3
</pre>

 

==== 3. Backup durchführen ====

Mit dem wie beschrieben eingerichteten DbRep-Device kann das Buckup gestartet werden mit:

set Rep.SQLite dumpSQLite

[[Datei:logsqlite_closeduntil.PNG|right|thumb|500px|LogSQLITE ist geschlossen bis ...]]

Zu Beginn des Vorgangs wird sofort die Verbindung des DbLog-Devices zur Datenbank getrennt.
Ein laufendes Backup kann mit "set Rep.SQLite cancelDump" abgebrochen werden.
Das laufende Backup wird im state angezeigt mit "SQLite Dump is running - be patient and see Logfile !". Dieser Satz ist ernst gemeint, wobei der Dump über die Online-API sehr schnell arbeitet. Im Logfile mit (mindestens) verbose 3 werden die relevanten Informationen zur Verfügung gestellt:

<pre>
2018.01.13 08:35:10.745 3: DbRep Rep.SQLite - ################################################################
2018.01.13 08:35:10.746 3: DbRep Rep.SQLite - ### New SQLite dump ###
2018.01.13 08:35:10.747 3: DbRep Rep.SQLite - ################################################################
2018.01.13 08:35:10.748 3: DbRep Rep.SQLite - execute command before dump: 'set LogSQLITE reopen 3600'
2018.01.13 08:35:10.883 2: DbLog LogSQLITE: Connection closed until 09:35:10 (3600 seconds).
2018.01.13 08:35:10.917 3: DbRep Rep.SQLite - Size of database /opt/fhem/fhem.db before optimize (MB): 2554
2018.01.13 08:35:10.918 3: DbRep Rep.SQLite - VACUUM database /opt/fhem/fhem.db....
2018.01.13 08:44:04.216 3: DbRep Rep.SQLite - Size of database /opt/fhem/fhem.db after optimize (MB): 2554
2018.01.13 08:44:04.280 3: DbRep Rep.SQLite - Starting dump of database 'fhem.db'
2018.01.13 08:45:03.810 3: DbRep Rep.SQLite - Size of backupfile: 2553.64 MB
2018.01.13 08:45:04.579 3: DbRep Rep.SQLite - FTP: transferring /sds1/backup/dumps_FHEM/fhem_2018_01_13_08_44.sqlitebkp
2018.01.13 08:45:48.838 3: DbRep Rep.SQLite - FTP: fhem_2018_01_13_08_44.sqlitebkp transferred successfully to sds1.myds.me into dir /ftp
2018.01.13 08:45:48.844 3: DbRep Rep.SQLite - Deleting old dumpfile 'fhem_2018_01_13_08_13.sqlitebkp'
2018.01.13 08:45:49.273 3: DbRep Rep.SQLite - Finished backup of database fhem - total time used: 638 seconds
2018.01.13 08:45:49.358 2: DbRep Rep.SQLite - command after dump message: "Reopen executed."
2018.01.13 08:45:49.370 3: DbRep Rep.SQLite - Database dump finished successfully.
</pre>

[[Datei:repsqlite_dumprunning.PNG|right|thumb|400px|das Backup läuft]]

Setzt man das Attribut "ftpDebug=1", erhält man im Log zusätzliche Informationen zum FTP-Transfer:

<pre>
2018.01.13 08:50:22.385 3: DbRep Rep.SQLite - Size of backupfile: 2553.82 MB
Net::FTP>>> Net::FTP(2.79)
Net::FTP>>> Exporter(5.72)
Net::FTP>>> Net::Cmd(2.30)
Net::FTP>>> IO::Socket::INET(1.35)
Net::FTP>>> IO::Socket(1.38)
Net::FTP>>> IO::Handle(1.35)
Net::FTP=GLOB(0xb12ed20)<<< 220 SDS1 FTP server ready.
Net::FTP=GLOB(0xb12ed20)>>> USER ftpuser
Net::FTP=GLOB(0xb12ed20)<<< 331 Password required for ftpuser.
Net::FTP=GLOB(0xb12ed20)>>> PASS ....
Net::FTP=GLOB(0xb12ed20)<<< 230 User ftpuser logged in, access restrictions apply.
Net::FTP=GLOB(0xb12ed20)>>> TYPE I
Net::FTP=GLOB(0xb12ed20)<<< 200 Type set to I.
Net::FTP=GLOB(0xb12ed20)>>> CWD /ftp
Net::FTP=GLOB(0xb12ed20)<<< 250 CWD command successful.
2018.01.13 08:50:22.880 3: DbRep Rep.SQLite - FTP: transferring /sds1/backup/dumps_FHEM/fhem_2018_01_13_08_49.sqlitebkp
Net::FTP=GLOB(0xb12ed20)>>> PORT 192,168,2,45,145,42
Net::FTP=GLOB(0xb12ed20)<<< 200 PORT command successful.
Net::FTP=GLOB(0xb12ed20)>>> ALLO 2677867520
Net::FTP=GLOB(0xb12ed20)<<< 202 ALLO command ignored.
Net::FTP=GLOB(0xb12ed20)>>> STOR fhem_2018_01_13_08_49.sqlitebkp
Net::FTP=GLOB(0xb12ed20)<<< 150 Opening BINARY mode data connection for 'fhem_2018_01_13_08_49.sqlitebkp'.
Net::FTP=GLOB(0xb12ed20)<<< 226 Transfer complete.
2018.01.13 08:51:06.859 3: DbRep Rep.SQLite - FTP: fhem_2018_01_13_08_49.sqlitebkp transferred successfully to sds1.myds.me into dir /ftp
</pre>

[[Datei:repsqlite_dumpfinished.PNG|right|thumb|500px|Backup ist erfolgreich abgeschlossen]]

In vorliegenden Beispiel wird nach einem erfolgreichen Backup im state "Warning - dump finished, but command after dump message appeared" angezeigt. Diese Warnung rührt daher, dass das Reopen-Kommando eine Rückkehrinfo mitteilt, die als Problem gewertet und im Reading "afterdump_message" ausgegeben wird. In diesem Fall ist es nur eine Information.

In den erstellten Readings wird zusammengetragen welches File mit welcher Größe ertsellt wurde, welche alten Files gelöscht wurden, Informationen zum FTP-Transfer und welche Zeit der Gesamtprozess benötgt hat.

Das so vorbereitete Backup kann nun z.B. täglich oder auch mit einer wesentlich kürzeren Wiederholungsperiode (alle x Stunden) über ein at-Device eingeplant werden:

define At.SQLite.Dump at *23:52:00 set Rep.SQLite dumpSQLite

==== 4. Restore ====

Sollte es einmal zur Korruption des Datenbankfiles kommen (database disk image is malformed) und Reparaturversuche erfolglos bleiben, kann ein Restore die einzigste oder vielleicht auch einfachste Möglichkeit sein die Datenbank wieder herzustellen.

Das kann mit dem angelegten DbRep-Device im laufenden Betrieb geschehen. Auch hier ist wieder wichtig, dass das DbLog-Device LogSQLITE im asynchronen Modus betrieben wird und die Reopen-Zeit (siehe Einstellung Attribut "executeBeforeProc") sehr großzügig eingestellt ist.

Zum Restore gibt es den Befehl "set ... restoreSQLite <File>".

[[Datei:sqliterestore_auswahl.PNG|right|thumb|500px|Auswahlmenü Files für Restore ]]

Im FHEMWEB öffnet sich dazu eine DropDown-Liste die alle vorhandenen und zur Quelldatenbank passenden Dumpfiles auflistet. Das herzustellende File
kann so bequem ausgewählt werden. Die Dumpfiles müssen sich in dem Verzeichnis befinden, welches durch das Attribut "dumpDirLocal" festgelegt wurde (default (./log). [[Datei:sqliterestore_running.PNG|left|thumb|500px|Restore läuft]]

Der restore wird demzufolge gestartet mit:

set Rep.SQLite restoreSQLite <File>

Wieder wird zu Beginn des Vorgangs das verbundene DbLog-Device von der Datenbank abgekoppelt und nach dem Restore wieder automatisch verbunden. Eine Datenbankoptimierung bzw. FTP-Transfer wird bei diesem Vorgang natürlich nicht ausgeführt.

Das Log zeigt den Prozessverlauf:

<pre>
2018.01.13 09:21:55.435 3: DbRep Rep.SQLite - ################################################################
2018.01.13 09:21:55.437 3: DbRep Rep.SQLite - ### New database Restore/Recovery ###
2018.01.13 09:21:55.437 3: DbRep Rep.SQLite - ################################################################
2018.01.13 09:21:55.438 3: DbRep Rep.SQLite - execute command before restore: 'set LogSQLITE reopen 3600'
2018.01.13 09:21:55.448 2: DbLog LogSQLITE: Connection closed until 10:21:55 (3600 seconds).
2018.01.13 09:21:55.477 3: DbRep Rep.SQLite - Starting restore of database 'fhem.db'
2018.01.13 09:30:12.533 3: DbRep Rep.SQLite - Restore of /sds1/backup/dumps_FHEM/fhem_2018_01_13_08_49.sqlitebkp into 'fhem.db' finished - total time used: 497 seconds.
2018.01.13 09:30:12.685 2: DbRep Rep.SQLite - command after restore message: "Reopen executed."
2018.01.13 09:30:12.700 3: DbRep Rep.SQLite - Database restore finished successfully.
</pre>

Der Restore wurde erfolgreich abgeschlossen und die Verbindung des DbLog-Device LogSQLITE zur Datenbank wiederhergestellt. Das Logging wird nahtlos fortgeführt.

[[Datei:sqliterestore_finished.PNG|right|thumb|300px|Restore erfolgreich abgeschlossen]]

Es ist natürlich zu beachten, dass die Daten zwischen dem Erstellungszeitpunkt des eingespielten Backups und der aktuellen Zeit verloren sind !
Die bestehende (korrupte) Datenbank wird überschrieben. Deswegen ist es ratsam immer ein aktuelles (zeitnahes) Backup zu haben um den Datenverlust möglichst gering zu halten.

==== 5. Links ====
* Diskussion im Forum: "{{Link2Forum|Topic=82674|LinkText=Erstellung konsistentes Online-Backup im laufenden Betrieb}}"

=== Backup/Restore einer MySQL/MariaDB Datenbank im laufenden Betrieb ===

Das Backup einer MySQL/MariaDB Datenbank (im Folgenden stellvertretend als MySQL bezeichnet) kann als Varianten

* clientSide
* serverSide

Beim '''clientSide''' Backup werden die Daten über SQL-Statements aus der Datenbank gelesen, auf dem Client (dem FHEM-Server) verarbeitet und das Dumpfile geschrieben. Es werden history- und current-Tabelle gesichert, sowie eventuell weitere angelegte Tabellen und Views. Allerdings benötigt dieser Modus umfangreichere RAM und CPU-Ressorcen auf dem Client.

Die '''serverSide''' Option wird nachfolgend beispielhaft genauer erläutert.

==== serverSide Backup Option ====

Neben dem eigentlichen Backup kann optional einstellt werden, dass:

* vor dem Backup eine Tabellenoptimierung (optimizeTables) ausgeführt werden soll. Dadurch wird Plattenplatz freigegeben sofern möglich.
* vor und nach dem Backup kann ein FHEM-Kommando oder eine Perl-Routine ausgeführt werden (eine Perl-Routine ist in '''{ }''' einzuschließen)
* das erstellte Dumpfile kann komprimiert werden
* das erstellte Dumpfile kann über FTP(S) an einen FTP-Server übertragen werden
* über die interne Versionsverwaltung kann die Anzahl der im Backupverzeichnis zu verbleibenden Backup-Files festgelegt werden (default: 3)

Für die Erläuterung des Beispiels soll ein DbRep-Device erstellt werden, welches:

* die MySQL Datenbank im Betrieb (Online) sichert
* vor dem Dump die history-Tabelle optimiert
* das erstellte Dumpfile auf einen FTP-Server überträgt
* drei Versionen (Dumpfiles) nach der Übertragung auf dem FTP-Server belässt, ältere Files werden vom FTP-Server gelöscht
* eine Version (Dumpfile) nach einem erfolgreichen Backuplauf im Dumpverzeichnis verbleiben sollen

 

===== 1. Anlegen des DbRep-Devices =====

Das anzulegende Device wird sowohl für das (regelmäßige) Backup als auch für ein eventuelles Restore verwendet.
Die Definition des DbRep-Devices erfolgt unter Angabe des zu verbindenden DbLog-Devices (nicht der Datenbank selbst):

define Rep.fhemtest.Dump.ServerSide DbRep LogDB

Ist das Device definiert, verbindet es sich zu der Datenbank und wechselt in den state "connected", sofern die Verbindung erfolgreich verlief.
Prinzipiell funktioniert der hier beschriebene Backup-Prozess mit einem im synchronous Mode betriebenen DbLog-Device, aber es ist dringend angeraten das DbLog-Device (LogDB) in den asynchronen Modus umzuschalten. Dadurch werden FHEM-Blockierungen vermieden.

 

===== 2. Einstellungen des DbRep-Devices (Attribute) =====

Für die gewünschte Funktion müssen in diesem neu definierten Device einige relevante Attribute gesetzt werden.

:'''a) dumpDirRemote'''

Der Dump wird durch den MySQL-Server erstellt und per default im Home-Verzeichnis des MySQL-Servers gespeichert.
Es wird die gesamte history-Tabelle (nicht current-Tabelle) im '''CSV-Format''' ohne Einschränkungen exportiert.

Um es an einer anderen Stelle zu speichern, wird das Attribut "dumpDirRemote" gesetzt.

Auch wenn der MySQL-Server mit auf dem FHEM-Server läuft, also lokal, wird dieses Attribut zur Veränderung des Zielverzeichnisses verwendet.

 

:'''b) dumpDirLocal'''

Soll die interne Versionsverwaltung und die Dumpfilekompression des Moduls genutzt, sowie die Größe des erzeugten Dumpfiles ausgegeben werden, ist das Verzeichnis "dumpDirRemote" des MySQL-Servers auf dem Client zu mounten und im Attribut "dumpDirLocal" dem DbRep-Device bekannt zu machen.
Gleiches gilt wenn der FTP-Transfer nach dem Dump genutzt werden soll (Attribut "ftpUse" bzw. "ftpUseSSL").

Im Beispiel läuft der MySQL-Server auf einem entfernten Server und die Dump-Files werden dort im Verzeichnis

/volume1/ApplicationBackup

angelegt. Dieses Verzeichnis soll auf dem FHEM-Server als Verzeichnis "/sds1/backup" gemountet werden.
Wenn noch nicht passiert, den NFS Client auf dem FHEM Server installieren:

sudo apt-get update
sudo apt-get install nfs-common

Auf dem entfernten Server wird das Verzeichnis freigegeben/exportiert.
Wenn noch nicht vorhanden, ist zunächst das notwendige Paket zu installieren:

sudo apt-get install nfs-kernel-server

Ist das Paket vorhanden, existiert die Datei '''/etc/exports'''.
In der Datei '''/etc/exports''' wird das zu exportierende Verzeichnis hinzugefügt. Aus Gründen der Sicherheit wird nur die IP-Adresse des FHEM Servers für den Zugriff zugelassen:

/volume1/ApplicationBackup 192.168.50.33(rw,root_squash,async,no_subtree_check)

Soll ein Netzwerk freigegeben werden, kann der Eintrag in in dieser Form erfolgen:

/volume1/ApplicationBackup 192.168.XXX.0/24(rw,root_squash,async,no_subtree_check)

Danach Datei /etc/exports neu einlesen:

sudo exportfs -ra

Auf dem Client Rechner wird der Mountpoint für das einzuhängende Verzeichnus erstellt:

sudo mkdir /sds1/backup

Einen Eintrag in '''/etc/fstab''' erstellen:

<IP-Adresse>:/volume1/ApplicationBackup /sds1/backup nfs auto,defaults,tcp,intr 0 0

Ausführen:

mount /sds1/backup

In diesem Verzeichnis existiert das Directory "dumps_FHEM", in dem die Backup-Files gespeichert werden sollen. Das Attribut wird entsprechend gesetzt auf:

attr Rep.fhemtest.Dump.ServerSide dumpDirLocal /sds1/backup/dumps_FHEM

'''Hinweis:''' 
Läuft der MySQL-Server mit FHEM lokal auf dem gleichen Server, zeigen die Attribute '''dumpDirRemote und dumpDirLocal''' auf das '''identische Verzeichnis'''. Trotzdem sind beide Attribute zu definieren.

 
:'''b) dumpFilesKeep'''

Dieser Parameter stellt die Anzahl der aufzubewahrenden Backup-Files ein. Es werden immer die "x" neuesten bzw. letzten Files im Verzeichnis gehalten, wobei nur die zu der jeweiligen Datenbank gehörenden Files betrachtet werden.
Die Zugehörigkeit des Dump-Files zur Quelldatenbank wird anhand des Filenamens ermittelt.

Er setzt sich zusammen aus <Datenbankname>_history_<Erstellungsdatum_Uhrzeit>.csv

Beispiel: fhemtest_history_2020_05_14_03_42.csv (+.gzip falls Dumpfiles komprimiert werden)

Ist dieses Attribut nicht gesetzt, werden die 3 neuesten Backup-Files im Verzeichnis behalten.
Um nur 2 Files zu behalten wird das Attribut gesetz:

attr Rep.fhemtest.Dump.ServerSide dumpFilesKeep 2

:'''c) Aktionen vor und nach dem Backup ausführen'''

Vor und nach der Dump-Ausführung kann ein FHEM-Kommando bzw. Perl-Befehle ausgeführt werden. Perl-Befehle müssen in '''{ }''' eingeschlossen werden.

Für das Beispiel soll vor dem Backup die Verbindung des DbLog-Devices LogDB zur Datenbank getrennt werden. Dadurch werden keine neuen Daten in die Datenbank geschrieben. Wenn das DbLog-Device LogDB im asynchronen Modus wie empfohlen betrieben wird, tritt auch kein Datenverlust ein, da die zu loggenden Daten im Cache verbleiben bis die Verbindung zur DB wiederhergestellt wird.

Um die Verbindung zu trennen wird ein

set LogDB reopen <Zeit in Sekunden>

verwendet. Die Zeitspanne wird sehr großzügig gewählt und soll sicherstellen, dass innerhalb dieser Zeit das Backup abgeschlossen ist. Nach dem Backup wird sofort

set LogDB reopen

ausgeführt, was die Verbindung des DbLog-Devices LogDB zur Datenbank unmittelbar wiederherstellt.

attr Rep.fhemtest.Dump.ServerSide executeBeforeProc set LogDB reopen 3600
attr Rep.fhemtest.Dump.ServerSide executeAfterProc set LogDB reopen

:'''d) vor dem Backup Datenbank verkleinern (optimizeTables)'''

Diese optionale Funktion wird durch das Attribut "optimizeTablesBeforeDump" eingeschaltet. Dadurch diese Funktion wird Platz innerhalb der Datenbank freigegeben der durch Löschvorgänge entstanden ist und dadurch die Größe des Datenbankfiles verringert.

attr Rep.fhemtest.Dump.ServerSide optimizeTablesBeforeDump 1

Durch die Tabellenoptimierung verlängert sich die Dumpzeit.

:'''e) das angelegte Dump-File nach dem Backup zum FTP-Server übertragen'''

DbRep bietet die Möglichkeit, das erstellte Dump-File per FTP oder verschlüsselt per FTPS zum FTP-Server zu übertragen. Dazu gibt es einen Satz von Attributen um dem Device alle notwendigen Angaben für den FTP-Transfer zur Verfügung zu stellen. Es gibt dafür folgende Attribute:

* ftpUse : FTP Transfer nach dem Dump wird eingeschaltet (bzw. ftpUseSSL mit SSL Verschlüsselung)
* ftpUser : User zur Anmeldung am FTP-Server, default: anonymous
* ftpPwd : Passwort des FTP-Users, default nicht gesetzt
* ftpDir : Verzeichnis auf dem FTP-Server in welches das File übertragen werden soll (default: FTP-root)
* ftpPort : FTP-Port, default: 21
* ftpServer : Name oder IP-Adresse des FTP-Servers
* ftpTimeout : Timeout für die FTP-Verbindung in Sekunden (default: 30)
* ftpPassive : setzen wenn passives FTP verwendet werden soll
* ftpDebug : Debugging des FTP Verkehrs zur Fehlersuche

Gemäß dieser Beschreibung und dem Ziel dieses Beispiels werden die für FTP-Transfer relevanten Attribute wie folgt gesetzt:

attr Rep.fhemtest.Dump.ServerSide ftpDir /ftp # Subdirectory ftp unter FTP-root als Zielverzeichnis
attr Rep.fhemtest.Dump.ServerSide ftpPwd ftpftp1
attr Rep.fhemtest.Dump.ServerSide ftpServer sds1.<fqdn>
attr Rep.fhemtest.Dump.ServerSide ftpUse 1
attr Rep.fhemtest.Dump.ServerSide ftpUser ftpuser

Der FTP-Server muss natürlich vorab eingerichtet und funktionsfähig sein. Sollten beim FTP-Transfer Fehler auftreten, kann das Attribut ftpDebug = 1 gesetzt werden um entsprechende Ausgaben zur Analyse des Problems im Log zu erhalten.

[[Datei:dumpmysql1.PNG|right|thumb|300px|Fertig definiertes Device Rep.fhemtest.Dump.ServerSide]]

 
:'''f) Hilfsattribute'''

Für die Funktion nicht relevant aber informativ ist das Attribut "showproctime = 1". Ist das Attribut gesetzt, wird das Reading "background_processing_time" angelegt. Es enthält nach der Ausführung die verbrauchte Prozesszeit.

Im Attribut "userExitFn" kann eine Perl-Routine hinterlegt werden, um zum Beispiel nach dem Backup eine Mail oder Telegram-Message mit dem Erfolgsstatus zu versenden.

Das fertig konfigurierte Device hier als RAW-Definition zur einfachen Nachnutzung. Die Angaben sind natürlich anzupassen:

<pre>
define Rep.fhemtest.Dump.ServerSide DbRep LogDB
attr Rep.fhemtest.Dump.ServerSide devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen .*Dump.*is.*running.*:remotecontrol/black_btn_PLAYgreen Database.*backup.*finished.*:remotecontrol/black_btn_GREEN tn_GREEN error.*:remotecontrol/black_btn_RED
attr Rep.fhemtest.Dump.ServerSide dumpCompress 1
attr Rep.fhemtest.Dump.ServerSide dumpDirLocal /sds1/backup/dumps_FHEM
attr Rep.fhemtest.Dump.ServerSide dumpDirRemote /volume1/ApplicationBackup/dumps_FHEM
attr Rep.fhemtest.Dump.ServerSide dumpFilesKeep 1
attr Rep.fhemtest.Dump.ServerSide event-on-update-reading state
attr Rep.fhemtest.Dump.ServerSide executeAfterProc set LogDB reopen
attr Rep.fhemtest.Dump.ServerSide executeBeforeProc set LogDB reopen 3600
attr Rep.fhemtest.Dump.ServerSide fastStart 1
attr Rep.fhemtest.Dump.ServerSide ftpDebug 0
attr Rep.fhemtest.Dump.ServerSide ftpDir /ftp
attr Rep.fhemtest.Dump.ServerSide ftpDumpFilesKeep 3
attr Rep.fhemtest.Dump.ServerSide ftpPwd ftpftp1
attr Rep.fhemtest.Dump.ServerSide ftpServer sds1.<fqdn>
attr Rep.fhemtest.Dump.ServerSide ftpUse 0
attr Rep.fhemtest.Dump.ServerSide ftpUser ftpuser
attr Rep.fhemtest.Dump.ServerSide optimizeTablesBeforeDump 1
attr Rep.fhemtest.Dump.ServerSide showproctime 1
attr Rep.fhemtest.Dump.ServerSide userExitFn doafterdump
</pre>

 

===== 3. Backup durchführen =====

Voraussetzung ist, dass der verwendete Datenbankuser das globale Privileg '''FILE''' besitzt.
Falls der User dieses Recht nicht hat, kann man es mit dem definierten DbRep-Device wie folgt erledigen.

:'''(optional) dem Datenbankuser das FILE Privileg zuweisen'''

Da die Rechtezuweisung nur mit einem administrativen DB-User (i.A. root) funktioniert, wird dieser User im DbRep-Device angelegt und aktiviert:

<pre>
set Rep.fhemtest.Dump.ServerSide adminCredentials <Admin-User> <Passwort>
attr Rep.fhemtest.Dump.ServerSide useAdminCredentials 1
</pre>

Nun kann dem verwendeten Datenbankuser das FILE Privileg zugeordnet werden:

<pre>
set Rep.fhemtest.Dump.ServerSide sqlCmd GRANT FILE ON *.* TO '<DB-User>'@'%';
</pre>

Dabei ist '''<DB-User>''' durch den in der DbLog-Konfiguration angegebenen User zu ersetzen da die gesamte Datenbankarbeit mit diesem User erfolgt.

Nach der Ausführung schaltet man die Nutzung des administrativen Users wieder ab mit:

<pre>
attr Rep.fhemtest.Dump.ServerSide useAdminCredentials 0
</pre>

Die Rechte können nun überprüft werden mit

<pre>
set Rep.fhemtest.Dump.ServerSide sqlCmd show grants;
</pre>

und werden im Ergebnis dargestellt (z.B. für den DB-User fhemtest):

<pre>
SqlResultRow_1 GRANTS FOR FHEMTEST@%
SqlResultRow_2 GRANT PROCESS, FILE, INDEX ON *.* TO 'fhemtest'@'%' IDENTIFIED BY PASSWORD '*...............'
SqlResultRow_3 GRANT SELECT, INSERT, UPDATE, DELETE, ALTER, EXECUTE, SHOW VIEW ON `fhemtest`.* TO 'fhemtest'@'%'
SqlResultRow_4 GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX ON `fhemtest`.`fhemtest` TO 'fhemtest'@'%'
</pre>

 
:'''Backup starten'''

[[Datei:dumpmysql2.PNG|right|thumb|400px|Backup läuft ...]]
Mit dem wie beschrieben eingerichteten DbRep-Device kann das Backup gestartet werden mit:

set Rep.fhemtest.Dump.ServerSide dumpMySQL serverSide

Zu Beginn des Vorgangs wird sofort die Verbindung des DbLog-Devices zur Datenbank getrennt.
Ein laufendes serverSide Backup kann mit FHEM-Mitteln nicht abgebrochen werden !

Das laufende Backup wird im state angezeigt mit "serverSide Dump is running - be patient and see Logfile !".

Im Logfile mit (mindestens) verbose 3 werden die relevanten Informationen zur Verfügung gestellt:

<pre>
2020.05.14 22:59:18.610 3: DbRep Rep.fhemtest.Dump.ServerSide - ########################################
2020.05.14 22:59:18.611 3: DbRep Rep.fhemtest.Dump.ServerSide - ### New database serverSide dump ###
2020.05.14 22:59:18.611 3: DbRep Rep.fhemtest.Dump.ServerSide - ########################################
2020.05.14 22:59:18.612 3: DbRep Rep.fhemtest.Dump.ServerSide - execute command before dump: 'set LogDB reopen 3600'
2020.05.14 22:59:18.613 2: DbLog LogDB: Connection closed until 23:59:18 (3600 seconds).
2020.05.14 22:59:18.660 3: DbRep Rep.fhemtest.Dump.ServerSide - Searching for tables inside database fhemtest....
2020.05.14 22:59:18.664 3: DbRep Rep.fhemtest.Dump.ServerSide - Size of database fhemtest before optimize (MB): 8298.98
2020.05.14 22:59:18.665 3: DbRep Rep.fhemtest.Dump.ServerSide - Optimizing tables
2020.05.14 22:59:18.665 3: DbRep Rep.fhemtest.Dump.ServerSide - Optimizing table `current` (INNODB). It will take a while.
2020.05.14 22:59:19.560 3: DbRep Rep.fhemtest.Dump.ServerSide - Table 1 `current` optimized successfully.
2020.05.14 22:59:19.560 3: DbRep Rep.fhemtest.Dump.ServerSide - Optimizing table `history` (INNODB). It will take a while.
2020.05.14 23:30:09.183 3: DbRep Rep.fhemtest.Dump.ServerSide - Table 2 `history` optimized successfully.
2020.05.14 23:30:09.186 3: DbRep Rep.fhemtest.Dump.ServerSide - 2 tables have been optimized.
2020.05.14 23:30:09.253 3: DbRep Rep.fhemtest.Dump.ServerSide - Size of database fhemtest after optimize (MB): 8298.98
2020.05.14 23:30:09.254 3: DbRep Rep.fhemtest.Dump.ServerSide - Starting dump of database 'fhemtest', table 'history'
2020.05.14 23:39:47.566 3: DbRep Rep.fhemtest.Dump.ServerSide - compress file /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_14_23_30.csv
2020.05.14 23:42:33.138 3: DbRep Rep.fhemtest.Dump.ServerSide - file compressed to output file: /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_14_23_30.csv.gzip
2020.05.14 23:42:34.784 3: DbRep Rep.fhemtest.Dump.ServerSide - input file deleted: /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_14_23_30.csv
2020.05.14 23:42:34.785 3: DbRep Rep.fhemtest.Dump.ServerSide - Number of exported datasets: 49032159
2020.05.14 23:42:34.787 3: DbRep Rep.fhemtest.Dump.ServerSide - Size of backupfile: 419.73 MB
2020.05.14 23:42:37.082 3: DbRep Rep.fhemtest.Dump.ServerSide - FTP: transferring /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_14_23_30.csv.gzip
2020.05.14 23:42:47.511 3: DbRep Rep.fhemtest.Dump.ServerSide - FTP: fhemtest_history_2020_05_14_23_30.csv.gzip transferred successfully to sds1.myds.me into dir /ftp
2020.05.14 23:42:47.558 3: DbRep Rep.fhemtest.Dump.ServerSide - Deleting old dumpfile 'fhemtest_history_2020_05_14_22_12.csv.gzip'
2020.05.14 23:42:47.857 3: DbRep Rep.fhemtest.Dump.ServerSide - Finished backup of database fhemtest - total time used (hh:mm:ss): 00:43:29
2020.05.14 23:42:47.948 2: DbRep Rep.fhemtest.Dump.ServerSide - command message after dump: "Reopen executed."
2020.05.14 23:42:47.973 3: DbRep Rep.fhemtest.Dump.ServerSide - Database dump finished successfully.
</pre>

[[Datei:dumpmysql3.PNG|right|thumb|500px|Backup ist erfolgreich abgeschlossen]]

In vorliegenden Beispiel wird nach einem erfolgreichen Backup im state '''"Warning - dump finished, but command after dump message appeared"''' angezeigt.

Diese Warnung rührt daher, dass das Reopen-Kommando eine Rückkehrinfo mitteilt, die als Issue gewertet und im Reading "afterdump_message" ausgegeben wird. In diesem Fall ist es nur eine Information.

In den erstellten Readings wird zusammengetragen welches File mit welcher Größe erstellt wurde, welche alten Files gelöscht wurden, Informationen zum FTP-Transfer und welche Zeit der Gesamtprozess benötgt hat.

Das so vorbereitete Backup kann nun z.B. täglich oder auch mit einer wesentlich kürzeren Wiederholungsperiode (alle x Stunden) über ein at-Device eingeplant werden:

define At.MySQL.Dump at *23:52:00 set Rep.fhemtest.Dump.ServerSide dumpMySQL serverSide

 

===== 4. Restore =====

Voraussetzung für das Restore ist, dass der verwendete Datenbankuser das globale Privileg '''FILE''' besitzt.
Falls der User dieses Recht nicht hat, kann man es mit dem definierten DbRep-Device wie folgt erledigen.

:'''(optional) dem Datenbankuser das FILE Privileg zuweisen'''

Da die Rechtezuweisung nur mit einem administrativen DB-User (i.A. root) funktioniert, wird dieser User im DbRep-Device angelegt und aktiviert:

<pre>
set Rep.fhemtest.Dump.ServerSide adminCredentials <Admin-User> <Passwort>
attr Rep.fhemtest.Dump.ServerSide useAdminCredentials 1
</pre>

Nun kann dem verwendeten Datenbankuser das FILE Privileg zugeordnet werden:

<pre>
set Rep.fhemtest.Dump.ServerSide sqlCmd GRANT FILE ON *.* TO '<DB-User>'@'%';
</pre>

Dabei ist '''<DB-User>''' durch den in der DbLog-Konfiguration angegebenen User zu ersetzen da die gesamte Datenbankarbeit mit diesem User erfolgt.

Nach der Ausführung schaltet man die Nutzung des administrativen Users wieder ab mit:

<pre>
attr Rep.fhemtest.Dump.ServerSide useAdminCredentials 0
</pre>

'''Alternativ''' kann die Rechtezuweisung auf der Konsole des MySQL-Servers ausgeführt werden:

<pre>
sudo mysql -u root -p
GRANT File ON *.* TO '<DB-User>'@'%';
exit
</pre>

Die Rechte können nun überprüft werden mit

<pre>
set Rep.fhemtest.Dump.ServerSide sqlCmd show grants;
</pre>

Nun kann der Restore ausgeführt werden.

Ein mit der Option '''serverSide''' erstellter Dump enthält ausschließlich die Daten der history-Tabelle.
Der Restore kann nur in eine bestehende Datenabank und entsprechend angelegte history Tabelle erfolgen.
Ist nach einem Datenbankfehler die Tabelle/Datenbank zerstört, must sie zunächst mit den vorbereiteten Befehlen in den
[https://svn.fhem.de/trac/browser/trunk/fhem/contrib/dblog/db_create_mysql.sql SVN-Skripten] bereitgestellt werden.

Ist die history-Tabelle noch intakt und soll nur der Inhalt ersetzt werden, muss die Tabelle vorab geleert werden da sonst unter Umständen doppelte Datensätze enstehen wenn kein primary Key verwendet ist.
Das kann einfach mit dem Befehl

set <Name> sqlCmd truncate table history

erreicht werden. Damit werden '''alle''' Daten der history-Tabelle hochperformant gelöscht. Die Tabelle selbst bleibt erhalten.

Sollte der truncate Befehl wegen nicht ausreichender Rechte des DB-Users mit Fehler enden, kann ein administrativer Datenbankuser (i.A. 'root') mit dem Kommando und Attribut

set <Name> adminCredentials <Name> <Passwort>
attr <Name> useAdminCredentials 1

hinterlegt und aktiviert werden.

Ein Restore kann mit dem angelegten DbRep-Device im laufenden Betrieb geschehen. Auch hier ist wieder wichtig, dass das DbLog-Device im asynchronen Modus betrieben wird und die Reopen-Zeit (siehe Einstellung Attribut "executeBeforeProc") sehr großzügig eingestellt ist.

Zum Restore dient der Befehl

set <Name> restoreMySQL <File>

[[Datei:dumpmysql4.PNG|right|thumb|500px|Auswahlmenü Files für Restore ]]

Im FHEMWEB öffnet sich dazu eine DropDown-Liste die alle vorhandenen und zur Quelldatenbank passenden Dumpfiles auflistet.
Das herzustellende File kann so bequem ausgewählt werden. Die Dumpfiles müssen sich in dem Verzeichnis befinden, welches durch das Attribut '''dumpDirLocal''' festgelegt wurde (default (./log). [[Datei:dumpmysql5.PNG|left|thumb|500px|Restore läuft]]

Der restore wird demzufolge gestartet mit:

set Rep.fhemtest.Dump.ServerSide restoreMySQL <File>

Der Restore der history-Tabelle kann nun online im laufenden FHEM-Betrieb erfolgen.
Wieder wird zu Beginn des Vorgangs das verbundene DbLog-Device von der Datenbank abgekoppelt und nach dem Restore wieder automatisch verbunden. Eine Datenbankoptimierung bzw. FTP-Transfer wird bei diesem Vorgang natürlich nicht ausgeführt.

[[Datei:dumpmysql6.PNG|left|thumb|500px|Fortschrittsanzeige in einem zweiten DbRep Device]]
In einem zweiten (z.B. kopierten) DbRep Device kann mit Hilfe des Befehls

get Rep.fhemtest.Dump.ServerSide procinfo

der Fortschritt des Restores überwacht werden. In der Spalte '''PROGRESS''' wird der Fortschritt in '''%''' angegeben.

Das Log zeigt den Ablauf des Restores:

<pre>
2020.05.15 13:07:24.369 3: DbRep Rep.fhemtest.Dump.ServerSide - #######################################
2020.05.15 13:07:24.370 3: DbRep Rep.fhemtest.Dump.ServerSide - ### New database Restore/Recovery ###
2020.05.15 13:07:24.371 3: DbRep Rep.fhemtest.Dump.ServerSide - #######################################
2020.05.15 13:07:24.371 3: DbRep Rep.fhemtest.Dump.ServerSide - execute command before restore: 'set LogDB reopen 3600'
2020.05.15 13:07:24.429 3: DbRep Rep.fhemtest.Dump.ServerSide - uncompress file /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_15_11_47.csv.gzip
2020.05.15 13:09:31.152 3: DbRep Rep.fhemtest.Dump.ServerSide - file uncompressed to output file: /sds1/backup/dumps_FHEM/fhemtest_history_2020_05_15_11_47.csv
2020.05.15 13:09:31.237 3: DbRep Rep.fhemtest.Dump.ServerSide - Size of uncompressed file: 5511.52 MB
2020.05.15 13:09:31.242 3: DbRep Rep.fhemtest.Dump.ServerSide - Starting restore of database 'fhemtest', table 'history'.
2020.05.15 14:42:28.566 2: DbLog LogDB: Connection closed until 16:42:28 (7200 seconds).
2020.05.15 14:46:22.391 3: DbRep Rep.fhemtest.Dump.ServerSide - Restore of /volume1/ApplicationBackup/dumps_FHEM/fhemtest_history_2020_05_15_11_47.csv into 'fhemtest', 'history' finished - total time used (hh:mm:ss): 01:38:57
2020.05.15 14:46:22.457 2: DbRep Rep.fhemtest.Dump.ServerSide - command message after restore: "Reopen executed."
2020.05.15 14:46:22.481 3: DbRep Rep.fhemtest.Dump.ServerSide - Database restore finished successfully.
</pre>

[[Datei:dumpmysql7.PNG|right|thumb|300px|Restore erfolgreich abgeschlossen]]

Der Restore wurde erfolgreich abgeschlossen und die Verbindung des DbLog-Device LogDB zur Datenbank wiederhergestellt. Das Logging wird nahtlos fortgeführt.

Es ist natürlich zu beachten, dass die Daten zwischen dem Erstellungszeitpunkt des eingespielten Backups und der aktuellen Zeit verloren sind !
Eventuell in der Tabelle '''history''' noch vorhandene Daten werden '''nicht''' überschrieben.

 

=== Speichern von Berechnungswerten in der Datenbank und Erstellen eines Plots (ab Version 7.5.1) ===

Es sollen aus in der Datenbank vorhandenen minütlichen Leistungswerten eines Wechselrichters die maximal-, minimal- und durchschnittlichen Leistungswerte pro Tag berechnet werden und diese Ergebnisse wieder in die Datenbank geschrieben werden um daraus einen Plot zu erstellen.
Diese Berechnung soll immer aktuell für den laufenden Monat erfolgen.

Die Ausgangswerte liegen in der Datenbank als minütliche kW-Einträge vor (Auszug DbRep fetchrows):

<pre>
2018-01-18_15-55-49__MySTP_5000__total_pac 0.200
2018-01-18_15-56-50__MySTP_5000__total_pac 0.218
2018-01-18_16-00-14__MySTP_5000__total_pac 0.209
2018-01-18_16-00-39__MySTP_5000__total_pac 0.198
2018-01-18_16-01-39__MySTP_5000__total_pac 0.142
2018-01-18_16-02-39__MySTP_5000__total_pac 0.130
2018-01-18_16-03-39__MySTP_5000__total_pac 0.117
2018-01-18_16-05-39__MySTP_5000__total_pac 0.087
2018-01-18_16-06-39__MySTP_5000__total_pac 0.071
2018-01-18_16-07-39__MySTP_5000__total_pac 0.076
2018-01-18_16-08-39__MySTP_5000__total_pac 0.065
2018-01-18_16-09-39__MySTP_5000__total_pac 0.069
2018-01-18_16-10-39__MySTP_5000__total_pac 0.060
2018-01-18_16-12-39__MySTP_5000__total_pac 0.065
2018-01-18_16-13-39__MySTP_5000__total_pac 0.068
2018-01-18_16-14-39__MySTP_5000__total_pac 0.054
2018-01-18_16-15-39__MySTP_5000__total_pac 0.041
2018-01-18_16-16-39__MySTP_5000__total_pac 0.027
2018-01-18_16-17-39__MySTP_5000__total_pac 0.026
2018-01-18_16-18-39__MySTP_5000__total_pac 0.021
2018-01-18_16-19-39__MySTP_5000__total_pac 0.018
2018-01-18_16-20-39__MySTP_5000__total_pac 0.012
</pre>

Für die Berechnung der Ergenisse stehen in DbRep die Kommandos maxValue, minValue und averageValue zur Verfügung.

 
==== 1. Anlegen des DbRep-Devices ====

Das anzulegende Device wird für alle notwendigen Berechnungen verwendet.
Die Definition des DbRep-Devices erfolgt unter Angabe des zu verbindenden DbLog-Devices (nicht der Datenbank selbst):

define Rep.total_pac DbRep LogDB

Ist das Device definiert, verbindet es sich zu der Datenbank und wechselt in den state "connected", sofern die Verbindung erfolgreich verlief.
Prinzipiell funktioniert der hier Ablauf mit einem im synchronous Mode betriebenen DbLog-Device, aber es ist dringend angeraten das DbLog-Device (LogDB) in den asynchronen Modus umzuschalten. Dadurch werden Blockierungen von FHEM verhindert.

 

==== 2. Einstellungen des DbRep-Devices (Attribute) ====
[[Datei:Rep.total_pac.PNG|right|thumb|400px|Device definiert]]
Für die gewünschte Funktion müssen in diesem neu definierten Device einige relevante Attribute gesetzt werden.

Da die Berechnungen immer für den aktuellen Monat erstellt werden sollen, wird das Attribut "timestamp_begin" so definiert, dass immer der Beginn des aktuellen Monats dynamisch ermittelt wird. Das ist gegeben durch den Eintrag:

attr Rep.total_pac timestamp_begin current_month_begin

Es soll ein Ergebniswert pro Tag erzeugt werden. Damit dies erreicht werden kann, wird das Attribut "aggregation" verwendet und auf den Wert "day" eingestellt. Würde zum Beispiel ein stündlicher Ergebniswert gewünscht sein, hätte "aggregation = hour" den benötigten Effekt.

attr Rep.total_pac aggregation day

Die Attribute "device" und "reading" legen das auszuwertende Device und Reading fest. Dabei ist zu beachten, dass im Gegensatz zur allgemein gültigen Möglichkeit devspec bzw. SQL-Wildcards zu verwenden bei dieser speziellen Detailfunktion dies nicht der Fall ist. Das heißt. es muß immer ein eindeutiges Device und ein eindeutiges Reading angegeben werden. Der Grund liegt in der Notwendigkeit, bei der Speicherung der Ergebnisdaten der Datenbank ebenfalls ein eindeutiges Device und Reading zu übergeben. In dem Beispiel wird das Device "MySTP_5000" und das Reading "total_pac" ausgewertet.

attr Rep.total_pac device MySTP_5000
attr Rep.total_pac reading total_pac

Hilfreiche Attribute sind noch "event-on-update-reading" zur Begrenzung der Events, "showproctime" zur Bestimmung der Prozesszeiten und "allowDeletion" um die Möglichkeit zu haben, irrtümlich gespeicherte Berechnungsergebnisse wieder über das DbRep-Device zu löschen.

attr Rep.total_pac event-on-update-reading state
attr Rep.total_pac showproctime 1
attr Rep.total_pac allowDeletion 1

Das so vorbereitete Device ist für die benötigten Funktionen ausreichend eingestellt.
Zur einfachen Nachnutzung nochfolgend die Raw-Definition des DbRep-Devices:

<pre>
define Rep.total_pac DbRep LogDB
attr Rep.total_pac aggregation day
attr Rep.total_pac allowDeletion 1
attr Rep.total_pac device MySTP_5000
attr Rep.total_pac event-on-update-reading state
attr Rep.total_pac reading total_pac
attr Rep.total_pac room DbLog
attr Rep.total_pac showproctime 1
attr Rep.total_pac timestamp_begin current_month_begin
attr Rep.total_pac verbose 3
</pre>

 
==== 3. Berechnung ausführen und Speicherung der Ergebnisse ====
[[Datei:average.PNG|right|thumb|300px|Average Berechnung]]
Die benötigten Funktionen sind:

averageValue - Berechnung des täglichen Durchschnittswert der Wechselrichterleistung (kW)
maxValue - Berechnung des täglichen Maximalwertes der Wechselrichterleistung (kW)
minValue - Berechnung des täglichen Minimalwertes der Wechselrichterleistung (kW)

[[Datei:minval.PNG|right|thumb|300px|MinVal Berechnung]]
Für jede dieser Kommandos stehen im DbRep die Optionen "display" und "writeToDB" zur Verfügung. Die Option "display" stellt die Ergenisse lediglich im Browser dar und kann dazu die Ergebnisse vor der Speicherung zu bewerten.
So ergeben die Kommandos:

set Rep.total_pac minValue display
set Rep.total_pac maxValue display
set Rep.total_pac avarageValue display

die täglichen Min-, Max- und Durchschnittswerte der WR-Leistung.

[[Datei:maxval.PNG|right|thumb|300px|MaxVal Berechnung]]
Entsprechen die Ergebnisse den Erwartungen bzw. dem Ziel, können die folgenden Kommandos verwendet werden um die Berechnung durchzuführen und dabei gleichzeitig in die Datenbank zu schreiben.

set Rep.total_pac minValue writeToDB
set Rep.total_pac maxValue writeToDB
set Rep.total_pac avarageValue writeToDB

Die Daten werden in der history-Tabelle gespeichert und, sofern das DbLog-Device das Attribut "DbLogType = Current..." gestzt hat, auch in der current-Tabelle gespeichert. Im letzteren Fall kann das Ergebnisreading bei der Erstellung des Plots sofort aus der DropDown-Liste ausgewählt werden.

Bei der Datenspeicherung wird der neue Readingnamen aus einem Präfix und dem originalen Readingnamen gebildet. Der Präfix setzt sich aus der Bildungsfunktion und der gewählten Aggregation zusammen, d.h. im Fall des Beispiels aus "min","max","avg" und "day".
Der Timestamp der neuen Readings in der Datenbank wird von der eingestellten Aggregationsperiode abgeleitet, sofern kein eindeutiger Zeitpunkt des Ergebnisses bestimmt werden kann. So kann der Zeitpunkt des Maximalwertes eines Tages wertes genau bestimmt werden und der resultierende Datensatz wird mit diesem Timestamp gespeichert.

Die resultierende Readingnamen werden somit wie folgt in der Datenbank gespeichert:

max_day_total_pac
min_day_total_pac
avg_day_total_pac

Die Berechnungen können regelmäßig über ein at eingeplant werden. Die Funktionen vermeiden dabei die Speicherung von doppelten Datensätzen. Wurde bei einem Berechnungslauf der Datensatz bereits gespeichert, wird dieser Datensatz beim nächsten Durchlauf nicht noch einmal gespeichert.

==== 4. Erstellung des Plots ====
[[Datei:dropdown.PNG|right|thumb|300px|Drop-Down Liste SVG]]
Wird durch das DbLog-Device die current-Tabelle genutzt, das Attribut "DbLogType = Current..." ist gesetzt, können die Ergebnisreadings max_day_total_pac, min_day_total_pac und avg_day_total_pac im SVG-Editor ausgewählt werden (siehe {{Link2CmdRef|Lang=de|Anker=SVG}} bei SVG).

Durch die Wahl des Plot-Typ "bars" und dem SVG-Attribut "fixedrange = month" entsteht der gewünschte Tageswert-Plot über den aktuellen Monat.

[[Datei:svg_calc.PNG|right|thumb|300px|Ergebnis SVG]]
Hier wiederum die Raw-Definition des SVG-Device:

<pre>
defmod SVG_LogDB_16 SVG LogDB:SVG_LogDB_16:HISTORY
attr SVG_LogDB_16 fixedrange month
attr SVG_LogDB_16 room Energie,SVG_MySQL
attr SVG_LogDB_16 title "Max Leistung: $data{max1} kW, Min Leistung: $data{min3} kW,Max. Durchschnittsleistung: $data{max2} kW "
</pre>

sowie des gplot-Files:

<pre>
# Created by FHEM/98_SVG.pm, 2018-01-18 21:45:27
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<TL>'
set ytics
set y2tics
set grid
set ylabel "kW"
set y2label "kW"
set yrange [0:6]
set y2range [0:6]

#LogDB MySTP_5000:max_day_total_pac
#LogDB MySTP_5000:avg_day_total_pac
#LogDB MySTP_5000:min_day_total_pac

plot "<IN>" using 1:2 axes x1y2 title 'Max-Leistung / Tag' ls l0fill lw 1 with bars,\
"<IN>" using 1:2 axes x1y2 title 'Average / Tag' ls l2fill lw 1 with bars,\
"<IN>" using 1:2 axes x1y2 title 'Min-Leistung / Tag' ls l1fill lw 1 with bars
</pre>

 
=== Öffnungszeiten von Fenster/Türen aus der Datenbank ermitteln ===

Ziel ist es, die Öffnungszeit eines Fensters oder einer Tür zu ermitteln sobald es wieder geschlossen wird und ein Reading mit der Zeit in dem entsprechenden Device (Fensterkontakt) zu setzen.

Für das Beispiel wird angenommen dass:

* der Status der Sensoren als "open" und "close" in der Datenbank gespeichert ist
* das verwendetet DbRep-Device "Rep.WindowOpenTime" heißt
* das verwendete DbLog-Device "LogDBShort" heißt (wird mit dem DbRep-Device bei der Definition assoziiert)

Zunächst wird zur Auswertung von closed-Events ein entsprechendes Notify definiert (Raw-Format):

<pre>
defmod N.WindowClosed notify (.*fenster.*|.*terrasse.tuer.*):closed \
{ \
if($NAME =~ /(.*fenster.*|.*terrasse.tuer.*)/) {\
fhem("set LogDBShort commitCache;; defmod calcse at +00:00:10 {SwitchEvent(\"$NAME\")};;");; \
}\
}
attr N.WindowClosed alias Starte Ermittlung der Fenster Öffnungszeiten
attr N.WindowClosed comment Wird verwendet um die letzte Öffnungszeit der Fenster aus der Datenbank zu ermitteln und im Reading "LastOpenTime" abzulegen.
attr N.WindowClosed room Datenbank->Produktiv
</pre>

Die zusätzlich if-Abfrage im Notify behob ein Problem bei den Fensterkontakten die mit einem Thermostat gepeert sind, da in diesem Fall der Event mehrfach auftrat. Der Teil '''"set LogDBShort commitCache"''' speichert den Cache der Datenbank vor der Berechnung sofern sie im asynchronen Modus betrieben wird (kann entfallen wenn im synchronen Mode betrieben). Um der DB Zeit zur Abspeicherung zu geben, wird die Berechnung über ein AT mit einer entsprechenden Verzögerung (hier 10 Sekunden) angestartet. Die Zeit im AT bitte entsprechend der eigenen Systembedingungen anpassen.

Im Notify wird die Funktion '''SwitchEvent($NAME)''' aufgerufen. Diese Funktion wird in der 99_myUtils.pm eingefügt:

<syntaxhighlight lang="perl">
##########################################################################################################
# This function is used to start an SQL query for the given device "$name" and check
# how much time the device was in state defined by $usedVal1 today.
# The query is done by a DbRep device.
#
# In this example the name of the DbRep device is "Rep.WindowOpenTime"
##########################################################################################################
sub SwitchEvent($) {
my ($name) = @_;

Log3 $name , 5, "$name - SwitchEvent called";

my $usedReading = "\"state\""; # name of the reading which holds the state which has to be checked
my $usedVal1 = "\"open\""; # reading value which starts the time measuerement
my $usedVal2 = "\"closed\""; # reading value which stops the time measurement
my $device = "\"$name\""; # name of the device which state has to be checked
my $dbRepDevice = "Rep.WindowOpenTime"; # name of the DbRep device

# The query will check for the current day the cumulated time difference between $usedVal1 and $usedVal2
# the example here is a homemetic threeStateSensor (window contact) and the result of the query is
# the cumulated time which the window was open (in seconds) and the name of the device whic is
# used by the function SwitchQueryResult()
# Example: AZ_Fensterkontakt|433.2
my $sql = "SET \@topen = NULL,\@closed = NULL, \@popen = NULL;;".
" SELECT DEVICE ,SUM(TIMEDIFF(tclosed, topen)) AS duration FROM (".
" SELECT TIMESTAMP, VALUE, DEVICE,".
" \@topen := \@popen AS topen,".
" \@closed := IF(VALUE = $usedVal2, TIMESTAMP, NULL) AS tclosed,".
" \@popen := IF(VALUE = $usedVal1, TIMESTAMP, NULL) AS prev_open".
" FROM history WHERE".
" DATE(TIMESTAMP) = CURDATE() AND".
" DEVICE = $device AND".
" READING = $usedReading AND ".
" (VALUE = $usedVal1 OR VALUE = $usedVal2)".
" ORDER BY TIMESTAMP".
" ) AS tmp";

Log3 $name , 5, "$name - SwitchEvent start query: $sql";

fhem("set $dbRepDevice sqlCmd $sql"); # start the query now. Result will be processed in the function SwitchQueryResult() below

return;
}
</syntaxhighlight>

Die Funktion '''SwitchEvent()''' bekommt den Namen des Gerätes übergeben welches Event ausgelöst hat. Damit wird eine SQL-Abfrage für dieses Gerät gestartet und ermittelt, wieviel Zeit (in Sekunden) für das übergebene Gerät zwischen dem Zustand "open" und "closed" verbracht wurde.

Das verwendete DbRep-Device wird wie folgt definiert:

<pre>
define Rep.WindowOpenTime DbRep LogDBShort
attr Rep.WindowOpenTime aggregation no
attr Rep.WindowOpenTime comment Öffnungszeit der Fenster ermitteln
attr Rep.WindowOpenTime initialized:control_3dot_hor_s connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen
attr Rep.WindowOpenTime reading state
attr Rep.WindowOpenTime showproctime 1
attr Rep.WindowOpenTime sqlResultFormat sline
attr Rep.WindowOpenTime event-on-update-reading state
attr Rep.WindowOpenTime userExitFn SwitchQueryResult
</pre>

Ganz wichtig ist die Zeile '''attr Rep.powerOnTime userExitFn SwitchQueryResult'''. Hier ist die Funktion '''SwitchQueryResult()''' angegeben, die nach erfolgreicher Bearbeitung der SQL-Query aufgerufen wird. Diese Funktion wird ebenfalls in der 99_myUtils.pm eingefügt:

<syntaxhighlight lang="perl">
##########################################################################################################
# This function will be called from the DbRep device if the attribute
# attr Name_of_your_DbRep_device userExitFn SwitchQueryResult is set.
# This function create a new reading "LastOpenTime" at the device for which the query is done and
# set the cumulated time difference in seconds to the reading.
##########################################################################################################
sub SwitchQueryResult($$$) {
my ($name,$reading,$value) = @_; # $name is the name of the DbRep device which is calling this function
my $hash = $defs{$name};

# DbRep calls this function several times with different informations.
# if $reading is SqlResult, $value will hold the result of the query
if ($reading eq "SqlResult") {
my ($dev,$val) = split('\|',$value); # split the result in two parts
$dev = $dev?$dev:"";
$val = $val?$val:"";
if (!$val) {
$val = 0;
}
$val = DbRep_sec2hms($val); # calculate seconds to hms
Log3 $name , 5, "DbRep $name - SwitchQueryResult splitted result: $dev $val";

fhem("setreading $dev LastOpenTime $val") if($dev); # set the reading "LastOpenTime" with the time if device-Log was found
}

return;
}
</syntaxhighlight>

Die Funktion SwitchQueryResult() rechnet das Ergebnis der query aus dem DbRep Device von Sekunden in das Format hh:mm:ss um und trägt die berechnete Zeit als Reading "'''LastOpenTime'''" im jeweiligen Fensterkontakt ein.

So kann man z.B. im Device mit dem Namen "eg.bad.fenster" das Reading "'''LastOpenTime 00:03:58'''" finden.
Die vorliegende Berechnung liefert immer die Zeit des letzten Öffnungszyklus des aktuellen Tages. Möchte man die Zeiten des gesamten Tages akkumulieren, kann nach der Beschreibung "[[Summe aller Einschaltzeiten eines Gerätes]]" verfahren werden.

=== Grünlandtemperatursumme ermitteln und in SVG-Grafik darstellen ===
Nachfolgendes Beispiel zeigt, wie die Grünlandtemperatursumme ermittelt werden kann und die Ermittlungsergebnisse in der Datenbank gespeichert werden, um sie in einer SVG-Grafik darzustellen. Das beschriebene Verfahren kann natürlich auch für andere Anwendungsfälle angewendet werden.

Was ist die Grünlandtemperatursumme?

Hier die Definition aus [https://de.wikipedia.org/wiki/Grünlandtemperatursumme Wikipedia]:

: ''Die Grünlandtemperatursumme (GTS) ist eine Spezialform der Wachstumsgradtage, die in der Agrarmeteorologie verwendet wird. Sie wird herangezogen, um in Mitteleuropa den Termin für das Einsetzen der Feldarbeit nach dem Winter zu bestimmen.''
: ''Eine Wärmesumme ist allgemein eine gewisse Lufttemperatur eines Tages über die Tage einer Periode summiert. Dabei verwendet man besonders die kumulierte korrigierte GTS, die nach Monat gewichtet wird.''
: ''Wird im Frühjahr die Summe von 200 überschritten, ist der nachhaltige Vegetationsbeginn erreicht. Hintergrund ist die Stickstoffaufnahme und -verarbeitung des Bodens, welcher von dieser Temperatursumme abhängig ist. In mittleren Breiten wird das meist im Laufe des März, an der Wende von Vorfrühling zu Mittfrühling erreicht. ''

Zur Bestimmung der GTS benötigt man zunächst die Aufzeichnung der örtlichen Temperaturwerte in einer DbLog-Datenbank.
Im Beispiel wird dazu das Reading '''temperature''' des Device '''MyWetter''' (Device vom Typ [[Weather]]) genutzt. Die Einrichtung des Weather- und DbLog-Devices wird an dieser Stelle nicht beschrieben und als bekannt vorausgesetzt.

Es wird angenommen, dass:
* das definierte DbLog-Device im asynchronen Mode betrieben wird
* das Reading '''temperature''' des Device '''MyWetter''' in der DbLog-Datenbank gespeichert wird

Zur Ermittlung des GTS wird ein DbRep-Device mit gesetztem [[Attribut]] '''avgDailyMeanGWSwithGTS''' verwendet. Dieses Attribut legt die Berechnung der täglichen Durchschnittstemperatur nach den Regularien des Deutschen Wetterdienstes fest und aktiviert auf dieser Grundlage weiterhin die Berechnung der Grünlandtemperatursumme.

[[Datei:gts1.PNG|right|thumb|400px|GTS Ermittlung]]
Die RAW-Definition des verwendeten DbRep-Devices:
<pre>
define Rep.GTS DbRep LogDB
attr Rep.GTS averageCalcForm avgDailyMeanGWSwithGTS
attr Rep.GTS device MyWetter
attr Rep.GTS fastStart 1
attr Rep.GTS reading temperature
attr Rep.GTS room DbLog
attr Rep.GTS showproctime 1
attr Rep.GTS timestamp_begin current_year_begin
attr Rep.GTS timestamp_end previous_day_end
attr Rep.GTS userExitFn saveGTS
</pre>

'''LogDB''' ist der Name des angeschlossenen DbLog-Devices und ist natürlich entsprechend anzupassen. Unbedingt wichtig ist es, den Start der Auswertung auf den Beginn des Jahres zu setzen. Das Attribut '''timestamp_begin = current_year_begin''' erfüllt diese Bedingung. Das Attribut '''userExitFn''' wird noch erläutert.

Die Berechnung wird gestartet mit dem Befehl:
:<code>set Rep.GTS averageValue display</code>

Im Ergebnis entstehen Readings die auszugsweise nachfolgend aufgelistet sind:
<pre>
2021-02-26 22:32:08 2021-02-11__MyWetter__temperature__AVGDMGWS__2021-02-11 -5.1
2021-02-26 22:32:08 2021-02-11__MyWetter__temperature__GrasslandTemperatureSum 40.1
2021-02-26 22:32:08 2021-02-12__MyWetter__temperature__AVGDMGWS__2021-02-12 -6.8
2021-02-26 22:32:08 2021-02-12__MyWetter__temperature__GrasslandTemperatureSum 40.1
2021-02-26 22:32:08 2021-02-13__MyWetter__temperature__AVGDMGWS__2021-02-13 insufficient values - execute get Rep.GTS versionNotes 2 for further information
2021-02-26 22:32:08 2021-02-14__MyWetter__temperature__AVGDMGWS__2021-02-14 -8.2
2021-02-26 22:32:08 2021-02-14__MyWetter__temperature__GrasslandTemperatureSum 40.1
2021-02-26 22:32:08 2021-02-15__MyWetter__temperature__AVGDMGWS__2021-02-15 -3.2
2021-02-26 22:32:08 2021-02-15__MyWetter__temperature__GrasslandTemperatureSum 40.1
</pre>

Die Meldung "insufficient values - execute get Rep.GTS versionNotes 2 for further information" ist ein Hinweis darauf, dass die für die Ermittlung der Durchschnittstagestemperaturen nach den Regularien des Deutschen Wettederdienstes geforderten Werte nicht (komplett) in der DB vorhanden sind.

Um die Grünlandtemperatursumme im SVG-Diagramm anzuzeigen, muss dieser Wert für jeden Tag in der DB gespeichert werden. Alle benötigten Informationen sind in den DbRep-Readings, z.B.:

<pre>
2021-02-12__MyWetter__temperature__GrasslandTemperatureSum 40.1
</pre>

vorhanden. Der Präfix enthält das Datum, für das die jeweilige Grünlandtemperatursumme gilt, d.h., es muß nur noch ein neuer Wert zu diesem korrespondierenden Datum in die DB geschrieben werden. Das wird durch eine kleine Routine in 99_myUtils.pm erreicht, die im Attribut '''userExitFn''' des DbRep-Devices hinterlegt wird.

'''Routine in 99_myUtils.pm einfügen:'''
<syntaxhighlight lang="perl">
##############################################################
# speichern GTS in Datenbank
##############################################################
sub saveGTS {
my $name = shift;
my $reading = shift;
my $value = shift;
my $device = "MyWetter"; # Weather-Device -> anpassen !
my $logdev = "LogDB"; # DbLOg Device -> anpassen !

# 2021-02-14__MyWetter__temperature__GrasslandTemperatureSum 40.1
if($reading =~ /GrasslandTemperatureSum/x) {
my ($date) = (split "__", $reading)[0];
my ($y,$m,$d) = split "-", $date;
my $ts = "$y-$m-$d 12:00:00";

CommandSet(undef, "$logdev addCacheLine $ts|$device|calculated|calculated|GrasslandTemperatureSum|$value|");
}

return;
}
</syntaxhighlight>

In der Routine sind die Variablen '''$device''' und '''$logdev''' mit den realen Devices Weather und DbLog zu ersetzen.

;Funktionsweise
:Ist der Auswertungslauf beendet, werden alle Readings, die "GrasslandTemperatureSum" enthalten, in ihre Bestandteile aufgesplittet, der Timestamp zum Speichern in der Datenbank formatiert und der neu in der DB zu erstellende Datensatz in den Cache des DbLog-Devices eingefügt. Der nächste Sync-Lauf in DbLog fügt die im Cache erstellten Datensätze in die Datenbank ein.

==== Definition des SVG-Devices ====
[[Datei:gts2.PNG|right|thumb|400px|GTS SVG Darstellung]]
In der Datenbank befinden sich nun Datensätze mit dem '''Device MyWetter''' und dem '''Reading GrasslandTemperatureSum''' die im SVG Diagramm ausgewertet werden können.

RAW-Definition des SVG-Devices:
<pre>
defmod SVG_GTS SVG LogDB:SVG_GTS:HISTORY
attr SVG_GTS fixedrange month
attr SVG_GTS label "aktuelle Grünlandtemperatur $data{max1}"
attr SVG_GTS room SVG
</pre>

Die dazugehörige GPLOT-Datei (SVG_GTS.gplot):
<pre>
# Created by FHEM/98_SVG.pm, 2021-02-27 08:08:30
set terminal png transparent size <SIZE> crop
set output '<OUT>.png'
set xdata time
set timefmt "%Y-%m-%d_%H:%M:%S"
set xlabel " "
set title '<L1>'
set ytics
set y2tics
set grid
set ylabel "Score"
set y2label "Score"

#LogDB MyWetter:GrasslandTemperatureSum::

plot "<IN>" using 1:2 axes x1y2 title 'GTS' ls l1fill lw 1 with ibars
</pre>

[[Kategorie:Logging]]

MQTT2 DEVICE - Schritt für Schritt

2024-05-15T07:22:13Z

Dora71: /* json2nameValue() */ Erklärung des 4. und 5. Parameters ergänzt inklusive Codebeispiel

== Einführung ==
Das Protokoll [[MQTT]] ermöglicht einen flexiblen Datenaustausch zwischen unterschiedlichsten Geräten und FHEM und insbesondere auch bidirektionale Kommunikation von und zu FHEM. Es gibt dabei jedoch nur einen geringen Grad der Standardisierung des Datenaustauschs. In der Praxis sind daher relative viele unterschiedliche Wege aufzufinden, wie die Kommunikation via MQTT in den externen Geräten und Diensten konkret umgesetzt wurde - jeder Autor einer firmware oder Software kann dies so lösen, wie es ihm beliebt, und nicht jeder beherzigt dabei den Grundsatz, dass die Kommunikation via MQTT "leichtgewichtig" sein sollte.

{{Randnotiz|RNTyp=Info|RNText=Grundsätzlich stehen für viele Geräte-Typen bereits Vorlagen zur Verfügung, siehe [[AttrTemplate|attrTemplate]], die einem die wesentliche Konfigurationsarbeit abnehmen können, wie sie hier beschrieben ist. Die damit jeweils erzeugten Konfigurationen sind Einrichtungsbeispiele, die v.a. eine in sich konsistenze Zusammenstellung der verschiedenen Attribute enthalten. Es steht jedem User frei, diese Ausgangsbasis dann nach seinem Belieben zu ändern. Spätere Änderungen des verwendeten attrTemplate wirken sich nicht automatisch auf die durch frühere Versionen oder den User nachkonfigurierte Geräte aus! Da es vorkommen kann, dass sich die per MQTT übermittelten Daten und Topics ändern, wenn z.B. eine firmware aktualisiert wurden, kann dies Anpassungen am jeweiligen Template erforderlich machen. Grundsätzlich sollen die per attrTemplate für MQTT2_DEVICE verfügbaren attrTemplate jeweils für die aktuellste verfügbare stabile firmware-Version passen.}}

Das Modul [[MQTT2_DEVICE]] bietet eine Vielzahl von Möglichkeiten, auf die verschiedensten Anforderungen einzugehen, und die ein- und ausgehenden Daten zu einem oder mehreren FHEM-[[Gerät|Gerät/en]] zusammenzufassen. Eine Übersicht häufig vorkommender MQTT-Geräte ist in [[MQTT2-Module - Praxisbeispiele]] zu finden.

Ziel dieses Artikels ist die Darstellung der Schritte, die sich als zweckmäßig erwiesen haben zur Einrichtung von "guten" FHEM-Geräten.
{{Randnotiz|RNTyp=Info|RNText=Viele - teils komplexe Beispiele und weitere Verweise sind im {{Link2Forum|Topic=116162|LinkText=MQTT-Workshop für MQTT2-Module}} zu finden.}}Dabei soll am Ende erreicht werden:
* standardisierte set- (und ggf. get-)-Kommandos, insbesondere unter Beachtung der [[DevelopmentGuidelinesReadings| Developer Guidelines für Readings]]
* Schließen des Informationskreises von eventuellen Kommandos bis zur Rückmeldung des (externen) Gerätes oder Dienstes (im Folgenden: "Gegenstelle")
* standardisierte Reading-Namen, damit möglichst Auswertungen nicht speziell an das jeweilige Gerät angepasst werden müssen
* Reduzierung und Vermeidung von unnötigen Datenpunkten und Events
* Einrichten von regelmäßigen Abfrage-Timern (falls erforderlich!).

== Vorbereitung ==
=== MQTT2_SERVER ===
Selbst, wenn grundsätzlich ein externer MQTT-Server IO-Device zum Einsatz kommt, ist sehr zu empfehlen, für die Beschäftigung mit einem neuen, unbekannten Device zunächst einen {{Link2CmdRef|Anker=MQTT2_SERVER|Lang=en|Label=MQTT2_SERVER}} einzurichten. Ist der Port 1883 bereits belegt, nimmt man einfach einen anderen Port, z.B. 1884: <code>define m2server MQTT2_SERVER 1884 global</code>. Sollte die Gegenstelle tiefer strukturierte Daten im JSON-Format über verschiedene Topics als Payload übermittelt, kann es ausnahmsweise hilfreich sein, '''in der Einrichtungsphase''' auch das Attribut "autocreate" am MQTT2_SERVER auf "complex" zu stellen: <code>attr m2server autocreate complex</code>. Weiter muss die allgemeine [[Autocreate|autocreate-Instanz]] aktiv sein. Für den Regelbetrieb und für einfache, bekannte Devices (sowie für solche, für die bereits attrTemplate vorhanden sind), wird ausdrücklich empfohlen, das ''autocreate''-Atribut am m2server gar nicht erst zu setzten, dann wird ''autocreate'' mit der (default) Einstellung ''simple'' verwendet. Die Hintergründe sind nachfolgend im Abschnitt zu ''json2nameValue()'' zu finden.

=== Begrifflichkeiten ===
Ein typisches, von "autocreate" erstelltes Gerät sieht dann z.b. (mit autocreate = simple am MQTT2_SERVER) so aus:
<syntaxhighlight lang="text">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD readingList DVES_9B01BD:tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/LWT:.* LWT\
DVES_9B01BD:tele/DVES_9B01BD/UPTIME:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/SENSOR:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO1:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO2:.* { json2nameValue($EVENT) }\
DVES_9B01BD:tele/DVES_9B01BD/INFO3:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/RESULT:.* { json2nameValue($EVENT) }\
DVES_9B01BD:stat/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }
attr MQTT2_DVES_9B01BD room MQTT2_DEVICE
</syntaxhighlight>
Wir unterscheiden bei jeder Zeile des readingList-Attributs vier Elemente, die ersten drei werden jeweils durch einen Doppelpunkt voneinander getrennt:
==== CID ====
Dies ist die Gerätekennung (hier: DVES_9B01BD). Diese ist auch Bestandteil des ''define'', über diese wird ermittelt, zu welchem FHEM-Gerät via MQTT eingehende Informationen zugeordnet werden sollen. Diese Angabe ist weder im define noch in der readingList zwingend, aber in der Definition für den Hauptkanal eines Gerätes empfohlen. Es empfiehlt sich, die CID-Angaben bei eigenen readingList-Einträgen wegzulassen bzw. diese zu löschen. So kann einfacher zwischen automatisch generierten und eigenen Angaben unterschieden werden und die Geräte sind leichter zwischen verschiedenen IO-Modulen zu verschieben.
==== Topic ====
Datenpunkt, an den eine Information gesendet wird. Empfangsseitig sind dies hier z.B. ''tele/DVES_9B01BD/STATE'' oder ''tele/DVES_9B01BD/LWT''.
Enthält der Topic Doppelpunkte oder Sonderzeichen, kann dies zu Problemen führen. Da der Topic intern als ''regex'' behandelt wird, kann man sich das in solchen Sonderfälle dadurch zu nutze machen, dass man z.B problematische Zeichen durch Punkte oder "beliebige Zeichenfolgen" ersetzt. So kann z.B. aus dem per autocreate erstellten <code>attr reader readingList SMLReader/Strom/sensor/1/obis/1-0:1.8.0/255/value:.* Strombezug_tariflos</code> folgendes abgeleitet werden: <code>attr reader readingList SMLReader/Strom/sensor/1/obis/1-0.1.8.0/255/value:.* Strombezug_tariflos</code>,

==== Payload ====
Der jeweilige Nachrichteninhalt. Da dieser nicht im vorhinein bekannt ist, wird er in der readingList typischerweise als "beliebige Zeichenfolge" (".*") notiert.

==== Auswertung ====
Dies kann entweder direkt der Reading-Name sein, dem die Payload zugeordnet werden soll, oder ein Perl-Ausdruck. Hier wird z.B. die eingehende Information für ''tele/DVES_9B01BD/LWT'' dem Reading ''LWT'' zugeordnet, während die Informationen aus ''tele/DVES_9B01BD/STATE'' an die Funktion ''json2nameValue()'' übergeben werden. ''$EVENT'' entspricht dabei der ''Payload''.

=== defaults ===
Für unbekannte Gegenstellen ist zunächst immer zu empfehlen, deren "Grundeinstellungen" zu verwenden, und Anpassungen erst und nur insoweit vorzunehmen, als es für ein besseres Zusammenspiel mit FHEM sinnvoll ist. Abzuraten ist insbesondere von:
* Änderungen der Topics und Topic-Sturkturen (ausgenommen den Fall, dass schon andere Gegenstellen im Einsatz sind, die identische Topics verwenden)
* Vergabe von ''friendly names''

== Bestandsaufnahme ==
=== Projektseiten finden ===
Viele Geräte, die das MQTT-Protokoll verwenden, haben eigene Projektseiten oder API-Beschreibungen, denen man entnehmen kann, wie mit dieser Gegenstelle Daten ausgetauscht werden können. Diese sollte man bei allen weiteren Schritten stets zur Hand haben. Dabei kann es neben der allgemeinen Beschreibung auch ein oder mehrere Detail-Seiten geben, auf denen nähere Informationen zu den spezifischen Geräte zu finden sein können.

=== MQTT - Datenverkehr mitlesen ===
Sowohl MQTT2_SERVER wie MQTT2_CLIENT bieten in der Detailansicht die Option ''Show MQTT traffic''. Darüber läßt sich der ein- und ausgehende Datenverkehr bequem mitlesen. Bei MQTT2_CLIENT wird dabei allerdings vorausgesetzt, dass er überhaupt Daten vom MQTT-Server erhält, also insbesondere die ''subscriptions'' korrekt gesetzt sind (falls per Attribut eingeschränkt).

=== readingList ===
Zunächst empfiehlt es sich, einfach die Gegenstelle neu zu starten und (ggf. über ein FileLog) aufzuzuzeichnen, was über welchen Topic wie oft an Informationen gesendet wird. Dabei kann und sollte durchaus - sofern dies möglich ist - der eine oder andere Schaltvorgang (z.B. über das Web-Interface der Gegenstelle) durchgeführt werden, sofern dies möglich ist (oder allgemeiner: möglichst viele bekannte Anweisungen ausführen lassen). Am Ende sollte man eine möglichst vollständige Auflistung in der readingList erhalten haben.
Falls strukturierte Daten im JSON-Format als Payload verwendet werden, kann man diese auch zusätzlich ohne die Verarbeitung durch ''json2nameValue()'' aufzeichnen, z.B. indem man die betreffende Zeile in der readingList doppelt:
<syntaxhighlight lang="text">
defmod MQTT2_DVES_9B01BD MQTT2_DEVICE DVES_9B01BD
attr MQTT2_DVES_9B01BD readingList tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT) }\
tele/DVES_9B01BD/STATE:.* json_STATE\
tele/DVES_9B01BD/LWT:.* LWT\
[...]
</syntaxhighlight>
So kann man mit Hilfe des betreffenden Logs ggf. auch über ein externes Tool wie mosquitto_pub MQTT-Nachrichten an FHEM generieren, ohne darauf warten zu müssen, dass diese von der Gegenstelle selbst erzeugt werden.

=== ignoreRegexp ===
Manche Gegenstellen senden beim Start Konfigurationsinformationen, die allerdings nicht durch FHEM ausgewertet werden können. Die betreffenden Topics sollte man (allgemein) so in die ignoreRegexp beim MQTT2_SERVER bzw. [[MQTT2_CLIENT]] aufnehmen, dass derartige Informationen künftig gar nicht mehr an MQTT2_DEVICE weitergereicht werden. Danach kann man die betreffenden Zeilen aus der readingList löschen! Entsprechendes gilt für die hierüber generierten Readings.

Weiter ist zu empfehlen, in diese ignoreRegexp auch die Topics aufzunehmen, über die Gegenstellen typischerweise Kommandos entgegennehmen. Dies könnte z.B. so aussehen:
<code>attr m2server ignoreRegexp shellies/[^/]+/command|cmnd/[^/]+/|homeassistant/.*/config|tasmota/discovery</code>

=== Viele Geräte? ===
==== "split" ====
Sind auf einer Hardware mehrere "Hauptschalter" vorhanden (z.B. ein Relay-Board), ist sehr zu empfehlen, für jeden dieser "Hauptschalter" ein eigenes FHEM-Gerät anzulegen (für logische Einheiten wie Rollladenaktoren ggf. paarweise). MQTT2_DEVICE unterstützt [[DevelopmentModuleAPI#SetExtensions|SetExtensions]] und kann daher Kommandos wie "on-for-timer" über FHEM-interne Mechanismen gut umsetzen. Dies erfordert allerdings, dass die Kommandos "on" und "off" verfügbar sein müssen.
Wird ein Gerät gesplittet, sollten im Gerät, das den ersten (Haupt-) Kanal repräsentiert dann alle Kommunikationsdaten gebündelt werden, Querverweise zu den weiteren Kanälen kann man über das spezielle Readings "associatedWith" herstellen.

==== bridgeRegexp ====
{{Randnotiz|RNTyp=Info|RNText=Manche derartige Interfaces müssen zunächst entsprechend konfiguriert werden, dass die zu einem Sensor oder Aktor gehörenden Daten jeweils auf einem eigenen Topic ausgegeben werden. Insbesondere ist dies bei Tasmota (ZigBee oder Bluetooth) der Fall!}}
In eher seltenen Fällen kommt es vor, dass eine Gegenstelle eine Art "Brücke" zu einer Mehrzahl über diese Brücke anzusteuernder (oder zu empfangender) Aktoren oder Sensoren darstellt. In diesen Fällen kann es geboten sein, die eigentliche Gegenstelle als Hauptdevice darzustellen und für jede weitere Hardware (Sensor oder Aktor) dann ein oder mehrere Einzeldevices anzulegen. Dies kann mit Hilfe des Attributs bridgeRegexp automatisiert erfolgen, wenn sich der Sensor/Aktor aus der Topic-Struktur ablesen läßt.

== readingList optimieren==
=== gute Reading-Namen - Klartext ===
Viele Gegenstellen senden z.B. einen online/offline-Status als "last will and testament" unter einem Topic, der mit "LWT" endet. Dieses hier sendet zwar passende Daten, aber an einen anderen Topic. In solchen Fällen man kann den von autocreate erzeugten Eintrag einfach anpassen:
attr DEVICE readingList /dingtian/DEVNAME/out/lwt_availability:.* LWT

=== Bedingte Hash-Rückgaben ===
Manchmal erfolgt zwar die Übergabe eines Klartextes als $EVENT - allerdings nicht in der Form, wie man das in FHEM gerne hätte. Hier als "0" oder "1". Mit etwas Perl und der Rückgabe eines Hashes kann man so etwas beliebig umformen:
attr DEVICE readingList DEVNAME/relay/0:.* { $EVENT ? {state=>'on'} : {state=>'off'} }\
DEVNAME/status:.* { $EVENT ? {LWT=>'Online'} : {LWT=>'Offline'} }
Weiteres Beispiel: Der "state" kommt in Großschreibung und soll in Kleinschreibung geändert werden:
attr DEVICE readingList switchbot/esp32_2/bot/switchbottwo/state:.* { { state => lc $EVENT } }

=== json2nameValue() ===
Mit Hilfe der Funktion json2nameValue() (in Verbindung mit dem attribut ''jsonMap'') lassen sich
* "gute Reading-Namen" auch aus JSON-Payloads erzeugen (2. und 3. Argument)
* unnötige Readings vorab ausfiltern (3., 4. und 5. Argument)
Beispiele für die Verwendung der Argumente 1 bis 3 sind der commandref in der Erläuterung des Attributs ''jsonMap'' bei MQTT2_DEVICE zu entnehmen, die (wie die Argumente 2 und 3 optionalen) Argumente 4 und 5 entsprechen einem Positiv- bzw.- Negativ-Filter.
Wird (übergangsweise!) ''autocreate'' in der ''complex''-Variante eingestellt, werden für alle (bisher nicht bekannten) Topics Einträge wie dieser erzeugt:
attr MQTT2_DVES_9B01BD readingList tele/DVES_9B01BD/STATE:.* { json2nameValue($EVENT,'STATE_',$JSONMAP) }
* Das zweite Argument (''STATE_'') ist ein "Präfix", der allen aus dem JSON erzeugten Readings aus diesem Topic (zunächst) vorangestellt wird. Mit dessen Hilfe läßt sich rekonsturieren, aus welchem Topic die betreffende Information ursprünglich kam. In der Regel ist dies nach der Einrichtung nicht mehr wichtig, und dieses Argument kann auf "nichts" (zwei einfache Quotes) gestellt werden. Allerdings kann es in Einzelfällen sinnvoll sein, Präfixe zu verwenden, um zwischen scheinbar gleichen Werte aus unterschiedlichen Quellen zu unterscheiden. Dies kann man erst abschließend entscheiden, wenn alle von der Gegenstelle gelieferten Daten bekannt sind.
* Das dritte Argument ''$JSONMAP'' kann in der Regel so belassen werden. Dann kann mit Hilfe des Attributs ''jsonMap'' eine Zuordnungstabelle für Namensänderungen für die zu generierenden Readingnamen erzeugt und/oder Werte schlicht gelöscht werden.
<syntaxhighlight lang="perl6">
json2nameValue($EVENT,'STATE_',$JSONMAP,'positiv')
json2nameValue($EVENT,'STATE_',$JSONMAP,'','negativ')
</syntaxhighlight>
* Das vierte Argument ist optional. Es ist ein (Positiv) Filter, der nur Readings in der Liste erscheinen lässt, die diesem Argument entsprechen, im Beispiel oben wären das alle Readings, die den Ausdruck "positiv" enthalten. Das Argument selber ist eine regexp. '''Achtung:''' Wird dieses Argument zusammen mit dem Attribut jsonMap benutzt, so wird zuerst das Mapping auf die neuen Readings-Bezeichnungen ausgeführt und erst dann dieser Filter ausgeführt, d. h. es muss auf die ersetzten Readings-Bezeichnungen gefiltert werden!
* Das fünfte Argument ist ebenfalls optional. Es ist ein (Negativ) Filter. Im obigen Beispiel werden alle Readings, die den Ausdruck "negativ" enthalten, aus den Readings ausgefiltert. Ebenso wie das 4. Argument ist es eine regexp. Im Zusammenspiel mit jsonMap wird hier zuerst der Filter ausgewertet und erst anschließend erfolgt das Mapping auf die neuen Readings-Namen.

=== Auswertung unterbinden ===
Indem man einen Perl-Aufruf festlegt (geschweifte Klammern), dieser aber nichts zurückgibt, kann man bestimmte unerwünschte Readings ausfiltern. Im einfachsten Fall wäre dies:
shellies/DEVNAME/temperature_f:.* {}

Komplexer mit Auswertung der Payload:
STATTOPIC/RESULT:.* { $EVENT =~ m{HSBColor...(\d+),(\d+),(\d+)} ? $2 eq ReadingsVal($NAME,'saturation','unknown') ? return : { saturation=>$2 } : return }

=== Perl ===
Wie am Beispiel der speziellen Funktion <code>json2nameValue()</code> sowie der Hash-Rückgabe bereits dargestellt, ist es möglich, bei der Auswertung auch Perl-Funktionen einzusetzen, und diverse Variablen an diese zu übergeben. Ebenso ist es möglich, eigenen Perl-Code zu verwenden, der z.B. dann längere Zuordnungstabellen, Event-Reduzierungsmechanismen, ... enthalten kann.

== Events optimieren==
Leider senden relativ viele Gegenstellen in ihren Standardeinstellungen sehr viele Daten, auch ohne dass sich etwas geändert hätte. Dies erzeugt uU. in FHEM eine erhebliche Last, so dass es dringend zu empfehlen ist, alle Maßnahmen zu prüfen, durch die dieses Verhalten unterbunden oder vermindert werden kann. Dabei sollte möglichst frühzeitig eingegriffen werden, entsprechend den folgenden Handlungsoptionen: Daten, die die firmware gar nicht erst sendet, muss FHEM nicht am Interface-Modul entgegennehmen. Daten, die direkt am Interface-Modul verworfen werden (ignoreRegexp), muss das Client-Modul nicht auswerten. Readings, die man (an einem bestimmten Device) nicht benötigt, sollte man nicht erzeugen, damit keine [[Eventhandler]] aktiv werden müssen, unveränderte, aber gewünschte Daten müssen nicht unbedingt (immer) Events erzeugen.

=== firmware-Einstellungen ===
Bei manchen firmwares kann man einstellen, ob bzw. wie oft oder aus welchem Anlass Daten gesendet werden sollen. Es wird dringlich empfohlen, bei "gesprächigen" Gegenstellen zu recherchieren, ob und in welcher Weise diese derartige Möglichkeiten bietet. Falls solche nicht vorhanden sind, lohnt es sich, auf den betreffenden Projektseiten nachzufragen, ob es diese Optionen gibt - nicht selten hat sich ein firmware-Autor darüber schlicht noch keine Gedanken gemacht und baut in der nächsten Version ggf. entsprechende Optionen ein?

=== Auswertung unterbinden ===
(s.o. für Topics/Readings, die gar nicht benötigt werden). Dies ist insbesondere auch zu empfehlen, wenn identische Daten zum gleichen Zeitpunkt sowohl als Klartext wie auch in einem JSON-Format übermittelt werden. In solchen Fällen ist es eher zu empfehlen, die JSON-Zweige zu abonnieren und den Rest (ggf. über einen ignoreRegexp-Eintrag) gar nicht auszuwerten.
Doppelungen sollten in jedem Fall vermieden werden!
Grundsätzlich erzeugt jeder Topic eine eigene Event-Loop, mehrere Readings-updates, die aus einer einzigen JSON-Payload abgeleitet werden, erzeugen dagegen eine gemeinsame Event-Loop. Durch solche Maßnahmen läßt sich die Systembelastung deutlich reduzieren.
Für Daten aus JSON-Payloads besteht darüber hinaus die Möglichkeit, diese komplett auszufiltern (siehe jsonMap weiter oben)

=== event-on-change-reading und Co. ===
Da die firmwares häufig recht gesprächig programmiert sind, sollte man auf eine sinnvolle Begrenzung der durch Aktualisierungen verursachten Events besonderen Wert legen. Dazu ist in erster Linie das Attribut [[Event-on-change-reading|event-on-change-reading]] zu bearbeiten und ggf. passende threshold-Werte zu setzen, es empfiehlt sich allerdings, dabei auch zu untersuchen, inwieweit die weiteren, funktional ergänzenden Attribute zu setzen sind:
* [[Event-min-interval|event-min-interval]]
* [[Event-on-update-reading|event-on-update-reading]]
* timestamp-on-change-reading und
* [[Event-aggregator|event-aggregator]]

=== gute Reading-Namen - userReadings ===
Manchmal werden per MQTT Werte übersendet, die so nicht direkt verwendbar sind. Beispiele hierfür wären:
* Batteriespannungen in mV (z.B. bei zigbee2mqtt)
* Farbwerte als Einzelreading (für die Anzeige in FHEM wird aber ein RGB-Wert benötigt)
In diesen Fällen kann man zwar nicht ohne weiteres den Ausgangswert umrechnen lassen, (über externe Module wie readingsChange sehr wohl), aber es ist über den Weg "userReadings" ohne weiteres möglich, passende Readings zu generieren. Dabei sollte aber zur Verringerung der Systembelastung allgemein sowie ggf. falscher Ergebnisse unbedingt darauf geachtet werden, dass diese auch mit einer ''trigger''-Angabe versehen sind!

== setList ==

=== Allgemeines ===
Die setList ist dazu gedacht, Kommandos zu definieren, welche an die Gegenstelle gesendet werden können.

=== Syntax ===
In der Regel besteht jede Zeile aus folgenden, per Leerzeichen getrennten Argumenten:
* einem setter-Namen, ggf. ergänzt durch ein widget (s.u.)
* einem Topic, unter dem die Payload gesendet werden soll und
* der Payload.
Es können diverse Variablen genutzt werden, u.A. auch $EVENT und $EVTPARTx-Elemente, die der Rückgabe (setter-Name und ggf. gesetzter Wert) aus dem jeweiligen "widget" entsprechen.

=== on und off ===
Damit die weitergehenden Befehle wie ''on-for-timer'' aus den [[DevelopmentModuleIntro#X_Set|SetExtensions]] funktionieren, muss ein MQTT2_DEVICE die Befehle "on" und "off" kennen. Diese sollten also - wenn es eine Art "Hauptschalter" gibt - gesondert für diesen Hauptschalter angegeben werden.
Hat ein Gerät mehrerer solcher "Hauptschalter", empfiehlt es sich, für jeden dieser Schalter eine eigene MQTT2_DEVICE-Instanz anzulegen.

==== setStateList ====
Gibt es in einem Device neben dem "Hauptschalter" weitere setzbare Readings (z.B. für Helligkeit und Farbe oder eine Temperatur), empfiehlt es sich v.a. dann, wenn das Gerät den Empfang (bzw. die Ausführung) von Befehlen bestätigt, nur die auf den jeweiligen Hauptschalter bezogenen ''set''-Anweisungen in ''state'' zu schreiben. Diese (z.B. on, off und toggle) wären dann in das ''setStateList''-Attribut aufzunehmen.

==== setExtensionsEvent ====
Will man per SetExtensions realisierte laufende Timer visualisieren, empfiehlt es sich, dieses Attribut zu setzen.

=== widgets ===
In der setList können prinzipiell alle in [[FHEMWEB/Widgets|Widgets]] dargestellten Eingabemöglichkeiten verwendet werden.

=== Perl-Kommandos ===
Eigentlich ist die setList dazu gedacht, eine publish-Anweisungen über das IODev abzusetzen. Da aber generisch auch Perl-Code aufgerufen werden kann, ist dies nicht zwingend, so dass zum einen aus Perl heraus auch mehrfach-Publishes ebenso möglich sind wie beliebige "fhem"-Kommandos, die gar nichts mit MQTT zu tun haben müssen (z.B. das regelmäßige Löschen von evtl. veralteten Readings am betreffenden Gerät). Wird Text zurückgegeben, wird dies als "<topic> <payload>" interpretiert und dies gepublisht, erfolgt gar keine Rückgabe, unterbleibt dies.

== getList ==
Die getList ist dazu gedacht, asynchrone Abfragen an die Gegenstelle zu ermöglichen.
Die Syntax dabei ist
* einem getter-Namen, ggf. ergänzt durch ein widget (s.u.)
* Reading-Name, unter dem die Antwort erwartet wird
* einem Topic, unter dem die Payload gesendet werden soll und
* (optional) der Payload.
Auch hier können diverse Variablen genutzt werden, und/oder das ganze für die Ausführung von Perl-Code genutzt werden.

== periodicCmd ==
Für regelmäßige Aufgaben (mit mind. minütlicher Frequenz) kann eine Liste von get- oder set-Kommandos angegeben werden. Dies kann für regelmäßige Abfragen ebenso genutzt werden wie z.B. zum Löschen veralteter Informationen/Readings.

== Abschließende Aufgaben ==
Um das finale Aussehen des Gerätes zu beeinflussen, stehen dann noch die weiteren allgemeinen Attribute zur Verfügung, die in [[DeviceOverview anpassen]] beschrieben sind.

== Hinweise ==
<references />
[[Kategorie:HOWTOS]]
[[Kategorie:MQTT]]

Alexa-Fhem

2020-02-02T11:16:29Z

Dora71: /* Alexa-Fhem als Service (systemd) installieren */

{{Randnotiz|RNTyp=r|RNText='''ACHTUNG''': Diese Seite beschreibt nicht mehr exakt die jeweils nötigen Amazon Seiten. Es ist etwas Interpretation und Verständnis nötig.

Für alle, die neu einsteigen und sich mit dem FHEM Vereinsserver als Proxy anfreunden können, empfiehlt es sich hier: [[FHEM Connector für Amazon Alexa]] einzusteigen.}}

'''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 weitergehende Informationen über die Reaktion von Alexa enthält und Rückmeldung an Amazon erlaubt.
*Skill (engl. für Fertigkeit, Können) ist die Bezeichnung für eine per Spracherkennung zu bedienende Funktionalität des Alexa-Systems, z.B. zur Nachrichtenansage, 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_8.x | sudo -E bash -
sudo apt-get install -y nodejs
</syntaxhighlight>

===node.js updaten===
Um node.js aus einer vorherige Installation zu updaten (Version 4 ist deprecated und in AWS Amazon nicht mehr unterstützt):
<syntaxhighlight lang="bash" style="width:50%;">
# Zuerst alexa-fhem stoppen, dann
sudo apt-get remove nodejs
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs
sudo npm install npm@latest -g

#--> in Amazon Konsole NodeJs auf 8.1 umstellen (Funktion in AWS Konsole editieren, im Pulldown-Menü "Runtime" eine neuere Version auswählen, und speichern)
#--> Raspi Reboot (vielleicht nicht nötig)
</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. 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. 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>. 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. 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, sonst die Zeile löschen!
# ''nat-upnp'' -> wenn nat-upnp verwendet werden soll: ''true'', sonst die Zeile löschen!
# ''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 a) Offenes fhem - System ohne Absicherung:
{
"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"
}
]
}

Beispiel b) Abgesichertes fhem - System mit TLS/SSL und HTTP Basic-Authentication:
{
"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",
"auth": {"user": "fhemuser", "pass": "fhempassword"},
"ssl": true,
"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 ====
Hierbei muss man zunächst herausfinden, welche der folgenden Startvarianten sein LINUX - OS zum Einsatz kommen:
initd.d oder systemd.

Auf keinen Fall darf man "sicherheitshalber" beide Varianten installieren, dies zu Fehler(-meldungen) führt.

===== Vorgehen bei init.d =====
Diese Variante kommt unter anderem auf dem Raspberry Pi mit dem OS-Varianten "Wheezy" zum Einsatz

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>

===== Vorgehen bei systemd =====
Diese Variante kommt unter anderem auf dem Raspberry Pi ab/seit der OS-Variante "Jessie" zum Einsatz

Bei systemd Systemen funktioniert das obengenannte vorgehen leider nicht, man kann das gleiche aber mit dem Modul
[https://forum.fhem.de/index.php/topic,79952.0.html 98_serviced.pm - systemd und initd Dienste steuern] umsetzen.
Wichtig ist das der User unter dem alexa ausgeführt wird ohne Passwort abfrage sudo ausführen darf, dazu muss er in der <code>/etc/sudoers</code> eingetragen werden, z.b. so <code>fhem ALL=(ALL) NOPASSWD: ALL</code>

Sollte es dann nicht funktionieren kann das an einem Gruppen eintrag unterhalb der User definition in der <code>/etc/sudoers</code>, in diesem Fall den user am ende der <code>/etc/sudoers</code> eintragen, dann sollte es funktionieren

==== 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 style="width:75%;" lang="bash">
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

Sollte sich der Service nicht starten lassen und endet die Ausgabe ähnlich wie hier:
<code>Feb 02 09:47:25 inet alexa[2738]: STDIN EOF</code>
kann eine Anpassung der ExecStart Zeile aus der alexa.service Datei helfen:
ExecStart=/opt/fhem/alexa-fhem/bin/alexa --dockerDetached -U /home/alexa/.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 [[Datei:Amazon Developer.jpg||200px]]
# Anmeldedaten eingeben [[Datei:LogIn.jpg||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'' [[Datei:Apps1.jpg|200px]]
# Anschließend auswählen ''Security Profiles'' [[Datei:Security.jpg|200px]]
# Auswählen ''Create a New Security Profile'' aus [[Datei:Newsecurity.jpg|200px]]
# Dann einen Namen und eine Beschreibung für das Profil eingeben und mit ''Save'' bestätigen [[Datei:SecurityName.jpg|200px]]
# Anschließend den die Daten unter ''Gneral'' merken oder Kopieren [[Datei:SecurityGenerl.jpg|200px]]
# Im Anschluß daran auf ''Web Settings'' klicken und dort auf ''Edit'' [[Datei:WebSettings.jpg|200px]]
# Und nun die im Bild gezeigten Daten eintragen [[Datei:WebSettingsDaten.jpg|200px]]
## https://layla.amazon.co.uk/api/skill/link/xxx
## https://pitangui.amazon.com/api/skill/link/xxx
## https://layla.amazon.com/api/skill/link/xxx
# Das xxx muss hierbei durch den Wert ersetzt werden, der in den beiden Abschnitten SmartHome Skill anlegen bzw. Custom Skill anlegen jeweils unter Punkt 4 (Seite Configuration) bei Redirect Urls am Ende der URLs angezeigt wird
# Im anschluß daran oben auf ''Login with Amazon'' [[Datei:LoginwithAlexa.jpg|200px]]

===== Login with Amazon =====
{{Randnotiz|RNTyp=[g|Info]|RNText=Hier wird beschrieben, wo ''Client Id'' und ''Client Secret'' zu finden sind}}
# In der neu geladenen Seite im Dropdown Menü das vorher angelegte Profil unter ''Select a Security Profil'' auswählen und mit ''Confirm'' bestätigen [[Datei:LoginwithAlexaSelect.jpg|200px]]
# Im folgenden Fenster die Adresse https://www.amazon.com/gp/help/customer/display.html?nodeId=468496 eingeben und mit ''Save'' bestätigen. '''Todo Erklärungsbedarf: WARUM diese Adresse''' [[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 [[Datei:Developer.amazon.com-13-login_with_amazon_-_web_settings.png|200px]]

==== Skills bearbeiten (Gilt für den SmartHome wie auch den Customer Skill)====
# Im Menü den Punkt ''ALEXA'' auswählen und anschließend im Dropdown Menü ''Alexa Skills Kit'' auswählen [[Datei:AlexaSkill.jpg|200px]]

===== SmartHome Skill anlegen =====
# Rechts ''Create Skill'' auswählen [[Datei:AlexaSkillCreate.jpg|200px]]
# Auf der folgenden Seite die folgenden Daten eingeben und dann mit ''Next'' bestätigen:
#:* ''Skill Name'' -> beliebiger Name, z.B. "MySmartHome Basic")
#:* ''Default Language'' -> ''German''
#:* ''Choose a model to add to your skill'' -> ''SmartHome '' anklicken
#:* ''Anschließend rechts oben auf ''Create Skill'' [[Datei:AlexaSkillCreateSmart.jpg|200px]]''
# Nun auf die Seite https://signin.aws.amazon.com/ wechseln und dort einloggen [[Datei:AWSAnmelden.jpg|200px]]
# Nach dem Login links oben auf ''Services'' klicken und anschließend auf ''Lambda'' [[Datei:AWSLambda.jpg|200px]]
# Auf der ''Lambda'' Seite "Funktion' auswählen links im Menü und dann rechts auf ''Funktion erstellen'' klicken [[Datei:LamdbaFunktion.jpg|200px]]
# Auf der Seite ''Funktion erstellen'' dann auf ''Ohne Vorgabe erstellen' klicken''
#:* Unter ''Name'' einen Beliebigen Namen eingeben
#:* Bei ''Laufzeit'' ''Nodejs 8.10'' auswählen
#:* Unter ''Rolle'' ''Erstellen einer benutzerdefinierten Rolle'' auswählen, im anschluß daran sollte sich automatisch ein neues Fenster öffnen, in diesem alles unverändert lassen und auf ''Allow'' klicken wodurch sich das Fenster wieder schließen sollte [[Datei:IAM.jpg|200px]]
#:*Jetzt noch rechts unten auf ''Funktion erstellen klicken'' [[Datei:OhneVorgabe.jpg|200px]]

# Auf der jetzt geöffneten Seite rechts oben die ''arn'' Nummer aufschreiben/kopieren und links aus dem Menü ''Alexa Smart Home'' hinzufügen [[Datei:Arn.jpg|200px]]
# Unten auf der Seite unter ''Auslöser konfigurieren'' muss die Skill ID eingetragen werden, diese findet man im developer account unter dem Skill. [[Datei:Auslöser.jpg|200px]]
# Anschließend noch rechts unten auf ''Hinzufügen'' klicken und danach rechts oben auf ''Speichern''

# Nun auf ''Test'' (Bezeichnung im Screenshot) klicken und unten auf der Seite unter ''Funktionscode'' den vorhanden Code löschen und den Code aus der ''Lambda.js'' welche sich in dem ''alexa-fhem-0.4.4'' Paket befindet einfügen [[Datei:Arn2.jpg|200px]]
 [[Datei:Code.jpg|200px]]
# Im Code müsst ihr den ''Hostname'' anpassen, also eure DynDns z.b. einfügen, anschließen rechts oben wieder auf ''Speichern''

# Nun wieder zurück in den Alexa developer Account und hier folgende Daten eintragen
{{Randnotiz|RNTyp=r|RNText=Es funktioniert nur noch die v3 api (v2 ist deprecated). Die Version hierfür gibt es im {{Link2Forum|Topic=81324|LinkText=Forum}}. bitte die hinweise dort lesen und beachten.}}
#:* ''Payload Version'' -> ''v3(preferred)'' auswählen 
#:* ''Default endpoint'' -> Hier die ''arn'' Nummer von oben eintragen/einfügen
#:* Dann den Haken setzen bei ''Europe, India'' und nochmals die ''arn'' eintragen und anschließend rechts oben auf ''Save''
# Links im Menü ''Account Linking'' auswählen und dort folgende Daten eintragen
#:* ''Authorization URI'' -> ''https://www.amazon.com/ap/oa''
#:* ''Access Token URI'' -> ''https://api.amazon.com/auth/o2/token''
#:* ''Client ID'' -> ''Eure Client ID, fängt mit amzn......an'', zu finden unter ''https://developer.amazon.com'' -> '' Apps & Services'' -> ''Security Profiles'' -> Profil auswählen -> ''Web Settings''
#.* ''Client Secret'' -> ''Euer Client Secret'', siehe ''Client ID''
#:* ''Scope'' -> ''Add Scope'' auswählen und ''profile:user_id'' (wörtlich 1:1 eintragen) eintragen
#:* ''Redirect URLs'' -> Diese 3 Adressen merken/kopieren
# Alles andere auf dieser seite kann gleich bleiben, jetzt noch rechts oben wieder auf ''Save'' klicken [[Datei:Account.jpg|200px]]

# Anschließend wieder zurück zum ''Amazon developer Account'' https://developer.amazon.com , dort wieder das ''Security Profile'' aufrufen und die drei Links unter ''Allowed Return URLs'' (wo eingangs am Schluss 3 XXX gesetzt wurden) mit den Links von Oben ''Redirect URLs'' ersetzen
# Nun geht es weiter in der ''Amazon Alexa developer Konsole'' https://developer.amazon.com/alexa/console/ask wo oben auf ''Distribution'' geklickt werden muss.
# Hier sind alle angaben Freiwillig bzw. können Frei gewählt werden bis auf die ''Privacy Policy URL'' , diese muss eingetragen werden, anschließend links unten auf ''Save and continue'' [[Datei:German.jpg|200px]]

# Auf der kommenden Seite ''Privacy & Compliance'' entsprechend anklicken und wieder unter auf ''Save and continue''
# Unter ''Availability'' alles so lassen und wieder auf ''Save and continue''
# Nun den Alexa Service auf dem Fhem Rechner neustarten, den Skill in der Alexa App aktivieren und nach geräten suchen lassen

===== Custom Skill anlegen =====
<ol>
<li> Oben rechts ''Add a New Skill'' auswählen [[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" [[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: <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 [[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.
 [[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 [[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> [[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 [[Datei:Aws.amazon.com-01-site.png|200px]]
# Anmeldedaten eingeben [[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 [[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 [[Datei:Aws.amazon.com-04-get_started_now.png|200px]]
# Den Blueprint ''Blank function'' auswählen [[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 [[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 [[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. [[Datei:Aws.amazon.com-07-configure_function.png|200px]]
# Auf der Übersichtsseite dann ''Create function'' anklicken [[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 [[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 [[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 [[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 [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Oben rechts ''Meine Skills'' bzw. ''Ihre Skills'' auswählen [[Datei:Alexa.amazon.de-03-meine_skills.png|200px]]
# In der Liste der Skills sollte das angelegte FHEM Skill angezeigt werden. Dieses anklicken [[Datei:Alexa.amazon.de-02-liste_skills.png|200px]]
# Oben Rechts in den Details des Skills auf ''Skill aktivieren'' klicken [[Datei:Alexa.amazon.de-04-skill_details.png|200px]]
# In dem neu geöffneten Fenster die Autorisierung bestätigen [[Datei:Alexa.amazon.de-05-amazon_auth.png|200px]]
# Anschließend sollte die Verbindung erfolgreich aufgebaut worden sein [[Datei:Alexa.amazon.de-06-success.png|200px]]

=== Geräte ===
# Auf http://alexa.amazon.de anmelden
# Auf ''Smart Home'' klicken [[Datei:Alexa.amazon.de-01-startseite.png|200px]]
# Anschließend den Punkt ''Geräte suchen'' anklicken [[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 UnityMedia 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

==Weitergehende Informationen==
*[[Alexa_und_Mappings]]
*[[Alexa_Tipps_und_Kniffe]]
[[Kategorie:HOWTOS]]
[[Kategorie:Sprachsteuerung]]

FTUI Widget Tts

2019-03-03T14:20:52Z

Dora71: /* Attribute */ Beispiel für Stimmenauswahl korrigiert

Das [[{{PAGENAME}}|TTS Widget]] ist ein Widget für [[FHEM Tablet UI]], mit dem man eine Sprachansage ausgeben kann. Damit lassen sich z.B. Warnungen ausgeben oder der Wetterbericht ansagen.

==Attribute==
{|class="wikitable"
!Attribut
!Beschreibung
!Standard-Wert
!Beispiel
|-
|'''data-get'''||Reading, aus dem der angesagte Text ausgelesen wird||state||data-get="state"
|-
|'''data-voice'''||Auswahl der Stimme||Deutsch Female||data-voice="UK English Male" data-voice="Chinese Female"
|-
|'''data-pitch'''||Tonhöhe (Bereich 0 bis 2)||1.0||
|-
|'''data-rate'''||Sprachgeschwindigkeit (Bereich 0 bis 1.5)||1.0||
|-
|'''data-volume'''||Lautstärke (Bereich 0 bis 1)||1.0||
|}

==CSS Klassen==
Keine

==Hinweise==
* Nach der Ersteinrichtung oder Änderung einer Stimme kann die erste Sprachausgabe verzögert werden, da die Daten der Stimme über das Internet geladen werden müssen.
* Um eine kurze Pause zwischen zwei Worten zu erzeugen, z.B. um Hinweise deutlicher erscheinen zu lassen kann das Komma verwendet werden: set speak Bewegung,Haustür
* Im iOS-Umfeld werden Sounds (und auch Videos) nicht immer automatisch abgespielt. Nähere Details [https://developers.google.com/web/updates/2017/09/autoplay-policy-changes hier]. Um das tts-Widget auf einem Apple-Tablet nutzen zu können, muss man die Seite (..../fhem/ftui/) zum Homebildschirm hinzufügen.

==Beispiele==
===Einfache Ansage===
In FHEM einen Dummy definieren:

<syntaxhighlight lang="html">
define speak dummy
</syntaxhighlight>

Auf der gewünschten FTUI Seite ganz am Anfang nach dem <body> Tag das Widget einbauen:

<syntaxhighlight lang="html">
<div data-type="tts" data-device="speak"></div>
</syntaxhighlight>

In FHEM in der Eingabezeile eingeben:

<syntaxhighlight lang="html">
set speak Guten Morgen
</syntaxhighlight>

Jetzt sollte das Tablet "Guten Morgen" sagen. Das ganze lässt sich jetzt z.B. in notifys oder at-Befehle einbauen.

===Zeitansage===
Dummy definieren und Widget einbauen wie in Beispiel 1

In FHEM ein at definieren:

<syntaxhighlight lang="html">
defmod EveryHour at +*01:00:00 {fhem ("set speak Es ist ".strftime('%H', localtime)." Uhr");}
attr EveryHour alignTime 00:00
</syntaxhighlight>

Zu jeder vollen Stunde wird jetzt die Zeit angesagt.

===Einstellbare Zeitansage===
Montag bis Freitag wird zu einer einstellbaren Zeit selbige angesagt.
<syntaxhighlight lang="html">
defmod Sprachausgabe dummy
attr Sprachausgabe readingList Ist_aktiv
attr Sprachausgabe userReadings Ist_aktiv

defmod Sprachausgabe_Hauptschalter dummy
attr Sprachausgabe_Hauptschalter setList on off

defmod Sprachbefehl at *07:00 { if ( !($we) && Value("Sprachausgabe_Hauptschalter") eq "on" ) {fhem("set Sprachausgabe Es ist [Sprachbefehl:TIMESPEC]")}}
</syntaxhighlight>

<syntaxhighlight lang="html">
<div data-type="tts" data-device="Sprachausgabe"></div>

<div data-type="checkbox" data-device="Sprachausgabe_Hauptschalter"
class="inline top-space" data-on-background-color="SeaGreen"></div>
<div data-type="label" class="inline" data-limits-get="Sprachausgabe_Hauptschalter:STATE" data-states='["on","off"]' data-colors='["SeaGreen","grey"]'>Zeitansage Mo ... Fr um</div>

<div data-type="datetimepicker"
data-device="Sprachbefehl"
data-datepicker="false"
data-step="5"
data-format="H:i"
data-get="TIMESPEC" data-set-value="*$v" data-cmd="modify"
data-limits-get="Sprachausgabe_Hauptschalter:STATE" data-states='["on","off"]' data-colors='["SeaGreen","grey"]'
class="inline"></div>
</syntaxhighlight>
[[Datei:Zeitansage.png]]

Teile dieses Codes stammen aus [[FTUI_Beispiel_Datetimepicker_f%C3%BCr_Timer]].

==Links==
[https://responsivevoice.org/faq/ ResponsiveVoice F.A.Q.]

[[Kategorie:FHEM Tablet UI|TTS]]
[[Kategorie:Akustische Ausgabe]]

SIGNALduino

2019-02-02T10:49:29Z

Dora71: /* Unterstützte Geräte */ Conrad Wetterstation KW9110 Details ergänzt

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===
{{Randnotiz|RNTyp=r|RNText=Viele user berichten über Empfangsprobleme bei Nutzung des XY-MK-5V; es wird ausdrücklich empfohlen, ein anderes Empfangsmodul zu nutzen!}}
[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101release.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanorelease.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_prominirelease.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_miniculcc1101release.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_radinocc1101release.hex
</code>

SIGNALESP_331rc4.bin (mit cc1101) für einen ESP8266 mit 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALESP/releases/download/3.3.1RC4/SIGNALESP_331RC4_1M.bin
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

Die Haupt-Seite für Firmware-Releases findet sich unter https://github.com/RFD-FHEM/SIGNALDuino/releases/ .

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E S||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0.3
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!
}}

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

STV

2019-01-25T06:42:24Z

Dora71: Link zur Dokumentation im Forum eingefügt

{{Infobox Modul
|ModPurpose=Client for Samsung TV
|ModType=x
|ModFTopic=82890
|ModForumArea=Multimedia
|ModTechName=70_STV.pm
|ModOwner=Zwiebel ({{Link2FU|103|Forum}}/[[Benutzer Diskussion:Plin53177|Wiki]])
}}

Das Modul '''STV''' ermöglicht die Steuerung von Samsung Fernsehern und Bluray-Playern.

== Voraussetzungen ==

=== Historie===

Im Ursprung wurde das Modul 70_STV.pm entwickelt, welches bis F-Serie funktionieren sollte. Das Modul ist im Standardumfang von FHEM enthalten.
Für die neue Zugriffsmethode per websocket ab K-Serie wurde das Modul so erweitert, dass per Python-Skript samsungctl die TV's problemlos ansteuerbar sind. Die größten Probleme scheinen die H- u. J-Serie zu bereiten. Diese nutzen neben websocket zusätzlich eine Verschlüsselung. Für den Zugriff wurde ein Python-Skript nach Perl übersetzt, das wiederum in die nicht offizielle STV eingebunden wurde. Schließlich wurde noch die Möglichkeit der Ausgabe von Medien-Streams für alle Serien über DLNA eingebaut. Die aktuelle inoffizielle Version, in der ALLE features enthalten sind, findet Ihr [https://forum.fhem.de/index.php/topic,57595.msg770704.html#msg770704 >>>hier<<<] neben der zusammengefassten Doku [https://forum.fhem.de/index.php/topic,82890.msg756500.html#msg756500 >>>hier<<<].

Neben den unterschiedlichsten Servern in der Firmware der TV's gibt es auch Unterschiede bei der Berechtigungssteuerung. Nachfolgend findet Ihr relevante Informationen zu den unterschiedlichen Serien.

===Steuerungsmöglichkeiten (allgemein)===

Steuerungsmöglichkeiten(Voraussetzung also eine LAN- oder WLAN-Verbindung u. berechtigter Zugriff) aus FHEM heraus sind
* senden von remote control Befehlen an den TV
* Bildschirmnachrichten wie z.B. InfoScreen bei eingehendem Anruf
* Abspielen von Video, Audio, Foto Konserven

===B/C/D-Series(vor 2012) ===

Da diese TV's schon relativ alt sind hier nur eine Zusammenfassung von Funktionen, die sich je nach Modell unterscheiden:
* Älteste Modelle(B-Serie ?): mute, volume, call, sms, date über port 52235 UPNP/SOAP
* Jüngere Modelle(C-/D-Serie): sämtliche remote control commands port über 55000, keine Bildschirmnachrichten ?, Port 7676 u. service urn:samsung.com:service:MainTVAgent2:1 nicht verfügbar ?

===E-Series(2012)===
sämtliche remote control commands über port 55000; Definition mit FHEM-Standard-Modul STV und Port '''55000'''.

'''Zugriffsberechtigung:'''
Einstellungen findet man unter:
Menü->Netzwerk->AllShare-Einstellungen->Liste der registrierten Endgeräte->Zulassen|Verbieten|Aus der Liste löschen

'''Registrierung:'''
Bei erstmaligem Zugriff eines Endgeräts erscheint auf dem TV ein pop-up: Neues Netzwerkgerät erkannt......: Zulassen|Verbieten

Eine Pin-Eingabe ist nicht erforderlich. Eine Einmalige Registrierung berechtigt für den Dauerbetrieb des Endgeräts, wobei (bei mir)
das Gerät "Perl Samsung Remote" mit der IP 127.0.0.1 angelegt wurde und mit dieser Zugangsberechtigung nun ALLE devices über
FHEM für die Steuerung zugelassen sind.

'''Bildschirmnachrichten:'''
über port 7676 ist UPNP/SOAP (z.B. Browseraufruf mit InfoDisplay f. Anruferinfo) verfügbar. Ebenso ist die Medienausgabe per DLNA möglich
nur mit der inoffiziellen Version !)

'''Bestätigte Modelle:'''

ganze Serie

===F-Series(2013) ===
Vermutlich kein Unterschied zur E-Serie.

===H-Series(2014) ===

Mit dieser Serie führte Samsung die verschlüsselte Kommunikation über websockets und Port 8000 ein. Für die Zugriffsberechtigung muss einmalig das Perl-Skript
regapp.pl aus diesem [https://forum.fhem.de/index.php/topic,57595.msg748445.html#msg748445 Post] (https://forum.fhem.de/index.php/topic,57595.msg748445.html#msg748445) zur Erzeugung des session-key ausgeführt werden.

'''Notwendige Vorbereitung:'''

1. Erstellen der Datei samsung_session_key.txt mit dem Perl-Skript regappl.pl (Pin-Eingabe über FB des TV erforderlich)
2. Bei ERFOLG(lieber mal reingucken ;)) die Datei in das FHEM-Verzeichnis kopieren, wo auch die fhem.cfg liegt
3. Manchen wird noch das Perl-Modul Crypt::Rijndael fehlen. Das installiert man(für Debian):
a) sudo apt-get update
b) sudo apt-get upgrade
c) sudo apt-get install libcrypt-rijndael-perl
d) ein reboot schadet an dieser Stelle nie
4. define MeinTV STV MEINE_IP wse

'''Zugriffsberechtigung:'''
Menü/Netzwerk/Multimedia-Geräteeinstellungen. Dort kann man "SmartDevices" erlauben, verbieten und löschen.
- einmal verboten und der Key ist unbrauchbar. Also neu pairen.
- die IP scheint egal zu sein. Mit den passenden session_key und session_id kann man von jedem Rechner aus zugreifen.

'''Registrierung:'''
Mittlerweile ist das Perl-Skript do_v2.pl von Raymund auch in das inoffizielle70_STV eingebunden. Das Skript regapp.pl muss nach wie vor einmalig(?) für die Schlüsselerzeugung ausgeführt werden. Bitte Vorgehensweise im vorgenannten Post beachten !

'''Bildschirmnachrichten:'''
Bildschirmnachrichten bzw. generelle Medienausgabe über DLNA möglich

'''Bestätigte Modelle:'''
UE-55H6740SV, UExyHU6900, UE40H6400, UE55H6700

Info des Python-Skript-Autors:
'''Note''' that the following TV Models are most likely incompatible for one reason or another H4xxx, H510x, H52xx, H53x3, H5403, H6003, H61x3, H6201, H6203, S9, S9C

===J-Series(2015) ===
Die verschlüsselte Kommunikation erfolgt über websockets und Port 8000. Für die Zugriffsberechtigung muss einmalig das Perl-Skript
regapp.pl aus diesem [https://forum.fhem.de/index.php/topic,57595.msg748445.html#msg748445 Post] (https://forum.fhem.de/index.php/topic,57595.msg748445.html#msg748445) zur Erzeugung des session-key ausgeführt werden.

'''Notwendige Vorbereitung:'''

1. Erstellen der Datei samsung_session_key.txt mit dem Perl-Skript regappl.pl, und zwar auf dem Rechner, der später den Fernseher steuern soll.
In dieser Serie erzeugt der Fernseher die Pin, diese wird von regappl.pl abgefragt
2. Bei Erfolg die Datei in das FHEM-Verzeichnis kopieren (dort wo auch die fhem.cfg liegt). Umbenennen,so dass es den unter Punkt 4 vewendeten Devicenamen (beispielsweise MeinTV) im eigenen Namen hat. Zugriffsrechte setzen mit
chown fhem:dialout samsung_session_key.txt
mv samsung_session_key.txt MeinTV_session_key.txt
3. Ggf. das Perl-Modul Crypt::Rijndael nachinstallieren mit
sudo apt-get install libcrypt-rijndael-perl
4. Fernseher in FHEM definieren als
define MeinTV STV <ip-adresse des Fernsehers> 8000

'''Zugriffsberechtigung:'''
Auf dem Fernseher unter Menü/Netzwerk/Multimedia-Geräteeinstellungen. Dort kann man "SmartDevices" erlauben, verbieten und löschen.

'''Bildschirmnachrichten:'''
Bildschirmnachrichten bzw. generelle Medienausgabe über DLNA möglich

'''Bestätigte Modelle:'''
UE55UJ7000, UE48JU7590(THKMDEUC-1452)

Info des Python-Skript-Autors:
'''Note''' the the following TV Models are most likely incompatible for one reason or another
J4xxx, J50xx, J51xx, J52xx, J53xx, UNxxJ6200, J6201, J6203, J620D

Tizen 2.3(nicht aber UJ4300, UJ5300)

Spätere Modelle wie K-Serie ?

===K-Series(2016)===

Der Port ist durch Samsung auf 8001 geändert. Eine Verschlüsselung gibt es nicht mehr. Dominik hat den Aufruf des im Netz verfügbaren Python-Skripts samsungctl in das STV-Modul integriert. Die Installation des Python-Skripts samsungctl ist zusätzlich erforderlich.

Für die Definition des TV in FHEM ist anstatt des tatsächlichen Ports "ws" anzugeben.

'''Notwendige Vorbereitung:'''
1. sudo apt-get update
2. sudo apt-get upgrade
3. pip installieren. wheezy bietet nur eine V. 1.1, von der im Inet abgeraten wird. Deshalb habe ich die v 9.0.1 mit
wget https://bootstrap.pypa.io/get-pip.py geladen.
4. sudo python get-pip.py (ohne sudo gab es eine exception meldung)
5. sudo pip install websocket-client
6. sudo pip install samsungctl (das package wird dann automatisch heruntergeladen und installiert)
7. das File /usr/local/lib/python2.7/dist-packages/samsungctl/__main__.py editiert
o except FileNotFoundError: in except: ändern
o Folgende Zeile löschen directories.append(os.path.join(os.getenv("HOME"), ".config"))
8. Damit das geänderte 70_STV lief, musste ich einerseits "use Blocking;" am Anfang des Moduls hinzufügen und scheinbar ist der /usr/local/bin bei mir nicht bekannt, so dass ich den einfachen Aufruf von samsungctl in /usr/local/bin/samsungctl ändern musste.

Das Senden der üblichen remote control commands funktioniert.

'''Definition in FHEM:'''
anstatt einem numerischen Port ist der String ws einzugeben

'''Zugriffsberechtigung:'''
* Popup mit Bestätigung
* dann unter Einstellungen -> Allgemein -> Geräteverbindungsmanager findet man eine Geräteliste (da kann man die einzelnen zugriffsberechtigten Geräte auch wieder rausschmeissen) und man kann sogar die Zugriffsbenachrichtigung verändern (nur einmal od. jedes Mal).

'''Bildschirmnachrichten:'''
Bildschirmnachrichten bzw. generelle Medienausgabe über DLNA möglich

'''Bestätigte Modelle:'''
ganze Serie ?: UE40K5579, UE55KU6170, UE65ks7090

Tizen 2.4 (nicht aber: UBD-K8500, UBD-KM85C, UBD-KM85)

===M-Series(2017)===

Vermutlich kein Unterschied zur K-Serie. :-\

'''Bestätigte Modelle:'''
ganze Serie ?

Tizen 3.0(UMU6100 Tizen 2.4)

===Q-Series(2018)===

Mal sehen, was uns da wieder erwartet. Vorstellung wohl im Februar 2018.

Tizen 4.0

== Installation ==
=== Erste Schritte ===

(für Version aus dem FHEM Repository)

Device in FHEM anlegen:

:<code>define <name> STV <ip></code>

Danach sollte das Device bei eingeschaltetem Fernseher oder Bluray-Player in den Status '''opened''' gehen.

Ist dies nicht der Fall ist die Modellreihe zu ermitteln. Am Command-Prompt kann mittels nmap ermittelt werden welche Ports geöffnet sind (xxx.xxx.xxx.xxx ist in diesem Beispiel die IP-Adresse des Samsung-Gerätes)

<code>nmap xxx.xxx.xxx.xxx</code>
<code>Starting Nmap 6.47 ( http://nmap.org ) at 2018-02-18 09:22 CET</code>
<code>Nmap scan report for xxx.xxx.xxx.xxx</code>
<code>Host is up (0.0095s latency).</code>
<code>Not shown: 997 closed ports</code>
<code>PORT STATE SERVICE</code>
<code>7676/tcp open imqbrokerd</code>
<code>8080/tcp open http-proxy</code>
<code>8443/tcp open https-alt</code>

anschließend die High Ports scannen

<code>nmap -sT -p50000-65534 xxx.xxx.xxx.xxx</code>
<code>Starting Nmap 6.47 ( http://nmap.org ) at 2018-02-18 09:25 CET</code>
<code>Nmap scan report for xxx.xxx.xxx.xxx</code>
<code>Host is up (0.015s latency).</code>
<code>Not shown: 15532 closed ports</code>
<code>PORT STATE SERVICE</code>
<code>52345/tcp open unknown</code>
<code>55000/tcp open unknown</code>
<code>55001/tcp open unknown</code>

Jetzt gilt es folgende Fälle zu unterscheiden:
* Port 52235 wird ausgewiesen
: define <device> STV <ip>
: ohne Portangabe

Jetzt gilt es folgende Fälle zu unterscheiden:
* Port 55000 wird ausgewiesen
: define <device> STV <ip>
: ohne Portangabe

Bei dem aktuellen Modul aus dem FHEM-Repository kann kein Port mitgegeben werden. Die Definition kann dann nachträglich im angelisteten Device durch Bearbeitung der DEF erfolgen. Die IP-Adresse um den Port ergänzen
xxx.xxx.xxx.xxx 55000
und speichern.

===Alternative: Aktuelle Version aus dem Forum===

Die im Anhang zu [https://forum.fhem.de/index.php/topic,57595.msg770704.html#msg770704 Post #298] vom 21.2.2018 publizierte Fassung ist in der Entwicklung, bietet aber weitergehende Funktionen.

Diese dort gepostete Version des 70_STV sollte für ALLE Serien die Ausgabe von Bildschirmnachrichten per DLNA ermöglichen. Bitte lest den Post, um auf dem laufenden zu bleiben. Wenn die Version fertig ist wird sie hier dokumentiert.

== Anwendung ==
=== Attribute ===

''Basics & Allgemeines''
* '''MAC'''
: nur bei Bedarf: die IP-Adresse des Rechners auf dem FHEM läuft. Sollte das zu steuernde Gerät nicht reagieren und im FHEM-Log "[STV] mymac" mit "invalid format" auftauchen, dann bitte dieses Attribut setzen.

* '''fork'''
: enable|disable

* '''setWhenOffline'''
: execute|ignore Ist der Fehnseher ausgeschaltet hängt ein Set-Befehl, bis das Modul realisiert, dass der Fernseher ausgeschaltet ist. Mit ''setWhenOffline ignore'' lässt sich dieses Verhalten verhindern.

''nur in aktueller Entwicklerversion''
* '''callerURI '''
: callerURI ist für die Nutzung von Anruferinfo gedacht.

* '''screenURI'''
: Über screenURI und einen Dummy kann z.B. ein InfoDisplay von FHEM auf dem TV ausgeben. In die URIs wird der jeweilige Pfad zum Bild eingetragen(also so, wie man es bereits beim Test des DLNAClient gemacht hatte).

Durch die Definition der jeweiligen URI, wurde dynamisch das Befehlsset des TV-devices erweitert. Für den Aufruf der callerURI steht der neue set-Befehl caller und für screenURI entsprechend screen zur Verfügung.

=== Set ===

Das Modul kennt derzeit folgende Commands

''Basis-Commandset'' (bei Nutzung von Port 52235)

* set <name> '''mute''' {on|off]
: schaltet den Ton ein/aus

* set <name> '''volume''' <nummer>
: Lautstärke ändern. <nummer> kann zwischen 0 und 100 liegen

* set <name> '''call''' <von_name> <von_number> <an_name> <an_number>
: <von_name> = Name des Anrufers
: <von_number> = Nummer des Anrufers
: <an_name> = Name des Anzurufenden
: <an_number> = Nummer des Anzurufenden

* set <name> '''sms''' <von_name> <von_number> <an_name> <an_number> <text>
: <von_name> = Name des Anrufers
: <von_number> = Nummer des Anrufers
: <an_name> = Name des Anzurufenden
: <an_number> = Nummer des Anzurufenden
: <text> = SMS Nachrichtentext

* set <name> '''date''' <start_datum> <start_zeit> <an_name> <an_number> <betreff> <ende_datum> <ende_zeit> <ort> <nachrichtentext>
: Termineinladung mit
: <start_datum> = Startdatum
: <start_zeit> = Startzeit
: <an_name> = Name des Einzuladenden
: <an_number> = Nummer des Einzuladenden
: <betreff> = Betreff der Einladung
: <ende_datum> = Enddatum
: <ende_zeit> = Endzeit
: <ort> = Treffpunkt
: <nachrichtentext> = Text der Einladung

''Erweitertes Commandset'' (bei Nutzung von Port 55000)

* set <name> '''connect'''
: Mit dem Fernseher/Player verbinden

* set <name> '''button'''
: button ist ein Befehl der Fernbedienung aus dieser Liste:
: [ 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 11 | 12 | 3SPEED | 4_3 | 16_9 | AD | ADDDEL | ALT_MHP | ANGLE | ANTENA | ANYNET | ANYVIEW | APP_LIST | ASPECT | AUTO_ARC_ANTENNA_AIR | AUTO_ARC_ANTENNA_CABLE | AUTO_ARC_ANTENNA_SATELLITE | AUTO_ARC_ANYNET_AUTO_START | AUTO_ARC_ANYNET_MODE_OK | AUTO_ARC_AUTOCOLOR_FAIL | AUTO_ARC_AUTOCOLOR_SUCCESS | AUTO_ARC_CAPTION_ENG | AUTO_ARC_CAPTION_KOR | AUTO_ARC_CAPTION_OFF | AUTO_ARC_CAPTION_ON | AUTO_ARC_C_FORCE_AGING | AUTO_ARC_JACK_IDENT | AUTO_ARC_LNA_OFF | AUTO_ARC_LNA_ON | AUTO_ARC_PIP_CH_CHANGE | AUTO_ARC_PIP_DOUBLE | AUTO_ARC_PIP_LARGE | AUTO_ARC_PIP_LEFT_BOTTOM | AUTO_ARC_PIP_LEFT_TOP | AUTO_ARC_PIP_RIGHT_BOTTOM | AUTO_ARC_PIP_RIGHT_TOP | AUTO_ARC_PIP_SMALL | AUTO_ARC_PIP_SOURCE_CHANGE | AUTO_ARC_PIP_WIDE | AUTO_ARC_RESET | AUTO_ARC_USBJACK_INSPECT | AUTO_FORMAT | AUTO_PROGRAM | AV1 | AV2 | AV3 | BACK_MHP | BOOKMARK | CALLER_ID | CAPTION | CATV_MODE | CHDOWN | CHUP | CH_LIST | CLEAR | CLOCK_DISPLAY | COMPONENT1 | COMPONENT2 | CONTENTS | CONVERGENCE | CONVERT_AUDIO_MAINSUB | CUSTOM | CYAN | DEVICE_CONNECT | DISC_MENU | DMA | DNET | DNIe | DNSe | DOOR | DOWN | DSS_MODE | DTV | DTV_LINK | DTV_SIGNAL | DVD_MODE | DVI | DVR | DVR_MENU | DYNAMIC | ENTER | ENTERTAINMENT | ESAVING | EXIT | EXT1 | EXT2 | EXT3 | EXT4 | EXT5 | EXT6 | EXT7 | EXT8 | EXT9 | EXT10 | EXT11 | EXT12 | EXT13 | EXT14 | EXT15 | EXT16 | EXT17 | EXT18 | EXT19 | EXT20 | EXT21 | EXT22 | EXT23 | EXT24 | EXT25 | EXT26 | EXT27 | EXT28 | EXT29 | EXT30 | EXT31 | EXT32 | EXT33 | EXT34 | EXT35 | EXT36 | EXT37 | EXT38 | EXT39 | EXT40 | EXT41 | FACTORY | FAVCH | FF | FF_ | FM_RADIO | GAME | GREEN | GUIDE | HDMI | HDMI1 | HDMI2 | HDMI3 | HDMI4 | HELP | HOME | ID_INPUT | ID_SETUP | INFO | INSTANT_REPLAY | LEFT | LINK | LIVE | MAGIC_BRIGHT | MAGIC_CHANNEL | MDC | MENU | MIC | MORE | MOVIE1 | MS | MTS | MUTE | NINE_SEPERATE | OPEN | PANNEL_CHDOWN | PANNEL_CHUP | PANNEL_ENTER | PANNEL_MENU | PANNEL_POWER | PANNEL_SOURCE | PANNEL_VOLDOW | PANNEL_VOLUP | PANORAMA | PAUSE | PCMODE | PERPECT_FOCUS | PICTURE_SIZE | PIP_CHDOWN | PIP_CHUP | PIP_ONOFF | PIP_SCAN | PIP_SIZE | PIP_SWAP | PLAY | PLUS100 | PMODE | POWER | POWEROFF | POWERON | PRECH | PRINT | PROGRAM | QUICK_REPLAY | REC | RED | REPEAT | RESERVED1 | RETURN | REWIND | REWIND_ | RIGHT | RSS | RSURF | SCALE | SEFFECT | SETUP_CLOCK_TIMER | SLEEP | SOUND_MODE | SOURCE | SRS | STANDARD | STB_MODE | STILL_PICTURE | STOP | SUB_TITLE | SVIDEO1 | SVIDEO2 | SVIDEO3 | TOOLS | TOPMENU | TTX_MIX | TTX_SUBFACE | TURBO | TV | TV_MODE | UP | VCHIP | VCR_MODE | VOLDOWN | VOLUP | WHEEL_LEFT | WHEEL_RIGHT | W_LINK | YELLOW | ZOOM1 | ZOOM2 | ZOOM_IN | ZOOM_MOVE | ZOOM_OUT ]

=== Get ===

Derzeit keine Funktionen realisiert.

=== Readings ===

* '''state''': Status der Verbindung

== Anwendungsbeispiele ==

folgen noch

== Bekannte Probleme / Fehlersuche ==

Im Foum gibt es zwei Threads
* [https://forum.fhem.de/index.php/topic,12988.msg79079.html Original Thread]
* [https://forum.fhem.de/index.php/topic,57595.msg490160.html#msg490160 für Fernseher ab J-Serie]

== Links ==
* https://forum.fhem.de/index.php/topic,82890.0.html Zusammenfassende Doku: Samsung TV und FHEM

[[Kategorie:Unterhaltungselektronik]]

SIGNALduino

2018-11-26T17:07:20Z

Dora71: /* Unterstützte Geräte */ Conrad KW9110 hinzugefügt

{{Infobox Modul
|ModPurpose=Empfang und Verarbeitung von digitalen Signalen
|ModType=d
|ModFTopic=38402
|ModCmdRef=SIGNALduino
|ModForumArea=Sonstige Systeme
|ModTechName=00_SIGNALduino.pm
|ModOwner=Sidey ({{Link2FU|8018|Forum}}/[[Benutzer Diskussion:Sidey|Wiki]])
}}

== Einleitung ==
=== Übersicht ===
Unter den Namen SIGNALduino versteht man sowohl den Low-Cost Empfänger für digitale Signale (vergleichbar dem [[CUL]]) als auch das gleichnamige Modul mit dem Dateinamen 00_SIGNALduino.pm. Mit dem SIGNALduino kann man entweder 433 oder 868 MHz-Geräte auslesen und ansprechen. Der SIGNALduino funktioniert auch mit anderen Medien wie Infrarot oder direkter Kabelverbindung.

Der SIGNALduino(-Stick) erkennt Signale anhand von Mustern und gibt sie (als maximal detaillierte Beschreibung einer Signalabfolge) dann schlicht sofort nur noch an FHEM zur Auswertung (Dekodierung) weiter. Auch nicht erkannte Signale werden an FHEM übergeben.
Aufgabe des SIGNALduino (Firmware/Stick) ist es also nur, Signal-Aktivitäten zu erfassen und maximal präzise (als kurzer Text-String) zu beschreiben.
Alles weitere (echte, finale Auswertung / Zuweisung dieser Signal-Daten) wird dann auf einer großen Box (Raspberry o.ä.) gemacht.

=== Vorteil gegenüber einem CUL/FHEMduino ===
Der SIGNALduino hat den Vorteil einer sehr schnellen Demodulation des Funksignals. Sollen weitere Protokolle dekodiert werden, so muss dazu nur ein passendes FHEM Modul entwickelt oder ein universelles Modul erweitert werden (also auf flexibel direkt updatebarer Rechner-Seite!!). Änderungen am Arduino-Firmware-Code sind normalerweise nicht notwendig (sofern die grundsätzliche Signal-Klassifizierung des Sticks korrekt funktioniert - leider nicht immer, z.B.: [https://github.com/RFD-FHEM/SIGNALDuino/issues/65 MU-Nachrichten werden z.T. als MC erkannt]).

Ein großer Vorteil des SIGNALduino besteht darin, dass auch Geräte mit leicht abweichende Frequenzen steuerbar sind; so empfangen die Somfy-Rolladenmotoren beispielsweise auf 433.42 und nicht, wie bei anderen Geräten sehr oft üblich, auf 433.92 MHz. Die Frequenzumstellung stellt für den SIGNALduino kein Problem dar.

Ebenso kann man den SIGNALduino direkt an den Sendeausgang eines Sensors anbinden und die digitalen Signale empfangen, dabei bitte aber auf die passenden Spannungen achten, denn ein Arduino Nano verträgt nur 5V.

== Hardware ==

Der SIGNALduino (Hardware) wird über den USB Port angeschlossen, er kann aber auch mit zusätzlichen ESP Modulen über ein WLAN angebunden werden.

Der SIGNALduino basiert auf einem [http://arduino.cc/de/Main/ArduinoBoardNano Arduino Nano], die Schaltung entspricht der des [[FHEMduino]] oder dem [[Selbstbau_CUL]]:
* Entweder wird ein Arduino mit einfachen Sende- und Empfangsmodulen verwendet, dann ist die Verkabelung identisch zum [[FHEMduino]]
* Oder es wird ein CC1101 Transceiver verwendet, dann ist die Verkabelung identisch zum [[Selbstbau_CUL]].
* Zuletzt gibt es ein fertig konfektioniertes Modul von In-Circuit mit Radino CC1101 Varianten, link zum [http://shop.in-circuit.de/index.php Hersteller].

Achten Sie beim Selbstbau auf die entsprechenden Sender-Empfänger. Der sehr preiswert angebotene XY-MK-5V hat sich als zu unzuverlässig erwiesen, während anscheinend beim CC1101 (insbesondere der "grünen Version") keine Probleme auftreten.

Es stehen auch für den [https://www.arduino.cc/en/Main/arduinoBoardUno UNO] und [https://www.arduino.cc/en/Main/ArduinoBoardProMini PRO Mini] Firmware-Dateien zur Verfügung. Die ausgelieferte Firmware läuft nur auf Mikrocontrollern mit 16 MHz; wer einen Mikrocontroller mit 8 MHz verwenden möchte, muss die Firmware selbst compilieren. Die SW ist auf [https://github.com/RFD-FHEM/SIGNALDuino github]. Vorgesehen ist nur die Übersetzung unter Windows mit Visual Studio und dem Visual Micro Zusatz. Es gibt aber auch eine Anleitung, wie man mit der [[Arduino]] IDE oder einem Makefile [[SIGNALduino Compilieren]] kann.

Es gibt auch eine Variante des SIGNALduino, die auf einem [[ESP8266]] nativ läuft, diese funktioniert seit Anfang 2018 annehmbar, allerdings befindet diese sich noch in einer Entwicklungsphase.

An den "SIGNALESP" kann auch ein CC1101 via SPI angebunden werden:

{||
!CC1101 Bezeichnung
!ESP Pin
|-
|CLK||GPIO14
|-
|MOSI||GPIO13
|-
|MISO||GPIO12
|-
|CSN||GPIO15
|-
|GDO0||GPIO4
|-
|GDO2||GPIO5
|}

Wird ein einfacher Empfänger / Sender Kombination verwendet, dann über die PINs:

{||
! Bezeichnung
! ESP Pin
|-
|Transmitter||GPIO4
|-
|Receiver||GPIO5
|}

=== Einfache Module ===

[[Datei:Fhemduino_schematic.png|200px|thumb|right|Beispielschaltplan SIGNAL(FHEM)duino]]

Mit einem Arduino-Nano und folgenden, billigen Sende- und Empfangsmodulen können Sie einen SIGNALduino bauen:
* FS1000A Dies ist das Sendemodul (TX) und wird oft im Set mit dem billigen XY-MK-5V-Empfänger angeboten (etwa 5€).
* RXB6 Das ist das empfohlene Empfangsmodul (RX), statt XY-MK-5V, etwa 5€ aus Deutschland.

Die Verkabelung erfolgt analog zum [[FHEMduino]] und das bedeutet (Arduino -> Modul):
* PIN D2 an DATA des RX-Moduls
* PIN D11 an DATA des TX-Moduls (PIN links mit Beschriftung ATAD)

Zusätzlich muss noch jeweils GND und 5V des Arduino mit dem GND bzw. VCC des Moduls verbunden werden.

Jetzt fehlen noch die Antennen. Dafür braucht man ein 17,2 cm langes Stück Kupferdraht, das wird beim Anschluss "ANT" jeweils am Modul angelötet (anfängergeeignet).

== Software: Modul ==

=== USB-ID ermitteln ===
Bevor der SIGNALduino mit dem FHEM Server (im Beispiel hier ein Raspberry PI) verbunden werden kann, muss die USB-Schnittstelle ermittelt werden. Hierzu bitte auf dem Terminal den Befehl
<pre> ls -l /dev/serial/by-id </pre>
ausführen. Beispielhaft sieht das Ergebnis etwa so aus:
''lrwxrwxrwx 1 root root 13 Jan 31 00:02 '''usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port''' -> ../../ttyUSB0''
Damit ist der Anschluss des SIGNALduino bestimmt und das Gerät kann wie im nächsten Abschnitt beschrieben definiert werden. Zuvor muss noch das Modul geladen werden.

=== FHEM-Modul laden ===
Die SIGNALduino Module werden über das FHEM [[update]] verteilt, sobald die Änderungen einen "stabilen" und alltags tauglichen Zustand haben.

Die in der Entwicklung befindliche Version kann mit folgenden Befehlen geladen werden:

* FHEM aktualisieren: <code>update</code>
* SIGNALduino Modul aktualisieren: <code>update all <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code> Durch das Update von FHEM wird sichergestellt, dass das Modul mit FHEM arbeitet.
*Danach kann das Gerät wie folgt definiert werden (die Spezifikation des USB-Anschlusses muss dabei an die aktuellen Gegebenheiten angepasst werden):
:<code>define <eigener-SIGNALduino-Name> SIGNALduino /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_A903N5T5-if00-port0@57600</code>
* Solltet Ihr einen SIGNALESP via IP einbinden wollen ist die Syntax
:<code>define <eigener-SIGNALESP-Name> SIGNALduino <ip-adresse>:23</code>
Nach dem Einbinden wird der SIGNALduino, falls er erkannt wird, im Status "Opened" angezeigt.

Für neuere Entwicklungen kann in FHEM auch dauerhaft die developer Version aktualisiert werden:
<code>update add <nowiki>https://raw.githubusercontent.com/RFD-FHEM/RFFHEM/dev-r33/controls_signalduino.txt</nowiki></code>
Danach wird FHEM bei dem normalen Update-Befehl immer automatisch die aktuelle dev Version laden.

Die nachfolgenden Beispiel-Befehle verwenden "sduino" als <eigener-SIGNALduino-Name>.

==== Flashen des Arduino mit der SIGNALduino Firmware ====
Falls avrdude noch nicht vorhanden ist, kann es mit folgendem Befehl installiert werden:
:<code>sudo apt-get install avrdude</code>

In FHEM ist der SIGNALduino mit dem Status "Open" vorhanden. Jetzt müssen wir FHEM noch mitteilen, welche Hardware wir angeschlossen haben. Über das Attribut ''hardware'' lässt sich zwischen den mitgelieferten Firmware-Dateien wechseln. Solltet ihr einen Nano mit cc1101 Transceiver verwenden, so wählt bitte folgende Hardware
<code>attr sduino hardware nanoCC1101</code>
sonst üblicherweise
<code>attr sduino hardware nano328</code>

Anschließend kann der ''flash'' Befehl abgesetzt werden:
<code>set sduino flash </code>
Dadurch wird der Arduino mit der gewählten Firmware geflasht. Das Ergebnis wird im Webinterface direkt angezeigt.

Alternativ kann auch der Flash-Befehl mit einem Dateinamen aufgerufen werden. Diese Möglichkeit sollte jedoch nur verwendet werden, wenn die SIGNALduino Firmware selbst compiliert wurde und eine andere Hardware verwendet wird. Der Flash-Befehl wird wie folgt aufgerufen:
:<code>set sduino flash FHEM/firmware/SIGNALduino_mega2560.hex</code>
(je nachdem wo und unter welchem Namen die .hex Datei abgelegt wurde)

==== Flashen einer Firmware über HTTP ====
Die Firmware wird in absehbarer Zeit nicht mehr über den Update Mechanismus verteilt werden.
Damit die passende Firmware auf den SIGNALduino geladen werden kann, wird diese dann über HTTP geladen.

==== Vorabversion einer Firmware ====
Die Firmware des SIGNALduino wird ebenso wie das FHEM Modul auch weiter entwickelt.
Die Entwickler sind auf Tests und Rückmeldungen der Nutzer angewiesen, da leider nicht alle Sensoren vorher getestet werden können.

Aktuell (November 2018) ist noch die Version 3.3.1 in Entwicklung. Diese steht aktuell in einer Release Candidate Version zur Verfügung.

Für die folgenden Microcontroller kann man die Firmware downloaden. (Die Download Links funktionieren erst ab einer FHEM-Modul Version vom 11.03.2018!)

SIGNALDuino_nanocc1101.hex für einen Nano mit CC1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nanocc1101.hex
</code>

SIGNALDuino_nano.hex für einen Nano ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_nano.hex
</code>

SIGNALDuino_promini.hex für einen promini 3,3v / 8 Mhz ohne cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_promini.hex
</code>

SIGNALDuino_miniculcc1101.hex für einen promini 3,3v / 8 Mhz mit cc1101 (minicul)

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_miniculcc1101.hex
</code>

SIGNALDuino_radinocc1101.hex für einen radino mit cc1101

<code>set sduino flash https://github.com/RFD-FHEM/SIGNALDuino/releases/download/3.3.1-RC10/SIGNALDuino_radinocc1101.hex
</code>

SIGNALESP_331rc4.bin (mit cc1101) für einen ESP8266 mit 1 MB Flash
<code>set ipduino flash https://github.com/RFD-FHEM/SIGNALESP/releases/download/3.3.1RC4/SIGNALESP_331RC4_1M.bin
</code>
!Achtung, aktuell wird die Firmware für den ESP dadurch nur herunter geladen. Flashen müsst ihr leider immer noch über ein passendes Tool
z.B. [https://github.com/nodemcu/nodemcu-flasher ESP8266Flasher.exe] oder Esptool und einer seriellen Konsole.

Nach dem Booten des ESPs, spannt dieser ein eigenes WLAN auf. Habt ihr euch damit verbunden, könnt ihr den ESP mit eurem vorhandenen WLAN verbinden.

==== Flashen eines radino Boards mit ATmega32U4 ====

Diese Funktion steht nur in der Entwicklungsversion dev-r33 zur Verfügung:

Auch sind Berichte bekannt, dass der Radino beim Neustart von FHEM nicht korrekt initialisiert wird.

==== Fehler beim Flashen ====
Sollte bei einem Flash Vorgang ein Fehler auftreten, solltet ihr zunächst im Logfile mit Verbose 5 nachsehen.

Findet ihr dort keine Fehlermeldung, gibt es noch ein separates Flashlog, welches ihr über einen Browser aufrufen könnt. Dazu müsst ihr nur den Folgenden Pfad an euren Servernamen anhängen:
<code>
/fhem/FileLog_logWrapper?dev=Logfile&type=text&file=SIGNALduino-Flash.log
</code>

=== Geräteerkennung ===
==== Unterstützte Geräte ====
Für die folgenden Geräte gibt es derzeit (2017) eine Unterstützung für den Betrieb mit FHEM. Die Geräte werden [[autocreate|automatisch erkannt]] und in der Konfiguration eingetragen, wenn der SIGNALduino läuft.
Bitte Geräte mit sehr präzisen Referenzen hier listen (Produktnummer, Protokoll-Variantenname etc.), damit eine globale Suche/Verifikation maximal erfolgreich ist.
{|class="wikitable"
! style="text-align:left;"| Produkt
! (E)mpfangen (S)enden
! Hinweise
! Verwendetes Modul
! Protokoll ID
|-
|Conrad Wetterstation KW9110||E||Sensor: KW9010, neben Temperatur u. Luftfeuchte werden auch Trend, Batterie u. Kanal erfasst|| CUL_TCM97001 || 0
|-
|TCM Wetterstation (97001 und 21xxx Serie)||E|| || CUL_TCM97001 || 0
|-
|ABS Wetterstation (ABS 700)||E|| || CUL_TCM97001 || 0
|-
|Prologue Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Rubicson Wetterstation ||E|| ||CUL_TCM97001 ||0
|-
|NC_WS Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|[http://www.gt-support.de/ GT-WT-02 Wetterstation]||E|| ||CUL_TCM97001 || 0
|-
|AURIOL Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Mebus Wetterstation ||E|| ||CUL_TCM97001 || 0
|-
|Intertechno Funkschalter||E S|| ||IT || 3,4,5,17
|-
|<strike>Conrad RSL Funkschalter</strike>||E S|| Funktioniert aktuell nicht || SIGNALduino_RSL ||
|-
|[http://global.oregonscientific.com/product_view.php?id=5 Oregon Scientific Wettersensoren]||E || Protokoll V2 & V3 implementiert || OREGON || 10
|-
|Bresser Temp/Hydro Sensor||E || || Hideki || 12
|-
|[https://de.hama.com/00104985/hama-aussensensor-ts33c-fuer-wetterstation Hama TS33C]||E || || Hideki || 12
|-
|TFA Temp/Hydro Sensor||E || || Hideki || 12
|-
|Lacrosse TX2/TX3 Sensoren||E || || CUL_TX || 8
|-
|TFA 30320902||E || || SD_WS07 || 7
|-
|Eurochron eas800z||E || || SD_WS07 || 7
|-
|Technoline WS6750/TX70DTH||E || || SD_WS07 || 7
|-
|FreeTec Außenmodul NC-7344||E || || SD_WS07 || 7
|-
|CTW600||E || || SD_WS09 || 9
|-
|WH1080||E || || SD_WS09 || 9
|-
|Visivon remote pt4450||E || || none || 24
|-
|Einhell HS 434/6||E || || none || 21
|-
|Flamingo FA20RF / FA21RF Rauchmelder||E || || none || 13
|-
|mumbi m-FS300||E || || none || 26,27
|-
|TFA 30.3200||E || || none || 33
|-
|Livolo||E|| || none || 20
|-
|Smartwares RM174RF/2 (RM174RF-001CPR) 4500177571 ||E [S?]|| IT EV1527; TODO herausfinden: Alarmierung (wie Alarmton getriggered werden kann); Batterieinfo? || IT || 3
|-
|Smartwares SH5-TSO-A||E S|| || IT || ?
|-
|X10 Security Devices||E|| || || 39
|-
|[[Somfy_via_SIGNALduino|Somfy RTS]]||E S|| || SOMFY || 43
|}
Bei einigen Intertechno-Funksteckdosen (Brennenstuhl) kann es zu Empfangsproblemen kommen. Hier muss die Taktrate, mit der gesendet wird, angepasst werden. Dazu muss für ''Funksteckdose'' (also sauber per-Client-Instanz-spezifisch, NICHT SIGNALduino-Transceiver-global) das Attribut
:<code>attr <Funksteckdose> ITclock 300</code>
gesetzt werden, der Standardwert ist 250.

==== Mein Gerät wird in FHEM nicht erkannt ====
1. Prüfen, ob vom Sensor die Signaldaten (verbose >=4) erkannt werden. Sobald ihr die empfangenen Signaldaten im Logfile zuordnen könnt, geht es weiter mit:

2. Eröffnet ein Thema unter [https://github.com/RFD-FHEM/RFFHEM/issues github] nach folgendem Muster:
:''Thema : Protokoll für <Das verwendete Gerät>
:Inhalt: Eure Hardware z.B. Arduino Nano mit XYZ Empfänger, oder Arduino Nano direkt an Gerät x

3. Auszug aus dem Logfile, welches zum Gerät gehört.
:''Alles was ihr sonst noch über das Gerät und die übertragenen Daten wisst.

Im Forum solltet ihr solche Fragen besser nicht posten, wenn das Gerät noch nicht unterstützt wird, dazu ist Github besser geeignet. Inzwischen wurde im Wiki eine eigene Seite eröffnet, die sich mit der Erkennung unbekannter Protokolle beschäftigt: [[Unbekannte_Funkprotokolle#Ansatz_1_-_Versuchen|Unbekannte_Funkprotokolle]].

==== Es wird ein Protokoll erkannt, Autocreate legt aber kein device an ====
Im SIGNALduino sind >30 Protokolle implementiert. Jedoch gibt es nur wenige Module, welche diese Protokolle verarbeiten.
Teilweise ist das auch nicht zwingend notwendig, um seine Anforderungen zu erfüllen. Insbesondere für Schalter bzw. Sensoren, die nur zwei Zustände kennen, geht es meist ohne Modul und automatisch angelegtem Gerät.

Nehmen wir an, wir haben einen Schalter. Dieser kann einen oder zwei Zustände senden.
Im FHEM Log (und, insbesondere, im FHEMWEB Event Monitor) tauchen Meldungen ähnlich dieser auf

<code>
2015.11.15 15:52:23 4: SIGNALduino_unknown incomming msg: u85#FF8081
</code>

Wir können mit Hilfe des Modules DOIF auf diese Nachricht eine Aktion ausführen:

Entweder, wenn wir den Inhalt der Nachricht nur zu Teilen wissen, da er sich ändert:

<code>
define mydoif DOIF ([sduino:&DMSG] =~ "u85#FF8081") (set Lamp on)
attr mydoif do always
</code>

Oder, wenn wir den Inhalt exakt kennen, dann auch als Vergleichsstring

<code>
define mydoif DOIF ([sduino:&DMSG] eq "u85#FF8081") (set relais on)
attr mydoif do always
</code>

Der Teil u85#FF8081 muss individuell angepasst werden, der Name eures SIGNALduino möglicherweise auch.

Als Alternative zu DOIF hier ein regex-verwendendes notify-Beispiel für einen Sender, der meint, zwei Codes alternierend senden zu müssen:

<code>
define n_sender_trigger notify sduino:UNKNOWNCODE.*u41#(13B72253|163873B3) { my_sender_trigger_indicate();; }
</code>

Selbstverfreilich muss in diesem Moment auch eine sub my_sender_trigger_indicate() definiert werden (z.B. in FHEM/99_myUtils.pm), die dort z.B. als Test eine Log-Ausgabe (Log3()) machen kann.

=== Das Logfile ===
Im Logfile ab [[Verbose]] 4 tauchen diverse Meldungen auf, deren Bedeutung kurz erläutert wird (verbose 3 unterdrückt diese Meldungen).

UPDATE: der folgende Bereich ist von einem weniger erfahrenen Zeitgenossen früher nach Kräften erweitert/geschrieben worden. Mittlerweile existiert aber ein neuer Inhalt [[Unbekannte_Funkprotokolle]] (siehe auch Erwähnung weiter oben), der als sehr gut beschrieben und unvergleichlich detailreicher bezeichnet werden muss ("endlich gibt es sowas!"). Der Bereich hier dürfte somit zwar für grundlegende Verdeutlichungen noch recht sinnvoll sein, der Inhalt sollte allerdings evt. in eine konsistente Dokumentation überarbeitet (verlagert/dedupliziert/reduziert) werden.

Die Protokolle (von der SIGNALDuino-Firmware gesendete Signal-Beschreibungs-Strings) können wie folgt unterschieden werden:

*MS - Nachricht mit Sync Puls: Hierzu ein Beispiel
:<code>MS;P0=-108;P1=395;P2=-1033;P3=-547;P4=-19932;P5=-8916;P6=1368;D=151313131312131313131313131313131312121212121313131313131312131212132;CP=1;SP=5;</code> P0-P6 sind die Signalpegel (Dauer und positiv/negativ). Hinter D= befindet sich die Abfolge der Signale. Die ersten beiden Ziffern 15 in D sind wie folgt zu lesen. Zuerst wurde ein Signal "1" also P1 mit 395 Mikrosekunden high (die Zeitdauer ergibt sich aufgrund der Mitteilung "P1=395") und anschließend ein Signal "5" also P5 mit 8916 Mikrosekunden low (die Zeitdauer ergibt sich aufgrund der Mitteilung "P5=-8916") gemessen. CP=1 ist die Referenz auf den Takt des Signales - der Basistakt ist in diesem Fall ~395 Mikrosekunden. SP=5 gibt die Referenz zum Syncpuls an, der das gesamte Signal einleitet. Welche Signalfolge nun eine binäre 1 bzw. 0 bedeutet, wird im SIGNALduino über die integrierte Protokoll Liste realisiert.

*MC - Nachricht vom Typ Manchester: Manchesterkodierte Signale können bereits sehr einfach im Arduino in eine Binärform umgewandelt werden. Es wird hier nach IEEE 802.3 umgewandelt. In Manchester Signalen gibt es lange und kurze Pulse. Deren Durchschnittswert wird mit LL (long low), LH (long high), SL (short low) und SH (short high) übermittelt. Zusätzlich, um das Protokoll schneller erkennen zu können, wird die Taktfrequenz mit übermittelt (C=429 Mikrosekunden). Die Daten befinden sich hinter D= und werden in HEX Form übergeben.
:<code>MC;LL=-1066;LH=904;SL=-562;SH=385;D=332B4B4D54D5554B552CD2D554B2B5354A;C=429;</code>

*MU - Message unsynced: Diese Art von Nachrichten sind nicht nach Manchester codiert und haben auch keinen erkennbaren Sync / Clock Signalpegel am Start der Nachricht. Bei diesen Nachrichtentypen ist es, im Vergleich zu den anderen, am wahrscheinlichsten, dass das übermittelte Signal unvollständig oder überhaupt kein Signal ist. Wie bei MS sind P0-P6 die Signalpegel und in D= wird die Abfolge der Signalpegel referenziert. CP=2 gibt auch hier die Referenz zum Takt an, allerdings muss dieser nicht korrekt erkannt worden sein.
:<code>MU;P0=1372;P1=-580;P2=362;P3=-1047;D=01212321212321212121212121212123212123212321232121212121212321;CP=2;</code>

Es erscheinen viele Meldungen dieser Art:

<pre>
Fingerprint for MU Protocol id xxxx -> yyy matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 28 -> IC Ledspot matches, trying to demodulate
sduino: Starting demodulation at Position 1
Fingerprint for MU Protocol id 29 -> HT12e remote matches, trying to demodulate
</pre>

Dies sind nun Bemühungen, anhand der von der SIGNALDuino-Firmware gelieferten rohen aber detaillierten Signal-Strings eine Vor-Analyse / Fingerprinting vorzunehmen.
Man könnte nun z.B. bei solchen Fingerprinting-Analysen erkennen:
* dass der Basis-Takt-Wert innerhalb eines charakteristischen Zeit-Bereichs liegt
* dass die Anzahl der Sync-Pulse eine präzise Zahl ist
* dass Längen erkannter Puls-Typen innerhalb eines Bereichs liegen

Mittels solcher Untersuchungen kann man also final hoffentlich hinreichend plausibel feststellen, "dass diese Aktivitäten offensichtlich(?) zu einer Funk-Komponente Rauchmelder von Hersteller XYZ gehören müssen, und man somit weiterleiten muss an ein (möglicherweise bereits existierendes) Userdaten-Dekodier-Modul für diese Herstellerkomponente".

Bei einer dann erfolgenden Demodulation des noch rohen SIGNALDuino-Strings könnte man z.B. (hoffentlich richtigerweise) annehmen, dass eine Signalpegel-Typ-Folge "13" eine binäre 1 bedeuten soll, während eine Folge "12" eine binäre 0 bedeuten soll. Man erhält aus dem Gesamt-Puls-String also nach vollständiger Demodulation eine Abfolge von vielen 0/1 Bits, die insgesamt ein Datenwort darstellen, mit einer gewissen Länge von NN bits (diese Längen-Angabe könnte übrigens - neben Namenssuche nach Hersteller oder Produkt etc. - ein wichtiges Such-Merkmal sein, ob andere Frameworks tatsächlich bereits wissen, wie Daten dieser Funk-Komponente zu dekodieren sind!). Dieses demodulierte Datenwort ist nun das finale Datenwort, welches einen Container für die Funk-Komponenten-Informationen darstellt (in diesem Container also beispielsweise enthalten: Temperatur, Feuchte, Akku-Status, ID, Alarm, ... - zumindest wenn nicht dummerweise der ganze Container erst einmal CRC- oder Crypto-verschlüsselt ist...).

Man muss an dieser Stelle unbedingt sagen, dass dieses Userdaten-Datenwort (einer bestimmten Hersteller-Funk-Komponente!) natürlich bei ''jeglichen'' Transceiver-Systemen ''immer'' gleich erkannt werden ''muss'' - an dieser Stelle ist also ganz klar, dass diese Daten an ''allgemeine'' FHEM-Module weitergeleitet (Dispatched) werden müssen, die nach Übernahme von Daten von ''jeglichen'' Transceiver-Systemen diese Daten immer auf die gleiche Weise ('''''generisch/zentral''''') für die jeweilige Hersteller-Funk-Komponente erledigen.

'''Die Abfolge ist also ganz klar:'''
Funk-Aktivität --> Transceiver-Gerät/Firmware (SIGNALDuino) --> maximal detailreich beschreibender Rx-Analyse-Output-String --> Fingerprinting-Grobzuordnung des (SIGNALDuino-Firmware-)Outputs (durch 00_SIGNALduino.pm) auf gerätespezifisches Verhalten --> ''generische/zentrale'' Dekodierung des gerätespezifischen Protokoll-Datenworts, in zentralen Grundsatz-Modulen wie z.B. <code>14_SD_WS.pm</code>).

Und wenn dann bei einer solchen Schritte-Abfolge irgendetwas noch fehlen/unpassend sein sollte, dann muss eben entsprechendes Development an gewissen Stellen erfolgen ;-)

====Minimieren (whitelist/blacklist) von unerwünschter Kommunikations-Aktivität/Einträgen====

"Unknown Code" bedeutet, dass der SIGNALduino Signaldaten empfangen und diese binär interpretiert hat. Diese Meldung soll uns nun aber mitteilen, dass es dann nicht weiter verarbeitet werden kann, da kein Modul existiert (oder kein Weiterleitungs-Dispatch zu einem bereits existierenden), welches diese Daten jetzt in ihre Bedeutung umwandeln kann.
:<code>sduino: Unknown code u1FFFFF0, help me!</code>

Außerdem kommt es gehäuft zu Logmeldungen und auch Events in ähnlicher Form:
:<code>SIGNALduino_unknown incomming msg: u85#FF8081</code>

Mittlerweile sind über 50 Protokolle für den SIGNALduino definiert. Dadurch kommt es vor, dass sich ein Signal mit mehr als einem Protokoll demodulieren lässt. Meist führt dies dann zu zusätzlichen "Unknown code"-Einträgen.

Derartige Einträge können mit dem Attribut WhitelistID minimiert werden. Dabei werden die Geräte, die nach Daten-Empfang tatsächlich verarbeitet werden sollen (also welche Protokolle vom FHEM Modul berücksichtigt werden), mit ihrer Protokollnummer in die WhitelistID aufgenommen.
Für Protokolle, die nicht berücksichtigt werden, gibt es weder Logeinträge noch Events. Diese werden im Programmablauf nicht berücksichtigt. Das spart zum einen Ressourcen und trägt auch zur Übersichtlichkeit bei.
Die Protokollnummer kann Tabelle [[#Unterst.C3.BCtzte_Ger.C3.A4te]] entnommen werden (hilfreich ist es auch, wenn in den verwendeten Geräten im Internal <gerätename>_DMSG nachgesehen wird). So bedeutet beispielsweise ein Eintrag der Form <code>W50#FF553335FFBC</code> dass dann das Protokoll #50 in die Whitelist aufzunehmen wäre (<code>attr sduino whitelist_IDs 50</code>).
{{Randnotiz|RNTyp=r|RNText=Achtung Schreibweise: Dokumentation oft als WhitelistID o.ä., aber Name ist whitelist_IDs!!
}}
Die Angabe erfolgt durch Komma getrennt: z.B.:
:<code>1,2,5,10</code>

=== Senden mit dem SIGNALduino ===
Der SIGNALduino kann etwas "raw senden", indem ihm das SIGNAL so übermittelt wird, wie er es moduliert. Hierzu muss der Befehl wie folgt eingegeben werden:

<code>
set sduino sendMsg P3#00111010#R4
</code>

Dieser Befehl moduliert die Bitfolge 00111010 mittels Protokoll #3 und wiederholt die Nachricht 4x.
Die Protokoll Nummer kann aus einer empfangenen Nachricht extrahiert werden. Ebenso die Bits.
<code>
sduino: extracted data 00111010 (bin)
sduino: Found Protocol id 3
</code>

Alternativ kann das Signal auch in einer "rohform" angegeben werden. Dies ist manchmal in speziellen Fällen notwendig:
<code>
set sduino raw SR;;R=3;;P0=4742;;P1=-1554;;P2=286;;P3=-786;;P4=649;;P5=-420;;D=0123234545234545452323232323454523234523454523232345454523232323452345234523452345;;
</code>

R=3 bedeutet, das Signal wird 3x gesendet.
Die Übertragung besteht aus den in D angegeben Pulsen, welche in P0-P5 definiert werden.
Die Daten kann man aus einer empfangenen MS oder MU Nachricht extrahieren.

Alternativ kann ab Version 3.2 auch eine vereinfachte Form eingegeben werden.

====Fehlersuche====

(Zielgerät reagiert nicht, etc.)

* Nachrichtenwiederholungsanzahl muss evt. für manche Geräte entsprechend groß eingestellt sein
* Sende-Takt-Wert (Clock) passt evt. nicht ganz, siehe z.B. Thread-Antwort [https://forum.fhem.de/index.php/topic,58397.msg775434.html#msg775434 Signalduino Version 3.3.1], wo für IT-Geräte ein Attribut anhand der CP= des Empfangsdaten-Logs modifiziert wird. ACHTUNG: dies kann entweder global das Internal-Attribut ITClock eines SIGNALduino-Transceiver-Devices sein, oder (viel besser da korrekt geräte-instanz-spezifische Konfiguration) das ITclock eines IT-Client-Devices.
{{Randnotiz|RNTyp=r|RNText=VORSICHT blöder Schreibweisen-Mismatch ITClock vs. ITclock!!
}}

== Fehlerbehandlung ==
Der SIGNALduino kann mit folgendem Befehl auf Werkseinstellungen zurückgesetzt werden:
:<code>get raw e</code>
als Antwort kommt dann "ccFactoryReset done". Ob ein solcher Reset nötig ist, erkennt man an der Antwort auf den Befehl "get config", auf den dann die Meldung "config: MS=1;MU=1;MC=1" folgen sollte.

In der Firmware sind die folgenden Befehle eingebaut

*:<code>get raw C<reg></code>
<reg> is a (two digit) hex number: return the value of the cc1101 register. <reg>=99 dumps the first 48 registers.
Example: C35 -> C35 = 0D
*:<code>get raw e</code>
EEPROM / factory reset. resets all eeprom values without reboot
*:<code>get raw r<AA></code>
Read eeprom (da das "R" beim SIGNALDuino bereits mit freeram belegt ist, habe ich das "r" verwendet)
*:<code>get raw r<AA>n</code>
Read 16 byte from eeprom (z.B. r00n)
*:<code>get raw W<AA><DD></code>
Write eeprom (schreibt einen Wert ins EEPROM und ins CC1101 Register. Die eeprom Adresse hat einen Offset von 2. z.B W041D schreibt 1D ins Register 2)

Die Sendeleistung lässt sich mit
:<code>get sduino ccreg 3E</code>

prüfen, wobei die Rückmeldung wie folgt zu lesen ist:
"-10_dBm" => '34',
"-5_dBm" => '68',
"0_dBm" => '60',
"5_dBm" => '84',
"7_dBm" => 'C8',
"10_dBm" => 'C0'
Dabei wird die Sendeleistung dauerhaft mit dem Befehl
:<code>set sduino cc1101_patable <value></code>
hochgeschaltet (<value> durch den Wert ersetzen).

Weitere Firmware-Befehle sind im Thread-Beitrag {{Link2Forum|Topic=58396|Message=497921}} zu finden.

== Foren Links ==
* {{Link2Forum|Topic=38402|LinkText=Forenthread - Ankündigung}}
* {{Link2Forum|Topic=58396|LinkText=SIGNALDuino Empfänger Firm- und Hardware}}
* {{Link2Forum|Topic=58397|LinkText=Signalduino Entwicklung Version 3.3.1 }}
* [http://www.rflink.nl/blog2/wiring Beschreibung zu diversen Empfängern und Verbesserung der Empfangsleistung]
* [[SIGNALduino in die Arduino Entwicklungsumgebung einbinden]]
* [[Somfy via SIGNALduino]]

[[Kategorie:Interfaces]]
[[Kategorie:Arduino]]
[[Kategorie:433MHz]]
[[Kategorie:868MHz]]

TelegramBot

2018-10-21T17:23:34Z

Dora71: /* Gruppen */

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

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

Das TelegramBot-Modul benötigt keine Zusatzsoftware auf dem FHEM-Server (anders als die Variante [[Telegram]]), sondern verwendet das [https://core.telegram.org/bots/api TelegramBot-API] über https-Aufrufe. Es muss jedoch das [http://www.fhemwiki.de/wiki/Raspberry_Pi#N.C3.BCtzliche_Zusatzpakete perl JSON modul] installiert sein.

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

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

== Features ==
Unterstützt werden:

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

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

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

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

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

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

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

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

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

Beispiel: <code>attr teleBot pollingTimeout 120</code>

'''Der TelegramBot kann erst dann Nachrichten an einen telegram user schicken, wenn dieser zuerst an den telegram bot eine Nachricht gesendet hat.'''
Dafür muss man in seinem Telegram-Client den Kontakt @botName suchen und dann eine Nachricht darn versenden.

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

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

For a description of the Bot API, see this page: https://core.telegram.org/bots/api
</pre>
Um einen Chat an einen "Contact" versenden zu können, muss zuerst in Contacts (bei Readings) ein Kontakt auftauchen. Wenn man sich zum allerersten Mal bei Telegram angemeldet hat, gibt es noch keinen Chat mit irgendjemanden. Man muss sich zuerstmal selbst eine Nachricht im Smartphone zusenden, dann taucht unter Readings der Eintrag Contacts auf. Erst dann kann man eine Nachricht mit @msgPeerId (das ist Ziffernfolge des Contacts ) oder mit @msgPeer (das ist der Name nach dem Doppelpunkt) vom TelegramBot auf sein Smartphone senden.

== Tipps ==

=== Privacyeinstellungen ===

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

=== Kontakte ===

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

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

Verschiedene Einträge werden durch Leerzeichen getrennt.

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

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

=== Reset ===

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

=== Gruppen ===

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

==== Supergroups / Supergruppen ====

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

== Beispielszenarien ==

=== Benachrichtigungen über Ereignisse ===

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

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

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

=== Versand von Bildern ===

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

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

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

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

=== Versand von SVG-Plots ===

SVG-Plots können mit dem Befehl
<code>cmdSend [ @<peer1> ... @<peerN> ] <fhem command></code>
verschickt werden.

Das angegebene FHEM-Kommando wird ausgeführt und das Ergebnis an die angegebenen Peers bzw. den Standard-Peer verschickt.

Mit dem folgenden Befehl wird der SVG-Plot SVG_FileLog_Aussen an den Standard-Peer geschickt:
<code>set mein_telegramBot cmdSend { plotAsPng('SVG_FileLog_Aussen') }</code>

Nach <code>define cmd_sendTelegramSVG cmdalias TGSVG .* AS set mein_telegramBot cmdSend { plotAsPng("$EVENT") }</code>
kann man mit einem kurzen
<code>TGSVG SVG_Garten</code>
ein beliebiges SVG über die Kommandozeile per Telegram versenden.

Um das SVG nun noch mit einem Text zu versehen, muss eine Textnachricht dazu gesendet werden, was sich am einfachsten durch das Ausführen eines FHEM-Befehls auf Perl-Ebene realisieren lässt:

<code>{fhem "set mein_telegramBot message Bildbeschreibung;; set mein_telegramBot cmdSend { plotAsPng('mein_SVG') }" }</code>

'''Hinweis:''' früher wurde zum Verschicken von Plots auch die interne Funktion TelegramBot_ExecuteCommand verwendet; mit dem Update Ende Februar 2017 hat diese Funktion einen zusätzlichen Parameter erhalten und lautet nun
<code>TelegramBot_ExecuteCommand($defs{"mein_telegramBot"}, meine_ZielID, undef, '{plotAsPng("mein_SVG")}');</code>

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

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

Evtl. sind weitere Module erforderlich:

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

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

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

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

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

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

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

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

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

übernehmen und mit der Nachricht verschicken.

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

=== Kommandos auslösen ===

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

<code>attr telebotdevice cmdKeyword doit</code>

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

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

Beispiele

<code>doit set schalter on</code>

<code>doit list telegrambot</code>

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

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

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

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

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

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

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

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

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

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

<pre>
Favorites

/short1 = set TYPE=ROLLADEN pos 100

/short2 = set TYPE=ROLLADEN pos 0

</pre>

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

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

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

<pre>
Favorites

/short1 = Rollaeden zu

/short2 = Rollaeden auf

</pre>

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

* Source code für das 50_TelegramBot.pm-Modul: https://github.com/viegener/Telegram-fhem/blob/master/50_TelegramBot.pm

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