homebridge-tuya-plus 3.13.1-dev.1 → 3.14.0-alpha.1

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

@@ -1,45 +1,97 @@
-name: Publish dev to npm
+name: Publish to npm (dev + PR test builds)
 
-# Publishes every commit on `main` to npm under the `dev` dist-tag.
+# This workflow publishes two kinds of UNSTABLE builds to npm. Stable releases
+# always live on the `latest` dist-tag and are cut manually; nothing here ever
+# touches `latest`.
 #
-# 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.
+# 1. Dev builds (automatic) — every push to `main`:
+#      * Published under the `dev` dist-tag.
+#      * Versioned as <next-minor>.0-dev.<run-number> (e.g. 3.14.0-dev.42).
+#        package.json at 3.13.0 -> dev builds target 3.14.0. In semver these
+#        sort below the eventual 3.14.0 release, so `latest` always wins.
+#      * Release commits are skipped: if a push changes package.json's version
+#        (you bumped it to cut a real release), no dev build is published.
 #
-# One-time setup required for this to succeed (see PR/commit notes):
+# 2. PR test builds (manual) — a maintainer comments `/publish` on a PR:
+#      * Published under a PR-specific `pr-<N>` dist-tag (e.g. pr-57), with a
+#        unique version <next-minor>.0-pr.<N>.<run-number> (e.g. 3.14.0-pr.57.43).
+#      * Lets you install and try an unmerged PR on real hardware without
+#        disturbing `latest` OR `dev`:  npm i -g homebridge-tuya-plus@pr-57
+#      * Cleanup is a token-free local step: run `npm run cleanup:pr-tags` to
+#        delete the `pr-<N>` tags of merged/closed PRs (uses your npm login).
+#        OIDC can't manage dist-tags, so this is intentionally not a CI job.
+#      * Triggered ONLY by someone with push (write) access to the repo — the
+#        owner and any write/maintain/admin collaborator. A drive-by `/publish`
+#        from an outside PR author (no push access) does nothing.
+#
+# Why a separate `pr-<N>` tag instead of reusing `dev`: `dev` is a moving
+# channel users follow to get "latest main". Publishing unmerged PR code there
+# would feed untested code to everyone on `@dev`. A per-PR tag keeps three clear
+# lanes — `latest` (everyone), `dev` (main followers), `pr-<N>` (that one PR).
+#
+# ---------------------------------------------------------------------------
+# 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 token that npm only accepts when its
+#     claims match THIS repo + THIS workflow file (publish-dev.yml) + the
+#     `npm-dev` environment. There is no durable credential to exfiltrate.
+#   * npm allows only ONE trusted publisher per package, so BOTH paths must run
+#     from this file and use `environment: npm-dev` to authenticate. (The PR
+#     path needs no extra npm/GitHub setup beyond the existing dev config.)
+#   * The `dev` path never runs on `pull_request`; the PR path runs on
+#     `issue_comment`, which always uses the workflow file from `main` — a PR
+#     cannot alter this file to change what runs.
+#   * Untrusted PR code is fenced off from the publishing credential:
+#       - `pr-test` checks out and runs the PR's code (npm ci / lint / test)
+#         but is UNPRIVILEGED: `contents: read`, no secrets, no id-token, and
+#         `persist-credentials: false`. Same blast radius as ordinary fork CI.
+#       - `pr-publish` HOLDS the OIDC permission but runs NO PR code: no
+#         `npm ci`, no build, no tests, and `--ignore-scripts` on both
+#         `npm version` and `npm publish`, so no lifecycle script executes
+#         while the credential is present. It only packs + uploads the tarball.
+#       - The OIDC token is scoped to THIS package, so a PR that renames the
+#         package in package.json cannot hijack a different one (publish fails).
+#       - The head SHA is resolved once, up front, and pinned for every later
+#         job, so a push landed after `/publish` cannot swap in different code.
+#   * Comment/reaction jobs use a write-scoped token but check out NO PR code.
+#
+# ---------------------------------------------------------------------------
+# One-time setup (already in place for the dev path; PR path reuses it):
 #   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).
+#   2. GitHub repo Settings -> Environments -> `npm-dev`, deployment branches
+#      restricted to `main` (optional: required reviewer). The PR path runs on
+#      `main`'s ref too, so this restriction is satisfied for both paths.
 
 on:
   push:
     branches: [main]
   workflow_dispatch:
+  # Maintainer types `/publish` on a PR to cut a test build of that PR.
+  issue_comment:
+    types: [created]
 
-# Least privilege by default; only the publish job opts into id-token.
+# Least privilege by default; jobs opt into more only where needed.
 permissions:
   contents: read
 
-# Don't cancel an in-flight publish; let each commit publish its version.
+# Serialize per lane, never cancel an in-flight publish: `publish-dev` for the
+# dev path, `publish-pr-<N>` per PR for the PR path (so they don't block).
 concurrency:
-  group: publish-dev
+  group: ${{ github.event_name == 'issue_comment' && format('publish-pr-{0}', github.event.issue.number) || 'publish-dev' }}
   cancel-in-progress: false
 
 jobs:
+  # ===========================================================================
+  # DEV PATH — push to main / manual dispatch. (Behavior unchanged.)
+  # ===========================================================================
   test:
+    if: github.event_name != 'issue_comment'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -50,8 +102,61 @@ jobs:
       - 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:
+    if: github.event_name != 'issue_comment'
+    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
+    needs: [test, prepare]
+    # Dev path only, and skip release commits (version bumped in this push).
+    if: github.event_name != 'issue_comment' && 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.
@@ -71,17 +176,9 @@ jobs:
       - name: Ensure OIDC-capable npm
         run: npm install -g npm@latest
 
-      - name: Compute dev version
-        id: ver
-        run: |
-          NEXT="$(node -e "const v=require('./package.json').version.split('.'); v[2]=Number(v[2])+1; console.log(v.join('.'))")"
-          VERSION="${NEXT}-dev.${GITHUB_RUN_NUMBER}"
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "Will publish $VERSION"
-
       # Writes package.json on the runner only; nothing is committed.
       - name: Set version
-        run: npm version "${{ steps.ver.outputs.version }}" --no-git-tag-version --allow-same-version --ignore-scripts
+        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.
@@ -89,3 +186,236 @@ jobs:
       # --provenance attaches a signed build attestation (needs a public repo).
       - name: Publish (dev tag)
         run: npm publish --tag dev --provenance --ignore-scripts
+
+  # ===========================================================================
+  # PR PATH — maintainer comments `/publish` on a PR. (New.)
+  # ===========================================================================
+
+  # Gate + ack. Runs NO PR code. Verifies the commenter is a maintainer,
+  # resolves & pins the PR head, and reads the version base from trusted `main`.
+  authorize:
+    if: >
+      github.event_name == 'issue_comment' &&
+      github.event.issue.pull_request &&
+      startsWith(github.event.comment.body, '/publish') &&
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # checkout main to read the version base
+      issues: write # react to / comment on the triggering comment
+      pull-requests: write
+    outputs:
+      authorized: ${{ steps.auth.outputs.authorized }}
+      head_sha: ${{ steps.auth.outputs.head_sha }}
+      head_repo: ${{ steps.auth.outputs.head_repo }}
+      pr_number: ${{ steps.auth.outputs.pr_number }}
+      base_version: ${{ steps.basever.outputs.base_version }}
+    steps:
+      - name: Verify maintainer & resolve PR head
+        id: auth
+        uses: actions/github-script@v7
+        with:
+          script: |
+            // Require the command to be exactly `/publish` (optional trailing text).
+            const body = (context.payload.comment.body || '').trim();
+            if (!/^\/publish(?:\s|$)/.test(body)) {
+              core.setOutput('authorized', 'false');
+              return;
+            }
+            // Authorization: the commenter must have PUSH (write) access. The
+            // REST `permission` field uses legacy roles, so `admin`/`write`
+            // covers admin/maintain/write (can push) and excludes triage/read.
+            // This is stricter and truer to intent than author_association (a
+            // COLLABORATOR could be read-only). The job `if` is only a coarse
+            // pre-filter; this API check is the authoritative gate.
+            const username = context.payload.comment.user.login;
+            let canPush = false;
+            try {
+              const { data: perm } = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                username,
+              });
+              canPush = ['admin', 'write'].includes(perm.permission);
+              core.info(`${username} permission: ${perm.permission} (role: ${perm.role_name || 'n/a'})`);
+            } catch (err) {
+              // If the permission API can't be read, fall back to the trusted
+              // author_association set so a maintainer is never locked out. This
+              // still keeps out drive-by PR authors (CONTRIBUTOR / NONE).
+              const assoc = context.payload.comment.author_association;
+              canPush = ['OWNER', 'MEMBER', 'COLLABORATOR'].includes(assoc);
+              core.warning(`Permission API unavailable (${err.status || err.message}); fell back to association ${assoc}.`);
+            }
+            if (!canPush) {
+              core.notice(`Ignoring /publish from ${username}: no push access.`);
+              core.setOutput('authorized', 'false');
+              return;
+            }
+            // Resolve the PR's CURRENT head and pin this exact SHA for every
+            // later job, so a push landed after `/publish` can't swap in code.
+            const { data: pr } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.issue.number,
+            });
+            if (!pr.head.repo) {
+              core.setFailed('PR head repository is unavailable (fork deleted?).');
+              core.setOutput('authorized', 'false');
+              return;
+            }
+            core.setOutput('head_sha', pr.head.sha);
+            core.setOutput('head_repo', pr.head.repo.full_name);
+            core.setOutput('pr_number', String(pr.number));
+            core.setOutput('authorized', 'true');
+            // Acknowledge so the maintainer sees the command was accepted.
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: 'eyes',
+            });
+
+      # Version base comes from TRUSTED main, never the PR's package.json, so an
+      # untrusted PR cannot influence the published version.
+      - name: Checkout main (trusted)
+        if: steps.auth.outputs.authorized == 'true'
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Compute version base from main
+        id: basever
+        if: steps.auth.outputs.authorized == 'true'
+        run: |
+          NEXT="$(node -e "const v=require('./package.json').version.split('.'); v[1]=Number(v[1])+1; v[2]=0; console.log(v.join('.'))")"
+          echo "base_version=$NEXT" >> "$GITHUB_OUTPUT"
+          echo "Version base (from main): $NEXT"
+
+  # Unprivileged gate: runs the PR's code. No secrets, read-only token, no
+  # id-token, no persisted git credentials — same trust level as fork CI.
+  pr-test:
+    needs: authorize
+    if: needs.authorize.outputs.authorized == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ needs.authorize.outputs.head_repo }}
+          ref: ${{ needs.authorize.outputs.head_sha }}
+          persist-credentials: false
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run test
+
+  # Privileged publish. Holds the OIDC permission but runs NO PR code: no
+  # npm ci, no build, no tests; --ignore-scripts on version + publish.
+  pr-publish:
+    needs: [authorize, pr-test]
+    if: needs.authorize.outputs.authorized == 'true'
+    runs-on: ubuntu-latest
+    # Must match the trusted publisher's environment (npm allows one publisher
+    # per package). issue_comment runs on main's ref, so a main-only branch
+    # restriction on this environment is satisfied.
+    environment: npm-dev
+    permissions:
+      contents: read
+      id-token: write # OIDC -> npm Trusted Publishing (no stored token)
+    outputs:
+      version: ${{ steps.ver.outputs.version }}
+      tag: ${{ steps.ver.outputs.tag }}
+    steps:
+      # The PR's code — but we never execute it (see --ignore-scripts below).
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ needs.authorize.outputs.head_repo }}
+          ref: ${{ needs.authorize.outputs.head_sha }}
+          persist-credentials: false
+
+      - 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
+
+      # Unique, immutable version + a PR-specific dist-tag. Base comes from main
+      # (via authorize), so the PR's package.json cannot influence versioning.
+      - name: Compute PR build version + tag
+        id: ver
+        env:
+          BASE: ${{ needs.authorize.outputs.base_version }}
+          PR: ${{ needs.authorize.outputs.pr_number }}
+        run: |
+          VERSION="${BASE}-pr.${PR}.${GITHUB_RUN_NUMBER}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=pr-${PR}" >> "$GITHUB_OUTPUT"
+          echo "Will publish $VERSION under dist-tag pr-${PR}"
+
+      # Writes package.json on the runner only; --ignore-scripts so no PR
+      # version/preversion/postversion hook runs with the credential present.
+      - name: Set version
+        run: npm version "${{ steps.ver.outputs.version }}" --no-git-tag-version --allow-same-version --ignore-scripts
+
+      # Published under pr-<N>, NEVER latest/dev. No NODE_AUTH_TOKEN: npm
+      # exchanges the OIDC id-token for a short-lived, package-scoped credential.
+      # --ignore-scripts ensures no PR lifecycle script runs with that credential.
+      - name: Publish (pr-<N> tag)
+        run: npm publish --tag "${{ steps.ver.outputs.tag }}" --provenance --ignore-scripts
+
+  # Report the outcome back on the PR. Runs NO PR code.
+  notify:
+    needs: [authorize, pr-publish]
+    if: always() && needs.authorize.outputs.authorized == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/github-script@v7
+        env:
+          PUBLISH_RESULT: ${{ needs.pr-publish.result }}
+          PR_NUMBER: ${{ needs.authorize.outputs.pr_number }}
+          HEAD_SHA: ${{ needs.authorize.outputs.head_sha }}
+          VERSION: ${{ needs.pr-publish.outputs.version }}
+          TAG: ${{ needs.pr-publish.outputs.tag }}
+        with:
+          script: |
+            const { PUBLISH_RESULT, PR_NUMBER, HEAD_SHA, VERSION, TAG } = process.env;
+            const issue_number = Number(PR_NUMBER);
+            const comment_id = context.payload.comment.id;
+            const { owner, repo } = context.repo;
+            const runUrl = `${context.serverUrl}/${owner}/${repo}/actions/runs/${context.runId}`;
+            if (PUBLISH_RESULT === 'success') {
+              const sha = (HEAD_SHA || '').slice(0, 7);
+              const body = [
+                `🚀 Published this PR to npm for testing — built from \`${sha}\`.`,
+                ``,
+                `**Install this exact build:**`,
+                '```sh',
+                `npm install -g homebridge-tuya-plus@${VERSION}`,
+                '```',
+                `**…or follow this PR's tag** (always points at this PR's newest \`/publish\` build):`,
+                '```sh',
+                `npm install -g homebridge-tuya-plus@${TAG}`,
+                '```',
+                ``,
+                `In the Homebridge UI you can also paste \`${VERSION}\` into the plugin's “Install Alternate Version” field.`,
+                ``,
+                `> ℹ️ Prerelease for testing only — **not** tagged \`latest\` or \`dev\`, so it won't reach normal installs.`,
+              ].join('\n');
+              await github.rest.issues.createComment({ owner, repo, issue_number, body });
+              await github.rest.reactions.createForIssueComment({ owner, repo, comment_id, content: 'rocket' });
+            } else {
+              await github.rest.issues.createComment({
+                owner, repo, issue_number,
+                body: `❌ \`/publish\` did not complete — the build, tests, or publish step failed. See the [run logs](${runUrl}).`,
+              });
+              await github.rest.reactions.createForIssueComment({ owner, repo, comment_id, content: 'confused' });
+            }

package/Changelog.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file. This project uses [semantic versioning](https://semver.org/).
 
+## Unreleased
+
+* [+] **Tuya Cloud support for devices that can't be reached over the LAN** — most notably battery-powered "sleepy" irrigation/sprinkler timers, which sleep almost all the time and only ever talk to Tuya's cloud, so the local protocol can never reach them. The plugin stays LAN-first: cloud is strictly opt-in. Add a top-level `cloud` credentials block (or a per-device `cloud` object) and set `"cloud": true` on the device.
+  * Realtime updates arrive over Tuya's **MQTT** message service (via the optional `mqtt` dependency, installed automatically); initial state and control use the Tuya OpenAPI. There is no polling.
+  * Works with both **Custom** and **Smart Home** Cloud projects (the latter via app-account login).
+  * The existing **IrrigationSystem** accessory works unchanged over the cloud — its data-points are simply addressed by Tuya "code" (e.g. `switch_1`, `battery_percentage`) instead of a numeric id; the device logs its codes on startup. Battery-only controllers with no rain sensor: set `"noRainSensor": true`.
+  * See the wiki: **[Tuya Cloud Setup](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)**.
+* [*] **IrrigationSystem: add the HAP Service Label service for multi-valve controllers** — an accessory that exposes a collection of same-type services (more than one `Valve`) must include a `ServiceLabel` service to anchor each valve's `ServiceLabelIndex`. It was missing, so stricter Home app clients (notably iOS) scattered the zones as separate tiles instead of nesting them under the single irrigation tile. The service is added automatically (with the Arabic-numerals namespace) whenever there is more than one valve; user-set zone names still take precedence.
+* [*] **Fix realtime (MQTT) cloud updates being silently dropped** — external changes (physical buttons, the Tuya app, the device's own timers) now show up in HomeKit within a second or two. The decryptor was verifying the AES-GCM auth tag (`decipher.final()`), but Tuya's real status frames don't carry a tag that verifies against the documented AAD, so every realtime message was being thrown away. Now decrypts with `update()` only, matching the official `tuya/tuya-homebridge` and `0x5e/homebridge-tuya-platform` implementations.
+* [*] **Fix cloud irrigation valves that could be turned on but not off** — the per-zone write coalescer was dropping any command that matched the last-known `device.state`. Cloud devices never optimistically advance `state` (it only moves once the realtime stream confirms the device), so an "off" issued before the "on" was echoed matched the stale "off" and was discarded — HomeKit showed the zone closed while it kept running. Queued commands are now sent as-is (callers already queue only genuine changes).
+
 ## 2.0.1 (2021-03-25)
 This update includes the following changes:
 

package/Readme.MD

@@ -69,6 +69,14 @@ Protocol **3.5** is currently the newest Tuya LAN protocol in existence: it is t
 
 This plugin is nevertheless **3.6-ready**: if a device reports a newer protocol version (e.g. `3.6`) in its broadcast, the plugin automatically talks to it using the newest (3.5/GCM) protocol stack while tagging payloads with the device's reported version — the same forward-compatibility strategy used by tinytuya. Should such a device misbehave, you can pin it to a specific protocol with the `forceVersion` device option (e.g. `"forceVersion": "3.5"`), or use `version` to set a protocol for devices that can't be discovered (e.g. on another subnet).
 
+## Cloud devices (for hardware that can't be controlled locally)
+
+This is a **LAN-first** plugin — virtually every Tuya device is controlled locally, which is faster, more private, and keeps working without internet. A few devices, though, simply **can't** be reached over the LAN: battery-powered "sleepy" devices — for example the **irrigation / faucet timers** — sleep almost all the time and only ever connect out to Tuya's cloud, so they never answer on the local network.
+
+For exactly these cases the plugin can talk to a device through the **Tuya Cloud** instead — strictly **opt-in, per device**. You add your Tuya Cloud project credentials once and set `"cloud": true` on the device; everything else works the same.
+
+👉 **[Tuya Cloud Setup guide](https://github.com/adrianjagielak/homebridge-tuya-plus/blob/main/wiki/Tuya-Cloud-Setup.md)** — how to get credentials and configure a cloud device.
+
 ## Installation Instructions
 
 #### Option 1: Install via Homebridge Config UI X:
@@ -91,9 +99,23 @@ 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
+These are versioned like `3.14.0-dev.<n>` and may be unstable; use the default
 install above for production.
 
+#### Testing a specific pull request:
+
+Maintainers can publish an unmerged PR as a throwaway test build by commenting
+`/publish` on it. The build goes to its own `pr-<number>` tag — never `latest`
+or `dev` — so it never reaches normal installs. The bot replies on the PR with
+the exact install command, e.g.:
+
+```
+sudo npm install -g homebridge-tuya-plus@pr-57
+```
+
+Each build also gets a unique, immutable version like `3.14.0-pr.57.<n>` that you
+can pin or paste into the Homebridge UI's "Install Alternate Version" field.
+
 ## Configuration
 > UI
 

package/config.schema.json

@@ -19,12 +19,71 @@
         "placeholder": "Timeout (millisecond) for device IP address discovery",
         "default": 60000
       },
+      "cloud": {
+        "type": "object",
+        "title": "Tuya Cloud (optional — only for devices that can't be reached over the LAN)",
+        "description": "This plugin is LAN-first. A few devices — notably battery-powered 'sleepy' irrigation timers — sleep most of the time and only ever talk to Tuya's cloud, so they cannot be controlled locally. Create a free Cloud project at iot.tuya.com, enter its credentials here, then tick 'Control via Tuya Cloud' on each such device. See the wiki for step-by-step setup.",
+        "properties": {
+          "accessId": {
+            "type": "string",
+            "title": "Access ID / Client ID"
+          },
+          "accessKey": {
+            "type": "string",
+            "title": "Access Secret / Client Secret"
+          },
+          "region": {
+            "type": "string",
+            "title": "Data center / region",
+            "default": "us",
+            "description": "Must match the region your Tuya / Smart Life app account is registered in.",
+            "oneOf": [
+              { "title": "Central Europe", "enum": ["eu"] },
+              { "title": "Western Europe (Azure)", "enum": ["eu-w"] },
+              { "title": "Western America", "enum": ["us"] },
+              { "title": "Eastern America (Azure)", "enum": ["us-e"] },
+              { "title": "China", "enum": ["cn"] },
+              { "title": "India", "enum": ["in"] },
+              { "title": "Singapore", "enum": ["sg"] }
+            ]
+          },
+          "username": {
+            "type": "string",
+            "title": "App account email/phone (Smart Home projects only)",
+            "description": "For 'Smart Home' Cloud projects: the Tuya / Smart Life app account that owns the devices. Leave blank for 'Custom' projects (which link devices by QR scan)."
+          },
+          "password": {
+            "type": "string",
+            "title": "App account password (Smart Home projects only)"
+          },
+          "countryCode": {
+            "type": "string",
+            "title": "Country calling code (Smart Home projects only)",
+            "placeholder": "e.g. 1, 44, 48"
+          },
+          "schema": {
+            "type": "string",
+            "title": "App (Smart Home projects only)",
+            "default": "tuyaSmart",
+            "oneOf": [
+              { "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."
+          }
+        }
+      },
       "devices": {
         "type": "array",
         "orderable": false,
         "items": {
           "type": "object",
-          "required": ["type", "name", "id", "key"],
+          "required": ["type", "name", "id"],
           "properties": {
             "type": {
               "type": "string",
@@ -136,8 +195,18 @@
               }
             },
             "key": {
-              "title": "Tuya Key",
+              "title": "Tuya Key (local key — required for LAN devices)",
               "type": "string",
+              "description": "The device's local key. Required for normal (LAN) devices. Not needed for cloud devices (tick 'Control via Tuya Cloud' below).",
+              "condition": {
+                "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
+              }
+            },
+            "cloud": {
+              "type": ["boolean", "object"],
+              "title": "Control via Tuya Cloud (instead of the LAN)",
+              "default": false,
+              "description": "Enable for devices that can't be reached locally (e.g. battery-powered irrigation timers). Uses the platform-level 'cloud' credentials above. Advanced: instead of a checkbox you can set this to an object with per-device { accessId, accessKey, region, … } to use different credentials for this one device.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices].type !== 'null';"
               }
@@ -648,7 +717,7 @@
               "type": "integer",
               "title": "Number of Valves / Zones",
               "placeholder": 4,
-              "description": "How many valves/zones the controller has. They are assumed to be on data-points 1, 2, 3, … For non-sequential data-points use the 'valves' list instead.",
+              "description": "How many valves/zones the controller has. They are assumed to be on data-points 1, 2, 3, … (or, for cloud devices, on the codes switch_1, switch_2, …). For non-sequential data-points use the 'valves' list instead.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type);"
               }
@@ -662,7 +731,7 @@
                 "type": "object",
                 "properties": {
                   "name": { "type": "string", "title": "Zone name", "placeholder": "Lawn" },
-                  "dp": { "type": "integer", "title": "Data-point", "placeholder": 1 },
+                  "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 }
                 }
               },
@@ -724,9 +793,9 @@
               }
             },
             "dpBattery": {
-              "type": "integer",
-              "placeholder": 46,
-              "title": "Battery data-point",
+              "type": ["integer", "string"],
+              "placeholder": "46 or battery_percentage",
+              "title": "Battery data-point (numeric id, or cloud code)",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noBattery;"
               }
@@ -741,9 +810,9 @@
               }
             },
             "dpCharging": {
-              "type": "integer",
-              "placeholder": 101,
-              "title": "Charging-status data-point",
+              "type": ["integer", "string"],
+              "placeholder": "101 or charge_state",
+              "title": "Charging-status data-point (numeric id, or cloud code)",
               "description": "Boolean data-point reporting whether the battery is charging (e.g. solar / USB-C units). HomeKit shows Charging / Not Charging; if your controller doesn't report this, it shows Not Chargeable.",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noBattery;"
@@ -778,9 +847,9 @@
               }
             },
             "dpRain": {
-              "type": "integer",
-              "placeholder": 49,
-              "title": "Rain sensor data-point",
+              "type": ["integer", "string"],
+              "placeholder": "49 or rain_sensor_state",
+              "title": "Rain sensor data-point (numeric id, or cloud code)",
               "condition": {
                 "functionBody": "return model.devices && model.devices[arrayIndices] && ['IrrigationSystem'].includes(model.devices[arrayIndices].type) && !model.devices[arrayIndices].noRainSensor;"
               }