mirror of
https://github.com/weewx/weewx.git
synced 2026-04-22 10:37:06 -04:00
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.0a2
|
|
<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>
|