@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/tasmota/tasmota.classes.runtime.ts

@@ -0,0 +1,274 @@
+import * as plugins from '../../plugins.js';
+import { DeviceCommunicationError } from '../../core/errors.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IServiceCallResult } from '../../core/types.js';
+import { MqttClient } from '../mqtt/mqtt.classes.client.js';
+import type { IMqttMessage } from '../mqtt/mqtt.types.js';
+import { parseTasmotaRecord, tasmotaRecord, TasmotaMapper } from './tasmota.mapper.js';
+import { normalizeTasmotaConfig } from './tasmota.config.js';
+import type { IHomeAssistantTasmotaConfig, ITasmotaConfig, ITasmotaDeviceState, ITasmotaSelectedDevice } from './tasmota.types.js';
+
+export class TasmotaRuntime implements IIntegrationRuntime {
+  public readonly domain = 'tasmota';
+  private readonly config: ITasmotaConfig;
+  private readonly client: MqttClient;
+  private readonly lifetime = new AbortController();
+  private readonly states = new Map<string, ITasmotaDeviceState>();
+  private readonly listeners = new Set<(eventArg: IIntegrationEvent) => void>();
+  private readonly changed = new Set<() => void>();
+  private readonly subscriptionCleanups = new Set<() => void>();
+  private readonly stopConnectionListener: () => void;
+  private initializing = true;
+  private started = false;
+  private destroyed = false;
+  private destroyPromise?: Promise<void>;
+
+  constructor(configArg: IHomeAssistantTasmotaConfig) {
+    this.config = normalizeTasmotaConfig(configArg);
+    this.client = new MqttClient(this.config.broker);
+    for (const device of this.config.devices) this.states.set(device.id, { generation: 0, ready: false, online: false, queryPending: false, updatedAt: new Date(0).toISOString(), controls: {}, sensors: {} });
+    this.stopConnectionListener = this.client.onConnectionState((stateArg) => {
+      if (this.destroyed) return;
+      if (!stateArg.connected) {
+        for (const device of this.config.devices) this.markOffline(device);
+      } else if (!this.initializing) {
+        this.refreshInBackground(this.config.devices);
+      }
+      if (stateArg.error) this.emit({ type: 'error', data: { message: stateArg.error.message } });
+    });
+  }
+
+  public async start(abortSignalArg?: AbortSignal): Promise<void> {
+    this.checkActive(abortSignalArg);
+    if (this.started) throw new DeviceCommunicationError('Tasmota runtime has already started.');
+    this.started = true;
+    try {
+      await this.withDeadline(async (signalArg) => {
+        await this.client.start(signalArg);
+        for (const device of this.config.devices) {
+          await this.client.subscribe(`${device.statusBase}#`, (messageArg) => this.receive(device, messageArg), signalArg);
+          await this.client.subscribe(`${device.telemetryBase}#`, (messageArg) => this.receive(device, messageArg), signalArg);
+        }
+        await this.refresh(this.config.devices, signalArg);
+      }, abortSignalArg);
+      this.initializing = false;
+    } catch (errorArg) {
+      await this.destroy();
+      throw errorArg;
+    }
+  }
+
+  public isHealthy(): boolean {
+    return !this.destroyed && this.client.isHealthy() && this.config.devices.every((deviceArg) => this.ready(deviceArg));
+  }
+
+  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.checkActive(abortSignalArg);
+    return this.config.devices.map((deviceArg) => TasmotaMapper.device(deviceArg, this.state(deviceArg), this.client.connected));
+  }
+
+  public async entities(): Promise<IIntegrationEntity[]> {
+    return (await this.devices()).flatMap((deviceArg) => TasmotaMapper.entities(deviceArg));
+  }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.checkActive(abortSignalArg);
+    const listener = (eventArg: IIntegrationEvent): void => handlerArg(eventArg);
+    this.listeners.add(listener);
+    const cleanup = (): void => {
+      this.listeners.delete(listener);
+      abortSignalArg?.removeEventListener('abort', cleanup);
+      this.subscriptionCleanups.delete(cleanup);
+    };
+    this.subscriptionCleanups.add(cleanup);
+    abortSignalArg?.addEventListener('abort', cleanup, { once: true });
+    return async () => cleanup();
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    this.checkActive(abortSignalArg);
+    if (requestArg.device.integrationDomain !== this.domain) return { success: false, error: 'Tasmota device is not selected.' };
+    const device = this.config.devices.find((deviceArg) => deviceArg.id === requestArg.device.id);
+    if (!device) return { success: false, error: 'Tasmota device is not selected.' };
+    if (!this.client.isHealthy() || !this.ready(device)) return { success: false, error: 'Tasmota device has no fresh online state.' };
+    const featureId = requestArg.feature.id;
+    let command: string;
+    let payload: string;
+    const relay = device.relays.find((relayArg) => featureId === `power_${relayArg}`);
+    if (relay !== undefined && typeof requestArg.value === 'boolean') {
+      command = `POWER${relay}`;
+      payload = requestArg.value ? 'ON' : 'OFF';
+    } else if (featureId === 'brightness' && device.brightness && typeof requestArg.value === 'number' && Number.isInteger(requestArg.value) && requestArg.value >= 0 && requestArg.value <= 100) {
+      command = 'Dimmer';
+      payload = String(requestArg.value);
+    } else {
+      return { success: false, error: 'Tasmota write requires a selected relay boolean or brightness integer from 0 through 100.' };
+    }
+    await this.client.publish({ topic: `${device.commandBase}${command}`, payload, qos: 0, retain: false }, abortSignalArg);
+    return { success: true, data: { accepted: true } };
+  }
+
+  public destroy(): Promise<void> {
+    if (this.destroyPromise) return this.destroyPromise;
+    this.destroyed = true;
+    this.stopConnectionListener();
+    this.lifetime.abort(new DeviceCommunicationError('Tasmota runtime destroyed.'));
+    for (const cleanup of [...this.subscriptionCleanups]) cleanup();
+    this.listeners.clear();
+    this.changed.clear();
+    this.destroyPromise = this.client.destroy();
+    return this.destroyPromise;
+  }
+
+  private state(deviceArg: ITasmotaSelectedDevice): ITasmotaDeviceState {
+    const state = this.states.get(deviceArg.id);
+    if (!state) throw new DeviceCommunicationError('Selected Tasmota device state is missing.');
+    return state;
+  }
+
+  private ready(deviceArg: ITasmotaSelectedDevice): boolean {
+    const state = this.state(deviceArg);
+    return state.ready && state.online;
+  }
+
+  private checkActive(abortSignalArg?: AbortSignal): void {
+    abortSignalArg?.throwIfAborted();
+    this.lifetime.signal.throwIfAborted();
+  }
+
+  private async withDeadline<TValue>(operationArg: (signalArg: AbortSignal) => Promise<TValue>, abortSignalArg?: AbortSignal): Promise<TValue> {
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(new DeviceCommunicationError('Tasmota fresh state deadline exceeded.')), this.config.initialSnapshotTimeoutMs);
+    const signal = AbortSignal.any([this.lifetime.signal, deadline.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+    try {
+      signal.throwIfAborted();
+      return await operationArg(signal);
+    } finally {
+      clearTimeout(timer);
+      deadline.abort();
+    }
+  }
+
+  private async refresh(devicesArg: ITasmotaSelectedDevice[], signalArg: AbortSignal, generationsArg = new Map<string, number>()): Promise<void> {
+    for (const device of devicesArg) {
+      const state = this.state(device);
+      state.ready = false;
+      state.queryPending = true;
+      state.generation += 1;
+      generationsArg.set(device.id, state.generation);
+    }
+    for (const handler of this.changed) handler();
+    const fresh = this.waitForFresh(devicesArg, generationsArg, signalArg);
+    const queries = async (): Promise<void> => {
+      for (const device of devicesArg) {
+        await this.client.publish({ topic: `${device.commandBase}State`, payload: '', qos: 0, retain: false }, signalArg);
+        await this.client.publish({ topic: `${device.commandBase}Status`, payload: '10', qos: 0, retain: false }, signalArg);
+      }
+    };
+    await Promise.all([fresh, queries()]);
+  }
+
+  private refreshInBackground(devicesArg: ITasmotaSelectedDevice[]): void {
+    const generations = new Map<string, number>();
+    void this.withDeadline((signalArg) => this.refresh(devicesArg, signalArg, generations)).catch((errorArg: unknown) => {
+      if (this.destroyed) return;
+      const currentDevices = devicesArg.filter((deviceArg) => this.state(deviceArg).generation === generations.get(deviceArg.id));
+      if (!currentDevices.length) return;
+      for (const device of currentDevices) this.markOffline(device);
+      this.emit({ type: 'error', data: { message: errorArg instanceof Error ? errorArg.message : 'Tasmota state refresh failed.' } });
+    });
+  }
+
+  private waitForFresh(devicesArg: ITasmotaSelectedDevice[], generationsArg: Map<string, number>, signalArg: AbortSignal): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const cleanup = (): void => {
+        this.changed.delete(check);
+        signalArg.removeEventListener('abort', aborted);
+      };
+      const check = (): void => {
+        if (devicesArg.some((deviceArg) => this.state(deviceArg).generation !== generationsArg.get(deviceArg.id))) {
+          cleanup();
+          reject(new DeviceCommunicationError('Tasmota state refresh superseded by a connection or availability change.'));
+          return;
+        }
+        if (this.client.connected && devicesArg.every((deviceArg) => this.ready(deviceArg))) {
+          cleanup();
+          resolve();
+        }
+      };
+      const aborted = (): void => {
+        cleanup();
+        reject(signalArg.reason);
+      };
+      this.changed.add(check);
+      signalArg.addEventListener('abort', aborted, { once: true });
+      if (signalArg.aborted) aborted();
+      else check();
+    });
+  }
+
+  private markOffline(deviceArg: ITasmotaSelectedDevice): void {
+    const state = this.state(deviceArg);
+    const wasOnline = this.ready(deviceArg);
+    state.ready = false;
+    state.online = false;
+    state.queryPending = false;
+    state.generation += 1;
+    if (wasOnline) this.emit({ type: 'availability_changed', deviceId: deviceArg.id, data: { online: false } });
+    for (const handler of this.changed) handler();
+  }
+
+  private receive(deviceArg: ITasmotaSelectedDevice, messageArg: IMqttMessage): void {
+    if (this.destroyed) return;
+    const status = messageArg.topic.startsWith(deviceArg.statusBase);
+    const suffix = messageArg.topic.slice((status ? deviceArg.statusBase : deviceArg.telemetryBase).length);
+    const state = this.state(deviceArg);
+    if (!status && suffix === 'LWT') {
+      if (messageArg.payload === 'Offline') this.markOffline(deviceArg);
+      else if (messageArg.payload === 'Online' && !this.ready(deviceArg) && !state.queryPending && !this.initializing) this.refreshInBackground([deviceArg]);
+      return;
+    }
+    if (messageArg.retain && state.ready) return;
+    let record = parseTasmotaRecord(messageArg.payload);
+    if (status && /^POWER(?:[1-9]\d*)?$/u.test(suffix) && typeof messageArg.payload === 'string') record = { [suffix]: messageArg.payload };
+    if (!record) {
+      if (['RESULT', 'STATE', 'SENSOR', 'STATUS10', 'STATUS11'].includes(suffix)) this.emit({ type: 'error', deviceId: deviceArg.id, data: { message: 'Invalid Tasmota JSON state message.' } });
+      return;
+    }
+    const sensorRecord = suffix === 'STATUS10' ? tasmotaRecord(record.StatusSNS) : suffix === 'SENSOR' ? record : undefined;
+    if (sensorRecord) {
+      state.sensors = TasmotaMapper.sensors(sensorRecord);
+      state.updatedAt = new Date().toISOString();
+    } else if (['RESULT', 'STATE', 'STATUS11'].includes(suffix) || /^POWER(?:[1-9]\d*)?$/u.test(suffix)) {
+      const controlRecord = suffix === 'STATUS11' ? tasmotaRecord(record.StatusSTS) : record;
+      if (!controlRecord) return;
+      const controls = TasmotaMapper.controls(deviceArg, controlRecord);
+      state.updatedAt = new Date().toISOString();
+      const fullState = suffix === 'STATE' || suffix === 'STATUS11' || (suffix === 'RESULT' && (typeof controlRecord.Time === 'string' || typeof controlRecord.Uptime === 'string' || typeof controlRecord.UptimeSec === 'number'));
+      const invalidRelay = deviceArg.relays.some((relayArg) => (controlRecord[`POWER${relayArg}`] !== undefined || (relayArg === 1 && controlRecord.POWER !== undefined)) && controls[`power_${relayArg}`] === undefined);
+      const invalidDimmer = deviceArg.brightness && controlRecord.Dimmer !== undefined && controls.brightness === undefined;
+      if ((fullState && !TasmotaMapper.completeControls(deviceArg, controls)) || invalidRelay || invalidDimmer) {
+        state.controls = controls;
+        this.markOffline(deviceArg);
+        this.emit({ type: 'error', deviceId: deviceArg.id, data: { message: 'Tasmota state does not report valid configured controls.' } });
+        this.emit({ type: 'state_changed', deviceId: deviceArg.id });
+        return;
+      }
+      if (fullState) state.controls = controls;
+      else Object.assign(state.controls, controls);
+      if (fullState && !messageArg.retain && state.queryPending && TasmotaMapper.completeControls(deviceArg, controls)) {
+        state.ready = true;
+        state.online = true;
+        state.queryPending = false;
+        this.emit({ type: 'availability_changed', deviceId: deviceArg.id, data: { online: true } });
+      }
+    } else return;
+    this.emit({ type: 'state_changed', deviceId: deviceArg.id });
+    for (const handler of this.changed) handler();
+  }
+
+  private emit(eventArg: Omit<IIntegrationEvent, 'integrationDomain' | 'timestamp'>): void {
+    if (this.destroyed) return;
+    const event: IIntegrationEvent = { ...eventArg, integrationDomain: this.domain, timestamp: Date.now() };
+    for (const handler of this.listeners) handler(event);
+  }
+}

package/ts/integrations/tasmota/tasmota.config.ts

@@ -0,0 +1,69 @@
+import { IntegrationError } from '../../core/errors.js';
+import type { IHomeAssistantTasmotaConfig, ITasmotaConfig, ITasmotaDeviceConfig, ITasmotaSelectedDevice } from './tasmota.types.js';
+
+const fail = (messageArg: string): never => {
+  throw new IntegrationError(messageArg, 'INVALID_TASMOTA_CONFIG');
+};
+
+const topicPart = (valueArg: unknown, labelArg: string): string => {
+  if (typeof valueArg !== 'string' || !valueArg.trim() || /[+#\u0000-\u001f\u007f]/u.test(valueArg) || valueArg !== valueArg.trim()) {
+    return fail(`${labelArg} must be a nonempty MQTT topic without wildcards or control characters.`);
+  }
+  return valueArg;
+};
+
+const selectedDevice = (deviceArg: ITasmotaDeviceConfig): ITasmotaSelectedDevice => {
+  if (!deviceArg || typeof deviceArg !== 'object') return fail('Every Tasmota device must be a config object.');
+  const topic = topicPart(deviceArg.topic, 'Tasmota topic');
+  const fullTopic = deviceArg.fullTopic ?? '%prefix%/%topic%/';
+  if (typeof fullTopic !== 'string' || fullTopic.length > 100 || !fullTopic.endsWith('/') || fullTopic.split('%prefix%').length !== 2 || fullTopic.split('%topic%').length !== 2 || /%/u.test(fullTopic.replace('%prefix%', '').replace('%topic%', ''))) {
+    return fail('FullTopic must end in / and contain exactly one %prefix% and one %topic%; other tokens are unsupported.');
+  }
+  const prefixes = deviceArg.prefixes ?? { command: 'cmnd', status: 'stat', telemetry: 'tele' };
+  if (!prefixes || typeof prefixes !== 'object') return fail('Tasmota prefixes must specify command, status and telemetry strings.');
+  if (deviceArg.name !== undefined && (typeof deviceArg.name !== 'string' || !deviceArg.name.trim())) return fail('Tasmota name must be a nonempty string.');
+  if (deviceArg.model !== undefined && typeof deviceArg.model !== 'string') return fail('Tasmota model must be a string.');
+  const base = (prefixArg: string): string => {
+    const prefix = topicPart(prefixArg, 'Tasmota prefix');
+    return topicPart(fullTopic.replace(/%prefix%|%topic%/gu, (tokenArg) => tokenArg === '%prefix%' ? prefix : topic), 'Tasmota FullTopic');
+  };
+  const relays = deviceArg.relays ?? [1];
+  if (!Array.isArray(relays) || relays.some((relayArg) => !Number.isInteger(relayArg) || relayArg < 1 || relayArg > 32) || new Set(relays).size !== relays.length) {
+    return fail('Tasmota relays must be unique integers from 1 through 32.');
+  }
+  if (deviceArg.brightness !== undefined && typeof deviceArg.brightness !== 'boolean') return fail('Tasmota brightness must be boolean.');
+  const powerOnPayload = deviceArg.powerOnPayload ?? 'ON';
+  const powerOffPayload = deviceArg.powerOffPayload ?? 'OFF';
+  if (typeof powerOnPayload !== 'string' || !powerOnPayload || typeof powerOffPayload !== 'string' || !powerOffPayload || powerOnPayload === powerOffPayload) return fail('Tasmota power state texts must be distinct nonempty strings.');
+  return {
+    id: deviceArg.id === undefined ? `tasmota:${encodeURIComponent(topic)}` : topicPart(deviceArg.id, 'Tasmota device id'),
+    topic,
+    name: deviceArg.name ?? topic,
+    model: deviceArg.model,
+    commandBase: base(prefixes.command),
+    statusBase: base(prefixes.status),
+    telemetryBase: base(prefixes.telemetry),
+    relays: [...relays].sort((leftArg, rightArg) => leftArg - rightArg),
+    brightness: deviceArg.brightness ?? false,
+    powerOnPayload,
+    powerOffPayload,
+  };
+};
+
+export const normalizeTasmotaConfig = (configArg: IHomeAssistantTasmotaConfig): ITasmotaConfig => {
+  if (!configArg || typeof configArg !== 'object' || !configArg.broker || typeof configArg.broker.host !== 'string' || !configArg.broker.host.trim() || configArg.broker.host !== configArg.broker.host.trim()) return fail('Tasmota requires a real MQTT broker host without surrounding whitespace.');
+  if (configArg.broker.port !== undefined && (!Number.isInteger(configArg.broker.port) || configArg.broker.port < 1 || configArg.broker.port > 65_535)) return fail('Tasmota broker port must be an integer from 1 through 65535.');
+  if (configArg.broker.protocol !== undefined && configArg.broker.protocol !== 'mqtt' && configArg.broker.protocol !== 'mqtts') return fail('Tasmota broker protocol must be mqtt or mqtts.');
+  if (!Array.isArray(configArg.devices) || !configArg.devices.length || configArg.devices.length > 128) return fail('Select from 1 through 128 Tasmota devices.');
+  const devices = configArg.devices.map(selectedDevice);
+  if (new Set(devices.map((deviceArg) => deviceArg.id)).size !== devices.length) return fail('Selected Tasmota device ids must be unique.');
+  const bases = devices.flatMap((deviceArg) => [deviceArg.commandBase, deviceArg.statusBase, deviceArg.telemetryBase]);
+  if (bases.some((baseArg, indexArg) => bases.some((otherArg, otherIndexArg) => indexArg !== otherIndexArg && baseArg.startsWith(otherArg)))) return fail('Selected Tasmota FullTopics and prefixes must not overlap.');
+  const initialSnapshotTimeoutMs = configArg.initialSnapshotTimeoutMs ?? 10_000;
+  if (!Number.isInteger(initialSnapshotTimeoutMs) || initialSnapshotTimeoutMs < 1 || initialSnapshotTimeoutMs > 2_147_483_647) return fail('initialSnapshotTimeoutMs must be a timer-safe positive integer.');
+  return {
+    devices,
+    initialSnapshotTimeoutMs,
+    broker: { ...configArg.broker, discovery: false, birthMessage: false, willMessage: false, subscriptions: [], entities: [], discoveryMessages: [], retainedMessages: [] },
+  };
+};

package/ts/integrations/tasmota/tasmota.discovery.ts

@@ -0,0 +1,84 @@
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
+import { normalizeTasmotaConfig } from './tasmota.config.js';
+import type { IHomeAssistantTasmotaConfig } from './tasmota.types.js';
+
+class TasmotaManualMatcher implements IDiscoveryMatcher<IDiscoveryCandidate> {
+  public readonly id = 'tasmota-selected-device';
+  public readonly source = 'manual' as const;
+
+  public async matches(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    const topic = candidateArg.metadata?.topic;
+    const matched = candidateArg.integrationDomain === 'tasmota' && typeof candidateArg.host === 'string' && Boolean(candidateArg.host) && typeof topic === 'string' && Boolean(topic);
+    return {
+      matched,
+      confidence: matched ? 'high' : 'low',
+      reason: matched ? 'Selected Tasmota device has a broker host and device topic; setup verifies live state.' : 'Tasmota requires an explicit broker host and device topic.',
+      candidate: matched ? candidateArg : undefined,
+      normalizedDeviceId: matched ? `tasmota:${encodeURIComponent(topic)}` : undefined,
+    };
+  }
+}
+
+class TasmotaCandidateValidator implements IDiscoveryValidator {
+  public readonly id = 'tasmota-selected-device-validator';
+
+  public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    return new TasmotaManualMatcher().matches(candidateArg);
+  }
+}
+
+export const createTasmotaDiscoveryDescriptor = (): DiscoveryDescriptor => {
+  return new DiscoveryDescriptor({ integrationDomain: 'tasmota', displayName: 'Tasmota' })
+    .addMatcher(new TasmotaManualMatcher())
+    .addValidator(new TasmotaCandidateValidator());
+};
+
+export class TasmotaConfigFlow implements IConfigFlow<IHomeAssistantTasmotaConfig> {
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IHomeAssistantTasmotaConfig>> {
+    void contextArg;
+    return {
+      kind: 'form',
+      title: 'Connect a selected Tasmota device',
+      description: 'Use the device MQTT broker, unique Topic and FullTopic. The device must already be configured for this broker.',
+      fields: [
+        { name: 'host', label: 'MQTT broker host', type: 'text', required: true },
+        { name: 'port', label: 'MQTT broker port', type: 'number' },
+        { name: 'useTls', label: 'Use MQTT TLS', type: 'boolean' },
+        { name: 'username', label: 'Broker username', type: 'text' },
+        { name: 'password', label: 'Broker password', type: 'password' },
+        { name: 'topic', label: 'Device Topic', type: 'text', required: true },
+        { name: 'fullTopic', label: 'FullTopic', type: 'text' },
+        { name: 'relayCount', label: 'Relay count (0 through 32)', type: 'number' },
+        { name: 'brightness', label: 'Single-channel Dimmer', type: 'boolean' },
+      ],
+      submit: async (valuesArg) => {
+        try {
+          for (const field of ['username', 'password', 'fullTopic']) if (valuesArg[field] !== undefined && typeof valuesArg[field] !== 'string') throw new Error(`${field} must be a string.`);
+          for (const field of ['useTls', 'brightness']) if (valuesArg[field] !== undefined && typeof valuesArg[field] !== 'boolean') throw new Error(`${field} must be boolean.`);
+          const relayCount = valuesArg.relayCount ?? 1;
+          if (typeof relayCount !== 'number' || !Number.isInteger(relayCount) || relayCount < 0 || relayCount > 32) throw new Error('relayCount must be an integer from 0 through 32.');
+          const host = valuesArg.host ?? candidateArg.host;
+          const topic = valuesArg.topic ?? candidateArg.metadata?.topic;
+          if (typeof host !== 'string' || typeof topic !== 'string') throw new Error('Broker host and device topic are required.');
+          const port = valuesArg.port ?? candidateArg.port;
+          if (port !== undefined && (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535)) throw new Error('Broker port must be an integer from 1 through 65535.');
+          const config: IHomeAssistantTasmotaConfig = {
+            broker: {
+              host,
+              port,
+              protocol: valuesArg.useTls === true ? 'mqtts' : 'mqtt',
+              username: typeof valuesArg.username === 'string' ? valuesArg.username : undefined,
+              password: typeof valuesArg.password === 'string' ? valuesArg.password : undefined,
+            },
+            devices: [{ topic, fullTopic: typeof valuesArg.fullTopic === 'string' && valuesArg.fullTopic ? valuesArg.fullTopic : undefined, relays: Array.from({ length: relayCount }, (_, indexArg) => indexArg + 1), brightness: valuesArg.brightness === true }],
+          };
+          normalizeTasmotaConfig(config);
+          return { kind: 'done', title: 'Selected Tasmota device configured', config };
+        } catch (errorArg) {
+          return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Invalid Tasmota configuration.' };
+        }
+      },
+    };
+  }
+}

package/ts/integrations/tasmota/tasmota.mapper.ts

@@ -0,0 +1,88 @@
+import * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { ITasmotaDeviceState, ITasmotaSelectedDevice } from './tasmota.types.js';
+
+export const tasmotaRecord = (valueArg: unknown): Record<string, unknown> | undefined => {
+  return valueArg !== null && typeof valueArg === 'object' && !Array.isArray(valueArg) ? valueArg as Record<string, unknown> : undefined;
+};
+
+export const parseTasmotaRecord = (payloadArg: unknown): Record<string, unknown> | undefined => {
+  if (typeof payloadArg !== 'string') return tasmotaRecord(payloadArg);
+  try {
+    return tasmotaRecord(JSON.parse(payloadArg));
+  } catch {
+    return undefined;
+  }
+};
+
+export class TasmotaMapper {
+  public static controls(deviceArg: ITasmotaSelectedDevice, recordArg: Record<string, unknown>): Record<string, boolean | number> {
+    const controls: Record<string, boolean | number> = {};
+    for (const relay of deviceArg.relays) {
+      const value = recordArg[`POWER${relay}`] ?? (relay === 1 ? recordArg.POWER : undefined);
+      if (value === deviceArg.powerOnPayload) controls[`power_${relay}`] = true;
+      if (value === deviceArg.powerOffPayload) controls[`power_${relay}`] = false;
+    }
+    if (deviceArg.brightness && typeof recordArg.Dimmer === 'number' && Number.isInteger(recordArg.Dimmer) && recordArg.Dimmer >= 0 && recordArg.Dimmer <= 100) controls.brightness = recordArg.Dimmer;
+    return controls;
+  }
+
+  public static completeControls(deviceArg: ITasmotaSelectedDevice, controlsArg: Record<string, boolean | number>): boolean {
+    return deviceArg.relays.every((relayArg) => typeof controlsArg[`power_${relayArg}`] === 'boolean') && (!deviceArg.brightness || typeof controlsArg.brightness === 'number');
+  }
+
+  public static sensors(recordArg: Record<string, unknown>): Record<string, number | boolean | string> {
+    const sensors: Record<string, number | boolean | string> = {};
+    const visit = (recordArg: Record<string, unknown>, pathArg: string[], depthArg: number): void => {
+      if (depthArg > 6) return;
+      for (const [key, value] of Object.entries(recordArg)) {
+        if (!pathArg.length && ['Time', 'TempUnit', 'PressureUnit'].includes(key)) continue;
+        const path = [...pathArg, key];
+        const child = tasmotaRecord(value);
+        if (child) visit(child, path, depthArg + 1);
+        else if (typeof value === 'boolean' || typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value))) {
+          if (Object.keys(sensors).length >= 256) return;
+          sensors[`sensor_${path.map(encodeURIComponent).join('/')}`] = value;
+        }
+      }
+    };
+    visit(recordArg, [], 0);
+    return sensors;
+  }
+
+  public static device(deviceArg: ITasmotaSelectedDevice, stateArg: ITasmotaDeviceState, connectedArg: boolean): plugins.shxInterfaces.data.IDeviceDefinition {
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = deviceArg.relays.map((relayArg) => ({ id: `power_${relayArg}`, capability: 'switch', name: `Relay ${relayArg}`, readable: true, writable: true }));
+    if (deviceArg.brightness) features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' });
+    for (const id of Object.keys(stateArg.sensors).sort()) features.push({ id, capability: id.startsWith('sensor_ENERGY/') ? 'energy' : 'sensor', name: id.slice('sensor_'.length).split('/').map(decodeURIComponent).join(' '), readable: true, writable: false });
+    const values = { ...stateArg.controls, ...stateArg.sensors };
+    return {
+      id: deviceArg.id,
+      integrationDomain: 'tasmota',
+      name: deviceArg.name,
+      protocol: 'mqtt',
+      manufacturer: 'Tasmota',
+      model: deviceArg.model,
+      online: connectedArg && stateArg.ready && stateArg.online,
+      features,
+      state: features.map((featureArg) => ({ featureId: featureArg.id, value: values[featureArg.id] ?? null, updatedAt: stateArg.updatedAt })),
+      metadata: { topic: deviceArg.topic, stateSource: 'tasmota-mqtt', fresh: stateArg.ready },
+    };
+  }
+
+  public static entities(deviceArg: plugins.shxInterfaces.data.IDeviceDefinition): IIntegrationEntity[] {
+    return deviceArg.features.map((featureArg) => {
+      const platform = featureArg.capability === 'switch' ? 'switch' : featureArg.capability === 'light' ? 'light' : 'sensor';
+      return {
+        id: `${platform}.${encodeURIComponent(deviceArg.id)}.${encodeURIComponent(featureArg.id)}`,
+        uniqueId: `${deviceArg.id}:${featureArg.id}`,
+        integrationDomain: 'tasmota',
+        deviceId: deviceArg.id,
+        platform,
+        name: `${deviceArg.name} ${featureArg.name}`,
+        state: deviceArg.state.find((stateArg) => stateArg.featureId === featureArg.id)?.value ?? null,
+        available: deviceArg.online,
+        attributes: { featureId: featureArg.id, unit: featureArg.unit },
+      };
+    });
+  }
+}

package/ts/integrations/tasmota/tasmota.types.ts

@@ -1,4 +1,50 @@
+import type { IMqttConfig } from '../mqtt/mqtt.types.js';
+
+export interface ITasmotaDeviceConfig {
+  topic: string;
+  id?: string;
+  name?: string;
+  model?: string;
+  fullTopic?: string;
+  prefixes?: { command: string; status: string; telemetry: string };
+  relays?: number[];
+  brightness?: boolean;
+  powerOnPayload?: string;
+  powerOffPayload?: string;
+}
+
 export interface IHomeAssistantTasmotaConfig {
-  // TODO: replace with the TypeScript-native config for tasmota.
-  [key: string]: unknown;
+  broker: IMqttConfig & { host: string };
+  devices: ITasmotaDeviceConfig[];
+  initialSnapshotTimeoutMs?: number;
+}
+
+export interface ITasmotaSelectedDevice {
+  id: string;
+  topic: string;
+  name: string;
+  model?: string;
+  commandBase: string;
+  statusBase: string;
+  telemetryBase: string;
+  relays: number[];
+  brightness: boolean;
+  powerOnPayload: string;
+  powerOffPayload: string;
+}
+
+export interface ITasmotaConfig {
+  broker: IMqttConfig & { host: string };
+  devices: ITasmotaSelectedDevice[];
+  initialSnapshotTimeoutMs: number;
+}
+
+export interface ITasmotaDeviceState {
+  generation: number;
+  ready: boolean;
+  online: boolean;
+  queryPending: boolean;
+  updatedAt: string;
+  controls: Record<string, boolean | number>;
+  sensors: Record<string, number | boolean | string>;
 }

package/ts/integrations/tplink/index.ts

@@ -4,3 +4,6 @@ export * from './tplink.classes.integration.js';
 export * from './tplink.discovery.js';
 export * from './tplink.mapper.js';
 export * from './tplink.types.js';
+export * from './tplink.native.types.js';
+export * from './tplink.native.mapper.js';
+export * from './tplink.validation.js';

package/ts/integrations/tplink/readme.md

@@ -0,0 +1,38 @@
+# TP-Link legacy Kasa
+
+`TplinkIntegration` provides a native local TCP runtime for the single relay advertised by legacy `IOT.SMARTPLUGSWITCH` devices. The integration delegates legacy XOR framing, same-connection identity and capability preflight, bounded operation queues, cancellation, and terminal socket cleanup to `@ecobridge.xyz/devicemanager` `KasaProtocol` (available from version `4.3.0`).
+
+```typescript
+import { TplinkIntegration } from '@smarthome.exchange/integrations';
+
+const integration = new TplinkIntegration();
+const runtime = await integration.setup({
+  homeId: 'your-home-id',
+  transport: 'legacy-kasa',
+  host: '192.168.1.40',
+  expectedDeviceId: '800611223344556677889900AABBCCDDEEFF001122',
+}, {});
+try {
+  const [device] = await runtime.devices();
+  const [entity] = await runtime.entities();
+  const result = await runtime.callService!({
+    domain: 'switch', service: 'turn_on', target: { entityId: entity.id },
+  });
+  console.log(result);
+  console.log((await runtime.devices())[0].state);
+} finally {
+  await integration.destroy();
+}
+```
+
+Configuration requires an explicit home ID, literal unicast IP address, expected legacy device ID, and `transport: 'legacy-kasa'`. Port defaults to `9999`; `timeoutMs` defaults to `5000` and covers queue admission, connection, identity preflight and the response. Resource limits are `maxResponseBytes` (default `65536`, range `128–1048576`) and `maxPendingOperations` (default `16`, range `1–128`). The deadline range is `1–30000` ms. Discovery advertisements are hints: actual legacy system information must verify identity and single-relay support before setup succeeds.
+
+The runtime exposes one writable `power` switch feature and one switch entity. IDs contain both the home and observed device identity. It admits only exact owned targets, `switch.turn_on`, `switch.turn_off`, or a boolean `power` feature write. Toggle, broadcast targets, additional service data and unsupported features are rejected before any write. `devices()` and `entities()` obtain fresh authoritative system information. Subscriptions observe these explicit reads; the integration does not claim a push protocol or run automatic polling.
+
+A successful write reports `outcome: 'accepted'` and `physicalStateConfirmed: false`. A protocol acknowledgment confirms acceptance only, never physical completion. Subsequent reads remain authoritative; there is no optimistic state update. Rejections report `not-sent`, `rejected` or `indeterminate`; an indeterminate effect must not be retried automatically. No command is retried or automatically reconnected. Destroy is terminal and idempotent, cancels queued and active work, drains owned sockets, and releases subscriptions.
+
+Legacy Kasa takes no credentials and performs no authentication. Its XOR obfuscation is not cryptographic encryption; an observed device-ID match does not authenticate the peer. Configure only an owner-controlled network endpoint. No secrets or filesystem application state are stored. If a caller provides a config store, it must be an encrypted `NoSqlConfigStore` scoped to the configured home and `tplink`; the integration does not own or close that store.
+
+Tapo, SMART/AES/KLAP, cloud login, bulbs, dimmer settings, energy-meter features, schedules, discovery broadcasts and child power strips are unsupported. These devices fail admission rather than falling back to snapshots or another transport. The existing `TplinkMapper` remains an offline snapshot mapping utility; supplying snapshots or `commandExecutor` to the native runtime is no longer supported. Migrate runtime configuration to the explicit native schema above.
+
+Verified against local TCP protocol fixtures only. Physical hardware, vendor credentials and firmware-specific behavior remain unverified. See the owning package's Kasa documentation and the [Home Assistant TP-Link integration](https://www.home-assistant.io/integrations/tplink/) for ecosystem coverage; that broader coverage does not define this runtime's admitted subset.