From ffe439af05b983f95791c5bab4e35b2cec6dac27 Mon Sep 17 00:00:00 2001 From: Tom Keffer Date: Sat, 17 Sep 2016 18:02:27 -0700 Subject: [PATCH] Bumped version to V3.6.0a1. Augmented documentation for wee_database --- bin/weewx/__init__.py | 2 +- docs/customizing.htm | 2 +- docs/readme.htm | 2 +- docs/upgrading.htm | 2 +- docs/usersguide.htm | 2 +- docs/utilities.htm | 4070 +++++++++++++++++++++-------------------- weewx.conf | 2 +- 7 files changed, 2069 insertions(+), 2013 deletions(-) diff --git a/bin/weewx/__init__.py b/bin/weewx/__init__.py index e695d754..30e778e9 100644 --- a/bin/weewx/__init__.py +++ b/bin/weewx/__init__.py @@ -6,7 +6,7 @@ """Package weewx, containing modules specific to the weewx runtime engine.""" import time -__version__="3.5.0" +__version__="3.6.0a1" # Holds the program launch time in unix epoch seconds: # Useful for calculating 'uptime.' diff --git a/docs/customizing.htm b/docs/customizing.htm index 35340fd7..955d24c8 100644 --- a/docs/customizing.htm +++ b/docs/customizing.htm @@ -35,7 +35,7 @@
-Version: 3.5.0 +Version: 3.6.0a1
weewx Customization Guide
diff --git a/docs/readme.htm b/docs/readme.htm index 8956fc16..a99036f2 100644 --- a/docs/readme.htm +++ b/docs/readme.htm @@ -17,7 +17,7 @@
-Version: 3.5.0 +Version: 3.6.0a1
weewx Documentation
diff --git a/docs/upgrading.htm b/docs/upgrading.htm index 0ababdd9..d1f49426 100644 --- a/docs/upgrading.htm +++ b/docs/upgrading.htm @@ -67,7 +67,7 @@
-Version: 3.5.0 +Version: 3.6.0a1
weewx Upgrade Guide
diff --git a/docs/usersguide.htm b/docs/usersguide.htm index c4ea7155..67d9a1e0 100644 --- a/docs/usersguide.htm +++ b/docs/usersguide.htm @@ -35,7 +35,7 @@
-Version: 3.5.0 +Version: 3.6.0a1
diff --git a/docs/utilities.htm b/docs/utilities.htm index d86dce70..c2267bce 100644 --- a/docs/utilities.htm +++ b/docs/utilities.htm @@ -22,7 +22,7 @@
- +
@@ -35,41 +35,51 @@
-Version: 3.5.0 - +Version: 3.6.0a1 + -
weewx Utilities Guide
+
weewx Utilities Guide
+

This is a reference guide to the executable utilities that come with weewx:

@@ -291,9 +301,8 @@ Saved configuration to /home/weewx/weewx.conf

wee_database

-

The database utility simplifies operations typically made to the - database. For example, it can backfill the daily summaries - or check a SQLite database for embedded strings where floats are +

This database utility simplifies typical database maintenance operations. For example, it + can backfill the daily summaries or check a SQLite database for embedded strings where floats are expected.

Run the utility with the @@ -362,6 +371,51 @@ If you are using a MySQL database it is assumed that you have the appropriate permissions for the requested operation. +

Option --create-archive

+

If the database does not already exist, this option will create it and initialize it with the + schema specified in the configuration file weewx.conf. Because + weewx does this automatically, this option is rarely needed.

+ +

Option --drop-daily

+

In addition to the regular archive data, every weewx database also includes a daily summary table + for each observation type. Because there can be dozens of observation types, there can be dozens + of these daily summaries. It doesn't happen very often, but there can be occasions when it's + necessary to drop them all then rebuild them. Dropping them by hand would be very tedious! + This option does them all at once.

+ +

Option --backfill-daily

+

This option is kind of the inverse of option --drop-daily in that it + rebuilds the daily summaries from the archive data.

+ +

Option --reconfigure

+

This option is useful changing the schema in your database.

+ +

It creates a new database with the same name as the old, + except with the suffix _new attached at + the end (nominally, weewx.sdb_new + if you are using SQLite, weewx_new if you + are using MySQL). It then initializes it + with the schema specified in weewx.conf. Finally, + it copies over the data from your old database into the new database.

+ +

Option --string-check

+

Normally, all entries in the archive database are pure numbers. However, some visual SQLite database editors + use a null string instead of a null value when deleting entries. These nulls strings can + crash weewx. This option checks for them and, if the option --fix + is specified, substitutes a true null value if it finds any.

+ +

Option --transfer

+

This option is useful for moving your database from one type of database to another, such as + from SQLite to MySQL. To use it, you must have two bindings specified in your + weewx.conf configuration file. One will serve as the source, the other + as the destination. Specify the source binding with option --binding, + the destination binding with option --dest-binding.

+

See the Wiki for examples of moving data from + SQLite + to MySQL, and from + MySQL + to SQLite, + using wee_database.

@@ -371,13 +425,13 @@ permissions for the requested operation.

Troubleshooting problems when running weewx often involves analysis of a number of pieces of seemingly disparate system and weewx related information. The - wee_debug utility gathers this information into + wee_debug utility gathers all this information together into a single output to make troubleshooting easier. The wee_debug utility is particularly useful for new - users as the output may be redirected to file then emailed or posted to a + users as the output may be redirected to a file then emailed or posted to a forum to assist in remote troubleshooting.

-

Before using wee_debug, it's worth running it +

Run the utility with the --help option to see how it is used:

wee_debug --help
@@ -411,23 +465,23 @@ should thoroughly check the generated output for personal/private information before posting the information publicly. -

Generating a debug report

+

Generating a debug report

-

Generate a debug report using the --info - option as follows:

+

Generate a debug report using the --info + option as follows:

-

Warning!
- The wee_debug output includes a copy of the in use weewx - config file (usually weewx.conf) and whilst wee_debug - attempts to obfuscate any personal or sensitive information in weewx.conf, the - user should carefully check the wee_debug output for any remaining personal or - sensitive information before emailing or posting the output publicly.

+

Warning!
+ The wee_debug output includes a copy of the in use weewx + config file (usually weewx.conf) and whilst wee_debug + attempts to obfuscate any personal or sensitive information in weewx.conf, the + user should carefully check the wee_debug output for any remaining personal or + sensitive information before emailing or posting the output publicly.

- 
wee_debug --info
+ 
wee_debug --info
-

This results in:

+

This results in:

Using verbosity=1, displaying most info
 
 wee_debug output will be sent to stdout(console)
@@ -541,164 +595,161 @@ Parsed and obfuscated weewx.conf
 wee_debug report successfully generated
-

Redirecting wee_debug output

+

Redirecting wee_debug output

-

wee_debug output is sent by default to - stdout unless the optional --output - option is used. --output with no parameter will - send the wee_debug output to the default file - /var/tmp/weewx.debug. Usage is as follows:

+

By default, wee_debug output is sent to the system "standard output" + (stdout) unless the --output + option is used.

+

Option --output with no parameter sends output to the default file + /var/tmp/weewx.debug. Example:

- 
wee_debug --info --output
+ 
wee_debug --info --output
-

output can be sent to a file other than the default by including the - path and file name as a parameter after --output:

+

Option --output with a specified file will send it to that file. + Example:

- 
wee_debug --info --output /home/weewx/another.debug
+ 
wee_debug --info --output /home/weewx/another.debug
-

wee_debug verbosity

+

wee_debug verbosity

-

The depth of information included in the wee_debug - output can be changed using the --verbosity option. - The --verbosity option can be set to 0, 1 or 2 with - each higher level successively displaying more information. The default level - is 1. The information displayed for each level is:

+

The depth of information included in the wee_debug + output can be changed using the --verbosity option. + The --verbosity option can be set to 0, 1 or 2 with + each higher level successively displaying more information. The default level + is 1. The information displayed for each level is:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LevelIncluded Information
--verbosity 0path and name of weewx config file used (usually weewx.conf) -
name of weewx database binding used
operating system version
weewx version number
weewx station type and driver name
summary of currently installed extensions
summary of weewx archive
parsed and obfusated weewx config file (usually weewx.conf) -
--verbosity 1as per --verbosity 0
cpu info summary
system load averages
driver config extract from weewx config file (usually weewx.conf) -
summary of databases configured in weewx config file (usually weewx.conf) -
--verbosity 2as per --verbosity 1
list of supported SQL keys
list of supported observation types
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LevelIncluded Information
--verbosity 0path and name of weewx config file used (usually weewx.conf) +
name of weewx database binding used
operating system version
weewx version number
weewx station type and driver name
summary of currently installed extensions
summary of weewx archive
parsed and obfusated weewx config file (usually weewx.conf) +
--verbosity 1as per --verbosity 0
cpu info summary
system load averages
driver config extract from weewx config file (usually weewx.conf) +
summary of databases configured in weewx config file (usually weewx.conf) +
--verbosity 2as per --verbosity 1
list of supported SQL keys
list of supported observation types
- + -

wee_device

+

wee_device

-

This section describes how to configure some of the more popular - station hardware.

+

The utility wee_device can be used to configure the hardware of some + of the more popular weather stations. It can set things like rain bucket size, station archive interval, + altitude, EEPROM constants, etc. In order to do its job, it depends on optional code + being present in the hardware driver. Not all drivers have this code, so it may not work for your specific + device. If it does not, + you will have to consult your manufacturer's instructions for how to set these things through your console + or other means.

-

Some stations can be configured using the - wee_device utility supplied with weewx. - This utility uses code in the hardware-specific driver to set EEPROM - constants, read station memory, set the station archive interval, set - the altitude, configure rain bucket types, and many other options, - depending on the hardware.

+

Run the utility with the --help option + to see which options are available.

-

Note that some stations cannot be configured by software at all, - and some stations are only partly configurable by software.

+

wee_device --help

-

Run the utility with the --help option - to see which options are available.

+

The utility requires a weewx.conf file. + If no file is specified, it will look for + weewx.conf in the standard location. If + your configuration file is in a non-standard location, specify the + path to the configuration file as the first argument. For example,

-

wee_device --help

+

wee_device /path/to/weewx.conf --help

-

The utility requires a weewx.conf file. - If no file is specified, it will look for - weewx.conf in the standard location. If - your configuration file is in a non-standard location, specify the - path to the configuration file as the first argument. For example,

+

What follows is a guide to the level of support offered by wee_device for + each type of weather station.

-

wee_device /path/to/weewx.conf --help

+

AcuRite

+ +

The wee_device utility cannot + configure AcuRite stations.

+ +

The AcuRite console must be set to USB mode 3 or 4. Communication + via USB is disabled in modes 1 and 2. Mode 4 is more reliable than + mode 3; mode 3 enables logging of data, mode 4 does not. When the + console is logging it frequently causes USB communication problems.

+ +

The wind speed updates every 18 seconds. The wind direction updates + every 30 seconds. Other sensors update every 60 seconds.

+ +

The AcuRite stations do not record wind gusts.

+ +

The station emits partial packets, which may confuse some online + services

-

AcuRite

+

CC3000

-

The wee_device utility cannot - configure AcuRite stations.

+

The CC3000 data logger may be configured to return data in + METRIC or US units. These are not the same groups of METRIC and US + units as defined within weewx. However, the + CC3000 driver will convert to the appropriate units for the + weewx configuration.

-

The AcuRite console must be set to USB mode 3 or 4. Communication - via USB is disabled in modes 1 and 2. Mode 4 is more reliable than - mode 3; mode 3 enables logging of data, mode 4 does not. When the - console is logging it frequently causes USB communication problems.

+

The CC3000 data logger stores 2MB of records.

-

The wind speed updates every 18 seconds. The wind direction updates - every 30 seconds. Other sensors update every 60 seconds.

+

The CC3000 driver supports catchup on startup, but it does not + support hardware record generation.

-

The AcuRite stations do not record wind gusts.

- -

The station emits partial packets, which may confuse some online - services

- - -

CC3000

- -

The CC3000 data logger may be configured to return data in - METRIC or US units. These are not the same groups of METRIC and US - units as defined within weewx. However, the - CC3000 driver will convert to the appropriate units for the - weewx configuration.

- -

The CC3000 data logger stores 2MB of records.

- -

The CC3000 driver supports catchup on startup, but it does not - support hardware record generation.

- -

The wee_device utility can be used to - configure the station hardware. When the - station_type is - CC3000, - the --help option will produce output - something like this:

+

The wee_device utility can be used to + configure the station hardware. When the + station_type is + CC3000, + the --help option will produce output + something like this:

CC3000 driver version 0.8
 Usage: wee_device [config_file] [options] [--debug] [--help]
@@ -720,52 +771,52 @@ Options:
 
 Mutating actions will request confirmation before proceeding.
-

Station information

+

Station information

-

Display the station settings with the --info - option.

- 
wee_device --info
-

This will result in something like:

+

Display the station settings with the --info + option.

+ 
wee_device --info
+

This will result in something like:

firmware: Rainwise CC-3000 Version: 1.3 Build 006 Sep 04 2013
 time: 2014/06/02 08:22:17
 units: ENGLISH
 memory: 251372 bytes, 4334 records, 12%
 interval: 1
-

Changing the archive interval

+

Changing the archive interval

-

CC3000 loggers ship from the factory with an archive interval - of 1 minutes (60 seconds). To change the station's - interval to 5 minutes, do the following:

+

CC3000 loggers ship from the factory with an archive interval + of 1 minutes (60 seconds). To change the station's + interval to 5 minutes, do the following:

-

wee_device --set-interval=5

+

wee_device --set-interval=5

-

FineOffsetUSB

+

FineOffsetUSB

-

The station clock can only be set manually via buttons on the - console, or (if the station supports it) by WWVB radio. The - FineOffsetUSB driver ignores the station clock since it cannot be - trusted.

+

The station clock can only be set manually via buttons on the + console, or (if the station supports it) by WWVB radio. The + FineOffsetUSB driver ignores the station clock since it cannot be + trusted.

-

The station reads data from the sensors every 48 seconds. - The 30xx stations read UV data every 60 seconds.

+

The station reads data from the sensors every 48 seconds. + The 30xx stations read UV data every 60 seconds.

-

The 10xx and 20xx stations can save up to 4080 historical readings. - That is about 85 days of data with the default recording interval of - 30 minutes, or about 14 days with a recording interval of 5 minutes. - The 30xx stations can save up to 3264 historical readings.

+

The 10xx and 20xx stations can save up to 4080 historical readings. + That is about 85 days of data with the default recording interval of + 30 minutes, or about 14 days with a recording interval of 5 minutes. + The 30xx stations can save up to 3264 historical readings.

-

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

+

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

-

The wee_device utility can be used to - configure the station hardware. When the - station_type is - FineOffsetUSB, - the --help option will produce output - something like this:

+

The wee_device utility can be used to + configure the station hardware. When the + station_type is + FineOffsetUSB, + the --help option will produce output + something like this:

FineOffsetUSB driver version 1.7
 Usage: wee_device [config_file] [options] [--debug] [--help]
@@ -791,12 +842,12 @@ Options:
 --format=FORMAT      format for output, one of raw, table, or dict
 
 Mutating actions will request confirmation before proceeding.
-

Station information

+

Station information

-

Display the station settings with the --info - option.

- 
wee_device --info
-

This will result in something like:

+

Display the station settings with the --info + option.

+ 
wee_device --info
+

This will result in something like:

Fine Offset station settings:
                     local time: 2013.02.11 18:34:28 CET
                   polling_mode: ADAPTIVE
@@ -824,121 +875,121 @@ Mutating actions will request confirmation before proceeding.
version: 255 wind_coef: None wind_mult: 0 -

Highlighted values can be modified with the wee_device utility.

+

Highlighted values can be modified with the wee_device utility.

-

Changing the archive interval

+

Changing the archive interval

-

Fine Offset stations ship from the factory with an archive interval - (read_period) of 30 minutes (1800 seconds). To change the station's - interval to 5 minutes, do the following:

+

Fine Offset stations ship from the factory with an archive interval + (read_period) of 30 minutes (1800 seconds). To change the station's + interval to 5 minutes, do the following:

-

wee_device --set-interval=5

+

wee_device --set-interval=5

-

Dumping the console memory

+

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_device - can display these records in space-delimited, raw bytes, or dictionary format.

+

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_device + 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:

- 
wee_device --history=30
-

To clear the console memory:

- 
wee_device --clear-memory
+

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

+ 
wee_device --history=30
+

To clear the console memory:

+ 
wee_device --clear-memory
-

Checking the USB quality

+

Checking the USB quality

-

Use the wee_device 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.

+

Use the wee_device 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:

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

+

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

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

-

Polling mode and the polling interval

+

Polling mode and the polling interval

-

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

- - - - - - - - - - + +
Polling modes for Fine Offset stations
Modeweewx.confNotes
ADAPTIVE +

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

+ + + + + + + + + + - - - - - + + + + + - + - -
Polling modes for Fine Offset stations
Modeweewx.confNotes
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 + +

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.

+ 		+

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

-

The console reads the sensors every 48 seconds (60 seconds for UV), so setting the polling_interval to a value less than 48 will result in duplicate - readings. -

-
+

The console reads the sensors every 48 seconds (60 seconds for UV), so setting the polling_interval to a value less than 48 will result in duplicate + readings. +

+
-

TE923

+

TE923

-

Some station models will recognize up to 5 remote - temperature/humidity sensor units. Use the hardware switch in each - sensor unit to identify sensors. Use the - map in - weewx.conf to associate each sensor with a - database field. -

+

Some station models will recognize up to 5 remote + temperature/humidity sensor units. Use the hardware switch in each + sensor unit to identify sensors. Use the + map in + weewx.conf to associate each sensor with a + database field. +

-

The station has either 208 or 3442 history records, depending on - the model. That is just over a day (208 records) or about 23 days - (3442 records) with an archive interval of 5 minutes.

+

The station has either 208 or 3442 history records, depending on + the model. That is just over a day (208 records) or about 23 days + (3442 records) with an archive interval of 5 minutes.

-

The TE923 driver will read history records from the station when weewx - starts up, but it does not support hardware record generation.

+

The TE923 driver will read history records from the station when weewx + starts up, but it does not support hardware record generation.

-

The wee_device utility can be used to - configure the station hardware. When the - station_type is - TE932, - the --help option will produce output - something like this:

+

The wee_device utility can be used to + configure the station hardware. When the + station_type is + TE932, + the --help option will produce output + something like this:

Using configuration file /home/weewx/weewx.conf
 Using TE923 driver version 0.16 (weewx.drivers.te923)
@@ -977,12 +1028,12 @@ Options:
 Be sure to stop weewx first before using. Mutating actions will request
 confirmation before proceeding.
-

Station information

+

Station information

-

Use the --info option to display the - station configuration:

- 
wee_device --info
-

This will result in something like:

+

Use the --info option to display the + station configuration:

+ 
wee_device --info
+

This will result in something like:

Querying the station for the configuration...
         altitude: 16
            bat_1: True
@@ -1001,12 +1052,12 @@ confirmation before proceeding.
version_uv: 20 version_wind: 38 -

Display sensor status

+

Display sensor status

-

Use the --current option to display the - current status of each sensor:

- 
wee_device --current
-

This will result in something like:

+

Use the --current option to display the + current status of each sensor:

+ 
wee_device --current
+

This will result in something like:

Querying the station for current weather data...
         dateTime: 1454615168
         forecast: 5
@@ -1050,41 +1101,41 @@ confirmation before proceeding.
windspeed: None windspeed_state: invalid -

Changing the archive interval

+

Changing the archive interval

-

TE923 stations ship from the factory with an archive interval of 1 - hour (3600 seconds). To change the station's - interval to 5 minutes (300 seconds), do the following:

+

TE923 stations ship from the factory with an archive interval of 1 + hour (3600 seconds). To change the station's + interval to 5 minutes (300 seconds), do the following:

-

wee_device --set-interval=300

+

wee_device --set-interval=300

-

Dumping the logger memory

+

Dumping the logger memory

-

wee_device can display the records from the - logger in tabular or dictionary format.

+

wee_device can display the records from the + logger in tabular or dictionary format.

-

For example, to display the most recent 30 records:

- 
wee_device --history=30 --format dict
+

For example, to display the most recent 30 records:

+ 
wee_device --history=30 --format dict
-

Ultimeter

+

Ultimeter

-

The wee_device utility cannot - configure Ultimeter stations.

+

The wee_device utility cannot + configure Ultimeter stations.

-

The Ultimeter driver operates the Ultimeter in Data Logger Mode, - which results in sensor readings every 1/2 second or so.

+

The Ultimeter driver operates the Ultimeter in Data Logger Mode, + which results in sensor readings every 1/2 second or so.

-

The Ultimeter driver ignores the maximum, minimum, and average - values recorded by the station.

+

The Ultimeter driver ignores the maximum, minimum, and average + values recorded by the station.

-

Vantage

+

Vantage

-

When the station_type is - Vantage, - the --help option will produce output - something like this:

+

When the station_type is + Vantage, + the --help option will produce output + something like this:

Using configuration file /home/weewx/weewx.conf
 Using Vantage driver version 3.0 (weewx.drivers.vantage)
@@ -1150,12 +1201,12 @@ Options:
 Be sure to stop weewx first before using. Mutating actions will request
 confirmation before proceeding.
-

Station information

+

Station information

-

Use the --info option to display the - current EEPROM settings:

- 
wee_device --info
-

This will result in something like:

+

Use the --info option to display the + current EEPROM settings:

+ 
wee_device --info
+

This will result in something like:

Davis Vantage EEPROM settings:
 
     CONSOLE TYPE:                   VantagePro2
@@ -1222,180 +1273,180 @@ confirmation before proceeding.
Outside Temperature: +0.0 F Outside Humidity: +0% Extra Temperature 1: +0.0 F -

The console version number is available only on consoles with firmware - dates after about 2006.

+

The console version number is available only on consoles with firmware + dates after about 2006.

-

Highlighted values can be changed using this utility.

+

Highlighted values can be changed using this utility.

-

Time zone

+

Time zone

-

To set the time zone code to Central European Time (code 20):

- 
wee_device --set-tz-code=20
-

You can set either the time zone code or the - time zone offset, but not both.

+

To set the time zone code to Central European Time (code 20):

+ 
wee_device --set-tz-code=20
+

You can set either the time zone code or the + time zone offset, but not both.

-

Archive interval

+

Archive interval

-

Valid archive intervals for the Davis Vantage stations are 60, - 300, 600, 900, 1800, 3600, and 7200 seconds. 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.

+

Valid archive intervals for the Davis Vantage stations are 60, + 300, 600, 900, 1800, 3600, and 7200 seconds. 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.

-

To change the archive interval to 10 minutes (600 seconds):

- 
wee_device --set-interval=600
-

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.

+

To change the archive interval to 10 minutes (600 seconds):

+ 
wee_device --set-interval=600
+

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.

-

Rain bucket type

+

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.1 mm bucket (bucket code "2"), use the - following:

- 
wee_device --set-bucket=2
+

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.1 mm bucket (bucket code "2"), use the + following:

+ 
wee_device --set-bucket=2
-

Additional sensors

+

Additional sensors

-

If you have additional sensors for your Vantage station, you - can configure them using your console. However, if you have - a Davis - Weather Envoy receiver, it will not have a console! As an alternative, - the weewx - utility wee_device lets - you do this from the command line.

+

If you have additional sensors for your Vantage station, you + can configure them using your console. However, if you have + a Davis + Weather Envoy receiver, it will not have a console! As an alternative, + the weewx + utility wee_device lets + you do this from the command line.

-

For example, to add an extra temperature sensor to channel 3, do the following:

- 
wee_device --set-transmitter-type=3,1,2
-

This says to turn on channel 3, set its type to 1 ("Temperature only"), and have it show up in the - database as extraTemp2. Here's another example, this time for a combined - temperature / humidity sensor:

- 
wee_device --set-transmitter-type=5,3,2,4
-

This will add the combined sensor to channel 5, set its type to 3 ("Temperature and humidity"), - and it will show up in the database - as extraTemp2 and extraHumid4.

+

For example, to add an extra temperature sensor to channel 3, do the following:

+ 
wee_device --set-transmitter-type=3,1,2
+

This says to turn on channel 3, set its type to 1 ("Temperature only"), and have it show up in the + database as extraTemp2. Here's another example, this time for a combined + temperature / humidity sensor:

+ 
wee_device --set-transmitter-type=5,3,2,4
+

This will add the combined sensor to channel 5, set its type to 3 ("Temperature and humidity"), + and it will show up in the database + as extraTemp2 and extraHumid4.

-

The --help option will give you the code for each sensor type.

+

The --help option will give you the code for each sensor type.

-

Setting offsets

+

Setting offsets

-

The Davis instruments can correct sensor errors by adding - an offset to their emitted values. This is particularly - useful for Southern Hemisphere users. Davis fits the wind vane - to the Integrated Sensor Suite (ISS) in a position optimized for - Northern Hemisphere users, who face the solar panel to the - south. Users south of the equator must orient the ISS's solar - panel to the north to get maximal insolation, resulting in a - 180° error in the wind direction. The solution is to add a - 180° offset correction. You can do this with the following - command:

+

The Davis instruments can correct sensor errors by adding + an offset to their emitted values. This is particularly + useful for Southern Hemisphere users. Davis fits the wind vane + to the Integrated Sensor Suite (ISS) in a position optimized for + Northern Hemisphere users, who face the solar panel to the + south. Users south of the equator must orient the ISS's solar + panel to the north to get maximal insolation, resulting in a + 180° error in the wind direction. The solution is to add a + 180° offset correction. You can do this with the following + command:

- 
wee_device --set-offset=windDir,180
+ 
wee_device --set-offset=windDir,180
-

Dumping the logger memory

+

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. - Stop weewx first, then

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

+

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. + Stop weewx first, then

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

-

WMR100

+

WMR100

-

The wee_device utility cannot - configure WMR100 stations.

+

The wee_device utility cannot + configure WMR100 stations.

-

The station emits partial packets, which may confuse some online - services.

+

The station emits partial packets, which may confuse some online + services.

-

WMR200

+

WMR200

-

The wee_device utility cannot - configure WMR200 stations.

+

The wee_device utility cannot + configure WMR200 stations.

-

The station emits partial packets, which may confuse some online - services.

+

The station emits partial packets, which may confuse some online + services.

-

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

+

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

-

WMR300

+

WMR300

-

The wee_device utility cannot - configure WMR300 stations.

+

The wee_device utility cannot + configure WMR300 stations.

-

The station emits partial packets, which may confuse some online - services.

+

The station emits partial packets, which may confuse some online + services.

-

When weewx starts up it will attempt to - download all records from the console since the last record in the - archive database. This can take a couple of hours, depending on the - number of records in the logger and the speed of the computer and disk. -

+

When weewx starts up it will attempt to + download all records from the console since the last record in the + archive database. This can take a couple of hours, depending on the + number of records in the logger and the speed of the computer and disk. +

-

WMR9x8

+

WMR9x8

-

The wee_device utility cannot - configure WMR9x8 stations.

+

The wee_device utility cannot + configure WMR9x8 stations.

-

The station includes a data logger, but the driver does not read - records from the station.

+

The station includes a data logger, but the driver does not read + records from the station.

-

The station emits partial packets, which may confuse some online - services.

+

The station emits partial packets, which may confuse some online + services.

-

WS1

+

WS1

-

The wee_device utility cannot - configure WS1 stations.

+

The wee_device utility cannot + configure WS1 stations.

-

The WS1 stations produce data every 1/2 second or so.

+

The WS1 stations produce data every 1/2 second or so.

-

WS23xx

+

WS23xx

-

The hardware interface is a serial port, but USB-serial converters - can be used with computers that have no serial port. Beware that - not every type of USB-serial converter will work. Converters based - on ATEN UC-232A chipset are known to work.

+

The hardware interface is a serial port, but USB-serial converters + can be used with computers that have no serial port. Beware that + not every type of USB-serial converter will work. Converters based + on ATEN UC-232A chipset are known to work.

-

The station does not record wind gust or wind gust direction.

+

The station does not record wind gust or wind gust direction.

-

The hardware calculates windchill and dewpoint.

+

The hardware calculates windchill and dewpoint.

-

The station has 175 history records. That is just over 7 days - of data with the factory default history recording interval of 60 - minutes, or about 14 hours with a recording interval of 5 minutes.

+

The station has 175 history records. That is just over 7 days + of data with the factory default history recording interval of 60 + minutes, or about 14 hours with a recording interval of 5 minutes.

-

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

+

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

-

When the station_type is - WS23xx, - the --help option will produce output - something like this:

+

When the station_type is + WS23xx, + the --help option will produce output + something like this:

WS23xx driver version 0.21
 Usage: wee_device [config_file] [options] [--debug] [--help]
@@ -1416,12 +1467,12 @@ Options:
 
 Mutating actions will request confirmation before proceeding.
-

Station information

+

Station information

-

Display the station settings with the --info - option.

- 
wee_device --info
-

This will result in something like:

+

Display the station settings with the --info + option.

+ 
wee_device --info
+

This will result in something like:

buzzer: 0
 connection time till connect: 1.5
 connection type: 15
@@ -1446,58 +1497,58 @@ icon alarm active: 0
 in humidity: 48.0
 ...
-

Changing the archive interval

+

Changing the archive interval

-

WS23xx stations ship from the factory with an archive interval of 60 - minutes (3600 seconds). To change the station's interval to 5 minutes, - do the following:

+

WS23xx stations ship from the factory with an archive interval of 60 + minutes (3600 seconds). To change the station's interval to 5 minutes, + do the following:

-

wee_device --set-interval=5

+

wee_device --set-interval=5

-

Warning!
- Changing the recording interval will clear the station memory.

+

Warning!
+ Changing the recording interval will clear the station memory.

-

Dumping the console memory

+

Dumping the console memory

-

WS23xx stations store records in a circular buffer - once the - buffer fills, the oldest records are replaced by newer records. The - console stores up to 175 records. - The history number of records indicates how - many records are in memory. The - history interval indicates the number of - minutes between records.

+

WS23xx stations store records in a circular buffer - once the + buffer fills, the oldest records are replaced by newer records. The + console stores up to 175 records. + The history number of records indicates how + many records are in memory. The + history interval indicates the number of + minutes between records.

-

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

- 
wee_device --history=30
-

To clear the console memory:

- 
wee_device --clear-memory
+

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

+ 
wee_device --history=30
+

To clear the console memory:

+ 
wee_device --clear-memory
-

WS28xx

+

WS28xx

-

weewx communicates with a USB transceiver, - which communicates with the station console, which in turn communicates - with the sensors. The transceiver and console must be paired and - synchronized.

+

weewx communicates with a USB transceiver, + which communicates with the station console, which in turn communicates + with the sensors. The transceiver and console must be paired and + synchronized.

-

The station has 1797 history records. That is just over 6 days - of data with an archive interval of 5 minutes.

+

The station has 1797 history records. That is just over 6 days + of data with an archive interval of 5 minutes.

-

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

+

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

-

The WS28xx driver sets the station archive interval to - 5 minutes.

+

The WS28xx driver sets the station archive interval to + 5 minutes.

-

The WS28xx driver does not support hardware archive record - generation.

+

The WS28xx driver does not support hardware archive record + generation.

-

When the station_type is - WS28xx, - the --help option will produce output - something like this:

+

When the station_type is + WS28xx, + the --help option will produce output + something like this:

WS28xx driver version 0.33
 Usage: wee_device [config_file] [options] [--debug] [--help]
@@ -1519,80 +1570,80 @@ Options:
 
 Mutating actions will request confirmation before proceeding.
-

Pairing

+

Pairing

-

The console and transceiver must be paired. Pairing ensures that your - transceiver is talking to your console, not your neighbor's console. - Pairing should only have to be done once, although you might have to - pair again after power cycling the console, for example after you replace - the batteries.

+

The console and transceiver must be paired. Pairing ensures that your + transceiver is talking to your console, not your neighbor's console. + Pairing should only have to be done once, although you might have to + pair again after power cycling the console, for example after you replace + the batteries.

-

There are two ways to pair the console and the transceiver:

-
    -
  1. The Weewx way. Be sure that - weewx is not running. - Run the configuration utility, - press and hold the [v] button on the console until you see - 'PC' in the display, then release the button. If the console pairs - with the transceiver, 'PC' will go away within a second or two. +

    There are two ways to pair the console and the transceiver:

    +
      +
    1. The Weewx way. Be sure that + weewx is not running. + Run the configuration utility, + press and hold the [v] button on the console until you see + 'PC' in the display, then release the button. If the console pairs + with the transceiver, 'PC' will go away within a second or two. 
      wee_device --pair
 
 Pairing transceiver with console...
 Press and hold the [v] key until "PC" appears (attempt 1 of 3)
 Transceiver is paired to console
      -
      2. -
    2. The HeavyWeather way. Follow the pairing - instructions that came with the station. You will have to run - HeavyWeather on a windows computer with the USB transceiver. After - HeavyWeather indicates the devices are paired, put the USB transceiver - in your weewx computer and start weewx. - Do not power cycle the station console or you will have to start - over. -
      3. -
    +
    2. +
  2. The HeavyWeather way. Follow the pairing + instructions that came with the station. You will have to run + HeavyWeather on a windows computer with the USB transceiver. After + HeavyWeather indicates the devices are paired, put the USB transceiver + in your weewx computer and start weewx. + Do not power cycle the station console or you will have to start + over. +
    3. +
-

If the console does not pair, you will see messages in the log such as - this:

- 
ws28xx: RFComm: message from console contains unknown device ID (id=165a resp=80 req=6)
-

Either approach to pairing may require multiple attempts.

+

If the console does not pair, you will see messages in the log such as + this:

+ 
ws28xx: RFComm: message from console contains unknown device ID (id=165a resp=80 req=6)
+

Either approach to pairing may require multiple attempts.

-

Synchronizing

+

Synchronizing

-

After pairing, the transceiver and console must be synchronized in - order to communicate. Synchronization will happen automatically at the - top of each hour, or you can force synchronization by pressing the [SET] - button momentarily. Do not press and hold the [SET] button - that - modifies the console alarms.

+

After pairing, the transceiver and console must be synchronized in + order to communicate. Synchronization will happen automatically at the + top of each hour, or you can force synchronization by pressing the [SET] + button momentarily. Do not press and hold the [SET] button - that + modifies the console alarms.

-

When the transceiver and console are synchronized, you will see lots of - 'ws28xx: RFComm' messages in the log when debug=1. - When the - devices are - not synchronized, you will see messages like this about every 10 - minutes:

- 
Nov  7 19:12:17 raspi weewx[2335]: ws28xx: MainThread: no contact with console
-

If you see this, or if you see an extended gap in the weather data - in the weewx plots, press momentarily the [SET] button, or wait until - the top of the hour.

+

When the transceiver and console are synchronized, you will see lots of + 'ws28xx: RFComm' messages in the log when debug=1. + When the + devices are + not synchronized, you will see messages like this about every 10 + minutes:

+ 
Nov  7 19:12:17 raspi weewx[2335]: ws28xx: MainThread: no contact with console
+

If you see this, or if you see an extended gap in the weather data + in the weewx plots, press momentarily the [SET] button, or wait until + the top of the hour.

-

When the transceiver has not received new data for awhile, you will see - messages like this in the log:

- 
Nov  7 19:12:17 raspi weewx[2335]: ws28xx: MainThread: no new weather data
-

If you see 'no new weather data' messages with the - 'no contact with console' messages, - it simply means that the transceiver has not been able to synchronize - with the console. If you see only the 'no new weather data' messages, - then the sensors are not communicating with the console, or the console - may be defective.

+

When the transceiver has not received new data for awhile, you will see + messages like this in the log:

+ 
Nov  7 19:12:17 raspi weewx[2335]: ws28xx: MainThread: no new weather data
+

If you see 'no new weather data' messages with the + 'no contact with console' messages, + it simply means that the transceiver has not been able to synchronize + with the console. If you see only the 'no new weather data' messages, + then the sensors are not communicating with the console, or the console + may be defective.

-

Station information

+

Station information

-

Display the station settings with the --info - option.

+

Display the station settings with the --info + option.

-

wee_device --info

+

wee_device --info

-

This will result in something like:

+

This will result in something like:

alarm_flags_other: 0
 alarm_flags_wind_dir: 0
@@ -1633,28 +1684,28 @@ threshold_weather: 3
 wind_gust_max: 12.874765625
 wind_gust_max_time: None
-

Alarms

+

Alarms

-

When an alarm goes off, communication with the transceiver stops. - The WS28xx driver clears all alarms in the station. It is better to - create alarms in weewx, and the weewx alarms - can do much more than the console alarms anyway.

+

When an alarm goes off, communication with the transceiver stops. + The WS28xx driver clears all alarms in the station. It is better to + create alarms in weewx, and the weewx alarms + can do much more than the console alarms anyway.

- + -

wee_extension

+

wee_extension

-

- The utility wee_extension is used to add and - remove extensions. It's worth running with the - --help - option to see how it is used: -

+

+ The utility wee_extension is used to add and + remove extensions. It's worth running with the + --help + option to see how it is used: +

- 
wee_extension --help
+ 
wee_extension --help
-

This results in:

+

This results in:

 Usage: wee_extension --help
@@ -1691,53 +1742,53 @@ Options:
   --dry-run             Print what would happen but do not do it.
   --verbosity=N         How much status to display, 0-3
-

To install an extension:

+

To install an extension:

wee_extension --install extensions/basic
 wee_extension --install basic.tar.gz
-

To uninstall an extension:

+

To uninstall an extension:

-

wee_extension --uninstall basic

+

wee_extension --uninstall basic

-

To list installed extensions:

+

To list installed extensions:

-

wee_extension --list

+

wee_extension --list

-

The utility will make only the following changes:

- -

The utility makes a copy of any file or directory that it - modifies or replaces. When installing, it creates a directory called - installer in the - user directory. The contents of the - installer directory are - used to enumerate and uninstall extensions.

+

The utility will make only the following changes:

+ +

The utility makes a copy of any file or directory that it + modifies or replaces. When installing, it creates a directory called + installer in the + user directory. The contents of the + installer directory are + used to enumerate and uninstall extensions.

-

Installing an extension

+

Installing an extension

-

- Let's try installing a simple extension, - cmon, - used to monitor your computer. -

+

+ Let's try installing a simple extension, + cmon, + used to monitor your computer. +

-

- First download it. You can either do this from the link given in the - wiki, or by using wget (which you may have - to install): -

- 
wget -P /var/tmp http://lancet.mit.edu/mwall/projects/weather/releases/weewx-cmon-0.7.tgz
+

+ First download it. You can either do this from the link given in the + wiki, or by using wget (which you may have + to install): +

+ 
wget -P /var/tmp http://lancet.mit.edu/mwall/projects/weather/releases/weewx-cmon-0.7.tgz
-

- This will put the tarfile weewx-cmon-0.7.tgz - in the directory /var/tmp. -

+

+ This will put the tarfile weewx-cmon-0.7.tgz + in the directory /var/tmp. +

-

Now install the extension:

+

Now install the extension:

wee_extension --install=/var/tmp/weewx-cmon-0.7.tgz
 Request to install '/var/tmp/weewx-cmon-0.7.tgz'
 Extracting from tarball /var/tmp/weewx-cmon-0.7.tgz
@@ -1746,78 +1797,78 @@ Saving installer file to /home/weewx/bin/weecfg/user/installer/cmon
 Saved configuration dictionary. Backup copy at /home/weewx/weewx.conf.20150430130322
 Finished installing extension '/var/tmp/weewx-cmon-0.7.tgz'
-

The installer has done a number of things for you:

-
    -
  1. It put a new skin, cmon, in the - skins subdirectory; -
    2. -
  2. It put a new service, - user.cmon.ComputerMonitor, - in the list of services to be run by - weewx; -
    3. -
  3. It defined a new database, cmon_sqlite, - and a binding, cmon_binding, - to that database; -
    4. -
  4. It added a top-level "stanza" - [ComputerMonitor] - to your configuration file weewx.conf, - that specifies the data binding cmon - is to use. -
    5. -
  5. And, finally, it saved the details of how the extension was - installed so you can remove it later, should you choose to do so. -
    6. -
+

The installer has done a number of things for you:

+
    +
  1. It put a new skin, cmon, in the + skins subdirectory; +
    2. +
  2. It put a new service, + user.cmon.ComputerMonitor, + in the list of services to be run by + weewx; +
    3. +
  3. It defined a new database, cmon_sqlite, + and a binding, cmon_binding, + to that database; +
    4. +
  4. It added a top-level "stanza" + [ComputerMonitor] + to your configuration file weewx.conf, + that specifies the data binding cmon + is to use. +
    5. +
  5. And, finally, it saved the details of how the extension was + installed so you can remove it later, should you choose to do so. +
    6. +
-

Listing installed extensions

+

Listing installed extensions

-

The utility wee_extension can tell you which - extensions you have installed:

+

The utility wee_extension can tell you which + extensions you have installed:

wee_extension --list
 Extension Name   Version  Description
 cmon             0.7      Collect and display computer health indicators
-

You can see it lists the extension we just installed, cmon.

+

You can see it lists the extension we just installed, cmon.

-

Removing extensions

+

Removing extensions

-

You can remove an extension using the same tool:

+

You can remove an extension using the same tool:

wee_extension --uninstall=cmon
 wee_extension --list
 No extensions installed
- + -

wee_import

+

wee_import

-

Some weewx users will have historical data from - another source (e.g., other weather station software or a manually compiled - file) which they wish to import into weewx. - Such data can, depending upon the source, be imported - using the wee_import utility. This section - details the use of the wee_import utility. -

+

Some weewx users will have historical data from + another source (e.g., other weather station software or a manually compiled + file) which they wish to import into weewx. + Such data can, depending upon the source, be imported + using the wee_import utility. This section + details the use of the wee_import utility. +

-

The wee_import utility supports importing - observational data from the following sources:

- +

The wee_import utility supports importing + observational data from the following sources:

+ -

Before starting, it's worth running the utility with the - --help flag to see how - wee_import is used:

+

Before starting, it's worth running the utility with the + --help flag to see how + wee_import is used:

- 
wee_import --help
+ 
wee_import --help
-

This will result in an output that looks something like this:

+

This will result in an output that looks something like this:

Usage: wee_import --help
        wee_import --version
@@ -1856,170 +1907,170 @@ archive. Daily summaries are updated as each archive record is
 imported so there should be no need to separately drop and rebuild
 the daily summaries using the wee_database utility.
-

Command line options

+

Command line options

-

The wee_import command line options are - described in more detail below:

+

The wee_import command line options are + described in more detail below:

-

--config

+

--config

-

The utility is pretty good at "guessing" where your configuration file - weewx.conf is, but if you've done an unusual - install, you may have to tell it explicitly. You can do this by using - the --config option:

+

The utility is pretty good at "guessing" where your configuration file + weewx.conf is, but if you've done an unusual + install, you may have to tell it explicitly. You can do this by using + the --config option:

wee_import --config=/this/folder/weewx.conf --import-config=/folder/import.conf
-

--import-config

+

--import-config

-

wee_import uses a secondary configuration file to - store various import parameters. The - --import-config command line option - is mandatory for all imports. Example import configuration files for - each type of import supported by wee_import - are provided in the util/import folder. These - example files are best used by making a copy of the applicable example - file in a working directory and then modifying the duplicate file to - suit your needs. The --import-config - command line option is used as follows:

+

wee_import uses a secondary configuration file to + store various import parameters. The + --import-config command line option + is mandatory for all imports. Example import configuration files for + each type of import supported by wee_import + are provided in the util/import folder. These + example files are best used by making a copy of the applicable example + file in a working directory and then modifying the duplicate file to + suit your needs. The --import-config + command line option is used as follows:

wee_import --import-config=/folder/import.conf
-

--dry-run

+

--dry-run

-

The inclusion of the --dry-run command - line option will cause the import to proceed but no actual data will be - saved to the database. This is a useful option to use when first - importing data.

+

The inclusion of the --dry-run command + line option will cause the import to proceed but no actual data will be + saved to the database. This is a useful option to use when first + importing data.

wee_import --import-config=/folder/import.conf --dry-run
-

--date

+

--date

-

The date-time range of records to be imported can be specified by use of - the --date command line option. The - --date command line option can - specify a single date, as single date-time, a date range or a date-time - range. The date format used is YYYY/MM/DD and - the date-time format YYYY/MM/DD HH:MM. A range - is specified by separating two date or date-time formats by a hyphen, - e.g., '2015/12/1-2015/12/30'. Note that the - date-time or date-time range string must be enclosed in single or double - quotation marks. The effect of the different - --date command line option values - is shown in the following table:

+

The date-time range of records to be imported can be specified by use of + the --date command line option. The + --date command line option can + specify a single date, as single date-time, a date range or a date-time + range. The date format used is YYYY/MM/DD and + the date-time format YYYY/MM/DD HH:MM. A range + is specified by separating two date or date-time formats by a hyphen, + e.g., '2015/12/1-2015/12/30'. Note that the + date-time or date-time range string must be enclosed in single or double + quotation marks. The effect of the different + --date command line option values + is shown in the following table:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
command line optionRecords imported for a CSV or Cumulus importRecords imported for a Weather Underground import
omitted
(i.e., the default)		All available recordsTodays records only
--date 2015/12/22All records from 2015/12/22 00:00 (inclusive) to 2015/12/23 00:00 (exclusive)All records from 2015/12/22 00:00 (inclusive) to 2015/12/23 00:00 (exclusive)
--date "2015/12/22 22:30"The record timestamped 2015/12/22 22:30 onlyThe record timestamped 2015/12/22 22:30 only
--date 2015/12/22-2016/02/20All records from 2015/12/22 00:00 (inclusive) to 2016/2/21 00:00 (exclusive)All records from 2015/12/22 00:00 (inclusive) to 2016/2/21 00:00 (exclusive)
--date "2016/3/18 15:29-2016/6/20 22:00"All records from 2016/3/18 15:29 (inclusive) to 2016/6/20 22:00 (exclusive)All records from 2016/3/18 15:29 (inclusive) to 2016/6/20 22:00 (exclusive)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
command line optionRecords imported for a CSV or Cumulus importRecords imported for a Weather Underground import
omitted
(i.e., the default)		All available recordsTodays records only
--date 2015/12/22All records from 2015/12/22 00:00 (inclusive) to 2015/12/23 00:00 (exclusive)All records from 2015/12/22 00:00 (inclusive) to 2015/12/23 00:00 (exclusive)
--date "2015/12/22 22:30"The record timestamped 2015/12/22 22:30 onlyThe record timestamped 2015/12/22 22:30 only
--date 2015/12/22-2016/02/20All records from 2015/12/22 00:00 (inclusive) to 2016/2/21 00:00 (exclusive)All records from 2015/12/22 00:00 (inclusive) to 2016/2/21 00:00 (exclusive)
--date "2016/3/18 15:29-2016/6/20 22:00"All records from 2016/3/18 15:29 (inclusive) to 2016/6/20 22:00 (exclusive)All records from 2016/3/18 15:29 (inclusive) to 2016/6/20 22:00 (exclusive)
-

- Note
If the --date - command line option is omitted the default is to import all available - records when importing from a CSV or Cumulus source or to import today's - records only when importing from Weather Underground. -

+

+ Note
If the --date + command line option is omitted the default is to import all available + records when importing from a CSV or Cumulus source or to import today's + records only when importing from Weather Underground. +

-

--log

+

--log

-

The --log option controls the - wee_import log output. Omitting the option - will result in wee_import log output being - sent to the weewx log file (nominally the - system log, refer to - Monitoring weewx - and - Where to find things - to find it). wee_import log output can be - disabled by using --log=-. The - --log command line option is used as - follows: -

+

The --log option controls the + wee_import log output. Omitting the option + will result in wee_import log output being + sent to the weewx log file (nominally the + system log, refer to + Monitoring weewx + and + Where to find things + to find it). wee_import log output can be + disabled by using --log=-. The + --log command line option is used as + follows: + 

wee_import --import-config=/folder/import.conf --log=-
-

--verbose

+

--verbose

-

Inclusion of the --verbose command - line option will cause additional information to be printed during - wee_import execution.

+

Inclusion of the --verbose command + line option will cause additional information to be printed during + wee_import execution.

wee_import --import-config=/folder/import.conf --verbose
-

Importing from CSV files

+

Importing from CSV files

-

wee_import can import data from - a single CSV file. The CSV source file must be - structured as follows:

+

wee_import can import data from + a single CSV file. The CSV source file must be + structured as follows:

- -

A CSV file suitable for import by wee_import - may look like this:

+

A CSV file suitable for import by wee_import + may look like this:

Time,Temp,Dewpoint,Press,WindDir,WindSpeed,WindGust,Hum,dailyrain,SolarRad
 2016-02-01 00:00:00,13.5,9.2,1005.6,359,0.0,0.0,75,12.0,0.00
@@ -2033,125 +2084,127 @@ the daily summaries using the wee_database utility.
2016-02-01 00:45:00,12.9,9.8,1005.3,22,1.6,3.2,81,23.0,0.00 2016-02-01 00:50:00,12.9,9.7,1005.3,22,1.6,1.6,81,23.0,0.00 -

weewx archive fields populated during a CSV import

+

weewx archive fields populated during a CSV import

-

The weewx archive fields populated during a - CSV import depend on the CSV-to-weewx field - mappings specified in [CSV] section in the - import configuration file. If a valid field mapping exists, the - weewx field exists in the - weewx archive table schema and provided the - mapped CSV field contains valid data, then the corresponding - weewx field will populated. Note that the CSV - import is the only import supported by - wee_import that allows any - weewx archive field to be populated. -

+

The weewx archive fields populated during a + CSV import depend on the CSV-to-weewx field + mappings specified in [CSV] section in the + import configuration file. If a valid field mapping exists, the + weewx field exists in the + weewx archive table schema and provided the + mapped CSV field contains valid data, then the corresponding + weewx field will populated. Note that the CSV + import is the only import supported by + wee_import that allows any + weewx archive field to be populated. +

-

- Note
The use of the - calc_missing option in the import - configuration file may result in a - number of derived fields being calculated from the imported data. If - these derived fields exist in the in-use database schema they will be - saved to the database as well. -

+

+ Note
The use of the + calc_missing option in the import + configuration file may result in a + number of derived fields being calculated from the imported data. If + these derived fields exist in the in-use database schema they will be + saved to the database as well. +

-

Importing observations from a CSV file

+

Importing observations from a CSV file

-

To import observations from a CSV file:

+

To import observations from a CSV file:

-
    -
  1. Ensure the source data file is in a folder accessible by the machine - that will run wee_import. For the - purposes of these instructions the source data file - data.csv located in the - /var/tmp folder will be used. -
    2. +
      +
    1. Ensure the source data file is in a folder accessible by the machine + that will run wee_import. For the + purposes of these instructions the source data file + data.csv located in the + /var/tmp folder will be used. +
      2. -
    2. Make a backup of the - weewx database in case the import - should go awry. -
      3. +
    3. Make a backup of the + weewx database in case the import + should go awry. +
      4. -
    4. Create an import configuration file. - In this case we will make a copy of the example CSV - import configuration file and save it as - csv.conf in the - /var/tmp directory: -
      5. +
    5. Create an import configuration file. + In this case we will make a copy of the example CSV + import configuration file and save it as + csv.conf in the + /var/tmp directory: + 
      6. $ cp /home/weewx/util/import/csv-example.conf /var/tmp/csv.conf
      -
    6. Confirm that the source option is set to CSV: +
    7. Confirm that the source option is set to + CSV: +
      8. + + 
      source = CSV
      + +
    8. Confirm that the following options in the [CSV] + section are set: +
      9. + +
        +
      • file. + The full path and file name of the file containing the CSV + formatted data to be imported.
        • - - 
        source = CSV
        - -
      • Confirm that the following options in the [CSV] - section are set: +
      • interval. + Determines how the weewx interval + field is derived.
        • - -
          -
        • file. - The full path and file name of the file containing the CSV - formatted data to be imported. -
          • -
        • interval. - Determines how the weewx interval - field is derived. -
          • -
        • qc. Determines - whether quality control checks are performed on the imported - data. -
          • -
        • calc_missing. - Determines whether missing derived observations will be - calculated from the imported data. -
          • -
        • tranche. The - number of records written to the - weewx database in each transaction. -
          • -
        • UV_sensor. - Whether a UV sensor was installed when the source data was - produced. -
          • -
        • solar_sensor. - Whether a solar radiation sensor was installed when the - source data was produced. -
          • -
        • raw_datetime_format. - The format of the imported date time field. -
          • -
        • rain. Determines - how the weewx rain field is - derived. -
          • -
        • wind_direction. - Determines how imported wind direction fields are - interpreted. -
          • -
        • [[Map]]. Defines - the mapping between imported data fields and - weewx archive fields. Also defines - the units of measure for each imported field. -
          • -
        - -
      • When first importing data it is prudent to do a dry run import - before any data are actually imported. A dry run import will perform - all steps of the import without actually writing imported data to - the weewx database. In addition, - consideration should be given to any additional command line options - such as --date. +
      • qc. Determines + whether quality control checks are performed on the imported + data.
        • -

        To perform a dry run enter the following command:

        +
      • calc_missing. + Determines whether missing derived observations will be + calculated from the imported data. +
        • +
      • tranche. The + number of records written to the + weewx database in each transaction. +
        • +
      • UV_sensor. + Whether a UV sensor was installed when the source data was + produced. +
        • +
      • solar_sensor. + Whether a solar radiation sensor was installed when the + source data was produced. +
        • +
      • raw_datetime_format. + The format of the imported date time field. +
        • +
      • rain. Determines + how the weewx rain field is + derived. +
        • +
      • wind_direction. + Determines how imported wind direction fields are + interpreted. +
        • +
      • [[Map]]. Defines + the mapping between imported data fields and + weewx archive fields. Also defines + the units of measure for each imported field. +
        • +
      + +
    9. When first importing data it is prudent to do a dry run import + before any data are actually imported. A dry run import will perform + all steps of the import without actually writing imported data to + the weewx database. In addition, + consideration should be given to any additional command line options + such as --date. +
      10. +

      To perform a dry run enter the following command:

      wee_import --import-config=/var/tmp/csv.conf --dry-run
      -

      The output should be something like this:

      +

      The output should be something like this:

      Starting wee_import...
 A CSV import from source file '/var/tmp/data.csv' has been requested.
@@ -2165,34 +2218,34 @@ Records processed: 70685; Unique records: 70685; Last timestamp: 2010-09-04 04:2
 Finished dry run import. 70685 records were processed and 70685 unique records would have been imported.
      -

      The output includes details about the data source, its - destination and some other details on how the data will - be processed. The import will then - be performed but no data will be written to the - weewx database. Upon completion a - brief summary of the records processed is provided. -

      +

      The output includes details about the data source, its + destination and some other details on how the data will + be processed. The import will then + be performed but no data will be written to the + weewx database. Upon completion a + brief summary of the records processed is provided. +

      -

      - Note
      As the weewx database is - not altered when the --dry-run command - line option is used, wee_import log output - is suspended during a dry run import. In effect, the use of - --dry-run is equivalent to - --dry-run --log=-. During a dry run import - the only wee_import output is that - displayed on stdout. -

      +

      + Note
      As the weewx database is + not altered when the --dry-run command + line option is used, wee_import log output + is suspended during a dry run import. In effect, the use of + --dry-run is equivalent to + --dry-run --log=-. During a dry run import + the only wee_import output is that + displayed on stdout. +

      -
    10. Once the dry run results are satisfactory the data can be - imported using the following command: -
      11. +
    11. Once the dry run results are satisfactory the data can be + imported using the following command: +
      12. - 
      wee_import --import-config=/var/tmp/csv.conf
      + 
      wee_import --import-config=/var/tmp/csv.conf
      -

      This will result in a short preamble similar to that from - the dry run. At the end - of the preamble there will be a prompt:

      +

      This will result in a short preamble similar to that from + the dry run. At the end + of the preamble there will be a prompt:

      Starting wee_import...
 A CSV import from source file '/var/tmp/data.csv' has been requested.
@@ -2205,265 +2258,266 @@ Proceeding will save all imported records in the weewx archive.
 Are you sure you want to proceed (y/n)?
      -
    12. If the import parameters - are acceptable enter y to proceed with the - import or n to abort the import. - If the import is confirmed then the source - data will be imported, processed and saved in the - weewx database. Information on the - progress of the import will be displayed similar to the following: -
      13. +
    13. If the import parameters + are acceptable enter y to proceed with the + import or n to abort the import. + If the import is confirmed then the source + data will be imported, processed and saved in the + weewx database. Information on the + progress of the import will be displayed similar to the following: + 
      14. Records processed: 250; Unique records: 250; Last timestamp: 2010-02-09 19:25:00 AEST (1265707500)
      -

      The line commencing with Records processed - should update as records are imported with progress information on - number of records processed, number of unique records imported and - the date time of the latest record processed. When the import is - complete a brief summary is displayed similar to the following:

      +

      The line commencing with Records processed + should update as records are imported with progress information on + number of records processed, number of unique records imported and + the date time of the latest record processed. When the import is + complete a brief summary is displayed similar to the following:

      Records processed: 70685; Unique records: 70685; Last timestamp: 2010-09-04 04:20:00 AEST (1283538000)
 Finished import. 70685 raw records resulted in 70685 unique records being processed in 276.63 seconds.
 Those records with a timestamp already in the archive will not have been imported.
 Confirm successful import in the weewx log file.
      -
    14. Whilst wee_import will advise of the - number of records processed and the number of unique records found, - wee_import does know how many, if any, of - the imported records were successfully saved to the database. The - user should look carefully through the - weewx log file covering the - wee_import session and take note of any - records that were not imported. The most common reason for imported - records not being saved to the database is because a record with - that timestamp already exists in the database, in such cases - something similar to following will be found in the log: -
      15. +
    15. Whilst wee_import will advise of the + number of records processed and the number of unique records found, + wee_import does know how many, if any, of + the imported records were successfully saved to the database. The + user should look carefully through the + weewx log file covering the + wee_import session and take note of any + records that were not imported. The most common reason for imported + records not being saved to the database is because a record with + that timestamp already exists in the database, in such cases + something similar to following will be found in the log: + 
      16.  Aug 22 14:38:28 jessie2 weewx[863]: manager: unable to add record 2010-09-04 04:20:00 AEST (1283538000) to database 'weewx.sdb': UNIQUE constraint failed: archive.dateTime
      -

      In such cases the user should take note of the timestamp of the - record(s) concerned and make a decision about whether to delete the - pre-existing record and re-import the record or retain the - pre-existing record.

      - -
    +

    In such cases the user should take note of the timestamp of the + record(s) concerned and make a decision about whether to delete the + pre-existing record and re-import the record or retain the + pre-existing record.

    -

    Importing from Weather Underground

    +
-

wee_import can import data from - the daily history of a Weather Undeground PWS. A Weather Underground - daily history provides weather station observations received by Weather - Underground for the PWS concerned on a day by day basis. As such, the - data is analogous to the weewx archive table. - When wee_import imports data from a Weather - Underground daily history each day is considered a 'period'. - wee_import processes one period at a time in - chronological order (oldest to newest) and provides import summary data - on a per period basis. -

+

Importing from Weather Underground

-

weewx archive fields populated during a Weather Underground import

+

wee_import can import data from + the daily history of a Weather Undeground PWS. A Weather Underground + daily history provides weather station observations received by Weather + Underground for the PWS concerned on a day by day basis. As such, the + data is analogous to the weewx archive table. + When wee_import imports data from a Weather + Underground daily history each day is considered a 'period'. + wee_import processes one period at a time in + chronological order (oldest to newest) and provides import summary data + on a per period basis. +

-

A Weather Underground import will populate - weewx archive fields as follows:

+

weewx archive fields populated during a Weather Underground import

-
diff --git a/weewx.conf b/weewx.conf index a99a19e5..3379dd31 100644 --- a/weewx.conf +++ b/weewx.conf @@ -17,7 +17,7 @@ WEEWX_ROOT = /home/weewx socket_timeout = 20 # Do not modify this. It is used when installing and updating weewx. -version = 3.5.0 +version = 3.6.0a1 ##############################################################################