DOCSEARCHbyAlgolia
Submit Docs

tuya-local

repository·main·Indexed 25 days ago

https://github.com/make-all/tuya-local

A Home Assistant integration for local control of Tuya-firmware devices over WiFi, bypassing the Tuya cloud to improve speed and reliability. It uses YAML device configuration files to map Tuya Data Points (DPs) to Home Assistant entities, supporting various DP types (string, boolean, integer, bitfield, etc.) and complex mapping rules for data transformation.

Tokens
14.7K
Snippets
4
Records
63
Agent score
86%

What's inside tuya-local

  1. Understand Tuya hub support limitations

    main
    This project does not intend to support non-Tuya devices via Tuya hubs. The project focus is on making Tuya devices work with standard BLE and Zigbee support in Home Assistant. Users with non-Tuya devices should use standard Home Assistant integrations rather than attempting to route them through Tuya hubs via this project.

  2. Use IR/RF Blasters for learning and sending commands

    main

    Tuya IR/RF blasters are exposed as remote entities and infrared emitters.

    Learning Commands

    Use the remote.learn_command service:

    • command: The name to store the command under (e.g., power).
    • device: The appliance name (e.g., TV).
    • command_type: Set to rf for RF remotes; omit for IR.

    Sending Commands

    1. Learned Commands: Use remote.send_command with the same command and device used during learning.
    2. Direct IR/RF Codes: Use the infrared platform with prefixes:
      • b64:<base64_encoded_ir_code>
      • rf:<base64_encoded_rf_code>
    3. Cross-Emitter Commands: Use the send_learned_ir_command service to send a command learned by a Tuya remote entity to any other infrared emitter.

  3. Contribute device configuration files

    main

    If your device is not supported, you can help by providing a configuration file.

    How to gather data for a new device:

    1. Check Home Assistant Logs: If a device is unrecognized, the logs will contain the current data points (dps) returned by the device.
    2. Use Tuya IoT Explorer: Sign up at iot.tuya.com. Under Cloud > Device Control, use the Query Things Data Model function to find DP IDs and range information for integer/enum types.

    Requirements for Pull Requests:

    When requesting support, include:

    • Logs showing the LOCAL DPS received from the device.
    • Device identification (model and brand).
    • Gathered datapoint information.
    • Links to manuals or webpages (even in other languages).

  4. Configure Tuya Secure Locks

    main

    Tuya BLE locks use a pairing mechanism involving two datapoints (DPs):

    • 60: remote_no_pd_seykey
    • 61: remote_no_dp_key

    To unlock a lock, you can capture the 8-digit ASCII numeric code sent by the app during the pairing phase. This code can be extracted by eavesdropping on the message in the Tuya developer portal and decoding the payload (which contains 4 bytes of binary, the 8-digit code, and 3-4 more bytes of binary). The 8-digit code from the first paired app should work for subsequent unlocking.

  5. Configure tuya-local devices

    main

    After installation, you can configure devices via the Home Assistant Integrations UI (Settings > Devices & Services > Add Integration).

    There are two configuration paths:

    1. Cloud-assisted (Recommended): Log in to the Tuya or SmartLife app via the integration. This automatically retrieves the device list and necessary local connection data (device ID and local key), avoiding the need for a Tuya IoT developer account.
    2. Manual: Provide all device details manually as per the DEVICES_DETAILS.md guide.

  6. Configure Smart Plugs, Wall Sockets, and Switches

    main

    Most smart plugs follow a standard Tuya template, making many manufacturer-specific configurations compatible with other brands. However, features and datapoint locations can vary significantly between manufacturers.

    Tip for adding devices: When adding a device, the default selected option for the device type typically has the most matching datapoints. If the device appears to be of that type, it is likely the best configuration option to start with.

  7. Enable Meal Plan for Pet Feeders

    main
    Many pet feeders expose an encoded Meal plan setting via a text entity. This is disabled by default. To enable it, go to the Device settings in Home Assistant. Once enabled, the format is compatible with the FrederikM97/mealplan-card custom card.

  8. Find Device ID, Local Key, and Node ID using tinytuya wizard

    main

    You can use the tinytuya library to scan your network and automatically gather the id, key, and node_id (required for hub-dependent devices) needed for configuration.

    Prerequisites

    Before running the wizard, gather these credentials from the Tuya Developer Portal (Cloud -> Development -> Open project):

    • Access ID/Client ID
    • Access Secret/Client Secret
    • A sample Device ID
    • Your Region (e.g., "Central Europe Data Center")

    Execution

    Run the following command in your terminal (e.g., on your Home Assistant machine):

    python -m tinytuya wizard

    Follow the interactive prompts:

    • Enter API Key from tuya.com: Use your Access ID/Client ID.
    • Enter API Secret from tuya.com: Use your Access Secret/Client Secret.
    • Enter any Device ID...: Enter a registered device ID or type scan to scan the network.
    • Enter Your Region: Enter your datacenter's region.
    • Download DP Name mappings?: Enter Y.
    • Poll local devices?: Enter Y.

    Results

    The wizard generates a devices.json file containing:

    • id: The device ID.
    • key: The local key.
    • node_id: The sub-device ID (essential for hub-dependent devices).
    • mapping: Data point descriptions (used if the device is not yet natively supported).
    python -m tinytuya wizard

  9. Find Device ID and Local Key via Tuya IoT Developer Portal

    main

    If you are manually configuring devices, you can retrieve the Device ID and local_key using the Tuya Developer portal. This method is useful if you prefer not to use the cloud-assisted configuration flow.

    1. Get Device ID: Log in to the Developer Portal. Under Cloud, you should see a list of your devices containing the Device ID. Ensure your server is set correctly at the top of the page.
    2. Get Local Key:
      • Select Cloud from the sidebar, then go to API Explorer.
      • Under Devices Management, select the Query Device Details in Bulk function.
      • Enter your Device IDs, separated by commas.
      • The results will include the local_key for each device.

    Note: You must use Tuya-branded "Tuya Smart" or "SmartLife" apps to access devices through the developer portal. Some manufacturer-branded apps may have limited functionality (e.g., missing vacuum cleaner maps) when used this way.

  10. Configure Device IP Address

    main

    When configuring devices, you can set the IP address manually or use Auto.

    • Manual IP (Recommended): It is highly recommended to fix the device's IP address in your router configuration and enter that specific IP into the integration. This ensures better reconnection performance and stability.
    • Auto IP: You can enter Auto to allow the integration to discover the address.

    Drawbacks of Auto IP:

    • It may fail if localtuya is installed.
    • It may fail if the Tuya/Smartlife app is currently connected locally to the device.
    • It may fail if your network is not a simple single subnet.
    • Reconnection performance is significantly worse because the integration must search the network every time.

  11. Structure of Device Configuration Files

    main

    Device configuration files are written in YAML and map Tuya Data Points (DPs) to Home Assistant attributes. A single device configuration can define multiple Home Assistant entities.

    At the top level, a configuration must include:

    • name: A descriptive, generic name for the device type.
    • products (Optional): A list of specific products this config applies to. Each entry must have an id (matching product_id from cloud info or productKey from local discovery). You can also include manufacturer, model, model_id, and a specific name override.
    • entities: A list of Home Assistant entities provided by the device.

  12. Configure Tuya devices connected via hubs

    main

    When adding a sub-device that connects through a hub (e.g., battery-powered water timers), you must provide the hub's credentials and the sub-device's specific ID:

    • Device id (uuid): Use the hub's device ID.
    • IP address or hostname: Use the hub's IP address or hostname.
    • Local key: Use the hub's local key.
    • Sub device id: Use the actual device's node_id (this is different from the device ID; you can find it using tinytuya).