@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/mqtt/mqtt.classes.configflow.ts

@@ -17,28 +17,32 @@ export class MqttConfigFlow implements IConfigFlow<IMqttConfig> {
         { name: 'clientId', label: 'Client ID', type: 'text' },
         { name: 'discoveryPrefix', label: 'Discovery prefix', type: 'text' },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'MQTT configured',
-        config: {
-          host: this.stringValue(valuesArg.host) || candidateArg.host || '',
-          port: this.numberValue(valuesArg.port) || candidateArg.port || 1883,
-          protocol: valuesArg.protocol === 'mqtts' ? 'mqtts' : 'mqtt',
-          username: this.stringValue(valuesArg.username),
-          password: this.stringValue(valuesArg.password),
-          clientId: this.stringValue(valuesArg.clientId),
-          discovery: true,
-          discoveryPrefix: this.stringValue(valuesArg.discoveryPrefix) || 'homeassistant',
-        },
-      }),
+      submit: async (valuesArg) => {
+        const host = this.stringValue(valuesArg.host) || candidateArg.host;
+        const protocol = valuesArg.protocol === 'mqtts' ? 'mqtts' : 'mqtt';
+        const port = valuesArg.port ?? candidateArg.port ?? (protocol === 'mqtts' ? 8883 : 1883);
+        if (!host || typeof port !== 'number' || !Number.isSafeInteger(port) || port < 1 || port > 65535) {
+          return { kind: 'error', error: 'A broker host and integer port from 1 through 65535 are required.' };
+        }
+        return {
+          kind: 'done',
+          title: 'MQTT configured',
+          config: {
+            host,
+            port,
+            protocol,
+            username: this.stringValue(valuesArg.username),
+            password: typeof valuesArg.password === 'string' ? valuesArg.password : undefined,
+            clientId: this.stringValue(valuesArg.clientId),
+            discovery: true,
+            discoveryPrefix: this.stringValue(valuesArg.discoveryPrefix) || 'homeassistant',
+          },
+        };
+      },
     };
   }
 
   private stringValue(valueArg: unknown): string | undefined {
     return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
   }
-
-  private numberValue(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' && Number.isFinite(valueArg) ? valueArg : undefined;
-  }
 }

package/ts/integrations/mqtt/mqtt.classes.integration.ts

@@ -1,6 +1,6 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { MqttClient } from './mqtt.classes.client.js';
 import { MqttConfigFlow } from './mqtt.classes.configflow.js';
 import { createMqttDiscoveryDescriptor } from './mqtt.discovery.js';
@@ -23,8 +23,16 @@ export class MqttIntegration extends BaseIntegration<IMqttConfig> {
   };
 
   public async setup(configArg: IMqttConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new MqttRuntime(new MqttClient(configArg));
+    const client = new MqttClient(configArg);
+    const runtime = new MqttRuntime(client);
+    try {
+      await client.start(contextArg.abortSignal);
+      return runtime;
+    } catch (error) {
+      try { await runtime.destroy(); }
+      catch (cleanupError) { throw new AggregateError([error, cleanupError], 'MQTT setup and cleanup failed.'); }
+      throw error;
+    }
   }
 
   public async destroy(): Promise<void> {}
@@ -33,65 +41,132 @@ export class MqttIntegration extends BaseIntegration<IMqttConfig> {
 export class HomeAssistantMqttIntegration extends MqttIntegration {}
 
 class MqttRuntime implements IIntegrationRuntime {
-  public domain = 'mqtt';
+  public readonly domain = 'mqtt';
+  private readonly handlers = new Set<(eventArg: IIntegrationEvent) => void>();
+  private readonly subscriptionCleanups = new Set<() => Promise<void>>();
+  private readonly removeMessageHandler: () => void;
+  private readonly removeConnectionHandler: () => void;
+  private previousEntities = new Map<string, IIntegrationEntity>();
+  private updatePromise = Promise.resolve();
+  private updateRequested = false;
+  private updating = false;
+  private destroyed = false;
 
-  constructor(private readonly client: MqttClient) {}
+  constructor(private readonly client: MqttClient) {
+    this.removeMessageHandler = client.onMessage(() => this.queueUpdate());
+    this.removeConnectionHandler = client.onConnectionState((stateArg) => {
+      if (stateArg.error) this.emit({ type: 'error', integrationDomain: this.domain, data: { message: stateArg.error.message }, timestamp: Date.now() });
+      this.queueUpdate();
+    });
+  }
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return MqttMapper.toDevices(await this.client.getSnapshot());
+  public isHealthy(): boolean {
+    return this.client.isHealthy();
+  }
+
+  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return MqttMapper.toDevices(await this.client.getSnapshot(abortSignalArg));
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
     return MqttMapper.toEntities(await this.client.getSnapshot());
   }
 
-  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void): Promise<() => Promise<void>> {
-    return this.client.subscribe('#', (messageArg) => {
-      handlerArg({
-        type: 'state_changed',
-        integrationDomain: 'mqtt',
-        data: messageArg,
-        timestamp: messageArg.timestamp || Date.now(),
-      });
-    });
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    if (this.destroyed) throw new Error('MQTT runtime has been destroyed.');
+    if (abortSignalArg?.aborted) throw new Error('MQTT subscription aborted.');
+    this.handlers.add(handlerArg);
+    let released = false;
+    const cleanup = async (): Promise<void> => {
+      if (released) return;
+      released = true;
+      this.handlers.delete(handlerArg);
+      this.subscriptionCleanups.delete(cleanup);
+      abortSignalArg?.removeEventListener('abort', abort);
+    };
+    const abort = (): void => { void cleanup(); };
+    this.subscriptionCleanups.add(cleanup);
+    abortSignalArg?.addEventListener('abort', abort, { once: true });
+    this.queueUpdate();
+    return cleanup;
   }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain === 'mqtt') {
-      if (requestArg.service !== 'publish') {
-        return { success: false, error: `Unsupported MQTT service: ${requestArg.service}` };
-      }
-      const publishOptions = this.publishOptionsFromRequest(requestArg);
-      if (!publishOptions) {
-        return { success: false, error: 'MQTT publish requires data.topic.' };
-      }
-      await this.client.publish(publishOptions);
+    try {
+      let command: IMqttPublishOptions | undefined;
+      if (requestArg.domain === 'mqtt') {
+        if (requestArg.service !== 'publish') return { success: false, error: 'Unsupported MQTT broker service.' };
+        command = this.publishOptionsFromRequest(requestArg);
+      } else command = MqttMapper.commandForService(await this.client.getSnapshot(), requestArg);
+      if (!command) return { success: false, error: 'MQTT service requires an available, unambiguous supported target and valid input.' };
+      await this.client.publish(command);
       return { success: true };
-    }
+    } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
+  }
 
-    const publishOptions = MqttMapper.commandForService(await this.client.getSnapshot(), requestArg);
-    if (!publishOptions) {
-      return { success: false, error: `MQTT entity service ${requestArg.domain}.${requestArg.service} has no command topic mapping.` };
-    }
-    await this.client.publish(publishOptions);
-    return { success: true };
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const command = MqttMapper.commandForFeature(await this.client.getSnapshot(abortSignalArg), requestArg);
+      if (!command) return { success: false, error: 'MQTT feature requires an available, unambiguous supported target and valid value.' };
+      await this.client.publish(command, abortSignalArg);
+      return { success: true };
+    } catch (error) { return { success: false, error: error instanceof Error ? error.message : String(error) }; }
   }
 
   public async destroy(): Promise<void> {
+    this.destroyed = true;
+    this.removeMessageHandler();
+    this.removeConnectionHandler();
+    for (const cleanup of [...this.subscriptionCleanups]) await cleanup();
+    this.handlers.clear();
     await this.client.destroy();
+    await this.updatePromise;
   }
 
-  private publishOptionsFromRequest(requestArg: IServiceCallRequest): IMqttPublishOptions | undefined {
-    const topic = requestArg.data?.topic;
-    if (typeof topic !== 'string' || !topic) {
-      return undefined;
+  private queueUpdate(): void {
+    if (this.destroyed) return;
+    this.updateRequested = true;
+    if (this.updating) return;
+    this.updating = true;
+    this.updatePromise = this.updateSnapshots().catch((error: unknown) => {
+      if (!this.destroyed) this.emit({ type: 'error', integrationDomain: this.domain, data: { message: error instanceof Error ? error.message : String(error) }, timestamp: Date.now() });
+    }).finally(() => {
+      this.updating = false;
+      if (this.updateRequested && !this.destroyed) this.queueUpdate();
+    });
+  }
+
+  private async updateSnapshots(): Promise<void> {
+    while (this.updateRequested && !this.destroyed) {
+      this.updateRequested = false;
+      const entities = await this.entities();
+      const next = new Map(entities.map((entityArg) => [entityArg.uniqueId, entityArg]));
+      for (const entity of entities) {
+        const previous = this.previousEntities.get(entity.uniqueId);
+        const event = { integrationDomain: this.domain, entityId: entity.id, deviceId: entity.deviceId, timestamp: Date.now() };
+        if (!previous) this.emit({ ...event, type: 'entity_added', data: entity });
+        if (previous?.available !== entity.available) this.emit({ ...event, type: 'availability_changed', data: { available: entity.available } });
+        if (!previous || JSON.stringify(previous.state) !== JSON.stringify(entity.state) || JSON.stringify(previous.attributes) !== JSON.stringify(entity.attributes)) {
+          this.emit({ ...event, type: 'state_changed', data: entity });
+        }
+      }
+      for (const [id, entity] of this.previousEntities) {
+        if (!next.has(id)) this.emit({ type: 'entity_removed', integrationDomain: this.domain, entityId: entity.id, deviceId: entity.deviceId, timestamp: Date.now() });
+      }
+      this.previousEntities = next;
     }
-    const qos = requestArg.data?.qos;
-    return {
-      topic,
-      payload: requestArg.data?.payload as IMqttPublishOptions['payload'],
-      qos: qos === 1 || qos === 2 ? qos : 0,
-      retain: requestArg.data?.retain === true,
-    };
+  }
+
+  private emit(eventArg: IIntegrationEvent): void {
+    for (const handler of this.handlers) handler(eventArg);
+  }
+
+  private publishOptionsFromRequest(requestArg: IServiceCallRequest): IMqttPublishOptions | undefined {
+    const data = requestArg.data;
+    if (typeof data?.topic !== 'string' || !data.topic) return undefined;
+    const qos = data.qos;
+    if (qos !== undefined && qos !== 0 && qos !== 1 && qos !== 2) return undefined;
+    if (data.retain !== undefined && typeof data.retain !== 'boolean') return undefined;
+    return { topic: data.topic, payload: data.payload as IMqttPublishOptions['payload'], qos: qos ?? 0, retain: data.retain === true };
   }
 }

package/ts/integrations/mqtt/mqtt.mapper.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../../plugins.js';
-import type { IIntegrationEntity, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
 import type { IMqttConfig, IMqttDeviceInfo, IMqttEntityConfig, IMqttMessage, IMqttPayload, IMqttPublishOptions, IMqttSnapshot } from './mqtt.types.js';
 
 const defaultDiscoveryPrefix = 'homeassistant';
@@ -11,7 +11,9 @@ const defaultPayloadNotAvailable = 'offline';
 const abbreviations: Record<string, string> = {
   avty: 'availability',
   avty_t: 'availability_topic',
+  avty_mode: 'availability_mode',
   cmd_t: 'command_topic',
+  cmd_tpl: 'command_template',
   cmps: 'components',
   def_ent_id: 'default_entity_id',
   dev: 'device',
@@ -60,10 +62,10 @@ const originAbbreviations: Record<string, string> = {
 
 export class MqttMapper {
   public static toSnapshot(configArg: IMqttConfig, connectedArg = false, receivedMessagesArg: IMqttMessage[] = []): IMqttSnapshot {
-    const messages = [...(configArg.retainedMessages || []), ...(configArg.discoveryMessages || []), ...receivedMessagesArg];
+    const messages = structuredClone([...new Map([...(configArg.retainedMessages || []), ...(configArg.discoveryMessages || []), ...receivedMessagesArg].map((messageArg) => [messageArg.topic, messageArg])).values()]);
     const entities = [
-      ...(configArg.entities || []),
-      ...this.entitiesFromDiscoveryMessages(configArg.discoveryMessages || [], configArg.discoveryPrefix || defaultDiscoveryPrefix),
+      ...structuredClone(configArg.entities || []),
+      ...(configArg.discovery === false ? [] : this.entitiesFromDiscoveryMessages(messages, configArg.discoveryPrefix || defaultDiscoveryPrefix)),
     ];
     return {
       brokerInfo: {
@@ -90,7 +92,7 @@ export class MqttMapper {
       protocol: 'mqtt',
       manufacturer: 'MQTT',
       model: 'Broker',
-      online: snapshotArg.brokerInfo.connected || Boolean(snapshotArg.messages.length || snapshotArg.entities.length),
+      online: snapshotArg.brokerInfo.connected,
       features: [
         { id: 'connection', capability: 'sensor', name: 'Connection', readable: true, writable: false },
         { id: 'discovery_prefix', capability: 'sensor', name: 'Discovery prefix', readable: true, writable: false },
@@ -110,10 +112,12 @@ export class MqttMapper {
       const deviceId = this.deviceIdForEntity(entity, snapshotArg);
       const existing = devices.get(deviceId);
       const feature = this.featureForEntity(entity);
-      const state = { featureId: feature.id, value: this.deviceStateValue(entity.state ?? null), updatedAt };
+      const state = { featureId: feature.id, value: this.deviceStateValue(this.canonicalState(entity)), updatedAt };
+      const online = this.entityAvailable(entity, snapshotArg);
       if (existing) {
         existing.features.push(feature);
         existing.state.push(state);
+        existing.online ||= online;
         continue;
       }
       devices.set(deviceId, {
@@ -123,7 +127,7 @@ export class MqttMapper {
         protocol: 'mqtt',
         manufacturer: entity.device?.manufacturer,
         model: entity.device?.model,
-        online: this.available(entity, snapshotArg.messages),
+        online,
         features: [feature],
         state: [state],
         metadata: {
@@ -142,8 +146,8 @@ export class MqttMapper {
 
   public static toEntities(snapshotArg: IMqttSnapshot): IIntegrationEntity[] {
     return snapshotArg.entities.map((entityArg) => ({
-      id: entityArg.defaultEntityId || `${this.toEntityPlatform(entityArg.platform)}.${this.slug(entityArg.name || entityArg.objectId || entityArg.uniqueId || 'mqtt')}`,
-      uniqueId: entityArg.uniqueId || `mqtt_${this.slug(entityArg.objectId || entityArg.name || entityArg.stateTopic || entityArg.commandTopic || 'entity')}`,
+      id: entityArg.defaultEntityId || `${this.toEntityPlatform(entityArg.platform)}.${this.slug(entityArg.uniqueId || entityArg.objectId || entityArg.name || 'mqtt')}`,
+      uniqueId: this.uniqueId(entityArg),
       integrationDomain: 'mqtt',
       deviceId: this.deviceIdForEntity(entityArg, snapshotArg),
       platform: this.toEntityPlatform(entityArg.platform),
@@ -159,35 +163,39 @@ export class MqttMapper {
         unit: entityArg.unitOfMeasurement,
         discoveryTopic: entityArg.discoveryTopic,
       },
-      available: this.available(entityArg, snapshotArg.messages),
+      available: this.entityAvailable(entityArg, snapshotArg),
     }));
   }
 
   public static commandForService(snapshotArg: IMqttSnapshot, requestArg: IServiceCallRequest): IMqttPublishOptions | undefined {
     const entity = this.findTargetEntity(snapshotArg, requestArg);
-    if (!entity?.commandTopic) {
+    if (entity && requestArg.target.deviceId && this.deviceIdForEntity(entity, snapshotArg) !== requestArg.target.deviceId) return undefined;
+    if (!entity?.commandTopic || requestArg.domain !== entity.platform || !this.controlSupported(entity) || !this.entityAvailable(entity, snapshotArg)) {
       return undefined;
     }
     const raw = entity.rawConfig || {};
     let payload: IMqttPayload | undefined;
-    if (requestArg.service === 'turn_on') {
+    if (requestArg.service === 'turn_on' && ['switch', 'light', 'fan'].includes(entity.platform)) {
       payload = entity.payloadOn || defaultPayloadOn;
-    } else if (requestArg.service === 'turn_off') {
+    } else if (requestArg.service === 'turn_off' && ['switch', 'light', 'fan'].includes(entity.platform)) {
       payload = entity.payloadOff || defaultPayloadOff;
-    } else if (requestArg.service === 'press') {
+    } else if (requestArg.service === 'press' && entity.platform === 'button') {
       payload = typeof raw.payload_press === 'string' ? raw.payload_press : 'PRESS';
-    } else if (requestArg.service === 'open_cover') {
+    } else if (requestArg.service === 'open_cover' && entity.platform === 'cover') {
       payload = typeof raw.payload_open === 'string' ? raw.payload_open : 'OPEN';
-    } else if (requestArg.service === 'close_cover') {
+    } else if (requestArg.service === 'close_cover' && entity.platform === 'cover') {
       payload = typeof raw.payload_close === 'string' ? raw.payload_close : 'CLOSE';
-    } else if (requestArg.service === 'stop_cover') {
+    } else if (requestArg.service === 'stop_cover' && entity.platform === 'cover') {
       payload = typeof raw.payload_stop === 'string' ? raw.payload_stop : 'STOP';
-    } else if (requestArg.service === 'set_value') {
-      payload = requestArg.data?.value as IMqttPayload;
-    } else if (requestArg.service === 'select_option') {
-      payload = requestArg.data?.option as IMqttPayload;
-    } else if (requestArg.service === 'set_temperature') {
-      payload = requestArg.data?.temperature as IMqttPayload;
+    } else if (requestArg.service === 'set_value' && (entity.platform === 'number' || entity.platform === 'text')) {
+      const value = requestArg.data?.value;
+      if (entity.platform === 'number' && typeof value === 'number' && Number.isFinite(value) &&
+        (typeof raw.min !== 'number' || value >= raw.min) && (typeof raw.max !== 'number' || value <= raw.max)) payload = value;
+      if (entity.platform === 'text' && typeof value === 'string' &&
+        (typeof raw.max !== 'number' || value.length <= raw.max) && (typeof raw.min !== 'number' || value.length >= raw.min)) payload = value;
+    } else if (requestArg.service === 'select_option' && entity.platform === 'select') {
+      const option = requestArg.data?.option;
+      if (typeof option === 'string' && Array.isArray(raw.options) && raw.options.includes(option)) payload = option;
     }
     if (payload === undefined) {
       return undefined;
@@ -200,9 +208,28 @@ export class MqttMapper {
     };
   }
 
+  public static commandForFeature(snapshotArg: IMqttSnapshot, requestArg: IDeviceFeatureWriteRequest): IMqttPublishOptions | undefined {
+    const entities = snapshotArg.entities.filter((entityArg) =>
+      this.deviceIdForEntity(entityArg, snapshotArg) === requestArg.device.id &&
+      this.featureForEntity(entityArg).id === requestArg.feature.id
+    );
+    if (entities.length !== 1) return undefined;
+    const entity = entities[0];
+    let service: string;
+    let data: Record<string, unknown> = {};
+    if (['switch', 'light', 'fan'].includes(entity.platform) && typeof requestArg.value === 'boolean') service = requestArg.value ? 'turn_on' : 'turn_off';
+    else if (entity.platform === 'button' && requestArg.value === 'press') service = 'press';
+    else if (entity.platform === 'cover' && ['open', 'close', 'stop'].includes(String(requestArg.value))) service = String(requestArg.value) + '_cover';
+    else if (entity.platform === 'number' || entity.platform === 'text') { service = 'set_value'; data = { value: requestArg.value }; }
+    else if (entity.platform === 'select') { service = 'select_option'; data = { option: requestArg.value }; }
+    else return undefined;
+    const mapped = this.toEntities(snapshotArg).find((entityArg) => entityArg.uniqueId === this.uniqueId(entity));
+    return mapped ? this.commandForService(snapshotArg, { domain: entity.platform, service, target: { entityId: mapped.id }, data }) : undefined;
+  }
+
   public static entitiesFromDiscoveryMessages(messagesArg: IMqttMessage[], prefixArg = defaultDiscoveryPrefix): IMqttEntityConfig[] {
     const entities: IMqttEntityConfig[] = [];
-    for (const message of messagesArg) {
+    for (const message of new Map(messagesArg.map((messageArg) => [messageArg.topic, messageArg])).values()) {
       const parsedTopic = this.parseDiscoveryTopic(message.topic, prefixArg);
       if (!parsedTopic || message.payload === '' || message.payload === null) {
         continue;
@@ -211,6 +238,7 @@ export class MqttMapper {
       if (!payload) {
         continue;
       }
+      if (payload.migrate_discovery === true) continue;
       this.replaceAllAbbreviations(payload);
       this.replaceTopicBase(payload);
       if (parsedTopic.component === 'device') {
@@ -218,11 +246,14 @@ export class MqttMapper {
         for (const [componentId, componentConfig] of Object.entries(components)) {
           const componentPayload = { ...payload, ...this.asRecord(componentConfig) };
           delete componentPayload.components;
-          entities.push(this.entityFromPayload(componentPayload, String(componentPayload.platform || 'sensor'), parsedTopic.objectId, parsedTopic.nodeId, message.topic, componentId));
+          this.replaceTopicBase(componentPayload);
+          const platform = componentPayload.platform;
+          if (typeof platform !== 'string' || !this.isPlatform(platform)) continue;
+          entities.push(this.entityFromPayload(componentPayload, platform, parsedTopic.objectId, parsedTopic.nodeId, message.topic, componentId));
         }
         continue;
       }
-      entities.push(this.entityFromPayload(payload, parsedTopic.component, parsedTopic.objectId, parsedTopic.nodeId, message.topic));
+      if (this.isPlatform(parsedTopic.component)) entities.push(this.entityFromPayload(payload, parsedTopic.component, parsedTopic.objectId, parsedTopic.nodeId, message.topic));
     }
     return entities;
   }
@@ -242,6 +273,13 @@ export class MqttMapper {
       stateTopic: this.stringValue(payloadArg.state_topic),
       commandTopic: this.stringValue(payloadArg.command_topic),
       availabilityTopic: this.stringValue(payloadArg.availability_topic),
+      availability: Array.isArray(payloadArg.availability) ? payloadArg.availability.flatMap((availabilityArg: unknown) => {
+        const availability = this.asRecord(availabilityArg);
+        this.replaceAbbreviations(availability, abbreviations);
+        const topic = this.stringValue(availability.topic);
+        return topic ? [{ topic, payloadAvailable: this.stringValue(availability.payload_available), payloadNotAvailable: this.stringValue(availability.payload_not_available) }] : [];
+      }) : undefined,
+      availabilityMode: payloadArg.availability_mode === 'all' || payloadArg.availability_mode === 'any' ? payloadArg.availability_mode : 'latest',
       jsonAttributesTopic: this.stringValue(payloadArg.json_attributes_topic),
       valueTemplate: this.stringValue(payloadArg.value_template),
       stateValueTemplate: this.stringValue(payloadArg.state_value_template),
@@ -271,15 +309,16 @@ export class MqttMapper {
   }
 
   private static parseDiscoveryTopic(topicArg: string, prefixArg: string): { component: string; nodeId?: string; objectId: string } | undefined {
-    const parts = topicArg.split('/').filter(Boolean);
-    if (parts[0] !== prefixArg || parts[parts.length - 1] !== 'config') {
+    if (!topicArg.startsWith(prefixArg + '/')) return undefined;
+    const parts = topicArg.slice(prefixArg.length + 1).split('/');
+    if (parts.some((partArg) => !partArg) || parts[parts.length - 1] !== 'config') {
       return undefined;
     }
-    if (parts.length === 4) {
-      return { component: parts[1], objectId: parts[2] };
+    if (parts.length === 3) {
+      return { component: parts[0], objectId: parts[1] };
     }
-    if (parts.length === 5) {
-      return { component: parts[1], nodeId: parts[2], objectId: parts[3] };
+    if (parts.length === 4) {
+      return { component: parts[0], nodeId: parts[1], objectId: parts[2] };
     }
     return undefined;
   }
@@ -288,12 +327,12 @@ export class MqttMapper {
     if (typeof payloadArg === 'string') {
       try {
         const parsed = JSON.parse(payloadArg) as unknown;
-        return this.asRecord(parsed);
+        return this.isRecord(parsed) ? structuredClone(parsed) : undefined;
       } catch {
         return undefined;
       }
     }
-    return this.asRecord(payloadArg);
+    return this.isRecord(payloadArg) ? structuredClone(payloadArg) : undefined;
   }
 
   private static replaceAllAbbreviations(payloadArg: Record<string, unknown>): void {
@@ -336,6 +375,15 @@ export class MqttMapper {
         payloadArg[key] = `${value.slice(0, -1)}${topicBase}`;
       }
     }
+    if (Array.isArray(payloadArg.availability)) {
+      for (const item of payloadArg.availability) {
+        if (!this.isRecord(item)) continue;
+        this.replaceAbbreviations(item, abbreviations);
+        const topic = this.stringValue(item.topic);
+        if (topic?.startsWith('~')) item.topic = topicBase + topic.slice(1);
+        else if (topic?.endsWith('~')) item.topic = topic.slice(0, -1) + topicBase;
+      }
+    }
   }
 
   private static deviceFromPayload(payloadArg: Record<string, unknown>): IMqttDeviceInfo | undefined {
@@ -369,15 +417,14 @@ export class MqttMapper {
   }
 
   private static latestMessage(messagesArg: IMqttMessage[], topicArg: string): IMqttMessage | undefined {
-    const matches = messagesArg.filter((messageArg) => messageArg.topic === topicArg);
-    return matches.sort((leftArg, rightArg) => (rightArg.timestamp || 0) - (leftArg.timestamp || 0))[0] || matches[matches.length - 1];
+    return messagesArg.findLast((messageArg) => messageArg.topic === topicArg);
   }
 
   private static renderValue(payloadArg: IMqttPayload, templateArg?: string): IMqttPayload {
     if (!templateArg) {
       return payloadArg;
     }
-    if (templateArg.includes('value_json')) {
+    if (/^\s*{{\s*value_json(?:\.[a-zA-Z0-9_]+|\[['"][^'"]+['"]\])\s*}}\s*$/.test(templateArg)) {
       const parsed = typeof payloadArg === 'string' ? this.safeJson(payloadArg) : payloadArg;
       const pathMatch = /value_json(?:\.([a-zA-Z0-9_]+)|\[['"]([^'"]+)['"]\])/.exec(templateArg);
       const key = pathMatch?.[1] || pathMatch?.[2];
@@ -385,10 +432,10 @@ export class MqttMapper {
         return parsed[key] as IMqttPayload;
       }
     }
-    if (templateArg.includes('value')) {
+    if (/^\s*{{\s*value\s*}}\s*$/.test(templateArg)) {
       return payloadArg;
     }
-    return payloadArg;
+    return null;
   }
 
   private static attributesPayload(payloadArg: IMqttPayload): Record<string, unknown> {
@@ -415,6 +462,19 @@ export class MqttMapper {
   }
 
   private static available(entityArg: IMqttEntityConfig, messagesArg: IMqttMessage[]): boolean {
+    if (entityArg.availability?.length) {
+      const availability = entityArg.availability;
+      const isAvailable = (indexArg: number): boolean => {
+        const item = availability[indexArg];
+        const message = this.latestMessage(messagesArg, item.topic);
+        return message?.payload === (item.payloadAvailable || defaultPayloadAvailable);
+      };
+      if (entityArg.availabilityMode === 'all') return availability.every((_, indexArg) => isAvailable(indexArg));
+      if (entityArg.availabilityMode === 'any') return availability.some((_, indexArg) => isAvailable(indexArg));
+      const latest = messagesArg.findLast((messageArg) => availability.some((itemArg) => itemArg.topic === messageArg.topic));
+      const index = availability.findIndex((itemArg) => itemArg.topic === latest?.topic);
+      return index >= 0 && isAvailable(index);
+    }
     if (!entityArg.availabilityTopic) {
       return true;
     }
@@ -425,6 +485,29 @@ export class MqttMapper {
     return availabilityMessage.payload !== (entityArg.payloadNotAvailable || defaultPayloadNotAvailable) && availabilityMessage.payload === (entityArg.payloadAvailable || defaultPayloadAvailable);
   }
 
+  private static entityAvailable(entityArg: IMqttEntityConfig, snapshotArg: IMqttSnapshot): boolean {
+    return (!snapshotArg.brokerInfo.host || snapshotArg.brokerInfo.connected) && this.available(entityArg, snapshotArg.messages);
+  }
+
+  private static canonicalState(entityArg: IMqttEntityConfig): IMqttPayload {
+    const state = this.entityState(entityArg);
+    if (['switch', 'light', 'fan', 'binary_sensor'].includes(entityArg.platform)) {
+      if (state === 'on' || state === (entityArg.payloadOn || defaultPayloadOn)) return true;
+      if (state === 'off' || state === (entityArg.payloadOff || defaultPayloadOff)) return false;
+    }
+    return state === 'unknown' ? null : state as IMqttPayload;
+  }
+
+  private static controlSupported(entityArg: IMqttEntityConfig): boolean {
+    const raw = entityArg.rawConfig || {};
+    return Boolean(entityArg.commandTopic) && !raw.command_template && (!raw.schema || raw.schema === 'default') &&
+      ['switch', 'light', 'fan', 'button', 'cover', 'number', 'select', 'text'].includes(entityArg.platform);
+  }
+
+  private static uniqueId(entityArg: IMqttEntityConfig): string {
+    return entityArg.uniqueId || 'mqtt_' + this.slug(entityArg.discoveryTopic || entityArg.objectId || entityArg.name || entityArg.stateTopic || entityArg.commandTopic || 'entity');
+  }
+
   private static featureForEntity(entityArg: IMqttEntityConfig): plugins.shxInterfaces.data.IDeviceFeature {
     const platform = this.toEntityPlatform(entityArg.platform);
     return {
@@ -432,7 +515,7 @@ export class MqttMapper {
       capability: this.capabilityForPlatform(platform),
       name: entityArg.name || entityArg.objectId || 'MQTT entity',
       readable: Boolean(entityArg.stateTopic),
-      writable: Boolean(entityArg.commandTopic),
+      writable: this.controlSupported(entityArg),
       unit: entityArg.unitOfMeasurement,
     };
   }
@@ -441,7 +524,9 @@ export class MqttMapper {
     if (platformArg === 'light') {
       return 'light';
     }
-    if (platformArg === 'switch' || platformArg === 'button' || platformArg === 'cover' || platformArg === 'select' || platformArg === 'number' || platformArg === 'text') {
+    if (platformArg === 'cover') return 'cover';
+    if (platformArg === 'vacuum') return 'vacuum';
+    if (platformArg === 'switch' || platformArg === 'button' || platformArg === 'select' || platformArg === 'number' || platformArg === 'text') {
       return 'switch';
     }
     if (platformArg === 'climate') {
@@ -457,20 +542,27 @@ export class MqttMapper {
   }
 
   private static toEntityPlatform(platformArg: string): TEntityPlatform {
-    const allowed: TEntityPlatform[] = ['light', 'switch', 'sensor', 'binary_sensor', 'button', 'climate', 'cover', 'fan', 'media_player', 'number', 'select', 'text', 'update'];
-    return allowed.includes(platformArg as TEntityPlatform) ? platformArg as TEntityPlatform : 'sensor';
+    if (!this.isPlatform(platformArg)) throw new Error('Unsupported MQTT entity platform: ' + platformArg);
+    return platformArg;
+  }
+
+  private static isPlatform(platformArg: string): platformArg is TEntityPlatform {
+    return ['light', 'switch', 'sensor', 'binary_sensor', 'button', 'camera', 'climate', 'cover', 'fan', 'media_player', 'number', 'select', 'text', 'update', 'vacuum'].includes(platformArg);
   }
 
   private static findTargetEntity(snapshotArg: IMqttSnapshot, requestArg: IServiceCallRequest): IMqttEntityConfig | undefined {
     if (requestArg.target.entityId) {
       const entities = this.toEntities(snapshotArg);
-      const entity = entities.find((entityArg) => entityArg.id === requestArg.target.entityId || entityArg.uniqueId === requestArg.target.entityId);
-      return entity ? snapshotArg.entities.find((entityArg) => (entityArg.uniqueId || `mqtt_${this.slug(entityArg.objectId || entityArg.name || entityArg.stateTopic || entityArg.commandTopic || 'entity')}`) === entity.uniqueId) : undefined;
+      const matched = entities.filter((entityArg) => entityArg.id === requestArg.target.entityId || entityArg.uniqueId === requestArg.target.entityId);
+      if (matched.length !== 1) return undefined;
+      const configs = snapshotArg.entities.filter((entityArg) => this.uniqueId(entityArg) === matched[0].uniqueId);
+      return configs.length === 1 ? configs[0] : undefined;
     }
     if (requestArg.target.deviceId) {
-      return snapshotArg.entities.find((entityArg) => this.deviceIdForEntity(entityArg, snapshotArg) === requestArg.target.deviceId && entityArg.commandTopic);
+      const matched = snapshotArg.entities.filter((entityArg) => this.deviceIdForEntity(entityArg, snapshotArg) === requestArg.target.deviceId && entityArg.commandTopic && entityArg.platform === requestArg.domain);
+      return matched.length === 1 ? matched[0] : undefined;
     }
-    return snapshotArg.entities.find((entityArg) => entityArg.commandTopic);
+    return undefined;
   }
 
   private static deviceIdForEntity(entityArg: IMqttEntityConfig, snapshotArg: IMqttSnapshot): string {