TOS API 接口文档

Base URL: https://api.otodone.com

TOS API 是 otoDone 物联网平台的核心后端服务，为设备端和管理控制台提供 RESTful 接口。

---

设备端接口（v1）

设备主动调用的接口，用于心跳、上报数据、拉取指令等。

心跳

POST /v1/device/heartbeat

设备定期上报在线状态，服务端根据心跳时间判断设备是否在线（60 秒无心跳判定离线）。

设备信息

GET /v1/device/{device_id}

获取单个设备的基本信息（型号、固件版本、IP、最后在线时间等）。

遥测上报

POST /v1/device/{device_id}/telemetry

单条遥测数据上报。

POST /v1/device/{device_id}/telemetry/batch

批量遥测数据上报。

指令拉取与确认

GET /v1/device/{device_id}/commands

设备拉取待执行的指令队列。

POST /v1/device/{device_id}/commands/ack

设备确认指令已执行，上报执行结果。

配置管理

GET /v1/device/{device_id}/config

获取设备配置。

POST /v1/device/{device_id}/config

设置设备配置。

日志上报

POST /v1/device/{device_id}/logs

单条日志上报。

POST /v1/device/{device_id}/logs/batch

批量日志上报，支持 JSON 数组或 text/plain 格式。

时间同步

GET /v1/time

获取服务器当前时间戳。

POST /v1/device/{device_id}/time/sync

设备时间同步请求。

OTA 升级检查

GET /tos/upgrade/check
GET /v1/ota/check

检查固件是否有新版本可用。

设备绑定

GET /v1/device/{device_id}/bind/code

获取设备绑定码。

GET /v1/device/{device_id}/bind/status

查询设备绑定状态。

POST /v1/bind/verify

验证绑定请求。

---

管理端接口（Admin）

Console 控制台调用的接口，需要在请求头中携带 X-Console-Token 进行认证。

元数据

GET /api/admin/meta

获取系统元数据，包括表情列表、HID 键值映射等。

汇总统计

GET /api/admin/summary

获取设备汇总统计信息（在线设备数、指令计数等）。

设备列表

GET /api/admin/devices

获取全部设备列表。

设备详情

GET /api/admin/device/{device_id}/detail

获取单个设备的详细信息。

添加设备

POST /api/admin/device/add

请求体示例：

{
  "device_id": "404e6efc4ba0",
  "model": "TOS-CNAEK7"
}

删除设备

POST /api/admin/device/{device_id}/delete

删除指定设备及其相关数据。

下发指令

POST /api/admin/device/{device_id}/command

向设备下发控制指令。请求体示例：

{
  "action": "bleep",
  "params": {
    "duration": 80
  }
}

设置表情

POST /api/admin/device/{device_id}/expression

设置设备当前表情。

HID 操作

POST /api/admin/device/{device_id}/hid

下发 HID 键鼠操作指令。

日志查询

GET /api/admin/logs

获取操作日志。

POST /api/admin/logs/clear

清理日志数据。

指令队列

GET /api/admin/commands

获取指令队列记录。

POST /api/admin/commands/clear

清理指令队列。

---

认证方式

接口类型	认证方式
设备端 v1	通过 device_id 标识设备身份
管理端 Admin	请求头 X-Console-Token

---

常用指令参考

action	说明	params 示例
bleep	蜂鸣	{"duration": 80}
sync_time	同步时间	{}
ota_check	检查固件更新	{}
ping	心跳测试	{}
reboot	重启设备	{}
expression	设置表情	{"expression": "happy"}
hid_text	HID 文本输入	{"text": "hello"}
hid_combo	HID 组合键	{"keys": ["ctrl", "shift", "esc"]}
hid_key	HID 单键按下	{"key": "enter"}
hid_click	HID 鼠标点击	{"button": "left", "hold": 35}
hid_scroll	HID 滚轮滚动	{"wheel": -4}
hid_vendor	HID 厂商自定义	{"text": "ping"}
hid_release	HID 释放全部按键	{}