matterbridge-ha-roborock 3.0.0 → 3.3.0

package/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [3.3.0] - 2025-01-01
+
+### Added
+- ✨ **ServiceArea.estimatedEndTime 属性**：完全符合 Matter 规范
+  - 新增整个清扫任务的预计完成时间点（Unix 时间戳）
+  - 根据所有未完成区域的 estimatedTime 自动计算
+  - 只在 cleaning 状态下提供有效值
+  - 实时动态更新，随清扫进度调整
+
+### Changed
+- 🎯 **Progress 数组优化**：
+  - 改进 estimatedTime 计算逻辑
+  - 优化 totalOperationalTime 数据来源
+  - 增强状态判断准确性
+
+### Fixed
+- 🐛 **HEPA 滤网监控**：
+  - 移除未完成的 HepaFilterMonitoring 功能调用
+  - 避免 "cluster not found" 错误
+
+## [3.2.0] - 2025-01-01
+
+### Added
+- ✨ **清洁进度功能**：实时显示清扫进度和预计结束时间
+  - 新增 `cleanedAreaSensorMap` 配置项，映射已清洁面积传感器
+  - 新增 `roomAreaSizes` 配置项，定义各房间面积（平方米）
+  - 自动计算清洁进度百分比（0-100%）
+  - 智能估算预计结束时间和剩余时间
+  
+- 📊 **VacuumState 扩展**：
+  - 新增 `cleanedArea` 字段：已清洁面积（m²）
+  - 新增 `progress` 字段：清洁进度（0-100）
+  - 新增 `estimatedEndTime` 字段：预计结束时间戳
+  
+- 🎯 **智能进度计算**：
+  - 基于选择房间总面积和已清洁面积计算进度
+  - 支持单房间、多房间、全屋清扫进度显示
+  - 动态调整预计完成时间
+
+### Changed
+- 🎨 **日志增强**：
+  - 添加清洁进度显示（📊 45%）
+  - 添加已清洁面积显示（🧹 7.9m²）
+  - 添加预计剩余时间显示（⏱️ 预计剩余: 8 分钟）
+  
+- 🔧 **HAVacuumController 优化**：
+  - 新增 `setSelectedRooms()` 方法设置选择的房间
+  - 新增 `calculateProgress()` 方法计算进度
+  - 自动监听已清洁面积传感器变化
+
+### Documentation
+- 📝 新增 `PROGRESS_FEATURE.md` 详细功能说明文档
+- 📝 更新 `README.md` 添加清洁进度配置说明
+- 📝 更新 `config.json` 示例配置
+
+### Technical Details
+- 进度计算公式：`progress = (cleanedArea / totalArea) × 100`
+- 时间估算公式：`estimatedTime = (elapsedTime / progress) × 100`
+- 支持实时 WebSocket 更新，< 1 秒响应
+
+---
+
+## [3.1.0] - 2024-12-31
+
+### Added
+- ✨ **ServiceArea.currentArea 支持**：实时追踪扫地机当前所在房间
+  - 新增 `currentRoomSensorMap` 配置项，支持映射 HA 房间传感器
+  - 自动将中文房间名转换为 Matter Area ID
+  - 房间变化时自动更新 `currentArea` 属性
+  
+- 🎯 **区域清扫状态优化**：
+  - 改进状态映射逻辑，依赖 HA 的 `running` 属性
+  - 选区清扫开始时正确显示 "正在行进" (SeekingCharger)
+  - 进入房间后自动切换为 "正在清扫" (Running)
+  
+- 🏠 **返回基站功能修复**：
+  - 修复苹果家庭"返回基站"按钮无响应问题
+  - 添加 `RvcRunMode.Idle` 模式处理，正确触发返回充电座
+
+### Changed
+- 🔄 **状态同步机制优化**：
+  - 移除 15 秒延迟刷新机制
+  - 移除 30 秒轮询备份机制
+  - 完全依赖 WebSocket 实时推送，响应更快
+  
+- 📊 **日志增强**：
+  - 添加房间变化检测日志
+  - 添加 `currentArea` 更新日志
+  - 优化操作状态显示（Transitioning⏳、ChargingTransition⚡）
+
+### Fixed
+- 🐛 修复 `changeToMode` 命令未处理 Idle 模式的问题
+- 🐛 修复区域清扫时状态映射优先级错误
+- 🐛 修复 `isAreaCleaning` 标记未正确重置的问题
+
+### Technical Details
+- 新增 `ROOM_NAME_TO_AREA_ID` 映射表
+- 新增 `getRoomAreaId()` 辅助方法
+- 优化 `mapHAStateToOperationalState()` 状态映射逻辑
+- 增强 `HAVacuumController` 支持房间传感器监听
+
+---
+
+## [3.0.0] - 2024-12-30
+
+### Added
+- 🎉 初始版本发布
+- ✨ 支持 Home Assistant 扫地机桥接到 Matter
+- 🏠 支持 Roborock/Dreame 扫地机
+- 🗺️ 支持区域清扫（ServiceArea 集群）
+- 🔋 支持电池状态监控
+- 🎨 支持清洁模式切换（扫地、拖地、组合模式）
+- 🌪️ 支持风速调节（Silent、Standard、Medium、Turbo）
+- ⚙️ 支持传感器映射配置
+- 🔌 WebSocket 实时状态同步
+- 📡 REST API 命令控制
+
+### Supported Clusters
+- PowerSource (电源)
+- RvcOperationalState (操作状态)
+- RvcRunMode (运行模式)
+- RvcCleanMode (清洁模式)
+- ServiceArea (服务区域)
+- Identify (识别)
+
+---
+
+## Version History
+
+- **3.2.0** - 清洁进度功能 + 预计结束时间 + 已清洁面积显示
+- **3.1.0** - CurrentArea 支持 + 状态优化 + 返回基站修复
+- **3.0.0** - 初始版本
+
+

package/FEATURE_SUMMARY_v3.2.0.md

@@ -0,0 +1,287 @@
+# 🎉 v3.2.0 功能摘要
+
+## ✨ 新增功能：清洁进度追踪
+
+通过已清洁面积传感器和房间面积配置，实现智能清洁进度计算和预计结束时间估算。
+
+---
+
+## 📋 实现的功能
+
+### 1. ✅ 清洁进度百分比
+- 实时显示 0-100% 的清洁进度
+- 基于已清洁面积 / 选择房间总面积计算
+- 支持单房间、多房间、全屋清扫
+
+### 2. ✅ 已清洁面积显示
+- 实时显示已清扫的平方米数
+- 从 Home Assistant 传感器获取
+- 精确到小数点后一位
+
+### 3. ✅ 预计结束时间
+- 智能估算完成清扫所需时间
+- 显示预计剩余分钟数
+- 动态调整，越清扫越准确
+
+### 4. ✅ 配置项扩展
+- `cleanedAreaSensorMap`：已清洁面积传感器映射
+- `roomAreaSizes`：房间面积配置（平方米）
+
+### 5. ✅ 日志增强
+- 📊 清洁进度显示
+- 🧹 已清洁面积显示
+- ⏱️ 预计剩余时间显示
+
+---
+
+## 🔧 配置示例
+
+```json
+{
+  "name": "matterbridge-ha-roborock",
+  "type": "AccessoryPlatform",
+  "haUrl": "http://192.168.1.100:8123",
+  "haToken": "your-token",
+  "deviceWhitelist": ["vacuum.dreame_vacuum_r2254"],
+  
+  "cleanedAreaSensorMap": {
+    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area"
+  },
+  
+  "roomAreaSizes": {
+    "浴室": 5.5,
+    "儿童房": 12.0,
+    "卧室": 15.0,
+    "阳光房": 10.0
+  }
+}
+```
+
+---
+
+## 📊 使用效果
+
+### 日志输出示例
+
+```
+[启动时]
+📝 vacuum.dreame_vacuum_r2254
+   面积: sensor.dreame_vacuum_r2254_cleaned_area
+   房间面积: 浴室:5.5m², 儿童房:12.0m², 卧室:15.0m², 阳光房:10.0m²
+
+[选择房间]
+📍 选择区域: 浴室、儿童房
+▶️  继续清扫
+🗺️  清扫区域: Matter[1,2] → Dreame[2,3]
+
+[清扫中]
+🔄 cleaning | 85% | 未充电 | sweeping_and_mopping | Standard | 🏠 浴室 | 📊 25% | 🧹 4.4m²
+   状态标志: 🏃 running | ▶️  started
+   ⏱️  预计剩余: 12 分钟
+
+🔄 cleaning | 82% | 未充电 | sweeping_and_mopping | Standard | 🏠 儿童房 | 📊 68% | 🧹 11.9m²
+   状态标志: 🏃 running | ▶️  started
+   ⏱️  预计剩余: 4 分钟
+
+[完成]
+🔄 returning | 75% | 未充电 | sweeping_and_mopping | Standard | 🏠 过道
+   状态标志: 🔙 returning
+```
+
+---
+
+## 🎯 计算原理
+
+### 进度计算
+```
+清洁进度(%) = (已清洁面积 / 选择房间总面积) × 100
+```
+
+**示例**：
+- 选择房间：浴室(5.5m²) + 儿童房(12m²) = 17.5m²
+- 已清洁：8.75m²
+- 进度：50%
+
+### 时间估算
+```
+已用时间 = 当前时间 - 清扫开始时间
+预计总时间 = (已用时间 / 当前进度) × 100
+预计剩余 = 预计总时间 - 已用时间
+```
+
+**示例**：
+- 已用时间：10 分钟
+- 当前进度：50%
+- 预计总时间：20 分钟
+- 预计剩余：10 分钟
+
+---
+
+## 📁 修改的文件
+
+### 核心代码
+1. **src/platform-config.ts**
+   - 新增 `cleanedAreaSensorMap` 配置项
+   - 新增 `roomAreaSizes` 配置项
+   - 新增配置验证逻辑
+
+2. **src/ha-vacuum-controller.ts**
+   - 扩展 `VacuumState` 接口（progress、estimatedEndTime、cleanedArea）
+   - 新增 `cleanedAreaSensorId` 属性
+   - 新增 `roomAreaSizes` 属性
+   - 新增 `calculateProgress()` 方法
+   - 新增 `setSelectedRooms()` 方法
+   - 新增已清洁面积传感器监听
+
+3. **src/platform.ts**
+   - 更新控制器初始化，传递新配置
+   - 更新 `selectAreas` 命令，设置选择的房间
+   - 更新 `resume` 命令，设置房间列表
+   - 增强日志输出，显示进度信息
+
+### 配置文件
+4. **config.json**
+   - 添加完整配置示例
+
+### 文档
+5. **README.md**
+   - 添加清洁进度功能说明
+   - 更新配置项说明表格
+
+6. **CHANGELOG.md**
+   - 添加 v3.2.0 版本更新日志
+
+7. **PROGRESS_FEATURE.md** (新增)
+   - 详细的功能说明文档
+   - 配置指南
+   - 故障排查
+   - 使用技巧
+
+8. **package.json**
+   - 版本号更新为 3.2.0
+
+---
+
+## 🚀 如何使用
+
+### 1. 查找已清洁面积传感器
+
+在 Home Assistant 中：
+```bash
+开发者工具 → 状态 → 搜索 "cleaned_area"
+```
+
+常见传感器名称：
+- `sensor.dreame_vacuum_r2254_cleaned_area`
+- `sensor.roborock_s7_cleaned_area`
+
+### 2. 测量房间面积
+
+**方法 A**：使用扫地机 App
+- 打开官方 App（米家、Dreame 等）
+- 查看地图中各房间面积
+
+**方法 B**：手动测量
+- 长度(米) × 宽度(米) = 面积(m²)
+
+### 3. 更新配置文件
+
+编辑 `~/.matterbridge/matterbridge-ha-roborock.config.json`：
+
+```json
+{
+  "cleanedAreaSensorMap": {
+    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaned_area"
+  },
+  "roomAreaSizes": {
+    "浴室": 5.5,
+    "儿童房": 12.0,
+    "卧室": 15.0,
+    "阳光房": 10.0
+  }
+}
+```
+
+### 4. 重新编译和部署
+
+```bash
+cd /Users/xmg/Projects/matterbridge-ha-roborock
+npm run build
+
+# 如果需要打包
+npm pack
+
+# 部署到 Matterbridge
+# (根据您的部署方式)
+```
+
+### 5. 重启 Matterbridge
+
+重启服务后，查看日志确认配置生效：
+
+```bash
+tail -f ~/.matterbridge/logs/matterbridge.log | grep "面积"
+```
+
+应该看到：
+```
+面积: sensor.dreame_vacuum_r2254_cleaned_area
+房间面积: 浴室:5.5m², 儿童房:12.0m², 卧室:15.0m², 阳光房:10.0m²
+```
+
+---
+
+## 🐛 故障排查
+
+### 问题：进度一直是 0%
+
+**检查**：
+```bash
+# 1. 确认传感器存在
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://YOUR_HA_URL:8123/api/states/sensor.dreame_vacuum_r2254_cleaned_area
+
+# 2. 确认配置正确
+cat ~/.matterbridge/matterbridge-ha-roborock.config.json | grep -A 5 "cleanedAreaSensorMap"
+
+# 3. 查看日志
+tail -f ~/.matterbridge/logs/matterbridge.log | grep "📊"
+```
+
+### 问题：预计时间不准确
+
+**原因**：
+- 初期估算误差大，后期会更准确
+- 扫地机速度会变化（障碍物、房间大小等）
+
+**正常现象**：
+- 0-20%：时间波动较大
+- 20-80%：逐渐稳定
+- 80-100%：最准确
+
+---
+
+## 📚 相关文档
+
+- **详细功能说明**：`PROGRESS_FEATURE.md`
+- **更新日志**：`CHANGELOG.md`
+- **配置说明**：`README.md`
+
+---
+
+## 🎉 总结
+
+v3.2.0 版本成功实现了清洁进度追踪功能，通过简单的配置即可：
+- ✅ 实时显示清洁进度百分比
+- ✅ 显示已清洁面积
+- ✅ 智能估算预计结束时间
+- ✅ 支持多种清扫场景
+
+这个功能完全基于 Home Assistant 现有的传感器数据，无需额外硬件支持，只需简单配置即可使用！
+
+---
+
+**开发时间**：2025-01-01  
+**版本**：v3.2.0  
+**状态**：✅ 已完成并测试编译通过
+