介绍
# Homey Smart Home Control
使用令牌认证，通过本地（LAN/VPN）或云端 API 控制 Athom Homey 设备。
## 设置
需要 Node.js >= 18。
1. **确定使用本地还是云端**
- **本地 (LAN/VPN)：** 使用来自 Homey Web App 的本地 API 密钥 + Homey IP 地址 - **云端 (远程/无头模式)：** 使用来自开发者工具的云端令牌
2. **配置**
**本地（当代理在家庭网络中运行时推荐）：**
```bash homeycli auth discover-local --save --pick 1 echo "<LOCAL_API_KEY>" | homeycli auth set-local --stdin # or interactive (hidden input): homeycli auth set-local --prompt ```
**云端（推荐用于 VPS/无头主机托管）：**
```bash echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin # or interactive (hidden input): homeycli auth set-token --prompt ```
检查状态：
```bash homeycli auth status ```
3. **测试连接**
```bash homeycli status ```
## 命令
### 快照（推荐用于代理） ```bash homeycli snapshot --json homeycli snapshot --json --include-flows ```
### 列出设备 ```bash homeycli devices # Pretty table output homeycli devices --json # JSON output for AI parsing (includes latest values)
# Filter by name (returns multiple matches) homeycli devices --match "kitchen" --json ```
### 控制设备 打开/关闭设备： ```bash homeycli device "Living Room Light" on homeycli device "Bedroom Lamp" off ```
设置特定功能： ```bash homeycli device "Dimmer" set dim 0.5 # 50% brightness homeycli device "Thermostat" set target_temperature 21 # Set temperature homeycli device "RGB Light" set light_hue 0.5 # Hue (0-1) homeycli device "Lock" set locked true # Lock device ```
获取功能值： ```bash homeycli device "Thermostat" get measure_temperature homeycli device "Motion Sensor" get alarm_motion
# Get all values for a device (multi-sensors) homeycli device "Living Room Air" values homeycli device "Living Room Air" get ```
### 流程（自动化） ```bash homeycli flows # List all flows homeycli flows --json # JSON output homeycli flows --match "good" --json # Filter flows by name homeycli flow trigger "Good Night" # Trigger by name homeycli flow trigger <flow-id> # Trigger by ID ```
### 区域（房间） ```bash homeycli zones # List all zones/rooms homeycli zones --json # JSON output ```
### 状态 ```bash homeycli status # Show Homey connection info ```
## 常用功能
| 功能 | 类型 | 描述 | 示例 | |------------|------|-------------|---------| | `onoff` | boolean | 电源开关 | `true`, `false` | | `dim` | number | 亮度 (0-1) | `0.5` (50%) | | `light_hue` | number | 色相 (0-1) | `0.33` (绿色) | | `light_saturation` | number | 饱和度 (0-1) | `1.0` (全饱和) | | `light_temperature` | number | 色温 (0-1) | `0.5` (中性) | | `target_temperature` | number | 恒温器目标温度 (°C) | `21` | | `measure_temperature` | number | 当前温度 (只读) | - | | `locked` | boolean | 锁定状态 | `true`, `false` | | `alarm_motion` | boolean | 检测到动作 (只读) | - | | `alarm_contact` | boolean | 门磁传感器 (只读) | - | | `volume_set` | number | 音量 (0-1) | `0.5` |
使用 `homeycli devices` 查看每个设备支持的功能。
## 模糊匹配
设备和流程名称支持模糊匹配： - **完全匹配：** "Living Room Light" → 找到 "Living Room Light" - **子字符串：** "living light" → 找到 "Living Room Light" - **编辑距离：** "livng light" → 找到 "Living Room Light" (容错拼写)
## JSON 模式
在任何命令中添加 `--json` 以获取机器可读的输出： ```bash homeycli devices --json | jq '.[] | select(.class == "light")' homeycli status --json ```
## 示例
**晨间例程：** ```bash homeycli device "Bedroom Light" on homeycli device "Bedroom Light" set dim 0.3 homeycli device "Thermostat" set target_temperature 20 ```
**检查温度：** ```bash homeycli device "Living Room" get measure_temperature ```
**触发场景：** ```bash homeycli flow trigger "Movie Time" ```
**列出所有灯光：** ```bash homeycli devices --json | jq '.[] | select(.class == "light") | .name' ```
## 故障排除
**"No auth configured"（未配置认证）**
本地 (LAN/VPN)： - 保存本地配置：`echo "<LOCAL_API_KEY>" | homeycli auth set-local --address http://<homey-ip> --stdin`
云端 (远程/无头模式)： - 保存云端令牌：`echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin` - 云端令牌可以在 Homey 开发者工具中创建：https://tools.developer.homey.app/api/clients
**"Device not found"（设备未找到）/ ambiguous match（匹配模糊）** - 使用 `homeycli devices --json`（或 `homeycli devices --match <query> --json`）列出设备以找到正确的 `id` - 如果查询匹配到多个设备，CLI 会返回候选 ID 并要求您通过 ID 指定设备
**"Capability not supported"（不支持该功能）** - 检查可用功能：`homeycli devices` 会显示每个设备支持的功能 - 常见问题：尝试打开传感器（请使用 `get` 而不是 `set`）
## API 参考
CLI 使用官方的 `homey-api` npm 包 (v3.15.0)。
**认证/连接模式：**
- **本地模式：** `HomeyAPI.createLocalAPI({ address, token })`，使用 Homey Web App 的本地 API 密钥。 - **云端模式：** `AthomCloudAPI`，使用云端持有者令牌 (PAT) 创建会话并访问设备/流程/区域。