mirror/weewx
1
0
Fork 0
mirror of https://github.com/weewx/weewx.git synced 2026-04-18 00:26:57 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
3fe5f3f475fcbebf8648b95e04a3dd4de685bd2b
weewx/docs/usersguide.htm
Tom Keffer 3fe5f3f475 Include [Defaults] in User's Guide
2018-12-05 05:40:07 -08:00

3608 lines
180 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<title>WeeWX: User's Guide</title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<link rel="stylesheet" href="css/ui-lightness/jquery-ui-1.10.4.custom.min.css"/>
<link rel="stylesheet" href="css/jquery.tocify.css"/>
<link rel="stylesheet" href="css/weewx_docs.css"/>
<link rel="icon" href="images/favicon.png" type="image/png"/>
</head>
<body>
<div class="sidebar">
<div class="doclist">
<a href="usersguide.htm">User's Guide</a><br/> <a href="customizing.htm">Customization Guide</a><br/> <a
href="hardware.htm">Hardware Guide</a><br/> <a href="utilities.htm">Utilities Guide</a><br/> <a
href="upgrading.htm">Upgrade Guide</a><br/> <a href="devnotes.htm">Notes for Developers</a>
</div>
<div id="toc_controls"></div>
<div id="toc_parent">
<div id="toc">
<!-- The table of contents will be injected here -->
</div>
</div>
</div>
<div class="main">
<div class="header">
<div class="logoref">
<a href='http://weewx.com'> <img src='images/logo-weewx.png' class='logo' style="float:right"
alt="weewx logo"/> </a><br/> <span class='version'>
Version: 3.9
</span>
</div>
<div class="title">User's Guide to WeeWX</div>
</div>
<div id="technical_content" class="content">
<p>
This is the complete guide to installing, configuring, and troubleshooting WeeWX.
</p>
<h1 id="about">About WeeWX</h1>
<p><a href="http://www.weewx.com">WeeWX</a> is software, written in <a href="http://www.python.org">Python</a>,
that interacts with a 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 weather services such as <a
href="https://www.wunderground.com">WeatherUnderground</a>, <a href="http://wxqa.com">CWOP</a>, or <a
href="https://www.pwsweather.com/">PWSweather.com</a>.
</p>
<p>Initial development began in the winter of 2008-2009, with the first release in 2009.</p>
<p>The source code is hosted on <a href="https://github.com/weewx/weewx">GitHub</a>, while downloads are
available at <a href="http://weewx.com/downloads"><span class="code">weewx.com/downloads</span></a>.
</p>
<p>WeeWX is about 13,000 lines of code, plus another 13,000 for the drivers for all the types of supported
hardware.
</p>
<h1 id="prerequisites">System requirements</h1>
<h2 id="hardware">Station hardware</h2>
<p>WeeWX includes support for many types of weather stations. In addition to hardware support, WeeWX comes with
a software simulator, useful for testing and evaluation.
</p>
<p>The <a href="hardware.htm#driver_status">driver compatibility table</a> in the hardware guide has a detailed
list of the manufacturers and models supported by the drivers that come with WeeWX. If you do not see your
hardware in this table, check the list of <a href="http://weewx.com/hardware.html">supported hardware</a>;
the pictures may help you identify the manufacturer and/or model. Compatibility for some hardware is
provided by 3rd party drivers, available at the <a href="https://github.com/weewx/weewx/wiki">Wiki</a>.
Finally, check the <a href="http://weewx.com/hwcmp.html">hardware comparison</a> to see if your hardware is
known but not yet supported.
</p>
<p>
If you still cannot find your hardware, post to the <a
href="https://groups.google.com/forum/#!forum/weewx-user">User's Group</a> for help.
</p>
<h2>Computer hardware</h2>
<p>WeeWX is written in Python, so it has the overhead associated with that language. Nevertheless, it is "fast
enough" on just about any hardware. It has been run on everything from an early MacBook to a router!
</p>
<p>I run WeeWX on a Fit-PC with a 500 MHz AMD Geode processor and 512 MB of memory. Configured this way, it
consumes about 5% of the CPU, 100 MB of virtual memory, and 20 MB of real memory.
</p>
<p>WeeWX also runs great on a Raspberry Pi, although report generation will take longer. For example, the 12 "To
Date" templates take about 5.1 seconds on the RPi, compared to 3.0 seconds on my Fit-PC, and a mere 0.9
seconds on my vintage Dell Optiplex 745.
</p>
<h2>Time</h2>
<p> You should run a <a href="http://www.ntp.org/">NTP</a> daemon on your server to ensure 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>
<p>The time on some stations is automatically synchronized with the WeeWX server nominally every four hours. The
synchronization frequency can be adjusted in the WeeWX configuration.
</p>
<h2>Python</h2>
<p>
Python 2.6 or 2.7 is required. If you are using Python 2.6, see the <a href="#python2_6">special note
below</a> about PySerial.
</p>
<p>
Python 3 will not work.
</p>
<h2 id="permissions">Permissions</h2>
<p>There are a few places where permissions affect WeeWX:
</p>
<ul>
<li>Installation/Configuration. The user who does the installation must have write permission in order to do
the install. Similarly, the user who modifies configuration files and skins must have write permission
on those files and directories. The specific folders depend on the installation method, and are listed
in the <a href="#Where_to_find_things">layout table</a> below.
</li>
<li>Running. Most USB and serial devices require administrative (root) access. Unless the device has been
configured with a udev rule or other mechanism that grants access to non-root users, WeeWX commands must
be run as root or must be prefaced with <span class="code">sudo</span> for temporary administrative
privileges.
</li>
</ul>
<p>Normally WeeWX is installed and run with administrative (root) permissions. However, it is not uncommon to
install and run WeeWX as a generic non-root user, or even as a user created specifically to run WeeWX.
</p>
<h1 id="installing">Installing WeeWX</h1>
<h2>Required skills</h2>
<p>
In the world of open-source hobbyist software, WeeWX is pretty easy to install and configure. There are not
many package dependencies, the configuration is simple, and this guide includes extensive instructions.
There are thousands of people who have successfully done an install. However, there is no "point-and-click"
interface, so you will have to do some manual configuring.
</p>
<p>You should have the following skills:</p>
<ul>
<li>The patience to read and follow this guide;</li>
<li>Willingness and ability to edit a configuration file;</li>
<li>Some familiarity with Linux or other Unix derivatives;</li>
<li>Ability to do simple Unix tasks such as changing file permissions and running commands;
</li>
<li>No programming experience is necessary unless you wish to extend WeeWX. In this case, you should be
comfortable programming in Python.
</li>
</ul>
<p>If you get stuck, there is a very active <a href="https://groups.google.com/forum/#!forum/weewx-user">User's
Group</a> to help, but, please, try to solve the problem yourself before posting.
</p>
<h2>Overview</h2>
<p>This is an outline of the process to install, configure, and run WeeWX:</p>
<ol>
<li>Read the <a href="hardware.htm">hardware notes</a> for your weather station. This will let you know of
any features, limitations, or quirks of your hardware.
</li>
<li>Install WeeWX. Use the step-by-step instructions in one of the <a href="#installation_methods">installation
methods</a> below.
</li>
<li>Configure the hardware. This involves setting things like the onboard archive interval, rain bucket
size, etc. You may have to follow directions given by your hardware manufacturer, or you may be able to
use the utility <a href="utilities.htm#wee_device_utility"><span class="code">wee_device</span>.</a>
</li>
<li>Launch the <span class="code">weewxd</span> program. It can be run either as a <a
href="#Running_as_a_daemon">daemon</a>, or <a href="#Running_directly">directly from the command
line</a>.
</li>
<li>Tune the installation. Typically this is done by changing settings in the <a href="#weewxconf"><span
class="code">weewx.conf</span></a> configuration file. For example, you might want to <a
href="#station_registry">register your station</a>, so it shows up on a world-wide map of WeeWX
installations.
</li>
<li><a href="customizing.htm">Customize</a> the installation. This is an advanced topic, which allows you to
shape WeeWX exactly to your liking!
</li>
</ol>
<h2 id="installation_methods">Installation methods</h2>
<p>
WeeWX can be installed from a DEB (Debian) or RPM (Redhat, SUSE) package, or it can be installed using the
standard Python utility <span class='code'>setup.py</span>.
</p>
<p>
The DEB or RPM package approach is simpler and is the recommended method for beginners. However, it requires
root privileges, and will install the bits and pieces of WeeWX in standard operating system locations across
the file system instead of in a single directory. The net effect is that configuration files, templates, and
code will all be installed in separate locations, most of which will require root privileges to modify.
</p>
<p>
Installation using <span class="code">setup.py</span> is the recommended method for those who plan to write
custom services and reports for WeeWX. It will put everything in a single directory, specified by the
parameter <span class='code'>home</span> in the <span class='code'>setup.cfg</span> file, making it easier
to modify WeeWX. This file is not used by the other installation methods. If the user installing WeeWX has
permission to write to the directory, root privileges will not be required to install, run, or modify WeeWX.
</p>
<h2><a href='debian.htm'>Installing from DEB package</a></h2>
<p>For Debian, Ubuntu, Mint, and Raspbian operating systems, follow the <a href='debian.htm'>instructions for
Debian-based systems</a>.
</p>
<h2><a href='redhat.htm'>Installing from Redhat RPM package</a></h2>
<p>For Redhat, CentOS, Fedora operating systems, follow the the <a href='redhat.htm'>instructions for
Redhat-based systems</a>.
</p>
<h2><a href='suse.htm'>Installing from SuSE RPM package</a></h2>
<p>For SuSE and OpenSUSE, follow the <a href='suse.htm'>instructions for SuSE-based systems</a>.</p>
<h2><a href='macos.htm'>Installing on MacOS</a></h2>
<p>For MacOS, follow the <a href='macos.htm'>instructions for MacOS systems</a>.</p>
<h2><a href='setup.htm'>Installing using the Python tool setup.py</a></h2>
<p>For all other operating systems, follow the <a href='setup.htm'><span class="code">setup.py</span>
instructions</a>. This method can also be used on Debian-, Redhat-, and SUSE-based operating systems as
well, and may be a better choice if you intend to heavily customize WeeWX.
</p>
<h2 id="Where_to_find_things">Where to find things</h2>
<p>
Here is a summary of the layout for the different install methods, along with the symbolic names used for
each role. These names are used throughout the documentation.
</p>
<div id='dir-layout-table' class='tabs' style='padding-top:1em'>
<div id='layout-tab-deb' class='tab selected' onclick="showtab('layout','deb')">
Debian <img src='images/logo-debian.png' class='thumbnail' alt="Debian logo"/> <img
src='images/logo-ubuntu.png' class='thumbnail' alt="Ubuntu logo"/> <img src='images/logo-mint.png'
class='thumbnail'
alt="Mint logo"/>
</div>
<div id='layout-tab-rpm' class='tab' onclick="showtab('layout','rpm')">
Redhat/SUSE <img src='images/logo-redhat.png' class='thumbnail' alt="Redhat logo"/> <img
src='images/logo-centos.png' class='thumbnail' alt="Centos logo"/> <img src='images/logo-fedora.png'
class='thumbnail'
alt="Fedora logo"/> <img
src='images/logo-suse.png' class='thumbnail' alt="SUSE logo"/>
</div>
<div id='layout-tab-macos' class='tab' onclick="showtab('layout','macos')">macos <img
src='images/logo-apple.png' class='thumbnail' alt="Apple logo"/>
</div>
<div id='layout-tab-setup' class='tab' onclick="showtab('layout','setup')">setup.py</div>
</div>
<div id='layout' style='clear:both; width: 80%;'>
<div id='layout-deb'>
<table class='locations'>
<tr class='selected'>
<td colspan='3' class='locations_banner'>Application layout for install using DEB package</td>
</tr>
<tr class="first_row">
<td>Role</td>
<td>Symbolic Name</td>
<td>Nominal Location</td>
</tr>
<tr>
<td>WeeWX root directory</td>
<td class="symcode">WEEWX_ROOT</td>
<td class="tty">/</td>
</tr>
<tr>
<td>Executables</td>
<td class="symcode">BIN_ROOT</td>
<td class='tty'>/usr/share/weewx/</td>
</tr>
<tr>
<td>Configuration directory</td>
<td class="symcode">CONFIG_ROOT</td>
<td class='tty'>/etc/weewx/</td>
</tr>
<tr>
<td>Skins and templates</td>
<td class="symcode">SKIN_ROOT</td>
<td class='tty'>/etc/weewx/skins/</td>
</tr>
<tr>
<td>SQLite databases</td>
<td class="symcode">SQLITE_ROOT</td>
<td class='tty'>/var/lib/weewx/</td>
</tr>
<tr>
<td>Web pages and images</td>
<td class="symcode">HTML_ROOT</td>
<td class='tty'>/var/www/html/weewx/</td>
</tr>
<tr>
<td>Documentation</td>
<td class="symcode">DOC_ROOT</td>
<td class='tty'>/usr/share/doc/weewx/</td>
</tr>
<tr>
<td>Examples</td>
<td class="symcode">EXAMPLE_ROOT</td>
<td class='tty'>/usr/share/doc/weewx/examples/</td>
</tr>
<tr>
<td>PID file</td>
<td class="symcode"></td>
<td class='tty'>/var/run/weewx.pid</td>
</tr>
<tr>
<td>Log file</td>
<td class="symcode"></td>
<td class='tty'>/var/log/syslog</td>
</tr>
</table>
</div>
<div id='layout-rpm' style='display:none'>
<table class='locations'>
<tr class='selected'>
<td colspan='3' class='locations_banner'>Application layout for install using RPM package</td>
</tr>
<tr class="first_row">
<td>Role</td>
<td>Symbolic Name</td>
<td>Nominal Location</td>
</tr>
<tr>
<td>WeeWX root directory</td>
<td class="symcode">WEEWX_ROOT</td>
<td class="tty">/</td>
</tr>
<tr>
<td>Executables</td>
<td class="symcode">BIN_ROOT</td>
<td class='tty'>/usr/share/weewx/</td>
</tr>
<tr>
<td>Configuration directory</td>
<td class="symcode">CONFIG_ROOT</td>
<td class='tty'>/etc/weewx/</td>
</tr>
<tr>
<td>Skins and templates</td>
<td class="symcode">SKIN_ROOT</td>
<td class='tty'>/etc/weewx/skins/</td>
</tr>
<tr>
<td>SQLite databases</td>
<td class="symcode">SQLITE_ROOT</td>
<td class='tty'>/var/lib/weewx/</td>
</tr>
<tr>
<td>Web pages and images</td>
<td class="symcode">HTML_ROOT</td>
<td class='tty'>/var/www/html/weewx/</td>
</tr>
<tr>
<td>Documentation</td>
<td class="symcode">DOC_ROOT</td>
<td class='tty'>/usr/share/doc/weewx-x.y.z/</td>
</tr>
<tr>
<td>Examples</td>
<td class="symcode">EXAMPLE_ROOT</td>
<td class='tty'>/usr/share/doc/weewx-x.y.z/examples/</td>
</tr>
<tr>
<td>PID file</td>
<td class="symcode"></td>
<td class='tty'>/var/run/weewx.pid</td>
</tr>
<tr>
<td>Log file</td>
<td class="symcode"></td>
<td class='tty'>/var/log/messages</td>
</tr>
</table>
</div>
<div id='layout-macos' style='display:none'>
<table class='locations'>
<tr class='selected'>
<td colspan='3' class='locations_banner'>Application layout for install on MacOS
</td>
</tr>
<tr class="first_row">
<td>Role</td>
<td>Symbolic Name</td>
<td>Nominal Location</td>
</tr>
<tr>
<td>WeeWX root directory</td>
<td class="symcode">WEEWX_ROOT</td>
<td class="tty">/Users/Shared/weewx/</td>
</tr>
<tr>
<td>Executables</td>
<td class="symcode">BIN_ROOT</td>
<td class='tty'>/Users/Shared/weewx/bin/</td>
</tr>
<tr>
<td>Configuration directory</td>
<td class="symcode">CONFIG_ROOT</td>
<td class='tty'>/Users/Shared/weewx/</td>
</tr>
<tr>
<td>Skins and templates</td>
<td class="symcode">SKIN_ROOT</td>
<td class='tty'>/Users/Shared/weewx/skins/</td>
</tr>
<tr>
<td>SQLite databases</td>
<td class="symcode">SQLITE_ROOT</td>
<td class='tty'>/Users/Shared/weewx/archive/</td>
</tr>
<tr>
<td>Web pages and images</td>
<td class="symcode">HTML_ROOT</td>
<td class='tty'>/Users/Shared/weewx/public_html/</td>
</tr>
<tr>
<td>Documentation</td>
<td class="symcode">DOC_ROOT</td>
<td class='tty'>/Users/Shared/weewx/docs/</td>
</tr>
<tr>
<td>Examples</td>
<td class="symcode">EXAMPLE_ROOT</td>
<td class='tty'>/Users/Shared/weewx/examples/</td>
</tr>
<tr>
<td>PID file</td>
<td class="symcode"></td>
<td class='tty'>/var/run/weewx.pid</td>
</tr>
<tr>
<td>Log file</td>
<td class="symcode"></td>
<td class='tty'>/var/log/system.log</td>
</tr>
</table>
</div>
<div id='layout-setup' style='display:none'>
<table class='locations'>
<tr class='selected'>
<td colspan='3' class='locations_banner'>Application layout for install using <span
class='code'>setup.py</span>
</td>
</tr>
<tr class="first_row">
<td>Role</td>
<td>Symbolic Name</td>
<td>Nominal Location</td>
</tr>
<tr>
<td>WeeWX root directory</td>
<td class="symcode">WEEWX_ROOT</td>
<td class="tty">/home/weewx/</td>
</tr>
<tr>
<td>Executables</td>
<td class="symcode">BIN_ROOT</td>
<td class='tty'>/home/weewx/bin/</td>
</tr>
<tr>
<td>Configuration directory</td>
<td class="symcode">CONFIG_ROOT</td>
<td class='tty'>/home/weewx/</td>
</tr>
<tr>
<td>Skins and templates</td>
<td class="symcode">SKIN_ROOT</td>
<td class='tty'>/home/weewx/skins/</td>
</tr>
<tr>
<td>SQLite databases</td>
<td class="symcode">SQLITE_ROOT</td>
<td class='tty'>/home/weewx/archive/</td>
</tr>
<tr>
<td>Web pages and images</td>
<td class="symcode">HTML_ROOT</td>
<td class='tty'>/home/weewx/public_html/</td>
</tr>
<tr>
<td>Documentation</td>
<td class="symcode">DOC_ROOT</td>
<td class='tty'>/home/weewx/docs/</td>
</tr>
<tr>
<td>Examples</td>
<td class="symcode">EXAMPLE_ROOT</td>
<td class='tty'>/home/weewx/examples/</td>
</tr>
<tr>
<td>PID file</td>
<td class="symcode"></td>
<td class='tty'>/var/run/weewx.pid</td>
</tr>
<tr>
<td>Log file</td>
<td class="symcode"></td>
<td class='tty'>/var/log/syslog</td>
</tr>
</table>
</div>
</div>
<!-- Moved wee_config description to utilities.htm-->
<h1 id="running">Running WeeWX</h1>
<p>WeeWX can be run either directly, or as a daemon. When first trying WeeWX, it is best to run it directly
because you will be able to see sensor output and diagnostics, as well as log messages. Once everything is
working properly, run it as a daemon.
</p>
<h2 id="Running_directly">Running directly</h2>
<p>To run WeeWX directly, invoke the main program, <span class="code">weewxd</span>, giving the configuration
file as its only parameter:
</p>
<pre class="tty cmd">sudo weewxd weewx.conf</pre>
<p>It should start by downloading any data stored in your weather station (if the station has a data logger)
into the archive database. For some stations, such as the Davis Vantage with a couple thousand records, this
could take a minute or two. I have found this process particularly slow on SuSE for some reason.
</p>
<p>WeeWX will then start monitoring live sensor data (also referrred to as 'LOOP' data), printing a short
version of the received data on standard output, about once every two seconds for a Vantage station, or
considerably longer for some other stations.
</p>
<p>You can tell a running instance of WeeWX 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>
<pre class="tty"><span class="cmd">ps -a</span> # Note the PID of the weewxd process
<span class="cmd">kill -HUP <em>pid</em></span> # Send it a HUP signal</pre>
<p>Note that this <em>only</em> rereads the configuration file. It will not reload any code.</p>
<h2 id="Running_as_a_daemon">Running as a daemon</h2>
<p>For unattended operations it is best to have WeeWX run as a daemon, started automatically when the server is
rebooted.
</p>
<p>If you use a packaged install from a DEB or RPM distribution, this is done automatically. You can ignore this
section.
</p>
<p>Start by selecting the appropriate run script. They can be found in the source or installation under <span
class="code">util/init.d/</span>.
</p>
<table class="locations" style="width:90%">
<tr>
<td style='width:30%'>Debian/Ubuntu/Mint:</td>
<td class='tty'>util/init.d/weewx.debian</td>
</tr>
<tr>
<td>Redhat/CentOS/Mint:</td>
<td class='tty'>util/init.d/weewx.redhat</td>
</tr>
<tr>
<td>SuSE:</td>
<td class='tty'>util/init.d/weewx.suse</td>
</tr>
</table>
<p>Check the chosen script to make sure the variable <span class="code">WEEWX_ROOT</span> has been set to the
proper root directory for your WeeWX installation (it should have been set to the correct value
automatically by the install process, but it is worth checking).
</p>
<p>Copy it to the proper location for your system:</p>
<table class="locations" style="width:90%">
<tr>
<td style="width: 30%">Debian/Ubuntu/Mint:</td>
<td class='tty'><span class="cmd">cp util/init.d/weewx.debian /etc/init.d/weewx</span></td>
</tr>
<tr>
<td>Redhat/CentOS/Fedora:</td>
<td class='tty'><span class="cmd">cp util/init.d/weewx.redhat /etc/rc.d/init.d/weewx</span></td>
</tr>
<tr>
<td>SuSE:</td>
<td class='tty'><span class="cmd">cp util/init.d/weewx.suse /etc/init.d/weewx</span></td>
</tr>
</table>
<p>Make sure the script is executable:</p>
<table class="locations" style="width:90%">
<tr>
<td style="width: 30%">Debian/Ubuntu/Mint:</td>
<td class='tty'><span class="cmd">chmod +x /etc/init.d/weewx</span></td>
</tr>
<tr>
<td>Redhat/CentOS/Fedora:</td>
<td class='tty'><span class="cmd">chmod +x /etc/init.d/rc.d/weewx</span></td>
</tr>
<tr>
<td>SuSE:</td>
<td class='tty'><span class="cmd">chmod +x /etc/init.d/weewx</span></td>
</tr>
</table>
<p>Create symbolic links in the run level directories:</p>
<table class="locations" style="width:90%">
<tr>
<td style="width: 30%">Debian/Ubuntu/Mint:</td>
<td class='tty'><span class="cmd">update-rc.d weewx defaults 98</span></td>
</tr>
<tr>
<td>Redhat/CentOS/Fedora:</td>
<td class='tty'><span class="cmd">chkconfig weewx on</span></td>
</tr>
<tr>
<td>SuSE:</td>
<td class='tty'><span class="cmd">/usr/lib/lsb/install_initd /etc/init.d/weewx</span></td>
</tr>
</table>
<p>WeeWX will now start automatically whenever your system is booted. You can also manually start, stop, and
restart the WeeWX daemon:
</p>
<pre class="tty cmd">sudo /etc/init.d/weewx start
sudo /etc/init.d/weewx stop
sudo /etc/init.d/weewx restart</pre>
<p>By default, the scripts are designed to have WeeWX run at run levels 2, 3, 4 and 5. Incidentally, a nice tool
for setting run levels with Debian (Ubuntu, Mint) 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 &quot;Expert&quot; mode to see the run levels.
</p>
<p>You can also tell WeeWX to reread its configuration file without stopping by using the &#39;reload&#39;
option:
</p>
<pre class="tty cmd">sudo /etc/init.d/weewx reload </pre>
<h1 id="monitoring">Monitoring WeeWX</h1>
<p>WeeWX 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>To watch the log as it is generated, use the <span class="code">tail</span> command with the <span
class="code">-f</span> option:
</p>
<p class='tty cmd'>tail -f /var/log/syslog</p>
<p>Set the debug option in <span class='code'>weewx.conf</span> to generate many more checks and output more
information. This can be useful for diagnosing problems and debugging.
</p>
<p class='tty'>debug = 1</p>
<h1 id="integrating_with_webserver">Integrating with a web server</h1>
<h2>If the server is on the same machine</h2>
<p>The reports generated by WeeWX can be served by a web server running on the same computer as WeeWX. These are
instructions for making WeeWX reports available via the Apache web server. The process is similar for other
web servers such as <span class='code'>nginx</span> or <span class='code'>lighthttpd</span>.
</p>
<ol>
<li>
<p>Install the Apache web server on the computer on which WeeWX is running. For example, on Debian
systems:
</p>
<p class='tty cmd'>sudo apt-get install apache2</p>
</li>
<li>
<p>Configure Apache to see the WeeWX reports.</p>
<ul>
<li>
<p>If WeeWX was installed from DEB or RPM package, no configuration should be necessary since
the reports are placed in the directory <span class='code'>/var/www/html/weewx</span>, which
is in the Apache DocumentRoot directory <span class='code'>/var/www/html</span></p>
</li>
<li>
<p>If WeeWX was installed using <span class='code'>setup.py</span>, you must tell Apache where
to find the WeeWX reports. One method is to install an Apache configuration snippet:
</p>
<pre class='tty cmd'>sudo cp util/apache/conf.d/weewx.conf /etc/apache2/conf.d</pre>
<p>Be sure that the path in the Apache configuration snippet matches the <span class='code'>HTML_ROOT</span>
defined in the WeeWX configuration file. For example, the path for a default <span
class='code'>setup.py</span> installation would look like this:
</p>
<pre class='tty'>Alias /weewx <span class="highlight">/home/weewx/public_html</span>
&lt;Directory <span class="highlight">/home/weewx/public_html</span>&gt;
Options FollowSymlinks
AllowOverride None
&lt;/Directory&gt;</pre>
<p>Restart Apache to make the changes happen:</p>
<pre class='tty cmd'>sudo /etc/init.d/apache2 restart</pre>
</li>
</ul>
</li>
<li>
<p>Open the WeeWX URL in a web browser:</p>
<p class='tty'>http://localhost/weewx</p>
</li>
</ol>
<h2>If the server is on a different machine</h2>
<p>Use FTP or RSYNC to transfer the files generated by WeeWX to your remote server. In WeeWX, FTP and RSYNC are
implemented as reports. They are configured in the <span class="code">[StdReport]</span> section of the
WeeWX configuration file.
</p>
<p>For example, the following configuration would use RSYNC to copy the html and images files from the standard
report to a folder <span class="code">/var/www/html/weewx</span> on the server <span class="code">wx.example.com</span>:
</p>
<pre class='tty'>[StdReport]
[[RSYNC]]
skin = Rsync
server = wx.example.com
path = /var/www/html/weewx
user = wxuser</pre>
<p>The following configuration would use FTP to copy the html and images:</p>
<pre class='tty'>[StdReport]
[[FTP]]
skin = Ftp
server = wx.example.com
path = /var/www/html/weewx
user = wxuser
password = wxpass</pre>
<p>See the documentation for the <a href="#config_FTP"><span class="code">[[FTP]]</span></a> and <a
href="#config_RSYNC"><span class="code">[[RSYNC]]</span></a> sections of the configuration file <span
class="code">weewx.conf</span> for details and options.
</p>
<h1 id="backup">Making backups</h1>
<p>
To backup a WeeWX installation, you will need to make a copy of
</p>
<ul>
<li>configuration information;</li>
<li>skins and templates;</li>
<li>any custom code or extensions you have installed;</li>
<li>the WeeWX database.</li>
</ul>
<p>
It is not necessary to backup the generated images, HTML files, or NOAA reports since WeeWX will easily
create these again.
</p>
<p>Individual instructions follow.</p>
<h2>Configuration</h2>
<p>
Save the <span class='code'>weewx.conf</span> file.
</p>
<table class="locations" style="width:70%">
<tr>
<td style="width: 30%">setup.py:</td>
<td class='tty'>/home/weewx/weewx.conf</td>
</tr>
<tr>
<td>DEB/RPM:</td>
<td class='tty'>/etc/weewx/weewx.conf</td>
</tr>
</table>
<h2>Skins and templates</h2>
<p>
Save the contents of the skins directory if you have modified the default skin or if you have added any new
skins or template files.
</p>
<table class="locations" style="width:70%">
<tr>
<td style="width: 30%">setup.py:</td>
<td class='tty'>/home/weewx/skins</td>
</tr>
<tr>
<td>DEB/RPM:</td>
<td class='tty'>/etc/weewx/skins</td>
</tr>
</table>
<h2>Custom code or extensions</h2>
<p>
Save the contents of the <span class='code'>user</span> directory if you have modified the database schema
or added any extensions. If the extensions save data to a database you should backup those databases as
well.
</p>
<table class="locations" style="width:70%">
<tr>
<td style="width: 30%">setup.py:</td>
<td class='tty'>/home/weewx/bin/user</td>
</tr>
<tr>
<td>DEB/RPM:</td>
<td class='tty'>/usr/share/weewx/user</td>
</tr>
</table>
<h2>Database</h2>
<p>
Finally, you will need to backup the database.
</p>
<p>
For a SQLite configuration, make a copy of the <span class='code'>weewx.sdb</span> file.
</p>
<table class="locations" style="width:70%">
<tr>
<td style="width: 30%">setup.py:</td>
<td class='tty'>/home/weewx/archive/weewx.sdb</td>
</tr>
<tr>
<td>DEB/RPM:</td>
<td class='tty'>/var/lib/weewx/weewx.sdb</td>
</tr>
</table>
<p class="note">
Do not make the copy of the SQLite database while in the middle of a transaction! Schedule the backup for
immediately after an archive record is written, and then make sure the backup completes before the next
archive record arrives. Alternatively, stop WeeWX, perform the backup, then restart WeeWX.
</p>
<p>
For a MySQL configuration, save a dump of the archive database.
</p>
<h2>Restoring from backup</h2>
<p>
To restore from backup, do a fresh install of WeeWX, replace the default files with those from a backup,
then start WeeWX.
</p>
<h1 id="configuring_mysql">Configuring MySQL</h1>
<p>This section applies only to those who wish to use the MySQL database, instead of the default SQLite
database.
</p>
<p>First, verify that the MySQLdb python package is installed:</p>
<pre class="tty">python -c "import MySQLdb"</pre>
<p>If this results in an import error</p>
<pre class="tty">ImportError: No module named MySQLdb</pre>
<p>then install the MySQLdb package. For example, on Debian systems:
</p>
<pre class="tty">sudo apt-get install python-mysqldb</pre>
<p>Next, change the WeeWX configuration to use MySQL instead of SQLite. In the WeeWX configuration file, change
the <a href="#wx_binding"><span class="code">[[wx_binding]]</span></a> section to point to the MySQL
database, <span class="code">archive_mysql</span>, instead of the SQLite database <span class="code">archive_sqlite</span>.
</p>
<p> After the change, it will look something like this (change <span class="highlight">highlighted</span>):
</p>
<pre class="tty">
[[wx_binding]]
# The database should match one of the sections in [Databases]
<span class="highlight">database = archive_mysql</span>
# The name of the table within the database
table_name = archive
# The class to manage the database
manager = weewx.wxmanager.WXDaySummaryManager
# The schema defines to structure of the database contents
schema = schemas.wview.schema</pre>
<p>Assuming that you want to use the default database configuration, the <span class="code"><a
href="#Databases">[[MySQL]]</a></span> section should look something like this:
</p>
<pre class="tty"> [[MySQL]]
driver = weedb.mysql
host = localhost
user = weewx
password = weewx
</pre>
<p>This assumes user <span class="code">weewx</span> has the password <span class="code">weewx</span>. Adjust as
necessary.
</p>
<p>You will need to give the necessary permissions for the database <span class="code">weewx</span> to whatever
MySQL user you choose, by default, user <span class="code">weewx</span>. Here are the necessary minimum
permissions:
</p>
<pre class="tty">mysql&gt; <span class="cmd">CREATE USER 'weewx'@'localhost' IDENTIFIED BY 'weewx';</span>
mysql&gt; <span class="cmd">GRANT select, update, create, delete, insert, drop ON weewx.* TO weewx@localhost;</span></pre>
<h1 id="wview_compatibility">Compatibility with <span class="code">wview</span></h1>
<h2>sqlite3</h2>
<p>The SQLite archive database used by WeeWX (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.
</p>
<p>If you have data from <span class='code'>wview</span>, you can 'import' them into WeeWX by simply copying the
SQLite database file. Assuming that the <span class='code'>wview</span> data are in file <span class='code'>/var/wview/archive/wview-archive.sdb</span>,
</p>
<pre class='tty cmd'>sudo /etc/init.d/weewx stop
cd <span class="symcode">SQLITE_ROOT</span>
mv weewx.sdb weewx.sdb.bak
cp /var/wview/archive/wview-archive.sdb weewx.sdb
sudo /etc/init.d/weewx start</pre>
<p>
Internally, within the <span class="code">weewx.sdb</span> database, WeeWX also maintains a "daily summary"
of all the statistics. This is done for performance reasons. The daily summary will automatically be built
on the first startup. This could take a few minutes if the <span class='code'>wview</span> archive contains
more than a month or two of data.
</p>
<p>
On my modest 500 MHz <a href="http://www.fit-pc.com/">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.
</p>
<h2>MySQL</h2>
<p>The MySQL archive database used by wview is "almost" compatible with WeeWX. The one difference is that in
wview, the column <span class="code">interval</span> is named <span class="code">arcInt</span> (presumably
because <span class="code">interval</span> is a keyword in MySQL, although it can still be used by
surrounding the word with backquotes).
</p>
<p>To change the column name to what WeeWX uses, namely <span class="code">interval</span>, use the utility
<span class="code">mysql</span> and issue the command:
</p>
<pre class="tty">mysql> <span class="cmd">ALTER TABLE <em>your-wview-archive-name</em> CHANGE arcInt `interval` INTEGER NOT NULL;</span> </pre>
<p>where <span class="code"><em>your-wview-archive-name</em></span> is the name of your wview archive database.
Note that the word <span class="code">
interval</span> is surrounded by backquotes.
</p>
<p>Then in the <span class="code">[Databases]</span> section of <span class="code">weewx.conf</span>, replace
the name of the database with whatever your installation of wview used <span class="code"><em>your-wview-archive-name</em></span>:
</p>
<pre class="tty">[[archive_mysql]]
database_type = MySQL
database_name = <span class="highlight"><em>your-wview-archive-name</em></span></pre>
<h1 id="weewxconf">The configuration file <span class="code">weewx.conf</span></h1>
<p>The configuration file <span class="code">weewx.conf</span> is a big text file that holds the configuration
information about your installation of WeeWX. This includes things such as:
</p>
<ul>
<li>The type of hardware you have;</li>
<li>The name of your station;</li>
<li>What kind of database to use and where is it located;</li>
<li>How to recognize out-of-range observations, <i>etc</i>.</li>
</ul>
<p class='note'>The location of <span class="code">weewx.conf</span> will depend on your installation method and
operating system. For example, if you used the <span class='code'>setup.py</span> method, then the nominal
location is <span class='code'>/home/weewx</span>, and so your configuration file will be <span
class='code'>/home/weewx/weewx.conf</span>. For other configurations, consult the <a
href="#dir-layout-table">application layout table</a> in the 'Installation methods' section.
</p>
<p class='note'>There is another type of configuration file, <span class="code">skin.conf</span>, for
presentation-specific options. It is described in the <a href="customizing.htm">Customization Guide</a>,
under the section <em> <a href="customizing.htm#standard_skin">The StdReport <span
class="code">skin.conf</span></a></em>.
</p>
<p>The following sections are the definitive guide to the many configuration options available in <span
class='code'>weewx.conf</span>. <em>They contain many more options than you are likely to need!</em> &mdash;
you can safely ignore most of them. The truly important ones, the ones you are likely to have to customize
for your station, are <span class="config_important">highlighted</span>.
</p>
<p>Default values are provided for many options, meaning that if they are not listed in the configuration file
<em>at all</em>, WeeWX will pick sensible values. When the documentation below gives a &quot;default value&quot;
this is what it means.
</p>
<p>What follows is organized by the different sections of the configuration file.</p>
<h2>General</h2>
<p>The options declared at the top are not actually part of any section.</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 in the log file.
This is strongly recommended if you are having trouble. Otherwise, set to 0. Default is 0 (no debug).
</p>
<p class="config_option">WEEWX_ROOT</p>
<p>Set to the root directory of the WeeWX file hierarchy for this station. Normally, this is set automatically
by the installation process. Required. No default.
</p>
<p class="config_option">log_success</p>
<p>If set to <span class="code">true</span>, the default will be to log a successful operation (for example, the
completion of a report, or uploading to the Weather Underground, <i>etc</i>.) to the system log. Default is
<span class="code">true</span>.
</p>
<p class="config_option">log_failure</p>
<p>If set to <span class="code">true</span>, the default will be to log an unsuccessful operation (for example,
failure to generate a report, or failure to upload to the Weather Underground, <i>etc</i>.) to the system
log. Default is <span class="code">true</span>.
</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 using FTP to send data to a web
server or when sending data to the Weather Underground. Twenty (20) seconds is reasonable. Default is 20.
</p>
<p class='config_option'>gc_interval</p>
<p>Set to how often garbage collection should be performed by the Python runtime engine. Default is every 10,800
seconds (3 hours).
</p>
<p class="config_option">loop_on_init</p>
<p>Normally, if the hardware driver fails to load, WeeWX will exit. The assumption is that there is a
configuration problem and so retries are useless. However, in some cases, drivers can fail to load for
intermittent reasons, such as a network failure. In these cases, it may be useful to have WeeWX do a retry.
Setting this option to 1 will cause WeeWX to keep retrying indefinitely.
</p>
<h2 class="config_section">[Station]</h2>
<p>This section covers options relating to your weather station setup.</p>
<p class="config_important">location</p>
<p>The station location should be a UTF-8 string that describes the geography of where your weather station is
located. Required. No default.
</p>
<pre class="tty">location = "A small ranch in Kentucky"</pre>
<p class="config_important">latitude <br/> longitude</p>
<p>The lat/lon should be set in decimal degrees, negative for southern and western hemispheres, respectively.
Required. No default.
</p>
<pre class="tty">latitude = 38.8977
longitude = -77.0366</pre>
<p class="config_option"><span class="config_important">altitude</span></p>
<p>Normally the station altitude is downloaded from your hardware, but not all stations support this. Set to the
altitude of the station and the unit used for the altitude. Example:
</p>
<pre class="tty">altitude = 700, foot</pre>
<p>An example in meters:</p>
<pre class="tty">altitude = 220, meter</pre>
<p class="config_important">station_type</p>
<p>Set to the type of hardware you are using.</p>
<pre class="tty">station_type = Simulator</pre>
<p>Whatever option you choose, you <strong>must have a matching section</strong> in your configuration file. For
example, if you choose <span class="code">station_type = Simulator</span>, then you will need a <span
class="code">[Simulator]</span> section. While you can do this by hand, it is tedious and error-prone.
The better way to add the needed section is by using the utility <a href="utilities.htm#wee_config_utility"><span
class="code">wee_config</span></a> with the <span class="code">--reconfigure</span> option. If the
needed section is missing, this utility will automatically inject it into the configuration file.
</p>
<p>Valid options include:</p>
<table class="indent">
<tr class="first_row">
<td>Option</td>
<td>Description</td>
</tr>
<tr>
<td class="code first_col">Simulator</td>
<td>A software weather station simulator. Useful for testing and debugging.
</td>
</tr>
<tr>
<td class="code first_col">AcuRite</td>
<td>AcuRite 5-in-1 stations with USB interface</td>
</tr>
<tr>
<td class="code first_col">CC3000</td>
<td>RainWise CC3000 data logger</td>
</tr>
<tr>
<td class="code first_col">FineOffsetUSB</td>
<td>Fine Offset 10xx, 20xx, and 30xx stations</td>
</tr>
<tr>
<td class="code first_col">TE923</td>
<td>Hideki TE923 stations</td>
</tr>
<tr>
<td class="code first_col">Ultimeter</td>
<td>PeetBros Ultimeter stations</td>
</tr>
<tr>
<td class="code first_col">Vantage</td>
<td>Davis Vantage weather stations</td>
</tr>
<tr>
<td class="code first_col">WMR100</td>
<td>Oregon Scientific WMR100 series stations</td>
</tr>
<tr>
<td class="code first_col">WMR200</td>
<td>Oregon Scientific WMR200 series stations</td>
</tr>
<tr>
<td class="code first_col">WMR300</td>
<td>Oregon Scientific WMR300 series stations</td>
</tr>
<tr>
<td class="code first_col">WMR9x8</td>
<td>Oregon Scientific WMR-918/968 series stations</td>
</tr>
<tr>
<td class="code first_col">WS1</td>
<td>Argent Data Systems WS1 stations</td>
</tr>
<tr>
<td class="code first_col">WS23xx</td>
<td>La Crosse 23xx stations</td>
</tr>
<tr>
<td class="code first_col">WS28xx</td>
<td>La Crosse 28xx stations</td>
</tr>
</table>
<p id="station_url" class="config_option"><span class="config_important">station_url</span></p>
<p>If you have a website, you may optionally specify an URL for its HTML server. It will be included in the RSS
file generated by WeeWX and, if you choose to opt into the <a href="#station_registry">station registry</a>,
it will also be included in the <a href="http://weewx.com/stations.html">map of WeeWX stations</a>.
</p>
<p>Example:</p>
<pre class="tty">station_url = http://www.mywebsite.com</pre>
<p class="config_option" id="rain_year_start">rain_year_start
</p>
<p>Normally the start of the rain year is downloaded from your hardware, but not all stations support this. Set
to the start of your rain year, for example, 10, if your rain year starts in October (as mine does). Default
is 1.
</p>
<pre class="tty">rain_year_start = 1</pre>
<p class="config_option" id="week_start">week_start</p>
<p>Start of the week. 0=Monday, 1= Tuesday, ... , 6 = Sunday. Default is 6 (Sunday)
</p>
<pre class="tty">week_start = 0</pre>
<h3 class="config_section">[Simulator]</h3>
<p>This section is for options relating to the software weather station simulator that comes with WeeWX.</p>
<p class="config_option">loop_interval</p>
<p>The time (in seconds) between emitting loop packets. Default is 2.5</p>
<p class="config_option">mode</p>
<p>One of either <span class='code'>simulator</span> or <span class='code'>generator</span>. Default is <span
class='code'>simulator</span>.
</p>
<table class="indent">
<tr>
<td class="code">simulator</td>
<td>Real-time simulator. It will sleep between emitting packets.</td>
</tr>
<tr>
<td class="code">generator</td>
<td>Emit packets as fast as it can. Useful for testing.</td>
</tr>
</table>
<p class="config_option">start</p>
<p>The local start time for the generator in the format <span class="code">YYYY-mm-ddTHH:MM</span>. An example
would be <span class="code">2012-03-30T18:30</span>. This would code 30-March-2012, at 6:30pm, local time.
Optional. Default is the present time.
</p>
<h3 class="config_section">[AcuRite]</h3>
<p>This section is for options relating to the AcuRite 5-in-1 series of weather stations with USB connectors.
</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, "AcuRite 01035", "AcuRite 01036", or "02032C"</p>
<p class="config_option">use_constants</p>
<p>Some stations (01035, 01036) use the HP038 sensor, which contains constants that define how the pressure and
temperature should be interpreted. Other stations (02032, 02064) use the MS5607 sensor, which requires a
different calculation to determine the pressure and temperature from the sensor. When <span class='code'>use_constants</span>
is <span class='code'>True</span>, the driver will use the constants to determine which type of sensor is in
the station and will adjust the calculation accordingly. A value of False causes the driver to use a linear
approximation, regardless of the type of sensors. The default is True.
</p>
<h3 class="config_section">[CC3000]</h3>
<p>This section is for options relating to the RainWise Mark III weather stations and CC3000 data logger.</p>
<p class="config_important">port</p>
<p>The serial port, e.g., <span class='code'>/dev/ttyS0</span>. When using a USB-Serial converter, the port will
be something like <span class='code'>/dev/ttyUSB0</span>. Default is <span class='code'>/dev/ttyUSB0</span>
</p>
<p class='config_option'>polling_interval</p>
<p>The <span class="code">polling_interval</span> determines how often WeeWX will query the station for data.
The default is 1 second.
</p>
<p class="config_option">sensor_map</p>
<p>This option defines the mapping between temperature values in the database and the remote sensors. Two
additional temperature sensors are supported.
</p>
<p>For example, this would associate extraTemp1 with the second optional temperature sensor:
</p>
<pre class='tty'>[[sensor_map]]
extraTemp1 = TEMP 2</pre>
<p>See the <a href="hardware.htm#cc3000_data">Hardware Guide</a> for a complete listing of sensor names and the
default database fields for each sensor.
</p>
<h3 class="config_section">[FineOffsetUSB]</h3>
<p>This section is for options relating to the Fine Offset series of weather stations with USB connectors.</p>
<p class="warning">The following settings are <strong>highly</strong> recommended for Fine Offset stations.
Using hardware record generation or adaptive polling is more likely to cause USB communication failure.
Using hardware record generation will cause delays in report generation.
</p>
<pre class='tty'>
[FineOffsetUSB]
polling_mode = PERIODIC
polling_interval = 60
[StdArchive]
record_generation = software</pre>
<p class="config_important">model</p>
<p>Set to the station model. For example, WH1080, WS2080, WH3081, etc.</p>
<p class='config_option'>polling_mode</p>
<p>One of <span class='code'>PERIODIC</span> or <span class='code'>ADAPTIVE</span>. In <span class='code'>PERIODIC</span>
mode, WeeWX queries the console at regular intervals determined by the <span
class='code'>polling_interval</span>. In <span class='code'>ADAPTIVE</span> mode, WeeWX attempts to
query the console at times when it is not reading data from the sensors or writing data to memory. See the
section <a href="hardware.htm#polling_mode_and_the_polling_interval"> Polling Mode and interval</a> in the
Hardware Guide for more details. The default is <span class='code'>PERIODIC</span>.
</p>
<p class='config_option'>polling_interval</p>
<p>The frequency, in seconds, at which WeeWX will poll the console for data. Default is 60. This setting applies
only when the <span class='code'>polling_mode</span> is <span class='code'>PERIODIC</span>.
</p>
<p class='config_option'>data_format</p>
<p>There are two classes of hardware, the 10xx/20xx consoles and the 30xx consoles. Unlike the 10xx/20xx
consoles, the 30xx consoles record luminosity and UV, so they have a different data format. Use the <span
class='code'>data_format</span> to indicate which type of hardware you have. Possible values are <span
class='code'>1080</span> (for the 10xx and 20xx consoles) and <span class='code'>3080</span> (for the
30xx consoles). Default is <span class='code'>1080</span>.
</p>
<h3 class="config_section">[TE923]</h3>
<p>This section is for options relating to the Hideki TE923 series of weather stations.</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, Meade TE923W or TFA Nexus. Default is "TE923".</p>
<p class="config_option">sensor_map</p>
<p>This option defines the mapping between temperature/humidity values in the database and the remote sensors.
Up to 5 remote sensors are supported. A switch on each sensor determines which of 5 channels that sensor
will use. For example, if the switch on the sensor is set to 3, the temperature from that sensor will be t_3
and the humidity from that sensor will be h_3.
</p>
<p>For example, this would associate outTemp and outHumidity with sensor 4:
</p>
<pre class='tty'>[[sensor_map]]
outTemp = t_4
outHumidity = h_4</pre>
<p>See the <a href="hardware.htm#te923_data">Hardware Guide</a> for a complete listing of sensor names and the
default database fields for each sensor.
</p>
<h3 class="config_section">[Ultimeter]</h3>
<p>This section is for options relating to the PeetBros Ultimeter weather stations.</p>
<p class="config_important">port</p>
<p>The serial port, e.g., <span class='code'>/dev/ttyS0</span>. When using a USB-Serial converter, the port will
be something like <span class='code'>/dev/ttyUSB0</span>. Default is <span class='code'>/dev/ttyUSB0</span>
</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, Ultimeter 2000 or Ultimeter 800. Default is "Ultimeter".</p>
<h3 class="config_section">[Vantage]</h3>
<p>This section is for options relating to the Davis Vantage series of hardware (<em>VantagePro,
VantagePro2</em> or <em>VantageVue</em>).
</p>
<p class="config_important">type</p>
<p>Set to either <span class="code">serial</span>, for a serial or USB connection to the VantagePro (by far the
most common), or to <span class="code">ethernet</span> for the WeatherLinkIP. No default.
</p>
<p class="config_important">port</p>
<p>If you chose <span class="code">serial</span>, for <span class='code'>type</span>, then set to the serial
port name used by the station. For example, <span class="code">/dev/ttyUSB0</span> is a common location for
USB ports, <span class="code">/dev/ttyS0</span> for serial ports. Otherwise, not required. No default.
</p>
<p class="config_important">host</p>
<p>If you chose <span class="code">ethernet</span>, then specify either the IP address (<em>e.g.</em>, <span
class="code">192.168.0.1</span>) or hostname (<em>e.g.</em>, <span class="code">console.mydomain.com</span>)
to the console. Otherwise, not required. No default.
</p>
<p class="config_option">baudrate</p>
<p>Set to the baudrate of the station. The default is 19200.</p>
<p class="config_option">tcp_port</p>
<p>The port where WeatherLinkIP will be listening. Default is 22222.
</p>
<p class="config_option">tcp_send_delay</p>
<p>How long to block after sending a socket packet to the WeatherLinkIP. Default is 1 second.</p>
<p class="config_option">iss_id</p>
<p>Set to the ID number of the Integrated Sensor Suite (ISS). This is used in the formula to calculate reception
quality for wireless stations. Default is 1.
</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. 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>
<h3 class="config_section">[WMR100]</h3>
<p>This section is for options relating to the Oregon Scientific WMR100 series of weather stations with USB
connectors.
</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, WMR100 or WMRS200.</p>
<p class="config_option">sensor_map</p>
<p>This option defines the mapping between observations from remote sensors and the fields in the database.
</p>
<p>For example, this would associate extraTemp1 with the remote T/H sensor on channel 5:
</p>
<pre class='tty'>[[sensor_map]]
extraTemp1 = temperature_5</pre>
<p>See the <a href="hardware.htm#wmr100_data">Hardware Guide</a> for a complete listing of sensor names and the
default database fields for each sensor.
</p>
<h3 class="config_section">[WMR200]</h3>
<p>This section is for options relating to the Oregon Scientific WMR200 series of weather stations with USB
connectors.
</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, WMR200 or WMR200A.</p>
<p class="config_option">use_pc_time</p>
<p>If True, use the computer time, otherwise use the station time. Default is True.</p>
<p class="config_option">archive_interval</p>
<p>Set the wmr200 archive interval in seconds. Default is 60 seconds.</p>
<p>The wmr200 hardware records archive data at an immutable rate of 60 seconds. This field may be set to a
higher value enabling the WeeWX engine to coalesce live data packets. However, when the wmr200 is not
connected to a system via USB or if the WeeWX software is not running, the wmr200 console will continue to
store weather data in onboard console memory at a fixed rate of 60 seconds.
</p>
<p class="config_option">erase_archive</p>
<p>If True, erase onboard console memory archive on startup. Default is False.</p>
<p class="config_option">archive_startup</p>
<p>When retrieving archive data packets from the wmr200 onboard console memory, there is no explicit indication
that all the data has been drained. This field specifies when to transition from archive mode to live mode.
This transition occurs when no archive packets are detected within this time interval. Default is 120
seconds.
</p>
<p class="config_option">archive_threshold</p>
<p>Occasionally when retrieving archive packets from the wmr200 onboard memory a stale data packet will be
detected. The archive packets are presented in sequential order typically timestamped 60 seconds apart.
However, there is no guarantee the archive packets are exactly 60 seconds apart. Should an incoming archive
data packet timestamp exceed the previous archive data packet one by the amount in this field it will be
dropped. Default is 1512000 seconds (1 week).
</p>
<p class="config_option">sensor_status</p>
<p>If True, emit sensor faults and failures to log. Default is True.</p>
<p class="config_option">sensor_map</p>
<p>This option defines the mapping between observations from remote sensors and the fields in the database.
</p>
<p>For example, this would associate extraTemp1 with the remote T/H sensor on channel 5:
</p>
<pre class='tty'>[[sensor_map]]
extraTemp1 = temperature_5</pre>
<p>See the <a href="hardware.htm#wmr200_data">Hardware Guide</a> for a complete listing of sensor names and the
default database fields for each sensor.
</p>
<h3 class="config_section">[WMR300]</h3>
<p>This section is for options relating to the Oregon Scientific WMR300 series of weather stations with USB
connectors.
</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, WMR300 or WMR300A.</p>
<p class="config_option">sensor_map</p>
<p>This option defines the mapping between temperature/humidity values in the database and the remote sensors.
Up to 8 remote sensors are supported.
</p>
<p>For example, this would associate outTemp and outHumidity with sensor 4:
</p>
<pre class='tty'>[[sensor_map]]
outTemp = temperature_4
outHumidity = humidity_4</pre>
<p>See the <a href="hardware.htm#wmr300_data">Hardware Guide</a> for a complete listing of sensor names and the
default database fields for each sensor.
</p>
<h3 class="config_section">[WMR9x8]</h3>
<p>This section is for options relating to the Oregon Scientific WMR-918/968 series of weather stations with
serial connectors.
</p>
<p class="config_important">type</p>
<p>For the moment, only <span class="code">serial</span> is supported.</p>
<p class="config_important">port</p>
<p>Along with the <span class="code">serial</span> option above, you must set the serial port name used by the
station. For example, <span class="code">/dev/ttyUSB0</span> is a common location for USB ports, <span
class="code">/dev/ttyS0</span> for serial ports. No default.
</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, WMR968 or WMR918.</p>
<p class="config_option">sensor_map</p>
<p>This option defines the mapping between observations from remote sensors and the fields in the database.
</p>
<p>For example, this would associate extraTemp1 with the remote T/H sensor on channel 5:
</p>
<pre class='tty'>[[sensor_map]]
extraTemp1 = temperature_5
extraHumid1 = humidity_5</pre>
<p>See the <a href="hardware.htm#wmr9x8_data">Hardware Guide</a> for a complete listing of sensor names and the
default database fields for each sensor.
</p>
<h3 class="config_section">[WS1]</h3>
<p>This section is for options relating to the Argent Data Systems WS1 weather stations.</p>
<p class="config_important">port</p>
<p>The serial port, e.g., <span class='code'>/dev/ttyS0</span>. When using a USB-Serial converter, the port will
be something like <span class='code'>/dev/ttyUSB0</span>. Default is <span class='code'>/dev/ttyUSB0</span>
</p>
<p class='config_option'>polling_interval</p>
<p>The <span class="code">polling_interval</span> determines how often WeeWX will query the station for data.
The default is 1 second.
</p>
<h3 class="config_section">[WS23xx]</h3>
<p>This section is for options relating to the La Crosse WS-23xx series of weather stations.</p>
<p class="config_important">port</p>
<p>The serial port, e.g., <span class='code'>/dev/ttyS0</span>. When using a USB-Serial converter, the port will
be something like <span class='code'>/dev/ttyUSB0</span>. Default is <span class='code'>/dev/ttyUSB0</span>
</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, WS-2315, LaCrosse WS2317, etc. Default is "LaCrosse WS23xx".</p>
<p class='config_option'>polling_interval</p>
<p>The <span class="code">polling_interval</span> determines how often WeeWX will query the station for data. If
no <span class="code">polling_interval</span> is specified (the default), WeeWX will automatically use a
polling interval based on the type of connection between the station and the sensors (wired or wireless).
When connected with a wire, the console updates sensor data every 8 seconds. When connected wirelessly, the
console updates from 16 to 128 seconds, depending on sensor activity.
</p>
<h3 class='config_section'>[WS28xx]</h3>
<p>This section is for options relating to the La Crosse WS-28xx series of weather stations.</p>
<p class="config_important">transceiver_frequency</p>
<p>Radio frequency to use between USB transceiver and console. Specify either US or EU. US uses 915 MHz, EU uses
868.3 MHz. Default is US.
</p>
<p class="config_important">model</p>
<p>Set to the station model. For example, LaCrosse WS2810, TFA Primus, etc. Default is "LaCrosse WS28xx".</p>
<h2 class="config_section">[StdRESTful]</h2>
<p>This section is for configuring the <span class="code">StdRESTful</span> services, which upload to simple <a
href="https://en.wikipedia.org/wiki/Representational_State_Transfer">RESTful</a> servers such as the <a
href="https://www.wunderground.com/">Weather Underground</a>, <a href="https://www.pwsweather.com/">PWSweather.com</a>,
or <a href="http://www.wxqa.com/">CWOP</a>.
</p>
<h3 class="config_section" id="station_registry">[[StationRegistry]]</h3>
<p> A registry of WeeWX weather stations is maintained at <span class="code">weewx.com</span>. Stations are
displayed on a map and a list at <a href="http://weewx.com/stations.html">http://weewx.com/stations.html</a>
</p>
<p>How does the registry work? Individual weather stations periodically contact the registry. Each station
provides a URL to identify itself, plus other information such as the station type and WeeWX version. No
personal information, nor any meteorological data, is sent.
</p>
<p>To add your station to this list, you must do two things:</p>
<ol>
<li>Enable the StationRegistry in <span class="code">weewx.conf</span> by setting the option <span
class="code">register_this_station</span> to <span class="code">True</span>. Your station will contact
the registry once per week. If your station does not contact the registry for about a month, it will be
removed from the list.
</li>
<li>Provide a <span class="code">station_url</span>, either in section <a href="#station_url"><span
class='code'>[Station]</span></a>, or in the <span class='code'>[[StationRegistry]]</span> section.
</li>
</ol>
<p>The <span class='code'>station_url</span> is used to uniquely identify each station, so choose it carefully
before you set <span class='code'>register_this_station</span> to <span class='code'>True</span>.
</p>
<pre class="tty">[StdRestful]
[[StationRegistry]]
register_this_station = True</pre>
<p class="config_important">register_this_station</p>
<p>Set this to <span class="code">True</span> to register the weather station.</p>
<p class="config_option">description</p>
<p>
A description of the station. If no description is specified, the <span
class="config_option">location</span> from the <span class="code">[Station]</span> section will be used.
</p>
<p class="config_option">station_url</p>
<p>
The URL to the weather station. If no URL is specified, the <span class="config_option">station_url</span>
from the <span class="code">[Station]</span> section will be used.
</p>
<p class='config_option'>log_success</p>
<p>In case of success, make a note in the system log. The default is <span class='code'>True</span>.</p>
<p class='config_option'>log_failure</p>
<p>In case of failure, make a note in the system log. The default is <span class='code'>True</span>.</p>
<h3 class="config_section">[[AWEKAS]]</h3>
<p class="config_section">WeeWX can send your current data to the <a href="https://www.awekas.at/">Automatisches
Wetterkarten System</a> (AWEKAS). If you wish to do this, set the option <span class='code'>enable</span> to
<span class="code">true</span>, then set options <span class='code'>username</span> and <span class='code'>password</span>
appropriately. When you are done, it will look something like
</p>
<pre class="tty">[StdRestful]
[[AWEKAS]]
enable = true
username = joeuser
password = XXX </pre>
<p class="config_important">enable</p>
<p>
Set to <span class="code">true</span> to enable posting to AWEKAS. Optional. Default is <span class="code">false</span>.
</p>
<p class="config_important">username</p>
<p>Set to your AWEKAS username (<i>e.g.</i>, <span class="code">joeuser</span>). Required.</p>
<p class="config_important">password</p>
<p>Set to your AWEKAS password. Required.</p>
<p class="config_option">language</p>
<p>Set to your preferred language. Default is <span class='code'>en</span>.</p>
<p class='config_option'>log_success</p>
<p>In case of success, make a note in the system log. The default is <span class='code'>True</span>.</p>
<p class='config_option'>log_failure</p>
<p>In case of failure, make a note in the system log. The default is <span class='code'>True</span>.</p>
<p class='config_option'>retry_login</p>
<p>How long to wait in seconds before retrying a bad login. Default is 3600 seconds (one hour).</p>
<h3 class="config_section">[[CWOP]]</h3>
<p>WeeWX can send your current data to the <a href="http://www.wxqa.com/">Citizen Weather Observer Program</a>.
If you wish to do this, set the option <span class='code'>enable</span> to <span class='code'>true</span>,
then set the option <span class='code'>station</span> to your CWOP station code. If your station is an
amateur radio APRS station, you will have to set <span class="code">passcode</span> as well. When you are
done, it will look something like
</p>
<pre class="tty">[StdRestful]
[[CWOP]]
enable = true
station = CW1234
passcode = XXX # Replace with your passcode (APRS stations only)
post_interval = 600</pre>
<p class="config_important">enable</p>
<p>
Set to <span class="code">true</span> to enable posting to the CWOP. Optional. Default is <span
class="code">false</span>.
</p>
<p class="config_important">station</p>
<p>Set to your CWOP station ID (<em>e.g.</em>, <span class="code">CW1234</span>) or amateur radio callsign
(APRS). 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.
Required for APRS stations, ignored for others.
</p>
<p class="config_option">post_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 600 seconds.
</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 when WeeWX attempts a catch up, old data could be interpreted as the
current conditions. Optional. Default is 600 seconds.
</p>
<p class="config_option">server_list</p>
<p>A comma-delimited list of the servers that should be tried for uploading data. Optional. Default is: <span
class="code">cwop.aprs.net:14580, cwop.aprs.net:23</span></p>
<p class='config_option'>log_success</p>
<p>In case of success, make a note in the system log. The default is <span class='code'>True</span>.</p>
<p class='config_option'>log_failure</p>
<p>In case of failure, make a note in the system log. The default is <span class='code'>True</span>.</p>
<h3 class="config_section">[[PWSweather]]</h3>
<p>WeeWX can send your current data to the <a href="https://www.pwsweather.com/">PWSweather.com</a> service. If
you wish to do this, set the option <span class='code'>enable</span> to <span class='code'>true</span>, then
set the options <span class='code'>station</span> and <span class='code'>password</span> appropriately. When
you are done, it will look something like
</p>
<pre class="tty">[StdRestful]
[[PWSweather]]
enable = true
station = BOISE
password = XXX</pre>
<p class="config_important">enable</p>
<p>
Set to <span class="code">true</span> to enable posting to the PWSweather. Optional. Default is <span
class="code">false</span>.
</p>
<p class="config_important">station</p>
<p>Set to your PWSweather station ID (<i>e.g.</i>, <span class='code'>BOISE</span>). Required.</p>
<p class="config_important">password</p>
<p>Set to your PWSweather password. Required.</p>
<p class='config_option'>log_success</p>
<p>In case of success, make a note in the system log. The default is <span class='code'>True</span>.</p>
<p class='config_option'>log_failure</p>
<p>In case of failure, make a note in the system log. The default is <span class='code'>True</span>.</p>
<p class='config_option'>retry_login</p>
<p>How long to wait in seconds before retrying a bad login. Default is 3600 seconds (one hour).</p>
<h3 class="config_section">[[WOW]]</h3>
<p class="config_section">WeeWX can send your current data to the <a href="http://wow.metoffice.gov.uk/">British
Weather Observations Website (WOW)</a> service. If you wish to do this, set the option <span class='code'>enable</span>
to <span class="code">true</span>, then set options <span class="code">station</span> and <span
class="code">password</span> appropriately. Read <a
href="http://wow.metoffice.gov.uk/support/dataformats#automatic">Importing Weather Data into WOW</a> on
how to find your site's username and how to set the password for your site. When you are done, it will look
something like
</p>
<pre class="tty">[StdRestful]
[[WOW]]
enable = true
station = 12345678
password = XXX</pre>
<p class="config_important">enable</p>
<p>
Set to <span class="code">true</span> to enable posting to WOW. Optional. Default is <span class="code">false</span>.
</p>
<p class="config_important">station</p>
<p>Set to your WOW station ID (<i>e.g.</i>, <span class="code">12345678</span> for Pre June 1996 sites, or <span
class="code">6a571450-df53-e611-9401-0003ff5987fd</span> for later ones). Required.
</p>
<p class="config_important">password</p>
<p>Set to your WOW Authentication Key. Required. This is not the same as your WOW password but a 6 digit
numerical PIN.
</p>
<p class='config_option'>log_success</p>
<p>In case of success, make a note in the system log. The default is <span class='code'>True</span>.</p>
<p class='config_option'>log_failure</p>
<p>In case of failure, make a note in the system log. The default is <span class='code'>True</span>.</p>
<p class='config_option'>retry_login</p>
<p>How long to wait in seconds before retrying a bad login. Default is 3600 seconds (one hour).</p>
<h3 class="config_section" id="Wunderground">[[Wunderground]]</h3>
<p>
WeeWX can send your current data to the <a href="https://www.wunderground.com/">Weather Underground</a>. If
you wish to do this, set the option <span class="code">enable</span> to <span class="code">true</span>, then
set the options <span class='code'>station</span> and <span class="code">password</span> appropriately. When
you are done, it will look something like
</p>
<pre class="tty">[StdRestful]
[[Wunderground]]
enable = true
station = KCASANFRA11
password = XXX
rapidfire = False</pre>
<p class="config_important">enable</p>
<p>
Set to <span class="code">true</span> to enable posting to the Weather Underground. Optional. Default is
<span class="code">false</span>.
</p>
<p class="config_important">station</p>
<p>
Set to your Weather Underground station ID (<em>e.g.</em>, <span class="code">KCASANFRA11</span>). Required.
</p>
<p class="config_important">password</p>
<p>Set to your Weather Underground password. Required.</p>
<p class="config_option">rapidfire</p>
<p>
Set to <span class="code">True</span> to have WeeWX post using the <a
href="https://www.wunderground.com/weatherstation/rapidfirehelp.asp">Weather Underground's "Rapidfire"
protocol</a>. This will send a post to the WU site with every LOOP packet, which can be as often as every
2.5 seconds in the case of the Vantage instruments. Not all instruments support this. Optional. Default is
<span class="code">False</span>.
</p>
<p class="config_option">rtfreq</p>
<p>When <span class="config_option">rapidfire</span> is set, the <span class="code">rtfreq</span> parameter is
sent, and should correspond to "the frequency of updates in seconds". Optional. Default is <span
class="code">2.5</span></p>
<p class="config_option">archive_post</p>
<p>
This option tells WeeWX to post on every archive record, which is the normal "PWS" mode for the Weather
Underground. Because they prefer that you either use their "Rapidfire" protocol, or their PWS mode, but not
both, the default for this option is the opposite for whatever you choose above for option <span
class="code">rapidfire</span>. However, if for some reason you want to do both, then you may set both
options to <span class="code">True</span>.
</p>
<p class='config_option'>post_indoor_observations</p>
<p>In the interest of respecting your privacy, WeeWX does not post indoor temperature or humidity to the Weather
Underground unless you set this option to <span class="code">True</span>. Default is <span class="code">False</span>.
</p>
<p class='config_option'>log_success</p>
<p>In case of success, make a note in the system log. The default is <span class='code'>False</span> for
Rapidfire mode, <span class='code'>True</span> for PWS mode.
</p>
<p class='config_option'>log_failure</p>
<p>In case of failure, make a note in the system log. The default is <span class='code'>False</span> for
Rapidfire mode, <span class='code'>True</span> for PWS mode.
</p>
<p class='config_option'>retry_login</p>
<p>How long to wait in seconds before retrying a bad login. Default is 3600 seconds (one hour).</p>
<p class='config_option'>[[[Essentials]]]</p>
<p>Occasionally (but not always!) when the Weather Underground is missing a data point it will substitute the
value zero (<span class='code'>0.0</span>), thus messing up statistics and plots. For all observation types
listed in this section, the post will be skipped if that type is missing. For example,
</p>
<pre class='tty'>[[[Essentials]]]
outTemp = True</pre>
<p>would cause the post to be skipped if there is no outside temperature (observation type <span class='code'>outTemp</span>).
</p>
<h2 class="config_section" id="Reports">[StdReport]</h2>
<p>This section is for configuring the <span class="code">StdReport</span> service, which 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
sub-sections, running each report in order.
</p>
<p>WeeWX ships with the following sub-sections:</p>
<table class="indent">
<tr class="first_row">
<td>Sub-section</td>
<td>Description</td>
</tr>
<tr>
<td><span class="code">[[SeasonsReport]]</span></td>
<td>A full-featured single-page skin. Statistics and plots are revealed by button presses.</td>
</tr>
<tr>
<td><span class="code">[[SmartphoneReport]]</span></td>
<td>A skin formatted for smaller screens.</td>
</tr>
<tr>
<td><span class="code">[[MobileReport]]</span></td>
<td>A static skin formatted for very small screens.</td>
</tr>
<tr>
<td><span class="code">[[StandardReport]]</span></td>
<td>An older skin that shipped with WeeWX for many years. Requires little resources to generate and
display.
</td>
</tr>
<tr>
<td><span class="code">[[FTP]]</span></td>
<td>Not a skin, but uses the reporting machinery to FTP results to a remote webserver.</td>
</tr>
<tr>
<td><span class="code">[[RSYNC]]</span></td>
<td>Not a skin, but uses the reporting machinery to Rsync results to a remote webserver.</td>
</tr>
</table>
<p>Order matters. The reports that generate HTML and images, that is, SeasonsReport, SmartphoneReport,
MobileReport, and StandardReport, are run <em>first</em>, then the reports that move them to a webserver,
FTP and RSYNC, are run. This insures that report generation is done before the results are sent off.
</p>
<p>
Details for how to customize reports are in the section <em><a href="customizing.htm#customizing_reports">Customizing
reports</a></em>, in the <a href="customizing.htm">Customization Guide</a>.
</p>
<p class="config_option">SKIN_ROOT</p>
<p>The directory where the skins live. A relative path is relative to <span class="symcode">WEEWX_ROOT</span>.
</p>
<p class="config_option" id="HTML_ROOT">HTML_ROOT</p>
<p>The target directory for the generated files. A relative path is relative to <span
class="symcode">WEEWX_ROOT</span>. Generated files and images will be put here.
</p>
<p class="config_option">data_binding</p>
<p>
The data source to be used for the reports. It should match a binding given in section <a
href="#DataBindings"><span class="code">[DataBindings]</span></a> below. The binding can be overridden in
individual reports. Optional. Default is <span class="code">wx_binding</span>.
</p>
<p class="config_option">report_timing</p>
<p>This parameter uses a cron-like syntax that determines when a report will be run. The setting can be
overridden in individual reports, so it is possible to run each report with a different schedule. Refer to
the <em><a href="customizing.htm#customizing_gen_time">Customizing the report generation time</a></em>
section in the <a href="customizing.htm">Customization Guide</a> for details. Optional. The default value
results in each report running on each archive interval.
</p>
<h3 class="config_section" id="stock_reports">[[SeasonsReport]]<br/> [[SmartphoneReport]]<br/>
[[MobileReport]]<br/> [[StandardReport]]</h3>
<p>
These are the four reports that actually generate HTML files and plots. They all ship in the standard WeeWX
distribution. They all use US Customary units by default, but this can be changed by editing section <a
href="#Section_Defaults"><span class="code">[Defaults]</span></a>.
</p>
<p>They all have the following options in common.</p>
<p class="config_option">skin</p>
<p>
Where to find the skin. This should be a subdirectory under <span class="symcode">SKIN_ROOT</span>. Inside
the directory should be any templates used by the skin and a skin configuration file, <span class="code">skin.conf</span>.
</p>
<p class="config_important">enable</p>
<p>
Set to <span class="code">true</span> to enable the processing of this skin. Set to <span
class="code">false</span> to disable. If this option is missing, <span class="code">True</span> is assumed.
</p>
<p class="config_option">HTML_ROOT</p>
<p>Where to put the results. If not specified, the value for <a href="#HTML_ROOT"><span class="symcode">HTML_ROOT</span></a>
above will be used.
</p>
<h3 class="config_section" id="config_FTP">[[FTP]]</h3>
<p>While this &quot;report&quot; does not actually generate anything, it uses the report machinery to upload
files from directory <span class="symcode">
HTML_ROOT</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 class="config_important">enable</p>
<p>Set to <span class="code">true</span> (the default) to enable FTP. Set to <span class="code">false</span> to
disable.
</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 (<em>e.g.</em>, <span class="code">www.threefools.org</span>, 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 (<em>e.g.</em>, <span class="code">/weather</span>).
NB: some FTP servers require a leading slash (&#39;<span class="code">/</span>&#39;), some do not. Required.
No default.
</p>
<p class="config_important">secure_ftp</p>
<p>Set to <span class="code">True</span> to use FTP (FTPS) over TLS. This is an extension to the FTP protocol
that uses a Secure Socket Layer (SSL) protocol, <em>not</em> to be confused with SFTP, which uses a Secure
Socket Shell protocol. Not all FTP servers support this. In particular, the Microsoft FTP server seems to do
a poor job of it. Requires Python V2.7. Will not work with older versions of Python. Optional. Default is
<span class="code">False</span></p>
<p class="config_option">port</p>
<p>Set to the port ID of your FTP server. Default is <span class="code">21</span>.</p>
<p class="config_option">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>WeeWX 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" id="config_RSYNC">[[RSYNC]]</h3>
<p>While this &quot;report&quot; does not actually generate anything, it uses the report machinery to upload
files from directory <span class="symcode">
HTML_ROOT</span> to a remote webserver using <a href="https://rsync.samba.org/">rsync</a>. Fast,
efficient, and secure, it does an incremental update, that is, it only synchronizes those parts of a file
that have changed, saving the outgoing bandwidth of your Internet connection.
</p>
<p>
If you wish to use rsync, you must configure passwordless ssh using public/private key authentication from
the user account that WeeWX runs, to the user account on the remote machine where the files will be copied.
</p>
<p class="config_important">enable</p>
<p>Set to <span class="code">true</span> (the default) to enable rsync. Set to <span class="code">false</span>
to disable.
</p>
<p class="config_important">server</p>
<p>Set to the name of your server. This name should appear in your <span class="code">.ssh/config</span> file.
Required. No default
</p>
<p class="config_important">user</p>
<p>Set to the ssh username you use for your rsync connection to your web server. The local user that WeeWX runs
as must have <a href='https://www.tecmint.com/ssh-passwordless-login-using-ssh-keygen-in-5-easy-steps/'>
passwordless ssh</a> configured for <em>user@server</em>. 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 (<i>e.g.</i>, <span class="code">/var/www/html/weather</span>).
Make sure <span class='code'>user</span> has write privileges in this directory. Required. No default.
</p>
<p class="config_important">delete</p>
<p>Files that don't exist in the local report are removed from the remote location. <em>USE WITH CAUTION:</em>
If you make a mistake in setting the <span class="code">path</span>, this can cause unexpected files to be
deleted on the remote server. Valid values are 1 to enable and 0 to disable. Required. Default is 0.
</p>
<h2 class="config_section" id="StdConvert">[StdConvert]</h2>
<p>This section is for configuring the <span class="code">StdConvert</span> service. This service acts as a
filter, converting the unit system coming off your hardware to a target output unit system. All downstream
services, including the archiving service, will then see this unit system. Hence, your data will be stored
in the database using whatever unit system you specify here.
</p>
<p><em>Once chosen, it cannot be changed!</em> WeeWX does not allow you to mix unit systems within the
databases. You must chose a unit system and then stick with it. This means that users coming from wview
(which uses US Customary) should not change the default setting. Having said this, there is a way of
reconfiguring the database to use another unit system. See the section <a
href="customizing.htm#Changing_the_unit_system">Changing the unit system</a> in the <a
href="customizing.htm">Customization Guide</a>.
</p>
<p class='note'><strong>Note!</strong><br/> This service only affects the units used in the <em>databases</em>.
In particular, it has nothing to do with what units are displayed in plots or files. Those units are
specified in the skin configuration file, <span class="code">skin.conf</span>, as described in the <a
href="customizing.htm">Customization Guide</a>, under section <em>
<!--suppress HtmlUnknownAnchorTarget -->
<a href="customizing.htm#Changing_options">Changing options</a></em>. Because of this, unless you have a
special purpose application, there is really no good reason to change from the default, which is <span
class="code">US</span>.
</p>
<p class="warning"><strong>Warning!</strong><br/> If, despite these precautions, you do decide to change the
units of data stored in the database, be sure to read the sections <span class="code"><a
href="#StdCalibrate">[StdCalibrate]</a></span> and <span class="code"><a
href="#StdQC">[StdQC]</a></span>, and change the units there as well!
</p>
<p class="config_option" id="option_target_unit">target_unit</p>
<p>Set to either <span class="code">US</span>, <span class="code">METRICWX</span>, or <span
class="code">METRIC</span>. The difference between <span class="code">METRICWX</span>, and <span
class="code">METRIC</span> is that the former uses <span class="code">mm</span> instead of <span
class="code">cm</span> for rain, and <span class="code">m/s</span> instead of <span
class="code">km/hr</span> for wind speed. See the Appendix <a href="customizing.htm#units"> Units</a> in the
<a href="customizing.htm">Customization Guide</a> for the exact differences beween these three choices.
Default is <span class="code">US</span>.
</p>
<h2 class="config_section" id="StdCalibrate">[StdCalibrate]</h2>
<p>This section is for configuring the <span class="code">StdCalibrate</span> service. This service offers an
opportunity to correct for any calibration errors in your instruments. It is very general and flexible.
</p>
<p>Because this service is normally run after <span class="code">StdConvert</span>, the units to be used should
be the same as the target unit system chosen in <a href="#StdConvert"><span
class="code">StdConvert</span></a> above. It is also important that this service be run before the
archiving service <span class="code">StdArchive</span>, so that it is the corrected data that are stored.
</p>
<p>In a default configuration, calibrations are applied to observations from the hardware. They are not applied
to derived calculations since the <span class="code">StdWXCalculate</span> service runs after <span
class="code">StdCalibrate</span>.
</p>
<h3 class="config_section">[[Corrections]]</h3>
<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&deg;F. You could add the expression:
</p>
<p class='tty'>outTemp = outTemp - 0.2</p>
<p>Perhaps you need a linear correction around a reference temperature of 68&deg;F:
</p>
<p class='tty'>outTemp = outTemp + (outTemp-68) * 0.02</p>
<p>It is even possible to do corrections involving more than one variable. Suppose you have a temperature
sensitive barometer:
</p>
<p class='tty'>barometer = barometer + (outTemp-32) * 0.0091</p>
<p>All correction expressions are run in the order given.</p>
<p>Both LOOP data and archive data will be corrected.</p>
<p>If you are using a Davis Vantage instrument and all you require is a simple correction offset, this can also
be done in the hardware. See your manual for instructions.
</p>
<h2 class="config_section" id="StdQC">[StdQC]</h2>
<p>This section is for configuring the <span class="code">StdQC</span> service. This service offers a very
simple <em>Quality Control</em> that only checks that values are within a minimum and maximum range.
</p>
<p>Because this service is normally run after <span class="code">StdConvert</span>, the units to be used should
be the same as the target unit system chosen in <a href="#StdConvert"><span
class="code">StdConvert</span></a>. It is also important that it be run after the calibration service,
<span class="code">StdCalibrate
</span>and before the archiving service <span class="code">StdArchive</span>, so that it is the calibrated and
corrected data that are stored.
</p>
<p>In a default configuration, quality control checks are applied to observations from the hardware. They are
not applied to derived calculations since the <span class="code">StdWXCalculate</span> service runs after
the quality control.
</p>
<h3 class="config_section">[[MinMax]]</h3>
<p>In this section you list the observation types you wish to have checked, along with their minimum and maximum
values. If not specified, the units should are in <em>the same unit system as specified in section <span
class="code"><a href="#StdConvert">StdConvert</a></span></em>.
</p>
<p>For example,</p>
<pre class="tty">[[MinMax]]
outTemp = -40, 120
barometer = 28, 32.5
outHumidity = 0, 100 </pre>
<p>With <span class='code'>target_unit = US</span> (the default), if a temperature should fall outside of the
inclusive range -40 &deg;F through 120 &deg;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>You can also specify units.</p>
<p>For example,</p>
<pre class="tty">[[MinMax]]
outTemp = -40, 60, degree_C
barometer = 28, 32.5, inHg</pre>
<p>In this example, if a temperature should fall outside of the inclusive range -40 &deg;C through 60 &deg;C,
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. Since the units are specified,
these values apply no matter what the <span class='code'>target_unit</span>.
</p>
<p>Both LOOP and archive data will be checked.</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, for the VP2, there is no real point in checking wind speed.
</p>
<h2 class="config_section" id="StdWXCalculate">[StdWXCalculate]</h2>
<p>The calculation service calculates derived quantities such as <span class='code'>dewpoint</span>, <span
class='code'>windchill</span>, and <span class='code'>heatindex</span>.
</p>
<p>Some hardware provides derived quantities, others provide only raw observations. The calculation service
provides derived quantities for hardware that does not provide them, and known algorithms for hardware that
provides unreliable or antiquated calculations.
</p>
<p>The section <span class="code">[StdWXCalculate]</span> consists of a group of general options, followed by a
subsection <span class="code">[[Calculations]]</span> that specifies the calculation strategy to be used for
each derived quantity.
</p>
<p class="config_option" id="ignore_zero_wind">ignore_zero_wind</p>
<p>
Indicates whether the wind direction should be undefined when the wind speed is zero. The default value is
<span class="code">True</span>: the wind direction will be undefined when wind speed is zero.
</p>
<p>
To report the wind vane direction even when there is no wind speed, change this to False:
</p>
<pre class="tty">[StdWXCalculate]
...
ignore_zero_wind = False</pre>
<h3 class="config_section">[[Calculations]]</h3>
<p>This subsection specifies which strategy is to be used to provide values for derived variables. The service
can calculate the following values:
</p>
<ul>
<li>pressure</li>
<li>barometer</li>
<li>altimeter</li>
<li>windchill</li>
<li>heatindex</li>
<li>dewpoint</li>
<li>inDewpoint</li>
<li>rainRate</li>
<li>maxSolarRad</li>
<li>cloudbase</li>
<li>humidex</li>
<li>appTemp</li>
<li>ET</li>
<li>windrun</li>
</ul>
<p>In its default configuration, the service calculates values only if they have not already been provided by
the hardware or driver. This is the default configuration:
</p>
<pre class="tty">[StdWXCalculate]
[[Calculations]]
pressure = prefer_hardware
barometer = prefer_hardware
altimeter = prefer_hardware
windchill = prefer_hardware
heatindex = prefer_hardware
dewpoint = prefer_hardware
inDewpoint = prefer_hardware
rainRate = prefer_hardware</pre>
<p>The options for each quantity are <span class='code'>hardware</span>, <span class='code'>software</span>, or
<span class='code'>prefer_hardware</span></p>
<table class="indent">
<tr>
<td class="code">hardware</td>
<td>Never calculate the value.</td>
</tr>
<tr>
<td class="code">software</td>
<td>Always calculate the value.</td>
</tr>
<tr>
<td class="code">prefer_hardware</td>
<td>Calculate the value only if it is not provided by hardware.</td>
</tr>
</table>
<p>For example, if your weather station calculates windchill using the pre-2001 algorithm, and you prefer to
have WeeWX calculate it using a current algorithm, specify the following:
</p>
<pre class="tty">[StdWXCalculate]
...
[[Calculations]]
...
windchill = software</pre>
<h2 class="config_section" id="StdArchive">[StdArchive]</h2>
<p>This section is for configuring <span class="code">StdArchive</span>, the service that stores data in a
database.
</p>
<p class="config_option">archive_interval</p>
<p>If your station hardware supports data logging then the archive interval will be downloaded from the station.
Otherwise, you must specify it here in seconds. Optional. Default is 300 seconds.
</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" id="record_generation">record_generation</p>
<p>Set to whether records should be downloaded off the hardware (recommended), or generated in software. If set
to <span class="code">hardware</span>, then WeeWX tries to download archive records from your station.
However, not all types of stations support this, in which case WeeWX falls back to software generation. A
setting of <span class="code">hardware</span> will work for most users. A notable exception is <a
href="http://www.wxforum.net/index.php?topic=10315.0">users who have cobbled together homebrew serial
interfaces</a> for the Vantage stations that do not include memory for a logger. These users should set
this option to <span class="code">software</span>, forcing software record generation. Default is <span
class="code">hardware</span>.
</p>
<p class="config_option" id="record_augmentation">record_augmentation</p>
<p>When performing hardware record generation, this option will attempt to augment the record with any
additional observation types that it can extract out of the LOOP packets. Default is <span
class="code">True</span>.
</p>
<p class="config_option">loop_hilo</p>
<p>Set to <span class="code">True</span> to have LOOP data and archive data to be used for high / low
statistics. Set to <span class="code">False</span> to have only archive data used. If your sensor emits lots
of spiky data, setting to <span class="code">False</span> may help. Default is <span
class="code">True</span>.
</p>
<p class="config_option">data_binding</p>
<p>The data binding to be used to store the data. This should match one of the bindings in the <span
class="code">[DataBindings]</span> section, below. Optional. Default is <span class="code">wx_binding</span>.
</p>
<h2 class="config_section">[StdTimeSynch]</h2>
<p>This section is for configuring <span class="code">StdTymeSynch</span>, a service that can synchronize the
onboard clock of station with your computer. Not all weather station hardware supports this.
</p>
<p class="config_option">clock_check</p>
<p>How often to check the clock on the weather station in seconds. Default is 14,400 seconds (every 4 hours)</p>
<p class="config_option">max_drift</p>
<p>The maximum amount of clock drift to tolerate, in seconds, before resetting the clock. Default is 5.</p>
<h2 class="config_section" id="DataBindings">[DataBindings]</h2>
<p>
A "data binding" associates storage characteristics with a specific database. Each binding contains a
database from the <a href="#Databases"><span class='code'>[Databases]</span></a> section plus parameters
such as schema, table name, and mechanism for aggregating data.
</p>
<h3 class="config_section" id="wx_binding">[[wx_binding]]</h3>
<p>
This is the binding normally used for weather data. A typical <span class="code">[[wx_binding]]</span>
section looks something like this:
</p>
<pre class="tty">
[[wx_binding]]
database = archive_sqlite
table_name = archive
manager = weewx.wxmanager.WXDaySummaryManager
schema = schemas.wview.schema</pre>
<p>What follows is more detailed information about each of the binding options.</p>
<p class="config_important">database</p>
<p>
The actual database to be used &mdash; it should match one of the sections in <a href="#Databases"><span
class="code">[Databases]</span></a>. Should you decide to use a MySQL database, instead of the default
SQLite database, this is the place to change it. See the section <a href="#configuring_mysql"><em>Configuring
MySQL</em></a> for details. Required.
</p>
<p class="config_option">table_name</p>
<p>
Internally, the archive data is stored in one, long, flat table. This is the name of that table. Normally
this does not need to be changed. Optional. Default is <span class="code">archive</span>
</p>
<p class="config_option">manager</p>
<p>
The name of the class to be used to manage the table. Optional. Default is class <span class="code">weewx.wxmanager.WXDaySummaryManager</span>.
This class stores daily summaries in the database, and a few types, such as heating- and cooling-degree
days, appropriate for weather. Normally, this does not need to be changed.
</p>
<p class="config_option">schema</p>
<p>
A Python list holding the structure of the schema to be used to initialize the database. After
initialization, it is not used. Optional. Default is <span class="code">schemas.wview.schema</span>, the
schema used by the <a href="http://www.wviewweather.com">wview</a> weather system.
</p>
<h2 class="config_section" id="Databases">[Databases]</h2>
<p>This section lists actual databases. The name of each database is given in double brackets, for example,
<span class="code">[[archive_sqlite]]</span>. Each database section contains the parameters necessary to
create and manage the database. The number of parameters varies depending on the type of database.
</p>
<h3 class="config_section">[[archive_sqlite]]</h3>
<p>This definition uses the <a href="http://sqlite.org/">SQLite</a> database engine to store data. SQLite is
open-source, simple, lightweight, highly portable, and memory efficient. For most purposes it serves nicely.
</p>
<p class="config_option">database_type</p>
<p>Set to <span class="code">SQLite</span> to signal that this is a SQLite database.</p>
<p class="config_option">database_name</p>
<p>The path to the SQLite file relative to the <span class="code">SQLITE_ROOT</span> option. Default is <span
class="code">weewx.sdb</span>.
</p>
<h3 class="config_section">[[archive_mysql]]</h3>
<p>This definition uses the MySQL database engine to store data. It is free, highly-scalable, but more
complicated to administer.
</p>
<p class="config_option">database_type</p>
<p>Set to <span class="code">MySQL</span> to signal that this is a MySQL database.</p>
<p class="config_option">database_name</p>
<p>The name of the database. Default is <span class="weewx">weewx</span>. Required.</p>
<h2 class="config_section">[DatabaseTypes]</h2>
<p>This section defines defaults for the various kinds of databases.</p>
<h3 class="config_section">[[SQLite]]</h3>
<p>This section defines default values for SQLite databases. They can be overridden by individual databases.</p>
<p class="config_option">driver</p>
<p>The sqlite driver name. Required.</p>
<p class="config_option">SQLITE_ROOT</p>
<p>
The location of the directory holding the SQLite databases. For <span class="code">setup.py</span>
installations, the default is the <span class="symcode">WEEWX_ROOT</span><span class="code">/archive</span>
directory. For DEB or RPM installations, it is <span class="code">/var/lib/weewx</span>.
</p>
<p class="config_option" id='archive_timeout'>timeout</p>
<p>
When the database is accessed by multiple threads and one of those threads modifies the database, the SQLite
database is locked until that transaction is completed. The <span class='code'>timeout</span> option
specifies how long other threads should wait for the lock to go away before raising an exception. The
default is 5 seconds.
</p>
<p class='config_option'>isolation_level</p>
<p>
Set the current isolation level. See the pysqlite documentation on <a
href="http://docs.python.org/2.7/library/sqlite3.html#sqlite3.Connection.isolation_level"> isolation
levels</a> for more information. There is no reason to change this, but it is here for completeness. Default
is <span class='code'>None</span> (autocommit).
</p>
<h3 class="config_section">[[MySQL]]</h3>
<p>This section defines default values for MySQL databases. They can be overridden by individual databases.</p>
<p>
Note that if you choose the <a href="http://www.mysql.com/">MySQL</a> database, it is assumed that you know
how to administer it. In particular, you will have to set up a user with appropriate create and modify
privileges.
</p>
<p class="config_option">driver</p>
<p>The MySQL driver name. Required.</p>
<p class="config_important">host</p>
<p>
The name of the server on which the database is located. Default is <span class="code">localhost</span>.
</p>
<p class="config_important">user</p>
<p>The user name to be used to log into the server. Required.</p>
<p class="config_important">password</p>
<p>The password. Required.</p>
<p class="config_option">port</p>
<p>The port number to be used. Optional. Default is 3306.</p>
<p class="config_option">engine</p>
<p>The type of MySQL database storage engine to be used. This should not be changed without a good reason.
Default is <span class="code">INNODB</span>.
</p>
<h2 class="config_section" id="Section_Defaults">[Defaults]</h2>
<p>
This section covers a suite of "general options," which control things such as which unit system should be
used in reports, what label to be used for an observation type, and how it should be formatted. Details can
be found in <a href="customizing.htm#General_options"><em>General options</em></a> in the <a
href="customizing.htm">Customization Guide</a>.
</p>
<h2 class="config_section">[Engine]</h2>
<p>
This section is used to configure the internal service engine in WeeWX. It is for advanced customization.
Details on how to do this can be found in the section <em> <a href="customizing.htm#service_engine">Customizing
the WeeWX service engine</a></em> of the <a href="customizing.htm">Customization Guide</a>.
</p>
<h3 class="config_section">[[Services]]</h3>
<p>
Internally, WeeWX consists of many <em>services</em>, each responsible for some aspect of the program's
functionality. After an event happens, such as the arrival of a new LOOP packet, any interested service gets
a chance to do some useful work on the event. For example, a service might manipulate the packet, print it
out, store it in a database, etc. This section controls which services are loaded and in what order they get
their opportunity to do that work. Before WeeWX v2.6, this section held one, looong option called <span
class="code">service_list</span>, which held the names of all the services that should be run. Since then,
this list has been broken down into five, smaller, lists, given below. They are run in the order given
below.
</p>
<p class="config_option" id="prep_services">prep_services</p>
<p>
These services get called before any others. They are typically used to prepare the console. For example,
the service <span class="code">weewx.wxengine.StdTimeSynch</span>, which is responsible for making sure the
console's clock is up to date, is a member of this group.
</p>
<p class="config_option" id="process_services">process_services</p>
<p>Services in this group tend to process any incoming data. They typically do things like quality control, or
unit conversion, or sensor calibration.
</p>
<p class="config_option" id="archive_services">archive_services</p>
<p>Once data have been processed, services in this group archive them.</p>
<p class="config_option" id="restful_services">restful_services</p>
<p>RESTful services, such as the Weather Underground, or CWOP, are in this group. They need processed data that
have been archived, hence they are run after the preceeding groups.
</p>
<p class="config_option" id="report_services">report_services</p>
<p>The various reporting services run in this group, including the standard reporting engine.</p>
<p>For reference, here is the standard set of services that are run with the default distribution.</p>
<pre class="tty">
prep_services = weewx.engine.StdTimeSynch
process_services = weewx.engine.StdConvert, weewx.engine.StdCalibrate,\
weewx.engine.StdQC, weewx.wxservices.StdWXCalculate
archive_services = weewx.engine.StdArchive
restful_services = weewx.restx.StdStationRegistry, weewx.restx.StdWunderground,\
weewx.restx.StdPWSweather, weewx.restx.StdCWOP, weewx.restx.StdWOW,\
weewx.restx.StdAWEKAS
report_services = weewx.engine.StdPrint, weewx.engine.StdReport
</pre>
<p>If you're the type who likes to clean out your car trunk after every use it, then you may also be the type
who wants to pare this down to the bare minimum. However, this will only make a slight difference in
execution speed and memory use.
</p>
<h1 id="troubleshooting">Troubleshooting</h1>
<p>This section lists some common problems installing and running WeeWX. If you are stuck, be sure to:</p>
<ul>
<li style="margin-bottom: 1em">Set the option <span class="code">debug</span> to <span class="code">1</span>
in <span class='code'>weewx.conf</span>. This will put much more information in the log file, which can
be very useful for troubleshooting and debugging!
<p class='tty'>debug = 1</p>
</li>
<li style="margin-bottom: 1em">Look at the <a href="#monitoring">log file</a>. We are always happy to take
questions, but the first thing someone will ask is, &quot;Did you look at the log file?&quot;
<p class='tty cmd'>sudo tail -f /var/log/syslog</p>
</li>
<li style="margin-bottom: 1em">Run <span class="code">weewxd</span> directly from the command line, rather
than as a daemon. Generally, WeeWX will catch and log any unrecoverable exceptions. But if you are
getting strange results, it is worth running directly and looking for any clues.
<p class='tty cmd'>sudo weewxd weewx.conf</p>
</li>
</ul>
<p>If you are still stuck, post your problem to the <a
href="https://groups.google.com/forum/#!forum/weewx-user">weewx-user group</a>. The Wiki has some guidelines
on <a href="https://github.com/weewx/weewx/wiki/Help!-Posting-to-weewx-user"> how to do an effective
post</a>.
</p>
<h2>Hardware problems</h2>
<h3>Tips on making a system reliable</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>
<div class='image image-right' style='width:205px'>
<a href="images/ferrites.jpg"><img src="images/ferrites.jpg"
style="width:200px; border:solid; border-width: 1px;"
alt="Cable connection looped through a ferrite coil"/></a>
<div class='image_caption'>Ferrite coils on a Davis Envoy. There are two coils, one on the USB connection
(top wire) and one on the power supply. Both have loops. Click for larger picture.
</div>
</div>
<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 do
not 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
&mdash; just a second or two &mdash; so you do not need a big one. The 425VA unit I use to protect my
fit-PC cost $55 at Best Buy.
</li>
<li>If you buy a Davis VantagePro and your computer has an old-fashioned serial port, get the VantagePro
with a serial connection, not a USB connection. See the section on <a href="#davis_cp2101_converter">Davis
cp2101 converter problems</a> for details.
</li>
<li>If you do use a USB connection, put a ferrite coil on each end of the cable to your console. If you have
enough length and the ferrite coil is big enough, make a loop so it goes through the coil twice. See the
figure at right.
</li>
</ul>
<h3>Establishing connectivity</h3>
<p>If you are unable to get anything out of WeeWX first check that you have connectivity to your weather
station. For the Davis stations, you can use a terminal emulator to run a simple test. Set it up to
communicate using the appropriate port and baudrate. I like <span class="code">minicom</span> because it can
be run from through a simple TTY connection. The utility <span class="code">screen</span> also works well.
For example:
</p>
<pre class="tty cmd">minicom -b 19200 -D /dev/ttyUSB0</pre>
<p>or, using <span class='code'>screen</span>:</p>
<pre class="tty cmd">screen /dev/ttyUSB0 19200</pre>
<p>Then type in <span class="code">TEST</span>, all in capital letters. It will not echo the characters. Then
hit the <span class="code">&lt;enter&gt;</span> key. It should echo back <span class="code">TEST</span>.
</p>
<p>If this works, then you have established connectivity with the Davis and the problem must lie elsewhere.</p>
<h3 id="davis_cp2101_converter">Davis cp2101 converter problems</h3>
<p>The USB converter used in the Davis VantagePro is known to have some &quot;noise&quot; problems. The symptom
is that the Linux kernel will disconnect from your old USB port claiming &quot;EMI noise&quot;, and
reconnect to a new and different port, where WeeWX cannot find it. Here is a typical log output:
</p>
<pre class='tty'>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
... (messages elided)
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 3
years ago, and have not had a problem since.
</p>
<p>However, there is one final step that you can take to really 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 follow it. You just specify port <span class="code">/dev/vpro</span>
in the configuration file <span class="code">weewx.conf</span> and be done with it.
</p>
<h3 id='udev_script'>Installing a udev script</h3>
<p>Use a udev rule to ensure that a USB device always appears at the same location such as <span class='code'>/dev/vpro</span>
instead of <span class='code'>/dev/ttyUSB2</span></p>
<p>For example, for my VantagePro2 weather station, I have installed a file <span class="code">/etc/udev/rules.d/vpro.rules</span>
on my fit-PC that looks like this:
</p>
<pre class='tty'># Automount the VantagePro2 to port /dev/vpro.
# Install in /etc/udev/rules.d/vpro.rules
#
ACTION==&quot;add&quot;, ATTRS{interface}==&quot;CP2102 USB to UART Bridge Controller&quot;, SYMLINK+=&quot;vpro&quot;</pre>
<p>This rule says 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 to UART Bridge Controller</span>,
then add a symbolic link for its physical port to <span class="code">/dev/vpro</span>.
</p>
<p>Here is a rule that works for my Serial-to-USB cable, made by "Y.C. Cable USA". It not only adds a symbolic
link <span class="code">vpro</span>, but also sets the <span class="code">chmod</span> permissions to <span
class="code">666</span>, allowing any user to read or write to it.
</p>
<pre class='tty'># Automount Serial-to-USB cable to port /dev/vpro
# Install in /etc/udev/rules.d/cable.rules
#
ACTION=="add",ATTRS{idVendor}=="05ad",ATTRS{idProduct}=="0fba",MODE="0666",SYMLINK+="vpro"</pre>
<p>Your devices may, and probably will, have different identifiers!! I can recommend this article, &quot;<a
href="http://www.reactivated.net/writing_udev_rules.html"><em>Writing udev rules</em></a>,&quot; for how to
find and write an appropriate <span class="code">udev</span> rule for your controller. (Note, however, that
this article uses the old <span class="code">udevinfo</span> command, rather than the newer <span
class="code">udevadm</span> command.) In particular, run the command
</p>
<p class='tty cmd'>udevadm info --attribute-walk --path $(udevadm info --query=path --name=/dev/ttyUSB0)</p>
<p>where <span class="code">/dev/ttyUSB0</span> is the port (substitute your real USB port) the weather station
is attached to. It will print out various identifiers that can be useful in identifying your weather station
to <span class="code">udev</span>. While the first example script above used a rule that matched attribute
<span class="code">interface</span>, others are possible. For example, the second example, for the
serial-to-USB cable, chose to match the attribute <span class="code">product</span>.
</p>
<p>Once you have 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 weather station, 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>
<h3 id="html_generated_but_not_updated">WeeWX generates HTML pages, but it does not update them</h3>
<p>If you are getting a symptom that everything appears normal, that is image and HTML files are generated (<em>look
in the log to be sure</em>) and sent to your webserver (if you have configured FTP or rsync), but the values
in the web pages are not being updated, it could be due to clock skew or corrupt station memory.
</p>
<h4>Clock skew</h4>
<p>If the database contains a record with time stamp (the dateTime field) in the future, then records from the
station that are older than that future date will be ignored. How can the database contain records from the
future? Sometimes the computer clock is not set correctly. For example, the raspberry pi has no clock, so if
WeeWX saves data before the pi has synchronized its clock with internet time servers, the records will have
incorrect time stamps, some of which might be in the future.
</p>
<p>The solution is to delete any records with time stamp in the future. For a sqlite database, the procedure
looks like this:
</p>
<pre class="tty"><span class="cmd">cp /home/weewx/archive/weewx.sdb /home/weewx/archive/weewx.sdb.backup
sqlite3 /home/weewx/archive/weewx.sdb</span>
sqlite> <span class="cmd">delete from archive where dateTime > X;</span>
sqlite> <span class="cmd">.exit</span></pre>
<p>The timestamp X is the current time in unix epoch time (number of seconds since 1 January 1970). <a
href="https://www.epochconverter.com/">This website</a> is useful for determining the current unix epoch
time.
</p>
<h4>Corrupt station memory</h4>
<p>If you have a Vantage station, the problem might be because the data on board your console has become
garbled. The way the Davis Vantage series works is that the software (WeeWX in this case) asks the console
for all archive data &quot;since&quot; some time. The console then downloads the records one at a time.
After it gets to the very last one, the memory wraps around, and the timestamp will suddenly jump backwards
in time a couple weeks &mdash; this is how the software knows it has downloaded the last record and so it
stops.
</p>
<p>However, if the internal memory gets garbled, the console will immediately return archives in the past, and
so it looks like the timestamps have decreased in value and so WeeWX figures that is it: there is no more
data. Here is what the log typically looks like (with <span class="code">debug=1</span>):
</p>
<pre class="tty">Nov 26 14:20:15 raspberrypi weewx[3849]: vantage: Getting archive packets since 2016-11-25 19:55:00 CET (1480100100)
Nov 26 14:20:15 raspberrypi weewx[3849]: vantage: gentle wake up of console successful
Nov 26 14:20:15 raspberrypi weewx[3849]: vantage: Retrieving 45 page(s); starting index= 1
Nov 26 14:20:15 raspberrypi weewx[3849]: vantage: DMPAFT complete: page timestamp 2016-11-02 19:25:00 CET (1478111100) less than final timestamp 2016-11-25 19:55:00 CET (1480100100)
Nov 26 14:20:15 raspberrypi weewx[3849]: vantage: Catch up complete.
Nov 26 14:20:15 raspberrypi weewx[3849]: reportengine: Running reports for latest time in the database.
Nov 26 14:20:15 raspberrypi weewx[3849]: reportengine: Running report StandardReport
Nov 26 14:20:15 raspberrypi weewx[3849]: vantage: Requesting 200 LOOP packets.
Nov 26 14:20:15 raspberrypi weewx[3849]: reportengine: Found configuration file /etc/weewx/skins/Standard/skin.conf for report StandardReport
Nov 26 14:20:15 raspberrypi weewx[3849]: cheetahgenerator: using search list ['weewx.cheetahgenerator.Almanac', 'weewx.cheetahgenerator.Station', 'weewx.cheetahgenerator.Stats', 'weewx.cheetahgenerator.UnitInfo', 'weewx.cheetahgenerator.Extras']
Nov 26 14:20:15 raspberrypi weewx[3849]: vantage: gentle wake up of console successful
Nov 26 14:20:19 raspberrypi weewx[3849]: cheetahgenerator: Generated 14 files for report StandardReport in 4.16 seconds
Nov 26 14:20:20 raspberrypi weewx[3849]: genimages: Generated 12 images for StandardReport in 0.62 seconds
Nov 26 14:20:20 raspberrypi weewx[3849]: reportengine: copied 9 files to /var/www/html/weewx
Nov 26 14:20:20 raspberrypi weewx[3849]: reportengine: Running report FTP
Nov 26 14:20:20 raspberrypi weewx[3849]: reportengine: Found configuration file /etc/weewx/skins/Ftp/skin.conf for report FTP
</pre>
<p>Note how WeeWX did a <span class="code">DMPAFT</span> command ("<span class="code">Getting archive packets since 2016-11-25 19:55:00</span>").
The console responded that it has lots of records after that time ("<span class="code">Retrieving 45 page(s);
starting index= 1</span>"), but when WeeWX actually tries to retrieve them, they are all before the
requested time.
</p>
<p>There seems to be two fixes:</p>
<ol>
<li>Unplug the console, take out the batteries, and wait a minute or two. This will cause the console
software to internally reboot. In one case this has fixed the problem without data loss.
</li>
<li>If all else fails, clear the memory of the console <a href="hardware.htm#vantage_clear_console_memory">using
the utility <span class="code">wee_device</span></a>. This may cause loss of data, but usually works.
Adjust paths as necessary:
</li>
</ol>
<pre class="tty cmd">wee_device --clear-memory</pre>
<p>See also the section <em><a href="hardware.htm#vantage_dumping_the_logger_memory">Dumping the logger
memory</a></em>, which may help you avoid data loss.
</p>
<h3>3rd party Vantage connectors</h3>
<p>This section is for those who are using a homebrew or 3rd party connector to a Davis Vantage console that
does not contain a logger, such as the <a href="http://www.wxforum.net/index.php?topic=14063.0">DSI-01
serial interface</a>. That is, it is a pure serial connection to the console, with no onboard memory.
</p>
<p>For these interfaces, you must set record generation to <em>software</em>. Without this information, WeeWX is
unable to detect the absence of onboard memory. If you do not do this, you will get errors that look like
the following in your syslog:
</p>
<pre class="tty">Nov 27 20:30:21 rpi weewx[5607]: reportengine: Caught unrecoverable exception in generator weewx.filegenerator.FileGenerator
Nov 27 20:30:21 rpi weewx[5607]: **** 'NoneType' object has no attribute '__getitem__'
Nov 27 20:30:21 rpi weewx[5607]: **** Traceback (most recent call last):
Nov 27 20:30:21 rpi weewx[5607]: **** File "/home/weewx/bin/weewx/reportengine.py", line 132, in run
Nov 27 20:30:21 rpi weewx[5607]: **** obj.start()
Nov 27 20:30:21 rpi weewx[5607]: **** File "/home/weewx/bin/weewx/reportengine.py", line 259, in start
Nov 27 20:30:21 rpi weewx[5607]: **** self.run()
Nov 27 20:30:21 rpi weewx[5607]: **** File "/home/weewx/bin/weewx/filegenerator.py", line 41, in run
Nov 27 20:30:21 rpi weewx[5607]: **** self.setup()
Nov 27 20:30:21 rpi weewx[5607]: **** File "/home/weewx/bin/weewx/filegenerator.py", line 52, in setup
Nov 27 20:30:21 rpi weewx[5607]: **** self.initAlmanac(self.gen_ts)
Nov 27 20:30:21 rpi weewx[5607]: **** File "/home/weewx/bin/weewx/filegenerator.py", line 87, in initAlmanac
Nov 27 20:30:21 rpi weewx[5607]: **** rec = self.getRecord(archivedb, celestial_ts)
Nov 27 20:30:21 rpi weewx[5607]: **** File "/home/weewx/bin/weewx/filegenerator.py", line 115, in getRecord
Nov 27 20:30:21 rpi weewx[5607]: **** record_dict_vt = weewx.units.dictFromStd(record_dict)
Nov 27 20:30:21 rpi weewx[5607]: **** File "/home/weewx/bin/weewx/units.py", line 892, in dictFromStd
Nov 27 20:30:21 rpi weewx[5607]: **** std_unit_system = d['usUnits']
Nov 27 20:30:21 rpi weewx[5607]: **** TypeError: 'NoneType' object has no attribute '__getitem__'
Nov 27 20:30:21 rpi weewx[5607]: **** Generator terminated...
Nov 27 20:30:23 rpi weewx[5607]: genimages: Generated 11 images in 2.53 seconds</pre>
<p>See the section on option <span class="code">
<a href="#record_generation">record_generation</a></span>.
</p>
<h3>Raspberry Pi</h3>
<p>WeeWX runs very well on the Raspberry Pi, from the original Model A and Model B, to the latest incarnations.
However, the Pi does have some quirks, including issues with USB power and lack of a clock.
</p>
<p>
See the <a href="https://github.com/weewx/weewx/wiki">Wiki</a> for up-to-date information on <a
href="https://github.com/weewx/weewx/wiki/Raspberry%20Pi"> <em>Running WeeWX on a Raspberry Pi</em></a>.
</p>
<h3>Fine Offset USB lockups</h3>
<p>The Fine Offset series weather stations and their derivatives are a fine value and can be made to work
reasonably reliably, but they have one problem that is difficult to work around: the USB can unexpectantly
lock up, making it impossible to communicate with the console. The symptom in the log will look something
like this:
</p>
<pre class="tty">Jun 7 21:50:33 localhost weewx[2460]: fousb: get archive interval failed attempt 1 of 3: could not detach kernel driver from interface 0: No data available</pre>
<p>The exact error may vary, but the thing to look for is the "<span
class='code'>could not detach kernel driver</span>" message. Unfortunately, we have not found a software
cure for this. Instead, you must power cycle the unit. Remove the batteries and unplug the USB, then put it
back together. No need to restart WeeWX.
</p>
<p>More details about <a href="https://github.com/weewx/weewx/wiki/FineOffset%20USB%20lockup"><em>Fine Offset
lockups</em></a> can be found in the <a href="https://github.com/weewx/weewx/wiki">Wiki</a>.
</p>
<h3 id='archive_interval'>Archive interval</h3>
<p>Most hardware with data-logging includes a parameter to specify the archive interval used by the logger. If
the hardware and driver support it, WeeWX will use this interval as the <span class='code'><em>archive_interval</em></span>.
If not, WeeWX will fall back to the <span class='code'>archive_interval</span> specified in <a
href='#StdArchive'><span class='code'>[StdArchive]</span></a>. The default fallback value is 300 seconds
(5 minutes).
</p>
<p>If the hardware archive interval is large, it will take a long time before anything shows up in the WeeWX
reports. For example, WS23xx stations ship with an archive interval of 60 minutes, and Fine Offset stations
ship with an archive interval of 30 minutes. If you run WeeWX with a WS23xx station in its factory default
configuration, it will take 60 minutes before the first data point shows up, then another 60 minutes until
the next one, and so on.
</p>
<p>
Since reports are generated when a new archive record arrives, a large archive interval means that reports
will be generated infrequently.
</p>
<p>If you want data and reports closer to real-time, use the <a href="utilities.htm#wee_device_utility"><span
class="code">wee_device</span></a> utility to change the interval.
</p>
<h2>Software problems</h2>
<p>This section covers some common software configuration problems.</p>
<h3>Nothing in the log file</h3>
<p>As it is running, WeeWX periodically sends status information, failures, and other things to your system's
logging facility. They typically look something like this:
</p>
<pre class='tty'>-DATE- --TIME-- HOST weewx[-PID-]: LOG_MESSAGE
Jan 1 09:46:32 saga weewx[15292]: wxengine: Initializing weewx version 2.5.1
Jan 1 09:46:32 saga weewx[15292]: wxengine: Using Python 2.6.6 (r266:84292, Dec 27 2010, 21:57:32) #012[GCC 4.4.5 20100902 (prerelease)]
Jan 1 09:46:32 saga weewx[15292]: wxengine: pid file is /var/run/weewx.pid</pre>
<p>The location of this logging file varies from system to system, but it is typically in <span class="code">/var/log/syslog</span>,
or something similar.
</p>
<p>However, some systems default to saving only warning or critical information, so the <span
class="code">info</span> messages from WeeWX may not appear. If this happens to you, check your system
logging configuration. On Debian systems, look in <span class="code">/etc/rsyslog.conf</span>. On Redhat
systems, look in <span class="code">/etc/syslog.conf</span>.
</p>
<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 WeeWX is run directly than when it is run as a daemon.
</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 class='tty'>[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 class='tty'>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>
<p class='tty'>[Reports] [[FTP]]] ... (details elided)</p>
<p>Note the extra closing bracket on the subsection <span class="code">FTP</span>.
</p>
<h3>No barometer data</h3>
<p>If everything appears normal except that you have no barometer data, the problem may be a mismatch between
the unit system used for service <span class="code">StdConvert</span> and the unit system used by service
<span class="code">StdQC</span>. For example:
</p>
<pre class="tty">[StdConvert]
target_unit = METRIC
...
[StdQC]
[[MinMax]]
barometer = 28, 32.5</pre>
<p>The problem is that you are requiring the barometer data to be between 28 and 32.5, but with the unit system
set to <span class="code">METRIC</span>, the data will be in the range 990 to 1050 or so!
</p>
<p>The solution is to change the values to match the units in StdConvert, or specify the units in MinMax,
regardless of the units in StdConvert. For example:
</p>
<pre class="tty">[StdConvert]
target_unit = US
...
[StdQC]
[[MinMax]]
barometer = 950, 1100, mbar</pre>
<h3><span class="code">Cheetah.NameMapper.NotFound</span> errors</h3>
<p>If you get errors of the sort:</p>
<pre class='tty'>Apr 12 05:12:32 raven reportengine[3074]: filegenerator: Caught exception &quot;&lt;class &#39;NameMapper.NotFound&#39;&gt;&quot;
Apr 12 05:12:32 raven reportengine[3074]: **** Message: &quot;cannot find &#39;fubar&#39; in template /home/weewx/skins/Standard/index.html.tmpl&quot;
Apr 12 05:12:32 raven reportengine[3074]: **** Ignoring template and continuing.</pre>
<p>you have a tag in your template that WeeWX does not recognize. In this example, it is the tag <span
class="code">$fubar</span> in the template <span
class="code">/home/weewx/skins/Standard/index.html.tmpl</span>.
</p>
<h3 id="many_loop_read_errors">Many LOOP read errors with Davis Vantage</h3>
<p>The symptom is many LOOP errors and unreliable downloading of archive records. Your log may look like this:
</p>
<pre class="tty">
Jan 18 20:38:52 rpi weewx[6024]: VantagePro: Opened up serial port /dev/ttyUSB0, baudrate 19200
Jan 18 20:38:53 rpi weewx[5977]: VantagePro: LOOP #12; read error. Try #1
Jan 18 20:38:53 rpi weewx[5977]: **** Expected to read 99 chars; got 0 instead
Jan 18 20:38:58 rpi weewx[7543]: VantagePro: LOOP #13; read error. Try #1
Jan 18 20:38:58 rpi weewx[7543]: **** Expected to read 99 chars; got 4 instead
Jan 18 20:39:03 rpi weewx[7543]: VantagePro: LOOP #14; read error. Try #2
Jan 18 20:39:03 rpi weewx[7543]: **** Expected to read 99 chars; got 0 instead
Jan 18 20:39:03 rpi weewx[5977]: VantagePro: LOOP #13; read error. Try #2
Jan 18 20:39:03 rpi weewx[5977]: **** Expected to read 99 chars; got 4 instead
Jan 18 20:39:08 rpi weewx[7543]: VantagePro: LOOP #15; read error. Try #3
Jan 18 20:39:08 rpi weewx[7543]: **** Expected to read 99 chars; got 4 instead
Jan 18 20:39:09 rpi weewx[5977]: VantagePro: LOOP #14; read error. Try #3
Jan 18 20:39:09 rpi weewx[5977]: **** Expected to read 99 chars; got 2 instead
Jan 18 20:39:14 rpi weewx[5977]: VantagePro: LOOP #15; read error. Try #4
Jan 18 20:39:14 rpi weewx[5977]: **** Expected to read 99 chars; got 2 instead</pre>
<p>If you look closely at the log above, you'll see that there are multiple instances of WeeWX running
simultaneously (process IDs 5977, 6024, and 7543). They are contending with each other for control of the
console, resulting in missed packets and records.
</p>
<p>The cure is simple: kill all but one of them. Or, better yet, kill them all, then start WeeWX.</p>
<h3 id='dots_in_plots'>Dots in the plots</h3>
<p>If you see dots instead of lines in the daily plots, you might want to change the graphing options or adjust
the station's archive interval.
</p>
<p>In a default configuration, a time period greater than 1% of the displayed timespan is considered to be a gap
in data. So when the interval between data points is greater than about 10 minutes, the daily plots show
dots instead of connected points.
</p>
<p>Change the <a href="customizing.htm#line_gap_fraction"><span class='code'>line_gap_fraction</span></a> option
in <span class="code">skin.conf</span> to control how much time is considered a break in data.
</p>
<p>As for the archive interval, check the log file for an entry like this soon after WeeWX starts up:</p>
<pre class='tty'>Dec 30 10:54:17 saga weewx[10035]: wxengine: The archive interval in the configuration file (300) does not match the station hardware interval (1800).
Dec 30 10:54:17 saga weewx[10035]: wxengine: Using archive interval of 1800</pre>
<p>In this example, interval in <span class="code">weewx.conf</span> is 5 minutes, but the station interval is
30 minutes. When the interval in <span class="code">weewx.conf</span> does not match the station's hardware
interval, WeeWX defers to the station's interval.
</p>
<p>Use the <a href="utilities.htm#wee_device_utility"><span class="code">wee_device</span></a> utility to change
the station's interval.
</p>
<h3 id='spikes'>Spikes in the graphs</h3>
<p>Occasionally you may see anomalous readings, typically manifested as spikes in the graphs. The source could
be a flaky serial/USB connection, radio or other interference, a cheap USB-Serial adapter, low-quality
sensors, or simply an anomalous reading.
</p>
<p>Sensor quality matters. It is not unusual for some low-end hardware to report odd sensor readings
occasionally (once every few days). Some sensors, such as solar radiation/UV, have a limited lifespan of
about 5 years. The (analog) humidity sensors on older Vantage stations are known to deteriorate after a few
years in wet environments.
</p>
<p>If you frequently see anomalous data, first check the hardware.</p>
<p>To keep bad data from the database, add a quality control (QC) rule such as Min/Max bounds. See the <a
href="#StdQC">QC</a> section for details.
</p>
<p>To remove bad data from the database, you will have to do some basic SQL commands. For example, let's say the
station emitted some very high temperatures and wind speeds for one or two readings. This is how to remove
them:
</p>
<ol>
<li>stop WeeWX</li>
<li>Make a copy of the archive database
<pre class='tty cmd'>cp weewx.sdb weewx-YYMMDD.sdb</pre>
</li>
<li>Verify the bad data exist where you think they exist
<pre class='tty'><span class="cmd">sqlite3 weewx.sdb</span>
sqlite&gt; <span class="cmd">select dateTime,outTemp from archive where outTemp &gt; 1000;</span></pre>
</li>
<li>See whether the bad temperature and wind data happened at the same time
<pre class='tty'>sqlite&gt; <span class="cmd">select dateTime,outTemp,windSpeed from archive where outTemp &gt; 1000;</span></pre>
</li>
<li>Remove the bad data by setting to NULL
<pre class='tty'>sqlite&gt; <span
class="cmd">update archive set windSpeed=NULL where outTemp &gt; 1000;</span>
sqlite&gt; <span class="cmd">update archive set outTemp=NULL where outTemp &gt; 1000;</span></pre>
</li>
<li>Delete the aggregate statistics so that WeeWX can regenerate them without the anomalies
<pre class='tty cmd'>sudo wee_database --drop-daily</pre>
</li>
<li>start WeeWX</li>
</ol>
<h3>'Database is locked' error</h3>
<p>This seems to be a problem with the Raspberry Pi, <strong>when using SQLite</strong>. There is no analogous
problem with MySQL databases. You will see errors in the system log that looks like this:
</p>
<pre class='tty'>
Feb 12 07:11:06 rpi weewx[20930]: **** File "/usr/share/weewx/weewx/archive.py", line 118, in lastGoodStamp
Feb 12 07:11:06 rpi weewx[20930]: **** _row = self.getSql("SELECT MAX(dateTime) FROM %s" % self.table)
Feb 12 07:11:06 rpi weewx[20930]: **** File "/usr/share/weewx/weewx/archive.py", line 250, in getSql
Feb 12 07:11:06 rpi weewx[20930]: **** File "/usr/share/weewx/weedb/sqlite.py", line 120, in execute
Feb 12 07:11:06 rpi weewx[20930]: **** raise weedb.OperationalError(e)
Feb 12 07:11:06 rpi weewx[20930]: **** OperationalError: database is locked
Feb 12 07:11:06 rpi weewx[20930]: **** _cursor.execute(sql, sqlargs)
Feb 12 07:11:06 rpi weewx[20930]: **** File "/usr/share/weewx/weedb/sqlite.py", line 120, in execute
Feb 12 07:11:06 rpi weewx[20930]: **** raise weedb.OperationalError(e)
<span class='highlight'>Feb 12 07:11:06 rpi weewx[20930]: **** OperationalError: database is locked</span></pre>
<p>We are still trying to decipher exactly what the problem is, but it seems that (many? most? all?)
implementations of the SQLite 'C' access libraries on the RPi sleep for a full second if they find the
database locked. This gives them only five chances within the 5 second timeout period before an exception is
raised.
</p>
<p>Not all Raspberry Pis have this problem. It seems to be most acute when running big templates with lots of
queries, such as the forecast extension.
</p>
<p>There are a few possible fixes:</p>
<ul>
<li>Increase the <a href='#archive_timeout'><span class='code'>timeout</span> option</a>.</li>
<li>Use a high quality SD card in your RPi. There seems to be some evidence that faster SD cards are more
immune to this problem.
</li>
<li>Trim the size of your templates to minimize the number of queries necessary.</li>
</ul>
<p>None of these 'fixes' are very satisfying and we're trying to come up with a more robust solution.</p>
<h3>Strings in the database</h3>
<p>If you modify the SQLite archive database using an editing tool, occasionally strings will get embedded in
it, causing WeeWX to raise an exception. <strong>This is only a problem with SQLite</strong>. There is no
analogous problem with MySQL databases. You will see errors in the system log that look something like this:
</p>
<pre class='tty'>
Dec 31 17:01:06 arm weewx[18141]: **** File "/usr/share/weewx/weewx/wxengine.py", line 432, in __init__
Dec 31 17:01:06 arm weewx[18141]: **** self.setupStatsDatabase(config_dict)
Dec 31 17:01:06 arm weewx[18141]: **** File "/usr/share/weewx/weewx/wxengine.py", line 543, in setupStatsDatabase
Dec 31 17:01:06 arm weewx[18141]: **** self.statsDb.backfillFrom(self.archive)
Dec 31 17:01:06 arm weewx[18141]: **** File "/usr/share/weewx/weewx/stats.py", line 461, in backfillFrom
Dec 31 17:01:06 arm weewx[18141]: **** _statsDict.addRecord(_rec)
Dec 31 17:01:06 arm weewx[18141]: **** File "/usr/share/weewx/weewx/accum.py", line 305, in addRecord
Dec 31 17:01:06 arm weewx[18141]: **** self._add_value(record[obs_type], obs_type, record['dateTime'], add_hilo)
Dec 31 17:01:06 arm weewx[18141]: **** File "/usr/share/weewx/weewx/accum.py", line 264, in _add_value
Dec 31 17:01:06 arm weewx[18141]: **** self[obs_type].addSum(val)
Dec 31 17:01:06 arm weewx[18141]: **** File "/usr/share/weewx/weewx/accum.py", line 81, in addSum
Dec 31 17:01:06 arm weewx[18141]: **** self.sum += val
<span class='highlight'>Dec 31 17:01:06 arm weewx[18141]: **** TypeError: unsupported operand type(s) for +=: 'float' and 'unicode'</span>
Dec 31 17:01:06 arm weewx[18141]: **** Exiting.</pre>
<p>The problem is that a unicode null string <span class='code'>u''</span> got entered where a <span
class='code'>NULL</span> should be. The utility <span class='code'>wee_database</span> can fix this. Run it
with the option <span class='code'>--check-strings</span> to search for these embedded strings. Add the
option <span class='code'>--fix-strings</span> to have the utility fix them:
</p>
<pre class="tty cmd">wee_database weewx.conf --check-strings --fix-strings</pre>
<h3 id="python2_6">Python 2.6</h3>
<p>Unfortunately, the current version of PySerial, 3.x, does not work with Python 2.6. If your hardware requires
PySerial (check the <a href="hardware.htm"><em>Hardware Guide</em></a>), you will have to downgrade to
PySerial V2.7, which you can <a href="https://sourceforge.net/projects/pyserial/files/pyserial/2.7/">obtain
from SourceForge</a>.
</p>
<h3>FreeBSD</h3>
<p>User Fabian reports that the following had to be done to get the VantagePro2 working under FreeBSD:</p>
<pre class="tty">I needed the uslcom Driver for the usb/rs232 Adapter used by my vantage. Also I had to reset the memory of the weatherstation.
Loading the Driver:
Put uslcom_load=&quot;YES&quot; in /boot/loader.conf (to load it as module).
Which gives here an output like:
uslcom0: &lt;CP2102 USB to UART Bridge Controller&gt; on usbus1
And put in <span class="code">weewx.conf</span>:
port = /dev/cuaU0</pre>
<h3 id="funky_symbols">Funky symbols in plots</h3>
<p>If your plots have strange looking symbols for units, such as degrees Fahrenheit (&deg;F), that look
something like this:
</p>
<img src='images/funky_degree.png' alt='funky degree sign'/>
<p>Then the problem may be that you are missing the fonts specified for the option <span class="code">unit_label_font_path</span>
in your <span class="code">skin.conf</span> file and, instead, WeeWX is substituting a default font, which
does not support the Unicode character necessary to make a degree sign. Look in section <span class="code">[ImageGenerator]</span>
for a line that looks like:
</p>
<pre class="tty">unit_label_font_path = /usr/share/fonts/truetype/freefont/FreeMonoBold.ttf</pre>
<p>Make sure that the specified path (<span
class='code'>/usr/share/fonts/truetype/freefont/FreeMonoBold.ttf</span> in this case) actually exists. If it
does not, on Debian operating systems (such as Ubuntu), you may be able to install the necessary fonts:
</p>
<pre class="tty cmd">sudo apt-get install fonts-freefont-ttf
sudo fc-cache -f -v</pre>
<p>(On older systems, the package <span class="code">fonts-freefont-ttf</span> may be called <span class="code">ttf-freefont</span>).
The first command installs the "Truetype" fonts, the second rebuilds the font cache. If your system does not
have <span class="code">fc-cache</span> command, then install it from the <span
class="code">fontconfig</span> package:
</p>
<pre class="tty cmd">sudo apt-get install fontconfig</pre>
<p>If none of this works, or if you are on a different operating system, then you will have to change the option
<span class="code">unit_label_font_path</span> to point to something on your system which does support the
Unicode characters you plan to use.
</p>
<h3>UnicodeEncodeError</h3>
<p>This problem is closely related to the <a href="#funky_symbols">"Funky symbols"</a> problem above. In this
case, you may see errors in your log that look like:
</p>
<pre class="tty">May 14 13:35:23 web weewx[5633]: cheetahgenerator: Generated 14 files for report StandardReport in 1.27 seconds
May 14 13:35:23 web weewx[5633]: reportengine: Caught unrecoverable exception in generator weewx.imagegenerator.ImageGenerator
May 14 13:35:23 web weewx[5633]: **** 'ascii' codec can't encode character u'\xe8' in position 5: ordinal not in range(128)
May 14 13:35:23 web weewx[5633]: **** Traceback (most recent call last):
May 14 13:35:23 web weewx[5633]: **** File "/usr/share/weewx/weewx/reportengine.py", line 139, in run
May 14 13:35:23 web weewx[5633]: **** obj.start()
May 14 13:35:23 web weewx[5633]: **** File "/usr/share/weewx/weewx/reportengine.py", line 170, in start
May 14 13:35:23 web weewx[5633]: **** self.run()
May 14 13:35:23 web weewx[5633]: **** File "/usr/share/weewx/weewx/imagegenerator.py", line 36, in run
May 14 13:35:23 web weewx[5633]: **** self.genImages(self.gen_ts)
May 14 13:35:23 web weewx[5633]: **** File "/usr/share/weewx/weewx/imagegenerator.py", line 220, in genImages
May 14 13:35:23 web weewx[5633]: **** image = plot.render()
May 14 13:35:23 web weewx[5633]: **** File "/usr/share/weewx/weeplot/genplot.py", line 175, in render
May 14 13:35:23 web weewx[5633]: **** self._renderTopBand(draw)
May 14 13:35:23 web weewx[5633]: **** File "/usr/share/weewx/weeplot/genplot.py", line 390, in _renderTopBand
May 14 13:35:23 web weewx[5633]: **** top_label_size = draw.textsize(top_label, font=top_label_font)
May 14 13:35:23 web weewx[5633]: **** File "/usr/lib/python2.7/dist-packages/PIL/ImageDraw.py", line 278, in textsize
May 14 13:35:23 web weewx[5633]: **** return font.getsize(text)
May 14 13:35:23 web weewx[5633]: <span class="highlight">**** UnicodeEncodeError: 'ascii' codec can't encode character u'\xe8' in position 5: ordinal not in range(128)</span>
May 14 13:35:23 web weewx[5633]: **** Generator terminated...</pre>
<p>This is frequently caused by the necessary Truetype fonts not being installed on your computer and, instead,
a default font is being substituted, which only knows how to plot ASCII characters. The cure is as before:
install the font.
</p>
<h3>Data is archived but some/all reports do not run</h3>
<p>If WeeWX appears to be running normally but some or all reports are not being run, either all the time or
periodically, the problem could be the inadvertant use or incorrect setting of the <span class="code">report_timing</span>
option in <span class='code'>weewx.conf</span>. The <span class="code">report_timing</span> option allows
the user to specify when some or all reports are run (refer <a href="customizing.htm#customizing_gen_time">Customizing
the report generation time</a>). By default the <span class="code">report_timing</span> option is
disabled and all reports are run each archive period.
</p>
<p>To see if the <span class="code">report_timing</span> option is causing reports to be skipped inspect the <a
href="#monitoring">log file</a>. Any reports that are skipped due to the <span
class="code">report_timing</span> option will be logged as follows:
</p>
<pre class="tty">Apr 29 09:30:17 rosella weewx[3319]: reportengine: Report StandardReport skipped due to report_timing setting</pre>
<p>If reports are being incorrectly skipped due to <span class="code">report_timing</span> then edit <span
class='code'>weewx.conf</span> and check for a <span class="code">report_timing</span> option in <span
class="code">[StdReport]</span>. Either remove all occurrences of <span class="code">report_timing</span> to
run all reports each archive period or confirm the correct use and setting of the <span class="code">report_timing</span>
option.
</p>
<h3>The wrong reports are being skipped by <span class="code">report_timing</span></h3>
<p>If the <span class="code">report_timing</span> option is being used and the results are not as expected,
there may be an error in the <span class="code">report_timing</span> option. If there are errors in the
<span class="code">report_timing</span> parameter, the report will be run on each archive interval. First
check the <span class="code">report_timing</span> option parameters to ensure they are valid and there are
no additonal spaces or other unwanted characters. Then check that the parameters are correctly set for the
desired report generation times. For example, is the correct day of the week number being used if limiting
the day of the week parameter. Refer to <a href="customizing.htm#customizing_gen_time">Customizing the
report generation time</a>.
</p>
<p>Check the <a href="#monitoring">log file</a> for any entries relating to the reports concerned. Errors in the
<span class="code">report_timing</span> parameter and skipped reports are logged only when <span
class="code">debug=1</span> in <span class="code">weewx.conf</span>.
</p>
<h2>Meteorological problems</h2>
<h3 id='pressure_mismatch'>The pressure reported by WeeWX does not match the pressure on the console</h3>
<p>
Be sure that you are comparing the right values. There are three different types of pressure:
</p>
<dl>
<dt>Station Pressure</dt>
<dd>
The <em>Station Pressure</em> (SP), which is the raw, absolute pressure measured by the station. This is
<span class='code'>pressure</span> in WeeWX packets and archive records.
</dd>
<dt>Sea Level Pressure</dt>
<dd>
The <em>Sea Level Pressure</em> (SLP) is obtained by correcting the <em>Station Pressure</em> for
altitude and local temperature. This is <span class='code'>barometer</span> in WeeWX packets and archive
records.
</dd>
<dt>Altimeter</dt>
<dd>
The <em>Altimeter Setting</em> (AS) is obtained by correcting the <em>Station Pressure</em> for
altitude. This is <span class='code'>altimeter</span> in WeeWX packets and archive records.
</dd>
</dl>
<p>
Any station might require calibration. For some hardware, this can be done at the weather station console.
Alternatively, use the <span class='code'>StdCalibrate</span> section to apply an offset.
</p>
<p>
If your station is significantly above (or below) sea level, be sure that the station altitude is specified
properly. Also, be sure that any calibration results in a station pressure and/or barometric pressure that
matches those reported by other stations in your area.
</p>
<h3 id='pressure_calibration'>Calibrating <span class='code'>barometer</span> does not change the pressure
displayed by WeeWX</h3>
<p>
Be sure that the calibration is applied to the correct quantity.
</p>
<p>
The corrections in the <span class='code'>StdCalibrate</span> section apply only to raw values from the
hardware; corrections are not applied to derived quantities.
</p>
<p>
The station hardware matters. Some stations report gauge pressure (<span class='code'>pressure</span>) while
other stations report sea-level pressure (<span class='code'>barometer</span>). For example, if the hardware
is a Vantage station, the correction must be applied to <span class='code'>barometer</span> since the
Vantage station reports <span class='code'>barometer</span> and WeeWX calculates <span
class='code'>pressure</span>. However, if the hardware is a FineOffset station, the correction must be
applied to <span class='code'>pressure</span> since the FineOffset stations report <span class='code'>pressure</span>
and WeeWX calculates <span class='code'>barometer</span>.
</p>
<h3 id='rain_mismatch'>The rainfall and/or rain rate reported by WeeWX do not match the console</h3>
<p>
First of all, be sure that you are comparing the right quantities. The value <span class='code'>rain</span>
is the amount of rainfall observed in a period of time. The period of time might be a LOOP interval, in
which case the <span class='code'>rain</span> is the amount of rain since the last LOOP packet. Or the
period of time might be an archive interval, in which case the <span class='code'>rain</span> is the total
of rain reported in each LOOP packet since the last archive record.
</p>
<p>
Some consoles report the amount of rain in the past hour, or the amount of rain since midnight.
</p>
<p>
The rain rate is a derived quantity. Some stations report a rain rate, but for those that do not, WeeWX will
calculate the rain rate.
</p>
<p>
Be sure that the units are correct.
</p>
<p>
Finally, beware of calibration factors specific to the hardware. For example, the bucket type on a Vantage
station must be specified when you set up the weather station. If you modify the rain bucket with a larger
collection area, then you will have to add a multiplier in the <span class='code'>StdCalibrate</span>
section.
</p>
<p>
To diagnose rain issues, run WeeWX directly so that you can see each LOOP packet and REC archive record. Tip
the bucket to verify that each bucket tip is detected and reported by WeeWX. Verify that each bucket tip is
converted to the correct rainfall amount. Then check the database to verify that the values are properly
added and recorded.
</p>
<h3 id="zero_windspeed">There is no wind direction when wind speed is zero</h3>
<p>
This is by design &mdash; if there is no wind, then the wind direction is undefined, represented by NULL
in the database or None in Python. This policy is enforced by the <span class='code'>StdWXCalculate</span>
service. If necessary, it can be overridden. See option <a href="#ignore_zero_wind"><span class="code">ignore_zero_wind</span></a>
in the <a href="#StdWXCalculate"><span class='code'>[StdWXCalculate]</span></a> section.
</p>
<p>
WeeWX distinguishes between a value of zero and no value (NULL or None). However, some services do not make
this distinction and replace a NULL or None with a clearly invalid value such as -999.
</p>
</div> <!--- end technical_content -->
<div class="footer">
<p class="copyright"> &copy; <a href="copyright.htm">Copyright</a> Tom Keffer</p>
</div>
</div>
<!-- Our scripts load last so the content can load first -->
<script src="js/jquery-1.11.1.min.js"></script>
<script src="js/jquery-ui-1.10.4.custom.min.js"></script>
<script src="js/jquery.tocify-1.9.0.min.js"></script>
<script src="js/weewx.js"></script>
<script>
$(function () {
var level = get_default_level();
create_toc_control(level);
generate_toc(level);
});
</script>
<script>
function showtab(tab, id) {
document.getElementById(tab + '-deb').style.display = 'none';
document.getElementById(tab + '-rpm').style.display = 'none';
document.getElementById(tab + '-macos').style.display = 'none';
document.getElementById(tab + '-setup').style.display = 'none';
document.getElementById(tab + '-' + id).style.display = 'block';
document.getElementById(tab + '-tab-deb').className = 'tab';
document.getElementById(tab + '-tab-rpm').className = 'tab';
document.getElementById(tab + '-tab-macos').className = 'tab';
document.getElementById(tab + '-tab-setup').className = 'tab';
document.getElementById(tab + '-tab-' + id).className = 'tab selected';
}
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink