Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

rustuya

GitHub release

Local control of Tuya devices in Home Assistant, with no cloud round trip for state or commands.

rustuya talks to your devices over the LAN through rustuya-bridge, interprets them, and creates their Home Assistant devices and entities itself, with the IL device hub built in.

Tuya devices ──LAN──► rustuya-bridge ──MQTT──► rustuya ──► Home Assistant entities

Tuya Cloud is only used once, to fetch your device list and local keys (QR code login from the Smart Life / Tuya Smart app).

Requirements

  • Home Assistant 2025.3 or newer.
  • An MQTT broker (for example the Mosquitto broker add-on), which rustuya-bridge needs. rustuya connects to it itself; Home Assistant's MQTT integration is not required. Without one, rustuya can run a small broker of its own (see Setup).
  • rustuya-bridge, either one you already run, or the one rustuya can run inside Home Assistant (amd64 and aarch64).

Installation

Open your Home Assistant instance and open a repository inside the Home Assistant Marketplace.

  1. In Marketplace, search for rustuya and download it.
  2. Add integration → rustuya (see below).

Setup

Setup first asks how rustuya should run. MQTT is the small message hub that devices and programs use to talk to each other (the broker). If you don't know what it is, pick the first option.

choice when
Beginner: everything inside Home Assistant (recommended) You don't know MQTT and don't want to set up a broker. rustuya runs rustuya-bridge and a small broker of its own (pymqttd) between them, reachable only from this machine.
Expert: my own MQTT broker; Home Assistant runs the bridge You already run a broker (for example the Mosquitto add-on). rustuya starts and owns rustuya-bridge itself.
Expert: my own MQTT broker and my own rustuya-bridge You already run both. Setup checks that your running bridge answers on the broker; if it is not on the default topic root rustuya, it asks for that root.

For the two expert choices, enter the broker (host, port, optional username and password).

The built-in broker is for a setup without one. If you already have a broker, using it alongside your own is possible and will not conflict, but it is not recommended: it only duplicates the broker you have. Choose it on purpose, for example to keep rustuya's traffic isolated from your other devices. Otherwise use one of the expert choices, and share your own broker if other devices need it. The built-in broker runs as a separate process, listens only on 127.0.0.1 with credentials made up at each start, and is stopped with Home Assistant, so nothing else on your network can use it. What it retains lives in memory: after a Home Assistant restart the devices show their last values, unavailable, until the bridge has reconnected to them.

The rustuya panel

Configure → Add the rustuya panel to the sidebar adds an administrator panel. It shows:

  • Devices: the Tuya Cloud list compared with what the bridge holds. You can filter by missing, bridge only, mismatch, online and offline, see sub-devices under their gateway, add, update or remove devices, and Register manually (Wi-Fi devices or sub-devices without a cloud login).

  • Converter files: list, edit, delete or drop in your own rule files (see Non-standard devices), and Update builtin rules.

  • Options:

    • remote control of locks, alarms and garage doors (off by default)
    • data points Home Assistant core would not classify (off by default)
    • automatic builtin rule updates (on by default)
  • Settings:

    • bridge topic root
    • device file
    • embedded bridge's state file and log level

    Saving restarts the integration.

Hide panel in its toolbar removes it from the sidebar again. The integration and the panel are available in English and Korean.

Cover settings

A curtain or blind that moves the wrong way, or reports opening / closing wrongly, can be fixed from its own configuration entities. Each appears only where it changes something:

setting shown when the cover has use it when
Invert current position a position it reports fully opened, it shows 0%
Invert target position a target position, separate from the reported one Open closes it
Invert control an open / close command and no target position Open closes it
Use target as current position distinct reported and target position sources the target should supply the displayed position
Motion state source a position or control data point inferred (default) infers motion, control uses the device's control reports, none disables it
Invert reported motion the control motion source opening and closing are reversed

These change nothing on the device. They are saved to zz_settings.json in <config>/rustuya_converters/ and survive restarts.

Non-standard devices

Tuya's cloud schemas are fragmented, and some devices report data points the standard mapping does not know. Fixes are JSON rule files in <config>/rustuya_converters/ (or dropped onto the panel), applied live:

{"overrides": {"<product_id>": {"cover": {"invert_position": true}}}}

A rule can rename a data point, define one the schema lacks, map the device's words to standard ones, fix labels and classes, or define a declarative converter. See tuya-interpreter's device customization guide. Python code is never loaded.

Official builtin rules for known devices are downloaded into rustuya_converters/rules/builtin/ at start and daily. A yellow dot on Update builtin rules means an update is waiting when automatic updates are off. Updates only touch files they downloaded, and your own files are applied after them.

If you write a fix for a common device, please contribute it to tuya-interpreter so everyone gets it as a builtin rule.

Service: rustuya.send_command

Writes one raw data point to a device, bypassing IL. Fire and forget.

action: rustuya.send_command
data:
  device_id: bf0123456789abcdef   # Tuya device id, or the Home Assistant device id
  dp: "1"
  value: true

Locks, alarms and garage doors are refused unless their remote control is allowed in the panel's Options.

Removing a device

For a device you no longer have:

  1. Remove it from the bridge: in the panel's Devices, or under Configure → Sync devices with the bridge by selecting it in Remove from the bridge. rustuya then deletes it from Home Assistant, and the bridge clears its own retained topics. Removing a gateway removes its sub-devices too.
  2. Once it is gone from the Smart Life / Tuya Smart app (delete it there if it is still listed), fetch the device list again (Configure → Fetch devices from Tuya Cloud), so it no longer shows as missing.

Home Assistant refuses to delete a device the bridge still holds, since it would come right back. Fetching the list again after it is gone from the app takes it out of Home Assistant, but the bridge keeps it, as bridge only in the panel, and keeps trying to reach it until you remove it from the bridge.

Upgrading from a version before 0.2

rustuya used to publish IL over MQTT for the IL device integration. It now creates the entities itself and publishes nothing on the broker, and it does not take over the old entities. To move, keeping the same entity IDs (areas, custom names and other registry changes are lost):

  1. Before updating, disable the rustuya entry.

  2. Clear what it left on the broker, so IL device deletes those devices. This clears every retained topic under the prefix: if another IL producer shares it, restart that producer afterwards, or clear only the topics of your devices.

    mosquitto_sub -h <broker> -t 'il/#' --retained-only --remove-retained -W 3
    
  3. Update rustuya, restart Home Assistant and enable the entry. Remove IL device if nothing else uses it.

Done in another order, the old entities keep their IDs and the new ones get a _2 suffix.

Removing

Deleting the integration removes its devices from Home Assistant and deletes the device list and Tuya login it kept under .storage/rustuya/. With the embedded bridge it also clears that bridge's retained topics and state file. A device file you pointed elsewhere and everything on an external bridge are left alone. Then remove rustuya in HACS and restart.

Troubleshooting

  • No devices appear: check the device is registered on the bridge (the panel's Devices) and in the device list.

  • A device stays unavailable: the Home Assistant log has a warning naming the device and why, also shown on its card in the panel's Devices:

    • not connected … code 914: the bridge reached the device but it rejected the local key or protocol version.
    • not connected … code 905: the bridge cannot reach it. With rustuya-bridge 0.4.6 or later the reason says how: refused or closed (often another local client, such as LocalTuya or Tuya Local, holding the device's only connection), unreachable or dial_timeout (IP, subnet, VLAN, firewall), not_located (no IP set and none heard on the LAN; in a container, use host networking).
    • connected but sent no state: the connection is up but the device's state never arrives; usually a wrong protocol version.
  • Commands or values look doubled: run only one rustuya per bridge. The integration cannot see a standalone daemon or rustuya-manager plugin on the same bridge, since it no longer shares IL with them over MQTT.

  • Debug logs:

    logger:
      logs:
        custom_components.rustuya: debug
        rustuya_local: debug
    

Issues: https://github.com/3735943886/rustuya-local/issues

Other ways to run it

The same service also runs outside Home Assistant, for any IL consumer:

Run only one of them per bridge.

For contributors:

License: MIT

Metadata

Release files for rustuya-local 0.2.3rc3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rustuya-local 0.2.3rc3
File Size Uploaded Provenance Actions
rustuya_local-0.2.3rc3.tar.gz 289.5 kB With provenance Details for rustuya_local-0.2.3rc3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rustuya-local 0.2.3rc3
File Interpreter ABI Platform Actions
rustuya_local-0.2.3rc3-py3-none-any.whl Python 3 none any Details for rustuya_local-0.2.3rc3-py3-none-any.whl

Total release size: 354.3 kB

Release files / rustuya_local-0.2.3rc3.tar.gz

Download URL rustuya_local-0.2.3rc3.tar.gz
Size 289.5 kB
Tags Source
SHA-256 checksum
How to use checksums
8b8fbf9b3203eca125d587565ea4e8bbfd951df25c2705aa764961f976ecbf12
BLAKE2b-256 checksum
How to use checksums
8d3a08467d5f19f28bc145d728466a8f057cc61b6aa0f94fef8baf32c2c31b5c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / rustuya_local-0.2.3rc3-py3-none-any.whl

Download URL rustuya_local-0.2.3rc3-py3-none-any.whl
Size 64.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
64233a7638ec28aa2d871ae9aa31d4888da7df5cd2758fac96c48df744b30548
BLAKE2b-256 checksum
How to use checksums
51be291711f0b3672740af9d2e0bf2642d009baf81efdd0233c3a884b8f8abe6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for rustuya-local 0.2.3rc3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rustuya_local-0.2.3rc3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page