🌐 English · Dansk · Deutsch · Español · Français · Italiano · Nederlands · Norsk (bokmål) · Polski · Português · Suomi · Svenska · Čeština · 中文
This is a Home Assistant integration for TerraMow robotic lawn mowers.
Control
- Lawn mower entity: start, pause and dock
- Zone mowing: zone select entity and
terramow.start_select_regionservice - Schedule editing —
terramow.add_schedule/terramow.delete_scheduleservices write weekly mowing slots to the mower with read-back verification. Note: current retail firmware does not yet accept schedule writes over local MQTT (the vendor app uses Bluetooth/cloud) — until firmware adds it, use the weather-adaptive mowing blueprint for HA-side scheduling - Interactive map card — pan/zoom vector lawn map for dashboards: live robot position (activity-tinted, with follow mode), on-card start / pause / dock controls, battery & job-progress chips, optional mowed-coverage shading, mowing path, base station, zones with tap-to-mow selection, forbidden areas and virtual walls; theme-aware, self-registering, with a UI editor (
custom:terramow-map-card) - Edge trim mowing button
- Settings from Home Assistant: mowing height, speed, spacing, blade speed, edge cutting distance, main direction mode and angles, thorough corner cutting, high-grass edge trim mode
- Maintenance: reset buttons for the blade disk and base station counters
Monitoring
- Live map camera with mowing path, robot pose and base station (plus a clean map-only camera for dashboards, resolution configurable via options)
- Battery: level, charging state, temperature state, charger connected, power switch
- Job progress: current session area, progress (%), duration and job type; lifetime mowing time, job count and mowed area
- Status: mission / sub-mission / mission state, operation mode, power mode, back-to-station reason, rain detection, problem indicator, saving-data and data-conversion indicators
- Map: status, area, detected / buildable / backing-up flags
- Schedule: next-scheduled-start sensor and a read-only mowing-schedule calendar (the next mow appears on the calendar card)
- Firmware update entity, firmware version on the device page, and version compatibility sensor
- All entities update instantly on device pushes — no polling delay
Advanced diagnostics (reverse-engineered data points — mostly in the Diagnostic entity category, many disabled by default; see unofficial data-point notes)
- Errors & events: active-error count (with the raw error list as an attribute) and last-event code
- Cellular / 4G: modem enabled, signal strength (RSRP / RSRQ), connection type, and a force cellular network readout
- Environment: device-reported sunrise / sunset, daylight state, defogger heating, illumination light, and an extreme-weather warning (with an optional info URL)
- Safety & advanced settings: cliff-detection and slope-detection state, rain-sensor threshold, after-rain auto-resume and resume-delay, and a force single base station readout
- Operating modes: movement / map / mowing mode strings
- Mapping & progress: manual-mapping guidance flags (relocation / takeover needed, boundary closed) and a map-save progress percentage
Events & automation
- Mower event entity — fires a discrete event on every notable transition (
mowing_started,paused,returning,docked,mowing_completed,error), each carrying the raw mission fields, so automations react to happenings without polling activity state - One-click automation blueprints (see below)
Integration quality of life
- Zeroconf/mDNS auto-discovery
- Reconfigure flow (change host/IP without re-adding) and reauth flow
- Repair issues — actionable dashboard cards for incompatible firmware and for due blade / base-station maintenance
- Diagnostics download for easy bug reports
- Translated into 33 languages (bg, ca, cs, da, de, el, en, es, et, fi, fr, hr, hu, it, ja, ko, lt, lv, nb, nl, pl, pt, pt-BR, ro, ru, sk, sl, sr, sv, tr, uk, zh-Hans, zh-Hant)
- Confirmed commands — zone mowing waits for the device's dp_119 acknowledgement and reports rejections instead of silently "succeeding"
- MQTT based local push communication — no cloud required
| Platform | Entities |
|---|---|
| Lawn mower | Start / pause / dock control with live activity |
| Camera | Map with path, robot and base station; clean map-only variant |
| Sensor | Battery level, battery state, battery temperature state, map status, map area, mow height, mow speed, operation mode, pose, total mowing time / jobs / mowed area, current session area / progress / duration / job type, remaining blade & base station time, next scheduled start, version compatibility, main direction status, power mode, back-to-station reason, mission, sub-mission, mission state. Diagnostic: active errors, last event, cellular RSRP / RSRQ / type, sunrise, sunset, movement / map / mowing mode, rain-sensor threshold, after-rain resume delay, map save progress |
| Binary sensor | Charging, navigation located, firmware upgrading, power switch, problem, rain detected, map detected / buildable / backing up, saving data, data conversion in progress. Diagnostic: cellular enabled, defogger heating, illumination, daylight, extreme weather, cliff / slope detection, after-rain auto-resume, force single base station, force cellular network, manual-mapping relocation / takeover / boundary-closed |
| Select | Zone select, mow speed, blade speed, main direction mode, high-grass edge trim mode |
| Number | Mowing height, edge cutting distance, mowing spacing, single direction angle, auto-rotate angle interval, first / second direction angle |
| Switch | Thorough corner cutting |
| Button | Edge trim, reset blade timer, reset base station timer |
| Update | Firmware version |
| Event | Mower event (mowing started / paused / returning / docked / completed / error) |
| Calendar | Mowing schedule (next scheduled mow) |
- Make sure HACS is installed
- Use the button above to add to HACS
- Go to HACS → Integrations → + → Search for "TerraMow"
- Install and restart Home Assistant
- Copy the
custom_components/terramowfolder to your Home Assistant/config/custom_componentsfolder - Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration
- Search for "TerraMow" and follow the configuration steps
Devices on the local network are discovered automatically via Zeroconf — accept the discovered device and enter the MQTT password. For manual setup the following parameters are required:
- Host: IP address or hostname of the TerraMow device
- Password: MQTT password for authentication
Changing settings later
- Reconfigure (Settings → Devices & Services → TerraMow → Reconfigure): change the host/IP or password in place, e.g. after the mower received a new DHCP address — no need to remove and re-add the integration.
- Options (Configure): tune the map camera — output resolution (higher is sharper but costs more bandwidth and CPU per render), map theme (
light/dark) and whether to shade the already-mowed coverage. - If the device password changes, Home Assistant automatically starts a reauthentication flow.
- Home Assistant 2024.6.0 or later (tested with 2025.1.1)
- TerraMow firmware version 6.6.0 or later
- TerraMow APP version 1.6.0 or later
- Live map and mowing path require firmware HA module version 3; on version 2 (e.g. S800) everything else works and the version compatibility sensor reports it
This integration works with TerraMow robotic lawn mowers that expose the local MQTT/HTTP interface — i.e. any model on the required firmware. It has been used with the TerraMow S-series, including the S800 (which reports firmware HA module version 2) and newer units on version 3. Any TerraMow mower on firmware 6.6.0+ and app 1.6.0+ should work; the version-compatibility sensor and a repair issue tell you if a specific unit's firmware is too old for a given feature.
Start mowing for a list of selected sub-regions.
service: terramow.start_select_region
target:
entity_id: lawn_mower.terramow
data:
region_ids: [1, 2]Write or remove a weekly mowing slot on the mower. Each write is confirmed against the device (dp_119 acknowledgement plus a schedule read-back).
service: terramow.add_schedule
target:
entity_id: lawn_mower.terramow
data:
week_days: [tuesday, thursday]
start_time: "07:45:00"
end_time: "09:15:00"delete_schedule takes the item_id of the slot (shown as the calendar
event's uid and returned when a slot is added).
Note: current retail firmware does not yet accept schedule writes over local MQTT (the vendor app uses Bluetooth/cloud). Until firmware adds it, use the weather-adaptive mowing blueprint for HA-side scheduling.
The integration ships its own Lovelace card — auto-registered, no manual resource or HACS frontend install needed:
type: custom:terramow-map-card
entity: lawn_mower.terramowIt renders the lawn as vectors (crisp at any zoom, follows your HA theme): zones, forbidden areas, virtual walls, the mowing path, the base station and the robot's live position. Drag to pan, scroll or pinch to zoom, double-tap to re-fit. Tap one or more zones and press the button that appears to mow exactly those zones (terramow.start_select_region under the hood). Options and details: see the dashboard guide. Live map data requires firmware HA module version 3 (same as the map camera). The card is also available in the dashboard card picker as TerraMow Map Card, with a full UI editor — no YAML needed.
A ready-made Lovelace view (live map, controls, progress gauge, status glance) plus notification automations: see the dashboard guide.
One-click importable blueprints for the most common notifications — each just asks for the relevant TerraMow entity and a notification action:
- Weather-adaptive mowing — start mowing on your schedule, skipped automatically when rain is detected or forecast
- Problem notification — when the mower reports a fault
- Returned because of rain — when the mower docks due to rain
- Mowing finished — when a mowing job completes
Using the event entity directly — the mower event entity is the most flexible trigger. Its event_type attribute is one of mowing_started, paused, returning, docked, mowing_completed, error, and it carries the raw mission, sub_mission, state, back_to_station_reason and has_error fields:
triggers:
- trigger: state
entity_id: event.terramow_mower_event
attribute: event_type
to: mowing_completed
actions:
- action: notify.mobile_app_phone
data:
message: "TerraMow finished mowing 🌱"The integration raises actionable Home Assistant repair issues (Settings → Devices & Services → Repairs) instead of hiding problems in sensors:
- Firmware incompatible / update required — the firmware is too old for the integration (or a specific feature). Derived from the version-compatibility check; clears when a compatible firmware reports in.
- Blade maintenance due — the blade disc has run for its recommended 240-hour service interval. Clean/replace the blades and press the Reset Blade Timer button to clear it.
- Base station maintenance due — the base station has run for its recommended 30-day service interval. Clean it and press the Reset Base Station Timer button to clear it.
- Diagnostics download: Settings → Devices & Services → TerraMow → three-dot menu → Download diagnostics produces a redacted JSON snapshot (device state, firmware compatibility, raw data point caches) — please attach it to bug reports.
- Discovering unsupported features: the mower publishes more data points than are documented. The first payload of every unknown data point is logged once at INFO level; enable debug logging for the
terramowintegration to record all of them. If you find a data point for a missing feature (e.g. lift alarm, schedule switch, error codes), please share it in an issue.
TerraMow is a local push integration. The mower runs an on-device MQTT broker; Home Assistant connects to it directly over the LAN (no cloud) and subscribes to the device's data-point topics, so entity states update the instant the mower reports a change rather than on a polling interval. Larger payloads (the map, the live path) are announced over MQTT and fetched on demand over local HTTP. If the mower is asleep or off the network the connection is retried with exponential backoff, and the lawn-mower entity surfaces the connection loss as its error activity.
Commands fail loudly, not silently. When you send a command — dock, start_mowing, pause, edge trim, zone mowing, or any setting change — it is published at MQTT QoS 1 (so a brief reconnect buffers it instead of dropping it). If the mower is offline/unreachable, the broker rejects the publish, or a command arrives faster than the device can accept it, the service call fails with an error instead of silently reporting success. This means an automation that calls lawn_mower.dock while the mower is unreachable now sees the failure (and can retry or notify) rather than believing the mower is on its way back when it never received the command.
- No cloud / remote access — Home Assistant must be on the same LAN as the mower; there is no cloud fallback.
- Firmware-gated features — the live map and mowing-path view require firmware HA module version 3; on version 2 (e.g. the S800) everything else works and the compatibility sensor / repair issue reports the limitation.
- Firmware updates are performed through the TerraMow app, not from Home Assistant; the firmware
updateentity is informational only. - The pose sensor and the clean-mode map camera are disabled by default (the pose sensor updates at ~2 Hz); enable them from the entity settings if you need them.
- Many advanced-diagnostic entities are disabled by default and grouped under the Diagnostic category (cellular, sunrise/sunset, operating modes, manual-mapping flags, etc.); they come from reverse-engineered data points, so enable only the ones you need. See the unofficial data-point notes.
- Some device data points are undocumented; unknown ones are logged once to help discover missing features.
- Rain-aware notifications — get a push when the mower returns to its dock because of rain (see the blueprints above).
- Fault alerts — be notified the moment the mower reports a problem (stuck, lifted, blocked).
- Zone mowing from automations — call
terramow.start_select_regionto mow specific sub-regions on a schedule or from a dashboard button. - Maintenance reminders — the remaining blade / base-station time sensors and the reset buttons let you automate maintenance reminders.
- Live map on a dashboard — show the map camera with the robot position and mowing path (see the dashboard guide).
The integration is translated into: Български · Català · Čeština · Dansk · Deutsch · Eesti · Ελληνικά · English · Español · Français · Hrvatski · Italiano · 日本語 · 한국어 · Latviešu · Lietuvių · Magyar · Nederlands · Norsk (bokmål) · Polski · Português · Português (Brasil) · Română · Русский · Slovenčina · Slovenščina · Српски · Suomi · Svenska · Türkçe · Українська · 简体中文 · 繁體中文.
- v0.5.0: entity state values changed from uppercase to lowercase (e.g.
MISSION_IDLE→mission_idle) to comply with Home Assistant translation requirements. Automations or templates comparing raw state strings need a one-time update; displayed names are unchanged.
Open an issue on GitHub for support.
For developers interested in understanding or extending this integration:
- Contributing guide — setup, quality gates (100% coverage,
mypy --strict, translations), PR and release process - Architecture — integration internals: hub lifecycle, execution model, data-point catalog, map/path pipeline
- Developer guide — the on-the-wire MQTT/HTTP device protocol
- What this fork adds over upstream
To run the test suite locally:
pip install -r requirements_test.txt
pytest tests/ --cov=custom_components/terramow --cov-fail-under=100This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.