homebridge-tuya-curtains-combined

Homebridge platform plugin for Tuya devices that combine curtain/blind and light control in a single unit. Exposes one accessory with two services in HomeKit: Window Covering (curtain) and Light.

Control is done locally via the Tuya LAN protocol (using TuyAPI), so you need the device local key and optional IP for best reliability.

Using Tuya Web / Cloud instead of local?

Yes, it’s posible to control Tuya devices over the cloud instead of LAN, but this plugin currently only implements local control. Here are the options:

| Approach | What you need | Pros | Cons | |----------|----------------|------|------| | Local (this plugin) | Device ID + local key (+ optional IP) | No cloud dependency, works offline, low latency | Requires getting the local key (Tuya IoT or tuya-convert) | | Tuya Web (app login) | Smart Life / Tuya app email + password + country code | No device key; uses same account as the app | Unofficial/consumer API; other plugins (e.g. @milo526/homebridge-tuya-web) use it but often don’t support covers/curtains; depends on Tuya not changing the API | | Tuya Open API (developer) | Tuya IoT project (Access ID/Key), then link app and get devices | Official, stable, supports all device types | More setup (developer account, cloud project, link app); different auth and API than “Tuya Web” |

• If you want cloud only: Use the official Tuya Homebridge plugin (Tuya Developer / Open API) and see if your combined curtain+light device is supported or can be added. For “Tuya Web” style (app login), check @milo526/homebridge-tuya-web — it may support lights and possibly some covers, but not necessarily combined curtain+light.
• If you want cloud support in this plugin: It would mean adding a second backend (e.g. Tuya Open API or the web API) alongside the existing local one, with config to choose “local” vs “cloud” and the right credentials. That’s a larger change but feasible.

So: yes, Tuya web/cloud is possible in general; this repo today only does local. For cloud, use an existing cloud-based plugin or we can add a cloud backend here in a future version.

Requirements

• Node.js >= 18
• Homebridge >= 1.6
• Tuya device with both curtain and light (or two logical functions) on the same device
• Device ID and local key from the Tuya/Smart Life app (e.g. via Tuya IoT Platform or tuya-convert)

Installation

npm install -g homebridge-tuya-curtains-combined

Or install from this repo for development:

cd homebridge-tuya-curtains-combined
npm install
npm run build
# Then link: sudo hb-service link (from this directory)

Configuration

Add a platform (not an accessory) in Homebridge.

Simple UI (Homebridge Config UI X)

If you use Homebridge Config UI X, the plugin exposes a form-based UI to add and edit accessories. After installing this plugin, open the Homebridge UI → Plugins → find Tuya Curtain Light (or the platform name) in your config → you’ll see a Devices list with an “Add accessory” button. Fill in Name, Device ID, and Device Key (and optionally IP and DPS). Save and restart; the new accessory will appear in Home. No need to edit config.json by hand.

Local: what you need to provide

| Field | Required? | Description | |-------|-----------|-------------| | name | Yes | Display name in the Home app (e.g. "Living Room Curtain"). | | deviceId | Yes | Tuya device ID (20 chars, from Tuya/Smart Life app or Tuya IoT Platform). | | deviceKey | Yes | Tuya local key (16 characters). Needed for local LAN control. | | ip | No | Device IP on your network. Speeds up connection; find it in your router or app. | | curtainDps | No (has defaults) | Which DPS control the curtain. Default: control: "1", position: "2". Change if your device uses other DPS numbers. | | lightDps | No (has defaults) | Which DPS control the light. Default: switch: "3", brightness: "" (on/off only). Set brightness to e.g. "4" if your device supports it. |

So at minimum for local you must set: name, deviceId, and deviceKey. The rest have defaults or are optional.

Example:

{
  "platforms": [
    {
      "platform": "TuyaCurtainLight",
      "devices": [
        {
          "name": "Living Room Curtain",
          "deviceId": "YOUR_DEVICE_ID",
          "deviceKey": "YOUR_16_CHAR_LOCAL_KEY",
          "ip": "192.168.1.100",
          "curtainDps": {
            "control": "1",
            "position": "2"
          },
          "lightDps": {
            "switch": "3",
            "brightness": "4"
          }
        }
      ]
    }
  ]
}

Finding Device ID and Key

• Device ID: Often visible in the Tuya/Smart Life app under device settings, or from the Tuya IoT Platform after linking your app.
• Local key: Required for local control. Options:
  • Tuya IoT Platform: Create a cloud project, link the app, add the device, then read the local key in the device details.
  • tuya-convert (for supported devices): Use the process that flashes alternative firmware; it can reveal the local key.
  • Some community tools can dump keys from the official app (use at your own risk).

DPS (Data Points)

Tuya devices expose properties as numbered DPS (e.g. 1, 2, 3). They vary by product. You must set curtainDps and lightDps to match your device.

| Config | Meaning | Example | |---------------|--------|--------| | curtainDps.control | DP for open/close/stop (if your device uses a control DP instead of position only) | "1" | | curtainDps.position| DP for curtain position 0–100 (0 = open, 100 = closed, or vice versa depending on device) | "2" | | lightDps.switch | DP for light on/off (boolean) | "3" | | lightDps.brightness| Optional DP for brightness 0–100. Omit or "" for on/off only | "4" |

• Curtain: The plugin currently sets position via the position DP (e.g. 2) with a 0–100 value. If your device uses a control DP with values like open/close/stop or 1/2/3, you can still use the position DP for target position; the plugin does not send control strings in the initial version.
• Light: Switch DP is required; brightness is optional. If your device uses a different range (e.g. 10–1000), you may need to scale in a custom fork.

Optional: IP address

Setting ip avoids discovery and can make the connection faster and more stable. Find the device IP from your router or the Tuya app (if shown).

Troubleshooting: "Can't control" / EHOSTUNREACH

If you see connect EHOSTUNREACH 192.168.x.x:6668 or Connect failed in the log, the machine running Homebridge cannot reach the device on the network. The key and device ID are not the cause.

• Homebridge must be on the same LAN as the Tuya device. Local control is direct TCP to the device. If Homebridge runs in the cloud, on another VLAN, or in a Docker network that can’t reach your WiFi, you’ll get EHOSTUNREACH.
• Check the device IP: If you set ip in config, make sure it’s still correct (DHCP may have changed it). In your router or the Tuya app, confirm the device’s current IP. You can also remove the ip field from the device config so the plugin uses discovery (device ID only); then the plugin will try to find the device on the LAN.
• Check the device is on: Power and WiFi connected. Same WiFi as the Homebridge host (or a subnet that can route to it).
• From the Homebridge host, try: ping 192.168.68.143 (use your device IP). If ping fails, fix network/routing so the host can reach that IP; the plugin can’t work until it can open a TCP connection to the device on port 6668.

Behavior

• Each entry in devices becomes one HomeKit accessory with two services:
  • Window Covering – target/current position (0–100).
  • Light – on/off and optional brightness.
• The plugin connects to the device over the local network and polls state every 30 seconds; control is sent immediately when you change something in HomeKit.
• Only one TCP connection to the device is used at a time; avoid using the Tuya app at the same time for that device if you see disconnects.

Development

npm install
npm run build

• TypeScript source in src/.
• Main entry: src/index.ts (platform registration).
• Platform: src/platform.ts (discovers and creates accessories from config).
• Accessory: src/curtainLightAccessory.ts (Window Covering + Lightbulb services and Tuya communication).

Testing on your Homebridge server

If you develop on your Mac/PC and Homebridge runs on another machine (Raspberry Pi, NAS, etc.), you can test the plugin there in two ways.

Option 1: Copy project and link (good for active development)

1. On your dev machine – build the plugin:

   cd homebridge-tuya-curtains-combined
   npm install
   npm run build

2. Copy the whole project folder to the server (replace user@host and path with yours):

   rsync -avz --exclude node_modules ./homebridge-tuya-curtains-combined user@YOUR_SERVER:/tmp/

   Or with scp:

   scp -r homebridge-tuya-curtains-combined user@YOUR_SERVER:/tmp/

   (Omitting node_modules with rsync keeps the copy small; you’ll install on the server.)

3. On the server (SSH) – install dependencies, build, and link the plugin so Homebridge uses your copy:

   cd /tmp/homebridge-tuya-curtains-combined
   npm install
   npm run build
   sudo hb-service link

   When prompted, choose this directory. That creates a symlink from Homebridge’s plugin directory to this folder, so changes (after npm run build) take effect after restarting Homebridge.

   If npm is not found on the server (common on the official Homebridge image): do everything on your Mac and copy the built project including node_modules and dist, so the server doesn’t need npm or TypeScript:

   • On your Mac: npm install, npm run build.
   • Copy the whole folder to the server (include node_modules and dist), e.g. scp -r homebridge-tuya-curtains-combined user@SERVER:/tmp/.
   • On the server: cd /tmp/homebridge-tuya-curtains-combined then sudo hb-service link (no npm install or npm run build). Homebridge only needs Node to load the plugin.

4. Add the platform to your Homebridge config (Config UI X or config.json), then restart Homebridge.

To stop using the linked plugin and use the published one again:

sudo hb-service unlink

Option 2: Install from a tarball (one-off test)

1. On your dev machine – pack the plugin:

   cd homebridge-tuya-curtains-combined
   npm run build
   npm pack

   This creates e.g. homebridge-tuya-curtains-combined-1.0.0.tgz.

2. Copy the tarball to the server and install it as the plugin (typical path is ~/.homebridge or /var/lib/homebridge; adjust if yours is different):

   scp homebridge-tuya-curtains-combined-1.0.0.tgz user@YOUR_SERVER:/tmp/
   ssh user@YOUR_SERVER
   npm install -g /tmp/homebridge-tuya-curtains-combined-1.0.0.tgz

   If Homebridge is installed per-user, run the npm install -g without sudo and ensure the same user runs Homebridge.

3. Restart Homebridge and add the platform in config.

License

ISC