客户自有账号系统对接方案
概述
本文档适用于客户自有账号系统项目开发指导。
主要功能：
1. 客户 APP 集成 APPSDK
2. 客户 APP 使用自身账号系统，通过 Oauth 方式完成 APPSDK 账号登录
3. 客户 APP 能够使用 BroadLink 家庭系统，产品服务等功能
4. 客户 APP 能够使用萤石摄像头
5. BroadLink APP 能够使用 客户账号登录，同时同步数据
1. BroadLink 相关 License 申请
为了设备的安全，所有使用SDK的用户必须向 BroadLink DNAKit 开发者平台 申请 License。
注意：License 必须与应用的包名（PackageName）相关联，不同的应用包名需要申请不同的 License。
申请流程（图文）：
- 进入 BroadLink DNAKit 开发者平台
- 登录账号，没有账号的请先注册，并申请为开发者
- 等待审核通过
- 审核通过后，进入主页，选择 平台接入 -> SDK接入
- 选择 License申请 -> 新建License申请，按要求填写信息，若要控制第三方厂家的设备，请在备注中说明厂家的名称以及具体的产品型号，提交审核
审核通过之后，可以在申请页面看见 License
注意：本方案中基本信息里面 用户账号类型 需要选择为 BroadLink账号系统
以上工作需要由技术对接人员指导客户完成申请。
2. 账号系统对接
2.1 客户账号系统
客户自身账号系统已经完善的情况下，需要增加 OAuth2.0 授权的方式，可以通过 客户自身平台/后台添加 的方式，能够注册 BroadLink 相关信息到客户平台。
同时客户平台返回包括 ClientID，ClientSecret 等信息，便于 BroadLink 平台集成完成对接工作。
以上工作由技术对接人员与客户沟通完成。
2.2 BroadLink账号系统
BroadLink 服务端开发工程师，再拿到 ClientID，ClientSecret 等信息之后，根据客户账号系统对接相关协议以及接口，完成对接工作。
同时提供一种新的 thirdType 字符串给 APPSDK，用于后续接口使用。
3. 客户APP端
3.1 集成 BroadLink APPSDK
客户集成 BroadLink APPSDK，可以参考 APPSDK接入集成说明
如下所示为核心功能库各个模块之间关系：
3.2 账号登录
客户如果需要能够通过SDK，对设备进行远程控制，则必须先完成账号登录功能，在本方案中使用的是客户自身账号系统，则需要将 accessToken，openId 等信息传入SDK，进行校验。
相关接口如下：
public static BLLoginResult oauthLogin(String thirdType, String thirdID, String accesstoken, String topsign, String nickname, String iconUrl)请求参数
| 参数名称 | 参数类型 | 备注 |
|---|---|---|
| thirdType | String | Oauth 公司名称，例如 “facebook”, 该名称由 BroadLink 提供 |
| thirdID | String | OpenID，由Oauth公司注册提供 |
| accesstoken | String | AccessToken，由Oauth公司注册提供 |
| topsign | String | 暂为 null |
| nickname | String | 用户昵称 |
| iconUrl | String | 用户头像URL |
具体接口可以参考 SDK账号系统文档
3.3 设备管理控制
BroadLink 设备控制系统提供设备配网、设备发现、设备配对以及统一的设备控制功能。
具体接口可以参考 APPSDK 设备控制系统说明
3.3.1 设备配网
通过SDK将SSID和密码发送给设备，使设备连接WiFi路由器的过程。
相关接口如下：
public static BLDeviceConfigResult deviceConfig(BLDeviceConfigParam deviceConfigParam, int timeout)具体参考 设备配网
3.3.2 设备发现
SDK可以发现在同一个局域网内符合 BroadLink 相关设备协议的网络设备。 由于该扫描耗时，且单一次扫描无法做到局域网内所有设备都能扫描到，所以SDK采用开启后台线程，发现设备后通过回调的方式再上报给开发者。
相关接口如下：
//开启设备扫描
public static void startProbe();
//关闭设备扫描
public static void stopProbe();//设置扫描设备回调函数
public static void setOnDeviceScanListener(BLDeviceScanListener scanListener);
public abstract class BLDeviceScanListener {
public boolean shouldAdd(BLDNADevice device){
return false;
}
public abstract void onDeviceUpdate(BLDNADevice device, boolean isNewDevice);
}具体参考 设备发现
3.3.3 添加设备
为了能够更加方便的控制设备，设备需要主动添加到SDK内一次，SDK会缓存设备的相关信息，而在后续的设备操作中，只需要传入设备的唯一 did 即可。 同时SDK会对添加SDK里的设备状态进行维护查询。 如果设备不再需要在SDK里控制了，则需要主动删除相关的设备 did 。
相关接口如下：
public static void addDevice(BLDNADevice device);
public static void addDevice(ArrayList<BLDNADevice> listDevice);具体参考 添加设备
3.3.4 设备控制
设备控制分透传控制和脚本控制：
透传控制
SDK直接将二进制数据透传给设备，设备收到之后，依旧返回二进制数据，APP需要自行解析二进制数据的含义。
相关接口如下：
public static BLPassthroughResult dnaPassthrough(String did, String sDid, byte[] data, BLConfigParam configParam);具体参考 设备控制 - 数据透传
脚本控制
每一个产品在 BroadLink DNAKit创建的时候，都会生成一个控制的脚本。 设备脚本包含有设备的相关信息，标准的控制指令等。
SDK可以下载脚本到指定路径，在控制设备的时候，将不同的控制指令，通过脚本转换为设备接收的二进制指令下发。 同样能将设备返回二进制指令，通过脚本转换为控制指令，便于APP识别和使用。
相关接口如下：
public static BLStdControlResult dnaControl(String did, String sDid, BLStdControlParam stdControlParam, BLConfigParam configParam);具体参考 设备控制 - 脚本方式
3.4 家庭管理系统
BroadLink 提供了一套完整的家庭管理系统。 通过该系统，开发者可以很好的将 用户，设备，模块 ，房间，家庭 的概念结合起来，构造出一套完整的智能硬件控制系统。 在客户APP中添加的设备，如果需要在 BroadLink APP里面也能进行控制，则必须将设备按照 模块 的格式添加到 家庭 和 房间 内。
具体可以参考 APPSDK 家庭管理系统说明
3.4.1 获取家庭信息
第一步 查询账户下家庭ID列表
相关接口如下：
//查询账户下家庭ID列表
public static BLFamilyIdListGetResult queryLoginUserFamilyIdList();参数说明：
BLFamilyIdListGetResult
public class BLFamilyIdListGetResult extends BLBaseResult {
private List<BLFamilyIdInfo> idInfoList = new ArrayList<BLFamilyIdInfo>();
}
public class BLFamilyIdInfo {
private int shareFlag = 0; //家庭是否被分享
private String familyId; //家庭唯一ID
private String familyVersion; //家庭版本号
private String familyName; //家庭名称
}第二步 获取指定家庭ID的全部信息
相关接口如下：
//获取指定家庭ID的全部信息
public static BLAllFamilyInfoResult queryAllFamilyInfos(String[] ids);BLAllFamilyInfoResult
public class BLAllFamilyInfoResult extends BLBaseResult {
private List<BLFamilyAllInfo> allInfos = new ArrayList<BLFamilyAllInfo>();
}
public class BLFamilyAllInfo {
private int shareFlag = 0; //家庭是否被分享
private String createUser; //家庭创建者userId
private BLFamilyInfo familyInfo; //家庭基本信息
private List<BLFamilyRoomInfo> roomInfos = new ArrayList<BLFamilyRoomInfo>(); //房间信息列表
private List<BLFamilyModuleInfo> moduleInfos = new ArrayList<BLFamilyModuleInfo>(); //模块信息列表
private List<BLFamilyDeviceInfo> deviceInfos = new ArrayList<BLFamilyDeviceInfo>(); //设备信息列表
private List<BLFamilyDeviceInfo> subDeviceInfos = new ArrayList<BLFamilyDeviceInfo>(); //子设备信息列表
}通过该接口获取指定家庭的详细信息，可以得到一个家庭的全部信息 BLFamilyAllInfo ，这些信息包含有：
- 家庭自身的基本信息
BLFamilyInfo - 家庭下房间信息列表
BLRoomInfo - 家庭下模块信息列表
BLModuleInfo - 家庭下设备信息列表
BLFamilyDeviceInfo - 家庭下子设备信息列表
BLFamilyDeviceInfo
上述参数具体内容，请参考 家庭信息
3.4.2 房间操作
创建家庭之后，会默认生成多个房间。 家庭也可以创建多个房间，同时也可以对房间进行修改、删除等操作。
相关接口如下：
public static BLManageRoomResult manageFamilyRooms(String familyId, String familyVersion, List<BLFamilyRoomInfo> roomInfos);具体可参考 房间相关接口
3.4.3 模块操作
家庭模块是家庭控制的基本单元，通过对模块的操作，可以实现在家庭环境下控制单个设备、多个设备、场景以及自定义模版的实现。
模块信息包括：
public class BLFamilyModuleInfo {
private String familyId; //模块所在家庭ID
private String roomId; //模块所在房间ID
private String moduleId; //模块自身ID
private String name; //模块名称
private String iconPath; //模块icon路径
private List<ModuleDeviceInfo> moduleDevs; //模块下挂设备列表
private int followDev; //模块移动时，设备是否跟随 0-NO 1-YES
private int order; //模块序号
private int flag; //模块Flag
private int moduleType; //模块类型
private String scenceType; //场景类型
private String extend; //模块扩展信息，由用户自定义
}模块具体的 增/删/改 操作，可参考 家庭模块相关接口
4. 摄像头设备对接
摄像头接入具体参考 萤石接入流程说明