W76M（WiFi+蓝牙 mini 门禁控制器）API

概述

W76M 是单门 WiFi+蓝牙门禁控制器，设备序列号以 W76M 开头。本文档说明设备注册、远程开门、门磁与继电器配置、WiFi 配置、在线查询、OTA 和蓝牙应急开门协议。

  • API 基础地址：https://wdev.wmj.com.cn
  • 云端命令地址：POST https://wdev.wmj.com.cn/deviceApi/send
  • 当前量产维护版本：76.0.5，适用 W76M 硬件 1.0.0、软件 76.0.x 版本线。
  • 76.0.5 支持 set_ext_button 及开门按钮事件；旧版本使用前应通过 getdevinfo 确认返回 ext_button_enabled 字段。

除单独标明的地址外，下列云端命令均使用 POST https://wdev.wmj.com.cn/deviceApi/send，请求头为 Content-Type: application/json。

云端接口的 code=0 表示平台请求成功；设备命令还应检查 data.info.code。涉及配置变更时，建议再次调用 getdevinfo 回读最终状态。

点击下面的序号展开
1.注册设备

简要描述

将 W76M 设备绑定到开发者账号。注册成功后才能调用设备控制接口。

请求URL

https://wdev.wmj.com.cn/deviceApi/register

请求方式

POST

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}
参数名 必选 类型 说明
app_id 是 string 开发者 app_id
app_secret 是 string 开发者 app_secret
device_sn 是 string W76M 设备序列号

返回示例

{
  "code": 0,
  "msg": "注册成功"
}
2.远程开门

简要描述

按设备当前配置的继电器脉冲时长触发开门。脉冲时长通过 set_relay 设置。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "open",
    "info": {
      "sn": "{{device_sn}}"
    }
  }
}
参数名 必选 类型 说明
data.cmd_type 是 string 固定为 open
data.info.sn 否 string 传入时必须与目标设备序列号一致

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "type": 1,
    "cmd_type": "open",
    "info": {
      "doorstate": 0,
      "err_code": 0,
      "code": 0,
      "msg": ""
    }
  }
}

备注

  • doorstate 是门磁输入状态，不等同于继电器动作反馈。
  • 若设备处于常开模式，开门命令只进行提示，不重复改变常开状态。
3.获取设备信息

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "getdevinfo",
    "info": {}
  }
}

主要返回字段

字段 类型 说明
sw_ver string 软件版本
hw_ver string 硬件版本
project string 固定为 W76M
net_type string 固定为 wifi
sta_ssid string 当前 WiFi 名称
rssi number WiFi 信号强度，单位 dBm
doorstate number 门磁状态：0 或 1
switch_state number 当前继电器输出状态
nonc number 0=常闭模式，1=常开模式
relay1 number 开门继电器脉冲时长，单位毫秒
device_sound number 蜂鸣器：0=关闭，1=启用
ext_button_enabled number 开门按钮：0=停用，1=启用；仅支持该字段的固件返回
ble_advertising boolean 蓝牙是否正在广播
mqtt_connected boolean MQTT 是否已连接
free_heap number 当前空闲堆内存
min_free_heap number 本次启动后的最小空闲堆内存
uptime_ms number 本次启动后的运行时间，单位毫秒
code number 设备业务码，0 表示成功
msg string 设备业务说明

备注

设备信息可能包含配置字段，业务系统不应将完整原始响应写入公开日志。

4.获取门状态

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "getdoorstate",
    "info": {}
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "getdoorstate",
    "info": {
      "doorstate": 0,
      "err_code": 0,
      "code": 0,
      "msg": ""
    }
  }
}
5.设置常开/常闭模式

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_nonc",
    "info": {
      "type": 0
    }
  }
}
参数名 必选 类型 说明
data.info.type 是 number 0=常闭模式，1=常开模式

返回说明

成功时 data.info.nonc 返回最终模式。配置会持久保存。

6.设置继电器脉冲时长

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_relay",
    "info": {
      "relay1": 1000
    }
  }
}
参数名 必选 类型 取值范围 说明
data.info.relay1 是 number 100～60000 开门继电器脉冲时长，单位毫秒

成功时 data.info.relay1 返回保存后的时长。

7.设置蜂鸣器

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_device_sound",
    "info": {
      "device_sound": 1
    }
  }
}
参数名 必选 类型 说明
data.info.device_sound 是 number 0=关闭提示音，1=启用提示音
8.远程配置WiFi

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_wifi",
    "info": {
      "ssid": "ExampleWiFi",
      "passwd": "example-password"
    }
  }
}
参数名 必选 类型 说明
data.info.ssid 是 string 2.4GHz WiFi 名称，最长32字节
data.info.passwd 是 string WiFi 密码；开放网络可传空字符串，最长63字符

备注

  • 兼容字段 password，新接入建议统一使用 passwd。
  • 此接口只保存 WiFi 配置，不立即切换当前连接。保存成功后，在允许设备短暂离线的维护窗口调用 restart 使新配置生效，再查询在线状态并回读 sta_ssid；不要以保存应答代替联网结果。
9.修改设备密码

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_pwd",
    "info": {
      "device_pwd": "new-device-password",
      "admin_pwd": "new-admin-password"
    }
  }
}
参数名 必选 类型 说明
data.info.device_pwd 否 string 本地应急开门密码，最长31字符
data.info.admin_pwd 否 string 配网页面管理密码，最长31字符

至少传入一个需要修改的密码。密码属于敏感信息，禁止记录在公开日志中。

10.设置开门按钮

版本要求

当前 76.0.5 支持此协议。旧版本应先检查 getdevinfo 是否返回 ext_button_enabled；不返回时请先升级，不能假定接口可用。

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_ext_button",
    "info": {
      "enable": 1
    }
  }
}
参数名 必选 类型 说明
data.info.enable 是 number 只接受数字 0 或 1

行为说明

  • 1：启用短按开门和 ext_button 事件。
  • 0：停用短按开门和事件；不影响长按5秒进入配网及长按15秒恢复出厂。
  • 配置持久保存。成功后应调用 getdevinfo 校验 ext_button_enabled。
11.开门按钮主动事件

启用按钮后，每次确认短按上报一次 type=2 事件：

{
  "device_sn": "{{device_sn}}",
  "type": 2,
  "cmd_type": "ext_button",
  "info": {
    "event": "press",
    "state": 1,
    "uptime_ms": 123456,
    "event_uid": "{{device_sn}}-2-123456-1"
  }
}

业务系统应使用 event_uid 做幂等去重。设备离线时本地按钮开门不受影响，但事件不会补发。

12.重启设备

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "restart",
    "info": {}
  }
}

设备先返回应答，约1.2秒后重启。应通过在线状态和 getdevinfo.uptime_ms 确认重启结果。

13.OTA固件升级

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_ota",
    "info": {
      "hw_ver": "1.0.0",
      "sw_ver": "76.0.5",
      "url": "http://fm.wmj.com.cn/ota/W76M/W76M_v76.0.5_ota.bin"
    }
  }
}
参数名 必选 类型 说明
data.info → hw_ver 是 string 目标固件硬件版本，必须与设备一致
data.info.sw_ver 是 string 目标软件版本，必须高于当前版本
data.info.url 是 string 可公网访问的 HTTP/HTTPS 应用固件地址

备注

  • 仅使用与 W76M 硬件及分区匹配的应用 OTA 固件，不能使用4MB量产整包。
  • OTA accepted 只表示升级任务已启动。升级成功必须以设备重连并回读目标版本为准。
  • 适用 W76M 硬件 1.0.0、软件 76.0.x 版本线；请先检查设备当前版本。
  • 设备正在恢复网络时，OTA 请求可能返回忙；待设备重新连接后重试。
  • 76.0.5 改善 WiFi 仍连接但云端长时间无法访问时的自动重连，并减少重复网络错误日志。外部网络持续中断时仍需排查路由器和上联网路。
14.查询在线状态

请求URL

https://wdev.wmj.com.cn/deviceApi/getOnLine

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "data": {
    "online": 1
  },
  "msg": "查询成功"
}

部分旧版服务可能返回兼容字段 on_line，取值同样为 0 或 1。

15.蓝牙应急开门

获取临时密码

POST https://wdev.wmj.com.cn/deviceApi/TPassword

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

成功后读取 data.pwd，并通过BLE写入设备：

  • 开锁服务：FEE0
  • 写特性：FEE1
  • 通知特性：FEE2

向 FEE1 写入：

{
  "cmd_type": "ble_pwd_open_lock",
  "info": {
    "data": "12345678"
  }
}

设备通过 FEE2 通知执行结果：

{
  "state": 1,
  "info": {
    "code": 0,
    "msg": "Unlock success"
  }
}

临时密码采用滚动码校验，开门成功后状态会推进；业务端不得缓存后重复使用。

16.本地配网与应急能力
  • 设备持续提供以序列号命名的 SoftAP，并支持2.4GHz WiFi配网。
  • 手机连接设备热点后可访问 http://192.168.4.1/；主流系统会尝试自动弹出配网页面。
  • BLE配网服务 UUID 为 0D38；蓝牙应急开门服务为 FEE0。
  • 断网时仍可通过本地配网页面输入设备应急开门密码，不依赖云端连接。
17.常见错误
场景 处理建议
平台返回设备不在线 先调用 getOnLine；不要通过反复发送控制命令探活
配置命令平台返回成功但设备字段未改变 检查 data.info.code，再使用 getdevinfo 回读
OTA收到应答但版本未改变 核对硬件版本、目标版本、URL和应用固件类型，并等待设备重连回读
蓝牙能发现但无法开门 重新获取临时密码，确认写入 FEE1 并监听 FEE2 通知
18.解绑设备

请求URL

https://wdev.wmj.com.cn/deviceApi/logout

请求参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "msg": "解绑成功"
}
更新日志
日期 内容
2026-09-09 发布 76.0.5 量产维护版本，明确适用硬件及版本线，完善统一请求方式、按钮接口版本要求与 OTA 使用说明，明确远程 WiFi 配置保存后需重启生效。
2026-09-08 更新 76.0.5 固件下载及升级示例，改善长时间无法连接云端时的自动恢复，减少重复网络错误日志，补充升级忙状态处理。
2026-08-30 首次发布 W76M 开发者接口文档，补充云端控制、WiFi配置、在线查询、OTA、BLE应急开门、本地配网及开门按钮版本边界。
作者：极客师傅  创建时间：2026-08-30 00:09
最后编辑：极客师傅  更新时间：2026-09-09 10:08
上一篇：
下一篇：