KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

ecovacs-deebot.js

★ 145 Open GitHub ↗

A Node.js library for running Ecovacs Deebot and yeedi vacuum cleaner robots

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ecovacs-deebot.js

![Logo](https://raw.githubusercontent.com/mrbungle64/ecovacs-deebot.js/1.0.0-alpha.0/ecovacs-deebot.png)

[![Stable version](https://img.shields.io/npm/v/ecovacs-deebot/latest?label=stable)](https://www.npmjs.com/package/ecovacs-deebot)
[![Beta version](https://img.shields.io/npm/v/ecovacs-deebot/beta?label=beta)](https://www.npmjs.com/package/ecovacs-deebot)
[![Alpha version](https://img.shields.io/npm/v/ecovacs-deebot/alpha?label=alpha)](https://www.npmjs.com/package/ecovacs-deebot)
[![github-workflow](https://github.com/mrbungle64/ecovacs-deebot.js/actions/workflows/node.js.yml/badge.svg)](https://github.com/mrbungle64/ecovacs-deebot.js)

> **⚠️ Maintenance Status:** This project has transitioned to a more sustainable maintenance model. Development now focuses exclusively on modern **MQTT/JSON** communication.

---

## 🗺️ The Roadmap & Legacy "Clean Cut"

To reduce technical debt and ensure long-term maintainability, the following architectural cut has been implemented:

### Phase 1: Final Legacy Milestone (v0.9.x) — Final
* **v0.9.5 (Stable):** Final stable release with verified support for legacy XML-based protocols.
* **v0.9.6-beta.12 (Final Legacy Release):** Last development milestone to support legacy hardware (XMPP/XML and MQTT/XML).

### Phase 2: Modernization (v1.0.0+) — In Progress
* **v1.0.0-alpha:** Development has shifted exclusively to a pure **MQTT/JSON** stack.
* **Legacy Removal:** All legacy XML-based code and dependencies have been removed to ensure stability and security.

---

## Why we are dropping Legacy Support

The decision to end support for XML-based models is a technical necessity:

* **Node.js 22.15+ & Infrastructure Constraints:** Modern environments and ARM64 architectures require up-to-date runtime support. Newer map payloads can use zstd compression, which depends on Node.js 22.15+ built-in `zlib` support.
* **Security vs. Compatibility:** To bypass the build issues of native modules, legacy protocols often rely on pure JavaScript XML parsers like `@xmldom/xmldom`. These are known to be vulnerable to security risks like XML Injection (XXE) and are no longer suitable for modern, secure architectures.
* **Official End-of-Life:** Most legacy models (e.g., 500, 600, 700, 900 series, OZMO 930) reached their official manufacturer support end.
* **Clean Cut:** Dropping these protocols allows us to remove the associated technical debt and risky dependencies, focusing exclusively on a fast and stable MQTT/JSON architecture.

---

## Models & support tiers

For a full list of all known device classes, their respective support tiers, and details on how device capabilities are resolved, please refer to the following documentation:

* [Support Tiers](docs/SUPPORT_TIER.md)
* [Models & Capability Resolution](docs/MODELS.md)

### Important note on new models
Support for new models is no longer added upon request. Due to high time constraints, **I will not implement new models based on logs alone**. Requests for new model support without an accompanying **Pull Request** may be closed without further notice.

---

## Installation & usage

* [Installation Guide](docs/INSTALLATION.md) (includes [Docker Compose Setup](docs/INSTALLATION.md#5-running-with-docker-compose-local-development--testing))
* [Usage Instructions](docs/USAGE.md)
* [Command Reference](docs/COMMANDS.md)
* [Event Reference](docs/EVENTS.md)

**Requirement:** Node.js >= 22.15

---

## ⚠️ Known issues
* **Map Image Generation:** Rendering is now pure JavaScript (the native `canvas` dependency was removed), which resolves the previous instability on 32-bit systems and needs no Cairo/build prerequisites. Overlay edges (spot areas, virtual boundaries) and the robot/charger icons are drawn as simple aliased vector shapes, and pixel-level parity with the official app across all series is still being validated.
* **Movement Control:** The "move" function is highly model-specific and not implemented with universal logic.
* **Legacy Models:** If you own a model that requires the XML protocol, this version will throw an `Error`. Please stick to `v0.9.5` or `v0.9.6-beta.12`.

---

## Changelog

### 1.0.0-alpha (current)
* **Breaking Changes:**
    * Complete removal of legacy XMPP/XML and MQTT/XML protocol stacks
    * Refactoring for pure MQTT/JSON communication
* **Device verification:** Added support for the Ecovacs device-verification flow (login code `1013`). `connect()` throws `EcovacsAPI.DeviceVerificationRequired`; complete the login with `api.requestDeviceVerificationCode()` and `api.verifyDevice(code)` (invalid codes throw `EcovacsAPI.InvalidVerificationCode`, code `1012`). See [Usage Instructions](docs/USAGE.md#device-verification-login-code-1013).
* **Long-running connections:** Opt-in automatic access-token refresh (`api.enableAutoTokenRefresh()` / `credentialsUpdated` event) for 24/7 clients.
* **Refactoring:** Centralized model identification and properties documentation in `docs/MODELS.md`

### 0.9.6 (Final Legacy Support)
* **Final milestone** for all XML-based models
* Enforced minimum Node.js version 20.x
* Added support for T20, T30, X2, and X8 series

### 0.9.5 (Final Legacy stable)
* Added GoToPosition shortcut function (e.g. T8, T9 and X1 series)
* Fix AirDryingStart and AirDryingStop commands

### 0.0.2 - 0.9.4
* See [Changelog archive](https://github.com/mrbungle64/ecovacs-deebot.js/wiki/Changelog-(archive))

---

## Credits
Special thanks to [@edenhaus](https://github.com/DeebotUniverse/client.py) for the technical exchange and to [@wpietri](https://github.com/wpietri) for the foundational reverse engineering of the protocol.

## Disclaimer
I am in no way affiliated with Ecovacs Robotics Co., Ltd. or yeedi Technology Limited.

ecovacs-deebot.js

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README