Ecovacs GOAT G1 for Home Assistant

A mower-only Home Assistant custom integration for ECOVACS GOAT G1 lawn mowers.

It gives you a lawn mower entity, useful sensors, mower settings, and an optional dashboard card with map, start, stop, dock, and cut-direction controls.

Important

This is an unofficial community project. It is not affiliated with, endorsed by, certified by, or supported by ECOVACS.

Use it at your own risk. A robotic mower has moving blades and can cause damage or injury if used unsafely. Always keep the mower in sight when testing new commands, and stop using the integration if either Home Assistant or the official ECOVACS app loses reliable control.

Tested Mower

Developed and tested with an ECOVACS GOAT G1-800.

No promise is made that it will work with any other mower model. ECOVACS vacuums are not supported.

Other models (experimental)

The integration now detects the mower family and adapts the protocol dialect it uses:

• GOAT G1 line (G1, G1-800 / G-800, G1-2000, G1-1600) — fully implemented and validated. Uses the UWB beacon + *_V2 map dialect.
• GOAT O-series (O800 RTK, O1200, O1200 LiDAR Pro, ...) — experimental, best-effort. These models speak a different dialect: the clean command (not clean_V2), getCleanInfo (not getCleanInfo_V2), RTK reference points (rtkPos) instead of UWB, and the getMapState / getMapTrack / getMI / getAreaSet map commands. This was confirmed against a decrypted capture of a GOAT O800 RTK (firmware 1.9.10).

For O-series mowers the integration:

• Detects the model and reports it on the GOAT model line diagnostic sensor (with family, map_dialect, and an experimental flag).
• Drives the lawn mower entity, start/pause/resume/stop/dock controls, status, battery, error, and the live position map (mower marker + path) from the shared position stream.
• Shows the RTK base station on the map (from getRTK) where the G1 line shows UWB beacons.
• Does not yet draw the completed-area outline, because the only available O-series capture was taken while docked (the map-trace command returns fail with no job running), so there is no validated geometry sample to decode. The map id is still learned so this can be finished later.
• Avoids spamming *_V2 map errors that the previous G1-only code produced on these mowers.

If you own an O-series mower and want fuller support (especially the area outline), the most useful thing you can provide is a sanitized capture from the official app taken during active mowing. See Debug Capture below and the issue tracker.

Why This Integration Exists

This project is separate from Home Assistant's regular ECOVACS integration. It was created because the regular Ecovacs/Home Assistant path is built around a broader vacuum-oriented command stack, while this project only targets GOAT mowers and uses behavior observed from the official ECOVACS app.

The goal is to keep communication with the mower conservative: use pushed updates where possible, refresh state only when needed, and avoid broad background polling.

Features

• Start or resume mowing, stop mowing, and return to dock.
• Battery, error, Wi-Fi, current mow, total mow, and consumable sensors.
• Settings for rain delay, animal protection, AI recognition, edge mowing, safer mode, warning switches, cut direction, mowing efficiency, and obstacle avoidance.
• Diagnostic model-line and feature information to help identify G1 variants.
• Optional Lovelace card with a live map and clear mower controls.
• Opt-in debug capture tools for troubleshooting.

Installation With HACS

Until this is available as a default HACS repository, add it manually:

1. In Home Assistant, open HACS.
2. Open the three-dot menu and choose Custom repositories.
3. Add https://github.com/Janverhu/ecovacs-goat-g1.
4. Select category Integration.
5. Install Ecovacs GOAT G1.
6. Restart Home Assistant.
7. Add the integration from Settings -> Devices & services -> Add integration.

Testing pre-release (beta) builds

Experimental builds — for example new model support being validated with a tester — are automatically published as pre-releases from the development branch (each push produces an incrementing beta such as 0.2.0b1, 0.2.0b2). To install one in HACS:

1. Open Ecovacs GOAT G1 in HACS.
2. Three-dot menu -> Redownload.
3. Enable Show beta versions.
4. Pick the beta (e.g. 0.2.0b1) and download, then restart Home Assistant.

To return to a stable build later, redownload and pick the latest non-beta version.

Setup

You need your ECOVACS account username, password, and country. The integration uses the ECOVACS cloud, just like the official app.

During setup, choose a Home Assistant device name. A generated default such as Ecovacs-GOAT-1 is provided.

Optional Dashboard Card

The custom card is optional, but recommended. It exposes a clear stop button and a mower-focused map layout.

No manual install is needed. The integration bundles the card and registers it with Home Assistant automatically: it serves ecovacs-goat-card.js from the integration and loads it as a frontend module, versioned to the integration release so browsers pick up updates after each upgrade (a hard refresh may be needed once).

Just add Ecovacs GOAT Card from the custom card picker (you may need to reload the dashboard once after first install).

Upgrading from a manual install (do this): if you previously added a /local/ecovacs_goat/ecovacs-goat-card.js Lovelace resource, remove it in Settings -> Dashboards -> Resources, then hard-refresh your browser (Ctrl+Shift+R / Cmd+Shift+R). This is required: a dashboard card can only be registered once, and the old manual resource has no version in its URL, so your browser keeps loading the cached old card and never picks up the bundled one. You can also delete the copied config/www/ecovacs_goat/ecovacs-goat-card.js file.

The card’s keepalive control starts a timed request_live_position_stream session so the mower behaves as if the official app map is open (MQTT-heavy updates). How that fits with the trace outline and the 60 second fallback is explained under How It Behaves below.

Example YAML:

type: custom:ecovacs-goat-card
entity: lawn_mower.mower
battery_entity: sensor.mower_battery_level
error_entity: sensor.mower_error
area_entity: sensor.mower_mowing_area
progress_entity: sensor.mower_mowing_progress
direction_entity: number.mower_cut_direction
stop_button: button.mower_end_mowing
name: Mower

How It Behaves

The integration tries to be conservative with the mower and cloud connection:

• It prefers live updates pushed by ECOVACS over MQTT.
• It refreshes grouped state at startup and after meaningful MQTT changes (with a short debounced readback).
• It avoids broad background polling loops.

Live map: position line, completed outline, and keepalive

The map is built from two layers that update at different rates:

1. Completed mowing outline (trace) — A path from the mower cloud (getMapTrace_V2) or from MQTT onMapTrace_V2. It shows where the mower has already cut. Trace payloads are relatively heavy, so the integration throttles them: MQTT trace pushes are ignored until enough heading change has accumulated from live position updates (about 90° in total, using the mower’s reported heading and/or the direction of travel between consecutive points, with a small minimum move distance so noise does not open the gate). When that threshold is reached, the integration schedules a trace refresh and accepts new trace data. If onPos never arrives, that heading gate never advances from turns alone, so while mowing the integration also refreshes the trace on the same slow cloud poll it uses for position when MQTT has gone stale (about every 60 seconds).

2. The “last line” / in-progress segment — While mowing, the integration keeps a short polyline of recent positions (position_history): ideally one point per MQTT onPos message. If onPos has been quiet for about 60 seconds, a background task asks the cloud for getPos instead. When a new trace snapshot is applied, that live segment is reset so the stored outline and the line still being drawn stay aligned.

Keepalive (“someone is watching the map”) — In the official app, opening the live map nudges the cloud and mower toward faster onPos and related map traffic. Home Assistant does not do that continuously. The service ecovacs_goat_g1.request_live_position_stream asks ECOVACS for an app-style map session (map set, trace, map point) and, when you pass duration_seconds, keeps a keepalive window open: a background loop sends appping, repeats the stream request, and keeps app-presence MQTT active so the mower treats the session like an open app map. The optional Ecovacs GOAT card starts this for you (default 10 minutes per activation) and passes force: true, which bypasses the coordinator’s usual spacing on stream requests so the loop can stay aggressive while the window runs. While MQTT onPos is flowing, the moving dot and the live segment update from those pushes, and accumulated heading opens the trace gate after turns. If onPos stops (no keepalive and no mower pushes), updates fall back to the ~60 second mowing poll for both position and trace, which keeps the map roughly current but not smoothly animated.

Constants such as the 90° gate, 60 second stale interval, and stream request spacing live in mower_coordinator.py if you need exact values.

For technical protocol notes, see docs/protocol-summary.md.

Debug Capture

If a model or feature does not work, use the debug capture services before opening an issue. Captures are disabled by default and stored locally under /config/ecovacs_goat_g1_debug/.

Recommended workflow:

1. Call ecovacs_goat_g1.start_debug_capture from Developer Tools -> Services.
2. Reproduce the problem.
3. Optionally call ecovacs_goat_g1.mark_debug_capture at useful moments.
4. Call ecovacs_goat_g1.stop_debug_capture.
5. Download Home Assistant diagnostics or call ecovacs_goat_g1.export_debug_capture.

Do not share passwords, access tokens, device IDs, or private network details publicly.

Troubleshooting

• If entities are unknown after setup, press Refresh state once the mower is online.
• If commands fail, check whether the official ECOVACS app can still control the mower.
• If both Home Assistant and the official app lose contact with the mower, stop testing and recover the mower first.
• When opening an issue, include the integration version, mower model, Home Assistant logs, and the action that failed.

Safety

Only use mower commands when the mower is in a safe outdoor state. Keep people, pets, and objects away from the mower while testing. If behavior looks wrong, stop the mower with the official app or physical controls first.

This software is provided without any warranty. Compatibility is best effort and may change if ECOVACS changes its app, cloud service, firmware, or account behavior. You are responsible for deciding whether it is safe to use with your mower and property.

ECOVACS and GOAT names and trademarks belong to their respective owner. This project does not claim any ownership of ECOVACS branding or official assets.

More Information

• docs/protocol-summary.md has sanitized protocol notes.
• CONTRIBUTING.md explains the development scope.
• SECURITY.md explains what not to share publicly.
• ACKNOWLEDGEMENTS.md credits related community work.

License

MIT License. See LICENSE.