APPSDK 红外码模块说明

API概览

名称 描述
requestIRCodeDeviceTypes 获取支持的红外码设备的ID
requestIRCodeDeviceBrands 获取品牌类型ID
requestSubAreas 获取地区列表
requestSTBProviderV3 获取机顶盒运营商ID
requestSTBChannelListV3 获取机顶盒频道列表
requestSTBIRCodeScriptDownloadUrl 获取机顶盒脚本下载信息
requestIRCodeScriptDownloadUrlV3 获取红外码脚本下载信息
recognizeACIRCodeV3 自动识别红外码
downloadIRCodeScriptByIdV3 下载红外码脚本
queryACIRCodeInfomation 获取空调红外码脚本基本信息
queryACIRCodeData 空调红外码数据获取
getMatchTreeV3 红外码匹配树获取
requestCaptchaIdV3 获取频率限制时请求验证码
freeLimitV3 通过验证码增加使用次数

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);

参数说明

参数名 参数类型 备注
deviceType int 设备类型ID

返回值

BLResponseResult

参数名 参数类型 备注
responseBody String 请求返回数据,需要自行解析

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);

参数说明

参数名 参数类型 备注
locateid int 地区ID

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)

参数说明

参数名 参数类型 备注
countryCode String 国家码
provinceCode String 省码
cityCode String 城市码

2.2.3 获取机顶盒频道列表

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

V2接口,后续作废:

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

参数说明

参数名 参数类型 备注
locateid int 地区ID
providerid int 运营商ID

V3接口:

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

参数说明

参数名 参数类型 备注
countryCode String 国家码
provinceCode String 省码
cityCode String 城市码
providerType | String 运营商类型
providerId int 运营商ID

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

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

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

参数说明

参数名 参数类型 备注
locateid int 地区ID
providerid int 运营商ID
brandId int 机顶盒品牌ID,若不清楚该ID,传入 -1 即可

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);

参数说明

参数名 参数类型 备注
deviceType int 设备类型
deviceBrand int 品牌类型ID

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

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

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

V2接口,后续作废:

public static BLResponseResult recognizeACIRCode(String hexString);

V3接口:

public static BLResponseResult recognizeACIRCodeV3(String hexString);

参数说明

参数名 参数类型 备注
hexString String 红外码HEX String

2.5 下载红外码脚本

V2接口,后续作废:

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

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

参数说明

参数名 参数类型 备注
UrlString String 脚本下载URL
savePath String 脚本保存路径
randkey String 脚本随机密钥

V3接口:

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

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

参数说明

参数名 参数类型 备注
mtag String ””:普通红码文件,“xz”:空调xz文件,“gz”:空调gz文件。电视机顶盒默认为json,空调为lua,其他为脚本
ircodeid String 红外码 ircodeid ,下载唯一ID
savePath String 脚本保存路径

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

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

public static BLIrdaConProductResult queryACIRCodeInfomation(String scriptPath);

参数说明

参数名 参数类型 备注
savePath String 脚本保存路径

返回值

BLIrdaConProductResult

参数名 参数类型 备注
name String 设备名称
max_temperature int 最大支持温度值
min_temperature int 最小支持温度值
state int 空调开关状态
mode int 空调模式
windspeed int 空调风速
windirect int 空调出风口方向

2.7 空调红外码数据获取

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

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

参数说明

参数名 参数类型 备注
savePath String 脚本保存路径
params BLQueryIRCodeParams 空调配置参数

BLQueryIRCodeParams 说明

参数名 参数类型 备注
state int 空调开关状态
mode int 空调模式
speed int 空调风速
direct int 空调出风口方向
temperature int 空调设置温度
key int 空调按键,部分空调使用
freq int 红外码频率,默认 38 kHz

返回值

BLIrdaConDataResult

参数名 参数类型 备注
freq int 红外码频率,默认 38 kHz
ircode String 红外码HEX String

2.8 红外码匹配树获取

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

参数说明

参数名 参数类型 备注
countrycode String 国家码
devtypeid int 设备类型ID
brandid int 品牌ID

返回参数说明

参数名 参数类型 备注
hotircode JSON 热门红外码品牌
matchtree JSON 红外码匹配树

hotircode 内部参数说明:

参数名 参数类型 备注
ircodeid String[] 热门红外码品牌 ircode id 列表,前3套为最热门红外码

matchtree 内部参数说明:

参数名 参数类型 备注
key String 按键名称
codeList JSONArray 红外码数据列表
code int[] 测试使用的红外码值
ircodeid String 红外码品牌 ircode id
chirdren matchtree 子节点,如果存在,需要继续解析该 matchtree ,才能决定红外码 ircodeid

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

public static BLResponseResult requestCaptchaIdV3(String targetUrl);

参数说明

参数名 参数类型 备注
targetUrl String 被限制下载的URL

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

public static BLBaseResult freeLimitV3(String captchaId, String captchaValue)

参数说明

参数名 参数类型 备注
captchaId String 前面获取的验证码id
captchaValue String 图片上面的验证码

2.11 波型码转为单元码

public static String waveCodeChangeToUnitCode(String waveCode)

2.12 单元码转为波型码

public static String unitCodeChangeToWaveCode(String unitCode)