Architecture
Rustuya is designed with a layered architecture that separates network concerns, protocol logic, and user-facing APIs. This separation ensures high performance, reliability, and ease of maintenance.
Layer Overview
- User API Layer: Provides high-level interfaces for Rust and Python.
- Sync Wrapper Layer: Bridges the asynchronous core to synchronous APIs for ease of use in simple scripts.
- Core Logic Layer: Manages device lifecycle, connection pooling, and event dispatching.
- Protocol Layer: Handles Tuya-specific message framing, encryption, and decryption.
- Transport Layer: Manages low-level TCP/UDP communication using
tokio.
Component Breakdown
- Device (device/): Represents a single physical Tuya device. Manages its own background connection task.
- Protocol (protocol/mod.rs): Implements the Tuya protocol versions (3.1 to 3.5, and device22 variation).
- Crypto (crypto.rs): Handles AES encryption and MD5/HMAC hashing required by the protocol.
- Scanner (scanner.rs): Manages UDP discovery for finding devices on the local network.
- Runtime (runtime.rs): Internal utilities for managing background tasks and timers.
- Sync (sync.rs): A blocking wrapper around the asynchronous core, providing a simple interface for synchronous environments.
- Python (python/src/lib.rs): PyO3-based bindings that expose the library’s functionality to Python with native performance.
For maintainer-facing notes on how each component actually behaves at runtime — lifecycles, channels, timers, backoff math, the unified-listener model, and the small decisions that the layer overview glosses over — see Technical Notes.