mirror of
https://github.com/weewx/weewx.git
synced 2026-04-21 18:17:01 -04:00
2cf0ef2c3d
A new event, END_ARCHIVE_PERIOD has been added, signaling the end of the archive period. The LOOP packets emitted by the driver for the Davis Vantage series now includes the max wind gust and direction seen since the beginning of the current archive period.
342 lines
20 KiB
HTML
342 lines
20 KiB
HTML
<!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">
|
|
|
|
<!-- $Revision$ -->
|
|
<!-- $Author$ -->
|
|
<!-- $Date$ -->
|
|
|
|
<head>
|
|
<meta content="en-us" http-equiv="Content-Language" />
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
|
|
<title>weewx: Upgrade Guide</title>
|
|
<link href="weewx_docs.css" rel="stylesheet" />
|
|
<style type="text/css">
|
|
.tty {
|
|
white-space: pre-line;
|
|
}
|
|
</style>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<h1 class="title">Upgrading <span class="code">weewx</span><br />
|
|
<span class="version">Version: 2.4.0a1 </span></h1>
|
|
<p>This document has three sections:</p>
|
|
<ul>
|
|
<li><a href="#Upgrading_using_setup.py">Upgrading using <span class="code">setup.py</span></a></li>
|
|
<li><a href="#Upgrading_using_DEB/RPM_package">Upgrading using DEB/RPM package</a></li>
|
|
<li><a href="#Instructions_for_specific_versions">Instructions for specific
|
|
versions</a></li>
|
|
</ul>
|
|
<p>The section <em><a href="#Instructions_for_specific_versions">Instructions for
|
|
Specific Versions</a></em> applies to both installation methods.</p>
|
|
<p class="warning"><strong>Warning!</strong><br />
|
|
You must use the same upgrade technique as your initial install!<br />
|
|
<br />
|
|
For example, if you used <span class="code">setup.py</span> to install
|
|
<span class="code">weewx</span>, you should use <span class="code">setup.py</span>
|
|
to upgrade.<br />
|
|
<br />
|
|
If you used a DEB or RPM package to install, then you should upgrade using the same
|
|
package type. </p>
|
|
<h1><a name="Upgrading_using_setup.py">Upgrading using <span class="code">setup.py</span></a></h1>
|
|
<p>Before upgrading <span class="code">weewx</span>, check the section <em>
|
|
<a href="#Instructions_for_specific_versions">Instructions for Specific Versions</a></em>
|
|
to see if any specific actions are required. Then follow the standard installation
|
|
procedure:</p>
|
|
<p>Unpack the archive:</p>
|
|
<p class="tty">tar xvf weewx-X.Y.Z.tar.gz</p>
|
|
<p>Change directory into it:</p>
|
|
<p class="tty">cd weewx-X.Y.Z </p>
|
|
<p>Build the distribution:</p>
|
|
<p class="tty">./setup.py build </p>
|
|
<p>Install <span class="code">weewx</span>:</p>
|
|
<p class="warning"><strong>Warning!</strong><br />
|
|
Before doing the next step, be sure that <span class="code">home</span> in the file
|
|
<span class="code">setup.cfg</span> is set to the location of the previous
|
|
<span class="code">weewx</span> installation. </p>
|
|
<p class="tty">sudo ./setup.py install </p>
|
|
<p>The install process will do the following: </p>
|
|
<ul>
|
|
<li>Save the old <span class="code">bin</span> directory as
|
|
<span class="symcode">$WEEWX_INSTALL</span><span class="code">/bin.YYYYMMDDHHMMSS</span>
|
|
where YYYYMMDDHHMMSS is a timestamp</li>
|
|
<li>Install the new version in the <span class="code">bin</span> directory,
|
|
while preserving any user extensions in the <span class="code">bin/user</span>
|
|
directory</li>
|
|
<li>Save a copy of the old <span class="code">weewx.conf</span> as
|
|
<span class="symcode">$WEEWX_INSTALL</span><span class="code">/weewx.conf.YYYYMMDDHHMMSS</span>
|
|
</li>
|
|
<li>Merge any changes made to the old configuration file <span class="code">
|
|
weewx.conf</span> into the new configuration file, then install the merged copy.
|
|
This effectively causes any changes to override the values in the new version
|
|
of <span class="code">weewx.conf</span> </li>
|
|
<li>Install a <span class="code">skins</span> directory if one does not already
|
|
exist. </li>
|
|
</ul>
|
|
<h1><a name="Upgrading_using_DEB/RPM_package">Upgrading using DEB/RPM package</a></h1>
|
|
<h2>DEB Package</h2>
|
|
<p>Upgrade to X.Y.Z like this:</p>
|
|
<p class="tty">sudo dpkg -i weewx_X.Y.Z-R.deb</p>
|
|
<p>The upgrade process will not modify the <span class="code">weewx</span> databases.</p>
|
|
<p>Unmodified files will be upgraded. If modifications have been made to the weewx
|
|
configuration, you will be prompted as to whether you want to keep the existing
|
|
configuration or accept the new configuration. Either way, <span class="code">dpkg</span>
|
|
will save a copy of the option you did not choose.</p>
|
|
<p>For example, if <span class="code">/etc/weewx/weewx.conf</span> was modified,
|
|
<span class="code">dpkg</span> will present a message something like this:</p>
|
|
<p class="tty">Configuration file `/etc/weewx/weewx.conf' ==> Modified (by
|
|
you or by a script) since installation. ==> Package distributor has shipped
|
|
an updated version. What would you like to do about it ? Your
|
|
options are: Y or I : install the package maintainer's version N
|
|
or O : keep your currently-installed version D
|
|
: show the differences between the versions Z
|
|
: start a shell to examine the situation The default action is to keep your
|
|
current version. *** weewx.conf (Y/I/N/O/D/Z) [default=N] ?</p>
|
|
<p>Choosing <span class="code">I</span> (install the new version) will place the
|
|
previous configuration in <span class="code">/etc/weewx/weewx.conf.dpkg-old</span>
|
|
where it can be compared with the new version <span class="code">/etc/weewx/weewx.conf</span>
|
|
</p>
|
|
<p>Choosing <span class="code">O</span> (keep the current version) will place the
|
|
new configuration in <span class="code">/etc/weewx/weewx.conf.dpkg-new</span> where
|
|
it can be compared with the old version <span class="code">/etc/weewx/weewx.conf</span>
|
|
</p>
|
|
<h2>RPM Package</h2>
|
|
<p>Upgrade to X.Y.Z like this:</p>
|
|
<p class="tty">sudo rpm -U weewx-X.Y.Z-R.rpm</p>
|
|
<p>The upgrade process will not modify the <span class="code">weewx</span> databases.</p>
|
|
<p>Unmodified files will be upgraded. If modifications have been made to the configuration,
|
|
<span class="code">rpm</span> will display a message about any differences between
|
|
the changes and the new configuration. Any new changes from the upgrade will be
|
|
noted as files with a <span class="code">.rpmnew</span> extension and the modified
|
|
files will be left untouched.</p>
|
|
<p>For example, if <span class="code">/etc/weewx/weewx.conf</span> was modified,
|
|
<span class="code">rpm</span> will present a message something like this:</p>
|
|
<p class="tty">warning: /etc/weewx/weewx.conf created as /etc/weewx/weewx.conf.rpmnew</p>
|
|
<h1><a name="Instructions_for_specific_versions">Instructions for specific versions</a></h1>
|
|
<h2>V2.3 or earlier</h2>
|
|
<p>The option <span class="code">time_length</span> will now be the exact length
|
|
of the resultant plot. Before, a plot with <span class="code">time_length</span>
|
|
equal to 24 hours would result in a plot of 27 hours, now it's 24 hours. If you
|
|
want the old behavior, set it equal to 27 hours. To do this, change your section
|
|
in <span class="code">skin.conf</span> from</p>
|
|
<p class="tty">[[day_images]] x_label_format = %H:%M bottom_label_format
|
|
= %m/%d/%y %H:%M time_length = 86400 # == 24 hours</p>
|
|
<p>to</p>
|
|
<p class="tty">[[day_images]] x_label_format = %H:%M bottom_label_format
|
|
= %m/%d/%y %H:%M <span class="highlight">time_length = 97200 # == 27
|
|
hours</span></p>
|
|
<p>The service <span class="code">StdTimeSync</span> now synchronizes the console's
|
|
onboard clock on startup. This is nice because if the clock failed, perhaps because
|
|
the battery was taken out, the time is corrected first <em>before</em> data is downloaded
|
|
from the logger's memory. To take advantage of this, you can move service
|
|
<span class="code">StdTimeSync</span> to the front of the list of services to be
|
|
run. For example:</p>
|
|
<p class="tty"> [[WxEngine]]<br />
|
|
# The list of services the main weewx engine should run:<br />
|
|
service_list = <span class="highlight">weewx.wxengine.StdTimeSynch</span>, weewx.wxengine.StdConvert,
|
|
weewx.wxengine.StdCalibrate, weewx.wxengine.StdQC, weewx.wxengine.StdArchive, weewx.wxengine.StdPrint,
|
|
weewx.wxengine.StdRESTful, weewx.wxengine.StdReport<br />
|
|
</p>
|
|
<h2>V2.2 or earlier</h2>
|
|
<p>The signature of the function "<span class="code">loader</span>", used to return
|
|
an instance of the station device driver, has changed slightly. It has changed from</p>
|
|
<p class="tty">loader(config_dict)</p>
|
|
<p>to</p>
|
|
<p class="tty">loader(config_dict, engine)</p>
|
|
<p>That is, a second parameter, <span class="code">engine</span>, has been added.
|
|
This is a reference to the <span class="code">weewx</span> engine.</p>
|
|
<p>This change will affect only those who have written their own device driver.
|
|
</p>
|
|
<h2>V2.1 or earlier</h2>
|
|
<p>Version 2.2 introduces a schema, found in <span class="code">bin/user/schemas.py</span>,
|
|
for the stats database. This schema is used only when initially creating the database.
|
|
If you have a specialized stats database, that is, one that saves types other than
|
|
the default that comes with <span class="code">weewx</span>, you should edit this
|
|
file to reflect your changes before attempting to rebuild the database.</p>
|
|
<h2>V1.14 or earlier</h2>
|
|
<p>Version 2.0 introduces many new features, including a revamped internal engine.
|
|
There are two changes that are not backwards compatible:</p>
|
|
<ul>
|
|
<li>The configuration file, <span class="code">weewx.conf</span>. When upgrading
|
|
from V1.X, the setup utility will install a new, fresh copy of
|
|
<span class="code">weewx.conf</span>, which you will then have to edit by hand.
|
|
Thereafter, V2.X upgrades should be automatic.</li>
|
|
<li>Custom services. If you have written a custom service, it will have to be
|
|
updated to use the new engine. The overall architecture is very similar, except
|
|
that functions must be <em>bound</em> to events, rather than get called implicitly.
|
|
See the sections <a href="customizing.htm#Customizing_a_Service">Customizing
|
|
a Service</a> and <a href="customizing.htm#Adding_a_Service">Adding a Service</a>
|
|
in the <a href="customizing.htm">Customizing Guide</a> for details on how to
|
|
do this.</li>
|
|
</ul>
|
|
<p>All skins should be completely backwards compatible, so you should not have to
|
|
change your templates or skin configuration file, <span class="code">skin.conf</span>.
|
|
</p>
|
|
<p>If you have written a custom report generator it should also be backwards compatible.</p>
|
|
<h2>V1.13 or earlier</h2>
|
|
<p>Version 1.14 introduces some new webpages that have been expressly formatted
|
|
for the smartphone by using <a href="http://jquery.com/">jQuery</a>.</p>
|
|
<p>The skins shipped with the distribution take advantage of these features. If
|
|
you do nothing, your old skins will continue to work, but you will not be taking
|
|
advantage of these new webpages.</p>
|
|
<p>If you want them, then you have two choices:</p>
|
|
<ol>
|
|
<li>Rename your old skin directory (call it "<span class="code">skins.old</span>")
|
|
then do the install. This will install the new skin distribution. You can then
|
|
modify it to reflect any changes you have made, referring to
|
|
<span class="code">skins.old</span> for guidance. If you have not changed many
|
|
things, this approach will be the easiest.</li>
|
|
<li>Alternatively, change the contents of your existing skin directory to include
|
|
the new webpages. If you take this approach, you will need to copy over the
|
|
contents of the subdirectory <span class="code">skins/Standard/smartphone</span>
|
|
from the distribution into your <span class="code">skins/Standard</span> directory.
|
|
You will then need to modify your <span class="code">skin.conf</span>.
|
|
<p>After the section that looks like</p>
|
|
<p class="tty">[[[Mobile]]] template = mobile.html.tmpl</p>
|
|
<p>add the following directives:</p>
|
|
<p class="tty">[[[MobileSmartphone]]] template = smartphone/index.html.tmpl
|
|
[[[MobileTempOutside]]] template = smartphone/temp_outside.html.tmpl
|
|
[[[MobileRain]]] template = smartphone/rain.html.tmpl
|
|
[[[MobileBarometer]]] template = smartphone/barometer.html.tmpl
|
|
[[[MobileWind]]] template = smartphone/wind.html.tmpl
|
|
[[[MobileRadar]]] template = smartphone/radar.html.tmpl</p>
|
|
<p>Then modify section <span class="code">[CopyGenerator]</span> to add the
|
|
<span class="highlight">highlighted</span> files:</p>
|
|
<p class="tty">[CopyGenerator] # #
|
|
This section is used by the generator CopyGenerator # #
|
|
List of files that are to be copied at the first invocation of the generator
|
|
only copy_once = backgrounds/*, weewx.css, mobile.css,
|
|
favicon.ico, <span class="highlight">smartphone/icons/*, smartphone/custom.js</span></p>
|
|
</li>
|
|
</ol>
|
|
<p>Whichever approach you chose, the generated files will appear in
|
|
<span class="code">public_html/smartphone</span>. The start of the document root
|
|
will be at <span class="code">public_html/smartphone/index.html</span>. You may
|
|
want to add a link to this in the template for your main index page
|
|
<span class="code">skins/Standard/index.html.tmpl</span>.</p>
|
|
<h2>V1.12 or earlier</h2>
|
|
<p>Version 1.13 changed the way binding happens to the databases used in reports
|
|
so that it happens much later. The upshot is that the signature of a few functions
|
|
changed. Most you are unlikely to encounter. The exception is if you have written
|
|
custom template <em>search lists</em>, as described in the section <em>
|
|
<a href="customizing.htm#Extending_an_existing_generator">Extending an existing
|
|
report generator</a></em> in the <a href="customizing.htm">Customizing weewx guide</a>.
|
|
This section has been updated to reflect the new function signatures. As a side
|
|
effect, the illustrated example actually has become much simpler!</p>
|
|
<p>No changes to skins.</p>
|
|
<h2>V1.9 or earlier</h2>
|
|
<p>Version 1.10 introduced several new features. </p>
|
|
<h3>New almanac features, icon, and mobile template</h3>
|
|
<p>Version 1.10 introduces some extra almanac features, such as the azimuth and
|
|
elevation of the sun and moon, or when the next solstice will be. It also includes
|
|
a template formatted for smartphones, as well as an icon ("<span class="code">favicon.ico</span>")
|
|
that displays in your browser toolbar. The skins shipped with the distribution take
|
|
advantage of these features. If you do nothing, your old skins will continue to
|
|
work, but you will not take advantage of these new features. </p>
|
|
<p>If you want these new features then you have two choices:</p>
|
|
<ol>
|
|
<li>Rename your old skin directory (call it "<span class="code">skin.old</span>")
|
|
then do the install. This will install the new skin distribution. You can modify
|
|
it to reflect any changes you have made, referring to <span class="code">skin.old</span>
|
|
for guidance.</li>
|
|
<li>Alternatively, change the contents of your existing skin directory to take
|
|
advantage of the new features. If you take this approach, you will need to copy
|
|
over files <span class="code">favicon.ico, mobile.css</span>, and
|
|
<span class="code">mobile.html.tmpl</span> from the distribution into your
|
|
<span class="code">skin/Standard</span> directory. Modify <span class="code">
|
|
skins/Standard/index.html.tmpl</span> to take advantage of the new almanac features,
|
|
using the version shipped with the distribution for guidance. You will then
|
|
need to modify your <span class="code">skin.conf</span>.
|
|
<p>Add a new <span class="code">[[[Mobile]]]</span> section:</p>
|
|
<p class="tty">[FileGenerator] ... [[ToDate]] ... [[[Mobile]]] template
|
|
= mobile.html.tmpl</p>
|
|
<p>Then add <span class="code">mobile.css</span> and <span class="code">favicon.ico</span>
|
|
to the list of files to be copied on report generation:</p>
|
|
<p class="tty">[CopyGenerator] copy_once = backgrounds/*,
|
|
weewx.css, mobile.css, favicon.ico</p>
|
|
</li>
|
|
</ol>
|
|
<p>Which approach you should take will depend on how extensively you have modified
|
|
the stock skin distribution. If the modifications are slight, approach #1 will be
|
|
easier, otherwise use approach #2.</p>
|
|
<h3>Backwards compatibility</h3>
|
|
<p>With the introduction of explicit control of output units in the templates such
|
|
as</p>
|
|
<p class="tty">$day.outTemp.max.degree_C</p>
|
|
<p>the calling signature of the following two Python classes was changed</p>
|
|
<ul>
|
|
<li><span class="code">weewx.stats.TaggedStats</span></li>
|
|
<li><span class="code">weewx.stats.TimeSpanStats</span></li>
|
|
</ul>
|
|
<p>The example of writing a custom generator <span class="code">MyFileGenerator</span>
|
|
(which produced "all time" statistics) has been changed to reflect the
|
|
new signatures.</p>
|
|
<p>This will only affect you if you have written a custom generator.</p>
|
|
<h2>V1.7.0 or earlier</h2>
|
|
<p>With the introduction of a standard archiving service, <span class="code">StdArchive</span>,
|
|
the names of some events have changed. This will not affect you unless you have
|
|
written a custom service.</p>
|
|
<h2>V.1.5.0 or earlier</h2>
|
|
<p>V1.7 introduces <em>skins</em>. The skins live in subdirectory
|
|
<span class="code">skins</span>. They are <em>not</em> compatible with the old
|
|
<span class="code">template</span> subdirectory --- you can't simply rename
|
|
<span class="code">templates</span> to <span class="code">skins</span>. </p>
|
|
<p>The part of the configuration file dealing with the presentation layer has been
|
|
split off into a separate file <span class="code">skin.conf</span>. Hence, once
|
|
again, the installation script <span class="code">setup.py</span> will NOT merge
|
|
your old <span class="code">weewx.conf</span> configuration file into the new one.
|
|
You will have to re-edit <span class="code">weewx.conf</span> to put in your customizations.
|
|
You may also have to edit <span class="code">skin.conf</span> for whatever skin
|
|
you choose (right now, only one skin, <em>Standard</em>, comes with the distribution).</p>
|
|
<p>However, a reinstall of V1.7 <em>will</em> merge your changes for
|
|
<span class="code">weewx.conf</span>. It will also merge any changes you have made
|
|
to <span class="code">skin.conf</span> as well.</p>
|
|
<p>Please check the following:</p>
|
|
<ul>
|
|
<li>Option "<span class="code">altitude</span>" in section
|
|
<span class="code">[Station]</span> now takes a unit. Hence, it should look
|
|
something like:
|
|
<p class="tty">altitude = 120, meter</p>
|
|
<br />
|
|
</li>
|
|
<li>In a similar manner, options <span class="code">heating_base</span> and
|
|
<span class="code">cooling_base</span> in <span class="code">skin.conf</span>
|
|
also take units:
|
|
<p class="tty">heating_base = 65, degree_F cooling_base = 65, degree_F</p>
|
|
</li>
|
|
</ul>
|
|
<p>The directory '<span class="code">templates</span>' is no longer used;
|
|
it has been replaced with directory '<span class="code">skins</span>'. You
|
|
may delete it if you wish:</p>
|
|
<p class="tty">rm -r <span class="symcode">$WEEWX_ROOT</span>/templates</p>
|
|
<h2>V1.4.0 or earlier</h2>
|
|
<p>Because the configuration file <span class="code">weewx.conf</span> changed significantly
|
|
going from V1.4 to V1.5, the installation script <span class="code">setup.py</span>
|
|
will NOT merge your old configuration file into the new one. You will have to re-edit
|
|
<span class="code">weewx.conf</span> to put in your customizations.</p>
|
|
<h2>V1.2.0 or earlier</h2>
|
|
<h3>Optional</h3>
|
|
<p>Option <span class="code">clock_check</span>, previously found in the
|
|
<span class="code">[VantagePro]</span> section, is now found in the
|
|
<span class="code">[Station]</span> section. The install program will put a default
|
|
value in the new place, but it will not delete nor move your old value over. If
|
|
you have changed this value or if you can't stand the thought of
|
|
<span class="code">clock_check</span> appearing in two different places, you should
|
|
delete the old one found under <span class="code">[VantagePro]</span> and make sure
|
|
the new value, found under <span class="code">[Station]</span> is correct.</p>
|
|
<p>Two Python files are no longer used, so they may be deleted from your installation
|
|
if you wish:</p>
|
|
<p class="tty">rm <span class="symcode">$WEEWX_ROOT</span>/bin/weewx/processdata.py
|
|
rm <span class="symcode">$WEEWX_ROOT</span>/bin/weewx/mainloop.py</p>
|
|
<p>In addition, file <span class="code">readme.htm</span> has been moved to subdirectory
|
|
<span class="symcode">$WEEWX_ROOT</span><span class="code">/docs</span>, so the
|
|
old one can be deleted:</p>
|
|
<p class="tty">rm <span class="symcode">$WEEWX_ROOT</span>/readme.htm</p>
|
|
<p> </p>
|
|
<p class="copyright">© <a href="copyright.htm">Copyright</a> Tom Keffer </p>
|
|
|
|
</body>
|
|
|
|
</html>
|