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