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 the significant changes 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.
weectl extension may be used to upgrade an existing Ecowitt Gateway driver extension installation irrespective of whether the Ecowitt Gateway driver extension was installed manually, using the legacy extension installer wee_extension or weectl extension. To use weectl extension to upgrade an existing Ecowitt Gateway driver extension installation:
-
Install the latest version of the Ecowitt Gateway driver using the weectl utility.
Note: The exact command syntax to invoke weectl on your system will depend on the installer used to install WeeWX. Refer to Installation methods in the WeeWX User's Guide.
For WeeWX package installs:
weectl extension install https://github.com/gjr80/weewx-gw1000/releases/latest/download/gw1000.zipFor WeeWX pip installs the Python virtual environment must be activated before the extension is installed:
source ~/weewx-venv/bin/activate weectl extension install https://github.com/gjr80/weewx-gw1000/releases/latest/download/gw1000.zipFor WeeWX installs from git the Python virtual environment must be activated before the extension is installed:
source ~/weewx-venv/bin/activate python3 ~/weewx/src/weectl.py extension install https://github.com/gjr80/weewx-gw1000/releases/latest/download/gw1000.zip -
Make any necessary changes to WeeWX, in particular weewx.conf, based on the relevant portions of the Instructions for specific versions section.
-
You may test the upgraded Ecowitt Gateway driver without interfering with an existing running WeeWX instance by running the driver file directly using the
--test-drivercommand line option:For WeeWX package installs use:
PYTHONPATH=/usr/share/weewx python3 /etc/weewx/bin/usergw1000.py --test-driver --ip-address=device_ip_addresswhere device_ip_address is the IP address of the gateway device being used.
For WeeWX pip installs the Python virtual environment must be activated before the driver is invoked:
source ~/weewx-venv/bin/activate python3 ~/weewx-data/bin/user/gw1000.py --test-driver --ip-address=device_ip_addresswhere device_ip_address is the IP address of the gateway device being used.
For WeeWX installs from git the Python virtual environment must be activated before the driver is invoked using the path to the local WeeWX git clone:
source ~/weewx-venv/bin/activate PYTHONPATH=~/weewx/src python3 ~/weewx-data/bin/user/gw1000.py --test-driver --ip-address=device_ip_addresswhere device_ip_address is the IP address of the gateway device being used.
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 not from WeeWX, but rather directly from the driver.
-
Restart the WeeWX daemon:
sudo /etc/init.d/weewx restartor
sudo service weewx restartor
sudo systemctl start reweewx
V0.6.0 changes have no impact on existing users.
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 internal driver fields to support rainfall data from the WS90 piezoelectric rainfall gauge. The new internal piezo rainfall gauge 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 the GW1000 driver 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 |
Note: The Ecowitt LAN/Wi-Fi Gateway API does not currently support hour total rainfall and total rainfall fields for the piezo rainfall gauge data as it does for traditional rainfall gauge data.
Users who have a traditional rainfall gauge only should see no difference and need do nothing unless a custom field map involving 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_' rainfall field names.
Users with a piezo rainfall gauge and using the default field map will see the piezo rainfall data appear in WeeWX 'p_' fields as per the above table. It is likely that most users will instead want the piezo rain data to appear in the 'standard' WeeWX rainfall fields which will entail using a custom field map. The easiest way to create a custom field map for the piezo rain is to add suitable 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 = p_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 per the above table. The user may wish to change this mapping, perhaps to map the piezo rainfall gauge data to the 'standard' WeeWX rainfall fields and the traditional rainfall gauge data to a separate set of WeeWX fields. In such a case a custom field mapping for both the piezo and traditional rainfall gauge data will be required. A suitable custom field map for such a case may look something like:
[[field_map_extensions]]
rain = p_rain
stormRain = p_rainevent
rainRate = p_rainrate
dayRain = p_rainday
weekRain = p_rainweek
monthRain = p_rainmonth
yearRain = p_rainyear
rain2 = t_rain
stormRain2 = t_rainevent
rainRate2 = t_rainrate
hourRain2 = t_rainhour
dayRain2 = t_rainday
weekRain2 = t_rainweek
monthRain2 = t_rainmonth
yearRain2 = t_rainyear
totalRain2 = t_raintotal
Note that if the chosen WeeWX field names are not in the database schema and the user wishes to store the data in the database the fields concerned will need to be added to the database. Refer to Customizing the database in the WeeWX Customization Guide.
Due to differences between the Ecowitt LAN/Wi-Fi Gateway API documentation and the model numbers of the WN34 temperature sensors it has been necessary to replace all references to the WH34 temperature sensor in the Ecowitt Gateway driver with the WN34 temperature sensor. This change is an internal change only and will have no impact on 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.0 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.
Further information on changes to support for WN34/WH34 sensors introduced in the Ecowitt Gateway driver v0.5.0 are provided in the Changes to support for WN34 sensors wiki page.
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) whereas 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_extensions]]entries) 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_battor$current.wh35_chx_sigtag in a WeeWX report) then changes will need to be made to the report tags or the device field map will need alteration (via one or more[[field_map_extensions]]settings) if the WN35 battery and signal state data is to continue to be used in the report. - If the WN35 battery and signal state data was not being used the user need do nothing.
Previously battery and signal state data for WH32 sensors was reported as wh26_batt and wh26_sig. Likewise, the WH32 was reported as a WH26 device in the output when the Ecowitt Gateway driver was run directly with the --sensors command line option. A wh32 config option has been introduced (refer to Available Config Options) to allow the user to set whether the outdoor temperature and humidity sensor is a WH32 (or variant) or not. If the wh32 option is set to True (the default) WH32 battery and signal state data will appear as wh32_batt and wh32_sig respectively and the WH32 sensor will be correctly labelled in the --sensors output.
Users who do not use the wh26_batt and wh26_sig fields will not be affcted by this change but this change may present a problem for users who may have used the wh26_batt and wh26_sig fields elsewhere. The recommended solution is to modify the reports, services or other code that was using the wh26_batt and wh26_sig fields to accept wh32_batt and wh32_sig instead. Users who were storing the wh26_batt and wh26_sig in the database may need to add wh32_batt and wh32_sig fields to the database to continue storing the WH32 battery and signal state data. Another approach is to continue to use wh26_batt and wh26_sig by adding suitable mapping to the [[field_map_extensions]] to map the gateway device internal wh32_batt and wh32_sig fields to the legacy wh26_batt and wh26_sig fields. Such entries might look like:
[[field_map_extensions]]
wh26_batt = wh32_batt
wh26_sig = wh32_sig
Note: Outdoor temperature and humidity observation data is unaffected by this change. Outdoor temperature and humidity observation data has always been correctly displayed by the Ecowitt Gateway driver.
The WH40 and WH51 sensor battery state data is now provided in Volts rather than as a binary value. No changes ae required to the Ecowitt Gateway driver configuration or the WeeWX database. However, depending on how the data is used reports or templates using the WH40 and/or WH51 sensor battery state data may need minor alternation to ensure the data is displayed correctly.
V0.4.2 changes have no impact on existing users.
V0.4.1 changes have no impact on existing users.
V0.4.0 changes are minor and should have minimal impact on existing 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 existing 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 existing 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 existing 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 existing users. These changes and their impact on existing 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 existing 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.