W751 多路柜门锁控制器 云端控制接口文档

项目概述

W751是多路柜门锁控制系统的上位机，基于WiFi模块，通过MQTT协议连接云端，并通过串口与CabinetController下位机通信，实现对36路×N块板子的柜门锁控制。

系统架构

云端服务器 <--Internet--> W751 <--串口或485--> CabinetController(下位机) --> 36路柜门锁
                                              |
                                              +---> CabinetController(地址1) --> 36路
                                              |
                                              +---> CabinetController(地址2) --> 36路
                                              ...

W751 开发者API文档

概述

本文档描述了 W751 多路柜门锁控制系统的云端 API 接口，开发者可通过这些接口实现设备注册、远程开锁、状态查询等功能。

错误码说明

错误码说明
0x00成功
0x01未知命令
0x02参数错误
0x03校验错误
0x04执行失败
0xFF通信超时
点击下面的序号展开
1. 开锁 (open_lock)

  • 开启指定柜门锁（脉冲模式，到期自动关闭）

请求URL

  • MQTT主题: {device_sn} (设备序列号)

请求方式

  • MQTT消息发布

请求格式

  • json

参数（方式一：板地址+锁号）
{
  "msg_id": 1,
  "data": {
    "cmd_type": "open_lock",
    "info": {
      "addr": 0,
      "lock": 5,
      "duration": 10,
      "cmd_id": "order123",
      "user_id": "user456"
    }
  }
}
参数（方式二：全局锁号）
{
  "msg_id": 1,
  "data": {
    "cmd_type": "open_lock",
    "info": {
      "global_lock": 41,
      "duration": 10
    }
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：open_lock
data.info.addr否int板子地址 0-7，默认0 (方式一必填)
data.info.lock否int锁号 1-36 (方式一必填)
data.info.global_lock否int全局锁号 1-288 (方式二必填)
data.info.duration否int脉冲时间（单位100ms），0或不填=默认1秒
data.info.cmd_id否string业务命令ID，用于回调
data.info.user_id否string用户ID，用于回调
返回示例
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 1,
  "cmd": "open_lock",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "addr": 0,
    "lock": 5
  }
}
返回参数说明
参数名类型说明
device_snstring设备序列号
typeint消息类型：1=响应
msg_idint对应请求的消息ID
cmdstring命令类型
info.codeint业务错误码，0成功其他异常
info.err_codeint硬件错误码
info.msgstring错误描述
info.addrint板子地址
info.lockint锁号

 

2. 批量开锁 (open_locks)

  • 同时开启同一块板子上的多个锁

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数
{
  "msg_id": 2,
  "data": {
    "cmd_type": "open_locks",
    "info": {
      "addr": 0,
      "locks": [1, 3, 5, 7],
      "duration": 10
    }
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：open_locks
data.info.addr是int板子地址 0-7
data.info.locks是array锁号数组，每个元素1-36
data.info.duration否int脉冲时间（单位100ms）
返回示例
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 2,
  "cmd": "open_locks",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "addr": 0,
    "requested": 4,
    "success": 4,
    "opened": [1, 3, 5, 7]
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.requestedint请求开启的锁数量
info.successint成功开启的锁数量
info.openedarray成功开启的锁号列表

 

3. 开全部锁 (open_all_locks)

  • 开启指定板子上所有36路锁

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数
{
  "msg_id": 3,
  "data": {
    "cmd_type": "open_all_locks",
    "info": {
      "addr": 0
    }
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：open_all_locks
data.info.addr否int板子地址 0-7，默认0
返回示例
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 3,
  "cmd": "open_all_locks",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "addr": 0
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.addrint板子地址

 

4. 关全部锁 (close_all_locks)

  • 强制关闭指定板子上所有锁（立即中止脉冲）

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数
{
  "msg_id": 4,
  "data": {
    "cmd_type": "close_all_locks",
    "info": {
      "addr": 0
    }
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：close_all_locks
data.info.addr否int板子地址 0-7，默认0
返回示例
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 4,
  "cmd": "close_all_locks",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "addr": 0
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.addrint板子地址

 

5. 查询门状态 (get_door_status)

  • 查询柜门开关状态（1=关闭，0=打开）

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数（查询单板）
{
  "msg_id": 5,
  "data": {
    "cmd_type": "get_door_status",
    "info": {
      "addr": 0
    }
  }
}
参数（查询所有在线板）
{
  "msg_id": 5,
  "data": {
    "cmd_type": "get_door_status",
    "info": {}
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：get_door_status
data.info.addr否int板子地址 0-7，不填则查询所有在线板
返回示例（单板）
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 5,
  "cmd": "get_door_status",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "addr": 0,
    "doors": [1,1,1,0,1,1,1,1, 1,1,1,1,1,1,1,1, 1,1,1,1,1,1,1,1, 1,1,1,1,1,1,1,1, 1,1,1,1],
    "raw": "F7FFFFFFFF"
  }
}
返回示例（所有板）
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 5,
  "cmd": "get_door_status",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "boards": [
      {"addr": 0, "doors": [1,1,1,1,...]},
      {"addr": 1, "doors": [1,1,1,1,...]}
    ]
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.addrint板子地址（单板查询时）
info.doorsarray36个门状态，1=关闭，0=打开
info.rawstring原始位图数据（HEX格式）
info.boardsarray所有板的门状态数组（批量查询时）

 

6. 扫描在线板子 (scan_boards)

  • 扫描所有在线的下位机板子

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数
{
  "msg_id": 6,
  "data": {
    "cmd_type": "scan_boards",
    "info": {}
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：scan_boards
data.info是object暂未使用
返回示例
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 6,
  "cmd": "scan_boards",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "count": 2,
    "online_addrs": [0, 1]
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.countint在线板子数量
info.online_addrsarray在线板子地址列表

 

7. 心跳检测 (cabinet_heartbeat)

  • 检测指定板子是否在线

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数
{
  "msg_id": 7,
  "data": {
    "cmd_type": "cabinet_heartbeat",
    "info": {
      "addr": 0
    }
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：cabinet_heartbeat
data.info.addr是int板子地址 0-7
返回示例
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 7,
  "cmd": "cabinet_heartbeat",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "addr": 0,
    "online": true
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.addrint板子地址
info.onlinebool在线状态：true=在线，false=离线

 

8. 控制板载继电器 (cabinet_relay)

  • 控制下位机板子上的P3.4继电器（可用于总电源控制等）

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数
{
  "msg_id": 8,
  "data": {
    "cmd_type": "cabinet_relay",
    "info": {
      "addr": 0,
      "on": true
    }
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：cabinet_relay
data.info.addr是int板子地址 0-7
data.info.on是bool继电器状态：true=吸合，false=断开
返回示例
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 8,
  "cmd": "cabinet_relay",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "addr": 0,
    "on": true
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.addrint板子地址
info.onbool当前继电器状态

 

9. 获取设备信息 (getdevinfo)

  • 获取W751上位机及连接的柜门锁控制器信息

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数
{
  "msg_id": 9,
  "data": {
    "cmd_type": "getdevinfo",
    "info": {}
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：getdevinfo
data.info是object暂未使用
返回示例
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 9,
  "cmd": "getdevinfo",
  "info": {
    "code": 0,
    "sw_ver": "51.0.01",
    "hw_ver": "1.0.0",
    "project": "W751",
    "rssi": -45,
    "free_heap": 120000,
    "cabinet": {
      "online_boards": 2,
      "boards": [
        {"addr": 0, "version": "2.0.11", "channels": 36},
        {"addr": 1, "version": "2.0.11", "channels": 36}
      ]
    },
    "device_pwd": "123456",
    "admin_pwd": "888888",
    "callback_url": "http://your-server.com/callback",
    "callback_enabled": 1,
    "pending_callbacks": 0
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.sw_verstring上位机软件版本
info.hw_verstring上位机硬件版本
info.projectstring项目型号
info.rssiintWiFi信号强度（dBm）
info.free_heapint可用内存（字节）
info.cabinet.online_boardsint在线柜控板数量
info.cabinet.boardsarray柜控板数组
info.cabinet.boards[].addrint板地址 (0-7)
info.cabinet.boards[].versionstring固件版本号
info.cabinet.boards[].channelsint通道数量 (36)

 

10. 下位机OTA升级 (cabinet_ota)

  • 远程升级STC8H下位机固件

请求URL

  • MQTT主题: {device_sn}

请求方式

  • MQTT消息发布

请求格式

  • json

参数
{
  "msg_id": 10,
  "data": {
    "cmd_type": "cabinet_ota",
    "info": {
      "addr": 0,
      "url": "http://ota.example.com/CabinetController_v2.0.11_OTA.hex"
    }
  }
}
参数名必选类型说明
msg_id是int消息ID
data.cmd_type是string命令类型：cabinet_ota
data.info.addr否int板子地址 0-7，默认0
data.info.url是string固件下载地址（Intel HEX格式）
返回示例
//成功
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 10,
  "cmd": "cabinet_ota",
  "info": {
    "code": 0,
    "err_code": 0,
    "msg": "",
    "addr": 0,
    "status": "ota_complete"
  }
}
//失败
{
  "device_sn": "W751XXXX",
  "type": 1,
  "msg_id": 10,
  "cmd": "cabinet_ota",
  "info": {
    "code": 1,
    "err_code": -1,
    "msg": "cabinet_ota failed: -1",
    "error_code": -1
  }
}
返回参数说明
参数名类型说明
info.codeint业务错误码，0成功其他异常
info.addrint板子地址
info.statusstring升级状态：ota_complete=成功
info.error_codeint失败时的错误码
备注

  • 固件URL必须是可公网访问的HTTP地址

  • 固件格式必须是Intel HEX格式（.hex文件）

  • 升级过程中设备会自动重启下位机

  • 下位机采用"不死模式"，升级失败可重试

 

11. 回调通知

门状态变化通知将发送到用户注册的回调地址

a. 门状态变化事件 (door_event)

当柜门状态发生变化时，设备会主动上报：

{
  "device_sn": "W751XXXX",
  "type": 2,
  "cmd_type": "door_event",
  "info": {
    "addr": 0,
    "doors": [1,1,1,0,1,1,...],
    "raw": "F7FFFFFFFF"
  }
}
参数类型说明
cmd_typestringdoor_event：门状态变化通知
device_snstring设备序列号
info.addrint发生变化的板子地址
info.doorsarray36个门状态，1=关闭，0=打开
info.rawstring原始位图数据（HEX格式）

b. 设备上线通知 (online)

当设备连接到服务器时，会发送上线通知：

{
  "device_sn": "W751XXXX",
  "type": 2,
  "cmd_type": "online",
  "info": {
    "model": "W751",
    "sw": "51.0.01",
    "rssi": -45,
    "cabinet_boards": 2
  }
}
参数类型说明
cmd_typestringonline：设备上线通知
device_snstring设备序列号
info.modelstring设备型号
info.swstring软件版本
info.rssiint信号强度（dBm）
info.cabinet_boardsint在线柜控板数量

附录

设备序列号规则

W751 设备序列号格式为：W751 + MAC地址后6位

示例：W751A1B2C3

全局锁号计算

全局锁号 = (板地址 × 36) + 锁号

示例计算结果
第0板第1锁0×36+11
第0板第36锁0×36+3636
第1板第1锁1×36+137
第1板第5锁1×36+541
第7板第36锁7×36+36288

支持的命令类型汇总

cmd_type说明
open_lock开锁（单个）
open_locks批量开锁
open_all_locks开全部锁
close_all_locks关全部锁
get_door_status查询门状态
scan_boards扫描在线板子
cabinet_heartbeat心跳检测
cabinet_relay控制继电器
getdevinfo获取设备信息
cabinet_ota下位机OTA升级

回调通知类型汇总

cmd_type说明
door_event门状态变化通知
online设备上线通知

更新记录

版本日期说明
1.0.02025-12-01初始版本
1.1.02026-01-28新增下位机OTA升级接口，合并版本查询到getdevinfo
作者：极客师傅  创建时间：2026-01-28 20:11
最后编辑：极客师傅  更新时间：2026-01-28 20:28
上一篇：
下一篇：