homebridge-tuya-plus 3.14.0-beta.1 → 3.14.0-dev.3

package/.github/CODEOWNERS

@@ -0,0 +1,5 @@
+# Changes to CI/release automation require the maintainer's review.
+# Enforced only when branch protection on `main` has
+# "Require review from Code Owners" enabled.
+/.github/workflows/ @adrianjagielak
+/.github/CODEOWNERS  @adrianjagielak

package/.github/workflows/publish-dev.yml

@@ -0,0 +1,146 @@
+name: Publish dev to npm
+
+# Publishes commits on `main` to npm under the `dev` dist-tag.
+#
+# Versioning:
+#   * Dev builds target the NEXT minor release, since releases here are
+#     usually a minor bump. With package.json at e.g. 3.13.0, dev builds
+#     are published as 3.14.0-dev.<run-number> (minor +1, patch reset to 0,
+#     prerelease tag = the GitHub Actions run number). In semver these sort
+#     below the eventual 3.14.0 release, so `latest` always wins once cut.
+#   * Release commits are skipped: if a push changes package.json's version
+#     (i.e. you bumped it to cut a real release and publish to npm
+#     manually), no dev build is published for that push.
+#
+# Security model (why a malicious PR cannot steal publishing rights):
+#   * No npm token is stored anywhere. Publishing uses npm Trusted
+#     Publishing (OIDC): GitHub mints a short-lived, cryptographically
+#     signed token that npm only accepts when its claims match THIS repo +
+#     THIS workflow file. There is no durable credential to exfiltrate.
+#   * This workflow never runs on `pull_request`, only on pushes to `main`
+#     (post-merge) and manual dispatch — so fork PRs get nothing.
+#   * The privileged `publish` job is minimal and isolated: it does not
+#     run `npm ci`, a build, or tests, and uses `--ignore-scripts`, so no
+#     repo/dependency code executes while the OIDC permission is present.
+#     Tests run in a separate, unprivileged job that gates publishing, and
+#     the version is computed in an unprivileged `prepare` job.
+#
+# One-time setup required for this to succeed (see PR/commit notes):
+#   1. npmjs.com -> package Settings -> Trusted Publisher:
+#        Publisher: GitHub Actions
+#        Organization/user: adrianjagielak
+#        Repository:        homebridge-tuya-plus
+#        Workflow filename: publish-dev.yml
+#        Environment:       npm-dev
+#   2. GitHub repo Settings -> Environments -> create `npm-dev`,
+#      restrict deployment branches to `main` (optional: required reviewer).
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Least privilege by default; only the publish job opts into id-token.
+permissions:
+  contents: read
+
+# Don't cancel an in-flight publish; let each commit publish its version.
+concurrency:
+  group: publish-dev
+  cancel-in-progress: false
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run test
+
+  # Unprivileged: decides whether this push should publish a dev build, and
+  # computes the dev version. Kept out of the `publish` job so no extra work
+  # runs while the OIDC publishing permission is present.
+  prepare:
+    runs-on: ubuntu-latest
+    outputs:
+      should_publish: ${{ steps.check.outputs.should_publish }}
+      version: ${{ steps.ver.outputs.version }}
+    steps:
+      # Full history so we can read package.json from before this push.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Skip dev builds for release commits: if package.json's version
+      # changed anywhere in this push (before -> after), treat it as a manual
+      # release and publish nothing. If we can't determine the previous
+      # version (first push, manual dispatch, missing file), default to
+      # publishing — a dev build is the safe fallback.
+      - name: Decide whether to publish a dev build
+        id: check
+        run: |
+          CURR="$(node -p "require('./package.json').version")"
+          BEFORE="${{ github.event.before }}"
+          if [ -z "$BEFORE" ] || [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
+            BEFORE="$(git rev-parse --verify --quiet HEAD~1 || true)"
+          fi
+          PREV=""
+          if [ -n "$BEFORE" ] && git cat-file -e "$BEFORE:package.json" 2>/dev/null; then
+            git show "$BEFORE:package.json" > "$RUNNER_TEMP/prev-package.json"
+            PREV="$(node -p "require('$RUNNER_TEMP/prev-package.json').version")"
+          fi
+          echo "Previous version: ${PREV:-<unknown>}"
+          echo "Current version:  $CURR"
+          if [ -n "$PREV" ] && [ "$PREV" != "$CURR" ]; then
+            echo "::notice::package.json version changed ($PREV -> $CURR); skipping dev publish (treated as a manual release commit)."
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Dev builds target the next MINOR release (minor +1, patch -> 0).
+      - name: Compute dev version
+        id: ver
+        run: |
+          NEXT="$(node -e "const v=require('./package.json').version.split('.'); v[1]=Number(v[1])+1; v[2]=0; console.log(v.join('.'))")"
+          VERSION="${NEXT}-dev.${GITHUB_RUN_NUMBER}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Will publish $VERSION"
+
+  publish:
+    needs: [test, prepare]
+    # Skip release commits (version bumped in this push).
+    if: needs.prepare.outputs.should_publish == 'true'
+    runs-on: ubuntu-latest
+    # Bind this environment in repo Settings to the `main` branch so that
+    # only main can ever reach the publish step.
+    environment: npm-dev
+    permissions:
+      contents: read # checkout
+      id-token: write # OIDC -> npm Trusted Publishing (no stored token)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      # Trusted Publishing (OIDC) requires npm >= 11.5.1.
+      - name: Ensure OIDC-capable npm
+        run: npm install -g npm@latest
+
+      # Writes package.json on the runner only; nothing is committed.
+      - name: Set version
+        run: npm version "${{ needs.prepare.outputs.version }}" --no-git-tag-version --allow-same-version --ignore-scripts
+
+      # No NODE_AUTH_TOKEN: npm exchanges the OIDC id-token for a
+      # short-lived, package-scoped credential at publish time.
+      # --ignore-scripts ensures no lifecycle script runs with that credential.
+      # --provenance attaches a signed build attestation (needs a public repo).
+      - name: Publish (dev tag)
+        run: npm publish --tag dev --provenance --ignore-scripts

package/Readme.MD

@@ -81,6 +81,19 @@ Search for "Tuya" in [homebridge-config-ui-x](https://github.com/oznu/homebridge
 sudo npm install -g homebridge-tuya-plus
 ```
 
+#### Bleeding-edge (`dev`) builds:
+
+Every commit to `main` is automatically published to npm under the `dev` tag — a
+separate, unstable channel. The stable release always stays on `latest`, so this
+won't affect normal installs. To try the latest in-development build:
+
+```
+sudo npm install -g homebridge-tuya-plus@dev
+```
+
+These are versioned like `3.13.1-dev.<n>` and may be unstable; use the default
+install above for production.
+
 ## Configuration
 > UI
 

package/config.schema.json

@@ -579,6 +579,14 @@
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['SimpleGarageDoor'].includes(model.devices[arrayIndices].type);"
               }
             },
+            "stopBeforeCloseMs": {
+              "type": "integer",
+              "placeholder": "1500",
+              "description": "Optional. The controller ignores a close command while the gate is actively moving, so unless the state DP already reads 11 (stopped) the plugin sends stop, waits this many milliseconds, then sends close. Tune to roughly how long the gate takes to halt after a stop. Default 1500.",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices] && ['SimpleGarageDoor'].includes(model.devices[arrayIndices].type);"
+              }
+            },
             "partialOpenMs": {
               "type": "integer",
               "placeholder": "2000",

package/lib/SimpleGarageDoorAccessory.js

@@ -13,14 +13,21 @@ const BaseAccessory = require('./BaseAccessory');
 // sync no matter how the gate was triggered (Home app, a physical remote, the
 // Tuya app, ...).
 //
-// Unlike the original open/stop/close-only gates, this controller switches
-// direction on its own — sending open while it is closing (or vice versa)
-// just reverses it — so there is no stop-first dance: a HomeKit toggle simply
-// fires the matching action.
+// Opening is symmetric and forgiving: the controller reverses on its own, so
+// an open command works directly even while the gate is closing — we just fire
+// it. Closing is asymmetric, though: the controller IGNORES a close command
+// while the gate is actively moving. The one exception is when the status DP
+// reads exactly 11 (stopped) — e.g. after a partial-open or an external stop —
+// where the gate is idle and accepts close immediately. So unless we can see
+// it's already stopped, a close is sent as stop -> wait -> close.
 const STATE_STOPPED = 11;
 const STATE_OPENING_OR_OPEN = 12;
 const STATE_CLOSING_OR_CLOSED = 13;
 
+// How long to wait between the stop and the close in the stop-before-close
+// path. Overridable per-device via the `stopBeforeCloseMs` config option.
+const DEFAULT_STOP_BEFORE_CLOSE_MS = 1500;
+
 class SimpleGarageDoorAccessory extends BaseAccessory {
     static getCategory(Categories) {
         return Categories.GARAGE_DOOR_OPENER;
@@ -82,8 +89,15 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
         const partialOpenMs = parseInt(this.device.context.partialOpenMs, 10);
         this.partialOpenMs = Number.isFinite(partialOpenMs) && partialOpenMs > 0 ? partialOpenMs : 0;
 
-        // The only pending side effect we track is the partial-open auto-stop.
+        const stopBeforeCloseMs = parseInt(this.device.context.stopBeforeCloseMs, 10);
+        this.stopBeforeCloseMs = Number.isFinite(stopBeforeCloseMs) && stopBeforeCloseMs >= 0
+            ? stopBeforeCloseMs
+            : DEFAULT_STOP_BEFORE_CLOSE_MS;
+
+        // Pending side effects we may need to cancel: the partial-open auto-stop
+        // and the close that trails a stop in the stop-before-close path.
         this.partialStopTimer = null;
+        this.pendingCloseTimer = null;
 
         // Seed the initial state from whatever the device has already reported.
         // If it hasn't reported yet, fall back to the persisted target, then to
@@ -177,6 +191,10 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
 
     _onDeviceChange(changes) {
         if (!changes || !changes.hasOwnProperty(this.dpState)) return;
+        // Mid stop-before-close: the stop we just issued can briefly report 11
+        // (=OPEN), which would fight the close we're about to send. Ignore
+        // status reports until the close has gone out.
+        if (this.pendingCloseTimer) return;
         const isOpen = this._mapDpState(changes[this.dpState]);
         if (isOpen === null) {
             this.log.info(`[SimpleGarageDoor] ${this.device.context.name}: ignoring unknown state DP value ${JSON.stringify(changes[this.dpState])}`);
@@ -228,9 +246,56 @@ class SimpleGarageDoorAccessory extends BaseAccessory {
         const open = value === Characteristic.TargetDoorState.OPEN;
         this.accessory.context.cachedTargetDoorState = value;
         if (this.characteristicTargetDoorState) this.characteristicTargetDoorState.updateValue(value);
-        const dp = open ? this.dpOpen : this.dpClose;
-        this.log.info(`[SimpleGarageDoor] ${this.device.context.name}: ${open ? 'open' : 'close'} (dp${dp})`);
-        this.setMultiStateLegacyAsync({[dp]: true});
+        if (open) this._sendOpen();
+        else this._sendClose();
+    }
+
+    // Open is always safe to fire directly — the controller reverses on its
+    // own, even mid-close. Abandon any pending stop-before-close.
+    _sendOpen() {
+        this._cancelPendingClose();
+        this.log.info(`[SimpleGarageDoor] ${this.device.context.name}: open (dp${this.dpOpen})`);
+        this.setMultiStateLegacyAsync({[this.dpOpen]: true});
+    }
+
+    // Close is ignored while the gate is actively moving, so fire it directly
+    // only when the status DP shows the gate is already stopped (11). Otherwise
+    // stop first, wait stopBeforeCloseMs, then close.
+    _sendClose() {
+        const name = this.device.context.name;
+        if (this.pendingCloseTimer) {
+            // A stop-before-close is already running — don't restart it (and
+            // push the close out) on a duplicate or retransmitted request.
+            this.log.info(`[SimpleGarageDoor] ${name}: close ignored — a stop-before-close is already running`);
+            return;
+        }
+        if (this._isStopped()) {
+            this.log.info(`[SimpleGarageDoor] ${name}: close (dp${this.dpClose}) — gate already stopped`);
+            this.setMultiStateLegacyAsync({[this.dpClose]: true});
+            return;
+        }
+        this.log.info(`[SimpleGarageDoor] ${name}: stop-before-close — stop (dp${this.dpStop}) now, close (dp${this.dpClose}) in ${this.stopBeforeCloseMs}ms`);
+        this.setMultiStateLegacyAsync({[this.dpStop]: true});
+        this.pendingCloseTimer = setTimeout(() => {
+            this.pendingCloseTimer = null;
+            this.log.info(`[SimpleGarageDoor] ${name}: stop-before-close — firing close (dp${this.dpClose})`);
+            this.setMultiStateLegacyAsync({[this.dpClose]: true});
+        }, this.stopBeforeCloseMs);
+    }
+
+    // True only when the controller reports the gate is stopped (11) — the one
+    // state where it will accept a close without a stop first.
+    _isStopped() {
+        const raw = this.device.state ? this.device.state[this.dpState] : undefined;
+        const value = typeof raw === 'string' ? parseInt(raw, 10) : raw;
+        return value === STATE_STOPPED;
+    }
+
+    _cancelPendingClose() {
+        if (this.pendingCloseTimer) {
+            clearTimeout(this.pendingCloseTimer);
+            this.pendingCloseTimer = null;
+        }
     }
 
     // Partial open: fire the open action, then after partialOpenMs fire a stop

package/lib/TuyaAccessory.js

@@ -226,9 +226,21 @@ class TuyaAccessory extends EventEmitter {
             }
         });
 
-        this._socket.on('close', err => {
+        this._socket.on('close', () => {
             this.connected = false;
             this.session_key = null;
+
+            // A heartbeat timer must never outlive its socket. The pinger
+            // callbacks act on `this._socket`, so a stale timer left over from a
+            // dead socket would later fire against a freshly reconnected one and
+            // trip a spurious ERR_PING_TIMED_OUT. Clearing it here covers every
+            // teardown path (error-driven destroy as well as the graceful end
+            // below).
+            if (this._socket._pinger) {
+                clearTimeout(this._socket._pinger);
+                this._socket._pinger = null;
+            }
+
             //this.log.info('Closed connection with', this.context.name);
         });
 
@@ -236,6 +248,32 @@ class TuyaAccessory extends EventEmitter {
             this.connected = false;
             this.session_key = null;
             this.log.info('Disconnected from', this.context.name);
+
+            // The device closed the connection on its own. This is routine for
+            // many Tuya devices (e.g. LED ceiling lights) that recycle their
+            // long-lived LAN sockets every few minutes. Previously nothing here
+            // tore the socket down or reconnected: the heartbeat timer kept
+            // running and, because `connected` is now false, its pings went
+            // nowhere until the full ping timeout elapsed and emitted a
+            // misleading "ERR_PING_TIMED_OUT" ~30s later - which was the only
+            // thing that ultimately triggered a reconnect. Tear down and
+            // reconnect promptly instead, so recovery is quick and the logs
+            // reflect what actually happened (a clean disconnect, not a ping
+            // failure).
+            if (this._socket._pinger) {
+                clearTimeout(this._socket._pinger);
+                this._socket._pinger = null;
+            }
+
+            // Destroying first means a trailing RST can't resurface as an
+            // 'error' and schedule a second, competing reconnect.
+            this._socket.destroy();
+
+            if (!this._socket._errorReconnect) {
+                this._socket._errorReconnect = setTimeout(() => {
+                    process.nextTick(this._connect.bind(this));
+                }, 5000);
+            }
         });
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-tuya-plus",
-  "version": "3.14.0-beta.1",
+  "version": "3.14.0-dev.3",
   "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/SimpleGarageDoorAccessory.test.js

@@ -49,7 +49,9 @@ function makeSimpleGarage(initialContext = {}) {
     instance.dpStop = '103';
     instance.dpState = '105';
     instance.partialOpenMs = 0;
+    instance.stopBeforeCloseMs = 1500;
     instance.partialStopTimer = null;
+    instance.pendingCloseTimer = null;
     instance.currentDoorState = CDS.CLOSED;
     instance.characteristicCurrentDoorState = {
         value: CDS.CLOSED,
@@ -77,7 +79,7 @@ function emitState(device, value) {
 }
 
 // ---------------------------------------------------------------------------
-// State DP -> door state mapping (the heart of the new behaviour)
+// State DP -> door state mapping
 // ---------------------------------------------------------------------------
 describe('SimpleGarageDoorAccessory._onDeviceChange', () => {
     test('State 12 (opening/open) drives Current and Target to OPEN', () => {
@@ -165,39 +167,37 @@ describe('SimpleGarageDoorAccessory._onDeviceChange', () => {
 });
 
 // ---------------------------------------------------------------------------
-// setTargetDoorState — fires the matching action, no stop-first dance
+// Open — always fired directly, even mid-motion
 // ---------------------------------------------------------------------------
-describe('SimpleGarageDoorAccessory.setTargetDoorState', () => {
-    test('OPEN fires the open action immediately (no stop first)', () => {
-        const { instance, device, accessory } = makeSimpleGarage();
+describe('SimpleGarageDoorAccessory.setTargetDoorState — open', () => {
+    test('OPEN fires the open action immediately, even while the gate is closing', () => {
+        const { instance, device } = makeSimpleGarage();
+        device.state['105'] = STATE_CLOSING_OR_CLOSED;
 
         instance.setTargetDoorState(TDS.OPEN);
 
         expect(device.update).toHaveBeenCalledTimes(1);
         expect(device.update).toHaveBeenCalledWith({ '101': true });
-        expect(accessory.context.cachedTargetDoorState).toBe(TDS.OPEN);
-        expect(instance.characteristicTargetDoorState.value).toBe(TDS.OPEN);
     });
 
-    test('CLOSE fires the close action immediately (no stop first)', () => {
-        const { instance, device, accessory } = makeSimpleGarage();
-        instance.currentDoorState = CDS.OPEN;
+    test('OPEN never fires a stop first', () => {
+        const { instance, device } = makeSimpleGarage();
+        device.state['105'] = STATE_OPENING_OR_OPEN;
 
-        instance.setTargetDoorState(TDS.CLOSED);
+        instance.setTargetDoorState(TDS.OPEN);
 
-        expect(device.update).toHaveBeenCalledTimes(1);
-        expect(device.update).toHaveBeenCalledWith({ '102': true });
-        expect(accessory.context.cachedTargetDoorState).toBe(TDS.CLOSED);
-        expect(instance.characteristicTargetDoorState.value).toBe(TDS.CLOSED);
+        expect(device.update).not.toHaveBeenCalledWith({ '103': true });
+        expect(device.update).toHaveBeenCalledWith({ '101': true });
     });
 
-    test('CurrentDoorState is not touched until the device reports it', () => {
-        const { instance, device } = makeSimpleGarage();
+    test('Target + persistence update optimistically; Current waits for the DP', () => {
+        const { instance, device, accessory } = makeSimpleGarage();
         instance.currentDoorState = CDS.CLOSED;
         instance.characteristicCurrentDoorState.value = CDS.CLOSED;
 
         instance.setTargetDoorState(TDS.OPEN);
-        // Target updated, but Current waits for the status DP.
+        expect(accessory.context.cachedTargetDoorState).toBe(TDS.OPEN);
+        expect(instance.characteristicTargetDoorState.value).toBe(TDS.OPEN);
         expect(instance.characteristicCurrentDoorState.updateValue).not.toHaveBeenCalled();
         expect(instance.currentDoorState).toBe(CDS.CLOSED);
 
@@ -207,25 +207,165 @@ describe('SimpleGarageDoorAccessory.setTargetDoorState', () => {
         expect(instance.characteristicCurrentDoorState.value).toBe(CDS.OPEN);
     });
 
-    test('Custom DPs are respected', () => {
+    test('Custom open DP is respected', () => {
         const { instance, device } = makeSimpleGarage();
         instance.dpOpen = '1';
-        instance.dpClose = '2';
 
         instance.setTargetDoorState(TDS.OPEN);
+
         expect(device.update).toHaveBeenCalledWith({ '1': true });
+    });
+});
+
+// ---------------------------------------------------------------------------
+// Close — direct only when already stopped (state 11), otherwise stop-first
+// ---------------------------------------------------------------------------
+describe('SimpleGarageDoorAccessory.setTargetDoorState — close (stop-before-close)', () => {
+    beforeEach(() => jest.useFakeTimers());
+    afterEach(() => jest.useRealTimers());
+
+    test('CLOSE fires immediately when the gate is already stopped (state 11)', () => {
+        const { instance, device, accessory } = makeSimpleGarage();
+        device.state['105'] = STATE_STOPPED;
+
+        instance.setTargetDoorState(TDS.CLOSED);
+
+        expect(device.update).toHaveBeenCalledTimes(1);
+        expect(device.update).toHaveBeenCalledWith({ '102': true });
+        expect(instance.pendingCloseTimer).toBeNull();
+        expect(accessory.context.cachedTargetDoorState).toBe(TDS.CLOSED);
+        expect(instance.characteristicTargetDoorState.value).toBe(TDS.CLOSED);
+    });
+
+    test('CLOSE while opening (state 12) fires stop, then close after stopBeforeCloseMs', () => {
+        const { instance, device } = makeSimpleGarage();
+        instance.stopBeforeCloseMs = 1500;
+        device.state['105'] = STATE_OPENING_OR_OPEN;
+
+        instance.setTargetDoorState(TDS.CLOSED);
+
+        // Stop goes out immediately, close is deferred.
+        expect(device.update).toHaveBeenCalledTimes(1);
+        expect(device.update).toHaveBeenNthCalledWith(1, { '103': true });
+
+        jest.advanceTimersByTime(1500 - 1);
+        expect(device.update).toHaveBeenCalledTimes(1);
+
+        jest.advanceTimersByTime(1);
+        expect(device.update).toHaveBeenCalledTimes(2);
+        expect(device.update).toHaveBeenNthCalledWith(2, { '102': true });
+        expect(instance.pendingCloseTimer).toBeNull();
+    });
+
+    test('CLOSE while closing (state 13) also uses stop-before-close', () => {
+        const { instance, device } = makeSimpleGarage();
+        instance.stopBeforeCloseMs = 1500;
+        device.state['105'] = STATE_CLOSING_OR_CLOSED;
 
         instance.setTargetDoorState(TDS.CLOSED);
-        expect(device.update).toHaveBeenCalledWith({ '2': true });
+        expect(device.update).toHaveBeenNthCalledWith(1, { '103': true });
+
+        jest.advanceTimersByTime(1500);
+        expect(device.update).toHaveBeenNthCalledWith(2, { '102': true });
     });
 
-    test('Stop is never fired by a normal open/close', () => {
+    test('CLOSE with no reported state yet uses stop-before-close', () => {
         const { instance, device } = makeSimpleGarage();
+        instance.stopBeforeCloseMs = 1500;
+        // device.state['105'] intentionally left undefined
+
+        instance.setTargetDoorState(TDS.CLOSED);
+        expect(device.update).toHaveBeenNthCalledWith(1, { '103': true });
 
+        jest.advanceTimersByTime(1500);
+        expect(device.update).toHaveBeenNthCalledWith(2, { '102': true });
+    });
+
+    test('A duplicate CLOSE during the wait does not restart or double-fire', () => {
+        const { instance, device } = makeSimpleGarage();
+        instance.stopBeforeCloseMs = 1500;
+        device.state['105'] = STATE_OPENING_OR_OPEN;
+
+        instance.setTargetDoorState(TDS.CLOSED);
+        expect(device.update).toHaveBeenCalledTimes(1); // stop
+
+        jest.advanceTimersByTime(1000);
+        instance.setTargetDoorState(TDS.CLOSED); // retransmit / second tap
+        expect(device.update).toHaveBeenCalledTimes(1); // no extra stop, timer not pushed out
+
+        jest.advanceTimersByTime(500);
+        expect(device.update).toHaveBeenCalledTimes(2);
+        expect(device.update).toHaveBeenNthCalledWith(2, { '102': true });
+    });
+
+    test('OPEN during the wait cancels the pending close and opens instead', () => {
+        const { instance, device } = makeSimpleGarage();
+        instance.stopBeforeCloseMs = 1500;
+        device.state['105'] = STATE_OPENING_OR_OPEN;
+
+        instance.setTargetDoorState(TDS.CLOSED);
+        expect(device.update).toHaveBeenNthCalledWith(1, { '103': true }); // stop
+
+        jest.advanceTimersByTime(500);
         instance.setTargetDoorState(TDS.OPEN);
+        expect(instance.pendingCloseTimer).toBeNull();
+        expect(device.update).toHaveBeenNthCalledWith(2, { '101': true }); // open
+
+        // The trailing close must never fire.
+        jest.advanceTimersByTime(5000);
+        expect(device.update).toHaveBeenCalledTimes(2);
+    });
+
+    test('Status reports are ignored during the stop-before-close window', () => {
+        const { instance, device, accessory } = makeSimpleGarage();
+        instance.stopBeforeCloseMs = 1500;
+        device.state['105'] = STATE_OPENING_OR_OPEN;
+        instance.currentDoorState = CDS.OPEN;
+        instance.characteristicCurrentDoorState.value = CDS.OPEN;
+
         instance.setTargetDoorState(TDS.CLOSED);
+        expect(accessory.context.cachedTargetDoorState).toBe(TDS.CLOSED);
 
-        expect(device.update).not.toHaveBeenCalledWith({ '103': true });
+        // The stop makes the controller momentarily report 11 (=OPEN). That
+        // must be ignored, or it would bounce Target back to OPEN mid-close.
+        emitState(device, STATE_STOPPED);
+        expect(accessory.context.cachedTargetDoorState).toBe(TDS.CLOSED);
+        expect(instance.currentDoorState).toBe(CDS.OPEN);
+
+        // Close fires, then the controller reports 13 and we resume mirroring.
+        jest.advanceTimersByTime(1500);
+        expect(device.update).toHaveBeenNthCalledWith(2, { '102': true });
+        emitState(device, STATE_CLOSING_OR_CLOSED);
+        expect(instance.currentDoorState).toBe(CDS.CLOSED);
+        expect(accessory.context.cachedTargetDoorState).toBe(TDS.CLOSED);
+    });
+
+    test('stopBeforeCloseMs is configurable', () => {
+        const { instance, device } = makeSimpleGarage();
+        instance.stopBeforeCloseMs = 300;
+        device.state['105'] = STATE_OPENING_OR_OPEN;
+
+        instance.setTargetDoorState(TDS.CLOSED);
+        expect(device.update).toHaveBeenNthCalledWith(1, { '103': true });
+
+        jest.advanceTimersByTime(299);
+        expect(device.update).toHaveBeenCalledTimes(1);
+        jest.advanceTimersByTime(1);
+        expect(device.update).toHaveBeenNthCalledWith(2, { '102': true });
+    });
+
+    test('Custom stop/close DPs are respected in the stop-before-close path', () => {
+        const { instance, device } = makeSimpleGarage();
+        instance.dpClose = '2';
+        instance.dpStop = '4';
+        instance.stopBeforeCloseMs = 1000;
+        device.state['105'] = STATE_OPENING_OR_OPEN;
+
+        instance.setTargetDoorState(TDS.CLOSED);
+        expect(device.update).toHaveBeenNthCalledWith(1, { '4': true });
+
+        jest.advanceTimersByTime(1000);
+        expect(device.update).toHaveBeenNthCalledWith(2, { '2': true });
     });
 });
 
@@ -248,7 +388,9 @@ describe('SimpleGarageDoorAccessory — disconnected', () => {
 // ---------------------------------------------------------------------------
 describe('SimpleGarageDoorAccessory persistence', () => {
     test('Stores the latest target on the accessory context', () => {
-        const { instance, accessory } = makeSimpleGarage();
+        const { instance, device, accessory } = makeSimpleGarage();
+        // Already stopped, so the close fires immediately (no dangling timer).
+        device.state['105'] = STATE_STOPPED;
 
         instance.setTargetDoorState(TDS.OPEN);
         expect(accessory.context.cachedTargetDoorState).toBe(TDS.OPEN);
@@ -310,22 +452,28 @@ describe('SimpleGarageDoorAccessory._handlePartialOpen', () => {
         expect(device.update).toHaveBeenNthCalledWith(2, { '103': true });
     });
 
-    test('A direct open/close cancels the armed auto-stop', () => {
+    test('A direct close cancels the partial auto-stop and runs stop-before-close', () => {
         const { instance, device } = makeSimpleGarage();
         instance.partialOpenMs = 2000;
+        instance.stopBeforeCloseMs = 1500;
+        device.state['105'] = STATE_OPENING_OR_OPEN; // gate is moving during the partial
 
         instance._handlePartialOpen();
         expect(instance.partialStopTimer).not.toBeNull();
+        expect(device.update).toHaveBeenNthCalledWith(1, { '101': true }); // open
 
-        // User takes manual control before the auto-stop fires.
+        // User closes before the partial auto-stop fires.
         jest.advanceTimersByTime(500);
         instance.setTargetDoorState(TDS.CLOSED);
-        expect(instance.partialStopTimer).toBeNull();
-        expect(device.update).toHaveBeenLastCalledWith({ '102': true });
+        expect(instance.partialStopTimer).toBeNull(); // partial auto-stop cancelled
+        expect(device.update).toHaveBeenNthCalledWith(2, { '103': true }); // stop-before-close stop
 
-        // The stop must never fire now.
+        jest.advanceTimersByTime(1500);
+        expect(device.update).toHaveBeenNthCalledWith(3, { '102': true }); // close
+
+        // The cancelled partial stop never fires a stray write.
         jest.advanceTimersByTime(5000);
-        expect(device.update).not.toHaveBeenCalledWith({ '103': true });
+        expect(device.update).toHaveBeenCalledTimes(3);
     });
 
     test('Does nothing when partialOpenMs is not configured', () => {
@@ -375,8 +523,9 @@ describe('SimpleGarageDoorAccessory — force switches', () => {
         expect(accessory.context.cachedTargetDoorState).toBe(TDS.OPEN);
     });
 
-    test('Force Close fires the close action', () => {
+    test('Force Close fires the close action (immediately when already stopped)', () => {
         const { instance, device, accessory } = makeSimpleGarage();
+        device.state['105'] = STATE_STOPPED;
 
         instance.setTargetDoorState(TDS.CLOSED);
 

package/test/TuyaAccessory.protocol.test.js

@@ -10,6 +10,7 @@
 // mix of legacy paths.
 
 const crypto = require('crypto');
+const EventEmitter = require('events');
 const TuyaAccessory = require('../lib/TuyaAccessory');
 const TuyaDiscovery = require('../lib/TuyaDiscovery');
 
@@ -526,3 +527,100 @@ describe('discovery of 3.5+/3.6 devices', () => {
         expect(found[0].version).toBe('3.6');
     });
 });
+
+// Many Tuya devices (e.g. LED ceiling lights) recycle their long-lived LAN
+// sockets every few minutes, closing the connection with a TCP FIN ('end').
+// The handler must tear that connection down and reconnect promptly instead of
+// leaving a half-dead socket whose stale heartbeat timer later fires a
+// misleading ERR_PING_TIMED_OUT - which used to be the only thing that
+// triggered a reconnect.
+describe('graceful disconnect handling', () => {
+    const net = require('net');
+    let realNetSocket;
+    let createdSockets;
+
+    const makeFakeSocket = () => {
+        const s = new EventEmitter();
+        s.destroyed = false;
+        s.setKeepAlive = () => {};
+        s.setNoDelay = () => {};
+        s.connect = jest.fn();
+        s.write = jest.fn(() => true);
+        s.destroy = jest.fn(function destroy() { this.destroyed = true; });
+        return s;
+    };
+
+    beforeEach(() => {
+        jest.useFakeTimers();
+        createdSockets = [];
+        realNetSocket = net.Socket;
+        // TuyaAccessory calls net.Socket() dynamically, so swapping the property
+        // is enough to hand it a controllable fake (no real network I/O).
+        net.Socket = function FakeSocket() {
+            const s = makeFakeSocket();
+            createdSockets.push(s);
+            return s;
+        };
+    });
+
+    afterEach(() => {
+        net.Socket = realNetSocket;
+        jest.clearAllTimers();
+        jest.useRealTimers();
+    });
+
+    // Bring a device up to a steady, connected state on a fake socket.
+    const establish = device => {
+        device._connect();
+        const socket = device._socket;
+        // An established connection has already cleared its connect watchdog.
+        clearTimeout(socket._connTimeout);
+        socket._connTimeout = null;
+        device.connected = true;
+        return socket;
+    };
+
+    test("a device-initiated 'end' clears the heartbeat, tears down, and schedules a reconnect without a spurious ping timeout", () => {
+        const device = makeDevice('3.5');
+        const socket = establish(device);
+
+        // A heartbeat retry timer is in flight. With the old handler it survived
+        // the disconnect and later emitted a misleading ERR_PING_TIMED_OUT.
+        const pingErrors = [];
+        socket.on('error', err => {
+            if (err && err.message === 'ERR_PING_TIMED_OUT') pingErrors.push(err);
+        });
+        socket._pinger = setTimeout(
+            () => device._socket.emit('error', new Error('ERR_PING_TIMED_OUT')),
+            50
+        );
+
+        // The device closes the LAN connection on its own (TCP FIN -> 'end').
+        socket.emit('end');
+
+        expect(device.connected).toBe(false);
+        expect(socket._pinger).toBeNull();             // stale timer cleared
+        expect(socket.destroy).toHaveBeenCalledTimes(1); // socket torn down
+        expect(socket._errorReconnect).toBeTruthy();     // a reconnect is scheduled
+
+        // Advance well past where the leaked timer would have fired: it must not.
+        jest.advanceTimersByTime(1000);
+        expect(pingErrors).toHaveLength(0);
+
+        // The log reflects a clean disconnect, never a ping failure.
+        expect(device.log.info).toHaveBeenCalledWith('Disconnected from', device.context.name);
+        const logged = device.log.info.mock.calls.flat().join(' ');
+        expect(logged).not.toMatch(/ERR_PING_TIMED_OUT/);
+    });
+
+    test("the 'close' teardown clears any lingering heartbeat timer", () => {
+        const device = makeDevice('3.5');
+        const socket = establish(device);
+
+        socket._pinger = setTimeout(() => {}, 10000);
+        socket.emit('close');
+
+        expect(socket._pinger).toBeNull();
+        expect(device.connected).toBe(false);
+    });
+});

package/wiki/Supported-Device-Types.md

@@ -428,9 +428,12 @@ Both the current and target door state are mirrored straight from this DP, so
 HomeKit stays in sync however the gate was operated (Home app, a physical
 remote, the Tuya app, ...).
 
-A HomeKit toggle simply fires the matching action — the controller reverses
-direction on its own, so no stop-first command is needed. There is no
-obstruction detection.
+Opening is direct: the controller reverses on its own, so an open command is
+fired straight away even while the gate is closing. Closing is asymmetric — the
+controller ignores a close command while the gate is actively moving. So unless
+the status DP already reads `11` (stopped, e.g. after a partial-open or an
+external stop, where close is accepted immediately), a close is sent as
+**stop → wait `stopBeforeCloseMs` → close**. There is no obstruction detection.
 
 ```json5
 {
@@ -450,7 +453,7 @@ obstruction detection.
     "dpClose": 102,
 
     /* Override the default datapoint identifier for the stop action
-       (only used by the partial-open feature) */
+       (used by the partial-open feature and the stop-before-close) */
     "dpStop": 103,
 
     /* Override the default datapoint identifier for the reported state.
@@ -458,6 +461,12 @@ obstruction detection.
        (closing/closed) is treated as CLOSED. */
     "dpState": 105,
 
+    /* Optional. The controller ignores a close while the gate is moving,
+       so unless the state DP already reads 11 (stopped) the plugin sends
+       stop, waits this many milliseconds, then sends close. Tune to about
+       how long the gate takes to halt after a stop. Default 1500. */
+    "stopBeforeCloseMs": 1500,
+
     /* Optional. If set, exposes an extra stateful switch that mirrors
        whether the gate is currently open in HomeKit's view. Tapping it
        ON triggers a partial-open: the gate opens and then stops itself