@caseman72/tuya-api

Simple Tuya API client for local LAN control of smart climate devices (mini-splits, AC units). No cloud dependency — communicates directly with devices over your local network using the Tuya protocol.

Installation

npm install @caseman72/tuya-api

Setup

Create a .tuya-devices.json file with your device configurations:

cp .tuya-devices.example.json .tuya-devices.json

Each device needs:

• id — Tuya Device ID (from Tuya IoT Platform)
• name — Friendly name
• key — Local encryption key (from Tuya IoT Platform device details)
• ip — Local LAN IP (optional, auto-discovered if omitted)
• version — Protocol version ("3.4" for most modern devices)

The file is searched in:

1. Current working directory
2. ~/.config/tuya-api/.tuya-devices.json

Usage

import Tuya from '@caseman72/tuya-api';

const tuya = new Tuya();

// Get all device statuses
const statuses = await tuya.getAllStatuses();

// Control by name or ID
const status = await tuya.getStatus('Living Room');
await tuya.setPower('Living Room', true);
await tuya.setTemperature('Living Room', 72);
await tuya.setMode('Living Room', 'cool');     // 'heat' or 'cool'
await tuya.setFanSpeed('Living Room', 'auto');  // 'low', 'medium', 'high', 'auto'

// Raw DPS access
await tuya.setDps('Living Room', '4', 'cold');

// Scan device to discover DPS mapping
const scan = await tuya.scan('Living Room');

// Clean up
await tuya.disconnectAll();

Constructor Options

const tuya = new Tuya({
  devicesPath: '.',        // Path to search for .tuya-devices.json
  devices: [...]           // Or pass device configs directly
});

DPS Mapping

Tuya climate devices use numbered data points (DPS). The defaults work for most mini-splits:

| DPS | Function | Values | |-----|----------|--------| | 1 | Power | true/false | | 24 | Target Temp °F | Integer × 10 (e.g., 690 = 69.0°F) | | 23 | Current Temp °F | Integer | | 4 | Mode | "cold" / "hot" | | 5 | Fan Speed | "low" / "mid" / "high" / "auto" | | 19 | Temp Unit | "f" / "c" |

Override per-device in .tuya-devices.json with a dps object and temp_scale value.

License

MIT