APPSDK 红外码模块说明

API概览

1. 概述

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

1.1 使用步骤

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

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

1.2 获取方式

红码描述文件有三种获取方式: 根据品牌型号查询获取、机顶盒运营商获取、空调一键匹配获取和红外码匹配树获取

一、根据品牌型号查询获取：

1. 获取设备类型 ID
2. 获取设备品牌 ID
3. 根据上述获取到的设备类型ID和品牌ID，获取红外码脚本下载信息
4. 调用下载接口，下载红外码脚本

二、根据机顶盒机顶盒运营商获取，本方式只适合机顶盒设备：

1. 获取设备类型 ID，固定为 2
2. 获取机顶盒所在地区ID
3. 获取机顶盒运营商ID
4. 获取机顶盒频道列表
5. 获取机顶盒脚本下载信息
6. 调用下载接口，下载红外码脚本

三、空调一键匹配的工作方式如下:

1. 将RM产品配置成学习模式
2. 按遥控器的按钮(开关键即可)
3. 将RM学习到的按钮指令发送到匹配API
4. 如果匹配到了，云端会返回脚本URI
5. 调用下载接口，下载红外码脚本

四、 红外码匹配树获取

红外码匹配树是最新方式获取红外码下载的 ircodeId，能够最快方式准确获取到客户想要的红外码。

1. 获取国家码
2. 获取设备类型 ID和设备品牌 ID
3. 通过匹配树接口获取到匹配信息
4. 空调只需要获取 hotircode 列表里的 ircodeId 列表，前三套为最热门红外码
5. 其他产品需要通过树状结构数据 matchtree，进行匹配测试，确定红外码 ircodeId
6. 调用下载接口，下载红外码脚本

1.3 红外码解析

电视机和机顶盒下载的红外码文件内容为 JSON 格式，开发者自行读取该文件解析即可。
空调下载的红外码文件内容为 GZ 格式，需要使用 2.6 节内容解析和获取红外码。

2. API 接口介绍

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

iOS 系统可以调用 BLLet 类中的 ircode 属性和相应的实例方法。

Android 系统可以调用 BLLet 类中的 IRCode 静态类方法。

2.1 获取支持的红外码设备的ID

诸如空调（AC），电视机（TV）可以通过查询对应的类型ID，品牌ID获取是否支持该型号的红外码，同时可以获取到下载脚本的URL。

2.1.1 设备类型ID（deviceType）

现有SDK支持以下几种设备类型，对应的ID如下：

public class BLIRCodeDeviceType {
    /** 所有 **/
    public static final int BL_IRCODE_DEVICE_ALL = 0;
    /** 电视 **/
    public static final int BL_IRCODE_DEVICE_TV = 1;
    /** 机顶盒 **/
    public static final int BL_IRCODE_DEVICE_TV_BOX = 2;
    /** 云空调 **/
    public static final int BL_IRCODE_DEVICE_AC = 3;
}

通过函数获取红外码支持的所有类型ID：

public static BLResponseResult requestIRCodeDeviceTypes();

2.1.2 品牌类型ID（deviceBrand）

通过传入 设备类型ID ，可以查询到所支持的所有的 品牌类型ID ，开发者通过返回的数据，查找到所需要的设备。

public static BLResponseResult requestIRCodeDeviceBrands(int deviceType);

参数说明

返回值

BLResponseResult

2.2 机顶盒设备红外码操作接口

机顶盒设备（STB）无法通过品牌来获取到相应的脚本，而是通过查询地区和运营商ID的方式来准确判断对应的红外码脚本。

2.2.1 获取机顶盒所在地区ID

SDK 通过查询指定地区ID，可以获取到属于该地区下的子地区的ID。 该接口采用树型结构，顶端ID为0，即可以查询到所有国家的ID。

如果查询到的叶结点 isleaf 为 0， 代表下方还有地区需要查询，反之 isleaf 为 1， 则无法再查询。

/**
* Gets the list of regions under the specified region ID
* if ID = 0, get all countries‘ ids
* if isleaf = 0, you need call this interface again to get the list of regions.
* if isleaf = 1, don't need get again.
*
* @param locateid Region ID
* @return the list of regions
*/
public BLResponseResult requestSubAreas(int locateid);

参数说明

2.2.2 获取机顶盒运营商ID

V2接口，后续作废：

1. 获取到指定的地区ID之后，就可以再次查询该地区下所有的运营商，并且获得对应的运营商ID。

public static BLResponseResult requestSTBProvider(int locateid);

1. 直接通过传入国家/省份/城市名称，也可以获取该地区下所有的运营商，并且获得对应的运营商ID。

public static BLResponseResult requestSTBProvider(String country, String province, String city);

V3接口：

public static BLResponseResult requestSTBProviderV3(String countryCode, String provinceCode, String cityCode)

参数说明

2.2.3 获取机顶盒频道列表

通过 2.2.2 相关接口查询得到机顶盒相应地区和运营商的ID，即可向云端请求获取该机顶盒频道列表

V2接口，后续作废：

public static BLResponseResult requestSTBChannelList(int locateid, int providerid);

参数说明

V3接口：

public static BLResponseResult requestSTBChannelListV3(String countryCode, String provinceCode, String cityCode, String providerType, int providerId)

参数说明

2.2.4 获取机顶盒脚本下载信息

通过 2.3.2 相关接口查询得到机顶盒相应地区和运营商的ID，即可向云端请求获红外码脚本下的URL。

public static BLResponseResult requestSTBIRCodeScriptDownloadUrl(int locateid, int providerid, int brandId);

参数说明

2.3 获取红外码脚本下载信息 (机顶盒除外)

通过 2.1 节相关步骤，可以准确获知设备是否支持，以及设备对应的 设备类型ID，品牌类型ID。

通过这些ID，就可以向云端查询该设备所对应的红外码脚本下载的URL。

V2接口，后续作废：

public static BLResponseResult requestIRCodeScriptDownloadUrl(int deviceType, int deviceBrand);

V3接口：

public static BLResponseResult requestIRCodeScriptDownloadUrlV3(int deviceType, int deviceBrand);

参数说明

2.4 自动识别红外码，获取空调脚本下载URL

开发者如果事先了解到设备的某条红外码，将其转化成十六进制字符串，再将其上报到云端，云端会自动识别该红外码，返回相应的URL列表。

由于识别到的下载URL可能存在多个，所有有可能需要请求多个红外码才能准确识别出来。 请求结果包含有 下载URL 以及 脚本随机密钥 。

V2接口，后续作废：

public static BLResponseResult recognizeACIRCode(String hexString);

V3接口：

public static BLResponseResult recognizeACIRCodeV3(String hexString);

参数说明

2.5 下载红外码脚本

V2接口，后续作废：

根据上面几节内容获取到的红外码脚本下载URL，即可向云端请求下载该红外码脚本。

public static BLDownLoadIRCodeResult downloadIRCodeScript(String UrlString, String savePath, String randkey);

参数说明

V3接口：

根据上面几节内容获取到的红外码脚本的 ircodeId ，即可向云端请求下载该红外码脚本。

public static BLDownLoadIRCodeResult downloadIRCodeScriptByIdV3(String mtag, String ircodeid, String savePath);

参数说明

2.6 获取红外码脚本基本信息

由于不同的红外码脚本，在处理上存在较大的差异， 空调设备脚本基本都是线性属性，从基本信息中可以获取到相应控制的参数的范围，所以要先获取到红外码脚本的基本信息。

public static BLIrdaConProductResult queryACIRCodeInfomation(String scriptPath);

参数说明

返回值

BLIrdaConProductResult

2.7 空调红外码数据获取

根据脚本基本信息，可以得知此接口所需要传入的数据，再获取到相应的红外码十六进制字符串。

public static BLIrdaConDataResult queryACIRCodeData(String scriptPath, BLQueryIRCodeParams params);

参数说明

BLQueryIRCodeParams 说明

返回值

BLIrdaConDataResult

2.8 红外码匹配树获取

public static BLResponseResult getMatchTreeV3(String countrycode, int devtypeid, int  brandid);

参数说明

返回参数说明

hotircode 内部参数说明：

matchtree 内部参数说明：

2.9 获取频率限制时请求验证码

public static BLResponseResult requestCaptchaIdV3(String targetUrl);

参数说明

2.10 通过验证码增加使用次数

public static BLBaseResult freeLimitV3(String captchaId, String captchaValue)

参数说明

2.11 波型码转为单元码

public static String waveCodeChangeToUnitCode(String waveCode)

2.12 单元码转为波型码

public static String unitCodeChangeToWaveCode(String unitCode)