@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/wiz/wiz.mapper.ts

@@ -1,764 +1,91 @@
 import * as plugins from '../../plugins.js';
-import type { IIntegrationEntity, IIntegrationEvent, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
-import type {
-  IWizButtonRecord,
-  IWizClientCommand,
-  IWizConfig,
-  IWizDeviceFeatures,
-  IWizDeviceInfo,
-  IWizEntityRecord,
-  IWizEvent,
-  IWizManualEntry,
-  IWizPilotPatch,
-  IWizPilotState,
-  IWizSensorRecord,
-  IWizSnapshot,
-  IWizSnapshotDevice,
-} from './wiz.types.js';
-import { wizDefaultPort } from './wiz.types.js';
-
-const wizScenes: Array<{ id: number; name: string }> = [
-  { id: 35, name: 'Alarm' },
-  { id: 10, name: 'Bedtime' },
-  { id: 29, name: 'Candlelight' },
-  { id: 27, name: 'Christmas' },
-  { id: 6, name: 'Cozy' },
-  { id: 13, name: 'Cool white' },
-  { id: 26, name: 'Club' },
-  { id: 12, name: 'Daylight' },
-  { id: 33, name: 'Diwali' },
-  { id: 23, name: 'Deep dive' },
-  { id: 22, name: 'Fall' },
-  { id: 5, name: 'Fireplace' },
-  { id: 7, name: 'Forest' },
-  { id: 15, name: 'Focus' },
-  { id: 30, name: 'Golden white' },
-  { id: 28, name: 'Halloween' },
-  { id: 24, name: 'Jungle' },
-  { id: 25, name: 'Mojito' },
-  { id: 14, name: 'Night light' },
-  { id: 1, name: 'Ocean' },
-  { id: 4, name: 'Party' },
-  { id: 31, name: 'Pulse' },
-  { id: 8, name: 'Pastel colors' },
-  { id: 19, name: 'Plantgrowth' },
-  { id: 2, name: 'Romance' },
-  { id: 16, name: 'Relax' },
-  { id: 36, name: 'Snowy sky' },
-  { id: 3, name: 'Sunset' },
-  { id: 20, name: 'Spring' },
-  { id: 21, name: 'Summer' },
-  { id: 32, name: 'Steampunk' },
-  { id: 17, name: 'True colors' },
-  { id: 18, name: 'TV time' },
-  { id: 34, name: 'White' },
-  { id: 9, name: 'Wake-up' },
-  { id: 11, name: 'Warm white' },
-  { id: 1000, name: 'Rhythm' },
-];
-
-const wizSceneNamesById = new Map(wizScenes.map((sceneArg) => [sceneArg.id, sceneArg.name]));
-const wizSceneIdsByName = new Map(wizScenes.map((sceneArg) => [sceneArg.name.toLowerCase(), sceneArg.id]));
-
-const wizButtonSources: Record<string, string> = {
-  wfa1: 'on',
-  wfa2: 'off',
-  wfa3: 'night',
-  wfa8: 'decrease_brightness',
-  wfa9: 'increase_brightness',
-  wfa16: '1',
-  wfa17: '2',
-  wfa18: '3',
-  wfa19: '4',
-};
-
-const pilotPatchKeys = new Set(['state', 'sceneId', 'temp', 'dimming', 'r', 'g', 'b', 'c', 'w', 'speed', 'ratio', 'fanState', 'fanMode', 'fanSpeed', 'fanRevrs']);
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IServiceCallRequest } from '../../core/types.js';
+import type { IWizSnapshot, TWizControl } from './wiz.types.js';
+import { wizControl, wizRecord } from './wiz.validation.js';
 
 export class WizMapper {
-  public static readonly sceneNames = wizScenes.map((sceneArg) => sceneArg.name);
-
-  public static toSnapshot(configArg: IWizConfig, connectedArg?: boolean, eventsArg: IWizEvent[] = []): IWizSnapshot {
-    const source = configArg.snapshot;
-    const devices: IWizSnapshotDevice[] = [
-      ...(source?.devices || []),
-      ...(configArg.devices || []),
-    ];
-
-    for (const entry of configArg.manualEntries || []) {
-      if (entry.snapshot) {
-        devices.push(...entry.snapshot.devices);
-      } else {
-        devices.push(this.deviceFromManualEntry(entry));
-      }
-    }
-
-    if (!devices.length && (configArg.host || configArg.mac || configArg.name || configArg.deviceInfo || configArg.pilot)) {
-      devices.push({
-        host: configArg.host,
-        port: configArg.port || wizDefaultPort,
-        mac: configArg.mac || configArg.deviceInfo?.mac || configArg.pilot?.mac,
-        name: configArg.name || configArg.deviceInfo?.name,
-        deviceInfo: configArg.deviceInfo,
-        pilot: configArg.pilot,
-        available: connectedArg ?? Boolean(configArg.pilot || source?.connected),
-      });
-    }
-
-    return {
-      connected: connectedArg ?? source?.connected ?? false,
-      host: configArg.host || source?.host,
-      port: configArg.port || source?.port || wizDefaultPort,
-      devices,
-      events: [...(source?.events || []), ...(configArg.events || []), ...eventsArg],
-    };
-  }
+  public static deviceId(snapshotArg: IWizSnapshot): string { return `wiz:${encodeURIComponent(snapshotArg.homeId)}:${snapshotArg.info.macAddress}`; }
+  public static entityId(snapshotArg: IWizSnapshot): string { return `${this.deviceId(snapshotArg)}:control`; }
 
   public static toDevices(snapshotArg: IWizSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
-    const updatedAt = new Date().toISOString();
-    return snapshotArg.devices.map((deviceArg) => this.toDevice(deviceArg, updatedAt));
-  }
-
-  public static toEntities(snapshotArg: IWizSnapshot): IIntegrationEntity[] {
-    const entities: IIntegrationEntity[] = [];
-    const usedIds = new Map<string, number>();
-
-    for (const device of snapshotArg.devices) {
-      const info = this.deviceInfo(device);
-      const pilot = device.pilot || {};
-      const features = this.features(device);
-      const deviceId = this.deviceId(device);
-      const baseName = this.deviceName(device);
-      const isSocket = this.isSocket(device);
-      const hasLight = !isSocket && features.light !== false;
-
-      if (hasLight) {
-        entities.push(this.entity('light', baseName, deviceId, this.uniqueId('light', device), pilot.state ? 'on' : 'off', usedIds, {
-          ...this.baseAttributes(device),
-          brightness: pilot.dimming,
-          brightness255: this.percentToByte(pilot.dimming),
-          colorTemperatureKelvin: pilot.temp,
-          rgbColor: this.rgb(pilot),
-          sceneId: this.sceneId(pilot),
-          effect: this.sceneName(pilot),
-          effectList: this.sceneNames,
-          writable: true,
-        }, device.available !== false));
-      }
-
-      if (isSocket || features.switch) {
-        entities.push(this.entity('switch', baseName, deviceId, this.uniqueId('switch', device), pilot.state ? 'on' : 'off', usedIds, {
-          ...this.baseAttributes(device),
-          writable: true,
-        }, device.available !== false));
-      }
-
-      if (features.fan || pilot.fanState !== undefined) {
-        entities.push(this.entity('fan', `${baseName} Fan`, deviceId, this.uniqueId('fan', device), pilot.fanState ? 'on' : 'off', usedIds, {
-          ...this.baseAttributes(device),
-          percentage: this.fanPercentage(device, pilot),
-          fanMode: pilot.fanMode,
-          fanSpeed: pilot.fanSpeed,
-          fanReverse: pilot.fanRevrs,
-          writable: true,
-        }, device.available !== false));
-      }
-
-      if (typeof pilot.rssi === 'number') {
-        entities.push(this.sensorEntity(device, { key: 'rssi', name: `${baseName} RSSI`, value: pilot.rssi, unit: 'dBm', deviceClass: 'signal_strength' }, usedIds));
-      }
-      if (typeof pilot.pc === 'number' || features.power) {
-        entities.push(this.sensorEntity(device, { key: 'power', name: `${baseName} Power`, value: typeof pilot.pc === 'number' ? pilot.pc / 1000 : undefined, unit: 'W', deviceClass: 'power' }, usedIds));
-      }
-      if (features.occupancy || pilot.src === 'pir') {
-        entities.push(this.sensorEntity(device, { key: 'occupancy', name: `${baseName} Occupancy`, platform: 'binary_sensor', value: pilot.src === 'pir' ? pilot.state : undefined, deviceClass: 'occupancy' }, usedIds));
-      }
-
-      for (const sensor of device.sensors || []) {
-        entities.push(this.sensorEntity(device, sensor, usedIds));
-      }
-
-      if (features.effect || pilot.speed !== undefined) {
-        entities.push(this.numberEntity(device, 'effect_speed', `${baseName} Effect Speed`, pilot.speed, usedIds, { min: 10, max: 200, step: 1, wizPilotKey: 'speed' }));
-      }
-      if (features.dualHead || pilot.ratio !== undefined) {
-        entities.push(this.numberEntity(device, 'dual_head_ratio', `${baseName} Dual Head Ratio`, pilot.ratio, usedIds, { min: 0, max: 100, step: 1, wizPilotKey: 'ratio' }));
-      }
-      if (features.effect || this.sceneId(pilot) !== undefined) {
-        entities.push(this.entity('select', `${baseName} Effect`, deviceId, `${this.uniqueId('select', device)}_effect`, this.sceneName(pilot) || 'None', usedIds, {
-          ...this.baseAttributes(device),
-          options: this.sceneNames,
-          wizPilotKey: 'sceneId',
-          writable: true,
-        }, device.available !== false));
-      }
-
-      for (const button of this.buttons(device)) {
-        entities.push(this.buttonEntity(device, button, usedIds));
-      }
-
-      for (const entity of device.entities || []) {
-        entities.push(this.explicitEntity(device, entity, usedIds));
-      }
-    }
-
-    return entities;
-  }
-
-  public static toIntegrationEvent(eventArg: IWizEvent): IIntegrationEvent {
-    return {
-      type: eventArg.type === 'command_failed' || eventArg.type === 'error' ? 'error' : 'state_changed',
-      integrationDomain: 'wiz',
-      deviceId: eventArg.deviceId,
-      entityId: eventArg.entityId,
-      data: eventArg,
-      timestamp: eventArg.timestamp || Date.now(),
-    };
-  }
-
-  public static commandForService(snapshotArg: IWizSnapshot, requestArg: IServiceCallRequest): IWizClientCommand | undefined {
-    if (requestArg.domain === 'wiz' && requestArg.service === 'set_pilot' && this.isRecord(requestArg.data?.payload)) {
-      const targetEntity = this.findTargetEntity(snapshotArg, requestArg);
-      return {
-        type: 'setPilot',
-        service: requestArg.service,
-        deviceId: targetEntity?.deviceId || requestArg.target.deviceId,
-        entityId: targetEntity?.id || requestArg.target.entityId,
-        payload: requestArg.data.payload as IWizPilotPatch,
-        target: requestArg.target,
-      };
-    }
-
-    const target = this.findTargetEntity(snapshotArg, requestArg);
-    if (!target) {
-      return undefined;
-    }
-    const device = snapshotArg.devices.find((deviceArg) => this.deviceId(deviceArg) === target.deviceId);
-    const payload = this.payloadForService(target, requestArg, device);
-    if (!payload || !Object.keys(payload).length) {
-      return undefined;
-    }
-    return {
-      type: 'setPilot',
-      service: requestArg.service,
-      deviceId: target.deviceId,
-      entityId: target.id,
-      payload,
-      target: requestArg.target,
-    };
-  }
-
-  public static sceneIdFromName(valueArg: string): number | undefined {
-    return wizSceneIdsByName.get(valueArg.toLowerCase());
-  }
-
-  private static toDevice(deviceArg: IWizSnapshotDevice, updatedAtArg: string): plugins.shxInterfaces.data.IDeviceDefinition {
-    const info = this.deviceInfo(deviceArg);
-    const pilot = deviceArg.pilot || {};
-    const featuresInfo = this.features(deviceArg);
-    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
-      { id: 'availability', capability: 'sensor', name: 'Availability', readable: true, writable: false },
-    ];
-    const state: plugins.shxInterfaces.data.IDeviceState[] = [
-      { featureId: 'availability', value: deviceArg.available === false ? 'offline' : 'online', updatedAt: updatedAtArg },
-    ];
-    const isSocket = this.isSocket(deviceArg);
-    const hasLight = !isSocket && featuresInfo.light !== false;
-
-    if (hasLight) {
-      features.push({ id: 'on', capability: 'light', name: 'Power', readable: true, writable: true });
-      this.pushDeviceState(state, 'on', pilot.state ?? false, updatedAtArg);
-      if (featuresInfo.brightness !== false || typeof pilot.dimming === 'number') {
-        features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' });
-        this.pushDeviceState(state, 'brightness', pilot.dimming, updatedAtArg);
-      }
-      if (featuresInfo.colorTemp || typeof pilot.temp === 'number') {
-        features.push({ id: 'color_temperature', capability: 'light', name: 'Color Temperature', readable: true, writable: true, unit: 'K' });
-        this.pushDeviceState(state, 'color_temperature', pilot.temp, updatedAtArg);
-      }
-      if (featuresInfo.color || this.rgb(pilot)) {
-        features.push({ id: 'rgb', capability: 'light', name: 'RGB Color', readable: true, writable: true });
-        this.pushDeviceState(state, 'rgb', this.rgbRecord(pilot), updatedAtArg);
-      }
-      if (featuresInfo.effect || this.sceneId(pilot) !== undefined) {
-        features.push({ id: 'effect', capability: 'light', name: 'Effect', readable: true, writable: true });
-        this.pushDeviceState(state, 'effect', this.sceneName(pilot) || null, updatedAtArg);
-      }
-    }
-
-    if (isSocket || featuresInfo.switch) {
-      features.push({ id: 'switch', capability: 'switch', name: 'Power', readable: true, writable: true });
-      this.pushDeviceState(state, 'switch', pilot.state ?? false, updatedAtArg);
-    }
-
-    if (featuresInfo.fan || pilot.fanState !== undefined) {
-      features.push({ id: 'fan', capability: 'fan', name: 'Fan', readable: true, writable: true });
-      this.pushDeviceState(state, 'fan', Boolean(pilot.fanState), updatedAtArg);
-      features.push({ id: 'fan_speed', capability: 'fan', name: 'Fan Speed', readable: true, writable: true, unit: '%' });
-      this.pushDeviceState(state, 'fan_speed', this.fanPercentage(deviceArg, pilot), updatedAtArg);
-    }
-
-    if (typeof pilot.rssi === 'number') {
-      features.push({ id: 'rssi', capability: 'sensor', name: 'RSSI', readable: true, writable: false, unit: 'dBm' });
-      this.pushDeviceState(state, 'rssi', pilot.rssi, updatedAtArg);
-    }
-    if (typeof pilot.pc === 'number' || featuresInfo.power) {
-      features.push({ id: 'power', capability: 'energy', name: 'Power', readable: true, writable: false, unit: 'W' });
-      this.pushDeviceState(state, 'power', typeof pilot.pc === 'number' ? pilot.pc / 1000 : undefined, updatedAtArg);
-    }
-    if (featuresInfo.occupancy || pilot.src === 'pir') {
-      features.push({ id: 'occupancy', capability: 'sensor', name: 'Occupancy', readable: true, writable: false });
-      this.pushDeviceState(state, 'occupancy', pilot.src === 'pir' ? Boolean(pilot.state) : undefined, updatedAtArg);
-    }
-
-    for (const sensor of deviceArg.sensors || []) {
-      features.push({ id: sensor.key, capability: 'sensor', name: sensor.name || this.title(sensor.key), readable: true, writable: Boolean(sensor.writable), unit: sensor.unit });
-      this.pushDeviceState(state, sensor.key, this.deviceStateValue(sensor.value), updatedAtArg);
-    }
-    for (const button of this.buttons(deviceArg)) {
-      features.push({ id: `button_${button.key}`, capability: 'switch', name: button.name || this.title(button.key), readable: true, writable: true });
-      this.pushDeviceState(state, `button_${button.key}`, String(button.value ?? button.lastPressedAt ?? 'idle'), updatedAtArg);
-    }
-
-    return {
-      id: this.deviceId(deviceArg),
-      integrationDomain: 'wiz',
-      name: this.deviceName(deviceArg),
-      protocol: 'unknown',
-      manufacturer: info.manufacturer || 'WiZ',
-      model: info.model || info.moduleName || String(info.bulbType || 'WiZ device'),
-      online: deviceArg.available !== false,
-      features,
-      state,
-      metadata: {
-        ...deviceArg.metadata,
-        protocol: 'wiz-udp-json',
-        host: deviceArg.host || info.host,
-        port: deviceArg.port || info.port || wizDefaultPort,
-        mac: this.mac(deviceArg),
-        moduleName: info.moduleName,
-        fwVersion: info.fwVersion,
-        typeId: info.typeId,
-        features: featuresInfo,
-      },
-    };
-  }
-
-  private static payloadForService(entityArg: IIntegrationEntity, requestArg: IServiceCallRequest, deviceArg?: IWizSnapshotDevice): IWizPilotPatch | undefined {
-    if (requestArg.service === 'turn_off') {
-      return entityArg.platform === 'fan' || requestArg.domain === 'fan' ? { fanState: 0 } : { state: false };
-    }
-    if (requestArg.service === 'turn_on') {
-      const payload: IWizPilotPatch = entityArg.platform === 'fan' || requestArg.domain === 'fan' ? { fanState: 1 } : { state: true };
-      this.applyServiceData(payload, requestArg, entityArg, deviceArg);
-      return payload;
-    }
-    if (requestArg.service === 'set_percentage' || requestArg.service === 'set_brightness') {
-      const percentage = this.percentageFromData(requestArg.data, requestArg.service);
-      if (percentage === undefined) {
-        return undefined;
-      }
-      if (entityArg.platform === 'fan' || requestArg.domain === 'fan') {
-        return percentage <= 0 ? { fanState: 0 } : { fanState: 1, fanSpeed: this.percentageToFanSpeed(deviceArg, percentage) };
-      }
-      return percentage <= 0 ? { state: false } : { state: true, dimming: this.clamp(Math.round(percentage), 10, 100) };
-    }
-    if (requestArg.service === 'set_value') {
-      return this.setValuePayload(entityArg, requestArg);
-    }
-    if (requestArg.service === 'select_option' || requestArg.service === 'select_effect') {
-      const option = this.stringFromData(requestArg.data, ['option', 'effect', 'value']);
-      const sceneId = typeof option === 'string' ? this.sceneIdFromName(option) : undefined;
-      return sceneId === undefined ? undefined : { state: true, sceneId };
-    }
-    if (requestArg.domain === 'fan') {
-      if (requestArg.service === 'set_direction') {
-        const direction = this.stringFromData(requestArg.data, ['direction']);
-        return direction ? { fanRevrs: direction === 'reverse' ? 1 : 0 } : undefined;
-      }
-      if (requestArg.service === 'set_preset_mode') {
-        const presetMode = this.stringFromData(requestArg.data, ['preset_mode', 'presetMode']);
-        return presetMode === 'breeze' ? { fanMode: 2 } : undefined;
-      }
-    }
-    return undefined;
-  }
-
-  private static applyServiceData(payloadArg: IWizPilotPatch, requestArg: IServiceCallRequest, entityArg: IIntegrationEntity, deviceArg?: IWizSnapshotDevice): void {
-    const brightness = this.percentageFromData(requestArg.data, 'turn_on');
-    if (brightness !== undefined && entityArg.platform !== 'fan' && requestArg.domain !== 'fan') {
-      payloadArg.dimming = this.clamp(Math.round(brightness), 10, 100);
-    }
-    if (brightness !== undefined && (entityArg.platform === 'fan' || requestArg.domain === 'fan')) {
-      payloadArg.fanSpeed = this.percentageToFanSpeed(deviceArg, brightness);
-    }
-    const kelvin = this.kelvinFromData(requestArg.data);
-    if (kelvin !== undefined) {
-      payloadArg.temp = kelvin;
-    }
-    const rgb = this.rgbFromData(requestArg.data, 'rgb_color') || this.rgbFromData(requestArg.data, 'rgb');
-    if (rgb) {
-      payloadArg.r = rgb[0];
-      payloadArg.g = rgb[1];
-      payloadArg.b = rgb[2];
-    }
-    const rgbw = this.rgbFromData(requestArg.data, 'rgbw_color');
-    if (rgbw) {
-      payloadArg.r = rgbw[0];
-      payloadArg.g = rgbw[1];
-      payloadArg.b = rgbw[2];
-      payloadArg.w = rgbw[3];
-    }
-    const rgbww = this.rgbFromData(requestArg.data, 'rgbww_color');
-    if (rgbww) {
-      payloadArg.r = rgbww[0];
-      payloadArg.g = rgbww[1];
-      payloadArg.b = rgbww[2];
-      payloadArg.c = rgbww[3];
-      payloadArg.w = rgbww[4];
-    }
-    const effect = this.stringFromData(requestArg.data, ['effect', 'option']);
-    const sceneId = effect ? this.sceneIdFromName(effect) : this.numberFromData(requestArg.data, ['sceneId', 'scene_id']);
-    if (sceneId !== undefined) {
-      payloadArg.sceneId = sceneId;
-    }
-    const speed = this.numberFromData(requestArg.data, ['speed']);
-    if (speed !== undefined) {
-      payloadArg.speed = this.clamp(Math.round(speed), 10, 200);
-    }
-  }
-
-  private static setValuePayload(entityArg: IIntegrationEntity, requestArg: IServiceCallRequest): IWizPilotPatch | undefined {
-    const value = this.valueFromData(requestArg.data, ['value', 'state']);
-    const field = this.stringFromData(requestArg.data, ['field', 'attribute', 'key']) || (typeof entityArg.attributes?.wizPilotKey === 'string' ? entityArg.attributes.wizPilotKey : undefined);
-    if (value === undefined || !field || !pilotPatchKeys.has(field)) {
-      return undefined;
-    }
-    if (field === 'speed') {
-      return typeof value === 'number' ? { speed: this.clamp(Math.round(value), 10, 200) } : undefined;
-    }
-    if (field === 'ratio') {
-      return typeof value === 'number' ? { ratio: this.clamp(Math.round(value), 0, 100) } : undefined;
-    }
-    if (field === 'sceneId' && typeof value === 'string') {
-      const sceneId = this.sceneIdFromName(value);
-      return sceneId === undefined ? undefined : { state: true, sceneId };
-    }
-    return { [field]: value } as IWizPilotPatch;
-  }
-
-  private static findTargetEntity(snapshotArg: IWizSnapshot, requestArg: IServiceCallRequest): IIntegrationEntity | undefined {
-    const entities = this.toEntities(snapshotArg);
-    if (requestArg.target.entityId) {
-      return entities.find((entityArg) => entityArg.id === requestArg.target.entityId || entityArg.uniqueId === requestArg.target.entityId);
-    }
-    if (requestArg.target.deviceId) {
-      return entities.find((entityArg) => entityArg.deviceId === requestArg.target.deviceId && entityArg.platform === requestArg.domain)
-        || entities.find((entityArg) => entityArg.deviceId === requestArg.target.deviceId && Boolean(entityArg.attributes?.writable))
-        || entities.find((entityArg) => entityArg.deviceId === requestArg.target.deviceId);
-    }
-    return entities.find((entityArg) => entityArg.platform === requestArg.domain && Boolean(entityArg.attributes?.writable));
-  }
-
-  private static deviceFromManualEntry(entryArg: IWizManualEntry): IWizSnapshotDevice {
-    return {
-      id: entryArg.id,
-      host: entryArg.host,
-      port: entryArg.port || wizDefaultPort,
-      mac: entryArg.mac || entryArg.macAddress || entryArg.deviceInfo?.mac,
-      name: entryArg.name || entryArg.deviceInfo?.name,
-      deviceInfo: {
-        ...entryArg.deviceInfo,
-        host: entryArg.host,
-        port: entryArg.port || wizDefaultPort,
-        mac: entryArg.mac || entryArg.macAddress || entryArg.deviceInfo?.mac,
-        name: entryArg.name || entryArg.deviceInfo?.name,
-        manufacturer: entryArg.manufacturer || entryArg.deviceInfo?.manufacturer,
-        model: entryArg.model || entryArg.deviceInfo?.model,
-      },
-      pilot: entryArg.pilot,
-      available: Boolean(entryArg.pilot),
-      metadata: entryArg.metadata,
+    const pilot = snapshotArg.info.observedState;
+    const capabilities = snapshotArg.info.capabilities;
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [];
+    const state: plugins.shxInterfaces.data.IDeviceState[] = [];
+    const add = (idArg: string, nameArg: string, capabilityArg: plugins.shxInterfaces.data.TDeviceCapability,
+      valueArg: plugins.shxInterfaces.data.TDeviceStateValue | undefined, writableArg: boolean, unitArg?: string): void => {
+      if (valueArg === undefined) return;
+      features.push({ id: idArg, name: nameArg, capability: capabilityArg, readable: true, writable: writableArg, unit: unitArg });
+      state.push({ featureId: idArg, value: valueArg, updatedAt: snapshotArg.observedAt });
     };
+    add('power', 'Power', 'switch', pilot.power, capabilities.power);
+    add('brightness', 'Brightness', 'light', pilot.brightness, capabilities.brightness, '%');
+    add('rgb', 'RGB', 'light', pilot.rgb ? `${pilot.rgb.red},${pilot.rgb.green},${pilot.rgb.blue}` : undefined, capabilities.rgb);
+    add('color_temperature', 'Observed colour temperature', 'sensor', pilot.colorTemperature, false, 'K');
+    add('scene_id', 'Observed scene ID', 'sensor', pilot.sceneId, false);
+    return [{ id: this.deviceId(snapshotArg), integrationDomain: 'wiz', protocol: 'udp', manufacturer: 'WiZ',
+      name: snapshotArg.name ?? snapshotArg.info.moduleName ?? 'WiZ', model: snapshotArg.info.moduleName,
+      features, state, online: true, metadata: {
+        homeId: snapshotArg.homeId, macAddress: snapshotArg.info.macAddress, host: snapshotArg.host, port: snapshotArg.port,
+        firmwareVersion: snapshotArg.info.firmwareVersion, deviceClass: snapshotArg.info.deviceClass,
+        observedAt: snapshotArg.observedAt, networkAuthenticated: false, physicalStateConfirmed: false,
+      } }];
   }
 
-  private static explicitEntity(deviceArg: IWizSnapshotDevice, entityArg: IWizEntityRecord, usedIdsArg: Map<string, number>): IIntegrationEntity {
-    const platform = this.corePlatform(entityArg.platform);
-    const name = entityArg.name || this.deviceName(deviceArg);
-    return this.entity(platform, name, this.deviceId(deviceArg), entityArg.uniqueId || `${this.uniqueId(platform, deviceArg)}_${entityArg.key || this.slug(name)}`, this.entityState(entityArg.state, platform), usedIdsArg, {
-      ...this.baseAttributes(deviceArg),
-      ...entityArg.attributes,
-      wizPilotKey: entityArg.key,
-      writable: entityArg.writable,
-    }, entityArg.available !== false && deviceArg.available !== false, entityArg.entityId);
-  }
-
-  private static sensorEntity(deviceArg: IWizSnapshotDevice, sensorArg: IWizSensorRecord, usedIdsArg: Map<string, number>): IIntegrationEntity {
-    const platform = sensorArg.platform || 'sensor';
-    const state = platform === 'binary_sensor' ? sensorArg.value ? 'on' : 'off' : sensorArg.value ?? 'unknown';
-    return this.entity(platform, sensorArg.name || `${this.deviceName(deviceArg)} ${this.title(sensorArg.key)}`, this.deviceId(deviceArg), `${this.uniqueId(platform, deviceArg)}_${this.slug(sensorArg.key)}`, state, usedIdsArg, {
-      ...this.baseAttributes(deviceArg),
-      wizSensorKey: sensorArg.key,
-      wizPilotKey: sensorArg.writable ? sensorArg.key : undefined,
-      deviceClass: sensorArg.deviceClass,
-      unit: sensorArg.unit,
-      writable: sensorArg.writable,
-    }, sensorArg.available !== false && deviceArg.available !== false);
-  }
-
-  private static numberEntity(deviceArg: IWizSnapshotDevice, keyArg: string, nameArg: string, valueArg: unknown, usedIdsArg: Map<string, number>, attributesArg: Record<string, unknown>): IIntegrationEntity {
-    return this.entity('number', nameArg, this.deviceId(deviceArg), `${this.uniqueId('number', deviceArg)}_${this.slug(keyArg)}`, valueArg ?? 'unknown', usedIdsArg, {
-      ...this.baseAttributes(deviceArg),
-      ...attributesArg,
-      writable: true,
-    }, deviceArg.available !== false);
-  }
-
-  private static buttonEntity(deviceArg: IWizSnapshotDevice, buttonArg: IWizButtonRecord, usedIdsArg: Map<string, number>): IIntegrationEntity {
-    const name = buttonArg.name || `${this.deviceName(deviceArg)} ${this.title(buttonArg.key)}`;
-    return this.entity('button', name, this.deviceId(deviceArg), `${this.uniqueId('button', deviceArg)}_${this.slug(buttonArg.key)}`, buttonArg.value ?? 'idle', usedIdsArg, {
-      ...this.baseAttributes(deviceArg),
-      wizButtonKey: buttonArg.key,
-      lastPressedAt: buttonArg.lastPressedAt,
-      writable: true,
-    }, buttonArg.available !== false && deviceArg.available !== false);
-  }
-
-  private static entity(platformArg: TEntityPlatform, nameArg: string, deviceIdArg: string, uniqueIdArg: string, stateArg: unknown, usedIdsArg: Map<string, number>, attributesArg: Record<string, unknown>, availableArg: boolean, explicitEntityIdArg?: string): IIntegrationEntity {
-    return {
-      id: explicitEntityIdArg || this.entityId(platformArg, nameArg, usedIdsArg),
-      uniqueId: uniqueIdArg,
-      integrationDomain: 'wiz',
-      deviceId: deviceIdArg,
-      platform: platformArg,
-      name: nameArg,
-      state: stateArg,
-      attributes: attributesArg,
-      available: availableArg,
-    };
-  }
-
-  private static buttons(deviceArg: IWizSnapshotDevice): IWizButtonRecord[] {
-    const buttons = [...(deviceArg.buttons || [])];
-    const source = typeof deviceArg.pilot?.src === 'string' ? deviceArg.pilot.src : undefined;
-    if (source && wizButtonSources[source]) {
-      buttons.push({ key: wizButtonSources[source], name: `${this.deviceName(deviceArg)} Button ${this.title(wizButtonSources[source])}`, value: source });
-    }
-    return buttons;
-  }
-
-  private static deviceInfo(deviceArg: IWizSnapshotDevice): IWizDeviceInfo {
-    return {
-      ...deviceArg.deviceInfo,
-      id: deviceArg.deviceInfo?.id || deviceArg.id,
-      host: deviceArg.host || deviceArg.deviceInfo?.host,
-      port: deviceArg.port || deviceArg.deviceInfo?.port || wizDefaultPort,
-      mac: deviceArg.mac || deviceArg.deviceInfo?.mac || deviceArg.pilot?.mac,
-      name: deviceArg.name || deviceArg.deviceInfo?.name,
-    };
-  }
-
-  private static features(deviceArg: IWizSnapshotDevice): IWizDeviceFeatures {
-    const info = this.deviceInfo(deviceArg);
-    const pilot = deviceArg.pilot || {};
-    const lowerType = String(info.bulbType || info.model || info.moduleName || '').toLowerCase();
-    const isSocket = this.isSocket(deviceArg);
-    return {
-      light: !isSocket,
-      switch: isSocket,
-      brightness: typeof pilot.dimming === 'number' || !isSocket,
-      color: ['r', 'g', 'b'].every((keyArg) => typeof pilot[keyArg] === 'number') || lowerType.includes('rgb'),
-      colorTemp: typeof pilot.temp === 'number' || lowerType.includes('tw') || lowerType.includes('tunable'),
-      effect: typeof pilot.sceneId === 'number' || typeof pilot.schdPsetId === 'number' || info.features?.effect,
-      fan: typeof pilot.fanState === 'number' || info.features?.fan,
-      power: typeof pilot.pc === 'number' || info.powerMonitoring || info.features?.power,
-      occupancy: pilot.src === 'pir' || info.features?.occupancy,
-      button: Boolean(deviceArg.buttons?.length) || Boolean(pilot.src && wizButtonSources[String(pilot.src)]) || info.features?.button,
-      dualHead: typeof pilot.ratio === 'number' || info.features?.dualHead,
-      ...info.features,
-    };
-  }
-
-  private static isSocket(deviceArg: IWizSnapshotDevice): boolean {
-    const info = this.deviceInfo(deviceArg);
-    const text = [info.bulbType, info.model, info.moduleName, info.typeId].filter((valueArg) => valueArg !== undefined).join(' ').toLowerCase();
-    return info.isSocket === true || info.features?.switch === true || text.includes('socket') || text.includes('plug');
-  }
-
-  private static deviceId(deviceArg: IWizSnapshotDevice): string {
-    return `wiz.device.${this.slug(deviceArg.id || this.mac(deviceArg) || deviceArg.host || this.deviceName(deviceArg))}`;
-  }
-
-  private static uniqueId(platformArg: string, deviceArg: IWizSnapshotDevice): string {
-    return `wiz_${platformArg}_${this.slug(this.mac(deviceArg) || deviceArg.id || deviceArg.host || this.deviceName(deviceArg))}`;
-  }
-
-  private static deviceName(deviceArg: IWizSnapshotDevice): string {
-    const info = this.deviceInfo(deviceArg);
-    return info.name || deviceArg.name || (this.mac(deviceArg) ? `WiZ ${this.shortMac(this.mac(deviceArg))}` : 'WiZ device');
-  }
-
-  private static mac(deviceArg: IWizSnapshotDevice): string | undefined {
-    return this.normalizeMac(deviceArg.mac || deviceArg.deviceInfo?.mac || deviceArg.pilot?.mac);
-  }
-
-  private static baseAttributes(deviceArg: IWizSnapshotDevice): Record<string, unknown> {
-    const info = this.deviceInfo(deviceArg);
-    return {
-      wizDeviceId: this.deviceId(deviceArg),
-      wizHost: info.host,
-      wizPort: info.port || wizDefaultPort,
-      wizMac: this.mac(deviceArg),
-      moduleName: info.moduleName,
-      fwVersion: info.fwVersion,
-      model: info.model,
-    };
-  }
-
-  private static sceneId(pilotArg: IWizPilotState): number | undefined {
-    if (typeof pilotArg.schdPsetId === 'number') {
-      return 1000;
-    }
-    return typeof pilotArg.sceneId === 'number' && pilotArg.sceneId > 0 ? pilotArg.sceneId : undefined;
-  }
-
-  private static sceneName(pilotArg: IWizPilotState): string | undefined {
-    const sceneId = this.sceneId(pilotArg);
-    return sceneId === undefined ? undefined : wizSceneNamesById.get(sceneId) || `Scene ${sceneId}`;
-  }
-
-  private static fanPercentage(deviceArg: IWizSnapshotDevice, pilotArg: IWizPilotState): number | undefined {
-    if (typeof pilotArg.fanSpeed !== 'number') {
-      return undefined;
-    }
-    const max = this.deviceInfo(deviceArg).fanSpeedRange || 6;
-    return this.clamp(Math.round(pilotArg.fanSpeed / max * 100), 0, 100);
-  }
-
-  private static percentageToFanSpeed(deviceArg: IWizSnapshotDevice | undefined, percentageArg: number): number {
-    const max = deviceArg ? this.deviceInfo(deviceArg).fanSpeedRange || 6 : 6;
-    return this.clamp(Math.ceil(this.clamp(percentageArg, 0, 100) / 100 * max), 1, max);
-  }
-
-  private static percentToByte(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' ? this.clamp(Math.round(valueArg / 100 * 255), 0, 255) : undefined;
-  }
-
-  private static percentageFromData(dataArg: Record<string, unknown> | undefined, serviceArg: string): number | undefined {
-    const pct = this.numberFromData(dataArg, ['percentage', 'brightness_pct']);
-    if (pct !== undefined) {
-      return this.clamp(pct, 0, 100);
-    }
-    const brightness = this.numberFromData(dataArg, serviceArg === 'set_brightness' ? ['brightness', 'value'] : ['brightness']);
-    return brightness === undefined ? undefined : this.clamp(Math.round(brightness / 255 * 100), 0, 100);
-  }
-
-  private static kelvinFromData(dataArg: Record<string, unknown> | undefined): number | undefined {
-    const direct = this.numberFromData(dataArg, ['color_temp_kelvin', 'kelvin', 'temp', 'color_temperature']);
-    if (direct !== undefined) {
-      return Math.round(direct);
-    }
-    const mired = this.numberFromData(dataArg, ['color_temp', 'color_temp_mired']);
-    return mired && mired > 0 ? Math.round(1000000 / mired) : undefined;
-  }
-
-  private static rgb(pilotArg: IWizPilotState): number[] | undefined {
-    return typeof pilotArg.r === 'number' && typeof pilotArg.g === 'number' && typeof pilotArg.b === 'number'
-      ? [pilotArg.r, pilotArg.g, pilotArg.b]
-      : undefined;
-  }
-
-  private static rgbRecord(pilotArg: IWizPilotState): Record<string, unknown> | undefined {
-    const rgb = this.rgb(pilotArg);
-    return rgb ? { r: rgb[0], g: rgb[1], b: rgb[2], c: pilotArg.c, w: pilotArg.w } : undefined;
-  }
-
-  private static rgbFromData(dataArg: Record<string, unknown> | undefined, keyArg: string): number[] | undefined {
-    const value = dataArg?.[keyArg];
-    if (!Array.isArray(value) || value.length < 3) {
-      return undefined;
-    }
-    const numbers = value.map((valueArg) => typeof valueArg === 'number' && Number.isFinite(valueArg) ? this.clamp(Math.round(valueArg), 0, 255) : undefined);
-    return numbers.every((valueArg) => valueArg !== undefined) ? numbers as number[] : undefined;
-  }
-
-  private static valueFromData(dataArg: Record<string, unknown> | undefined, keysArg: string[]): unknown {
-    for (const key of keysArg) {
-      if (dataArg && key in dataArg) {
-        return dataArg[key];
-      }
-    }
-    return undefined;
-  }
-
-  private static numberFromData(dataArg: Record<string, unknown> | undefined, keysArg: string[]): number | undefined {
-    const value = this.valueFromData(dataArg, keysArg);
-    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
-  }
-
-  private static stringFromData(dataArg: Record<string, unknown> | undefined, keysArg: string[]): string | undefined {
-    const value = this.valueFromData(dataArg, keysArg);
-    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
-  }
-
-  private static corePlatform(platformArg: TEntityPlatform | string): TEntityPlatform {
-    const platform = platformArg.toLowerCase();
-    const allowed: TEntityPlatform[] = ['light', 'switch', 'sensor', 'binary_sensor', 'button', 'climate', 'cover', 'fan', 'media_player', 'number', 'select', 'text', 'update'];
-    return allowed.includes(platform as TEntityPlatform) ? platform as TEntityPlatform : 'sensor';
-  }
-
-  private static entityState(valueArg: unknown, platformArg: TEntityPlatform): unknown {
-    if (platformArg === 'light' || platformArg === 'switch' || platformArg === 'fan' || platformArg === 'binary_sensor') {
-      return typeof valueArg === 'boolean' ? valueArg ? 'on' : 'off' : valueArg ?? 'unknown';
-    }
-    return valueArg ?? 'unknown';
-  }
-
-  private static pushDeviceState(stateArg: plugins.shxInterfaces.data.IDeviceState[], featureIdArg: string, valueArg: unknown, updatedAtArg: string): void {
-    if (valueArg === undefined) {
-      return;
-    }
-    stateArg.push({ featureId: featureIdArg, value: this.deviceStateValue(valueArg), updatedAt: updatedAtArg });
-  }
-
-  private static deviceStateValue(valueArg: unknown): plugins.shxInterfaces.data.TDeviceStateValue {
-    if (typeof valueArg === 'string' || typeof valueArg === 'number' || typeof valueArg === 'boolean' || valueArg === null || this.isRecord(valueArg)) {
-      return valueArg;
-    }
-    return valueArg === undefined ? null : String(valueArg);
-  }
-
-  private static entityId(platformArg: TEntityPlatform, nameArg: string, usedIdsArg: Map<string, number>): string {
-    const base = `${platformArg}.${this.slug(nameArg)}`;
-    const count = usedIdsArg.get(base) || 0;
-    usedIdsArg.set(base, count + 1);
-    return count ? `${base}_${count + 1}` : base;
-  }
-
-  private static shortMac(valueArg?: string): string {
-    return (valueArg || '').replace(/[^a-fA-F0-9]/g, '').slice(-6).toUpperCase();
-  }
-
-  private static normalizeMac(valueArg?: string): string | undefined {
-    if (!valueArg) {
-      return undefined;
-    }
-    const compact = valueArg.replace(/[^a-fA-F0-9]/g, '').toLowerCase();
-    return compact.length === 12 ? compact.match(/.{1,2}/g)?.join(':') : valueArg.toLowerCase();
-  }
-
-  private static title(valueArg: string): string {
-    return valueArg.replace(/_/g, ' ').replace(/\b\w/g, (matchArg) => matchArg.toUpperCase());
-  }
-
-  private static slug(valueArg: string): string {
-    return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'wiz';
-  }
-
-  private static clamp(valueArg: number, minArg: number, maxArg: number): number {
-    return Math.max(minArg, Math.min(maxArg, valueArg));
-  }
-
-  private static isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+  public static toEntities(snapshotArg: IWizSnapshot): IIntegrationEntity[] {
+    const pilot = snapshotArg.info.observedState;
+    return [{ id: this.entityId(snapshotArg), uniqueId: this.entityId(snapshotArg), deviceId: this.deviceId(snapshotArg), integrationDomain: 'wiz',
+      platform: snapshotArg.info.deviceClass === 'socket' ? 'switch' : snapshotArg.info.deviceClass === 'unknown' ? 'sensor' : 'light',
+      name: snapshotArg.name ?? snapshotArg.info.moduleName ?? 'WiZ', state: pilot.power === undefined ? null : pilot.power ? 'on' : 'off', available: true,
+      attributes: { homeId: snapshotArg.homeId, writable: Object.values(snapshotArg.info.capabilities).some(Boolean),
+        capabilities: snapshotArg.info.capabilities, brightness: pilot.brightness, rgb: pilot.rgb,
+        colorTemperature: pilot.colorTemperature, sceneId: pilot.sceneId, observedAt: snapshotArg.observedAt,
+        networkAuthenticated: false, physicalStateConfirmed: false },
+    }];
+  }
+
+  public static controlForService(snapshotArg: IWizSnapshot, requestArg: IServiceCallRequest): TWizControl {
+    const request = wizRecord(requestArg, ['domain', 'service', 'target', 'data']);
+    const target = wizRecord(request.target, ['deviceId', 'entityId']);
+    if (target.deviceId === undefined && target.entityId === undefined ||
+      target.deviceId !== undefined && target.deviceId !== this.deviceId(snapshotArg) ||
+      target.entityId !== undefined && target.entityId !== this.entityId(snapshotArg)) throw new TypeError('WiZ requires an exact owned home/device/entity target.');
+    const domain = snapshotArg.info.deviceClass === 'socket' ? 'switch' : 'light';
+    if (request.domain !== domain) throw new TypeError('WiZ service domain must match the observed device class.');
+    if (request.service === 'turn_on' || request.service === 'turn_off') {
+      if (request.data !== undefined) wizRecord(request.data, []);
+      return this.requireCapability(snapshotArg, wizControl({ feature: 'power', value: request.service === 'turn_on' }));
+    }
+    if (request.service === 'set_brightness') {
+      const data = wizRecord(request.data, ['brightness']);
+      return this.requireCapability(snapshotArg, wizControl({ feature: 'brightness', value: data.brightness }));
+    }
+    if (request.service === 'set_rgb') {
+      const data = wizRecord(request.data, ['rgb']);
+      return this.requireCapability(snapshotArg, wizControl({ feature: 'rgb', value: data.rgb }));
+    }
+    throw new TypeError('WiZ supports only explicit power, brightness and RGB services.');
+  }
+
+  public static controlForFeature(snapshotArg: IWizSnapshot, requestArg: IDeviceFeatureWriteRequest): TWizControl {
+    const request = wizRecord(requestArg, ['device', 'feature', 'value']);
+    const device = wizRecord(request.device);
+    const feature = wizRecord(request.feature);
+    const metadata = wizRecord(device.metadata);
+    if (device.id !== this.deviceId(snapshotArg) || device.integrationDomain !== 'wiz' || metadata.homeId !== snapshotArg.homeId) {
+      throw new TypeError('WiZ feature write must target the exact configured home and device.');
+    }
+    let value = request.value;
+    if (feature.id === 'rgb') {
+      if (typeof value !== 'string' || !/^(0|[1-9]\d{0,2}),(0|[1-9]\d{0,2}),(0|[1-9]\d{0,2})$/.test(value)) throw new TypeError('WiZ RGB features require three exact decimal bytes.');
+      const channels = value.split(',').map(Number);
+      value = { red: channels[0], green: channels[1], blue: channels[2] };
+    }
+    return this.requireCapability(snapshotArg, wizControl({ feature: feature.id, value }));
+  }
+
+  private static requireCapability(snapshotArg: IWizSnapshot, controlArg: TWizControl): TWizControl {
+    if (!snapshotArg.info.capabilities[controlArg.feature]) throw new TypeError('WiZ control is unsupported by the observed device.');
+    return controlArg;
   }
 }