This release is a pre-release and may not be stable for production use.
rustuya
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
- In Marketplace, search for rustuya and download it.
- 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:
- 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.
- 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):
-
Before updating, disable the rustuya entry.
-
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
-
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
reasonsays how:refusedorclosed(often another local client, such as LocalTuya or Tuya Local, holding the device's only connection),unreachableordial_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:
- Standalone daemon (
pip install rustuya-local) - rustuya-manager plugin
Run only one of them per bridge.
For contributors:
License: MIT
Metadata
Release files for rustuya-local 0.2.3rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rustuya_local-0.2.3rc1.tar.gz | 286.5 kB | With provenance | Details for rustuya_local-0.2.3rc1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rustuya_local-0.2.3rc1-py3-none-any.whl | Python 3 | none | any | Details for rustuya_local-0.2.3rc1-py3-none-any.whl |
Total release size: 351.0 kB
Release files / rustuya_local-0.2.3rc1.tar.gz
| Download URL | rustuya_local-0.2.3rc1.tar.gz |
|---|---|
| Size | 286.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
753ce747b3dcad89f67a322ca5aebabbf2e49f3114652000e382b779c3c216f2
|
|
BLAKE2b-256 checksum How to use checksums |
e4d0ea0775967d8573b0d8cedcab5db2b72ea03d562ed4ece6cf0cfa6061122f
|
| 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 15, 2026.
Transparency logRelease files / rustuya_local-0.2.3rc1-py3-none-any.whl
| Download URL | rustuya_local-0.2.3rc1-py3-none-any.whl |
|---|---|
| Size | 64.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dd879c4348294bc2464cff23600d09d8a52f709294d3c3b24eec3d9bd09b9f6d
|
|
BLAKE2b-256 checksum How to use checksums |
df31de96031156c70abb755086fef9dc95839749dcd184be1719a493e5c98b4f
|
| 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 15, 2026.
Transparency logSecurity for rustuya-local 0.2.3rc1
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.
Attestation for rustuya_local-0.2.3rc1.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 15, 2026.
Transparency logA 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.