App SDK IR code management

API Overview

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

Return Parameter

BLResponseResult

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

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

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

V3 interface:

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

*Request Parameter

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

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

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

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

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

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

Return Parameter

BLIrdaConProductResult

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

BLQueryIRCodeParams

Return Parameter

BLIrdaConDataResult

2.8 Get by IR code matching tree

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

Request Parameter

Return Parameter

hotircode Parameter:

matchtree Parameter:

2.9 Request verification code when getting frequency limit

public static BLResponseResult requestCaptchaIdV3(String targetUrl);

Request Parameter

2.10 Increase the number of uses by captcha

public static BLBaseResult freeLimitV3(String captchaId, String captchaValue)

Request Parameter

2.11 Wavecode to Unitcode

public static String waveCodeChangeToUnitCode(String waveCode)

2.12 Unitcode to Wavecode

public static String unitCodeChangeToWaveCode(String unitCode)