HS Knowledge Vault

Tuya IoT 平台接入与本地局域网直连控制（Local-First IoT Hub）

5分钟阅读

Tuya IoT 平台接入与本地局域网直连控制（Local-First IoT Hub）

HS Design 体系智能家居中枢规范
运行环境：IDAPC（Debian WSL 2 常驻 Systemd 服务）
服务端点：http://127.0.0.1:8088 / http://192.168.68.x:8088

⚡ 终局落地架构：Local-First 本地局域网直连控制

1. 痛点根治与技术演进

  • 根本痛点：家庭宽带公网 IP 呈多出口动态轮询（实测 5 分钟内在 27.125.244.x、27.125.243.x 等网段快速跳变），导致涂鸦开放平台频繁报 1114/1010（IP 不在白名单），手动或自动加白均受制于网络延迟与公网可用性。
  • 终局架构（Local-First IoT Hub）：
    • 100% 局域网直连：基于 tinytuya 协议直接与局域网内 Tuya 网关 / Wi-Fi 设备通过 TCP Socket 建立 AES-128 加密通道；
    • 零外网依赖：即使断开外网宽带，内网灯控、风扇、情景模式照常运行；
    • 极致响应延迟：状态查询仅 20ms，控制指令执行 50~150ms；
    • Systemd 常驻守护：/etc/systemd/system/local-tuya-hub.service 开机自启，24/7 稳定运行。

🔑 全量设备密钥表与局域网拓扑（13 台设备）

1. 局域网网关与直连节点

设备 ID设备名称局域网 IPLocal Key协议版本类型
eb9cc6595a801bc44dfgsfZigbee wireless Gateway192.168.68.102nglJQj}GKVyY=B7Qv3.3ZigBee 多模网关
eb919af738309ceaf02fwsMulti-Mode Gateway192.168.68.105`I}V~RVq*O)SfGs`
eb46191b73990b601c2g1xJake IR Remote192.168.68.100`G9L(-{CCKlxA.>R`v3.3
ebf60607f51748bf7dr5ieOffice Smart IR待上线w1u760R.~9}U>4R9v3.3办公室红外遥控

2. 子设备明细（挂载于网关）

子设备 ID子设备名称挂载网关 / CID功能点（DPS 映射）
eb510055dd2c2d4509gjtcJake Bedroom 3路开关网关 192.168.68.102
CID: a4c13869c7960c74		DPS 1 (switch_1): 靠窗灯 / 床灯
DPS 2 (switch_2): 入口灯
DPS 3 (switch_3): 吊扇
eb34b275a1acb08eeailn8Jake Curtain 智能窗帘网关 192.168.68.102
CID: 38398ffffecb59e7		开合比例 / 定时
ebe2d5a41775b182fexk3zHuman Sensor 人体传感器网关 192.168.68.102
CID: a4c138a2a08ac55a		人体感应 / 灵敏度
eb5a599b452bbb3e9cofa9Rear Walkway 走廊灯网关 192.168.68.105
CID: a4c138aa0e7a59ad		DPS 1: 走廊灯开关
eb4ebbf7efb6851ecdblbrEntrance Light 门口灯网关 192.168.68.105
CID: a4c13802f4b28f68		DPS 1: 门口主灯
DPS 2: 辅助灯
eb164197d5adccf3f5dhocJake aircon 海信空调红外遥控 192.168.68.100红外功能码驱动
eb37dc26d8980f899dkidvMistral table fan 台扇红外遥控 192.168.68.100Speed / 摆头
eb9c12ce7dc7305b20jac8Gree Aircon 格力空调办公室红外遥控红外功能码驱动
eb09cf026db4912e58fbjsHisense Aircon 空调办公室红外遥控红外功能码驱动

📡 RESTful API 与 Webhook 接口规范

基础信息

  • Base URL：http://127.0.0.1:8088（或局域网 http://192.168.68.x:8088）
  • 请求格式：支持 Query 参数（?state=on|off）及 JSON Body（{"state": true}）

1. 健康检查与拓扑查询

  • 请求：GET /health
  • 响应：
{
  "status": "healthy",
  "service": "Local Tuya IoT Hub",
  "mode": "LAN Direct (Local-First)",
  "listen": "0.0.0.0:8088",
  "gateways": { ... },
  "devices": { ... }
}

2. 卧室专属快捷控制

端点方法说明对应硬件
/api/bedroom/window_light?state=on|offPOST / GET控制卧室靠窗灯Jake Bedroom switch_1
/api/bedroom/entry_light?state=on|offPOST / GET控制卧室入口灯Jake Bedroom switch_2
/api/bedroom/fan?state=on|offPOST / GET控制卧室吊扇Jake Bedroom switch_3
/api/bedroom/all?state=on|offPOST / GET同步控制卧室所有路Jake Bedroom 1, 2, 3

3. 情景 Webhook（MacroDroid / GPS 地理围栏）

  • 到家开灯：
    • POST /webhook/home
    • 动作：自动开启靠窗灯（DPS 1）与入口灯（DPS 2）。
  • 离家全关：
    • POST /webhook/away
    • 动作：自动关闭卧室所有开关与吊扇（DPS 1, 2, 3）。
  • 向下兼容端点：
    • GET/POST /webhook/tuya?action=home
    • GET/POST /webhook/tuya?action=away

4. 通用设备查询与控制

  • 查询设备状态：GET /api/device/<device_id>/status
  • 控制指定 DPS：POST /api/device/<device_id>/set?dps=1&state=on

🛠️ 系统服务守护配置

Systemd 服务文件

路径：/etc/systemd/system/local-tuya-hub.service

[Unit]
Description=HS Design Local-First Tuya IoT Hub Service
After=network.target network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=root
WorkingDirectory=/root/smart-home
ExecStart=/usr/bin/python3 /root/smart-home/local_hub.py
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal
Environment=PYTHONUNBUFFERED=1
 
[Install]
WantedBy=multi-user.target

常用运维命令

# 查看服务运行状态
systemctl status local-tuya-hub.service
 
# 查看实时日志
journalctl -u local-tuya-hub.service -f
 
# 重启服务
systemctl restart local-tuya-hub.service

📚 离线元数据文件

  • 完整设备云端导出：/root/smart-home/devices.json
  • 本地服务入口：/root/smart-home/local_hub.py

关系图谱

反向链接