matterbridge-ha-roborock 3.1.0 → 3.3.0

package/PROGRESS_FEATURE.md

@@ -0,0 +1,488 @@
+# 📊 清洁进度功能详细说明
+
+## 🎯 功能概述
+
+v3.2.0 新增的清洁进度功能，通过已清洁面积传感器和房间面积配置，实时计算清扫进度和预计结束时间。
+
+---
+
+## ✨ 功能特性
+
+### 1. 实时进度显示
+- **清洁进度**：0-100% 的百分比显示
+- **已清洁面积**：实时显示已清扫的平方米数
+- **预计剩余时间**：智能估算完成清扫所需时间
+
+### 2. 自动计算
+- 根据选择的房间自动计算总面积
+- 实时更新清洁进度
+- 动态调整预计结束时间
+
+### 3. 多场景支持
+- ✅ 单房间清扫
+- ✅ 多房间清扫
+- ✅ 全屋清扫
+
+---
+
+## 🔧 配置指南
+
+### 完整配置示例
+
+```json
+{
+  "name": "matterbridge-ha-roborock",
+  "type": "AccessoryPlatform",
+  "haUrl": "http://192.168.1.100:8123",
+  "haToken": "your-long-lived-access-token",
+  "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"
+  },
+  "cleanedAreaSensorMap": {
+    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area"
+  },
+  "roomAreaSizes": {
+    "浴室": 5.5,
+    "儿童房": 12.0,
+    "卧室": 15.0,
+    "阳光房": 10.0
+  }
+}
+```
+
+### 配置项详解
+
+#### cleanedAreaSensorMap（必需）
+
+**作用**：映射扫地机的已清洁面积传感器
+
+**格式**：
+```json
+{
+  "vacuum实体ID": "已清洁面积传感器ID"
+}
+```
+
+**如何查找传感器ID**：
+
+1. 在 Home Assistant 中进入"开发者工具" → "状态"
+2. 搜索您的扫地机名称
+3. 查找包含 `cleaned_area` 或类似名称的传感器
+4. 常见命名格式：
+   - `sensor.扫地机名称_cleaned_area`
+   - `sensor.扫地机名称_total_cleaned_area`
+   - `sensor.扫地机名称_cleaning_area`
+
+**示例**：
+```json
+"cleanedAreaSensorMap": {
+  "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area",
+  "vacuum.roborock_s7": "sensor.roborock_s7_cleaned_area"
+}
+```
+
+#### roomAreaSizes（必需）
+
+**作用**：定义每个房间的面积（平方米）
+
+**格式**：
+```json
+{
+  "房间名称": 面积数值
+}
+```
+
+**重要提示**：
+- 房间名称必须与 `src/platform.ts` 中 `SUPPORTED_AREAS` 的 `locationName` 完全一致
+- 面积单位：平方米（m²）
+- 支持小数（如 5.5）
+
+**如何测量房间面积**：
+
+方法1：使用扫地机 App
+- 打开扫地机官方 App
+- 查看地图中各房间的面积信息
+- 直接使用 App 显示的数值
+
+方法2：查看 Home Assistant
+- 某些集成会提供房间面积属性
+- 在实体属性中查找 `room_area` 或类似字段
+
+方法3：手动测量
+- 使用卷尺测量房间长度和宽度
+- 计算：面积 = 长度(米) × 宽度(米)
+- 对于不规则房间，可以分块计算后相加
+
+**示例**：
+```json
+"roomAreaSizes": {
+  "客厅": 25.5,      // 5.1m × 5.0m
+  "主卧": 18.0,      // 4.5m × 4.0m
+  "次卧": 12.0,      // 4.0m × 3.0m
+  "厨房": 8.5,       // 3.4m × 2.5m
+  "浴室": 5.5,       // 2.2m × 2.5m
+  "阳台": 6.0        // 3.0m × 2.0m
+}
+```
+
+---
+
+## 📐 进度计算原理
+
+### 计算公式
+
+```typescript
+// 1. 计算选择房间的总面积
+总面积 = Σ(选择的每个房间面积)
+
+// 2. 计算清洁进度
+清洁进度(%) = (已清洁面积 / 总面积) × 100
+
+// 3. 计算预计结束时间
+已用时间 = 当前时间 - 清扫开始时间
+预计总时间 = (已用时间 / 当前进度) × 100
+预计剩余时间 = 预计总时间 - 已用时间
+```
+
+### 计算示例
+
+**场景**：清扫浴室 + 儿童房
+
+```
+配置：
+  浴室面积：5.5 m²
+  儿童房面积：12.0 m²
+  总面积：17.5 m²
+
+清扫过程：
+  T0 (开始)：
+    已清洁面积：0 m²
+    进度：0%
+    预计剩余：计算中...
+  
+  T5 (5分钟后)：
+    已清洁面积：4.4 m²
+    进度：25%
+    已用时间：5 分钟
+    预计总时间：20 分钟
+    预计剩余：15 分钟
+  
+  T10 (10分钟后)：
+    已清洁面积：8.8 m²
+    进度：50%
+    已用时间：10 分钟
+    预计总时间：20 分钟
+    预计剩余：10 分钟
+  
+  T18 (18分钟后)：
+    已清洁面积：17.5 m²
+    进度：100%
+    完成！
+```
+
+---
+
+## 📝 使用流程
+
+### 1. 在 Apple Home 中选择房间
+
+1. 打开苹果家庭 App
+2. 找到扫地机设备
+3. 点击进入详情
+4. 选择要清扫的房间（如：浴室、儿童房）
+
+### 2. 开始清扫
+
+点击"开始清扫"按钮，系统会：
+- 记录清扫开始时间
+- 设置选择的房间列表
+- 开始监听已清洁面积传感器
+
+### 3. 实时监控进度
+
+在日志中可以看到：
+
+```
+📍 选择区域: 浴室、儿童房
+▶️  继续清扫
+🗺️  清扫区域: Matter[1,2] → Dreame[2,3]
+
+🔄 cleaning | 85% | 未充电 | sweeping_and_mopping | Standard | 🏠 过道 | 📊 0% | 🧹 0.0m²
+   状态标志: ▶️  started
+
+🔄 cleaning | 84% | 未充电 | sweeping_and_mopping | Standard | 🏠 浴室 | 📊 15% | 🧹 2.6m²
+   状态标志: 🏃 running | ▶️  started
+   ⏱️  预计剩余: 12 分钟
+
+🔄 cleaning | 82% | 未充电 | sweeping_and_mopping | Standard | 🏠 浴室 | 📊 31% | 🧹 5.4m²
+   状态标志: 🏃 running | ▶️  started
+   ⏱️  预计剩余: 9 分钟
+
+🔄 cleaning | 80% | 未充电 | sweeping_and_mopping | Standard | 🏠 儿童房 | 📊 68% | 🧹 11.9m²
+   状态标志: 🏃 running | ▶️  started
+   ⏱️  预计剩余: 4 分钟
+
+🔄 returning | 75% | 未充电 | sweeping_and_mopping | Standard | 🏠 过道
+   状态标志: 🔙 returning
+```
+
+### 4. 清扫完成
+
+当扫地机返回充电座时，进度信息会自动重置。
+
+---
+
+## 🎨 日志说明
+
+### 进度相关日志标记
+
+| 标记 | 说明 | 示例 |
+|------|------|------|
+| 📊 | 清洁进度百分比 | 📊 45% |
+| 🧹 | 已清洁面积 | 🧹 7.9m² |
+| ⏱️ | 预计剩余时间 | ⏱️ 预计剩余: 8 分钟 |
+| 🏠 | 当前所在房间 | 🏠 浴室 |
+
+### 完整日志示例
+
+```
+[2025-01-01 10:00:00] 📝 vacuum.dreame_vacuum_r2254
+[2025-01-01 10:00:00]    电池: sensor.dreame_vacuum_r2254_battery_level
+[2025-01-01 10:00:00]    充电: binary_sensor.dreame_vacuum_r2254_charging_state
+[2025-01-01 10:00:00]    模式: select.dreame_vacuum_r2254_cleaning_mode
+[2025-01-01 10:00:00]    错误: sensor.dreame_vacuum_r2254_error
+[2025-01-01 10:00:00]    房间: sensor.sao_di_ji_current_room
+[2025-01-01 10:00:00]    面积: sensor.dreame_vacuum_r2254_cleaned_area
+[2025-01-01 10:00:00]    房间面积: 浴室:5.5m², 儿童房:12.0m², 卧室:15.0m², 阳光房:10.0m²
+
+[2025-01-01 10:05:00] 📍 选择区域: 浴室、儿童房
+[2025-01-01 10:05:01] ▶️  继续清扫
+[2025-01-01 10:05:01] 🗺️  清扫区域: Matter[1,2] → Dreame[2,3]
+
+[2025-01-01 10:05:05] 🔄 cleaning | 85% | 未充电 | sweeping_and_mopping | Standard | 🏠 过道 | 📊 0% | 🧹 0.0m²
+[2025-01-01 10:05:05]    状态标志: ▶️  started
+
+[2025-01-01 10:06:30] 🔄 cleaning | 84% | 未充电 | sweeping_and_mopping | Standard | 🏠 浴室 | 📊 25% | 🧹 4.4m²
+[2025-01-01 10:06:30]    🚪 房间变化: 过道 → 浴室 (isAreaCleaning: true)
+[2025-01-01 10:06:30]    状态标志: 🏃 running | ▶️  started
+[2025-01-01 10:06:30]    ⏱️  预计剩余: 4 分钟
+[2025-01-01 10:06:30]    🎯 已到达清扫区域: 浴室，开始清扫！
+
+[2025-01-01 10:10:00] 🔄 cleaning | 80% | 未充电 | sweeping_and_mopping | Standard | 🏠 儿童房 | 📊 75% | 🧹 13.1m²
+[2025-01-01 10:10:00]    🚪 房间变化: 浴室 → 儿童房 (isAreaCleaning: true)
+[2025-01-01 10:10:00]    状态标志: 🏃 running | ▶️  started
+[2025-01-01 10:10:00]    ⏱️  预计剩余: 2 分钟
+[2025-01-01 10:10:00]    🎯 已到达清扫区域: 儿童房，开始清扫！
+
+[2025-01-01 10:12:30] 🔄 returning | 75% | 未充电 | sweeping_and_mopping | Standard | 🏠 过道
+[2025-01-01 10:12:30]    状态标志: 🔙 returning
+```
+
+---
+
+## 🐛 故障排查
+
+### 问题 1：进度一直显示 0%
+
+**可能原因**：
+1. 未配置 `cleanedAreaSensorMap`
+2. 未配置 `roomAreaSizes`
+3. 传感器 ID 错误
+4. 房间名称不匹配
+
+**解决方法**：
+
+```bash
+# 1. 检查传感器是否存在
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://YOUR_HA_URL:8123/api/states/sensor.dreame_vacuum_r2254_cleaned_area
+
+# 2. 检查传感器值
+# 应该返回类似：{"state": "12.5", ...}
+
+# 3. 检查配置文件
+cat ~/.matterbridge/matterbridge-ha-roborock.config.json
+
+# 4. 检查日志
+tail -f ~/.matterbridge/logs/matterbridge.log | grep "面积"
+```
+
+### 问题 2：预计时间不准确
+
+**原因**：
+- 预计时间基于当前速度估算
+- 扫地机速度会变化（不同房间、障碍物等）
+- 初期估算误差较大，后期会更准确
+
+**正常现象**：
+- 清扫初期（0-20%）：预计时间波动较大
+- 清扫中期（20-80%）：预计时间逐渐稳定
+- 清扫后期（80-100%）：预计时间最准确
+
+### 问题 3：房间面积不知道怎么设置
+
+**推荐方法**：
+
+1. **使用扫地机 App**（最准确）
+   - 打开官方 App（米家、Dreame 等）
+   - 查看地图，App 通常会显示各房间面积
+
+2. **运行一次全屋清扫**
+   - 让扫地机完整清扫一次
+   - 查看总清洁面积
+   - 按房间占比估算
+
+3. **保守估算**
+   - 先设置一个大概值
+   - 观察几次清扫后调整
+   - 进度达到 100% 时清扫应该刚好完成
+
+### 问题 4：日志中没有进度信息
+
+**检查清单**：
+
+```bash
+# 1. 确认已编译最新代码
+cd /Users/xmg/Projects/matterbridge-ha-roborock
+npm run build
+
+# 2. 确认配置文件正确
+cat config.json | grep -A 5 "cleanedAreaSensorMap"
+cat config.json | grep -A 10 "roomAreaSizes"
+
+# 3. 重启 Matterbridge
+# 停止并重新启动 Matterbridge 服务
+
+# 4. 查看启动日志
+tail -f ~/.matterbridge/logs/matterbridge.log | grep "面积"
+# 应该看到：
+#   面积: sensor.dreame_vacuum_r2254_cleaned_area
+#   房间面积: 浴室:5.5m², 儿童房:12.0m², ...
+```
+
+---
+
+## 💡 使用技巧
+
+### 1. 精确测量房间面积
+
+```bash
+# 在 Home Assistant 中运行一次单房间清扫
+# 然后查看该房间的清洁面积
+
+# 例如：清扫浴室
+# 查看 sensor.dreame_vacuum_r2254_cleaned_area
+# 假设显示 5.3m²，则配置：
+"浴室": 5.3
+```
+
+### 2. 处理不规则房间
+
+对于 L 型或不规则房间：
+- 分块测量后相加
+- 或使用扫地机 App 显示的面积
+- 可以略微放大 5-10%（考虑重复清扫区域）
+
+### 3. 优化预计时间准确性
+
+- 保持房间整洁，减少障碍物
+- 使用稳定的清扫模式
+- 多次清扫后，系统会"学习"平均速度
+
+### 4. 全屋清扫进度
+
+如果想显示全屋清扫进度：
+- 在 `roomAreaSizes` 中配置所有房间
+- 系统会自动累加所有房间面积
+
+---
+
+## 📊 技术细节
+
+### VacuumState 接口扩展
+
+```typescript
+export interface VacuumState {
+  // ... 原有字段
+  cleanedArea?: number;        // 已清洁面积（m²）
+  progress?: number;           // 清洁进度（0-100）
+  estimatedEndTime?: number;   // 预计结束时间（Unix时间戳）
+}
+```
+
+### 进度计算逻辑
+
+```typescript
+private calculateProgress(
+  state: string,
+  cleanedArea?: number,
+  currentRoom?: string
+): { progress?: number; estimatedEndTime?: number } {
+  // 只在清扫状态下计算
+  if (state !== 'cleaning') {
+    return { progress: undefined, estimatedEndTime: undefined };
+  }
+
+  // 计算选择房间的总面积
+  const totalArea = this.selectedRoomNames.reduce((sum, roomName) => {
+    return sum + (this.roomAreaSizes![roomName] || 0);
+  }, 0);
+
+  // 计算进度
+  const progress = Math.min(100, Math.round((cleanedArea / totalArea) * 100));
+
+  // 计算预计结束时间
+  const elapsedTime = Date.now() - this.cleaningStartTime;
+  const estimatedTotalTime = (elapsedTime / progress) * 100;
+  const estimatedEndTime = this.cleaningStartTime + estimatedTotalTime;
+
+  return { progress, estimatedEndTime };
+}
+```
+
+---
+
+## 🔄 版本历史
+
+### v3.2.0 (2025-01-01)
+- ✨ 新增清洁进度计算功能
+- ✨ 新增预计结束时间估算
+- ✨ 新增已清洁面积显示
+- 📝 新增 `cleanedAreaSensorMap` 配置项
+- 📝 新增 `roomAreaSizes` 配置项
+- 🎨 优化日志输出，显示进度信息
+
+---
+
+## 🤝 贡献
+
+如果您有改进建议或发现问题，欢迎：
+- 提交 Issue
+- 提交 Pull Request
+- 分享使用经验
+
+---
+
+## 📄 许可证
+
+MIT License
+
+---
+
+**如果这个功能对你有帮助，请给个 ⭐ Star！**
+

package/README.md

@@ -87,6 +87,15 @@ npm install -g matterbridge-ha-roborock
   },
   "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
   }
 }
 ```
@@ -103,8 +112,11 @@ npm install -g matterbridge-ha-roborock
 | `cleaningModeEntityMap` | object | ⭐ | 清洁模式实体映射 |
 | `errorSensorMap` | object | ⭐ | 错误传感器映射 |
 | `currentRoomSensorMap` | object | ⭐ | 当前房间传感器映射（v3.1.0+） |
+| `cleanedAreaSensorMap` | object | 🆕 | 已清洁面积传感器映射（v3.2.0+） |
+| `roomAreaSizes` | object | 🆕 | 房间面积配置，单位：平方米（v3.2.0+） |
 
-⭐ = 强烈推荐配置以获得最佳体验
+⭐ = 强烈推荐配置以获得最佳体验  
+🆕 = 新功能，用于计算清洁进度
 
 ## 🚀 使用
 
@@ -139,6 +151,77 @@ matterbridge
 - 🗺️ 选择房间清扫
 - 🔋 查看电量和充电状态
 - 📍 查看当前位置
+- 📊 查看清洁进度（v3.2.0+）
+
+## 📊 清洁进度功能（v3.2.0 新增）
+
+### 功能说明
+
+通过配置房间面积和已清洁面积传感器，系统可以自动计算：
+- **清洁进度**：实时显示清扫完成百分比（0-100%）
+- **已清洁面积**：显示已清扫的平方米数
+- **预计结束时间**：根据当前进度估算剩余时间
+
+### 配置步骤
+
+#### 1. 添加已清洁面积传感器
+
+在配置文件中添加 `cleanedAreaSensorMap`：
+
+```json
+{
+  "cleanedAreaSensorMap": {
+    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area"
+  }
+}
+```
+
+#### 2. 配置房间面积
+
+在配置文件中添加 `roomAreaSizes`（单位：平方米）：
+
+```json
+{
+  "roomAreaSizes": {
+    "浴室": 5.5,
+    "儿童房": 12.0,
+    "卧室": 15.0,
+    "阳光房": 10.0
+  }
+}
+```
+
+**注意**：房间名称必须与 `src/platform.ts` 中 `SUPPORTED_AREAS` 的 `locationName` 完全一致。
+
+#### 3. 测量房间面积
+
+如何获取房间面积：
+1. 在 Home Assistant 中查看扫地机的地图
+2. 使用扫地机 App 查看各房间面积
+3. 或手动测量：长度 × 宽度（米）
+
+### 进度计算原理
+
+```
+清洁进度 = (已清洁面积 / 选择房间总面积) × 100%
+
+预计剩余时间 = (已用时间 / 当前进度) × (100 - 当前进度)
+```
+
+**示例**：
+- 选择房间：浴室(5.5m²) + 儿童房(12m²) = 17.5m²
+- 已清洁面积：8.75m²
+- 清洁进度：50%
+- 已用时间：10分钟
+- 预计剩余：10分钟
+
+### 日志输出示例
+
+```
+🔄 cleaning | 85% | 未充电 | sweeping_and_mopping | Standard | 🏠 浴室 | 📊 45% | 🧹 7.9m²
+   状态标志: 🏃 running | ▶️  started
+   ⏱️  预计剩余: 8 分钟
+```
 
 ## 🗺️ 区域清扫配置
 

package/RELEASE_CHECKLIST.md

@@ -176,3 +176,4 @@ npm install -g matterbridge-ha-roborock
 **发布日期**: _______________
 **发布人**: _______________
 
+

package/config.json

@@ -6,5 +6,29 @@
   "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"
+  },
+  "cleanedAreaSensorMap": {
+    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area"
+  },
+  "roomAreaSizes": {
+    "浴室": 5.5,
+    "儿童房": 12.0,
+    "卧室": 15.0,
+    "阳光房": 10.0
+  },
   "debug": true
 }