Ecovacs in Home Assistant Part10 - extend ecovacs build-in integration for the Ecovacs X5 Pro( )

Ecovacs in Home Assistant Part10 - extend ecovacs build-in integration for the Ecovacs X5 Pro(mxse7w.py )

 

DEEBOT X5 PRO (China Version - MXSE7W)

This article specifically targets the Chinese Mainland version of the ECOVACS DEEBOT X5 PRO.

Unlike the global models, the Chinese version has several hardware and software differences that are important when integrating it with Home Assistant.

 

The model  is:

DEEBOT X5 PRO
Model: MXSE7W
Region: China

 

 

https://github.com/DeebotUniverse/client.py/blob/dev/deebot_client/hardware/mxse7w.py

"""Deebot DEEBOT X5 PRO OMNI Capabilities."""

from __future__ import annotations

# Import various "Capability" base classes and device type definitions from the deebot_client library
from deebot_client.capabilities import (
    Capabilities,
    CapabilityClean,
    CapabilityCleanAction,
    CapabilityCustomCommand,
    CapabilityEvent,
    CapabilityExecute,
    CapabilityExecuteTypes,
    CapabilityLifeSpan,
    CapabilityMap,
    CapabilitySet,
    CapabilitySetEnable,
    CapabilitySettings,
    CapabilitySetTypes,
    CapabilityStation,
    CapabilityStats,
    CapabilityWater,
    DeviceType,
)
# Import relevant commands for controlling station actions and JSON serialization
from deebot_client.commands import StationAction
from deebot_client.commands.json import station_action
from deebot_client.commands.json.advanced_mode import GetAdvancedMode, SetAdvancedMode
from deebot_client.commands.json.auto_empty import GetAutoEmpty, SetAutoEmpty
from deebot_client.commands.json.battery import GetBattery
from deebot_client.commands.json.carpet import (
    GetCarpetAutoFanBoost,
    SetCarpetAutoFanBoost,
)
from deebot_client.commands.json.charge import Charge
from deebot_client.commands.json.charge_state import GetChargeState
from deebot_client.commands.json.child_lock import GetChildLock, SetChildLock
from deebot_client.commands.json.clean import CleanAreaV2, CleanV2
from deebot_client.commands.json.clean_count import GetCleanCount, SetCleanCount
from deebot_client.commands.json.clean_logs import GetCleanLogs
from deebot_client.commands.json.clean_preference import (
    GetCleanPreference,
    SetCleanPreference,
)
from deebot_client.commands.json.continuous_cleaning import (
    GetContinuousCleaning,
    SetContinuousCleaning,
)
from deebot_client.commands.json.custom import CustomCommand
from deebot_client.commands.json.efficiency import GetEfficiencyMode, SetEfficiencyMode
from deebot_client.commands.json.error import GetError
from deebot_client.commands.json.fan_speed import GetFanSpeed, SetFanSpeed
from deebot_client.commands.json.life_span import GetLifeSpan, ResetLifeSpan
from deebot_client.commands.json.map import (
    GetCachedMapInfo,
    GetMajorMap,
    GetMapInfoV2,
    GetMapSetV2,
    GetMapTrace,
    GetMinorMap,
    SetMajorMap,
)
from deebot_client.commands.json.multimap_state import (
    GetMultimapState,
    SetMultimapState,
)
from deebot_client.commands.json.network import GetNetInfo
from deebot_client.commands.json.ota import GetOta, SetOta
from deebot_client.commands.json.play_sound import PlaySound
from deebot_client.commands.json.pos import GetPos
from deebot_client.commands.json.relocation import SetRelocationState
from deebot_client.commands.json.stats import GetStats, GetTotalStats
from deebot_client.commands.json.sweep_mode import GetSweepMode, SetSweepMode
from deebot_client.commands.json.true_detect import GetTrueDetect, SetTrueDetect
from deebot_client.commands.json.voice_assistant_state import (
    GetVoiceAssistantState,
    SetVoiceAssistantState,
)
from deebot_client.commands.json.volume import GetVolume, SetVolume
from deebot_client.commands.json.water_info import GetWaterInfo, SetWaterInfo
from deebot_client.commands.json.work_mode import GetWorkMode, SetWorkMode
from deebot_client.commands.json.work_state import GetWorkState
from deebot_client.const import DataType

# Import "Event" and enum definitions used to notify the client when the vacuum state changes
from deebot_client.events import (
    AdvancedModeEvent,
    AvailabilityEvent,
    BatteryEvent,
    CachedMapInfoEvent,
    CarpetAutoFanBoostEvent,
    ChildLockEvent,
    CleanCountEvent,
    CleanLogEvent,
    CleanPreferenceEvent,
    ContinuousCleaningEvent,
    CustomCommandEvent,
    EfficiencyModeEvent,
    ErrorEvent,
    FanSpeedEvent,
    FanSpeedLevel,
    LifeSpan,
    LifeSpanEvent,
    MajorMapEvent,
    MapChangedEvent,
    MapTraceEvent,
    MultimapStateEvent,
    NetworkInfoEvent,
    OtaEvent,
    PositionsEvent,
    ReportStatsEvent,
    RoomsEvent,
    StateEvent,
    StationEvent,
    StatsEvent,
    SweepModeEvent,
    TotalStatsEvent,
    TrueDetectEvent,
    VoiceAssistantStateEvent,
    VolumeEvent,
    WorkMode,
    WorkModeEvent,
    auto_empty,
    water_info,
)
from deebot_client.events.auto_empty import AutoEmptyEvent
from deebot_client.events.efficiency_mode import EfficiencyMode
from deebot_client.models import StaticDeviceInfo


def get_device_info() -> StaticDeviceInfo:
    """Get all static device information and capability mappings supported by the DEEBOT X5 PRO OMNI model."""
    return StaticDeviceInfo(
        DataType.JSON,  # This model uses JSON data format for communication
        Capabilities(
            device_type=DeviceType.VACUUM,  # Device type: Robotic Vacuum Cleaner
            
            # --- Basic Status Capabilities ---
            availability=CapabilityEvent(
                AvailabilityEvent, [GetBattery(is_available_check=True)]
            ),  # Availability status (determines if the device is online by checking the battery status)
            battery=CapabilityEvent(BatteryEvent, [GetBattery()]),  # Battery level status
            charge=CapabilityExecute(Charge),  # Charging control command (return to dock)
            
            # --- Cleaning Control Capabilities ---
            clean=CapabilityClean(
                action=CapabilityCleanAction(command=CleanV2, area=CleanAreaV2),  # Global cleaning and area cleaning
                continuous=CapabilitySetEnable(
                    ContinuousCleaningEvent,
                    [GetContinuousCleaning()],
                    SetContinuousCleaning,
                ),  # Continuous cleaning / Resume cleaning (Get/Set/Event)
                count=CapabilitySet(CleanCountEvent, [GetCleanCount()], SetCleanCount),  # Cleaning cycle count (e.g., clean 1 or 2 times)
                log=CapabilityEvent(CleanLogEvent, [GetCleanLogs()]),  # Cleaning logs / historical records
                preference=CapabilitySetEnable(
                    CleanPreferenceEvent, [GetCleanPreference()], SetCleanPreference
                ),  # Cleaning preference settings
                work_mode=CapabilitySetTypes(
                    event=WorkModeEvent,
                    get=[GetWorkMode()],
                    set=SetWorkMode,
                    types=(
                        WorkMode.MOP,               # Mop only
                        WorkMode.MOP_AFTER_VACUUM,  # Mop after vacuum
                        WorkMode.VACUUM,            # Vacuum only
                        WorkMode.VACUUM_AND_MOP,    # Vacuum and mop simultaneously
                    ),
                ),  # Working mode switching
            ),
            
            # --- Custom Commands & Error Handling ---
            custom=CapabilityCustomCommand(
                event=CustomCommandEvent, get=[], set=CustomCommand
            ),  # Passthrough / custom low-level command capability
            error=CapabilityEvent(ErrorEvent, [GetError()]),  # Malfunction and error events
            
            # --- Fan Speed Settings ---
            fan_speed=CapabilitySetTypes(
                event=FanSpeedEvent,
                get=[GetFanSpeed()],
                set=SetFanSpeed,
                types=(
                    FanSpeedLevel.QUIET,     # Quiet
                    FanSpeedLevel.NORMAL,    # Normal
                    FanSpeedLevel.MAX,       # Max
                    FanSpeedLevel.MAX_PLUS,  # Max Plus
                ),
            ),
            
            # --- Consumables & Maintenance Lifecycle ---
            life_span=CapabilityLifeSpan(
                types=(
                    LifeSpan.BRUSH,              # Main brush
                    LifeSpan.FILTER,             # Dustbin filter
                    LifeSpan.HAND_FILTER,        # Handheld / fine filter
                    LifeSpan.SIDE_BRUSH,         # Side brush
                    LifeSpan.UNIT_CARE,          # Unit maintenance
                    LifeSpan.CLEANING_SOLUTION,  # Cleaning solution
                    LifeSpan.SEWAGE_BOX,         # Wastewater tank maintenance
                ),
                event=LifeSpanEvent,
                get=[
                    GetLifeSpan(
                        [
                            LifeSpan.BRUSH,
                            LifeSpan.FILTER,
                            LifeSpan.HAND_FILTER,
                            LifeSpan.SIDE_BRUSH,
                            LifeSpan.CLEANING_SOLUTION,
                            LifeSpan.SEWAGE_BOX,
                        ]
                    )
                ],
                reset=ResetLifeSpan,  # Reset consumable lifecycle timer command
            ),
            
            # --- Map Capabilities ---
            map=CapabilityMap(
                cached_info=CapabilityEvent(CachedMapInfoEvent, [GetCachedMapInfo()]),  # Cached map information
                changed=CapabilityEvent(MapChangedEvent, []),  # Map update / change events
                info=CapabilityExecute(GetMapInfoV2),  # Get basic map details
                major=CapabilitySet(MajorMapEvent, [GetMajorMap()], SetMajorMap),  # Main map management
                minor=CapabilityExecute(GetMinorMap),  # Secondary / multi-floor map management
                multi_state=CapabilitySetEnable(
                    MultimapStateEvent, [GetMultimapState()], SetMultimapState
                ),  # Multi-map management switch state
                position=CapabilityEvent(PositionsEvent, [GetPos()]),  # Real-time vacuum coordinates on the map
                relocation=CapabilityExecute(SetRelocationState),  # Relocation command
                rooms=CapabilityEvent(RoomsEvent, [GetCachedMapInfo()]),  # Room / zone information on the map
                set=CapabilityExecute(GetMapSetV2),  # Map configurations and settings
                trace=CapabilityEvent(MapTraceEvent, [GetMapTrace()]),  # Cleaning path / movement trace
            ),
            
            # --- Network & Audio ---
            network=CapabilityEvent(NetworkInfoEvent, [GetNetInfo()]),  # Wi-Fi and network status information
            play_sound=CapabilityExecute(PlaySound),  # Find my robot / play prompt tone
            
            # --- Advanced Settings ---
            settings=CapabilitySettings(
                advanced_mode=CapabilitySetEnable(
                    AdvancedModeEvent, [GetAdvancedMode()], SetAdvancedMode
                ),  # Advanced mode switch
                carpet_auto_fan_boost=CapabilitySetEnable(
                    CarpetAutoFanBoostEvent,
                    [GetCarpetAutoFanBoost()],
                    SetCarpetAutoFanBoost,
                ),  # Auto-boost suction on carpets switch
                child_lock=CapabilitySetEnable(
                    ChildLockEvent, [GetChildLock()], SetChildLock
                ),  # Child lock switch
                efficiency_mode=CapabilitySetTypes(
                    event=EfficiencyModeEvent,
                    get=[GetEfficiencyMode()],
                    set=SetEfficiencyMode,
                    types=(
                        EfficiencyMode.ENERGY_EFFICIENT_MODE, # Energy-saving mode
                        EfficiencyMode.STANDARD_MODE,         # Standard mode
                    ),
                ),  # Cleaning efficiency / power consumption mode
                ota=CapabilitySetEnable(OtaEvent, [GetOta()], SetOta),  # Firmware OTA update status and settings
                sweep_mode=CapabilitySetEnable(
                    SweepModeEvent, [GetSweepMode()], SetSweepMode
                ),  # Sweeping mode settings
                true_detect=CapabilitySetEnable(
                    TrueDetectEvent, [GetTrueDetect()], SetTrueDetect
                ),  # TrueDetect 3D structured light obstacle avoidance switch
                voice_assistant=CapabilitySetEnable(
                    VoiceAssistantStateEvent,
                    [GetVoiceAssistantState()],
                    SetVoiceAssistantState,
                ),  # YIKO voice assistant status and switch
                volume=CapabilitySet(VolumeEvent, [GetVolume()], SetVolume),  # Voice broadcast volume settings
            ),
            
            # --- Operation & Station Status Monitoring ---
            state=CapabilityEvent(StateEvent, [GetChargeState(), GetWorkState()]),  # Vacuum main state (Charging/Working)
            station=CapabilityStation(
                action=CapabilityExecuteTypes(
                    station_action.StationAction, types=(StationAction.EMPTY_DUSTBIN,)
                ),  # Control station actions (e.g., manually trigger dust collection)
                auto_empty=CapabilitySetTypes(
                    event=AutoEmptyEvent,
                    get=[GetAutoEmpty()],
                    set=SetAutoEmpty,
                    types=(
                        auto_empty.Frequency.AUTO,  # Automatic dust collection
                        auto_empty.Frequency.SMART, # Smart dust collection
                    ),
                ),  # Auto-empty frequency settings
                state=CapabilityEvent(StationEvent, [GetWorkState()]),  # OMNI station's own working state
            ),
            
            # --- Cleaning Statistics Data ---
            stats=CapabilityStats(
                clean=CapabilityEvent(StatsEvent, [GetStats()]),  # Current / single cleaning session stats (area, time)
                report=CapabilityEvent(ReportStatsEvent, []),  # Data reporting events
                total=CapabilityEvent(TotalStatsEvent, [GetTotalStats()]),  # Lifetime cumulative cleaning statistics
            ),
            
            # --- Water Tank & Mop Module Control ---
            water=CapabilityWater(
                amount=CapabilitySetTypes(
                    event=water_info.WaterAmountEvent,
                    get=[GetWaterInfo()],
                    set=SetWaterInfo,
                    types=(
                        water_info.WaterAmount.LOW,    # Low water level
                        water_info.WaterAmount.MEDIUM, # Medium water level
                        water_info.WaterAmount.HIGH,   # High water level
                    ),
                ),  # Mopping water flow adjustment
                mop_attached=CapabilityEvent(
                    water_info.MopAttachedEvent, [GetWaterInfo()]
                ),  # Detect whether the mopping pad/bracket is installed
            ),
        ),
    )

 

 

1.Root Node —— StaticDeviceInfo

2.Branch Nodes

 

 

3.Leaf Nodes

 

Extend the Built-in Home Assistant Ecovacs Integration for the DEEBOT X5 PRO (MXSE7W, China Version)

 

step 1.

cd /data/homeassistant202405

docker cp  ha:/usr/local/lib/python3.14/site-packages/deebot_client/hardware/mxse7w.py .

 

step 2.Add new station actions for StationAction.CLEAN_BASE functionality

            station=CapabilityStation(
                action=CapabilityExecuteTypes(
                    station_action.StationAction, 
                    types=(
                           StationAction.EMPTY_DUSTBIN,
                           StationAction.DRY_MOP,
                           StationAction.WASH_MOP,
                           StationAction.CLEAN_BASE,
                     ) # add StationAction.WASH_MOP, 20260715
                ),

step 3.

docker cp mxse7w.py ha:/usr/local/lib/python3.14/site-packages/deebot_client/hardware/

docker restart ha

 

step 4.