matterbridge-ha-roborock 3.0.0

package/src/platform.ts

@@ -0,0 +1,601 @@
+import {
+  Matterbridge,
+  PlatformConfig,
+  MatterbridgeAccessoryPlatform
+} from 'matterbridge';
+
+import { RoboticVacuumCleaner } from 'matterbridge/devices';
+import { RvcCleanMode, RvcRunMode, RvcOperationalState, ServiceArea, PowerSource, Identify } from 'matterbridge/matter/clusters';
+
+import { HomeAssistantClient } from './homeassistant-client.js';
+import { HAVacuumController, VacuumState, CleanModeConfig } from './ha-vacuum-controller.js';
+import { RoborockPlatformConfig, validateConfig } from './platform-config.js';
+
+// Clean Mode 定义
+const CLEAN_MODE = {
+  VacMopQuiet: 5, VacMopQuick: 6, VacMopMax: 7, VacMopDeep: 8,
+  MopQuiet: 31, MopQuick: 32, MopMax: 33, MopDeep: 34,
+  VacQuiet: 66, VacQuick: 67, VacMax: 68, VacDeep: 69,
+};
+
+const CLEAN_MODE_LABELS: Record<number, string> = {
+  [CLEAN_MODE.VacMopQuiet]: 'Mop & Vacuum: Quiet',
+  [CLEAN_MODE.VacMopQuick]: 'Mop & Vacuum: Quick',
+  [CLEAN_MODE.VacMopMax]: 'Mop & Vacuum: Max',
+  [CLEAN_MODE.VacMopDeep]: 'Mop & Vacuum: DeepClean',
+  [CLEAN_MODE.MopQuiet]: 'Mop: Quiet',
+  [CLEAN_MODE.MopQuick]: 'Mop: Quick',
+  [CLEAN_MODE.MopMax]: 'Mop: Max',
+  [CLEAN_MODE.MopDeep]: 'Mop: DeepClean',
+  [CLEAN_MODE.VacQuiet]: 'Vacuum: Quiet',
+  [CLEAN_MODE.VacQuick]: 'Vacuum: Quick',
+  [CLEAN_MODE.VacMax]: 'Vacuum: Max',
+  [CLEAN_MODE.VacDeep]: 'Vacuum: DeepClean',
+};
+
+const SUPPORTED_RUN_MODES: RvcRunMode.ModeOption[] = [
+  { label: 'Idle', mode: 1, modeTags: [{ value: RvcRunMode.ModeTag.Idle }] },
+  { label: 'Cleaning', mode: 2, modeTags: [{ value: RvcRunMode.ModeTag.Cleaning }] },
+  { label: 'Mapping', mode: 3, modeTags: [{ value: RvcRunMode.ModeTag.Mapping }] },
+];
+
+const SUPPORTED_CLEAN_MODES: RvcCleanMode.ModeOption[] = [
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.VacMopQuiet], mode: CLEAN_MODE.VacMopQuiet, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }, { value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.Quiet }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.VacMopQuick], mode: CLEAN_MODE.VacMopQuick, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }, { value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.Quick }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.VacMopMax], mode: CLEAN_MODE.VacMopMax, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }, { value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.Max }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.VacMopDeep], mode: CLEAN_MODE.VacMopDeep, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }, { value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.DeepClean }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.MopQuiet], mode: CLEAN_MODE.MopQuiet, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }, { value: RvcCleanMode.ModeTag.Quiet }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.MopQuick], mode: CLEAN_MODE.MopQuick, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }, { value: RvcCleanMode.ModeTag.Quick }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.MopMax], mode: CLEAN_MODE.MopMax, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }, { value: RvcCleanMode.ModeTag.Max }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.MopDeep], mode: CLEAN_MODE.MopDeep, modeTags: [{ value: RvcCleanMode.ModeTag.Mop }, { value: RvcCleanMode.ModeTag.DeepClean }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.VacQuiet], mode: CLEAN_MODE.VacQuiet, modeTags: [{ value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.Quiet }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.VacQuick], mode: CLEAN_MODE.VacQuick, modeTags: [{ value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.Quick }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.VacMax], mode: CLEAN_MODE.VacMax, modeTags: [{ value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.Max }] },
+  { label: CLEAN_MODE_LABELS[CLEAN_MODE.VacDeep], mode: CLEAN_MODE.VacDeep, modeTags: [{ value: RvcCleanMode.ModeTag.Vacuum }, { value: RvcCleanMode.ModeTag.DeepClean }] },
+];
+
+// 清洁模式映射：Matter模式 -> HA配置（清洁模式 + 风速）
+const CLEAN_MODE_TO_HA: Record<number, CleanModeConfig> = {
+  // 吸尘+拖地 (sweeping_and_mopping)
+  [CLEAN_MODE.VacMopQuiet]: { cleaningMode: 'sweeping_and_mopping', fanSpeed: 'Silent' },
+  [CLEAN_MODE.VacMopQuick]: { cleaningMode: 'sweeping_and_mopping', fanSpeed: 'Standard' },
+  [CLEAN_MODE.VacMopMax]: { cleaningMode: 'sweeping_and_mopping', fanSpeed: 'Strong' },
+  [CLEAN_MODE.VacMopDeep]: { cleaningMode: 'sweeping_and_mopping', fanSpeed: 'Turbo' },
+
+  // 仅拖地 (mopping)
+  [CLEAN_MODE.MopQuiet]: { cleaningMode: 'mopping', fanSpeed: 'Silent' },
+  [CLEAN_MODE.MopQuick]: { cleaningMode: 'mopping', fanSpeed: 'Standard' },
+  [CLEAN_MODE.MopMax]: { cleaningMode: 'mopping', fanSpeed: 'Strong' },
+  [CLEAN_MODE.MopDeep]: { cleaningMode: 'mopping', fanSpeed: 'Turbo' },
+
+  // 仅吸尘 (sweeping)
+  [CLEAN_MODE.VacQuiet]: { cleaningMode: 'sweeping', fanSpeed: 'Silent' },
+  [CLEAN_MODE.VacQuick]: { cleaningMode: 'sweeping', fanSpeed: 'Standard' },
+  [CLEAN_MODE.VacMax]: { cleaningMode: 'sweeping', fanSpeed: 'Strong' },
+  [CLEAN_MODE.VacDeep]: { cleaningMode: 'sweeping', fanSpeed: 'Turbo' },
+};
+
+// Matter 区域定义（Apple Home 中显示的名称）
+const SUPPORTED_AREAS: ServiceArea.Area[] = [
+  { areaId: 1, mapId: null, areaInfo: { locationInfo: { locationName: '浴室', floorNumber: null, areaType: null }, landmarkInfo: null } },
+  { areaId: 2, mapId: null, areaInfo: { locationInfo: { locationName: '儿童房', floorNumber: null, areaType: null }, landmarkInfo: null } },
+  { areaId: 3, mapId: null, areaInfo: { locationInfo: { locationName: '卧室', floorNumber: null, areaType: null }, landmarkInfo: null } },
+  { areaId: 4, mapId: null, areaInfo: { locationInfo: { locationName: '阳光房', floorNumber: null, areaType: null }, landmarkInfo: null } },
+];
+
+// Matter areaId -> Dreame segment ID 映射
+const MATTER_TO_DREAME_SEGMENT: Record<number, string> = {
+  1: '2',  // 浴室 -> Dreame segment 2
+  2: '3',  // 儿童房 -> Dreame segment 3
+  3: '5',  // 卧室 -> Dreame segment 5
+  4: '6',  // 阳光房 -> Dreame segment 6
+};
+
+const OPERATIONAL_STATES: RvcOperationalState.OperationalStateStruct[] = [
+  { operationalStateId: RvcOperationalState.OperationalState.Stopped, operationalStateLabel: 'Stopped' },
+  { operationalStateId: RvcOperationalState.OperationalState.Running, operationalStateLabel: 'Running' },
+  { operationalStateId: RvcOperationalState.OperationalState.Paused, operationalStateLabel: 'Paused' },
+  { operationalStateId: RvcOperationalState.OperationalState.Error, operationalStateLabel: 'Error' },
+  { operationalStateId: RvcOperationalState.OperationalState.SeekingCharger, operationalStateLabel: 'SeekingCharger' },
+  { operationalStateId: RvcOperationalState.OperationalState.Charging, operationalStateLabel: 'Charging' },
+  { operationalStateId: RvcOperationalState.OperationalState.Docked, operationalStateLabel: 'Docked' },
+];
+
+// 状态映射函数
+function mapHAStateToOperationalState(
+  haState: string, 
+  isCharging: boolean, 
+  errorMsg?: string,
+  rawAttributes?: any
+): RvcOperationalState.OperationalState {
+  // 检查错误
+  if (errorMsg && errorMsg !== 'no_error' && errorMsg !== 'null' && errorMsg !== 'unavailable') {
+    return RvcOperationalState.OperationalState.Error;
+  }
+  
+  // 优先检查 docked 状态（在基站上）
+  if (haState === 'docked') {
+    // 只信任充电传感器的值，不检查 rawAttributes.charging
+    if (isCharging) {
+      return RvcOperationalState.OperationalState.Charging;
+    }
+    // 如果不在充电，显示已停靠
+    return RvcOperationalState.OperationalState.Docked;
+  }
+  
+  // 检查充电状态（不在基站但在充电，理论上不应该发生）
+  if (isCharging) {
+    return RvcOperationalState.OperationalState.Charging;
+  }
+  
+  // 特殊处理 cleaning 状态（基于 running/started/paused 属性）
+  if (haState === 'cleaning') {
+    // paused 优先级最高
+    if (rawAttributes?.paused === true) {
+      return RvcOperationalState.OperationalState.Paused;
+    }
+    
+    // running = true → 正在清扫
+    if (rawAttributes?.running === true) {
+      return RvcOperationalState.OperationalState.Running;
+    }
+    
+    // running = false 但 started = true → 正在前往目的地
+    if (rawAttributes?.started === true && rawAttributes?.running === false) {
+      return RvcOperationalState.OperationalState.SeekingCharger;
+    }
+    
+    // 默认：正在运行（兼容没有 running 属性的情况）
+    return RvcOperationalState.OperationalState.Running;
+  }
+  
+  // 处理 returning 状态
+  if (haState === 'returning' || rawAttributes?.returning === true) {
+    return RvcOperationalState.OperationalState.SeekingCharger;
+  }
+  
+  // 处理 paused 状态
+  if (haState === 'paused' || rawAttributes?.paused === true) {
+    return RvcOperationalState.OperationalState.Paused;
+  }
+  
+  // 优先使用详细状态（attributes.status）- 兼容其他扫地机
+  if (rawAttributes?.status) {
+    const detailedMap: Record<string, RvcOperationalState.OperationalState> = {
+      'Cruising': RvcOperationalState.OperationalState.SeekingCharger,
+      'Back home': RvcOperationalState.OperationalState.SeekingCharger,
+      'Go Charging': RvcOperationalState.OperationalState.SeekingCharger,
+      'Segment cleaning': RvcOperationalState.OperationalState.Running,
+      'Zone cleaning': RvcOperationalState.OperationalState.Running,
+      'Room cleaning': RvcOperationalState.OperationalState.Running,
+      'Spot cleaning': RvcOperationalState.OperationalState.Running,
+      'Cleaning': RvcOperationalState.OperationalState.Running,
+      'Fast mapping': RvcOperationalState.OperationalState.Running,
+      'Charging': RvcOperationalState.OperationalState.Charging,
+      'Docked': RvcOperationalState.OperationalState.Docked,
+      'Idle': RvcOperationalState.OperationalState.Stopped,
+      'Paused': RvcOperationalState.OperationalState.Paused,
+      'Error': RvcOperationalState.OperationalState.Error,
+    };
+    
+    if (detailedMap[rawAttributes.status] !== undefined) {
+      return detailedMap[rawAttributes.status];
+    }
+  }
+  
+  // 基本状态映射（idle 等其他状态）
+  const stateMap: Record<string, RvcOperationalState.OperationalState> = {
+    'idle': RvcOperationalState.OperationalState.Stopped,
+    'error': RvcOperationalState.OperationalState.Error,
+  };
+  
+  return stateMap[haState.toLowerCase()] || RvcOperationalState.OperationalState.Stopped;
+}
+
+function mapHAStateToRunMode(haState: string): number {
+  const runModeMap: Record<string, number> = {
+    'cleaning': 2, 'docked': 1, 'paused': 2, 'idle': 1, 'returning': 1, 'charging': 1, 'error': 1,
+  };
+  return runModeMap[haState.toLowerCase()] || 1;
+}
+
+export class RoborockHAPlatform extends MatterbridgeAccessoryPlatform {
+  private haClient?: HomeAssistantClient;
+  private vacuumControllers = new Map<string, HAVacuumController>();
+  private matterDevices = new Map<string, RoboticVacuumCleaner>();
+  private platformConfig?: RoborockPlatformConfig;
+
+  constructor(matterbridge: Matterbridge, log: any, config: PlatformConfig) {
+    super(matterbridge, log, config);
+    this.log.info('🔧 初始化扫地机插件...');
+  }
+
+  override async onStart(reason?: string): Promise<void> {
+    this.log.info(`▶️  启动插件: ${reason || '未知原因'}`);
+    this.platformConfig = validateConfig(this.config as unknown as RoborockPlatformConfig);
+    
+    this.haClient = new HomeAssistantClient(this.platformConfig.haUrl, this.platformConfig.haToken);
+    const ok = await this.haClient.testConnection();
+    if (!ok) throw new Error('Failed to connect to Home Assistant');
+    
+    this.log.info('✅ HA 连接成功');
+    
+    try {
+      await this.haClient.connectWebSocket();
+      this.log.info('✅ WebSocket 实时连接成功');
+    } catch {
+      this.log.warn('⚠️  WebSocket 连接失败，使用轮询模式');
+    }
+    
+    await this.discoverDevices(this.platformConfig);
+    this.log.info('✅ 插件启动完成\n');
+  }
+
+  private async discoverDevices(config: RoborockPlatformConfig): Promise<void> {
+    if (!this.haClient) return;
+    
+    const vacuums = await this.haClient.getVacuumEntities();
+    this.log.info(`🔍 发现 ${vacuums.length} 台扫地机`);
+    
+    const filtered = vacuums.filter(v => {
+      if (config.deviceBlacklist?.includes(v.entity_id)) {
+        this.log.info(`⏭  跳过 ${v.entity_id} (黑名单)`);
+        return false;
+      }
+      if (config.deviceWhitelist?.length && !config.deviceWhitelist.includes(v.entity_id)) {
+        this.log.info(`⏭  跳过 ${v.entity_id} (不在白名单)`);
+        return false;
+      }
+      return true;
+    });
+    
+    this.log.info(`📝 注册 ${filtered.length} 台设备\n`);
+    
+    for (const vacuum of filtered) {
+      try {
+        await this.registerVacuum(vacuum.entity_id, config);
+      } catch (err) {
+        this.log.error(`❌ 注册失败 ${vacuum.entity_id}:`, err);
+      }
+    }
+  }
+
+  private async registerVacuum(entityId: string, config: RoborockPlatformConfig): Promise<void> {
+    if (!this.haClient) return;
+    
+    this.log.info(`📝 ${entityId}`);
+    
+    // 获取传感器映射
+    const batterySensorId = config.batterySensorMap?.[entityId];
+    const chargingSensorId = config.chargingSensorMap?.[entityId];
+    const cleaningModeEntityId = config.cleaningModeEntityMap?.[entityId];
+    const errorSensorId = config.errorSensorMap?.[entityId];
+    
+    if (batterySensorId) {
+      this.log.info(`   电池: ${batterySensorId}`);
+    }
+    if (chargingSensorId) {
+      this.log.info(`   充电: ${chargingSensorId}`);
+    }
+    if (cleaningModeEntityId) {
+      this.log.info(`   模式: ${cleaningModeEntityId}`);
+    }
+    if (errorSensorId) {
+      this.log.info(`   错误: ${errorSensorId}`);
+    }
+    
+    const controller = new HAVacuumController(
+      this.haClient, 
+      entityId,
+      batterySensorId,
+      chargingSensorId,
+      cleaningModeEntityId,
+      errorSensorId
+    );
+    await controller.initialize();
+    
+    const state = controller.getState();
+    if (!state) throw new Error('No vacuum state available');
+    
+    this.log.info(
+      `   状态:${state.state} | 电量:${state.batteryLevel}% | 充电:${state.isCharging ? '是' : '否'} | ` +
+      `模式:${state.cleaningMode || '无'} | 风速:${state.fanSpeed || '无'}`
+    );
+    
+    const device = this.createMatterDevice(entityId, state, controller);
+    await this.registerDevice(device);
+    
+    this.vacuumControllers.set(entityId, controller);
+    this.matterDevices.set(entityId, device);
+    
+    this.log.info(`✅ 注册完成\n`);
+  }
+
+  private createMatterDevice(
+    entityId: string,
+    state: VacuumState,
+    controller: HAVacuumController
+  ): RoboticVacuumCleaner {
+    const name = state.rawAttributes?.friendly_name || entityId;
+    this.log.info(`   创建 Matter 设备: ${name}`);
+    
+    const initialOperationalState = mapHAStateToOperationalState(state.state, state.isCharging);
+    const initialRunMode = mapHAStateToRunMode(state.state);
+    
+    const device = new RoboticVacuumCleaner(
+      name, entityId, 'server', initialRunMode, SUPPORTED_RUN_MODES,
+      CLEAN_MODE.VacMopQuiet, SUPPORTED_CLEAN_MODES,
+      undefined, undefined, initialOperationalState, OPERATIONAL_STATES,
+      SUPPORTED_AREAS, undefined, SUPPORTED_AREAS[0]?.areaId, []
+    );
+    
+    this.log.info(`   初始状态 → 运行:${initialOperationalState} | 模式:${initialRunMode} | 充电:${state.isCharging ? '是' : '否'}`);
+    
+    // 设置初始电量
+    this.updateBatteryState(device, state);
+    
+    let selectedAreaIds: number[] = [];
+    
+    // Command handlers
+    device.addCommandHandler('selectAreas', async ({ request }) => {
+      const { newAreas } = request as ServiceArea.SelectAreasRequest;
+      selectedAreaIds = newAreas || [];
+      const areaNames = selectedAreaIds.map(id => 
+        SUPPORTED_AREAS.find(a => a.areaId === id)?.areaInfo?.locationInfo?.locationName || `Area ${id}`
+      );
+      this.log.info(`📍 选择区域: ${areaNames.join('、')}`);
+    });
+    
+    device.addCommandHandler('pause', async () => {
+      this.log.info(`⏸  暂停清扫`);
+      await controller.pause();
+    });
+    
+    device.addCommandHandler('resume', async () => {
+      this.log.info(`▶️  继续清扫`);
+      if (selectedAreaIds.length > 0 && selectedAreaIds.length < SUPPORTED_AREAS.length) {
+        await controller.cleanSegments(selectedAreaIds, MATTER_TO_DREAME_SEGMENT);
+        
+        // 15秒后主动刷新状态
+        setTimeout(async () => {
+          try {
+            this.log.info(`⏰ 15秒后自动刷新状态`);
+            await controller.forceRefreshState();
+          } catch (error) {
+            this.log.error(`❌ 自动刷新状态失败:`, error);
+          }
+        }, 15000);
+      } else {
+        await controller.start();
+      }
+    });
+    
+    device.addCommandHandler('goHome', async () => {
+      this.log.info(`🏠 返回充电`);
+      selectedAreaIds = [];
+      await controller.returnToBase();
+    });
+    
+    // Locate/Identify 命令
+    device.addCommandHandler('identify', async ({ request }) => {
+      this.log.info(`📍 定位扫地机`);
+      try {
+        await controller.locate();
+        this.log.info(`✅ 定位成功`);
+      } catch (error) {
+        this.log.error(`❌ 定位失败:`, error);
+      }
+    });
+    
+    device.addCommandHandler('changeToMode', async ({ request }) => {
+      const mode = (request as any).newMode;
+      const modeName = CLEAN_MODE_LABELS[mode] || `Unknown(${mode})`;
+      const haConfig = CLEAN_MODE_TO_HA[mode];
+      
+      if (haConfig) {
+        this.log.info(`🔄 切换模式: ${modeName} → ${haConfig.cleaningMode} + ${haConfig.fanSpeed}`);
+        
+        try {
+          // 设置清洁模式和风速
+          await controller.setCleaningModeAndFanSpeed(haConfig);
+          this.log.info(`✅ 模式切换成功`);
+        } catch (error) {
+          this.log.error(`❌ 模式切换失败:`, error);
+        }
+      } else {
+        this.log.warn(`⚠️  未知模式: ${mode}`);
+      }
+      
+      // 如果是 Cleaning 模式，启动清扫
+      if (mode === 2 || modeName.includes('Cleaning')) {
+        if (selectedAreaIds.length > 0 && selectedAreaIds.length < SUPPORTED_AREAS.length) {
+          await controller.cleanSegments(selectedAreaIds, MATTER_TO_DREAME_SEGMENT);
+          
+          // 15秒后主动刷新状态
+          setTimeout(async () => {
+            try {
+              this.log.info(`⏰ 15秒后自动刷新状态`);
+              await controller.forceRefreshState();
+            } catch (error) {
+              this.log.error(`❌ 自动刷新状态失败:`, error);
+            }
+          }, 15000);
+        } else {
+          await controller.start();
+        }
+      }
+    });
+    
+    // State sync
+    controller.on('stateChanged', (s: VacuumState) => {
+      const errorStr = s.errorMsg ? ` | ❌ ${s.errorMsg}` : '';
+      
+      // 显示关键状态标志（running/started/paused）
+      const runningStr = s.rawAttributes?.running ? '🏃 running' : '';
+      const startedStr = s.rawAttributes?.started ? '▶️  started' : '';
+      const pausedStr = s.rawAttributes?.paused ? '⏸️  paused' : '';
+      const returningStr = s.rawAttributes?.returning ? '🔙 returning' : '';
+      const statusFlags = [runningStr, startedStr, pausedStr, returningStr].filter(Boolean).join(' | ');
+      
+      this.log.info(
+        `🔄 ${s.state} | ${s.batteryLevel}% | ${s.isCharging ? '充电中' : '未充电'} | ` +
+        `${s.cleaningMode || '无模式'} | ${s.fanSpeed || '无风速'}${errorStr}`
+      );
+      
+      if (statusFlags) {
+        this.log.info(`   状态标志: ${statusFlags}`);
+      }
+      
+      // 更新电池状态
+      this.updateBatteryState(device, s);
+      
+      // 更新运行状态（传递 rawAttributes 而不是 detailedStatus）
+      const newOperationalState = mapHAStateToOperationalState(
+        s.state, 
+        s.isCharging, 
+        s.errorMsg,
+        s.rawAttributes
+      );
+        
+        // 如果有错误，显示错误详情
+        if (s.errorMsg && s.errorMsg !== 'no_error' && s.errorMsg !== 'unavailable') {
+          const errorInfo = mapDreameErrorToMatter(s.errorMsg);
+          if (errorInfo) {
+            this.log.info(`   ✓ 运行状态: ${newOperationalState} (Error)`);
+            this.log.info(`   ✓ 错误详情: ${errorInfo.errorStateLabel} - ${s.errorMsg}`);
+          }
+        }
+      try {
+        device.setAttribute(
+          RvcOperationalState.Cluster.id,
+          'operationalState',
+          newOperationalState,
+          this.log
+        );
+        this.log.debug(`   ✓ 运行状态: ${newOperationalState}`);
+      } catch (error) {
+        this.log.error(`   ✗ 运行状态更新失败:`, error);
+      }
+      
+      // 更新运行模式
+      const newRunMode = mapHAStateToRunMode(s.state);
+      try {
+        device.setAttribute(
+          RvcRunMode.Cluster.id,
+          'currentMode',
+          newRunMode,
+          this.log
+        );
+        this.log.debug(`   ✓ 运行模式: ${newRunMode}`);
+      } catch (error) {
+        this.log.error(`   ✗ 运行模式更新失败:`, error);
+      }
+    });
+    
+    return device;
+  }
+
+  private updateBatteryState(device: RoboticVacuumCleaner, state: VacuumState): void {
+    try {
+      const batPercentRemaining = Math.min(200, Math.max(0, state.batteryLevel * 2));
+      const batChargeLevel = state.isCharging 
+        ? PowerSource.BatChargeLevel.Ok 
+        : (state.batteryLevel > 20 ? PowerSource.BatChargeLevel.Ok : PowerSource.BatChargeLevel.Critical);
+      
+      const batChargeState = state.isCharging 
+        ? PowerSource.BatChargeState.IsCharging 
+        : PowerSource.BatChargeState.IsNotCharging;
+      
+      this.log.debug(
+        `   🔋 电量: ${state.batteryLevel}% (Matter值:${batPercentRemaining}) | ` +
+        `充电:${state.isCharging ? '是' : '否'}`
+      );
+      
+      device.setAttribute(PowerSource.Cluster.id, 'batPercentRemaining', batPercentRemaining, this.log);
+      device.setAttribute(PowerSource.Cluster.id, 'batChargeLevel', batChargeLevel, this.log);
+      device.setAttribute(PowerSource.Cluster.id, 'batChargeState', batChargeState, this.log);
+      
+    } catch (error) {
+      this.log.error('❌ 电池状态更新失败:', error);
+    }
+  }
+
+  override async onConfigure(): Promise<void> {
+    this.log.info('⚙️  配置插件');
+  }
+
+  override async onShutdown(reason?: string): Promise<void> {
+    this.log.info(`🛑 关闭插件: ${reason || '未知原因'}`);
+    for (const ctrl of this.vacuumControllers.values()) {
+      ctrl.destroy();
+    }
+    await this.haClient?.disconnect();
+    this.vacuumControllers.clear();
+    this.matterDevices.clear();
+    this.log.info('✅ 插件已关闭');
+  }
+}
+/**
+ * 将 Dreame 错误消息映射为 Matter 错误
+ * 基于真实历史数据优化
+ */
+function mapDreameErrorToMatter(errorMsg?: string): { errorStateId: number; errorStateLabel: string; errorStateDetails: string } | null {
+  if (!errorMsg || errorMsg === 'no_error' || errorMsg === 'null') {
+    return null;
+  }
+  
+  if (errorMsg === 'unavailable') {
+    return null;
+  }
+  
+  const lowerError = errorMsg.toLowerCase().replace(/\s+/g, '_');
+  
+  const knownErrors: Record<string, { id: number; label: string }> = {
+    'drop': { id: 0x02, label: '悬崖传感器' },
+    'bumper': { id: 0x02, label: '碰撞传感器异常' },
+    'route': { id: 0x02, label: '路径规划失败' },
+    'mop_removed': { id: 0x03, label: '拖布未安装' },
+    'clean_mop_pad': { id: 0x03, label: '需要清洁拖布' },
+    'unknown': { id: 0x02, label: '未知错误' },
+  };
+  
+  if (knownErrors[lowerError]) {
+    return {
+      errorStateId: knownErrors[lowerError].id,
+      errorStateLabel: knownErrors[lowerError].label,
+      errorStateDetails: errorMsg
+    };
+  }
+  
+  if (lowerError.includes('wheel') || lowerError.includes('brush') || 
+      lowerError.includes('stuck') || lowerError.includes('sensor')) {
+    return {
+      errorStateId: 0x02,
+      errorStateLabel: '机械/传感器故障',
+      errorStateDetails: errorMsg
+    };
+  }
+  
+  if (lowerError.includes('dustbin') || lowerError.includes('filter') || 
+      lowerError.includes('mop') || lowerError.includes('water')) {
+    return {
+      errorStateId: 0x03,
+      errorStateLabel: '需要维护',
+      errorStateDetails: errorMsg
+    };
+  }
+  
+  if (lowerError.includes('battery') || lowerError.includes('charging')) {
+    return {
+      errorStateId: 0x01,
+      errorStateLabel: '电源问题',
+      errorStateDetails: errorMsg
+    };
+  }
+  
+  return {
+    errorStateId: 0x02,
+    errorStateLabel: '设备错误',
+    errorStateDetails: errorMsg
+  };
+}

package/test/test-connection.ts

@@ -0,0 +1,53 @@
+import { HomeAssistantClient } from '../src/homeassistant-client.js';
+import { HAVacuumController } from '../src/ha-vacuum-controller.js';
+
+async function test() {
+  console.log('=== Testing HA Connection ===\n');
+
+  const HA_URL = process.env.HA_URL || 'http://homeassistant.local:8123';
+  const HA_TOKEN = process.env.HA_TOKEN || '';
+
+  if (!HA_TOKEN) {
+    console.error('❌ Set HA_TOKEN: export HA_TOKEN="your-token"');
+    process.exit(1);
+  }
+
+  try {
+    console.log('1. Creating client...');
+    const client = new HomeAssistantClient(HA_URL, HA_TOKEN);
+
+    console.log('2. Testing connection...');
+    await client.testConnection();
+
+    console.log('3. Getting vacuums...');
+    const vacuums = await client.getVacuumEntities();
+    console.log(`   Found ${vacuums.length} vacuum(s)`);
+
+    for (const v of vacuums) {
+      console.log(`   - ${v.entity_id} (${v.state}, ${v.attributes.battery_level}%)`);
+    }
+
+    if (vacuums.length > 0) {
+      console.log('\n4. Testing controller...');
+      const ctrl = new HAVacuumController(client, vacuums[0].entity_id);
+      await ctrl.initialize();
+      console.log('   ✅ Controller OK');
+
+      console.log('\n5. Testing WebSocket...');
+      await client.connectWebSocket();
+      console.log('   ✅ WebSocket OK');
+
+      console.log('\n6. Cleanup...');
+      ctrl.destroy();
+      client.disconnect();
+    }
+
+    console.log('\n✅ All tests passed!');
+    process.exit(0);
+  } catch (error) {
+    console.error('\n❌ Test failed:', error);
+    process.exit(1);
+  }
+}
+
+test();

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*", "test/**/*"],
+  "exclude": ["node_modules", "dist"]
+}