npm package: @jay-d-tyler/homebridge-tuya
Description: Homebridge plugin for Smart Life and Tuya Smart devices with real-time MQTT updates
Author: Jay D. Tyler
Latest version: 1.0.1

# @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