MQTT 指令控制与 HTTP OpenAPI

选择接入方式

快速开始：查询音量

复制curl -X POST "https://iot.yikedi.cn/openapi/devices/4CEBD60BFD62/commands" \
  -H "Authorization: Bearer ykd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"cmd-0001","command":"GETVOLUME;"}'

复制curl "https://iot.yikedi.cn/openapi/devices/4CEBD60BFD62/requests/cmd-0001" \
  -H "Authorization: Bearer ykd_your_api_key"

复制Topic: ykd/devices/4CEBD60BFD62/cmd

{
  "requestId": "cmd-0001",
  "command": "GETVOLUME;"
}

复制{
  "requestId": "cmd-0001",
  "mac": "4CEBD60BFD62",
  "feedback": "VOLUME current=45;"
}

连接参数与设备标识

deviceId 与 Client ID

deviceId 固定使用设备大写 MAC：12 位十六进制字符，不带冒号、短横线或空格，例如 4CEBD60BFD62。播放器默认 Client ID 为 ykdplayer-4CEBD60BFD62。

Topic 总表

管理多台设备时可订阅 ykd/devices/+/reply、ykd/devices/+/api/reply、ykd/devices/+/api/progress、ykd/devices/+/status 和 ykd/devices/+/playback/status。所有上行消息都带 mac，用它区分设备。

MQTT 请求与反馈格式

基础控制请求

复制{
  "requestId": "cmd-0002",
  "command": "SELECTPLAYLIST 1;PLAY 1;"
}

基础控制反馈

复制{
  "requestId": "cmd-0002",
  "mac": "4CEBD60BFD62",
  "feedback": "OK:SELECTPLAYLIST;OK:PLAY;"
}

requestId 匹配请求，mac 区分设备，feedback 是实际执行结果。批量命令遇到失败时停止后续命令。

当前内容播放状态与进度 Topic

视频、图片、网页、PDF 和 PPT 的播放状态与进度统一发布到 ykd/devices/{deviceId}/playback/status。播放期间约每 1 秒发布；暂停、完成、停止或错误时立即发布状态变化。

MQTT Payload

复制{
  "mac": "4CEBD60BFD62",
  "playSessionId": "90d89d0e-1470-44c8-9c75-fb8cf9fb7ab6",
  "sequence": 5,
  "mediaType": "video",
  "fileName": "company.mp4",
  "state": "playing",
  "positionMs": 42000,
  "durationMs": 120000,
  "ended": false,
  "reason": null,
  "reportedAt": 1788400000000
}

PDF / PPT 页进度

文档播放会额外携带 pageNumber、totalPages、pagePositionMs 和 pageDurationMs。页码从 1 开始。

状态与上报行为

该 Topic 使用 QoS 1、Retain=true。Retain 只表示 Broker 保存最后一条播放状态；服务器仍应结合 state、reportedAt 和设备在线状态判断内容是否仍在播放。

接口地址与鉴权

平台网页、OpenAPI 和 MQTT Broker 的对外域名统一使用 iot.yikedi.cn。

1. 1
   登录平台

   登录 YKD IoT 设备管理平台。

2. 2
   生成 API Key

   进入“开发设置 → HTTP API”，选择权限和有效期。登录后可按需查看完整 Key，页面会在 60 秒后自动隐藏。

3. 3
   服务端调用

   每次请求增加 Authorization: Bearer ykd_xxx。

权限 Scope

OpenAPI 接口总表

下表路径均相对于接口根地址。路径中的 {mac} 使用设备的 12 位大写 MAC。

发送任意基础 CMD

前面 CMD 表中的每一条命令，都通过同一个 commands 接口发送。requestId 可省略，由平台自动生成；需要幂等控制时建议主动提供。

复制POST /openapi/devices/4CEBD60BFD62/commands
Authorization: Bearer ykd_your_api_key
Content-Type: application/json

{
  "requestId": "cmd-0002",
  "command": "SELECTPLAYLIST 1;PLAY 1;"
}

平台先返回 202 accepted；再查询 GET /openapi/devices/4CEBD60BFD62/requests/cmd-0002，完成后的 feedback 为 OK:SELECTPLAYLIST;OK:PLAY;。

设备查询示例

复制# 名下设备
GET /openapi/devices

# 单台设备与播放状态
GET /openapi/devices/4CEBD60BFD62/status

读取当前播放进度

GET /devices/{mac} 和 GET /devices/{mac}/status 都返回独立的 playback 对象；后者还返回设备原始 status 与服务器时间。以下为 playback 节选：

复制{
  "playback": {
    "playSessionId": "90d89d0e-1470-44c8-9c75-fb8cf9fb7ab6",
    "sequence": 5,
    "mediaType": "video",
    "fileName": "company.mp4",
    "state": "playing",
    "positionMs": 42000,
    "durationMs": 120000,
    "ended": false,
    "reason": null,
    "reportedAt": 1788400000000,
    "playing": true,
    "online": true
  }
}

playback 来自 MQTT playback/status；设备在线、开关机、IP、版本和音量等信息仍来自 MQTT status，两者不再共用一个消息。

播放列表与文件进阶功能

MQTT 发布到 ykd/devices/{deviceId}/api/request；OpenAPI 发布到 POST /devices/{mac}/requests。两种方式的请求体相同。

查询播放列表

复制{
  "requestId": "list-0001",
  "method": "GET",
  "path": "/api/dir"
}

查询播放项

复制{
  "requestId": "file-list-0001",
  "method": "GET",
  "path": "/api/dir/file?playlist_index=1"
}

从地址下载并添加单文件

复制{
  "requestId": "upload-0001",
  "method": "POST",
  "path": "/api/item/add",
  "body": {
    "playlist_index": 1,
    "name_alias": "企业宣传片"
  },
  "file": {
    "download_url": "https://oss.example.com/company.mp4?signature=xxx",
    "file_name": "company.mp4",
    "size": 356728901,
    "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

download_url、file_name、size、sha256 都必填。设备直接从 HTTPS 地址下载；MQTT 不传文件二进制。

从设备导出单文件

复制{
  "requestId": "download-0001",
  "method": "GET",
  "path": "/api/file/downloaditems?playlist_index=1&index=3",
  "file": {
    "upload_url": "https://oss.example.com/export/company.mp4?signature=xxx"
  }
}

删除播放项

复制{
  "requestId": "delete-0001",
  "method": "POST",
  "path": "/api/item/delete",
  "body": { "playlist_index": 1, "index": 3 }
}

平台素材上传与发送

适合客户先把素材上传到 YKD IoT 平台，再让指定播放器直接从对象存储下载。

1. 上传素材

复制curl -X POST "https://iot.yikedi.cn/openapi/materials?name=company.mp4" \
  -H "Authorization: Bearer ykd_your_api_key" \
  -H "Content-Type: video/mp4" \
  --data-binary "@company.mp4"

2. 发送到设备

复制POST /openapi/devices/4CEBD60BFD62/materials/{materialId}/send
Authorization: Bearer ykd_your_api_key
Content-Type: application/json

{
  "requestId": "upload-0002",
  "playlistIndex": 1,
  "nameAlias": "企业宣传片"
}

平台只通过 MQTT 下发下载地址、文件名、大小和 SHA-256；播放器直接访问素材地址，文件不会经过 MQTT Broker。

查询反馈、进度与事件

按 requestId 查询

复制GET /openapi/devices/4CEBD60BFD62/requests/upload-0001
Authorization: Bearer ykd_your_api_key

文件任务状态依次为 accepted → downloading → verifying → importing → completed；失败时为 failed。

复制{
  "requestId": "upload-0001",
  "mac": "4CEBD60BFD62",
  "kind": "advanced",
  "state": "downloading",
  "progress": {
    "state": "downloading",
    "progress": 35
  }
}

查询事件

GET /devices/{mac}/events?after=时间戳&limit=100。可用 type=reply、apiReply、apiProgress、status 或 playbackStatus 过滤。播放进度事件示例：GET /devices/{mac}/events?type=playbackStatus。

MQTT 进阶反馈

复制{
  "requestId": "upload-0001",
  "mac": "4CEBD60BFD62",
  "state": "failed",
  "error": "CHECKSUM_MISMATCH",
  "message": "file sha256 mismatch"
}

HTTP 状态码、错误与安全规则

常见文件错误码

INVALID_REQUESTREQUEST_ID_CONFLICTAPI_NOT_ALLOWEDPLAYLIST_NOT_FOUNDFILE_NOT_FOUNDFILE_EXISTSDOWNLOAD_FAILEDUPLOAD_FAILEDNO_SPACESIZE_MISMATCHCHECKSUM_MISMATCH