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    $ cd /usr/local/src
  17    $ git clone git://git.cweiske.de/usb-wde1-tools.git
  18    $ cd usb-wde1-tools
  19
  20 1. A process needs to watch the USB interface and log the last
  21    line with temperature data into a log file.
  22    You can do that manually with
  23    $ socat /dev/ttyUSB0,b9600 STDOUT |./munin/log-single-line.sh test.log
  24
  25    The most easy way is to run
  26    $ cd munin && nohup ./usb-wde1-log-last.sh &
  27    once. It backgrounds the logging process and logs into /tmp/usb-wde1-last.
  28    This process needs to be started whenever the machine is rebooted.
  29
  30 2. Link the munin plugin:
  31    $ cd /etc/munin/plugins
  32    $ ln -s /usr/local/src/usb-wde1-tools/munin/usb-wde1_ usb-wde1_temperature
  33    $ ln -s /usr/local/src/usb-wde1-tools/munin/usb-wde1_ usb-wde1_humidity
  34
  35 3. Configure the plugins
  36    Edit /etc/munin/plugin-conf.d/munin-node and add the following lines:
  37    [usb-wde1_*]
  38    env.logfile /tmp/usb-wde1-last
  39    env.host_name House
  40    env.sensors 0 1 7
  41    env.sensor0 Living room
  42    env.sensor1 Kitchen
  43    env.sensor7 Outside
  44
  45 4. Try it:
  46    $ munin-run usb-wde1_temperature autoconf
  47     - should echo "yes"
  48    $ munin-run usb-wde1_temperature config
  49     - should display the plugin configuration with all environment variables
  50       set
  51    $ munin-run usb-wde1_temperature
  52    $ munin-run usb-wde1_humidity
  53     - should display the current values from the log file
  54
  55 5. You are done - enjoy.
  56
  57
  58
  59 Debugging & Development
  60 =======================
  61 The dummy data generator is a small php script that generates log lines
  62 as they would come from the usb-wde1 usb port:
  63 $ ./dummy-data-generator.php |./munin/log-single-line.sh test.log
  64
  65 Local (non-installed) plugin setup:
  66 $ cd munin
  67 $ ln -s usb-wde1_ usb-wde1_temperature
  68 $ ln -s usb-wde1_ usb-wde1_humidity
  69 $ cd ..
  70
  71
  72 Running the munin plugin for development purposes is also relatively easy
  73 since you can pass the environment configuration variables
  74 from the munin configuration on the command line:
  75 $ logfile=test.log sensors="0 1 7" ./munin/usb-wde1_temperature
  76
  77 When you have problems running the munin plugin, try to
  78 remove the line
  79  env.host_name House
  80 from file usb-wde1_
  81
  82
  83 Permission errors
  84 -----------------
  85
  86     cu: open (/dev/ttyUSB0): Permission denied
  87     cu: /dev/ttyUSB0: Line in use
  88
  89 Only way that I found to fix this was change ownership of `/dev/ttyUSB0` to uucp::
  90
  91      $ chown uucp /dev/ttyUSB0
  92
  93
  94 HTML/Plain text output
  95 ======================
  96 You may use ``htmlreport/gen-html.php`` to generate HTML or plain text
  97 files with the temperature and humidity information.
  98
  99 Install PHP and the PHP rrd extension (``pear install pecl/rrd``) to make it
 100 work.
 101
 102 Run ``gen-html.php`` every 5 minutes.