2.10.1 • Published 4 months ago

homebridge-ecowitt-weather-sensors v2.10.1

Weekly downloads
-
License
Apache-2.0
Repository
github
Last release
4 months ago

Homebridge Ecowitt Weather Sensors

verified-by-homebridge Test Status NPM Version NPM Downloads License

:fast_forward: :fast_forward: :fast_forward: Getting Started | Supported Devices | Configuration | FAQs | Contributing :rewind: :rewind: :rewind:

Homebridge support for your Fine Offset weather station (Ecowitt, Ambient, Froggit, GoGen, and more)

This plugin runs a server that can receive data reports from your weather station Wifi Gateway or Display Console. It works with all brands that white-label Fine Offset products including Ecowitt, Ambient, Froggit, GARNI, GoGen, ELV, Misol, Pantech, and Watson.

Features

  • Support for most Fine Offset weather station products
  • Operates locally without the need for any cloud services
  • Detection thresholds for most weather sensor devices to drive automations
  • Customize units, sensor override names, and whether to show or hide a device

Requirements

  • Wifi Gateway or Display Console such as the Ecowitt GW2000 or the Ambient WS4000 (supported devices)
  • For Ecowitt (and most other white-labels), the WSView Plus app (iOS / Android)
  • For Ambient products, the awnet app (iOS / Android)

:warning: This plugin uses a few custom characteristics on HomeKit services which are not visible on the HomeKit app. For full functionality, third-party apps such as Eve, Controller for HomeKit or Home+ are recommended, but not required.

Installation

Search for "Ecowitt" on the Homebridge Config UI X Plugins screen, find homebridge-ecowitt-weather-sensors and select to install.

Getting Started

It is recommended to configure the plugin via the Settings UI.

The plugin's Base Station settings must be configured before configuring the gateway or display console.

MAC Address

This can be found on the About screen on the Weather Display Console, or via the app (WSView Plus or awnet). The MAC address is used to validate that the data report was sent from the correct gateway or display console. If the MAC address is not provided, MAC validation will be disabled meaning that the source MAC of each data report will not be checked. MAC address validation can also be optionally disabled in Advanced settings in the plugin UI.

   

WSView Plus app and awnet app showing MAC Address

Data Report Service

The Port and Path settings configure on which port and path the data report service will listen for data reports coming from the gateway or display console.

Default settings are 8080 for the port and /data/report/ for the path. Other values may be used as desired. Depending on your system or network configuration ensure the Port selected is not already in use and is accessible from the base station.

Plugin UI with Required Configuration Options

Gateway / Display Console Configuration

After configuring the Base Station settings, restart Homebridge and confirm via the status logs that there are no errors and that the data report service has been started and is listening.

Before updating the gateway or display console to report its data to the plugin, ensure all the available devices have been configured and are correctly reporting their data to the base station through the app (WSView Plus or awnet).

The plugin requires the custom weather service to be configured to report data with Path and Port parameters that match the same in the Base Station settings.

:warning: Please double check that the path and port on the custom weather service match the path and port specified on the plugin settings. The plugin will warn you in the logs if it receives a data report on an unexpected path. If there are difficulties with setting the path properly, the accept any path config option in Advanced settings in the plugin UI can be enabled. :warning:

The service Protocol Type must be configured as Ecowitt or Ambient. The Upload Interval can be configured as desired. Anywhere from 20 seconds to 60 seconds is recommended as the data report messages are relatively small and do not put much load on the network or Homebridge host. Keep in mind that the weather sensors transmit data at different rates - anywhere from ~16 seconds to ~80 seconds (depending on the device) so single digit values for the Upload Interval may result in the same repeated data being transmitted from the base station to the plugin.

The gateway or display console can be configured using the app (WSView Plus or awnet). See the screenshots below for the custom weather service upload configuration in each app.

   

WSView Plus app and awnet app showing Custom Weather Service

It is also recommended to configure the Homebridge host system with a static IP address (or DHCP reservation) to avoid issues with Homebridge IP address changing after system reboots.

After the gateway or display console configuration has been updated, there should be Homebridge status logs indicating accessories are discovered after the first data report is received. Please note that the plugin does not log the data report each time a data report is received, but that behavior can be enabled in Advanced settings in the plugin UI.

Supported Devices

This plugin currently supports the devices shown in the tables below, and any equivalent devices from white-label brands. Any device transmitting data using the Ecowitt protocol or Ambient protocol will likely be supported regardless of whether that specific brand / model is mentioned in the table.

All accessories created by this plugin will use the Ecowitt model numbers so for example the Ambient Weather WH31P will show as an Ecowitt WN30. For help translating model numbers across brands, see this guide on Fine Offset clones.

If your gateway, console and/or sensor is currently not supported, please open a feature request.

Gateways and Consoles

EcowittAmbientDescriptionServiceProduct Image
GW1000 / GW1100---Wifi Weather Station GatewayIndoor TemperatureIndoor Humidity
GW1200---Wifi Weather Station GatewayIndoor TemperatureIndoor Humidity
GW2000---Wifi Weather Station GatewayIndoor TemperatureIndoor Humidity
GW3000---Wifi Weather Station GatewayIndoor TemperatureIndoor Humidity
HP2550 (and variants)WS2000 / WS4000 / WS50007" TFT Color Display Consoleuse WN32P for indoor temperature and humidity
HP2560 / HP2561 / HP2564---7" TFT Color Display Console with Indoor Sensor AntennaIndoor TemperatureIndoor Humidity
HP3500 (and variants)WS30004.3" TFT Color Display Consoleuse WN32P for indoor temperature and humidity
WS2320 / WS2350---7" LCD DisplayIndoor TemperatureIndoor Humidity
WS2900 / WS2910WS2902 (A, B, C, and D variants)6.8" Color LCD Display with Touch ButtonsIndoor TemperatureIndoor Humidity
WS3800 / WS3820---7.5" LCD Display with IOT Intelligent Linkage ControlIndoor TemperatureIndoor Humidity
WS3900 / WS3910---7.5" LCD Display with IOT Intelligent Linkage ControlIndoor TemperatureIndoor Humidity indoor carbon dioxide not supported
WN1820 / WN1821---4.9" LCD DisplayIndoor TemperatureIndoor Humidity indoor carbon dioxide not supported
WN1900 / WN1910 / WN1920WS19654.9" LCD DisplayIndoor TemperatureIndoor Humidity
WN1980---5.3" LCD Display with Touch Screen KeysIndoor TemperatureIndoor Humidity

Sensors

EcowittAmbientDescriptionServiceProduct Image
WH25---Indoor Temperature, Humidity and Barometric SensorIndoor TemperatureIndoor HumidityBattery
WH26---Outdoor Temperature and Humidity SensorTemperatureHumidityBattery
WN30WH31PThermometer with ProbeTemperatureBattery
WN31 / WH31 (including S and EP variants)WH31E / WH32M / WH51RFMulti-Channel Temperature and Humidity SensorTemperatureHumidityBattery
WN32 / WH32 (including EP variant)---Outdoor Temperature and Humidity Sensor Note this will register as a WH26TemperatureHumidityBattery
WN32PWH32BIndoor Temperature, Humidity and Barometric Sensor Note this will register as a WH25Indoor TemperatureIndoor HumidityBattery
WN34 (S, D, and L variants)---Multi-Channel Temperature SensorTemperatureBattery
WN35WH51LWLeaf Wetness SensorLeaf WetnessBattery
WN36WH31PFFloating Pool Thermometer Note this will register as a WN30TemperatureBattery
WH40 (including H variant)---Self-Emptying Rain Collector Rainfall SensorRain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly TotalBattery
WH41PM25PM2.5 Air Quality Sensor with Solar PanelPM2.5 Air QualityPM2.5 Air Quality (24hrs)Battery
WH43PM25INPM2.5 Air Quality Sensor Note this will register as a WH41PM2.5 Air QualityPM2.5 Air Quality (24hrs)Battery
WH45AQIN5-in-1 PM2.5 / PM10 / CO₂ Air Quality SensorTemperatureHumidityPM2.5 Air QualityPM2.5 Air Quality (24hrs)PM10 Air QualityPM10 Air Quality (24hrs)CO₂ LevelCO₂ Level (24 hrs)Battery
WH46 (including D variant)---7-in-1 PM1.0 / PM2.5 / PM4.0 / PM10 / CO₂ Air Quality SensorTemperatureHumidityPM2.5 Air QualityPM2.5 Air Quality (24hrs)PM10 Air QualityPM10 Air Quality (24hrs)CO₂ LevelCO₂ Level (24 hrs)Battery
WH51 (and L variant)WH31SMSoil Moisture SensorSoil MoistureBattery
WH55WH31LAWater Leak Detection SensorWater LeakBattery
WH57WH31LLightning Detection SensorLightning EventsLightning DistanceLightning TimeBattery

Sensor Arrays

EcowittAmbientDescriptionServiceProduct Image
WH65 (Y-shape) / WS69 (I-shape)WS2000Solar Powered 7-in-1 Outdoor StationTemperatureHumiditySolar RadiationUV IndexWind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedRain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly TotalBattery
WN67WS19655-in-1 Outdoor StationTemperatureHumidityWind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedRain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly TotalBattery
WS68---Solar Powered 4-in-1 Outdoor StationSolar RadiationUV IndexWind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedBattery
WS80WS5000Solar Powered 6-in-1 Outdoor StationTemperatureHumiditySolar RadiationUV IndexWind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedBattery
WS85---3-in-1 Solar Weather StationWind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedRain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly TotalBattery
WS90WS4000Solar Powered 7-in-1 Outdoor Anti-vibration Haptic Sensor ArrayTemperatureHumiditySolar RadiationUV IndexWind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedRain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly TotalBattery

:warning: This plugin does not currently implement barometric (pressure) services and PM1.0/PM4.0 air quality services. While these are not supported natively by HomeKit as this time, they are planned to be implemented with custom characteristics, see this issue.

Configuration

Basic Configuration

This plugin will work with the basic configuration described in Getting Started. Note that port defaults to 8080 and path defaults to /data/report/. The MAC is only required if you would like MAC address validation on each received data report. As an example -

{
    "platform": "Ecowitt",
    "baseStation": {
        "mac": "30:C9:22:3E:DD:2B",
        "port": 8080,
        "path": "/data/report/"
    }
}

All Configuration

It's recommended to configure the plugin through the Plugin Config UI on the Homebridge UI. Checkout the configs folder for examples if you are configuring through JSON directly.

OptionDefaultExplanation
baseStation.mac00:00:00:00:00:00The MAC address of the gateway or console. If not set or if invalid, the default is used and MAC validation (additional.macValidation) will be disabled
baseStation.port8080The port on which to listen for data reports from the gateway or console
baseStation.path/data/report/The URL path on which to listen for data reports from the gateway or console
units.windmphThe units to display wind speed. Possible values are: mph: Miles per Hourkph: Kilometers per Hourmps: Meters per Secondkts: Knots
units.raininThe units to display rain accumulation. Possible values are: in: Inchesmm: Millimeters
units.distancemiThe units to display distance such as lightning strike distance. Possible values are: mi: Mileskm: Kilometers
units.temperaturefhThe units to display temperature. Possible values are: fh: Fahrenheitce: Celcius
thresholds{}A mapping of a weather data property to the trigger threshold for that property. By default no thresholds are set. Trigger thresholds should be specified in the units selected under the units configuration block. Possible keys are: windSpeedwindGustSpeedwindMaxDailySpeedrainRaterainEventTotalrainHourlyTotalrainDailyTotalrainWeeklyTotalrainMonthlyTotalrainYearlyTotaluvIndexlightningEventslightningDistance *lightningTime * *The value of the weather data property must be greater than the threshold to trigger the accessory (motion detected), except for lightningDistance and lightningTime which are triggered when the weather data property is less than the threshold.
hidden{}A mapping of a data property or device to whether it should be displayed. By default no data properties or devices are hidden. Either a data property is hidden across all devices, or the device with all its data properties is hidden. See customHidden if more granularity is needed. Possible keys to hide data are: windDirectionwindSpeedwindGustSpeedwindMaxDailySpeedrainRaterainEventTotalrainHourlyTotalrainDailyTotalrainWeeklyTotalrainMonthlyTotalrainYearlyTotalsolarRadiationuvIndextemperaturehumidityindoorTemperatureindoorhumiditysoilMoistureleafWetnesswaterLeakairQualityPM25airQualityPM25AvgairQualityPM10airQualityPM10AvgcarbonDioxidecarbonDioxideAvglightningEventslightningDistancelightningTimebattery Possible keys to hide devices are: BASE (For gateway or console)WH25 (Also use for WN32P)WH26 (Also use for WN32)WN30 (Also use for WN36)WN31WN34WN35WH40WH41 (Also use for WH43)WH45WH46WH51WH55WH57WH65 (Also use for WS69)WN67WS68WS80WS85WS90 These product numbers correspond to the Ecowitt device numbers so if you are using a non-Ecowitt device please translate your model to the equivalent Ecowitt device. Please note that if all data properties for a device are hidden, the device itself will be hidden automatically.
customHidden[]A list of service identifies that specifies a specific service on a specific device should not be displayed. This provides additional customization beyond hidden by allowing any service on any device to be hidden. The service identifier is specified in the form YYYY(CHZ):<data-property>. YYYY is the device id (e.g. WH41) (CHZ) is the optional channel id if the device uses a channel. The data property can be set to any of the data keys indicated in hidden. See here for additional help with custom hidden properties.
nameOverrides[]A list of key value pairs that specifies the override name for an accessory service. Each override takes on the form: {"key": "<the-service-identifier>", "value", "<the-override-name>"} The service identifier is specified in the form YYYY(CHZ):<data-property>. YYYY is the device id (e.g. WH41) (CHZ) is the optional channel id if the device uses a channel. The data property can be set to any of the data keys indicated in hidden. See here for additional help with name overrides.
additional.staticNamesfalseSet to true to not show the weather metric value in the service names of the accessory so that the service names do not change.
additional.validateMactrueCheck that the MAC address in each data report matches the MAC address specified for the plugin, and do not process the data report if it does not match.
additional.luxFactor126.7Factor to multiple the Solar Radiation data (in W/m2) to convert to Lux.
additional.acceptAnyPathfalseProcess data reports that are submitted to the plugin on paths other than the path specified in baseStation.path.
additional.validateTimestamptrueCheck the recency of the data report with the dateutc data property, and do not process the data report if its determined to be old.
additional.removeStaleDevicestrueRemove the accessory from Homebridge if it does not appear in the current data report during device discovery.
additional.logDataReportsfalseShow the full data report in Homebridge logs every time a data report is received. If not enabled, the data report is also shown in the logs when Homebridge is in debug mode.

Frequently Asked Questions

How do I migrate to this plugin from other Homebridge Ecowitt plugins?

This plugin includes most prior version of Homebridge Ecowitt plugin forks including v1.0 and v1.1 from spatialdude, v1.2 and v1.3 from ochong and v1.4 from pavelserbajlo. If you are currently using any of these mentioned versions, you can switch to the same version of this plugin and get the same functionality.

I would also recommend updating to the latest version of this plugin to take advantage of the new features. Check out the v2 migration guide for more info on updating.

Does this plugin support devices produced by other manufacturers?

There are a number of weather station distributors that re-brand the hardware sensors from Fine Offset. Along with Ecowitt, other notable distributors include Ambient Weather and Froggit. These brands typically also use similar firmware / software within their ecosystem, and many provide the ability to publish weather data reports to a custom endpoint.

If the weather station equipment you are using supports a custom weather service endpoint using the Ecowitt protocol or Ambient protocol, then this plugin can support it regardless of the labeled distributor. For any issues, please file a Github issue, and make sure to include the data report.

I've added a device to my gateway or console, and can see it on the app (WSView Plus or awnet), but the accessory is not showing up in Homebridge or Homekit?

The plugin only performs device discovery on the first data report after the plugin starts. If you add a device, please restart Homebridge to trigger the discovery and the plugin should pick up the new device, and create the accessory. In the Homebridge logs, you can look for logs that begin with Adding new accessory to confirm it was added.

I use a sensor that's not currently supported. What can I do to get it supported?

Please open a feature request on the Github project to let me know what devices you are interested in getting support for. Please make sure to include the data report in the feature request.

I'm having difficulties with setting the name overrides for a data property. Can you help?

Yes, this is definitely a bit tricky, and might require a bit of trial of error. I would suggest first looking at the Name Overrides Guide and see if that is able to help for your case. And of course, if you need additional help with setting name overrides, please file a Githbub issue.

Contributing

Contributions are welcomed! Please report bugs, suggest improvements, and open pull requests. For major pull requests, please open an issue first to discuss what you would like to change. See the Contributing Guide for more info.

The project is also looking for your input on these issues.

Supporting

This plugin requires my time and energy to develop and maintain, as well as the occasional purchase of sensor arrays and gateways. If you feel you have gotten value from this plugin, please consider making a donation. Github Stars are appreciated too!

:fast_forward: :fast_forward: :fast_forward: Getting Started | Supported Devices | Configuration | FAQs | Contributing :rewind: :rewind: :rewind: