README.rst

   1 *********************
   2 USB-WDE1 Munin plugin
   3 *********************
   4 Generate graphs for temperature and humidity by utilizing Munin.
   5
   6
   7 Idea
   8 ====
   9 0. Keep a logfile with the most recent single line
  10 1. Use the munin plugin to generate munin-compatible data from the log file
  11
  12
  13 Setup
  14 =====
  15 0. Checkout the munin plugin code::
  16
  17    $ cd /usr/local/src
  18    $ git clone git://git.cweiske.de/usb-wde1-tools.git
  19    $ cd usb-wde1-tools
  20
  21 1. A process needs to watch the USB interface and log the last
  22    line with temperature data into a log file.
  23    You can do that manually with ::
  24
  25      $ socat /dev/ttyUSB0,b9600 STDOUT |./munin/log-single-line.sh test.log
  26
  27    The most easy way is to run ::
  28
  29      $ cd munin && nohup ./usb-wde1-log-last.sh &
  30
  31    once. It backgrounds the logging process and logs into ``/var/spool/usb-wde1/usb-wde1-last``.
  32    This process needs to be started whenever the machine is rebooted.
  33
  34    The ``systemd/`` directory contains a ``usb-wde1-log.service`` file you can copy to
  35    ``/etc/systemd/system/``. After copying it, run::
  36
  37      $ systemctl daemon-reload
  38      $ systemctl start usb-wde1-log
  39      $ systemctl status usb-wde1-log
  40      $ systemctl enable usb-wde1-log
  41
  42 2. Link the munin plugin::
  43
  44    $ cd /etc/munin/plugins
  45    $ ln -s /usr/local/src/usb-wde1-tools/munin/usb-wde1_ usb-wde1_temperature
  46    $ ln -s /usr/local/src/usb-wde1-tools/munin/usb-wde1_ usb-wde1_humidity
  47
  48 3. Configure the plugins:
  49
  50    Edit ``/etc/munin/plugin-conf.d/munin-node`` and add the following lines::
  51
  52      [usb-wde1_*]
  53      env.logfile /var/spool/usb-wde1/usb-wde1-last
  54      env.host_name House
  55      env.sensors 0 1 7
  56      env.sensor0 Living room
  57      env.sensor1 Kitchen
  58      env.sensor7 Outside
  59
  60 4. Try it::
  61
  62      $ munin-run usb-wde1_temperature autoconf
  63
  64    should echo "yes"
  65    ::
  66
  67      $ munin-run usb-wde1_temperature config
  68
  69    should display the plugin configuration with all environment variables set
  70    ::
  71
  72      $ munin-run usb-wde1_temperature
  73      $ munin-run usb-wde1_humidity
  74
  75    should display the current values from the log file
  76
  77 5. You are done - enjoy.
  78
  79
  80
  81 Debugging & Development
  82 =======================
  83 The dummy data generator is a small php script that generates log lines
  84 as they would come from the usb-wde1 usb port::
  85
  86   $ ./dummy-data-generator.php |./munin/log-single-line.sh test.log
  87
  88 Local (non-installed) plugin setup::
  89
  90   $ cd munin
  91   $ ln -s usb-wde1_ usb-wde1_temperature
  92   $ ln -s usb-wde1_ usb-wde1_humidity
  93   $ cd ..
  94
  95
  96 Running the munin plugin for development purposes is also relatively easy
  97 since you can pass the environment configuration variables
  98 from the munin configuration on the command line::
  99
 100   $ logfile=test.log sensors="0 1 7" ./munin/usb-wde1_temperature
 101
 102 When you have problems running the munin plugin, try to
 103 remove the line ::
 104
 105   env.host_name House
 106
 107 from file ``usb-wde1_``
 108
 109
 110 Permission errors
 111 -----------------
 112 ::
 113
 114     cu: open (/dev/ttyUSB0): Permission denied
 115     cu: /dev/ttyUSB0: Line in use
 116
 117 Only way that I found to fix this was change ownership of `/dev/ttyUSB0` to uucp::
 118
 119      $ chown uucp /dev/ttyUSB0
 120
 121
 122 HTML/Plain text output
 123 ======================
 124 You may use ``htmlreport/gen-html.php`` to generate HTML or plain text
 125 files with the temperature and humidity information.
 126
 127 Install PHP and the PHP rrd extension (``pear install pecl/rrd``) to make it
 128 work.
 129
 130 Run ``gen-html.php`` every 5 minutes.
 131
 132
 133 Static USB device name
 134 ======================
 135 When you have multiple serial USB devices attached to the computer,
 136 rebooting may lead to switched ttyUSB* numbers.
 137
 138 A solution is to define a udev rule in ``/etc/udev/rules.d/99-usb-wde1.rules``::
 139
 140   SUBSYSTEM=="tty", ATTRS{serial}=="XQJ2EJEMADDFYBD3", SYMLINK+="usbwde1"
 141
 142 You can find the serial number in ``dmesg`` output::
 143
 144   usb 1-3: new full-speed USB device number 2 using xhci_hcd
 145   usb 1-3: New USB device found, idVendor=10c4, idProduct=ea60, bcdDevice= 1.00
 146   usb 1-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
 147   usb 1-3: Product: ELV USB-WDE1 Wetterdatenempfänger
 148   usb 1-3: Manufacturer: Silicon Labs
 149   usb 1-3: SerialNumber: XQJ2EJEMADDFYBD3
 150
 151 After creating the file, activate it::
 152
 153   $ udevadm control --reload
 154   $ udevadm trigger
 155
 156 Now a file ``/dev/usbwde1`` exists.
 157
 158 Modify ``munin/usb-wde1-log-last.sh`` to use the new device file instead
 159 of ``ttyUSB0``.