mirror of
https://github.com/weewx/weewx.git
synced 2026-04-19 09:06:58 -04:00
1301 lines
73 KiB
HTML
1301 lines
73 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: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;
|
|
text-decoration: underline;
|
|
}
|
|
.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: bold;
|
|
}
|
|
.config_section {
|
|
font-family: "Courier New", Courier, monospace;
|
|
font-weight: bold;
|
|
}
|
|
.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.9</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="#Troubleshooting">Troubleshooting</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> or
|
|
<a href="http://www.pwsweather.com/">PWSweather.com</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>Key features:</p>
|
|
<ul>
|
|
<li>An easy to understand, simple, extensible micro-kernel
|
|
architecture<em>;</em></li>
|
|
<li>Uploads to popular weather sites, such as Weather Underground
|
|
and CWOP;</li>
|
|
<li>Uploads to your website using FTP;</li>
|
|
<li>Support for multiple <em>skins</em>;</li>
|
|
<li>Simple, but extensible templating system;</li>
|
|
<li>Support for multiple unit systems;</li>
|
|
<li>Calibration corrections;</li>
|
|
<li>Ability to extend <span class="code">weewx</span> with new
|
|
services and reports.</li>
|
|
</ul>
|
|
<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 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 well under 5,000 lines of code. It also has another 2,900
|
|
comment lines. Because it is pure Python, it requires no makefiles, no builds,
|
|
no special installs. 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. 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.</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">pyserial</a> (Version
|
|
2.3 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 where to install <span class="code">weewx</span></h2>
|
|
<p>Next step is figuring out where you want to install <span class="code">weewx</span>.
|
|
If <span class="code"><em>$WEEWX_INSTALL</em></span> symbolizes the root
|
|
location of where the <span class="code">weewx</span> directory will be
|
|
installed, then the nominal directory layout is:</p>
|
|
<table align="center" style="width: 60%">
|
|
<tr>
|
|
<td><strong>Subdirectory</strong></td>
|
|
<td><strong>Contents</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code"><em>$WEEWX_INSTALL</em>/bin</span></td>
|
|
<td>Python packages and scripts</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code"><em>$WEEWX_INSTALL</em>/weewx.conf</span></td>
|
|
<td>Configuration file</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code"><em>$WEEWX_INSTALL</em>/skins</span></td>
|
|
<td>Template skins and their configuration files</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code"><em>$WEEWX_INSTALL</em>/archive</span></td>
|
|
<td>sqlite3 archive and statistical databases</td>
|
|
</tr>
|
|
<tr>
|
|
<td><span class="code"><em>$WEEWX_INSTALL</em>/public_html</span></td>
|
|
<td>Generated HTML and .PNG images</td>
|
|
</tr>
|
|
</table>
|
|
<p>By default, the location for <span class="code"><em>WEEWX_INSTALL</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_INSTALL</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 '<span class="code">bin</span>' subdirectory as <span class="code"><em>
|
|
$WEEWX_INSTALL</em>/bin.YYYYMMDDHHMMSS</span>
|
|
where YYYYMMDDHHMMSS is a timestamp;</li>
|
|
<li>Save a copy of your old <span class="code">weewx.conf</span> as
|
|
<span class="code"><em>$WEEWX_INSTALL</em>/weewx.conf.YYYYMMDDHHMMSS;</span></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>Install a <span class="code">'skins'</span> subdirectory if one does not
|
|
already exist.</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 does not
|
|
actually have to be "built" and "installed" at all! You can just simply run it out of whatever
|
|
directory you unpack it into. However, it must still be told where to find the
|
|
skin templates and databases, as well as where to put the generated HTML files
|
|
and plot images. This is done by setting <span class="code">WEEWX_ROOT</span> in <span class="code">weewx.conf</span>
|
|
to reflect where your data files can be found (normally, the install process
|
|
does this for you):</p>
|
|
<pre>> # Edit WEEWX_ROOT to reflect the location of your data hierarchy:
|
|
> vi ./weewx-X.Y.Z/weewx.conf
|
|
> # Now run weewxd.py out of the directory you unpacked weewx into:
|
|
> ./weewx-X.Y.Z/bin/weewxd.py ./weewx-X.Y.Z/weewx.conf</pre>
|
|
<h1>6. <a name="Configuring_weewx">Configuring <span class="code">weewx</span></a></h1>
|
|
<p>This section covers configuring <span class="code">weewx</span>, in
|
|
particular 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> data root directory, generally <span class="code">/home/weewx</span>.
|
|
The subdirectories <span class="code">archive</span>, <span class="code">skins</span>,
|
|
and <span class="code">public_html</span> are expected to be found here.
|
|
</p>
|
|
<h2>6.1 Moving from wview</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>The main archive database can be just copied over because wview and <span class="code">weewx</span>
|
|
use identical schemas:</p>
|
|
<pre>mkdir <em>$WEEWX_ROOT</em>/archive
|
|
cp /usr/local/var/wview/archive/wview-archive.sdb <span class="code"><em>$WEEWX_ROOT</em></span>/archive/weewx.sdb</pre>
|
|
<p>The second database, the statistics, will then be automatically created and
|
|
backfilled on startup of weewx. 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>I have found that a five minute (300 seconds) archive interval works well for
|
|
the VantagePro. Because of the large amount of onboard memory it carries, going
|
|
to a larger interval really does not have any advantages.</p>
|
|
<p><em>Choose your archiving interval carefully! </em>Once chosen, it cannot be
|
|
changed without messing up your statistics (highs and lows will be OK, but
|
|
averages and rms wind speed will be wrong).</p>
|
|
<p>After setting the desired interval in the configuration file, 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 in a separate document <em>
|
|
<a href="customizing.htm">Customizing <span class="code">weewx</span></a> </em>under section <em>
|
|
<a href="customizing.htm#Reference:_The_Standard_skin_configuration_file">Reference:
|
|
The standard skin configuration file</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>
|
|
<p class="config_option">debug</p>
|
|
<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>
|
|
<p class="config_option">socket_timeout</p>
|
|
<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>
|
|
<p class="config_important">WEEWX_ROOT</p>
|
|
<p>Set to the root directory of the <span class="code">weewx</span> data file hierarchy
|
|
for this station, nominally '<span class="code">/home/weewx</span>'. The
|
|
weewx data subdirectories <span class="code">skins</span>, <span class="code">
|
|
archive</span>, and <span class="code">public_html</span> are expected to be
|
|
found here. 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>
|
|
<p class="config_important">location</p>
|
|
<p>The station location should be a UTF-8 string that describes the geography of
|
|
where you weather station is located, such as '<span class="code">Hood River, Oregon</span>'. Required. No
|
|
default.</p>
|
|
<p class="config_important">latitude<br />
|
|
longitude</p>
|
|
<p>The lat/lon should be set in decimal degrees, negative for southern and eastern
|
|
hemispheres, respectively. Required. No default.</p>
|
|
<p class="config_important">altitude</p>
|
|
<p>Set to the altitude of the station and the unit used for the altitude.
|
|
Required. No default. Example:</p>
|
|
<pre>altitude = 700, foot</pre>
|
|
<p class="config_important">rain_year_start</p>
|
|
<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>
|
|
<p class="config_option">week_start</p>
|
|
<p>Start of the week. 0=Monday, 1= Tuesday, ... , 6 = Sunday. Default is 6 (Sunday)</p>
|
|
<p class="config_option">clock_check</p>
|
|
<p>How often to check the station's onboard clock for drift, in seconds. Default
|
|
is 14400 (every 4 hours)</p>
|
|
<p class="config_option">max_drift</p>
|
|
<p>The maximum amount of drift to tolerate, in seconds, in the onboard
|
|
clock, before resetting the clock. Default is 5.</p>
|
|
<p class="config_option">cache_loop_data</p>
|
|
<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>
|
|
<p class="config_option">station_type</p>
|
|
<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>
|
|
<p class="config_important">port</p>
|
|
<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>
|
|
<p class="config_option">baudrate</p>
|
|
<p>Set to the baudrate of your station. The default is 19200.</p>
|
|
<p class="config_important">archive_interval</p>
|
|
<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>
|
|
<p class="config_option">iss_id</p>
|
|
<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>
|
|
<p class="config_option">archive_delay</p>
|
|
<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>
|
|
<p class="config_option">timeout</p>
|
|
<p>How many seconds to wait for a response from the station before giving
|
|
up. Default is 5 seconds.</p>
|
|
<p class="config_option">wait_before_retry</p>
|
|
<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>
|
|
<p class="config_option">max_tries</p>
|
|
<p>How many times to try again before giving up. Default is 4.</p>
|
|
<p class="config_option">unit_system</p>
|
|
<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">[RESTful]</h3>
|
|
<p>This section is for configuring uploads to simple
|
|
<a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">RESTful</a>
|
|
servers such as the <a href="http://www.wunderground.com/">Weather Underground</a>,
|
|
<a href="http://www.pwsweather.com/">PWSweather.com</a>, or
|
|
<a href="http://www.wxqa.com/">CWOP</a>.</p>
|
|
<h4 class="config_section">[[Wunderground]]</h4>
|
|
<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>
|
|
<p class="config_important">station</p>
|
|
<p>Set to your Weather Underground station ID (e.g., <span class="code">KORHOODR3</span>).
|
|
Required.</p>
|
|
<p class="config_important">password</p>
|
|
<p>Set to your Weather Underground password. Required.</p>
|
|
<h4 class="config_section">[[PWSweather]]</h4>
|
|
<p><span class="code">Weewx </span>can send your current data to the
|
|
PWSweather.com service.
|
|
If you do not wish to do this, comment out the two options below.</p>
|
|
<p class="config_important">station</p>
|
|
<p>Set to your PWSweather station ID.
|
|
Required.</p>
|
|
<p class="config_important">password</p>
|
|
<p>Set to your PWSweather password. Required.</p>
|
|
<h4 class="config_section">[[CWOP]]</h4>
|
|
<p><span class="code">Weewx</span> can send your data to the Citizen Weather
|
|
Observer Program. If you do not wish to do this, comment out option "<span class="code">station</span>"
|
|
below.</p>
|
|
<p class="config_important">station</p>
|
|
<p>Set to your CWOP station ID (e.g., <span class="code">CW1234</span>).
|
|
Required.</p>
|
|
<p class="config_important">passcode</p>
|
|
<p>This is used for APRS (amateur radio) stations only. Set to the passcode
|
|
given to you by the CWOP operators. Otherwise, leave this option commented out
|
|
[Required for APRS stations; ignored for others]</p>
|
|
<p class="config_option">server</p>
|
|
<p>A comma separated list of servers:ports to try. Unless you have a good reason
|
|
to change this, use the servers listed. [Required.]</p>
|
|
<p class="config_option">interval</p>
|
|
<p>The interval in seconds between posts. Because CWOP is heavily used, the
|
|
operators discourage very frequent posts. Every 5 minutes (300 seconds) is fine,
|
|
but they prefer every 10 minutes (600 s) or even longer. Setting this value to
|
|
zero will cause every archive record to be posted. [Optional. Default is zero.]</p>
|
|
<p class="config_option">stale</p>
|
|
<p>How old a record can be before it will not be used for a catch up. CWOP does
|
|
not use the timestamp on a posted record. Instead, they use the wall clock time
|
|
that it came in. This means that if your station is off the air for a long
|
|
period of time, then weewx attempts a catch up, old data could be interpreted as
|
|
the current conditions. [Optional. Default is 1800 seconds.]</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>
|
|
<p class="config_option">archive_file</p>
|
|
<p>The path, relative to the <span class="code">WEEWX_ROOT </span>directory, to
|
|
the database. Required</p>
|
|
<p class="config_option">unit_system</p>
|
|
<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>
|
|
<p class="config_option">stats_file</p>
|
|
<p>The path, relative to the <span class="code">WEEWX_ROOT </span>directory to the
|
|
statistical database. Required.</p>
|
|
<p class="config_option"><a name="stats_types">stats_types</a></p>
|
|
<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>
|
|
<p class="config_important">passive</p>
|
|
<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>
|
|
<p class="config_option">max_tries</p>
|
|
<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">[Calibrate]</h3>
|
|
<p>One of the services that <span class="code">weewx</span> can run is a <em>calibration service</em>
|
|
called <span class="code">StdCalibrate</span>.
|
|
This service offers an opportunity to correct for any calibration errors in your
|
|
instruments. It is very general and flexible.</p>
|
|
<p>If you do not wish to apply any calibrations, you can leave it out of
|
|
<span class="code"><a href="#service_list">service_list</a></span>, the list of
|
|
services to be run, and it will not be loaded or run.</p>
|
|
<h4 class="config_section">[[Corrections]]</h4>
|
|
<p>In this section you list all <em>correction expressions</em>. For example,
|
|
say that you know your outside thermometer reads high by 0.2°F. You could
|
|
add the expression:</p>
|
|
<pre>outTemp = outTemp - 0.2</pre>
|
|
<p>Perhaps you need a linear correction around a reference temperature of 68°F:</p>
|
|
<pre>outTemp = outTemp + (outTemp-68) * 0.02</pre>
|
|
<p>It is even possible to do corrections involving more than one variable.
|
|
Suppose you have a temperature sensitive barometer:</p>
|
|
<pre>barometer = barometer + (outTemp-32) * 0.0091</pre>
|
|
<p>All correction expressions are run in the order given.</p>
|
|
<p>The units should be <em>in the native units of the instrument</em>, US
|
|
Customary in the case of the VantagePro.</p>
|
|
<p>Both LOOP data and archive data will be corrected. It is important that the
|
|
calibration service, <span class="code">StdCalibrate</span>, be run <em>before</em>
|
|
the archiving service <span class="code">StdArchive</span>, so that it is the
|
|
corrected data that is stored.</p>
|
|
<p>If all you require is a simple correction offset, this can also be done in
|
|
the Davis VantagePro hardware. See your manual for instructions.</p>
|
|
<h3 class="config_section">[QC]</h3>
|
|
<p>Another service that weewx can run is a <em>quality control service</em>
|
|
called <span class="code">StdQC</span>. This service is very simple and only
|
|
checks that values are within a minimum and maximum range.</p>
|
|
<p>If you do not wish to use this service, you can leave it out of
|
|
<span class="code"><a href="#service_list">service_list</a></span>, the list of
|
|
services to be run, and it will not be loaded or run.</p>
|
|
<h4 class="config_section">[[MinMax]]</h4>
|
|
<p>In this section you list the observation types you wish to have checked,
|
|
along with their minimum and maximum values. The units should be in the native
|
|
units of the weather station hardware (<em>e.g.</em>, US Customary in the case of the Davis
|
|
VantagePro2). For example,</p>
|
|
<p class="tty">[[MinMax]]<br />
|
|
outTemp = -40, 120<br />
|
|
barometer = 28, 32.5<br />
|
|
outHumidity = 0, 100</p>
|
|
<p>In this example, if a temperature should fall outside of the inclusive range
|
|
-40 °F through 120 °F, then it will be set to the null value,
|
|
<span class="code">None</span> and ignored. In a similar manner, the acceptable
|
|
values for barometric pressure would be 28 through 32.5 inHg, for humidity 0
|
|
through 100%.</p>
|
|
<p>Both LOOP and archive data will be checked. It is important that the quality
|
|
control service be run <em>after</em> the calibration service <span class="code">
|
|
StdCalibrate</span> and <em>before</em> the archiving service <span class="code">
|
|
StdArchive</span>, so that it is the calibrated data that is checked and then
|
|
stored.</p>
|
|
<p>Knowing the details of how your hardware encodes data helps to minimize the
|
|
number of observations that need to be checked. For example, the VP2 devotes
|
|
only one unsigned byte to storing wind speed, and even then <span class="code">
|
|
0xff</span> is devoted to a bad value, so the only possible values that could
|
|
appear are 0 through 126 mph, a reasonable range. So, there is no real point in
|
|
checking wind speed for these instruments.</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="file://RAVEN/tkeffer/workspace/weewx/docs/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>
|
|
<p class="config_option"><a name="service_list">service_list</a></p>
|
|
<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. The standard list of services run by weewx is:</p>
|
|
<p class="tty">service_list = weewx.wxengine.StdCalibrate, weewx.wxengine,StdQC,
|
|
weewx.wxengine.StdArchive, weewx.wxengine.StdTimeSynch, weewx.wxengine.StdPrint,
|
|
weewx.wxengine.StdRESTful, weewx.wxengine.StdReportService</p>
|
|
<p>You can leave some of these services out if you do not need them. However,
|
|
this will only make a slight difference in execution speed.</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: 70%" align="center">
|
|
<tr>
|
|
<td style="width: 25%">SuSE:</td>
|
|
<td class="code"><em>$WEEWX_ROOT</em>/start_script/SuSE/weewx</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width: 25%">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: 70%" align="center">
|
|
<tr>
|
|
<td style="width: 25%">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: 70%" align="center"> <tr>
|
|
<td style="width: 25%">SuSE:</td>
|
|
<td class="code">chmod +x /etc/init.d/weewx</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width: 25%">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: 70%" align="center">
|
|
<tr>
|
|
<td style="width: 25%">SuSE:</td>
|
|
<td class="code">/usr/lib/lsb/install_initd /etc/init.d/weewx</td>
|
|
</tr>
|
|
<tr>
|
|
<td style="width: 25%">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. This will
|
|
be done automatically on startup by <span class="code">weewx</span>.</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 name="Troubleshooting">Troubleshooting</a></h1>
|
|
<p>If you get stuck, be sure to </p>
|
|
<ul>
|
|
<li>Set option <span class="code">debug </span>in <span class="code">weewx.conf</span>
|
|
to <span class="code">1</span> (one)! It will put lots more information in the
|
|
log file, which can be very useful for troubleshooting and debugging!</li>
|
|
<li><a href="#Monitoring_weewx">Look at the log file</a>. I am always happy
|
|
to take questions, but the first thing I will ask you is: "Did you look at
|
|
the log file?"</li>
|
|
<li>Run from the command line. Generally, weewx will catch and log any
|
|
unrecoverable exceptions. But if you are getting strange results, it is
|
|
worth running from the command line and looking for any clues.</li>
|
|
</ul>
|
|
<h2>10.1 Execution</h2>
|
|
<h3><span class="code">configobj</span> errors</h3>
|
|
<p>These are errors in the configuration file. Two are very common.
|
|
Incidentally, these errors are far easier to diagnose when <span class="code">
|
|
weewx</span> is run from the command line.</p>
|
|
<h4><span class="code">configobj.DuplicateError</span> exception</h4>
|
|
<p>This error is caused by using an identifier more than once in the
|
|
configuration file. For example, you may have inadvertently listed your FTP
|
|
server twice:</p>
|
|
<pre>[Reports]
|
|
[[FTP]]
|
|
... (details elided)
|
|
user = fred
|
|
server = ftp.myhost.com
|
|
password = mypassword
|
|
server = ftp.myhost.com # OOPS! Listed it twice!
|
|
path = /weather
|
|
... </pre>
|
|
<p>Generally, if you encounter this error, the log file will give you the line
|
|
number it happened in:</p>
|
|
<pre>Apr 24 12:09:15 raven weewx[11480]: wxengine: Error while parsing configuration file /home/weewx/weewx.conf
|
|
Apr 24 12:09:15 raven weewx[11480]: wxengine: Unable to initialize main loop:
|
|
Apr 24 12:09:15 raven weewx[11480]: **** Duplicate keyword name at line 254.
|
|
Apr 24 12:09:15 raven weewx[11480]: **** Exiting. </pre>
|
|
<h4><span class="code">configobj.NestingError</span> exception</h4>
|
|
<p>This is a very similar error, and is caused by a misformed section nesting.
|
|
For example:</p>
|
|
<pre>[Reports]
|
|
[[FTP]]]
|
|
... (details elided)</pre>
|
|
<p>Note the extra closing bracket on the subsection <span class="code">FTP</span>.</p>
|
|
<h2>10.2 Hardware</h2>
|
|
<h3>Tips on a reliable system</h3>
|
|
<p>If you are having problems keeping your weather station up for long periods
|
|
of time, here are some tips, in decreasing order of importance:</p>
|
|
<ul>
|
|
<li>Run on dedicated hardware. If you are using the server for other tasks,
|
|
particularly as your desktop machine, you will have reliability problems. If
|
|
you are using it as a print or network server, you will probably be OK.</li>
|
|
<li>Run headless. Modern graphical systems are extremely complex. As new
|
|
features are added, test suites don't always catch up. Your system will be
|
|
much more reliable if you run it without a windowing system (X Windows, in
|
|
the case of Linux).</li>
|
|
<li>Use an Uninterruptible Power Supply (UPS). The vast majority of power
|
|
glitches are very short lived — just a second or two — so you do not
|
|
need a big one. The 425 VA unit I use to protect my fit-PC cost me
|
|
$55 at Best Buy.</li>
|
|
<li>Use a VantagePro console with a serial connection, not a USB connection. See the
|
|
next section for details.</li>
|
|
<li>If you do use a USB connection, put a ferrite coil on each end of the
|
|
connection.</li>
|
|
</ul>
|
|
<h3>cp2101 converter problems</h3>
|
|
<p>The USB converter used in the Davis VantagePro is known to have some "noise"
|
|
problems. The symptom is that the Linux kernel will disconnect from your old USB
|
|
port claiming "EMI noise", and reconnect to a new and different port, where
|
|
<span class="code">weewx</span> can't find it. Here's
|
|
a typical log output:</p>
|
|
<pre>Nov 29 10:40:21 hummingbird kernel: [6661624.786792] hub 2-0:1.0: port 3 disabled by hub (EMI?), re-enabling...
|
|
Nov 29 10:40:21 hummingbird kernel: [6661624.786871] usb 2-3: USB disconnect, address 2
|
|
Nov 29 10:40:21 hummingbird kernel: [6661624.795778] cp2101 2-3:1.0: device disconnected
|
|
Nov 29 10:40:21 hummingbird weewx[25808]: VantagePro: Max retries exceeded while getting LOOP packets</pre>
|
|
<pre> </pre>
|
|
<pre>... (messages elided)</pre>
|
|
<pre> </pre>
|
|
<pre>Nov 29 10:40:22 hummingbird kernel: [6661625.352340] cp2101 2-3:1.0: cp2101 converter detected
|
|
Nov 29 10:40:22 hummingbird kernel: [6661625.528107] usb 2-3: reset full speed USB device using ohci_hcd and address 3
|
|
Nov 29 10:40:22 hummingbird kernel: [6661625.735497] usb 2-3: cp2101 converter now attached to ttyUSB1</pre>
|
|
<p>In this example, the VantagePro was connected to <span class="code">
|
|
/dev/ttyUSB0</span>, but then reconnected to <span class="code">/dev/ttyUSB1</span>. </p>
|
|
<p>If you put ferrite coils on the USB connection, you will eliminate 90% of
|
|
this problem. I did this about 6 months ago, and have not had a problem since. </p>
|
|
<p>However, there is one final step you can take that will reallly harden up
|
|
your system: install a <span class="code">udev</span> script that will create
|
|
a symbolic link to the VantagePro USB port, whatever it might be. With this
|
|
approach, if the port jumps from <span class="code">ttyUSB0</span> to
|
|
<span class="code">ttyUSB1</span>, the symbolic link will move
|
|
as well. You just specify port <span class="code">/dev/vpro</span> and be done with it. Here's how:</p>
|
|
<h4>Installing a udev script</h4>
|
|
<p>I have installed a file <span class="code">/etc/udev/rules.d/66-vpro.rules</span>
|
|
on my fit-PC that looks like this:</p>
|
|
<pre># Automount the VantagePro2 to port /dev/vpro.</pre>
|
|
<pre># Install in /dev/udev/rules.d/66-vpro.rules</pre>
|
|
<pre>#</pre>
|
|
<pre>ACTION=="add", ATTRS{interface}=="CP2102 USB to UART Bridge Controller", SYMLINK+="vpro"</pre>
|
|
<p>What this rule says is that when the USB port is plugged in (action
|
|
<span class="code">add</span>), and it has an attribute with name
|
|
<span class="code">interface</span> that is equal to "<span class="code">CP2102
|
|
USB to UART Bridge Controller</span>", then add a symbolic link for its physical port
|
|
to <span class="code">/dev/vpro</span>. </p>
|
|
<p>Your controller may have a different identifier!! I can recommend this
|
|
article, "<a href="http://www.reactivated.net/writing_udev_rules.html"><em>Writing
|
|
udev rules</em></a><span class="style1">,</span>" for how to find and write an
|
|
appropriate <span class="code">udev</span> rule for your controller. In
|
|
particular, run the command</p>
|
|
<pre># udevinfo -a -p $(udevinfo -q path -n /dev/ttyUSB0)</pre>
|
|
<p>where<span class="code"> /dev/ttyUSB0</span> is the port (substitute your
|
|
real USB port) the VP2 is attached to. It will print out various identifiers
|
|
that can be useful in identifying your VP2 to <span class="code">udev</span>.</p>
|
|
<p>Once you've installed your <span class="code">udev</span> rule, you can then
|
|
set <span class="code">port=/dev/vpro</span> in <span class="code">weewx.conf</span>,
|
|
confident that it will always point to your VantagePro2, no matter which USB
|
|
port it is actually attached to!</p>
|
|
<p>I have tested this system many times. You can yank the USB port out of the
|
|
machine and then plug it back in while also pulling out the network connection
|
|
in the middle of an FTP upload: weewx will recover.</p>
|
|
<p>Or, at least, it should!</p>
|
|
<p> </p>
|
|
<h2>10.3 Templates</h2>
|
|
<h3><span class="code">Cheetah.NameMapper.NotFound</span> errors</h3>
|
|
<p>If you get errors of the sort:</p>
|
|
<pre>Apr 12 05:12:32 raven reportengine[3074]: filegenerator: Caught exception "<class 'NameMapper.NotFound'>"
|
|
Apr 12 05:12:32 raven reportengine[3074]: **** Message: "cannot find 'fubar' in template /home/weewx/skins/Standard/index.html.tmpl"
|
|
Apr 12 05:12:32 raven reportengine[3074]: **** Ignoring template and continuing.</pre>
|
|
<p>you have a tag in your template that <span class="code">weewx</span>
|
|
does not recognize (in this example, it's the tag <span class="code">$fubar</span>
|
|
in the template <span class="code">/home/weewx/skins/Standard/index.html.tmpl</span>.</p>
|
|
<h1>11. A<a name="Architectural_notes">rchitectural notes</a></h1>
|
|
<p>This section is not needed to get started. </p>
|
|
<h2>11.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>"Fast enough." In any design decision, architectural simplicity
|
|
and elegance trumps speed.
|
|
</li>
|
|
<li>One code base. The same code base should be used for all platforms, all
|
|
weather stations, all reports, 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>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>11.2 Strategies</h2>
|
|
<p>To meet these goals, the following strategies were used:</p>
|
|
<ul>
|
|
<li>A "micro-kernel" design. The actual internal engine does very little.
|
|
It's main job is to load and run <em>services</em> at runtime, making it easy for users to add or subtract features.</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>Isolate the data collection and archiving code in a single thread that
|
|
is simple enough that it is unlikely to crash. The report
|
|
processing is where most mistakes are likely to happen, so isolate that in a
|
|
separate thread. If it crashes, it will not affect the main data thread.</li>
|
|
<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>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 due to
|
|
its simplicity), then this causes program termination. If it happens in the
|
|
report processing thread (much more likely), then only the generation of reports
|
|
will be affected — the main thread will continue downloading data off the
|
|
instrument and putting them in the database. You can fix the problem at your
|
|
leisure, without worrying about losing any data.</p>
|
|
<h2>11.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>
|
|
<tr>
|
|
<td>value tuple</td>
|
|
<td>A 2-way tuple. First element is a value, second element the unit
|
|
type the value is in. An example would be <span class="code">(21.2,
|
|
'degree_C')</span>.</td>
|
|
</tr>
|
|
</table>
|
|
<h2>11.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>11.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>11.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>
|
|
<p> </p>
|
|
|
|
</body>
|
|
|
|
</html>
|