APPSDK 使用流程

概述

APPSDK 目前主要包含以下几个库:

BLLetCore 库

核心功能库,主要用于设备控制,设备配网和维护设备相关信息接口。

BLLetAccount 库

账号系统库,主要用于 Broadlink账户登录/注册,以及账号互通相关功能。

BLLetFamily 库

家庭系统库,主要提供家庭、家庭设备和房间管理接口。

BLLetIRCode 库

红外码库,主要提供红外码查询、下载和解析接口。

各个模块之间的关系:

整体框图

1. 前期准备

主要分为以下步骤:

1.  License 申请
2.  Android 工程配置
3.  iOS 工程配置

具体参考 APPSDK集成说明

2. SDK 初始化

为保障SDK不被释放,Android 可以在 Application 创建的时候初始化,iOS 可以在 AppDelegate 里初始化。

具体参考 APPSDK 初始化说明

初始化的时候,可以配置如下全局参数:

        // 配置参数类
        BLConfigParam blConfigParam = new BLConfigParam();
        // 1. 设置日志级别,默认为 4 全部打印
        blConfigParam.put(BLConfigParam.CONTROLLER_LOG_LEVEL, "4");
        // 2. 设置底层打印日志级别,默认为 4 全部打印
        blConfigParam.put(BLConfigParam.CONTROLLER_JNI_LOG_LEVEL, "4");
        // 3. 设置脚本保存目录, 默认在 ../let/ 目录下
        blConfigParam.put(BLConfigParam.SDK_FILE_PATH, "");
        // 4. 设置本地控制超时时间,默认 3000ms
        blConfigParam.put(BLConfigParam.CONTROLLER_LOCAL_TIMEOUT, "3000");
        // 5. 设置远程控制超时时间,默认 5000ms
        blConfigParam.put(BLConfigParam.CONTROLLER_REMOTE_TIMEOUT, "5000");
        // 6. 设置控制重试次数,默认 1
        blConfigParam.put(BLConfigParam.CONTROLLER_SEND_COUNT, "1");
        // 7. 设置设备控制支持的网络模式,默认 -1 都支持。  0 - 局域网控制,非0 - 局域网/远程都支持。
        blConfigParam.put(BLConfigParam.CONTROLLER_NETMODE, "-1");
        // 8. 设置脚本和UI文件下载资源平台。 默认 0 老平台。  1 - 新平台
        blConfigParam.put(BLConfigParam.CONTROLLER_SCRIPT_DOWNLOAD_VERSION, "1");
        // 9. 批量查询设备在线状态最小设备数
        blConfigParam.put(BLConfigParam.CONTROLLER_QUERY_COUNT, "8");
        // 10. 使用APPService服务,此功能为新集群,若为老集群,请设置为 0
        blConfigParam.put(BLConfigParam.APP_SERVICE_ENABLE, "1");
        // 11. 设置云端服务器访问域名,如不设置,则使用SDK解析License出的lid自行拼接
        blConfigParam.put(BLConfigParam.APP_SERVICE_HOST, "https://Your service host");
        // 12. 设置设备连接服务器信息
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("tcp", "xxx");
        jsonObject.put("http","xxx");
        blConfigParam.put(BLConfigParam.DEVICE_CONNECTION_SERVER_HOST, jsonObject.toJSONString());

初始化的时候,必须先初始化 BLLetCore 库, 获取到 lidcompanyId 之后,才可以去初始化其他几个库(BLAccount / BLFamily / BLIRCode

3. 账号模块

BroadLink 提供了一套完整的账户系统供开发者接入。SDK如果需要控制设备进行远程控制,则必须先完成账号登录。

API具体参考 APPSDK 账号系统说明

开发者有以下多套方式接入:

账号流程

登录成功之后,返回信息如下:

参数名称 参数类型 备注
userid String 用户ID
loginsession String 登录的Session
nickname String 用户昵称
iconpath String 用户头像URL地址
sex String 用户性别
birthday String 用户生日
fname String 用户姓
lname String 用户名
email String 用户邮箱地址
phone String 用户手机号
countrycode String 用户手机号对应的地区码,例如:0086
loginip String 登录的IP地址
logintime String 登录时间
pwdflag int 用户密码是否已设置

4. 家庭模块

BroadLink 提供了一套完整的家庭管理系统。通过该系统,开发者可以很好的将 *用户*,*设备*,模块 ,*房间*,家庭 的概念结合起来,构造出一套完整的智能硬件控制系统。

API具体参考 APPSDK 家庭管理系统说明

用户

要使用该家庭管理系统必须接入使用BroadLink的账户系统,只有在用户成功登录之后,才能对家庭管理系统进行操作。单个用户可以创建多个家庭,同时也可以加入到其它用户创建的家庭,或者邀请其它用户加入自己创建的家庭。

家庭

本管理系统除了提供家庭的 增、删、改、查 的功能,还提供了家庭的邀请和退出的功能。家庭信息的每一次更新,都会产生新的家庭版本,在后续的部分接口中,需要指定该家庭版本。

房间

家庭下面可以创建不用的多个房间,例如客厅、卧室等。

模块

要使 家庭 能够管理符合BroadLink协议的设备,则需要使用 模块 的概念。模块 内包含有所在家庭的ID,所在房间的ID,自身的ID和类型,模块下挂载的设备列表信息等。 支持对 模块 的创建、删除,模块基本信息的修改,模块房间的移动。

家庭流程

通过获取指定家庭的详细信息,可以得到一个家庭的全部信息 BLFamilyAllInfo,这些信息包含有:

注意:

5. 设备模块

BroadLink 设备控制系统提供设备配网、设备发现、设备配对以及统一的设备控制功能。

API具体参考 APPSDK 设备控制系统说明

基本概念

设备配网

SDK通过广播/组播的方式,发送UDP报文,将手机输入的Wi-Fi SSID和密码以一定的格式发送给设备端,设备接受到相应的信息后,自行向路由器发送DHCP请求,完成设备配网的功能。

设备发现

SDK通过发送广播包的方式,发现在同一个局域网内符合 BroadLink 相关设备协议的网络设备。

设备配对

SDK获取设备控制的唯一ID和key,设备远程控制必须带上这个两个值,否则会返回-7。
id和key是设备远程控制的必要参数,id和key由设备生成,且仅只会在设备复位重新配置的情况下改变,复位后需要重新配对

设备控制

按照设备网络状态可以分为: 局域网控制和远程控制。
按照命令格式可以分为: 透传控制和脚本控制。

局域网控制

SDK在局域网内,通过UDP发包给设备,直接达到控制设备的目的。设备信息里面必须包含有设备的局域网IP地址。

远程控制

SDK通过设备接入服务器,发送设备控制报文,达到远程控制设备的目的。必须使用 BLLetAccount 完成账号登录之后才能使用。

设备控制分透传控制和脚本控制:

透传控制

SDK直接将二进制数据透传给设备,设备收到之后,依旧返回二进制数据,APP需要自行解析二进制数据的含义。

脚本控制

每一个产品在 BroadLink DNAKit 创建的时候,都会生成一个控制的脚本。设备脚本包含有设备的相关信息,标准的控制指令等。 SDK可以下载脚本到指定路径,在控制设备的时候,将不同的控制指令,通过脚本转换为设备接收的二进制指令下发。同样能将设备返回二进制指令,通过脚本转换为控制指令,便于APP识别和使用。

主要流程如下:

控制流程

  1. 账号登录 ,如果需要远程控制设备,必须要先登录。
  2. 设备配网 ,通过SDK将SSID和密码发送给设备,使设备连接WiFi路由器的过程,设备无法配置入网点击这里?
  3. 设备发现 ,在开启设备扫描 startProbe 之后自动发现局域网设备,通过回调的方式告诉开发者。
  4. 设备配对pair 把获取到的 idkey 设置到设备信息里面
  5. 添加设备 ,调用 addDevice 将设备信息添加到SDK管理。
  6. 下载脚本 ,脚本信息(Profile)包含有设备的相关信息,标准的控制指令等。
  7. 设备控制 ,APPSDK会根据添加设备的信息的不同(主要是局域网IP地址)来判断使用局域网控制,还是远程控制。

UI包下载

开发者如果要使用 BroadLink 已经开发完成的产品 UI 包,可以通过以下接口下载:

  /**
   * Download device control ui.
   *
   * @param pid Product pid
   * @return Download result
   */
  public static BLDownloadUIResult downloadUI(String pid);

开发者如果要使用这个UI包的话,必须引入 Cordova 相关库,同时开发如下接口的 Cordova Plugin
具有相关接口参考 《APP Native 提供H5接口 - v2.4.pdf》

6. 红外码模块

BroadLink集成了多套红外码系统,如果需要使用红外码功能,需要单独向BroadLink申请开放权限。
SDK则提供了相关红外码的查找,下载,基本信息获取以及红外码指令生成接口。

API具体参考 APPSDK 红外码模块说明

主要流程如下:

红外码流程

使用红码服务分为如下几个步骤:

  1. 获取红码描述文件
  2. 下载到红码描述文件后,调用 API 可以获取该红码描述文件对应产品的功能参数
  3. 生成红码指令将产品的功能参数传入 API 后,即可获取到红码二进制指令
  4. 发送到RM产品通过 RM 的控制 API,将红码二进制指令发送给 RM,完成产品控制

红码描述文件有两种获取方式:一键匹配及根据品牌型号查询

一键匹配的工作方式如下:

  1. 将RM产品配置成学习模式
  2. 按遥控器的按钮(开关键即可)
  3. 将RM学习到的按钮指令发送到匹配API
  4. 如果匹配到了,云端会返回脚本URI