APPSDK 设备控制系统说明

API概览

1. 基本功能介绍

APPSDK 设备控制系统是基于原有 DNASDK 开发，提供设备配网、设备发现、设备配对以及统一的设备控制功能。

基本概念

设备配网

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

设备发现

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

设备配对

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

设备控制

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

局域网控制

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

远程控制

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

主要流程如下：

主要流程：

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

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

透传控制

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

脚本控制

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

2. API 接口介绍

设备控制系统相关接口将会在 BLLetCore 库的 BLLet 类初始化之后，就会以单例的方式实例化。

iOS 系统可以调用 BLLet 类中的 controller 属性和相应的实例方法。 Android 系统可以调用 BLLet 类中的 Controller 静态类方法。

2.1 设备配网

deviceConfig 方式进行设备网络配置采用局域网 UDP 发包的方式对设备进行 Wi-Fi 配置。

注意：

1. 由于设备配网采用了3代不用的配网协议，虽然3代配网方式都可以互相兼容，但开发者为了提高配网的效率，需要提前清楚设备所遵循的配网协议，在接口中填入。
2. 该接口只要有一个设备接入局域网就直接返回了，多个设备同时配置时并不能保证所有设备都可以成功接入局域网。
3. 在部分路由器下，由于配网发包速度较快，路由器负载过高，导致设备无法从路由器获取到DHCP分配到的 IP，从而导致配网失败，返回 -4000。针对这一情况，开发者需要自行通过设备发现接口进行判断是否有新设备发现。

    public static BLDeviceConfigResult deviceConfig(BLDeviceConfigParam deviceConfigParam, int timeout);

请求参数

BLDeviceConfigParam 说明

返回参数

BLDeviceConfigResult 说明

2.2 设备AP方式配网

AP 方式进行设备网络配置，首先需要设备进入 AP 广播模式，手机端连接到该 AP 中，然后再进行后续接口调用。

通过下述接口，获取到设备能够连接到的 Wi-Fi 列表：

public static BLGetAPListResult deviceAPList(int timeOut);

请求参数

返回参数

BLGetAPListResult 说明

BLAPInfo 说明

然后指定上述接口获取到的某一 Wi-Fi 进行配置：

public static BLAPConfigResult deviceAPConfig(String ssid, String password, int type, BLConfigParam configParam);

配置完成之后，开发者需要自行通过设备发现接口进行判断是否有新设备发现。

2.3 设备局域网发现

SDK可以发现在同一个局域网内符合 BroadLink 相关设备协议的网络设备。 由于该扫描耗时，且单一次扫描无法做到局域网内所有设备都能扫描到，所以SDK采用开启后台线程，发现设备后通过回调的方式再上报给开发者。

2.3.1 开启/关闭设备扫描

public static void startProbe(int probeInterval);
public static void stopProbe();

请求参数

2.3.2 扫描到设备回调

通过设置回调接口类 BLDeviceScanListener，设备每次扫描到新设备之后都会上报。

public static void setOnDeviceScanListener(BLDeviceScanListener scanListener);

public abstract class BLDeviceScanListener {
    public abstract void onDeviceUpdate(BLDNADevice device, boolean isNewDevice);
}

BLDNADevice 设备信息说明

注意：

1. SDK每一次扫描到设备之后都会通过 onDeviceUpdate 接口上报
2. onDeviceUpdate 接口内的参数 isNewDevice，是指设备是否被SDK添加过
3. 可以通过查看 BLDNADevice device 的设备信息 newConfig 属性判断扫描到的设备是否是新配置的设备

2.4 设备添加

为了能够更加方便的控制设备，设备需要主动添加到SDK内一次，SDK会缓存设备的相关信息，而在后续的设备操作中，只需要传入设备的唯一 did 即可。 同时SDK会对添加SDK里的设备状态进行维护查询。 如果设备不再需要在SDK里控制了，则需要主动删除相关的设备 did 。

public static void addDevice(BLDNADevice device);
public static void addDevice(ArrayList<BLDNADevice> listDevice);

注意：

1. 不论是Wi-Fi设备还是子设备，要使用SDK对其进行控制，都必须先 addDevice 将其添加到SDK中才可以进行后续操作。

2.5 设备配对

为了能够安全的控制设备，每一个符合 BroadLink 协议的设备都会生成一个控制的 ID 和 Key ，
在设备不重置复位的情况下，该控制的 Key 都是唯一的。如果设备复位重置，则会重新生成一个新的控制 ID 和 Key 。

public static BLPairResult pair(BLDNADevice device, BLConfigParam configParam);

注意：

1. 注意该接口只能在与设备在同一个局域网内才能 pair 成功
2. 如果在设备控制的时候，返回接口为 -7, 请再次调用此接口获取最新的控制的 ID 和 Key
3. 获取到的 ID 和 key ,需要设置到 device 的信息中

2.6 设备控制 - 数据透传

该种方式下，SDK 仅将应用发送的数据原封不动的发送至设备上，且设备返回的数据也同样不做处理直接回传给应用。

public static BLPassthroughResult dnaPassthrough(String deviceId, String sDeviceId, byte[] data, BLConfigParam configParam);

请求参数

返回参数

BLPassthroughResult 说明

2.7 设备控制 - 脚本方式

设备脚本包含有设备的相关信息，标准的控制指令等。 由于同一类的产品型号Pid的产品脚本都是相同的，所以同一类的产品只需要下载一份脚本即可。

2.7.1 脚本版本查询

设备脚本均包含版本信息，如果版本更新，请重新下载脚本

public static BLQueryResoureVersionResult queryScriptVersion(List<String> pidList);

请求参数

返回参数

BLQueryResoureVersionResult 说明

BLResourceVersion 说明

2.7.2 脚本下载

public static BLDownloadScriptResult downloadScript(String pid);

请求参数

返回参数

BLDownloadScriptResult 说明

注意：

1. 该接口需要下载文件，耗时较长
2. 脚本下载如果返回 403，请确认 License 里是否已经添加该设备
3. 脚本下载如果返回 404，请确认下载平台上是否存在该脚本，确认下载平台为新平台或者老平台。查看该参数 BLConfigParam.CONTROLLER_SCRIPT_DOWNLOAD_VERSION

2.7.3 脚本信息获取

脚本信息(Profile) 包含有设备的相关信息，标准的控制指令等。 SDK会缓存读取到的Profile信息，如果脚本存在更新，Profile也会更新，则需要手动清除掉缓存的Profile信息。

public static BLProfileStringResult queryProfileByPid(String pid, String profilePath);

请求参数

返回参数

BLProfileStringResult 说明

2.7.4 设备控制 - 脚本方式

该种方式下，设备控制指令必须符合 SDK 的指令规则。 SDK 将应用层发送的指令通过脚本解析成设备识别的控制命令发送至设备， 且设备返回的数据也会通过脚本处理成符合规则的指令回传给应用。

开发者通过设置符合SDK接口的数据，将相应的 value 和 param 填充到SDK接口内， SDK再重新组装成符合标准的JSON控制命令，再通过传入的控制脚本解析成指令发送给模块， 且模块返回的数据也会通过脚本处理成符合规则的指令回传给应用。

public static BLStdControlResult dnaControl(String deviceId, String sDeviceId, BLStdControlParam stdControlParam, BLConfigParam configParam);

请求参数

返回参数

BLStdControlResult 说明

BLStdData 说明

2.7.5 设备控制 - 通用命令

SDK 提供通用控制命令，由 APP 自行组织命令和内容，通过 SDK 发送给设备。

public static String dnaControl(String deviceId, String sDeviceId, String dataStr, String cmd, BLConfigParam configParam)

请求参数

返回参数

cmd 和 dataStr 有较多的格式，具体请参考： 设备控制Command详解

2.8 通用定时任务

注意：

插座类SP设备和红外遥控类RM设备的定时不支持此接口，需要采用上一节Demo的形式进行配置。

如果设备的 Profile 支持 dev_task 家族 相关命令，则设备支持使用此接口来设置任务。SDK支持对设备的任务的增删改查的相关功能。 新增／修改设备的任务，对设备的控制都是通过脚本实现的，所以在接口中要实现对设备的任务控制与设备脚本控制的命令 stdData 规则相同。

任务类型taskType

2.8.1 普通任务/延迟任务

普通任务和延迟任务极其类似，分别支持16组不同的定时任务。延迟任务的效果需要UI来显示控制。

采用如下接口增加或者修改任务：

public static BLQueryTaskResult updateTask(String deviceId, String sDeviceId,  int taskType, 
        boolean isNew, BLTimerInfo task, BLStdData stdData, BLConfigParam configParam);

参数说明

*BLTimerInfo*：

2.8.2 周期任务

周期任务是以周为单位，每周指定日期执行命令

public static BLQueryTaskResult updateTask(String deviceId, String sDeviceId, 
        boolean isNew, BLPeriodInfo task, BLStdData stdData, BLConfigParam configParam);

参数说明

*BLPeriodInfo*：

2.8.3 循环任务/防盗任务

循环任务/防盗任务是以周为单位，在固定的时间段内，执行不同的两条命令

注意：

循环任务/防盗任务现只支持2组任务的设置，如果修改任务，index必须为0/1

public static BLQueryTaskResult updateTask(String deviceId, String sDeviceId,  int taskType, boolean isNew, BLCycleInfo task, BLStdData stdData1, BLStdData stdData2, BLConfigParam configParam);

参数说明

*BLCycleInfo*：

2.8.4 任务列表查询

public static BLQueryTaskResult queryTask(String deviceId, String sDeviceId, BLConfigParam configParam);

参数说明

返回值

BLQueryTaskResult

2.8.5 任务删除

任务删除需要指定任务类型和任务的索引。 具体需要从任务列表查询获取。

public static BLQueryTaskResult delTask(String deviceId, String sDeviceId, int taskType, int index, BLConfigParam configParam);

参数说明

2.8.6 任务命令查询

任务命令查询需要指定任务类型和任务的索引。获取实际执行的命令的值。

public static BLTaskDataResult queryTaskData(String deviceId, String sDeviceId, int taskType, int index, BLConfigParam configParam);

参数说明

2.8.7 定时显示时区设置

由于设备端使用的时区总是处于东八区，所以在定时设置喝显示时，需要根据APP设置的时区，转换相应的时差值，再下发给设备端。

​ Ps: 如果没有设置该值，SDK会自动根据手机当前时间和设备时间的差值进行换算。

iOS 端设置全局变量 BLConfigParam 里的参数：

/// 设置APP时区，用于定时设置转换
/// 如果是东八区，则设置为 8。如果是西五区，则设置为 -5 
@property (nonatomic, copy) NSNumber *utcTimeZone;

Android 端调用如下接口：

/**
 * 设置用户时区
 * 如果是东八区，则设置为 8。如果是西五区，则设置为 -5 
 */
public static void setUtcTimeZone(int timeZone);

/**
 * 获取用户时区
 */
public static int getUserTimeZone();

2.9 设备状态查询

查询单个设备状态

对于已经添加到SDK里的设备，SDK会自动查询设备的状态（本地，远程，离线），而没有添加到SDK到设备，如果使用该接口查询则会返回未知。 如果SDK开启了 Probe 线程，当 Probe 扫描到设备之后，设备状态则会置为本地. 如果SDK未开启 Porbe 线程，或者 Probe 不到设备，SDK则会向云端请求查询该设备的状态是远程在线／离线。

public static int queryDeviceState(String deviceId);

批量查询设备云端在线状态

已联网设备会和 BroadLink 云端保持心跳连接，则为设备在线； 如果长时间心跳消失，则认为是设备离线。 本接口可以批量查询设备的在线状况，使用前需要确认 lid + devinfo.ibroadlink.com 该服务是否已经部署。

public static BLQueryDeviceStatusResult queryDeviceOnServer(ArrayList<BLDNADevice> listDevice);

参数说明

返回值说明

[
    {
        "did":"xxxx",       // 设备唯一did
        "status": 0         // 设备在线状态。 0 - 离线， 1 - 在线
    }
]

2.10 设备时间查询

由于设备固件无法根据实时根据时区来调整时间，所以设备里面查询到的时间都是北京时间（东八区时），如果开发者需要在应用里显示或者设置设备时间相关操作，则需要先获取到设备时间，再转化为当地时间。

public static BLDeviceTimeResult queryDeviceTime(String deviceId);

参数说明

2.11 设备上报数据查询

部分设备(例如带计量功能的插座)会定时向服务端上报数据，通过该接口则可以查询到指定时间内上报的所有数据。

注意：

该接口现仅支持计量类插座查询电量统计。

public static BLBaseBodyResult queryDeviceData(String deviceId, String familyId, String startTime, String endTime, String type)

参数说明

type参数说明

返回值说明

返回值为json格式字符串，根据字符串解析获取相关信息

2.12 固件升级

开发者如果想要升级指定设备的固件版本，需要先搭建固件下载的服务器，将该服务器域名传人到指定接口内。

public static BLBaseResult updateFirmware(String deviceId, String url, BLConfigParam configParam);

参数说明

返回值说明

注意：

• 命令发送结果，并非固件升级结果。
• 固件升级结果需要观察设备状态，设备重启，指示灯慢闪重新连接上网络之后则升级成功。

2.13 获取 RMAC 红外码脚本信息

RMAC 脚本为 Lua 格式， 需要使用该接口获取RMAC红码脚本信息

public static BLIRCodeInfoResult queryRMACIRCodeInfomation(String scriptPath)

参数说明

返回值说明

2.14 获取 RMAC 发送红外码 Hex格式

RMAC 脚本为 Lua 格式， 需要使用该接口获取 RMAC 发送红外码 Hex格式

public static BLIRCodeDataResult queryRMACIRCodeData(String scriptPath, BLQueryIRCodeParams params)

参数说明

返回值说明

2.15 计算日出日落时间

获取指定日期，经度和纬度，获取当天日出日落时间

public BLSunriseResult calulateSunriseTime(String date, double longitude, double latitude)

参数说明

返回值说明

2.16 设备连接服务器查询

获取设备连接到的服务器相关信息，该接口需要设备固件支持相关命令才能查询。

public BLQueryDeviceConnectServerResult queryDeviceConnectServerInfo(String deviceId)

参数说明

返回值说明

ServerBean 说明

2.17 获得已添加到sdk的设备列表

查询已添加到sdk中的设备列表

 public ArrayList<BLDNADevice> queryDeviceAddedList()

参数说明

返回值说明