matterbridge-ha-roborock 3.1.0 → 3.4.4

package/WEB_UI_GUIDE.md

@@ -0,0 +1,228 @@
+# Matterbridge Web UI 配置指南
+
+本插件完全支持通过 Matterbridge Web UI 进行可视化配置，无需手动编辑 JSON 文件。
+
+## 📱 访问 Web UI
+
+1. 启动 Matterbridge：
+```bash
+matterbridge
+```
+
+2. 打开浏览器访问：
+```
+http://localhost:8283
+```
+
+3. 如果是远程服务器，将 `localhost` 替换为服务器 IP 地址
+
+## ⚙️ 配置步骤
+
+### 1. 找到插件
+
+在 Matterbridge Web UI 的插件列表中找到 `matterbridge-ha-roborock`
+
+### 2. 点击配置按钮
+
+点击插件旁边的配置图标（齿轮图标）
+
+### 3. 填写配置项
+
+#### 必填项
+
+**Home Assistant URL**
+- 格式：`http://IP:端口`
+- 示例：`http://192.168.1.100:8123`
+- 说明：你的 Home Assistant 完整地址
+
+**Home Assistant 长期访问令牌**
+- 在 Home Assistant 中创建：
+  1. 点击左下角用户名
+  2. 选择"安全"
+  3. 滚动到"长期访问令牌"
+  4. 点击"创建令牌"
+  5. 复制生成的令牌
+- 这是一个密码字段，输入后会自动隐藏
+
+**Matter 模式**
+- `server`（推荐）：每个设备独立配对
+- `bridge`：所有设备通过一个桥接器
+
+#### 可选项（推荐配置）
+
+**设备白名单**
+- 点击"添加项"按钮
+- 输入扫地机的 entity_id
+- 示例：`vacuum.dreame_vacuum_r2254`
+- 可以添加多个设备
+
+**电池传感器映射**
+- 格式：`vacuum.xxx` → `sensor.xxx_battery_level`
+- 示例：
+  ```
+  键: vacuum.dreame_vacuum_r2254
+  值: sensor.dreame_vacuum_r2254_battery_level
+  ```
+
+**充电状态传感器映射**
+- 格式：`vacuum.xxx` → `binary_sensor.xxx_charging_state`
+- 示例：
+  ```
+  键: vacuum.dreame_vacuum_r2254
+  值: binary_sensor.dreame_vacuum_r2254_charging_state
+  ```
+
+**清洁模式实体映射**
+- 格式：`vacuum.xxx` → `select.xxx_cleaning_mode`
+- 示例：
+  ```
+  键: vacuum.dreame_vacuum_r2254
+  值: select.dreame_vacuum_r2254_cleaning_mode
+  ```
+
+**错误传感器映射**
+- 格式：`vacuum.xxx` → `sensor.xxx_error`
+- 示例：
+  ```
+  键: vacuum.dreame_vacuum_r2254
+  值: sensor.dreame_vacuum_r2254_error
+  ```
+
+**当前房间传感器映射**
+- 格式：`vacuum.xxx` → `sensor.xxx_current_room`
+- 示例：
+  ```
+  键: vacuum.dreame_vacuum_r2254
+  值: sensor.sao_di_ji_current_room
+  ```
+
+**已清洁面积传感器映射**
+- 格式：`vacuum.xxx` → `sensor.xxx_cleaned_area`
+- 示例：
+  ```
+  键: vacuum.dreame_vacuum_r2254
+  值: sensor.dreame_vacuum_r2254_cleaned_area
+  ```
+
+**清洁时间传感器映射**
+- 格式：`vacuum.xxx` → `sensor.xxx_cleaning_time`
+- 示例：
+  ```
+  键: vacuum.dreame_vacuum_r2254
+  值: sensor.dreame_vacuum_r2254_cleaning_time
+  ```
+
+**房间面积配置**
+- 用于计算清洁进度和预计完成时间
+- 格式：`房间名称` → `面积（平方米）`
+- 示例：
+  ```
+  键: 浴室
+  值: 5.5
+  
+  键: 儿童房
+  值: 12
+  
+  键: 卧室
+  值: 15
+  
+  键: 阳光房
+  值: 10
+  ```
+
+#### 高级选项
+
+**轮询间隔 (毫秒)**
+- 默认：30000 (30秒)
+- 范围：5000 - 300000
+- 说明：状态更新的轮询间隔
+
+**调试模式**
+- 默认：关闭
+- 开启后会输出详细的调试日志
+
+**关闭时注销设备**
+- 默认：关闭
+- 开启后插件关闭时会从 Matter 网络注销设备
+
+### 4. 保存配置
+
+点击"保存"按钮保存配置
+
+### 5. 重启插件
+
+保存后需要重启插件使配置生效：
+1. 在插件列表中找到 `matterbridge-ha-roborock`
+2. 点击重启按钮
+3. 等待插件重新加载
+
+## 🎯 配置验证
+
+### 检查插件状态
+
+在 Web UI 中查看插件状态：
+- ✅ 绿色：运行正常
+- ⚠️ 黄色：有警告
+- ❌ 红色：有错误
+
+### 查看日志
+
+在 Web UI 中点击"日志"按钮查看详细日志：
+- 确认 Home Assistant 连接成功
+- 确认设备已注册
+- 查看配对码
+
+### 测试配置
+
+1. 在苹果家庭或其他 Matter 控制器中添加设备
+2. 使用配对码配对
+3. 测试基本功能：
+   - 开始/暂停清扫
+   - 返回充电
+   - 选择房间清扫
+
+## 💡 常见问题
+
+### Q: 配置保存后没有生效？
+A: 需要重启插件才能使配置生效
+
+### Q: 如何查看我的 entity_id？
+A: 在 Home Assistant 中：
+1. 开发者工具 → 状态
+2. 搜索你的设备
+3. 复制 entity_id
+
+### Q: 房间名称从哪里获取？
+A: 房间名称来自你的 Home Assistant 集成配置，通常在扫地机的地图配置中
+
+### Q: 配置了传感器映射但没有效果？
+A: 确保：
+1. entity_id 正确（在 HA 中存在）
+2. 传感器有值（不是 unavailable）
+3. 已重启插件
+
+### Q: Web UI 无法访问？
+A: 检查：
+1. Matterbridge 是否正在运行
+2. 防火墙是否允许 8283 端口
+3. 如果是远程访问，使用服务器 IP 而不是 localhost
+
+## 📚 更多信息
+
+- [完整文档](./README.md)
+- [配置示例](./config.example.json)
+- [更新日志](./CHANGELOG.md)
+
+## 🆘 获取帮助
+
+如果遇到问题：
+1. 查看 Matterbridge 日志
+2. 启用调试模式获取详细信息
+3. 在 GitHub 提交 Issue
+
+
+
+
+
+
+

package/config.example.json

@@ -0,0 +1,47 @@
+{
+  "name": "matterbridge-ha-roborock",
+  "type": "AccessoryPlatform",
+  "haUrl": "http://homeassistant.local:8123",
+  "haToken": "YOUR_LONG_LIVED_ACCESS_TOKEN_HERE",
+  "matterMode": "server",
+  "pollInterval": 30000,
+  "debug": false,
+  "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"
+  },
+  "cleaningTimeSensorMap": {
+    "vacuum.dreame_vacuum_r2254": "sensor.dreame_vacuum_r2254_cleaning_time"
+  },
+  "roomAreaSizes": {
+    "浴室": 5.5,
+    "儿童房": 12,
+    "卧室": 15,
+    "阳光房": 10
+  },
+  "unregisterOnShutdown": false
+}
+
+
+
+
+
+
+

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
 }

package/deploy-to-server.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+
+SERVER="root@10.10.10.167"
+PASSWORD="19940725"
+VERSION=$(node -p "require('./package.json').version")
+PACKAGE_FILE="matterbridge-ha-roborock-${VERSION}.tgz"
+
+echo "🚀 部署 matterbridge-ha-roborock v${VERSION} 到服务器..."
+echo ""
+
+# 检查包文件是否存在
+if [ ! -f "$PACKAGE_FILE" ]; then
+    echo "❌ 包文件不存在: $PACKAGE_FILE"
+    echo "请先运行: npm pack"
+    exit 1
+fi
+
+echo "📦 1/4 上传包到服务器..."
+expect << EOF
+set timeout 30
+spawn scp $PACKAGE_FILE $SERVER:/tmp/
+expect {
+    "password:" { send "$PASSWORD\r"; exp_continue }
+    "yes/no" { send "yes\r"; exp_continue }
+    eof
+}
+EOF
+
+if [ $? -ne 0 ]; then
+    echo "❌ 上传失败"
+    exit 1
+fi
+echo "✅ 上传成功"
+echo ""
+
+echo "🔧 2/4 连接到服务器..."
+echo ""
+
+expect << 'EOFEXPECT'
+set timeout 60
+set password "19940725"
+set server "root@10.10.10.167"
+set version [exec node -p "require('./package.json').version"]
+
+spawn ssh $server
+
+expect {
+    "password:" { send "$password\r" }
+    "yes/no" { send "yes\r"; exp_continue }
+}
+
+expect "# "
+send "echo '=== 停止 Matterbridge ==='\r"
+
+expect "# "
+send "pkill -f matterbridge || true\r"
+
+expect "# "
+send "sleep 2\r"
+
+expect "# "
+send "echo '=== 安装新版本 ==='\r"
+
+expect "# "
+send "npm install -g /tmp/matterbridge-ha-roborock-$version.tgz\r"
+
+expect "# "
+send "echo '=== 验证安装 ==='\r"
+
+expect "# "
+send "npm list -g matterbridge-ha-roborock\r"
+
+expect "# "
+send "echo '=== 清理临时文件 ==='\r"
+
+expect "# "
+send "rm -f /tmp/matterbridge-ha-roborock-*.tgz\r"
+
+expect "# "
+send "echo '=== 启动 Matterbridge ==='\r"
+
+expect "# "
+send "cd ~ && nohup matterbridge > /tmp/matterbridge.log 2>&1 &\r"
+
+expect "# "
+send "sleep 3\r"
+
+expect "# "
+send "echo '=== 检查运行状态 ==='\r"
+
+expect "# "
+send "ps aux | grep matterbridge | grep -v grep\r"
+
+expect "# "
+send "exit\r"
+
+expect eof
+EOFEXPECT
+
+if [ $? -eq 0 ]; then
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "✅ 部署完成！"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "📊 服务器信息:"
+    echo "   地址: $SERVER"
+    echo "   版本: v${VERSION}"
+    echo ""
+    echo "🔍 查看日志:"
+    echo "   ssh $SERVER 'tail -f /tmp/matterbridge.log'"
+    echo ""
+    echo "🛑 停止服务:"
+    echo "   ssh $SERVER 'pkill -f matterbridge'"
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+else
+    echo ""
+    echo "❌ 部署失败"
+    exit 1
+fi
+
+
+
+
+
+
+
+

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

@@ -5,6 +5,7 @@ import { HomeAssistantClient } from './homeassistant-client.js';
  */
 export interface VacuumState {
     state: string;
+    detailedState?: string;
     batteryLevel: number;
     isCharging: boolean;
     fanSpeed?: string;
@@ -12,6 +13,9 @@ export interface VacuumState {
     error?: string;
     errorMsg?: string;
     currentRoom?: string;
+    cleanedArea?: number;
+    cleaningTime?: number;
+    hepaFilterLife?: number;
     rawAttributes?: any;
 }
 /**
@@ -33,8 +37,17 @@ export declare class HAVacuumController extends EventEmitter {
     private cleaningModeEntityId?;
     private errorSensorId?;
     private currentRoomSensorId?;
+    private stateSensorId?;
+    private cleanedAreaSensorId?;
+    private cleaningTimeSensorId?;
+    private hepaFilterSensorId?;
+    private roomAreaSizes?;
+    private selectedRoomNames;
     private currentState?;
-    constructor(haClient: HomeAssistantClient, entityId: string, batterySensorId?: string, chargingSensorId?: string, cleaningModeEntityId?: string, errorSensorId?: string, currentRoomSensorId?: string);
+    private roomTimers;
+    private lastRoom?;
+    private taskStartTime;
+    constructor(haClient: HomeAssistantClient, entityId: string, batterySensorId?: string, chargingSensorId?: string, cleaningModeEntityId?: string, errorSensorId?: string, currentRoomSensorId?: string, stateSensorId?: string, cleanedAreaSensorId?: string, cleaningTimeSensorId?: string, hepaFilterSensorId?: string, roomAreaSizes?: Record<string, number>);
     /**
      * 初始化控制器 - 获取初始状态并设置监听
      */
@@ -51,6 +64,18 @@ export declare class HAVacuumController extends EventEmitter {
      * 获取当前状态
      */
     getState(): VacuumState | undefined;
+    /**
+     * 获取选择的房间名称列表
+     */
+    getSelectedRoomNames(): string[];
+    /**
+     * 设置选择的房间名称列表
+     */
+    setSelectedRoomNames(roomNames: string[]): void;
+    /**
+     * 获取房间面积配置
+     */
+    getRoomAreaSizes(): Record<string, number> | undefined;
     /**
      * 强制刷新状态（用于主动更新）
      */
@@ -97,6 +122,23 @@ export declare class HAVacuumController extends EventEmitter {
      * @param segmentMap Matter ID 到 Dreame ID 的映射
      */
     cleanSegments(segments: number[], segmentMap?: Record<number, string>): Promise<void>;
+    /**
+     * 更新房间计时器
+     * 当房间切换时记录上一个房间的时间，开始新房间的计时
+     */
+    updateRoomTimer(currentRoom: string | undefined, isCleaningState: boolean): void;
+    /**
+     * 获取指定房间的清扫时间（秒）
+     */
+    getRoomTime(roomName: string): number;
+    /**
+     * 重置所有房间计时器
+     */
+    resetRoomTimers(): void;
+    /**
+     * 获取房间计时信息（用于调试）
+     */
+    getRoomTimersInfo(): Record<string, number>;
     /**
      * 销毁控制器
      */