@ecobridge.xyz/devicemanager 3.0.2

package/ts/features/feature.fan.ts

@@ -0,0 +1,296 @@
+/**
+ * Fan Feature
+ * Provides control for fans (speed, oscillation, direction)
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type { IFeatureOptions } from '../interfaces/feature.interfaces.js';
+import type {
+  TFanProtocol,
+  TFanDirection,
+  IFanCapabilities,
+  IFanState,
+  IFanFeatureInfo,
+  IFanProtocolClient,
+} from '../interfaces/smarthome.interfaces.js';
+
+/**
+ * Options for creating a FanFeature
+ */
+export interface IFanFeatureOptions extends IFeatureOptions {
+  /** Protocol type */
+  protocol: TFanProtocol;
+  /** Entity ID (for Home Assistant) */
+  entityId: string;
+  /** Protocol client for controlling the fan */
+  protocolClient: IFanProtocolClient;
+  /** Fan capabilities */
+  capabilities?: Partial<IFanCapabilities>;
+}
+
+/**
+ * Fan Feature - speed, oscillation, and direction control
+ *
+ * Protocol-agnostic: works with Home Assistant, MQTT, Bond, etc.
+ *
+ * @example
+ * ```typescript
+ * const fan = device.getFeature<FanFeature>('fan');
+ * if (fan) {
+ *   await fan.turnOn(75); // 75% speed
+ *   await fan.setOscillating(true);
+ * }
+ * ```
+ */
+export class FanFeature extends Feature {
+  public readonly type = 'fan' as const;
+  public readonly protocol: TFanProtocol;
+
+  /** Entity ID (e.g., "fan.bedroom") */
+  public readonly entityId: string;
+
+  /** Capabilities */
+  public readonly capabilities: IFanCapabilities;
+
+  /** Current state */
+  protected _isOn: boolean = false;
+  protected _percentage?: number;
+  protected _presetMode?: string;
+  protected _oscillating?: boolean;
+  protected _direction?: TFanDirection;
+
+  /** Protocol client for controlling the fan */
+  private protocolClient: IFanProtocolClient;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: IFanFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    this.entityId = options.entityId;
+    this.protocolClient = options.protocolClient;
+
+    this.capabilities = {
+      supportsSpeed: options.capabilities?.supportsSpeed ?? true,
+      supportsOscillate: options.capabilities?.supportsOscillate ?? false,
+      supportsDirection: options.capabilities?.supportsDirection ?? false,
+      supportsPresetModes: options.capabilities?.supportsPresetModes ?? false,
+      presetModes: options.capabilities?.presetModes,
+      speedCount: options.capabilities?.speedCount,
+    };
+  }
+
+  // ============================================================================
+  // Properties
+  // ============================================================================
+
+  /**
+   * Get current on/off state (cached)
+   */
+  public get isOn(): boolean {
+    return this._isOn;
+  }
+
+  /**
+   * Get current speed percentage 0-100 (cached)
+   */
+  public get percentage(): number | undefined {
+    return this._percentage;
+  }
+
+  /**
+   * Get current preset mode (cached)
+   */
+  public get presetMode(): string | undefined {
+    return this._presetMode;
+  }
+
+  /**
+   * Get oscillating state (cached)
+   */
+  public get oscillating(): boolean | undefined {
+    return this._oscillating;
+  }
+
+  /**
+   * Get direction (cached)
+   */
+  public get direction(): TFanDirection | undefined {
+    return this._direction;
+  }
+
+  /**
+   * Get available preset modes
+   */
+  public get presetModes(): string[] | undefined {
+    return this.capabilities.presetModes;
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    try {
+      const state = await this.protocolClient.getState(this.entityId);
+      this.updateStateInternal(state);
+    } catch {
+      // Ignore errors fetching initial state
+    }
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    // Nothing to disconnect
+  }
+
+  // ============================================================================
+  // Fan Control
+  // ============================================================================
+
+  /**
+   * Turn on the fan
+   * @param percentage Optional speed percentage
+   */
+  public async turnOn(percentage?: number): Promise<void> {
+    await this.protocolClient.turnOn(this.entityId, percentage);
+    this._isOn = true;
+    if (percentage !== undefined) {
+      this._percentage = percentage;
+    }
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Turn off the fan
+   */
+  public async turnOff(): Promise<void> {
+    await this.protocolClient.turnOff(this.entityId);
+    this._isOn = false;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Toggle the fan
+   */
+  public async toggle(): Promise<void> {
+    await this.protocolClient.toggle(this.entityId);
+    this._isOn = !this._isOn;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Set speed percentage
+   * @param percentage Speed 0-100
+   */
+  public async setPercentage(percentage: number): Promise<void> {
+    if (!this.capabilities.supportsSpeed) {
+      throw new Error('Fan does not support speed control');
+    }
+
+    const clamped = Math.max(0, Math.min(100, Math.round(percentage)));
+    await this.protocolClient.setPercentage(this.entityId, clamped);
+    this._percentage = clamped;
+    this._isOn = clamped > 0;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Set preset mode
+   * @param mode Preset mode name
+   */
+  public async setPresetMode(mode: string): Promise<void> {
+    if (!this.capabilities.supportsPresetModes) {
+      throw new Error('Fan does not support preset modes');
+    }
+
+    await this.protocolClient.setPresetMode(this.entityId, mode);
+    this._presetMode = mode;
+    this._isOn = true;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Set oscillating state
+   * @param oscillating Whether to oscillate
+   */
+  public async setOscillating(oscillating: boolean): Promise<void> {
+    if (!this.capabilities.supportsOscillate) {
+      throw new Error('Fan does not support oscillation');
+    }
+
+    await this.protocolClient.setOscillating(this.entityId, oscillating);
+    this._oscillating = oscillating;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Set direction
+   * @param direction forward or reverse
+   */
+  public async setDirection(direction: TFanDirection): Promise<void> {
+    if (!this.capabilities.supportsDirection) {
+      throw new Error('Fan does not support direction control');
+    }
+
+    await this.protocolClient.setDirection(this.entityId, direction);
+    this._direction = direction;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Get current state as object
+   */
+  public getState(): IFanState {
+    return {
+      isOn: this._isOn,
+      percentage: this._percentage,
+      presetMode: this._presetMode,
+      oscillating: this._oscillating,
+      direction: this._direction,
+    };
+  }
+
+  /**
+   * Refresh state from the device
+   */
+  public async refreshState(): Promise<IFanState> {
+    const state = await this.protocolClient.getState(this.entityId);
+    this.updateStateInternal(state);
+    return state;
+  }
+
+  /**
+   * Update state from external source
+   */
+  public updateState(state: IFanState): void {
+    this.updateStateInternal(state);
+    this.emit('state:changed', state);
+  }
+
+  /**
+   * Internal state update
+   */
+  private updateStateInternal(state: IFanState): void {
+    this._isOn = state.isOn;
+    this._percentage = state.percentage;
+    this._presetMode = state.presetMode;
+    this._oscillating = state.oscillating;
+    this._direction = state.direction;
+  }
+
+  // ============================================================================
+  // Feature Info
+  // ============================================================================
+
+  public getFeatureInfo(): IFanFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'fan',
+      protocol: this.protocol,
+      capabilities: this.capabilities,
+      currentState: this.getState(),
+    };
+  }
+}

package/ts/features/feature.light.ts

@@ -0,0 +1,369 @@
+/**
+ * Light Feature
+ * Provides control for smart lights (brightness, color, effects)
+ */
+
+import { Feature, type TDeviceReference } from './feature.abstract.js';
+import type { IFeatureOptions } from '../interfaces/feature.interfaces.js';
+import type {
+  TLightProtocol,
+  ILightCapabilities,
+  ILightState,
+  ILightFeatureInfo,
+  ILightProtocolClient,
+} from '../interfaces/smarthome.interfaces.js';
+
+/**
+ * Options for creating a LightFeature
+ */
+export interface ILightFeatureOptions extends IFeatureOptions {
+  /** Protocol type */
+  protocol: TLightProtocol;
+  /** Entity ID (for Home Assistant) */
+  entityId: string;
+  /** Protocol client for controlling the light */
+  protocolClient: ILightProtocolClient;
+  /** Light capabilities */
+  capabilities?: Partial<ILightCapabilities>;
+}
+
+/**
+ * Light Feature - brightness, color, and effect control
+ *
+ * Protocol-agnostic: works with Home Assistant, Hue, MQTT, Zigbee, etc.
+ *
+ * @example
+ * ```typescript
+ * const light = device.getFeature<LightFeature>('light');
+ * if (light) {
+ *   await light.turnOn({ brightness: 200 });
+ *   await light.setColorTemp(4000); // 4000K warm white
+ *   await light.setRgbColor(255, 100, 50);
+ * }
+ * ```
+ */
+export class LightFeature extends Feature {
+  public readonly type = 'light' as const;
+  public readonly protocol: TLightProtocol;
+
+  /** Entity ID (e.g., "light.living_room") */
+  public readonly entityId: string;
+
+  /** Capabilities */
+  public readonly capabilities: ILightCapabilities;
+
+  /** Current state */
+  protected _isOn: boolean = false;
+  protected _brightness?: number;
+  protected _colorTemp?: number;
+  protected _colorTempMireds?: number;
+  protected _rgbColor?: [number, number, number];
+  protected _hsColor?: [number, number];
+  protected _xyColor?: [number, number];
+  protected _effect?: string;
+
+  /** Protocol client for controlling the light */
+  private protocolClient: ILightProtocolClient;
+
+  constructor(
+    device: TDeviceReference,
+    port: number,
+    options: ILightFeatureOptions
+  ) {
+    super(device, port, options);
+    this.protocol = options.protocol;
+    this.entityId = options.entityId;
+    this.protocolClient = options.protocolClient;
+
+    // Set capabilities with defaults
+    this.capabilities = {
+      supportsBrightness: options.capabilities?.supportsBrightness ?? false,
+      supportsColorTemp: options.capabilities?.supportsColorTemp ?? false,
+      supportsRgb: options.capabilities?.supportsRgb ?? false,
+      supportsHs: options.capabilities?.supportsHs ?? false,
+      supportsXy: options.capabilities?.supportsXy ?? false,
+      supportsEffects: options.capabilities?.supportsEffects ?? false,
+      supportsTransition: options.capabilities?.supportsTransition ?? true,
+      effects: options.capabilities?.effects,
+      minMireds: options.capabilities?.minMireds,
+      maxMireds: options.capabilities?.maxMireds,
+      minColorTempKelvin: options.capabilities?.minColorTempKelvin,
+      maxColorTempKelvin: options.capabilities?.maxColorTempKelvin,
+    };
+  }
+
+  // ============================================================================
+  // Properties
+  // ============================================================================
+
+  /**
+   * Get current on/off state (cached)
+   */
+  public get isOn(): boolean {
+    return this._isOn;
+  }
+
+  /**
+   * Get current brightness 0-255 (cached)
+   */
+  public get brightness(): number | undefined {
+    return this._brightness;
+  }
+
+  /**
+   * Get current color temperature in Kelvin (cached)
+   */
+  public get colorTemp(): number | undefined {
+    return this._colorTemp;
+  }
+
+  /**
+   * Get current color temperature in Mireds (cached)
+   */
+  public get colorTempMireds(): number | undefined {
+    return this._colorTempMireds;
+  }
+
+  /**
+   * Get current RGB color (cached)
+   */
+  public get rgbColor(): [number, number, number] | undefined {
+    return this._rgbColor;
+  }
+
+  /**
+   * Get current HS color [hue 0-360, saturation 0-100] (cached)
+   */
+  public get hsColor(): [number, number] | undefined {
+    return this._hsColor;
+  }
+
+  /**
+   * Get current XY color (cached)
+   */
+  public get xyColor(): [number, number] | undefined {
+    return this._xyColor;
+  }
+
+  /**
+   * Get current effect (cached)
+   */
+  public get effect(): string | undefined {
+    return this._effect;
+  }
+
+  /**
+   * Get available effects
+   */
+  public get effects(): string[] | undefined {
+    return this.capabilities.effects;
+  }
+
+  // ============================================================================
+  // Connection
+  // ============================================================================
+
+  protected async doConnect(): Promise<void> {
+    // Fetch initial state
+    try {
+      const state = await this.protocolClient.getState(this.entityId);
+      this.updateStateInternal(state);
+    } catch {
+      // Ignore errors fetching initial state
+    }
+  }
+
+  protected async doDisconnect(): Promise<void> {
+    // Nothing to disconnect
+  }
+
+  // ============================================================================
+  // Light Control
+  // ============================================================================
+
+  /**
+   * Turn on the light
+   * @param options Optional settings to apply when turning on
+   */
+  public async turnOn(options?: {
+    brightness?: number;
+    colorTemp?: number;
+    rgb?: [number, number, number];
+    transition?: number;
+  }): Promise<void> {
+    await this.protocolClient.turnOn(this.entityId, options);
+    this._isOn = true;
+    if (options?.brightness !== undefined) {
+      this._brightness = options.brightness;
+    }
+    if (options?.colorTemp !== undefined) {
+      this._colorTemp = options.colorTemp;
+    }
+    if (options?.rgb !== undefined) {
+      this._rgbColor = options.rgb;
+    }
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Turn off the light
+   * @param options Optional transition time
+   */
+  public async turnOff(options?: { transition?: number }): Promise<void> {
+    await this.protocolClient.turnOff(this.entityId, options);
+    this._isOn = false;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Toggle the light
+   */
+  public async toggle(): Promise<void> {
+    await this.protocolClient.toggle(this.entityId);
+    this._isOn = !this._isOn;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Set brightness level
+   * @param brightness Brightness 0-255
+   * @param transition Optional transition time in seconds
+   */
+  public async setBrightness(brightness: number, transition?: number): Promise<void> {
+    if (!this.capabilities.supportsBrightness) {
+      throw new Error('Light does not support brightness control');
+    }
+
+    const clamped = Math.max(0, Math.min(255, Math.round(brightness)));
+    await this.protocolClient.setBrightness(this.entityId, clamped, transition);
+    this._brightness = clamped;
+    if (clamped > 0) {
+      this._isOn = true;
+    }
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Set color temperature in Kelvin
+   * @param kelvin Color temperature in Kelvin (e.g., 2700 warm, 6500 cool)
+   * @param transition Optional transition time in seconds
+   */
+  public async setColorTemp(kelvin: number, transition?: number): Promise<void> {
+    if (!this.capabilities.supportsColorTemp) {
+      throw new Error('Light does not support color temperature');
+    }
+
+    // Clamp to supported range if available
+    let clamped = kelvin;
+    if (this.capabilities.minColorTempKelvin && this.capabilities.maxColorTempKelvin) {
+      clamped = Math.max(
+        this.capabilities.minColorTempKelvin,
+        Math.min(this.capabilities.maxColorTempKelvin, kelvin)
+      );
+    }
+
+    await this.protocolClient.setColorTemp(this.entityId, clamped, transition);
+    this._colorTemp = clamped;
+    this._colorTempMireds = Math.round(1000000 / clamped);
+    this._isOn = true;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Set RGB color
+   * @param r Red 0-255
+   * @param g Green 0-255
+   * @param b Blue 0-255
+   * @param transition Optional transition time in seconds
+   */
+  public async setRgbColor(r: number, g: number, b: number, transition?: number): Promise<void> {
+    if (!this.capabilities.supportsRgb) {
+      throw new Error('Light does not support RGB color');
+    }
+
+    const clampedR = Math.max(0, Math.min(255, Math.round(r)));
+    const clampedG = Math.max(0, Math.min(255, Math.round(g)));
+    const clampedB = Math.max(0, Math.min(255, Math.round(b)));
+
+    await this.protocolClient.setRgbColor(this.entityId, clampedR, clampedG, clampedB, transition);
+    this._rgbColor = [clampedR, clampedG, clampedB];
+    this._isOn = true;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Set light effect
+   * @param effect Effect name from available effects
+   */
+  public async setEffect(effect: string): Promise<void> {
+    if (!this.capabilities.supportsEffects) {
+      throw new Error('Light does not support effects');
+    }
+
+    await this.protocolClient.setEffect(this.entityId, effect);
+    this._effect = effect;
+    this._isOn = true;
+    this.emit('state:changed', this.getState());
+  }
+
+  /**
+   * Get current state as object
+   */
+  public getState(): ILightState {
+    return {
+      isOn: this._isOn,
+      brightness: this._brightness,
+      colorTemp: this._colorTemp,
+      colorTempMireds: this._colorTempMireds,
+      rgbColor: this._rgbColor,
+      hsColor: this._hsColor,
+      xyColor: this._xyColor,
+      effect: this._effect,
+    };
+  }
+
+  /**
+   * Refresh state from the device
+   */
+  public async refreshState(): Promise<ILightState> {
+    const state = await this.protocolClient.getState(this.entityId);
+    this.updateStateInternal(state);
+    return state;
+  }
+
+  /**
+   * Update state from external source (e.g., state change event)
+   */
+  public updateState(state: ILightState): void {
+    this.updateStateInternal(state);
+    this.emit('state:changed', state);
+  }
+
+  /**
+   * Internal state update
+   */
+  private updateStateInternal(state: ILightState): void {
+    this._isOn = state.isOn;
+    this._brightness = state.brightness;
+    this._colorTemp = state.colorTemp;
+    this._colorTempMireds = state.colorTempMireds;
+    this._rgbColor = state.rgbColor;
+    this._hsColor = state.hsColor;
+    this._xyColor = state.xyColor;
+    this._effect = state.effect;
+  }
+
+  // ============================================================================
+  // Feature Info
+  // ============================================================================
+
+  public getFeatureInfo(): ILightFeatureInfo {
+    return {
+      ...this.getBaseFeatureInfo(),
+      type: 'light',
+      protocol: this.protocol,
+      capabilities: this.capabilities,
+      currentState: this.getState(),
+    };
+  }
+}