V1 蓝牙接口与设备绑定
接口总览
小程序与设备之间有两种通信方式：业务命令（AT 指令，走 BLUFI custom data 通道）和配网控制帧（BLUFI 标准协议帧，仅 WiFi 配网模式使用）。
业务命令（所有模式通用）
通过 BLUFI CUSTOM_DATA 数据帧收发，内容为纯 ASCII 字符串，无换行/终止符。
| 方向 | 命令 | 说明 | 触发时机 |
|---|---|---|---|
| 手机 → 设备 | AT+GETID | 请求设备立即执行一轮授权并回复设备码 | 连接后主动拉取；绑定成功后通知重启 |
| 设备 → 手机 | AT+ID=<device_id> | 上报设备码 | 连接后自动一轮；收到 AT+GETID 后立即一轮；联网成功后自动一轮；兜底每 60s 一轮 |
注意
设备码（device_id）：由云端鉴权接口返回（格式以云端为准），是设备的公开唯一标识。小程序拿到后调用下方云端绑定接口完成绑定。
云端绑定接口
小程序通过以下接口与云端交互，完成设备绑定。接口基础地址：https://api.jimitu.top/lg/mac-auth/api。
所有请求均需携带 Authorization: Bearer <mac_auth_key>（格式：mk_xxxxxxx，平台签发的客户密钥），并在请求体（或查询参数）中传入 external_user_id（调用方自己的用户标识，用于绑定归属）。
POST /bind：绑定设备
请求信息
- 请求 URI：
POST https://api.jimitu.top/lg/mac-auth/api/bind
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <mac_auth_key>，设备配对客户密钥（mk_ 开头，平台签发） |
Content-Type | 否 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_id | string | 是 | 通过 BLE 获取的设备码 |
external_user_id | string | 是 | 调用方用户标识（绑定归属） |
channel_id | integer | 否 | 渠道 ID，不传则自动识别 |
请求示例
bash
curl -X POST "https://api.jimitu.top/lg/mac-auth/api/bind" \
-H "Authorization: Bearer <mac_auth_key>" \
-H "Content-Type: application/json" \
-d '{"device_id": "<device_id>", "external_user_id": "<your_user_id>"}'响应信息
成功时返回：
json
{
"success": true,
"data": {
"mac": "<mac>",
"lingge_device_id": "<device_id>",
"lingge_binding_id": 33,
"lingge_character_id": 71,
"cm_user_id": "<your_user_id>",
"bound_at": "<timestamp>"
}
}设备已被其他用户绑定时返回 409 冲突：
json
{
"success": false,
"error_code": "EXTERNAL_USER_ID_DUPLICATE",
"message": "设备已被其他账号绑定"
}注意
遇到 409 冲突时，可提示用户确认换绑，换绑调用 POST /rebind。
POST /rebind：换绑设备
本接口为拓展能力，原接口无此功能。自动解绑旧用户，绑定到当前用户。
请求信息
- 请求 URI：
POST https://api.jimitu.top/lg/mac-auth/api/rebind
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <mac_auth_key>，设备配对客户密钥（mk_ 开头，平台签发） |
Content-Type | 否 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_id | string | 是 | 要绑定的设备码 |
external_user_id | string | 是 | 调用方用户标识 |
channel_id | integer | 否 | 渠道 ID，不传则自动识别 |
请求示例
bash
curl -X POST "https://api.jimitu.top/lg/mac-auth/api/rebind" \
-H "Authorization: Bearer <mac_auth_key>" \
-H "Content-Type: application/json" \
-d '{"device_id": "<device_id>", "external_user_id": "<your_user_id>"}'响应信息
成功时返回：
json
{
"success": true,
"data": {
"mac": "<mac>",
"lingge_device_id": "<device_id>",
"lingge_binding_id": 33,
"lingge_character_id": 71,
"cm_user_id": "<your_user_id>",
"bound_at": "<timestamp>"
}
}DELETE /bind：解绑设备
请求信息
- 请求 URI：
DELETE https://api.jimitu.top/lg/mac-auth/api/bind
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <mac_auth_key>，设备配对客户密钥（mk_ 开头，平台签发） |
Content-Type | 否 |
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
device_id | string | 是 | 要解绑的设备码 |
external_user_id | string | 是 | 调用方用户标识 |
请求示例
bash
curl -X DELETE "https://api.jimitu.top/lg/mac-auth/api/bind" \
-H "Authorization: Bearer <mac_auth_key>" \
-H "Content-Type: application/json" \
-d '{"device_id": "<device_id>", "external_user_id": "<your_user_id>"}'响应信息
json
{
"success": true,
"data": {
"device_id": "<device_id>",
"unbound": true
}
}注意
解绑后设备重启时检测到 unbound，会重新进入蓝牙广播等待绑定。
GET /list：查询已绑定设备
请求信息
- 请求 URI：
GET https://api.jimitu.top/lg/mac-auth/api/list?external_user_id=<your_user_id>
| Header | 必填 | 说明 |
|---|---|---|
Authorization | 是 | Bearer <mac_auth_key>，设备配对客户密钥（mk_ 开头，平台签发） |
请求示例
bash
curl -X GET "https://api.jimitu.top/lg/mac-auth/api/list?external_user_id=<your_user_id>" \
-H "Authorization: Bearer <mac_auth_key>"响应信息
json
{
"success": true,
"data": [
{
"device_id": "<device_id>",
"bound_at": "2026-08-17T10:00:00Z"
}
]
}注意
返回该用户标识下所有已绑定的设备列表。