mirror/weewx
1
0
Fork 0
mirror of https://github.com/weewx/weewx.git synced 2026-04-19 00:56:54 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
ffe439af05b983f95791c5bab4e35b2cec6dac27
weewx/docs/utilities.htm

3755 lines
175 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta content="en-us" http-equiv="Content-Language"/>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
<title>weewx: Utilities Guide</title>
<link href="css/ui-lightness/jquery-ui-1.10.4.custom.min.css" rel="stylesheet"/>
<link href="css/jquery.tocify.css" rel="stylesheet"/>
<link href="css/weewx_docs.css" rel="stylesheet"/>
</head>
<body>
<div class="sidebar">
<div class="doclist">
<a href="usersguide.htm">User's Guide</a><br/>
<a href="customizing.htm">Customization Guide</a><br/>
<a href="upgrading.htm">Upgrade Guide</a><br/>
<a href="utilities.htm">Utilities Guide</a>
</div>
<div id="toc_controls"></div>
<div id="toc_parent">
<div id="toc">
<!-- The table of contents will be injected here -->
</div>
</div>
</div>
<div class="main">
<div class="header">
<div class="logoref">
<a href='http://weewx.com'>
<img src='images/logo-weewx.png' class='logo' align='right' alt="weewx logo"/>
</a><br/>
<span class='version'>
Version: 3.6.0a1
</span>
</div>
<div class="title"><span class="code">weewx</span> Utilities Guide</div>
</div>
<div id="technical_content" class="content">
<p>This is a reference guide to the executable utilities that come with <span class="code">weewx</span>:</p>
<ul>
<li><a href="#wee_config_utility">
<span class="code">wee_config</span></a>
for changing the configuration file, and configuring new device drivers;
</li>
<li><a href="#wee_database_utility">
<span class="code">wee_database</span></a>
for reconfiguring the database;
</li>
<li><a href="#wee_debug_utility">
<span class="code">wee_debug</span></a>
for producing debug reports for remote support;
</li>
<li><a href="#wee_device_utility">
<span class="code">wee_device</span></a>
for configuring your hardware;
</li>
<li><a href="#wee_extension_utility">
<span class="code">wee_extension</span></a>
for installing and removing extensions;
</li>
<li><a href="#wee_import_utility">
<span class="code">wee_import</span></a>
for importing historical data from external sources;
</li>
<li><a href="#wee_reports_utility">
<span class="code">wee_reports</span></a>
for running reports without running weewx itself;
</li>
<li><a href="#weewxd_utility">
<span class="code">weewxd</span></a>
the main weewx program;
</li>
<li><a href="#wunderfixer">
<span class="code">wunderfixer</span></a>
for resending data missing on the Weather Underground site.
</li>
</ul>
<!-- ======== -->
<h1 id="wee_config_utility"><span class="code">wee_config</span></h1>
<p>
When you install <span class="code">weewx</span> for the first time,
the installation process will prompt you for the most essential
options, such as the type of hardware you are using, latitude,
longitude, or altitude. But, what if you want to change these later?
In particular, what if you want to change device drivers? You could
edit the definitive configuration file, <span class="code">weewx.conf</span>,
by hand &mdash; described in detail in the <a href="usersguide.htm">User's Guide</a>
&mdash; but it's a big file with lots of nuances. Alternatively, if
you're just changing something simple, you may be able to use the
utility <span class="code">wee_config</span>.
</p>
<p>
Before starting, it's worth running it with the <span
class="code">--help</span> option to see how it is used:
</p>
<pre class="tty cmd">wee_config --help</pre>
<p>This results in:</p>
<pre class="tty">Usage: wee_config --help
wee_config --version
wee_config --list-drivers
wee_config --install --dist-config=DIST_CONFIG --output=OUT_CONFIG
[--driver=DRIVER] [--units=(us|metric)]
[--latitude=yy.y] [--longitude=xx.x] [--altitude=zz.z,(foot|meter)]
[--location="Home Sweet Home"]
[--no-prompt] [--no-backup]
wee_config --upgrade CONFIG_FILE|--config=CONFIG_FILE
--dist-config=DIST_CONFIG
[--output=OUT_CONFIG] [--no-prompt] [--no-backup] [--warn-on-error]
wee_config --reconfigure CONFIG_FILE|--config=CONFIG_FILE
[--driver=DRIVER] [--units=(us|metric)]
[--latitude=yy.y] [--longitude=xx.x] [--altitude=zz.z,(foot|meter)]
[--location="Home Sweet Home"]
[--output=OUT_CONFIG] [--no-prompt] [--no-backup]
Commands:
--list-drivers List the available weewx device drivers, then exit.
--install Install a new configuration file starting with the contents of
DIST_CONFIG, prompting for station parameters.
--upgrade Update the contents of configuration file CONFIG_FILE to the
installed version, then merge the result with the contents of
configuration file DIST_CONFIG.
--reconfigure Modify an existing configuration file CONFIG_FILE with any
specified station parameters. Use this command with the
driver option to change the device driver.
Station parameters:
--driver --units
--latitude --longitude
--altitude --location
Options:
-h, --help show this help message and exit
--version Show the weewx version then exit.
--list-drivers List the available device drivers.
--install Install a new configuration file.
--upgrade Update an existing configuration file, then merge with
contents of DIST_CONFIG.
--reconfigure Reconfigure an existing configuration file.
--config=CONFIG_FILE Use configuration file CONFIG_FILE.
--dist-config=DIST_CONFIG
Use template configuration file DIST_CONFIG.
--output=OUT_CONFIG Save to configuration file OUT_CONFIG. If not
specified then replace existing configuration file.
--driver=DRIVER Use the driver DRIVER. For example,
weewx.driver.vantage
--latitude=yy.y The station latitude in decimal degrees.
--longitude=xx.x The station longitude in decimal degrees.
--altitude=zz,(foot|meter)
The station altitude in either feet or meters. For
example, '750,foot' or '320,meter'
--location=LOCATION A text description of the station. For example,
"Santa's workshop, North Pole"
--units=(metric|us) Set display units to 'metric' or 'us'.
--no-prompt Do not prompt. Use default or specified values.
--no-backup When replacing an existing configuration file, do not
create a backup copy.
--warn-on-error Only warn if an update is not possible. Default
behavior is to warn then exit.
--debug Show diagnostic information while running.
</pre>
<p>
The utility is pretty good about "guessing" where your configuration
file <span class="code">weewx.conf</span> is, but if you've done an
unusual install, you may have to tell it explicitly. You can do this by
either putting the location directly in the command line:
</p>
<pre class="tty cmd">wee_config /home/weewx/weewx.conf</pre>
<p>
or by using option <span class="code">--config</span>:
</p>
<pre class="tty cmd">wee_config --config=/home/weewx/weewx.conf</pre>
<h2>Changing device drivers</h2>
<p>
The most common use for <span class="code">wee_config</span> is to
change device drivers. Say that you originally installed
<span class="code">weewx</span> with the Simulator. Now you've bought a
Davis Vantage and you want to switch to that. Here's how you do it.
First, if you don't know the name of the driver, you can ask
<span class="code">wee_config</span> to list all the available drivers:
</p>
<pre class="tty cmd">wee_config --list-drivers</pre>
<p>This will result in something like:</p>
<pre class="tty">
Module name Driver name Version Status
weewx.drivers.acurite AcuRite 0.19 No module named usb
weewx.drivers.cc3000 CC3000 0.8
weewx.drivers.fousb FineOffsetUSB 1.7 No module named usb
weewx.drivers.simulator Simulator 3.0
weewx.drivers.te923 TE923 0.14 No module named usb
weewx.drivers.ultimeter Ultimeter 0.13
weewx.drivers.vantage Vantage 3.0
weewx.drivers.wmr100 WMR100 3.0 No module named usb
weewx.drivers.wmr200 WMR200 3.0 No module named usb
weewx.drivers.wmr9x8 WMR9x8 3.0
weewx.drivers.ws1 WS1 0.19
weewx.drivers.ws23xx WS23xx 0.24
weewx.drivers.ws28xx WS28xx 0.34 No module named usb
</pre>
<p>The column <span class="code">Status</span> can give you some indication of whether you are missing
any modules to use this driver. It's not completely accurate, but works for most drivers.</p>
<p>
From this list, we can see that the name of the driver for the Vantage is
<span class="code">weewx.drivers.vantage</span>. Now run
<span class="code">wee_config</span>, with the
<span class="code">--reconfigure</span>
command, specifying that driver:
</p>
<pre class="tty cmd">wee_config --reconfigure --driver=weewx.drivers.vantage</pre>
<p>
The utility will go through your previously selected options, such as
station description, latitude, longitude, altitude, <i>etc.</i>. With the exception
of your newly specified device driver, all your
previously selected values will be the defaults. So, all you have to do is keep hitting
enter. This is what it looked like when I switched from the simulator
to the Vantage driver:
</p>
<pre class="tty">Using configuration file /home/weewx/weewx.conf
Enter a brief description of the station, such as its location. For example:
Santa's Workshop, North Pole
description [Hood River, Oregon]:
Specify altitude, with units 'foot' or 'meter'. For example:
35, foot
12, meter
altitude [700, foot]:
Specify latitude in decimal degrees, negative for south.
latitude [45]:
Specify longitude in decimal degrees, negative for west.
longitude [-125]:
Indicate the preferred units for display: 'metric' or 'us'
units [metricwx]:
Installed drivers include:
0) AcuRite (weewx.drivers.acurite)
1) CC3000 (weewx.drivers.cc3000)
2) FineOffsetUSB (weewx.drivers.fousb)
3) Simulator (weewx.drivers.simulator)
4) TE923 (weewx.drivers.te923)
5) Ultimeter (weewx.drivers.ultimeter)
6) Vantage (weewx.drivers.vantage)
7) WMR100 (weewx.drivers.wmr100)
8) WMR200 (weewx.drivers.wmr200)
9) WMR9x8 (weewx.drivers.wmr9x8)
10) WS1 (weewx.drivers.ws1)
11) WS23xx (weewx.drivers.ws23xx)
12) WS28xx (weewx.drivers.ws28xx)
choose a driver [6]:
Specify the hardware interface, either 'serial' or 'ethernet'.
If the station is connected by serial, USB, or serial-to-USB
adapter, specify serial. Specify ethernet for stations with
WeatherLinkIP interface.
type [serial]:
Specify a port for stations with a serial interface, for
example /dev/ttyUSB0 or /dev/ttyS0.
port [/dev/ttyUSB0]:
Saved backup to /home/weewx/weewx.conf.20150430084525
Saved configuration to /home/weewx/weewx.conf
</pre>
<p>
If this is too much trouble, you can specify the <span class="code">--no-prompt</span>
option:
</p>
<pre class="tty cmd">wee_config --reconfigure --driver=weewx.drivers.vantage --no-prompt</pre>
<p>This will accept all the defaults, including your new device
driver, without asking for any input.</p>
<h2>Other <span class="code">wee_config</span> commands</h2>
<p>The other commands offered by <span class="code">wee_config</span>,
such as <span class="code">--install</span> and
<span class="code">--upgrade</span>, are used by the various <span class="code">weewx</span>
installers and are not generally intended for the end user.</p>
<!-- ======== -->
<h1 id="wee_database_utility"><span class="code">wee_database</span></h1>
<p>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.</p>
<p>Run the utility with the
<span class="code">--help</span> flag to see how it is used:</p>
<pre class="tty cmd">wee_database --help</pre>
<p>This will result in an output that looks something like this:</p>
<pre class="tty">
Usage: wee_database --help
wee_database --create-archive
[CONFIG_FILE|--config=CONFIG_FILE]
[--binding=BINDING_NAME]
wee_database --drop-daily
[CONFIG_FILE|--config=CONFIG_FILE]
[--binding=BINDING_NAME]
wee_database --backfill-daily
[CONFIG_FILE|--config=CONFIG_FILE]
[--binding=BINDING_NAME]
[--trans-days=DAYS]
wee_database --reconfigure
[CONFIG_FILE|--config=CONFIG_FILE]
[--binding=BINDING_NAME]
wee_database --string-check
[CONFIG_FILE|--config=CONFIG_FILE]
[--binding=BINDING_NAME] [--fix]
wee_database --transfer
[CONFIG_FILE|--config=CONFIG_FILE]
[--binding=BINDING_NAME]
--dest-binding=BINDING_NAME
[--dry-run]
Configure the weewx databases. Most of these functions are handled
automatically by weewx, but they may be useful as a utility in special cases.
In particular, the 'reconfigure' option can be useful if you decide to add or
drop data types from the database schema or change unit systems and the
'transfer' option is useful if converting from one database type to another.
Options:
-h, --help show this help message and exit
--config=CONFIG_FILE Use configuration file CONFIG_FILE.
--create-archive Create the archive database.
--drop-daily Drop the daily summary tables from a database.
--backfill-daily Backfill a database with daily summaries.
--reconfigure Create a new archive database using configuration
information found in the configuration file. In
particular, the new database will use the unit system
found in option [StdConvert][target_unit]. The new
database will have the same name as the old database,
with a '_new' on the end.
--string-check Check a sqlite version of the archive database to see
whether it contains embedded strings.
--fix Fix any embedded strings in a sqlite database.
--transfer Transfer the weewx archive from source database to
destination database.
--binding=BINDING_NAME
The data binding. Default is 'wx_binding'.
--dest-binding=BINDING_NAME
The destination data binding.
--dry-run Print what would happen but do not do it.
--trans-days=DAYS Limit backfill transactions to no more than DAYS days
of archive data at a time. Default value is 5. May be
increased for a slight speed increase or reduced to
reduce memory usage.
If you are using a MySQL database it is assumed that you have the appropriate
permissions for the requested operation.
</pre>
<h2>Option <span class="code">--create-archive</span></h2>
<p>If the database does not already exist, this option will create it and initialize it with the
schema specified in the configuration file <span class="code">weewx.conf</span>. Because
weewx does this automatically, this option is rarely needed.</p>
<h2>Option <span class="code">--drop-daily</span></h2>
<p>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.</p>
<h2>Option <span class="code">--backfill-daily</span></h2>
<p>This option is kind of the inverse of option <span class="code">--drop-daily</span> in that it
rebuilds the daily summaries from the archive data.</p>
<h2>Option <span class="code">--reconfigure</span></h2>
<p>This option is useful changing the schema in your database.</p>
<p>It creates a new database with the same name as the old,
except with the suffix <span class="code">_new</span> attached at
the end (nominally, <span class="code">weewx.sdb_new</span>
if you are using SQLite, <span class="code">weewx_new</span> if you
are using MySQL). It then initializes it
with the schema specified in <span class="code">weewx.conf</span>. Finally,
it copies over the data from your old database into the new database.</p>
<h2>Option <span class="code">--string-check</span></h2>
<p>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 <span class="code">--fix</span>
is specified, substitutes a true null value if it finds any.</p>
<h2>Option <span class="code">--transfer</span></h2>
<p>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
<span class="code">weewx.conf</span> configuration file. One will serve as the source, the other
as the destination. Specify the source binding with option <span class="code">--binding</span>,
the destination binding with option <span class="code">--dest-binding</span>.</p>
<p>See the Wiki for examples of moving data from
<a href="https://github.com/weewx/weewx/wiki/Transfer%20from%20sqlite%20to%20MySQL#using-wee_database">SQLite
to MySQL</a>, and from
<a href="https://github.com/weewx/weewx/wiki/Transfer%20from%20MySQL%20to%20sqlite#using-wee_database">MySQL
to SQLite</a>,
using <span class="code">wee_database</span>.</p>
<!-- ======== -->
<h1 id="wee_debug_utility"><span class="code">wee_debug</span></h1>
<p>Troubleshooting problems when running <span class="code">weewx</span>
often involves analysis of a number of pieces of seemingly disparate system
and <span class="code">weewx</span> related information. The
<span class="code">wee_debug</span> utility gathers all this information together into
a single output to make troubleshooting easier. The
<span class="code">wee_debug</span> utility is particularly useful for new
users as the output may be redirected to a file then emailed or posted to a
forum to assist in remote troubleshooting.</p>
<p>Run the utility
with the <span class="code">--help</span> option to see how it is used:</p>
<pre class="tty cmd">wee_debug --help</pre>
<p>This results in:</p>
<pre class="tty">Usage: wee_debug --help
wee_debug --info
[--output|--output DEBUG_PATH]
[--verbosity=0|1|2]
wee_debug --version
Generate a standard suite of system/weewx information to aid in remote
debugging. The wee_debug output consists of two parts, the first part
containing a snapshot of relevant system/weewx information and the second part
a parsed and obfuscated copy of weewx.conf. This output can be redirected to
file and posted when seeking assistance via forums or email.
Options:
-h, --help show this help message and exit
--info Generate weewx debug output.
--output Write wee_debug output to DEBUG_PATH. DEBUG_PATH includes
path and file name. Default is /var/tmp/weewx.debug.
--verbosity=N How much detail to display, 0-2, default=1.
--version Display wee_debug version number.
wee_debug will attempt to obfuscate obvious personal/private information in
weewx.conf such as user names, passwords and API keys; however, the user
should thoroughly check the generated output for personal/private information
before posting the information publicly.
</pre>
<h2>Generating a debug report</h2>
<p>Generate a debug report using the <span class="code">--info</span>
option as follows:</p>
<p class="warning"><strong>Warning!</strong><br/>
The <span class="code">wee_debug</span> output includes a copy of the in use <span
class="code">weewx</span>
config file (usually <span class="code">weewx.conf</span>) and whilst <span
class="code">wee_debug</span>
attempts to obfuscate any personal or sensitive information in <span class="code">weewx.conf</span>, the
user should carefully check the <span class="code">wee_debug</span> output for any remaining personal or
sensitive information before emailing or posting the output publicly.</p>
<pre class="tty cmd">wee_debug --info</pre>
<p>This results in:</p>
<pre class="tty">Using verbosity=1, displaying most info
wee_debug output will be sent to stdout(console)
Using configuration file /home/weewx/weewx.conf
Using database binding 'wx_binding', which is bound to database 'archive_mysql'
System info
CPU implementer: 0x41
Features: half thumb fastmult vfp edsp java tls
CPU architecture: 7
BogoMIPS: 2.00
Hardware: BCM2708
CPU revision: 7
CPU part: 0xb76
model name: ARMv6-compatible processor rev 7 (v6l)
Serial: 000000009581b554
processor: 0
CPU variant: 0x0
Revision: 000e
Operating system: debian 7.8
Linux rosella 4.1.6+ #810 PREEMPT Tue Aug 18 15:19:58 BST 2015 armv6l
1 minute load average: 0.19
5 minute load average: 0.15
15 minute load average: 0.12
General weewx info
Weewx version 3.2.1 detected.
Station info
Station type: Simulator
Driver: weewx.drivers.simulator
Driver info
[Simulator]
# This section is for the weewx weather station simulator
# The time (in seconds) between LOOP packets.
loop_interval = 2.5
# The simulator mode can be either 'simulator' or 'generator'.
# Real-time simulator. Sleep between each LOOP packet.
mode = simulator
# Generator. Emit LOOP packets as fast as possible (useful for testing).
#mode = generator
# The start time. If not specified, the default is to use the present time.
#start = 2011-01-01 00:00
# The driver to use:
driver = weewx.drivers.simulator
Currently installed extensions
Extension Name Version Description
Weewx-WD 1.2.0b1 Weewx support for Weather Display Live, SteelSeries Gauges and Carter Lake/Saratoga weather web site templates.
Archive info
Database name: weewx
Table name: archive
Unit system: 16(METRIC)
First good timestamp: 2013-01-01 00:00:00 AEST (1356962400)
Last good timestamp: 2015-09-06 02:15:00 AEST (1441469700)
Number of records: 281178
weewx (weewx.conf) is set to use an archive interval of 300 seconds.
The station hardware was not interrogated in determining archive interval.
Databases configured in weewx.conf
Database name: weewx
Database driver: weedb.mysql
Database host: localhost
Database name: wdsupp
Database driver: weedb.mysql
Database host: localhost
Database name: weewxwd
Database driver: weedb.mysql
Database host: localhost
Parsed and obfuscated weewx.conf
# WEEWX CONFIGURATION FILE
#
# Copyright (c) 2009-2015 Tom Keffer &lt;tkeffer@gmail.com&gt;
# See the file LICENSE.txt for your rights.
##############################################################################
# This section is for general configuration information.
... content removed for conciseness ...
# This section configures the internal weewx engine.
[Engine]
[[Services]]
# This section specifies the services that should be run. They are
# grouped by type, and the order of services within each group
# determines the order in which the services will be run.
prep_services = weewx.engine.StdTimeSynch
data_services = ,
process_services = weewx.engine.StdConvert, weewx.engine.StdCalibrate, weewx.engine.StdQC, weewx.wxservices.StdWXCalculate, user.weewxwd3.WdWXCalculate
archive_services = weewx.engine.StdArchive, user.weewxwd3.WdArchive, user.weewxwd3.WdSuppArchive
restful_services = weewx.restx.StdStationRegistry, weewx.restx.StdWunderground, weewx.restx.StdPWSweather, weewx.restx.StdCWOP, weewx.restx.StdWOW, weewx.restx.StdAWEKAS, user.sync.SyncService
report_services = weewx.engine.StdPrint, weewx.engine.StdReport
################################################################################
wee_debug report successfully generated
</pre>
<h2>Redirecting <span class="code">wee_debug</span> output</h2>
<p>By default, <span class="code">wee_debug</span> output is sent to the system "standard output"
(<span class="code">stdout</span>) unless the <span class="code">--output</span>
option is used. </p>
<p>Option <span class="code">--output</span> with no parameter sends output to the default file
<span class="code">/var/tmp/weewx.debug</span>. Example:</p>
<pre class="tty cmd">wee_debug --info --output</pre>
<p>Option <span class="code">--output</span> with a specified file will send it to that file.
Example:</p>
<pre class="tty cmd">wee_debug --info --output /home/weewx/another.debug</pre>
<h2><span class="code">wee_debug</span> verbosity</h2>
<p>The depth of information included in the <span class="code">wee_debug</span>
output can be changed using the <span class="code">--verbosity</span> option.
The <span class="code">--verbosity</span> 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:</p>
<table class="indent">
<tr class="first_row">
<td>Level</td>
<td>Included Information</td>
</tr>
<tr>
<td class="text_highlight" rowspan=8><span class="code">--verbosity 0</span></td>
<td>path and name of <span class="code">weewx</span> config file used (usually <span class="code">weewx.conf</span>)
</td>
</tr>
<tr>
<td>name of <span class="code">weewx</span> database binding used</td>
</tr>
<tr>
<td>operating system version</td>
</tr>
<tr>
<td><span class="code">weewx</span> version number</td>
</tr>
<tr>
<td><span class="code">weewx</span> station type and driver name</td>
</tr>
<tr>
<td>summary of currently installed extensions</td>
</tr>
<tr>
<td>summary of <span class="code">weewx</span> archive</td>
</tr>
<tr>
<td>parsed and obfusated <span class="code">weewx</span> config file (usually <span class="code">weewx.conf</span>)
</td>
</tr>
<tr>
<td class="text_highlight" rowspan=5><span class="code">--verbosity 1</span></td>
<td>as per <span class="code">--verbosity 0</span></td>
</tr>
<tr>
<td>cpu info summary</td>
</tr>
<tr>
<td>system load averages</td>
</tr>
<tr>
<td>driver config extract from <span class="code">weewx</span> config file (usually <span
class="code">weewx.conf</span>)
</td>
</tr>
<tr>
<td>summary of databases configured in <span class="code">weewx</span> config file (usually <span
class="code">weewx.conf</span>)
</td>
</tr>
<tr>
<td class="text_highlight" rowspan=3><span class="code">--verbosity 2</span></td>
<td>as per <span class="code">--verbosity 1</span></td>
</tr>
<tr>
<td>list of supported SQL keys</td>
</tr>
<tr>
<td>list of supported observation types</td>
</tr>
</table>
<!-- ======== -->
<h1 id="wee_device_utility"><span class="code">wee_device</span></h1>
<p>The utility <span class="code">wee_device</span> 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, <i>etc.</i> 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.</p>
<p>Run the utility with the <span class='code'>--help</span> option
to see which options are available.</p>
<p class="tty cmd">wee_device --help</p>
<p>The utility requires a <span class='code'>weewx.conf</span> file.
If no file is specified, it will look for
<span class='code'>weewx.conf</span> 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,</p>
<p class="tty cmd">wee_device /path/to/weewx.conf --help</p>
<p>What follows is a guide to the level of support offered by <span class="code">wee_device</span> for
each type of weather station.</p>
<h2 id="wee_device_acurite">AcuRite</h2>
<p>The <span class='code'>wee_device</span> utility cannot
configure AcuRite stations.</p>
<p>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.</p>
<p>The wind speed updates every 18 seconds. The wind direction updates
every 30 seconds. Other sensors update every 60 seconds.</p>
<p>The AcuRite stations do not record wind gusts.</p>
<p>The station emits partial packets, which may confuse some online
services</p>
<h2 id="wee_device_cc3000">CC3000</h2>
<p>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 <span class='code'>weewx</span>. However, the
CC3000 driver will convert to the appropriate units for the
<span class='code'>weewx</span> configuration.</p>
<p>The CC3000 data logger stores 2MB of records.</p>
<p>The CC3000 driver supports catchup on startup, but it does not
support hardware record generation.</p>
<p>The <span class='code'>wee_device</span> utility can be used to
configure the station hardware. When the
<span class='code'>station_type</span> is
<span class='code'>CC3000</span>,
the <span class='code'>--help</span> option will produce output
something like this:</p>
<pre class="tty">CC3000 driver version 0.8
Usage: wee_device [config_file] [options] [--debug] [--help]
Configuration utility for weewx devices.
Options:
-h, --help show this help message and exit
--debug display diagnostic information while running
-y answer yes to every prompt
--info display weather station configuration
--current display current weather readings
--history=N display N records (0 for all records)
--history-since=N display records since N minutes ago
--clear-memory clear station memory
--set-clock set station clock to computer time
--set-interval=N set logging interval to N minutes
--set-units=UNITS set units to METRIC or ENGLISH
Mutating actions will request confirmation before proceeding.</pre>
<h3>Station information</h3>
<p>Display the station settings with the <span class='code'>--info</span>
option.</p>
<pre class="tty cmd">wee_device --info</pre>
<p>This will result in something like:</p>
<pre class='tty'>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</pre>
<h3 id="cc3000_changing_the_archive_interval">Changing the archive interval</h3>
<p>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:</p>
<p class="tty cmd">wee_device --set-interval=5</p>
<h2 id="wee_device_fousb">FineOffsetUSB</h2>
<p>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.</p>
<p>The station reads data from the sensors every 48 seconds.
The 30xx stations read UV data every 60 seconds.</p>
<p>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.</p>
<p>When <span class='code'>weewx</span> starts up it will attempt
to download all records from the console since the last record in
the archive database.</p>
<p>The <span class='code'>wee_device</span> utility can be used to
configure the station hardware. When the
<span class='code'>station_type</span> is
<span class='code'>FineOffsetUSB</span>,
the <span class='code'>--help</span> option will produce output
something like this:</p>
<pre class="tty">FineOffsetUSB driver version 1.7
Usage: wee_device [config_file] [options] [--debug] [--help]
Configuration utility for weewx devices.
Options:
-h, --help show this help message and exit
--debug display diagnostic information while running
-y answer yes to every prompt
--info display weather station configuration
--current get the current weather conditions
--history=N display N records
--history-since=N display records since N minutes ago
--clear-memory clear station memory
--set-time set station clock to computer time
--set-interval=N set logging interval to N minutes
--live display live readings from the station
--logged display logged readings from the station
--fixed-block display the contents of the fixed block
--check-usb test the quality of the USB connection
--check-fixed-block monitor the contents of the fixed block
--format=FORMAT format for output, one of raw, table, or dict
Mutating actions will request confirmation before proceeding.</pre>
<h3>Station information</h3>
<p>Display the station settings with the <span class='code'>--info</span>
option.</p>
<pre class="tty cmd">wee_device --info</pre>
<p>This will result in something like:</p>
<pre class='tty'>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
<span class="highlight">data_count: 22</span>
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
<span class="highlight">read_period: 30</span>
<span class="highlight">rel_pressure: 1014.8</span>
temp_in_offset: 1792
temp_out_offset: 0
timezone: 0
unknown_01: 0
unknown_18: 0
version: 255
wind_coef: None
wind_mult: 0</pre>
<p><span class="highlight">Highlighted</span> values can be modified with the <span
class='code'>wee_device</span> utility.</p>
<h3 id="fo_changing_the_archive_interval">Changing the archive interval</h3>
<p>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:</p>
<p class="tty cmd">wee_device --set-interval=5</p>
<h3 id="fo_dumping_the_console_memory">Dumping the console memory</h3>
<p>Fine Offset stations store records in a circular buffer &mdash; 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 <span class='code'>data_count</span> indicates how many records are in memory.
The <span
class='code'>read_period</span> indicates the number of minutes between records. <span
class='code'>wee_device</span>
can display these records in space-delimited, raw bytes, or dictionary format.</p>
<p>For example, to display the most recent 30 records from the console memory:</p>
<pre class="tty cmd">wee_device --history=30</pre>
<p>To clear the console memory:</p>
<pre class="tty cmd">wee_device --clear-memory</pre>
<h3>Checking the USB quality</h3>
<p>Use the <span class='code'>wee_device</span> 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.</p>
<p>To test the quality of the USB connection to the console:</p>
<pre class="tty cmd">wee_device --check-usb</pre>
<p>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.</p>
<h3 id="polling_mode_and_the_polling_interval">Polling mode and the polling interval</h3>
<p>When reading 'live' data, <span class='code'>weewx</span> can read as fast as possible, or at a
user-defined
period. This is controlled by the <span class='code'>polling_mode</span> parameter.
</p>
<table class='indent'>
<caption>Polling modes for Fine Offset stations</caption>
<tr class="first_row">
<td width='15%'>Mode</td>
<td width='30%'><span class='code'>weewx.conf</span></td>
<td>Notes</td>
</tr>
<tr>
<td class="first_col">ADAPTIVE</td>
<td>
<pre class='tty' style='margin:0'>[FineOffsetUSB]
polling_mode = ADAPTIVE</pre>
</td>
<td>
<p>In this mode, <span class='code'>weewx</span> 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.</p>
</td>
</tr>
<tr>
<td class="first_col">PERIODIC</td>
<td>
<pre class='tty' style='margin:0'>[FineOffsetUSB]
polling_mode = PERIODIC
polling_interval = 60</pre>
</td>
<td>
<p>In this mode, <span class='code'>weewx</span> reads data from the station every <span
class='code'>polling_interval</span>
seconds.</p>
<p>The console reads the sensors every 48 seconds (60 seconds for UV), so setting the <span
class='code'>polling_interval</span> to a value less than 48 will result in duplicate
readings.
</p>
</td>
</tr>
</table>
<h2 id="wee_device_te923">TE923</h2>
<p>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
<span class='code'>map</span> in
<span class='code'>weewx.conf</span> to associate each sensor with a
database field.
</p>
<p>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.</p>
<p>The TE923 driver will read history records from the station when weewx
starts up, but it does not support hardware record generation.</p>
<p>The <span class='code'>wee_device</span> utility can be used to
configure the station hardware. When the
<span class='code'>station_type</span> is
<span class='code'>TE932</span>,
the <span class='code'>--help</span> option will produce output
something like this:</p>
<pre class='tty'>Using configuration file /home/weewx/weewx.conf
Using TE923 driver version 0.16 (weewx.drivers.te923)
Usage: wee_device [config_file] [options] [--debug] [--help]
Configuration utility for weewx devices.
Options:
-h, --help show this help message and exit
--debug display diagnostic information while running
-y answer yes to every prompt
--info display weather station configuration
--current get the current weather conditions
--history=N display N history records
--history-since=N display history records since N minutes ago
--minmax display historical min/max data
--get-date display station date
--set-date=YEAR,MONTH,DAY
set station date
--get-location-local display local location and timezone
--set-location-local=CITY|USR,LONG_DEG,LONG_MIN,E|W,LAT_DEG,LAT_MIN,N|S,TZ,DST
set local location and timezone
--get-location-alt display alternate location and timezone
--set-location-alt=CITY|USR,LONG_DEG,LONG_MIN,E|W,LAT_DEG,LAT_MIN,N|S,TZ,DST
set alternate location and timezone
--get-altitude display altitude
--set-altitude=ALT set altitude
--get-alarms display alarms
--set-alarms=WEEKDAY,SINGLE,PRE_ALARM,SNOOZE,MAXTEMP,MINTEMP,RAIN,WIND,GUST
set alarm state
--get-interval display archive interval
--set-interval=INTERVAL
set archive interval
--format=FORMAT formats include: table, dict
Be sure to stop weewx first before using. Mutating actions will request
confirmation before proceeding.</pre>
<h3>Station information</h3>
<p>Use the <span class="code">--info</span> option to display the
station configuration:</p>
<pre class="tty cmd">wee_device --info</pre>
<p>This will result in something like:</p>
<pre class="tty">Querying the station for the configuration...
altitude: 16
bat_1: True
bat_2: True
bat_3: True
bat_4: True
bat_5: True
bat_rain: True
bat_uv: False
bat_wind: True
latitude: 43.35
longitude: -72.0
version_bar: 23
version_rcc: 16
version_sys: 41
version_uv: 20
version_wind: 38</pre>
<h3>Display sensor status</h3>
<p>Use the <span class="code">--current</span> option to display the
current status of each sensor:</p>
<pre class="tty cmd">wee_device --current</pre>
<p>This will result in something like:</p>
<pre class="tty">Querying the station for current weather data...
dateTime: 1454615168
forecast: 5
h_1: 41
h_1_state: ok
h_2: 48
h_2_state: ok
h_3: None
h_3_state: no_link
h_4: None
h_4_state: no_link
h_5: None
h_5_state: no_link
h_in: 44
h_in_state: ok
rain: 2723
rain_state: ok
slp: 1012.4375
slp_state: ok
storm: 0
t_1: 13.9
t_1_state: ok
t_2: 21.5
t_2_state: ok
t_3: None
t_3_state: no_link
t_4: None
t_4_state: no_link
t_5: None
t_5_state: no_link
t_in: 22.85
t_in_state: ok
uv: None
uv_state: no_link
windchill: None
windchill_state: invalid
winddir: 12
winddir_state: invalid
windgust: None
windgust_state: invalid
windspeed: None
windspeed_state: invalid</pre>
<h3 id="te923_changing_the_archive_interval">Changing the archive interval</h3>
<p>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:</p>
<p class="tty cmd">wee_device --set-interval=300</p>
<h3 id="te923_dumping_the_logger_memory">Dumping the logger memory</h3>
<p><span class='code'>wee_device</span> can display the records from the
logger in tabular or dictionary format.</p>
<p>For example, to display the most recent 30 records:</p>
<pre class="tty cmd">wee_device --history=30 --format dict</pre>
<h2 id="wee_device_ultimeter">Ultimeter</h2>
<p>The <span class='code'>wee_device</span> utility cannot
configure Ultimeter stations.</p>
<p>The Ultimeter driver operates the Ultimeter in Data Logger Mode,
which results in sensor readings every 1/2 second or so.</p>
<p>The Ultimeter driver ignores the maximum, minimum, and average
values recorded by the station.</p>
<h2 id="wee_device_vantage">Vantage</h2>
<p>When the <span class='code'>station_type</span> is
<span class='code'>Vantage</span>,
the <span class='code'>--help</span> option will produce output
something like this:</p>
<pre class="tty">Using configuration file /home/weewx/weewx.conf
Using Vantage driver version 3.0 (weewx.drivers.vantage)
Usage: wee_device [config_file] [--help] [--info] [--clear]
[--set-interval=SECONDS] [--set-altitude=FEET] [--set-barometer=inHg]
[--set-bucket=CODE] [--set-rain-year-start=MM]
[--set-offset=VARIABLE,OFFSET]
[--set-transmitter-type=CHANNEL,TYPE,TEMP,HUM]
[--set-time] [--set-dst=[AUTO|ON|OFF]]
[--set-tz-code=TZCODE] [--set-tz-offset=HHMM]
[--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
--debug display diagnostic information while running
-y answer yes to every prompt
--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-offset=VARIABLE,OFFSET
Set the onboard offset for VARIABLE inTemp, outTemp,
extraTemp[1-7], inHumid, outHumid, extraHumid[1-7],
soilTemp[1-4], leafTemp[1-4], windDir) to OFFSET
(Fahrenheit, %, degrees)
--set-transmitter-type=CHANNEL,TYPE,TEMP,HUM
Set the transmitter type for CHANNEL (1-8), TYPE
(0=iss, 1=temp, 2=hum, 3=temp_hum, 4=wind, 5=rain,
6=leaf, 7=soil, 8=leaf_soil, 9=sensorlink, 10=none),
as extra TEMP station and extra HUM station (both 1-7,
if applicable)
--set-time Set the onboard clock to the current time.
--set-dst=AUTO|ON|OFF
Set DST to 'ON', 'OFF', or 'AUTO'
--set-tz-code=TZCODE Set timezone code to TZCODE. See your Vantage manual
for valid codes.
--set-tz-offset=HHMM Set timezone offset to HHMM. E.g. '-0800' for U.S.
Pacific 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).
Be sure to stop weewx first before using. Mutating actions will request
confirmation before proceeding.</pre>
<h3>Station information</h3>
<p>Use the <span class="code">--info</span> option to display the
current EEPROM settings: </p>
<pre class="tty cmd">wee_device --info</pre>
<p>This will result in something like:</p>
<pre class="tty">Davis Vantage EEPROM settings:
CONSOLE TYPE: VantagePro2
CONSOLE FIRMWARE:
Date: Dec 11 2012
Version: 3.12
CONSOLE SETTINGS:
<span class="highlight">Archive interval: 300 (seconds)</span>
<span class="highlight">Altitude: 700 (foot)</span>
Wind cup type: large
<span class="highlight">Rain bucket type: 0.01 inches</span>
<span class="highlight">Rain year start: 10</span>
<span class="highlight">Onboard time: 2014-09-25 07:41:14</span>
CONSOLE DISPLAY UNITS:
Barometer: inHg
Temperature: degree_F
Rain: inch
Wind: mile_per_hour
CONSOLE STATION INFO:
Latitude (onboard): 45.7
Longitude (onboard): -121.6
<span class="highlight">Use manual or auto DST? AUTO</span>
<span class="highlight">DST setting: N/A</span>
<span class="highlight">Use GMT offset or zone code? ZONE_CODE</span>
<span class="highlight">Time zone code: 4</span>
<span class="highlight">GMT offset: N/A</span>
TRANSMITTERS:
<span class="highlight">Channel 1: iss</span>
<span class="highlight">Channel 2: (N/A)</span>
<span class="highlight">Channel 3: temp (as extra temperature 1)</span>
<span class="highlight">Channel 4: (N/A)</span>
<span class="highlight">Channel 5: (N/A)</span>
<span class="highlight">Channel 6: (N/A)</span>
<span class="highlight">Channel 7: (N/A)</span>
<span class="highlight">Channel 8: (N/A)</span>
RECEPTION STATS:
Total packets received: 10670
Total packets missed: 128
Number of resynchronizations: 0
Longest good stretch: 934
Number of CRC errors: 651
BAROMETER CALIBRATION DATA:
<span class="highlight">Current barometer reading: 29.834 inHg</span>
<span class="highlight">Altitude: 700 feet</span>
Dew point: 55 F
Virtual temperature: 59 F
Humidity correction factor: 27
Correction ratio: 1.025
Correction constant: +0.000 inHg
Gain: 0.000
Offset: -47.000
OFFSETS:
<span class="highlight">Wind direction: +0 deg</span>
<span class="highlight">Inside Temperature: +0.0 F</span>
<span class="highlight">Inside Humidity: +0%</span>
<span class="highlight">Outside Temperature: +0.0 F</span>
<span class="highlight">Outside Humidity: +0%</span>
<span class="highlight">Extra Temperature 1: +0.0 F</span></pre>
<p>The console version number is available only on consoles with firmware
dates after about 2006.</p>
<p><span class="highlight">Highlighted</span> values can be changed using this utility.</p>
<h3 id="vantage_time_zone">Time zone</h3>
<p>To set the time zone code to Central European Time (code 20):</p>
<pre class="tty cmd">wee_device --set-tz-code=20</pre>
<p class="warning">You can set either the time zone code <em>or</em> the
time zone offset, but not both. </p>
<h3 id="vantage_archive_interval">Archive interval</h3>
<p>Valid archive intervals for the Davis Vantage stations are 60,
300, 600, 900, 1800, 3600, and 7200 seconds. However, if you are
ftp&#39;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.</p>
<p>To change the archive interval to 10 minutes (600 seconds):</p>
<pre class="tty cmd">wee_device --set-interval=600</pre>
<p>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. </p>
<h3 id="vantage_rain_bucket_type">Rain bucket type</h3>
<p>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 &quot;2&quot;), use the
following:</p>
<pre class="tty cmd">wee_device --set-bucket=2</pre>
<h3 id="vantage_configuring_additional_sensors">Additional sensors</h3>
<p>If you have additional sensors for your Vantage station, you
can configure them using your console. However, if you have
a <a href="http://www.davisnet.com/weather/products/weather_product.asp?pnum=06316">Davis
Weather Envoy receiver</a>, it will not have a console! As an alternative,
the <span class='code'>weewx</span>
utility <span class="code">wee_device</span> lets
you do this from the command line.</p>
<p>For example, to add an extra temperature sensor to channel 3, do the following:</p>
<pre class="tty cmd">wee_device --set-transmitter-type=3,1,2</pre>
<p>This says to turn on channel 3, set its type to 1 ("Temperature only"), and have it show up in the
database as <span class="code">extraTemp2</span>. Here's another example, this time for a combined
temperature / humidity sensor:</p>
<pre class="tty cmd">wee_device --set-transmitter-type=5,3,2,4</pre>
<p>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 <span class="code">extraTemp2</span> and <span class="code">extraHumid4</span>.</p>
<p>The <span class="code">--help</span> option will give you the code for each sensor type.</p>
<h3 id="vantage_setting_offsets">Setting offsets</h3>
<p>The Davis instruments can correct sensor errors by adding
an <em>offset</em> 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&deg; error in the wind direction. The solution is to add a
180&deg; offset correction. You can do this with the following
command:</p>
<pre class="tty cmd">wee_device --set-offset=windDir,180</pre>
<h3 id="vantage_dumping_the_logger_memory">Dumping the logger memory</h3>
<p>Generally, <span class="code">weewx</span> 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 <em><a href="#html_generated_but_not_updated">Weewx
generates HTML pages, but it does not update them</a></em>. 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 <span class="code">--dump</span> command
before clearing the memory, you might be able to save these data.
Stop <span class="code">weewx</span> first, then</p>
<pre class="tty cmd">wee_device --dump</pre>
<p>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 <em>all</em> data, it may result in many
duplicate primary key errors. These can be ignored.</p>
<h2 id="wee_device_wmr100">WMR100</h2>
<p>The <span class='code'>wee_device</span> utility cannot
configure WMR100 stations.</p>
<p>The station emits partial packets, which may confuse some online
services.</p>
<h2 id="wee_device_wmr200">WMR200</h2>
<p>The <span class='code'>wee_device</span> utility cannot
configure WMR200 stations.</p>
<p>The station emits partial packets, which may confuse some online
services.</p>
<p>When <span class='code'>weewx</span> starts up it will attempt to
download all records from the console since the last record in the
archive database.
</p>
<h2 id="wee_device_wmr300">WMR300</h2>
<p>The <span class='code'>wee_device</span> utility cannot
configure WMR300 stations.</p>
<p>The station emits partial packets, which may confuse some online
services.</p>
<p>When <span class='code'>weewx</span> 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.
</p>
<h2 id="wee_device_wmr9x8">WMR9x8</h2>
<p>The <span class='code'>wee_device</span> utility cannot
configure WMR9x8 stations.</p>
<p>The station includes a data logger, but the driver does not read
records from the station.</p>
<p>The station emits partial packets, which may confuse some online
services.</p>
<h2 id="wee_device_ws1">WS1</h2>
<p>The <span class='code'>wee_device</span> utility cannot
configure WS1 stations.</p>
<p>The WS1 stations produce data every 1/2 second or so.</p>
<h2 id="wee_device_ws23xx">WS23xx</h2>
<p>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.</p>
<p>The station does not record wind gust or wind gust direction.</p>
<p>The hardware calculates windchill and dewpoint.</p>
<p>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.</p>
<p>When <span class='code'>weewx</span> starts up it will attempt
to download all records from the console since the last record in
the archive database.</p>
<p>When the <span class='code'>station_type</span> is
<span class='code'>WS23xx</span>,
the <span class='code'>--help</span> option will produce output
something like this:</p>
<pre class="tty">WS23xx driver version 0.21
Usage: wee_device [config_file] [options] [--debug] [--help]
Configuration utility for weewx devices.
Options:
-h, --help show this help message and exit
--debug display diagnostic information while running
-y answer yes to every prompt
--info display weather station configuration
--current get the current weather conditions
--history=N display N history records
--history-since=N display history records since N minutes ago
--clear-memory clear station memory
--set-time set the station clock to the current time
--set-interval=N set the station archive interval to N minutes
Mutating actions will request confirmation before proceeding.</pre>
<h3>Station information</h3>
<p>Display the station settings with the <span class='code'>--info</span>
option.</p>
<pre class="tty cmd">wee_device --info </pre>
<p>This will result in something like:</p>
<pre class='tty'>buzzer: 0
connection time till connect: 1.5
connection type: 15
dew point: 8.88
dew point max: 18.26
dew point max alarm: 20.0
dew point max alarm active: 0
dew point max alarm set: 0
dew point max when: 978565200.0
dew point min: -2.88
dew point min alarm: 0.0
dew point min alarm active: 0
dew point min alarm set: 0
dew point min when: 978757260.0
forecast: 0
history interval: 5.0
history last record pointer: 8.0
history last sample when: 1385564760.0
history number of records: 175.0
history time till sample: 5.0
icon alarm active: 0
in humidity: 48.0
...</pre>
<h3 id="ws23xx_changing_the_archive_interval">Changing the archive interval</h3>
<p>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:</p>
<p class="tty cmd">wee_device --set-interval=5</p>
<p class="warning"><strong>Warning!</strong><br/>
Changing the recording interval will clear the station memory.</p>
<h3 id="ws23xx_dumping_the_console_memory">Dumping the console memory</h3>
<p>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 <span class='code'>history number of records</span> indicates how
many records are in memory. The
<span class='code'>history interval</span> indicates the number of
minutes between records.</p>
<p>For example, to display the latest 30 records from the console memory:</p>
<pre class="tty cmd">wee_device --history=30</pre>
<p>To clear the console memory:</p>
<pre class="tty cmd">wee_device --clear-memory</pre>
<h2 id="wee_device_ws28xx">WS28xx</h2>
<p><span class='code'>weewx</span> 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.</p>
<p>The station has 1797 history records. That is just over 6 days
of data with an archive interval of 5 minutes.</p>
<p>When <span class='code'>weewx</span> starts up it will attempt to
download all records from the console since the last record in the
archive database.
</p>
<p>The WS28xx driver sets the station archive interval to
5 minutes.</p>
<p>The WS28xx driver does not support hardware archive record
generation.</p>
<p>When the <span class='code'>station_type</span> is
<span class='code'>WS28xx</span>,
the <span class='code'>--help</span> option will produce output
something like this:</p>
<pre class="tty">WS28xx driver version 0.33
Usage: wee_device [config_file] [options] [--debug] [--help]
Configuration utility for weewx devices.
Options:
-h, --help show this help message and exit
--debug display diagnostic information while running
-y answer yes to every prompt
--check-transceiver check USB transceiver
--pair pair the USB transceiver with station console
--info display weather station configuration
--set-interval=N set logging interval to N minutes
--current get the current weather conditions
--history=N display N history records
--history-since=N display history records since N minutes ago
--maxtries=MAXTRIES maximum number of retries, 0 indicates no max
Mutating actions will request confirmation before proceeding.</pre>
<h3>Pairing</h3>
<p>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.</p>
<p>There are two ways to pair the console and the transceiver:</p>
<ol>
<li><strong>The Weewx way.</strong> Be sure that
<span class='code'>weewx</span> 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.
<pre class='tty'><span class="cmd">wee_device --pair</span>
Pairing transceiver with console...
Press and hold the [v] key until "PC" appears (attempt 1 of 3)
Transceiver is paired to console</pre>
</li>
<li><strong>The HeavyWeather way.</strong> 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 <span class="code">weewx</span> computer and start weewx.
Do not power cycle the station console or you will have to start
over.
</li>
</ol>
<p>If the console does not pair, you will see messages in the log such as
this:</p>
<pre class='tty'>ws28xx: RFComm: message from console contains unknown device ID (id=165a resp=80 req=6)</pre>
<p>Either approach to pairing may require multiple attempts.</p>
<h3>Synchronizing</h3>
<p>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.</p>
<p>When the transceiver and console are synchronized, you will see lots of
'<span class="code">ws28xx: RFComm</span>' messages in the log when <span class="code">debug=1</span>.
When the
devices are
not synchronized, you will see messages like this about every 10
minutes:</p>
<pre class='tty'>Nov 7 19:12:17 raspi weewx[2335]: ws28xx: MainThread: no contact with console</pre>
<p>If you see this, or if you see an extended gap in the weather data
in the <span class="code">weewx</span> plots, press momentarily the [SET] button, or wait until
the top of the hour.</p>
<p>When the transceiver has not received new data for awhile, you will see
messages like this in the log:</p>
<pre class='tty'>Nov 7 19:12:17 raspi weewx[2335]: ws28xx: MainThread: no new weather data</pre>
<p>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.</p>
<h3>Station information</h3>
<p>Display the station settings with the <span class='code'>--info</span>
option.</p>
<p class="tty cmd">wee_device --info</p>
<p>This will result in something like:</p>
<pre class='tty'>alarm_flags_other: 0
alarm_flags_wind_dir: 0
checksum_in: 1327
checksum_out: 1327
format_clock: 1
format_pressure: 0
format_rain: 1
format_temperature: 0
format_windspeed: 4
history_interval: 1
indoor_humidity_max: 70
indoor_humidity_max_time: None
indoor_humidity_min: 45
indoor_humidity_min_time: None
indoor_temp_max: 40.0
indoor_temp_max_time: None
indoor_temp_min: 0.0
indoor_temp_min_time: None
lcd_contrast: 4
low_battery_flags: 0
outdoor_humidity_max: 70
outdoor_humidity_max_time: None
outdoor_humidity_min: 45
outdoor_humidity_min_time: None
outdoor_temp_max: 40.0
outdoor_temp_max_time: None
outdoor_temp_min: 0.0
outdoor_temp_min_time: None
pressure_max: 1040.0
pressure_max_time: None
pressure_min: 960.0
pressure_min_time: None
rain_24h_max: 50.0
rain_24h_max_time: None
threshold_storm: 5
threshold_weather: 3
wind_gust_max: 12.874765625
wind_gust_max_time: None</pre>
<h3>Alarms</h3>
<p>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 <span class="code">weewx</span> alarms
can do much more than the console alarms anyway.</p>
<!-- ======== -->
<h1 id="wee_extension_utility"><span class="code">wee_extension</span></h1>
<p>
The utility <span class="code">wee_extension</span> is used to add and
remove extensions. It's worth running with the
<span class="code">--help</span>
option to see how it is used:
</p>
<pre class="tty cmd">wee_extension --help</pre>
<p>This results in:</p>
<pre class="tty">
Usage: wee_extension --help
wee_extension --list
[CONFIG_FILE|--config=CONFIG_FILE]
wee_extension --install=(filename|directory)
[CONFIG_FILE|--config=CONFIG_FILE]
[--tmpdir==DIR] [--dry-run] [--verbosity=N]
wee_extension --uninstall=EXTENSION
[CONFIG_FILE|--config=CONFIG_FILE]
[--verbosity=N]
Install, list, and uninstall extensions to weewx.
Commands:
--list: Show installed extensions.
--install: Install the specified extension.
--uninstall: Uninstall the specified extension.
Options:
-h, --help show this help message and exit
--list Show installed extensions.
--install=FILENAME|DIRECTORY
Install the extension contained in FILENAME or
DIRECTORY. FILENAME must be an archive that contains a
packaged extension such as pmon.tar.gz. DIRECTORY
must be a packaged extension.
--uninstall=EXTENSION
Uninstall the extension with name EXTENSION.
--config=CONFIG_FILE Use configuration file CONFIG_FILE.
--tmpdir=DIR Use temporary directory DIR.
--bin-root=BIN_ROOT Look in BIN_ROOT for weewx executables.
--dry-run Print what would happen but do not do it.
--verbosity=N How much status to display, 0-3</pre>
<p>To install an extension:</p>
<pre class='tty cmd'>wee_extension --install extensions/basic
wee_extension --install basic.tar.gz</pre>
<p>To uninstall an extension:</p>
<p class='tty cmd'>wee_extension --uninstall basic</p>
<p>To list installed extensions:</p>
<p class='tty cmd'>wee_extension --list</p>
<p>The utility will make only the following changes:</p>
<ul>
<li>Modifications to <span class='code'>weewx.conf</span></li>
<li>Add/Remove directories in <span class='code'>skins</span></li>
<li>Add/Remove directories in <span class='code'>user</span></li>
</ul>
<p>The utility makes a copy of any file or directory that it
modifies or replaces. When installing, it creates a directory called
<span class='code'>installer</span> in the
<span class='code'>user</span> directory. The contents of the
<span class='code'>installer</span> directory are
used to enumerate and uninstall extensions.</p>
<h2>Installing an extension</h2>
<p>
Let's try installing a simple extension,
<a href="https://github.com/weewx/weewx/wiki/cmon"><em>cmon</em></a>,
used to monitor your computer.
</p>
<p>
First download it. You can either do this from the link given in the
wiki, or by using <span class="code">wget</span> (which you may have
to install):
</p>
<pre class="tty cmd">wget -P /var/tmp http://lancet.mit.edu/mwall/projects/weather/releases/weewx-cmon-0.7.tgz</pre>
<p>
This will put the tarfile <span class="code">weewx-cmon-0.7.tgz</span>
in the directory <span class="code">/var/tmp</span>.
</p>
<p>Now install the extension:</p>
<pre class="tty"><span class="cmd">wee_extension --install=/var/tmp/weewx-cmon-0.7.tgz</span>
Request to install '/var/tmp/weewx-cmon-0.7.tgz'
Extracting from tarball /var/tmp/weewx-cmon-0.7.tgz
Added new service user.cmon.ComputerMonitor to process_services
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'</pre>
<p>The installer has done a number of things for you:</p>
<ol>
<li>It put a new skin, <span class="code">cmon</span>, in the
<span class="code">skins</span> subdirectory;
</li>
<li>It put a new service,
<span class="code">user.cmon.ComputerMonitor</span>,
in the list of services to be run by
<span class="code">weewx</span>;
</li>
<li>It defined a new database, <span class="code">cmon_sqlite</span>,
and a binding, <span class="code">cmon_binding</span>,
to that database;
</li>
<li>It added a top-level "stanza"
<span class="code">[ComputerMonitor]</span>
to your configuration file <span class="code">weewx.conf</span>,
that specifies the data binding <span class="code">cmon</span>
is to use.
</li>
<li>And, finally, it saved the details of how the extension was
installed so you can remove it later, should you choose to do so.
</li>
</ol>
<h2>Listing installed extensions</h2>
<p>The utility <span class="code">wee_extension</span> can tell you which
extensions you have installed:</p>
<pre class="tty"><span class="cmd">wee_extension --list</span>
Extension Name Version Description
cmon 0.7 Collect and display computer health indicators</pre>
<p>You can see it lists the extension we just installed, <span class="code">cmon</span>.</p>
<h2>Removing extensions</h2>
<p>You can remove an extension using the same tool:</p>
<pre class="tty"><span class="cmd">wee_extension --uninstall=cmon
wee_extension --list</span>
No extensions installed</pre>
<!-- ======== -->
<h1 id="wee_import_utility"><span class="code">wee_import</span></h1>
<p>Some <span class="code">weewx</span> 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 <span class="code">weewx</span>.
Such data can, depending upon the source, be imported
using the <span class="code">wee_import</span> utility. This section
details the use of the <span class="code">wee_import</span> utility.
</p>
<p>The <span class="code">wee_import</span> utility supports importing
observational data from the following sources:</p>
<ul>
<li>a single Comma Separated Values (CSV) format file</li>
<li>the historical observations of a Weather Underground personal
weather station
</li>
<li>one or more Cumulus monthly log files</li>
</ul>
<p>Before starting, it's worth running the utility with the
<span class="config_option">--help</span> flag to see how
<span class="code">wee_import</span> is used:</p>
<pre class="tty cmd">wee_import --help</pre>
<p>This will result in an output that looks something like this:</p>
<pre class="tty">Usage: wee_import --help
wee_import --version
wee_import --import-config=IMPORT_CONFIG_FILE
[--config=CONFIG_FILE]
[--date=YYYY/MM/DD|'YYYY/MM/DD hh:mm'|'YYYY/MM/DD (hh:mm)-YYYY/MM/DD (hh:mm)']
[--dry-run]
[--verbose]
[--log=-]
Import observation data into a weewx archive.
Options:
-h, --help show this help message and exit
--config=CONFIG_FILE Use weewx configuration file CONFIG_FILE.
--import-config=IMPORT_CONFIG_FILE
Use import configuration file IMPORT_CONFIG_FILE.
--dry-run Print what would happen but do not do it.
--date=YYYY-MM-DD Date or time to import as a string of form YYYY/MM/DD
or 'YYYY/MM/DD hh:mm'. A date range or date-time range
may be specified by separating two date strings or two
date-time strings with a hyphen. Arguments that
include hh:mm must be enclosed in quotation marks.
--log=- Control wee_import log output. By default log output
is sent to the weewx log file. wee_import logging may
be disabled by using '--log=-'. Some weewx API log
output cannot be controlled by wee_import and will be
sent to to the default log file irrespective of the '
--log' option.
--verbose Print useful extra output.
--version Display wee_import version number.
wee_import will import data from an external source into a weewx
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.</pre>
<h2><span id='common_options'>Command line options</span></h2>
<p>The <span class="code">wee_import</span> command line options are
described in more detail below:</p>
<h4><span class="config_option">--config</span></h4>
<p>The utility is pretty good at "guessing" where your configuration file
<span class="code">weewx.conf</span> is, but if you've done an unusual
install, you may have to tell it explicitly. You can do this by using
the <span class="config_option">--config</span> option:</p>
<pre class="tty cmd">wee_import --config=/this/folder/weewx.conf --import-config=/folder/import.conf
</pre>
<h4><span class="config_option">--import-config</span></h4>
<p><span class="code">wee_import</span> uses a secondary configuration file to
store various import parameters. The
<span class="config_option">--import-config</span> command line option
is mandatory for all imports. Example import configuration files for
each type of import supported by <span class="code">wee_import</span>
are provided in the <span class="code">util/import</span> 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 <span class="config_option">--import-config</span>
command line option is used as follows:</p>
<pre class="tty cmd">wee_import --import-config=/folder/import.conf
</pre>
<h4><span class="config_option">--dry-run</span></h4>
<p>The inclusion of the <span class="config_option">--dry-run</span> 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.</p>
<pre class="tty cmd">wee_import --import-config=/folder/import.conf --dry-run
</pre>
<h4><span class="config_option">--date</span></h4>
<p>The date-time range of records to be imported can be specified by use of
the <span class="config_option">--date</span> command line option. The
<span class="config_option">--date</span> 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 <span class="code">YYYY/MM/DD</span> and
the date-time format <span class="code">YYYY/MM/DD HH:MM</span>. A range
is specified by separating two date or date-time formats by a hyphen,
e.g., <span class="code">'2015/12/1-2015/12/30'</span>. Note that the
date-time or date-time range string must be enclosed in single or double
quotation marks. The effect of the different
<span class="config_option">--date</span> command line option values
is shown in the following table:</p>
<table class="indent" summary="--date_option operation">
<tbody>
<tr class="first_row">
<td>command line option</td>
<td>Records imported for a CSV or Cumulus import</td>
<td>Records imported for a Weather Underground import</td>
</tr>
<tr>
<td class="code first_col">omitted<br>(i.e., the default)</td>
<td>All available records</td>
<td>Todays records only</td>
</tr>
<tr>
<td class="code first_col">--date 2015/12/22</td>
<td>All records from 2015/12/22 00:00 (inclusive) to 2015/12/23 00:00 (exclusive)</td>
<td>All records from 2015/12/22 00:00 (inclusive) to 2015/12/23 00:00 (exclusive)</td>
</tr>
<tr>
<td class="code first_col">--date "2015/12/22 22:30"</td>
<td>The record timestamped 2015/12/22 22:30 only</td>
<td>The record timestamped 2015/12/22 22:30 only</td>
</tr>
<tr>
<td class="code first_col">--date 2015/12/22-2016/02/20</td>
<td>All records from 2015/12/22 00:00 (inclusive) to 2016/2/21 00:00 (exclusive)</td>
<td>All records from 2015/12/22 00:00 (inclusive) to 2016/2/21 00:00 (exclusive)</td>
</tr>
<tr>
<td class="code first_col">--date "2016/3/18&nbsp15:29-2016/6/20&nbsp22:00"</td>
<td>All records from 2016/3/18 15:29 (inclusive) to 2016/6/20 22:00 (exclusive)</td>
<td>All records from 2016/3/18 15:29 (inclusive) to 2016/6/20 22:00 (exclusive)</td>
</tr>
</tbody>
</table>
<p class="note">
<b>Note</b><br/>If the <span class="config_option">--date</span>
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.
</p>
<h4><span class="config_option">--log</span></h4>
<p>The <span class="config_option">--log</span> option controls the
<span class="code">wee_import</span> log output. Omitting the option
will result in <span class="code">wee_import</span> log output being
sent to the <span class="code">weewx</span> log file (nominally the
system log, refer to
<em><a href="usersguide.htm#monitoring">Monitoring <span class="code">weewx</span></a></em>
and
<em><a href="usersguide.htm#Where_to_find_things">Where to find things</a></em>
to find it). <span class="code">wee_import</span> log output can be
disabled by using <span class="config_option">--log=-</span>. The
<span class="config_option">--log</span> command line option is used as
follows:
</p>
<pre class="tty cmd">wee_import --import-config=/folder/import.conf --log=-
</pre>
<h4><span class="config_option">--verbose</span></h4>
<p>Inclusion of the <span class="config_option">--verbose</span> command
line option will cause additional information to be printed during
<span class="code">wee_import</span> execution.</p>
<pre class="tty cmd">wee_import --import-config=/folder/import.conf --verbose
</pre>
<h2>Importing from CSV files</h2>
<p><span class="code">wee_import</span> can import data from
a single CSV file. The CSV source file must be
structured as follows:</p>
<ul>
<li>The file must have a header row consisting of a comma separated
list of field names. The field names can be any valid string as long
as each field name is unique within the list. There is no
requirement for the field names to be in any particular order as
long as the same order is used for the observations on each row in
the file. These field names will be mapped to
<span class="code">weewx</span> field names in the
<span class="code">[CSV]</span> section of the import configuration
file.
</li>
<li>Observation data for a given date-time must be listed on a
single line with individual fields separated by a comma. The fields
must be in the same order as the field names in the header row.
</li>
<li>Blank fields are represented by the use of white space or no
space only between commas.
</li>
<li>There must a field that represents the date-time of the
observations on each line. This date-time field must be either a
Unix epoch timestamp or any date-time format that can be
represented using <em>
<a href="https://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior">Python
strptime() format codes</a></em>.
</li>
</ul>
<p>A CSV file suitable for import by <span class="code">wee_import</span>
may look like this:</p>
<pre class="tty">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
2016-02-01 00:05:00,13.4,9.3,1005.6,355,0.0,0.0,76,12.0,0.00
2016-02-01 00:10:00,13.3,9.4,1005.6,259,0.0,1.6,77,14.0,0.00
2016-02-01 00:20:00,13.2,9.4,1005.6,10,0.0,1.6,78,16.0,0.00
2016-02-01 00:25:00,13.2,9.6,1005.6,15,0.0,1.6,79,20.0,0.00
2016-02-01 00:30:00,13.1,9.6,1005.3,13,0.0,0.0,79,20.0,0.00
2016-02-01 00:35:00,13.1,9.7,1005.3,22,1.6,3.2,80,20.0,0.00
2016-02-01 00:40:00,13.0,9.6,1005.3,25,0.0,1.6,80,22.0,0.00
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</pre>
<h3><span class="code">weewx</span> archive fields populated during a CSV import</h3>
<p>The <span class="code">weewx</span> archive fields populated during a
CSV import depend on the CSV-to-<span class="code">weewx</span> field
mappings specified in <span class="code">[CSV]</span> section in the
import configuration file. If a valid field mapping exists, the
<span class="code">weewx</span> field exists in the
<span class="code">weewx</span> archive table schema and provided the
mapped CSV field contains valid data, then the corresponding
<span class="code">weewx</span> field will populated. Note that the CSV
import is the only import supported by
<span class="code">wee_import</span> that allows any
<span class="code">weewx</span> archive field to be populated.
</p>
<p class="note">
<b>Note</b><br/>The use of the
<span class="config_option"><a href="#csv_calc_missing">calc_missing</a></span> 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.
</p>
<h3>Importing observations from a CSV file</h3>
<p>To import observations from a CSV file:</p>
<ol>
<li>Ensure the source data file is in a folder accessible by the machine
that will run <span class="code">wee_import</span>. For the
purposes of these instructions the source data file
<span class="code">data.csv</span> located in the
<span class="code">/var/tmp</span> folder will be used.
</li>
<li>Make a backup of the
<span class="code">weewx</span> database in case the import
should go awry.
</li>
<li>Create an import configuration file.
In this case we will make a copy of the example CSV
import configuration file and save it as
<span class="code">csv.conf</span> in the
<span class="code">/var/tmp</span> directory:
</li>
<pre class="tty cmd">$ cp /home/weewx/util/import/csv-example.conf /var/tmp/csv.conf
</pre>
<li>Confirm that the <span class="code"><a href="#import_config_source">source</a></span> option is set to
CSV:
</li>
<pre class="tty">source = CSV</pre>
<li>Confirm that the following options in the <span class="code">[CSV]</span>
section are set:
</li>
<ul>
<li><strong><span class="code"><a href="#csv_file">file</a></span></strong>.
The full path and file name of the file containing the CSV
formatted data to be imported.
</li>
<li><strong><span class="code"><a href="#csv_interval">interval</a></span></strong>.
Determines how the <span class="code">weewx</span> interval
field is derived.
</li>
<li><strong><span class="code"><a href="#csv_qc">qc</a></span></strong>. Determines
whether quality control checks are performed on the imported
data.
</li>
<li><strong><span class="code"><a href="#csv_calc_missing">calc_missing</a></span></strong>.
Determines whether missing derived observations will be
calculated from the imported data.
</li>
<li><strong><span class="code"><a href="#csv_tranche">tranche</a></span></strong>. The
number of records written to the
<span class="code">weewx</span> database in each transaction.
</li>
<li><strong><span class="code"><a href="#csv_UV">UV_sensor</a></span></strong>.
Whether a UV sensor was installed when the source data was
produced.
</li>
<li><strong><span class="code"><a href="#csv_solar">solar_sensor</a></span></strong>.
Whether a solar radiation sensor was installed when the
source data was produced.
</li>
<li><strong><span class="code"><a
href="#csv_raw_datetime_format">raw_datetime_format</a></span></strong>.
The format of the imported date time field.
</li>
<li><strong><span class="code"><a href="#csv_rain">rain</a></span></strong>. Determines
how the <span class="code">weewx</span> rain field is
derived.
</li>
<li><strong><span class="code"><a href="#csv_wind_direction">wind_direction</a></span></strong>.
Determines how imported wind direction fields are
interpreted.
</li>
<li><strong><span class="code"><a href="#csv_map">[[Map]]</a></span></strong>. Defines
the mapping between imported data fields and
<span class="code">weewx</span> archive fields. Also defines
the units of measure for each imported field.
</li>
</ul>
<li>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 <span class="code">weewx</span> database. In addition,
consideration should be given to any additional command line options
such as <span class="code">--date</span>.
</li>
<p>To perform a dry run enter the following command:</p>
<pre class="tty cmd">wee_import --import-config=/var/tmp/csv.conf --dry-run
</pre>
<p>The output should be something like this:</p>
<pre class="tty">Starting wee_import...
A CSV import from source file '/var/tmp/data.csv' has been requested.
Using database binding 'wx_binding', which is bound to database 'weewx.sdb'
Destination table 'archive' unit system is '0x01' (US).
Missing derived observations will be calculated.
This is a dry run, imported data will not be saved to archive.
Starting dry run import ...
70685 records identified for import.
Records processed: 70685; Unique records: 70685; Last timestamp: 2010-09-04 04:20:00 AEST (1283538000)
Finished dry run import. 70685 records were processed and 70685 unique records would have been imported.
</pre>
<p>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
<span class="code">weewx</span> database. Upon completion a
brief summary of the records processed is provided.
</p>
<p class="note">
<b>Note</b><br/>As the <span class="code">weewx</span> database is
not altered when the <span class="code">--dry-run</span> command
line option is used, <span class="code">wee_import</span> log output
is suspended during a dry run import. In effect, the use of
<span class="code">--dry-run</span> is equivalent to
<span class="code">--dry-run --log=-</span>. During a dry run import
the only <span class="code">wee_import</span> output is that
displayed on <span class="code">stdout</span>.
</p>
<li>Once the dry run results are satisfactory the data can be
imported using the following command:
</li>
<pre class="tty cmd">wee_import --import-config=/var/tmp/csv.conf</pre>
<p>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:</p>
<pre class="tty">Starting wee_import...
A CSV import from source file '/var/tmp/data.csv' has been requested.
Using database binding 'wx_binding', which is bound to database 'weewx.sdb'
Destination table 'archive' unit system is '0x01' (US).
Missing derived observations will be calculated.
Starting import ...
70685 records identified for import.
Proceeding will save all imported records in the weewx archive.
Are you sure you want to proceed (y/n)?
</pre>
<li>If the import parameters
are acceptable enter <span class="code">y</span> to proceed with the
import or <span class="code">n</span> to abort the import.
If the import is confirmed then the source
data will be imported, processed and saved in the
<span class="code">weewx</span> database. Information on the
progress of the import will be displayed similar to the following:
</li>
<pre class="tty">Records processed: 250; Unique records: 250; Last timestamp: 2010-02-09 19:25:00 AEST (1265707500)
</pre>
<p>The line commencing with <span class="code">Records processed</span>
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:</p>
<pre class="tty">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.</pre>
<li>Whilst <span class="code">wee_import</span> will advise of the
number of records processed and the number of unique records found,
<span class="code">wee_import</span> does know how many, if any, of
the imported records were successfully saved to the database. The
user should look carefully through the
<span class="code">weewx</span> log file covering the
<span class="code">wee_import</span> 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:
</li>
<pre class="tty">
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
</pre>
<p>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.</p>
</ol>
<h2>Importing from Weather Underground</h2>
<p><span class="code">wee_import</span> 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 <span class="code">weewx</span> archive table.
When <span class="code">wee_import</span> imports data from a Weather
Underground daily history each day is considered a 'period'.
<span class="code">wee_import</span> processes one period at a time in
chronological order (oldest to newest) and provides import summary data
on a per period basis.
</p>
<h3><span class="code">weewx</span> archive fields populated during a Weather Underground import</h3>
<p>A Weather Underground import will populate
<span class="code">weewx</span> archive fields as follows:</p>
<ul>
<li>Provided data exists for each field in the Weather Underground
PWS daily history, the following <span class="code">weewx</span>
archive fields will be directly populated by imported data:
<ul>
<li><span class="code">dateTime</span></li>
<li><span class="code">barometer</span></li>
<li><span class="code">dewpoint</span></li>
<li><span class="code">outHumidity</span></li>
<li><span class="code">outTemp</span></li>
<li><span class="code">radiation</span></li>
<li><span class="code">rain</span></li>
<li><span class="code">windDir</span></li>
<li><span class="code">windGust</span></li>
<li><span class="code">windSpeed</span></li>
</ul>
<p class="note">
<b>Note</b><br/>If an appropriate field does not exist in
the Weather Underground daily history then the corresponding
<span class="code">weewx</span> archive field will be set
to <span class="code">None/NULL</span>.
For example, if there is no solar radiation sensor
then <span class="code">radiation</span> will be NULL,
or if <span class="code">outHumidity</span> was never
uploaded to Weather Undeground then
<span class="code">outHumidity</span> will be NULL.
</p>
</li>
<li>The following <span class="code">weewx</span> archive fields
will be populated from other settings or configuration
options:
</li>
<ul>
<li><span class="code">interval</span></li>
<li><span class="code">usUnits</span></li>
</ul>
<li>The following <span class="code">weewx</span> archive fields
will be populated with values derived from the imported data
provided <span class="code">calc_missing = True</span> is
included in the <span class="code">[WU]</span> section of the
import configuration file and the field exists in the
in-use <span class="code">weewx</span> archive table schema.
</li>
<ul>
<li><span class="code">altimeter</span></li>
<li><span class="code">ET</span></li>
<li><span class="code">heatindex</span></li>
<li><span class="code">pressure</span></li>
<li><span class="code">rainRate</span></li>
<li><span class="code">windchill</span></li>
</ul>
<p class="note">
<b>Note</b><br/>If
<span class="code">calc_missing = False</span> is included
in the <span class="code">[WU]</span> section of the import
configuration file being used then all of the above fields
will be set to <span class="code">None/NULL</span>.
The default setting of the
<span class="code">calc_missing</span> option is
<span class="code">True</span>
</p>
</ul>
<h3>Importing observations from Weather Underground</h3>
<p>To import observations from the daily history of a Weather Underground
PWS:</p>
<ol>
<li>Obtain the weather station ID of the Weather Underground PWS from
which data is to be imported. The station ID will be a sequence of
numbers and upper case letters that is usually 11 or 12 characters
in length. For the purposes of these instructions a weather station
ID of <span class="code">ISTATION123</span> will be used.
</li>
<li>Make a backup of the
<span class="code">weewx</span> database in case the
import should go awry.
</li>
<li>Create an import configuration file. In this case
we will make a copy of the example Weather Underground import
configuration file and save it as
<span class="code">wu.conf</span> in the
<span class="code">/var/tmp</span> directory:
<pre class="tty cmd">$ cp /home/weewx/util/import/wu-example.conf /var/tmp/wu.conf
</pre>
<li>Confirm that the <span class="code"><a href="#import_config_source">source</a></span> option is set to
WU
</li>
<pre class="tty">source = WU</pre>
<li>Confirm that the following options in the
<span class="code">[WU]</span> section are correctly set:
</li>
<ul>
<li><strong><span class="code"><a href="#wu_station_id">station_id</a></span></strong>.
The 11 or 12 character weather station ID of the Weather
Underground PWS that will be the source of the imported
data.
</li>
<li><strong><span class="code"><a href="#wu_interval">interval</a></span></strong>.
Determines how the <span class="code">weewx</span> interval
field is derived.
</li>
<li><strong><span class="code"><a href="#wu_qc">qc</a></span></strong>. Determines
whether quality control checks are performed on the imported
data.
</li>
<p class="note">
<b>Note</b><br/>As Weather Underground imports at times
contain nonsense values, particularly for fields for
which no data were uploaded to Weather Underground by the
PWS, the use of quality control checks on imported data
can prevent these nonsense values from being imported
and contaminating the <span class="code">weewx</span>
database.
</p>
<li><strong><span class="code"><a href="#wu_calc_missing">calc_missing</a></span></strong>.
Determines whether missing derived observations will be
calculated from the imported data.
</li>
<li><a href="#wu_tranche"><strong><span class="code">tranche</span></strong></a>. The
number of records written to the
<span class="code">weewx</span> database in each transaction.
</li>
<li><a href="#wu_wind_direction"><strong><span class="code">wind_direction</span></strong></a>.
Determines how imported wind direction fields are
interpreted.
</li>
</ul>
<li>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 <span class="code">weewx</span> database. In addition,
consideration should be given to any additional command line options
to be used such as <span class="code">--date</span>.
</li>
<p>To perform a dry run enter the following command:</p>
<pre class="tty cmd">wee_import --import-config=/var/tmp/wu.conf --date="2016/01/20 22:30-2016/01/23 06:00" --dry-run
</pre>
<p class="note">
<b>Note</b><br/>If the <span class="code">--date</span> command
line option is omitted or a date (not date-time) range is used
during a Weather Underground import, then the current days
history data will be imported. This includes records timestamped
from <span class="code">00:00</span> (inclusive) at the start
of the day up to but NOT including the
<span class="code">00:00</span> record at the end of the last
day. As the timestamped record refers to observations of the
previous interval, such an import actually includes one record
with observations from the previous day (the
<span class="code">00:00</span> record at the start of the day).
Whilst this will not present a problem for
<span class="code">wee_import</span> as any records being
imported with a timestamp that already exists in the
<span class="code">weewx</span> database are ignored, the user
may wish to use the <span class="code">--date</span> option
with a suitable date-time range to precisely control which
records are imported.
</p>
<p class="note">
<b>Note</b><br/><span class="code">wee_import</span> obtains
Weather Underground daily history data one day at a time via a
HTTP request and as such the import of large time spans of data
may take some time. Such imports may be best handled as a series
of imports of smaller time spans.
</p>
<p>This will result in a short preamble with details
on 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 written to the
<span class="code">weewx</span> database.
</p>
<p>The output should be similar to:</p>
<pre class="tty">Starting wee_import...
Observation history for Weather Underground station 'ISTATION123' will be imported.
Using database binding 'wx_binding', which is bound to database 'weewx.sdb'
Destination table 'archive' unit system is '0x01' (US).
Missing derived observations will be calculated.
Observations timestamped after 2016-01-20 22:30:00 AEST (1453293000) and up to and
including 2016-01-23 06:00:00 AEST (1453492800) will be imported.
This is a dry run, imported data will not be saved to archive.
Starting dry run import ...
Records covering multiple periods have been identified for import.
Period 1 ...
Records processed: 18; Unique records: 18; Last timestamp: 2016-01-20 23:55:00 AEST (1453298100)
Period 2 ...
Records processed: 263; Unique records: 263; Last timestamp: 2016-01-21 23:55:00 AEST (1453384500)
Period 3 ...
Records processed: 264; Unique records: 264; Last timestamp: 2016-01-22 23:50:00 AEST (1453470600)
Period 4 ...
Records processed: 62; Unique records: 62; Last timestamp: 2016-01-23 05:55:00 AEST (1453492500)
Finished dry run import. 607 records were processed and 607 unique records would have been imported.
</pre>
<p class="note">
<b>Note</b><br/>As the <span class="code">weewx</span> database is
not altered when the <span class="code">--dry-run</span> command
line option is used, <span class="code">wee_import</span> log output
is suspended during a dry run import. In effect, the use of
<span class="code">--dry-run</span> is equivalent to
<span class="code">--dry-run --log=-</span>. During a dry run import
the only <span class="code">wee_import</span> output is that
displayed on <span class="code">stdout</span>(console).
</p>
<li>Once the dry run results are satisfactory the source data can be
imported using the following command:
</li>
<pre class="tty cmd">wee_import --import-config=/var/tmp/wu.conf --date="2016/01/20 22:30-2016/01/23 06:00"
</pre>
<p>This will result in a short preamble similar to that of
a dry run. At the end of the preamble there will be a
prompt:</p>
<pre class="tty">Starting wee_import...
Observation history for Weather Underground station 'ISTATION123' will be imported.
Using database binding 'wx_binding', which is bound to database 'weewx.sdb'
Destination table 'archive' unit system is '0x01' (US).
Missing derived observations will be calculated.
Observations timestamped after 2016-01-20 22:30:00 AEST (1453293000) and up to and
including 2016-01-23 06:00:00 AEST (1453492800) will be imported.
Starting import ...
Records covering multiple periods have been identified for import.
Proceeding will save all imported records in the weewx archive.
Are you sure you want to proceed (y/n)?
</pre>
<p class="note">
<b>Note</b><br/><span class="code">wee_import</span> obtains
Weather Underground daily history data one day at a time via a HTTP
request and as such the import of large time spans of data may take
some time. Such imports may be best handled as a series of imports
of smaller time spans.
</p>
<li>If the import parameters
are acceptable enter <span class="code">y</span> to proceed with the
import or <span class="code">n</span> to abort the import.
If the import is confirmed, the source
data will be imported, processed and saved in the
<span class="code">weewx</span> database. Information on the
progress of the import will be displayed similar to the following:
</li>
<pre class="tty">Period 1 ...
Records processed: 18; Unique records: 18; Last timestamp: 2016-01-20 23:55:00 AEST (1453298100)
Period 2 ...
Records processed: 286; Unique records: 286; Last timestamp: 2016-01-21 23:55:00 AEST (1453384500)
</pre>
<p>The line commencing with <span class="code">Records processed</span>
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. If the import spans
multiple days then a new <span class="code">Period</span> line is
created for each day. When the import is complete a brief summary
is displayed similar to the following:</p>
<pre class="tty">Finished import. 607 raw records resulted in 607 unique records being processed in 80.94 seconds.
Those records with a timestamp already in the archive will not have been imported.
Confirm successful import in the weewx log file.
</pre>
<p class="note">
<b>Note</b><br/>It is not unusual to see a Weather Underground
import return a different number of records for the same import
performed at different times. If importing the current day this
could be because an additional record may have been added between
<span class="code">wee_import</span> runs. For periods before today,
this behaviour appears to be a vagary of Weather Underground. The
only solution appears to be to repeat the import with the same
<span class="code">--date</span> command line option setting and
observe whether the missing records are imported. Repeating the
import will not adversely affect any existing data as records with
timestamps that are already in the <span class="code">weewx</span>
archive will be ignored. It may; however, generated many
<span class="code">UNIQUE constraint failed: archive.dateTime</span>
messages in the <span class="code">weewx</span> log.
</p>
<li>Whilst <span class="code">wee_import</span> will advise of the
number of records processed and the number of unique records found,
<span class="code">wee_import</span> does know how many, if any, of
the imported records were successfully saved to the database. The
user should look carefully through the
<span class="code">weewx</span> log file covering the
<span class="code">wee_import</span> 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:
</li>
<pre class="tty">
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
</pre>
<p>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.</p>
</ol>
<h2>Importing from Cumulus</h2>
<p><span class="code">wee_import</span> can import observational data from
the one or more Cumulus monthly log files. A Cumulus monthly log file
records weather station observations for a single month. These files are
accumulated over time and can be considered analogous to the
<span class="code">weewx</span> archive table. When
<span class="code">wee_import</span> imports data from the Cumulus
monthly log files each log file is considered a 'period'.
<span class="code">wee_import</span> processes one period at a time in
chronological order (oldest to newest) and provides import summary
data on a per period basis.</p>
<h3><span class="code">weewx</span> archive fields populated during a Cumulus monthly log import</h3>
<p>A Cumulus monthly log file import will populate the
<span class="code">weewx</span> archive fields as follows:</p>
<ul>
<li>Provided data exists for each field in the Cumulus monthly
logs, the following <span class="code">weewx</span>
archive fields will be directly populated by imported data:
<ul>
<li><span class="code">dateTime</span></li>
<li><span class="code">barometer</span></li>
<li><span class="code">dewpoint</span></li>
<li><span class="code">heatindex</span></li>
<li><span class="code">inHumidity</span></li>
<li><span class="code">inTemp</span></li>
<li><span class="code">outHumidity</span></li>
<li><span class="code">outTemp</span></li>
<li><span class="code">radiation</span></li>
<li><span class="code">rain</span> (Cumulus 1.9.4 or
later)
</li>
<li><span class="code">rainRate</span></li>
<li><span class="code">UV</span></li>
<li><span class="code">windDir</span></li>
<li><span class="code">windGust</span></li>
<li><span class="code">windSpeed</span></li>
<li><span class="code">windchill</span></li>
</ul>
<p class="note">
<b>Note</b><br/>If a field in the Cumulus monthly log file
has no data then the corresponding
<span class="code">weewx</span> archive field will be set
to <span class="code">None/NULL</span>.
</p>
</li>
<li>The following <span class="code">weewx</span> archive fields
will be populated from other settings or configuration options:
</li>
<ul>
<li><span class="code">interval</span></li>
<li><span class="code">usUnits</span></li>
</ul>
<li>The following <span class="code">weewx</span> archive fields
will be populated with values derived from the imported data
provided <span class="code">calc_missing = True</span> is
included in the <span class="code">[Cumulus]</span> section of
the import configuration file being used and the field exists
in the in-use <span class="code">weewx</span> archive table
schema.
</li>
<ul>
<li><span class="code">altimeter</span></li>
<li><span class="code">ET</span></li>
<li><span class="code">pressure</span></li>
</ul>
<p class="note">
<b>Note</b><br/>If
<span class="code">calc_missing = False</span> is included
in the <span class="code">[WU]</span> section of the import
configuration file being used then all of the above fields
will be set to <span class="code">None/NULL</span>.
The default setting of the
<span class="code">calc_missing</span> option is
<span class="code">True</span>
</p>
</ul>
<h3>Importing observations from Cumulus monthly log files</h3>
<p>To import observations from one or more Cumulus monthly log files:</p>
<ol>
<li>Ensure the Cumulus monthly log file(s) to be used for the import
are located in a directory accessible by the machine that will run
<span class="code">wee_import</span>. For the purposes of these
instructions, there are nine monthly logs files covering the
period November 2015 to July 2016, inclusive, located in the
<span class="code">/var/tmp/cumulus</span> folder.
</li>
<li>Make a backup of the
<span class="code">weewx</span> database in case the
import should go awry.
</li>
<li>Create an import configuration file. In this case
we will make a copy of the example Cumulus import configuration file
and save it as <span class="code">cumulus.conf</span> in the
<span class="code">/var/tmp</span> directory:
<pre class="tty cmd">$ cp /home/weewx/util/import/cumulus-example.conf /var/tmp/cumulus.conf
</pre>
<li>Confirm that the <span class="code">source</span> option is set to Cumulus:
</li>
<pre class="tty">source = Cumulus</pre>
<li>Confirm that the following options in the
<span class="code">[Cumulus]</span> section are correctly set:
</li>
<ul>
<li><a href="#cumulus_directory"><strong><span class="code">directory</span></strong></a>.
The full path to the directory containing the Cumulus
monthly log files to be used as the source of the imported
data.
</li>
<li><a href="#cumulus_interval"><strong><span class="code">interval</span></strong></a>.
Determines how the <span class="code">weewx</span> interval
field is derived.
</li>
<li><a href="#cumulus_qc"><strong><span class="code">qc</span></strong></a>. Determines
whether quality control checks are performed on the imported
data.
</li>
<li><a href="#cumulus_calc_missing"><strong><span class="code">calc_missing</span></strong></a>.
Determines whether missing derived observations will be
calculated from the imported data.
</li>
<li><a href="#cumulus_delimiter"><strong><span class="code">delimiter</span></strong></a>. The
field delimiter used in the Cumulus monthly log files.
</li>
<li><a href="#cumulus_decimal"><strong><span class="code">decimal</span></strong></a>. The
decimal point character used in the Cumulus monthly log
files.
</li>
<li><a href="#cumulus_tranche"><strong><span class="code">tranche</span></strong></a>. The
number of records written to the
<span class="code">weewx</span> database in each transaction.
</li>
<li><a href="#cumulus_UV"><strong><span class="code">UV_sensor</span></strong></a>.
Whether a UV sensor was installed when the source data was
produced.
</li>
<li><a href="#cumulus_solar"><strong><span class="code">solar_sensor</span></strong></a>.
Whether a solar radiation sensor was installed when the
source data was produced.
</li>
<li><a href="#cumulus_units"><strong><span class="code">[[Units]]</span></strong></a>.
Defines the units used in the Cumulus monthly log files.
</li>
</ul>
<li>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 <span class="code">weewx</span> database. In addition,
consideration should be given to any additional command line options
to be used such as <span class="code">--date</span>.
</li>
<p>To perform a dry run enter the following command:</p>
<pre class="tty cmd">wee_import --import-config=/var/tmp/cumulus.conf --dry-run
</pre>
<p>This will result in a short preamble with
details on 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
<span class="code">weewx</span> database.
</p>
<p>The output should be similar to:</p>
<pre class="tty">Starting wee_import...
Cumulus monthly log files in the '/var/tmp/cumulus' directory will be imported
Using database binding 'wx_binding', which is bound to database 'weewx.sdb'
Destination table 'archive' unit system is '0x01' (US).
Missing derived observations will be calculated.
This is a dry run, imported data will not be saved to archive.
Starting dry run import ...
Records covering multiple periods have been identified for import.
Period 1 ...
Records processed: 4189; Unique records: 4169; Last timestamp: 2015-12-01 09:40:00 AEST (1448926800)
Period 2 ...
Records processed: 4461; Unique records: 4461; Last timestamp: 2016-01-01 09:40:00 AEST (1451605200)
Period 3 ...
Records processed: 4458; Unique records: 4458; Last timestamp: 2016-02-01 09:40:00 AEST (1454283600)
Period 4 ...
Records processed: 3940; Unique records: 3940; Last timestamp: 2016-03-01 09:40:00 AEST (1456789200)
Period 5 ...
Records processed: 4061; Unique records: 4061; Last timestamp: 2016-04-01 09:40:00 AEST (1459467600)
Period 6 ...
Records processed: 4298; Unique records: 4292; Last timestamp: 2016-05-01 08:40:00 AEST (1462056000)
Period 7 ...
Records processed: 4380; Unique records: 4379; Last timestamp: 2016-06-01 08:40:00 AEST (1464734400)
Period 8 ...
Records processed: 4317; Unique records: 4317; Last timestamp: 2016-07-01 08:40:00 AEST (1467326400)
Period 9 ...
Records processed: 3544; Unique records: 3543; Last timestamp: 2016-07-26 17:00:00 AEST (1469516400)
Finished dry run import. 37648 records were processed and 37620 unique records would have been imported.
</pre>
<p class="note">
<b>Note</b><br/>The nine periods correspond to the nine monthly log
files used for this import.
</p>
<li>Once the dry run results are satisfactory the data can be
imported using the following command:
</li>
<pre class="tty cmd">wee_import --import-config=/var/tmp/cumulus.conf
</pre>
<p>This will result in a preamble similar to that of a dry run.
At the end of the preamble there will be a prompt:</p>
<pre class="tty">Starting wee_import...
Cumulus monthly log files in the '/var/tmp/cumulus' directory will be imported
Using database binding 'wx_binding', which is bound to database 'weewx.sdb'
Destination table 'archive' unit system is '0x01' (US).
Missing derived observations will be calculated.
Starting import ...
Records covering multiple periods have been identified for import.
Proceeding will save all imported records in the weewx archive.
Are you sure you want to proceed (y/n)?
</pre>
<p>If there is more than one Cumulus monthly log file then
<span class="code">wee_import</span> will provide summary
information on a per period basis during the import. In addition,
if the <span class="code">--date</span> command line option is used
then source data that falls outside the date or date range
specified with the <span class="code">--date</span> command line
option is ignored. In such cases the preamble may look similar
to:</p>
<pre class="tty">Starting wee_import...
Cumulus monthly log files in the '/var/tmp/cumulus' directory will be imported
Using database binding 'wx_binding', which is bound to database 'weewx.sdb'
Destination table 'archive' unit system is '0x01' (US).
Missing derived observations will be calculated.
Observations timestamped after 2016-02-12 00:00:00 AEST (1455199200) and up to and
including 2016-02-25 00:00:00 AEST (1456322400) will be imported.
Starting import ...
Period 1 - no records identified for import.
Period 2 - no records identified for import.
Period 3 - no records identified for import.
Proceeding will save all imported records in the weewx archive.
Are you sure you want to proceed (y/n)?
</pre>
<li>If the import parameters are acceptable enter
<span class="code">y</span> to proceed with the
import or <span class="code">n</span> to abort the import.
If the import is confirmed, the source
data will be imported, processed and saved in the
<span class="code">weewx</span> database. Information on the
progress of the import will be displayed similar to the following:
</li>
<pre class="tty">Records processed: 1599; Unique records: 1599; Last timestamp: 2016-02-24 00:00:00 AEST (1456236000)
</pre>
<p>Again if there is more than one Cumulus monthly log file and if the
<span class="code">--date</span> command line option is used then
the progress information may instead look similar to:</p>
<pre class="tty">Period 4 ...
Records processed: 2521; Unique records: 2521; Last timestamp: 2016-03-01 09:40:00 AEST (1456789200)
Period 5 ...
Records processed: 4061; Unique records: 4061; Last timestamp: 2016-04-01 09:40:00 AEST (1459467600)
Period 6 ...
Records processed: 3238; Unique records: 3232; Last timestamp: 2016-04-24 00:00:00 AEST (1461420000)
</pre>
<p>The line commencing with <span class="code">Records processed</span>
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. If the import spans
multiple months (ie multiple monthly log files) then a new
<span class="code">Period</span> line is created for each month.
When the import is complete a brief summary is displayed similar to
the following:</p>
<pre class="tty">Finished import. 37648 raw records resulted in 37620 unique records being processed in 93.70 seconds.
Those records with a timestamp already in the archive will not have been imported.
Confirm successful import in the weewx log file.
</pre>
<li>Whilst <span class="code">wee_import</span> will advise of the
number of records processed and the number of unique records found,
<span class="code">wee_import</span> does know how many, if any, of
the imported records were successfully saved to the database. The
user should look carefully through the
<span class="code">weewx</span> log file covering the
<span class="code">wee_import</span> 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:
</li>
<pre class="tty">
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
</pre>
<p>In such cases 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.</p>
</ol>
<h2 id='import_failures'>Dealing with import failures</h2>
<p>Sometimes bad things happen during an import.</p>
<p>If errors were encountered, or if you suspect that the
<span class="code">weewx</span> database has been
contaminated with incorrect data, here are some things
you can try to fix things up.
</p>
<ul>
<li>Manually delete the contaminated data. Use SQL
commands to manipulate the data in the
<span class="code">weewx</span> archive database.
The simplicity of this process will depend on your
ability to use SQL, the amount of data imported, and
whether the imported data was dispersed amongst
existing. Once contaminated data have been removed the
daily summary tables will need to be dropped and
rebuilt using the
<span class="code">wee_database</span> utility.
</li>
<li>Delete the database and start over. For SQLite,
simply delete the database file. For MySQL, drop
the database. Then try the import again.
</li>
<li>If the above steps are not appropriate then the
database should be restored from backup. You did
make a backup before starting the import?
</li>
</ul>
<h2 id='import_config'>The import configuration file</h2>
<p><span class="code">wee_import</span> requires a second configuration file, the import configuration file, in
addition to the standard weewx configuration file. The import configuration file
specifies the import type and various options associated with
each type of import. The import configuration file is specified at the
<span class="code">wee_import</span> command line using the mandatory
<span class="code">--import-config</span> command line option. How the
user constructs the import configuration file is up to the user;
however, the recommended method is to copy one of the example import
configuration files located in the <span class="code">util/import</span>
folder, modify the configuration options in the newly copied file to
suit the import to be performed and then use this file as the import
configuration file.
</p>
<p>Following is the definitive guide to the options available in the import
configuration file. Default values are provided for a number of options,
meaning that if they are not listed in the import configuration file at
all <span class="code">wee_import</span> will pick sensible values.
When the documentation below gives a "default value" this is what it
means. What follows is organized by the different sections of the import
configuration file.
</p>
<h3 class="config_section">General</h3>
<p class='config_option' id='import_config_source'>source</p>
<p>The <span class="code">source</span> option determines the type of import
to be performed by <span class="code">wee_import</span>. The option
must be set to one of the following:
</p>
<ul>
<li><span class="code">CSV</span> to import from a single CSV format
file.
</li>
<li><span class="code">WU</span> to import from a Weather
Underground PWS daily history.
</li>
<li><span class="code">Cumulus</span> to import from one or more
Cumulus monthly log files.
</li>
</ul>
<p>There is no default.</p>
<h3 class="config_section">[CSV]</h3>
<p>The <span class="config_section">[CSV]</span> section contains the
options relating to the import of observational data from a CSV format
file.
</p>
<p class='config_option' id='csv_file'>file</p>
<p>The file containing the CSV format data to be used as the source during
the import. Include full path and filename. There is no default.
</p>
<p class='config_option' id='csv_interval'>interval</p>
<p>Determines how the time interval (<span class="code">weewx</span>
archive table field <span class="code">interval</span>) between
successive observations is derived. The interval can be derived by one
of three methods:
</p>
<ul>
<li>The interval can be calculated as the time, rounded to the
nearest minute, between the date-time of successive records.
This method is suitable when the data was recorded at fixed
intervals and there are NO missing records in the source data.
Use of this method when there are missing records in the source
data can compromise the integrity of the
<span class="code">weewx</span> statistical data. Select this
method by setting <span class="code">interval = derive</span>.
</li>
<li>The interval can be set to the same value as the
<span class="code">archive_interval</span> setting under
<span class="code">[StdArchive]</span> in
<span class="code">weewx.conf</span>. This setting is useful if
the data was recorded at fixed intervals but there are some
missing records and the fixed interval is the same as the
<span class="code">archive_interval</span> setting under
<span class="code">[StdArchive]</span> in
<span class="code">weewx.conf</span>. Select this method by
setting <span class="code">interval = conf</span>.
</li>
<li>The interval can be set to a fixed number of minutes. This
setting is useful if the source data was recorded at fixed
intervals but there are some missing records and the fixed
interval is different to the
<span class="code">archive_interval</span> setting under
<span class="code">[StdArchive]</span> in
<span class="code">weewx.conf</span>. Select this method by
setting <span class="code">interval = x</span> where
<span class="code">x</span> is an integer number of minutes.
</li>
</ul>
<p>The default value is <span class="code">derive</span>. If the CSV source
data records are equally spaced in time, but some records are missing,
then better result may be achieved using <span class="code">conf</span>
or a fixed interval setting.
</p>
<p class='config_option' id='csv_qc'>qc</p>
<p>Determines whether simple quality control checks are applied to imported
data. Setting <span class="code">qc = True</span> will result in
<span class="code">wee_import</span> applying the
<span class="code">weewx</span> <span class="code">StdQC</span> minimum
and maximum checks to any imported observations.
<span class="code">wee_import</span> quality control checks use the same
configuration settings, and operate in the same manner, as the
<a href="usersguide.htm#StdQC"><span class="code">StdQC</span></a> service. For example, for min/max QC, if
an observation falls
outside of the quality control range for that observation, then the
observation will be set to <span class="code">None</span>. The user will
be alerted through a short message similar to:</p>
<pre class="tty">2016-01-12 10:00:00 AEST (1452556800) record value 'outTemp' 194.34 outside limits (0.0, 120.0)
</pre>
<p>As derived observations are calculated after the quality control check is applied, derived
observations are not subject to quality control checks. Setting
<span class="code">qc = False</span> will result in
<span class="code">wee_import</span> not applying quality control checks
to imported data. The default is <span class="code">True</span>.
</p>
<p class='config_option' id='csv_calc_missing'>calc_missing</p>
<p>Determines whether any missing derived observations will be calculated
from the imported data. Setting
<span class="code">calc_missing = True</span> will result in
<span class="code">wee_import</span> using the <span class="code">weewx</span>
<span class="code">StdWXCalculate</span> service to calculate any
missing derived observations from the imported data. Setting
<span class="code">calc_missing = False</span> will result in
<span class="code">weewx</span> leaving any missing derived observations
as <span class="code">None</span>. The observations that
<span class="code">StdWXCalculate</span> can calculate are listed in the
<a href="usersguide.htm#StdWXCalculate">[StdWXCalculate]</a> section
of the <a href="usersguide.htm">User's Guide</a>. The default is
<span class="code">True</span>.
</p>
<p class='config_option' id='csv_tranche'>tranche</p>
<p>To speed up database operations imported records are committed to
database in groups of records rather than individually. The size of the
group is set by the <span class="code">tranche</span> parameter.
Increasing the <span class="code">tranche</span> parameter may result
in a slight speed increase but at the expense of increased memory usage.
Decreasing the <span class="code">tranche</span> parameter will result
in less memory usage but at the expense of more frequent database access
and likely increased time to import. The default is
<span class="code">250</span> which should suit most users.
</p>
<p class='config_option' id='csv_UV'>UV_sensor</p>
<p><span class="code">weewx</span> records a
<span class="code">None/NULL</span> for UV when no UV sensor is
installed, whereas some weather station software records a value of 0
for UV index when there is no UV sensor installed. The
<span class="code">UV_sensor</span> parameter enables
<span class="code">wee_import</span> to distinguish between the case
where a UV sensor is present and the UV index is 0 and the case where
no UV sensor is present and UV index is 0.
<span class="code">UV_sensor = False</span> should be used when no UV
sensor was used in producing the source data.
<span class="code">UV_sensor = False</span> will result in
<span class="code">None/Null</span> being recorded in the
<span class="code">weewx</span> archive field
<span class="code">UV</span> irrespective of any UV observations in the
source data. <span class="code">UV_sensor = True</span> should be used
when a UV sensor was used in producing the source data.
<span class="code">UV_sensor = True</span> will result in UV
observations in the source data being stored in the
<span class="code">weewx</span> archive field
<span class="code">UV</span>. The default is
<span class="code">True</span>.
</p>
<p class='config_option' id='csv_solar'>solar_sensor</p>
<p><span class="code">weewx</span> records a
<span class="code">None/NULL</span> when no solar radiation sensor is
installed, whereas some weather station software records a value of 0
for solar radiation when there is no solar radiation sensor installed.
The <span class="code">solar_sensor</span> parameter enables
<span class="code">wee_import</span> to distinguish between the case
where a solar radiation sensor is present and solar radiation is 0 and
the case where no solar radiation sensor is present and solar radiation
is 0. <span class="code">solar_sensor = False</span> should be used
when no solar radiation sensor was used in producing the source data.
<span class="code">solar_sensor = False</span> will result in
<span class="code">None/Null</span> being recorded in the
<span class="code">weewx</span> archive field
<span class="code">radiation</span> irrespective of any solar radiation
observations in the source data.
<span class="code">solar_sensor = True</span> should be used when a
solar radiation sensor was used in producing the source data.
<span class="code">solar_sensor = True</span> will result in solar
radiation observations in the source data being stored in the
<span class="code">weewx</span> archive field
<span class="code">radiation</span>. The default is
<span class="code">True</span>.
</p>
<p class='config_option' id='csv_raw_datetime_format'>raw_datetime_format</p>
<p><span class="code">weewx</span> records each record with a unique unix
epoch timestamp, whereas many weather station applications or web
sources export observational data with a human readable date-time.
This human readable date-time is interpreted according to the format
set by the <span class="config_option">raw_datetime_format</span>
option. This option consists of <em>
<a href="https://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior">Python
strptime() format codes</a>
</em> and literal characters to represent the date-time data being
imported. For example, if the source data uses the format
23 January 2015 15:34 then the appropriate setting for
<span class="config_option">raw_datetime_format</span> would be
<span class="code">%d %B %Y %H:%M</span>, 9:25:00 12/28/16 would use
<span class="code">%H:%M:%S %m/%d/%y</span>. If the source data provides
a unix epoch timestamp as the date-time field then the unix epoch
timestamp is used directly and the
<span class="config_option">raw_datetime_format</span> option is
ignored. The default is <span class="code">%Y-%m-%d %H:%M:%S</span>.
</p>
<p class='config_option' id='csv_rain'>rain</p>
<p><span class="code">weewx</span> records rainfall as the amount of rain
in the preceding archive period, so for a 5 minute archive period the
rain field in each archive record would contain the total rain that
fell in the previous 5 minutes. Many weather station applications
provide a daily or yearly total. <span class="code">wee_import</span>
can derive the <span class="code">weewx</span>
<span class="code">rain</span> field in one of two ways:
</p>
<ul>
<li>If the imported rain data is a running total then
<span class="code">wee_import</span> can derive the
<span class="code">weewx rain</span> field from successive
totals. For this method use
<span class="config_option">rain = cumulative</span>.
</li>
<li>If the imported rain data is a discrete value per date-time
period then <span class="config_option">rain = discrete</span>
should be used.
</li>
</ul>
</p>
<p class="note">
<b>Note</b><br/><span class="code">wee_import</span> only supports
cumulative rainfall data that resets on a midnight boundary, cumulative
rainfall data that resets at some other time; e.g., 9am, is not supported.
In such cases the rainfall data will need to be converted to either
reset on a midnight boundary or a discrete value per date-time period
and <span class="config_option">rain = discrete</span> used. The former
may be possible by selecting another rainfall field (if available) in
the source data, otherwise it will require manual manipulation of the
source data.
</p>
<p class='config_option' id='csv_wind_direction'>wind_direction</p>
<p><span class="code">weewx</span> records wind direction in degrees as a
number from 0 to 360 inclusive (no wind direction is recorded as
<span class="code">None/NULL</span>), whereas some data sources may
provide wind direction as number over a different range (e.g., -180 to
+180) or may use a particular value when there is no wind direction
(e.g., 0 may represent no wind direction and 360 may represent a northerly
wind, or -9999 (or some similar clearly invalid number) to represent
there being no wind direction). <span class="code">wee_import</span>
handles such variations in data by defining a range over which imported
wind direction values are accepted. Any value outside of this range is
treated as there being no wind direction and is recorded as
<span class="code">None/NULL</span>. Any value inside the range is
normalised to the range 0 to 360 inclusive (e.g., -180 would be normalised
to 180). The <span class="config_option">wind_direction</span> option
consists of two comma separated numbers of the format lower, upper where
lower and upper are inclusive. The operation of the
<span class="config_option">wind_direction</span> option is best
illustrated through the following table:
</p>
<table class="indent" style="width:50%" summary="wind_direction operation">
<tbody>
<tr class="first_row">
<td><span class="config_option">wind_direction</span> option setting</td>
<td>Source data wind direction value</td>
<td>Imported wind direction value</td>
</tr>
<tr>
<td class="code first_col" rowspan='7'>0, 360</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>160</td>
<td>160</td>
</tr>
<tr>
<td>360</td>
<td>360</td>
</tr>
<tr>
<td>500</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td>-45</td>
<td><span class="code">None/NULL</span>/td>
</tr>
<tr>
<td>-9999</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td>No data</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td class="code first_col" rowspan='7'>-360, 360</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>160</td>
<td>160</td>
</tr>
<tr>
<td>360</td>
<td>360</td>
</tr>
<tr>
<td>500</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td>-45</td>
<td>315</td>
</tr>
<tr>
<td>-9999</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td>No data</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td class="code first_col" rowspan='7'>-180, 180</td>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>160</td>
<td>160</td>
</tr>
<tr>
<td>360</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td>500</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td>-45</td>
<td>315</td>
</tr>
<tr>
<td>-9999</td>
<td><span class="code">None/NULL</span></td>
</tr>
<tr>
<td>No data</td>
<td><span class="code">None/NULL</span></td>
</tr>
</tbody>
</table>
<p>The default is <span class="config_option">0, 360</span>.
</p>
<p class='config_option' id='csv_map'>[[Map]]</p>
<p>The <span class='config_option'>[[Map]]</span> stanza defines the mapping
from the source data fields to <span class="code">weewx</span> archive
fields. The map consists of one row per field using the format:
</p>
<pre class="tty">weewx_archive_field_name = csv_field_name, weewx_unit_name
</pre>
<p>Where <span class="config_option">weewx_archive_field_name</span> is a
database field name in the <span class="code">weewx</span> archive table
schema, <span class="config_option">csv_field_name</span> is the name
of a field from the CSV file and
<span class="config_option">weewx_unit_name</span> is the
<span class="code">weewx</span> unit name of the units used by
<span class="config_option">csv_field_name</span>. This mapping allows
<span class="code">wee_import</span> to take a source data field, do
the appropriate unit conversion and store the resulting value in the
appropriate <span class="code">weewx</span> archive field. A mapping is
not required for every <span class="code">weewx</span> archive field
(e.g., the source may not provide inside temperature so no
<span class="code">inTemp</span> field mapping is required) and neither
does every CSV field need to be included in a mapping (e.g., the source
data field <span class="code">monthrain</span> may have no use if the
source data field <span class="code">dayrain</span> provides the data
for the <span class="code">weewx</span> archive
<span class="code">rain</span> field). Unused field mapping lines will
not be used and may be omitted.
</p>
<p class="note">
<b>Note</b><br/>Any <span class="code">weewx</span> archive fields that
are derived (e.g., <span class="code">dewpoint</span>) and for which there
is no field mapping may be calculated during import by use of the
<span class="config_option">calc_missing</span> option in the
<span class="code">[CSV]</span> section of the import configuration
file.
</p>
<h3 class="config_section">[WU]</h3>
<p>The <span class="config_option">[WU]</span> section contains the
options relating to the import of observational data from a Weather
Underground PWS daily history.
</p>
<p class='config_option' id='wu_station_id'>station_id</p>
<p>The Weather Underground weather station ID of the PWS from which the
daily history will be imported. There is no default.
</p>
<p class='config_option' id='wu_interval'>interval</p>
<p>Determines how the time interval (<span class="code">weewx</span>
database field <span class="code">interval</span>) between successive
observations is determined. This option is identical in operation to the
CSV <em><a href="#csv_interval">interval</a></em> option but applies to
Weather Underground imports only. As Weather Underground often skips
observation records when responding to a daily history query, the use of
<span class="config_option">interval = derive</span> may give incorrect
or inconsistent interval values. Better results may be obtained by using
<span class="config_option">interval = conf</span> if the current
<span class="code">weewx</span> installation has the same
<span class="code">archive_interval</span> as the Weather Underground
data, or by using <span class="config_option">interval = x</span> where
<span class="config_option">x</span> is the time interval in minutes
used to upload the Weather Underground data. The most appropriate
setting will depend on the completeness and (time) accuracy of the
Weather Underground data being imported.
</p>
<p>The default is <span class="code">derive</span>.</p>
<p class='config_option' id='wu_qc'>qc</p>
<p>Determines whether simple quality control checks are applied to imported
data. This option is identical in operation to the CSV
<em><a href="#csv_qc">qc</a></em> option but applies to Weather
Underground imports only. As Weather Underground imports at times
contain nonsense values, particularly for fields for which no data was
uploaded to Weather Underground by the PWS, the use of quality control
checks on imported data can prevent these nonsense values from being
imported and contaminating the <span class="code">weewx</span> database.
The default is <span class="code">True</span>.
</p>
<p class='config_option' id='wu_calc_missing'>calc_missing</p>
<p>Determines whether any missing derived observations will be calculated
from the imported data. This option is identical in operation to the
CSV <em><a href="#csv_calc_missing">calc_missing</a></em> option but
applies to Weather Underground imports only. The default is
<span class="code">True</span>.
</p>
<p class='config_option' id='wu_tranche'>tranche</p>
<p>The number of records written to the <span class="code">weewx</span>
database in each transaction. This option is identical in operation to
the CSV <em><a href="#csv_tranche">tranche</a></em> option but applies
to Weather Underground imports only. The default is
<span class="code">250</span> which should suit most users.
</p>
<p class='config_option' id='wu_wind_direction'>wind_direction</p>
<p>Determines the range of acceptable wind direction values in degrees.
This option is identical in operation to the CSV
<em><a href="#csv_wind_direction">wind_direction</a></em> option but
applies to Weather Underground imports only. The default is
<span class="config_option">0, 360</span> which should suit most users.
</p>
<h3 class="config_section">[Cumulus]</h3>
<p>The <span class="config_option">[Cumulus]</span> section contains the
options relating to the import of observational data from Cumulus
monthly log files.
</p>
<p class='config_option' id='cumulus_directory'>directory</p>
<p>The full path to the directory containing the Cumulus monthly log files
to be imported. Do not include a trailing /. There is no default.
</p>
<p class='config_option' id='cumulus_interval'>interval</p>
<p>Determines how the time interval (<span class="code">weewx</span>
database field <span class="code">interval</span>) between successive
observations is determined. This option is identical in operation to
the CSV <em><a href="#csv_interval">interval</a></em> option but
applies to Cumulus monthly log file imports only. As Cumulus monthly
log files can, at times, have missing entries, the use of
<span class="config_option">interval = derive</span> may give incorrect
or inconsistent interval values. Better results may be obtained by
using <span class="config_option">interval = conf</span> if the
<span class="config_option">archive_interval</span> for the current
<span class="code">weewx</span> installation is the same as the Cumulus
'data log interval' setting used to generate the Cumulus monthly log
files, or by using <span class="config_option">interval = x</span> where
<span class="config_option">x</span> is the time interval in minutes
used as the Cumulus 'data log interval' setting. The most appropriate
setting will depend on the completeness and (time) accuracy of the
Cumulus data being imported.
</p>
<p>The default is <span class="code">derive</span>.</p>
<p class='config_option' id='cumulus_qc'>qc</p>
<p>Determines whether simple quality control checks are applied to imported
data. This option is identical in operation to the CSV
<em><a href="#csv_qc">qc</a></em> option but applies to Cumulus imports
only. The default is <span class="code">True</span>.
</p>
<p class='config_option' id='cumulus_calc_missing'>calc_missing</p>
<p>Determines whether any missing derived observations will be calculated
from the imported data. This option is identical in operation to the
CSV <em><a href="#csv_calc_missing">calc_missing</a></em> option but
applies to Cumulus imports only. The default is
<span class="code">True</span>.
</p>
<p class='config_option' id='cumulus_delimiter'>delimiter</p>
<p>The character used as the field delimiter in the Cumulus monthly log
file. A comma is frequently used but it may be another character
depending on the settings on the machine that produced the Cumulus
monthly log files. This parameter must be included in quotation marks.
Default is <span class="config_option">','</span>.
</p>
<p class='config_option' id='cumulus_decimal'>decimal</p>
<p>The character used as the decimal point in the Cumulus monthly log files
A full stop is frequently used but it may be another character depending
on the settings on the machine that produced the Cumulus monthly log
files. This parameter must be included in quotation marks. Default is
<span class="config_option">'.'</span>.
</p>
<p class='config_option' id='cumulus_tranche'>tranche</p>
<p>The number of records are written to the <span class="code">weewx</span>
database in each transaction. This option is identical in operation to
the CSV <em><a href="#csv_tranche">tranche</a></em> option but applies
to Cumulus monthly log file imports only. The default is
<span class="config_option">250</span> which should suit most users.
</p>
<p class='config_option' id='cumulus_UV'>UV_sensor</p>
<p>The <span class="config_option">UV_sensor</span> parameter enables
<span class="code">wee_import</span> to distinguish between the case
where a UV sensor is present and the UV index is 0 and the case where
no UV sensor is present and UV index is 0. This option is identical in
operation to the CSV <em><a href="#csv_UV">UV_sensor</a></em> option
but applies to Cumulus monthly log file imports only. The default is
<span class="config_option">True</span>.
</p>
<p class='config_option' id='cumulus_solar'>solar_sensor</p>
<p>The <span class="config_option">solar_sensor</span> parameter enables
<span class="code">wee_import</span> to distinguish between the case
where a solar radiation sensor is present and the solar radiation is 0
and the case where no solar radiation sensor is present and solar
radiation is 0. This option is identical in operation to
the CSV <em><a href="#csv_solar">solar_sensor</a></em> option but
applies to Cumulus monthly log file imports only. The default is
<span class="config_option">True</span>.
</p>
<p class='config_option' id='cumulus_units'>[[Units]]</p>
<p>The <span class="config_option">[[Units]]</span> stanza defines the units
used in the Cumulus monthly log files. Units settings are required for
<span class="code">temperature</span>,
<span class="code">pressure</span>, <span class="code">rain</span> and
<span class="code">speed</span>. The format for each setting is:
</p>
<pre class="tty">obs_type = weewx_unit_name
</pre>
<p>Where <span class="code">obs_type</span> is one of
<span class="code">temperature</span>,
<span class="code">pressure</span>, <span class="code">rain</span> or
<span class="code">speed</span> and
<span class="code">weewx_unit_name</span> is the
<span class="code">weewx</span> unit name of the units used by that
particular <span class="code">obs_type</span>. As Cumulus supports a
different suite of possible units only a subset of the available
<span class="code">weewx</span> unit names can be used for some
settings.
</p>
<!-- ======== -->
<h1 id="wee_reports_utility"><span class="code">wee_reports</span></h1>
<p>In normal operation, <span class='code'>weewx</span> generates
reports on each archive interval, when new data arrive. The
reports utility is used to generate reports on demand. It uses
the same configuration file that
<span class='code'>weewx</span> uses.
</p>
<p>Run the utility with the <span class='code'>--help</span>
option to see how it is used:
</p>
<pre class="tty cmd">wee_reports --help</pre>
<p>This results in something like this:</p>
<pre class="tty">Usage: wee_reports: [config_file] [timestamp] [--config=CONFIG_FILE] [--help]
Run all reports defined in the specified configuration file. Use this utility
to run reports immediately instead of waiting for the end of an archive
interval.
Options:
-h, --help show this help message and exit
--config=CONFIG_FILE Use the configuration file CONFIG_FILE
</pre>
<!-- ======== -->
<h1 id="weewxd_utility"><span class="code">weewxd</span></h1>
<p>The <span class='code'>weewxd</span> application is the heart
of <span class='code'>weewx</span>. It can be run directly,
or in the background as a daemon.
</p>
<p>Run with the <span class='code'>--help</span> option to see
how it is used:
</p>
<pre class="tty cmd">weewxd --help</pre>
<p>This results in output something like:</p>
<pre class="tty">Usage: weewxd --help
weewxd --version
weewxd config_file [--daemon] [--pidfile=PIDFILE]
[--exit] [--loop-on-init]
[--log-label=LABEL]
Entry point to the weewx weather program. Can be run directly, or as a daemon
by specifying the '--daemon' option.
Arguments:
config_file: The weewx configuration file to be used.
Options:
-h, --help show this help message and exit
-d, --daemon Run as a daemon
-p PIDFILE, --pidfile=PIDFILE
Store the process ID in PIDFILE
-v, --version Display version number then exit
-x, --exit Exit on I/O and database errors instead of restarting
-r, --loop-on-init Retry forever if device is not ready on startup
-n LABEL, --log-label=LABEL
Label to use in syslog entries</pre>
<!-- ======== -->
<h1 id="wunderfixer_utility"><span class="code">wunderfixer</span></h1>
<!-- ======== -->
</div> <!-- end technical_content -->
<div class="footer">
<p class="copyright"> &copy; <a href="copyright.htm">Copyright</a> Tom Keffer </p>
</div>
</div> <!-- end class main -->
<!-- Our scripts load last so the content can load first -->
<script type="text/javascript" src="js/jquery-1.11.1.min.js"></script>
<script type="text/javascript" src="js/jquery-ui-1.10.4.custom.min.js"></script>
<script type="text/javascript" src="js/jquery.tocify-1.9.0.min.js"></script>
<script type="text/javascript" src="js/weewx.js"></script>
<script type="text/javascript">
$(function () {
var level = get_default_level();
create_toc_control(level);
generate_toc(level);
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink