homebridge-tuya-plus 3.14.0-dev.29 → 3.14.0-dev.30

package/config.schema.json

@@ -22,7 +22,7 @@
       "cloud": {
         "type": "object",
         "title": "Tuya Cloud fallback (optional)",
-        "description": "This plugin is LAN-first — every device is controlled locally. Add your Tuya Cloud project credentials here and the plugin keeps one Cloud session running in the background as a transparent fallback for every device: each accessory tries the LAN first, and only falls back to the cloud when it can't be reached locally — a flaky LAN moment, or a battery-powered 'sleepy' device that never appears on the LAN. It's opt-in and local is always preferred. Create a free Cloud project at iot.tuya.com. See the wiki for step-by-step setup.",
+        "description": "<a href='https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md'>Tuya Cloud API Setup</a>.",
         "properties": {
           "accessId": {
             "type": "string",
@@ -69,12 +69,6 @@
               { "title": "Tuya Smart", "enum": ["tuyaSmart"] },
               { "title": "Smart Life", "enum": ["smartlife"] }
             ]
-          },
-          "realtime": {
-            "type": "boolean",
-            "title": "Realtime updates (MQTT)",
-            "default": true,
-            "description": "Receive instant updates over Tuya's MQTT message service (uses the 'mqtt' package, installed automatically). If disabled, devices stay controllable and show their state at startup, but external changes (physical buttons, the device's own timers) won't be reflected until restart."
           }
         }
       },
@@ -96,7 +90,7 @@
                 {
                   "title": "Switch Gang / Basic Switch",
                   "enum": ["Switch"]
-                },                
+                },
                 {
                   "title": "Smart Plug / Barely Smart Power Strip",
                   "enum": ["Outlet"]
@@ -311,7 +305,7 @@
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['WledDimmer'].includes(model.devices[arrayIndices].type);"
               }
-            },            
+            },
             "dpColorTemperature": {
               "type": "integer",
               "placeholder": "3",
@@ -754,9 +748,21 @@
               "items": {
                 "type": "object",
                 "properties": {
-                  "name": { "type": "string", "title": "Zone name", "placeholder": "Lawn" },
-                  "dp": { "type": ["integer", "string"], "title": "Data-point (numeric id, or cloud code)", "placeholder": "1 or switch_1" },
-                  "defaultDuration": { "type": "integer", "title": "Default run time (seconds, 0 = run indefinitely)", "placeholder": 600 }
+                  "name": {
+                    "type": "string",
+                    "title": "Zone name",
+                    "placeholder": "Lawn"
+                  },
+                  "dp": {
+                    "type": ["integer", "string"],
+                    "title": "Data-point (numeric id, or cloud code)",
+                    "placeholder": "1 or switch_1"
+                  },
+                  "defaultDuration": {
+                    "type": "integer",
+                    "title": "Default run time (seconds, 0 = run indefinitely)",
+                    "placeholder": 600
+                  }
                 }
               },
               "condition": {
@@ -847,4 +853,4 @@
       }
     }
   }
-}
+}

package/index.js

@@ -40,328 +40,459 @@ const PLATFORM_NAME = 'TuyaLan';
 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: 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
+  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;
-
-module.exports = function(homebridge) {
-    ({
-        platformAccessory: PlatformAccessory,
-        hap: {Characteristic, Formats, Perms, Categories, Service, AdaptiveLightingController, uuid: UUID}
-    } = homebridge);
-
-    homebridge.registerPlatform(PLUGIN_NAME, PLATFORM_NAME, TuyaLan, true);
+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();
-        // 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();
-        });
+  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;
     }
 
-    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
-        }
-
-        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.log.warn('Discovered a device that has not been configured yet (%s@%s).', config.id, config.ip);
-                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);
+    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
     }
 
-    /* ------------------------------------------------------------------ *
-     *  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.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.log.warn(
+            'Discovered a device that has not been configured yet (%s@%s).',
+            config.id,
+            config.ip,
+          );
+        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.cloudApi = new TuyaCloudApi({...cloudCfg, log: this.log});
-
-        const realtime = cloudCfg.realtime === undefined ? true : coerceBoolean(cloudCfg.realtime, true);
-        this.cloudMessaging = realtime ? new TuyaCloudMessaging({api: this.cloudApi, log: this.log}) : null;
-
-        this.log.info('Tuya Cloud fallback enabled via %s%s.', this.cloudApi.endpoint, this.cloudMessaging ? ' (with realtime updates)' : ' (realtime updates disabled)');
+      });
+    }, this.config.discoverTimeout ?? DEFAULT_DISCOVER_TIMEOUT);
+  }
+
+  /* ------------------------------------------------------------------ *
+   *  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.',
+      );
     }
 
-    _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
+    this.cloudApi = new TuyaCloudApi({ ...cloudCfg, log: this.log });
+    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;
+
+          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);
     }
-
-    // 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);
+  }
+
+  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;
     }
 
-    registerPlatformAccessories(platformAccessories) {
-        this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, Array.isArray(platformAccessories) ? platformAccessories : [platformAccessories]);
+    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;
     }
 
-    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);
-        }
+    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;
     }
 
-    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));
+    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,
+      );
     }
 
-    removeAccessory(homebridgeAccessory) {
-        if (!homebridgeAccessory) return;
+    this.log.warn('Unregistering', homebridgeAccessory.displayName);
 
-        // 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.cachedAccessories.delete(homebridgeAccessory.UUID);
+    this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [
+      homebridgeAccessory,
+    ]);
+  }
 
-        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));
-    }
+  removeAccessoryByUUID(uuid) {
+    if (uuid) this.removeAccessory(this.cachedAccessories.get(uuid));
+  }
 }

package/lib/TuyaCloudMessaging.js

@@ -6,36 +6,27 @@ const crypto = require('crypto');
 /*
  * TuyaCloudMessaging
  * ------------------
- * Optional realtime updates for cloud-backed devices, over Tuya's MQTT message
- * service. ONE instance is shared by every cloud device on the same Tuya
- * project (one broker connection delivers status for all of them); messages are
- * fanned out to the right device by its `devId`.
+ * Realtime updates for cloud-backed devices, over Tuya's MQTT message service.
+ * ONE instance is shared by every cloud device on the same Tuya project (one
+ * broker connection delivers status for all of them); messages are fanned out
+ * to the right device by its `devId`.
  *
- * This is intentionally a best-effort accelerator layered on top of polling:
- * if the optional `mqtt` package is missing, or the broker can't be reached, or
- * a message can't be decrypted, nothing breaks — the devices simply keep
- * polling. When it IS working, changes (including physical button presses and
- * the rain sensor) show up in HomeKit within a second or two.
+ * Cloud updates (including physical button presses and the rain sensor) arrive
+ * over this stream rather than by polling, so they show up in HomeKit within a
+ * second or two. `mqtt` is a required dependency; if the broker can't be
+ * reached or a message can't be decrypted nothing crashes — the stream simply
+ * reconnects and the cloud REST reads still cover initial state.
  *
  * The connection + AES-GCM message decryption are faithful to the
  * actively-maintained `0x5e/homebridge-tuya-platform` (`src/core/TuyaOpenMQ.ts`),
  * re-implemented here with Node's built-in `crypto`.
  */
 
+const mqtt = require('mqtt');
+
 const GCM_TAG_LENGTH = 16;
 const PROTOCOL_DEVICE_STATUS = 4;
 
-// `mqtt` is an OPTIONAL dependency: realtime is a bonus, polling is the
-// guarantee. Loading it lazily keeps the plugin LAN-first and lets it run in
-// environments where mqtt isn't (or can't be) installed.
-let mqtt = null;
-let mqttLoadError = null;
-try {
-    mqtt = require('mqtt');
-} catch (ex) {
-    mqttLoadError = ex;
-}
-
 class TuyaCloudMessaging extends EventEmitter {
     constructor({api, log} = {}) {
         super();
@@ -56,10 +47,6 @@ class TuyaCloudMessaging extends EventEmitter {
         this.setMaxListeners(0);
     }
 
-    static isAvailable() {
-        return !!mqtt;
-    }
-
     // Register a device's status handler and lazily start the shared connection.
     subscribeDevice(devId, handler) {
         const id = '' + devId;
@@ -72,13 +59,8 @@ class TuyaCloudMessaging extends EventEmitter {
         if (this._stopped || this._started) return;
         this._started = true;
 
-        if (!mqtt) {
-            this.log.warn(`Tuya Cloud realtime disabled: the optional "mqtt" package is not installed${mqttLoadError ? ` (${mqttLoadError.message})` : ''}. Devices will poll instead. Install it with "npm install mqtt" in the plugin folder to enable instant updates.`);
-            return;
-        }
-
         this._connect().catch(ex => {
-            this.log.warn(`Tuya Cloud realtime could not start (${ex.message}); devices will poll instead.`);
+            this.log.warn(`Tuya Cloud realtime could not start (${ex.message}); it will keep retrying.`);
             this._scheduleRenew(60);
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-dev.29",
+  "version": "3.14.0-dev.30",
   "description": "A community-maintained Homebridge plugin for controlling Tuya devices in HomeKit. LAN-first, with an optional Tuya Cloud fallback for any device the LAN can't reach.",
   "main": "index.js",
   "scripts": {
@@ -29,12 +29,10 @@
     "fs-extra": "^8.1.0",
     "http-mitm-proxy": "^1.1.0",
     "json5": "^2.2.0",
+    "mqtt": "^5.15.1",
     "qrcode": "^1.4.1",
     "yaml": "^1.6.0"
   },
-  "optionalDependencies": {
-    "mqtt": "^5.15.1"
-  },
   "keywords": [
     "homebridge-plugin",
     "homebridge",

package/test/TuyaCloudMessaging.test.js

@@ -110,9 +110,4 @@ describe('TuyaCloudMessaging — decryption + dispatch', () => {
         mq.subscribeDevice('DEV1', () => { throw new Error('should not be called'); });
         expect(() => mq._onMessage('topic', Buffer.from('not json'))).not.toThrow();
     });
-
-    test('reports whether realtime is available (mqtt installed)', () => {
-        // mqtt is an (optional) dependency of this project, so it should load.
-        expect(typeof TuyaCloudMessaging.isAvailable()).toBe('boolean');
-    });
 });

package/test/index.test.js

@@ -97,12 +97,6 @@ describe('TuyaLan — cloud session setup', () => {
         expect(TuyaCloudApi.mock.calls[0][0]).toMatchObject({accessId: 'aid', accessKey: 'akey', region: 'eu'});
         expect(TuyaCloudMessaging).toHaveBeenCalledTimes(1);
     });
-
-    test('realtime:false skips the MQTT session', () => {
-        run({cloud: {...CLOUD, realtime: false}, devices: [SW()]});
-        expect(TuyaCloudApi).toHaveBeenCalledTimes(1);
-        expect(TuyaCloudMessaging).not.toHaveBeenCalled();
-    });
 });
 
 describe('TuyaLan — cloud participation', () => {

package/wiki/Tuya-Cloud-Setup.md

@@ -20,12 +20,23 @@ It helps in two situations:
 
 ## 2. Authorize the required API services
 
+There are two types of projects: `Custom` and `Smart Home`. The difference between them is:
+
+* The `Custom` project pulls devices from the project's assets.
+* The `Smart Home` project pulls devices from the user's home in the Tuya app.
+
+If you are a personal user and are unsure which one to choose, please use the Smart Home project.
+
 In the project, go to **Service API → Go to Authorize** and make sure these are subscribed (all free):
 
-* **IoT Core**
-* **Authorization**
-* **Smart Home Basic Service**
-* **Device Status Notification** ← needed for realtime MQTT updates
+* Authorization Token Management
+* Device Status Notification
+* IoT Core
+* IoT Video Live Stream (for cameras)
+* Industry Project Client Service (for the `Custom` project)
+* IR Control Hub Open Service (for IR devices)
+* Smart Home Scene Linkage (for scenes)
+* Smart Lock Open Service (for Lock devices)
 
 > **⚠️Remember to extend the API trial period every 6 months here: [Tuya IoT Platform > Cloud > Cloud Services > IoT Core](https://iot.tuya.com/cloud/products/detail?abilityId=1442730014117204014&id=p1668587814138nv4h3n&abilityAuth=0&tab=1) (the first-time subscription only gives you 1 month).**