removed

changed

added

Upgrading weewx
Version: 3.0.1

This document explains the three methods of upgrading:

The section Instructions for Specific Versions describes changes required from one version to the next. These changes apply to every upgrade method.

Warning!
You must use the same upgrade technique as your initial install! For example, if you used setup.py to install weewx, you should use setup.py to upgrade. If you used a DEB or RPM package to install, then you should upgrade using the same package type.

Upgrading using setup.py

Before upgrading weewx, check the section Instructions for Specific Versions to see if any specific actions are required. Then follow the standard installation procedure:

Unpack the archive:

tar xvfz weewx-X.Y.Z.tar.gz

Change directory into it:

cd weewx-X.Y.Z

Build the distribution:

./setup.py build

Install weewx:

Warning!
Before doing the next step, be sure that home in the file setup.cfg is set to the location of the previous weewx installation.

sudo ./setup.py install

The install process will do the following:

Upgrading using DEB package

Upgrade to X.Y.Z like this:

sudo dpkg -i weewx_X.Y.Z-R.deb

The upgrade process will not modify the weewx databases.

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, dpkg will save a copy of the option you did not choose.

For example, if /etc/weewx/weewx.conf was modified, dpkg will present a message something like this:

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] ?

Choosing I (install the new version) will place the previous configuration in /etc/weewx/weewx.conf.dpkg-old where it can be compared with the new version /etc/weewx/weewx.conf

Choosing O (keep the current version) will place the new configuration in /etc/weewx/weewx.conf.dpkg-new where it can be compared with the old version /etc/weewx/weewx.conf

Upgrading using RPM package

Upgrade to X.Y.Z like this:

sudo rpm -U weewx-X.Y.Z-R.rpm

The upgrade process will not modify the weewx databases.

Unmodified files will be upgraded. If modifications have been made to the configuration, rpm 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 .rpmnew extension and the modified files will be left untouched.

For example, if /etc/weewx/weewx.conf was modified, rpm will present a message something like this:

warning: /etc/weewx/weewx.conf created as /etc/weewx/weewx.conf.rpmnew

Instructions for specific versions

From V2.7 or earlier

Overview

While a lot has changed with Version 3, the upgrade process should take care of most changes for most users. However, if you have installed an extension or, especially, if you have written a custom service, search list extension, or uploader, you will have to make some changes.

Database contents

With Version 3, there is no longer a separate "stats" database. Instead, "daily summaries" have been included in the same database as the archive data — everything is under one name. For example, if you are using sqlite, both the archive data and the daily summaries will be inside file weewx.sdb. With MySQL, everything is inside the database weewx. This makes it easier to keep all data together when working with multiple databases.

This change in database structure should be transparent to you. On startup, weewx will automatically backfill the new internal daily summaries from the archive data. Your old "stats" database will no longer be used and may safely set aside or even deleted.

Pressure calibration

Since the new StdWXCalculate service is applied after the StdCalibrate services, the pressure_offset parameter is no longer necessary; pressure calibration can be applied just like any other calibration. If your pressure was calibrated using the pressure_offset parameter, move the calibration to the [StdCalibrate] section. This applies only to CC3000, FineOffsetUSB, Ultimeter, WS1, WS23xx, and WS28xx hardware.

weewx.conf

A version 2.X weewx.conf file is not compatible with Version 3.X. However, the upgrade process should automatically update the file. Nevertheless, the changes are documented below:

2.73.0
[StdReport]
    data_binding = wx_binding
[StdArchive]
    archive_database = archive_sqlite
    stats_database = stats_sqlite
    archive_schema = user.schemas.defaultArchiveSchema
    stats_schema = user.schemas.defaultStatsSchema
[StdArchive]
    data_binding = wx_binding
[DataBindings]
    [[wx_binding]]
        database = archive_sqlite
        manager = weewx.wxmanager.WXDaySummaryManager
        table_name = archive
        schema = schemas.wview.schema
[Databases]
    [[archive_sqlite]]
        root = %(WEEWX_ROOT)s
        database = archive/weewx.sdb
        driver = weedb.sqlite
    [[stats_sqlite]]
        root = %(WEEWX_ROOT)s
        database = archive/stats.sdb
        driver = weedb.sqlite
    [[archive_mysql]]
        host = localhost
        user = weewx
        password = weewx
        database = weewx
        driver = weedb.mysql
    [[stats_mysql]]
        host = localhost
        user = weewx
        password = weewx
        database = stats
        driver = weedb.mysql
[Databases]
    [[archive_sqlite]]
        root = %(WEEWX_ROOT)s
        database_name = archive/weewx.sdb
        driver = weedb.sqlite




    [[archive_mysql]]
        host = localhost
        user = weewx
        password = weewx
        database_name = weewx
        driver = weedb.mysql






[Engines]
  [[WxEngine]]
    prep_services = \
weewx.wxengine.StdTimeSynch
    process_services = \
weewx.wxengine.StdConvert, \
weewx.wxengine.StdCalibrate, \
weewx.wxengine.StdQC

    archive_services = \
weewx.wxengine.StdArchive
    restful_services = \
weewx.restx.StdStationRegistry, \
weewx.restx.StdWunderground, \
weewx.restx.StdPWSweather, \
weewx.restx.StdCWOP, \
weewx.restx.StdWOW, \
weewx.restx.StdAWEKAS
    report_services = \
weewx.wxengine.StdPrint, \
weewx.wxengine.StdReport
[Engine]
  [[Services]]
    prep_services = \
weewx.engine.StdTimeSynch
    process_services = \
weewx.engine.StdConvert, \
weewx.engine.StdCalibrate, \
weewx.engine.StdQC, \
weewx.wxservices.StdWXCalculate
    archive_services = \
weewx.engine.StdArchive
    restful_services = \
weewx.restx.StdStationRegistry, \
weewx.restx.StdWunderground, \
weewx.restx.StdPWSweather, \
weewx.restx.StdCWOP, \
weewx.restx.StdWOW, \
weewx.restx.StdAWEKAS
    report_services = \
weewx.engine.StdPrint, \
weewx.engine.StdReport

Custom data sources in skins

The mechanism for specifying non-default data sources in skins has changed. If you modified the Standard skin, or created or used other skins that draw data from a database other than the weather database, you must change how the other sources are specified.

For example, in the cmon extension:

2.73.0
[ImageGenerator]
    ...
    [[day_images]]
        ...
        [[[daycpu]]]
            archive_database = cmon_sqlite
            [[[cpu_user]]]
            [[[cpu_idle]]]
            [[[cpu_system]]]
[ImageGenerator]
    ...
    [[day_images]]
        ...
        [[[daycpu]]]
            data_binding = cmon_binding
            [[[cpu_user]]]
            [[[cpu_idle]]]
            [[[cpu_system]]]

Extensions

Many skins will work in v3 with no modification required. However, every search list extension will have to be upgraded, every restful extension must be upgraded, and some other services must be upgraded.

There is no automated upgrade system for extensions; if an extension must be upgraded, you must do it manually. If the extension has any python code, this will mean replacing any v2-compatible code with v3-compatible code. In some cases parts of the configuration file weewx.conf must be modified.

For example, to update the pmon extension, replace bin/user/pmon.py with the v3-compatible pmon.py and modify weewx.conf as shown in this table:

2.73.0
[ProcessMonitor]
    database = pmon_sqlite
[ProcessMonitor]
    data_binding = pmon_binding
[DataBindings]
    [[pmon_binding]]
        database = pmon_sqlite
        manager = weewx.manager.DaySummaryManager
        table_name = archive
        schema = user.pmon.schema
[Databases]
    [[pmon_sqlite]]
        root = %(WEEWX_ROOT)s
        database = archive/pmon.sdb
        driver = weedb.sqlite
[Databases]
    [[pmon_sqlite]]
        root = %(WEEWX_ROOT)s
        database_name = archive/pmon.sdb
        driver = weedb.sqlite

For other extensions, see the extension's documentation or contact the author of the extension.

Search list extensions

The introduction of data bindings has meant a change in the calling signature of search list extensions. By way of example, here's the example from the section Extending the list in the Customizing Guide, with the differences highlighted.

2.7 3.0
def get_extension(self, timespan, archivedb, statsdb):

    all_stats = TimeSpanStats(timespan,
                              statsdb,
                              formatter=self.generator.formatter,
                              converter=self.generator.converter)
    week_dt = datetime.date.fromtimestamp(timespan.stop) - datetime.timedelta(weeks=1)
    week_ts = time.mktime(week_dt.timetuple())
    seven_day_stats = TimeSpanStats(TimeSpan(week_ts, timespan.stop),
                                    statsdb,
                                    formatter=self.generator.formatter,
                                    converter=self.generator.converter)

    search_list_extension = {'alltime'   : all_stats,
                             'seven_day' : seven_day_stats}
        
    return search_list_extension
def get_extension_list(self, timespan, db_lookup):

    all_stats = TimespanBinder(timespan, 
                               db_lookup,
                               formatter=self.generator.formatter,
                               converter=self.generator.converter)
    week_dt = datetime.date.fromtimestamp(timespan.stop) - datetime.timedelta(weeks=1)
    week_ts = time.mktime(week_dt.timetuple())
    seven_day_stats = TimespanBinder(TimeSpan(week_ts, timespan.stop),
                                     db_lookup,
                                     formatter=self.generator.formatter,
                                     converter=self.generator.converter)

    search_list_extension = {'alltime'   : all_stats,
                             'seven_day' : seven_day_stats}
        
    return [search_list_extension]

A few things to note:

Derived quantities

Some calculations that were done in drivers or in hardware are now done consistently by the new StdWXCalculate service. Drivers should no longer calculate derived quantities such as windchill, heatindex, dewpoint, or rain rate.

Driver APIs

The base class for drivers has been renamed, and new, optional, methods have been defined to provide hooks for configuring hardware and producing default and upgraded configuration stanzas.

These changes affect only those who have written custom drivers.

2.73.0
import weewx.abstractstation

class ACME960(weewx.abstractstation.AbstractStation):
    ...
import weewx.drivers

class ACME960(weewx.drivers.AbstractDevice):
    ...

Service APIs

The base class for services has moved.

This affects only those who have written custom services.

2.73.0
import weewx.wxengine

class BetterMousetrapService(weewx.wxengine.StdService):
    ...
import weewx.engine

class BetterMousetrapService(weewx.engine.StdService):
    ...

RESTful APIs

Some of the methods internal to RESTful services have changed, specifically those that relate to getting configuration options from weewx.conf and configuring databases.

This affects only those who have written custom RESTful services.

Here is an example of obtaining the database dictionary for use in the RESTful service thread.

2.73.0
site_dict = weewx.restx.get_dict(config_dict, 'Uploader') db_name = config_dict['StdArchive']['archive_database'] db_dict = config_dict['Databases'][db_name] site_dict.setdefault('database_dict', db_dict) site_dict = config_dict['StdRESTful']['Uploader'] site_dict = accumulateLeaves(site_dict, max_level=1) manager_dict = weewx.manager.open_manager_with_config(config_dict, 'wx_binding')

Database APIs

The methods for obtaining, opening, and querying databases have changed. This affects only those who have written code that accesses databases.

The class Manager and its subclasses have replaced the old Archive class. The table name is no longer hard-coded, so developers should use the table name from the database binding. There is no longer a separate StatsDb class, its functions having been subsumed into the Manager class and its subclasses.

A new class DBBinder is the preferred way of getting a Manager class, as it will automatically take care of instantiating the right class, as well as caching instances of Manager. An instance of DBBinder is held by the engine as attribute db_binder. Here's an example of making a simple query.

2.73.0
db = config_dict['StdArchive']['archive_database'] self.database_dict = config_dict['Databases'][db] with weewx.archive.Archive.open(self.database_dict) as archive: val = archive.getSql("SELECT AVG(windSpeed) FROM archive " "WHERE dateTime>? AND dateTime<=?", (start_ts, end_ts)) with self.engine.db_binder.get_manager('wx_binding') as db_manager: val = db_manager.getSql("SELECT AVG(windSpeed) FROM %s " "WHERE dateTime>? AND dateTime<=?" % db_manager.table_name, (start_ts, end_ts))

Generator APIs

The base class for report generators has changed. The old class CachedReportGenerator no longer exists; its functionality has been replaced by an instance of DBBinder, held by the generator superclass. This affects only those who have written customer generators.

Here's an example:

2.7 3.0
class GaugeGenerator(weewx.reportengine.CachedReportGenerator) def run(self): archive_name = self.config_dict['GaugeGenerator']['archive_name'] archive = self._getArchive(archive_name) results = archive.getSql(...) class GaugeGenerator(weewx.reportengine.ReportGenerator) def run(self): db_manager = self.generator.db_binder.get_manager() results = db_manager.getSql(...)

Extension installer

The setup.py utility is now included in the installation; it is no longer necessary to keep a copy of the weewx source tree just for the setup.py utility.

For .deb and .rpm installations, the command wee_setup is a symlink to setup.py.

The options for installing extensions changed slightly to be more consistent with the rest of the options to setup.py.

2.73.0
setup.py --extension --install extensions/basic
setup.py --extension --install basic.tar.gz
setup.py --extension --uninstall basic
setup.py --extension --list
setup.py --extension --install basic.tar.gz --dryrun
setup.py install --extension extensions/basic
setup.py install --extension basic.tar.gz
setup.py uninstall --extension basic
setup.py list-extensions
setup.py install --extension basic.tar.gz --dry-run

From V2.6 or earlier

Version 2.7 is backwards compatible with earlier versions with one minor exception.

It now includes the ability to localize the weewx and server uptimes. Previously, the labels days, hours, and minutes were hardcoded in a Python utility. There was no way of changing them. Now, like any other labels, they are taken from the skin configuration file, skin.conf, section [[Labels]]. Older configuration files had a definition for hour, but none for day, and minute. Also, the old definition for hour used an abbreviation hrs instead of hours.

If you do nothing, your weewx and station uptimes will look like:

Weewx uptime:  1 day, 1 hrs, 41 minutes
Server uptime: 2 days, 10 hrs, 22 minutes

Note how the label for hours is abbreviated and always uses the plural. If you want the previous behavior, or if you want to localize the labels, you should update your skin configuration file. Remove the old entries for hour and second and replace them with:

day               = " day",    " days"
hour              = " hour",   " hours"
minute            = " minute", " minutes"
second            = " second", " seconds"

The first item is the singular spelling, the second the plural. This will result in the desired

Weewx uptime:  1 day, 1 hour, 41 minutes
Server uptime: 2 days, 10 hours, 22 minutes

From V2.5 or earlier

Version 2.6 is backwards compatible with earlier versions, with a couple of small exceptions.

From V2.3 or earlier

The option time_length will now be the exact length of the resultant plot. Before, a plot with time_length 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 skin.conf from

[[day_images]] x_label_format = %H:%M bottom_label_format = %m/%d/%y %H:%M time_length = 86400 # == 24 hours

to

[[day_images]] x_label_format = %H:%M bottom_label_format = %m/%d/%y %H:%M time_length = 97200 # == 27 hours

The service StdTimeSync 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 before data is downloaded from the logger's memory. To take advantage of this, you can move service StdTimeSync to the front of the list of services to be run. For example:

[[WxEngine]] # The list of services the main weewx engine should run: service_list = weewx.wxengine.StdTimeSynch, weewx.wxengine.StdConvert, weewx.wxengine.StdCalibrate, weewx.wxengine.StdQC, weewx.wxengine.StdArchive, weewx.wxengine.StdPrint, weewx.wxengine.StdRESTful, weewx.wxengine.StdReport

From V2.2 or earlier

The signature of the function "loader", used to return an instance of the station device driver, has changed slightly. It has changed from

loader(config_dict)

to

loader(config_dict, engine)

That is, a second parameter, engine, has been added. This is a reference to the weewx engine.

This change will affect only those who have written their own device driver.

From V2.1 or earlier

Version 2.2 introduces a schema, found in bin/user/schemas.py, 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 weewx, you should edit this file to reflect your changes before attempting to rebuild the database.

From V1.14 or earlier

Version 2.0 introduces many new features, including a revamped internal engine. There are two changes that are not backwards compatible:

All skins should be completely backwards compatible, so you should not have to change your templates or skin configuration file, skin.conf.

If you have written a custom report generator it should also be backwards compatible.

From V1.13 or earlier

Version 1.14 introduces some new webpages that have been expressly formatted for the smartphone by using jQuery.

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.

If you want them, then you have two choices:

  1. Rename your old skin directory (call it "skins.old") 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 skins.old for guidance. If you have not changed many things, this approach will be the easiest.
  2. 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 skins/Standard/smartphone from the distribution into your skins/Standard directory. You will then need to modify your skin.conf.

    After the section that looks like

    [[[Mobile]]] template = mobile.html.tmpl

    add the following directives:

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

    Then modify section [CopyGenerator] to add the highlighted files:

    [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, smartphone/icons/*, smartphone/custom.js

Whichever approach you chose, the generated files will appear in public_html/smartphone. The start of the document root will be at public_html/smartphone/index.html. You may want to add a link to this in the template for your main index page skins/Standard/index.html.tmpl.

From V1.12 or earlier

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 search lists, as described in the section Extending an existing report generator in the Customizing weewx guide. This section has been updated to reflect the new function signatures. As a side effect, the illustrated example actually has become much simpler!

No changes to skins.

From V1.9 or earlier

Version 1.10 introduced several new features.

New almanac features, icon, and mobile template

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 ("favicon.ico") 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.

If you want these new features then you have two choices:

  1. Rename your old skin directory (call it "skin.old") then do the install. This will install the new skin distribution. You can modify it to reflect any changes you have made, referring to skin.old for guidance.
  2. 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 favicon.ico, mobile.css, and mobile.html.tmpl from the distribution into your skin/Standard directory. Modify skins/Standard/index.html.tmpl to take advantage of the new almanac features, using the version shipped with the distribution for guidance. You will then need to modify your skin.conf.

    Add a new [[[Mobile]]] section:

    [FileGenerator] ... [[ToDate]] ... [[[Mobile]]] template = mobile.html.tmpl

    Then add mobile.css and favicon.ico to the list of files to be copied on report generation:

    [CopyGenerator] copy_once = backgrounds/*, weewx.css, mobile.css, favicon.ico

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.

Backwards compatibility

With the introduction of explicit control of output units in the templates such as

$day.outTemp.max.degree_C

the calling signature of the following two Python classes was changed

The example of writing a custom generator MyFileGenerator (which produced "all time" statistics) has been changed to reflect the new signatures.

This will only affect you if you have written a custom generator.

From V1.7.0 or earlier

With the introduction of a standard archiving service, StdArchive, the names of some events have changed. This will not affect you unless you have written a custom service.

From V.1.5.0 or earlier

V1.7 introduces skins. The skins live in subdirectory skins. They are not compatible with the old template subdirectory --- you can't simply rename templates to skins.

The part of the configuration file dealing with the presentation layer has been split off into a separate file skin.conf. Hence, once again, the installation script setup.py will NOT merge your old weewx.conf configuration file into the new one. You will have to re-edit weewx.conf to put in your customizations. You may also have to edit skin.conf for whatever skin you choose (right now, only one skin, Standard, comes with the distribution).

However, a reinstall of V1.7 will merge your changes for weewx.conf. It will also merge any changes you have made to skin.conf as well.

Please check the following:

The directory 'templates' is no longer used; it has been replaced with directory 'skins'. You may delete it if you wish:

rm -r $WEEWX_ROOT/templates

From V1.4.0 or earlier

Because the configuration file weewx.conf changed significantly going from V1.4 to V1.5, the installation script setup.py will NOT merge your old configuration file into the new one. You will have to re-edit weewx.conf to put in your customizations.

From V1.2.0 or earlier

Option clock_check, previously found in the [VantagePro] section, is now found in the [Station] 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 clock_check appearing in two different places, you should delete the old one found under [VantagePro] and make sure the new value, found under [Station] is correct.

Two Python files are no longer used, so they may be deleted from your installation if you wish:

rm $WEEWX_ROOT/bin/weewx/processdata.py rm $WEEWX_ROOT/bin/weewx/mainloop.py

In addition, file readme.htm has been moved to subdirectory $WEEWX_ROOT/docs, so the old one can be deleted:

rm $WEEWX_ROOT/readme.htm