mirror of
https://github.com/weewx/weewx.git
synced 2026-04-20 09:37:02 -04:00
a54cd82447
Clarified overriding of options in weewx.conf Clarified base temperatures for heating and cooling degree days.
2173 lines
95 KiB
HTML
2173 lines
95 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
|
|
<!-- $Revision$ -->
|
|
<!-- $Author$ -->
|
|
<!-- $Date$ -->
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us" />
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>The Weewx weather system</title>
|
|
<style type="text/css">
|
|
body {
|
|
font: 11pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
}
|
|
p {
|
|
font: 11pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
}
|
|
ol {
|
|
font: 11pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
}
|
|
ul {
|
|
font: 11pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
}
|
|
li {
|
|
font: 11pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
}
|
|
dl {
|
|
font: 11pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
}
|
|
dt {
|
|
font: 11pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
}
|
|
dd {
|
|
font: 11pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
}
|
|
h1 {
|
|
font: normal normal bold 18pt Verdana, arial, sans-serif;
|
|
color: teal;
|
|
border: 1px solid black;
|
|
border-bottom: 2px solid black;
|
|
border-right: 2px solid black;
|
|
background-color: #e8e8e8;
|
|
padding-left: .5em;
|
|
padding-right: .5em;
|
|
margin-top: 60pt;
|
|
}
|
|
h2 {
|
|
font: 15pt Verdana,arial,sans-serif;
|
|
color: teal;
|
|
border: 1px solid black;
|
|
background-color: #e8e8e8;
|
|
padding-left: .5em;
|
|
padding-right: .5em;
|
|
margin-top: 30pt;
|
|
}
|
|
h3 {
|
|
font: 12pt Verdana, arial, sans-serif;
|
|
color: teal;
|
|
border: 1px solid black;
|
|
background-color: #e8e8e8;
|
|
padding-left: .5em;
|
|
padding-right: .5em;
|
|
}
|
|
h4 {
|
|
font: 12pt Verdana,arial,sans-serif;
|
|
color: black;
|
|
font-weight: bold;
|
|
}
|
|
.code {
|
|
font-family: "Courier New", Courier, monospace;
|
|
}
|
|
table {
|
|
border-style: solid;
|
|
border-width: 1px;
|
|
border-collapse: collapse;
|
|
}
|
|
td {
|
|
border-style: solid;
|
|
border-width: 1px;
|
|
}
|
|
.indent {
|
|
margin-left: 40px;
|
|
}
|
|
.tty {
|
|
font-family: "Courier New", Courier, monospace;
|
|
margin-left: 40px;
|
|
margin-top: 0px;
|
|
margin-bottom: 0px;
|
|
background-color: #FFFFCC;
|
|
}
|
|
.title {
|
|
text-align: center;
|
|
margin-top: 0px;
|
|
}
|
|
.config_option {
|
|
font-family: "Courier New", Courier, monospace;
|
|
font-weight: normal;
|
|
}
|
|
.config_section {
|
|
font-family: "Courier New", Courier, monospace;
|
|
}
|
|
.config_important {
|
|
font-family: "Courier New", Courier, monospace;
|
|
font-weight: bold;
|
|
color: #0000FF;
|
|
}
|
|
.bold_n_blue {
|
|
color: #0000FF;
|
|
}
|
|
.style1 {
|
|
background-color: #FFFFCC;
|
|
}
|
|
.style2 {
|
|
border-style: solid;
|
|
}
|
|
.style3 {
|
|
font-size: xx-small;
|
|
}
|
|
</style>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1 class="title">The <span class="code">weewx</span> weather system<br />
|
|
Version 1.5</h1>
|
|
<h1>Table of Contents</h1>
|
|
<ol>
|
|
<li>
|
|
<p class="indent"><a href="#Copyright">Copyright</a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#About_weewx">About <span class="code">weewx</span></a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Downloading_weewx">Downloading
|
|
<span class="code">weewx</span></a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Prerequisites">Prerequisites</a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Installing_weewx">Installing <span class="code">
|
|
weewx</span></a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Configuring_weewx">Configuring
|
|
<span class="code">weewx</span></a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Running_weewx">Running <span class="code">weewx</span></a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Compatibility_with_wview">Compatibility with
|
|
<span class="code">wview</span></a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Monitoring_weewx">Monitoring <span class="code">
|
|
weewx</span></a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Types">Advanced topics: types</a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#HTML_Generation">Advanced topics: customizing HTML
|
|
generation</a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Architectural_notes">Advanced topics: architectural
|
|
notes</a></p>
|
|
</li>
|
|
<li>
|
|
<p class="indent"><a href="#Customizing_weewx">Advanced topics: customizing
|
|
the internal <span class="code">weewx</span> engines</a></p>
|
|
</li>
|
|
</ol>
|
|
<h1>1. <a name="Copyright">Copyright</a></h1>
|
|
<p>(c) 2009, 2010 by Tom Keffer <<a href="mailto:tkeffer@gmail.com">tkeffer@gmail.com</a>></p>
|
|
<p>This program is free software: you can redistribute it and/or modify it under
|
|
the terms of the GNU General Public License as published by the Free Software Foundation,
|
|
either version 3 of the License, or (at your option) any later version. </p>
|
|
<p>This program is distributed in the hope that it will be useful, but WITHOUT ANY
|
|
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
|
|
PARTICULAR PURPOSE. See the GNU General Public License for more details. </p>
|
|
<p>You should have received a copy of the GNU General Public License along with
|
|
this program. If not, see <http://www.gnu.org/licenses/>
|
|
<a href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses</a>.</p>
|
|
<h1>2. <a name="About_weewx">About <span class="code">weewx</span></a></h1>
|
|
<p><span class="code">weewx</span> is a piece of software, written in
|
|
<a href="http://www.python.org">Python</a>, that interacts with your
|
|
weather station to produce plots, reports, and HTML pages. It can
|
|
optionally publish to the <a href="http://www.wunderground.com">
|
|
WeatherUnderground</a>. It uses modern software concepts, making it
|
|
simple, robust, and easy to extend. For an example station see
|
|
<a href="http://www.threefools.org/weewx">Hood River West</a>.</p>
|
|
<p>I wrote <span class="code">weewx</span> over the winter of 2008-2009 for two reasons: it was a wet and
|
|
miserable winter here in Oregon with not much else to do, so there was no good reason
|
|
not to, and because I wanted a simple, easy-to-understand server to run my Davis
|
|
VantagePro2 weather station on a Linux box. I had been using
|
|
<a href="http://www.wviewweather.com/">wview</a>, which is a
|
|
high-performance and feature rich system authored by Mark Teel
|
|
with lots of users. Written in C, it's an efficient system that can run on very underpowered boxes. In exchange, it's huge
|
|
(45,000+ lines of code), tightly integrated in with its companion library, radlib (another
|
|
14,000+ lines), and very complex, making it difficult to understand and reliably
|
|
customize. I wanted something more modern and much simpler.</p>
|
|
<p>Having made a career in C++ and Java, I was also interested in some more
|
|
modern languages, so I thought I'd try either Python or Ruby (although, truth be
|
|
told, the roots of Python are nearly as old as C++!). I ended up picking Python because
|
|
its libraries are more mature and there are many mores choices for third party
|
|
libraries.</p>
|
|
<p><span class="code">Weewx</span> weighs in at under 4,000 lines of code, plus
|
|
another 2,500 comment lines. Because it is pure Python, it requires no makefiles, no builds, no special installs. However, to be fair, it is missing features such as support for other weather stations. On the other hand, it offers very powerful configuration
|
|
and templating options, as well as an internally extensible engine, making it easy to customize.
|
|
Its internal modular design and use of modern exception handling make it very
|
|
robust and difficult to crash. It is also architecturally
|
|
very simple and easy to understand.</p>
|
|
<h1>3. <a name="Downloading_weewx">Downloading <span class="code">weewx</span></a></h1>
|
|
<p><span class="code">weewx</span> can be downloaded from its
|
|
<a href="https://sourceforge.net">SourceForge</a> page:
|
|
<a href="https://sourceforge.net/projects/weewx">https://sourceforge.net/projects/weewx</a>.
|
|
</p>
|
|
<h1>4. <a name="Prerequisites">Prerequisites</a></h1>
|
|
<h2>4.1 Python</h2>
|
|
<p>Python V2.5 or V2.6 is required. The newer V3.0 distribution will not work.</p>
|
|
<h2>4.2 Required packages</h2>
|
|
<p>The following external packages are required to use <span class="code">weewx</span>.</p>
|
|
<ol>
|
|
<li><a href="http://www.sqlite.org/">sqlite3</a> (Version 3.5 or greater) A
|
|
SQL database written in C, which <span class="code">weewx</span> uses to store
|
|
data pulled from the weather station. Comes with Debian and many other Linux
|
|
distributions.</li>
|
|
<li><a href="http://pypi.python.org/pypi/pysqlite/">pysqlite</a> (Version 2.5
|
|
or greater) The Python interface to sqlite3.</li>
|
|
<li><a href="http://pypi.python.org/pypi/configobj/">configobj</a> (Version
|
|
4.5 or greater) Manages the configuration file <span class="code">weewx.conf</span>.</li>
|
|
<li><a href="http://pypi.python.org/pypi/pyserial/2.4">pyserial</a> (Version
|
|
1.35 or greater) Manages the serial connection to the weather station.</li>
|
|
<li><a href="http://www.cheetahtemplate.org">Cheetah</a> (Version 2.0 or greater)
|
|
The HTML templating engine.</li>
|
|
<li><a href="http://pypi.python.org/pypi/PIL">Python Imaging Library</a> (Version
|
|
1.1.6 or greater) Also known as PIL, this is included in many Python distributions.</li>
|
|
</ol>
|
|
<p>There are two general strategies for installing these prerequisites:</p>
|
|
<ol>
|
|
<li>Use operating system tools, such as <span class="code">apt-get</span> (or
|
|
its graphical equivalent Synaptic Package Manager) for Debian/Ubuntu or
|
|
<span class="code">yast</span> for SuSE; or</li>
|
|
<li>Use the Python tool <span class="code">
|
|
<a href="http://pypi.python.org/pypi/setuptools">easy_install</a></span>.</li>
|
|
</ol>
|
|
<p>Option #1 is easier, but if your Linux distribution does not come with such tools,
|
|
you may have to use <span class="code">easy_install</span>. Brief instructions for
|
|
both approaches are given below.</p>
|
|
<h3>Installation on Debian distributions (including Ubuntu) using
|
|
<span class="code">apt-get</span></h3>
|
|
<p>The instructions that follow are for using the Debian tool <span class="code">
|
|
apt_get</span>, but the same package names would be used should you chose to use
|
|
a graphical interface such as the Synaptic Package Manager.</p>
|
|
<h4>sqlite3</h4>
|
|
<p>My Ubuntu 8.10 system came with V3.5.9, which works just fine. However, if you
|
|
need to install:</p>
|
|
<p class="tty">sudo apt-get install sqlite3</p>
|
|
<h4>pysqlite</h4>
|
|
<p>Easily installed:</p>
|
|
<p class="tty">sudo apt-get install python-pysqlite2</p>
|
|
<h4>configobj</h4>
|
|
<p>Easily installed:</p>
|
|
<p class="tty">sudo apt-get install python-configobj</p>
|
|
<h4>pyserial</h4>
|
|
<p>Easily installed:</p>
|
|
<p class="tty">sudo apt-get install python-serial</p>
|
|
<h4>Cheetah</h4>
|
|
<p>Easily installed:</p>
|
|
<p class="tty">sudo apt-get install python-cheetah</p>
|
|
<h4>Python Imaging Library (PIL)</h4>
|
|
<p>My version of Python came with V1.1.6, which works great. However, some users
|
|
have reported having to install PIL. In this case</p>
|
|
<p class="tty">sudo apt-get install python-imaging</p>
|
|
<h3>Installation on SuSE using <span class="code">yast</span></h3>
|
|
<p>My SuSE 11.1 system came with some of the prerequisites installed, some available
|
|
through <span class="code">yast</span>, and three that required
|
|
<span class="code">easy_install</span>. To start, you will have to install the gcc
|
|
compiler:</p>
|
|
<p class="tty">sudo yast -i gcc</p>
|
|
<p>Then install <span class="code">easy_install</span>:</p>
|
|
<p class="tty">sudo yast -i python-setuptools</p>
|
|
<p>On my system, some scripts wanted to install themselves into
|
|
<span class="code">/usr/local/lib/python2.6/site-packages</span>, which didn't exist.
|
|
If this is the case, you may have to create these directories before running
|
|
<span class="code">easy_install</span>:</p>
|
|
<p class="tty">sudo mkdir /usr/local/lib/python2.6</p>
|
|
<p class="tty">sudo mkdir /usr/local/lib/python2.6/site-packages</p>
|
|
<h4>sqlite3</h4>
|
|
<p>My SuSE 11.1 system came with V3.6.4, which works just fine. However, if you
|
|
need to install:</p>
|
|
<p class="tty">sudo yast -i sqlite3</p>
|
|
<h4>pysqlite</h4>
|
|
<p>Install using <span class="code">easy_install</span>. See
|
|
<a href="#pysqlite_using_easy_install">comments below</a> about installing pysqlite
|
|
using <span class="code">easy_install</span>. On my SuSE 11.1 system, I had to install
|
|
the gcc compiler and the sqlite3 development environment first:</p>
|
|
<p class="tty">sudo yast -i gcc</p>
|
|
<p class="tty">sudo yast -i sqlite-devel</p>
|
|
<p>Then I was able to install pysqlite using <span class="code">easy_install</span>.
|
|
However, because the hosting site for pysqlite had changed recently, I had to give
|
|
the URL explicitly:</p>
|
|
<p class="tty">sudo easy_install
|
|
<a href="http://pysqlite.googlecode.com/files/pysqlite-2.5.5.tar.gz">http://pysqlite.googlecode.com/files/pysqlite-2.5.5.tar.gz</a></p>
|
|
<h4>configobj</h4>
|
|
<p>Install using <span class="code">easy_install</span>:</p>
|
|
<p class="tty">sudo easy_install configobj</p>
|
|
<h4>pyserial</h4>
|
|
<p>Install using <span class="code">yast</span>:</p>
|
|
<p class="tty">sudo yast-i python-serial</p>
|
|
<h4>Cheetah</h4>
|
|
<p>Install using <span class="code">easy_install</span> (My system emitted a bunch
|
|
of, apparently, benign warnings):</p>
|
|
<p class="tty">sudo easy_install Cheetah</p>
|
|
<h4>Python Imaging Library (PIL)</h4>
|
|
<p>Install using <span class="code">yast</span></p>
|
|
<p class="tty">sudo yast -i python-imaging</p>
|
|
<h3>Installation using <span class="code">easy_install</span></h3>
|
|
<p>An alternative approach to installing the required packages is by using the Python
|
|
setup tool "<span class="code">easy_install</span>", part of the
|
|
<a href="http://pypi.python.org/pypi/setuptools">python-setuptools package</a>.
|
|
Refer to their instructions on how to install this tool.</p>
|
|
<p>Once <span class="code">easy_install</span> has been installed, installing the rest of the packages is very easy.</p>
|
|
<h4>sqlite3</h4>
|
|
<p>My Ubuntu 8.10 system came with sqlite V3.5.9, which works just fine. If you do not
|
|
have sqlite3, refer to <a href="http://www.sqlite.org">the sqlite webpage</a> for
|
|
installation instructions.</p>
|
|
<h4><a name="pysqlite_using_easy_install">pysqlite</a></h4>
|
|
<p>While Version 2.3.X of <a href="http://pypi.python.org/pypi/pysqlite/">pysqlite</a>
|
|
is included with many versions of Python, the more recent 2.5.X or greater is required
|
|
in order to take advantage of transaction contexts. Hence, you may have to install
|
|
or upgrade. Because pysqlite builds a C library, you may have to install the Python
|
|
development environment first, if you have not already done so. Generally, this
|
|
means installing the gcc compiler. You may also have to install the sqlite3 development
|
|
environment as well.</p>
|
|
<p>With the development environment in place, you can easily build and install pysqlite:</p>
|
|
<p class="tty">easy_install pysqlite</p>
|
|
<p>If your system already has a version of pysqlite installed, but it is not a high
|
|
enough version (<span class="code">easy_install</span> will tell you the version
|
|
you have), then you may have to force an upgrade:</p>
|
|
<p class="tty">easy_install --upgrade pysqlite</p>
|
|
<p>Note that at the time of this writing (24 Oct 2009), the hosting site for pysqlite
|
|
has changed to one on <a href="http://pysqlite.googlecode.com">googlecode</a>, and
|
|
<span class="code">easy_install</span> could not find it. You may have to find and
|
|
give the URL explicitly to <span class="code">easy_install</span> (adjust version
|
|
numbers as necessary):</p>
|
|
<p class="tty">easy_install http://pysqlite.googlecode.com/files/pysqlite-2.5.5.tar.gz</p>
|
|
<h4>configobj</h4>
|
|
<p>Easily installed:</p>
|
|
<p class="tty">easy_install configobj</p>
|
|
<h4>pyserial</h4>
|
|
<p class="indent"><span class="code">easy_install pyserial</span></p>
|
|
<h4>Cheetah</h4>
|
|
<p class="indent"><span class="code">easy_install Cheetah</span></p>
|
|
<h4>Python Imaging Library (PIL)</h4>
|
|
<p>My version of Python came with V1.1.6, which works great.</p>
|
|
<h2>4.3 System requirements</h2>
|
|
<p>I run <span class="code">weewx</span> on a 500MHz system with an AMD Geode processor
|
|
and 512 MB of memory. Configured this way, it consumes about 5% of the CPU
|
|
and about 40MB of total memory.</p>
|
|
<h2>4.4 Weather station hardware requirements</h2>
|
|
<p>At this point, only the
|
|
<a href="http://www.davisnet.com/weather/products/vantagepro.asp">Davis VantagePro2</a>
|
|
is supported, and even then, only the "Revision B" version (firmware dated on or
|
|
after 22 April 2002). It would be very easy to port to a "Revision A" station or
|
|
even the original VantagePro, but I don't have access to the hardware to test it.</p>
|
|
<h1>5. <a name="Installing_weewx">Installing <span class="code">weewx</span></a></h1>
|
|
<p>Because <span class="code">weewx</span> is "Pure Python", that is it is 100%
|
|
Python with no "C" modules to compile, installing it is very easy. Furthermore,
|
|
it uses the standard Python <a href="http://docs.python.org/install/index.html">
|
|
distutils</a> install method, which is very easy and flexible. Detailed instructions
|
|
follow.</p>
|
|
<h2>5.1 Unpacking</h2>
|
|
<p>Start by unpack the tar ball (substitute your version for X.Y.Z) into any convenient
|
|
directory where you have write permission</p>
|
|
<p class="tty">tar xvf weewx-X.Y.Z</p>
|
|
<p>Then change directory into it:</p>
|
|
<p class="tty">cd weewx-X.Y.Z</p>
|
|
<h2>5.1 Choosing the <span class="code">WEEWX_ROOT</span> directory</h2>
|
|
<p>Next step is figuring out where you want to install <span class="code">weewx</span>.
|
|
If <span class="code"><em>WEEWX_ROOT</em></span> symbolizes the root location of
|
|
the <span class="code">weewx</span> directory hierarchy, then</p>
|
|
<ul>
|
|
<li><span class="code"><em>$WEEWX_ROOT</em>/bin</span> is where the Python packages
|
|
and scripts are installed;</li>
|
|
<li><span class="code"><em>$WEEWX_ROOT</em>/weewx.conf</span> is the configuration
|
|
file;</li>
|
|
<li><span class="code"><em>$WEEWX_ROOT</em>/templates</span> is where the html
|
|
templates live;</li>
|
|
<li><span class="code"><em>$WEEWX_ROOT</em>/archive</span> is the directory
|
|
where the sqlite3 databases live;</li>
|
|
<li><em>$</em><span class="code"><em>WEEWX_ROOT</em>/public_html</span> is where
|
|
generated html and .png images are put.</li>
|
|
</ul>
|
|
<p>By default, the location for <span class="code"><em>WEEWX_ROOT</em></span> is
|
|
<span class="code">/home/weewx</span>. However, it can be changed by editing the
|
|
file <span class="code">setup.cfg</span>. If you wish to install someplace else,
|
|
open up <span class="code">setup.cfg</span> and change the line</p>
|
|
<p class="tty">home = /home/weewx</p>
|
|
<p>to reflect your decision.</p>
|
|
<h2>5.2 Build and install</h2>
|
|
<p>Build the distribution</p>
|
|
<p class="tty">./setup.py build</p>
|
|
<p>(Because <span class="code">weewx</span> is pure Python this doesn't actually
|
|
build anything, but it does arrange files for the final installation)</p>
|
|
<p>Then install it. If you have write permission in the directory where
|
|
<span class="code">weewx</span> will go (<em>i.e.</em>, <span class="code"><em>$WEEWX_ROOT</em></span>),
|
|
then type</p>
|
|
<p class="tty">./setup.py install</p>
|
|
<p>Otherwise, if you do not have write permission, you will have to use sudo:</p>
|
|
<p class="tty">sudo ./setup.py install</p>
|
|
<h3>Upgrading</h3>
|
|
<p>Before upgrading from a previous version of <span class="code">weewx</span>,
|
|
check the upgrade notes, found in file <a href="upgrading.htm">upgrading.htm</a>, to see if there any
|
|
specific actions you need to do. </p>
|
|
<p>You then generally follow the procedure above. </p>
|
|
<p><strong>In particular, before starting, be sure to set </strong>
|
|
<span class="code"><strong>home</strong></span><strong> in the file </strong> <span class="code">
|
|
<strong>setup.cfg</strong></span><strong>. </strong> </p>
|
|
<p>The build and install process will do the following for you.</p>
|
|
<ul>
|
|
<li>Save your old template directories as <span class="code"><em>$WEEWX_ROOT</em>/templates.YYYYMMDDHHMMSS</span>
|
|
where YYYYMMDDHHMMSS is a timestamp;</li>
|
|
<li>Merge any changes you've made to your old configuration file
|
|
<span class="code">weewx.conf</span> into the new configuration file, then install
|
|
the merged copy (this effectively causes changes you've made to override the
|
|
values in the shipped version of <span class="code">weewx.conf</span>);</li>
|
|
<li>Save a copy of your old <span class="code">weewx.conf</span> as
|
|
<span class="code"><em>$WEEWX_ROOT</em>/weewx.conf.YYYYMMDDHHMMSS</span>.</li>
|
|
</ul>
|
|
<h2>5.3 Permissions</h2>
|
|
<p>Strictly speaking it is not necessary to install or run <span class="code">weewx</span>
|
|
with root privileges. You only need read/write access to the serial port for your
|
|
hardware. For example, if your hardware has a USB interface, on Ubuntu and SuSE:</p>
|
|
<p class="tty">sudo chmod a+rw /dev/ttyUSB0</p>
|
|
<p>Once done, if you edit <span class="code">setup.cfg</span> to install into a
|
|
directory where you have write permissions, you can install and run
|
|
<span class="code">weewx</span> without any root privileges at all. </p>
|
|
<h2>5.4 Final note on installation</h2>
|
|
<p>Because <span class="code">weewx</span> is pure Python, it actually does not
|
|
have to be "built" and "installed" at all! You can just simply run it out of whatever
|
|
directory you unpack it into (after, of course, editing <span class="code">weewx.conf</span>
|
|
to reflect your local environment). I do this all the time when testing. However,
|
|
the <span class="code">setup.py</span> script does include special provisions for
|
|
updating your configuration file <span class="code">weewx.conf</span>, which can
|
|
be handy when upgrading to a later version.</p>
|
|
<h1>6. <a name="Configuring_weewx">Configuring <span class="code">weewx</span></a></h1>
|
|
<p>This section covers configuring your archive and statistical database (if necessary;
|
|
this step is required only if you are moving from
|
|
<a href="http://www.wviewweather.com/">wview</a> to <span class="code">weewx</span>), configuring your weather
|
|
station, and configuring the configuration file <span class="code">weewx.conf</span>.</p>
|
|
<p>In the following, <span class="code"><em>$WEEWX_ROOT</em></span> refers to the
|
|
<span class="code">weewx</span> root directory, generally <span class="code">/home/weewx</span>.
|
|
</p>
|
|
<h2>6.1 Configuring the databases</h2>
|
|
<p>NOTE: This section is necessary only if you are moving from
|
|
<a href="http://www.wviewweather.com/">wview</a> to <span class="code">weewx</span>
|
|
and wish to transfer your old data over. If you are starting afresh, you do not
|
|
need to follow this section — the two main databases are created and populated automatically
|
|
by <span class="code">weewx</span>.</p>
|
|
<p>If you wish to transfer your wview data, note that two databases are maintained by weewx:</p>
|
|
<ul>
|
|
<li><span class="code"><em>$WEEWX_ROOT/$archive_file</em></span> (nominally
|
|
<span class="code">/home/weewx/archive/weewx.sdb</span>)</li>
|
|
<li><span class="code"><em>$WEEWX_ROOT/$stats_file</em></span> (nominally
|
|
<span class="code">/home/weewx/archive/stats.sdb</span>)</li>
|
|
</ul>
|
|
<p>Because wview and <span class="code">weewx</span> use identical schema for the first of these (the archive
|
|
database), it can be just copied over. However, the second (the statistical databases)
|
|
is different — the <span class="code">weewx</span> statistical database must be built manually and backfilled.
|
|
This is done using the configuration script <span class="code">configure.py</span>.
|
|
</p>
|
|
<p>Here's a summary of how to transfer your wview data to <span class="code">weewx</span>.</p>
|
|
<p class="tty">mkdir <em>$WEEWX_ROOT</em>/archive</p>
|
|
<p class="tty">cp /usr/local/var/wview/archive/wview-archive.sdb <span class="code"><em>$WEEWX_ROOT</em></span>/archive/weewx.sdb</p>
|
|
<p class="tty"><em>$WEEWX_ROOT</em>/bin/configure.py --create-stats <em>$WEEWX_ROOT</em>/weewx.conf</p>
|
|
<p class="tty"><em>$WEEWX_ROOT</em>/bin/configure.py --backfill-stats <em>$WEEWX_ROOT</em>/weewx.conf</p>
|
|
<p>If your existing database is large, backfilling could take some time. On my modest
|
|
500 MHz <a href="http://www.fit-pc.com/new/fit-pc-slim-specifications.html">fit-PC</a>
|
|
with 512 MB of memory it took a little over 4 minutes for a year and a half (25
|
|
MB) of data (while wview was running in the background).</p>
|
|
<h2>6.2 Configuring your weather station</h2>
|
|
<p>The only two variables <span class="code">weewx</span> tries to manage on the
|
|
VantagePro are the time and the archive interval. </p>
|
|
<h3>Time</h3>
|
|
<p>The time on the VP is automatically synchronized with the <span class="code">
|
|
weewx</span> server nominally every four hours (changeable by the user). You should run a
|
|
<a href="http://www.ntp.org/">NTP</a> daemon on your
|
|
server to insure that it is synchronized with the correct time. Doing so will greatly
|
|
reduce errors, especially if you send data to services such as the Weather Underground.</p>
|
|
<h3><a name="Archive_interval">Archive interval</a></h3>
|
|
<p>The archive interval is set in the main configuration file <span class="code">
|
|
<em>$WEEWX_ROOT</em>/weewx.conf. </span>Look for the entry <span class="code">archive_interval</span>
|
|
in the <span class="code">VantagePro</span> section. Set it to the number of seconds.
|
|
Valid entries are 60, 300, 600, 900, 1800, 3600, and 7200. However, if you are ftp'ing
|
|
lots of files to a server, setting it to 60 seconds may not give enough time to
|
|
have them all uploaded before the next archive record is due. If this is the case,
|
|
you should pick an archive interval of at least 300 seconds, or trim the number
|
|
of files you are using.</p>
|
|
<p>After setting to the desired interval, run the <span class="code">configure.py</span>
|
|
script to set it on the VantagePro. If it differs from the old archive interval,
|
|
the main memory log of the VantagePro will be cleared. </p>
|
|
<p class="tty"><em>$WEEWX_ROOT</em>/bin/configure.py --configure-VantagePro $WEEWX_ROOT/weewx.conf</p>
|
|
<h2>6.3 Editing the configuration file <span class="code">weewx.conf</span></h2>
|
|
<p>Virtually every conceivable configuration option is in the configuration file
|
|
<span class="code"><em>$WEEWX_ROOT</em>/weewx.conf</span>. Most of the important
|
|
ones are up near the top of the file. They are all documented in this section, although
|
|
you can safely ignore most of them. The truly important ones, the ones you are likely
|
|
to have to customize for your station, are shown in <span class="bold_n_blue">
|
|
<strong>bold face and in blue</strong></span>. </p>
|
|
<p>Default values are provided for many of them, meaning that if they are not listed
|
|
in the configuration file <em>at all</em>, <span class="code">weewx</span> will
|
|
pick sensible values. When the documentation below gives a "default value" this
|
|
is what it means. However, all options have been given values in the configuration
|
|
file that ships with <span class="code">weewx</span>, so you can see what they look
|
|
like. The value given in this shipped configuration file is not necessarily the
|
|
same as the "default value".</p>
|
|
<p>What follows is organized by the different sections of the configuration file.</p>
|
|
<h3>General</h3>
|
|
<p>The options declared at the top are not actually part of any section. There are
|
|
two:</p>
|
|
<h4 class="config_option">debug</h4>
|
|
<p>Set to 1 to have the program perform extra debug checks, as well as emit extra
|
|
information on the log file. Otherwise, set to 0. Default is 0 (no debug).</p>
|
|
<h4 class="config_option">socket_timeout</h4>
|
|
<p>Set to how long to wait before declaring a socket time out. This is used when
|
|
FTP'ing data to a web server or sending data to the Weather Underground. Twenty
|
|
(20) seconds is reasonable. Default is 20.</p>
|
|
<h3 class="config_section">[Station]</h3>
|
|
<p>This section covers options relating to the entire weather station setup. </p>
|
|
<h4 class="config_option">WEEWX_ROOT</h4>
|
|
<p>Set to the root directory of the <span class="code">weewx</span> file hierarchy
|
|
for this station, nominally '<span class="code">/home/weewx</span>'. This value
|
|
will be set automatically by the setup script <span class="code">setup.py</span>
|
|
to reflect the choice you made in the configuration file <span class="code">setup.cfg</span>.
|
|
Required. No default.</p>
|
|
<h4 class="config_important">location</h4>
|
|
<p>The station location should be a string that describes the geography of where
|
|
you weather station is located, such as 'Hood River, Oregon'. Required. No default.</p>
|
|
<h4 class="config_important">latitude<br />
|
|
longitude</h4>
|
|
<p>The lat/lon should be set in decimal degrees, negative for southern and eastern
|
|
hemispheres, respectively. Required. No default.</p>
|
|
<h4 class="config_important">altitude</h4>
|
|
<p>Should be set to the altitude of the station in the same units specified in
|
|
<span class="code"><a href="#group_altitude">group_altitude</a></span>. Required. No default.</p>
|
|
<h4 class="config_important">rain_year_start</h4>
|
|
<p>If your area uses a rain year that starts on something other than the first of
|
|
January, you may want to set this variable. For example, set to 10 if your rain
|
|
year starts in October (as mine does). Default is 1.</p>
|
|
<h4 class="config_important">radar_url</h4>
|
|
<p>This variable is available in the HTML templates. Set it to an appropriate URL
|
|
to display a radar image for your area. No default.</p>
|
|
<h4 class="config_option"><span class="config_important">heating_base<br />
|
|
cooling_base</span></h4>
|
|
<p>Set to the base temperature for calculating heating and cooling degree-days,
|
|
respectively, in the same units specified in <span class="code">
|
|
<a href="#group_temperature">group_temperature</a></span>. The default is 65.0 for both.</p>
|
|
<h4 class="config_option">week_start</h4>
|
|
<p>Start of the week. 0=Monday, 1= Tuesday, ... , 6 = Sunday. Default is 6
|
|
(Sunday)</p>
|
|
<h4 class="config_option">hemispheres</h4>
|
|
<p>Set to suitable abbreviations for the four hemispheres. Default is "N", "S",
|
|
"E", "W"</p>
|
|
<h4 class="config_option">clock_check</h4>
|
|
<p>How often to check the station's onboard clock for drift, in seconds. Default
|
|
is 14400 (every 4 hours)</p>
|
|
<h4 class="config_option">cache_loop_data</h4>
|
|
<p>Set to 1 (one) to cache LOOP data, otherwise, set to zero. Most users will
|
|
not want to change this unless you have a specialized application. Default is 1
|
|
(<em>i.e.</em>, cache LOOP data).</p>
|
|
<h4 class="config_option">station_type</h4>
|
|
<p>Set to the type of hardware you are using. For this version, only '<span class="code">VantagePro</span>'
|
|
is accepted. Required.</p>
|
|
<h3 class="config_section">[VantagePro]</h3>
|
|
<p>This section is for options relating to the VantagePro hardware.</p>
|
|
<h4 class="config_important">port</h4>
|
|
<p>Set to the port name used by your station. Example, /<span class="code">dev/ttyUSB0</span>
|
|
is a common location for USB ports under Debian, <span class="code">/dev/ttyS0</span>
|
|
for serial ports. Required. No default.</p>
|
|
<h4 class="config_option">baudrate</h4>
|
|
<p>Set to the baudrate of your station. The default is 19200.</p>
|
|
<h4 class="config_important">archive_interval</h4>
|
|
<p>Set to the desired archive interval of your station, in seconds. This variable
|
|
is only used when setting up your station. Otherwise, this value is read directly
|
|
from the station. Required if you <a href="#Archive_interval">configure your station</a>.
|
|
No default.</p>
|
|
<h4 class="config_option">iss_id</h4>
|
|
<p>Set to the ID number of your Integrated Sensor Suite (ISS). This is used in the
|
|
formula to calculate reception quality for wireless stations. The default is 1.</p>
|
|
<h4 class="config_option">archive_delay</h4>
|
|
<p>How long to wait in seconds after the top of an archiving interval before fetching
|
|
new data off the station. For example, if your archive interval is 5 minutes and
|
|
archive_delay is set to 15, then the data will be fetched at 00:00:15, 00:05:15,
|
|
00:10:15, etc. This delay is to give the station a few seconds to archive the data
|
|
internally, and in case your server has any other tasks to do at the top of the
|
|
minute. Default is 15 seconds.</p>
|
|
<h4 class="config_option">timeout</h4>
|
|
<p>How many seconds to wait for a response from the station before giving
|
|
up. Default is 5 seconds.</p>
|
|
<h4 class="config_option">wait_before_retry</h4>
|
|
<p>How many seconds to wait before retrying again. Unless you have a good reason
|
|
to change it, this value should be left at the default, as it is long enough for
|
|
the station to offer new data, but not so long as to go into a new loop packet (which
|
|
arrive every 2 seconds). Default is 1.2 seconds.</p>
|
|
<h4 class="config_option">max_retries</h4>
|
|
<p>How many times to try again before giving up. Default is 4.</p>
|
|
<h4 class="config_option">max_drift</h4>
|
|
<p>The maximum amount of drift to tolerate, in seconds, in the VantagePro's onboard
|
|
clock, before resetting the clock. Default is 5.</p>
|
|
<h4 class="config_option">unit_system</h4>
|
|
<p>What unit system is in use on your weather station hardware. Possible values
|
|
are '1' (U.S. Customary) or '2' (Metric). As far as I know, all Davis instruments support
|
|
only U.S.. In any case, U.S. is the only system supported by
|
|
<span class="code">weewx</span> at this time. Default is 1.</p>
|
|
<h3 class="config_section">[FTP]</h3>
|
|
<p>If you FTP your images and HTML files to an external web server,
|
|
<span class="code">weewx</span> can FTP them for you. It does an incremental update,
|
|
that is, it only FTPs any files that have changed, saving the outgoing bandwidth
|
|
of your Internet connection.</p>
|
|
<p>If you do not use such a server, comment out the first four options below.</p>
|
|
<p class="config_important">user</p>
|
|
<p>Set to the username you use for your FTP connection to your web server. Required.
|
|
No default.</p>
|
|
<p class="config_important">password</p>
|
|
<p>Set to the password you use for your FTP connection to your web server. Required.
|
|
No default.</p>
|
|
<p class="config_important">server</p>
|
|
<p>Set to the name of your web server (e.g., <a href="http://www.threefools.org">
|
|
www.threefools.org</a>, in my case). Required. No default</p>
|
|
<p class="config_important">path</p>
|
|
<p>Set to the path where the weather data will be stored on your webserver (e.g.,
|
|
'<span class="code">/weather</span>'). NB: some FTP servers require a
|
|
leading slash ('<span class="code">/</span>'), some don't. Required. No default.</p>
|
|
<h4 class="config_important">passive</h4>
|
|
<p>Set to 1 if you wish to use the more modern, FTP passive mode, 0 if you wish
|
|
to use active mode. Passive mode generally works better through firewalls, but not
|
|
all FTP servers do a good job of supporting it. See
|
|
<a href="http://slacksite.com/other/ftp.html">Active FTP vs. Passive FTP, a Definitive
|
|
Explanation</a> for a good explanation of the difference. Default is 1 (passive
|
|
mode).</p>
|
|
<h4 class="config_option">max_retries</h4>
|
|
<p><span class="code">Weewx</span> will try up to this many times to FTP a file
|
|
up to your server before giving up. Default is 3.</p>
|
|
<h3 class="config_section">[Wunderground]</h3>
|
|
<p><span class="code">Weewx </span>can send your current data to the Weather
|
|
Underground. If you do not wish to do this, comment out the two options below.</p>
|
|
<h4 class="config_option"><span class="config_important">station</span></h4>
|
|
<p>Set to your Weather Underground station ID (e.g., <span class="code">KORHOODR3</span>).
|
|
Required.</p>
|
|
<h4 class="config_important">password</h4>
|
|
<p>Set to your Weather Underground password. Required.</p>
|
|
<h3 class="config_section">[Archive]</h3>
|
|
<p>This section is for configuring the sqlite3 database in which the station archive
|
|
data is stored.</p>
|
|
<h4 class="config_option">archive_file</h4>
|
|
<p>The path, relative to the <span class="code">WEEWX_ROOT </span>directory, to
|
|
the database. Required</p>
|
|
<h4 class="config_option">unit_system</h4>
|
|
<p>What unit system to use inside the database. Required. The only one supported
|
|
right now is '1', the U.S. Customary system</p>
|
|
<h3 class="config_section">[Stats]</h3>
|
|
<p>This section is for configuring the sqlite3 database in which the station statistics
|
|
are stored.</p>
|
|
<h4 class="config_option">stats_file</h4>
|
|
<p>The path, relative to the <span class="code">WEEWX_ROOT </span>directory to the
|
|
statistical database. Required.</p>
|
|
<h4 class="config_option"><a name="stats_types">stats_types</a></h4>
|
|
<p>The list of types for which statistics will be kept. Types not listed will not
|
|
be available for generating HTML pages. Optional. The default is all types, resulting
|
|
in a possibly much bigger than necessary stats database (do you really have four
|
|
different soil moisture sensors?) The list that ships with the configuration file
|
|
will work for most stations and probably will not have to be modified.</p>
|
|
<h3 class="config_section">[Units]</h3>
|
|
<p>This section deals with Units and their formatting. </p>
|
|
<h4><a name="Unit_Classes">Unit Groups</a></h4>
|
|
<p>As there are many different observational measurement types (such as '<span class="code">outTemp</span>',
|
|
'<span class="code">barometer</span>', etc.) used in <span class="code">weewx</span>
|
|
(more than 50 at last count), it would be tedious, not to say possibly
|
|
inconsistent, to specify a different measurement system for each one of them. At
|
|
the other extreme, requiring them all to be "U.S. Customary" or "Metric" seems
|
|
overly restrictive. <span class="code">Weewx</span> has taken a middle route and
|
|
divided all the different measurement types into 12 different "unit groups." A
|
|
unit group is something like "<span class="code">group_temperature</span>." It
|
|
represents the measurement system to be used by all observation types that are
|
|
measured in temperature, such as inside temperature (type '<span class="code">inTemp</span>'),
|
|
outside temperature ('<span class="code">outTemp</span>'), dewpoint ('<span class="code">dewpoint</span>'),
|
|
wind chill ('<span class="code">windchill</span>'), and so on. If you
|
|
decide that you want unit group <span class="code">group_temperature</span> to be
|
|
measured in "<span class="code">degrees_C</span>" then you are saying <em>all</em>
|
|
members of its group will be reported in degrees Celsius.</p>
|
|
<h4 class="config_option">[[UnitGroups]]</h4>
|
|
<p>This section lists all the Unit Groups and specifies which unit system is to
|
|
be used for each one of them. Note that the unit system is always specified in
|
|
the singular. That is, specify "<span class="code">foot</span>" or "<span class="code">inch_per_hour</span>",
|
|
not "<span class="code">feet</span>" or "<span class="code">inches_per_hour</span>."</p>
|
|
<p>See section <a href="#Units">Units</a> for more information, including a concise
|
|
summary of the groups, their members, and which options can be used for each
|
|
group.</p>
|
|
<h4 class="config_important"><a name="group_altitude">group_altitude</a></h4>
|
|
<p>Which measurement unit to be used for altitude. Possible options
|
|
are '<span class="code">foot</span>' or
|
|
'<span class="code">meter</span>'.</p>
|
|
<h4 class="config_option">group_direction</h4>
|
|
<p>Which measurement unit to be used for direction. The only option is
|
|
"<span class="code">degree_compass</span>".</p>
|
|
<h4 class="config_option">group_moisture</h4>
|
|
<p>The measurement unit to be used for soil moisture. The only option
|
|
is "<span class="code">centibar</span>."</p>
|
|
<h4 class="config_option">group_percent</h4>
|
|
<p>The measurement unit to be used for percentages. The only option is
|
|
"<span class="code">percent</span>".</p>
|
|
<h4 class="config_important">group_pressure</h4>
|
|
<p>The measurement unit to be used for pressure. Possible options are
|
|
one of "<span class="code">inHg</span>" (inches of mercury),
|
|
"<span class="code">mbar</span>", or
|
|
"<span class="code">hPa</span>."</p>
|
|
<h4 class="config_option">group_radiation</h4>
|
|
<p>The measurement unit to be used for radiation. The only option is
|
|
"<span class="code">watt_per_meter_squared</span>."</p>
|
|
<h4 class="config_important">group_rain</h4>
|
|
<p>The measurement unit to be used for precipitation. Options are
|
|
"<span class="code">inch</span>",
|
|
"<span class="code">cm</span>," or
|
|
"<span class="code">mm</span>."</p>
|
|
|
|
<h4 class="config_important">group_rainrate</h4>
|
|
<p>The measurement unit to be used for rate of precipitation. Possible options
|
|
are one of "<span class="code">inch_per_hour</span>",
|
|
"<span class="code">cm_per_hour</span>", or
|
|
"<span class="code">mm_per_hour</span>".</p>
|
|
|
|
<h4 class="config_important">group_speed</h4>
|
|
<p>The measurement unit to be used for wind speeds. Possible options are one of "<span class="code">mile_per_hour</span>",
|
|
"<span class="code">km_per_hour</span>", "<span class="code">knot</span>", or "<span class="code">meter_per_second</span>."</p>
|
|
<h4 class="config_important">group_speed2</h4>
|
|
<p>This group is similar to <span class="code">group_speed</span>, but is used for calculated wind speeds
|
|
which typically have a slightly higher resolution. Possible options are one of "<span class="code">mile_per_hour2</span>",
|
|
"<span class="code">km_per_hour2</span>", "<span class="code">knot2</span>", or
|
|
"<span class="code">meter_per_second2</span>."</p>
|
|
<h4 class="config_important"><a name="group_temperature">group_temperature</a></h4>
|
|
<p>The measurement unit to be used for temperatures. Options are "<span class="code">degree_F</span>"
|
|
or "<span class="code">degree_C</span>."</p>
|
|
<h4 class="config_option">group_volt</h4>
|
|
<p>The measurement unit to be used for voltages. The only option is "<span class="code">volt</span>."</p>
|
|
<h4 class="config_option"><a name="Units_StringFormats">[[StringFormats]]</a></h4>
|
|
<p>This sub-section is used to specify what string format is to be used for each
|
|
unit when a quantity needs to be converted to a string. Typically, this happens
|
|
with y-axis labeling on plots and for statistics in
|
|
HTML file generation. For example, the options</p>
|
|
<p class="tty">degree_C = %.1f</p>
|
|
<p class="tty">inch = %.2f</p>
|
|
<p>would specify that the given string formats are to be used when formatting any temperature
|
|
measured in degrees Celsius or any precipitation amount measured in inches, respectively. The
|
|
<a href="http://docs.python.org/library/string.html#format-specification-mini-language">
|
|
formatting codes are those used by Python</a>, and are very similar to C's sprintf()
|
|
codes.</p>
|
|
<h3 class="config_section">[Images]</h3>
|
|
<p>This section, which controls which images (plots) get generated and with which
|
|
options, is by far the most complicated. However, it is extremely flexible and powerful.</p>
|
|
<h4>Time periods</h4>
|
|
<p>The section consists of one or more sub-sections, one for each time period (day, week,
|
|
month, and year). These sub-sections define the nature of aggregation and plot types
|
|
for the time period. For example, here's a typical set of options for sub-section
|
|
<span class="code">[[month_images]]</span>, controlling how images that cover a
|
|
month period are generated:</p>
|
|
<p class="tty">[[month_images]]</p>
|
|
<p class="tty"> x_label_format = %d</p>
|
|
<p class="tty"> bottom_label_format = %m/%d/%y %H:%M</p>
|
|
<p class="tty"> time_length = 2592000 # == 30 days</p>
|
|
<p class="tty"> aggregate_type = avg</p>
|
|
<p class="tty"> aggregate_interval = 10800 # == 3 hours</p>
|
|
<p>The option <span class="code">x_label_format</span> gives a
|
|
<a href="http://docs.python.org/library/datetime.html#strftime-behavior">strftime()</a>
|
|
type format for the x-axis. In this example, it will only show days (format option
|
|
"<span class="code">%d</span>"). The <span class="code">bottom_label_format</span>
|
|
is the format used to time stamp the image at the bottom. In this example, it will
|
|
show the time as <span class="code">10/25/09 15:35</span>. A plot will cover a nominal
|
|
30 days, and all items included in it will use an aggregate type of averaging over
|
|
3 hours. </p>
|
|
<h4>Image files</h4>
|
|
<p>Within each sub-section is another nesting, one for each image to be generated.
|
|
The title of each sub-sub-section is the filename to be used for the image.
|
|
Finally, at one additional nesting level (!) are the logical names of all the
|
|
line types to be drawn in the image. Values specified in the
|
|
level above can be overridden. For example, here's a typical set of options for
|
|
sub-sub-section <span class="code">[[[monthrain]]]</span>: </p>
|
|
<p class="tty">[[[monthrain]]]</p>
|
|
<p class="tty"> plot_type = bar</p>
|
|
<p class="tty"> yscale = None, None, 0.02</p>
|
|
<p class="tty"> [[[[rain]]]]</p>
|
|
<p class="tty"> aggregate_type = sum</p>
|
|
<p class="tty"> aggregate_interval = 86400</p>
|
|
<p class="tty"> label = Rain (daily avg)</p>
|
|
<p>This will generate an image file with name <span class="code">monthrain.png</span>.
|
|
It will be a bar plot. Option <span class="code">yscale</span> controls the y-axis
|
|
scaling — if left out, the scale will automatically be chosen. However, in this
|
|
example we are choosing to exercise some degree of control by specifying values
|
|
explicitly. It is a 3-way tuple (<span class="code">ylow</span>,
|
|
<span class="code">yhigh</span>, <span class="code">min_interval</span>), where
|
|
<span class="code">ymin</span> and <span class="code">ymax</span> are the minimum
|
|
and maximum y-axis values, respectively, and <span class="code">min_interval</span>
|
|
is the minimum tick interval. If set to '<span class="code">None</span>', the corresponding
|
|
value will be automatically chosen. So, in this example, we are letting
|
|
<span class="code">weewx</span> pick sensible y minimum and maximum values, but
|
|
we are requiring that the tick increment (<span class="code">min_interval</span>)
|
|
be at least 0.02. </p>
|
|
<p>Continuing on with the example above, there will be only one plot "line" (it
|
|
will actually be a series of bars) and it will
|
|
have logical name '<span class="code">rain</span>'. Because we haven't said
|
|
otherwise, the SQL data type to be used for this line will be the same as its
|
|
logical name, that is, <span class="code">rain</span>, but this can be
|
|
overridden (see below). The aggregation type will be summing (overriding
|
|
the averaging specified in sub-section <span class="code">[[month_images]]</span>),
|
|
so you get the total rain over the aggregate period (rather than the average) over
|
|
an aggregation interval of 86,400 seconds (one day). The plot line will be titled
|
|
with the indicated label ('<span class="code">Rain (daily avg)</span>')</p>
|
|
<h4>Including more than one SQL type in a plot</h4>
|
|
<p>More than one SQL type can be included in a plot. For example, here's how to
|
|
generate a plot with the week's outside temperature as well as dewpoint:</p>
|
|
<p class="tty">[[[monthtempdew]]]</p>
|
|
<p class="tty"> [[[[outTemp]]]]</p>
|
|
<p class="tty"> [[[[dewpoint]]]]</p>
|
|
<p>This would create an image in file <span class="code">monthtempdew.png</span>
|
|
that includes a line plot of both outside temperature and dewpoint.</p>
|
|
<h4>Including the same SQL type more than once in a plot</h4>
|
|
<p>Another example. Say you want a plot of the day's temperature, overlaid with
|
|
hourly averages. Here, you are using the same data type ('<span class="code">outTemp</span>')
|
|
for both plot lines, the first with averages, the second without. If you do the
|
|
obvious it won't work:</p>
|
|
<p class="tty">## WRONG ##</p>
|
|
<p class="tty">[[[daytemp_with_avg]]]</p>
|
|
<p class="tty"> [[[[outTemp]]]]</p>
|
|
<p class="tty"> aggregate_type = avg</p>
|
|
<p class="tty"> aggregate_interval = 3600</p>
|
|
<p class="tty"> [[[[outTemp]]]] # OOPS! The same section name appears more than
|
|
once!</p>
|
|
<p>The option parser does not allow the same section name ('<span class="code">outTemp</span>'
|
|
in this case) to appear more than once at a given level in the configuration
|
|
file, so an error will be declared (technical reason: formally, the sections are
|
|
an unordered dictionary). If you wish for the same SQL type to appear more than
|
|
once in a plot then there is a trick you must know: use option
|
|
<span class="code">data_type</span>. This will override the default action that
|
|
the logical line name is used for the SQL type. So, our example would look like
|
|
this:</p>
|
|
<p class="tty">[[[daytemp_with_avg]]]</p>
|
|
<p class="tty"> [[[[a_logical_name]]]]</p>
|
|
<p class="tty"> data_type = outTemp</p>
|
|
<p class="tty"> aggregate_type = avg</p>
|
|
<p class="tty"> aggregate_interval = 3600</p>
|
|
<p class="tty"> [[[[outTemp]]]]</p>
|
|
<p>Here, the first logical line has been given the name "<span class="code">a_logical_name</span>"
|
|
to distinguish it from the second line "<span class="code">outTemp</span>". We
|
|
have specified that the first line will use data type <span class="code">outTemp</span>
|
|
and that it will use averaging over a one hour period. The second also uses
|
|
<span class="code">outTemp</span>, but will not use averaging.</p>
|
|
<p>The result is a nice plot of the day's temperature, overlaid with a 3-hour
|
|
smoothed average.</p>
|
|
<h4>Progressive vector plots</h4>
|
|
<p><span class="code">Weewx</span> can produce progressive vector plots as well as the more conventional
|
|
x-y plots. To produce these, use plot type '<span class="code">vector</span>'.
|
|
You need a vector type to produce this kind of plot. There are two: '<span class="code">windvec</span>',
|
|
and '<span class="code">windgustvec</span>'. While they don't actually appear in
|
|
the SQL database, <span class="code">weewx</span> understands that they represent special vector-types.
|
|
The first, '<span class="code">windvec</span>', represents the average wind in
|
|
an archive period, the second, '<span class="code">windgustvec</span>' the max
|
|
wind in an archive period. Here's how to produce a progressive vector plot of
|
|
the year's biggest daily wind gusts, along with daily averages:</p>
|
|
<p class="tty">[[[yeargustoverlay]]]</p>
|
|
<p class="tty"> aggregate_interval = 86400</p>
|
|
<p class="tty"> [[[[windvec]]]]</p>
|
|
<p class="tty"> plot_type = vector</p>
|
|
<p class="tty"> aggregate_type = avg</p>
|
|
<p class="tty"> [[[[windgustvec]]]]</p>
|
|
<p class="tty"> plot_type = vector</p>
|
|
<p class="tty"> aggregate_type = max</p>
|
|
<p>This will produce an image file with name <span class="code">
|
|
yeargustoverlay.png</span>. It will consist of two progressive vector plots,
|
|
both using daily aggregation (86,400 seconds). For the first set of vectors, the daily
|
|
average will be used. In the second, the max of the gusts will be used.</p>
|
|
<p>By default, the sticks in the progressive wind plots point towards the wind
|
|
source. That is, the stick for a wind from the west will point left. If you have
|
|
a chronic wind direction (as I do), you may want to rotate the default direction
|
|
so that all the vectors don't line up over the x-axis, overlaying each other. Do
|
|
this by using option <span class="code">vector_rotate</span>. For example, with
|
|
my chronic westerlies, I set <span class="code">vector_rotate</span> to 90.0, so
|
|
winds out of the west point straight up. </p>
|
|
<p>If you use this kind of plot (the out-of-the-box version of
|
|
<span class="code">weewx</span> includes daily, weekly, monthly, and yearly
|
|
progressive wind plots), a small compass rose will be put in the lower-left
|
|
corner of the image to show the orientation of North.</p>
|
|
<h4>Overriding values</h4>
|
|
<p>Remember that values at any level can override values specified at a higher
|
|
level. For example, say you want to generate the standard plots, but for a few
|
|
key observation types such as barometer, you want to also generate some
|
|
oversized plots to give you extra detail, perhaps for an HTML popup. The
|
|
standard <span class="code">weewx.conf</span> file specifies plot size of
|
|
300x180 pixels, which will be used for all plots unless overridden:</p>
|
|
<p class="tty">[Images]</p>
|
|
<p class="tty"> ...</p>
|
|
<p class="tty"> image_width=300</p>
|
|
<p class="tty"> image_height = 180</p>
|
|
<p>The standard plot of barometric pressure will appear in <span class="code">
|
|
daybarometer.png</span>:</p>
|
|
<p class="tty"> [[[daybarometer]]]</p>
|
|
<p class="tty"> [[[[barometer]]]] </p>
|
|
<p>We now add our special plot of barometric pressure, but specify a larger
|
|
image size. This image will be put in file <span class="code">
|
|
daybarometer_big.png</span>.</p>
|
|
<p class="tty"> [[[daybarometer_big]]]</p>
|
|
<p class="tty"> image_width = 600</p>
|
|
<p class="tty"> image_height = 360</p>
|
|
<p class="tty"> [[[[barometer]]]]</p>
|
|
<h4>Summary</h4>
|
|
<p>Studying this section in the shipped version of <span class="code">weewx.conf</span>
|
|
will give you ideas about the many different image plot configurations that are
|
|
possible without hacking the code. </p>
|
|
<h3 class="config_section">[Labels]</h3>
|
|
<p>This section controls how measurement values are labeled. It is generally
|
|
used in plot generation, although there are a few other areas where it is used. It consists of
|
|
two sub-sections:</p>
|
|
<h4 class="config_option">[[Generic]]</h4>
|
|
<p>This sub-sections specifies default labels to be used for each SQL type. For
|
|
example, options</p>
|
|
<p class="tty">inTemp = Inside Temperature</p>
|
|
<p class="tty">outTemp = Outside Temperature</p>
|
|
<p>would cause the given labels to be used for plots involving SQL types
|
|
<span class="code">inTemp </span>and <span class="code">outTemp</span>..</p>
|
|
<h4 class="config_option">[[<a name="Units_StringFormats">UnitLabels]]</a></h4>
|
|
<p>This sub-section specifies what label to be used for each measurement unit
|
|
type. For example, the options</p>
|
|
<p class="tty">degree_F = \xb0F</p>
|
|
<p class="tty">inch = ' in'</p>
|
|
<p>would cause all temperatures to have unit labels '<span class="code">°F</span>'
|
|
and all precipitation to have labels '<span class="code"> in</span>'. (NB: the code
|
|
<span class="code">\xb0</span> is the hexadecimal value <span class="code">b0</span>,
|
|
which in many encodings encodes the degree sign.)</p>
|
|
<h3 class="config_section">[HTML]</h3>
|
|
<p>Section [HTML] has two options and two sub-sections. For additional information
|
|
on HTML generation <a href="#HTML_Generation">see the section below</a>.</p>
|
|
<h4 class="config_option">template_root</h4>
|
|
<p>This option specifies the directory, relative to <span class="code"><em>WEEWX_ROOT</em></span>,
|
|
where the HTML templates can be found. Required. No default.</p>
|
|
<h4 class="config_option">html_root</h4>
|
|
<p>This option specifies the directory, relative to <span class="code"><em>WEEWX_ROOT</em></span>,
|
|
where the generated HTML files should be put. Required. No default.</p>
|
|
<h4 class="config_option"><a name="HTML_UnitLabels">[[UnitLabels]]</a></h4>
|
|
<p>This subsection is similar to its eponymous counterpart in section
|
|
<span class="code">[Labels]</span> above, except it is used for HTML generation.
|
|
It is useful to have a separate section because HTML uses special 'entity' codes
|
|
to code special characters, such as the degree sign. For example, the options</p>
|
|
<p class="tty">degree_F = &deg;F</p>
|
|
<p class="tty">inch = ' in'</p>
|
|
<p>would cause outside temperature and rain to have unit labels '<span class="code">°F</span>'
|
|
and '<span class="code"> in</span>', respectively.</p>
|
|
<h4 class="config_option"><a name="HTML_Time">[[Time]]</a></h4>
|
|
<p>This subsection is used for time labels in HTML generation. It uses
|
|
<a href="http://docs.python.org/library/datetime.html#strftime-behavior">strftime()</a>
|
|
formats. For example</p>
|
|
<p class="tty">week = %H:%M on %A</p>
|
|
<p class="tty">month = %d-%b-%Y %H:%M</p>
|
|
<p>would specify that week data should use a format such as "<span class="code">15:20
|
|
on Sunday</span>", while month data should look like "<span class="code">06-Oct-2009
|
|
15:20</span>"</p>
|
|
<h1>7. <a name="Running_weewx">Running <span class="code">weewx</span></a></h1>
|
|
<p><span class="code">Weewx</span> can be run either from the command line (useful
|
|
for diagnostic purposes because it will print out a summary of every LOOP data),
|
|
or as a daemon. When first trying <span class="code">weewx</span>, it's probably
|
|
best to run it from the command line because you will be able to see command line
|
|
diagnostics, as well as log messages.</p>
|
|
<h2>7.1 Running from the command line</h2>
|
|
<p><span class="code">Weewx</span> can easily be run from the command line. Start
|
|
by making sure you have appropriate permissions to the serial port your weather
|
|
station uses. For example, if you are using a plain old serial port:</p>
|
|
<p class="tty">sudo chmod 666 /dev/ttyS0</p>
|
|
<p>Then run the main loop program, <span class="code">weewxd.py</span>, giving the
|
|
configuration file as its only parameter:</p>
|
|
<p class="tty"><em>$WEEWX_ROOT</em>/bin/weewxd.py <em>$WEEWX_ROOT</em>/weewx.conf</p>
|
|
<p>It should start by downloading any archive data from your weather station into
|
|
the database <span class="code"><em>$WEEWX_ROOT</em>/archive/weewx.sdb</span>. As
|
|
the Davis VantagePro can store a couple thousand archive records internally, this
|
|
could take a minute or two. I've found this process particularly slow on SuSE for
|
|
some reason.</p>
|
|
<p><span class="code">Weewx</span> will then start monitoring LOOP data, printing
|
|
a short version of the received data on standard output, about once every two seconds.</p>
|
|
<p>You can tell a running instance of <span class="code">weewx</span> to reread
|
|
its configuration file by sending it the <span class="code">HUP</span> signal.
|
|
First run <span class="code">ps</span> to find out the Process ID (PID) number
|
|
of the instance, then send it the <span class="code">HUP</span> signal:</p>
|
|
<p class="tty">ps -a # Note the
|
|
PID of the weewxd.py process</p>
|
|
<p class="tty">kill -HUP <em>pid</em> # Send it a HUP signal</p>
|
|
<h2>7.2 <a name="Running_as_a_daemon">Running as a daemon</a></h2>
|
|
<p>For unattended operations it is best to have <span class="code">weewx</span>
|
|
run as a daemon, started automatically when the server is rebooted. Start by selecting the appropriate run script. They can be found under
|
|
<span class="code"><em>$WEEWX_ROOT</em>/start_script</span>. </p>
|
|
<table style="width: 100%" class="indent">
|
|
<tr>
|
|
<td>SuSE:</td>
|
|
<td class="code"><em>$WEEWX_ROOT</em>/start_script/SuSE/weewx</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Debian/Ubuntu:</td>
|
|
<td class="code"><em>$WEEWX_ROOT</em>/start_script/Debian/weewx</td>
|
|
</tr>
|
|
</table>
|
|
<p>Check the chosen script to make sure the variable <span class="code">WEEWX_ROOT</span>
|
|
inside has been set to the proper root directory for your <span class="code">weewx</span>
|
|
installation (it should have been set to the correct value automatically by the
|
|
install process, but it's worth checking). </p>
|
|
<p>Copy it to the proper location for your system:</p>
|
|
<table style="width: 100%" class="indent">
|
|
<tr>
|
|
<td>SuSE:</td>
|
|
<td class="code">cp <em>$WEEWX_ROOT</em>/start_script/SuSE/weewx /etc/init.d</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Debian/Ubuntu:</td>
|
|
<td class="code">cp <em>$WEEWX_ROOT</em>/start_script/Debian/weewx /etc/init.d</td>
|
|
</tr>
|
|
</table>
|
|
<p>Make sure the script is executable </p>
|
|
<table style="width: 100%" class="indent">
|
|
<tr>
|
|
<td>SuSE:</td>
|
|
<td class="code">chmod +x /etc/init.d/weewx</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Debian/Ubuntu:</td>
|
|
<td class="code">chmod +x /etc/init.d/weewx</td>
|
|
</tr>
|
|
</table>
|
|
<p>Create symbolic links in the run level directories:</p>
|
|
<table style="width: 100%" class="indent">
|
|
<tr>
|
|
<td>SuSE:</td>
|
|
<td class="code">/usr/lib/lsb/install_initd /etc/init.d/weewx</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Debian/Ubuntu:</td>
|
|
<td class="code">update-rc.d weewx defaults 98</td>
|
|
</tr>
|
|
</table>
|
|
<p><span class="code">Weewx</span> will now start automatically whenever your system
|
|
is booted. You can also manually start, stop, and restart the <span class="code">
|
|
weewx</span> daemon:</p>
|
|
<p class="tty">/etc/init.d/weewx start</p>
|
|
<p class="tty">/etc/init.d/weewx stop</p>
|
|
<p class="tty">/etc/init.d/weewx restart</p>
|
|
<p>By default, the scripts are designed to have <span class="code">weewx</span>
|
|
run at run levels 2, 3, 4 and 5. Incidentally, a nice tool for setting run levels
|
|
with Debian (Ubuntu) systems is <a href="http://sysv-rc-conf.sourceforge.net/">sysv-rc-conf</a>.
|
|
It uses a curses interface to allow you to change easily which run level any of
|
|
your daemons runs at. There is a similar tool on SuSE. From the start menu run the
|
|
YAST Control Center, then look for Systems Services (Runlevel). Pick "Expert" mode
|
|
to see the run levels.</p>
|
|
<p>You can also tell <span class="code">weewx</span> to reread its configuration
|
|
file without stopping by using the 'reload' option:</p>
|
|
<p class="tty">/etc/init.d/weewx reload</p>
|
|
<h1>8. <a name="Compatibility_with_wview">Compatibility with <span class="code">
|
|
wview</span></a></h1>
|
|
<p>The sqlite3 archive database used by <span class="code">weewx</span> (nominally,
|
|
<span class="code">weewx.sdb</span>) is completely compatible with the database
|
|
used by <a href="http://www.wviewweather.com">wview</a> (usually called
|
|
<span class="code">wview-archive.sdb</span>), at least as of wview Version 5.2.X. The
|
|
schema and its semantics is identical. However, the statistical file
|
|
<span class="code">stats.sdb</span> is different, and must be rebuilt</p>
|
|
<h1>9. <a name="Monitoring_weewx">Monitoring <span class="code">weewx</span></a></h1>
|
|
<p><span class="code">Weewx</span> logs many events to the system log. On Debian
|
|
systems, this is <span class="code">/var/log/syslog</span>, on SuSE,
|
|
<span class="code">/var/log/messages</span>. Your system may use yet another place.
|
|
When troubleshooting the system, be sure to check it!</p>
|
|
<p>Setting the option <span class="code">debug </span>in <span class="code">weewx.conf</span>
|
|
to <span class="code">1</span> (one) will generate many more checks and output and
|
|
can be useful for debugging.</p>
|
|
<h1>10. Advanced topics: t<a name="Types">ypes</a></h1>
|
|
<p>This section is not needed to get started. </p>
|
|
<p>The weather variables used in <span class="code">weewx</span> generally fall into three different camps.
|
|
They can be a "SQL type", meaning they appear in the archive database, an
|
|
"Observational type", meaning that they either appear in the archive
|
|
database or are a derived quantity thereof,
|
|
or a "Statistical type," meaning that they appear in the statistical
|
|
database. Observational types can be used in plots, statistical types can be
|
|
aggregated and used in daily, weekly, monthly, and yearly summaries. </p>
|
|
<p>The following table shows all the possible types and what categories they
|
|
fall into. Note that just because a type appears in the table does not
|
|
necessarily mean that it is available for <em>your</em> station setup. That
|
|
would depend on whether your instrument supports the type, and whether or not
|
|
you configured <span class="code">weewx</span> to use that type.</p>
|
|
<table style="width: 80%" align="center" class="style2">
|
|
<tr >
|
|
<td><strong>Name</strong></td>
|
|
<td style="width: 200px"><strong>SQL Type</strong><br />
|
|
<span class="style3">(appears in archive database)</span></td>
|
|
<td style="width: 200px"><strong>Observation Type</strong><br />
|
|
<span class="style3">(can be used in plots)</span></td>
|
|
<td style="width: 200px"><strong>Stats Type</strong><br />
|
|
<span class="style3">(can be used in statistical aggregations)</span></td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">altimeter</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">altitude</td>
|
|
<td></td>
|
|
<td></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">barometer</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">consBatteryVoltage</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">dateTime</td>
|
|
<td>X</td>
|
|
<td></td>
|
|
<td></td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">dewpoint</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">ET</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">extraHumid1</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>x</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">extraHumid2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">extraTemp1</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">extraTemp2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">extraTemp3</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">hail</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">hailRate</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">heatindex</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">heatingTemp</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">heatingVoltage</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">inHumidity</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">inTemp</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">inTempBatteryStatus</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">interval</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td></td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">leafTemp2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">leafWet2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">outHumidity</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">outTemp</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code" >outTempBatteryStatus</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">pressure</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">radiation</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">rain</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code" >rainBatteryStatus</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">rainRate</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code" >referenceVoltage</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code" >rxCheckPercent</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">soilMoist1</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">soilMoist2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">soilMoist3</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">soilMoist4</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">soilTemp1</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">soilTemp2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">soilTemp3</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">soilTemp4</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">supplyVoltage</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">txBatteryStatus</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">usUnits</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td></td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">UV</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td></td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">wind</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">windvec</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">windBatteryStatus</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">windDir</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">windGust</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">windGustDir</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">windSpeed</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr >
|
|
<td class="code">windchill</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
</table>
|
|
<p> </p>
|
|
<h2>10.1 <a name="Units">Units</a></h2>
|
|
<p>The table below lists all the unit groups, their members, and which units are
|
|
options for the group.</p>
|
|
<table style="width: 60%" class="style2" align="center">
|
|
<tr>
|
|
<td><strong>Group</strong></td>
|
|
<td><strong>Members</strong></td>
|
|
<td><strong>Unit options</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">group_altitude</td>
|
|
<td class="code">altitude</td>
|
|
<td class="code">foot<br />
|
|
meter</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_direction</td>
|
|
<td>gustdir<br />
|
|
vecdir<br />
|
|
windDir<br />
|
|
windGustDir</td>
|
|
<td>degree_compass</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_moisture</td>
|
|
<td>soilMoist1<br />
|
|
soilMoist2<br />
|
|
soilMoist3<br />
|
|
soilMoist4</td>
|
|
<td>centibar</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_percent</td>
|
|
<td>extraHumid1<br />
|
|
extraHumid2<br />
|
|
inHumidity<br />
|
|
outHumidity<br />
|
|
rxCheckPercent</td>
|
|
<td>percent</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_pressure</td>
|
|
<td>barometer<br />
|
|
altimeter<br />
|
|
pressure</td>
|
|
<td>inHg<br />
|
|
mbar<br />
|
|
hPa</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_radiation</td>
|
|
<td>UV<br />
|
|
radiation</td>
|
|
<td>watt_per_meter_squared</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_rain</td>
|
|
<td>rain<br />
|
|
ET<br />
|
|
hail</td>
|
|
<td>in<br />
|
|
cm<br />
|
|
mm</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_rainrate</td>
|
|
<td>rainRate<br />
|
|
hailRate</td>
|
|
<td>in_per_hour<br />
|
|
cm_per_hour<br />
|
|
mm_per_hour</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_speed</td>
|
|
<td>wind<br />
|
|
windGust<br />
|
|
windSpeed<br />
|
|
windgustvec<br />
|
|
windvec</td>
|
|
<td>mile_per_hour<br />
|
|
km_per_hour<br />
|
|
knot<br />
|
|
meter_per_second</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_speed2</td>
|
|
<td>rms<br />
|
|
vecavg</td>
|
|
<td>mile_per_hour2<br />
|
|
km_per_hour2<br />
|
|
knot2<br />
|
|
meter_per_second2</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_temperature</td>
|
|
<td>dewpoint<br />
|
|
extraTemp1<br />
|
|
extraTemp2<br />
|
|
extraTemp3<br />
|
|
heatindex<br />
|
|
heatingTemp<br />
|
|
inTemp<br />
|
|
leafTemp1<br />
|
|
leafTemp2<br />
|
|
outTemp<br />
|
|
soilTemp1<br />
|
|
soilTemp2<br />
|
|
soilTemp3<br />
|
|
soilTemp4<br />
|
|
windchill</td>
|
|
<td>degree_F<br />
|
|
degree_C</td>
|
|
</tr>
|
|
<tr class="code">
|
|
<td>group_volt</td>
|
|
<td>consBatteryVoltage<br />
|
|
heatingVoltage<br />
|
|
referenceVoltage<br />
|
|
supplyVoltage</td>
|
|
<td>volt</td>
|
|
</tr>
|
|
</table>
|
|
<h1>11. Advanced topics: customizing <a name="HTML_Generation">HTML Generation</a></h1>
|
|
<p>This section is not needed to get started. </p>
|
|
<p>HTML generation is done using the <a href="http://www.cheetahtemplate.org/">Cheetah</a>
|
|
templating engine. This is a very powerful engine, which essentially lets you have
|
|
the full semantics of Python available in your templates. As this would make the
|
|
templates incomprehensible to anyone but a Python programmer, <span class="code">
|
|
weewx</span> adopts a very small subset of its power. </p>
|
|
<p>Generally, any value is specified by using a 'dot' code. For example:</p>
|
|
<p class="tty">$month.outTemp.max</p>
|
|
<p class="tty">$month.outTemp.maxtime</p>
|
|
<p class="tty">$current.outTemp</p>
|
|
<p>would code the max outside temperature for the month, the time it occurred, and
|
|
the current outside temperature, respectively. So, an HTML file that looks like</p>
|
|
<p class="tty"><html></p>
|
|
<p class="tty"> <head></p>
|
|
<p class="tty"> <title>Current conditions</title></p>
|
|
<p class="tty"> </head></p>
|
|
<p class="tty"> <body></p>
|
|
<p class="tty"> <p>Current temperature = $current.outTemp</p></p>
|
|
<p class="tty"> <p>Max for the month is $month.outTemp.max, which occurred at</p>
|
|
<p class="tty">$month.outTemp.maxtime</p></p>
|
|
<p class="tty"> </body></p>
|
|
<p class="tty"></html></p>
|
|
<p>would be all you need for a very simple HTML page that would display the text
|
|
(assuming that the <a href="#Unit_Classes">unit class</a> for temperature is
|
|
<span class="code">degree_F</span>):
|
|
</p>
|
|
<p class="indent">Current temperature = 51.0°F<br />
|
|
Max for the month is 68.8°F, which occurred at 07-Oct-2009 15:15</p>
|
|
<p>The format that was used to format the temperature (<span class="code">51.0</span>)
|
|
is specified in section <span class="code"><a href="#Units_StringFormats">[Units][[StringFormat]]</a></span>.
|
|
The unit label <span class="code">°F</span> is from section <span class="code">
|
|
<a href="#HTML_UnitLabels">[HTML][[UnitLabels]]</a></span>, while the time
|
|
format is from <span class="code"><a href="#HTML_Time">[HTML][[Time]]</a></span>.</p>
|
|
<p>The "dot" code has up to three parts. </p>
|
|
<ol>
|
|
<li>The first part is the time period, and can be one of <span class="code">
|
|
current</span>, <span class="code">day</span>, <span class="code">week</span>,
|
|
<span class="code">month</span>, <span class="code">year</span>, or
|
|
<span class="code">rainyear</span>.</li>
|
|
<li>The second part is the "statistical type". This is something like '<span class="code">outTemp</span>',
|
|
'<span class="code">rain</span>', '<span class="code">wind</span>', etc.
|
|
The statistical types are generally those that appear in the SQL databases with three exceptions. First, type '<span class="code">wind</span>'
|
|
is a special hybrid type and does not appear in the SQL database. It brings
|
|
together the several different SQL types '<span class="code">windSpeed</span>',
|
|
'<span class="code">windDir</span>', <span class="code">windGust</span>', and
|
|
'<span class="code">windGustDir</span>' under one roof (all are still available,
|
|
should you wish to use them for a specialized application). Exceptions number
|
|
two and three are '<span class="code">heatdeg</span>' and '<span class="code">cooldeg</span>',
|
|
heating and cooling degree-days, respectively, which are synthesized from average
|
|
outside temperature and do not appear directly in the database.</li>
|
|
<li>The last position is the aggregation type, available for any time period
|
|
except for '<span class="code">current</span>'. The table below in
|
|
section <a href="#Statistical_aggregations">Statistical aggregations</a> shows what aggregation
|
|
types are available for which types. </li>
|
|
</ol>
|
|
<p>In addition, if the first part of the dot code represents a time period
|
|
longer than a day (e.g., a week, month, year, or rainyear), then it can be
|
|
iterated over. This example uses a Cheetah 'for' loop to iterate over all months
|
|
in a year, printing out each month's min and max temperature.</p>
|
|
<p class="tty"><html></p>
|
|
<p class="tty"> <head></p>
|
|
<p class="tty"> <title>Year stats by month</title></p>
|
|
<p class="tty"> </head></p>
|
|
<p class="tty"> <body></p>
|
|
<p class="tty"> <p>Min, m<span class="style1">ax t</span>emperatures
|
|
by month:</p></p>
|
|
<p class="tty"> # for $month in $year.months</p>
|
|
<p class="tty"> $month.outTemp.min $month.outTemp.max</p>
|
|
<p class="tty"> # end for </p>
|
|
<p class="tty"> </body></p>
|
|
<p class="tty"></html></p>
|
|
<p>See the NOAA template files <span class="code">NOAA_month.tmpl</span> and
|
|
<span class="code">NOAA_year.tmpl</span> for examples using iteration, as well
|
|
as explicit formatting.</p>
|
|
<h2>11.1 <a name="Statistical_aggregations">Statistical aggregations</a></h2>
|
|
<p>Most of the HTML templates are devoted to generating <em>statistical
|
|
aggregates</em>, such as monthly max temperature, or year-to-date rainfall.
|
|
These are called <em>aggregations</em>, because they are a summary of lots of
|
|
underlying data. However, only certain aggregates make sense for certain
|
|
statistical
|
|
types. For example, heat degree days is defined on a daily basis, so while the
|
|
day's average temperature is meaningful, the day's heating degree days do not.</p>
|
|
<p>The following table defines which aggregates are available to be used in your template
|
|
for which statistical types (assuming your
|
|
station supports them and you have specified that it be stored in your stats database.
|
|
See section <a href="#stats_types">stats_types</a> in the <span class="code">weewx.conf</span>
|
|
configuration file).</p>
|
|
<table style="width: 100%">
|
|
<tr>
|
|
<td><em>Stats Type</em></td>
|
|
<td class="code">min</td>
|
|
<td class="code">mintime</td>
|
|
<td class="code">max</td>
|
|
<td class="code">maxtime</td>
|
|
<td class="code">avg</td>
|
|
<td class="code">sum</td>
|
|
<td class="code">rms</td>
|
|
<td class="code">vecavg</td>
|
|
<td class="code">vecdir</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">barometer</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">inTemp</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">outTemp</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">inHumidity</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">outHumidity</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">wind</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">rain</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">dewpoint</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">windchill</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">heatindex</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">heatdeg</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">cooldeg</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">ET</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">radiation</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">UV</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">extraTemp1<br />
|
|
extraTemp2<br />
|
|
extraTemp3</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">soilTemp1<br />
|
|
soilTemp2<br />
|
|
soilTemp3</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">leafTemp1<br />
|
|
leafTemp2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">extraHumid1<br />
|
|
extraHumid2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">soilMoist1<br />
|
|
soilMoist2<br />
|
|
soilMoist3<br />
|
|
soilMoist4</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">leafWet1<br />
|
|
leafWet2</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
<tr>
|
|
<td class="code">rxCheckPercent</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td>X</td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
<td> </td>
|
|
</tr>
|
|
</table>
|
|
<h1>12. Advanced topics: <a name="Architectural_notes">architectural notes</a></h1>
|
|
<p>This section is not needed to get started. </p>
|
|
<h2>12.1 Goals</h2>
|
|
<p>The primary goals of <span class="code">weewx </span>are:</p>
|
|
<ul>
|
|
<li>Architectural simplicity. No semaphores, no named pipes, no inter-process
|
|
communications, no complex multi-threading to manage. </li>
|
|
<li>One code base. The same code base should be used for all platforms, all
|
|
weather stations, all platforms, and any combination of features. Ample
|
|
configuration and customization options should be provided so the user
|
|
doesn't feel tempted to start hacking code. At worse, the user may have to
|
|
subclass, which is much easier to port to newer versions of the code base,
|
|
than customizing the base code.</li>
|
|
<li>Minimal reliance on external packages, so the user doesn't have to go chase
|
|
them down all over the Web before getting started.</li>
|
|
<li>"Fast enough." In any design decision, architectural simplicity trumps speed.
|
|
</li>
|
|
<li>Support only the Davis VantagePro2 initially (that's what I have), but make
|
|
no architectural decisions that lock out other stations.</li>
|
|
<li>As "pythonic" as I know how to make it. I'm a beginner Python programmer
|
|
with two decades of experience in C++. I tried hard to not make the code base
|
|
look like it was written by a C++ programmer who stumbled across a Python manual!</li>
|
|
</ul>
|
|
<h2>12.2 Strategies</h2>
|
|
<p>To meet these goals, the following strategies were used:</p>
|
|
<ul>
|
|
<li>A powerful configuration parser,
|
|
<a href="http://www.voidspace.org.uk/python/configobj.html">ConfigObj</a>, by
|
|
Michael Foord and Nicola Larosa, was chosen to read the configuration file.
|
|
This allows many options that might otherwise have to go in the code to go instead
|
|
in a configuration file.</li>
|
|
<li>A powerful templating engine, <a href="http://www.cheetahtemplate.org/">
|
|
Cheetah</a>, was used. This allows many variables that I may not have thought
|
|
of to be accessed from within the HTML templates, without starting to modify
|
|
the code.</li>
|
|
<li>A largely stateless design style. For example, many of the processing routines
|
|
read their own data from the database, rather than caching it and sharing with
|
|
other processing routines. While this means the same data may be read multiple
|
|
times, it also means the only point of possible cache incoherence is through
|
|
the database, where transactions are easily controlled. This greatly reduces
|
|
the chances of corrupting the data, making it much easier to understand and
|
|
modify the code base.</li>
|
|
<li>An engine-driven design. Key services are actually classes that can be
|
|
loaded at runtime, making it easy for users to add or subtract features.</li>
|
|
<li>No static variables (except read only variables) to make it easy to simultaneously
|
|
support multiple weather stations and to allow some level of multithreading.</li>
|
|
<li>Pure Python. The code base is 100% Python — no underlying C libraries need
|
|
be built to install <span class="code">weewx</span>. This also means no
|
|
Makefiles are needed.</li>
|
|
</ul>
|
|
<p>While <span class="code">weewx </span>is nowhere near as fast at generating images
|
|
and HTML as its predecessor, <span class="code">wview </span>(this is partially
|
|
because it uses fancier fonts and a much more powerful templating engine), it is
|
|
'fast enough' for all platforms but the slowest. I run it regularly on a 500 MHz
|
|
machine where generating the 9 images used in the "Current Conditions" page takes
|
|
just under 2 seconds (compared with <span class="code">wview</span>'s 0.4 seconds). </p>
|
|
<p>Unfortunately, the architectural goal of one code base is likely to be broken
|
|
with the arrival of Python V3.X. It has so many changes that are not backwards compatible
|
|
with V2.X, that a separate code base will most likely be needed. My intention is
|
|
to stick with the V2.5 and V2.6 versions until V3.X is so widespread it cannot be
|
|
ignored, then make a permanent switch. I doubt this will affect the average
|
|
<span class="code">weewx</span> user. </p>
|
|
<h2>12.3 Run time internals</h2>
|
|
<p>At a high-level, <span class="code">weewx</span> consists of an engine class called
|
|
<span class="code">StdEngine</span>. It is
|
|
responsible for loading any "services" that are to be run and arranging for them
|
|
to be called when key events occur, such as the arrival of LOOP data. The default install of <span class="code">weewx</span> includes the following services:</p>
|
|
<table style="width: 60%" align="center" class="style2">
|
|
<tr>
|
|
<td><strong>Service</strong></td>
|
|
<td><strong>Function</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">weewx.wxengine.StdWunderground</span></td>
|
|
<td>Starts thread to manage WU connection; adds new data to a Queue to
|
|
be posted to the WU by the thread.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">weewx.wxengine.StdCatchUp</span></td>
|
|
<td>Any data found on the weather station memory but not yet in the
|
|
archive, is retrieved and put in the archive.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">weewx.wxengine.StdTimeSynch</span></td>
|
|
<td>Arranges to have the clock on the station synchronized at regular
|
|
intervals.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">weewx.wxengine.StdPrint</span></td>
|
|
<td>Prints out new LOOP and archive packets on the console.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code">weewx.wxengine.StdProcess</span></td>
|
|
<td>Launches a new thread to do processing after a new archive record
|
|
arrives. The thread loads zero or more reports and processes them in
|
|
order. Reports do things such as generate HTML files, generate images,
|
|
or FTP files to a web server. New reports can be added easily by the
|
|
user.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>It is easy to add new services. The source distribution includes an example
|
|
new service called "<span class="code">MyAlarm</span>," which sends an email
|
|
when an arbitrary expression evaluates <span class="code">True</span>.</p>
|
|
<p>All writes to the databases are protected by transactions. You can kill the program
|
|
at any time (either Control-C if run from the command line or "<span class="code">/etc/init.d/weewx
|
|
stop</span>" if a daemon) without fear of corrupting the databases.</p>
|
|
<p>The code makes ample use of exceptions to insure graceful recovery from problems
|
|
such as network outages. It also monitors socket and console timeouts, restarting
|
|
whatever it was working on several times before giving up. In the case of an unrecoverable
|
|
console error (such as the console not responding at all), the program waits 60
|
|
seconds then restarts the program from the top.</p>
|
|
<p>Any "hard" exceptions, that is those that do not involve network and console
|
|
timeouts and are most likely due to a logic error, are logged, reraised, and ultimately
|
|
cause thread termination. If this happens in the main thread (not likely and hasn't
|
|
happened to me yet), then this causes program termination. Otherwise, the
|
|
program will keep chugging along, storing data, allowing you to fix the problem
|
|
at your leisure, without losing any data.</p>
|
|
<h2>12.4 Terminology</h2>
|
|
<p>This is a glossary of terminology used throughout the code.</p>
|
|
<table style="width: 100%">
|
|
<tr>
|
|
<td>packet</td>
|
|
<td>Something obtained off the weather station. Frequently uses a complex
|
|
internal encoding, so it requires some processing to be useful.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>record</td>
|
|
<td>Something obtained off the SQL database. </td>
|
|
</tr>
|
|
<tr>
|
|
<td>archive packet</td>
|
|
<td>A packet obtained off the store on the weather station. For example,
|
|
with a Davis VantagePro, it's obtained using their <span class="code">DMPAFT</span>
|
|
command. </td>
|
|
</tr>
|
|
<tr>
|
|
<td>loop packet</td>
|
|
<td>A packet with the current observations. For example, with a Davis VantagePro,
|
|
it's obtained using their <span class="code">LOOP</span> command. </td>
|
|
</tr>
|
|
<tr>
|
|
<td>archive record</td>
|
|
<td>A record obtained off the SQL database</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tuple-time</td>
|
|
<td>An instance of the Python object <span class="code">time.struct_time</span>.
|
|
This is a 9-wise tuple that represent a time. It could be in either local
|
|
time or UTC, though usually the former. See module <span class="code">time</span>
|
|
for more information. They are useful because they are a little closer in
|
|
format to what the Davis VantagePro uses, although they still require a
|
|
bit of processing. Variables carrying tuple time usually have a suffix '<span class="code">_tt</span>'.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>epoch time</td>
|
|
<td>Sometimes referred to as "unix time," or "unix epoch time." The number
|
|
of seconds since the epoch, which is 1 Jan 1970 00:00:00 UTC. Hence, it
|
|
always represents UTC (well.... after adding a few leap seconds. But, close
|
|
enough). This is the time used on the sqlite archive and appears as type
|
|
'<span class="code">dateTime</span>' in the SQL schema, perhaps an unfortunate
|
|
name because of the similarity to the Python type 'datetime'. Very easy
|
|
to manipulate, but it's an opaque big number. </td>
|
|
</tr>
|
|
<tr>
|
|
<td>time stamp</td>
|
|
<td>A variable in unix epoch time. Always in UTC. Variables carrying a time
|
|
stamp usually have a suffix '<span class="code">_ts</span>'.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>datetime</td>
|
|
<td>An instance of the Python object <span class="code">datetime.datetime</span>.
|
|
Variables of type datetime usually have a suffix '<span class="code">_dt</span>'.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>SQL type</td>
|
|
<td>A type that appears in the SQL database. This usually looks
|
|
something like '<span class="code">outTemp</span>', '<span class="code">barometer</span>',
|
|
'<span class="code">extraTemp1</span>', and so on.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>observation type</td>
|
|
<td>A type that can be used in the presentations. This is generally all
|
|
of the SQL types, plus calculated data (such as <span class="code">rms</span>
|
|
or <span class="code">vecavg</span>).</td>
|
|
</tr>
|
|
</table>
|
|
<h2>12.5 Units</h2>
|
|
<p>In general, there are three different areas where the unit system makes a
|
|
difference.:
|
|
</p>
|
|
<ol>
|
|
<li>On the weather station. As far as I know, the Davis VantagePro series
|
|
supports only U.S. Customary units internally. </li>
|
|
<li>In the database. The unit system of any individual record is indicated
|
|
by the "<span class="code">usUnits</span>" field. The numerical value 1
|
|
indicates U.S. Customary, 2 indicates Metric.
|
|
</li>
|
|
<li>In the presentation (i.e., html and image files). </li>
|
|
</ol>
|
|
<p>The general strategy is that measurements are stored internally in the native
|
|
measurement system of the weather instrument. That is, the units used in #1 and
|
|
#2 are always the same. With Version 1.5, weewx supports translations between #2
|
|
and #3, allowing any unit system to be used in the presentation layer.</p>
|
|
<p>It would be easy enough to support an instrument that uses metric units
|
|
internally, although this has not been done yet. </p>
|
|
<h2>12.6 Value "<span class="code">None</span>"</h2>
|
|
<p>The Python special value '<span class="code">None</span>' is used throughout
|
|
to signal a missing data point. All functions expect it.</p>
|
|
<p>However, the time value must never be '<span class="code">None</span>'. This
|
|
is because it is used as the primary key in the SQL database. </p>
|
|
<h2>12.7 Time</h2>
|
|
<p><span class="code">Weewx </span>stores all data in UTC (roughly, "Greenwich"
|
|
or "Zulu") time. However, usually one is interested in weather events in local time
|
|
and want image and HTML generation to reflect that. Furthermore, most weather stations
|
|
are configured in local time. This requires that many data times be converted back
|
|
and forth between UTC and local time. To avoid tripping up over time zones and daylight
|
|
savings time, <span class="code">weeewx</span> generally uses Python routines to
|
|
do this conversion. Nowhere in the code base is there any explicit recognition of
|
|
DST. Instead, its presence is implicit in the conversions. At times, this can cause
|
|
the code to be relatively inefficient. </p>
|
|
<p>For example, if one wanted to plot something every 3 hours in UTC time, it would
|
|
be very simple: to get the next plot point, just add 10,800 to the epoch time:</p>
|
|
<p class="tty">next_ts = last_ts + 10800</p>
|
|
<p>But, if one wanted to plot something for every 3 hours <em>in local time</em>
|
|
(that is, at 0000, 0300, 0600, etc.), despite a possible DST change in the middle,
|
|
one could modify the above to recognize whether a DST transition occurs sometime
|
|
between <span class="code">last_ts</span> and the next three hours and, if so, make
|
|
the necessary adjustments. This is generally what <span class="code">wview</span>
|
|
does. <span class="code">Weewx </span>takes a different approach and converts from
|
|
UTC to local, does the arithmetic, then converts back. This is inefficient, but
|
|
bulletproof against changes in DST algorithms, etc:</p>
|
|
<p class="tty">time_dt = datetime.datetime.fromtimestamp(last_ts)</p>
|
|
<p class="tty">delta = datetime.timedelta(seconds=10800)</p>
|
|
<p class="tty">next_dt = time_dt + delta</p>
|
|
<p class="tty">next_ts = int(time.mktime(next_dt.timetuple()))</p>
|
|
<p>Other time conversion problems are handled in a similar manner.</p>
|
|
<h1>13. Advanced topic: <a name="Customizing_weewx">customizing the internal
|
|
<span class="code">weewx</span></a> engines</h1>
|
|
<p>See file <a href="customizing.htm">customizing.htm</a> for details on how to
|
|
customize <span class="code">weewx</span>.</p>
|
|
|
|
</body>
|
|
|
|
</html>
|