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    You can run ``make`` to install the init script.
  35
  36 2. Link the munin plugin::
  37
  38    $ cd /etc/munin/plugins
  39    $ ln -s /usr/local/src/usb-wde1-tools/munin/usb-wde1_ usb-wde1_temperature
  40    $ ln -s /usr/local/src/usb-wde1-tools/munin/usb-wde1_ usb-wde1_humidity
  41
  42 3. Configure the plugins
  43    Edit /etc/munin/plugin-conf.d/munin-node and add the following lines::
  44
  45      [usb-wde1_*]
  46      env.logfile /var/spool/usb-wde1/usb-wde1-last
  47      env.host_name House
  48      env.sensors 0 1 7
  49      env.sensor0 Living room
  50      env.sensor1 Kitchen
  51      env.sensor7 Outside
  52
  53 4. Try it::
  54
  55      $ munin-run usb-wde1_temperature autoconf
  56
  57    should echo "yes"
  58    ::
  59
  60      $ munin-run usb-wde1_temperature config
  61
  62    should display the plugin configuration with all environment variables set
  63    ::
  64
  65      $ munin-run usb-wde1_temperature
  66      $ munin-run usb-wde1_humidity
  67
  68    should display the current values from the log file
  69
  70 5. You are done - enjoy.
  71
  72
  73
  74 Debugging & Development
  75 =======================
  76 The dummy data generator is a small php script that generates log lines
  77 as they would come from the usb-wde1 usb port::
  78
  79   $ ./dummy-data-generator.php |./munin/log-single-line.sh test.log
  80
  81 Local (non-installed) plugin setup::
  82
  83   $ cd munin
  84   $ ln -s usb-wde1_ usb-wde1_temperature
  85   $ ln -s usb-wde1_ usb-wde1_humidity
  86   $ cd ..
  87
  88
  89 Running the munin plugin for development purposes is also relatively easy
  90 since you can pass the environment configuration variables
  91 from the munin configuration on the command line::
  92
  93   $ logfile=test.log sensors="0 1 7" ./munin/usb-wde1_temperature
  94
  95 When you have problems running the munin plugin, try to
  96 remove the line ::
  97
  98   env.host_name House
  99
 100 from file ``usb-wde1_``
 101
 102
 103 Permission errors
 104 -----------------
 105 ::
 106
 107     cu: open (/dev/ttyUSB0): Permission denied
 108     cu: /dev/ttyUSB0: Line in use
 109
 110 Only way that I found to fix this was change ownership of `/dev/ttyUSB0` to uucp::
 111
 112      $ chown uucp /dev/ttyUSB0
 113
 114
 115 HTML/Plain text output
 116 ======================
 117 You may use ``htmlreport/gen-html.php`` to generate HTML or plain text
 118 files with the temperature and humidity information.
 119
 120 Install PHP and the PHP rrd extension (``pear install pecl/rrd``) to make it
 121 work.
 122
 123 Run ``gen-html.php`` every 5 minutes.