homebridge-tuya-plus 3.14.0-dev.5 → 3.14.0-dev.52

package/index.js

@@ -1,358 +1,599 @@
-const TuyaAccessory = require('./lib/TuyaAccessory');
-const TuyaDiscovery = require('./lib/TuyaDiscovery');
-const TuyaCloudApi = require('./lib/TuyaCloudApi');
-const TuyaCloudDevice = require('./lib/TuyaCloudDevice');
-const TuyaCloudMessaging = require('./lib/TuyaCloudMessaging');
-
-const OutletAccessory = require('./lib/OutletAccessory');
-const SimpleLightAccessory = require('./lib/SimpleLightAccessory');
-const MultiOutletAccessory = require('./lib/MultiOutletAccessory');
-const CustomMultiOutletAccessory = require('./lib/CustomMultiOutletAccessory');
-const RGBTWLightAccessory = require('./lib/RGBTWLightAccessory');
-const RGBTWOutletAccessory = require('./lib/RGBTWOutletAccessory');
-const TWLightAccessory = require('./lib/TWLightAccessory');
-const AirConditionerAccessory = require('./lib/AirConditionerAccessory');
-const AirPurifierAccessory = require('./lib/AirPurifierAccessory');
-const DehumidifierAccessory = require('./lib/DehumidifierAccessory');
-const ConvectorAccessory = require('./lib/ConvectorAccessory');
-const GarageDoorAccessory = require('./lib/GarageDoorAccessory');
-const SimpleGarageDoorAccessory = require('./lib/SimpleGarageDoorAccessory');
-const WledDimmerAccessory = require('./lib/WledDimmerAccessory');
-const SimpleDimmer2Accessory = require('./lib/SimpleDimmer2Accessory');
-const SimpleBlindsAccessory = require('./lib/SimpleBlindsAccessory');
-const SimpleHeaterAccessory = require('./lib/SimpleHeaterAccessory');
-const SimpleFanAccessory = require('./lib/SimpleFanAccessory');
-const SimpleFanLightAccessory = require('./lib/SimpleFanLightAccessory');
-const SwitchAccessory = require('./lib/SwitchAccessory');
-const ValveAccessory = require('./lib/ValveAccessory');
-const IrrigationSystemAccessory = require('./lib/IrrigationSystemAccessory');
-const OilDiffuserAccessory = require('./lib/OilDiffuserAccessory');
-const DoorbellAccessory = require('./lib/DoorbellAccessory');
-const VerticalBlindsWithTilt = require('./lib/VerticalBlindsWithTilt');
-const PercentBlindsAccessory = require('./lib/PercentBlindsAccessory');
-
-const PLUGIN_NAME = 'homebridge-tuya-plus';
-const PLATFORM_NAME = 'TuyaLan';
-// Seed used to derive accessory UUIDs. Must remain 'homebridge-tuya' so that
-// devices already paired with HomeKit keep their existing identity (names,
-// rooms, automations).
-const UUID_SEED = 'homebridge-tuya';
-const DEFAULT_DISCOVER_TIMEOUT = 60000;
-
-// Lenient boolean coercion (matches BaseAccessory._coerceBoolean) so config
-// values like true / "true" / 1 all read as true.
-const coerceBoolean = (b, df = false) =>
-    typeof b === 'boolean' ? b :
-    typeof b === 'string' ? b.toLowerCase().trim() === 'true' :
-    typeof b === 'number' ? b !== 0 : df;
-
-const CLASS_DEF = {
-    outlet: OutletAccessory,
-    simplelight: SimpleLightAccessory,
-    rgbtwlight: RGBTWLightAccessory,
-    rgbtwoutlet: RGBTWOutletAccessory,
-    twlight: TWLightAccessory,
-    multioutlet: MultiOutletAccessory,
-    custommultioutlet: CustomMultiOutletAccessory,
-    airconditioner: AirConditionerAccessory,
-    airpurifier: AirPurifierAccessory,
-    dehumidifier: DehumidifierAccessory,
-    convector: ConvectorAccessory,
-    garagedoor: GarageDoorAccessory,
-    simplegaragedoor: SimpleGarageDoorAccessory,
-    simpledimmer: WledDimmerAccessory,
-    wleddimmer: WledDimmerAccessory,
-    simpledimmer2: SimpleDimmer2Accessory,
-    simpleblinds: SimpleBlindsAccessory,
-    simpleheater: SimpleHeaterAccessory,
-    switch: SwitchAccessory,
-    fan: SimpleFanAccessory,
-    fanlight: SimpleFanLightAccessory,
-    watervalve: ValveAccessory,
-    irrigationsystem: IrrigationSystemAccessory,
-    oildiffuser: OilDiffuserAccessory,
-    doorbell: DoorbellAccessory,
-    verticalblindswithtilt: VerticalBlindsWithTilt,
-    percentblinds: PercentBlindsAccessory
-};
-
-let Characteristic, Formats, Perms, Categories, PlatformAccessory, Service, AdaptiveLightingController, UUID;
-
-module.exports = function(homebridge) {
-    ({
-        platformAccessory: PlatformAccessory,
-        hap: {Characteristic, Formats, Perms, Categories, Service, AdaptiveLightingController, uuid: UUID}
-    } = homebridge);
-
-    homebridge.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, TuyaLan, true);
-};
-
-class TuyaLan {
-    constructor(...props) {
-        [this.log, this.config, this.api] = [...props];
-
-        this.cachedAccessories = new Map();
-        // Shared Tuya Cloud clients, keyed by credential set, so several
-        // cloud devices on the same project share one token + one realtime
-        // (MQTT) connection. Empty unless cloud devices are configured.
-        this.cloudApis = new Map();
-        this.cloudMessagers = new Map();
-        this.api.hap.EnergyCharacteristics = require('./lib/EnergyCharacteristics')(this.api.hap);
-
-        if(!this.config || !this.config.devices) {
-            this.log("No devices found. Check that you have specified them in your config.json file.");
-            return false;
-        }
-
-        this._expectedUUIDs = this.config.devices.map(device => UUID.generate(UUID_SEED +(device.fake ? ':fake:' : ':') + device.id));
-
-        this.api.on('didFinishLaunching', () => {
-            this.discoverDevices();
-        });
-    }
-
-    discoverDevices() {
-        const devices = {};
-        const connectedDevices = [];
-        const fakeDevices = [];
-        const cloudDevices = [];
-        this.config.devices.forEach(device => {
-            try {
-                device.id = ('' + device.id).trim();
-                // Cloud devices don't need a local key; only trim when present.
-                if (device.key != null) device.key = ('' + device.key).trim();
-                device.type = ('' + device.type).trim();
-
-                device.ip = ('' + (device.ip || '')).trim();
-            } catch(ex) {}
-
-            if (!device.type) return this.log.error('%s (%s) doesn\'t have a type defined.', device.name || 'Unnamed device', device.id);
-            if (!CLASS_DEF[device.type.toLowerCase()]) return this.log.error('%s (%s) doesn\'t have a valid type defined.', device.name || 'Unnamed device', device.id);
-
-            if (this._isCloudDevice(device)) cloudDevices.push({name: device.id.slice(8), ...device});
-            else if (device.fake) fakeDevices.push({name: device.id.slice(8), ...device});
-            else devices[device.id] = {name: device.id.slice(8), ...device};
-        });
-
-        // Cloud devices are reached over the internet, not the LAN, so they need
-        // no discovery — wire them up right away.
-        cloudDevices.forEach(config => this._addCloudAccessory(config));
-
-        const deviceIds = Object.keys(devices);
-        if (deviceIds.length === 0) {
-            if (cloudDevices.length === 0) this.log.error('No valid configured devices found.');
-            return; // cloud-only (or empty) configuration: nothing to discover over LAN
-        }
-
-        this.log.info('Starting discovery...');
-
-        TuyaDiscovery.start({ids: deviceIds, log: this.log})
-            .on('discover', config => {
-                if (!config || !config.id) return;
-                if (!devices[config.id]) return this.log.warn('Discovered a device that has not been configured yet (%s@%s).', config.id, config.ip);
-
-                connectedDevices.push(config.id);
-
-                this.log.info('Discovered %s (%s) identified as %s (%s)', devices[config.id].name, config.id, devices[config.id].type, config.version);
-
-                // The version broadcast by the device wins over a configured `version`,
-                // but `forceVersion` overrides everything (e.g. to pin a device that
-                // reports a newer protocol, like 3.6, to a specific stack).
-                const device = new TuyaAccessory({
-                    ...devices[config.id], ...config,
-                    ...(devices[config.id].forceVersion ? {version: devices[config.id].forceVersion} : {}),
-                    log: this.log,
-                    UUID: UUID.generate(UUID_SEED + ':' + config.id),
-                    connect: false
-                });
-                this.addAccessory(device);
-            });
-
-        fakeDevices.forEach(config => {
-            this.log.info('Adding fake device: %s', config.name);
-            this.addAccessory(new TuyaAccessory({
-                ...config,
-                log: this.log,
-                UUID: UUID.generate(UUID_SEED + ':fake:' + config.id),
-                connect: false
-            }));
-        });
-
-        setTimeout(() => {
-            deviceIds.forEach(deviceId => {
-                if (connectedDevices.includes(deviceId)) return;
-
-                if (devices[deviceId].ip) {
-
-                    this.log.info('Failed to discover %s (%s) in time but will connect via %s.', devices[deviceId].name, deviceId, devices[deviceId].ip);
-
-                    const device = new TuyaAccessory({
-                        ...devices[deviceId],
-                        ...(devices[deviceId].forceVersion ? {version: devices[deviceId].forceVersion} : {}),
-                        log: this.log,
-                        UUID: UUID.generate(UUID_SEED + ':' + deviceId),
-                        connect: false
-                    });
-                    this.addAccessory(device);
-                } else {
-                    this.log.warn('Failed to discover %s (%s) in time but will keep looking.', devices[deviceId].name, deviceId);
-                }
-            });
-        }, this.config.discoverTimeout ?? DEFAULT_DISCOVER_TIMEOUT);
-    }
-
-    /* ------------------------------------------------------------------ *
-     *  Tuya Cloud helpers (for devices that can't be reached over the LAN,
-     *  e.g. battery-powered "sleepy" irrigation timers). This plugin stays
-     *  LAN-first; these paths are only exercised by devices opting in with
-     *  `cloud: true` (or a per-device `cloud` credentials object).
-     * ------------------------------------------------------------------ */
-
-    _isCloudDevice(device) {
-        return !!(device && (device.cloud === true || (typeof device.cloud === 'object' && device.cloud)));
-    }
-
-    // Effective cloud credentials/options for a device: the platform-level
-    // `cloud` block, overlaid with any per-device `cloud` object.
-    _resolveCloudConfig(device) {
-        const platform = (this.config.cloud && typeof this.config.cloud === 'object') ? this.config.cloud : {};
-        const perDevice = (typeof device.cloud === 'object' && device.cloud) ? device.cloud : {};
-        return {...platform, ...perDevice};
-    }
-
-    // One TuyaCloudApi per credential set, so multiple cloud devices on the
-    // same Tuya project share a single token.
-    _getCloudApi(cloudCfg) {
-        const key = TuyaCloudApi.keyFor(cloudCfg);
-        if (!this.cloudApis.has(key)) {
-            this.cloudApis.set(key, new TuyaCloudApi({...cloudCfg, log: this.log}));
-        }
-        return this.cloudApis.get(key);
-    }
-
-    // One shared realtime (MQTT) stream per credential set, unless realtime is
-    // disabled. Returns null when realtime is off — the device then shows its
-    // initial state and stays controllable, but won't receive live updates.
-    _getCloudMessaging(api, cloudCfg) {
-        const realtime = cloudCfg.realtime === undefined ? true : coerceBoolean(cloudCfg.realtime, true);
-        if (!realtime) return null;
-        const key = TuyaCloudApi.keyFor(cloudCfg);
-        if (!this.cloudMessagers.has(key)) {
-            this.cloudMessagers.set(key, new TuyaCloudMessaging({api, log: this.log}));
-        }
-        return this.cloudMessagers.get(key);
-    }
-
-    _addCloudAccessory(config) {
-        const cloudCfg = this._resolveCloudConfig(config);
-        if (!cloudCfg.accessId || !cloudCfg.accessKey) {
-            return this.log.error('%s (%s) is configured for the Tuya Cloud, but no credentials were found. Add a top-level "cloud" block (accessId, accessKey, region) or a per-device "cloud" object.', config.name, config.id);
-        }
-
-        const api = this._getCloudApi(cloudCfg);
-        const messaging = this._getCloudMessaging(api, cloudCfg);
-
-        this.log.info('Adding cloud device: %s (%s) via %s', config.name, config.id, api.endpoint);
-
-        this.addAccessory(new TuyaCloudDevice({
-            ...config,
-            cloud: true, // normalise so accessories can detect cloud mode
-            cloudApi: api,
-            messaging,
-            log: this.log,
-            UUID: UUID.generate(UUID_SEED + ':' + config.id),
-            connect: false
-        }));
-    }
-
-    registerPlatformAccessories(platformAccessories) {
-        this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, Array.isArray(platformAccessories) ? platformAccessories : [platformAccessories]);
-    }
-
-    configureAccessory(accessory) {
-        // also checks null objects or empty config - this._expectedUUIDs
-        if (accessory instanceof PlatformAccessory && this._expectedUUIDs && this._expectedUUIDs.includes(accessory.UUID)) {
-            this.cachedAccessories.set(accessory.UUID, accessory);
-            accessory.services.forEach(service => {
-                if (service.UUID === Service.AccessoryInformation.UUID) return;
-                service.characteristics.some(characteristic => {
-                    if (!characteristic.props ||
-                        !Array.isArray(characteristic.props.perms) ||
-                        characteristic.props.perms.length !== 3 ||
-                        !(characteristic.props.perms.includes(Perms.WRITE) && characteristic.props.perms.includes(Perms.NOTIFY))
-                    ) return;
-
-                    this.log.info('Marked %s unreachable by faulting Service.%s.%s', accessory.displayName, service.displayName, characteristic.displayName);
-
-                    characteristic.updateValue(new Error('Unreachable'));
-                    return true;
-                });
-            });
-        } else {
-            /*
-             * Irrespective of this unregistering, Homebridge continues
-             * to "_prepareAssociatedHAPAccessory" and "addBridgedAccessory".
-             * This timeout will hopefully remove the accessory after that has happened.
-             */
-            setTimeout(() => {
-                this.removeAccessory(accessory);
-            }, 1000);
-        }
-    }
-
-    addAccessory(device) {
-        const deviceConfig = device.context;
-        const type = (deviceConfig.type || '').toLowerCase();
-
-        const Accessory = CLASS_DEF[type];
-
-        let accessory = this.cachedAccessories.get(deviceConfig.UUID),
-            isCached = true;
-
-        const expectedCategory = Accessory.getCategory(Categories);
-
-        // Only treat a cached accessory as a "different type" when we actually
-        // have a category to compare against. If getCategory() resolves to
-        // undefined (e.g. an unknown HAP category constant), HomeKit stores the
-        // accessory as Categories.OTHER, so an undefined expectation would never
-        // match and we would needlessly unregister & recreate the accessory on
-        // every restart — wiping its HomeKit identity (name, room, automations).
-        if (accessory && expectedCategory !== undefined && accessory.category !== expectedCategory) {
-            this.log.info("%s has a different type (%s vs %s)", accessory.displayName, accessory.category, expectedCategory);
-            this.removeAccessory(accessory);
-            accessory = null;
-        }
-
-        if (!accessory) {
-            accessory = new PlatformAccessory(deviceConfig.name, deviceConfig.UUID, expectedCategory);
-            accessory.getService(Service.AccessoryInformation)
-                .setCharacteristic(Characteristic.Manufacturer, deviceConfig.manufacturer || "Unknown")
-                .setCharacteristic(Characteristic.Model, deviceConfig.model || "Unknown")
-                .setCharacteristic(Characteristic.SerialNumber, deviceConfig.id.slice(8));
-
-            isCached = false;
-        }
-
-        if (accessory && accessory.displayName !== deviceConfig.name) {
-            this.log.info(
-                "Configuration name %s differs from cached displayName %s. Updating cached displayName to %s ",
-                deviceConfig.name, accessory.displayName, deviceConfig.name);
-            accessory.displayName = deviceConfig.name;
-        }
-
-        this.cachedAccessories.set(deviceConfig.UUID, new Accessory(this, accessory, device, !isCached));
-    }
-
-    removeAccessory(homebridgeAccessory) {
-        if (!homebridgeAccessory) return;
-
-        this.log.warn('Unregistering', homebridgeAccessory.displayName);
-
-        delete this.cachedAccessories[homebridgeAccessory.UUID];
-        this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [homebridgeAccessory]);
-    }
-
-    removeAccessoryByUUID(uuid) {
-        if (uuid) this.removeAccessory(this.cachedAccessories.get(uuid));
-    }
-}
+const TuyaAccessory = require('./lib/TuyaAccessory');
+const TuyaDevice = require('./lib/TuyaDevice');
+const TuyaDiscovery = require('./lib/TuyaDiscovery');
+const TuyaCloudApi = require('./lib/TuyaCloudApi');
+const TuyaCloudMessaging = require('./lib/TuyaCloudMessaging');
+
+const OutletAccessory = require('./lib/OutletAccessory');
+const SimpleLightAccessory = require('./lib/SimpleLightAccessory');
+const MultiOutletAccessory = require('./lib/MultiOutletAccessory');
+const CustomMultiOutletAccessory = require('./lib/CustomMultiOutletAccessory');
+const RGBTWLightAccessory = require('./lib/RGBTWLightAccessory');
+const RGBTWOutletAccessory = require('./lib/RGBTWOutletAccessory');
+const TWLightAccessory = require('./lib/TWLightAccessory');
+const AirConditionerAccessory = require('./lib/AirConditionerAccessory');
+const AirPurifierAccessory = require('./lib/AirPurifierAccessory');
+const DehumidifierAccessory = require('./lib/DehumidifierAccessory');
+const ConvectorAccessory = require('./lib/ConvectorAccessory');
+const GarageDoorAccessory = require('./lib/GarageDoorAccessory');
+const SimpleGarageDoorAccessory = require('./lib/SimpleGarageDoorAccessory');
+const WledDimmerAccessory = require('./lib/WledDimmerAccessory');
+const SimpleDimmerAccessory = require('./lib/SimpleDimmerAccessory');
+const SimpleDimmer2Accessory = require('./lib/SimpleDimmer2Accessory');
+const SimpleBlindsAccessory = require('./lib/SimpleBlindsAccessory');
+const SimpleHeaterAccessory = require('./lib/SimpleHeaterAccessory');
+const SimpleFanAccessory = require('./lib/SimpleFanAccessory');
+const SimpleFanLightAccessory = require('./lib/SimpleFanLightAccessory');
+const SwitchAccessory = require('./lib/SwitchAccessory');
+const ValveAccessory = require('./lib/ValveAccessory');
+const IrrigationSystemAccessory = require('./lib/IrrigationSystemAccessory');
+const OilDiffuserAccessory = require('./lib/OilDiffuserAccessory');
+const DoorbellAccessory = require('./lib/DoorbellAccessory');
+const VerticalBlindsWithTilt = require('./lib/VerticalBlindsWithTilt');
+const PercentBlindsAccessory = require('./lib/PercentBlindsAccessory');
+
+const PLUGIN_NAME = 'homebridge-tuya-plus';
+const PLATFORM_NAME = 'TuyaLan';
+// Seed used to derive accessory UUIDs. Must remain 'homebridge-tuya' so that
+// devices already paired with HomeKit keep their existing identity (names,
+// rooms, automations).
+const UUID_SEED = 'homebridge-tuya';
+const DEFAULT_DISCOVER_TIMEOUT = 60000;
+
+const CLASS_DEF = {
+  outlet: OutletAccessory,
+  simplelight: SimpleLightAccessory,
+  rgbtwlight: RGBTWLightAccessory,
+  rgbtwoutlet: RGBTWOutletAccessory,
+  twlight: TWLightAccessory,
+  multioutlet: MultiOutletAccessory,
+  custommultioutlet: CustomMultiOutletAccessory,
+  airconditioner: AirConditionerAccessory,
+  airpurifier: AirPurifierAccessory,
+  dehumidifier: DehumidifierAccessory,
+  convector: ConvectorAccessory,
+  garagedoor: GarageDoorAccessory,
+  simplegaragedoor: SimpleGarageDoorAccessory,
+  simpledimmer: SimpleDimmerAccessory,
+  wleddimmer: WledDimmerAccessory,
+  simpledimmer2: SimpleDimmer2Accessory,
+  simpleblinds: SimpleBlindsAccessory,
+  simpleheater: SimpleHeaterAccessory,
+  switch: SwitchAccessory,
+  fan: SimpleFanAccessory,
+  fanlight: SimpleFanLightAccessory,
+  watervalve: ValveAccessory,
+  irrigationsystem: IrrigationSystemAccessory,
+  oildiffuser: OilDiffuserAccessory,
+  doorbell: DoorbellAccessory,
+  verticalblindswithtilt: VerticalBlindsWithTilt,
+  percentblinds: PercentBlindsAccessory,
+};
+
+let Characteristic,
+  Formats,
+  Perms,
+  Categories,
+  PlatformAccessory,
+  Service,
+  AdaptiveLightingController,
+  UUID;
+
+// Lenient boolean coercion for platform-level config flags, mirroring
+// BaseAccessory._coerceBoolean so the same true / 'true' / 1 spellings users
+// already use on device options are accepted on top-level options too.
+function coerceBoolean(value, defaultValue) {
+  const df = defaultValue || false;
+  return typeof value === 'boolean'
+    ? value
+    : typeof value === 'string'
+      ? value.toLowerCase().trim() === 'true'
+      : typeof value === 'number'
+        ? value !== 0
+        : df;
+}
+
+module.exports = function (homebridge) {
+  ({
+    platformAccessory: PlatformAccessory,
+    hap: {
+      Characteristic,
+      Formats,
+      Perms,
+      Categories,
+      Service,
+      AdaptiveLightingController,
+      uuid: UUID,
+    },
+  } = homebridge);
+
+  homebridge.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, TuyaLan, true);
+};
+
+class TuyaLan {
+  constructor(...props) {
+    [this.log, this.config, this.api] = [...props];
+
+    this.cachedAccessories = new Map();
+    // One TuyaDevice per configured device, keyed by Tuya id, so discovery can
+    // hand each its LAN target once it's found on the network.
+    this.tuyaDevices = new Map();
+    // A SINGLE shared Tuya Cloud session (OpenAPI token + realtime MQTT) for the
+    // whole platform — the global fallback every device can lean on. Stays null
+    // unless cloud credentials are configured.
+    this.cloudApi = null;
+    this.cloudMessaging = null;
+    this.api.hap.EnergyCharacteristics = require('./lib/EnergyCharacteristics')(
+      this.api.hap,
+    );
+
+    if (!this.config || !this.config.devices) {
+      this.log(
+        'No devices found. Check that you have specified them in your config.json file.',
+      );
+      return false;
+    }
+
+    this._expectedUUIDs = this.config.devices.map((device) =>
+      UUID.generate(UUID_SEED + (device.fake ? ':fake:' : ':') + device.id),
+    );
+
+    this.api.on('didFinishLaunching', () => {
+      this.discoverDevices();
+    });
+  }
+
+  discoverDevices() {
+    // Bring up the single shared cloud session first, so every device that opts
+    // into (or falls back to) the cloud shares one token and one MQTT stream.
+    this._setupCloudSession();
+
+    const lanDeviceIds = []; // ids we still want to find on the LAN
+    const connectedDevices = []; // ids discovered on the LAN
+    const fakeDevices = [];
+    const seenUUIDs = new Set(); // accessory UUIDs already configured this run
+
+    this.config.devices.forEach((device) => {
+      try {
+        device.id = ('' + device.id).trim();
+        // Cloud-only devices don't need a local key; only trim when present.
+        if (device.key != null) device.key = ('' + device.key).trim();
+        device.type = ('' + device.type).trim();
+
+        device.ip = ('' + (device.ip || '')).trim();
+      } catch (ex) {}
+
+      if (!device.type)
+        return this.log.error(
+          "%s (%s) doesn't have a type defined.",
+          device.name || 'Unnamed device',
+          device.id,
+        );
+      if (!CLASS_DEF[device.type.toLowerCase()])
+        return this.log.error(
+          "%s (%s) doesn't have a valid type defined.",
+          device.name || 'Unnamed device',
+          device.id,
+        );
+
+      // Two config entries that resolve to the same accessory UUID (the same
+      // Tuya id, real or fake) make addAccessory process that UUID twice. The
+      // second pass reads back the accessory wrapper the first pass cached
+      // instead of a PlatformAccessory and crashes the child bridge while
+      // trying to unregister it. Keep the first entry; skip the rest.
+      const uuid = UUID.generate(
+        UUID_SEED + (device.fake ? ':fake:' : ':') + device.id,
+      );
+      if (seenUUIDs.has(uuid))
+        return this.log.warn(
+          '%s (%s) is configured more than once; ignoring the duplicate entry.',
+          device.name || 'Unnamed device',
+          device.id,
+        );
+      seenUUIDs.add(uuid);
+
+      if (device.fake) {
+        fakeDevices.push({ name: device.id.slice(8), ...device });
+        return;
+      }
+
+      const tuyaDevice = this._createDevice({
+        name: device.id.slice(8),
+        ...device,
+      });
+      this.tuyaDevices.set(device.id, tuyaDevice);
+      this.addAccessory(tuyaDevice);
+
+      // A device with a local key can be reached on the LAN, so it wants
+      // discovery; the cloud, when configured, is its fallback. A device with
+      // no key is cloud-only (e.g. a battery-powered "sleepy" unit) and relies
+      // on the cloud session to be reachable at all.
+      if (device.key) lanDeviceIds.push(device.id);
+      else if (!this.cloudApi)
+        this.log.error(
+          '%s (%s) has no local key and no Tuya Cloud session is configured, so it can\'t be reached. Add a key for LAN control, or a top-level "cloud" block.',
+          tuyaDevice.context.name,
+          device.id,
+        );
+    });
+
+    fakeDevices.forEach((config) => {
+      this.log.info('Adding fake device: %s', config.name);
+      this.addAccessory(
+        new TuyaAccessory({
+          ...config,
+          log: this.log,
+          UUID: UUID.generate(UUID_SEED + ':fake:' + config.id),
+          connect: false,
+        }),
+      );
+    });
+
+    if (lanDeviceIds.length === 0) {
+      if (this.tuyaDevices.size === 0 && fakeDevices.length === 0)
+        this.log.error('No valid configured devices found.');
+      return; // cloud-only (or empty) configuration: nothing to discover over the LAN
+    }
+
+    // Debug switch: pretend LAN discovery fails for every device so the whole
+    // platform runs over the Tuya Cloud fallback — a way to exercise the cloud
+    // path end-to-end without taking devices off the LAN. We simply never start
+    // discovery (and never attach a LAN backend), leaving the cloud session each
+    // device was already wired with as its only transport. Useless without a
+    // configured cloud session — the affected devices then have no transport at
+    // all, so say so per device rather than failing silently.
+    if (coerceBoolean(this._debugConfig().forceCloudFallback)) {
+      this.log.warn(
+        'debug.forceCloudFallback is set: skipping LAN discovery; every device is forced onto the Tuya Cloud fallback.',
+      );
+      lanDeviceIds.forEach((deviceId) => {
+        const tuyaDevice = this.tuyaDevices.get(deviceId);
+        if (!tuyaDevice) return;
+        if (tuyaDevice.cloud) {
+          this.log.info(
+            'Forcing %s (%s) onto the Tuya Cloud fallback (debug.forceCloudFallback).',
+            tuyaDevice.context.name,
+            deviceId,
+          );
+        } else {
+          this.log.error(
+            'debug.forceCloudFallback is set but %s (%s) has no Tuya Cloud session, so it can\'t be reached.',
+            tuyaDevice.context.name,
+            deviceId,
+          );
+        }
+      });
+      return;
+    }
+
+    this.log.info('Starting discovery...');
+
+    TuyaDiscovery.start({ ids: lanDeviceIds, log: this.log }).on(
+      'discover',
+      (config) => {
+        if (!config || !config.id) return;
+        const tuyaDevice = this.tuyaDevices.get(config.id);
+        if (!tuyaDevice) return this._warnUnconfiguredDevice(config);
+        if (connectedDevices.includes(config.id)) return;
+
+        connectedDevices.push(config.id);
+
+        this.log.info(
+          'Discovered %s (%s) identified as %s (%s)',
+          tuyaDevice.context.name,
+          config.id,
+          tuyaDevice.context.type,
+          config.version,
+        );
+
+        // The version broadcast by the device wins over a configured `version`,
+        // but `forceVersion` overrides everything; attachLan applies that order.
+        tuyaDevice.attachLan({ ip: config.ip, version: config.version });
+      },
+    );
+
+    setTimeout(() => {
+      lanDeviceIds.forEach((deviceId) => {
+        if (connectedDevices.includes(deviceId)) return;
+
+        const tuyaDevice = this.tuyaDevices.get(deviceId);
+        if (!tuyaDevice) return;
+
+        if (tuyaDevice.context.ip) {
+          this.log.info(
+            'Failed to discover %s (%s) in time but will connect via %s.',
+            tuyaDevice.context.name,
+            deviceId,
+            tuyaDevice.context.ip,
+          );
+          tuyaDevice.attachLan({ ip: tuyaDevice.context.ip });
+        } else if (tuyaDevice.cloud) {
+          this.log.info(
+            'Failed to discover %s (%s) on the LAN; it will run over the Tuya Cloud fallback.',
+            tuyaDevice.context.name,
+            deviceId,
+          );
+        } else {
+          this.log.warn(
+            'Failed to discover %s (%s) in time but will keep looking.',
+            tuyaDevice.context.name,
+            deviceId,
+          );
+        }
+      });
+    }, this.config.discoverTimeout ?? DEFAULT_DISCOVER_TIMEOUT);
+  }
+
+  // The undocumented top-level `debug` block holds switches that only matter
+  // when developing or testing the plugin (e.g. forcing the Tuya Cloud path).
+  // It is intentionally absent from config.schema.json so it never surfaces in
+  // the Homebridge UI. Always returns an object so callers can read a flag
+  // without first guarding for the block's presence.
+  _debugConfig() {
+    return this.config.debug && typeof this.config.debug === 'object'
+      ? this.config.debug
+      : {};
+  }
+
+  // A device showed up on the LAN that isn't in the user's config. When the
+  // optional cloud session is available we look the device up there first, so
+  // the warning can name it (and hint at its product/category) and the user
+  // can tell which physical device still needs configuring — far more useful
+  // than a bare id@ip. If there's no cloud session, or the lookup fails (the
+  // device belongs to another account, the device-management API isn't
+  // authorised, the network is down, …), fall back to the plain warning.
+  // Never throws: enrichment is best-effort and must not disrupt discovery.
+  async _warnUnconfiguredDevice(config) {
+    const bareWarning = () =>
+      this.log.warn(
+        'Discovered a device that has not been configured yet (%s@%s).',
+        config.id,
+        config.ip,
+      );
+
+    if (!this.cloudApi) return bareWarning();
+
+    let info;
+    try {
+      info = await this.cloudApi.getDeviceInfo(config.id);
+    } catch (ex) {
+      this.log.debug(
+        'Tuya Cloud lookup for unconfigured device %s failed: %s',
+        config.id,
+        ex.message,
+      );
+    }
+    if (!info || !info.name) return bareWarning();
+
+    const details = [];
+    if (info.product_name) details.push(info.product_name);
+    if (info.category) details.push(`category ${info.category}`);
+
+    this.log.warn(
+      'Discovered a device that has not been configured yet: %s%s (%s@%s).',
+      `"${info.name}"`,
+      details.length ? ` — ${details.join(', ')}` : '',
+      config.id,
+      config.ip,
+    );
+  }
+
+  /* ------------------------------------------------------------------ *
+   *  Tuya Cloud — a single, global fallback session.
+   *
+   *  This plugin stays LAN-first: every device is controlled locally when it
+   *  can be. When a top-level `cloud` block is configured, the plugin keeps one
+   *  shared Tuya Cloud session alive in the background, and every device gains a
+   *  transparent cloud fallback for the moments the LAN can't be reached (a
+   *  flaky connection, or a battery-powered "sleepy" device that never appears
+   *  on the LAN at all). It's all opt-in — without `cloud`, nothing here runs.
+   * ------------------------------------------------------------------ */
+
+  _setupCloudSession() {
+    const cloudCfg =
+      this.config.cloud && typeof this.config.cloud === 'object'
+        ? this.config.cloud
+        : null;
+    if (!cloudCfg) return; // no cloud block: the plugin runs purely on the LAN
+
+    if (!cloudCfg.accessId || !cloudCfg.accessKey) {
+      return this.log.error(
+        'A "cloud" block is present but is missing accessId/accessKey, so the Tuya Cloud fallback is disabled. See the wiki: Tuya Cloud Setup.',
+      );
+    }
+
+    this.cloudApi = new TuyaCloudApi({
+      ...cloudCfg,
+      log: this.log,
+      logHttp: coerceBoolean(this._debugConfig().logCloudHttp),
+    });
+    this.cloudMessaging = new TuyaCloudMessaging({
+      api: this.cloudApi,
+      log: this.log,
+    });
+
+    this.log.info(
+      'Tuya Cloud fallback enabled via %s.',
+      this.cloudApi.endpoint,
+    );
+  }
+
+  _createDevice(device) {
+    // The one shared cloud session, when configured, backs every device as its
+    // fallback. There is no per-device cloud configuration.
+    const usesCloud = !!this.cloudApi;
+    return new TuyaDevice({
+      ...device,
+      cloudApi: usesCloud ? this.cloudApi : undefined,
+      messaging: usesCloud ? this.cloudMessaging : undefined,
+      cloudStartDelay: usesCloud ? this._nextCloudStartDelay() : 0,
+      log: this.log,
+      UUID: UUID.generate(UUID_SEED + ':' + device.id),
+      connect: false,
+    });
+  }
+
+  // Spread the cloud devices' first reads over a few seconds so a large install
+  // doesn't fire dozens of OpenAPI calls at once and trip Tuya's per-second rate
+  // limit at startup.
+  _nextCloudStartDelay() {
+    this._cloudStartCount = (this._cloudStartCount || 0) + 1;
+    return Math.min(15000, (this._cloudStartCount - 1) * 300);
+  }
+
+  registerPlatformAccessories(platformAccessories) {
+    this.api.registerPlatformAccessories(
+      PLUGIN_NAME,
+      PLATFORM_NAME,
+      Array.isArray(platformAccessories)
+        ? platformAccessories
+        : [platformAccessories],
+    );
+  }
+
+  configureAccessory(accessory) {
+    // also checks null objects or empty config - this._expectedUUIDs
+    if (
+      accessory instanceof PlatformAccessory &&
+      this._expectedUUIDs &&
+      this._expectedUUIDs.includes(accessory.UUID)
+    ) {
+      this.cachedAccessories.set(accessory.UUID, accessory);
+      accessory.services.forEach((service) => {
+        if (service.UUID === Service.AccessoryInformation.UUID) return;
+        service.characteristics.some((characteristic) => {
+          if (
+            !characteristic.props ||
+            !Array.isArray(characteristic.props.perms) ||
+            characteristic.props.perms.length !== 3 ||
+            !(
+              characteristic.props.perms.includes(Perms.WRITE) &&
+              characteristic.props.perms.includes(Perms.NOTIFY)
+            )
+          )
+            return;
+
+          // Each cached accessory starts faulted ("No Response") until its
+          // device connects — expected, and once per accessory at startup, so
+          // it belongs at debug rather than as a wall of cryptic info lines.
+          this.log.debug(
+            'Marked %s unreachable by faulting Service.%s.%s',
+            accessory.displayName,
+            service.displayName,
+            characteristic.displayName,
+          );
+
+          characteristic.updateValue(new Error('Unreachable'));
+          return true;
+        });
+      });
+    } else {
+      /*
+       * Irrespective of this unregistering, Homebridge continues
+       * to "_prepareAssociatedHAPAccessory" and "addBridgedAccessory".
+       * This timeout will hopefully remove the accessory after that has happened.
+       */
+      setTimeout(() => {
+        this.removeAccessory(accessory);
+      }, 1000);
+    }
+  }
+
+  addAccessory(device) {
+    const deviceConfig = device.context;
+    const type = (deviceConfig.type || '').toLowerCase();
+
+    const Accessory = CLASS_DEF[type];
+
+    let accessory = this.cachedAccessories.get(deviceConfig.UUID),
+      isCached = true;
+
+    const expectedCategory = Accessory.getCategory(Categories);
+
+    // Only treat a cached accessory as a "different type" when we actually
+    // have a category to compare against. If getCategory() resolves to
+    // undefined (e.g. an unknown HAP category constant), HomeKit stores the
+    // accessory as Categories.OTHER, so an undefined expectation would never
+    // match and we would needlessly unregister & recreate the accessory on
+    // every restart — wiping its HomeKit identity (name, room, automations).
+    if (
+      accessory &&
+      expectedCategory !== undefined &&
+      accessory.category !== expectedCategory
+    ) {
+      this.log.info(
+        '%s has a different type (%s vs %s)',
+        accessory.displayName,
+        accessory.category,
+        expectedCategory,
+      );
+      this.removeAccessory(accessory);
+      accessory = null;
+    }
+
+    if (!accessory) {
+      accessory = new PlatformAccessory(
+        deviceConfig.name,
+        deviceConfig.UUID,
+        expectedCategory,
+      );
+      accessory
+        .getService(Service.AccessoryInformation)
+        .setCharacteristic(
+          Characteristic.Manufacturer,
+          deviceConfig.manufacturer || 'Unknown',
+        )
+        .setCharacteristic(
+          Characteristic.Model,
+          deviceConfig.model || 'Unknown',
+        )
+        .setCharacteristic(
+          Characteristic.SerialNumber,
+          deviceConfig.id.slice(8),
+        );
+
+      isCached = false;
+    }
+
+    if (accessory && accessory.displayName !== deviceConfig.name) {
+      this.log.info(
+        'Configuration name %s differs from cached displayName %s. Updating cached displayName to %s ',
+        deviceConfig.name,
+        accessory.displayName,
+        deviceConfig.name,
+      );
+      accessory.displayName = deviceConfig.name;
+    }
+
+    this.cachedAccessories.set(
+      deviceConfig.UUID,
+      new Accessory(this, accessory, device, !isCached),
+    );
+  }
+
+  removeAccessory(homebridgeAccessory) {
+    if (!homebridgeAccessory) return;
+
+    // Only real PlatformAccessory instances can be unregistered. cachedAccessories
+    // also holds accessory wrappers (set by addAccessory), and Homebridge throws a
+    // fatal TypeError when handed anything else, taking down the whole child bridge.
+    // Guard against it rather than trust every caller.
+    if (!(homebridgeAccessory instanceof PlatformAccessory)) {
+      return this.log.warn(
+        'Skipped unregistering %s: not a PlatformAccessory.',
+        homebridgeAccessory.displayName,
+      );
+    }
+
+    this.log.warn('Unregistering', homebridgeAccessory.displayName);
+
+    this.cachedAccessories.delete(homebridgeAccessory.UUID);
+    this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [
+      homebridgeAccessory,
+    ]);
+  }
+
+  removeAccessoryByUUID(uuid) {
+    if (uuid) this.removeAccessory(this.cachedAccessories.get(uuid));
+  }
+}