====== vzlogger (en) ======

**vzlogger**...
  * is a tool to read and log measurements of a wide variety of smartmeters and sensors to the volkszaehler.org middleware.
  * runs as a daemon in background.
  * includes a tiny onboard HTTPd to serve realtime readings to the AJAX web frontend.

===== Features =====
  * evaluates middleware return code
  * buffering readings to RAM in case of: 
    * network timeout
    * invalid middleware return code/exception or misconfiguration
  * "local interface" onboard HTTPd ([[http://bugs.volkszaehler.org/view.php?id=9|[9] ]])
  * easily extendable with new sensor/meter protocols
  * runs on embedded devices (Plug-Computers, Routers, Fluksos etc..)
  * portable (conforms to POSIX standards)

===== Installation =====

vzlogger is hosted at [[https://github.com/volkszaehler/vzlogger]].

==== installation ====
for installing the current version, refer to  [[/software/controller/vzlogger/installation_cpp-version]].


===== Meters & Protocols =====

The following table contains an overview of the existing protocols supported by vzlogger:

^ID^Description^Status^Example & Usecases^Links & References^
|''file''|Read from file or fifo|**implemented**|[[http://owfs.org/|OWFS]], ''/proc/'' Filesystem|[[http://linux.die.net/man/3/exec|read(3)]]|
|''exec''|Parse program output|**untested**|[[http://www.digitemp.com/|digitemp]]|[[http://linux.die.net/man/3/exec|exec(3)]]|
|''sml''|SML as used by EDL-21, eHz and SyM<sup>2</sup> meters|**implemented**| |[[software:sml]]|
|''s0''|S0-meter directly or indirectly (USB)  connected to UART or GPIO|**implemented**|Quick and dirty method|[[/hardware/controllers/s0-an-rs232]]|
|''d0''|DLMS/D0 linebased cleartext|**implemented**| | [[development:standards|DIN EN 62056-21]]|
|''w1therm''| Support 1Wire-Sensors based on DSxxxxx|**implemented**| |1Wire Busmaster DS2482 ist Voraussetzung|
|''ocr''|OCR (image processing/recognizing) with USB-Cam|**implemented**| | |
|''random''|Generate random values with a [[http://en.wikipedia.org/wiki/Random_walk|random walk]]|**implemented**|Testing and demonstration | |
|''fluksov2''|Read from Flukso's onboard SPI fifo|**implemented**| |
|''fluksousb''|[[hardware:controllers:fluksousb|]]|**planned**| |[[https://github.com/comsound/flukso|'Bart's Protokoll']]|
|''vsm103''|Voldcraft VSM-103 Drehstromzähler|**planned**| |[[hardware:channels:meters:power:vsm-103|VSM-103]]|
|''kd302''|Energiekostenmessgerät KD 302|**planned**| |[[hardware:channels:meters:power:kd_302|KD 302]]|
|''ccost''|Weatherstation alike commercial smart metering system|**planned**| |[[http://www.currentcost.co.uk/powermeter/|CurrentCost]], [[http://umweltsuende.wordpress.com/2010/09/16/klein-aber-fein/|Umweltsünde]], [[http://www.jibble.org/currentcost/|Jibble]]|
|''tweetawatt''|KillAWatt mod with XBee wireless communication|**planned**| |[[https://github.com/adafruit/Tweet-a-Watt|Sourcecode]], [[http://www.ladyada.net/make/tweetawatt/|Blog]]|
|''ansi''|ANSI standard that describes a protocol used for two-way communications with an electricity meter, mostly used in North American markets.|**planned**| |[[development:standards#ansi|ANSI C12]]|
|''oms''|Open Metering System, based on M-Bus communication|**implemented**| |[[development:standards#oms_group|OMS Group]]|

===== APIs =====

Vzlogger is able to push the gathered data to different backend systems for further processing or storage. This is done via the `api` parameter that is configured per channel. Vzlogger's default backend api is volkszaehler, which is the volkszaehler middleware. Additonal options are mysmartgrid and a 'null' api.

===== Configuration =====
<note>Example configuration is not runable, all the ''meter'' are deactivated</note>
The vzlogger configuration is done with a file containing JSON encoded settings. General settings also can be set via the [[#command_line_parameters|command line]]. You must have at least one meter in your configuration. Channels are optional. A meter can have more channels. Ex. if you want to log to multiple middleware servers.

All meter protocols have own properties. We do not describe them here in detail. Just take a look at the example configuration. It contains a meter for every protocol.

Example configurations are included in the distribution,
see https://github.com/volkszaehler/vzlogger/blob/master/etc/
or in detail here in the wiki: [[software/controller/vzlogger/vzlogger_conf_parameter]]

You can also find different user's configurations in the [[//howto]] section.

You can also use these script: [[http://volkszaehler.github.io/vzlogger/|vzlogger.conf-editor]]

^ Meter ^ Identifier ^ Bemerkung ^
| SML, D0 | Obis-Codes z.B. 1-0:1.8.0 | Welche Obis-Codes/Identifier gesendet werden ist abhängig vom Gerät |
| OMS | Obis-Codes 1.8.0, 2.8.0, 1.7.0, 2.7.0 | max. die 4 Obis-Codes, abhängig vom Gerät |
| S0 | "Impulse" und "Impulse_neg" | Anzahl Impulse (pro Sekunde) |
| S0 | "Power" und "Power_neg" | Impulse pro Zeiteinheit umgerechnet in "Leistung" (per Parameter resolution) |
| 1Wire | ID des 1-Wire-Sensors | Pro gefundenem Sensor ein Identifer mit Temp. als Wert |
| FluksoV2 | 2 pro Channel mittels ChannelId und -ChannelId | Consumption = -ChannelId, Power = +ChannelId |
| File, Exec | (leer) oder per $i erkannter Identifier | z.B. $i = $v => Temperatur = 10 => Identifier "Temperatur", Value = 10 |
| OCR | konfigurierbar | siehe Config Option "identifier" |
| Random |  | kein Identifier Name, nur Wert und Zeit |


===== Command line parameters =====
^parameter^^example (default)^description^
^long^short| | |
|%%--%%config|-c|/etc/vzlogger.conf|configuration file|
|%%--%%log|-o|/var/log/vzlogger/vzlogger.log|log file|
|%%--httpd%%|-l|//off//|activate local interface (tiny HTTPd which serves live readings)|
|%%--httpd-port%%|-p|8081|TCP port for HTTPd|
|%%--%%help|-h| |show short help|
|%%--%%verbose|-v//level//|0|enable verbose output (0-15; 0 = log_alert, 1 = log_error, 3 = log-warning, 5 = log_info, 10 = log-debug, 15 = log_finest)|
|%%--%%version|-V| |show version of vzlogger|

===== Exit-Codes =====
For diagnostics usally the logfile is used because of vzlogger running under control of systemd. In cases this is not possible exit-codes will be shown.\\
E.g. calling ''systemctl status vzlogger'' shows something like: ''Main process exited, code=exited, status=1/FAILURE''
^code^text^meaning^
|1|FAILURE|generic failure, is also generated by unfeasible configuration when vzlogger is closed because of no active meters (example config from git)|
|64|USAGE|cli argument is bad|
|71|OSERR|moving service to background (daemon) didn't work out|
|73|CANTCREAT|vzlogger lacks the rights to write logfile|
|78|CONFIG|brocken syntax in config-file|

===== Links =====
  * [[https://github.com/volkszaehler/vzlogger/|Sourcecode]] on github.com
  * [[https://github.com/volkszaehler/libsml|libsml]]

===== Generate Debian packages for your favorite platform =====

<note important>Package source seems to be defunct!</note>

<code>
$ sudo echo "deb-src http://packages.0l.de/debian/ squeeze main non-free" >> /etc/apt/sources.list
$ sudo apt-get update
$ apt-get source vzlogger
$ cd vzlogger-<version>
$ sudo apt-get install debhelper
$ dpkg-buildpackage -b
</code>