Skip to content

Field map

gjr80 edited this page Jul 31, 2024 · 19 revisions

Mapping fields

The Ecowitt gateway driver uses a field map to map gateway device data to WeeWX field names. By manipulating the field map the user can control what gateway device data is placed in what WeeWX field. When coupled with managing the WeeWX database schema, the user can control what gateway device data is saved to the WeeWX database.

The default field map

The Ecowitt gateway driver includes a default field map that provides the default mapping of gateway device data to WeeWX fields. The following methodology was used in developing the default field map:

  • Gateway device data is mapped to fields in the WeeWX wview_extended schema where there is a direct equivalent or a reasonable equivalent. For example, the gateway device indoor humidity data is mapped to the WeeWX field inHumidity.
  • If there is no suitable field in the WeeWX wview_extended schema, gateway device data is mapped to fields in weewx.units.obs_group_dict where there is a direct or reasonable equivalent. For example, the gateway device year to date rainfall data is mapped to the WeeWX field yearRain.
  • For 'indexed' WeeWX fields such as extraTemp1 to extraTemp8 the index sequence was extended if the Ecowitt gateway device could provide additional indexed fields of the same name. For example, the Ecowitt gateway driver supports up to 17 additional temperature sensors on field extraTemp1 to extraTemp17.
  • If there is no suitable field in the WeeWX wview_extended schema or the weewx.units.obs_group_dict or if there was a need to avoid ambiguous WeeWX field names, gateway device data is mapped to a descriptive field name. For example, the gateway device 24-hour average CO2 concentration data is mapped to the WeeWX field co2_24h_avg.

The default field map used in the current Ecowitt gateway driver release can be found in tabular form at the bottom of this page. It can also be viewed by running the Ecowitt gateway driver directly with the --default-map command line option.

The default field map contains a mapping for all possible data elements the Ecowitt gateway driver might emit; however, only those gateway device data elements reported by the gateway device will be mapped to WeeWX fields. For example, a GW1000/GW1100 or GW2000 device by itself with no additional sensors will result in the WeeWX loop packet containing only inTemp, inHumidity and pressure1.

1 In reality the WeeWX loop packet will contain fields dateTime and usUnits and perhaps other derived values but the only gateway device fields will be inTemp, inHumidity and pressure.

Altering the field map

There are two means by which the user can alter the field map. The first is by defining a new field map through a [[field_map]] stanza under [GW1000] in weewx.conf. The second method is by altering the existing field map through a [[field_map_extensions]] stanza under [GW1000] in weewx.conf.

Note: If a [[field_map]] stanza is defined this field map will be used in place of the default field map. Whereas a [[field_map_extensions]] stanza extends or amends the default field map.

Note: Modifying the default field map through modification of the Ecowitt gateway driver Python code is not recommended as such changes will be lost when upgrading the Ecowitt gateway driver.

Defining a new field map

A new field map may be defined by including a [[field_map]] stanza with one or more entries under [GW1000] in weewx.conf. The format of the [[field_map]] stanza entries is as follows:

[[field_map]]
    weewx_field_name = ecowitt_field_name

Where ecowitt_field_name is the internal Ecowitt gateway driver field name to be mapped and weewx_field_name is the WeeWX field the Ecowitt data is to be mapped to. In other words, after mapping the data in ecowitt_field_name will appear in the loop packet field weewx_field_name. For example, to map the temperature data from the first WH31 external temperature sensor to the WeeWX field poolTemp the following entry would be used:

[[field_map]]
    poolTemp = temp1

Rules when defining a new field map. When a field map is defined with a [[field_map]] stanza there are a number of 'rules' that are applied by the Ecowitt gateway driver. These include:

  • The mapping defined by the [[field_map]] stanza will replace the default field in its entirety. Consequently, the only Ecowitt data that will be mapped will be that which is included in the [[field_map]] stanza even if other Ecowitt data is available.
  • The WeeWX field name need not exist in the database schema, the mapping merely places Ecowitt data in a field in the loop packet emitted by the driver.
  • By default, any WeeWX fields defined in the [[field_map]] stanza will also appear in the WeeWX generated archive record. This is a function of the WeeWX engine and is beyond the control of the Ecowitt gateway driver.
  • extractors
Modifying the default field map

A new in cases where the user wishes to change the mapping of a small number of fields but retain the other field map entries it may be simpler to modify the existing field map with a [[field_map_extensions]] stanza than it is to define an entire field map using a [[field_map]] stanza. A [[field_map_extensions]] stanza adds or amends entries in the existing field map.

The format of the [[field_map_extensions]] stanza entries is the same as for the [[field_map]] stanza:

[[field_map_extensions]]
    weewx_field_name = ecowitt_field_name

Where ecowitt_field_name is the internal Ecowitt gateway driver field name to be mapped and weewx_field_name is the WeeWX field the Ecowitt data is to be mapped to. In other words, after mapping the data in ecowitt_field_name will appear in the loop packet field weewx_field_name. For example, to map the temperature data from the first WH31 external temperature sensor to the WeeWX field poolTemp the following entry would be used:

[[field_map_extensions]]
    poolTemp = temp1

Rules when defining a field map extension. When a field map extension is defined with a [[field_map_extensions]] stanza there are a number of 'rules' that are applied by the Ecowitt gateway driver. Most of these rules are the same as for defining a new field map but some are subtly different. The rules are:

  • The mapping defined by the [[field_map_extensions]] stanza will be used to modify the existing field map (usually the default field map). Newly defined mappings will be added to the current field map and modified mappings will be used to update the current field map.
  • Ecowitt internal fields may only be mapped to one WeeWX field. If an Ecowitt internal field is already mapped to a WeeWX field and the same Ecowitt is used in a [[field_map_extensions]] entry the original mapping is deleted and replaced by the [[field_map_extensions]] entry.

Note: If the data from an Ecowitt internal field is required in more than one WeeWX field this can be achieved by placing one or more appropriate entries under [StdCalibration] [[Corrections]] in weewx.conf

  • The WeeWX field name need not exist in the database schema, the mapping merely places Ecowitt data in a field in the loop packet emitted by the driver.
  • By default, any WeeWX fields defined in the [[field_map_extensions]] stanza will also appear in the WeeWX generated archive record. This is a function of the WeeWX engine and is beyond the control of the Ecowitt gateway driver.
  • extractors
Extractors

When WeeWX synthesises an archive record from accumulated loop packet data a function is applied to the accumulated loop data for each field to give the resulting this function is known as the extractor function. The default extractor function is average, which results in the archive record value for a given field being the average of the accumulated loop packet value for that field. Other extractor functions include sum, max, min, first, last and noop. being the average of all of the , the function used to extract the archive record value for a given field

Tabulated default field map

The following table summarises the default field map as implemented in the Ecowitt gateway driver v0.6.3. The table is ordered alphabetically by WeeWX field name.

WeeWX field name Gateway device field name Description
co2 co2 WH45/WH46 CO2. Note 3.
co2_24h_avg co2_24h_avg WH45/WH46 24 hour average CO2. Note 3.
dateTime datetime Epoch timestamp
daymaxwind daymaxwind Maximum wind speed today
dayRain t_rainday Total traditional gauge rainfall today
dewpoint dewpoint Dew point
extraHumid1 humid1 WH31 channel 1 humidity
extraHumid2 humid2 WH31 channel 2 humidity
extraHumid3 humid3 WH31 channel 3 humidity
extraHumid4 humid4 WH31 channel 4 humidity
extraHumid5 humid5 WH31 channel 5 humidity
extraHumid6 humid6 WH31 channel 6 humidity
extraHumid7 humid7 WH31 channel 7 humidity
extraHumid8 humid8 WH31 channel 8 humidity
extraHumid17 humid17 WH45/WH46 humidity. Note 3.
extraTemp1 temp1 WH31 channel 1 temperature
extraTemp2 temp2 WH31 channel 2 temperature
extraTemp3 temp3 WH31 channel 3 temperature
extraTemp4 temp4 WH31 channel 4 temperature
extraTemp5 temp5 WH31 channel 5 temperature
extraTemp6 temp6 WH31 channel 6 temperature
extraTemp7 temp7 WH31 channel 7 temperature
extraTemp8 temp8 WH31 channel 8 temperature
extraTemp9 temp9 WN34 channel 1 temperature
extraTemp10 temp10 WN34 channel 2 temperature
extraTemp11 temp11 WN34 channel 3 temperature
extraTemp12 temp12 WN34 channel 4 temperature
extraTemp13 temp13 WN34 channel 5 temperature
extraTemp14 temp14 WN34 channel 6 temperature
extraTemp15 temp15 WN34 channel 7 temperature
extraTemp16 temp16 WN34 channel 8 temperature
extraTemp17 temp17 WH45/WH46 temperature. Note 3.
heap_free heap_free free heap memory
heatindex heatindex heat index
inHumidity inhumid inside humidity
inTemp intemp inside temperature
leafWet1 leafwet1 WN35 channel 1
leafWet2 leafwet2 WN35 channel 2
leafWet3 leafwet3 WN35 channel 3
leafWet4 leafwet4 WN35 channel 4
leafWet5 leafwet5 WN35 channel 5
leafWet6 leafwet6 WN35 channel 6
leafWet7 leafwet7 WN35 channel 7
leafWet8 leafwet8 WN35 channel 8
leak1 leak1 WH55 channel 1
leak2 leak2 WH55 channel 2
leak3 leak3 WH55 channel 3
leak4 leak4 WH55 channel 4
lightning_distance lightningdist distance to last lightning strike
lightning_last_det_time lightningdettime Epoch timestamp of last lightning strike
lightning_strike_count lightning_strike_count total lightning strike count this period
lightningcount lightningcount cumulative lightning strike count
luminosity light luminosity
monthRain t_rainmonth total traditional gauge rainfall this month
outHumidity outhumid outside humidity
outTemp outtemp outside temperature
p_dayRain p_rainday total piezo gauge rainfall today
p_monthRain p_rainmonth total piezo gauge rainfall this month
p_rain p_rain total piezo gauge rainfall this period
p_rainRate p_rainrate piezo gauge rain rate
p_stormRain p_rainevent total piezo gauge rainfall this rain event
p_weekRain p_rainweek total piezo gauge rainfall this week
p_yearRain p_rainyear total piezo gauge rainfall this year
pm1_0 pm1 WH46 PM1
pm2_5 pm251 WH41/WH43 channel 1 PM2.5
pm2_52 pm252 WH41/WH43 channel 2 PM2.5
pm2_53 pm253 WH41/WH43 channel 3 PM2.5
pm2_54 pm254 WH41/WH43 channel 4 PM2.5
pm2_55 pm255 WH45/WH46 PM2.5. Note 3.
pm4_0 pm4 WH46 PM4
pm2_51_24h_avg pm251_24h_avg WH41/WH43 channel 1 24 hour average PM2.5
pm2_52_24h_avg pm252_24h_avg WH41/WH43 channel 2 24 hour average PM2.5
pm2_53_24h_avg pm253_24h_avg WH41/WH43 channel 3 24 hour average PM2.5
pm2_54_24h_avg pm254_24h_avg WH41/WH43 channel 4 24 hour average PM2.5
pm2_55_24h_avg pm255_24h_avg WH45/WH46 24 hour average PM2.5. Note 3.
pm10_0 pm10 WH45/WH46 PM10. Note 3.
pm10_24h_avg pm10_24h_avg WH45/WH46 24 hour average PM10. Note 3.
pressure absbarometer absolute or station pressure
rain t_rain total traditional gauge rainfall this period
rainRate t_rainrate traditional gauge rain rate
relbarometer relbarometer relative pressure
soilMoist1 soilmoist1 WH51 channel 1 soil moisture
soilMoist2 soilmoist2 WH51 channel 2 soil moisture
soilMoist3 soilmoist3 WH51 channel 3 soil moisture
soilMoist4 soilmoist4 WH51 channel 4 soil moisture
soilMoist5 soilmoist5 WH51 channel 5 soil moisture
soilMoist6 soilmoist6 WH51 channel 6 soil moisture
soilMoist7 soilmoist7 WH51 channel 7 soil moisture
soilMoist8 soilmoist8 WH51 channel 8 soil moisture
soilMoist9 soilmoist9 WH51 channel 9 soil moisture. Note 2.
soilMoist10 soilmoist10 WH51 channel 10 soil moisture. Note 2.
soilMoist11 soilmoist11 WH51 channel 11 soil moisture. Note 2.
soilMoist12 soilmoist12 WH51 channel 12 soil moisture. Note 2.
soilMoist13 soilmoist13 WH51 channel 13 soil moisture. Note 2.
soilMoist14 soilmoist14 WH51 channel 14 soil moisture. Note 2.
soilMoist15 soilmoist15 WH51 channel 15 soil moisture. Note 2.
soilMoist16 soilmoist16 WH51 channel 16 soil moisture. Note 2.
soilTemp1 soiltemp1 Note 1
soilTemp2 soiltemp2 Note 1
soilTemp3 soiltemp3 Note 1
soilTemp4 soiltemp4 Note 1
soilTemp5 soiltemp5 Note 1
soilTemp6 soiltemp6 Note 1
soilTemp7 soiltemp7 Note 1
soilTemp8 soiltemp8 Note 1
soilTemp9 soiltemp9 Note 1
soilTemp10 soiltemp10 Note 1
soilTemp11 soiltemp11 Note 1
soilTemp12 soiltemp12 Note 1
soilTemp13 soiltemp13 Note 1
soilTemp14 soiltemp14 Note 1
soilTemp15 soiltemp15 Note 1
soilTemp16 soiltemp16 Note 1
stormRain t_rainevent total traditional gauge rainfall this rain event
totalRain t_raintotals total traditional gauge rainfall recorded
UV uvi UV index
uvradiation uv UV radiation
weekRain t_rainweek total traditional gauge rainfall this week
wh24_batt wh24_batt WH24 battery level
wh24_sig wh24_sig WH24 signal level
wh25_batt wh25_batt WH25 battery level
wh25_sig wh25_sig WH25 signal level
wh26_batt wh26_batt WH26 battery level
wh26_sig wh26_sig WH26 signal level
wh31_ch1_batt wh31_ch1_batt WH31 channel 1 battery level
wh31_ch1_sig wh31_ch1_sig WH31 channel 1 signal level
wh31_ch2_batt wh31_ch2_batt WH31 channel 2 battery level
wh31_ch2_sig wh31_ch2_sig WH31 channel 2 signal level
wh31_ch3_batt wh31_ch3_batt WH31 channel 3 battery level
wh31_ch3_sig wh31_ch3_sig WH31 channel 3 signal level
wh31_ch4_batt wh31_ch4_batt WH31 channel 4 battery level
wh31_ch4_sig wh31_ch4_sig WH31 channel 4 signal level
wh31_ch5_batt wh31_ch5_batt WH31 channel 5 battery level
wh31_ch5_sig wh31_ch5_sig WH31 channel 5 signal level
wh31_ch6_batt wh31_ch6_batt WH31 channel 6 battery level
wh31_ch6_sig wh31_ch6_sig WH31 channel 6 signal level
wh31_ch7_batt wh31_ch7_batt WH31 channel 7 battery level
wh31_ch7_sig wh31_ch7_sig WH31 channel 7 signal level
wh31_ch8_batt wh31_ch8_batt WH31 channel 8 battery level
wh31_ch8_sig wh31_ch8_sig WH31 channel 9 signal level
wh32_batt wh32_batt WH32 battery level
wh32_sig wh32_sig WH32 signal level
wh40_batt wh40_batt WH40 battery level
wh40_sig wh40_sig WH40 signal level
wh41_ch1_batt wh41_ch1_batt WH41/WH43 channel 1 battery level
wh41_ch1_sig wh41_ch1_sig WH41/WH43 channel 1 signal level
wh41_ch2_batt wh41_ch2_batt WH41/WH43 channel 2 battery level
wh41_ch2_sig wh41_ch2_sig WH41/WH43 channel 2 signal level
wh41_ch3_batt wh41_ch3_batt WH41/WH43 channel 3 battery level
wh41_ch3_sig wh41_ch3_sig WH41/WH43 channel 3 signal level
wh41_ch4_batt wh41_ch4_batt WH41/WH43 channel 4 battery level
wh41_ch4_sig wh41_ch4_sig WH41/WH43 channel 4 signal level
wh45_batt wh45_batt WH45 battery level
wh45_sig wh45_sig WH45 signal level
wh46_batt wh46_batt WH46 battery level
wh46_sig wh46_sig WH46 signal level
wh51_ch1_batt wh51_ch1_batt WH51 channel 1 battery level
wh51_ch1_sig wh51_ch1_sig WH51 channel 1 signal level
wh51_ch2_batt wh51_ch2_batt WH51 channel 2 battery level
wh51_ch2_sig wh51_ch2_sig WH51 channel 2 signal level
wh51_ch3_batt wh51_ch3_batt WH51 channel 3 battery level
wh51_ch3_sig wh51_ch3_sig WH51 channel 3 signal level
wh51_ch4_batt wh51_ch4_batt WH51 channel 4 battery level
wh51_ch4_sig wh51_ch4_sig WH51 channel 4 signal level
wh51_ch5_batt wh51_ch5_batt WH51 channel 5 battery level
wh51_ch5_sig wh51_ch5_sig WH51 channel 5 signal level
wh51_ch6_batt wh51_ch6_batt WH51 channel 6 battery level
wh51_ch6_sig wh51_ch6_sig WH51 channel 6 signal level
wh51_ch7_batt wh51_ch7_batt WH51 channel 7 battery level
wh51_ch7_sig wh51_ch7_sig WH51 channel 7 signal level
wh51_ch8_batt wh51_ch8_batt WH51 channel 8 battery level
wh51_ch8_sig wh51_ch8_sig WH51 channel 8 signal level
wh51_ch9_batt wh51_ch9_batt WH51 channel 9 battery level. Note 2
wh51_ch9_sig wh51_ch9_sig WH51 channel 9 signal level. Note 2
wh51_ch10_batt wh51_ch10_batt WH51 channel 10 battery level. Note 2
wh51_ch10_sig wh51_ch10_sig WH51 channel 10 signal level. Note 2
wh51_ch11_batt wh51_ch11_batt WH51 channel 11 battery level. Note 2
wh51_ch11_sig wh51_ch11_sig WH51 channel 11 signal level. Note 2
wh51_ch12_batt wh51_ch12_batt WH51 channel 12 battery level. Note 2
wh51_ch12_sig wh51_ch12_sig WH51 channel 12 signal level. Note 2
wh51_ch13_batt wh51_ch13_batt WH51 channel 13 battery level. Note 2
wh51_ch13_sig wh51_ch13_sig WH51 channel 13 signal level. Note 2
wh51_ch14_batt wh51_ch14_batt WH51 channel 14 battery level. Note 2
wh51_ch14_sig wh51_ch14_sig WH51 channel 14 signal level. Note 2
wh51_ch15_batt wh51_ch15_batt WH51 channel 15 battery level. Note 2
wh51_ch15_sig wh51_ch15_sig WH51 channel 15 signal level. Note 2
wh51_ch16_batt wh51_ch16_batt WH51 channel 16 battery level. Note 2
wh51_ch16_sig wh51_ch16_sig WH51 channel 16 signal level. Note 2
wh55_ch1_batt wh55_ch1_batt WH55 channel 1 battery level
wh55_ch1_sig wh55_ch1_sig WH55 channel 1 signal level
wh55_ch2_batt wh55_ch2_batt WH55 channel 2 battery level
wh55_ch2_sig wh55_ch2_sig WH55 channel 2 signal level
wh55_ch3_batt wh55_ch3_batt WH55 channel 3 battery level
wh55_ch3_sig wh55_ch3_sig WH55 channel 3 signal level
wh55_ch4_batt wh55_ch4_batt WH55 channel 4 battery level
wh55_ch4_sig wh55_ch4_sig WH55 channel 4 signal level
wh57_batt wh57_batt WH57 battery level
wh57_sig wh57_sig WH57 signal level
wh65_batt wh65_batt WH65 battery level
wh65_sig wh65_sig WH65 signal level
wh68_batt wh68_batt WH68 battery voltage
wh68_sig wh68_sig WH68 signal level
windchill windchill wind chill
windDir winddir wind direction
windGust gustspeed wind gust speed
windSpeed windspeed wind speed
wn34_ch1_batt wn34_ch1_batt WN34 channel 1 battery level
wn34_ch1_sig wn34_ch1_sig WN34 channel 1 signal level
wn34_ch2_batt wn34_ch2_batt WN34 channel 2 battery level
wn34_ch2_sig wn34_ch2_sig WN34 channel 2 signal level
wn34_ch3_batt wn34_ch3_batt WN34 channel 3 battery level
wn34_ch3_sig wn34_ch3_sig WN34 channel 3 signal level
wn34_ch4_batt wn34_ch4_batt WN34 channel 4 battery level
wn34_ch4_sig wn34_ch4_sig WN34 channel 4 signal level
wn34_ch5_batt wn34_ch5_batt WN34 channel 5 battery level
wn34_ch5_sig wn34_ch5_sig WN34 channel 5 signal level
wn34_ch6_batt wn34_ch6_batt WN34 channel 6 battery level
wn34_ch6_sig wn34_ch6_sig WN34 channel 6 signal level
wn34_ch7_batt wn34_ch7_batt WN34 channel 7 battery level
wn34_ch7_sig wn34_ch7_sig WN34 channel 7 signal level
wn34_ch8_batt wn34_ch8_batt WN34 channel 8 battery level
wn34_ch8_sig wn34_ch8_sig WN34 channel 9 signal level
wn35_ch1_batt wn35_ch1_batt WN35 channel 1 battery level
wn35_ch1_sig wn35_ch1_sig WN35 channel 1 signal level
wn35_ch2_batt wn35_ch2_batt WN35 channel 2 battery level
wn35_ch2_sig wn35_ch2_sig WN35 channel 2 signal level
wn35_ch3_batt wn35_ch3_batt WN35 channel 3 battery level
wn35_ch3_sig wn35_ch3_sig WN35 channel 3 signal level
wn35_ch4_batt wn35_ch4_batt WN35 channel 4 battery level
wn35_ch4_sig wn35_ch4_sig WN35 channel 4 signal level
wn35_ch5_batt wn35_ch5_batt WN35 channel 5 battery level
wn35_ch5_sig wn35_ch5_sig WN35 channel 5 signal level
wn35_ch6_batt wn35_ch6_batt WN35 channel 6 battery level
wn35_ch6_sig wn35_ch6_sig WN35 channel 6 signal level
wn35_ch7_batt wn35_ch7_batt WN35 channel 7 battery level
wn35_ch7_sig wn35_ch7_sig WN35 channel 7 signal level
wn35_ch8_batt wn35_ch8_batt WN35 channel 8 battery level
wn35_ch8_sig wn35_ch8_sig WN35 channel 9 signal level
ws80_batt ws80_batt WS80 battery voltage
ws80_sig ws80_sig WS80 signal level
ws90_batt ws90_batt WS90 battery voltage
ws90_sig ws90_sig WS90 signal level
yearRain t_rainyear total traditional gauge rainfall this year

Notes:

  1. Supported by the API but not yet supported by WSView Plus app or a sensor.
  2. API supports 16 soil moisture sensors but WSView Plus app appears to support only eight soil moisture sensors.
  3. API supports one WH45 or one WH46 but not both simultaneously, field contains data from whichever model sensor is connected.