Protocol Tuya

Protocol: Tuya Local & Cloud

Tuya is one of the largest IoT ecosystems worldwide, powering thousands of white-label brands (such as LSC Smart Connect, Nedis, Calex, Woox, Moes, and generic Smart Life devices).

• Ecosystem: Tuya Smart / Smart Life / LSC Smart Connect
• HomeNode Module: modules/tuya (homenode-module-tuya)
• Transport:
  • Local LAN: TCP port 6668 (Tuya Local encrypted protocol)
  • Cloud API: HTTPS REST (Tuya OpenAPI openapi.tuyaeu.com)
• Encryption: AES-128 (ECB/CBC) with pre-shared 16-byte local_key

---

1. Local Protocol Architecture (Port 6668)

Unlike pure cloud systems, most Tuya Wi-Fi devices run a local TCP server on port 6668 (and historically 6667). Once registered with an IP address, devices accept local connections without accessing the Tuya Cloud.

Protocol Versions

• Tuya 3.1 & 3.3: Uses AES-128-ECB or AES-128-CBC encryption.
• Tuya 3.4 & 3.5: Enhanced security with session negotiation and HMAC-SHA256 authentication.

Datapoints (DPs)

Tuya devices structure their state around numeric DP IDs:

• For Micro Solar Converters / Inverters (e.g., LSC Smart Connect):
  • Current PV Wattage ($W$)
  • Daily energy yield ($kWh$)
  • Total lifetime yield ($kWh$)
  • AC voltage ($V$) and frequency ($Hz$)
• For Smart Plugs / Relays:
  • DP 1: Switch (true/false)
  • DP 18: Current ($mA$)
  • DP 19: Power ($0.1 W$)
  • DP 20: Voltage ($0.1 V$)

---

2. Cryptographic Prerequisites

To establish a local encrypted TCP session to a Tuya device on port 6668, two parameters are required:

1. Virtual ID (device_id): A 20–22 alphanumeric character string assigned during device commissioning (visible in the manufacturer app under Device Information).
2. Local Key (local_key): A 16-byte secret key assigned to the device by Tuya's provisioning server.

---

3. Provisioning & Key Acquisition

HomeNode supports three acquisition paths:

1. Home Assistant Extraction:
   • If the device is connected via Home Assistant's Tuya integration, the local_key is stored in .storage/core.config_entries and can be imported into HomeNode.
2. mHomeNode iOS Companion App:
   • The user scans the Tuya authorization QR code or logs into Tuya within the iOS app.
   • The iOS app fetches the device list and local_keys via Tuya OpenAPI and syncs them securely to HomeNode Server.
3. Tuya Cloud Developer Credentials:
   • User configures client_id and secret in config/modules/tuya.toml, allowing HomeNode to poll keys directly.