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.
- 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
- 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)
⚠️ 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.
Search for "Ecowitt" on the Homebridge Config UI X Plugins screen, find homebridge-ecowitt-weather-sensors and select to install.
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.
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
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
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.
⚠️ 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.⚠️
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.
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.
| Ecowitt | Ambient | Description | Service | Product Image |
|---|---|---|---|---|
| GW1000 / GW1100 | --- | Wifi Weather Station Gateway |
|
 |
| GW1200 | --- | Wifi Weather Station Gateway |
|
 |
| GW2000 | --- | Wifi Weather Station Gateway |
|
 |
| GW3000 | --- | Wifi Weather Station Gateway |
|
 |
| HP2550 (and variants) | WS2000 / WS4000 / WS5000 | 7" TFT Color Display Console | use WN32P for indoor temperature and humidity |  |
| HP2560 / HP2561 / HP2564 | --- | 7" TFT Color Display Console with Indoor Sensor Antenna |
|
 |
| HP3500 (and variants) | WS3000 | 4.3" TFT Color Display Console | use WN32P for indoor temperature and humidity |  |
| WS2320 / WS2350 | --- | 7" LCD Display |
|
 |
| WS2900 / WS2910 | WS2902 | 6.8" Color LCD Display with Touch Buttons |
|
 |
| WS3800 / WS3820 | --- | 7.5" LCD Display with IOT Intelligent Linkage Control |
|
 |
| WS3900 / WS3910 | --- | 7.5" LCD Display with IOT Intelligent Linkage Control |
indoor carbon dioxide not supported |
 |
| WN1820 / WN1821 | --- | 4.9" LCD Display |
indoor carbon dioxide not supported |
 |
| WN1900 / WN1910 / WN1920 | WS1965 | 4.9" LCD Display |
|
 |
| WN1980 | --- | 5.3" LCD Display with Touch Screen Keys |
|
 |
| Ecowitt | Ambient | Description | Service | Product Image |
|---|---|---|---|---|
| WH25 | --- | Indoor Temperature, Humidity and Barometric Sensor |
|
 |
| WH26 | --- | Outdoor Temperature and Humidity Sensor |
|
 |
| WN30 | WH31P | Thermometer with Probe |
|
 |
| WN31 / WH31 (including S and EP variants) | WH31E / WH32M / WH51RF | Multi-Channel Temperature and Humidity Sensor |
|
 |
| WN32 / WH32 (including EP variant) | --- | Outdoor Temperature and Humidity Sensor Note this will register as a WH26 |
|
 |
| WN32P | WH32B | Indoor Temperature, Humidity and Barometric Sensor Note this will register as a WH25 |
|
 |
| WN34 (S, D, and L variants) | --- | Multi-Channel Temperature Sensor |
|
 |
| WN35 | WH51LW | Leaf Wetness Sensor |
|
 |
| WN36 | WH31PF | Floating Pool Thermometer Note this will register as a WN30 |
|
 |
| WH40 (including H variant) | --- | Self-Emptying Rain Collector Rainfall Sensor |
|
 |
| WH41 | PM25 | PM2.5 Air Quality Sensor with Solar Panel |
|
 |
| WH43 | PM25IN | PM2.5 Air Quality Sensor Note this will register as a WH41 |
|
 |
| WH45 | AQIN | 5-in-1 PM2.5 / PM10 / CO₂ Air Quality Sensor |
|
 |
| WH46 (including D variant) | --- | 7-in-1 PM1.0 / PM2.5 / PM4.0 / PM10 / CO₂ Air Quality Sensor |
|
 |
| WH51 (and L variant) | WH31SM | Soil Moisture Sensor |
|
 |
| WH55 | WH31LA | Water Leak Detection Sensor |
|
 |
| WH57 | WH31L | Lightning Detection Sensor |
|
 |
| Ecowitt | Ambient | Description | Service | Product Image |
|---|---|---|---|---|
| WH65 (Y-shape) / WS69 (I-shape) | WS2000 | Solar Powered 7-in-1 Outdoor Station |
|
 |
| WN67 | WS1965 | 5-in-1 Outdoor Station |
|
 |
| WS68 | --- | Solar Powered 4-in-1 Outdoor Station |
|
 |
| WS80 | WS5000 | Solar Powered 6-in-1 Outdoor Station |
|
 |
| WS85 | --- | 3-in-1 Solar Weather Station |
|
 |
| WS90 | WS4000 | Solar Powered 7-in-1 Outdoor Anti-vibration Haptic Sensor Array |
|
 |
⚠️ 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.
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/"
}
}
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 gateway or console. 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 gateway or console |
| baseStation.path | /data/report/ |
The URL path on which to listen for data reports from the gateway or console |
| units.wind | mph |
The units to display wind speed. Possible values are: mph: Miles per Hourkph: 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 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)WN67WS68WS80WS85WS90These 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.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 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. |
| additional.logDataReports | false |
Show 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. |
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.
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 accessoryto confirm it was added.
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.
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.
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.
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!
⏩ ⏩ ⏩ Getting Started | Supported Devices | Configuration | FAQs | Contributing ⏪ ⏪ ⏪