ShowenV2/clients/docs/API.md

ShowenV2 HTTP API 文档

基础信息

• Base URL: http://<device-ip>:8080
• API 前缀: /api
• 编码: UTF-8
• 认证: 当前版本无认证

响应约定

• 控制类/写操作接口统一返回：

{
  "status": "ok",
  "message": "开始播放"
}

• 失败时返回：

{
  "status": "error",
  "message": "错误描述"
}

• 查询类接口直接返回业务 JSON，不包裹 ok 字段。

Web UI

控制台页面

GET /
GET /index.html

• 当前实现为内嵌单文件 Web UI。
• 暂无独立静态资源目录服务；页面所需 CSS/JS 已内嵌在 HTML 中。

WebSocket

连接地址

ws://<device-ip>:8080/ws

服务端事件

• status_update
• config_update
• state_update
• ble_update

播放控制

获取播放状态

GET /api/status

响应示例：

{
  "running": true,
  "paused": false,
  "in_transition": false,
  "current_index": 0,
  "playlist_length": 3,
  "current_video": "intro"
}

播放

POST /api/play

暂停

POST /api/pause

下一个

POST /api/next

上一个

POST /api/previous

跳转到指定视频

POST /api/goto/:index

• index: 从 0 开始的视频索引

获取播放列表

GET /api/playlist

切换场景

POST /api/scene/:name

• name: 场景名称字符串，不是数字索引

触发状态机事件

POST /api/trigger/:name
POST /api/trigger/:name/:value

• value 为可选路径参数

配置

获取完整配置

GET /api/config

获取显示配置

GET /api/config/display

更新配置

POST /api/config
Content-Type: application/json

• 请求体为完整配置 JSON
• 服务端会先校验，再写回配置文件，并向管理层发送热重载请求

视频文件管理

获取视频列表

GET /api/videos

响应示例：

[
  {
    "name": "demo.mp4",
    "size": 1048576
  }
]

上传视频

POST /api/videos/upload
Content-Type: multipart/form-data

• 表单字段名：file
• 支持多文件上传

删除视频

DELETE /api/videos/:filename

WiFi

获取 WiFi 状态

GET /api/wifi/status

响应示例：

{
  "connected": true,
  "ssid": "MyWiFi",
  "ip": "192.168.1.10"
}

扫描 WiFi

GET /api/wifi/scan
POST /api/wifi/scan

响应示例：

[
  {
    "ssid": "MyWiFi",
    "signal": -50,
    "security": "WPA2"
  }
]

连接 WiFi

POST /api/wifi/connect
Content-Type: application/json

{
  "ssid": "MyWiFi",
  "password": "password123"
}

开启热点

POST /api/wifi/ap/start
POST /api/wifi/hotspot/start
Content-Type: application/json

请求体可选：

{
  "ssid": "showen",
  "password": "12345678"
}

关闭热点

POST /api/wifi/ap/stop
POST /api/wifi/hotspot/stop

BLE

获取 BLE 状态

GET /api/ble/status

响应示例：

{
  "running": true,
  "embedded": true,
  "device_name": "showen"
}

BLE 兼容启动接口

POST /api/ble/start
Content-Type: application/json

请求体可选：

{
  "device_name": "showen"
}

BLE 兼容停止接口

POST /api/ble/stop

与旧文档的差异说明

• 不存在 /api/stop
• 不存在 /api/wifi/disconnect
• /api/scene/:name 使用场景名，不使用数字索引
• 查询接口直接返回业务对象，不再包裹 { "ok": true, ... }