mirror of
https://github.com/weewx/weewx.git
synced 2026-04-18 08:36:54 -04:00
<!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:o="urn:schemas-microsoft-com:office:office" xmlns:v="urn:schemas-microsoft-com:vml">
<!-- $Revision$ -->
<!-- $Author$ -->
<!-- $Date$ -->
<head>
<meta content="en-us" http-equiv="Content-Language" />
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<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: bold xx-large Verdana, arial, sans-serif;
color: #FFFFFF;
border: 1px solid black;
border-bottom: 2px solid black;
border-right: 2px solid black;
background-color: #008080;
padding-left: .5em;
padding-right: .5em;
margin-top: 60pt;
border-right-width: medium;
border-bottom-width: medium;
}
h2 {
font: bold x-large Verdana, arial, sans-serif;
color: teal;
border: 1px solid black;
background-color: #e8e8e8;
padding-left: .5em;
padding-right: .5em;
margin-top: 30pt;
}
h3 {
font: bold medium Verdana, arial, sans-serif;
color: teal;
border: 1px solid black;
background-color: #e8e8e8;
padding-left: .5em;
padding-right: .5em;
}
h4 {
font: bold medium Verdana, arial, sans-serif;
color: black;
}
.code {
font-family: "Courier New", Courier, monospace;
}
table {
border-style: solid;
border-width: 1px;
border-collapse: collapse;
}
td {
border-style: solid;
border-width: 1px;
padding: 5px;
}
.indent {
margin-left: 40px;
}
.tty, pre {
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;
}
.xxsmall {
font-size: xx-small;
}
.highlight {
background-color: #FFFF66;
}
.center {
text-align: center;
}
.Example_output {
padding: 10px;
border: thin #000000 dotted;
font-family: "Times New Roman", Times, serif;
margin-left: 40px;
}
</style>
</head>
<body>
<h1 class="title">The <span class="code">weewx</span> weather system<br />
Version 1.6</h1>
<h1>Table of Contents</h1>
<ol>
<li><a href="#Copyright">Copyright</a></li>
<li><a href="#About_weewx">About weewx</a></li>
<li><a href="#Downloading_weewx">Downloading weewx</a></li>
<li><a href="#Prerequisites">Prerequisites</a></li>
<li><a href="#Installing_weewx">Installing weewx</a></li>
<li><a href="#Configuring_weewx">Configuring weewx</a></li>
<li><a href="#Running_weewx">Running weewx</a></li>
<li><a href="#Compatibility_with_wview">Compatibility with wview</a></li>
<li><a href="#Monitoring_weewx">Monitoring weewx</a></li>
<li><a href="#Architectural_notes">Architectural notes</a></li>
</ol>
<p>For information on customizing <span class="code">weewx</span>, see the separate
document <a href="customizing.htm"><em>Customizing </em><em><span class="code">weewx</span></em></a>.</p>
<p>For instructions on upgrading from various versions, see the separate
document <em><a href="upgrading.htm">Upgrading <span class="code">weewx</span></a></em>.</p>
<p>For instructions on porting to the SheevaPlug, see the separate document <em>
<a href="sheeva.htm">Notes on porting <span class="code">weewx</span> to the
SheevaPlug</a></em>.</p>
<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 upload the reports
to a remote Web server as well as 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, at this point it supports only
the <a href="http://www.davisnet.com/weather/products/vantagepro.asp">Davis
VantagePro2</a> weather station. 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 of sqlite, 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>/skins</span> is where the skins
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 'skin' subdirectory as <span class="code"><em>$WEEWX_ROOT</em>/skins.YYYYMMDDHHMMSS</span>
where YYYYMMDDHHMMSS is a timestamp;</li>
<li>Save your old 'bin' subdirectory as <span class="code"><em>$WEEWX_ROOT</em>/bin.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 files
<span class="code">weewx.conf</span> and <span class="code">skin.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
Slim</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>Station specific information is set in the configuration file
<span class="code"><em>$WEEWX_ROOT</em>/weewx.conf</span>. There is another configuration
file <span class="code">skin.conf</span> for presentation-specific options, which
is described under section <em>
<a href="customizing.htm#Reference:_The_Standard_skin_configuration_file">Reference:
The standard skin configuration file</a></em> in the document <em>
<a href="customizing.htm">Customizing <span class="code">weewx</span></a> </em>.</p>
<p>Most of the important options 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 UTF-8 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="customizing.htm#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_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="customizing.htm#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">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_tries</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">[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"><a name="[Stats]">[Stats]</a></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"><a name="[Reports]">[Reports]</a></h3>
<p>This section controls which reports are to be generated. While it can be highly
customized for your individual situation, this documentation describes the section
as shipped in the standard distribution.</p>
<p>Each report is represented by a sub-section, marked with double brackets (<em>e.g.</em>,
<span class="code">[[MyReport]]</span>). Any options for the report should be placed
under it. The standard report service will go through the sections, running each
report in order. Hence, for the stock distribution, report <span class="code">[[StandardReport]]</span>
will be run first, then report <span class="code">[[FTP]]</span> (which actually
optionally uploads the results to a remote web server). Details for how to customize
reports are in the section <em>
<a href="customizing.htm#Opportunities_for_customizing_reports">Opportunities for
customizing reports</a></em>, in the document <em><a href="customizing.htm">Customizing
<span class="code">weewx</span></a></em>.</p>
<p class="config_option">SKIN_ROOT</p>
<p>The directory relative to <span class="code"><em>$WEEWX_ROOT</em></span> where
the skins live. Default is <span class="code">skins</span>.</p>
<p class="config_option">HTML_ROOT</p>
<p>The target directory for the generated files, relative to <span class="code">
<em>$WEEWX_ROOT</em></span>. Generated files and images will be put here. Default
is <span class="code">public_html</span>.</p>
<h4 class="config_section">[[StandardReport]]</h4>
<p>This is the standard report that will be run on every archiving interval. It
uses the skin "<span class="code">Standard</span>", which generates four HTML pages
("day", "week", "month", and "year" observations),
plot graphs for same, an RSS feed, and NOAA
monthly and yearly reports. Unless changed otherwise, it uses US Customary Units
and puts the results in <span class="code">public_html</span> and subdirectory
<span class="code">public_html/NOAA</span>.</p>
<h4 class="config_section">[[FTP]]</h4>
<p>While this "report" doesn't actually generate anything, it uses the report machinery
to upload files from directory <span class="code"><em>$HTML_ROOT</em></span> to
a remote webserver. 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_tries</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">[Engines]</h3>
<p>This section is used to configure the internal service engine in weewx. It is
for advanced customization. Details on how to do this is found in the section
<em><a href="customizing.htm#Customizing_the_weewx_service_engine">Customizing the
weewx service engine</a> </em>in the document <a href="customizing.htm"><em>Customizing
</em><span class="code"><em>weewx</em></span></a>.</p>
<h4 class="config_section">[[WxEngine]]</h4>
<p>This section is for options used by the service engine.</p>
<pre>service_list</pre>
<p>This option is the list of <em>services</em> that are to be run by the service
engine. After each event (such as the arrival of LOOP data, etc.), they will be
run in the given order. </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 class="indent" style="width: 100%">
<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 class="indent" style="width: 100%">
<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 class="indent" style="width: 100%">
<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 class="indent" style="width: 100%">
<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. A<a name="Architectural_notes">rchitectural notes</a></h1>
<p>This section is not needed to get started. </p>
<h2>10.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>10.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>
<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>10.3 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>10.4 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>10.5 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>10.6 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">weewx</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>
</body>
</html>