@jay-d-tyler/homebridge-tuya

Modern Homebridge plugin for Smart Life and Tuya Smart 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 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

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:

{
  "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:

{
  "deviceOverrides": [
    {
      "deviceId": "abc123...",
      "name": "Kitchen Light",
      "deviceType": "light"
    },
    {
      "deviceId": "def456...",
      "exclude": true
    }
  ]
}

Development

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