网关及子设备功能
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 | 当前分页请求的子设备开始序号 |