Ecovacs smart home integration, free and open source
Control Ecovacs Deebot robot vacuums and GOAT mowers: start, dock, battery, errors.
Published by prohand
- Devices
- Version 1.3.0
- Requires Gladys >=5.1.0
- ★ 0
Control your Ecovacs Deebot robot vacuums and Ecovacs GOAT lawn mowers from Gladys: start and stop the job, send the robot back to its dock, set the suction power, follow the battery, the errors and the wear of the parts.
The integration goes through the Ecovacs cloud, with the account of the Ecovacs Home app: Ecovacs offers no local connection. Gladys needs Internet access, and the robot must show up in the app.
Before you start
- Install the Ecovacs Home app and add your robots to it.
- Note the email and password of the account, and the country chosen when the account was created.
- Account created with Google, Apple or Facebook sign-in: it has no password. Set one in the app (Profile, account settings).
Configuration
- Open the Configuration tab of the integration.
- Fill in the email, the password and the country of the account.
- Pick the refresh interval (1 minute by default).
- Save, then click Test the connection: the message lists the robots found.
- Open the Discover tab and add your robots.
Device verification
Ecovacs may ask to confirm Gladys as a new device (the message says so, the cloud answers code 1013 "Please update to the latest version"):
- Click Send the verification code: Ecovacs mails a code to the account (look in the spam folder too).
- Enter it in Confirm the device and click: the robots are listed.
Gladys keeps the same device id for the account, even after a restart.
The password is never sent in clear text: only its MD5 fingerprint goes to Ecovacs, as the app does.
What you get
| Feature | Vacuum | Mower | Detail |
|---|---|---|---|
| State | ✔ | ✔ | Stopped, running, paused, error, returning to dock, charging, docked |
| Cleaning / Mowing | ✔ | ✔ | 1 starts (or resumes after a pause), 0 stops |
| Return to dock / station | ✔ | ✔ | 1 sends the robot back |
| Suction power | ✔ | Quiet, Standard, Max, Max+ (depending on the model) | |
| Battery, Charging | ✔ | ✔ | In % |
| Last error | ✔ | ✔ | English text with its code, see the table below |
| Main brush, Side brush, Filter | ✔ | Remaining life in %, read every 30 minutes | |
| Blades, Camera lens brush | ✔ | Remaining life in %, read every 30 minutes |
A cloud badge shows on the robot card when it answers, unreachable when it no longer does (switched off, out of Wi-Fi).
Actions
- Test the connection: signs in and lists the robots found.
- Send the verification code / Confirm the device: device verification, when Ecovacs asks for it (see above).
- Locate a robot: the robot plays its "I'm here" sound.
Scenes (Gladys 5.1 or later)
The integration adds its own cards to the scene editor, under
Integrations. Every trigger can be narrowed to one robot; left empty, it
matches them all. Common variable: {{triggerEvent.data.name}} (robot name).
Triggers:
- Cleaning or mowing started: the robot starts working (not when it resumes after a pause).
- Cleaning or mowing finished: the robot stopped working (done, stopped or on its way back).
- Robot back on its dock: the robot is on its dock or station, charging.
- Robot error: the robot reported a new error. Variables
{{triggerEvent.data.code}}and{{triggerEvent.data.message}}. Perfect for a "robot stuck" notification. - Consumable worn out: a brush, filter or blade went down to 10 % of its
life or less. Can be narrowed by consumable; variables
{{triggerEvent.data.consumable_name}}and{{triggerEvent.data.percent}}.
Actions (output sent or located: true when the robot took the order, to
gate the rest of the scene):
- Start a robot (resumes when paused), Pause a robot, Stop a robot, Send a robot back to its dock, Locate a robot.
Dashboard widget
Add the Ecovacs robot widget to a dashboard and pick the robot in its settings. It shows:
- the battery, live;
- the state, the last error, the suction power, the wear of the consumables (orange under 10 %) and the connection;
- four buttons: Start (or Resume, or Pause while working), Stop, Dock and Locate.
The widget uses the last reading of the robot: displaying it costs no request to the Ecovacs cloud.
Common error codes
| Code | Meaning |
|---|---|
| 101 | Battery low |
| 102 | Robot stuck in a loop |
| 103 | Wheel problem |
| 104 | Cliff sensor problem |
| 105 | Robot stuck |
| 106 | Side brush worn out |
| 107 | Dust bin full |
| 108 | Side brush blocked |
| 109 | Main brush blocked |
| 110 | Dust bin missing |
| 111 | Bumper problem |
| 112 | Laser sensor problem |
| 113 | Main brush worn out |
| 115 | Battery problem |
| 118 | Filter blocked |
| 119 | Fan problem |
| 120 | Water tank problem |
| 204 | Wheel stuck |
| 312 | Replace the dust bag |
| 1007 | Mop plate loose |
Supported robots
- Recent Deebots (JSON protocol): OZMO 920/950, T8, T9, T10, T20, T30, X1,
X2, N8, N10… The new-generation (
_V2) and older commands are detected automatically. - GOAT mowers: support to be confirmed, feedback welcome.
- Not supported: the very old Deebots (first 600/900 series, XMPP protocol). "Test the connection" names them.
Troubleshooting
- "Ecovacs refused the email or password": check them in the app, and above all the country of the account. After such a refusal the integration stops retrying on its own (so as not to lock the account): fix the configuration or click Test the connection.
- "Ecovacs asks to confirm Gladys as a new device": follow Device verification. The integration does not retry on its own until then.
- "Ecovacs refused the verification code": the code is wrong or too old; ask for a new one.
- "The Ecovacs cloud cannot be reached": check the Internet access of Gladys. The integration retries every 5 minutes.
- The robot is unreachable: it is switched off or out of Wi-Fi; check it answers in the Ecovacs Home app.
- The integration logs (Gladys UI or
docker logs) never contain the password or the tokens.
Configuration settings
These are the settings Ecovacs asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Getting started | section | No | Your robots (Deebot vacuums, GOAT mowers) are reached through the Ecovacs cloud, with the account of the Ecovacs Home app: add the robots in the app first, then enter the same email, password and country here. Accounts created with Google, Apple or Facebook sign-in need a password: set one in the app (Profile, account settings). On the first connection, Ecovacs may ask to confirm Gladys as a new device: "Send the verification code" mails you a code, enter it in "Confirm the device". |
string | Yes | The email of your Ecovacs Home account. | |
| Password | secret | Yes | The password of your Ecovacs Home account. Only its MD5 fingerprint is sent to Ecovacs, as the app does. |
| Country of the account | select | Yes | The country chosen when the account was created: it decides which Ecovacs servers hold it. |
| Refresh interval | select | No | How often each robot is asked for its state through the cloud. |
How to install Ecovacs in Gladys
- In Gladys, open Integrations: Ecovacs appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/prohand/gladys-ecovacs:1.3.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/prohand/gladys-ecovacs.
Ecovacs requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Ecovacs is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by prohand, not by the Gladys core team.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation