网关及子设备功能

1. 概述

子设备是相对网关设备定义的,网关需要完成如下功能:

子设备与网关的通信协议因为采用的标准不同,会有所差异,具体参考具体子设备协议规范。

2. 子设备接入

sequenceDiagram participant client participant master participant APP APP->>master:3.1扫描子设备 master->>APP:3.1返回应答 APP->>master:3.2获取待添加子设备列表 master->>APP:3.2返回应答 APP->>master:3.5添加子设备 master->>APP:3.5返回应答 APP->>master:3.6获取子设备添加状态 master->>APP:3.6返回应答(download_status:1表示正在添加中) Note over client,master:双向认证 APP->>master:3.6获取子设备添加状态 master->>APP:3.6返回应答(download_status:1表示正在添加中) Note over client,master:client登陆成功 APP->>master:3.6获取子设备添加状态 master->>APP:3.6返回应答(download_status:0表示设备添加成功) APP->>master:3.4停止子设备扫描 master->>APP:3.4返回应答(download_status:0表示设备添加成功) Note over APP:若配网超时,APP下发3.4停止子设备扫描命令;

子设备接入网关的流程如下:

1.     将子设备设置成配置模式
2.     网关进入扫描模式
3.     网关返回待配置设备列表
4.     用户决定添加子设备
5.     获取子设备添加状态,直到返回状态为 0
6.     网关关闭扫描模式

3. 相关接口说明

子设备配置相关接口在 BLLetCore 库的 Controller 类里,可以调用 SDK 已经封装的接口如下:

3.1 开启子设备扫描模式

只有当子设备处于复位状态时,才会响应扫描指令。433双向射频协议的子设备,复位默认超时时间为30s。

public static BLSubdevResult subDevScanStart(String did, String subPid)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
subPid String 搜索的子设备的 pid 否,如果为空则搜索所有子设备

返回参数

BLSubdevResult 说明

参数名称 参数类型 备注
subdevStatus int 子设备结果 非0表示失败

3.2 获取扫描到的子设备列表

public static BLSubDevListResult devSubDevNewListQuery(String did, String subpid, int index, int count)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
subPid String 搜索的子设备的 pid 否,如果为空则搜索所有子设备
index int 开始索引
count int 请求的数量

返回参数

BLSubDevListResult 说明

参数名称 参数类型 备注
subdevStatus int 结果 非0表示失败
total int 扫描到的子设备的总数
index int 该index由应用层设定,这里仅作返回
list List 子设备信息列表

BLDNADevice 说明

子设备信息,一般包含以下几个内容

参数名称 参数类型 备注
did String 子设备唯一Id
pid String 子设备类型
name String 子设备名称
state int 子设备在线/离线状态,一般只有 Wi-Fi 的子设备会返回该值

3.4 关闭子设备扫描模式

public static BLSubdevResult subDevScanStop(String did)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did

3.5 子设备添加

public static BLSubdevResult subDevAdd(String did, BLDNADevice subDevInfo)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
subDevInfo BLDNADevice 扫描到的子设备的信息

添加子设备流程里面,SDK会获取子设备 Profile 下载的 URL ,发送给网关,网关再根据这个 URL 去下载相应的 Profile

3.6 获取子设备添加状态

public static BLSubDevAddResult devSubDevAddResultQuery(String did, String sDid)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
sdid String 子设备 did

返回参数

BLSubDevAddResult 说明

参数名称 参数类型 备注
subdevStatus int 结果 非0表示失败
download_status int 子设备添加结果 只有当该值为 0 时,子设备才表示添加成功

download_status 的值相关含义:

* 0:Success
* 1: downloading profile
* 2: download profile fail
* 3: no flash
* 4: profile error

3.7 获取子设备列表

public static BLSubDevListResult devSubDevListQuery(String did,int index, int count)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
index int 开始索引
count int 请求的数量

返回参数

BLSubDevListResult 说明

参数名称 参数类型 备注
subdevStatus int 结果 非0表示失败
total int 扫描到的子设备的总数
index int 该index由应用层设定,这里仅作返回
list List 子设备信息列表

BLDNADevice 说明

子设备信息,一般包含以下几个内容

参数名称 参数类型 备注
did String 子设备唯一Id
pid String 子设备类型
name String 子设备名称
state int 子设备在线/离线状态,一般只有 Wi-Fi 的子设备会返回该值

3.8 子设备删除

public static BLSubdevResult subDevDel(String did, String sDid)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
sdid String 需要删除的子设备 did

3.9 子设备固件版本获取

public static BLFirmwareVersionResult devSubDevVersion(String did, String sDid, BLConfigParam configParam)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
sdid String 需要删除的子设备 did
configParam BLConfigParam 发送参数

返回参数

BLFirmwareVersionResult 说明

参数名称 参数类型 备注
subdevStatus int 结果 非0表示失败
version String 固件版本

版本号说明: 子设备版本号 : version = hwversion * 1000 + fwversion

3.9 子设备固件升级

public BLSubdevResult devSubDevUpgradeFirmware(String did, String sDid, String url, BLConfigParam configParam)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
sdid String 需要删除的子设备 did
url String 固件升级地址 是, url 域名只支持 http 协议
configParam BLConfigParam 发送参数

该命令只是将子设备需要升级的URL发送给设备,设备收到命令后会立即返回,然后再开始子设备固件升级流程。 返回成功,不代表子设备升级成功,需要后续一直查询子设备版本号判断。

3.10 子设备列表备份(导出)

public static BLSubDevBackupResult subDevBackup(String did, int count, int index)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
sdid String 需要删除的子设备 did
count int 请求备份数量
index int 子设备索引值

返回参数

BLSubDevBackupResult 说明

参数名称 参数类型 备注
total int 子设备总数
index int 子设备索引值
list List 子设备备份信息

BLSubSevBackupInfo 说明

子设备备份信息,一般包含以下几个内容

参数名称 参数类型 备注
did String 子设备唯一Id
pid String 子设备类型
session String 语音通道session
sharedkey String 子设备控制key

3.11 子设备列表还原(导入)

本接口一次最大支持 4 个设备的导入,msgid由请求下发者(如APP)随机生成,标识一次还原事务,因为子设备列表可能会超过MTU,无法通过一个请求包完成,所以还原事务会被分割成多个子请求,那么每一个子请求的msgid必须一致。

模块端行为:

1)首次收到子设备还原请求,记录 msgid 和 total,如果 total 超过了当前 master 可容纳的子设备数目,那么直接返回错误;
2) 之后收到的还原请求,会先检查 msgid 是否匹配,如果不匹配那么直接丢弃;
3) 模块这边会设定一个超时,如果超过一定时间,没有拿到所有的子设备信息,则清除会话(之前记录的 msgid 失效,已经收到的子设备信息也会被清除);
4)模块根据 index 和 total 判断子设备信息是否收集完毕;
public static BLSubDevRestoreResult subDevRestore(String did, BLSubDevRestoreParam restoreParam)

请求参数

参数名称 参数类型 备注 是否必须
did String 网关设备 did
restoreParam BLSubDevRestoreParam 还原信息

BLSubDevRestoreParam 说明

子设备还原信息,一般包含以下几个内容

参数名称 参数类型 备注
msgid int 还原操作事务ID 这个ID必须在本次还原的过程中都是唯一不变的
total int 待还原的子设备总数目
index int 当前分页请求的子设备开始序号
list List 子设备备份信息

返回参数

BLSubDevRestoreResult 说明

参数名称 参数类型 备注
msgid int 还原操作事务ID 这个ID必须在本次还原的过程中都是唯一不变的
total int 待还原的子设备总数目
index int 当前分页请求的子设备开始序号