@jay-d-tyler/homebridge-tuya 1.0.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024 Jay D. Tyler
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,155 @@
+# @jay-d-tyler/homebridge-tuya
+
+Modern [Homebridge](https://homebridge.io) plugin for [Smart Life](https://smartlife.tuya.com) and [Tuya Smart](https://www.tuya.com) devices. Supports Homebridge 1.8+ and Homebridge 2.0 with real-time MQTT updates.
+
+## Features
+
+- Optimised for **Smart Life** (also supports Tuya Smart)
+- Automatic device discovery from your linked app account
+- Real-time device status via MQTT (with polling fallback)
+- Homebridge 2.0 compatible
+- Full Homebridge Config UI X settings support
+
+### Supported Devices
+
+| Device Type | HomeKit Service | Tuya Categories |
+|---|---|---|
+| Lights | Lightbulb (On/Off, Brightness, Color Temperature, Hue, Saturation) | dj, dd, fwl, dc, xdd, fsd, tgq, tgkg |
+| Switches | Switch | kg, tdq, pc |
+| Outlets | Outlet | cz, wkcz |
+| Fans | Fan (Active, Speed, Swing) | fs |
+| Covers | Window Covering (Position, State) | cl, clkg, jdcljqr |
+| Motion Sensors | Motion Sensor | pir |
+| Contact Sensors | Contact Sensor | mcs |
+| Temperature Sensors | Temperature Sensor | wsdcg |
+| Humidity Sensors | Humidity Sensor | ldcg |
+| Smoke Sensors | Smoke Sensor | ywbj |
+| Gas Sensors | Carbon Monoxide Sensor | rqbj |
+| Leak Sensors | Leak Sensor | sj |
+
+Multi-gang switches are automatically detected and exposed as separate HomeKit switches.
+
+Combo sensors (e.g. temperature + humidity) expose multiple HomeKit services.
+
+Battery-powered sensors include battery level and low battery status.
+
+## Prerequisites
+
+You need a **Tuya IoT Platform** Cloud Project (free for personal use) linked to your **Smart Life** or **Tuya Smart** app account.
+
+> **Important:** Smart Life and Tuya Smart use separate accounts and device data. Make sure you link the same app you use to manage your devices.
+
+### Step 1: Create a Tuya Cloud Project
+
+1. Go to [iot.tuya.com](https://iot.tuya.com) and sign up / log in
+2. Navigate to **Cloud** > **Development** > **Create Cloud Project**
+3. Choose a data center matching your Smart Life app region
+4. Select **Smart Home** as the industry and development method
+5. Note your **Access ID** and **Access Secret**
+
+### Step 2: Link Your Smart Life Account
+
+1. In your Cloud Project, go to the **Devices** tab
+2. Click **Link Tuya App Account** > **Add App Account**
+3. Open the Smart Life app, go to **Profile** and tap the scan icon in the top-right corner
+4. Scan the QR code shown in the Tuya IoT Platform
+5. Your devices should now appear in the Devices list
+
+### Step 3: Enable API Services
+
+In your Cloud Project, go to **Service API** and subscribe to:
+
+- **IoT Core** (for device control)
+- **Device Status Notification** (for MQTT real-time updates)
+
+### Step 4: Find Your User ID
+
+In the Smart Life app, go to **Profile** > **Settings** > **Account and Security**. Your UID is shown at the top of the page.
+
+## Installation
+
+### Via Homebridge UI
+
+Search for `@jay-d-tyler/homebridge-tuya` in the Homebridge UI plugin search and click Install.
+
+### Via CLI
+
+```bash
+npm install -g @jay-d-tyler/homebridge-tuya
+```
+
+## Configuration
+
+### Via Homebridge UI (Recommended)
+
+After installation, click **Settings** on the plugin card in Homebridge UI. Select **Smart Life** as your app, fill in your Tuya Cloud credentials, and choose your data center region.
+
+### Manual Configuration
+
+Add to your Homebridge `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "Tuya",
+      "name": "Tuya",
+      "appType": "smartlife",
+      "accessId": "YOUR_ACCESS_ID",
+      "accessSecret": "YOUR_ACCESS_SECRET",
+      "region": "us",
+      "userId": "YOUR_USER_ID"
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+| Option | Required | Default | Description |
+|---|---|---|---|
+| `platform` | Yes | `"Tuya"` | Must be `"Tuya"` |
+| `name` | Yes | `"Tuya"` | Display name in Homebridge |
+| `appType` | Yes | `"smartlife"` | App platform: `"smartlife"` or `"tuyasmart"` |
+| `accessId` | Yes | | Tuya IoT Platform Access ID |
+| `accessSecret` | Yes | | Tuya IoT Platform Access Secret |
+| `region` | Yes | `"us"` | Data center: `us`, `eu`, `cn`, `in`, `ueaz`, `weaz` |
+| `userId` | Yes | | Your Smart Life / Tuya Smart app User ID |
+| `pollingInterval` | No | `60000` | Polling interval in ms (30000-300000). Used as fallback when MQTT is unavailable. |
+| `enableMqtt` | No | `true` | Enable MQTT for real-time updates |
+| `debug` | No | `false` | Enable verbose debug logging |
+| `deviceOverrides` | No | `[]` | Per-device overrides (see below) |
+
+### Device Overrides
+
+Override auto-detected device type, set custom names, or exclude devices:
+
+```json
+{
+  "deviceOverrides": [
+    {
+      "deviceId": "abc123...",
+      "name": "Kitchen Light",
+      "deviceType": "light"
+    },
+    {
+      "deviceId": "def456...",
+      "exclude": true
+    }
+  ]
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/jay-d-tyler/homebridge-tuya.git
+cd homebridge-tuya
+npm install
+npm run build
+npm test
+```
+
+## License
+
+Apache-2.0

package/config.schema.json

@@ -0,0 +1,162 @@
+{
+  "pluginAlias": "Tuya",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Connect your Smart Life / Tuya Smart devices to HomeKit. Requires a [Tuya IoT Platform](https://iot.tuya.com) Cloud Project linked to your Smart Life or Tuya Smart app account.",
+  "footerDisplay": "For help, see the [README](https://github.com/jay-d-tyler/homebridge-tuya#readme).",
+  "schema": {
+    "type": "object",
+    "required": ["name", "appType", "accessId", "accessSecret", "region", "userId"],
+    "properties": {
+      "name": {
+        "type": "string",
+        "title": "Platform Name",
+        "default": "Tuya"
+      },
+      "appType": {
+        "type": "string",
+        "title": "App",
+        "description": "Which app do you use to manage your devices? Smart Life is the most common. Your Tuya IoT Cloud Project must be linked to the same app.",
+        "default": "smartlife",
+        "oneOf": [
+          { "title": "Smart Life", "enum": ["smartlife"] },
+          { "title": "Tuya Smart", "enum": ["tuyasmart"] }
+        ]
+      },
+      "accessId": {
+        "type": "string",
+        "title": "Access ID",
+        "description": "Your Tuya IoT Platform Cloud Project Access ID (also called Client ID).",
+        "placeholder": "e.g. p9axw8fqr..."
+      },
+      "accessSecret": {
+        "type": "string",
+        "title": "Access Secret",
+        "description": "Your Tuya IoT Platform Cloud Project Access Secret (also called Client Secret).",
+        "placeholder": "e.g. 3b4c5d6e..."
+      },
+      "region": {
+        "type": "string",
+        "title": "Data Center Region",
+        "description": "Must match the data center selected in your Tuya IoT Platform Cloud Project.",
+        "default": "us",
+        "oneOf": [
+          { "title": "Western America", "enum": ["us"] },
+          { "title": "Central Europe", "enum": ["eu"] },
+          { "title": "Western Europe", "enum": ["weaz"] },
+          { "title": "Eastern America", "enum": ["ueaz"] },
+          { "title": "India", "enum": ["in"] },
+          { "title": "China", "enum": ["cn"] }
+        ]
+      },
+      "userId": {
+        "type": "string",
+        "title": "User ID",
+        "description": "Your Tuya app User ID. In the Smart Life app: Profile → Settings → Account and Security → UID.",
+        "placeholder": "e.g. az16..."
+      },
+      "pollingInterval": {
+        "type": "integer",
+        "title": "Polling Interval (ms)",
+        "description": "Fallback polling interval in milliseconds when MQTT is unavailable. Minimum 30000 (30 seconds).",
+        "default": 60000,
+        "minimum": 30000,
+        "maximum": 300000
+      },
+      "enableMqtt": {
+        "type": "boolean",
+        "title": "Enable MQTT Real-time Updates",
+        "description": "Use MQTT for instant device state updates instead of polling. Requires 'Device Status Notification' service enabled in your Tuya Cloud Project.",
+        "default": true
+      },
+      "debug": {
+        "type": "boolean",
+        "title": "Debug Logging",
+        "description": "Enable verbose debug logging for troubleshooting.",
+        "default": false
+      },
+      "deviceOverrides": {
+        "type": "array",
+        "title": "Device Overrides",
+        "description": "Override the auto-detected device type or exclude specific devices.",
+        "items": {
+          "type": "object",
+          "required": ["deviceId"],
+          "properties": {
+            "deviceId": {
+              "type": "string",
+              "title": "Device ID"
+            },
+            "name": {
+              "type": "string",
+              "title": "Custom Name"
+            },
+            "deviceType": {
+              "type": "string",
+              "title": "Device Type Override",
+              "oneOf": [
+                { "title": "Auto-detect", "enum": ["auto"] },
+                { "title": "Light", "enum": ["light"] },
+                { "title": "Switch", "enum": ["switch"] },
+                { "title": "Outlet", "enum": ["outlet"] },
+                { "title": "Fan", "enum": ["fan"] },
+                { "title": "Cover", "enum": ["cover"] },
+                { "title": "Motion Sensor", "enum": ["motion_sensor"] },
+                { "title": "Contact Sensor", "enum": ["contact_sensor"] },
+                { "title": "Temperature Sensor", "enum": ["temperature_sensor"] },
+                { "title": "Humidity Sensor", "enum": ["humidity_sensor"] }
+              ],
+              "default": "auto"
+            },
+            "exclude": {
+              "type": "boolean",
+              "title": "Exclude Device",
+              "default": false
+            }
+          }
+        }
+      }
+    }
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "Smart Life / Tuya Cloud Credentials",
+      "items": [
+        "name",
+        "appType",
+        "accessId",
+        "accessSecret",
+        "region",
+        "userId"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Advanced Settings",
+      "expandable": true,
+      "items": [
+        "pollingInterval",
+        "enableMqtt",
+        "debug"
+      ]
+    },
+    {
+      "type": "fieldset",
+      "title": "Device Overrides",
+      "expandable": true,
+      "items": [
+        {
+          "key": "deviceOverrides",
+          "type": "array",
+          "items": [
+            "deviceOverrides[].deviceId",
+            "deviceOverrides[].name",
+            "deviceOverrides[].deviceType",
+            "deviceOverrides[].exclude"
+          ]
+        }
+      ]
+    }
+  ]
+}

package/dist/accessories/baseAccessory.d.ts

@@ -0,0 +1,27 @@
+import type { PlatformAccessory } from 'homebridge';
+import type { TuyaPlatform } from '../platform.js';
+import type { TuyaDevice, TuyaDeviceStatus } from '../types.js';
+export declare abstract class BaseAccessory {
+    protected platform: TuyaPlatform;
+    protected accessory: PlatformAccessory;
+    protected device: TuyaDevice;
+    protected statusCache: Map<string, string | number | boolean>;
+    constructor(platform: TuyaPlatform, accessory: PlatformAccessory, device: TuyaDevice);
+    /**
+     * Get a status value from cache
+     */
+    protected getStatusValue(code: string): string | number | boolean | undefined;
+    /**
+     * Find the first supported status code from a list of candidates.
+     * Returns the first code that has a value in the status cache.
+     */
+    protected findSupportedCode(codes: string[]): string | undefined;
+    /**
+     * Update status cache and handle the update
+     */
+    protected updateStatus(statuses: TuyaDeviceStatus[]): void;
+    /**
+     * Abstract method to be implemented by subclasses
+     */
+    protected abstract handleStatusUpdate(): void;
+}

package/dist/accessories/baseAccessory.js

@@ -0,0 +1,50 @@
+'use strict';
+export class BaseAccessory {
+    platform;
+    accessory;
+    device;
+    statusCache;
+    constructor(platform, accessory, device) {
+        this.platform = platform;
+        this.accessory = accessory;
+        this.device = device;
+        this.statusCache = new Map();
+        // Initialize cache from device status
+        for (const status of device.status) {
+            this.statusCache.set(status.code, status.value);
+        }
+        // Listen for real-time status updates
+        this.platform.on('deviceStatusUpdate', (deviceId, statuses) => {
+            if (deviceId === this.device.id) {
+                this.updateStatus(statuses);
+            }
+        });
+    }
+    /**
+     * Get a status value from cache
+     */
+    getStatusValue(code) {
+        return this.statusCache.get(code);
+    }
+    /**
+     * Find the first supported status code from a list of candidates.
+     * Returns the first code that has a value in the status cache.
+     */
+    findSupportedCode(codes) {
+        for (const code of codes) {
+            if (this.getStatusValue(code) !== undefined) {
+                return code;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Update status cache and handle the update
+     */
+    updateStatus(statuses) {
+        for (const status of statuses) {
+            this.statusCache.set(status.code, status.value);
+        }
+        this.handleStatusUpdate();
+    }
+}

package/dist/accessories/coverAccessory.d.ts

@@ -0,0 +1,22 @@
+import type { PlatformAccessory } from 'homebridge';
+import type { TuyaPlatform } from '../platform.js';
+import type { TuyaDevice } from '../types.js';
+import { BaseAccessory } from './baseAccessory.js';
+export declare class CoverAccessory extends BaseAccessory {
+    private service;
+    private positionCode;
+    private controlCode;
+    constructor(platform: TuyaPlatform, accessory: PlatformAccessory, device: TuyaDevice);
+    /**
+     * Find the position control code
+     */
+    private findPositionCode;
+    /**
+     * Find the control code (open/close/stop)
+     */
+    private findControlCode;
+    private setupTargetPosition;
+    private setupCurrentPosition;
+    private setupPositionState;
+    protected handleStatusUpdate(): void;
+}