Version: 3.9
User's Guide to WeeWX

This is the complete guide to installing, configuring, and troubleshooting WeeWX.

About WeeWX

WeeWX is software, written in Python, 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 WeatherUnderground, CWOP, or PWSweather.com.

Initial development began in the winter of 2008-2009, with the first release in 2009.

The source code is hosted on GitHub, while downloads are available at weewx.com/downloads.

WeeWX is about 13,000 lines of code, plus another 13,000 for the drivers for all the types of supported hardware.

System requirements

Station hardware

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.

The driver compatibility table 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 supported hardware; the pictures may help you identify the manufacturer and/or model. Compatibility for some hardware is provided by 3rd party drivers, available at the Wiki. Finally, check the hardware comparison to see if your hardware is known but not yet supported.

If you still cannot find your hardware, post to the User's Group for help.

Computer hardware

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!

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.

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.

Time

You should run a NTP 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.

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.

Python

Python 2.6 or 2.7 is required. If you are using Python 2.6, see the special note below about PySerial.

Python 3 will not work.

Permissions

There are a few places where permissions affect WeeWX:

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.

Installing WeeWX

Required skills

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.

You should have the following skills:

If you get stuck, there is a very active User's Group to help, but, please, try to solve the problem yourself before posting.

Overview

This is an outline of the process to install, configure, and run WeeWX:

  1. Read the hardware notes for your weather station. This will let you know of any features, limitations, or quirks of your hardware.
  2. Install WeeWX. Use the step-by-step instructions in one of the installation methods below.
  3. 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 wee_device.
  4. Launch the weewxd program. It can be run either as a daemon, or directly from the command line.
  5. Tune the installation. Typically this is done by changing settings in the weewx.conf configuration file. For example, you might want to register your station, so it shows up on a world-wide map of WeeWX installations.
  6. Customize the installation. This is an advanced topic, which allows you to shape WeeWX exactly to your liking!

Installation methods

WeeWX can be installed from a DEB (Debian) or RPM (Redhat, SUSE) package, or it can be installed using the standard Python utility setup.py.

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.

Installation using setup.py 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 home in the setup.cfg 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.

Installing from DEB package

For Debian, Ubuntu, Mint, and Raspbian operating systems, follow the instructions for Debian-based systems.

Installing from Redhat RPM package

For Redhat, CentOS, Fedora operating systems, follow the the instructions for Redhat-based systems.

Installing from SuSE RPM package

For SuSE and OpenSUSE, follow the instructions for SuSE-based systems.

Installing on MacOS

For MacOS, follow the instructions for MacOS systems.

Installing using the Python tool setup.py

For all other operating systems, follow the setup.py instructions. 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.

Where to find things

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.

Debian Debian logo Ubuntu logo Mint logo
Redhat/SUSE Redhat logo Centos logo Fedora logo SUSE logo
macos Apple logo
setup.py
Application layout for install using DEB package
Role Symbolic Name Nominal Location
WeeWX root directory WEEWX_ROOT /
Executables BIN_ROOT /usr/share/weewx/
Configuration directory CONFIG_ROOT /etc/weewx/
Skins and templates SKIN_ROOT /etc/weewx/skins/
SQLite databases SQLITE_ROOT /var/lib/weewx/
Web pages and images HTML_ROOT /var/www/html/weewx/
Documentation DOC_ROOT /usr/share/doc/weewx/
Examples EXAMPLE_ROOT /usr/share/doc/weewx/examples/
PID file /var/run/weewx.pid
Log file /var/log/syslog

Running WeeWX

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.

Running directly

To run WeeWX directly, invoke the main program, weewxd, giving the configuration file as its only parameter:

sudo weewxd weewx.conf

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.

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.

You can tell a running instance of WeeWX to reread its configuration file by sending it the HUP signal. First run ps to find out the Process ID (PID) number of the instance, then send it the HUP signal:

ps -a          # Note the PID of the weewxd process
kill -HUP pid  # Send it a HUP signal

Note that this only rereads the configuration file. It will not reload any code.

Running as a daemon

For unattended operations it is best to have WeeWX run as a daemon, started automatically when the server is rebooted.

If you use a packaged install from a DEB or RPM distribution, this is done automatically. You can ignore this section.

Start by selecting the appropriate run script. They can be found in the source or installation under util/init.d/.

Debian/Ubuntu/Mint: util/init.d/weewx.debian
Redhat/CentOS/Mint: util/init.d/weewx.redhat
SuSE: util/init.d/weewx.suse

Check the chosen script to make sure the variable WEEWX_ROOT 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).

Copy it to the proper location for your system:

Debian/Ubuntu/Mint: cp util/init.d/weewx.debian /etc/init.d/weewx
Redhat/CentOS/Fedora: cp util/init.d/weewx.redhat /etc/rc.d/init.d/weewx
SuSE: cp util/init.d/weewx.suse /etc/init.d/weewx

Make sure the script is executable:

Debian/Ubuntu/Mint: chmod +x /etc/init.d/weewx
Redhat/CentOS/Fedora: chmod +x /etc/init.d/rc.d/weewx
SuSE: chmod +x /etc/init.d/weewx

Create symbolic links in the run level directories:

Debian/Ubuntu/Mint: update-rc.d weewx defaults 98
Redhat/CentOS/Fedora: chkconfig weewx on
SuSE: /usr/lib/lsb/install_initd /etc/init.d/weewx

WeeWX will now start automatically whenever your system is booted. You can also manually start, stop, and restart the WeeWX daemon:

sudo /etc/init.d/weewx start
sudo /etc/init.d/weewx stop
sudo /etc/init.d/weewx restart

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 sysv-rc-conf. It uses a curses interface to allow you to change easily which run level any of your daemons runs at. There is a similar tool on SuSE. From the start menu run the YAST Control Center, then look for Systems Services (Runlevel). Pick "Expert" mode to see the run levels.

You can also tell WeeWX to reread its configuration file without stopping by using the 'reload' option:

sudo /etc/init.d/weewx reload 

Monitoring WeeWX

WeeWX logs many events to the system log. On Debian systems, this is /var/log/syslog, on SuSE, /var/log/messages. Your system may use yet another place. When troubleshooting the system, be sure to check it!

To watch the log as it is generated, use the tail command with the -f option:

tail -f /var/log/syslog

Set the debug option in weewx.conf to generate many more checks and output more information. This can be useful for diagnosing problems and debugging.

debug = 1

Integrating with a web server

If the server is on the same machine

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 nginx or lighthttpd.

  1. Install the Apache web server on the computer on which WeeWX is running. For example, on Debian systems:

    sudo apt-get install apache2

  2. Configure Apache to see the WeeWX reports.

    • If WeeWX was installed from DEB or RPM package, no configuration should be necessary since the reports are placed in the directory /var/www/html/weewx, which is in the Apache DocumentRoot directory /var/www/html

    • If WeeWX was installed using setup.py, you must tell Apache where to find the WeeWX reports. One method is to install an Apache configuration snippet:

      sudo cp util/apache/conf.d/weewx.conf /etc/apache2/conf.d

      Be sure that the path in the Apache configuration snippet matches the HTML_ROOT defined in the WeeWX configuration file. For example, the path for a default setup.py installation would look like this:

      Alias /weewx /home/weewx/public_html
      <Directory /home/weewx/public_html>
          Options FollowSymlinks
          AllowOverride None
      </Directory>

      Restart Apache to make the changes happen:

      sudo /etc/init.d/apache2 restart
  3. Open the WeeWX URL in a web browser:

    http://localhost/weewx

If the server is on a different machine

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 [StdReport] section of the WeeWX configuration file.

For example, the following configuration would use RSYNC to copy the html and images files from the standard report to a folder /var/www/html/weewx on the server wx.example.com:

[StdReport]
    [[RSYNC]]
        skin = Rsync
        server = wx.example.com
        path = /var/www/html/weewx
        user = wxuser

The following configuration would use FTP to copy the html and images:

[StdReport]
    [[FTP]]
        skin = Ftp
        server = wx.example.com
        path = /var/www/html/weewx
        user = wxuser
        password = wxpass

See the documentation for the [[FTP]] and [[RSYNC]] sections of the configuration file weewx.conf for details and options.

Making backups

To backup a WeeWX installation, you will need to make a copy of

It is not necessary to backup the generated images, HTML files, or NOAA reports since WeeWX will easily create these again.

Individual instructions follow.

Configuration

Save the weewx.conf file.

setup.py: /home/weewx/weewx.conf
DEB/RPM: /etc/weewx/weewx.conf

Skins and templates

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.

setup.py: /home/weewx/skins
DEB/RPM: /etc/weewx/skins

Custom code or extensions

Save the contents of the user 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.

setup.py: /home/weewx/bin/user
DEB/RPM: /usr/share/weewx/user

Database

Finally, you will need to backup the database.

For a SQLite configuration, make a copy of the weewx.sdb file.

setup.py: /home/weewx/archive/weewx.sdb
DEB/RPM: /var/lib/weewx/weewx.sdb

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.

For a MySQL configuration, save a dump of the archive database.

Restoring from backup

To restore from backup, do a fresh install of WeeWX, replace the default files with those from a backup, then start WeeWX.

Configuring MySQL

This section applies only to those who wish to use the MySQL database, instead of the default SQLite database.

First, verify that the MySQLdb python package is installed:

python -c "import MySQLdb"

If this results in an import error

ImportError: No module named MySQLdb

then install the MySQLdb package. For example, on Debian systems:

sudo apt-get install python-mysqldb

Next, change the WeeWX configuration to use MySQL instead of SQLite. In the WeeWX configuration file, change the [[wx_binding]] section to point to the MySQL database, archive_mysql, instead of the SQLite database archive_sqlite.

After the change, it will look something like this (change highlighted):

    [[wx_binding]]
        # The database should match one of the sections in [Databases]
        database = archive_mysql
        # 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

Assuming that you want to use the default database configuration, the [[MySQL]] section should look something like this:

    [[MySQL]]
        driver = weedb.mysql
        host = localhost
        user = weewx
        password = weewx

This assumes user weewx has the password weewx. Adjust as necessary.

You will need to give the necessary permissions for the database weewx to whatever MySQL user you choose, by default, user weewx. Here are the necessary minimum permissions:

mysql> CREATE USER 'weewx'@'localhost' IDENTIFIED BY 'weewx';
mysql> GRANT select, update, create, delete, insert, drop ON weewx.* TO weewx@localhost;

Compatibility with wview

sqlite3

The SQLite archive database used by WeeWX (nominally, weewx.sdb) is completely compatible with the database used by wview (usually called wview-archive.sdb), at least as of wview Version 5.2.X. The schema, and its semantics, is identical.

If you have data from wview, you can 'import' them into WeeWX by simply copying the SQLite database file. Assuming that the wview data are in file /var/wview/archive/wview-archive.sdb,

sudo /etc/init.d/weewx stop
cd SQLITE_ROOT
mv weewx.sdb weewx.sdb.bak
cp /var/wview/archive/wview-archive.sdb weewx.sdb
sudo /etc/init.d/weewx start

Internally, within the weewx.sdb 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 wview archive contains more than a month or two of data.

On my modest 500 MHz fit-PC Slim with 512 MB of memory it took a little over 4 minutes for a year and a half (25 MB) of data.

MySQL

The MySQL archive database used by wview is "almost" compatible with WeeWX. The one difference is that in wview, the column interval is named arcInt (presumably because interval is a keyword in MySQL, although it can still be used by surrounding the word with backquotes).

To change the column name to what WeeWX uses, namely interval, use the utility mysql and issue the command:

mysql> ALTER TABLE your-wview-archive-name CHANGE arcInt `interval` INTEGER NOT NULL; 

where your-wview-archive-name is the name of your wview archive database. Note that the word interval is surrounded by backquotes.

Then in the [Databases] section of weewx.conf, replace the name of the database with whatever your installation of wview used your-wview-archive-name:

[[archive_mysql]]
    database_type = MySQL
    database_name = your-wview-archive-name

The configuration file weewx.conf

The configuration file weewx.conf is a big text file that holds the configuration information about your installation of WeeWX. This includes things such as:

The location of weewx.conf will depend on your installation method and operating system. For example, if you used the setup.py method, then the nominal location is /home/weewx, and so your configuration file will be /home/weewx/weewx.conf. For other configurations, consult the application layout table in the 'Installation methods' section.

There is another type of configuration file, skin.conf, for presentation-specific options. It is described in the Customization Guide, under the section Reference: report options.

The following sections are the definitive guide to the many configuration options available in weewx.conf. They contain many more options than you are likely to need! — you can safely ignore most of them. The truly important ones, the ones you are likely to have to customize for your station, are highlighted.

Default values are provided for many options, meaning that if they are not listed in the configuration file at all, WeeWX will pick sensible values. When the documentation below gives a "default value" this is what it means.

Option hierarchy

In general, options closer to the "root" of weewx.conf are overridden by options closer to the leaves. Here's an example:

log_success = false
...
[StdRESTful]
    log_success = true
    ...
    [[Wunderground]]
        log_success = false     # Wunderground will not be logged
        ...
    [[WOW]]
        log_success = true      # WOW will be logged
        ...
    [[CWOP]]
                                # CWOP will be logged (inherits from [StdRESTful])
        ...

In this example, at the top level, log_success is set to false. So, unless set otherwise, successful operations will not be logged. However, for StdRESTful operations, it is set to true, so for these services, successful operations will be logged, unless set otherwise by an individual service. Looking at the individual services, successful operations for

What follows is organized by the different sections of the configuration file.

General

The options declared at the top are not actually part of any section.

debug

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).

WEEWX_ROOT

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.

log_success

If set to true, the default will be to log a successful operation (for example, the completion of a report, or uploading to the Weather Underground, etc.) to the system log. Default is true.

log_failure

If set to true, the default will be to log an unsuccessful operation (for example, failure to generate a report, or failure to upload to the Weather Underground, etc.) to the system log. Default is true.

socket_timeout

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.

gc_interval

Set to how often garbage collection should be performed by the Python runtime engine. Default is every 10,800 seconds (3 hours).

loop_on_init

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.

[Station]

This section covers options relating to your weather station setup.

location

The station location should be a UTF-8 string that describes the geography of where your weather station is located. Required. No default.

location = "A small ranch in Kentucky"

latitude
longitude

The lat/lon should be set in decimal degrees, negative for southern and western hemispheres, respectively. Required. No default.

latitude = 38.8977
longitude = -77.0366

altitude

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:

altitude = 700, foot

An example in meters:

altitude = 220, meter

station_type

Set to the type of hardware you are using.

station_type = Simulator

Whatever option you choose, you must have a matching section in your configuration file. For example, if you choose station_type = Simulator, then you will need a [Simulator] 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 wee_config with the --reconfigure option. If the needed section is missing, this utility will automatically inject it into the configuration file.

Valid options include:

Option Description
Simulator A software weather station simulator. Useful for testing and debugging.
AcuRite AcuRite 5-in-1 stations with USB interface
CC3000 RainWise CC3000 data logger
FineOffsetUSB Fine Offset 10xx, 20xx, and 30xx stations
TE923 Hideki TE923 stations
Ultimeter PeetBros Ultimeter stations
Vantage Davis Vantage weather stations
WMR100 Oregon Scientific WMR100 series stations
WMR200 Oregon Scientific WMR200 series stations
WMR300 Oregon Scientific WMR300 series stations
WMR9x8 Oregon Scientific WMR-918/968 series stations
WS1 Argent Data Systems WS1 stations
WS23xx La Crosse 23xx stations
WS28xx La Crosse 28xx stations

station_url

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 station registry, it will also be included in the map of WeeWX stations.

Example:

station_url = http://www.mywebsite.com

rain_year_start

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.

rain_year_start = 1

week_start

Start of the week. 0=Monday, 1= Tuesday, ... , 6 = Sunday. Default is 6 (Sunday)

week_start = 0

[Simulator]

This section is for options relating to the software weather station simulator that comes with WeeWX.

loop_interval

The time (in seconds) between emitting loop packets. Default is 2.5

mode

One of either simulator or generator. Default is simulator.

simulator Real-time simulator. It will sleep between emitting packets.
generator Emit packets as fast as it can. Useful for testing.

start

The local start time for the generator in the format YYYY-mm-ddTHH:MM. An example would be 2012-03-30T18:30. This would code 30-March-2012, at 6:30pm, local time. Optional. Default is the present time.

[AcuRite]

This section is for options relating to the AcuRite 5-in-1 series of weather stations with USB connectors.

model

Set to the station model. For example, "AcuRite 01035", "AcuRite 01036", or "02032C"

use_constants

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 use_constants is True, 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.

[CC3000]

This section is for options relating to the RainWise Mark III weather stations and CC3000 data logger.

port

The serial port, e.g., /dev/ttyS0. When using a USB-Serial converter, the port will be something like /dev/ttyUSB0. Default is /dev/ttyUSB0

polling_interval

The polling_interval determines how often WeeWX will query the station for data. The default is 1 second.

sensor_map

This option defines the mapping between temperature values in the database and the remote sensors. Two additional temperature sensors are supported.

For example, this would associate extraTemp1 with the second optional temperature sensor:

[[sensor_map]]
    extraTemp1 = TEMP 2

See the Hardware Guide for a complete listing of sensor names and the default database fields for each sensor.

[FineOffsetUSB]

This section is for options relating to the Fine Offset series of weather stations with USB connectors.

The following settings are highly 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.

[FineOffsetUSB]
    polling_mode = PERIODIC
    polling_interval = 60
[StdArchive]
    record_generation = software

model

Set to the station model. For example, WH1080, WS2080, WH3081, etc.

polling_mode

One of PERIODIC or ADAPTIVE. In PERIODIC mode, WeeWX queries the console at regular intervals determined by the polling_interval. In ADAPTIVE 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 Polling Mode and interval in the Hardware Guide for more details. The default is PERIODIC.

polling_interval

The frequency, in seconds, at which WeeWX will poll the console for data. Default is 60. This setting applies only when the polling_mode is PERIODIC.

data_format

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 data_format to indicate which type of hardware you have. Possible values are 1080 (for the 10xx and 20xx consoles) and 3080 (for the 30xx consoles). Default is 1080.

[TE923]

This section is for options relating to the Hideki TE923 series of weather stations.

model

Set to the station model. For example, Meade TE923W or TFA Nexus. Default is "TE923".

sensor_map

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.

For example, this would associate outTemp and outHumidity with sensor 4:

[[sensor_map]]
    outTemp = t_4
    outHumidity = h_4

See the Hardware Guide for a complete listing of sensor names and the default database fields for each sensor.

[Ultimeter]

This section is for options relating to the PeetBros Ultimeter weather stations.

port

The serial port, e.g., /dev/ttyS0. When using a USB-Serial converter, the port will be something like /dev/ttyUSB0. Default is /dev/ttyUSB0

model

Set to the station model. For example, Ultimeter 2000 or Ultimeter 800. Default is "Ultimeter".

[Vantage]

This section is for options relating to the Davis Vantage series of hardware (VantagePro, VantagePro2 or VantageVue).

type

Set to either serial, for a serial or USB connection to the VantagePro (by far the most common), or to ethernet for the WeatherLinkIP. No default.

port

If you chose serial, for type, then set to the serial port name used by the station. For example, /dev/ttyUSB0 is a common location for USB ports, /dev/ttyS0 for serial ports. Otherwise, not required. No default.

host

If you chose ethernet, then specify either the IP address (e.g., 192.168.0.1) or hostname (e.g., console.mydomain.com) to the console. Otherwise, not required. No default.

baudrate

Set to the baudrate of the station. The default is 19200.

tcp_port

The port where WeatherLinkIP will be listening. Default is 22222.

tcp_send_delay

How long to block after sending a socket packet to the WeatherLinkIP. Default is 1 second.

iss_id

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.

timeout

How many seconds to wait for a response from the station before giving up. Default is 5 seconds.

wait_before_retry

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.

max_tries

How many times to try again before giving up. Default is 4.

[WMR100]

This section is for options relating to the Oregon Scientific WMR100 series of weather stations with USB connectors.

model

Set to the station model. For example, WMR100 or WMRS200.

sensor_map

This option defines the mapping between observations from remote sensors and the fields in the database.

For example, this would associate extraTemp1 with the remote T/H sensor on channel 5:

[[sensor_map]]
    extraTemp1 = temperature_5

See the Hardware Guide for a complete listing of sensor names and the default database fields for each sensor.

[WMR200]

This section is for options relating to the Oregon Scientific WMR200 series of weather stations with USB connectors.

model

Set to the station model. For example, WMR200 or WMR200A.

use_pc_time

If True, use the computer time, otherwise use the station time. Default is True.

archive_interval

Set the wmr200 archive interval in seconds. Default is 60 seconds.

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.

erase_archive

If True, erase onboard console memory archive on startup. Default is False.

archive_startup

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.

archive_threshold

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).

sensor_status

If True, emit sensor faults and failures to log. Default is True.

sensor_map

This option defines the mapping between observations from remote sensors and the fields in the database.

For example, this would associate extraTemp1 with the remote T/H sensor on channel 5:

[[sensor_map]]
    extraTemp1 = temperature_5

See the Hardware Guide for a complete listing of sensor names and the default database fields for each sensor.

[WMR300]

This section is for options relating to the Oregon Scientific WMR300 series of weather stations with USB connectors.

model

Set to the station model. For example, WMR300 or WMR300A.

sensor_map

This option defines the mapping between temperature/humidity values in the database and the remote sensors. Up to 8 remote sensors are supported.

For example, this would associate outTemp and outHumidity with sensor 4:

[[sensor_map]]
    outTemp = temperature_4
    outHumidity = humidity_4

See the Hardware Guide for a complete listing of sensor names and the default database fields for each sensor.

[WMR9x8]

This section is for options relating to the Oregon Scientific WMR-918/968 series of weather stations with serial connectors.

type

For the moment, only serial is supported.

port

Along with the serial option above, you must set the serial port name used by the station. For example, /dev/ttyUSB0 is a common location for USB ports, /dev/ttyS0 for serial ports. No default.

model

Set to the station model. For example, WMR968 or WMR918.

sensor_map

This option defines the mapping between observations from remote sensors and the fields in the database.

For example, this would associate extraTemp1 with the remote T/H sensor on channel 5:

[[sensor_map]]
    extraTemp1 = temperature_5
    extraHumid1 = humidity_5

See the Hardware Guide for a complete listing of sensor names and the default database fields for each sensor.

[WS1]

This section is for options relating to the Argent Data Systems WS1 weather stations.

port

The serial port, e.g., /dev/ttyS0. When using a USB-Serial converter, the port will be something like /dev/ttyUSB0. Default is /dev/ttyUSB0

polling_interval

The polling_interval determines how often WeeWX will query the station for data. The default is 1 second.

[WS23xx]

This section is for options relating to the La Crosse WS-23xx series of weather stations.

port

The serial port, e.g., /dev/ttyS0. When using a USB-Serial converter, the port will be something like /dev/ttyUSB0. Default is /dev/ttyUSB0

model

Set to the station model. For example, WS-2315, LaCrosse WS2317, etc. Default is "LaCrosse WS23xx".

polling_interval

The polling_interval determines how often WeeWX will query the station for data. If no polling_interval 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.

[WS28xx]

This section is for options relating to the La Crosse WS-28xx series of weather stations.

transceiver_frequency

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.

model

Set to the station model. For example, LaCrosse WS2810, TFA Primus, etc. Default is "LaCrosse WS28xx".

[StdRESTful]

This section is for configuring the StdRESTful services, which upload to simple RESTful servers such as the Weather Underground, PWSweather.com, or CWOP.

log_success

If you set a value for log_success here, it will override the value set at the top-level and will apply only to RESTful services. In addition, log_success can be set for individual services by putting them under the appropriate subsection (e.g., [[CWOP]]).

log_failure

If you set a value for log_failure here, it will override the value set at the top-level and will apply only to RESTful services. In addition, log_failure can be set for individual services by putting them under the appropriate subsection (e.g., [[CWOP]]).

[[StationRegistry]]

A registry of WeeWX weather stations is maintained at weewx.com. Stations are displayed on a map and a list at http://weewx.com/stations.html

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.

To add your station to this list, you must do two things:

  1. Enable the StationRegistry in weewx.conf by setting the option register_this_station to True. 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.
  2. Provide a station_url, either in section [Station], or in the [[StationRegistry]] section.

The station_url is used to uniquely identify each station, so choose it carefully before you set register_this_station to True.

[StdRestful]
    [[StationRegistry]]
        register_this_station = True

register_this_station

Set this to True to register the weather station.

description

A description of the station. If no description is specified, the location from the [Station] section will be used.

station_url

The URL to the weather station. If no URL is specified, the station_url from the [Station] section will be used.

log_success

In case of success, make a note in the system log. The default is True.

log_failure

In case of failure, make a note in the system log. The default is True.

[[AWEKAS]]

WeeWX can send your current data to the Automatisches Wetterkarten System (AWEKAS). If you wish to do this, set the option enable to true, then set options username and password appropriately. When you are done, it will look something like

[StdRestful]
    [[AWEKAS]]
        enable = true
        username = joeuser
        password = XXX 

enable

Set to true to enable posting to AWEKAS. Optional. Default is false.

username

Set to your AWEKAS username (e.g., joeuser). Required.

password

Set to your AWEKAS password. Required.

language

Set to your preferred language. Default is en.

log_success

In case of success, make a note in the system log. The default is True.

log_failure

In case of failure, make a note in the system log. The default is True.

retry_login

How long to wait in seconds before retrying a bad login. Default is 3600 seconds (one hour).

[[CWOP]]

WeeWX can send your current data to the Citizen Weather Observer Program. If you wish to do this, set the option enable to true, then set the option station to your CWOP station code. If your station is an amateur radio APRS station, you will have to set passcode as well. When you are done, it will look something like

[StdRestful]
    [[CWOP]]
        enable = true
        station = CW1234
        passcode = XXX    # Replace with your passcode (APRS stations only)
        post_interval = 600

enable

Set to true to enable posting to the CWOP. Optional. Default is false.

station

Set to your CWOP station ID (e.g., CW1234) or amateur radio callsign (APRS). Required.

passcode

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.

post_interval

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.

stale

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.

server_list

A comma-delimited list of the servers that should be tried for uploading data. Optional. Default is: cwop.aprs.net:14580, cwop.aprs.net:23

log_success

In case of success, make a note in the system log. The default is True.

log_failure

In case of failure, make a note in the system log. The default is True.

[[PWSweather]]

WeeWX can send your current data to the PWSweather.com service. If you wish to do this, set the option enable to true, then set the options station and password appropriately. When you are done, it will look something like

[StdRestful]
    [[PWSweather]]
        enable = true
        station = BOISE
        password = XXX

enable

Set to true to enable posting to the PWSweather. Optional. Default is false.

station

Set to your PWSweather station ID (e.g., BOISE). Required.

password

Set to your PWSweather password. Required.

log_success

In case of success, make a note in the system log. The default is True.

log_failure

In case of failure, make a note in the system log. The default is True.

retry_login

How long to wait in seconds before retrying a bad login. Default is 3600 seconds (one hour).

[[WOW]]

WeeWX can send your current data to the British Weather Observations Website (WOW) service. If you wish to do this, set the option enable to true, then set options station and password appropriately. Read Importing Weather Data into WOW 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

[StdRestful]
    [[WOW]]
        enable = true
        station = 12345678
        password = XXX

enable

Set to true to enable posting to WOW. Optional. Default is false.

station

Set to your WOW station ID (e.g., 12345678 for Pre June 1996 sites, or 6a571450-df53-e611-9401-0003ff5987fd for later ones). Required.

password

Set to your WOW Authentication Key. Required. This is not the same as your WOW password but a 6 digit numerical PIN.

log_success

In case of success, make a note in the system log. The default is True.

log_failure

In case of failure, make a note in the system log. The default is True.

retry_login

How long to wait in seconds before retrying a bad login. Default is 3600 seconds (one hour).

[[Wunderground]]

WeeWX can send your current data to the Weather Underground. If you wish to do this, set the option enable to true, then set the options station and password appropriately. When you are done, it will look something like

[StdRestful]
    [[Wunderground]]
        enable = true
        station = KCASANFRA11
        password = XXX
        rapidfire = False

enable

Set to true to enable posting to the Weather Underground. Optional. Default is false.

station

Set to your Weather Underground station ID (e.g., KCASANFRA11). Required.

password

Set to your Weather Underground password. Required.

rapidfire

Set to True to have WeeWX post using the Weather Underground's "Rapidfire" protocol. 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 False.

rtfreq

When rapidfire is set, the rtfreq parameter is sent, and should correspond to "the frequency of updates in seconds". Optional. Default is 2.5

archive_post

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 rapidfire. However, if for some reason you want to do both, then you may set both options to True.

post_indoor_observations

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 True. Default is False.

log_success

In case of success, make a note in the system log. The default is False for Rapidfire mode, True for PWS mode.

log_failure

In case of failure, make a note in the system log. The default is False for Rapidfire mode, True for PWS mode.

retry_login

How long to wait in seconds before retrying a bad login. Default is 3600 seconds (one hour).

[[[Essentials]]]

Occasionally (but not always!) when the Weather Underground is missing a data point it will substitute the value zero (0.0), 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,

[[[Essentials]]]
    outTemp = True

would cause the post to be skipped if there is no outside temperature (observation type outTemp).

[StdReport]

This section is for configuring the StdReport 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.

Each report is represented by a sub-section, marked with double brackets (e.g., [[MyReport]]). 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.

WeeWX ships with the following sub-sections:

Sub-section Description
[[SeasonsReport]] A full-featured single-page skin. Statistics and plots are revealed by touch or button press.
[[SmartphoneReport]] A skin formatted for smaller screens, with a look-and-feel reminiscent of first-generation Apple iPhone.
[[MobileReport]] A static skin formatted for very small screens, with a look-and-feel reminiscent of WindowsCE or PalmOS.
[[StandardReport]] The original skin that shipped for many years as the default report. It uses static HTML and images, and requires few resources to generate and display.
[[FTP]] No presentation elements. Uses the reporting machinery to transfer files to a remote server using FTP.
[[RSYNC]] No presentation elements. Uses the reporting machinery to transfer files to a remote server using rsync.

Order matters. The reports that generate HTML and images, that is, SeasonsReport, SmartphoneReport, MobileReport, and StandardReport, are run first, 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.

Details for how to customize reports are in the section Customizing reports, in the Customization Guide.

SKIN_ROOT

The directory where the skins live. A relative path is relative to WEEWX_ROOT.

HTML_ROOT

The target directory for the generated files. A relative path is relative to WEEWX_ROOT. Generated files and images will be put here.

data_binding

The data source to be used for the reports. It should match a binding given in section [DataBindings] below. The binding can be overridden in individual reports. Optional. Default is wx_binding.

report_timing

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 Customizing the report generation time section in the Customization Guide for details. Optional. The default value results in each report running on each archive interval.

[[SeasonsReport]]
[[SmartphoneReport]]
[[MobileReport]]
[[StandardReport]]

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 [Defaults].

They all have the following options in common.

skin

Where to find the skin. This should be a subdirectory under SKIN_ROOT. Inside the directory should be any templates used by the skin and a skin configuration file, skin.conf.

enable

Set to true to enable the processing of this skin. Set to false to disable. If this option is missing, True is assumed.

HTML_ROOT

Where to put the results. If not specified, the value for HTML_ROOT above will be used.

[[FTP]]

While this "report" does not actually generate anything, it uses the report machinery to upload files from directory HTML_ROOT 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.

enable

Set to true (the default) to enable FTP. Set to false to disable.

user

Set to the username you use for your FTP connection to your web server. Required. No default.

password

Set to the password you use for your FTP connection to your web server. Required. No default.

server

Set to the name of your web server (e.g., www.threefools.org, in my case). Required. No default

path

Set to the path where the weather data will be stored on your webserver (e.g., /weather). NB: some FTP servers require a leading slash ('/'), some do not. Required. No default.

secure_ftp

Set to True to use FTP (FTPS) over TLS. This is an extension to the FTP protocol that uses a Secure Socket Layer (SSL) protocol, not 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 False

secure_data

If a secure session is requested (option secure_ftp=True), should we attempt a secure data connection as well? This option is useful due to a bug in the Python FTP client library. See Issue #284. Optional. Default is True.

port

Set to the port ID of your FTP server. Default is 21.

passive

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 Active FTP vs. Passive FTP, a Definitive Explanation for a good explanation of the difference. Default is 1 (passive mode).

max_tries

WeeWX will try up to this many times to FTP a file up to your server before giving up. Default is 3.

[[RSYNC]]

While this "report" does not actually generate anything, it uses the report machinery to upload files from directory HTML_ROOT to a remote webserver using rsync. 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.

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.

enable

Set to true (the default) to enable rsync. Set to false to disable.

server

Set to the name of your server. This name should appear in your .ssh/config file. Required. No default

user

Set to the ssh username you use for your rsync connection to your web server. The local user that WeeWX runs as must have passwordless ssh configured for user@server. Required. No default.

path

Set to the path where the weather data will be stored on your webserver (e.g., /var/www/html/weather). Make sure user has write privileges in this directory. Required. No default.

delete

Files that don't exist in the local report are removed from the remote location. USE WITH CAUTION: If you make a mistake in setting the path, 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.

[StdConvert]

This section is for configuring the StdConvert 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.

Once chosen, it cannot be changed! 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 Changing the unit system in the Customization Guide.

Note!
This service only affects the units used in the databases. 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, skin.conf, as described in the Customization Guide, under section How to change units. Because of this, unless you have a special purpose application, there is really no good reason to change from the default, which is US.

Warning!
If, despite these precautions, you do decide to change the units of data stored in the database, be sure to read the sections [StdCalibrate] and [StdQC], and change the units there as well!

target_unit

Set to either US, METRICWX, or METRIC. The difference between METRICWX, and METRIC is that the former uses mm instead of cm for rain, and m/s instead of km/hr for wind speed. See the Appendix Units in the Customization Guide for the exact differences beween these three choices. Default is US.

[StdCalibrate]

This section is for configuring the StdCalibrate service. This service offers an opportunity to correct for any calibration errors in your instruments. It is very general and flexible.

Because this service is normally run after StdConvert, the units to be used should be the same as the target unit system chosen in StdConvert above. It is also important that this service be run before the archiving service StdArchive, so that it is the corrected data that are stored.

In a default configuration, calibrations are applied to observations from the hardware. They are not applied to derived calculations since the StdWXCalculate service runs after StdCalibrate.

[[Corrections]]

In this section you list all correction expressions. For example, say that you know your outside thermometer reads high by 0.2°F. You could add the expression:

outTemp = outTemp - 0.2

Perhaps you need a linear correction around a reference temperature of 68°F:

outTemp = outTemp + (outTemp-68) * 0.02

It is even possible to do corrections involving more than one variable. Suppose you have a temperature sensitive barometer:

barometer = barometer + (outTemp-32) * 0.0091

All correction expressions are run in the order given.

Both LOOP data and archive data will be corrected.

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.

[StdQC]

This section is for configuring the StdQC service. This service offers a very simple Quality Control that only checks that values are within a minimum and maximum range.

Because this service is normally run after StdConvert, the units to be used should be the same as the target unit system chosen in StdConvert. It is also important that it be run after the calibration service, StdCalibrate and before the archiving service StdArchive, so that it is the calibrated and corrected data that are stored.

In a default configuration, quality control checks are applied to observations from the hardware. They are not applied to derived calculations since the StdWXCalculate service runs after the quality control.

[[MinMax]]

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 the same unit system as specified in section StdConvert.

For example,

[[MinMax]]
    outTemp = -40, 120
    barometer = 28, 32.5
    outHumidity = 0, 100 

With target_unit = US (the default), if a temperature should fall outside of the inclusive range -40 °F through 120 °F, then it will be set to the null value, None, and ignored. In a similar manner, the acceptable values for barometric pressure would be 28 through 32.5 inHg, for humidity 0 through 100%.

You can also specify units.

For example,

[[MinMax]]
    outTemp = -40, 60, degree_C
    barometer = 28, 32.5, inHg

In this example, if a temperature should fall outside of the inclusive range -40 °C through 60 °C, then it will be set to the null value, None, 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 target_unit.

Both LOOP and archive data will be checked.

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 0xff 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.

[StdWXCalculate]

The calculation service calculates derived quantities such as dewpoint, windchill, and heatindex.

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.

The section [StdWXCalculate] consists of a group of Observation defaults, followed by a subsection [[Calculations]] that specifies the calculation strategy to be used for each derived quantity.

ignore_zero_wind

Indicates whether the wind direction should be undefined when the wind speed is zero. The default value is True: the wind direction will be undefined when wind speed is zero.

To report the wind vane direction even when there is no wind speed, change this to False:

[StdWXCalculate]
    ...
    ignore_zero_wind = False

[[Calculations]]

This subsection specifies which strategy is to be used to provide values for derived variables. The service can calculate the following values:

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:

[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

The options for each quantity are hardware, software, or prefer_hardware

hardware Never calculate the value.
software Always calculate the value.
prefer_hardware Calculate the value only if it is not provided by hardware.

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:

[StdWXCalculate]
    ...
    [[Calculations]]
        ...
        windchill = software

[StdArchive]

This section is for configuring StdArchive, the service that stores data in a database.

archive_interval

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, and it must be evenly divisible by 60. Optional. Default is 300 seconds.

archive_delay

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.

record_generation

Set to whether records should be downloaded off the hardware (recommended), or generated in software. If set to hardware, 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 hardware will work for most users. A notable exception is users who have cobbled together homebrew serial interfaces for the Vantage stations that do not include memory for a logger. These users should set this option to software, forcing software record generation. Default is hardware.

record_augmentation

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 True.

loop_hilo

Set to True to have LOOP data and archive data to be used for high / low statistics. Set to False to have only archive data used. If your sensor emits lots of spiky data, setting to False may help. Default is True.

data_binding

The data binding to be used to store the data. This should match one of the bindings in the [DataBindings] section, below. Optional. Default is wx_binding.

[StdTimeSynch]

This section is for configuring StdTymeSynch, a service that can synchronize the onboard clock of station with your computer. Not all weather station hardware supports this.

clock_check

How often to check the clock on the weather station in seconds. Default is 14,400 seconds (every 4 hours)

max_drift

The maximum amount of clock drift to tolerate, in seconds, before resetting the clock. Default is 5.

[DataBindings]

A "data binding" associates storage characteristics with a specific database. Each binding contains a database from the [Databases] section plus parameters such as schema, table name, and mechanism for aggregating data.

[[wx_binding]]

This is the binding normally used for weather data. A typical [[wx_binding]] section looks something like this:

[[wx_binding]]
    database = archive_sqlite
    table_name = archive
    manager = weewx.wxmanager.WXDaySummaryManager
    schema = schemas.wview.schema

What follows is more detailed information about each of the binding options.

database

The actual database to be used — it should match one of the sections in [Databases]. Should you decide to use a MySQL database, instead of the default SQLite database, this is the place to change it. See the section Configuring MySQL for details. Required.

table_name

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 archive

manager

The name of the class to be used to manage the table. Optional. Default is class weewx.wxmanager.WXDaySummaryManager. 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.

schema

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 schemas.wview.schema, the schema used by the wview weather system.

[Databases]

This section lists actual databases. The name of each database is given in double brackets, for example, [[archive_sqlite]]. Each database section contains the parameters necessary to create and manage the database. The number of parameters varies depending on the type of database.

[[archive_sqlite]]

This definition uses the SQLite database engine to store data. SQLite is open-source, simple, lightweight, highly portable, and memory efficient. For most purposes it serves nicely.

database_type

Set to SQLite to signal that this is a SQLite database.

database_name

The path to the SQLite file relative to the SQLITE_ROOT option. Default is weewx.sdb.

[[archive_mysql]]

This definition uses the MySQL database engine to store data. It is free, highly-scalable, but more complicated to administer.

database_type

Set to MySQL to signal that this is a MySQL database.

database_name

The name of the database. Default is weewx. Required.

[DatabaseTypes]

This section defines defaults for the various kinds of databases.

[[SQLite]]

This section defines default values for SQLite databases. They can be overridden by individual databases.

driver

The sqlite driver name. Required.

SQLITE_ROOT

The location of the directory holding the SQLite databases. For setup.py installations, the default is the WEEWX_ROOT/archive directory. For DEB or RPM installations, it is /var/lib/weewx.

timeout

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 timeout option specifies how long other threads should wait for the lock to go away before raising an exception. The default is 5 seconds.

isolation_level

Set the current isolation level. See the pysqlite documentation on isolation levels for more information. There is no reason to change this, but it is here for completeness. Default is None (autocommit).

[[MySQL]]

This section defines default values for MySQL databases. They can be overridden by individual databases.

Note that if you choose the MySQL 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.

driver

The MySQL driver name. Required.

host

The name of the server on which the database is located. Default is localhost.

user

The user name to be used to log into the server. Required.

password

The password. Required.

port

The port number to be used. Optional. Default is 3306.

engine

The type of MySQL database storage engine to be used. This should not be changed without a good reason. Default is INNODB.

[Defaults]

This section covers a suite of default values, 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.

[Engine]

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 Customizing the WeeWX service engine of the Customization Guide.

[[Services]]

Internally, WeeWX consists of many services, 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 service_list, which held the names of all the services that should be run. Since then, this list has been broken down into smaller lists.

Services are run in the order given below.

Service list Function
prep_services Perform any actions before the main loop is run.
data_services Augment data, before it is processed.
process_services Process, filter, and massage the data.
archive_services Record the data in a database.
restful_services Upload processed data to an external RESTful service.
report_services Run any reports.

For reference, here is the standard set of services that are run with the default distribution.

Service list Function
prep_services weewx.engine.StdTimeSynch
data_services
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

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.

prep_services

These services get called before any others. They are typically used to prepare the console. For example, the service weewx.wxengine.StdTimeSynch, which is responsible for making sure the console's clock is up to date, is a member of this group.

data_services

Augment data before processing. Typically this means adding fields to a LOOP packet or ARCHIVE record.

process_services

Services in this group tend to process any incoming data. They typically do things like quality control, or unit conversion, or sensor calibration.

archive_services

Once data have been processed, services in this group archive them.

restful_services

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.

report_services

The various reporting services run in this group, including the standard reporting engine.

Troubleshooting

This section lists some common problems installing and running WeeWX. If you are stuck, be sure to:

If you are still stuck, post your problem to the weewx-user group. The Wiki has some guidelines on how to do an effective post.

Hardware problems

Tips on making a system reliable

If you are having problems keeping your weather station up for long periods of time, here are some tips, in decreasing order of importance:

Cable connection looped through a ferrite coil
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.

Establishing connectivity

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 minicom because it can be run from through a simple TTY connection. The utility screen also works well. For example:

minicom -b 19200 -D /dev/ttyUSB0

or, using screen:

screen /dev/ttyUSB0 19200

First, press <enter> a few times, in order to wake up the console. Then type TEST, all in capital letters. The characters will not be echoed back. Then press <enter> once more. The Davis should echo back TEST.

If this works, then you have established connectivity with the Davis and the problem must lie elsewhere.

Davis cp2101 converter problems

The USB converter used in the Davis VantagePro is known to have some "noise" problems. The symptom is that the Linux kernel will disconnect from your old USB port claiming "EMI noise", and reconnect to a new and different port, where WeeWX cannot find it. Here is a typical log output:

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

In this example, the VantagePro was connected to /dev/ttyUSB0, but then reconnected to /dev/ttyUSB1.

If you put ferrite coils on the USB connection, you will eliminate 90% of this problem. I did this about 8 years ago, and have not had a problem since.

However, there is one final step that you can take to really harden up your system: install a udev script that will create a symbolic link to the VantagePro USB port, whatever it might be. With this approach, if the port jumps from ttyUSB0 to ttyUSB1, the symbolic link will follow it. You just specify port /dev/vpro in the configuration file weewx.conf and be done with it.

Installing a udev script

Use a udev rule to ensure that a USB device always appears at the same location such as /dev/vpro instead of /dev/ttyUSB2

For example, for my VantagePro2 weather station, I have installed a file /etc/udev/rules.d/vpro.rules on my fit-PC that looks like this:

# Automount the VantagePro2 to port /dev/vpro.
# Install in /etc/udev/rules.d/vpro.rules
#
ACTION=="add", ATTRS{interface}=="CP2102 USB to UART Bridge Controller", SYMLINK+="vpro"

This rule says that when the USB port is plugged in (action add), and it has an attribute with name interface that is equal to CP2102 to UART Bridge Controller, then add a symbolic link for its physical port to /dev/vpro.

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 vpro, but also sets the chmod permissions to 666, allowing any user to read or write to it.

# 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"

Your devices may, and probably will, have different identifiers!! I can recommend this article, "Writing udev rules," for how to find and write an appropriate udev rule for your controller. (Note, however, that this article uses the old udevinfo command, rather than the newer udevadm command.) In particular, run the command

udevadm info --attribute-walk --path $(udevadm info --query=path --name=/dev/ttyUSB0)

where /dev/ttyUSB0 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 udev. While the first example script above used a rule that matched attribute interface, others are possible. For example, the second example, for the serial-to-USB cable, chose to match the attribute product.

Once you have installed your udev rule, you can then set port=/dev/vpro in weewx.conf, confident that it will always point to your weather station, no matter which USB port it is actually attached to!

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.

Or, at least, it should!

WeeWX generates HTML pages, but it does not update them

If you are getting a symptom that everything appears normal, that is image and HTML files are generated (look in the log to be sure) 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.

Clock skew

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.

The solution is to delete any records with time stamp in the future. For a sqlite database, the procedure looks like this:

cp /home/weewx/archive/weewx.sdb /home/weewx/archive/weewx.sdb.backup
sqlite3 /home/weewx/archive/weewx.sdb
sqlite> delete from archive where dateTime > X;
sqlite> .exit

The timestamp X is the current time in unix epoch time (number of seconds since 1 January 1970). This website is useful for determining the current unix epoch time.

Corrupt station memory

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 "since" 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 — this is how the software knows it has downloaded the last record and so it stops.

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 debug=1):

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

Note how WeeWX did a DMPAFT command ("Getting archive packets since 2016-11-25 19:55:00"). The console responded that it has lots of records after that time ("Retrieving 45 page(s); starting index= 1"), but when WeeWX actually tries to retrieve them, they are all before the requested time.

There seems to be two fixes:

  1. 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.
  2. If all else fails, clear the memory of the console using the utility wee_device. This may cause loss of data, but usually works. Adjust paths as necessary:
wee_device --clear-memory

See also the section Dumping the logger memory, which may help you avoid data loss.

3rd party Vantage connectors

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 DSI-01 serial interface. That is, it is a pure serial connection to the console, with no onboard memory.

For these interfaces, you must set record generation to software. 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:

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

See the section on option record_generation.

Raspberry Pi

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.

See the Wiki for up-to-date information on Running WeeWX on a Raspberry Pi.

Fine Offset USB lockups

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:

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

The exact error may vary, but the thing to look for is the "could not detach kernel driver" 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.

More details about Fine Offset lockups can be found in the Wiki.

Archive interval

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 archive_interval. If not, WeeWX will fall back to the archive_interval specified in [StdArchive]. The default fallback value is 300 seconds (5 minutes).

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.

Since reports are generated when a new archive record arrives, a large archive interval means that reports will be generated infrequently.

If you want data and reports closer to real-time, use the wee_device utility to change the interval.

Software problems

This section covers some common software configuration problems.

Nothing in the log file

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:

-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

The location of this logging file varies from system to system, but it is typically in /var/log/syslog, or something similar.

However, some systems default to saving only warning or critical information, so the info messages from WeeWX may not appear. If this happens to you, check your system logging configuration. On Debian systems, look in /etc/rsyslog.conf. On Redhat systems, look in /etc/syslog.conf.

configobj errors

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.

configobj.DuplicateError exception

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:

[Reports]
    [[FTP]]
        ... (details elided)
        user = fred
        server = ftp.myhost.com
        password = mypassword
        server = ftp.myhost.com # OOPS! Listed it twice!
        path = /weather
... 

Generally, if you encounter this error, the log file will give you the line number it happened in:

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. 

configobj.NestingError exception

This is a very similar error, and is caused by a misformed section nesting. For example:

[Reports] [[FTP]]] ... (details elided)

Note the extra closing bracket on the subsection FTP.

No barometer data

If everything appears normal except that you have no barometer data, the problem may be a mismatch between the unit system used for service StdConvert and the unit system used by service StdQC. For example:

[StdConvert]
    target_unit = METRIC
    ...

[StdQC]
    [[MinMax]]
        barometer = 28, 32.5

The problem is that you are requiring the barometer data to be between 28 and 32.5, but with the unit system set to METRIC, the data will be in the range 990 to 1050 or so!

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:

[StdConvert]
    target_unit = US
    ...

[StdQC]
    [[MinMax]]
        barometer = 950, 1100, mbar

Cheetah.NameMapper.NotFound errors

If you get errors of the sort:

Apr 12 05:12:32 raven reportengine[3074]: filegenerator: Caught exception "<class 'NameMapper.NotFound'>"
Apr 12 05:12:32 raven reportengine[3074]: **** Message: "cannot find 'fubar' in template /home/weewx/skins/Standard/index.html.tmpl"
Apr 12 05:12:32 raven reportengine[3074]: **** Ignoring template and continuing.

you have a tag in your template that WeeWX does not recognize. In this example, it is the tag $fubar in the template /home/weewx/skins/Standard/index.html.tmpl.

Many LOOP read errors with Davis Vantage

The symptom is many LOOP errors and unreliable downloading of archive records. Your log may look like this:

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

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.

The cure is simple: kill all but one of them. Or, better yet, kill them all, then start WeeWX.

Dots in the plots

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.

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.

Change the line_gap_fraction option in skin.conf to control how much time is considered a break in data.

As for the archive interval, check the log file for an entry like this soon after WeeWX starts up:

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

In this example, interval in weewx.conf is 5 minutes, but the station interval is 30 minutes. When the interval in weewx.conf does not match the station's hardware interval, WeeWX defers to the station's interval.

Use the wee_device utility to change the station's interval.

Spikes in the graphs

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.

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.

If you frequently see anomalous data, first check the hardware.

To keep bad data from the database, add a quality control (QC) rule such as Min/Max bounds. See the QC section for details.

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:

  1. stop WeeWX
  2. Make a copy of the archive database
    cp weewx.sdb weewx-YYMMDD.sdb
  3. Verify the bad data exist where you think they exist
    sqlite3 weewx.sdb
    sqlite> select dateTime,outTemp from archive where outTemp > 1000;
  4. See whether the bad temperature and wind data happened at the same time
    sqlite> select dateTime,outTemp,windSpeed from archive where outTemp > 1000;
  5. Remove the bad data by setting to NULL
    sqlite> update archive set windSpeed=NULL where outTemp > 1000;
    sqlite> update archive set outTemp=NULL where outTemp > 1000;
  6. Delete the aggregate statistics so that WeeWX can regenerate them without the anomalies
    sudo wee_database --drop-daily
  7. start WeeWX

'Database is locked' error

This seems to be a problem with the Raspberry Pi, when using SQLite. There is no analogous problem with MySQL databases. You will see errors in the system log that looks like this:

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)
Feb 12 07:11:06 rpi weewx[20930]: ****  OperationalError: database is locked

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.

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.

There are a few possible fixes:

None of these 'fixes' are very satisfying and we're trying to come up with a more robust solution.

Strings in the database

If you modify the SQLite archive database using an editing tool, occasionally strings will get embedded in it, causing WeeWX to raise an exception. This is only a problem with SQLite. There is no analogous problem with MySQL databases. You will see errors in the system log that look something like this:

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
Dec 31 17:01:06 arm weewx[18141]: **** TypeError: unsupported operand type(s) for +=: 'float' and 'unicode'
Dec 31 17:01:06 arm weewx[18141]: **** Exiting.

The problem is that a unicode null string u'' got entered where a NULL should be. The utility wee_database can fix this. Run it with the option --check-strings to search for these embedded strings. Add the option --fix-strings to have the utility fix them:

wee_database weewx.conf --check-strings --fix-strings

Python 2.6

Unfortunately, the current version of PySerial, 3.x, does not work with Python 2.6. If your hardware requires PySerial (check the Hardware Guide), you will have to downgrade to PySerial V2.7, which you can obtain from SourceForge.

FreeBSD

User Fabian reports that the following had to be done to get the VantagePro2 working under FreeBSD:

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="YES" in /boot/loader.conf (to load it as module).
Which gives here an output like:
uslcom0: <CP2102 USB to UART Bridge Controller> on usbus1
And put in weewx.conf:
port = /dev/cuaU0

Funky symbols in plots

If your plots have strange looking symbols for units, such as degrees Fahrenheit (°F), that look something like this:

funky degree sign

Then the problem may be that you are missing the fonts specified for the option unit_label_font_path in your skin.conf 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 [ImageGenerator] for a line that looks like:

unit_label_font_path = /usr/share/fonts/truetype/freefont/FreeMonoBold.ttf

Make sure that the specified path (/usr/share/fonts/truetype/freefont/FreeMonoBold.ttf 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:

sudo apt-get install fonts-freefont-ttf
sudo fc-cache -f -v

(On older systems, the package fonts-freefont-ttf may be called ttf-freefont). The first command installs the "Truetype" fonts, the second rebuilds the font cache. If your system does not have fc-cache command, then install it from the fontconfig package:

sudo apt-get install fontconfig

If none of this works, or if you are on a different operating system, then you will have to change the option unit_label_font_path to point to something on your system which does support the Unicode characters you plan to use.

UnicodeEncodeError

This problem is closely related to the "Funky symbols" problem above. In this case, you may see errors in your log that look like:

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]:         ****  UnicodeEncodeError: 'ascii' codec can't encode character u'\xe8' in position 5: ordinal not in range(128)
May 14 13:35:23 web weewx[5633]:         ****  Generator terminated...

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.

Data is archived but some/all reports do not run

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 report_timing option in weewx.conf. The report_timing option allows the user to specify when some or all reports are run (refer Customizing the report generation time). By default the report_timing option is disabled and all reports are run each archive period.

To see if the report_timing option is causing reports to be skipped inspect the log file. Any reports that are skipped due to the report_timing option will be logged as follows:

Apr 29 09:30:17 rosella weewx[3319]: reportengine: Report StandardReport skipped due to report_timing setting

If reports are being incorrectly skipped due to report_timing then edit weewx.conf and check for a report_timing option in [StdReport]. Either remove all occurrences of report_timing to run all reports each archive period or confirm the correct use and setting of the report_timing option.

The wrong reports are being skipped by report_timing

If the report_timing option is being used and the results are not as expected, there may be an error in the report_timing option. If there are errors in the report_timing parameter, the report will be run on each archive interval. First check the report_timing 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 Customizing the report generation time.

Check the log file for any entries relating to the reports concerned. Errors in the report_timing parameter and skipped reports are logged only when debug=1 in weewx.conf.

Meteorological problems

The pressure reported by WeeWX does not match the pressure on the console

Be sure that you are comparing the right values. There are three different types of pressure:

Station Pressure
The Station Pressure (SP), which is the raw, absolute pressure measured by the station. This is pressure in WeeWX packets and archive records.
Sea Level Pressure
The Sea Level Pressure (SLP) is obtained by correcting the Station Pressure for altitude and local temperature. This is barometer in WeeWX packets and archive records.
Altimeter
The Altimeter Setting (AS) is obtained by correcting the Station Pressure for altitude. This is altimeter in WeeWX packets and archive records.

Any station might require calibration. For some hardware, this can be done at the weather station console. Alternatively, use the StdCalibrate section to apply an offset.

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.

Calibrating barometer does not change the pressure displayed by WeeWX

Be sure that the calibration is applied to the correct quantity.

The corrections in the StdCalibrate section apply only to raw values from the hardware; corrections are not applied to derived quantities.

The station hardware matters. Some stations report gauge pressure (pressure) while other stations report sea-level pressure (barometer). For example, if the hardware is a Vantage station, the correction must be applied to barometer since the Vantage station reports barometer and WeeWX calculates pressure. However, if the hardware is a FineOffset station, the correction must be applied to pressure since the FineOffset stations report pressure and WeeWX calculates barometer.

The rainfall and/or rain rate reported by WeeWX do not match the console

First of all, be sure that you are comparing the right quantities. The value rain is the amount of rainfall observed in a period of time. The period of time might be a LOOP interval, in which case the rain is the amount of rain since the last LOOP packet. Or the period of time might be an archive interval, in which case the rain is the total of rain reported in each LOOP packet since the last archive record.

Some consoles report the amount of rain in the past hour, or the amount of rain since midnight.

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.

Be sure that the units are correct.

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 StdCalibrate section.

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.

There is no wind direction when wind speed is zero

This is by design — 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 StdWXCalculate service. If necessary, it can be overridden. See option ignore_zero_wind in the [StdWXCalculate] section.

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.