Ecowitt Controller

A .NET 10 bridge that connects Ecowitt weather stations and IoT subdevices to MQTT, with native Home Assistant auto-discovery.

Features

• Multi-gateway, multi-subdevice support
• Two ingestion modes per gateway: Push (legacy /data/report, works with any Ecowitt-protocol station) or Poll (get_livedata_info API, for IoT-capable gateways)
• Automatic discovery of new sensors and subdevices
• Bidirectional communication with subdevices (AC1100, WFC01, WFC02)
• Home Assistant MQTT discovery (devices, sensors, switches)
• Metric/imperial unit conversion (Push mode) — Poll mode passes the gateway's configured display unit through to HA verbatim
• Change-detection filtering to reduce MQTT noise

Supported Devices

Gateways: GW3000, GW2000, GW1200, GW1100, WN1980, WS3800, WS39x0

Subdevices (require IoT-capable gateway like GW2000/GW1200):

• AC1100 — Smart plug with power monitoring
• WFC01 — Water timer with flow sensor and temperature
• WFC02 — Water valve with optional flow sensor

Weather Stations: Any Fine Offset compatible station (Ecowitt, Froggit, Ambient Weather, ...) that supports custom Ecowitt protocol uploads.

Getting Started

Prerequisites: A running MQTT broker (e.g. Mosquitto).

Configuration

Create an appsettings.json. Minimal setup — just point it at your MQTT broker:

{
  "mqtt": {
    "host": "192.168.1.50"
  }
}

Full configuration with all options and their defaults:

{
  "Serilog": {
    "MinimumLevel": "Warning"
  },
  "mqtt": {
    "host": "",
    "user": "",
    "password": "",
    "port": 1883,
    "basetopic": "ecowitt",
    "clientId": "ecowitt-controller",
    "reconnect": true,
    "reconnectAttempts": 2,
    "useMqtt311": false
  },
  "ecowitt": {
    "pollingInterval": 30,
    "calculateValues": true,
    "retries": 2,
    "gateways": [
      {
        "name": "weatherstation_01",
        "ip": "192.168.1.101",
        "subdevices": true
      }
    ]
  },
  "controller": {
    "precision": 2,
    "unit": "metric",
    "homeassistantdiscovery": true
  }
}

Section	Key	Default	Description
mqtt	host	—	MQTT broker address (required)
mqtt	port	1883	MQTT broker port
mqtt	basetopic	ecowitt	Root MQTT topic prefix
mqtt	reconnect	true	Auto-reconnect on disconnect
mqtt	reconnectAttempts	2	Reconnect retry count
mqtt	useMqtt311	false	Use MQTT 3.1.1 instead of MQTT 5.0
ecowitt	pollingInterval	30	Subdevice polling interval (seconds)
ecowitt	liveDataInterval	5	Gateway livedata polling interval (seconds), used when a gateway is in Poll mode
ecowitt	calculateValues	true	Generate calculated sensor values
ecowitt	gateways	[]	Gateway definitions (name, ip, credentials, subdevices)
ecowitt.gateways[]	subdevices	false	Enable subdevice polling (only GW1200, GW2000, GW3000)
ecowitt.gateways[]	ingestMode	Push	Push (accept legacy /data/report HTTP push, default) or Poll (poll get_livedata_info on liveDataInterval; only GW1200/2000/3000). When Poll, push payloads from this gateway IP are dropped.
controller	precision	2	Decimal places for floating-point values
controller	unit	metric	metric or imperial
controller	homeassistantdiscovery	true	Publish HA MQTT discovery messages

Run with Docker

Multi-architecture images (amd64, arm64) are available on Docker Hub. The container expects its configuration at /config/appsettings.json.

docker run -d --name ecowitt-controller \
  -v /path/to/config:/config \
  -p 8080:8080 \
  --restart always \
  mplogas/ecowitt-controller:latest

Place your appsettings.json in the host directory you bind-mount to /config.

Docker Compose

services:
  ecowitt-controller:
    image: mplogas/ecowitt-controller:latest
    container_name: ecowitt-controller
    restart: always
    volumes:
      - type: bind
        source: /path/to/config
        target: /config
    ports:
      - "8080:8080"

Port 8080 must be reachable by your Ecowitt gateway for weather data uploads. If your gateway is on a specific VLAN or subnet, bind to the appropriate interface IP (e.g. 192.168.1.10:8080:8080).

Home Assistant Add-on

For Home Assistant OS / Supervised installations, Ecowitt Controller is available as a native add-on. This handles configuration, networking, and MQTT broker discovery automatically.

1. Add the add-on repository to your HA instance: https://github.com/mplogas/ha-addon-ecowitt-controller
2. Install Ecowitt Controller from the add-on store
3. Configure your gateways in the add-on settings
4. Start the add-on

The add-on runs on the host network and auto-discovers the Mosquitto broker if the official Mosquitto add-on is installed. See the add-on repository for full documentation.

Run from Source

cd src
dotnet run --project Ecowitt.Controller/Ecowitt.Controller.csproj -c Release

Configure Your Weather Station

The controller supports two ingestion modes per gateway. Pick one based on your hardware and preference. Both produce the same MQTT topics and Home Assistant entities downstream.

Push mode (default)

Works with any Ecowitt-protocol gateway, including older non-IoT models (GW1100, GW1000, WN1980, WS3800, WS39x0). The gateway uploads weather data to the controller on its configured posting interval.

1. Open your gateway's WebUI or the WS View Plus app
2. Go to weather services and enable the Customized upload
3. Set protocol to Ecowitt, enter the controller's IP, path /data/report, port 8080
4. Set the posting interval (e.g. 30 seconds)

Push mode is the default — no controller-side config change required.

Poll mode (IoT-capable gateways only)

Works with GW1200, GW2000, GW3000. The controller polls the gateway's get_livedata_info API on its own schedule (ecowitt.liveDataInterval, default 5 seconds), giving controller-owned timing and explicit failure detection.

1. Set ingestMode to Poll for the gateway entry in appsettings.json:

   "gateways": [
     {
       "name": "weatherstation_01",
       "ip": "192.168.1.101",
       "subdevices": true,
       "ingestMode": "Poll"
     }
   ]

2. No WSView configuration changes needed. The custom-upload setting in WSView can stay enabled — push payloads from Poll-mode gateway IPs are silently discarded.
3. Set your gateway's display units in WSView to whatever you want HA to show. Poll mode is unit-passthrough: the sensor unit in HA matches what the gateway is configured to display (e.g. set wind to m/s in WSView → HA shows m/s). The controller.unit setting governs Push-mode conversion only and has no effect on Poll-mode sensors.

Home Assistant Integration

With homeassistantdiscovery enabled (default), devices and sensors appear automatically in HA via MQTT discovery. Make sure your HA instance is connected to the same MQTT broker.

Tip: Running Home Assistant OS or Supervised? Use the HA add-on instead for a simpler setup.

Note: Gateways and their sensors only appear after the first data push from the Ecowitt device. This depends on the Upload Interval configured in your gateway's WebUI or the WS View Plus app (step 4 above). Subdevices are picked up on the next polling cycle after their parent gateway has reported in, so expect an additional delay of up to one pollingInterval.

Documentation

• Architecture — System design, data flow, and message bus topology
• HTTP API — Inbound weather data endpoint and outbound gateway polling
• MQTT Topics — Topic structure, payloads, and Home Assistant discovery

Tech Stack

• ASP.NET Core Web API — HTTP endpoint for Ecowitt weather data
• MQTTnet — MQTT client
• SlimMessageBus — In-memory message bus connecting the services
• Serilog — Structured logging
• Polly — HTTP retry policies

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.