使用本地 API

开始前

• 核对型号与固件

  使用兼容的 LANBON 联网版本。在面板设置中记下型号和固件版本，将电脑或控制器接到同一可信局域网。Mesh 组网使用主节点的地址和 Token。

• 在面板启用开放集成

  在面板打开「设置 → 开放集成」，开启总开关。通过「显示 Token」取得当前 Token。记下面板局域网 IP 和本地 API 端口，默认 8765。支持 mDNS 的客户端可查找 _lanbon._tcp.local.。Token 仅放入 Authorization 请求头。

查询设备与能力

1. 验证连接

   在 Bash 中运行以下命令（Windows 可用 Git Bash）。输入面板的地址、协议、端口和 Token。IPv6 地址请加方括号。成功时 /info 返回 HTTP 200。记下 gateway_id、firmware_version 和 transports.events。协议默认 HTTP，设备声明 HTTPS 时输入 https。

   复制

   read -r -p 'Panel IP or hostname: ' LOIP_HOST
   read -r -p 'API scheme [http]: ' LOIP_SCHEME
   if [ -z "$LOIP_SCHEME" ]; then LOIP_SCHEME=http; fi
   read -r -p 'API port [8765]: ' LOIP_PORT
   if [ -z "$LOIP_PORT" ]; then LOIP_PORT=8765; fi
   LOIP_BASE="$LOIP_SCHEME://$LOIP_HOST:$LOIP_PORT"
   read -r -s -p 'Panel token: ' LOIP_TOKEN
   echo
   curl --noproxy "*" --max-time 10 -sS -i -H "Authorization: Bearer $LOIP_TOKEN" "$LOIP_BASE/api/v1/info"

2. 读取快照

   在同一个终端运行下面的命令。用 devices[].id 找到在线目标，再从 components[] 复制组件 id。检查 enabled、commands 和 constraints。实际模式、可用命令和数值范围由这里的返回值决定。

   复制

   curl --noproxy "*" --max-time 10 -sS -i -H "Authorization: Bearer $LOIP_TOKEN" "$LOIP_BASE/api/v1/devices"

发送指令并验证

1. 准备请求

   选择一项可以安全操作的功能。把示例保存为 loip-command.json，替换设备和组件 ID，并根据组件的 commands 与 constraints 修改 command 和 params。每个新操作使用新的 request_id。

   复制

   {
     "request_id": "setup-001",
     "device_id": "aabbccddeeff",
     "component_id": "switch:1",
     "command": "set_on",
     "params": {
       "on": true
     }
   }

2. 提交并回读

   HTTP 200 且 status 为 completed 表示已完成。HTTP 202 / accepted 表示已接收，继续看后续状态。再运行上一步的快照命令，确认目标组件的 state 已更新。示例开关应显示 on 为 true。若请求超时，先回读状态再决定下一步。

   复制

   curl --noproxy "*" --max-time 10 -sS -i -H "Authorization: Bearer $LOIP_TOKEN" -H "Content-Type: application/json" --data-binary @loip-command.json "$LOIP_BASE/api/v1/command"

常见组件命令

以下是 LOIP 的命令示例。先从设备快照确认组件类型、命令与允许值，再把命令及参数填入上方的完整 JSON。窗帘、调光等功能随产品和当前模式变化。

开关 switch

set_on {"on":true}

调光 light

set_brightness {"brightness":50}

风扇 fan

set_speed_level {"speed_level":1}

窗帘 cover

stop {}

热水器 water_heater

set_on {"on":true}

保持状态同步

• WebSocket

  如果 /info 声明 events 为 websocket，连接 ws://<面板地址>:<端口>/api/v1/events（HTTPS 对应 wss），在握手时传入同一 Authorization 请求头。首次连接、重连、解析失败或收到 topology_changed 时重新读取 /devices。收到 state_changed 时用事件中的完整组件状态更新对应组件。

• 轮询

  如果 /info 声明 events 为 polling，定时读取 /devices，例如每 30 秒一次，并在发送命令后主动刷新。设备返回 ETag 时可原样用于 If-None-Match。304 表示保留上一次快照。把 revision 当作不透明标识。

排错与停用

• 找不到面板或连接超时

  核对总开关、主节点地址和实际端口。自动发现受网络隔离影响时，手动使用面板 IP。保持 API 在可信局域网内。

• 401、目标不存在或参数错误

  401 时从面板重新读取当前 Token。找不到组件、设备离线或参数不合法时，先重新读取快照，核对在线状态、组件 ID、当前模式与命令参数。

• 结束访问

  临时停用可关闭面板的开放集成总开关。需要撤销旧凭据时在面板执行轮换或撤销，并更新获准继续连接的客户端。在终端运行 unset LOIP_TOKEN 清除本次会话的变量。

资料与下载

python -m pip install aiolanbon==0.2.1