From 367072b9a0117384e8fab3b79bbbc042b8cb436c Mon Sep 17 00:00:00 2001
From: kaihs <>
Date: Tue, 12 Aug 2014 20:36:46 +0000
Subject: [PATCH] WMBUS: documentation fixes, added german documentation
git-svn-id: https://svn.fhem.de/fhem/trunk@6397 2b470e98-0d58-463d-a4d8-8e2adae1ed80
---
fhem/FHEM/36_WMBUS.pm | 124 +++++++++++++++++++++++++++++++++++++++---
fhem/FHEM/WMBus.pm | 10 +++-
2 files changed, 125 insertions(+), 9 deletions(-)
diff --git a/fhem/FHEM/36_WMBUS.pm b/fhem/FHEM/36_WMBUS.pm
index 7eb82fc23..7d3e108a9 100644
--- a/fhem/FHEM/36_WMBUS.pm
+++ b/fhem/FHEM/36_WMBUS.pm
@@ -305,7 +305,7 @@ WMBUS_Attr(@)
WMBUS - Wireless M-Bus
This module supports Wireless M-Bus meters for e.g. water, heat, gas or electricity.
- Wireless M-Bus is a standard protocol supported by various manufaturers.
+ Wireless M-Bus is a standard protocol supported by various manufacturers.
It uses the 868 MHz band for radio transmissions.
Therefore you need a device which can receive Wireless M-Bus messages, e.g. a CUL with culfw >= 1.59.
@@ -319,6 +319,14 @@ WMBUS_Attr(@)
WMBus messages can be optionally encrypted. In that case the matching AESkey must be specified with attr AESkey. Otherwise the decryption
will fail and no relevant data will be available.
+ Prerequisites
+ This module requires the perl module Crypt::CBC, Digest::CRC and Crypt::OpenSSL::AES (AES only if encrypted messages should be processed).
+ On a debian based system these can be installed with
+
+ sudo apt-get install libcrypt-cbc-perl libdigest-crc-perl libssl-dev
+ sudo cpan -i Crypt::OpenSSL::AES
+
+
Define
@@ -326,14 +334,14 @@ WMBUS_Attr(@)
Normally a WMBus device isn't defined manually but automatically through the autocreate mechanism upon the first reception of a message.
- For manual definition there are two ways.
+ For a manual definition there are two ways.
-
- Specifying a raw WMBus message as received by a CUL. Such a message starts with a lower case 'b' and contains at least 24 hexadecimal digits.
+ By specifying a raw WMBus message as received by a CUL. Such a message starts with a lower case 'b' and contains at least 24 hexadecimal digits.
The WMBUS module extracts all relevant information from such a message.
-
- Explictly specifify the information that uniquely identifies a WMBus device.
+ Explictly specify the information that uniquely identifies a WMBus device.
The manufacturer code, which is is a three letter shortcut of the manufacturer name. See
dlms.com for a list of registered ids.
The identification number is the serial no of the meter.
@@ -358,7 +366,7 @@ WMBUS_Attr(@)
for this "logical" device. An example for the physical device is a CUL.
- AESKey
- A 16 byte AES-Key in hexadecimal digits. Used to decrypt message from meters which have encryption enabled.
+ A 16 byte AES-Key in hexadecimal digits. Used to decrypt messages from meters which have encryption enabled.
@@ -366,7 +374,7 @@ WMBUS_Attr(@)
Readings
Meters can send a lot of different information depending on their type. An electricity meter will send other data than a water meter.
- The information also depends on the manufacturer of the meter. See the WMBus specification on oms-group.org for details.
+ The information also depends on the manufacturer of the meter. See the WMBus specification on oms-group.org for details.
The readings are generated in blocks starting with block 1. A meter can send several data blocks.
Each block has at least a type, a value and a unit, e.g. for an electricity meter it might look like
@@ -379,7 +387,7 @@ WMBUS_Attr(@)
There is also a fixed set of readings.
is_encrypted is 1 if the received message is encrypted.decryption_ok is 1 of a message has either been successfully decrypted or if it is unencrypted.decryption_ok is 1 if a message has either been successfully decrypted or if it is unencrypted.state contains the state of the meter and may contain error message like battery low. Normally it contains 'no error'.
@@ -388,4 +396,106 @@ WMBUS_Attr(@)
=end html
+
+=begin html_DE
+
+
+WMBUS - Wireless M-Bus
+
+ Dieses Modul unterstützt Zähler mit Wireless M-Bus, z. B. für Wasser, Gas oder Elektrizität.
+ Wireless M-Bus ist ein standardisiertes Protokoll das von unterschiedlichen Herstellern unterstützt wird.
+
+ Es verwendet das 868 MHz Band für Radioübertragungen.
+ Daher wird ein Gerät benötigt das die Wireless M-Bus Nachrichten empfangen kann, z. B. ein CUL mit culfw >= 1.59.
+
+ WMBus verwendet zwei unterschiedliche Radioprotokolle, T-Mode und S-Mode. Der Empfänger muss daher so konfiguriert werden, dass er das selbe Protokoll
+ verwendet wie der Sender. Im Falle eines CUL kann das erreicht werden, in dem das Attribut rfmode auf WMBus_T bzw. WMBus_S gesetzt wird.
+
+ WMBus Geräte senden Daten periodisch abhängig von ihrer Konfiguration. Es können u. U. Tage zwischen einzelnen Nachrichten vergehen oder sie können im
+ Minutentakt gesendet werden.
+
+ WMBus Nachrichten können optional verschlüsselt werden. Bei verschlüsselten Nachrichten muss der passende Schlüssel mit dem Attribut AESkey angegeben werden.
+ Andernfalls wird die Entschlüsselung fehlschlagen und es können keine relevanten Daten ausgelesen werden.
+
+ Voraussetzungen
+ Dieses Modul benötigt die perl Module Crypt::CBC, Digest::CRC and Crypt::OpenSSL::AES (AES wird nur benötigt wenn verschlüsselte Nachrichten verarbeitet werden sollen).
+ Bei einem Debian basierten System können diese so installiert werden
+
+ sudo apt-get install libcrypt-cbc-perl libdigest-crc-perl libssl-dev
+ sudo cpan -i Crypt::OpenSSL::AES
+
+
+
+ Define
+
+ define <name> WMBUS [<manufacturer id> <identification number> <version> <type>]|<bHexCode>
+
+ Normalerweise wird ein WMBus Device nicht manuell angelegt. Dies geschieht automatisch bem Empfang der ersten Nachrichten eines Gerätes über den
+ fhem autocreate Mechanismus.
+
+ Für eine manuelle Definition gibt es zwei Wege.
+
+ -
+ Durch Verwendung einer WMBus Rohnachricht wie sie vom CUL empfangen wurde. So eine Nachricht beginnt mit einem kleinen 'b' und enthält mindestens
+ 24 hexadezimale Zeichen.
+ Das WMBUS Modul extrahiert daraus alle benötigten Informationen.
+
+ -
+ Durch explizite Angabe der Informationen die ein WMBus Gerät eindeutig identfizieren.
+ Der Hersteller Code, besteht aus drei Buchstaben als Abkürzung des Herstellernamens. Eine Liste der Abkürzungen findet sich unter
+ dlms.com
+ Die Idenitfikationsnummer ist die Seriennummer des Zählers.
+ Version ist ein Versionscode des Zählers.
+ Typ ist die Art des Zählers, z. B. Wasser oder Elektrizität, kodiert als Zahl.
+
+
+
+
+
+
+
+ Set
+
+ Get
+
+
+ Attributes
+
+ - IODev
+ Setzt den IO oder physisches Gerät welches für den Empfang der Signale für dieses 'logische' Gerät verwendet werden soll.
+ Ein Beispiel für ein solches Gerät ist ein CUL.
+
+ - AESKey
+ Ein 16 Bytes langer AES-Schlüssel in hexadezimaler Schreibweise. Wird verwendet um Nachrichten von Zählern zu entschlüsseln bei denen
+ die Verschlüsselung aktiviert ist.
+
+
+
+
+ Readings
+
+ Zähler können sehr viele unterschiedliche Informationen senden, abhängig von ihrem Typ. Ein Elektrizitätszähler wird andere Daten senden als ein
+ Wasserzähler. Die Information hängt auch vom Hersteller des Zählers ab. Für weitere Informationen siehe die WMBus Spezifikation unter
+ oms-group.org.
+
+ Die Readings werden als Blöck dargestellt, beginnend mit Block 1. Ein Zähler kann mehrere Blöcke senden.
+ Jeder Block enthält zumindest einen Typ, einen Wert und eine Einheit. Für einen Elektrizitätszähler könnte das z. B. so aussehen
+
+ 1:type VIF_ELECTRIC_ENERGY
+ 1:unit Wh
+ 1:value 2948787
+
+
+ Es gibt auch eine Anzahl von festen Readings.
+
+ is_encrypted ist 1 wenn die empfangene Nachricht verschlüsselt ist.decryption_ok ist 1 wenn die Nachricht entweder erfolgreich entschlüsselt wurde oder gar nicht verschlüsselt war.state enthält den Status des Zählers und kann Fehlermeldungen wie 'battery low' enthalten. Normalerweise ist der Wert 'no error'.
+
+
+
+
+=end html_DE
+
=cut
diff --git a/fhem/FHEM/WMBus.pm b/fhem/FHEM/WMBus.pm
index 02fd1eb3e..0845a93d1 100644
--- a/fhem/FHEM/WMBus.pm
+++ b/fhem/FHEM/WMBus.pm
@@ -1,10 +1,16 @@
+# $Id: $
+
package WMBus;
use strict;
use warnings;
use feature qw(say);
-use Crypt::CBC;
-use Digest::CRC;
+use Crypt::CBC; # libcrypt-cbc-perl
+use Digest::CRC; # libdigest-crc-perl
+
+# there seems to be no debian package for Crypt::OpenSSL::AES, so use
+# sudo apt-get install libssl-dev
+# sudo cpan -i Crypt::OpenSSL::AES
require Exporter;
my @ISA = qw(Exporter);