设备管理 API

所有设备端点以 /api/v1 为前缀。设备 ID 通过 URL 路径参数 {device_id} 指定。

GET /api/v1/devices

获取设备列表。

响应

{
  "success": true,
  "devices": [
    {
      "device_id": "janpnp-001",
      "hostname": "janpnp-host",
      "ip": "192.168.1.10",
      "version": "1.0.0",
      "connect_time": 1721788800.0,
      "last_heartbeat": 1721788860.0,
      "last_status": {},
      "messages_sent": 42,
      "messages_received": 128,
      "alive": true,
      "registered": true
    }
  ]
}

说明：非管理员用户只能看到自己绑定的设备。

GET /api/v1/devices/discover

发现所有已注册且活跃的在线设备。返回最小化的设备信息。

响应

{
  "success": true,
  "devices": [
    {
      "device_id": "janpnp-001",
      "hostname": "janpnp-host",
      "version": "1.0.0",
      "alive": true
    }
  ]
}

GET /api/v1/devices/{device_id}

获取单个设备的完整信息。

响应

{
  "success": true,
  "device": {
    "device_id": "janpnp-001",
    "hostname": "janpnp-host",
    "ip": "192.168.1.10",
    "version": "1.0.0",
    "connect_time": 1721788800.0,
    "last_heartbeat": 1721788860.0,
    "last_status": {},
    "messages_sent": 42,
    "messages_received": 128,
    "alive": true,
    "registered": true
  }
}

错误

状态码	说明
`404`	device not found

GET /api/v1/devices/{device_id}/overview

获取设备的聚合概览。会并发拉取设备的系统、任务、硬件、视觉、相机、调试状态。

响应

{
  "success": true,
  "device": { "...": "设备信息" },
  "connection": {
    "connected": true,
    "alive": true,
    "connect_time": 1721788800.0,
    "last_heartbeat": 1721788860.0,
    "messages_sent": 42,
    "messages_received": 128
  },
  "status": { "状态数据" },
  "detail": {
    "system": { "系统状态" },
    "task": { "任务数据" },
    "hardware": { "硬件位置" },
    "vision": { "视觉状态" },
    "cameras": { "相机状态" },
    "debug": { "调试状态" }
  },
  "partial_errors": {},
  "partial": false
}

GET /api/v1/devices/{device_id}/status

获取设备最后上报的状态。

响应

{
  "success": true,
  "status": { "最后上报的设备状态" }
}

GET /api/v1/devices/{device_id}/connection

获取设备连接状态详情。

响应

{
  "success": true,
  "connected": true,
  "alive": true,
  "connect_time": 1721788800.0,
  "last_heartbeat": 1721788860.0,
  "messages_sent": 42,
  "messages_received": 128
}

POST /api/v1/devices/{device_id}/auth/login

设备登录与绑定。将请求转发给设备验证账号密码，验证通过后建立用户-设备绑定关系。

请求

{
  "username": "operator",
  "password": "device-password"
}

响应

{
  "success": true,
  "device_id": "janpnp-001",
  "user": { "设备端用户信息" }
}

错误

状态码	说明
`502`	设备未连接或未注册
`504`	设备响应超时