核心用法
Tuya Cloud Controller 是一款面向智能家居自动化的 IoT 设备管理工具，提供云端 API 与本地 LAN 两种控制模式。核心功能包括：
- 设备发现：
tuya_list_devices列出云端项目下所有设备；scan_local通过 UDP 广播扫描局域网内的 Tuya 设备 - 传感器读取：支持温度（自动除 10 转换）、湿度、电池电量、PIR 运动检测、门磁状态及土壤水分等多类型传感器，
tuya_read_sensor自动解析 DP 点数据 - 历史数据分析：
tuya_read_24h_avg计算土壤湿度 24 小时平均值，用于智能灌溉决策 - 设备控制：
tuya_control_device支持开关、阀门及倒计时定时（分钟级精度），特别针对双通道阀门（switch_1/countdown_1 与 switch_2/countdown_2）提供独立通道控制 - 本地直连：
read_local/control_local无需云端，直接通过 IP 和 local_key 操控设备，降低延迟并避免网络中断风险
显著优点
1. 双模式冗余：云端 API 适合远程管理，本地 LAN 模式保障断网可用性
2. 智能灌溉优化：24 小时土壤湿度均值计算，避免瞬时波动导致的误触发
3. 双通道阀门支持：独立控制左右出水口，适配复杂灌溉场景
4. 多区域兼容：预置 EU/US/CN/IN 四大区域端点，自动适配 Tuya 全球数据中心
5. 配置驱动：config.py 中的 CONTROLLABLE_DEVICES 注册表实现设备别名解析，提升脚本可读性
潜在缺点与局限性
- Zigbee 子设备本地控制受限：
read_local/control_localCLI 命令不直接支持 Zigbee 子设备，需调用 Python API 并手动传递cid参数 - 依赖 Tuya IoT Platform：需手动开通 IoT Core 服务并授权设备控制权限，新手配置门槛较高
- API 速率限制：历史日志查询可能触发限流，导致
count: 0回退至实时读数 - 倒计时精度：仅支持分钟级定时，秒级需求需自行实现二次逻辑
- 本地扫描网络依赖：UDP 广播可能被防火墙或企业网络阻断
适合人群
- 智能家居爱好者搭建自动化灌溉系统
- 开发者集成 Tuya 设备到自建 Home Assistant 或 Node-RED 工作流
- 农业/温室场景需要土壤湿度趋势分析的用户
- 注重隐私、偏好本地控制而非云端依赖的高级用户
常规风险
| 风险类型 | 说明 |
|---------|------|
| 凭证泄露 | `TUYA_ACCESS_ID`/`SECRET` 及 `local_key` 需严格保管，避免硬编码提交至版本控制 |
| 设备误操作 | 双通道阀门控制需确认 `switch_1`/`switch_2` 对应关系，错误通道可能导致灌溉失败或水损 |
| 网络中断 | 纯云端模式下设备离线将导致 `null` 返回值，关键场景建议部署本地 LAN 冗余 |
| 固件兼容性 | Tuya 设备固件更新可能变更 DP 点定义，需持续维护 `parse_sensor_data` 映射表 |
| 倒计时覆盖 | 连续发送倒计时命令会重置计时器，需设计幂等逻辑防止重复触发 |