homebridge-tsvesync 1.3.11 → 1.3.13

package/src/__tests__/accessories/air-quality-sensor.accessory.test.ts

@@ -0,0 +1,231 @@
+import { API, Logger } from 'homebridge';
+import { TSVESyncPlatform } from '../../platform';
+import { VeSync } from 'tsvesync';
+import { AirQualitySensorAccessory } from '../../accessories/air-quality-sensor.accessory';
+import { createMockLogger, createMockVeSync } from '../utils/test-helpers';
+
+interface MockAirQualityDevice {
+  deviceName: string;
+  deviceType: string;
+  cid: string;
+  uuid: string;
+  deviceStatus: string;
+  airQualityValue: number;
+  details: Record<string, any>;
+  getDetails: jest.Mock;
+  getNormalizedAirQuality?: jest.Mock;
+  airQualityLevel?: number;
+  airQualityLabel?: string;
+}
+
+describe('AirQualitySensorAccessory', () => {
+  let mockAPI: jest.Mocked<API>;
+  let platform: TSVESyncPlatform;
+  let logger: jest.Mocked<Logger>;
+  let api: jest.Mocked<VeSync>;
+
+  const AirQualityEnum = {
+    UNKNOWN: 0,
+    EXCELLENT: 1,
+    GOOD: 2,
+    FAIR: 3,
+    INFERIOR: 4,
+    POOR: 5,
+  } as const;
+
+  const ServiceEnum = {
+    AirQualitySensor: 'AirQualitySensor',
+    AccessoryInformation: 'AccessoryInformation',
+  } as const;
+
+  const createDevice = (overrides: Partial<MockAirQualityDevice> = {}): MockAirQualityDevice => ({
+    deviceName: overrides.deviceName || 'Dining Room AQ',
+    deviceType: overrides.deviceType || 'Core300S',
+    cid: overrides.cid || 'cid-123',
+    uuid: overrides.uuid || 'uuid-123',
+    deviceStatus: overrides.deviceStatus || 'on',
+    airQualityValue: overrides.airQualityValue ?? 18,
+    details: overrides.details || {
+      air_quality_value: overrides.airQualityValue ?? 18,
+      air_quality_level: overrides.airQualityLevel,
+      air_quality: overrides.airQualityLabel ?? 'good',
+      pm10: 22,
+    },
+    getDetails: overrides.getDetails || jest.fn().mockResolvedValue(true),
+    getNormalizedAirQuality: overrides.getNormalizedAirQuality,
+    airQualityLevel: overrides.airQualityLevel,
+    airQualityLabel: overrides.airQualityLabel,
+  });
+
+  const buildAccessory = (device: MockAirQualityDevice) => {
+    const airQualityService = {
+      getCharacteristic: jest.fn().mockImplementation((characteristic) => {
+        if (characteristic === AirQualityEnum) {
+          return {
+            setProps: jest.fn().mockReturnThis(),
+            onGet: jest.fn().mockReturnThis(),
+            updateValue: jest.fn().mockReturnThis(),
+          };
+        }
+        return {
+          onGet: jest.fn().mockReturnThis(),
+          updateValue: jest.fn().mockReturnThis(),
+          setProps: jest.fn().mockReturnThis(),
+        };
+      }),
+      setCharacteristic: jest.fn().mockReturnThis(),
+      updateCharacteristic: jest.fn().mockReturnThis(),
+    } as any;
+
+    const infoService = {
+      setCharacteristic: jest.fn().mockReturnThis(),
+    } as any;
+
+    const accessory = {
+      getService: jest.fn((service) => {
+        if (service === ServiceEnum.AccessoryInformation) return infoService;
+        if (service === ServiceEnum.AirQualitySensor) return null;
+        return null;
+      }),
+      addService: jest.fn((service) => {
+        if (service === ServiceEnum.AirQualitySensor) {
+          return airQualityService;
+        }
+        return airQualityService;
+      }),
+    } as any;
+
+    const accessoryInstance = new AirQualitySensorAccessory(platform, accessory, device as any);
+
+    return {
+      accessoryInstance,
+      airQualityService,
+      infoService,
+      accessory,
+    };
+  };
+
+  beforeEach(() => {
+    logger = createMockLogger();
+    api = createMockVeSync();
+
+    mockAPI = {
+      hap: {
+        Characteristic: {
+          AirQuality: AirQualityEnum,
+          PM2_5Density: 'PM2_5Density',
+          PM10Density: 'PM10Density',
+          Manufacturer: 'Manufacturer',
+          Model: 'Model',
+          SerialNumber: 'SerialNumber',
+          Name: 'Name',
+        },
+        Service: ServiceEnum,
+        uuid: {
+          generate: jest.fn(),
+        },
+      },
+      platformAccessory: jest.fn(),
+    } as unknown as jest.Mocked<API>;
+
+    platform = new TSVESyncPlatform(logger, { debug: false, retry: { maxRetries: 3 } } as any, mockAPI);
+    (platform as any).api = api;
+  });
+
+  it('configures AirQuality characteristic to expose VeSync levels', () => {
+    const device = createDevice({
+      getNormalizedAirQuality: jest.fn().mockReturnValue({ level: 2, label: 'good' }),
+      airQualityLevel: 2,
+      airQualityLabel: 'good',
+    });
+
+    const { airQualityService } = buildAccessory(device);
+
+    expect(airQualityService.getCharacteristic).toHaveBeenCalledWith(AirQualityEnum);
+    const setter = airQualityService.getCharacteristic.mock.results[0].value.setProps;
+    expect(setter).toHaveBeenCalledWith({
+      validValues: [
+        AirQualityEnum.UNKNOWN,
+        AirQualityEnum.EXCELLENT,
+        AirQualityEnum.GOOD,
+        AirQualityEnum.FAIR,
+        AirQualityEnum.INFERIOR,
+      ],
+    });
+  });
+
+  it('returns normalized air quality levels when provided by the device', async () => {
+    const device = createDevice({
+      getNormalizedAirQuality: jest.fn().mockReturnValue({ level: 3, label: 'moderate' }),
+      airQualityValue: 42,
+    });
+
+    const { accessoryInstance } = buildAccessory(device);
+
+    const value = await (accessoryInstance as any).getAirQuality();
+    expect(value).toBe(AirQualityEnum.FAIR);
+    expect(device.getNormalizedAirQuality).toHaveBeenCalled();
+  });
+
+  it('falls back to direct level properties when normalized metadata is unavailable', async () => {
+    const device = createDevice({
+      getNormalizedAirQuality: undefined,
+      airQualityLevel: 4,
+      details: {
+        air_quality_level: 4,
+        air_quality_value: 80,
+      },
+      airQualityValue: 80,
+    });
+
+    const { accessoryInstance } = buildAccessory(device);
+
+    const value = await (accessoryInstance as any).getAirQuality();
+    expect(value).toBe(AirQualityEnum.INFERIOR);
+  });
+
+  it('falls back to PM2.5 heuristic when no level information is available', async () => {
+    const device = createDevice({
+      getNormalizedAirQuality: undefined,
+      airQualityLevel: undefined,
+      details: {
+        air_quality_value: 120,
+      },
+      airQualityValue: 120,
+    });
+
+    const { accessoryInstance } = buildAccessory(device);
+
+    const value = await (accessoryInstance as any).getAirQuality();
+    expect(value).toBe(AirQualityEnum.INFERIOR);
+  });
+
+  it('clamps PM2.5 density to HomeKit-supported range', async () => {
+    const device = createDevice({
+      airQualityValue: 1450,
+      details: {
+        air_quality_value: 1450,
+      },
+    });
+
+    const { accessoryInstance } = buildAccessory(device);
+
+    const density = await (accessoryInstance as any).getPM25Density();
+    expect(density).toBe(1000);
+  });
+
+  it('updates characteristics during refresh cycle', async () => {
+    const device = createDevice({
+      airQualityValue: 24,
+      getNormalizedAirQuality: jest.fn().mockReturnValue({ level: 2, label: 'good' }),
+    });
+
+    const { accessoryInstance, airQualityService } = buildAccessory(device);
+
+    await (accessoryInstance as any).updateCharacteristics();
+
+    expect(device.getDetails).toHaveBeenCalled();
+    expect(airQualityService.updateCharacteristic).toHaveBeenCalledWith(AirQualityEnum, AirQualityEnum.GOOD);
+    expect(airQualityService.updateCharacteristic).toHaveBeenCalledWith('PM2_5Density', 24);
+  });
+});

package/src/__tests__/base.accessory.test.ts

@@ -299,7 +299,7 @@ describe('BaseAccessory', () => {
       expect((accessory as any).convertAirQualityToHomeKit(30)).toBe(2);  // GOOD
       expect((accessory as any).convertAirQualityToHomeKit(50)).toBe(3);  // FAIR
       expect((accessory as any).convertAirQualityToHomeKit(100)).toBe(4); // INFERIOR
-      expect((accessory as any).convertAirQualityToHomeKit(200)).toBe(5); // POOR
+      expect((accessory as any).convertAirQualityToHomeKit(200)).toBe(4); // INFERIOR
     });
 
     it('should persist device state', async () => {
@@ -309,4 +309,4 @@ describe('BaseAccessory', () => {
       expect(mockAccessory.context.device.details.testKey).toBe('testValue');
     });
   });
-}); 
+}); 

package/src/__tests__/devices/light.test.ts

@@ -547,6 +547,7 @@ describe('Light Device Tests', () => {
 
       await onCharacteristic._onSet(true);
 
+      expect(dimmer.turnOn).toHaveBeenCalled();
       expect(dimmer.setBrightness).toHaveBeenCalledWith(37);
     });
 
@@ -556,10 +557,13 @@ describe('Light Device Tests', () => {
 
       await onCharacteristic._onSet(true);
       await onCharacteristic._onSet(false);
+      expect(dimmer.turnOn).toHaveBeenCalledTimes(1);
+      expect(dimmer.turnOff).toHaveBeenCalledTimes(1);
       dimmer.setBrightness.mockClear();
 
       await onCharacteristic._onSet(true);
 
+      expect(dimmer.turnOn).toHaveBeenCalledTimes(2);
       expect(dimmer.setBrightness).toHaveBeenCalledWith(45);
     });
 

package/src/accessories/air-quality-sensor.accessory.ts

@@ -43,7 +43,6 @@ export class AirQualitySensorAccessory extends BaseAccessory {
           this.platform.Characteristic.AirQuality.GOOD,
           this.platform.Characteristic.AirQuality.FAIR,
           this.platform.Characteristic.AirQuality.INFERIOR,
-          this.platform.Characteristic.AirQuality.POOR,
         ],
       })
       .onGet(this.getAirQuality.bind(this));
@@ -91,12 +90,15 @@ export class AirQualitySensorAccessory extends BaseAccessory {
    */
   async getAirQuality(): Promise<CharacteristicValue> {
     try {
-      // Use the device's native getter for air quality value (PM2.5)
-      const extendedDevice = this.parentDevice as any;
-      const pm25 = extendedDevice.airQualityValue || 0;
-      
-      this.platform.log.debug(`${this.device.deviceName} AQ: PM2.5 value = ${pm25}`);
-      
+      const level = this.readNormalizedAirQualityLevel();
+      if (level >= 1) {
+        const hkValue = this.mapToHomeKitAirQuality(level);
+        this.platform.log.debug(`${this.device.deviceName} AQ: Normalized air quality level = ${level}`);
+        return hkValue;
+      }
+
+      const pm25 = this.getDevicePm25();
+      this.platform.log.debug(`${this.device.deviceName} AQ: Falling back to PM2.5 heuristic (${pm25})`);
       return this.convertPM25ToAirQuality(pm25);
     } catch (error) {
       this.platform.log.error(`${this.device.deviceName} AQ: Failed to get air quality:`, error);
@@ -109,9 +111,7 @@ export class AirQualitySensorAccessory extends BaseAccessory {
    */
   async getPM25Density(): Promise<CharacteristicValue> {
     try {
-      // Use the device's native getter for air quality value (PM2.5)
-      const extendedDevice = this.parentDevice as any;
-      const pm25 = extendedDevice.airQualityValue || 0;
+      const pm25 = this.getDevicePm25();
       
       // HomeKit expects PM2.5 in μg/m³, range 0-1000
       return Math.min(1000, Math.max(0, pm25));
@@ -148,11 +148,89 @@ export class AirQualitySensorAccessory extends BaseAccessory {
       return this.platform.Characteristic.AirQuality.GOOD; // Moderate (12.1-35.4 μg/m³)
     } else if (pm25 <= 55) {
       return this.platform.Characteristic.AirQuality.FAIR; // Unhealthy for Sensitive (35.5-55.4 μg/m³)
-    } else if (pm25 <= 150) {
-      return this.platform.Characteristic.AirQuality.INFERIOR; // Unhealthy (55.5-150.4 μg/m³)
-    } else {
-      return this.platform.Characteristic.AirQuality.POOR; // Very Unhealthy (>150.5 μg/m³)
     }
+    return this.platform.Characteristic.AirQuality.INFERIOR;
+  }
+
+  private mapToHomeKitAirQuality(level: number): CharacteristicValue {
+    switch (level) {
+      case 1:
+        return this.platform.Characteristic.AirQuality.EXCELLENT;
+      case 2:
+        return this.platform.Characteristic.AirQuality.GOOD;
+      case 3:
+        return this.platform.Characteristic.AirQuality.FAIR;
+      case 4:
+        return this.platform.Characteristic.AirQuality.INFERIOR;
+      default:
+        return this.platform.Characteristic.AirQuality.UNKNOWN;
+    }
+  }
+
+  private readNormalizedAirQualityLevel(): number {
+    const extendedDevice = this.parentDevice as any;
+
+    if (typeof extendedDevice.getNormalizedAirQuality === 'function') {
+      try {
+        const normalized = extendedDevice.getNormalizedAirQuality();
+        if (normalized && typeof normalized.level === 'number' && normalized.level >= 1) {
+          return normalized.level;
+        }
+      } catch (error) {
+        this.platform.log.debug(`${this.device.deviceName} AQ: getNormalizedAirQuality failed`, error);
+      }
+    }
+
+    const directLevel = extendedDevice.airQualityLevel ?? extendedDevice.details?.air_quality_level;
+    if (typeof directLevel === 'number' && directLevel >= 1) {
+      return directLevel;
+    }
+
+    const normalized = this.normalizeAirQuality(
+      extendedDevice.airQuality ?? extendedDevice.details?.air_quality ?? extendedDevice.airQualityLabel
+    );
+
+    return normalized.level;
+  }
+
+  private getDevicePm25(): number {
+    const extendedDevice = this.parentDevice as any;
+    const pm25 = extendedDevice.airQualityValue ?? extendedDevice.details?.air_quality_value ?? extendedDevice.pm25 ?? 0;
+    return Number.isFinite(pm25) ? pm25 : 0;
+  }
+
+  private normalizeAirQuality(value: unknown): { level: number; label: string } {
+    const stringMap: Record<string, number> = {
+      'excellent': 1,
+      'very good': 1,
+      'good': 2,
+      'moderate': 3,
+      'fair': 3,
+      'inferior': 4,
+      'poor': 4,
+      'bad': 4,
+    };
+
+    if (typeof value === 'number') {
+      const level = Number.isFinite(value) ? Math.trunc(value) : -1;
+      if (level >= 1 && level <= 4) {
+        return {
+          level,
+          label: level === 1 ? 'excellent' : level === 2 ? 'good' : level === 3 ? 'moderate' : 'poor',
+        };
+      }
+    } else if (typeof value === 'string') {
+      const normalized = value.trim().toLowerCase();
+      const level = stringMap[normalized];
+      if (level) {
+        return {
+          level,
+          label: level === 1 ? 'excellent' : level === 2 ? 'good' : level === 3 ? 'moderate' : 'poor',
+        };
+      }
+    }
+
+    return { level: -1, label: 'unknown' };
   }
 
   /**
@@ -234,4 +312,4 @@ export class AirQualitySensorAccessory extends BaseAccessory {
   identify(): void {
     this.platform.log.info(`${this.device.deviceName} AQ Sensor: Identify!`);
   }
-}
+}

package/src/accessories/base.accessory.ts

@@ -226,8 +226,7 @@ export abstract class BaseAccessory {
     if (pm25 <= 12) return 1;  // EXCELLENT
     if (pm25 <= 35) return 2;  // GOOD
     if (pm25 <= 55) return 3;  // FAIR
-    if (pm25 <= 150) return 4; // INFERIOR
-    return 5;                  // POOR
+    return 4;                  // INFERIOR (VeSync exposes four levels)
   }
 
   /**

package/src/accessories/light.accessory.ts

@@ -278,8 +278,34 @@ export class LightAccessory extends BaseAccessory {
       const isOn = value as boolean;
 
       if (this.isDimmerDevice) {
-        const targetBrightness = isOn ? this.resolveDimmerOnBrightness() : 0;
-        await this.setBrightness(targetBrightness);
+        const dimmer = this.device as VeSyncDimmerSwitch;
+        if (isOn) {
+          const toggled = await dimmer.turnOn();
+          if (!toggled) {
+            throw new Error('Failed to turn on device');
+          }
+
+          const targetBrightness = this.resolveDimmerOnBrightness();
+          if (targetBrightness > 0) {
+            const brightnessSet = await dimmer.setBrightness(targetBrightness);
+            if (!brightnessSet) {
+              throw new Error(`Failed to restore brightness to ${targetBrightness}`);
+            }
+            this.lastKnownDimmerBrightness = targetBrightness;
+            this.updateCharacteristicValue(this.platform.Characteristic.Brightness, targetBrightness);
+            await this.persistDeviceState('brightness', targetBrightness);
+          }
+        } else {
+          const toggled = await dimmer.turnOff();
+          if (!toggled) {
+            throw new Error('Failed to turn off device');
+          }
+          this.updateCharacteristicValue(this.platform.Characteristic.Brightness, 0);
+          await this.persistDeviceState('brightness', 0);
+        }
+
+        await this.persistDeviceState('deviceStatus', isOn ? 'on' : 'off');
+        await this.refreshDimmerDetails();
         return;
       }
 

package/src/types/device.types.ts

@@ -67,10 +67,13 @@ export interface VeSyncDeviceWithHumidity extends VeSyncDeviceWithPower {
 
 export interface VeSyncDeviceWithAirQuality extends VeSyncDeviceWithPower {
   airQuality: number;
+  airQualityLevel?: number;
+  airQualityLabel?: string;
   pm25?: number;
   filterLife: number;
   mode: string;
   setMode(mode: string): Promise<boolean>;
+  getNormalizedAirQuality?(): { level: number; label: string };
 }
 
 export interface VeSyncDeviceWithControls extends VeSyncDeviceWithPower {