Integración domótica eufy Clean, gratuita y de código abierto
eufy robot vacuums: state, battery, clean, pause, dock, suction, consumables, errors.
Publicado por LM1LC3N7
- Dispositivos
- Versión 0.1.1
- Requiere Gladys >=5.2.0
- ★ 0
La documentación de esta integración la escribe su autor y, por ahora, solo está disponible en inglés.
This integration brings the eufy robot vacuums (RoboVac, eufy Clean: X, L, G, C series…) into Gladys, through the eufy cloud (the one of the eufy app): state, battery, cleaning, pause, return to dock, cleaning type, suction power, life of the brushes, filter and mop, errors, and scene triggers. Updates arrive in real time over eufy's secure MQTT. Unofficial, not affiliated with Anker or eufy.
Development version (0.1). Built on the community SDK @mega-yfue/eufy-sdk and tested with simulated robots, not with a real robot yet. Feedback is welcome on the GitHub repository.
Not covered here: eufy cameras, video doorbells, locks, sensors and HomeBases. They belong to the eufy Security integration of the Gladys store (cicoub13/gladys-eufy); this one ignores them and never connects to them. eufy robot mowers are not supported yet.
Which account
Use the e-mail address and password of your eufy app account, and the country chosen when it was created (FR, BE, CH, GB, DE, US…).
- The integration signs in as its own "phone", different from the eufy app and from the eufy Security integration, so none of them should sign the others out. If the eufy app or Gladys keeps being signed out anyway, create a second eufy account, share the robot with it from the eufy app (robot → settings → share), and give Gladys that second account.
- An account that signs in with Google or Apple has no password: add a password in the eufy app, or use a second account.
Installation
- Install the integration from the Gladys store.
- In the Configuration tab, enter the e-mail address, the password and the country of the eufy account. Save.
- On the first sign-in, eufy usually sends a verification code (by
e-mail or in the app): the status says so. Type the code in
Verification code and save. The field empties itself; the session is
then kept in the integration's
/datafolder, so a restart does not ask for a new code. - The status says "Connected to eufy: 1 robot".
- Open the Discovery tab and add your robots. Their values arrive as soon as they are added and the robot reports (a docked robot may stay silent until something changes).
The captcha, if eufy asks for one
After several failed sign-ins, eufy may ask for a captcha. The Gladys
configuration screen cannot show an image, so the integration writes it in
its logs: a line that starts with data:image/png;base64,. Copy that whole
line, paste it into the address bar of your browser to see the image, type its
4 characters in Captcha answer and save. A wrong answer brings a new image
in the logs.
The Test the connection button shows the account, each robot with its state and battery, and whether the real-time channel is connected.
What you get
One Gladys device per robot vacuum, with the features the robot reports or the commands the SDK confirms for it:
| Feature | In Gladys |
|---|---|
| State | Stopped, Running, Paused, Error, Returning to dock, Charging, Docked |
| Cleaning (run mode) | Clean starts a cleaning (or resumes a paused one), Pause pauses it |
| Return to dock | sends the robot back to its dock |
| Cleaning type (clean mode) | robots with a mop: Auto (vacuum and mop), Vacuum, Mop |
| Suction power | Quiet, Standard, Turbo, Max, and BoostIQ or Max Pro when the robot offers them |
| Battery, Charging | battery level in %, charging on its dock |
| Error, Error code | the message ("Wheel stuck (2)", "No error") and the code, for scenes |
| Consumables (maintenance) | life remaining in % of the side brush, rolling brush, filter, mop, sensors and cleaning tray |
| Area cleaned, Cleaning time | of the current or last cleaning (m², minutes) |
| Find my robot | makes the robot beep |
- The features follow the robot: a robot without a mop has no cleaning type, a part the robot does not count has no feature. A feature the robot reports later is added; update the device from the Discovery tab to get it.
- Consumables: the robot counts the hours each part has worked; the integration turns them into a remaining life, with the lifetimes the Home Assistant integration uses (side brush 180 h, rolling brush 360 h, filter 360 h, mop 180 h; sensors to clean every 60 h, cleaning tray every 30 h). Resetting a counter after a replacement is done in the eufy app.
- There is no "stop": the SDK has not confirmed eufy's stop command yet. Pause then Return to dock ends a cleaning.
- The badge of each device shows
cloud, orunreachablewhen eufy says the robot is offline. - Older robots (G-series, L60, X8 and the other robots of the "eufy Home" line): the SDK reads their state, battery and errors but has no confirmed command for them yet; the test button marks them "read only".
Scenes
Two scene triggers, each can target one robot:
- Cleaning finished: the robot is back on its dock (or stopped) after a
cleaning. Variables
robot_name,duration(minutes) andarea(m²). Not fired when the cleaning stopped on an error. - Robot error: the robot reports a new error (wheel or brush stuck, dust
bin full, water tank empty, robot trapped…). Variables
robot_name,error_codeanderror_message. Fired once per new code.
The first reading after a start fires nothing. Commands are the usual "Control a device" actions (Cleaning: Clean / Pause, Return to dock, Suction power…), and the other values work with the "Device state changed" trigger.
How it works
The integration signs in to the eufy cloud like the app, reads the account's devices (every 10 minutes, to see a robot added or removed) and keeps one secure MQTT connection open: the robots report their changes on it, and the commands go through it. No polling of the robots. If the connection drops, it comes back by itself; if eufy ends the session, the integration signs in again after the delay eufy asks (one minute at least).
Options
| Option | Default | Purpose |
|---|---|---|
| eufy e-mail address, password | — | the account of the eufy app (or a second account) |
| Country of the account | FR | two letters, the country the account was created in |
| Verification code, Captcha answer | empty | only when eufy asks for them (see the status) |
| Language of the feature names | French | names of the features, suction levels and error messages |
Troubleshooting
- "eufy refused the sign-in": check the e-mail, the password and the country in the eufy app. The integration does not retry by itself: it waits for a change of the configuration.
- "eufy sent a verification code": type the code received by e-mail (or in the app) in Verification code and save, within a few minutes.
- "eufy asks for a captcha": see above; the image is in the logs.
- "The eufy session ended": another app signed in with the same account and identity, or the session expired. The integration signs in again by itself; if it keeps happening, use a second account with the robot shared.
- "the eufy real-time channel (MQTT) did not open": the robots cannot report. The integration tries again (1 minute, then longer); check that Gladys reaches the Internet.
- A robot shows no state: it reports on change only; start a cleaning or put it on its dock, the state follows.
- A robot is "read only": an older model; its commands will come with the SDK.
Privacy
The e-mail and password are stored by Gladys as a secret (never sent back to
the browser). The integration sends them, encrypted like the app does, to the
eufy cloud of the account's region to open a session, and keeps the session in
its /data folder. It does not register for camera notifications and opens no
connection to cameras or HomeBases. eufy, Anker, RoboVac and BoostIQ are
trademarks of their owner; this integration is not affiliated with Anker or
eufy.
Parámetros de configuración
Estos son los parámetros que eufy Clean te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Your eufy account | section | No | Brings your eufy robot vacuums (RoboVac, eufy Clean X, L, G, C series) into Gladys through the eufy cloud, the one of the eufy app: state, battery, start, pause, return to dock, cleaning type and suction power, life of the brushes, filter and mop, errors, and scene triggers when a cleaning ends or an error appears. Updates arrive in real time over eufy's secure MQTT. Sign in with the account of the eufy app (or a second account the robot is shared with), then add the robots from the Discovery tab. Cameras, doorbells, locks and HomeBases are left to the eufy Security integration. Unofficial, not affiliated with Anker or eufy. |
| eufy e-mail address | string | Sí | |
| eufy password | secret | Sí | |
| Country of the account | string | Sí | Two letters, the country chosen when the eufy account was created: FR, BE, CH, GB, DE, US… |
| If eufy asks for a code or a captcha | section | No | On the first sign-in, eufy usually sends a verification code (e-mail or app): type it below and save, it is used once and the field empties itself. After several failed sign-ins, eufy may ask for a captcha instead: its image is written in the integration logs as one line starting with data:image, to paste into the address bar of a browser; type its 4 characters below and save. The connection status says what eufy is waiting for. |
| Verification code | string | No | |
| Captcha answer | string | No | |
| Language of the feature names | select | No | Used for the names of the features, the suction levels and the error messages. |
Cómo instalar eufy Clean en Gladys
- En Gladys, abre Integraciones: eufy Clean aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/lm1lc3n7/gladys-eufy-clean:0.1.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/LM1LC3N7/gladys-eufy-clean.
eufy Clean requiere Gladys >=5.2.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
eufy Clean es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene LM1LC3N7, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación