smarthome

Control global smart home devices via Home Assistant (preferred) and Tuya Smart (fallback) with fuzzy name matching and local device caching.

SKILL.md universal-smarthome 通用智能家居支配Skill Dominate your smart home with seamless control across Home Assistant and Tuya Smart. 通过Home Assistant（首选）和涂鸦智能（备选）操控全球品牌家电，支持模糊名称匹配。

Setup 设置 Option 1: Config File (Recommended) 选项1：配置文件（推荐） Create /.config/universal-smarthome/config.json: 创建/.config/universal-smarthome/config.json：

{ "homeassistant": { "url": "http://homeassistant.local:8123", "token": "your-long-lived-access-token" }, "tuya": { "access_id": "your-access-id", "access_secret": "your-access-secret", "endpoint": "https://openapi.tuyacn.com" } } Option 2: Environment Variables 选项2：环境变量 export HA_URL="http://homeassistant.local:8123" export HA_TOKEN="your-long-lived-access-token" export TUYA_ACCESS_ID="your-access-id" export TUYA_ACCESS_SECRET="your-access-secret" Getting Home Assistant Token 获取Home Assistant令牌 Open Home Assistant → Profile (bottom left) 打开Home Assistant → 个人资料（左下角） Scroll to "Long-Lived Access Tokens" 滚动到“长期访问令牌” Click "Create Token", name it (e.g., "Clawdbot") 点击“创建令牌”，将其命名（例如，“Clawdbot”） Copy the token immediately (shown only once) 立即复制令牌（仅显示一次） Getting Tuya Credentials 获取涂鸦凭据 Log in to Tuya Smart Platform (https://iot.tuya.com/) 登录涂鸦智能开放平台（https://iot.tuyacn.com/） Create a cloud project or navigate to "Cloud Development" 创建云项目或进入“云开发” Get access_id and access_secret from the project credentials 从项目凭据中获取access_id和access_secret Quick Reference 快速参考 Discovery 设备发现 python3 scripts/smart.py discovery Sync all devices from Home Assistant and Tuya to local cache. 从Home Assistant和涂鸦同步所有设备到本地缓存。

Control Devices 控制设备

Turn on device by name

python3 scripts/smart.py control "device_name" on

Turn off device by name

python3 scripts/smart.py control "device_name" off

The script automatically identifies the platform (HA or Tuya) based on device ID

脚本根据设备ID自动识别平台（HA或涂鸦）

Device Name Matching 设备名称匹配 The script supports fuzzy name matching: 脚本支持模糊名称匹配：

If device_cache.json contains:

{"id": "light.living_room", "name": "客厅灯", "platform": "homeassistant"}

User can say: "打开客厅灯" or "打开灯"

用户可以说：“打开客厅灯”或“打开灯”

Priority: Exact name match → ID match → Fuzzy match 优先级：精确名称匹配 → ID匹配 → 模糊匹配 CLI Wrapper CLI包装器 The scripts/smart.py CLI provides smart home control: scripts/smart.py CLI提供智能家居控制：

Discovery - sync all devices

python3 scripts/smart.py discovery

Control device by name

python3 scripts/smart.py control "客厅灯" on python3 scripts/smart.py control "卧室灯" off

The script will:

1. Look up device ID from local cache

2. Try Home Assistant first (preferred)

3. Fallback to Tuya Cloud if HA fails or device not found

脚本将：

1. 从本地缓存查找设备ID

2. 优先尝试Home Assistant

3. 若HA失败或设备不存在，回退到涂鸦云端

Supported Platforms 支持平台 Platform平台 Features功能 Priority优先级 Home Assistant Local control, fast response, entity-based 本地控制，响应快，基于实体 1 (Primary) 首选 Tuya Cloud Cloud API, broader device support 云端API，更广泛的设备支持 2 (Fallback) 备选 Common Issues & Solutions 常见问题与解决方案 Error: Config missing 错误：配置文件缺失 Solution: Create /.config/universal-smarthome/config.json 解决方案：创建/.config/universal-smarthome/config.json

Error: 1004: Sign Invalid 错误：1004: 签名无效 Solution: Check Tuya access_id and access_secret. Ensure endpoint matches your region (cn/com/us/eu). 解决方案：检查涂鸦access_id和access_secret。确保endpoint匹配您的区域（cn/com/us/eu）。

Error: Entity not found 错误：实体未找到 Solution: Run "python3 scripts/smart.py discovery" to sync devices first. 解决方案：先运行“python3 scripts/smart.py discovery”同步设备。

Error: Connection refused (HA) 错误：连接被拒绝（HA） Solution: Check HA_URL, ensure Home Assistant is running and accessible. 解决方案：检查HA_URL，确保Home Assistant正在运行且可访问。

Error: 401 Unauthorized (HA) 错误：401未授权（HA） Solution: Token expired or invalid. Generate a new Long-Lived Access Token. 解决方案：令牌过期或无效。生成新的长期访问令牌。

Device not responding 设备无响应 Solutions: 解决方案：

1. Check if device is online in respective app (HA or Tuya) 检查设备是否在相应应用（HA或涂鸦）中在线
2. Try controlling directly in Home Assistant or Tuya app 尝试直接在Home Assistant或涂鸦应用中控制
3. Run discovery again to refresh device cache 再次运行discovery刷新设备缓存 Architecture 架构设计 ┌─────────────────┐ │ User Request │ │ 用户请求 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Semantic Parse │ │ 语义解析 │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Device Lookup │ │ 设备查找 │──────▶ Local Cache │ │ (device_cache.json) └────────┬────────┘ │ ▼ ┌────┴────┐ │ │ ▼ ▼ ┌───────┐ ┌───────┐ │ HA │ │ Tuya │ │ 优先 │ │ 备选 │ └───┬───┘ └───┬───┘ │ │ └────┬────┘ │ ▼ ┌─────────────────┐ │ Control Result │ │ 控制结果 │ └─────────────────┘ Security 安全说明 Credentials are stored locally at /.config/universal-smarthome/ 凭据存储在本地/.config/universal-smarthome/ No hardcoded tokens or secrets in scripts 脚本中无硬编码的令牌或密钥 Only访问用户定义的HA address and Tuya official API 只访问用户定义的HA地址和涂鸦官方API No third-party data exfiltration 无第三方数据回传 Troubleshooting 故障排除 401 Unauthorized: HA token expired or invalid. Generate a new one. 401未授权：HA令牌过期或无效。生成新的令牌。

Connection refused: Check HA_URL, ensure HA is running and accessible. 连接被拒绝：检查HA_URL，确保HA正在运行且可访问。

Entity not found: Run discovery to sync devices first. 实体未找到：先运行discovery同步设备。

1004 Sign Invalid: Verify Tuya credentials and region endpoint. 1004签名无效：验证涂鸦凭据和区域endpoint。

All platforms failed: Check network connection and device online status. 所有平台失败：检查网络连接和设备在线状态。

API Reference API参考 For advanced usage and custom integrations, see: 高级使用和自定义集成，请参阅：

Home Assistant API: https://developers.home-assistant.io/docs/api/rest/ Tuya Cloud API: https://developer.tuya.com/en/docs/iot/api-reference/list