deebot-client

What it is and what it does

deebot-client is a reverse-engineered Python library that communicates with Ecovacs Deebot robotic vacuums through the manufacturer's cloud REST API and MQTT messaging protocol. It allows developers to authenticate with an Ecovacs account, retrieve paired devices, send cleaning commands, and subscribe to device events like battery status changes. The library is maintained as a community contribution project and is not officially supported by Ecovacs.

The package wraps async I/O operations using aiohttp and aiomqtt, with cryptographic utilities for authentication. It exposes a Device class for command execution and an event subscription system. Because the API is reverse-engineered, the maintainers note that feature coverage depends on community contributions and cannot be guaranteed to remain stable.

Use it for:

• Integrate Deebot vacuums into Home Assistant or other home automation platforms via a Python client
• Build custom scheduling or geofencing logic to trigger vacuum commands based on external events
• Monitor battery level, cleaning status, and other device telemetry in real time via event subscriptions
• Create a web dashboard or mobile app backend that controls multiple Deebot devices remotely
• Automate vacuum operation as part of a broader smart-home workflow (e.g., start cleaning when leaving home)

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A Python client library for controlling Ecovacs Deebot robotic vacuums via their cloud API and MQTT protocol, enabling remote commands and event subscriptions.

Yes, if you own a Deebot vacuum and want programmatic control for home automation. The library is actively maintained, has no known vulnerabilities, and integrates well with Home Assistant. Be aware of the GPL-3.0-or-later copyleft license, the Python 3.14.0 requirement, and the Windows MQTT limitation. The reverse-engineered API carries inherent risk of breaking changes if Ecovacs alters their protocol.

Install

deebot-client on PyPI

pip install deebot-client

uv add deebot-client

poetry add deebot-client

Installing deebot-client

Before you install

Medium install friction due to 6 runtime dependencies including aiohttp, aiomqtt, and cryptography. Actively maintained with a recent release (15 days old) and steady repository activity. Note: aiomqtt has a known Windows limitation documented in the project.

License in practice

Licensed under GPL-3.0-or-later (copyleft). Any derivative work or application bundling this library must also be released under a compatible open-source license.

Quickstart

pip install deebot-client

import asyncio
from deebot_client.api_client import ApiClient
from deebot_client.authentication import Authenticator, create_rest_config
from deebot_client.device import Device
from deebot_client.mqtt_client import MqttClient, create_mqtt_config
import aiohttp

async with aiohttp.ClientSession() as session:
    rest_config = create_rest_config(session, device_id="id", alpha_2_country="DE")
    authenticator = Authenticator(rest_config, "account_id", "password_hash")
    api_client = ApiClient(authenticator)
    devices = await api_client.get_devices()

Requires Python 3.14.0 or later. On Windows, aiomqtt has a known limitation; see project documentation for workaround. Requires an active Ecovacs account set up via smartphone app.

Verify before relying

• Whether all Deebot device models are supported or only a subset
• Real-world latency and reliability of command execution over MQTT
• Whether the reverse-engineered API is stable or subject to breaking changes from Ecovacs

Package facts

Evidence: deebot_client-18.5.1-cp314-cp314-macosx_10_12_x86_64.whl; deebot_client-18.5.1-cp314-cp314-macosx_11_0_arm64.whl; deebot_client-18.5.1-cp314-cp314-manylinux_2_34_aarch64.whl; deebot_client-18.5.1-cp314-cp314-manylinux_2_34_x86_64.whl; deebot_client-18.5.1-cp314-cp314-musllinux_1_2_aarch64.whl; deebot_client-18.5.1-cp314-cp314-musllinux_1_2_x86_64.whl; deebot_client-18.5.1-cp314-cp314-win_amd64.whl

Keywords: home, automation, homeassistant, vacuum, robot, deebot, ecovacs

Tags

More Python Modules packages