科沃斯T50 PRO上下水版接入Home Assistant（含地图修复）

目录前言一、问题原理1. 设备识别不出来2. 地图打不开HTTP 500二、补丁思路映射到哪个型号三、操作步骤1. 新建自定义集成2. 在 configuration.yaml 启用3. 检查配置并重启4. 添加 Ecovacs 集成四、效果五、注意事项参考前言HA 自带的ecovacs集成可以接入科沃斯扫地机底层依赖 deebot-client 这个库。但国行 T50 系列的不少新型号库里还没收录账号能登录、集成能加上可设备一个实体都没有。网上现成的做法什么值得买这篇、瀚思彼岸这帖都是docker exec进 HA 容器直接改site-packages里的文件。这样有两个问题HA 一升级就失效容器镜像换了改过的文件也跟着没了HAOS 用户往往进不去容器Advanced SSH Web Terminal 插件默认开着保护模式执行docker只会提示PROTECTION MODE ENABLED!。我的做法是写一个几十行的自定义集成在 HA 启动时往内存里打补丁不碰任何库文件升级 HA 后也不用重做。我的机器是T50 PRO 上下水版还踩到了一个帖子里没提的坑不同批次的机器上报的型号 ID 不一样。环境Home Assistant OSHA GreenCore 2026.9.3内置 ecovacs 集成依赖deebot-client18.5.1设备DEEBOT T50 PRO 上下水版国区账号一、问题原理1. 设备识别不出来deebot-client 靠设备上报的class硬件 ID去加载deebot_client/hardware/class.py文件里写的是这个型号支持哪些功能。加载逻辑很简单# deebot_client/hardware/__init__.pyfull_package_namef{__package__}.{class_}moduleawaitasyncio.to_thread(importlib.import_module,full_package_name)找不到对应文件就会在日志里报Device class dur723 not recognized. Please add support for it: {... deviceName: DEEBOT T50 PRO 上下水版, model: FARADAYSE_PRO_A_W_CN, ...} Device DEEBOT T50 PRO 上下水版 not supported.重点先看日志里自己机器上报的class是什么不要照抄别人的。网上帖子里的 T50 Pro 上报的是q0n7xe我这台上下水版型号FARADAYSE_PRO_A_W_CN上报的却是dur723。只照帖子做q0n7xe的映射对我这台没用。查看方法设置 → 系统 → 日志搜not recognized。2. 地图打不开HTTP 500设备识别成功后地图实体image.xxx_map可能一直加载不出来/api/image_proxy/image.xxx_map返回 500。原因在deebot_client/messages/json/map/__init__.pyclassOnMapInfoV2(MessageBodyDataDict):classmethoddef_handle_body_data_dict(cls,event_bus,data):if(outline_version:data.get(outlineVer))0:returnHandlingResult.success()ifoutline_version!1:# Unsupported versionreturnHandlingResult.analyse()event_bus.notify(MapInfoEvent(map_iddata[mid],infodata[info]))returnHandlingResult.success()新固件回复的地图信息里outlineVer是2被当成不支持的版本直接丢掉MapInfoEvent永远不会触发生成 SVG 时就拿不到地图元信息。截至写这篇文章时deebot-client 18.6.0这两个问题上游都还没合并修复相关 PR#1835上下水版 q0n7xe、#1797接受 outlineVer 2。二、补丁思路型号映射Python 的importlib.import_module会先查sys.modules。只要提前把deebot_client.hardware.dur723指到一个已有的相近型号模块上库就能“找到”配置文件效果和帖子里建软链接一样。地图把OnMapInfoV2._handle_body_data_dict包一层遇到outlineVer 2就当成1交给原逻辑处理。GetMapInfoV2继承自OnMapInfoV2主动拉取和被动推送两条路径都能覆盖。加载顺序如果 ecovacs 集成比补丁先启动设备已经被判成不支持了所以补丁生效后会自动重载一次 ecovacs 配置项。映射到哪个型号可选的有两个配置文件型号说明elrxgb软链到c8rj4yT50 Max Pro Omni网上帖子用的上游有个已知问题 #1483getCleanPreference 返回 20005nxeux7软链到fd60ktT50 OMNI上游 PR #1835 给上下水版用的就是这份作者真机验证过两者一对比nxeux7多了基站状态GetStationState、拖布自动清洗频率、GetCleanInfoV2更贴近上下水版所以我选了nxeux7。三、操作步骤1. 新建自定义集成在 HA 配置目录下新建custom_components/ecovacs_patch/放两个文件。用 File editor、Samba 或 SSH 都可以不需要关闭保护模式。custom_components/ecovacs_patch/manifest.json{domain:ecovacs_patch,name:Ecovacs T50 Pro Patch,codeowners:[],dependencies:[],documentation:https://bbs.hassbian.com/thread-32418-1-1.html,iot_class:local_push,requirements:[],version:1.0.0}custom_components/ecovacs_patch/__init__.py运行时给 deebot-client 打补丁让科沃斯 T50 Pro 能在内置 ecovacs 集成里用。 1. 硬件 ID 别名库里没有对应文件的型号识别不出设备映射到功能相近的已支持型号。 2. 地图 outlineVer2库只认 1新固件回 2 时被丢弃导致地图实体 HTTP 500。 上游修好后直接删掉这个集成即可每个补丁都会先检查是否还需要。 from__future__importannotationsimportimportlibimportloggingimportsysfromhomeassistant.config_entriesimportConfigEntryStatefromhomeassistant.coreimportHomeAssistantfromhomeassistant.helpers.typingimportConfigType DOMAINecovacs_patch_LOGGERlogging.getLogger(__name__)# 设备上报的硬件 ID - 库里已有的配置模块# dur723: T50 PRO 上下水版(FARADAYSE_PRO_A_W_CN)按上游 PR #1835 对同款 q0n7xe 的做法映射到 T50 OMNIHARDWARE_ALIASES{q0n7xe:elrxgb,dur723:nxeux7}SUPPORTED_OUTLINE_VERSIONS(2,)def_patch_hardware()-bool:fromdeebot_clientimporthardware# noqa: PLC0415changedFalseforalias,sourceinHARDWARE_ALIASES.items():namef{hardware.__name__}.{alias}try:importlib.import_module(name)continue# 库里已有不需要补exceptModuleNotFoundError:passsys.modules[name]importlib.import_module(f{hardware.__name__}.{source})hardware._NOT_FOUND.discard(alias)# noqa: SLF001changedTrue_LOGGER.warning(已把硬件 ID %s 映射到 %s,alias,source)returnchangeddef_patch_map_info()-None:fromdeebot_client.messages.json.mapimportOnMapInfoV2# noqa: PLC0415ifgetattr(OnMapInfoV2,_ecovacs_patch,False):returnoriginalOnMapInfoV2._handle_body_data_dict.__func__# noqa: SLF001def_handle_body_data_dict(cls,event_bus,data):ifdata.get(outlineVer)inSUPPORTED_OUTLINE_VERSIONS:data{**data,outlineVer:1}returnoriginal(cls,event_bus,data)OnMapInfoV2._handle_body_data_dictclassmethod(_handle_body_data_dict)# noqa: SLF001OnMapInfoV2._ecovacs_patchTrue# noqa: SLF001_LOGGER.warning(已让 OnMapInfoV2 接受 outlineVer%s,SUPPORTED_OUTLINE_VERSIONS)asyncdefasync_setup(hass:HomeAssistant,config:ConfigType)-bool:hardware_changedawaithass.async_add_executor_job(_patch_hardware)awaithass.async_add_executor_job(_patch_map_info)# ecovacs 可能比本集成先加载完、已经错过了补丁重载一次让设备重新识别ifhardware_changed:forentryinhass.config_entries.async_entries(ecovacs):ifentry.stateisConfigEntryState.LOADED:hass.async_create_task(hass.config_entries.async_reload(entry.entry_id))returnTrue如果你的机器上报的是别的 class在HARDWARE_ALIASES里加一行就行比如0gxgac: nxeux7。可选的配置文件见 deebot_client/hardware 目录挑一个同系列的。2. 在 configuration.yaml 启用# 科沃斯 T50 Pro 补丁硬件ID别名 地图 outlineVer2ecovacs_patch:3. 检查配置并重启开发者工具 → YAML → 检查配置通过后重启 HASSH 里执行ha core check ha core restart也一样。日志里看到下面几行说明补丁已生效WARNING [custom_components.ecovacs_patch] 已把硬件 ID q0n7xe 映射到 elrxgb WARNING [custom_components.ecovacs_patch] 已把硬件 ID dur723 映射到 nxeux7 WARNING [custom_components.ecovacs_patch] 已让 OnMapInfoV2 接受 outlineVer(2,)另外会有一条We found a custom integration ecovacs_patch which has not been tested...所有自定义集成都会有这条不用管。4. 添加 Ecovacs 集成设置 → 设备与服务 → 添加集成 → 搜索Ecovacs填科沃斯 App 的账号和密码。如果之前已经加过、设备是空的补丁会自动重载没反应的话手动重新加载一次这个集成。四、效果我这台识别出 42 个实体其中 14 个诊断/配置类的默认禁用主要有vacuum.xxx开始/暂停/回充、吸力档位电量、基站状态、本次和累计清扫面积/时长主刷、边刷、滤网、尘袋、拖布、清洁液等耗材寿命以及对应的重置按钮拖布烘干、手动集尘、重定位按钮自动集尘频率、工作模式、水量档位、当前地图地图实体image.xxx_map通过/api/image_proxy返回 200 的 SVG五、注意事项先看自己的 class 再映射。同样叫 T50 PRO常见的就有q0n7xe、dur723、0gxgac几种日志里not recognized那一行写得很清楚。映射的是“相近型号”的配置上下水版特有的功能比如自动上下水相关设置可能没有对应实体这是正常的。个别命令如果机器不支持日志里可能会有少量 warning。补丁打在内存里HA 升级后照样生效。等上游正式支持你的型号后_patch_hardware会检测到库里已经有对应文件自动跳过到时候把custom_components/ecovacs_patch和 yaml 里那一行删掉就行。补丁依赖 deebot-client 的内部实现hardware._NOT_FOUND、OnMapInfoV2哪天库改了结构补丁可能会失效。升级后记得看一眼日志里那几行补丁提示还在不在。参考什么值得买HA 接入科沃斯 T50 PRO瀚思彼岸科沃斯 T50 Pro 接入 Home Assistant 并增加地图读取deebot-client PR #1835Add T50 PRO Water Supply Discharge versiondeebot-client PR #1797Accept outline version 2 in MapInfoV2 messagesdeebot-client issue #612如何添加新型号