跳到主要内容

接口协议

tag​

标签端目前支持以下通信方式

  • uwb（默认）
  • uart
  • iic
  • ble（仅单向广播部分数据）

通信方式由软件配置，硬件配置共同决定，默认全关，有以下配置方式

  • 软件使能：生产时配置或者通过后台工具配置
  • 硬件使能：对相关IO做上下拉处理（不做处理的IO默认上拉）

最终使能 = 软件使能 || 硬件使能，其中

  • uart ble不可同时开 同时开强制uart
  • uart iic不可同时开 同时开强制uart
  • uart iic uwb同时开视为无效
  • 一个都没有开时保底启用uwb（也即默认情况）

uart需要配合RX_REQ IO进行低功耗处理，如果不控制该IO，默认一直等待接收串口数据，处于高功耗状态

iic如果启用了但是没有实际外接iic主机，引脚悬空，会导致漏电，此为使用问题

用户解析数据可参考驱动示例代码，代码中也包含串口解析示例，会解析数据并打印日志

backend​

uBeacon Tools 内置API接口，可用于实现后台业务功能

通过API接口可获得Gateway、uBeacon、Tag设备的UID、坐标、电量、工作状态以及Tag的实时定位等信息，数据格式为JSON，接口协议包括MQTT、UDP、webhook、HTTP等，软件支持部署在Ubuntu、Windows、MacOs等平台

数据格式：JSON​

定位数据示例：

{
    "data": {
        "mapId": 2, //地图id
        "pos": [
            -3.2616942,
            4.3123593,
            1.1999172
        ], // 定位：x,y,z
        "posNoise": [
            0.71,
            0.62,
            0.03
        ],// 定位噪声: x, y, z, 值越大置信度越低。
        "time": 1752463929264, // 毫秒时间戳.
        "cnt": 575889100, //设备时间戳.
        "vel": [
            -0.08,
            0.1,
            0
        ], //速度：x,y,z
        "velNoise": [
            0.13,
            0.13,
            0.01
        ], //x,y,z方向的速度噪声, 值越大置信度越低。
        "fences": [
            {
                "id": 18,  // 标签所在的电子围栏id
                "name": "Fence-13", // 标签所在的电子围栏名称
                "userData": {} // 用户自定义数据
            }
        ],
        "optPoses": [
            [
                0.71,
                0.62,
                0.03
            ]
        ]  // 增加边界、墙约束后的输出位置
    },
    "deviceName": "T4", // 设备名，在软件内唯一
    "name": "Pos", // 消息类型
    "uid": "02084a71676424f9e16d"  //设备UID
}

推送数据API配置入口​

打开uBeacon Tool软件，按下图操作进入配置页面

API 配置入口示例

通过MQTT推送数据​

address: 协议://用户名:密码@主机名:端口 或者 协议://主机名:端口或者 主机名:端口

不加密协议支持：mqtt或者tcp、ws

加密协议支持：mqtts或者tcps、wss

示例：mqtt://admin:test@192.168.0.15:1883

api.mqtt.clientId: 客户端标识，可为空

api.mqtt.topic: 主题名

MQTT 配置示例

通过UDP推送数据​

api.udp.address: {ip或域名}:{端口}

localAddress: 指定本地IP地址，主要存在多网卡时指定使用选择的网卡

UDP 配置示例

通过webhook推送数据​

api.hook.url格式: http://{ip或域名}:{端口}/{自定义uri}

http method: POST

web hook 配置示例

HTTP获取设备状态​

URL: GET http://localhost:8088/openapi/v1/devices?deviceType=&online=&query=&page=&pageSize=

Query参数：

参数名参数类型参数说明
deviceTypeint根据设备类型搜索，空表示查询所有类型设备，1表示查询Gateway设备，2表示查询uBeacon设备，3表示查询Tag设备
onlinebool根据是否在线搜索，空表示查询所有状态，false表示查询离线设备，true表示查询在线设备
querystring根据设备名前缀搜索或者设备UID后缀搜索
pageint分页页码，默认为1，1表示第一页，依次类推
pageSizeint分页每页大小，默认为20，最大100

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": "",
    "data": {
        "records": [
          {
            "name": "U6", // 设备名 
            "type": 2,  // 设备类型，1表示Gateway设备，2表示uBeacon设备，3表示Tag设备
            "online": false, // 是否在线
            "onlineTime": 1727323909, //在线离线时间，online为true表示在线时间，online为false表示离线时间
            "uid": "0208f5579f8e183fa1eb", // 设备UID
            "power": 93, // 设备电量百分比
            "coordinate": { // 设备坐标，目前仅uBeacon设备有
                "coords": [
                  13.302,  // x坐标
                  12.9,    // y坐标
                  2.9      // z坐标
                ]
             }
           }
        ],
        "total": 1 // 当前搜索条件下的总数
    }
}

HTTP查询地图上电子围栏​

URL: GET http://localhost:8088/openapi/v1/maps/{mapId}/fences

Path参数：

参数名参数类型参数说明
mapIduint32电子围栏所在地图id

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": "",
    "data": {
        "records": [
            {
                "id": 11, // 电子围栏id
                "mapId": 2, // 电子围栏所在地图id
                "name": "测试围栏", // 电子围栏名称
                "enable": true, // 电子围栏是否使能
                "bounds": [
                    [
                        [
                            19.305483719334006,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            14.511200794018805
                        ]
                    ]
                ], // 电子围栏边界（当前不支持洞）
                "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
                "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
                "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效 
                "userData": {} // 用户自定义数据
            }
        ]
    }
}

HTTP搜索电子围栏​

URL: GET http://localhost:8088/openapi/v1/fences

Query参数：

参数名参数类型参数说明
mapIduint32电子围栏所在地图id
querystring根据电子围栏名前缀搜索
pageint分页页码，默认为1，1表示第一页，依次类推
pageSizeint分页每页大小，默认为20，最大100

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": "",
    "data": {
        "records": [
            {
                "id": 11, // 电子围栏id
                "mapId": 2, // 电子围栏所在地图id
                "name": "测试围栏", // 电子围栏名称
                "enable": true, // 电子围栏是否使能
                "bounds": [
                    [
                        [
                            19.305483719334006,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            14.511200794018805
                        ],
                        [
                            21.019341055303812,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            13.554935615509748
                        ],
                        [
                            19.305483719334006,
                            14.511200794018805
                        ]
                    ]
                ], // 电子围栏边界（当前不支持洞）
                "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
                "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
                "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效
                "userData": {} // 用户自定义数据
            }
        ],
        "total": 1 // 当前搜索条件下的总数
    }
}

HTTP查询某个电子围栏​

URL: GET http://localhost:8088/openapi/v1/fences/\{id\}

Path参数：

参数名参数类型参数说明
iduint32电子围栏id

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": "",
    "data": {
        "mapId": 2, // 电子围栏所在地图id
        "name": "测试围栏", // 电子围栏名称
        "enable": true, // 电子围栏是否使能
        "bounds": [
            [
                [
                    19.305483719334006,
                    14.511200794018805
                ],
                [
                    21.019341055303812,
                    14.511200794018805
                ],
                [
                    21.019341055303812,
                    13.554935615509748
                ],
                [
                    19.305483719334006,
                    13.554935615509748
                ],
                [
                    19.305483719334006,
                    14.511200794018805
                ]
            ]
        ], // 电子围栏边界（当前不支持洞）
        "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
        "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
        "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效
        "userData": {} // 用户自定义数据
    }
}

HTTP添加电子围栏​

URL: POST http://localhost:8088/openapi/v1/fences

Body参数：

参数名参数类型参数说明
namestring电子围栏名称
enablebool电子围栏是否使能
bounds[][][][][][][]float64电子围栏边界（当前不支持洞）
leaveBufferfloat64当离开电子围栏边界>leaveBuffer时才判定为离开
includes[]string电子围栏生效的标签uid，为空表示所有都生效
excludes[]string电子围栏不生效的标签uid，为空表示所有都生效
userDataObject用户自定义数据
{
    "mapId": 2, // 电子围栏所在地图id
    "name": "测试围栏", // 电子围栏名称
    "enable": true, // 电子围栏是否使能
    "bounds": [
        [
            [
                19.305483719334006,
                14.511200794018805
            ],
            [
                21.019341055303812,
                14.511200794018805
            ],
            [
                21.019341055303812,
                13.554935615509748
            ],
            [
                19.305483719334006,
                13.554935615509748
            ],
            [
                19.305483719334006,
                14.511200794018805
            ]
        ]
    ], // 电子围栏边界（当前不支持洞）
    "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
    "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
    "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效
    "userData": {} // 用户自定义数据
}

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

HTTP更新电子围栏​

URL: PUT http://localhost:8088/openapi/v1/fences/{id}

Path参数：

参数名参数类型参数说明
iduint32电子围栏id

Body参数：

参数名参数类型参数说明
namestring电子围栏名称
enablebool电子围栏是否使能
bounds[][][][][][][]float64电子围栏边界（当前不支持洞）
leaveBufferfloat64当离开电子围栏边界>leaveBuffer时才判定为离开
includes[]string电子围栏生效的标签uid，为空表示所有都生效
excludes[]string电子围栏不生效的标签uid，为空表示所有都生效
userDataObject用户自定义数据
{
    "name": "测试围栏", // 电子围栏名称
    "enable": true, // 电子围栏是否使能
    "bounds": [
        [
            [
                19.305483719334006,
                14.511200794018805
            ],
            [
                21.019341055303812,
                14.511200794018805
            ],
            [
                21.019341055303812,
                13.554935615509748
            ],
            [
                19.305483719334006,
                13.554935615509748
            ],
            [
                19.305483719334006,
                14.511200794018805
            ]
        ]
    ], // 电子围栏边界（当前不支持洞）
    "leaveBuffer": 0.3, // 当离开电子围栏边界>leaveBuffer时才判定为离开
    "includes": ["d910570506e6d4f7"],// 电子围栏生效标签uid，空表示都生效
    "excludes": ["d48475ae51904290"],//电子围栏不生效标签uid，空表示都生效
    "userData": {} // 用户自定义数据
}

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}

HTTP删除电子围栏​

URL: DELETE http://localhost:8088/openapi/v1/fences/{id}

Path参数：

参数名参数类型参数说明
iduint32电子围栏id

响应数据：

{
    "code": 0, // 0表示成功，非0表示失败
    "message": ""
}