Homebridge Ecowitt Weather Sensors

⏩ ⏩ ⏩ Getting Started | Supported Devices | Configuration | FAQs | Contributing ⏪ ⏪ ⏪

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.

⬆️ ⬆️ ⬆️ 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

⚠️ 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
GW1000 / GW1100	WiFi Weather Station Gateway	Indoor Temperature Indoor Humidity
GW1200	WiFi Weather Station Gateway	Indoor Temperature Indoor Humidity
GW2000	WiFi Weather Station Gateway	Indoor Temperature Indoor Humidity
HP2550 (and variants)	7" TFT Color Display Console
HP2560 (and variants)	7" TFT Color Display Console with Indoor Sensor Antenna	Indoor Temperature Indoor Humidity
HP3500 (and variants)	4.3" TFT Color Display Console
WH25	Indoor Temperature, Humidity and Barometric Sensor	Indoor Temperature Indoor Humidity
WH26	Outdoor Temperature and Humidity Sensor	Temperature Humidity
WN30	Thermometer with Probe	Temperature
WN31 / WH31 (including S and EP variants)	Multi-Channel Temperature and Humidity Sensor	Temperature Humdity
WN32 / WH32 (including EP variant)	Outdoor Temperature and Humidity Sensor Note this will register as a WH26	Temperature Humidity
WN32P	Indoor Temperature, Humidity and Barometric Sensor Note this will register as a WH25	Indoor Temperature Indoor 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 Rate Rain Event Total Rain Hourly Total Rain Daily Total Rain Weekly Total Rain Monthly Total Rain Yearly Total
WH41	PM2.5 Air Quality Sensor with Solar Panel	PM2.5 Air Quality PM2.5 Air Quality (24hrs)
WH43	PM2.5 Air Quality Sensor Note this will register as a WH41	PM2.5 Air Quality PM2.5 Air Quality (24hrs)
WH45	5-in-1 PM2.5 / PM10 / CO₂ Air Quality Sensor	Temperature Humidity PM2.5 Air Quality PM2.5 Air Quality (24hrs) PM10 Air Quality PM10 Air Quality (24hrs) CO₂ Level CO₂ Level (24 hrs)
WH46	7-in-1 PM1.0 / PM2.5 / PM4.0 / PM10 / CO₂ Air Quality Sensor	Temperature Humidity PM2.5 Air Quality PM2.5 Air Quality (24hrs) PM10 Air Quality PM10 Air Quality (24hrs) CO₂ Level CO₂ Level (24 hrs)
WH51 (and L variant)	Soil Moisture Sensor	Soil Moisture
WH55	Water Leak Detection Sensor	Water Leak
WH57	Lightning Detection Sensor	Lightning Events Lightning Distance Lightning Time
WH65 / WS69	Solar Powered 7-in-1 Outdoor Station	Temperature Humidity Solar Radiation UV Index Wind Direction Wind Speed Wind Gust Speed Wind Max Daily Speed Rain Rate Rain Event Total Rain Hourly Total Rain Daily Total Rain Weekly Total Rain Monthly Total Rain Yearly Total
WS68	Solar Powered 4-in-1 Outdoor Station	Solar Radiation UV Index Wind Direction Wind Speed Wind Gust Speed Wind Max Daily Speed
WS80	Solar Powered 6-in-1 Outdoor Station	Temperature Humidity Solar Radiation UV Index Wind Direction Wind Speed Wind Gust Speed Wind Max Daily Speed
WS85	3-in-1 Solar Weather Station	Wind Direction Wind Speed Wind Gust Speed Wind Max Daily Speed Rain Rate Rain Event Total Rain Hourly Total Rain Daily Total Rain Weekly Total Rain Monthly Total Rain Yearly Total
WS90	Solar Powered 7-in-1 Outdoor Anti-vibration Haptic Sensor Array	Temperature Humidity Solar Radiation UV Index Wind Direction Wind Speed Wind Gust Speed Wind Max Daily Speed Rain Rate Rain Event Total Rain Hourly Total Rain Daily Total Rain Weekly Total Rain Monthly Total Rain Yearly Total

⚠️ 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 Hour `kmh`: Kilometers per Hour `mps`: Meters per Second `kts`: Knots
units.rain	`in`	The units to display rain accumulation. Possible values are: `in`: Inches `mm`: Millimeters
units.distance	`mi`	The units to display distance such as lightning strike distance. Possible values are: `mi`: Miles `km`: Kilometers
units.temperature	`fh`	The units to display temperature. Possible values are: `fh`: Fahrenheit `ce`: 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: `windSpeed` `windGustSpeed` `windMaxDailySpeed` `rainRate` `rainEventTotal` `rainHourlyTotal` `rainDailyTotal` `rainWeeklyTotal` `rainMonthlyTotal` `rainYearlyTotal` `uvIndex` `lightningEvents` `lightningDistance ` `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: `windDirection` `windSpeed` `windGustSpeed` `windMaxDailySpeed` `rainRate` `rainEventTotal` `rainHourlyTotal` `rainDailyTotal` `rainWeeklyTotal` `rainMonthlyTotal` `rainYearlyTotal` `solarRadiation` `uvIndex` `temperature` `humdity` `indoorTemperature` `indoorHumdity` `soilMoisture` `leafWetness` `waterLeak` `airQualityPM25` `airQualityPM25Avg` `airQualityPM10` `airQualityPM10Avg` `carbonDioxide` `carbonDioxideAvg` `lightningEvents` `lightningDistance` `lightningTime` Possible keys to hide devices are: `GW1000` `GW2000` `HP2560` `WH25` (Also use for `WN32P`) `WH26` (Also use for `WN32`) `WN30` (Also use for `WN36`) `WN31` `WN34` `WN35` `WH40` `WH41` (Also use for `WH43`) `WH45` `WH46` `WH51` `WH55` `WH57` `WH65` `WS68` `WS80` `WS85` `WS90` 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/m²) 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.