-
Notifications
You must be signed in to change notification settings - Fork 10
Upgrade Guide
This is the guide to upgrading an existing Ecowitt Gateway driver extension installation. It should be used when upgrading an existing Ecowitt Gateway driver installation irrespective of whether the Ecowitt Gateway driver was installed manually or by using the WeeWX utility wee_extension. This guide also applies irrespective of whether the Ecowitt Gateway driver is used as a WeeWX driver or service.
The section Instructions for specific versions describes changes required from one version to the next along with specific actions that may need to be taken to upgrade to the version concerned. As a minimum you should refer to the relevant section before undertaking the upgrade.
wee_extension
may be used to upgrade an existing Ecowitt Gateway driver extension installation irrespective of whether the Ecowitt Gateway driver extension was installed manually or using wee_extension
. To use wee_extension
to upgrade an existing Ecowitt Gateway driver extension installation:
-
Download the latest Ecowitt Gateway driver extension package:
$ wget -P /var/tmp https://github.com/gjr80/weewx-gw1000/releases/download/v0.5.0b2/gw1000-0.5.0b2.tar.gz
-
Install the downloaded Ecowitt Gateway driver extension:
$ wee_extension --install=/var/tmp/gw1000-0.5.0b2.tar.gz
Note: Depending on your system/installation the above command may need to be prefixed with
sudo
.Note: Depending on your WeeWX installation
wee_extension
may need to be prefixed with the path towee_extension
. -
Make any necessary changes to WeeWX or weewx.conf based on the relevant portions of the Instructions for specific versions section.
-
You may test the upgraded Ecowitt Gateway driver by running the driver file directly using the
--test-driver
command line option:$ PYTHONPATH=/home/weewx/bin python -m user.gw1000 --test-driver
for WeeWX
setup.py
installs or for WeeWX package installs use:$ PYTHONPATH=/usr/share/weewx python -m user.gw1000 --test-driver
Note: Whilst the driver may be run independently of WeeWX, the driver still requires access to WeeWX and it's dependencies. Consequently, if WeeWX 4.0.0 or later is installed the driver must be run under the same Python version as WeeWX uses. This may be different to the Python version invoked by the command 'python'. This means that on some systems 'python' in the above commands may need to be changed to 'python2' or 'python3'.
You should observe loop packets being emitted on a regular basis. Once finished press
ctrl-c
to exit.Note: You will only see loop packets and not archive records when running the driver directly. This is because you are seeing output directly from the driver and not WeeWX.
-
Restart the WeeWX daemon:
$ sudo /etc/init.d/weewx restart
or
$ sudo service weewx restart
or
$ sudo systemctl start reweewx
An existing Ecowitt Gateway driver extension installation may be upgraded manually irrespective of whether the Ecowitt Gateway driver extension was previously installed/upgraded manually or using wee_extension
. However, to maintain the integrity of the installed extension data maintained by wee_extension
, it is recommended that extensions previously installed/upgraded by wee_extension
continue to be upgraded using wee_extension. You can check if the Ecowitt Gateway driver was previously installed/upgraded using the wee_extension
utility by using the following command:
$ wee_extension --list
If the Ecowitt Gateway driver was installed using the wee_extension
utility 'GW1000' will be listed as an installed extension.
To manually upgrade and existing Ecowitt Gateway driver extension installation:
-
Download the latest Ecowitt Gateway driver extension package:
$ wget -P /var/tmp https://github.com/gjr80/weewx-gw1000/releases/download/v0.5.0b2/gw1000-0.5.0b2.tar.gz
-
Extract the contents of the GW1000 driver extension package:
$ tar -xzf /var/tmp/gw1000-0.5.0b2.tar.gz -C /var/tmp
-
Copy the file gw1000.py to the BIN_ROOT/user directory:
$ cp /var/tmp/gw1000/bin/user/gw1000.py BIN_ROOT/user
Note: Depending on your system/installation the above command may need to be prefixed with sudo.
-
Make any necessary changes to WeeWX or weewx.conf based on the relevant portions of the Instructions for specific versions section.
-
You may test the upgraded Ecowitt Gateway driver by running the driver file directly using the
--test-driver
command line option:$ PYTHONPATH=/home/weewx/bin python -m user.gw1000 --test-driver
for WeeWX
setup.py
installs or for WeeWX package installs use:$ PYTHONPATH=/usr/share/weewx python -m user.gw1000 --test-driver
Note: Whilst the driver may be run independently of WeeWX, the driver still requires access to WeeWX and it's dependencies. Consequently, if WeeWX 4.0.0 or later is installed the driver must be run under the same Python version as WeeWX uses. This may be different to the Python version invoked by the command 'python'. This means that on some systems 'python' in the above commands may need to be changed to 'python2' or 'python3'.
You should observe loop packets being emitted on a regular basis. Once finished press
ctrl-c
to exit.Note: You will only see loop packets and not archive records when running the driver directly. This is because you are seeing output directly from the driver and not WeeWX.
-
Restart the WeeWX daemon:
$ sudo /etc/init.d/weewx restart
or
$ sudo service weewx restart
or
$ sudo systemctl start reweewx
V0.5.0 changes will affect some users as follows.
The introduction of support for the WS90 sensor suite has seen the introduction of a number of new fields to support the WS90 piezoelectric rainfall sensor. The new internal piezo rainfall fields are p_rain
, p_rainevent
, p_rainrate
, p_rainday
, p_rainweek
, p_rainmonth
and p_rainyear
.
The Ecowitt LAN/Wi-Fi Gateway API documentation and the WSView Plus app have introduced the concept of two distinct groups of rainfall data; traditional gauge rainfall data and piezo gauge rainfall data. In light of this, and to avoid confusion between the two, the internal driver rainfall fields that existed in v0.4.2 and earlier have been renamed with a 't_' prefix to distinguish these fields as containing traditional rainfall gauge data. The renamed internal traditional rainfall fields are t_rain
, t_rainevent
, t_rainrate
, t_rainhour
, t_rainday
, t_rainweek
, t_rainmonth
, t_rainyear
and t_raintotal
.
The default field map has also been adjusted such that the traditional rainfall gauge data is mapped to the 'standard' WeeWX rainfall fields and the piezo rainfall gauges data is mapped through to WeeWX fields with the 'p_' prefix. The rainfall related entries in the v0.5.0 default field map are:
WeeWX field name | Gateway device field name | Description |
---|---|---|
p_rain | p_rain | piezo gauge rainfall in the current archive or loop period |
p_rainevent | p_rainevent | rainfall event total piezo gauge rainfall |
p_rainrate | p_rainrate | piezo gauge rain rate |
p_rainday | p_rainday | total piezo gauge rainfall today |
p_rainweek | p_rainweek | total piezo gauge rainfall this week |
p_rainmonth | p_rainmonth | total piezo gauge rainfall this month |
p_rainyear | p_rainyear | total piezo gauge rainfall this year |
rain | t_rain | traditional gauge rainfall in the current archive or loop period |
stormRain | t_rainevent | rainfall event total traditional gauge rainfall |
rainRate | t_rainrate | traditional gauge rain rate |
hourRain | t_rainhour | total traditional gauge rainfall this hour |
dayRain | t_rainday | total traditional gauge rainfall today |
weekRain | t_rainweek | total traditional gauge rainfall this week |
monthRain | t_rainmonth | total traditional gauge rainfall this month |
yearRain | t_rainyear | total traditional gauge rainfall this year |
totalRain | t_raintotal | total traditional gauge rainfall |
Users who have a traditional rainfall gauge only should see no difference and need do nothing unless a custom field map that involves rainfall related fields is being used. If a custom field map is being used it will need to be adjusted to use the new internal 't_' field names.
Users who have a piezo rainfall gauge will need to create a custom field map to map the internal piezo rainfall fields to the 'standard' WeeWX fields otherwise the piezo rainfall data will be mapped by the default field map and appear in WeeWX fields with a 'p_' prefix (as shown above). The easiest way to create a custom field map for the piezo rain is to add entries under the [GW1000] field_map_extensions stanza. A suitable custom field map to map piezo rain to the 'standard' WeeWX rainfall fields may look something like:
[[field_map_extensions]]
rain = p_rain
stormRain = rainevent
rainRate = p_rainrate
dayRain = p_rainday
weekRain = p_rainweek
monthRain = p_rainmonth
yearRain = p_rainyear
Under the default field mapping users who have both traditional and piezo rainfall gauges will see the traditional rainfall gauge data mapped to the 'standard' WeeWX rainfall fields and the piezo rainfall data mapped to WeeWX fields with the 'p_' prefix (as detailed above). If the user wishes to map the piezo rainfall data to the 'standard' WeeWX rainfall fields then a custom field map will be required. If the traditional rainfall data is also to be mapped to WeeWX fields the piezo custom field mapping will then cause to be mapped the will need to decide which traditional and piezo internal rainfall fields are to be mapped to which WeeWX rainfall fields and create a suitable custom field map. The default field mapping will see the traditional rainfall gauge data mapped to the 'standard' WeeWX rainfall related fields (as shown above) and the piezo rainfall gauge data will be mapped through to WeeWX field with the 'p_' prefix This may involve identify existing unused WeeWX fields for the second set of rainfall data or it may involve creating new WeeWX fields for the second set of rainfall data. If the second set of rainfall data is to be stored to database then the WeeWX fields used to store the second set of rainfall data may need to be added to the WeeWX database. A suitable field map may look something like:
[[field_map_extensions]]
rain = p_rain
stormRain = rainevent
rainRate = p_rainrate
dayRain = p_rainday
weekRain = p_rainweek
monthRain = p_rainmonth
yearRain = p_rainyear
The Ecowitt LAN/Wi-Fi Gateway API does not yet give access to the xxx setting used in the Ecowitt WSView Plus app to determine whether piezo rain gauge data or traditional rain gauge data is uploaded as station rain data to external services. Accordingly, users with the user must manually configure which rain data will be used
This change is largely an internal change and will only a minor impact on users with WN34 soil/liquid temperature sensors. The gateway driver and service default field map continues to map temperature data for WN34 channels 1 to 8 (gateway device internal fields temp9
to temp16
) to WeeWX fields extraTemp9
to extraTemp16
respectively. Users will notice no change in the mapping of WN34 temperature data.
Earlier versions of the gateway driver did not provide WN34 battery and signal state data. As of v0.5.0b2 WN34 battery and signal data is now mapped to WeeWX fields wn34_chx_batt
and wn34_chx_sig
where x
is the WH34 channel number on the gateway device being used.
WN34 users will notice a slight change in the console output of some options when running the driver directly. Users will notice that the output now correctly refers to WN34 sensors rather than the previous WH34.
This change will only affect users who have WN35 leaf wetness sensors. As with the WN34 sensor redesignation this change is also largely internal, however, some users may need to adjust the mapping of WN35 battery and signal state data. No change will be required to leaf wetness data fields as the mapping fields used are independent of the sensor name.
WN35 battery and signal data will now be mapped to WeeWX fields wn35_chx_batt
and wn35_chx_sig
(where x
is the WN35 channel number on the gateway device being used) wheareas previously it was mapped to fields wh35_chx_batt
and wh35_chx_sig
. Users who were previously using the 'wh35' fields have a number of options:
- If the WN35 battery and signal state data was being saved to database then the user will need to either rename the database fields, create new database fields or alter the device field map (via one or more field_map_exensions settings) for this data to continue to be saved to database.
- If the WN35 battery and signal state data was not being saved to database but only the current data was used (eg using a
$current.wh35_chx_batt
or$current,wh35_chx_sig
tag in a WeeWX report) then chnages will need to be made to the report tags or the device field map will need alteration (via one or more field_map_exensions settings) if the WN35 battery and singal state data is to continue to be used in the report. - If the WN35 battery and signal state data was not beign used then then the user need do nothing.
may choose to (where x
is the WN35 channel number on the gateway device being used) and is default mapped to WeeWX fields of the same name.
V0.4.2 changes have no impact on users.
V0.4.1 changes have no impact on users.
V0.4.0 changes are minor and should have minimal impact on users. Keys changes are summarised below.
The GW1000 driver can now distinguish between GW1000 and GW1100 devices. Whilst both devices utilise the same API, some driver output will now display GW1000 or GW1100 rather than only GW1000. This relates mainly to log output and when running the driver directly, so most users should not have an issue. When run as a driver the tag $station.hardware
can be used in Cheetah report templates to display the correct device model.
Battery state data is now set to None
for sensors with a signal level of 0 (the previous behaviour was to decode and display whatever the GW1000 returned irrespective of signal level). This behaviour can be disabled by setting option show_all_batt = True
under [GW1000]
in weewx.conf
or by use of the --show-all-batt
command line option if running the driver directly. Those users that display or otherwise use battery state level data in Cheetah templates or other services etc may be affected by this change.
V0.3.1 changes were bug fixes only and v0.3.1 fully backwards compatible. There should be no affect on users
The main changes in v0.3.0 were introduction of support for the WH35 (as per API documentation)/WN35 (hardware model as released) leaf wetness sensor and the inclusion of the GW1000 lightningcount
in emitted loop packets. This release also included a number of bug fixes and improvements that are backwards compatible and should have no impact on users.
API documentation release v1.6.0 included support for up to eight WH35 leaf wetness sensors. Support for the WH35 leaf wetness sensor is believed to have been introduced in GW1000 firmware release v1.5.6. Support for up to eight leaf wetness sensors has been included in the GW1000 driver v0.3.0 with the default field map changed to map the output of the eight leaf wetness sensors to WeeWX fields leafWet1
to leafWet8
inclusive.
Historical Note: Before public release of the leaf wetness sensor the GW1000 API documentation referred to the leaf wetness sensor as WH35. Consequently, the GW1000 driver v0.3.0 refers to the leaf wetness sensor as WH35 and relevant sensor battery and signal state fields appear as wh35_chx_batt
and wh35_chx_sig
respectively (the leaf wetness sensor output is mapped to WeeWX fields leafWetx
so users who have one or more leaf wetness sensors will see no mention of WH35 in the leaf wetness data appearing in loop packets). Later, when the leaf wetness sensor was publicly released it was designated WN35 not WH35. This anomaly has been corrected in the GW1000 driver v0.4.2.
The decoding of sensor ID, battery state and signal level data was revised as per changes introduced in API documentation v1.6.0 and GW1000 firmware v1.6.5. This should be an internal GW1000 change only that does not affect users; however, any users noticing any battery state or signal level data discrepancies are asked to highlight these by raising an issue in the GW1000 driver GitHub repo or by posting to weewx-user.
Previously the daily cumulative lightning strike count field from the GW1000, lightningcount
, was used to derive the lightning_strike_count
field and the lightningcount
field was then discarded and not included in the emited loop packet. The lightningcount
field is still used to derive the lightning_strike_count
field but lightningcount
is now retained and included in the emitted loop packet.
Various new features were introduced and changes made in the GW1000 driver v0.2.0 release that may affect users. These changes and their impact on users are detailed below.
Support was added for the WH45 Air Quality Sensor with PM10, CO2 and additional PM2.5, temperature and humidity fields included in the GW1000 driver output. Also included are corresponding battery and sensor signal state fields.
Sensor signal level data for registered sensors is now included in loop packets. Loop packet field names generally use the following format:
sensor designator code_optional channel number_sig
for example:
wh31_ch1_sig
wh57_sig
Refer to the Field map wiki entry for a complete list of available sensor signal level field names.
To align with the field name formats already in use within WeeWX it was necessary to alter the WeeWX field names used in the default mapping of PM2.5 24 hour average particulate concentration data. To keep a similar naming convention within the GW1000 driver the corresponding GW1000 internal PM2.5 24 hour average particulate concentration field names were also altered. These changes may impact users who have WH41, WH43 or WH45 sensors and (1) save or display PM2.5 24 hour average data obtained from the GW1000 driver or (2) have altered the field map to map PM2.5 24 hour average particulate concentration data to another field or (3) modified their WeeWX database schema to store 24 hour average particulate concentration data. Affected users will need to make one or more changes to continue operating as before. Details of the changes required are provided in the Changes to 24 hour average particulate concentration field names wiki entry.
A number of new command line options have been introduced for when running the driver directly. These new options interrogate the GW1000 and present the current state of various GW1000 configuration options on screen. These new options will have no impact when the GW1000 driver is used as a WeeWX driver or service. The new options are:
-
--get-pm25-offset
. Used to display GW1000 PM2.5 sensor offset settings -
--get-services
. Used to display GW1000 supported weather services settings. -
--get-mulch-offset
. Used to display GW1000 multi-channel temperature-humidity sensor calibration settings. -
--get-soil-calibration
. Used to display GW1000 soil moisture sensor calibration settings. -
--get-calibration
. Used to display GW1000 sensor calibration settings.
The --rain-data
command line option has been renamed to --get-rain-data
. This option can only be used when running the GW1000 driver directly and the change will have no impact when the GW1000 driver is used as a WeeWX driver or service.