rustuya 0.3.0

A fast and concurrent Tuya Local API implementation in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

# Rustuya

[![Crates.io](https://img.shields.io/crates/v/rustuya.svg)](https://crates.io/crates/rustuya)
[![Pypi.org](https://badge.fury.io/py/rustuya.svg)](https://badge.fury.io/py/rustuya)
[![Documentation](https://docs.rs/rustuya/badge.svg)](https://docs.rs/rustuya)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Local-network control of Tuya-compatible devices, built in Rust with
first-class Python bindings. Designed for fleets of hundreds to
thousands of devices — a native Rust core handles the I/O while the
Python facade releases the GIL on every blocking call, so threaded
Python workers stay live.

## Install

**Rust**

```bash
cargo add rustuya
```

**Python**

```bash
pip install rustuya
```

## Quick start

**Rust (sync)**

```rust
use rustuya::sync::Device;

let dev = Device::new("DEVICE_ID", "LOCAL_KEY");
dev.set_value(1, true)?;                        // turn on DP 1
println!("{:?}", dev.status()?);                // read current DPS

for msg in dev.listener() {                     // real-time events
    println!("{:?}", msg);
}
```

**Rust (async)** — inside a `tokio` runtime

```rust
use rustuya::Device;
use futures_util::StreamExt;

#[tokio::main]
async fn main() -> Result<(), rustuya::TuyaError> {
    let dev = Device::new("DEVICE_ID", "LOCAL_KEY");
    dev.set_value(1, true).await?;              // turn on DP 1
    println!("{:?}", dev.status().await?);      // read current DPS

    let mut listener = dev.listener();
    while let Some(msg) = listener.next().await {   // real-time events
        println!("{:?}", msg);
    }
    Ok(())
}
```

**Python**

```python
from rustuya import Device

dev = Device("DEVICE_ID", "LOCAL_KEY")
dev.set_value(1, True)                          # turn on DP 1
print(dev.status())                             # read current DPS

for msg in dev.listener():                      # real-time events
    print(msg)
```

## Features

- Local-only — talks directly to devices over LAN, no Tuya Cloud
- Rust core + Python bindings (PyO3) — same engine for both
- Built for fleet scale — per-device background tasks with
  automatic reconnection and exponential backoff
- Full protocol coverage — Tuya 3.1 / 3.2 / 3.3 / 3.4 / 3.5 + device22

### Tested at fleet scale

Large-scale behavior is exercised against real mock devices — a 1000-device
[tuyamock](https://github.com/3735943886/tuyamock) fleet with actual TCP
connections and handshakes, not just unit mocks:

- **This repo** stands up the 1000-device fleet and asserts every connection
  establishes without deadlock under a bounded connect-concurrency cap, in CI
  ([`python/tests/test_fleet_scale.py`](python/tests/test_fleet_scale.py)).
- The downstream [rustuya-bridge](https://github.com/3735943886/rustuya-bridge)
  goes further end-to-end: a 1000-device fleet onboards cleanly with zero
  retained orphans after a mass clear, and a separate test holds the fleet idle
  for 30s to prove the heartbeat keeps every connection alive (witnessed
  mock-side) before fanning a single name-addressed command out to the whole
  fleet.

It proves the fleet machinery (bounded connect with no deadlock, heartbeat
survival, fan-out) holds with 1000 concurrent devices over real sockets, end to
end.

See the [Guide](https://3735943886.github.io/rustuya/) for the full API
reference, design philosophy, and architecture notes.

## Credits

The Tuya protocol layer in rustuya is derived from the specifications
and error codes documented in
[tinytuya](https://github.com/jasonacox/tinytuya):

- [Protocol Reference](https://github.com/jasonacox/tinytuya/blob/master/PROTOCOL.md)

## License

MIT