@homebridge-plugins/homebridge-tuya 3.0.0-beta.2 → 3.0.0-beta.21

package/README.md

@@ -1,9 +1,11 @@
 # @homebridge-plugins/homebridge-tuya
 
+<div align="center">
+
 [![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=for-the-badge&logoColor=%23FFFFFF&logo=homebridge)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
 
 ![node](https://badgen.net/npm/node/@homebridge-plugins/homebridge-tuya)
-![homebridge](https://img.shields.io/github/package-json/dependency-version/homebridge-plugins/homebridge-tuya/dev/homebridge)
+![homebridge](https://img.shields.io/github/package-json/dependency-version/homebridge-plugins/homebridge-tuya/peer/homebridge)
 
 [![Sponsor](https://img.shields.io/badge/Sponsor-❤-ff69b4)](https://github.com/sponsors/tassy-h)
 [![version](https://badgen.net/npm/v/@homebridge-plugins/homebridge-tuya)](https://npmjs.com/package/@homebridge-plugins/homebridge-tuya)
@@ -12,106 +14,77 @@
 [![mit-license](https://badgen.net/npm/license/@homebridge-plugins/homebridge-tuya)](https://github.com/homebridge-plugins/homebridge-tuya/blob/main/LICENSE)
 [![Build and Lint](https://github.com/homebridge-plugins/homebridge-tuya/actions/workflows/build.yml/badge.svg)](https://github.com/homebridge-plugins/homebridge-tuya/actions/workflows/build.yml)
 
-Unified Homebridge plugin for Tuya smart devices — supports **Tuya Cloud** (REST/MQTT) and **Tuya Local** (direct LAN/TCP) communication, or both simultaneously.
+**A unified Homebridge plugin for Tuya smart devices**
 
----
+Supports **Tuya Cloud** (REST/MQTT) and **Tuya Local** (direct LAN/TCP) communication — or both simultaneously.
 
-## Features
+</div>
 
-- **Three connection modes**: Cloud, Local (LAN), or Both simultaneously.
-- Optimized and improved code for better readability and maintainability.
-- Enhanced stability and reduced API errors.
-- Local LAN communication using the Tuya local protocol (v3.1–v3.5), no cloud connection required.
-- Automatic UDP device discovery on the local network.
-- Supports Tuya Scenes (Tap-to-Run) in Cloud mode.
-- Device configuration overrides for non-standard DPs.
-- Supports 60+ device categories including lights, switches, sensors, cameras, locks, IR remotes, and more.
+---
 
+## Overview
 
-## Supported Tuya Devices
-See [SUPPORTED_DEVICES.md](./SUPPORTED_DEVICES.md)
+This plugin integrates Tuya smart home devices with Apple HomeKit through Homebridge. Choose your connection method based on your needs:
 
+| Mode | Features | Requirements |
+|------|----------|--------------|
+| **Cloud** | Full features, remote access, scenes, automations | Tuya IoT account, internet |
+| **Local** | Fast response, no cloud dependency, privacy-focused | Devices & Homebridge on same network |
+| **Both** | Best of both worlds — local-first with cloud fallback | Both configurations |
 
-## Changelogs
-See [CHANGELOG.md](./CHANGELOG.md)
+**Supports 60+ device categories**: Lights, switches, sockets, outlets, fans, air conditioners, thermostats, door locks, cameras, sensors, garage doors, curtains, and more.
 
+---
 
-## Installation
+## Quick Features
 
-#### Homebridge Web UI
-Search for `@homebridge-plugins/homebridge-tuya` on the Plugins page and install it.
+✅ **Three connection modes** — Cloud, Local, or Both simultaneously  
+✅ **60+ device categories** — Comprehensive device support  
+✅ **Automatic discovery** — UDP broadcast discovery for local devices  
+✅ **Tuya Scenes** — Support for Tap-to-Run scenes in Cloud mode  
+✅ **Protocol support** — Tuya local protocol v3.1–v3.5  
+✅ **Device overrides** — Custom schema mapping for non-standard devices  
+✅ **Adaptive Lighting** — Supported on compatible light accessories  
+✅ **Enhanced stability** — Optimized code, reduced API errors  
 
-#### Command Line
-```
-npm install @homebridge-plugins/homebridge-tuya
-```
+---
 
+## Installation
 
-## Configuration
+### Homebridge Web UI (Recommended)
 
-### Connection Mode
+1. Open Homebridge UI
+2. Go to **Plugins** page
+3. Search for `@homebridge-plugins/homebridge-tuya`
+4. Click **Install**
+5. Configure using the Settings UI
 
-Set `mode` in your config to one of:
+### Command Line
 
-| Mode | Description |
-|------|-------------|
-| `cloud` | Connect via Tuya Cloud API (default, backward-compatible) |
-| `local` | Connect directly over LAN — no cloud needed |
-| `both`  | Cloud + Local simultaneously |
+```bash
+npm install @homebridge-plugins/homebridge-tuya
+```
 
 ---
 
-### Cloud Mode (`mode: "cloud"`)
-
-Requires a [Tuya IoT Platform](https://iot.tuya.com) account and cloud project:
+## Getting Started
 
-1. Create a cloud project and select your data center. See [Mappings Between OEM App Accounts and Data Centers](https://developer.tuya.com/en/docs/iot/oem-app-data-center-distributed?id=Kafi0ku9l07qb).
-2. On the Project Page > Devices Panel > Link Tuya App Account, link your Tuya app account.
-3. On the Project Page > Service API > Go to Authorize, subscribe to:
-   - Authorization Token Management
-   - Device Status Notification
-   - IoT Core
-   - IoT Video Live Stream *(for cameras)*
-   - Industry Project Client Service *(Custom project only)*
-   - IR Control Hub Open Service *(for IR devices)*
-   - Smart Home Scene Linkage *(for scenes)*
-   - Smart Lock Open Service *(for locks)*
-4. **⚠️ Extend the API trial every 6 months** at [IoT Core Cloud Services](https://iot.tuya.com/cloud/products/detail?abilityId=1442730014117204014&id=p1668587814138nv4h3n&abilityAuth=0&tab=1).
+### Step 1: Choose Your Connection Mode
 
-There are two project types:
+Decide between **Cloud**, **Local**, or **Both**:
 
-#### Custom Project (`options.projectType: "1"`)
+- **Cloud only**: Easiest setup, works remotely, but relies on internet
+- **Local only**: Fastest response, no cloud dependency, but limited features
+- **Both**: Recommended — local commands first, cloud as fallback
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `options.projectType` | ✅ | `"1"` |
-| `options.endpoint` | ✅ | Endpoint URL from [API Reference > Endpoints](https://developer.tuya.com/en/docs/iot/api-request?id=Ka4a8uuo1j4t4#title-1-Endpoints) |
-| `options.accessId` | ✅ | Access ID from [Tuya IoT Platform](https://iot.tuya.com/cloud) |
-| `options.accessKey` | ✅ | Access Secret from [Tuya IoT Platform](https://iot.tuya.com/cloud) |
-| `options.debug` | ➖ | Enable debug logging (default: `false`) |
-| `options.debugLevel` | ➖ | Comma-separated log filter: `api`, `mqtt`, or a device ID |
+### Step 2: Configuration
 
-#### Smart Home Project (`options.projectType: "2"`)
+Configuration uses the Homebridge Web UI or `config.json`. See [Configuration Guide](./docs/CONFIG_GUIDE.md) for detailed setup instructions.
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `options.projectType` | ✅ | `"2"` |
-| `options.accessId` | ✅ | Access ID |
-| `options.accessKey` | ✅ | Access Secret |
-| `options.countryCode` | ✅ | Country code of your app account's region |
-| `options.username` | ✅ | Tuya/Smart Life app username |
-| `options.password` | ✅ | App password (MD5 salted hash also accepted) |
-| `options.appSchema` | ✅ | `"tuyaSmart"` or `"smartlife"` |
-| `options.endpoint` | ➖ | Override endpoint (auto-detected from countryCode) |
-| `options.homeWhitelist` | ➖ | Array of Home IDs to include; blank = all homes |
-| `options.debug` | ➖ | Enable debug logging (default: `false`) |
-| `options.debugLevel` | ➖ | Comma-separated log filter |
-
-**Example cloud config:**
+**Quick example (Cloud mode):**
 ```json
 {
   "platform": "TuyaPlatform",
-  "name": "Tuya",
   "mode": "cloud",
   "options": {
     "projectType": "2",
@@ -125,112 +98,351 @@ There are two project types:
 }
 ```
 
+**Quick example (Local mode):**
+```json
+{
+  "platform": "TuyaPlatform",
+  "mode": "local",
+  "local": {
+    "autoDiscoverDevices": true,
+    "discoverTimeout": 5
+  }
+}
+```
+
 ---
 
-### Local Mode (`mode: "local"`)
+## Configuration Modes
+
+### Cloud Mode
 
-Communicates directly with your Tuya devices over LAN — no internet or Tuya Cloud account required after initial key retrieval.
+Connect via Tuya Cloud API with full feature support.
 
 **Requirements:**
-- Your Homebridge host and Tuya devices must be on the same network.
-- Each device's **local key** (16-character AES key). You can retrieve your local keys from the [Tuya IoT Platform](https://iot.tuya.com) — see [Get Local Keys](https://github.com/homebridge-plugins/homebridge-tuya/wiki/Get-Local-Keys-for-Your-Devices) for a guide.
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `local.autoDiscoverDevices` | ➖ | Auto-discover devices via UDP broadcast (default: `true`) |
-| `local.discoverTimeout` | ➖ | Discovery listen time in seconds (default: `5`) |
-| `local.devices` | ➖ | Optional list of known devices with their keys |
-| `local.devices[].tuyaDeviceId` | ✅ | Tuya device ID |
-| `local.devices[].tuyaKey` | ➖ | Local AES key (16 chars) |
-| `local.devices[].ip` | ➖ | Fixed IP address (optional; otherwise auto-discovered) |
-| `local.devices[].name` | ➖ | Friendly name |
-| `local.devices[].category` | ➖ | Category code (e.g. `light`, `switch`) to pick the right accessory handler |
-| `local.devices[].protocolVersion` | ➖ | Protocol version (e.g. `3.3`, `3.4`); auto-detected when blank |
-
-**Example local config:**
+- Tuya IoT Platform account
+- Cloud project setup
+- API credentials
+- Subscription to required services
+
+**See:** [Cloud Setup Guide](./docs/CONFIG_GUIDE.md#cloud-setup)
+
+### Local Mode
+
+Direct LAN communication without cloud dependency — faster and more private.
+
+**Requirements:**
+- Devices and Homebridge on same network
+- Device local keys
+- UDP broadcast enabled on network
+
+**See:** [Local Setup Guide](./docs/CONFIG_GUIDE.md#local-setup) and [Get Local Keys](./docs/Get-Local-Keys-for-Your-Devices.md)
+
+### Both Mode
+
+Hybrid mode using local commands with cloud fallback for reliability.
+
+**See:** [Both Mode Setup](./docs/CONFIG_GUIDE.md#both-mode)
+
+---
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [CONFIG_GUIDE.md](./docs/CONFIG_GUIDE.md) | **Detailed configuration reference** — all options explained |
+| [ADVANCED_OPTIONS.md](./docs/ADVANCED_OPTIONS.md) | Device schema overrides, non-standard DPs, custom mappings |
+| [SUPPORTED_DEVICES.md](./docs/SUPPORTED_DEVICES.md) | Complete list of 60+ supported device categories |
+| [Get Local Keys](./docs/Get-Local-Keys-for-Your-Devices.md) | Step-by-step guide to retrieve device local keys |
+| [CHANGELOG.md](./CHANGELOG.md) | Version history and updates |
+
+---
+
+## Supported Devices
+
+This plugin supports **60+ device categories** from Tuya's ecosystem:
+
+**Lighting:** Lights, ceiling lights, string lights, strip lights, dimmers, motion sensor lights, solar lights, and more  
+**Electrical:** Switches, sockets, power strips, curtain switches, dimmer switches, fan switches, wireless switches  
+**Climate:** Air conditioners, heaters, thermostats, humidifiers, dehumidifiers  
+**Security:** Door locks, door/window sensors, motion sensors, smoke detectors, CO detectors  
+**Cameras & Sensors:** Video cameras (with RTSP streaming), temperature/humidity sensors, air quality sensors  
+**Other:** IR controllers, garage door openers, fans, robot vacuums, and more
+
+**For a complete list:** See [SUPPORTED_DEVICES.md](./docs/SUPPORTED_DEVICES.md)
+
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Authentication Errors (`1106`, `2406`)
+
+If you receive these error codes in Cloud mode:
+
+1. Open the Tuya app → **Me** → **Settings** → **Network Diagnosis**
+2. Start diagnosis and upload logs
+3. Find the line starting with `Region code:`:
+   - `AY` = China
+   - `AZ` = West US
+   - `EU` = Central Europe
+   - `IN` = India
+4. Manually set `options.endpoint` in your config with the correct region endpoint
+
+**For help finding your endpoint:** [Tuya API Endpoints](https://developer.tuya.com/en/docs/iot/api-request?id=Ka4a8uuo1j4t4#title-1-Endpoints)
+
+#### 2. Device Not Showing Up
+
+**In Cloud mode:**
+- Verify the device is added to your Tuya app
+- Confirm the device category is in the [supported list](./docs/SUPPORTED_DEVICES.md)
+- Check that required APIs are subscribed on your cloud project
+
+**In Local mode:**
+- Ensure Homebridge and devices are on the **same network**
+- Disable any network isolation or guest network features
+- Enable UDP broadcast on your router/network
+- Manually add the device with its local key if auto-discovery fails
+
+**For both modes:**
+- Check HomeKit accessory cache: `rm -rf ~/.homebridge/persist/AccessoryInfo.${RANDOM}.json`
+- Review logs with `debug: true` enabled
+
+#### 3. Non-Standard Device Properties
+
+Some devices have non-standard Data Points (DPs) that don't map to the standard schema.
+
+**Solution:** Use device schema overrides. See [ADVANCED_OPTIONS.md](./docs/ADVANCED_OPTIONS.md) for examples.
+
+**Steps:**
+1. Enable debug mode and operate the device
+2. Find `TuyaDeviceList.{uid}.json` path from logs
+3. Identify the non-standard DP codes
+4. Add a `deviceOverrides` entry with custom schema mappings
+
+#### 4. Local Connection Not Working
+
+**Check:**
+- ✅ Homebridge can ping device: `ping <device_ip>`
+- ✅ Device local key is correct (16 characters)
+- ✅ Device protocol version is correct (try auto-detect first)
+- ✅ UDP port 6666 is open (used for discovery)
+- ✅ Network firewall allows local communication
+
+#### 5. Cloud API Trial Expired
+
+**⚠️ Important:** Tuya IoT Platform API trials expire every 6 months.
+
+**To renew:**
+1. Log in to [Tuya IoT Platform](https://iot.tuya.com)
+2. Go to **Cloud** → **API** → **IoT Core Cloud Services**
+3. Click **Extend** to renew trial
+4. **Set a calendar reminder** for 6 months later
+
+**Without renewal,** your plugin will stop working after expiration.
+
+---
+
+## Debug & Support
+
+### Enable Debug Logging
+
+Add to your config:
 ```json
 {
   "platform": "TuyaPlatform",
-  "name": "Tuya",
-  "mode": "local",
-  "local": {
-    "autoDiscoverDevices": true,
-    "discoverTimeout": 5,
-    "devices": [
-      {
-        "tuyaDeviceId": "abcdef1234567890",
-        "tuyaKey": "0123456789abcdef",
-        "ip": "192.168.1.100",
-        "name": "Living Room Light",
-        "category": "light"
-      }
-    ]
+  "options": {
+    "debug": true,
+    "debugLevel": "api,mqtt"
   }
 }
 ```
 
+**Debug levels:**
+- `api` — API call logs
+- `mqtt` — MQTT connection logs
+- `{device_id}` — Specific device logs
+
+### Getting Device Information
+
+After a successful connection, the cloud device list is saved at the path shown in Homebridge logs:
+```
+[TuyaPlatform] Device list saved at /path/to/TuyaDeviceList.{uid}.json
+```
+
+**⚠️ Warning:** Remove sensitive fields (`ip`, `lon`, `lat`, `local_key`) before sharing logs.
+
+### Reporting Issues
+
+When reporting issues, include:
+1. Plugin version (`npm list @homebridge-plugins/homebridge-tuya`)
+2. Homebridge version and Node version
+3. Device category and model
+4. Relevant debug logs (without sensitive data)
+5. Steps to reproduce
+
+**GitHub Issues:** [Create an issue](https://github.com/homebridge-plugins/homebridge-tuya/issues)
+
+---
+
+## FAQ
+
+### Connection Modes
+
+**Q: Which mode should I use?**
+
+- **Cloud only:** Simple setup, works remotely, but slower
+- **Local only:** Fastest, most private, but limited features
+- **Both (recommended):** Local commands first, cloud fallback for reliability
+
+**Q: Can I switch modes later?**
+
+Yes. Update the `mode` setting in your config and restart Homebridge.
+
+---
+
+### About Devices
+
+**Q: What devices does this plugin support?**
+
+This plugin supports 60+ Tuya device categories. See [SUPPORTED_DEVICES.md](./docs/SUPPORTED_DEVICES.md) for the complete list.
+
+**Q: My device isn't showing up. What do I do?**
+
+See [Troubleshooting → Device Not Showing Up](#2-device-not-showing-up).
+
+**Q: Can I customize how my device appears in HomeKit?**
+
+Yes. Use device overrides to:
+- Change category type
+- Map non-standard DPs to standard ones
+- Hide specific device properties
+- Enable Adaptive Lighting
+- And more
+
+See [ADVANCED_OPTIONS.md](./docs/ADVANCED_OPTIONS.md) for examples.
+
 ---
 
-### Both Mode (`mode: "both"`)
+### About Tuya Account
+
+**Q: Do I need a Tuya IoT account for Cloud mode?**
+
+Yes. You need to create a free trial project on [Tuya IoT Platform](https://iot.tuya.com).
+
+**Q: How do I get my local keys?**
+
+Follow the step-by-step guide: [Get Local Keys for Your Devices](./docs/Get-Local-Keys-for-Your-Devices.md)
+
+**Q: Can I use the same Tuya account for multiple Homebridge instances?**
+
+Not recommended. Use separate Tuya app accounts per Homebridge instance to avoid conflicts.
 
-Uses cloud + local simultaneously. Provide both `options` (cloud) and `local` blocks.
-- Local LAN commands are attempted first when the device is available locally.
-- The cloud connection remains active as a fallback.
-- This fallback is only used when a local command does not receive confirmation within 10 seconds; normal local commands remain local.
-- If a local command does not receive confirmation within 10 seconds, the plugin automatically retries it via cloud.
-- Cloud status updates can also satisfy pending local commands so the device does not get double-sent commands.
 ---
 
-### Advanced Options
-See [ADVANCED_OPTIONS.md](./ADVANCED_OPTIONS.md)
+### About Performance
+
+**Q: Why are local commands faster than cloud?**
+
+Local commands communicate directly with your devices over LAN (typically <100ms), while cloud commands go through Tuya's servers (typically >1 second).
 
+**Q: Does the plugin consume a lot of bandwidth?**
+
+No. In Local mode, it uses only local network traffic. In Cloud mode, it uses MQTT for efficient subscriptions and status updates.
+
+---
 
 ## Limitations
-- Using the same app account for multiple Homebridge/HomeAssistant instances is not recommended. Use separate app accounts per instance.
-- **⚠️ Cloud API trial expires every 6 months** — set a calendar reminder to renew.
-- Local mode requires devices and Homebridge to be on the same subnet.
 
+- **Same app account recommendation:** Using the same Tuya account for multiple Homebridge/Home Assistant instances is not recommended. Create separate accounts.
+- **Cloud API trial duration:** API trial must be renewed every 6 months.
+- **Local network requirement:** Local mode requires devices and Homebridge on the same subnet.
+- **Feature support variance:** Some features (Scenes, advanced automations) are only available in Cloud mode.
 
-## FAQ
+---
 
-#### About Login Issues
+## Development
 
-For most users, the data center is auto-detected. If you get error codes `1106` or `2406`:
+### Prerequisites
 
-1. Open the Tuya app → Me → Settings → Network Diagnosis.
-2. Start diagnosis, select Upload Log → Copy the Log to Clipboard.
-3. Find the line beginning with `Region code:`:
-   - `AY` = China, `AZ` = West US, `EU` = Central Europe, `IN` = India.
-4. Manually set `options.endpoint` in your config.
+- Node.js 20+ (or 22, 24, 25)
+- npm 10+
 
-#### What is "Standard DP" and "Non-standard DP"?
+### Build & Test
 
-"Standard DP" refers to device properties defined in [Tuya Standard Instruction Set](https://developer.tuya.com/en/docs/iot/standarddescription?id=K9i5ql6waswzq) (e.g. `switch_led`, `bright_value`). If your device works in the Tuya app but not this plugin, it likely has non-standard DPs.
+```bash
+# Install dependencies
+npm install
 
-#### Can "Non-standard DP" be supported?
+# Run linter
+npm run lint
 
-Yes — override the device schema. See [ADVANCED_OPTIONS.md](./ADVANCED_OPTIONS.md).
+# Fix linting issues
+npm run lint:fix
 
-Steps:
-1. On the Tuya Platform → Your Project → Devices → All Devices → View by Product.
-2. Click the pencil icon next to your product → select **DP Instruction** → save.
-3. Add a `deviceOverrides` entry with schema mappings in the plugin config.
+# Run tests
+npm test
 
+# Generate coverage report
+npm run coverage
 
-## Troubleshooting
+# Build for deployment
+npm run build
+
+# Watch mode (auto-rebuild on changes)
+npm run watch
+```
 
-#### 1. Get Device Information
+### Project Structure
 
-After a successful start, the cloud device list is saved at the path shown in the Homebridge log:
 ```
-[TuyaPlatform] Device list saved at /path/to/TuyaDeviceList.{uid}.json
+src/
+├── index.ts              # Plugin entry point
+├── platform.ts           # Main platform class
+├── config.ts             # Config interfaces
+├── settings.ts           # Constants
+├── cloud/                # Cloud/API logic
+│   ├── api/              # Tuya API clients
+│   └── device/           # Cloud device handling
+├── local/                # Local/LAN logic
+│   ├── protocol/         # Tuya local protocol
+│   └── device/           # Local device handling
+└── shared/               # Shared utilities
+    ├── accessory/        # HomeKit accessory factories
+    └── util/             # Utilities
+
+test/                     # Test suite
+docs/                     # Documentation
 ```
-**⚠️ Remove sensitive fields (`ip`, `lon`, `lat`, `local_key`, `uid`) before sharing.**
 
-#### 2. Enable Debug Mode
+### Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes and test thoroughly
+4. Run `npm run lint:fix` and `npm test`
+5. Commit with clear messages
+6. Push to your branch
+7. Open a Pull Request
+
+---
+
+## License
+
+MIT License — see [LICENSE](./LICENSE) file for details
+
+---
+
+## Support
 
-Add `"debug": true` to your `options` block and restart Homebridge.
+- ⭐ Star this repo if you find it helpful
+- 💖 [Sponsor the project](https://github.com/sponsors/tassy-h)
+- 🐛 [Report issues](https://github.com/homebridge-plugins/homebridge-tuya/issues)
+- 📖 [Documentation](./docs/CONFIG_GUIDE.md)
+
+---
 
-#### 3. Collect Logs
+## Changelog
 
-With debug enabled, operate your device physically or via the Tuya App and collect the MQTT/local protocol logs from the Homebridge log.
+See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.