matterbridge-ha-roborock

v3.4.4

Published

10 days ago

Matterbridge plugin for Roborock vacuums via Home Assistant

0High
0Medium
0Low

xmghelloword

matterbridge homeassistant roborock

Matterbridge HA Roborock

将 Home Assistant 中的 Roborock/Dreame 扫地机桥接到 Matter 生态系统，支持苹果家庭、Google Home 等 Matter 控制器。

✨ 功能特性

核心功能

🏠 完整的 Matter 扫地机支持：实现 RoboticVacuumCleaner 设备类型
🗺️ 区域清扫：支持选择特定房间进行清扫
📍 实时位置追踪：显示扫地机当前所在房间
🔋 电池监控：实时显示电量和充电状态
🎨 清洁模式：支持扫地、拖地、组合模式
🌪️ 风速调节：Silent、Standard、Medium、Turbo
⚡ 实时同步：通过 WebSocket 实时更新状态

Matter 集群支持

✅ PowerSource - 电源管理
✅ RvcOperationalState - 操作状态
✅ RvcRunMode - 运行模式
✅ RvcCleanMode - 清洁模式
✅ ServiceArea - 服务区域（分区清扫）
✅ Identify - 设备识别

📦 安装

通过 Matterbridge 安装（推荐）

安装 Matterbridge：

npm install -g matterbridge

安装插件：

matterbridge -add matterbridge-ha-roborock

手动安装

npm install -g matterbridge-ha-roborock

⚙️ 配置

方式一：通过 Matterbridge Web UI 配置（推荐）

启动 Matterbridge：

matterbridge

打开浏览器访问：http://localhost:8283
在插件列表中找到 matterbridge-ha-roborock，点击配置按钮
在 Web UI 中填写配置项：
- Home Assistant URL: 你的 HA 地址（如 http://192.168.1.100:8123）
- 长期访问令牌: 在 HA 中创建的令牌
- 设备白名单: 添加扫地机实体 ID（如 vacuum.dreame_vacuum_r2254）
- 传感器映射: 配置各种传感器的 entity_id
- 房间面积: 配置各房间面积用于计算清洁进度
保存配置并重启插件

方式二：手动编辑配置文件

在 Matterbridge 配置目录（通常是 ~/.matterbridge/）创建或编辑配置文件：

基础配置

{
  "name": "matterbridge-ha-roborock",
  "type": "AccessoryPlatform",
  "haUrl": "http://homeassistant.local:8123",
  "haToken": "your-long-lived-access-token",
  "deviceWhitelist": [
    "vacuum.dreame_vacuum_r2254"
  ]
}

完整配置（推荐）

{
  "name": "matterbridge-ha-roborock",
  "type": "AccessoryPlatform",
  "haUrl": "http://192.168.1.100:8123",
  "haToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "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.dreame_vacuum_r2254_current_room"
  },
  "cleanedAreaSensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area"
  },
  "roomAreaSizes": {
    "浴室": 5.5,
    "儿童房": 12.0,
    "卧室": 15.0,
    "阳光房": 10.0
  }
}

配置项说明

| 配置项 | 类型 | 必需 | 说明 | |--------|------|------|------| | haUrl | string | ✅ | Home Assistant 地址 | | haToken | string | ✅ | Home Assistant 长期访问令牌 | | deviceWhitelist | string[] | ✅ | 要桥接的扫地机实体 ID 列表 | | batterySensorMap | object | ⭐ | 电池电量传感器映射 | | chargingSensorMap | object | ⭐ | 充电状态传感器映射 | | cleaningModeEntityMap | object | ⭐ | 清洁模式实体映射 | | errorSensorMap | object | ⭐ | 错误传感器映射 | | currentRoomSensorMap | object | ⭐ | 当前房间传感器映射（v3.1.0+） | | cleanedAreaSensorMap | object | 🆕 | 已清洁面积传感器映射（v3.2.0+） | | roomAreaSizes | object | 🆕 | 房间面积配置，单位：平方米（v3.2.0+） |

⭐ = 强烈推荐配置以获得最佳体验
🆕 = 新功能，用于计算清洁进度

🚀 使用

1. 获取 Home Assistant 令牌

登录 Home Assistant
点击左下角用户名
滚动到"长期访问令牌"部分
点击"创建令牌"
复制令牌到配置文件

2. 启动 Matterbridge

matterbridge

3. 添加到苹果家庭

打开苹果家庭 App
点击右上角 "+"
选择"添加配件"
选择"更多选项"
找到"扫地机"并点击
输入 Matterbridge 显示的配对码

4. 开始使用

在苹果家庭中，你可以：

▶️ 启动/暂停清扫
🏠 返回充电座
🗺️ 选择房间清扫
🔋 查看电量和充电状态
📍 查看当前位置
📊 查看清洁进度（v3.2.0+）

📊 清洁进度功能（v3.2.0 新增）

功能说明

通过配置房间面积和已清洁面积传感器，系统可以自动计算：

清洁进度：实时显示清扫完成百分比（0-100%）
已清洁面积：显示已清扫的平方米数
预计结束时间：根据当前进度估算剩余时间

配置步骤

1. 添加已清洁面积传感器

在配置文件中添加 cleanedAreaSensorMap：

{
  "cleanedAreaSensorMap": {
    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area"
  }
}

2. 配置房间面积

在配置文件中添加 roomAreaSizes（单位：平方米）：

{
  "roomAreaSizes": {
    "浴室": 5.5,
    "儿童房": 12.0,
    "卧室": 15.0,
    "阳光房": 10.0
  }
}

注意：房间名称必须与 src/platform.ts 中 SUPPORTED_AREAS 的 locationName 完全一致。

3. 测量房间面积

如何获取房间面积：

在 Home Assistant 中查看扫地机的地图
使用扫地机 App 查看各房间面积
或手动测量：长度 × 宽度（米）

进度计算原理

清洁进度 = (已清洁面积 / 选择房间总面积) × 100%

预计剩余时间 = (已用时间 / 当前进度) × (100 - 当前进度)

示例：

选择房间：浴室(5.5m²) + 儿童房(12m²) = 17.5m²
已清洁面积：8.75m²
清洁进度：50%
已用时间：10分钟
预计剩余：10分钟

日志输出示例

🔄 cleaning | 85% | 未充电 | sweeping_and_mopping | Standard | 🏠 浴室 | 📊 45% | 🧹 7.9m²
   状态标志: 🏃 running | ▶️  started
   ⏱️  预计剩余: 8 分钟

🗺️ 区域清扫配置

定义房间映射

在 src/platform.ts 中配置你的房间映射：

// Matter Area ID -> Dreame Segment ID
const AREA_TO_SEGMENT_MAP: Record<number, string> = {
  1: '3',  // 浴室 -> Dreame segment 3
  2: '4',  // 儿童房 -> Dreame segment 4
  3: '5',  // 卧室 -> Dreame segment 5
  4: '6',  // 阳光房 -> Dreame segment 6
};

// HA 房间名称 -> Matter Area ID
const ROOM_NAME_TO_AREA_ID: Record<string, number | null> = {
  '浴室': 1,
  '儿童房': 2,
  '卧室': 3,
  '阳光房': 4,
  '过道': null,
  '充电座': null,
};

// 支持的区域定义
const SUPPORTED_AREAS = [
  {
    areaId: 1,
    areaInfo: {
      locationInfo: { locationName: '浴室' }
    }
  },
  // ... 更多房间
];

获取 Dreame Segment ID

在 Home Assistant 开发者工具中调用服务：

service: dreame_vacuum.vacuum_clean_segment
target:
  entity_id: vacuum.dreame_vacuum_r2254
data:
  segments: [3, 4, 5]  # 这些就是 segment ID

📊 状态映射

HA 状态 → Matter 操作状态

| HA State | Matter OperationalState | 显示 | |----------|------------------------|------| | docked | Docked (6) | 已充电 | | charging | Charging (5) | 充电中 | | cleaning + running=true | Running (1) | 正在清扫 | | cleaning + started=true | SeekingCharger (4) | 正在行进 | | returning | SeekingCharger (4) | 返回中 | | paused | Paused (2) | 已暂停 | | error | Error (3) | 错误 |

HA 状态 → Matter 运行模式

| HA State | Matter RunMode | 显示 | |----------|---------------|------| | docked, idle | Idle (1) | 空闲 | | cleaning | Cleaning (2) | 清扫中 | | mapping | Mapping (3) | 建图中 |

🔧 开发

环境要求

Node.js >= 18.0.0
TypeScript >= 5.3.0
Matterbridge >= 3.0.0

本地开发

# 克隆仓库
git clone https://github.com/yourusername/matterbridge-ha-roborock.git
cd matterbridge-ha-roborock

# 安装依赖
npm install

# 构建
npm run build

# 监听模式
npm run watch

# 测试连接
npm test

项目结构

matterbridge-ha-roborock/
├── src/
│   ├── index.ts                    # 插件入口
│   ├── platform.ts                 # 核心平台逻辑
│   ├── platform-config.ts          # 配置定义
│   ├── homeassistant-client.ts     # HA 客户端
│   └── ha-vacuum-controller.ts     # 扫地机控制器
├── test/
│   └── test-connection.ts          # 连接测试
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

🐛 故障排查

扫地机未显示

检查 HA 连接：

curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://homeassistant.local:8123/api/states/vacuum.your_vacuum

检查 Matterbridge 日志：

tail -f ~/.matterbridge/logs/matterbridge.log

区域清扫不工作

验证 segment ID 映射是否正确
在 HA 中手动测试 dreame_vacuum.vacuum_clean_segment 服务
检查 AREA_TO_SEGMENT_MAP 配置

返回基站无响应

确保使用 v3.1.0 或更高版本
检查 HA 中 vacuum.return_to_base 服务是否可用

📝 更新日志

查看 CHANGELOG.md 了解详细更新历史。

v3.1.0 (2024-12-31)

✨ 新增 currentArea 支持，实时显示当前房间
🎯 优化区域清扫状态映射
🏠 修复返回基站功能
🔄 移除轮询机制，完全依赖 WebSocket

v3.0.0 (2024-12-30)

🎉 初始版本发布

📄 许可证

MIT License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

🙏 致谢

Matterbridge - Matter 桥接框架
Home Assistant - 智能家居平台
Matter - 智能家居标准

📞 支持

📧 Email: [email protected]
💬 Issues: GitHub Issues
📖 文档: Wiki

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