Matterbridge HA Dreame

将 Home Assistant 中的 Roborock/Dreame 扫地机桥接到 Matter 生态系统（Apple Home / Google Home / Matter 控制器）。

✨ 功能特性

核心功能

• 🧹 完整的 Matter RVC 设备：RoboticVacuumCleaner 设备类型
• 🗺️ Service Area 区域清扫：选择房间、显示当前区域
• 🧭 地图支持：从 HA select.* 读取地图列表
• 🔋 电池与充电状态：PowerSource 集群
• 🎛️ 清洁/运行模式：RvcCleanMode + RvcRunMode
• ⚡ 实时同步：WebSocket 实时更新状态
• 🧱 Mapping 模式：调用 HA 的快速建图按钮

Matter 集群支持

• ✅ PowerSource
• ✅ RvcOperationalState
• ✅ RvcRunMode
• ✅ RvcCleanMode
• ✅ ServiceArea
• ✅ HepaFilterMonitoring
• ✅ Identify

进度与时间（v4.x）

• ServiceArea.progress 支持按房间估算
• estimatedTime 支持倒计时测试
• EstimatedEndTime 和 CountdownTime 由配置计算

📦 安装

Matterbridge 安装（推荐）

npm install -g matterbridge
matterbridge -add matterbridge-ha-dreame

直接安装

npm install -g matterbridge-ha-dreame

⚙️ 配置

方式一：Matterbridge Web UI（推荐）

1. 启动 Matterbridge：

   matterbridge

2. 打开 http://localhost:8283
3. 找到插件 matterbridge-ha-dreame → 配置

方式二：配置文件

配置文件路径（默认）：

~/.matterbridge/matterbridge-ha-dreame.config.json

完整示例（推荐）

{
  "name": "matterbridge-ha-dreame",
  "type": "AccessoryPlatform",
  "haUrl": "http://192.168.1.100:8123",
  "haToken": "YOUR_LONG_LIVED_ACCESS_TOKEN_HERE",
  "deviceWhitelist": [
    "vacuum.dreame_vacuum_r2254"
  ],
  "batterySensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_battery_level"
  },
  "chargingSensorMap": {
    "vacuum.dreame_vacuum_r2254": "binary_sensor.dreame_vacuum_r2254_charging_state"
  },
  "cleaningModeEntityMap": {
    "vacuum.dreame_vacuum_r2254": "select.dreame_vacuum_r2254_cleaning_mode"
  },
  "errorSensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_error"
  },
  "currentRoomSensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.sao_di_ji_current_room"
  },
  "stateSensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_state"
  },
  "taskStatusSensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_task_status"
  },
  "selectedMapEntityMap": {
    "vacuum.dreame_vacuum_r2254": "select.sao_di_ji_selected_map"
  },
  "fastMappingButtonMap": {
    "vacuum.dreame_vacuum_r2254": "button.dreame_vacuum_r2254_start_fast_mapping"
  },
  "cleanedAreaSensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area"
  },
  "cleaningTimeSensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaning_time"
  },
  "roomAreaSizes": {
    "浴室": 5.5,
    "儿童房": 12.0,
    "卧室": 15.0,
    "阳光房": 10.0
  },
  "roomCleaningDuration": {
    "浴室": 480,
    "儿童房": 1200,
    "卧室": 1500,
    "阳光房": 900
  },
  "progressEstimatedTimeCountdown": true,
  "countdownTimeSeconds": null,
  "phaseList": [
    "清扫中",
    "返回充电座",
    "清洗拖布",
    "已完成"
  ],
  "debug": false
}

关键配置项说明

| 配置项 | 说明 | |---|---| | haUrl, haToken | Home Assistant 连接参数（必填） | | deviceWhitelist | 需要桥接的扫地机实体 ID | | stateSensorMap | 详细状态传感器（用于更准的运行判断） | | taskStatusSensorMap | 任务状态（过滤任务启动前充电状态） | | selectedMapEntityMap | 地图列表来源（HA select 实体） | | fastMappingButtonMap | Mapping 模式对应的 HA button | | roomCleaningDuration | 每个房间的估计清扫时长（秒） | | progressEstimatedTimeCountdown | estimatedTime 倒计时测试 | | countdownTimeSeconds | 固定 CountdownTime（不设置则自动求和） |

房间名称必须与扫地机当前地图中的房间名称一致，否则进度无法匹配。

⏱️ 进度与时间逻辑

• ServiceArea.progress[].estimatedTime：
  • 来源：roomCleaningDuration
  • 若启用 progressEstimatedTimeCountdown，会从配置时长倒计时
• ServiceArea.estimatedEndTime：
  • 当前实现为 所有房间 estimatedTime 的和（倒计时秒数）
• RvcOperationalState.countdownTime：
  • 默认使用所有房间 estimatedTime 的总和
  • 若 countdownTimeSeconds 有值则使用固定秒数

这套逻辑用于测试 Apple Home 是否显示进度条，后续可对接真实耗时。

🗺️ 地图支持

• 插件从 selectedMapEntityMap 指定的 HA select.* 获取地图列表
• 当前地图会优先读取 HA 的 map_id / map_index
• 可选 mapIdMap 用于手动稳定映射（可不配）

🧭 Mapping 模式

• Matter 运行模式映射到 Mapping 时，会调用 HA fastMappingButtonMap
• 需要 HA 中存在类似 button.*_start_fast_mapping

🚀 使用

1. 启动 Matterbridge：

matterbridge

2. 在 Apple Home / Google Home 中添加配件

3. 通过控制器：

• 启动/暂停/返回基站
• 选择房间清扫
• 查看电量、进度、当前区域

🐛 常见问题

设备未发现

• 检查 haUrl/haToken
• 确认 deviceWhitelist 是否包含目标扫地机

进度显示为 null

• 需要配置 roomCleaningDuration
• 房间名必须与地图房间一致

Mapping 模式无效

• 检查 fastMappingButtonMap 是否正确
• 手动在 HA 中点一次按钮验证

🔧 开发

npm install
npm run build
npm run watch

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request：

• https://github.com/wdxst/matterbridge-ha-dreame/issues

如果这个项目对你有帮助，请给个 ⭐ Star！