Skip to content

设备接口

本文档介绍巴法云设备管理相关的API接口,包含主题创建、消息推送、设备查询等功能。

硬件设备说明

硬件设备可以使用HTTP协议访问API接口(将https改为http即可)。

创建单个主题

创建一个新的设备主题。

接口信息

  • 请求方法POST
  • 请求地址https://pro.bemfa.com/v1/createTopic
  • Content-Typeapplication/json

请求参数

参数类型是否必须说明
uidstring用户私钥
topicstring主题值,仅限字母、数字
typenumber设备协议类型
namestring主题昵称,中英文不限

协议类型说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本(内测中)
7TCP协议设备V2版本(内测中)

设备类型识别

设备类型通过主题名称后三位数字识别:

后缀设备类型示例
001插座设备socket001, power001
002灯泡设备light002, led002
003风扇设备fan003, air003
004传感器设备sensor004, temp004
005空调设备ac005, aircon005
006开关设备switch006, btn006
009窗帘设备curtain009, blind009

请求示例

json
{
    "uid": "00ad90fe27444dff9d5ee32b94c5ae08",
    "type": 3,
    "topic": "led002"
}

响应示例

json
{
    "code": 0,
    "message": "OK",
    "data": 0
}

状态码说明

状态码说明
0成功
10002请求参数有误
40000未知错误
40006设备已存在
40009主题错误,仅限字母、数字,最大长度64

创建多个主题

批量创建多个设备主题,最多一次可创建20个。

接口信息

  • 请求方法POST
  • 请求地址https://pro.bemfa.com/vs/web/v1/addTopics
  • Content-Typeapplication/json

请求参数

参数类型是否必须说明
openIDstring用户私钥
topicsstring[]主题数组,最多20个
typenumber设备协议类型
roomstring设备房间
groupstring设备分组
adminIDnumber企业ID

协议类型说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本(内测中)
7TCP协议设备V2版本(内测中)

设备类型识别

设备类型通过主题名称后三位数字识别:

  • 001: 插座设备
  • 002: 灯泡设备
  • 003: 风扇设备
  • 004: 传感器设备
  • 005: 空调设备
  • 006: 开关设备
  • 009: 窗帘设备

请求示例

json
{
    "openID": "00ad90fe27444dff9d5ee32b94c5ae08",
    "type": 3,
    "topics": [
        "xxsn001",
        "xxsn1002",
        "xxsn2002",
        "xxsn042",
        "led002"
    ],
    "group": "分组一",
    "adminID": 0
}

响应示例

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "code": 0,
        "message": ""
    }
}

状态码说明

状态码说明
0成功
10002请求参数有误
40000未知错误
40006设备已存在

删除主题

删除指定的设备主题。

接口信息

  • 请求方法POST
  • 请求地址https://pro.bemfa.com/v1/deleteTopic
  • Content-Typeapplication/json; charset=utf-8

请求参数

参数类型是否必须说明
uidstring用户私钥
topicstring主题名称(仅限字母、数字)
typenumber设备协议类型

协议类型说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本(内测中)
7TCP协议设备V2版本(内测中)

请求示例

json
{
    "uid": "4d9ec352e0376f2110a0c601a2857225",
    "topic": "tttt006",
    "type": 3
}

响应示例

json
{
    "code": 0,
    "message": "OK",
    "data": 0
}

状态码说明

状态码说明
0成功
10002请求参数有误
40000未知错误
40004uid或topic错误

推送消息

向指定主题发送消息,支持向微信推送通知。

接口信息

  • 请求方法POST
  • 请求地址https://apis.bemfa.com/va/postJsonMsg
  • Content-Typeapplication/json; charset=utf-8

请求参数

参数类型是否必须说明
uidstring用户私钥(从控制台获取)
topicstring主题名称
typenumber主题类型(1=MQTT协议,3=TCP协议)
msgstring消息内容(如:on、off等)
shareboolean是否为分享设备
wemsgstring微信推送消息(可选)

请求示例

json
{
    "uid": "7801e4ba1bf7406593d47250797860fd",
    "topic": "led002",
    "type": 3,
    "msg": "on"
}

响应示例

json
{
    "code": 0,
    "message": "OK",
    "data": 0
}

状态码说明

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

使用示例

可参考下图进行推送测试:

topic

接口信息

  • 请求方法GET

  • 请求地址https://apis.bemfa.com/va/sendMessage

参数是否必须说明
uid用户私钥,巴法云控制台获取
topic主题名,可在控制台创建
type主题类型,当type=1时是MQTT协议,3是TCP协议
msg消息体,要推送的消息,自定义即可,比如on,或off等等
wemsg发送到微信的消息,自定义即可。如果携带此字段,会将消息发送到微信

请求体示例:

http://apis.bemfa.com/va/sendMessage?uid=38fedc3d1dd04d87a19cc60a64577834&topic=000000002&type=3&msg=on

正确返回:

{
    "code": 0,
    "message": "OK",
    "data": 0
}

code 字段说明:

code状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

获取消息

获取主题消息,支持GET协议:

1、HTTP ### 接口信息

  • 请求方法GET

  • 请求地址https://apis.bemfa.com/va/getmsg

参数是否必须说明
uid用户私钥,巴法云控制台获取
topic主题名,可在控制台创建
type主题类型,当type=1时是MQTT协议,3是TCP协议
num获取的历史数据条数,不填默认默认是1,最大5000

示例:https://apis.bemfa.com/va/getmsg?uid=d4c470e057e04a3e8b2fefd0b74b6b16&topic=23123001&type=3

正确返回:

{
    "code": 0,
    "message": "OK",
    "data": [
        {
            "msg": "on",
            "time": "2022-08-03 17:26:34",
            "unix": 1659518794
        }
    ]
}

code 字段说明:

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

data内字段说明:

字段说明
msg获取的主题消息
time消息发送的时间,时区UTC/GMT+08:00
unix消息发送的时间戳

获取设备所有分组

接口信息

  • 请求方法GET

  • 请求地址http://apis.bemfa.com/vb/api/v1/allGroup

参数是否必须说明
openID用户私钥,巴法云控制台获取
type主题名,可在控制台创建

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

示例:http://apis.bemfa.com/vb/api/v1/allGroup?openID=00ad90fe27444dff9d5ee32b94c5ae08&type=3

正确返回:

{
    "code": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "name": "未分组",
                "num": 2
            },
            {
                "name": "设备一",
                "num": 5
            },
            {
                "name": "设备二",
                "num": 4
            }
        ]
    }
}

data字段说明:

字段说明
name分组名称
num分组内设备数量

通过分组获取设备

接口信息

  • 请求方法GET

  • 请求地址http://apis.bemfa.com/vb/api/v2/groupTopic

参数是否必须类型说明
openID字符串类型用户私钥
typeint整型主题类型
group字符串类型分组

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

示例:http://apis.bemfa.com/vb/api/v2/groupTopic?openID=00ad90fe27444dff9d5ee32b94c5ae08&type=1&group=未分组

正确返回:

{
  "code": 0,
  "msg": "success",
  "data": {
    "data": [
      {
        "topic": "1245001",
        "type": 1,
        "share": false,
        "time": "2024-06-27 10:50:32",
        "unix": 1719456632,
        "online": false,
        "name": "插座",
        "room": "",
        "msg": "",
        "pubOnline": false,
        "deviceType": "outlet",
        "group": "",
        "createTime": "2024-06-27 10:50:32"
      },
      {
        "topic": "2322006",
        "type": 1,
        "share": false,
        "time": "2024-03-31 23:49:22",
        "unix": 1711900162,
        "online": false,
        "name": "开关",
        "room": "",
        "msg": "off",
        "pubOnline": false,
        "deviceType": "switch",
        "group": "",
        "createTime": "2024-03-31 23:40:35"
      }
    ]
  }
}

data内字段说明:

字段说明
topic主题值
type协议类型
share是否是分享设备
time消息发送的时间,时区UTC/GMT+08:00
unix消息发送的时间戳
online是否在线
name主题名字
room房间名字
msg消息体
pubOnline推送者是否在线
deviceType设备类型
group分组
createTime主题创建时间

deviceType字段说明:

字段说明
outlet插座
light
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘
thermostat温控器
waterheater热水器
television电视
airpurifier空气净化器

获取设备所有房间

接口信息

  • 请求方法GET

  • 请求地址http://apis.bemfa.com/vb/api/v1/allRoom

参数是否必须类型说明
openID字符串类型用户私钥
typeint整型主题类型

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

示例:http://apis.bemfa.com/vb/api/v1/allRoom?openID=00ad90fe27444dff9d5ee32b94c5ae08&type=3

正确返回:

{
    "code": 0,
    "msg": "success",
    "data": {
        "data": [
            {
                "name": "未分组",
                "num": 11
            }
        ]
    }
}

data字段说明:

字段说明
name名称
num设备数量

通过房间获取设备

接口信息

  • 请求方法GET

  • 请求地址http://apis.bemfa.com/vb/api/v2/roomTopic

参数是否必须类型说明
openID字符串类型用户私钥
typeint整型主题类型
room字符串类型房间

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

示例:http://apis.bemfa.com/vb/api/v2/roomTopic?openID=00ad90fe27444dff9d5ee32b94c5ae08&type=3&room=未分组

正确返回:

{
  "code": 0,
  "msg": "success",
  "data": {
    "data": [
      {
        "topic": "0D4061002",
        "type": 3,
        "share": false,
        "time": "2024-06-27 09:53:59",
        "unix": 1719453239,
        "online": false,
        "name": "灯",
        "room": "",
        "msg": "on",
        "pubOnline": false,
        "deviceType": "light",
        "group": "",
        "createTime": "2024-06-21 16:06:38"
      },
      {
        "topic": "xxsn2002",
        "type": 3,
        "share": false,
        "time": "2024-09-11 11:28:13",
        "unix": 1726025293,
        "online": false,
        "name": "灯",
        "room": "",
        "msg": "",
        "pubOnline": false,
        "deviceType": "light",
        "group": "分组一",
        "createTime": "2024-09-11 11:28:13"
      }
    ]
  }
}

data内字段说明:

字段说明
topic主题值
type协议类型
share是否是分享设备
time消息发送的时间,时区UTC/GMT+08:00
unix消息发送的时间戳
online是否在线
name主题名字
room房间名字
msg消息体
pubOnline推送者是否在线
deviceType设备类型
group分组
createTime主题创建时间

deviceType字段说明:

字段说明
outlet插座
light
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘
thermostat温控器
waterheater热水器
television电视
airpurifier空气净化器

获取所有主题信息

接口信息

  • 请求方法GET

  • 请求地址http://apis.bemfa.com/vb/api/v2/allTopic

参数是否必须说明
uid用户私钥,巴法云控制台获取
type主题类型,当type=1时是MQTT协议,3是TCP协议

正确返回:

{
    "code": 0,
    "message": "OK",
    "data": [
        {
            "topic": "cat002",
            "msg": "off",
            "name": "home light",
            "online": true,
            "tid": "light",
            "sid": "",
            "time": "2022-08-03 16:39:27",
            "unix": 1659515967
        },
        {
            "topic": "me001",
            "msg": "on",
            "name": "电视",
            "online": false,
            "tid": "outlet",
            "sid": "",
            "time": "2022-08-03 11:49:11",
            "unix": 1659498551
        }
    ]
}

code 字段说明:

状态码说明
0成功
10002请求参数有误
40000未知错误
40003私钥错误

data内字段说明:

字段说明
topic主题值
type协议类型
share是否是分享设备
time消息发送的时间,时区UTC/GMT+08:00
unix消息发送的时间戳
online是否在线
name主题名字
room房间名字
msg消息体
pubOnline推送者是否在线
deviceType设备类型
group分组
createTime主题创建时间

deviceType字段说明:

字段说明
outlet插座
light
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘
thermostat温控器
waterheater热水器
television电视
airpurifier空气净化器

示例:http://apis.bemfa.com/vb/api/v2/allTopic?openID=4d9ec352e0376f2110a0c601a2857225&type=3

获取单个主题信息

接口信息

  • 请求方法GET

  • 请求地址http://apis.bemfa.com/vb/api/v2/topicInfo

参数是否必须类型说明
openID字符串类型用户私钥
typeint整型主题类型
topic字符串类型主题

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

正确返回:

{
    "code": 0,
    "msg": "success",
    "data": {
        "name": "客厅灯",
        "msg": "on",
        "online": true,
        "onlineNum": 1,
        "pubOnline": false,
        "deviceType": "light",
        "share": false,
        "group": "",
        "room": "客厅",
        "time": "2025-07-30 16:40:13",
        "unix": 1753864813,
        "createTime": "2024-12-27 17:52:49"
    }
}

data内字段说明:

参数类型说明
name字符串主题名称
msg字符串或json消息
onlinebool订阅是否在线
onlineNum整形订阅在线个数
pubOnlinebool发布者是否在线,半小时内是否有消息推送
deviceType设备类型
share是否是分享设备
group字符串分组名,空是没有分组
room字符串房间名,空是没有房间
time字符串主题消息发送的时间,时区UTC/GMT+08:00
unix整形消息发送的时间戳
createTime字符串主题创建的时间,时区UTC/GMT+08:00

deviceType字段说明:

字段说明
outlet插座
light
fan风扇
sensor传感器
aircondition空调
switch开关
curtain窗帘
thermostat温控器
waterheater热水器
television电视
airpurifier空气净化器

示例:http://apis.bemfa.com/vb/api/v2/topicInfo?openID=4d9ec352e0376f2110a0c601a2857225&type=3&topic=0D4061002

获取设备在线

接口信息

  • 请求方法GET

  • 请求地址https://apis.bemfa.com/va/online

参数是否必须说明
uid用户私钥,巴法云控制台获取
topic主题名,可在控制台创建
type主题类型,当type=1时是MQTT协议,3是TCP协议

正确返回:

{
    "code": 0,
    "message": "OK",
    "data": false
}

code 字段说明:

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

data 字段说明:

状态码说明
true设备在线
false设备离线

修改设备房间

接口信息

  • 请求方法POST

  • 请求地址http://apis.bemfa.com/vb/api/v1/changeTopicRoom

请求参数:

参数是否必须类型说明
openID字符串类型用户私钥
topicIDs字符串数组主题值,最少修改一个,最多一次可修改50个
room字符串类型房间 ,空值表示清空房间

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

请求示例:

{
    "openID":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topicIDs":["0D4061002"],
    "type":3,
    "rome":"客厅"
}

正确返回:

{
    "code": 0,
    "msg": "success",
    "data": {
        "code": 0
    }
}

data字段说明:

字段说明
code0成功

修改设备分组

接口信息

  • 请求方法POST

  • 请求地址http://apis.bemfa.com/vb/api/v1/changeTopicGroup

请求参数:

参数是否必须类型说明
openID字符串类型用户私钥
topicIDs字符串数组主题值,最少修改一个,最多一次可修改50个
group字符串类型分组名 ,空值表示清空分组

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

请求示例:

{
    "openID":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topicIDs":["sn01"],
    "type":3,
    "group":"分组2"
}

正确返回:

{
    "code": 0,
    "msg": "success",
    "data": {
        "code": 0
    }
}

data字段说明:

字段说明
code0成功

修改主题昵称

修改设备昵称

接口信息

  • 请求方法POST
  • 请求地址https://apis.bemfa.com/va/modifyName
  • Content-Typeapplication/json; charset=utf-8

请求参数

参数是否必须说明
uid用户私钥
topic主题名称,仅限字母、数字类型
type类型类型
name主题昵称

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

请求示例:

{
    "uid":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topic":"sn001",
    "type":3,
    "name":"卧室灯"
}

请求正常响应:

{
    "code": 0,
    "message": "OK",
    "data": 0
}

code 字段说明:

状态码说明
0成功
10002请求参数有误
40000未知错误

获取主题昵称

获取主题昵称

接口信息

  • 请求方法GET
  • 请求地址https://apis.bemfa.com/va/getName

请求参数

参数是否必须说明
uid用户私钥
topic主题名称
type类型类型

type字段值说明

说明
1MQTT协议设备
3TCP协议设备
5MQTT协议设备V2版本,内测中
7TCP协议设备V2版本,内测中

请求正常响应:

{
    "code": 0,
    "message": "OK",
    "data": "传感器"
}

data 字段是获取的主题昵称。

code 字段说明:

状态码说明
0成功
10002请求参数有误
40000未知错误
40004密钥或主题错误

获取时间

单片机使用建议使用http,端口80。https默认端口443。

接口信息

  • 请求方法GET

  • 请求地址https://api.bemfa.com/api/time/now/

参数是否必须说明
typetype不填默认为1,type=1是只获取时间,等于2获取日期和时间

示例:https://api.bemfa.com/api/time/now/?type=1

esp8266示例下载: 点击下载

esp32示例下载: 点击下载

设备分享

设备分享相关共有三个接口:设备分享,获取设备已分享列表,删除设备分享。

1、设备分享接口

接口信息

  • 请求方法POST

  • Content-Typeapplication/json; charset=utf-8

  • 请求地址https://apis.bemfa.com/va/shareDevice

参数是否必须说明
uid用户私钥,巴法云控制台获取
topic主题名,可在控制台创建
type主题类型,当type=1时是MQTT协议,3是TCP协议
name设备昵称
email接收人的邮箱

请求示例:

{
    "uid":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topic":"sn001",
    "type":3,
    "name":"卧室灯",
    "email":"133xxxxxxx@qq.com"
}

正确返回:

{
    "code": 0,
    "message": "OK",
    "data": null
}

code 字段说明:

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误
40005接入人邮箱错误或不存在
40005设备已存在

2、获取设备已分享列表

接口信息

  • 请求方法GET

  • 请求地址https://apis.bemfa.com/va/getShareList

参数是否必须说明
uid用户私钥,巴法云控制台获取
topic主题名,可在控制台创建
type主题类型,当type=1时是MQTT协议,3是TCP协议

正确返回:

{
    "code": 0,
    "message": "OK",
    "data": [
        {
            "email": "1217xxxxxx1@qq.com",
            "time": "2022-08-04 10:45:57",
            "unix": 1659581157
        },
        {
            "email": "1217xxxxxx2@qq.com",
            "time": "2022-08-04 10:45:59",
            "unix": 1659581159
        },
    ]
}

code 字段说明:

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误

data内字段说明:

字段说明
email接收者邮箱
time消息发送的时间,时区UTC/GMT+08:00
unix消息发送的时间戳

3、删除分享

接口信息

  • 请求方法POST

  • Content-Typeapplication/json; charset=utf-8

  • 请求地址https://apis.bemfa.com/va/deleteShare

参数是否必须说明
uid用户私钥,巴法云控制台获取
topic主题名,可在控制台创建
type主题类型,当type=1时是MQTT协议,3是TCP协议
email接收人的邮箱

请求示例:

{
    "uid":"00ad90fe27444dff9d5ee32b94c5ae08",
    "topic":"sn001",
    "type":3,
    "email":"133xxxxxxx@qq.com"
}

正确返回:

{
    "code": 0,
    "message": "OK",
    "data": null
}

code 字段说明:

状态码说明
0成功
10002请求参数有误
40000未知错误
40004私钥或主题错误
40005接入人邮箱错误或不存在

巴法开放联盟