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 15,000 lines of code, plus another 15,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 vintage 32-bit Fit-PC with a 500 MHz AMD Geode processor and 512 MB of memory. Configured this way, it consumes about 5% of the CPU, 120 MB of virtual memory, and 30 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 of the "Standard" report take about 5.1 seconds on a RPi B+, compared to 3.0 seconds on the Fit-PC, and 0.3 seconds on a NUC with a 4th gen i5 processor.

Time

You should run some sort of time synchronization daemon to ensure that your computer has the correct time. Doing so will greatly reduce errors, especially if you send data to services such as the Weather Underground. Systemd systems can use systemd-timesyncd, other systems can use NTP.

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.7, or Python 3.5 or later is required.

Permissions

There are a few places where permissions affect WeeWX:

• Installation/Configuration. The user who does the installation must have write permission in order to do the install. Similarly, the user who modifies configuration files and skins must have write permission on those files and directories. The specific folders depend on the installation method, and are listed in the layout table below.
• Running. Most USB and serial devices require administrative (root) access. Unless the device has been configured with a udev rule or other mechanism that grants access to non-root users, WeeWX commands must be run as root or must be prefaced with sudo for temporary administrative privileges.

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:

• The patience to read and follow this guide;
• Willingness and ability to edit a configuration file;
• Some familiarity with Linux or other Unix derivatives;
• Ability to do simple Unix tasks such as changing file permissions and running commands;
• No programming experience is necessary unless you wish to extend WeeWX. In this case, you should be comfortable programming in Python.

If you get stuck, there is a very active User's Group to help.

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 is run from the command line, either as a daemon, or directly.
5. Tune the installation. Typically this is done by changing settings in the WeeWX 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, making it easier to modify WeeWX. If the user installing WeeWX has permission to write to the directory, root privileges will not be required to install, run, or modify WeeWX. However, root privileges might be required to communicate with hardware.

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.

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.

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:

sudo weewxd

If your configuration file is named something other than weewx.conf, or if it is in a non-standard place, then you will have to specify it explicitly on the command line. For example:

sudo weewxd /some/path/to/weewx.conf

If your station has a data logger, the program will start by downloading any data stored in your weather station into the archive database. For some stations, such as the Davis Vantage with a couple thousand records, this could take a minute or two.

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.

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.

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 machine as WeeWX. See the wiki article Configure a web server (Apache, NGINX or lighttpd) for how to do this.

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 image files:

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

It is possible to rsync or FTP more than one directory to the remote server. For example, suppose you have a home webcam that puts its images in /home/webcam/www. You want to FTP not only the files generated by WeeWX, but also these webcam images, to a remote server. The webcam images should go in a subdirectory webcam of the weewx directory. The solution is to include more than one FTP section under [StdReport]:

[StdReport]

    # Location of the generated reports, relative to WEEWX_ROOT
    HTML_ROOT = public_html

    ...

    # As before:
    [[FTP]]
        skin = Ftp
        server = wx.example.com
        path = /weewx
        user = wxuser
        password = wxpass

    # Add a second FTP. You can name it anything.
    [[webcam_FTP]]
        skin = Ftp
        # Override HTML_ROOT:
        HTML_ROOT=/home/webcam/www
        server = wx.example.com
        path = /weewx/webcam
        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

• configuration information;
• skins and templates;
• any custom code or extensions you have installed;
• the WeeWX database.

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 / MariaDB

This section applies only to those who wish to use the MySQL database, instead of the default SQLite database. It assumes that you have installed a working version of MySQL or MariaDB.

1. Install the client libraries. How to do this depends on your operating system. Use the table below as a guide.

   sudo apt install mysql-client
   sudo apt install python3-mysqldb

   sudo yum install MySQL-python
   

   sudo zypper install python3-mysqlclient

2. 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.manager.DaySummaryManager
           # The schema defines to structure of the database contents
           schema = schemas.wview_extended.schema

3. Configure the MySQL host and credentials. 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.

4. Configure MySQL to give the necessary permissions for the database weewx to whatever MySQL user you choose. Here are the necessary minimum permissions, again assuming user weewx with password weewx. Adjust as necessary.:

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

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 type of hardware you have;
• The name of your station;
• What kind of database to use and where is it located;
• How to recognize out-of-range observations, etc.

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

• Wunderground will not be logged (set explicitly)
• WOW will be logged (set explicitly)
• CWOP will be logged (inherits from [StdRESTful]

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

debug_serial, debug_openclose, debug_checksum

The debug_serial, debug_openclose and debug_checksum can be set to one to produce debugging information in the WeeWX log. The defaults for these options are zero.

logger_threshold

The logger_threshold specifies the number of records in the CC3000 station's memory at which the station memory's should be cleared. If logger_threshold is not specified, or if zero is specified, the station's memory will never be cleared. In this case, when the memory fills up, new archive records will no longer be saved in memory. Note: the CC3000's memory will hold about 35,000 records. The default is 0 (i.e., never clear memory).

max_tries

The max_tries option specifies how many times WeeWX should retry communiating with the CC3000 station when a serial communications error occurs. The default is 5 times.

model

The model option specifies the name of the hardware reported to WeeWX. The default is CC3000.

polling_interval

The polling_interval determines how often WeeWX will query the station for data. The default is 2 seconds. Note: 2 seconds is a good choice as this is the rate at which the CC3000 receives updates from the Rainwise Mark III Weather Station.

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.

use_station_time

The use_station_time specifies whether the loop packets read by weewx should use the time specified in the CC3000 station packet or the computer time. The default is True (i.e., to use CC3000 station time.

[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 0.5 second.

loop_request

The type of LOOP packet to use for LOOP data. Options are 1 (type LOOP1); 2 (type LOOP2); or 3 (alternate between). Type LOOP2 packets have the advantage of including gauge pressure, altimeter, heat index, THSW, and a few other types, so they do not have to be calculated in software. On the other hand, they do not include any of the extra Davis sensors, such as soil moisture, leaf temperature, etc.

If you decide to alternate between packet types (option 3), then the console will send a type LOOP1 packet, followed by a type LOOP2 packet. This means that for certain types, and depending on the options specified in [StdWXCalculate], the value that is used by WeeWX can flip between hardware and software values with every packet. In this case, you should be sure to specify option hardware for types pressure, altimeter, dewpoint, windchill, and heatindex. This way, only hardware values will be used.

Not all stations support LOOP2 data. You need firmware version 1.90 or later.

Default is 1 (use LOOP1 type packets).

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.

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

mode

Select whether to connect via a serial line (option serial), or via an IP connection using TCP (option tcp), or UDP (option udp). Default is serial.

port

The port to be used. For a serial connection, this will be something like /dev/ttyUSB0. For a TCP or UDP connection, it will be an IP address and port, such as 192.168.1.12:3000 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 https://weewx.com/stations.html

How does the registry work? Individual weather stations periodically contact the registry. Each station provides a unique 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 station registry by setting option register_this_station to True in weewx.conf . 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 value for option station_url in section [Station]. This value must be unique, so choose it carefully.

[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

If you set a value here, it will apply only to the station registry.

log_failure

If you set a value here, it will apply only to the station registry.

[[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

If you set a value here, it will apply only to logging for AWEKAS.

log_failure

If you set a value here, it will apply only to logging for AWEKAS.

retry_login

How long to wait in seconds before retrying a bad login. If set to zero, no retry will be attempted. Default is 3600 seconds (one hour).

post_interval

The interval in seconds between posts. Setting this value to zero will cause every archive record to be posted. Optional. Default is zero.

[[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

If you set a value here, it will apply only to logging for CWOP.

log_failure

If you set a value here, it will apply only to logging for CWOP.

[[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

If you set a value here, it will apply only to logging for PWSweather.

log_failure

If you set a value here, it will apply only to logging for PWSweather.

retry_login

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

post_interval

The interval in seconds between posts. Setting this value to zero will cause every archive record to be posted. Optional. Default is zero.

[[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 user password. It is a 6 digit numerical PIN, unique for your station.

log_success

If you set a value here, it will apply only to logging for WOW.

log_failure

If you set a value here, it will apply only to logging for WOW.

retry_login

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

post_interval

The interval in seconds between posts. Setting this value to zero will cause every archive record to be posted. Optional. Default is zero.

[[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
        api_key = 04255779e9aa45b6e4579938630e67b

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.

api_key

Set to your Weather Underground API key. This is needed only if you plan on using the utility wunderfixer.

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

If you set a value here, it will apply only to logging for the Weather Underground.

log_failure

If you set a value here, it will apply only to logging for the Weather Underground.

retry_login

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

post_interval

The interval in seconds between posts. Setting this value to zero will cause every archive record to be posted. Optional. Default is zero.

force_direction

The Weather Underground has a bug where they will claim that a station is "unavailable" if it sends a null wind direction, even when the wind speed is zero. This option causes the software to cache the last non-null wind direction and use that instead. Default is False.

[[[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 what 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.

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 reporting. In addition, log_success can be set for individual reports by putting them under the appropriate subsection (e.g., [[Seasons]]).

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 reporting. In addition, log_failure can be set for individual reports by putting them under the appropriate subsection (e.g., [[Seasons]]).

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 are included in the standard distribution of WeeWX, and which actually generate HTML files and plots. They all use US Customary units by default (but this can be changed by setting the option unit_system).

They all have the following options in common.

lang

Which language the skin should be localized in. The value is a two-character language code as defined in ISO 639-1. This option only works with skins that have been internationalized. All skins that ship with WeeWX have been internationalized, but only a handful of languages are included. To see which language a skin supports, look in the subdirectory lang in the skin's directory. For example, if you see a file fr.conf, then the skin can be localized in French.

unit_system

Which unit system to use with the skin. Choices are US, METRIC, or METRICWX. See the Appendix Units in the Customizing Guide for definitions of these unit systems. Individual units can be overridden. See "How to change units" in the "Customization Guide" for more details.

enable

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

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.

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

reuse_ssl

Some FTP servers (notably PureFTP) reuse ssl connections with FTPS. Unfortunately, the Python library has a bug that prematurely closes such connections. See https://bit.ly/2Lrywla. Symptom is an exception OSError: [Errno 0] Error. This option activates a workaround for Python versions greater than 3.6. It won't work for earlier versions. Optional. Default is False.

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.

ftp_encoding

The vast majority of FTP servers send their responses back using UTF-8 encoding. However, there are a few oddballs that respond using Latin-1. This option allows you to specify an alternative encoding.

ciphers

Some clients require a higher cipher level than the FTP server is capable of delivering. The symptom is an error something like ssl.SSLError: [SSL: DH_KEY_TOO_SMALL] dh key too small (_ssl.c:997). This option allows you to specify a custom level. For example, in this case, you might want to specify:

ciphers='DEFAULT@SECLEVEL=1'

However, if possible, you are always better off upgrading the FTP server.

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

port

The port to use for the ssh connection. Default is to use the default port for the ssh command (generally 22).

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.

[[Defaults]]

This section defines default values for all reports. You can set:

• The unit system to be used;
• Overrides for individual units;
• Which language to be used;
• Number and time formats;
• Labels to be used;
• Calculation options for some derived values.

See the Customization Guide for more details.

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

Some hardware provides derived quantities, such as dewpoint, windchill, and heatindex, while other hardware does not. This service can be used to fill in any missing quantities, or to substitute a software-calculated value for hardware that has unreliable or obsolete calculations.

By default, the service can calculate the following values, although the list can be extended:

• pressure
• barometer
• altimeter
• windchill
• heatindex
• dewpoint
• inDewpoint
• rainRate
• maxSolarRad
• cloudbase
• humidex
• appTemp
• ET
• windrun

The configuration section [StdWXCalculate] consists of two different parts:

1. The sub-section [[Calculations]], which specifies which derived types are to be calculated and under what circumstances;
2. Zero or more sub-sections, which specify what parameters are to be used for the calculation. These are described below.

The service StdWXCalculate can be extended by the user to add new, derived types by using the XTypes system. See the wiki article Extensible types (XTypes) for how to do this.

data_binding

The data source to be used for historical data when calculating derived quantities. It should match a binding given in section [DataBindings] below. Optional. Default is wx_binding.

Note:
The data binding used by the StdWXCalculate service should normally match the data binding used by the StdArchive service. User's who use custom or additional data bindings should take care to ensure the correct data bindings are used by both services.

[[Calculations]]

This subsection specifies which strategy is to be used to provide values for derived variables. It consists of zero or more options with the syntax:

obs_type = directive[, optional_bindings]...

where

• directive is one of prefer_hardware, hardware, or software:

  prefer_hardware	Calculate the value in software only if it is not provided by hardware.
  hardware	Hardware values only are accepted: never calculate the value in software.
  software	Always calculate the value in software.

• optional_binding is optional, and consists of either loop, or archive. If loop, then the calculation will be done only for LOOP packets. If archive, then the calculation will be done only for archive records. If no binding is specified, then it will be done for both LOOP packets and archive records.

Example 1: if your weather station calculates windchill using the pre-2001 algorithm, and you prefer to have WeeWX calculate it using a modern algorithm, specify the following:

[StdWXCalculate]
    [[Calculations]]
      windchill = software

This will force WeeWX to always calculate a value for windchill, irregardless of whether the hardware provides one.

Example 2: suppose you want ET to be calculated, but only for archive records. The option would look like:

[StdWXCalculate]
    [[Calculations]]
      ET = software, archive

Defaults

Note:
In the absence of a [[Calculations]] section, no values will be calculated!

However, the version of weewx.conf that comes with the WeeWX distribution comes with a version of [[Calculations]] that looks like this:

[StdWXCalculate]
    [[Calculations]]
        pressure = prefer_hardware
        altimeter = prefer_hardware
        appTemp = prefer_hardware
        barometer = prefer_hardware
        cloudbase = prefer_hardware
        dewpoint = prefer_hardware
        ET = prefer_hardware
        heatindex = prefer_hardware
        humidex = prefer_hardware
        inDewpoint = prefer_hardware
        maxSolarRad = prefer_hardware
        rainRate = prefer_hardware
        windchill = prefer_hardware
        windrun = prefer_hardware

[[WXXTypes]]

The StdWXXTypes class is responsible for calculating the following simple, derived types:

• appTemp
• cloudbase
• dewpoint
• ET
• heatindex
• humidex
• inDewpoint
• maxSolarRad
• windchill
• windDir
• windRun

A few of these types have an option or two that can be set. These are described below.

[[[ET]]]

This subsection contains several options used when calculating ET (evapotranspiration). See the document Step by Step Calculation of the Penman-Monteith Evapotranspiration" for the definitions of cn and cd.

et_period

This option changes the period over which evapotranspiration is calculated. Default is 3600 seconds.

wind_height

The option wind_height is used to normalize where wind speed is measured for calculating evapotranspiration. It should be set to the height of your anemometer in meters. Default is 2.0.

albedo

The albedo to be used in the calculations. Default is 0.23.

cn

The numerator constant for the reference crop type and time step. Default is 37.

cd

The denominator constant for the reference crop type and time step. Default is 0.34.

[[[heatindex]]]

algorithm

Controls which algorithm will be used to calculate heat-index. Choices are new (see https://www.wpc.ncep.noaa.gov/html/heatindex_equation.shtml), or old. The newer algorithm will give results down to 40°F, which are sometimes less than the sensible temperature. For this reason, some people prefer the older algorithm, which applies only for temperatures above 80°F. Default is new.

[[[maxSolarRad]]]

This section is used for specifying options when calculating maxSolarRad, the theoretical maximum solar radiation.

algorithm

Controls which algorithm will be used to calculate maxSolarRad. Choices are bras ("Bras"), or rs (Ryan-Stolzenbach). Default is rs.

atc

The coefficient atc is the "atmospheric transmission coefficient" used by the 'Ryan-Stolzenbach' algorithm for calculating maximum solar radiation. Value must be between 0.7 and 0.91. Default is 0.8.

nfac

The coefficient nfac is "atmospheric turbidity" used by the 'Bras' algorithm for calculating maximum solar radiation. Values must be between 2 (clear) and 5 (smoggy). Default is 2.

[[[windDir]]]

force_null

Indicates whether the wind direction should be undefined when the wind speed is zero. The default value is True: when the wind speed is zero, the wind direction will be set to undefined (Python None).

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

[StdWXCalculate]
    [[WXXTypes]]
      [[[windDir]]]
        force_null = False

[[PressureCooker]]

This class is responsible for calculating pressure-related values. Given the right set of input types, it can calculate barometer, pressure, and altimeter. See the Wiki article Barometer, pressure, and altimeter for the differences between these three types.

max_delta_12h

Some of the calculations require the temperature 12 hours ago (to compensate for tidal effects), which requires a database lookup. There may or may not be a temperature exactly 12 hours ago. This option sets how much of a time difference is allowed. The default is 1800 seconds.

[[[altimeter]]]

algorithm

Which algorithm to use when calculating altimeter from gauge pressure. Possible choices are ASOS, ASOS2, MADIS, NOAA, WOB, and SMT, The default is ASOS.

[[RainRater]]

This class calculates rainRate from recent rain events.

rain_period

The algorithm calculates a running average over a period of time in the past. This option controls how far back to go in time. Default is 1800 seconds.

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

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 archiving operations.

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 archiving operations.

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.manager.DaySummaryManager
    schema = schemas.wview_extended.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.manager.DaySummaryManager. This class stores daily summaries in the database. Normally, this does not need to be changed.

schema

A Python structure holding the schema to be used to initialize the database. After initialization, it is not used. Optional. Default is schemas.wview_extended.schema, which is a superset of 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.

[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:

• Set the option debug to 1 in weewx.conf. This will put much more information in the log file, which can be very useful for troubleshooting and debugging!

  debug = 1

• Look at the log file. We are always happy to take questions, but the first thing someone will ask is, "Did you look at the log file?"

  sudo tail -f /var/log/syslog

• Run weewxd directly from the command line, rather than as a daemon. Generally, WeeWX will catch and log any unrecoverable exceptions. But if you are getting strange results, it is worth running directly and looking for any clues.

  sudo weewxd weewx.conf

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

Davis stations

For Davis-specific tips, see the Wiki article Troubleshooting Davis stations

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:

• Run on dedicated hardware. If you are using the server for other tasks, particularly as your desktop machine, you will have reliability problems. If you are using it as a print or network server, you will probably be OK.
• Run headless. Modern graphical systems are extremely complex. As new features are added, test suites do not always catch up. Your system will be much more reliable if you run it without a windowing system (X Windows, in the case of Linux).
• Use an Uninterruptible Power Supply (UPS). The vast majority of power glitches are very short lived — just a second or two — so you do not need a big one. The 425VA unit I use to protect my fit-PC cost $55 at Best Buy.
• If you buy a Davis VantagePro and your computer has an old-fashioned serial port, get the VantagePro with a serial connection, not a USB connection. See the Wiki article on Davis cp2101 converter problems for details.
• If you do use a USB connection, put a ferrite coil on each end of the cable to your console. If you have enough length and the ferrite coil is big enough, make a loop so it goes through the coil twice. See the figure at right.

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 (the first line is not actually part of the log):

 DATE    TIME       HOST    weewx[PID]  LEVL MESSAGE

Feb  8 04:25:16 hummingbird weewx[6932] INFO weewx.manager: Added record 2020-02-08 04:25:00 PST (1581164700) to database 'weewx.sdb'
Feb  8 04:25:16 hummingbird weewx[6932] INFO weewx.manager: Added record 2020-02-08 04:25:00 PST (1581164700) to daily summary in 'weewx.sdb'
Feb  8 04:25:17 hummingbird weewx[6932] INFO weewx.restx: PWSWeather: Published record 2020-02-08 04:25:00 PST (1581164700)
Feb  8 04:25:17 hummingbird weewx[6932] INFO weewx.restx: Wunderground-PWS: Published record 2020-02-08 04:25:00 PST (1581164700)
Feb  8 04:25:17 hummingbird weewx[6932] INFO weewx.restx: Windy: Published record 2020-02-08 04:25:00 PST (1581164700)
Feb  8 04:25:17 hummingbird weewx[6932] ERROR weewx.restx: WOW: Failed to publish record 2020-02-08 04:25:00 PST (1581164700): Failed upload after 3 tries

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

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.

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:

• Increase the timeout option.
• Use a high quality SD card in your RPi. There seems to be some evidence that faster SD cards are more immune to this problem.
• Trim the size of your templates to minimize the number of queries necessary.

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

Funky symbols in plots

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

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.gen_images(self.gen_ts)
May 14 13:35:23 web weewx[5633]:         ****    File "/usr/share/weewx/weewx/imagegenerator.py", line 220, in gen_images
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.

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