Homebridge Ecowitt Weather Sensors

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

Complete HomeKit support for Ecowitt Weather Sensors with Homebridge.

This plugin operates as a service that listens for data reports from an Ecowitt WiFi Gateway or Weather Display Console. The Ecowitt gateway or console must be configured to publish weather service reports to the Homebridge Ecowitt Weather Sensors plugin.

For bugs, feature requests, and questions - please file a new issue.

:arrow_up: :arrow_up: :arrow_up: v2 is now available! These docs are for v2, and v1 docs can be found here. See the v2 config migration guide to get started. Please report any issues.

Features

• Stable support for most Ecowitt weather sensor 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

: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.

Requirements

• Ecowitt WiFI Gateway or Weather Display console such as GW1200, GW2000, HP2550, or HP3500. Check supported devices for the full list of supported gateways and consoles.
• WSView Plus app is recommended, available through the Apple App Store or the Google Play Store.

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 Ecowitt gateway or display console.

MAC Address

This can be found on the About screen on the Weather Display Console, or via the WSView Plus app on the "My Devices" tab.

The MAC address is used to validate that the data report received is coming from the correct gateway or display console.

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 that its accessible from the Ecowitt 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 Ecowitt WSView Plus app.

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.

The service Protocol Type must be configured as Ecowitt. 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 Ecowitt devices typically transmit data to the base station every 60-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 Ecowitt WSView Plus app. In the app, select gateway or display console under "My Devices" then navigate to "More" on the upper right to select "Weather Services."

Ecowitt WSView Plus app showing Custom Weather Service

The gateway and display console can also be configured directly via its web UI on the "Weather Services" tab.

Ecowitt Gateway Web UI 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 based on the first data report received.

Supported Devices

The full list of all Ecowitt sensors and Ecowitt consoles can be found on the Ecowitt online store.

This plugin currently supports the Ecowitt devices shown in the table below. If your Ecowitt device is currently not supported, please open a feature request.

| Device | Description | Service | Product Image | | -------- | ------- | ------- | ------ | | GW1000 / GW1100 | WiFi Weather Station Gateway | Indoor TemperatureIndoor Humidity | | | GW1200 | WiFi Weather Station Gateway | Indoor TemperatureIndoor Humidity | | | GW2000 | WiFi Weather Station Gateway | Indoor TemperatureIndoor Humidity | | | HP2550 (and variants) | 7" TFT Color Display Console | | | | HP2560 (and variants) | 7" TFT Color Display Console with Indoor Sensor Antenna | Indoor TemperatureIndoor Humidity | | | HP3500 (and variants) | 4.3" TFT Color Display Console | | | | WH25 | Indoor Temperature, Humidity and Barometric Sensor | Indoor TemperatureIndoor Humidity | | | WH26| Outdoor Temperature and Humidity Sensor | TemperatureHumidity | | | WN30 | Thermometer with Probe | Temperature | | | WN31 / WH31 (including S and EP variants) | Multi-Channel Temperature and Humidity Sensor | TemperatureHumdity | | | WN32 / WH32 (including EP variant) | Outdoor Temperature and Humidity Sensor Note this will register as a WH26 | TemperatureHumidity | | | WN32P | Indoor Temperature, Humidity and Barometric Sensor Note this will register as a WH25| Indoor TemperatureIndoor Humidity | | | WN34 (S, D, and L variants) | Multi-Channel Temperature Sensor | Temperature | | | WN35 | Leaf Wetness Sensor | Leaf Wetness | | | WN36 | Floating Pool Thermometer Note this will register as a WN30 | Temperature | | | WH40 | Self-Emptying Rain Collector Rainfall Sensor | Rain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly Total | | | WH41 | PM2.5 Air Quality Sensor with Solar Panel | PM2.5 Air QualityPM2.5 Air Quality (24hrs) | | | WH43 | PM2.5 Air Quality Sensor Note this will register as a WH41 | PM2.5 Air QualityPM2.5 Air Quality (24hrs) | | | WH45 | 5-in-1 PM2.5 / PM10 / CO₂ Air Quality Sensor | TemperatureHumidityPM2.5 Air QualityPM2.5 Air Quality (24hrs)PM10 Air QualityPM10 Air Quality (24hrs)CO₂ LevelCO₂ Level (24 hrs) | | | WH46 | 7-in-1 PM1.0 / PM2.5 / PM4.0 / PM10 / CO₂ Air Quality Sensor | TemperatureHumidityPM2.5 Air QualityPM2.5 Air Quality (24hrs)PM10 Air QualityPM10 Air Quality (24hrs)CO₂ LevelCO₂ Level (24 hrs) | | | WH51 (and L variant)| Soil Moisture Sensor | Soil Moisture | | | WH55 | Water Leak Detection Sensor | Water Leak | | | WH57 | Lightning Detection Sensor | Lightning EventsLightning DistanceLightning Time | | | WH65 / WS69 | Solar Powered 7-in-1 Outdoor Station | TemperatureHumiditySolar RadiationUV IndexWind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedRain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly Total | | | WS68 | Solar Powered 4-in-1 Outdoor Station | Solar RadiationUV IndexWind DirectionWind SpeedWind Gust SpeedWind Max Daily Speed | | | WS80 | Solar Powered 6-in-1 Outdoor Station | TemperatureHumiditySolar RadiationUV IndexWind DirectionWind SpeedWind Gust SpeedWind Max Daily Speed | | | WS85 | 3-in-1 Solar Weather Station | Wind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedRain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly Total | | | WS90 | Solar Powered 7-in-1 Outdoor Anti-vibration Haptic Sensor Array | TemperatureHumiditySolar RadiationUV IndexWind DirectionWind SpeedWind Gust SpeedWind Max Daily SpeedRain RateRain Event TotalRain Hourly TotalRain Daily TotalRain Weekly TotalRain Monthly TotalRain Yearly Total | |

: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. 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.

| Option | Default | Explanation | | -------- | ------- | ------- | | baseStation.mac | 00:00:00:00:00:00 | The MAC address of the Ecowitt base station. If not set or if invalid, the default is used and MAC validation (additional.macValidation) will be disabled | | baseStation.port | 8080 | The port on which to listen for data reports from the Ecowitt Gateway or Console | | baseStation.path | /data/report | The URL path on which to listen for data reports from the Ecowitt Gateway or Console | | units.wind | mph | The units to display wind speed. Possible values are: mph: Miles per Hourkmh: Kilometers per Hourmps: Meters per Secondkts: Knots | | units.rain | in | The units to display rain accumulation. Possible values are: in: Inchesmm: Millimeters | | units.distance | mi | The units to display distance such as lightning strike distance. Possible values are: mi: Mileskm: Kilometers | | units.temperature | fh | The 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 weather data property or device to whether it should be displayed. By default no weather data or devices are hidden. Possible keys to hide weather data are: windDirectionwindSpeedwindGustSpeedwindMaxDailySpeedrainRaterainEventTotalrainHourlyTotalrainDailyTotalrainWeeklyTotalrainMonthlyTotalrainYearlyTotalsolarRadiationuvIndextemperaturehumdityindoorTemperatureindoorHumditysoilMoistureleafWetnesswaterLeakairQualityPM25airQualityPM25AvgairQualityPM10airQualityPM10AvgcarbonDioxidecarbonDioxideAvglightningEventslightningDistancelightningTime Possible keys to hide devices are: GW1000GW2000HP2560WH25 (Also use for WN32P)WH26 (Also use for WN32)WN30 (Also use for WN36)WN31WN34WN35WH40WH41 (Also use for WH43)WH45WH46WH51WH55WH57WH65WS68WS80WS85WS90 Please note that if all weather data properties for a device are hidden, the device itself will be hidden automatically. | | 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) or if an accessory has multiple services the weather data property should be included in the identifier YYYY(CHZ):<weather-data-property>. YYYY is the device id (e.g. WH41) (CHZ) is the optional channel id if the device uses a channel. The weather data property can be set to any of the weather data keys indicated in hidden | | additional.staticNames | false | Set 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.validateMac | true | Check 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.luxFactor | 126.7 | Factor to multiple the Solar Radiation data (in W/m2) to convert to Lux. | | additional.acceptAnyPath | false | Process data reports that are submitted to the plugin on paths other than the path specified in baseStation.path. | | additional.validateTimestamp | true | Check the recency of the data report with the dateutc weather data property, and do not process the data report if its determined to be old. | | additional.removeStaleDevices | true | Remove the accessory from Homebridge if it does not appear in the current data report during device discovery. |

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-package and re-brand the hardware sensors from Fine Offset. Along with Ecowitt, other notable distributors include Aercus, Ambient Weather, and Frogger. 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, please file a feature request to let me know what devices you would like support for. Please make sure to include the data report in the feature request.

I've added an Ecowitt device to my gateway or console, and can see it on the WSView Plus app , 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 an Ecowitt 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.

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.

Supporting

This plugin requires my time and energy to develop and maintain, as well as the occasional Ecowitt device purchase. If you feel you have gotten value from this plugin, please consider making a donation.

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