homebridge-tuya-plus 3.5.2 → 3.6.0

package/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Test Code
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "23"
+
+      - run: npm ci
+
+      - name: Run Jest
+        run: npm run test

package/config.schema.json

@@ -7,23 +7,27 @@
   "schema": {
     "type": "object",
     "properties": {
+      "name": {
+        "title": "Name",
+        "type": "string",
+        "default": "Tuya LAN"
+      },
       "discoverTimeout": {
         "title": "Device IP auto-discovery timeout",
         "type": "integer",
         "minimum": 0,
         "placeholder": "Timeout (millisecond) for device IP address discovery",
-        "default": 60000,
-        "required": false
+        "default": 60000
       },
       "devices": {
         "type": "array",
         "orderable": false,
         "items": {
           "type": "object",
+          "required": ["type", "name", "id", "key"],
           "properties": {
             "type": {
               "type": "string",
-              "required": true,
               "default": "null",
               "oneOf": [
                 {
@@ -107,7 +111,6 @@
             "name": {
               "type": "string",
               "description": "Anything you'd like to use to identify this device. You can always change the name from within the Home app later.",
-              "required": true,
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
               }
@@ -116,7 +119,6 @@
               "type": "string",
               "title": "Tuya ID",
               "description": "If you don't have the Tuya ID or Key, follow the steps found on the <a href='https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Get-Local-Keys-for-Your-Devices.md' target='_blank'>Setup Instructions</a> page.",
-              "required": true,
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
               }
@@ -124,7 +126,6 @@
             "key": {
               "title": "Tuya Key",
               "type": "string",
-              "required": true,
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
               }
@@ -132,7 +133,6 @@
             "ip": {
               "title": "IP Address",
               "type": "string",
-              "required": false,
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
               }

package/index.js

@@ -24,6 +24,7 @@ const ValveAccessory = require('./lib/ValveAccessory');
 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';
@@ -56,7 +57,8 @@ const CLASS_DEF = {
     watervalve: ValveAccessory,
     oildiffuser: OilDiffuserAccessory,
     doorbell: DoorbellAccessory,
-    verticalblindswithtilt: VerticalBlindsWithTilt
+    verticalblindswithtilt: VerticalBlindsWithTilt,
+    percentblinds: PercentBlindsAccessory
 };
 
 let Characteristic, Formats, Perms, Categories, PlatformAccessory, Service, AdaptiveLightingController, UUID;

package/lib/PercentBlindsAccessory.js

@@ -0,0 +1,80 @@
+const BaseAccessory = require('./BaseAccessory');
+
+class PercentBlindsAccessory extends BaseAccessory {
+    static getCategory(Categories) {
+        return Categories.WINDOW_COVERING;
+    }
+
+    constructor(...props) {
+        super(...props);
+    }
+
+    _registerPlatformAccessory() {
+        const {Service} = this.hap;
+        this.accessory.addService(Service.WindowCovering, this.device.context.name);
+        super._registerPlatformAccessory();
+    }
+
+    _registerCharacteristics(dps) {
+        const {Service, Characteristic} = this.hap;
+        const service = this.accessory.getService(Service.WindowCovering);
+        this._checkServiceName(service, this.device.context.name);
+
+        this.dpPercentControl = this._getCustomDP(this.device.context.dpPercentControl) || '2';
+        this.dpPercentState = this._getCustomDP(this.device.context.dpPercentState) || '2';
+        this.flipState = !!this.device.context.flipState;
+
+        const characteristicCurrentPosition = service.getCharacteristic(Characteristic.CurrentPosition)
+            .updateValue(this._mapPosition(dps[this.dpPercentState] !== undefined ? dps[this.dpPercentState] : 0))
+            .on('get', this.getCurrentPosition.bind(this));
+
+        const characteristicTargetPosition = service.getCharacteristic(Characteristic.TargetPosition)
+            .updateValue(this._mapPosition(dps[this.dpPercentControl] !== undefined ? dps[this.dpPercentControl] : 0))
+            .on('get', this.getTargetPosition.bind(this))
+            .on('set', this.setTargetPosition.bind(this));
+
+        service.getCharacteristic(Characteristic.PositionState)
+            .updateValue(Characteristic.PositionState.STOPPED)
+            .on('get', callback => callback(null, Characteristic.PositionState.STOPPED));
+
+        this.device.on('change', changes => {
+            if (changes.hasOwnProperty(this.dpPercentState)) {
+                const position = this._mapPosition(changes[this.dpPercentState]);
+                this.log.debug(`[TuyaAccessory] Blind current position updated to ${position}`);
+                characteristicCurrentPosition.updateValue(position);
+            }
+            if (changes.hasOwnProperty(this.dpPercentControl)) {
+                const position = this._mapPosition(changes[this.dpPercentControl]);
+                this.log.debug(`[TuyaAccessory] Blind target position updated to ${position}`);
+                characteristicTargetPosition.updateValue(position);
+            }
+        });
+    }
+
+    _mapPosition(value) {
+        const position = parseInt(value) || 0;
+        return this.flipState ? 100 - position : position;
+    }
+
+    getCurrentPosition(callback) {
+        this.getState(this.dpPercentState, (err, dp) => {
+            if (err) return callback(err);
+            callback(null, this._mapPosition(dp));
+        });
+    }
+
+    getTargetPosition(callback) {
+        this.getState(this.dpPercentControl, (err, dp) => {
+            if (err) return callback(err);
+            callback(null, this._mapPosition(dp));
+        });
+    }
+
+    setTargetPosition(value, callback) {
+        const position = this._mapPosition(value);
+        this.log.debug(`[TuyaAccessory] Setting blind position to ${position}`);
+        this.setState(this.dpPercentControl, position, callback);
+    }
+}
+
+module.exports = PercentBlindsAccessory;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "A community-maintained Homebridge plugin for controlling Tuya devices locally over LAN. Includes new features, fixes, and updated device support.",
   "main": "index.js",
   "scripts": {

package/test/uuidStability.test.js

@@ -0,0 +1,75 @@
+'use strict';
+
+// Regression guard for HomeKit accessory identity.
+//
+// HomeKit identifies accessories by UUID. Every UUID this plugin produces
+// must be derived from the legacy seed 'homebridge-tuya' (the PLUGIN_NAME
+// used in v3.4.0 and earlier) - NOT from the current npm package name
+// 'homebridge-tuya-plus'. v3.5.0 broke this and reset every device in
+// HomeKit; v3.5.1 restored it.
+//
+// These tests fail loudly if anyone "cleans up" the seed back to PLUGIN_NAME.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const indexSource = fs.readFileSync(path.join(__dirname, '..', 'index.js'), 'utf8');
+
+// HAP-NodeJS's uuid.generate algorithm, reproduced here so the test does not
+// require pulling in homebridge or hap-nodejs. Matches
+// https://github.com/homebridge/HAP-NodeJS/blob/master/src/lib/util/uuid.ts
+function hapGenerate(data) {
+    const sha1 = crypto.createHash('sha1').update(data).digest('hex');
+    let i = -1;
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        i += 1;
+        if (c === 'y') return ((parseInt(sha1[i], 16) & 0x3) | 0x8).toString(16);
+        return sha1[i];
+    });
+}
+
+describe('index.js UUID seed constants', () => {
+    test("UUID_SEED is 'homebridge-tuya' (legacy v3.4.0 PLUGIN_NAME)", () => {
+        expect(indexSource).toMatch(/const\s+UUID_SEED\s*=\s*'homebridge-tuya'\s*;/);
+    });
+
+    test("PLUGIN_NAME is 'homebridge-tuya-plus' (current npm package name)", () => {
+        expect(indexSource).toMatch(/const\s+PLUGIN_NAME\s*=\s*'homebridge-tuya-plus'\s*;/);
+    });
+
+    test('every UUID.generate(...) call uses UUID_SEED, never PLUGIN_NAME', () => {
+        const calls = indexSource.match(/UUID\.generate\([^)]*\)/g) || [];
+        expect(calls.length).toBeGreaterThan(0);
+        for (const call of calls) {
+            expect(call).toMatch(/UUID_SEED/);
+            expect(call).not.toMatch(/PLUGIN_NAME/);
+        }
+    });
+});
+
+describe('UUID stability against v3.4.0', () => {
+    // Pinned outputs derived from `homebridge-tuya:<deviceId>` (the v3.4.0
+    // seed). If any of these change, every existing user's HomeKit identity
+    // resets on upgrade.
+    const fixtures = [
+        {
+            seed: 'homebridge-tuya:bf1234567890abcdef1234',
+            uuid: 'f7bd0a51-7bb8-4405-9ea6-d3da81023f2f',
+        },
+        {
+            seed: 'homebridge-tuya:fake:device-001',
+            uuid: '4922e84f-cbd0-415f-8ad4-43d7891ace87',
+        },
+    ];
+
+    test.each(fixtures)('UUID for "$seed" is stable', ({ seed, uuid }) => {
+        expect(hapGenerate(seed)).toBe(uuid);
+    });
+
+    test('legacy seed and v3.5.0 broken seed produce different UUIDs', () => {
+        const id = 'bf1234567890abcdef1234';
+        expect(hapGenerate('homebridge-tuya:' + id))
+            .not.toBe(hapGenerate('homebridge-tuya-plus:' + id));
+    });
+});

package/wiki/Supported-Device-Types.md

@@ -21,6 +21,7 @@ If you are looking for verified configurations for your specific device, please
 |Simple Blinds|`SimpleBlinds`<sup>[11](#simple-blinds)</sup>|Smart blinds and smart switches that control blinds <small>([instructions](#simple-blinds))</small>|
 |Simple Blinds2|`SimpleBlinds2`<sup>[11](#simple-blinds)</sup>|Smart blinds and smart switches that control blinds(Use if simple Blinds (1) doesn't work for you. <small>([instructions](#simple-blinds))</small>|
 |Vertical Blinds with Tilt|`VerticalBlindsWithTilt`<sup>[11](#vertical-blinds-with-tilt)</sup>|Smart vertical blinds with open/close and panel rotation <small>([instructions](#vertical-blinds-with-tilt))</small>|
+|Percent Control Blinds|`PercentBlinds`<sup>[11](#percent-control-blinds)</sup>|Blinds that natively report and accept a percentage position via a `percent_control` datapoint <small>([instructions](#percent-control-blinds))</small>|
 |Smart Plug w/ White and Color Lights|`RGBTWOutlet`<sup>[12](#outlets-with-white-and-color-lights)</sup>|Smart plugs that have controllable RGBTW LEDs <small>([instructions](#outlets-with-white-and-color-lights))</small>|
 |Smart Fan Regulator|`SimpleFanAccessory`<sup>[more](#smart-fan-regulators-and-accessories)</sup>|Smart Fan Regulators that have controllable Speeds <small>([instructions](#smart-fan-regulators-and-accessories))</small>|
 |Smart Fan with Light|`SimpleFanLightAccessory`<sup>[more](#smart-fan-with-light)</sup>|Smart Fan devices that have controllable Speeds, Directions and a built-in Light<small>([instructions](#smart-fan-with-light))</small>|
@@ -456,6 +457,43 @@ Support for Tuya/Graywind Smart Vertical Blinds with open/close (retract/extend)
 }
 ```
 
+### Percent Control Blinds
+These are blinds or roller shades that natively report their current position and accept a target position as a percentage via a `percent_control` datapoint. Unlike `SimpleBlinds`, no timing calibration is needed — the device reports its actual position directly.
+
+#### Minimal Configuration
+```json
+{
+    "name": "My Blinds",
+    "type": "PercentBlinds",
+    "id": "032000123456789abcde",
+    "key": "0123456789abcdef"
+}
+```
+
+#### Full Configuration
+```json5
+{
+    "name": "My Blinds",
+    "type": "PercentBlinds",
+    "manufacturer": "Tuya",
+    "model": "Smart Roller Blind",
+    "id": "032000123456789abcde",
+    "key": "0123456789abcdef",
+
+    /* Additional parameters to override defaults only if needed */
+
+    /* Override the default datapoint identifier for setting target position (0–100) */
+    "dpPercentControl": "2",
+
+    /* Override the default datapoint identifier for reading current position (0–100).
+       Use "3" if your device reports position on a separate datapoint from control. */
+    "dpPercentState": "2",
+
+    /* If the device reports 0 as fully open instead of fully closed, flip the range */
+    "flipState": true
+}
+```
+
 ### Outlets with White and Color Lights
 These are plugs with a single outlet that that have controllable white and colored LEDs on them.