homebridge-ecowitt-weather-sensors v2.10.1

Homebridge Ecowitt Weather Sensors

: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

Sensors

Sensor Arrays

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

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: