@caseman72/tuya-api 1.0.0

package/.tuya-devices.example.json

@@ -0,0 +1,9 @@
+[
+  {
+    "id": "DEVICE_ID",
+    "name": "Living Room Mini-Split",
+    "key": "LOCAL_KEY",
+    "ip": "192.168.1.100",
+    "version": "3.4"
+  }
+]

package/README.md

@@ -0,0 +1,83 @@
+# @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
+
+```bash
+npm install @caseman72/tuya-api
+```
+
+## Setup
+
+Create a `.tuya-devices.json` file with your device configurations:
+
+```bash
+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
+
+```javascript
+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
+
+```javascript
+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

package/index.js

@@ -0,0 +1,116 @@
+import { readFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { getStatus, setPower, setTemperature, setMode, setFanSpeed, setDps, scan } from './lib/climate.js';
+import { disconnect, disconnectAll } from './lib/connection.js';
+
+function loadDevicesFile(devicesPath) {
+  const paths = [
+    join(devicesPath, '.tuya-devices.json'),
+    join(homedir(), '.config', 'tuya-api', '.tuya-devices.json'),
+  ];
+
+  const filePath = paths.find(p => existsSync(p));
+  if (!filePath) return [];
+
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    console.error('[tuya-api] Error loading devices file:', err.message);
+    return [];
+  }
+}
+
+class Tuya {
+  constructor(options = {}) {
+    this.devicesPath = options.devicesPath || '.';
+
+    if (options.devices && options.devices.length > 0) {
+      this._devices = options.devices;
+    } else {
+      this._devices = loadDevicesFile(this.devicesPath);
+    }
+  }
+
+  // Device lookup
+  getDevices() {
+    return this._devices;
+  }
+
+  getDevice(idOrName) {
+    const search = (idOrName || '').toLowerCase().trim();
+    return this._devices.find(d =>
+      d.id === idOrName || (d.name || '').toLowerCase().trim() === search
+    ) || null;
+  }
+
+  // Climate control
+  async getStatus(idOrName) {
+    const device = this.getDevice(idOrName);
+    if (!device) throw new Error(`Device not found: ${idOrName}`);
+    return getStatus(device);
+  }
+
+  async setPower(idOrName, on) {
+    const device = this.getDevice(idOrName);
+    if (!device) throw new Error(`Device not found: ${idOrName}`);
+    return setPower(device, on);
+  }
+
+  async setTemperature(idOrName, temp) {
+    const device = this.getDevice(idOrName);
+    if (!device) throw new Error(`Device not found: ${idOrName}`);
+    return setTemperature(device, temp);
+  }
+
+  async setMode(idOrName, mode) {
+    const device = this.getDevice(idOrName);
+    if (!device) throw new Error(`Device not found: ${idOrName}`);
+    return setMode(device, mode);
+  }
+
+  async setFanSpeed(idOrName, speed) {
+    const device = this.getDevice(idOrName);
+    if (!device) throw new Error(`Device not found: ${idOrName}`);
+    return setFanSpeed(device, speed);
+  }
+
+  async setDps(idOrName, dpsIndex, value) {
+    const device = this.getDevice(idOrName);
+    if (!device) throw new Error(`Device not found: ${idOrName}`);
+    return setDps(device, dpsIndex, value);
+  }
+
+  async scan(idOrName) {
+    const device = this.getDevice(idOrName);
+    if (!device) throw new Error(`Device not found: ${idOrName}`);
+    return scan(device);
+  }
+
+  // Get all device statuses
+  async getAllStatuses() {
+    const results = [];
+    for (const device of this._devices) {
+      try {
+        const status = await getStatus(device);
+        results.push(status);
+      } catch (err) {
+        results.push({ id: device.id, name: device.name, error: err.message });
+      }
+    }
+    return results;
+  }
+
+  // Connection management
+  async disconnect(idOrName) {
+    const device = this.getDevice(idOrName);
+    if (device) await disconnect(device.id);
+  }
+
+  async disconnectAll() {
+    return disconnectAll();
+  }
+}
+
+export default Tuya;
+export { Tuya };

package/lib/climate.js

@@ -0,0 +1,94 @@
+import { getConnection } from './connection.js';
+import { DEFAULT_DPS, DEFAULT_TEMP_SCALE, MODE_MAP, MODE_REVERSE, FAN_MAP, FAN_REVERSE } from './dps.js';
+
+function getDps(device) {
+  return { ...DEFAULT_DPS, ...(device.dps || {}) };
+}
+
+function getScale(device) {
+  return device.temp_scale || DEFAULT_TEMP_SCALE;
+}
+
+export async function getStatus(device) {
+  const conn = await getConnection(device);
+  const dps = getDps(device);
+  const scale = getScale(device);
+
+  const data = await conn.get({ schema: true });
+  const values = data.dps || data;
+
+  const tempUnit = values[dps.temp_unit] || 'f';
+  const useFahrenheit = tempUnit === 'f' || tempUnit === 'F';
+
+  const rawTarget = useFahrenheit ? values[dps.target_temp] : values[dps.target_temp_c];
+  const rawCurrent = useFahrenheit ? values[dps.current_temp] : values[dps.current_temp_c];
+
+  const rawMode = values[dps.mode];
+  const rawFan = values[dps.fan_speed];
+
+  return {
+    id: device.id,
+    name: device.name,
+    is_on: values[dps.power] === true,
+    target_temperature: rawTarget != null ? rawTarget / scale : null,
+    current_temperature: rawCurrent != null ? rawCurrent : null,
+    temp_unit: useFahrenheit ? 'F' : 'C',
+    mode: MODE_MAP[rawMode] || rawMode || null,
+    fan_speed: FAN_MAP[rawFan] || rawFan || null,
+    raw_dps: values
+  };
+}
+
+export async function setPower(device, on) {
+  const conn = await getConnection(device);
+  const dps = getDps(device);
+
+  await conn.set({ dps: parseInt(dps.power), set: on });
+  return { success: true, device: device.name, power: on ? 'on' : 'off' };
+}
+
+export async function setTemperature(device, temp) {
+  const conn = await getConnection(device);
+  const dps = getDps(device);
+  const scale = getScale(device);
+
+  const scaledTemp = Math.round(temp * scale);
+  await conn.set({ dps: parseInt(dps.target_temp), set: scaledTemp });
+  return { success: true, device: device.name, target_temperature: temp };
+}
+
+export async function setMode(device, mode) {
+  const conn = await getConnection(device);
+  const dps = getDps(device);
+
+  const tuyaMode = MODE_REVERSE[mode] || mode;
+  await conn.set({ dps: parseInt(dps.mode), set: tuyaMode });
+  return { success: true, device: device.name, mode };
+}
+
+export async function setFanSpeed(device, speed) {
+  const conn = await getConnection(device);
+  const dps = getDps(device);
+
+  const tuyaSpeed = FAN_REVERSE[speed] || speed;
+  await conn.set({ dps: parseInt(dps.fan_speed), set: tuyaSpeed });
+  return { success: true, device: device.name, fan_speed: speed };
+}
+
+export async function setDps(device, dpsIndex, value) {
+  const conn = await getConnection(device);
+  await conn.set({ dps: parseInt(dpsIndex), set: value });
+  return { success: true, device: device.name, dps: dpsIndex, value };
+}
+
+export async function scan(device) {
+  const conn = await getConnection(device);
+
+  const data = await conn.get({ schema: true });
+  let refreshData = null;
+  try {
+    refreshData = await conn.refresh({ schema: true });
+  } catch (_) {}
+
+  return { id: device.id, name: device.name, status: data, refresh: refreshData };
+}

package/lib/connection.js

@@ -0,0 +1,56 @@
+import TuyAPI from 'tuyapi';
+
+// Active connections keyed by device ID
+const connections = new Map();
+
+export async function getConnection(device) {
+  const existing = connections.get(device.id);
+  if (existing && existing.isConnected()) {
+    return existing;
+  }
+
+  // Clean up stale connection
+  if (existing) {
+    try { existing.disconnect(); } catch (_) {}
+    connections.delete(device.id);
+  }
+
+  const tuyaDevice = new TuyAPI({
+    id: device.id,
+    key: device.key,
+    ip: device.ip || undefined,
+    version: device.version || '3.4',
+    issueGetOnConnect: false,
+    issueRefreshOnConnect: false,
+  });
+
+  tuyaDevice.on('error', (err) => {
+    console.error(`[tuya-api] ${device.name || device.id} error:`, err.message);
+  });
+
+  tuyaDevice.on('disconnected', () => {
+    connections.delete(device.id);
+  });
+
+  if (!device.ip) {
+    await tuyaDevice.find({ timeout: 10 });
+  }
+  await tuyaDevice.connect();
+  connections.set(device.id, tuyaDevice);
+  return tuyaDevice;
+}
+
+export async function disconnect(deviceId) {
+  const conn = connections.get(deviceId);
+  if (conn) {
+    try { conn.disconnect(); } catch (_) {}
+    connections.delete(deviceId);
+  }
+}
+
+export async function disconnectAll() {
+  for (const [id, device] of connections) {
+    try { device.disconnect(); } catch (_) {}
+  }
+  connections.clear();
+}

package/lib/dps.js

@@ -0,0 +1,43 @@
+// Default DPS mapping for Tuya AC/climate devices (category: kt)
+export const DEFAULT_DPS = {
+  power: '1',
+  target_temp: '24',
+  current_temp: '23',
+  mode: '4',
+  fan_speed: '5',
+  temp_unit: '19',
+  target_temp_c: '2',
+  current_temp_c: '3'
+};
+
+// Default temperature scale (DPS 24 uses ×10, e.g. 690 = 69.0°F)
+export const DEFAULT_TEMP_SCALE = 10;
+
+// Tuya mode strings → human-readable
+export const MODE_MAP = {
+  cold: 'cool',
+  hot: 'heat',
+};
+
+export const MODE_REVERSE = {
+  cool: 'cold',
+  heat: 'hot',
+};
+
+// Fan speed mapping
+export const FAN_MAP = {
+  '1': 'low',
+  '2': 'medium',
+  '3': 'high',
+  auto: 'auto',
+  low: 'low',
+  mid: 'medium',
+  high: 'high',
+};
+
+export const FAN_REVERSE = {
+  low: 'low',
+  medium: 'mid',
+  high: 'high',
+  auto: 'auto',
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@caseman72/tuya-api",
+  "version": "1.0.0",
+  "description": "Simple Tuya API client for local LAN control of smart climate devices",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "lib/*.js",
+    "README.md",
+    ".tuya-devices.example.json"
+  ],
+  "scripts": {
+    "scan": "node lib/scan.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "keywords": [
+    "tuya",
+    "api",
+    "smart-home",
+    "iot",
+    "climate",
+    "mini-split",
+    "home-automation",
+    "turbro"
+  ],
+  "author": "Casey Manion <casey@manion.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/caseman72/tuya-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/caseman72/tuya-api/issues"
+  },
+  "homepage": "https://github.com/caseman72/tuya-api#readme",
+  "dependencies": {
+    "tuyapi": "^7.7.1"
+  }
+}