User's Guide to the weewx Weather System
Version: 2.3.3

This is the complete guide to installing and configuring weewx.

Table of Contents

About weewx

weewx is a piece of software, written in Python, that interacts with your weather station to produce plots, reports, and HTML pages. It can optionally upload the reports to a remote Web server as well as publish to the WeatherUnderground or PWSweather.com. It uses modern software concepts, making it simple, robust, and easy to extend. For an example station see Hood River West.

Key features:

I wrote weewx over the winter of 2008-2009 for two reasons: it was a wet and miserable winter here in Oregon with not much else to do, so there was no good reason not to, and because I wanted a simple, easy-to-understand server to run my Davis VantagePro2 weather station on a Linux box. I had been using wview, which is a high-performance and feature rich system authored by Mark Teel with lots of users. Written in C, it's an efficient system that can run on underpowered boxes. In exchange, it's huge (45,000+ lines of code), tightly integrated in with its companion library, radlib (another 14,000+ lines), and very complex, making it difficult to understand and reliably customize. I wanted something more modern and much, much simpler.

Having made a career in C++ and Java, I was also interested in some more modern languages, so I thought I'd try either Python or Ruby (although, truth be told, the roots of Python are nearly as old as C++!). I ended up picking Python because its libraries are more mature and there are many mores choices for third party libraries.

Weewx is about 7,000 lines of code, with another 4,400 comment lines. Because it is pure Python, it requires no makefiles, no builds, no special installs. It offers very powerful configuration and templating options, as well as an internally extensible engine, making it easy to customize. Its internal modular design and use of modern exception handling make it very robust and difficult to crash. It is also architecturally very simple and easy to understand.

Supported Hardware

Many types of station hardware are supported. In addition to hardware support, weewx comes with a software simulator, useful for testing and evaluation.

Vendor Model Link Required
Package
Station
Driver
Maturity
Ambient Weather WS1090 USB pyusb FineOffsetUSB5
WS2080 USB pyusb FineOffsetUSB5 Tested
WS2090 USB pyusb FineOffsetUSB5
Davis VantagePro2 Serial or USB pyserial Vantage1 Tested
VantagePro2 WeatherLink IP   Vantage1 Tested
VantageVue Serial or USB pyserial Vantage1 Tested
Elecsa 6975 USB pyusb FineOffsetUSB5
6976 USB pyusb FineOffsetUSB5
Fine Offset WH1080 USB pyusb FineOffsetUSB5 Tested
WH1081 USB pyusb FineOffsetUSB5
WH1091 USB pyusb FineOffsetUSB5
WH1090 USB pyusb FineOffsetUSB5 Tested
WS1080 USB pyusb FineOffsetUSB5
WA2080 USB pyusb FineOffsetUSB5
WA2081 USB pyusb FineOffsetUSB5
WH2080 USB pyusb FineOffsetUSB5
WH2081 USB pyusb FineOffsetUSB5
WH3080 USB pyusb FineOffsetUSB5
WH3081 USB pyusb FineOffsetUSB5 Tested
La Crosse C86234 USB pyusb WS28xx6 Experimental
WS-28XX USB pyusb WS28xx6 Experimental
National Geographic 265 USB pyusb FineOffsetUSB5
Oregon Scientific WMR100N USB pyusb WMR1002 Tested
WMR200 USB pyusb WMR2003 Experimental
WMR918 Serial pyserial WMR9x84
WMR968 Serial pyserial WMR9x84 Tested
TFA Primus USB pyusb WS28xx6 Experimental
Tycon TP1080WC USB pyusb FineOffsetUSB5
Watson W-8681 USB pyusb FineOffsetUSB5
WX-2008 USB pyusb FineOffsetUSB5
  1. Davis "Vantage" series of weather stations, including the VantagePro2™ and VantageVue™, using serial, USB, or WeatherLinkIP™ connections. Both the "Rev A" (firmware dated before 22 April 2002) and "Rev B" versions are supported.
  2. Oregon Scientific WMR100 series. Tested on the WMR100N, other stations may work as well.
  3. Oregon Scientific WMR200 series. This is an experimental version — it may or may not work. Please report any problems!
  4. Oregon Scientific WMR-918/968 series. Tested on the Oregon Scientific WMR-968, other stations may work as well.
  5. Fine Offset series of weather stations. These are branded by many vendors, including Ambient Weather, National Geographic, Watson, Elecsa, Tycon, Maplin, Froggit, and others. Tested on the Ambient Weather WS2080, other stations may work as well.
  6. La Crosse WS-28xx series. This is an experimental version — it may or may not work. Please report any problems!

System Requirements

I run weewx on a 500MHz system with an AMD Geode processor and 512 MB of memory. Configured this way, it consumes about 5% of the CPU and about 50MB of total memory.

On a Marvel 500MHz ARM CPU with 512MB RAM, weewx uses 63MB virtual and 40MB real memory when configured to generate 3 different standard reports. The CPU use is typically less than 0.5%, maxxing out at 90% for less than a minute every 5 minutes when weewx generates reports.

Time

You should run a NTP daemon on your server to ensure that it is synchronized with the correct time. Doing so will greatly reduce errors, especially if you send data to services such as the Weather Underground.

The time on the VantagePro is automatically synchronized with the weewx server nominally every four hours (changeable by the user).

Python

Python 2.5, 2.6, or 2.7 is required. Python 3 will not work.

Installing weewx

weewx can be installed using the standard Python utility setup.py or it can be installed from a DEB or RPM package.

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 easy to modify. If the user installing weewx has permission to write to the directory, root privileges will not be required to install, run, or modify weewx.

By contrast, the package approach is somewhat simpler, but 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.

Here is a summary of the layout for the different install methods, along with the symbolic names used for each role. These names are used throughout the documentation.

Debian
Redhat
setup.py
Application layout for install using DEB package
Role Symbolic Name Nominal Location
Executables $BIN_ROOT /usr/share/weewx/
Configuration directory $CONFIG_ROOT /etc/weewx/
Skins and templates $SKIN_ROOT /etc/weewx/skins/
Sqlite databases $SQLITE_ROOT /var/lib/weewx/
Web pages and images $HTML_ROOT /var/www/weewx/
Documentation $DOC_ROOT /usr/share/doc/weewx/
PID file /var/run/weewx.pid
Log file /var/log/syslog

Installing from DEB package

For Debian, Ubuntu, Mint operating systems.

Installing from RPM package

For Redhat, CentOS, Fedora operating systems.

Installing using the Python tool setup.py

For all operating systems.

Configuring weewx

This section covers configuring weewx, in particular the configuration files weewx.conf and skin.conf.

Station specific information is set in the configuration file $CONFIG_ROOT/weewx.conf. (There is another configuration file skin.conf for presentation-specific options, which is described in the Customizing Guide under section Reference: The standard skin configuration file.)

Most of the important options are up near the top of the file. They are all documented in this section, although you can safely ignore most of them. The truly important ones, the ones you are likely to have to customize for your station, are highlighted.

Default values are provided for many of them, 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. However, all options have been given values in the configuration file that ships with weewx, so you can see what they look like. The value given in this shipped configuration file is not necessarily the same as the "default value".

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

socket_timeout

Set to how long to wait before declaring a socket time out. This is used when FTP'ing data to a web server or sending data to the Weather Underground. Twenty (20) seconds is reasonable. Default is 20.

[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, such as Hood River, Oregon. Required. No default.

latitude
longitude

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

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

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.

week_start

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

station_type

Set to the type of hardware you are using. Valid options include:

Vantage Davis Vantage weather stations
WMR100 Oregon Scientific WMR100 series stations
WMR200 Oregon Scientific WMR200 series stations (experimental)
WMR9x8 Oregon Scientific WMR-918/968 series station
FineOffsetUSB Fine Offset USB stations

[Vantage]

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

type

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

port

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

host

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

baudrate

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

tcp_port

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

tcp_send_delay

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

iss_id

Set to the ID number of the Integrated Sensor Suite (ISS). This is used in the formula to calculate reception quality for wireless stations. Default is 1.

timeout

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

wait_before_retry

How many seconds to wait before retrying. Unless you have a good reason to change it, this value should be left at the default, as it is long enough for the station to offer new data, but not so long as to go into a new loop packet (which arrive every 2 seconds). Default is 1.2 seconds.

max_tries

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

[WMR100]

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

stale_wind

How long a wind record can be used to calculate wind chill (in seconds). Default is 30.

[WMR200]

This section is for options relating to the Oregon Scientific WMR200 series of weather stations with USB connectors. This support is experimental. Please report any problems!

stale_wind

How long a wind record can be used to calculate wind chill (in seconds). Default is 30.

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

stale_wind

How long a wind record can be used to calculate wind chill (in seconds). Default is 30.

[FineOffsetUSB]

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

model

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

pressure_offset

The offset, in millibars, that is applied to values from the station sensor. This offset is applied to the station pressure before calculating barometer and altimeter sea level pressures. Only the raw station pressure is recorded to database, not the station pressure with offset applied.

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. The default is PERIODIC.

polling_interval

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

[WS28xx]

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

pressure_offset

The offset, in millibars, that is applied to values from the station sensor. This offset is applied to the station pressure before calculating barometer and altimeter sea level pressures. Only the raw station pressure is recorded to database, not the station pressure with offset applied.

[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 start time for the generator in the format YYYY-MM-DD hh:mm. Optional. Default is the present time.

[StdRESTful]

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

[[Wunderground]]

Weewx can send your current data to the Weather Underground. If you do not wish to do this, leave the station commented.

station

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

password

Set to your Weather Underground password. Required.

[[PWSweather]]

Weewx can send your current data to the PWSweather.com service. If you do not wish to do this, leave the station commented.

station

Set to your PWSweather station ID. Required.

password

Set to your PWSweather password. Required.

[[WOW]]

Weewx can send your current data to the British Weather Observations Website (WOW) service. This section is not included in the version of weewx.conf that comes with the distribution, so you will have to add it by hand. When you're done, it will look similar to the Wunderground or PWSweather sections above, that is, something like this:

[StdRestful] . . . [[WOW]] station = 12345678 # Replace with your station number password = xxxxx # Replace with your password driver = weewx.restful.WOW

[[CWOP]]

Weewx can send your data to the Citizen Weather Observer Program. If you do not wish to do this, leave the station commented.

station

Set to your CWOP station ID (e.g., CW1234). Required.

passcode

This is used for APRS (amateur radio) stations only. Set to the passcode given to you by the CWOP operators. Otherwise, leave this option commented. Required for APRS stations, ignored for others.

server

A comma separated list of servers:ports to try. Unless you have a good reason to change this, use the servers listed. Required.

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

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 weewx attempts a catch up, old data could be interpreted as the current conditions. Optional. Default is 1800 seconds.

[StdReport]

This section is for configuring the StdReport service, which controls which reports are to be generated. While it can be highly customized for your individual situation, this documentation describes the section as shipped in the standard distribution.

Each report is represented by a sub-section, marked with double brackets (e.g., [[MyReport]]). Any options for the report should be placed under it. The standard report service will go through the sections, running each report in order. Hence, normally the report [[StandardReport]] will be run first, then report [[FTP]] (which actually optionally uploads the results to a remote web server). Details for how to customize reports are in the section Opportunities for customizing reports, in the Customizing 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.

[[StandardReport]]

This is the standard report that will be run on every archiving interval. It uses the skin "Standard", which generates four HTML pages ("day", "week", "month", and "year" observations), plot graphs for same, an RSS feed, and NOAA monthly and yearly reports. Unless changed otherwise, it uses US Customary Units and puts the results in public_html and subdirectory public_html/NOAA.

[[FTP]]

While this "report" doesn't 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.

If you do not use such a server, comment out the first four options below.

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 don't. Required. No default.

passive

Set to 1 if you wish to use the more modern, FTP passive mode, 0 if you wish to use active mode. Passive mode generally works better through firewalls, but not all FTP servers do a good job of supporting it. See Active FTP vs. Passive FTP, a Definitive Explanation for a good explanation of the difference. Default is 1 (passive mode).

max_tries

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

[[RSYNC]]

While this "report" doesn't 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 synchronizes those files that have changed, saving the outgoing bandwidth of your Internet connection.

If you do not use such a server, comment out the options below.

server

Set to the name of your web server (e.g., www.threefools.org, in my case). 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., /weather). Required. No default.

delete

Files that don't exist in the local report are removed from the remote location. USE WITH CAUTION: If you make a mistake in setting the path, this can cause unexpected files to be deleted on the remote server. Valid values are 1 to enable and 0 to disable. Required. Default is 0.

[StdConvert]

This section is for configuring the StdConvert service. This service acts as a filter, converting the unit system coming off your hardware to a target output unit system. Everything that follows, including the archiving service, will use the target unit system. Hence, your data will be stored using your chosen unit system.

Once chosen, it cannot be changed! Weewx does not allow you to mix unit systems within the databases. You must chose one or the other 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 Customizing Guide.

Note that whatever you choose here, it does not affect your options for the unit system to be used for reporting. 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 to Metric, be sure to read the sections [StdCalibrate] and [StdQC] below, and change the units there as well!

target_unit

Set to either US or METRIC. 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 is stored.

If you do not wish to apply any calibrations, you can leave it out of service_list, the list of services to be run, and it will not be loaded or run at all.

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

If you do not wish to use this service, you can leave it out of service_list, the list of services to be run, and it will not be loaded or run.

[[MinMax]]

In this section you list the observation types you wish to have checked, along with their minimum and maximum values. The units should be in the same unit system as specified in section StdConvert above.

Example,

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

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

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.

[StdArchive]

This section is for configuring StdArchive, the service that stores data in the databases. Options allow choosing which database to use for archiving and statistics.

archive_database

The database to be used to store the archive data. This should match a section given in the section [Databases] below. Normally, this is set to archive_sqlite. If you are using MySQL, you will want to change this to archive_mysql.

stats_database

The database to be used to store the statistical data. This should match a section given in the section [Databases] below. Normally, this is set to stats_sqlite. If you are using MySQL, you will want to change this to stats_mysql.

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.

archive_schema

This is used only when the archive database is first created. Thereafter, it is downloaded from the database. It should point to a Python list containing the archive database schema. The default is user.schemas.defaultArchiveSchema.

stats_schema

This is used only when the stats database is first created. Thereafter, it is downloaded from the database. It should point to a Python list containing the stats database schema. The default is user.schemas.defaultStatsSchema.

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

[Databases]

This section lists actual database bindings. The name of each database is given in double brackets below (for example, [[archive_sqlite]]). The details of the binding follow. You are free to add new bindings.

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 privileges to create and update the named databases.

[[archive_sqlite]]

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

database

The path to the archive sqlite file. A relative path is relative to $SQLITE_ROOT. Required.

[[stats_sqlite]]

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

database

The path to the stats sqlite file. A relative path is relative to $SQLITE_ROOT. Required.

[[archive_mysql]]

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

host

The host the archive database is located on. Default is localhost.

user

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

password

The password. Required.

database

The name of the archive database inside the server. Required.

[[stats_mysql]]

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

The host the stats database is located on. Default is localhost.

user

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

password

The password. Required.

database

The name of the statistical database inside the server. Required.

[Engines]

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

[[WxEngine]]

This section is for options used by the service engine.

service_list

This option is the list of services that are to be run by the service engine. After each event (such as the arrival of LOOP data, etc.), they will be run in the given order. The standard list of services run by weewx is:

service_list = weewx.wxengine.StdConvert, weewx.wxengine.StdCalibrate, weewx.wxengine, StdQC, weewx.wxengine.StdArchive, weewx.wxengine.StdTimeSynch, weewx.wxengine.StdPrint, weewx.wxengine.StdRESTful, weewx.wxengine.StdReport

Note that despite how it reads above, this option must be all on one line!

You can leave some of these services out if you do not need them. For example, the bare minimum if you are using a Davis Vantage instrument, storing your data in US Customary units, doing no data corrections or quality control and running as a daemon (no printing to console) would be:

service_list = weewx.wxengine.StdArchive, weewx.wxengine.StdTimeSynch, weewx.wxengine.StdRESTful, weewx.wxengine.StdReport

However, this will only make a slight difference in execution speed.

Configuring Station Hardware

Davis Vantage

Weewx comes with a configuration utlity, wee_config_vantage, that can set many of the on-board EEPROM constants in the Davis Vantage stations, such as its archive interval, altitude, rain bucket type, etc.

Run it with --help as an option to see its usage:

$BIN_ROOT/wee_config_vantage --help

This will print out something like:

Usage: wee_config_vantage: [config_file] [--help] [--info] [--clear] [--set-interval=SECONDS] [--set-altitude=FEET] [--set-barometer=inHg] [--set-bucket=CODE] [--set-rain-year-start=MM] [--set-time] [--set-lamp=['on'|'off]] [--dump] [--logger_summary=FILE] [--start | --stop] Configures the Davis Vantage weather station. Options: -h, --help show this help message and exit --config=FILE use configuration file FILE --info To print configuration, reception, and barometer calibration information about your weather station. --clear To clear the memory of your weather station. --set-interval=SECONDS Sets the archive interval to the specified number of seconds. Valid values are 60, 300, 600, 900, 1800, 3600, or 7200. --set-altitude=FEET Sets the altitude of the station to the specified number of feet. --set-barometer=inHg Sets the barometer reading of the station to a known correct value in inches of mercury. Specify 0 (zero) to have the console pick a sensible value. --set-bucket=CODE Set the type of rain bucket. Specify '0' for 0.01 inches; '1' for 0.2 MM; '2' for 0.1 MM --set-rain-year-start=MM Set the rain year start (1=Jan, 2=Feb, etc.). --set-time Set the onboard clock to the current time. --set-lamp=ON|OFF Turn the console lamp 'ON' or 'OFF' --start Start the logger. --stop Stop the logger. --dump Dump all data to the archive. NB: This may result in many duplicate primary key errors. --logger-summary=FILE Save diagnostic summary to FILE (for debugging the logger). Mutating actions will request confirmation before proceeding.

It is useful to run it with the --info option to see what the current EEPROM settings are on your station:

$BIN_ROOT/wee_config_vantage --info

This will print out something like:

VantagePro EEPROM settings: CONSOLE TYPE: VantagePro2 CONSOLE FIRMWARE: Date: Nov 28 2005 Version: <Unavailable> CONSOLE SETTINGS: Archive interval: 300 (seconds) Altitude: 700 (foot) Wind cup type: large Rain bucket type: 0.01 inches Rain year start: 10 Onboard time: 2012-09-30 16:48:27 PDT (1349048907) CONSOLE DISPLAY UNITS: Barometer: mbar Temperature: degree_F Rain: inch Wind: knot CONSOLE STATION INFO: Latitude (onboard): 45.7 Longitude (onboard): -121.6 Time zone code: 4 Use manual or auto DST? AUTO DST setting: N/A GMT offset: -8.0 hours Use GMT offset or time zone? TIME_ZONE RECEPTION STATS: Total packets received: 22843 Total packets missed: 748 Number of resynchronizations: 0 Longest good stretch: 534 Number of CRC errors: 647 BAROMETER CALIBRATION DATA: Current barometer reading: 30.209 inHg Altitude: 700 feet Dew point: 48 F Virtual temperature: 66 F Humidity correction factor: 23 Correction ratio: 1.025 Correction constant: +0.027 inHg Gain: -1.000 Offset: -1.000

Note that the console version number is available only on consoles with firmware dates after about 2006.

Highlighted values can be changed.

For example, to change the archive interval to 10 minutes (600 seconds):

$BIN_ROOT/wee_config_vantage --set-interval=600

Other parameters can be set in a similar manner.

Archive interval

Valid archive intervals are 60, 300, 600, 900, 1800, 3600, and 7200. However, if you are ftp'ing lots of files to a server, setting it to 60 seconds may not give enough time to have them all uploaded before the next archive record is due. If this is the case, you should pick an archive interval of at least 300 seconds, or trim the number of files you are using.

I have found that a five minute (300 seconds) archive interval works well for the Vantage stations. Because of the large amount of onboard memory they carry, going to a larger interval does not have any real advantages.

Choose your archiving interval carefully! Once chosen, it cannot be changed without messing up your statistics (highs and lows will be OK, but averages and rms wind speed will be wrong).

Rain bucket type

Normally, this is set by Davis, but if you have replaced your bucket with a different kind, you might want to reconfigure. For example, to change to a 0.1MM bucket (bucket code "2"), use the following:

$BIN_ROOT/wee_config_vantage --set-bucket=2

Dumping the logger memory

Generally, weewx downloads only new archive records from the on-board logger in the Vantage. However, occasionally the memory in the Vantage will get corrupted, making this impossible. See the troubleshooting section below "Weewx generates HTML pages, but it does not update them". The fix involves clearing the memory but, unfortunately, this means you may lose any data which might have accumulated in the logger memory, but not yet downloaded. By using the --dump command before clearing the memory, you might be able to save these data.

$BIN_ROOT/wee_config_vantage --dump

This will dump all data archived in the Vantage memory directly to the database, without regard to whether or not they have been seen before. Because the command dumps all data, it may result in many duplicate primary key errors. These can be ignored.

Fine Offset

The configuration utility wee_config_fousb is designed to diagnose and configure Fine Offset stations.

Run it with --help as an option to see its usage:

$BIN_ROOT/wee_config_fousb --help

This will print out something like:

Usage: wee_config_fousb [config_file] [options] [--help] Configuration utility for Fine Offset weather stations. Options: -h, --help show this help message and exit --config=FILE use configuration file FILE --info display weather station configuration --check-pressures query station for pressure sensor data --check-units compare raw and converted LOOP packets --check-usb test the quality of the USB connection --check-fixed-block monitor the contents of the fixed block --fixed-block display the contents of the fixed block --live display live readings from the station --logged display logged readings from the station --history-since=N display records since N minutes ago --history=N display N records --format=FORMAT format for output, one of raw, table, or dict --set-clock set station clock to computer time --set-pressure=P set relative pressure to P hPa (mbar) --set-interval=N set logging interval to N minutes --clear-memory clear station memory --slp=SLP calculate pressure offset from sea level pressure SLP -y answer yes to every prompt --debug display diagnostic information while running Mutating actions will request confirmation before proceeding.

Display the station settings with the --info option.

$BIN_ROOT/wee_config_fousb --info

This will result in something like this:

Fine Offset station settings: local time: 2013.02.11 18:34:28 CET polling_mode: ADAPTIVE abs_pressure: 933.3 current_pos: 592 data_changed: 0 data_count: 22 date_time: 2007-01-01 22:49 hum_in_offset: 18722 hum_out_offset: 257 id: None lux_wm2_coeff: 0 magic_1: 0x55 magic_2: 0xaa model: None rain_coef: None read_period: 30 rel_pressure: 1014.8 temp_in_offset: 1792 temp_out_offset: 0 timezone: 0 unknown_01: 0 unknown_18: 0 version: 255 wind_coef: None wind_mult: 0

Highlighted values can be modified with the wee_config_fousb utility.

Calibrating the pressure sensor

The pressure sensor in Fine Offset stations measures absolute, or station pressure. The sensor pressure may be off a bit when the station is at sea level, and almost certainly will be off when the station is above sea level. Stations at sea level are typically off by 1 to 10 millibars, while stations above a few hundred meters may be off by hundreds of millibars. When reporting weather data, weewx will calculate the equivalent sea level pressure, but the pressure sensor must be calibrated and an altitude must be specified.

To calibrate the pressure sensor, specify a pressure_offset, in millibars, in weewx.conf. If you do not know what the offset should be, use the wee_config_fousb utility to calculate this offset given the station altitude and a valid sea-level pressure from a nearby known-correct station.

For example, if the sea level pressure from a verified source is 1003.048 hPa, the following example will calculate the offset then ask whether to insert it into weewx.conf. It uses the altitude specified in weewx.conf and the station pressure and temperature.

$BIN_ROOT/wee_config_fousb --slp=1003.048

The output will look something like this:

Querying the station... Pressure offset is None Set pressure offset to 1.247000 hPa (y/n)? y Pressure offset is now 1.247000

For those using Imperial units, to convert inHg to hPa (mbar), multiply by 33.86389

weewx does not use the relative pressure in the Fine Offset console.

To display sensor, relative, and calculated pressures:

$BIN_ROOT/wee_config_fousb --check-pressures

Dumping the console memory

Fine Offset stations store records in a circular buffer - once the buffer fills, the oldest records are replaced by newer records. The 1080 and 2080 consoles store up to 4080 records. The 3080 consoles store up to 3264 records. The data_count indicates how many records are in memory. The read_period indicates the number of minutes between records. wee_config_fousb can display these records in space-delimited, raw bytes, or dictionary format.

For example, to display the most recent 30 records from the console memory:

$BIN_ROOT/wee_config_fousb --history=30

To clear the console memory:

$BIN_ROOT/wee_config_fousb --clear-memory

Checking the USB quality

Use the wee_config_fousb utility to test the quality of the USB connection between computer and console. Poor quality USB cables, under-powered USB hubs, and other devices on the bus can interfere with communication.

To test the quality of the USB connection to the console:

$BIN_ROOT/wee_config_fousb --check-usb

Let the utility run for at least a few minutes, or possibly an hour or two. It is not unusual to see a few bad reads in an hour, but if you see many bad reads within a few minutes, consider replacing the USB cable, USB hub, or removing other devices from the bus.

Operating modes

When weewx starts up it will attempt to download all records from the console since the last record in the archive database.

There are two modes for collecting 'live' sensor readings, adaptive or periodic, and two modes for obtaining archive records, hardware or software.

When reading 'live' data, weewx can read as fast as possible, or at a user-defined period. This is controlled by the polling_mode parameter.

Mode weewx.conf Notes

ADAPTIVE

[FineOffsetUSB] polling_mode = ADAPTIVE

In this mode, weewx reads data from the station as often as possible, but at intervals that avoid communication between the console and the sensors. Nominally this results in reading data every 48 seconds.

PERIODIC

[FineOffsetUSB] polling_mode = PERIODIC polling_interval = 60

In this mode, weewx reads data from the station every polling_interval seconds.

To obtain archive records, weewx can read archive records from the station console, or calculate archive records independent of the station memory. This is controlled by the record_generation parameter.

Mode weewx.conf Notes

Read from archive

[StdArchive] archive_interval = 300 record_generation = hardware

In this mode, archive records are read from the console archive. Each console archive record is an average of live samples over the logging interval, so each record in the weewx archive database will be an average of station sensor readings.

The archive_interval should match the logging interval specified in the console. Use wee_config_fousb to set the console logging interval.

Calculate from sensors

[StdArchive] archive_interval = 300 record_generation = software

In this mode, weewx calculates archive records based on the live data from the console. The archive_interval determines how often an archive record will be calculated.

The archive_interval should always be greater than the polling_interval. 300 (5 minutes) is a typical value for the archive interval.

If the polling_mode is PERIODIC and the polling_interval is greater than the archive_interval, the archive records will be collected/calculated at every polling interval, not at every archive interval.

Configuring MySQL

This section applies only for those using MySQL.

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

[Databases] [[archive_mysql]] host = localhost user = weewx password = weewx database = weewx driver = weedb.mysql [[stats_mysql]] host = localhost user = weewx password = weewx database = stats driver = weedb.mysql

This assumes user 'weewx' would have password 'weewx'. Adjust as necessary.

If you wish, databases 'weewx' and 'stats' can be combined into one database, although this will make it harder to drop the latter should you need to rebuild the stats database at a later time.

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

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

In addition to configuring MySQL, you will also need to indicate to weewx that you intend to use the configured database. See section [StdArchive] for details.

Running weewx

Weewx can be run either from the command line (useful for diagnostic purposes because it will print out a summary of every LOOP data), or as a daemon. When first trying weewx, it's probably best to run it from the command line because you will be able to see command line diagnostics, as well as log messages.

Running from the command line

Weewx can easily be run from the command line. Start by making sure you have appropriate permissions to the serial port your weather station uses. For example, if you are using a plain old serial port:

sudo chmod 666 /dev/ttyS0

Then run the main program, weewxd, giving the configuration file as its only parameter:

$BIN_ROOT/weewxd $CONFIG_ROOT/weewx.conf

It should start by downloading any data stored in your weather station into the archive database. As the Davis VantagePro can store a couple thousand archive records internally, this could take a minute or two. I've found this process particularly slow on SuSE for some reason.

Weewx will then start monitoring LOOP data, printing a short version of the received data on standard output, about once every two seconds.

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

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

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

Running as a daemon

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

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

Start by selecting the appropriate run script. They can be found under $WEEWX_ROOT/util/init.d/.

Debian/Ubuntu/Mint: $WEEWX_ROOT/util/init.d/weewx.debian
Redhat/CentOS/Mint: $WEEWX_ROOT/util/init.d/weewx.redhat
SuSE: $WEEWX_ROOT/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's worth checking).

Copy it to the proper location for your system:

Debian/Ubuntu/Mint: cp $WEEWX_ROOT/util/init.d/weewx.debian /etc/init.d/weewx
Redhat/CentOS/Fedora: cp $WEEWX_ROOT/util/init.d/weewx.redhat /etc/rc.d/init.d/weewx
SuSE: cp $WEEWX_ROOT/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:

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

By default, the scripts are designed to have weewx run at run levels 2, 3, 4 and 5. Incidentally, a nice tool for setting run levels with Debian (Ubuntu, Mint) systems is sysv-rc-conf. It uses a curses interface to allow you to change easily which run level any of your daemons runs at. There is a similar tool on SuSE. From the start menu run the YAST Control Center, then look for Systems Services (Runlevel). Pick "Expert" mode to see the run levels.

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

/etc/init.d/weewx reload

Monitoring weewx

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

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

Compatibility with wview

The sqlite3 archive database used by weewx (nominally, weewx.sdb) is completely compatible with the database used by wview (usually called wview-archive.sdb), at least as of wview Version 5.2.X. The schema and its semantics is identical. However, the statistical file stats.sdb is different, and must be rebuilt. This will be done automatically on startup by weewx.

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

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

When weewx starts it will generate a new stats.sdb file. This could take awhile if the wview archive contains more than a month or two of data.

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

Integrating weewx with a web server

If the server is on the same machine

The reports generated by weewx can be served by a web server running on the same computer as weewx. Here's how.

First, install a web server on the computer on which weewx is running. For example, on Debian systems:

sudo apt-get install apache2

Then, if weewx was installed from DEB or RPM package, simply enter the weewx URL in a web browser in order to see your webpages.

http://localhost/weewx

Alternatively, if weewx was installed using setup.py, copy the Apache configuration snippet that comes with weewx to the apache configuration directory, then restart Apache:

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

Be sure that the path in the Apache configuration snippet matches the HTML_ROOT defined in the weewx configuration file.

Alias /weewx /home/weewx/public_html <Directory /home/weewx/public_html> Options FollowSymlinks AllowOverride None Order allow,deny Allow from all </Directory>

Then open the weewx URL in a web browser:

http://localhost/weewx

If the server is on a different machine

Use the FTP or RSYNC 'reports' to upload to a web server. Either of these will copy everything from the HTML_ROOT directory to a location on the remote server on which the web server is running.

Troubleshooting

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

Hardware problems

Establishing connectivity

If you are unable to get anything out of weewx, first check that you have connectivity to your weather station. For the Davis stations, you can use a terminal emulator (I like minicom because it can be run from through a simple TTY connection) to run a simple test. Set it up to communicate using the appropriate port and baudrate. For example

minicom -b 19200 -D /dev/ttyUSB0

Then type in TEST, all in capital letters. It will not echo the characters. Then hit the <enter> key. It should echo back TEST.

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

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:

Ferrite coils
Ferrite coils on a Davis Envoy. There are two coils, one on the USB connection (top wire) and one on the power supply. Both have loops.

cp2101 converter problems

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

Nov 29 10:40:21 hummingbird kernel: [6661624.786792] hub 2-0:1.0: port 3 disabled by hub (EMI?), re-enabling... Nov 29 10:40:21 hummingbird kernel: [6661624.786871] usb 2-3: USB disconnect, address 2 Nov 29 10:40:21 hummingbird kernel: [6661624.795778] cp2101 2-3:1.0: device disconnected Nov 29 10:40:21 hummingbird weewx[25808]: VantagePro: Max retries exceeded while getting LOOP packets ... (messages elided) Nov 29 10:40:22 hummingbird kernel: [6661625.352340] cp2101 2-3:1.0: cp2101 converter detected Nov 29 10:40:22 hummingbird kernel: [6661625.528107] usb 2-3: reset full speed USB device using ohci_hcd and address 3 Nov 29 10:40:22 hummingbird kernel: [6661625.735497] usb 2-3: cp2101 converter now attached to ttyUSB1

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

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

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

Here's how:

Installing a udev script

I have installed a file /etc/udev/rules.d/vpro.rules on my fit-PC that looks like this:

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

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

Here's a rule that works for my Serial-to-USB cable, made by Prolific Technology, Inc.:

# Automount Serial-to-USB cable to port /dev/vpro # Install in /etc/udev/rules.d/cable.rules # ACTION=="add", ATTRS{product}=="USB-Serial Controller", SYMLINK+="vpro"

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

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

where /dev/ttyUSB0 is the port (substitute your real USB port) the VP2 is attached to. It will print out various identifiers that can be useful in identifying your VP2 to udev. While the first example script above used a rule that matched attribute interface, others are possible. For example, the second example, for the serial-to-USB cable, chose to match the attribute product.

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

I have tested this system many times. You can yank the USB port out of the machine and then plug it back in while also pulling out the network connection in the middle of an FTP upload: weewx will recover.

Or, at least, it should!

FreeBSD

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

I needed the uslcom Driver for the usb/rs232 Adapter used by my vantage. Also I had to reset the memory of the weatherstation. Loading the Driver: Put uslcom_load="YES" in /boot/loader.conf (to load it as module). Which gives here an output like: uslcom0: <CP2102 USB to UART Bridge Controller> on usbus1 And put in weewx.conf: port = /dev/cuaU0

Weewx generates HTML pages, but it does not update them

If you are getting a symptom that everything appears normal, that is HTML is getting generated and getting FTP'd to your webserver (look in the log to be sure!), but your web pages are not being updated, it could be because the data on board your console has gotten garbled. The way the Davis Vantage series works is that the software (weewx in this case) asks the console for all archive data "since" some time. The console then downloads the records one at a time. After it gets to the very last one, the memory wraps around, and the timestamp will suddenly jump backwards in time a couple weeks — this how the software knows it has downloaded the last record and so it stops.

However, if the internal memory gets garbled, the console will immediately return archives in the past, and so it looks like the timestamps have decreased in value and so weewx figures that's it: there's no more data.

I have received reports from a couple of users who have had this problem. There seems to be two fixes:

  1. Unplug the console, take out the batteries, and wait a minute or two. This will cause the console software to internally reboot. In one case this has fixed the problem without data loss.
  2. If all else fails, clear the memory of the console using the utility wee_config_vantage. This may cause loss of data, but usually works. Adjust paths as necessary:

$BIN_ROOT/wee_config_vantage --clear

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

3rd party Vantage connectors

This section is for those who are using a homebrew or 3rd party connector to a Davis Vantage console that does not contain a logger, such as the DSI-01 serial interface. That is, it is a pure serial connection to the console, with no onboard memory.

For these interfaces, you must set record generation to software. Without this information, weewx is unable to detect the absence of onboard memory. If you do not do this, you will get errors that look like the following in your syslog:

Nov 27 20:30:21 raspberrypi weewx[5607]: reportengine: Caught unrecoverable exception in generator weewx.filegenerator.FileGenerator Nov 27 20:30:21 raspberrypi weewx[5607]: **** 'NoneType' object has no attribute '__getitem__' Nov 27 20:30:21 raspberrypi weewx[5607]: **** Traceback (most recent call last): Nov 27 20:30:21 raspberrypi weewx[5607]: **** File "/home/weewx/bin/weewx/reportengine.py", line 132, in run Nov 27 20:30:21 raspberrypi weewx[5607]: **** obj.start() Nov 27 20:30:21 raspberrypi weewx[5607]: **** File "/home/weewx/bin/weewx/reportengine.py", line 259, in start Nov 27 20:30:21 raspberrypi weewx[5607]: **** self.run() Nov 27 20:30:21 raspberrypi weewx[5607]: **** File "/home/weewx/bin/weewx/filegenerator.py", line 41, in run Nov 27 20:30:21 raspberrypi weewx[5607]: **** self.setup() Nov 27 20:30:21 raspberrypi weewx[5607]: **** File "/home/weewx/bin/weewx/filegenerator.py", line 52, in setup Nov 27 20:30:21 raspberrypi weewx[5607]: **** self.initAlmanac(self.gen_ts) Nov 27 20:30:21 raspberrypi weewx[5607]: **** File "/home/weewx/bin/weewx/filegenerator.py", line 87, in initAlmanac Nov 27 20:30:21 raspberrypi weewx[5607]: **** rec = self.getRecord(archivedb, celestial_ts) Nov 27 20:30:21 raspberrypi weewx[5607]: **** File "/home/weewx/bin/weewx/filegenerator.py", line 115, in getRecord Nov 27 20:30:21 raspberrypi weewx[5607]: **** record_dict_vt = weewx.units.dictFromStd(record_dict) Nov 27 20:30:21 raspberrypi weewx[5607]: **** File "/home/weewx/bin/weewx/units.py", line 892, in dictFromStd Nov 27 20:30:21 raspberrypi weewx[5607]: **** std_unit_system = d['usUnits'] Nov 27 20:30:21 raspberrypi weewx[5607]: **** TypeError: 'NoneType' object has no attribute '__getitem__' Nov 27 20:30:21 raspberrypi weewx[5607]: **** Generator terminated... Nov 27 20:30:23 raspberrypi weewx[5607]: genimages: Generated 11 images in 2.53 seconds

See the section on option record_generation.

Software problems

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 from the command line.

configobj.DuplicateError exception

This error is caused by using an identifier more than once in the configuration file. For example, you may have inadvertently listed your FTP server twice:

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

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

Apr 24 12:09:15 raven weewx[11480]: wxengine: Error while parsing configuration file /home/weewx/weewx.conf Apr 24 12:09:15 raven weewx[11480]: wxengine: Unable to initialize main loop: Apr 24 12:09:15 raven weewx[11480]: **** Duplicate keyword name at line 254. Apr 24 12:09:15 raven weewx[11480]: **** Exiting.

configobj.NestingError exception

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

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

Note the extra closing bracket on the subsection FTP.

No barometer data

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

[StdConvert] target_unit = METRIC ... [StdQC] [[MinMax]] barometer = 28, 32.5

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

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's the tag $fubar in the template /home/weewx/skins/Standard/index.html.tmpl.

Architectural Notes

This section is not needed to get started.

Goals

The primary design goals of weewx are:

Strategies

To meet these goals, the following strategies were used:

While weewx is nowhere near as fast at generating images and HTML as its predecessor, wview (this is partially because weewx uses fancier fonts and a much more powerful templating engine), it is fast enough for all platforms but the slowest. I run it regularly on a 500 MHz machine where generating the 9 images used in the "Current Conditions" page takes just under 2 seconds (compared with 0.4 seconds for wview).

Unfortunately, the architectural goal of one code base is likely to be broken with the arrival of Python V3.X. It has so many changes that are not backwards compatible with V2.X, that a separate code base will most likely be needed. My intention is to stick with the V2.X versions until V3.X is so widespread it cannot be ignored, then make a permanent switch. Given the slow adoption rate of V3.X this is unlikely to happen anytime soon. In any case, I doubt the transition will affect the average weewx user.

All writes to the databases are protected by transactions. You can kill the program at any time (either Control-C if run from the command line or "/etc/init.d/weewx stop" if a daemon) without fear of corrupting the databases.

The code makes ample use of exceptions to insure graceful recovery from problems such as network outages. It also monitors socket and console timeouts, restarting whatever it was working on several times before giving up. In the case of an unrecoverable console error (such as the console not responding at all), the program waits 60 seconds then restarts the program from the top.

Any "hard" exceptions, that is those that do not involve network and console timeouts and are most likely due to a logic error, are logged, reraised, and ultimately cause thread termination. If this happens in the main thread (not likely due to its simplicity), then this causes program termination. If it happens in the report processing thread (much more likely), then only the generation of reports will be affected — the main thread will continue downloading data off the instrument and putting them in the database. You can fix the problem at your leisure, without worrying about losing any data.

Terminology

This is a glossary of terminology used throughout the code.

Name Description
archive record A record obtained from the SQL database
archive packet A packet obtained from the store on the weather station. For example, with a Davis VantagePro, it's obtained using the DMPAFT command.
datetime An instance of the Python object datetime.datetime. Variables of type datetime usually have a suffix _dt.
db_dict A dictionary with all the data necessary to bind to a database. An example for sqlite would be {'driver':'db.sqlite', 'root':'/home/weewx', 'database':'archive/weewx.sdb'}, an example for MySQL would be { 'driver':'db.mysql', 'host':'localhost', 'user':'weewx', 'password':'mypassword', 'database':'weewx'}.
epoch time Sometimes referred to as "unix time," or "unix epoch time." The number of seconds since the epoch, which is 1 Jan 1970 00:00:00 UTC. Hence, it always represents UTC (well... after adding a few leap seconds. But, close enough). This is the time used in the databases and appears as type dateTime in the SQL schema, perhaps an unfortunate name because of the similarity to the completely unrelated Python type datetime. Very easy to manipulate, but it is a big opaque number.
loop packet A packet with the current observations. For example, with a Davis VantagePro, it is obtained using the LOOP command.
observation type A type that can be used in the presentations. This is generally all of the SQL types, plus calculated data (such as rms or vecavg).
packet Something obtained from the weather station. Frequently uses a complex internal encoding, so it requires some processing to be useful.
record Something obtained from the SQL database.
SQL type A type that appears in the SQL database. This usually looks something like outTemp, barometer, extraTemp1, and so on.
time stamp A variable in unix epoch time. Always in UTC. Variables carrying a time stamp usually have a suffix _ts.
tuple-time An instance of the Python object time.struct_time. This is a 9-wise tuple that represent a time. It could be in either local time or UTC, though usually the former. See module time for more information. They are useful because they are a little closer in format to what the Davis VantagePro uses, although they still require a bit of processing. Variables carrying tuple time usually have a suffix _tt.
value tuple A 3-way tuple. First element is a value, second element the unit type the value is in, the third the unit group. An example would be (21.2, 'degree_C', 'group_temperature').

Units

In general, there are three different areas where the unit system makes a difference.:

  1. On the weather station. As far as I know, the Davis Vantage series supports only U.S. Customary units internally. The Oregon Scientific WMR-USB series uses an odd mix of US and metric.
  2. In the database. Either US or Metric can be used.
  3. In the presentation (i.e., html and image files).

The general strategy is that measurements are converted by service StdConvert as they come off the weather station into a target unit system, then stored internally in the database. Then, as they come off the database to be used for a report, they are converted into a target unit, specified by the skin.

Value "None"

The Python special value None is used throughout to signal a missing data point. All functions expect it.

However, the time value must never be None. This is because it is used as the primary key in the SQL database.

Time

Weewx stores all data in UTC (roughly, "Greenwich" or "Zulu") time. However, usually one is interested in weather events in local time and want image and HTML generation to reflect that. Furthermore, most weather stations are configured in local time. This requires that many data times be converted back and forth between UTC and local time. To avoid tripping up over time zones and daylight savings time, weewx generally uses Python routines to do this conversion. Nowhere in the code base is there any explicit recognition of DST. Instead, its presence is implicit in the conversions. At times, this can cause the code to be relatively inefficient.

For example, if one wanted to plot something every 3 hours in UTC time, it would be very simple: to get the next plot point, just add 10,800 to the epoch time:

next_ts = last_ts + 10800

But, if one wanted to plot something for every 3 hours in local time (that is, at 0000, 0300, 0600, etc.), despite a possible DST change in the middle, then things get a bit more complicated. One could modify the above to recognize whether a DST transition occurs sometime between last_ts and the next three hours and, if so, make the necessary adjustments. This is generally what wview does. Weewx takes a different approach and converts from UTC to local, does the arithmetic, then converts back. This is inefficient, but bulletproof against changes in DST algorithms, etc:

time_dt = datetime.datetime.fromtimestamp(last_ts) delta = datetime.timedelta(seconds=10800) next_dt = time_dt + delta next_ts = int(time.mktime(next_dt.timetuple()))

Other time conversion problems are handled in a similar manner.