Skip to main content

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 the way Home Assistant's own tuya integration does (via tuya-interpreter), and publishes them over MQTT as IL devices. The companion integration IL device turns them into Home Assistant devices and entities.

Tuya devices ──LAN──► rustuya-bridge ──MQTT──► Rustuya ──MQTT (il/…)──► IL device ──► 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) and Home Assistant's MQTT integration connected to it.
  • The IL device integration (in HACS), which creates the entities. Rustuya creates no entities itself.
  • 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 Community Store.

  1. In HACS, search for Rustuya and download it. Download IL device too.
  2. Restart Home Assistant.
  3. Settings → Devices & services → Add integration → IL device, with the topic prefix Rustuya will publish under (see IL topic prefix).
  4. Add integration → Rustuya (see below).

Setup

Setup first asks how to reach rustuya-bridge:

choice when
An external rustuya-bridge You already run rustuya-bridge (or rustuya-manager). Setup checks that the bridge answers on the broker; if it is not on the default topic root rustuya, it asks for that root.
Run rustuya-bridge inside Home Assistant Nothing else is running. Rustuya starts and owns the bridge itself. It still needs the MQTT broker.

Then enter the broker (host, port, optional username and password) and the IL topic prefix.

IL topic prefix

The default is il, which is also IL device's default, and is fine when Rustuya is your only IL producer. If you use, or may later add, other IL producers (for example rusthinq), give each its own prefix such as il/tuya. IL device then gets one entry per prefix, a separate hub with its own devices and options. Use the same prefix in Rustuya and in its IL device entry. The prefix can be changed later in the panel's Settings.

Next, setup offers to fetch your devices from Tuya Cloud:

  1. Enter the user code from Smart Life → Me → Settings → Account and Security (only needed for the first login).
  2. Scan the QR code with the Smart Life or Tuya Smart app and submit.
  3. Choose which devices to add to, update on, or remove from the bridge. Nothing changes unless you select it.

A saved login is reused next time. You can skip this step by closing the window and run it later from the integration's Configure.

Only devices registered on the bridge are published. They are then discovered by IL device: add them there (or turn on its Add discovered devices automatically).

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
    • IL prefix and source
    • device file
    • embedded bridge's state file and log level

    Saving restarts the integration. Moving the IL prefix or source first clears what the old one left on the broker.

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

Deleting the integration removes its devices from IL (so IL device removes them 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

  • The integration keeps retrying with "another producer": another Rustuya (the standalone daemon or the rustuya-manager plugin) already publishes on the same IL prefix and source. Run only one per bridge: stop the other one, and this one starts on its next retry.

  • No devices appear: check the device is registered on the bridge (the panel's Devices), that IL device uses the same prefix as Rustuya (see IL topic prefix), and that the device was added in IL device's discovered list.

  • 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.1.2

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.1.2
File Size Uploaded Provenance Actions
rustuya_local-0.1.2.tar.gz 267.2 kB With provenance Details for rustuya_local-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 329.6 kB

Release files / rustuya_local-0.1.2.tar.gz

Download URL rustuya_local-0.1.2.tar.gz
Size 267.2 kB
Tags Source
SHA-256 checksum
How to use checksums
901186778a464ec8dc43d2b2d2540136db748a6e396c3db0a9e927662308f349
BLAKE2b-256 checksum
How to use checksums
843a080233ca059e567bcff9b51188d1cfa7609e8cb3703c7b999c4f163be7ba
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 Oct 21, 2026.

Transparency log

Release files / rustuya_local-0.1.2-py3-none-any.whl

Download URL rustuya_local-0.1.2-py3-none-any.whl
Size 62.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
784268c1ab362bf99c5113a6091623a523d324261b86be17c252b01d933c8c8c
BLAKE2b-256 checksum
How to use checksums
4a525cf72f070785b27d6cd072279563078fd75840bd8622291f67f83a156cc9
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 Oct 21, 2026.

Transparency log

Security for rustuya-local 0.1.2

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.1.2.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 Oct 21, 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

0.1.2 This release

2 release files Full provenance

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