App SDK IR code management

API Overview

Name Description
requestIRCodeDeviceTypes Get the ID of the supported Ircode device
requestIRCodeDeviceBrands Get brand ID (deviceBrand)
requestSubAreas Get region ID of STB
requestSTBProviderV3 Get STB provider ID
requestSTBChannelListV3 Get STB channel list
requestSTBIRCodeScriptDownloadUrl Get STB script URL
requestIRCodeScriptDownloadUrlV3 Get IRcode script URL
recognizeACIRCodeV3 recognizeIRCod
downloadIRCodeScriptByIdV3 Download IRCode Script
queryACIRCodeInfomation Get AC IRCode Information
queryACIRCodeData Get AC IRCode
getMatchTreeV3 Get IRCode matching tree
requestCaptchaIdV3 Request verification code when getting frequency limit
freeLimitV3 Increase the number of uses by captcha

1. Overview

BroadLink integrated multiple sets of IR code for home appliances. The developers need to apply separately to BroadLink for the permission of using IR code library.

The SDK provides interfaces for querying and downloading IR codes, obtaining basic information and generating control commands.

1.1 Steps for use

There are several steps for using IR code service

  1. Obtain IR code script
  2. After the IR code script is downloaded, you can call the API to obtain the product function parameters of the specified product
  3. You can obtain the IR command in binary after the function parameters are obtained in API
  4. You can send the binary command to universal remote via API to control appliance.

1.2 Ways to obtain

You can use either way to obtain the IR code script: get by brand and model selection, get by set-top box operator, get by air conditioner one button match and get by IR code matching tree.

Get by brand and model selection:

  1. Get the devicetype ID
  2. Get the brand ID
  3. Get the IR code script download information based on the devicetype ID and brand ID obtained above
  4. Call the download interface and download the IR code script

Get by set-top box operator:

  1. Get the devicetype ID, fixed as 2
  2. Get the location ID
  3. Get the set-top box operator ID
  4. Get the chanel list of set-top box
  5. Get the set-top box download information
  6. Call the download interface and download the IR code script

Get by air conditioner one button match:

  1. Set universal remote in learning mode
  2. Point the remote to universal remote and press the button (normally ON/OFF)
  3. Send the learnt command to matched API
  4. If the API is matched, the script URL will be returned from cloud
  5. Call the download interface and download the IR code script

Get by IR code matching tree:

This is the latest way to get the IR code id of IR code download, which is the fastest way to get the exact IR code that the customer wants.

  1. Get the country ID
  2. Get the devicetype ID and brand ID
  3. Get the matching information through the matching tree interface
  4. The air conditioner only needs to get the ircodeId list in the hotircode list, the first three sets are the most popular infrared codes
  5. Other products need to test through matchtree to determine the ircodeId
  6. Call the download interface and download the IR code script

1.3 IR code analysis

The content of the IR code file of TVs and STBs is in JSON format, so developers can read the file and parse it by themselves.

The contents of the IR code file of the air conditioner are in GZ format and need to be parsed and obtained using the contents of section 2.6.

2. API Description

Home management interfaces will be instantiated as singleton after initialization of BLLet class in BLLetCore library.

You can invoke ircode attribute in BLLet class and relevant instance on iOS.

You can invoke ircode static method in BLLet class on Android.

2.1 Get the ID of the supported Ircode device

For example: AC ,TV can know if it supports the Ircode of this mode by querying device type and brand id,and at the same time, obtain the download script URL.

2.1.1 Get device type ID(deviceType)

The SDK supports the following device types,and the corresponding IDs are as follows:

public class BLIRCodeDeviceType {
    /** ALL **/
    public static final int BL_IRCODE_DEVICE_ALL = 0;
    /** TV **/
    public static final int BL_IRCODE_DEVICE_TV = 1;
    /** STB **/
    public static final int BL_IRCODE_DEVICE_TV_BOX = 2;
    /** AC **/
    public static final int BL_IRCODE_DEVICE_AC = 3;
}

Get all devicetype ID supported by the IR code through the function.

public static BLResponseResult requestIRCodeDeviceTypes();

2.1.2 Get brand ID(deviceBrand)

You can query all supported brand IDs by passed device type ID and find the required device from returned data.

public static BLResponseResult requestIRCodeDeviceBrands(int deviceType);

Request Parameter

Parameter Name Parameter Type Note
deviceType int Device type id

Return Parameter

BLResponseResult

Parameter Name Parameter Type Note
responseBody String Returned data (needs to be resolved)

2.2 Interface for STB IR codes

You need to get the IR code script for set-top box (STB) by querying region and carrier ID instead of using brand ID.

2.2.1 Get region ID of STB

You can get the region ID by querying specific country ID in SDK.

This interface is designed with tree structure with top value 0 for all country IDs.

If you find the leaf node isleaf is 0, it means there are regions can be queried. If isleaf is 1, the query will be invalid.

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

Request Parameter

Parameter Name Parameter Type Note
locateid int region ID

2.2.2 Get STB provider ID

V2 interface, later invalid

  1. 1.You can query all providers with their IDs if region ID is specified.
public static BLResponseResult requestSTBProvider(int locateid);
  1. 2.You can query all providers with their IDs if the name of country/province/city is specified.
public static BLResponseResult requestSTBProvider(String country, String province, String city);

V3 interface:

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

Request Parameter

Parameter Name Parameter Type Note
countryCode String country ID
provinceCode String province ID
cityCode String city ID

2.2.3 Get STB channel list

You can request from cloud for channel list supported by this STB using the region ID and provider ID got from the interface mentioned in 2.2.2.

V2 interface, later invalid

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

Request Parameter

Parameter Name Parameter Type Note
locateid int Region ID
providerid int Provider ID

V3 interface:

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

*Request Parameter

Parameter Name Parameter Type Note
countryCode String country ID
provinceCode String province ID
cityCode String city ID
providerType String provider type
providerId int provider ID

2.2.4 Get STB script URL

You can request from cloud for Ircode script URL by using the region ID and provider ID got from the interface mentioned in 2.2.2.

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

Request Parameter

Parameter Name Parameter Type Note
locateid int Region ID
providerid int Provider ID
brandId int Brand ID of STB, if not clear this ID, pass -1

2.3 Get Ircode script URL (Excluding set-top boxes)

You can know that if the device is supported and the device type ID and brand ID from the interface mentioned in 2.1

You can request from cloud for Ircode script URL by using the device type ID and brand ID

V2 interface, later invalid:

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

V3 interface:

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

Request Parameter

Parameter Name Parameter Type Note
deviceType int deviceType
deviceBrand int Brand ID

2.4 Auto Match,Get AC script URL

If you already have one of the IR code for the device, you can convert it to HEX string and submit it to cloud. The cloud server will automatically recognize the IR code and return the script URL list.

You may need to request for more than one IR code for precise recognition to minimize the list.

The returned result contains Downloading URL and Ransom key of script.

V2 interface, later invalid:

public static BLResponseResult recognizeACIRCode(String hexString);

V3 interface:

public static BLResponseResult recognizeACIRCodeV3(String hexString);

Request Parameter

Parameter Name Parameter Type Note
hexString String HEX string of IR code

2.5 Download IR Code Script

V2 interface, later invalid:

You can request for downloading the IR code script from cloud according to the obtained script URL mentioned in previous sections.

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

Request Parameter

Parameter Name Parameter Type Note
UrlString String Downloading URL of script
savePath String Script saved path
randkey String Random key of script

V3 interface:

You can request for downloading the IR code script from cloud according to the obtained ircodeId mentioned in previous sections.

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

Request Parameter

Parameter Name Parameter Type Note
mtag String ””:common ircode file,“xz”:xz file for AC,“gz”:gz file for AC. TV, set-top box default for json, air conditioner for lua, other for script
ircodeid String ircodeid, unique ID for downloading
savePath String Script saved path

2.6 Get IR Code Information

Different IR code scripts need to be processed separately:
1. The IR code scripts for ACs are linear and you can get the range of control parameter from basic information.
2. The IR code scripts for TV/STB are button-based and different buttons represent for different functions which require different IR codes.

public static BLIrdaConProductResult queryACIRCodeInfomation(String scriptPath);

Request Parameter

Parameter Name Parameter Type Note
savePath String Script saved path

Return Parameter

BLIrdaConProductResult

Parameter Name Parameter Type Note
name String Device name
max_temperature int max temperature
min_temperature int mini temperature
state int AC on/off state
mode int AC mode
windspeed int AC windspeed
windirect int AC windirect

2.7 Get AC IR Code

You can get the required data to be passed in this interface according to script basic information and then obtain the HEX string accordingly.

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

Request Parameter

Parameter Name Parameter Type Note
savePath String Script saved path
params BLQueryIRCodeParams AC configuration parameters

BLQueryIRCodeParams

Parameter Name Parameter Type Note
state int On/Off state
mode int Mode
speed int Fan speed
direct int Wind direction
temperature int Target temperature
key int Buttons (only for some models)
freq int IR frequency (default is 38 kHz)

Return Parameter

BLIrdaConDataResult

Parameter Name Parameter Type Note
freq int IR frequency (default is 38 kHz)
ircode String HEX string of IR code

2.8 Get by IR code matching tree

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

Request Parameter

Parameter Name Parameter Type Note
countrycode String country ID
devtypeid int devicetype ID
brandid int brand ID

Return Parameter

Parameter Name Parameter Type Note
hotircode JSON popular IRcode ID
matchtree JSON Ircode matching tree

hotircode Parameter:

Parameter Name Parameter Type Note
ircodeid String[] Popular IRcode ID list, the first 3 sets are the most popular IR code

matchtree Parameter:

Parameter Name Parameter Type Note
key String function name
codeList JSONArray IRcode list
code int[] IRcode used for testing
ircodeid String IRcode id
chirdren matchtree child node, if it exists, you need to continue parsing the matchtree to determine the IRcode ID

2.9 Request verification code when getting frequency limit

public static BLResponseResult requestCaptchaIdV3(String targetUrl);

Request Parameter

Parameter Name Parameter Type Note
targetUrl String URLs that are restricted from being downloaded

2.10 Increase the number of uses by captcha

public static BLBaseResult freeLimitV3(String captchaId, String captchaValue)

Request Parameter

Parameter Name Parameter Type Note
captchaId String verification code
captchaValue String The verification code above the picture

2.11 Wavecode to Unitcode

public static String waveCodeChangeToUnitCode(String waveCode)

2.12 Unitcode to Wavecode

public static String unitCodeChangeToWaveCode(String unitCode)