matterbridge-ha-roborock 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [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.1.0** - CurrentArea 支持 + 状态优化 + 返回基站修复
+- **3.0.0** - 初始版本
+

package/README.md

@@ -1,19 +1,321 @@
 # Matterbridge HA Roborock
 
-桥接 Home Assistant 中的 Roborock 到 Matter。
+[![npm version](https://badge.fury.io/js/matterbridge-ha-roborock.svg)](https://www.npmjs.com/package/matterbridge-ha-roborock)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+将 Home Assistant 中的 Roborock/Dreame 扫地机桥接到 Matter 生态系统，支持苹果家庭、Google Home 等 Matter 控制器。
+
+## ✨ 功能特性
+
+### 核心功能
+- 🏠 **完整的 Matter 扫地机支持**：实现 RoboticVacuumCleaner 设备类型
+- 🗺️ **区域清扫**：支持选择特定房间进行清扫
+- 📍 **实时位置追踪**：显示扫地机当前所在房间
+- 🔋 **电池监控**：实时显示电量和充电状态
+- 🎨 **清洁模式**：支持扫地、拖地、组合模式
+- 🌪️ **风速调节**：Silent、Standard、Medium、Turbo
+- ⚡ **实时同步**：通过 WebSocket 实时更新状态
+
+### Matter 集群支持
+- ✅ PowerSource - 电源管理
+- ✅ RvcOperationalState - 操作状态
+- ✅ RvcRunMode - 运行模式
+- ✅ RvcCleanMode - 清洁模式
+- ✅ ServiceArea - 服务区域（分区清扫）
+- ✅ Identify - 设备识别
+
+## 📦 安装
+
+### 通过 Matterbridge 安装（推荐）
+
+1. 安装 Matterbridge：
+```bash
+npm install -g matterbridge
+```
+
+2. 安装插件：
+```bash
+matterbridge -add matterbridge-ha-roborock
+```
+
+### 手动安装
+
+```bash
+npm install -g matterbridge-ha-roborock
+```
+
+## ⚙️ 配置
+
+在 Matterbridge 配置目录（通常是 `~/.matterbridge/`）创建或编辑配置文件：
+
+### 基础配置
 
-## 配置
 ```json
 {
+  "name": "matterbridge-ha-roborock",
+  "type": "AccessoryPlatform",
   "haUrl": "http://homeassistant.local:8123",
-  "haToken": "your-token",
-  "deviceWhitelist": ["vacuum.roborock_s7"]
+  "haToken": "your-long-lived-access-token",
+  "deviceWhitelist": [
+    "vacuum.dreame_vacuum_r2254"
+  ]
 }
 ```
 
-## 开发
+### 完整配置（推荐）
+
+```json
+{
+  "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"
+  }
+}
+```
+
+### 配置项说明
+
+| 配置项 | 类型 | 必需 | 说明 |
+|--------|------|------|------|
+| `haUrl` | string | ✅ | Home Assistant 地址 |
+| `haToken` | string | ✅ | Home Assistant 长期访问令牌 |
+| `deviceWhitelist` | string[] | ✅ | 要桥接的扫地机实体 ID 列表 |
+| `batterySensorMap` | object | ⭐ | 电池电量传感器映射 |
+| `chargingSensorMap` | object | ⭐ | 充电状态传感器映射 |
+| `cleaningModeEntityMap` | object | ⭐ | 清洁模式实体映射 |
+| `errorSensorMap` | object | ⭐ | 错误传感器映射 |
+| `currentRoomSensorMap` | object | ⭐ | 当前房间传感器映射（v3.1.0+） |
+
+⭐ = 强烈推荐配置以获得最佳体验
+
+## 🚀 使用
+
+### 1. 获取 Home Assistant 令牌
+
+1. 登录 Home Assistant
+2. 点击左下角用户名
+3. 滚动到"长期访问令牌"部分
+4. 点击"创建令牌"
+5. 复制令牌到配置文件
+
+### 2. 启动 Matterbridge
+
 ```bash
+matterbridge
+```
+
+### 3. 添加到苹果家庭
+
+1. 打开苹果家庭 App
+2. 点击右上角 "+"
+3. 选择"添加配件"
+4. 选择"更多选项"
+5. 找到"扫地机"并点击
+6. 输入 Matterbridge 显示的配对码
+
+### 4. 开始使用
+
+在苹果家庭中，你可以：
+- ▶️ 启动/暂停清扫
+- 🏠 返回充电座
+- 🗺️ 选择房间清扫
+- 🔋 查看电量和充电状态
+- 📍 查看当前位置
+
+## 🗺️ 区域清扫配置
+
+### 定义房间映射
+
+在 `src/platform.ts` 中配置你的房间映射：
+
+```typescript
+// 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 开发者工具中调用服务：
+
+```yaml
+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
+
+### 本地开发
+
+```bash
+# 克隆仓库
+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
+```
+
+## 🐛 故障排查
+
+### 扫地机未显示
+
+1. 检查 HA 连接：
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://homeassistant.local:8123/api/states/vacuum.your_vacuum
+```
+
+2. 检查 Matterbridge 日志：
+```bash
+tail -f ~/.matterbridge/logs/matterbridge.log
+```
+
+### 区域清扫不工作
+
+1. 验证 segment ID 映射是否正确
+2. 在 HA 中手动测试 `dreame_vacuum.vacuum_clean_segment` 服务
+3. 检查 `AREA_TO_SEGMENT_MAP` 配置
+
+### 返回基站无响应
+
+- 确保使用 v3.1.0 或更高版本
+- 检查 HA 中 `vacuum.return_to_base` 服务是否可用
+
+## 📝 更新日志
+
+查看 [CHANGELOG.md](./CHANGELOG.md) 了解详细更新历史。
+
+### v3.1.0 (2024-12-31)
+- ✨ 新增 `currentArea` 支持，实时显示当前房间
+- 🎯 优化区域清扫状态映射
+- 🏠 修复返回基站功能
+- 🔄 移除轮询机制，完全依赖 WebSocket
+
+### v3.0.0 (2024-12-30)
+- 🎉 初始版本发布
+
+## 📄 许可证
+
+MIT License - 详见 [LICENSE](./LICENSE) 文件
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 🙏 致谢
+
+- [Matterbridge](https://github.com/Luligu/matterbridge) - Matter 桥接框架
+- [Home Assistant](https://www.home-assistant.io/) - 智能家居平台
+- [Matter](https://csa-iot.org/all-solutions/matter/) - 智能家居标准
+
+## 📞 支持
+
+- 📧 Email: your-email@example.com
+- 💬 Issues: [GitHub Issues](https://github.com/yourusername/matterbridge-ha-roborock/issues)
+- 📖 文档: [Wiki](https://github.com/yourusername/matterbridge-ha-roborock/wiki)
+
+---
+
+**如果这个项目对你有帮助，请给个 ⭐ Star！**

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,178 @@
+# Release Checklist v3.1.0
+
+## 📋 发布前检查清单
+
+### 1️⃣ 代码准备
+- [x] 更新版本号到 3.1.0 (package.json)
+- [x] 创建 CHANGELOG.md
+- [x] 更新 README.md
+- [x] 创建 .npmignore
+- [x] 清理并重新编译代码
+- [x] 创建 npm 包 (npm pack)
+
+### 2️⃣ 测试验证
+- [ ] 本地测试所有功能
+  - [ ] 基本清扫功能
+  - [ ] 区域清扫功能
+  - [ ] 返回基站功能
+  - [ ] currentArea 更新
+  - [ ] 状态同步
+- [ ] 在 Matterbridge 中测试安装
+- [ ] 在苹果家庭中测试控制
+
+### 3️⃣ 文档检查
+- [x] README.md 包含完整使用说明
+- [x] CHANGELOG.md 记录所有更改
+- [x] 配置示例完整
+- [x] 故障排查指南
+
+### 4️⃣ npm 发布
+- [ ] 登录 npm 账号
+  ```bash
+  npm login
+  ```
+- [ ] 检查登录状态
+  ```bash
+  npm whoami
+  ```
+- [ ] 执行发布脚本
+  ```bash
+  ./publish.sh
+  ```
+- [ ] 验证发布成功
+  ```bash
+  npm view matterbridge-ha-roborock
+  ```
+
+### 5️⃣ GitHub 发布
+- [ ] 提交所有更改
+  ```bash
+  git add .
+  git commit -m "chore: release v3.1.0"
+  ```
+- [ ] 创建 git tag
+  ```bash
+  git tag -a v3.1.0 -m "Release v3.1.0"
+  ```
+- [ ] 推送到 GitHub
+  ```bash
+  git push origin main
+  git push origin v3.1.0
+  ```
+- [ ] 在 GitHub 创建 Release
+  - 标题: `v3.1.0 - CurrentArea Support + State Optimization`
+  - 描述: 复制 CHANGELOG.md 中的 v3.1.0 部分
+
+### 6️⃣ 发布后验证
+- [ ] 检查 npm 包页面
+  - https://www.npmjs.com/package/matterbridge-ha-roborock
+- [ ] 测试全局安装
+  ```bash
+  npm install -g matterbridge-ha-roborock
+  ```
+- [ ] 检查版本号
+  ```bash
+  npm list -g matterbridge-ha-roborock
+  ```
+
+### 7️⃣ 通知和推广
+- [ ] 更新项目文档
+- [ ] 发布更新公告
+- [ ] 通知现有用户
+- [ ] 更新相关论坛/社区帖子
+
+---
+
+## 🚀 快速发布命令
+
+```bash
+# 1. 确保在正确的分支
+git checkout main
+
+# 2. 拉取最新代码
+git pull
+
+# 3. 运行发布脚本
+./publish.sh
+
+# 4. 提交并推送
+git add .
+git commit -m "chore: release v3.1.0"
+git tag -a v3.1.0 -m "Release v3.1.0"
+git push origin main --tags
+```
+
+---
+
+## 📝 发布说明模板
+
+### npm 发布说明
+
+```markdown
+# matterbridge-ha-roborock v3.1.0
+
+## 🎉 新功能
+
+- ✨ **ServiceArea.currentArea 支持**：实时追踪扫地机当前所在房间
+- 🎯 **区域清扫状态优化**：改进状态映射逻辑
+- 🏠 **返回基站功能修复**：修复苹果家庭"返回基站"按钮
+
+## 🔄 改进
+
+- 移除轮询机制，完全依赖 WebSocket 实时推送
+- 优化日志输出，更清晰的状态显示
+
+## 🐛 修复
+
+- 修复 `changeToMode` 命令未处理 Idle 模式
+- 修复区域清扫状态映射优先级
+
+## 📦 安装
+
+\`\`\`bash
+npm install -g matterbridge-ha-roborock
+\`\`\`
+
+## 📖 文档
+
+查看 [README.md](https://github.com/yourusername/matterbridge-ha-roborock) 了解详细使用说明。
+```
+
+---
+
+## ⚠️ 注意事项
+
+1. **版本号规范**：遵循语义化版本 (Semantic Versioning)
+   - MAJOR.MINOR.PATCH (3.1.0)
+   - MAJOR: 不兼容的 API 更改
+   - MINOR: 向后兼容的功能新增
+   - PATCH: 向后兼容的问题修复
+
+2. **npm 发布权限**：确保有发布权限
+   ```bash
+   npm owner ls matterbridge-ha-roborock
+   ```
+
+3. **回滚方案**：如果发布有问题
+   ```bash
+   npm unpublish matterbridge-ha-roborock@3.1.0
+   ```
+   注意：unpublish 有 24 小时限制
+
+4. **标签管理**：
+   - `latest`: 默认标签，用于稳定版本
+   - `beta`: 测试版本
+   - `next`: 下一个版本
+
+---
+
+## ✅ 发布完成
+
+- [ ] npm 包已发布
+- [ ] GitHub Release 已创建
+- [ ] 文档已更新
+- [ ] 用户已通知
+
+**发布日期**: _______________
+**发布人**: _______________
+

package/dist/src/ha-vacuum-controller.d.ts

@@ -11,6 +11,7 @@ export interface VacuumState {
     cleaningMode?: string;
     error?: string;
     errorMsg?: string;
+    currentRoom?: string;
     rawAttributes?: any;
 }
 /**
@@ -31,9 +32,9 @@ export declare class HAVacuumController extends EventEmitter {
     private chargingSensorId?;
     private cleaningModeEntityId?;
     private errorSensorId?;
+    private currentRoomSensorId?;
     private currentState?;
-    private pollInterval?;
-    constructor(haClient: HomeAssistantClient, entityId: string, batterySensorId?: string, chargingSensorId?: string, cleaningModeEntityId?: string, errorSensorId?: string);
+    constructor(haClient: HomeAssistantClient, entityId: string, batterySensorId?: string, chargingSensorId?: string, cleaningModeEntityId?: string, errorSensorId?: string, currentRoomSensorId?: string);
     /**
      * 初始化控制器 - 获取初始状态并设置监听
      */
@@ -46,14 +47,6 @@ export declare class HAVacuumController extends EventEmitter {
      * 处理状态变化
      */
     private handleStateChange;
-    /**
-     * 启动轮询
-     */
-    private startPolling;
-    /**
-     * 停止轮询
-     */
-    private stopPolling;
     /**
      * 获取当前状态
      */