Key Implementation

 

Applications using the LG QRemote SDK can control IR LED through the background IR services on the LG smartphones. Before controlling devices, all applications have to connect to the IR services and then send commands they want to process.

 

This page will show the basic workflow for connecting to IR services and how to send IR signals and use the learning feature. To use the internal database, developers should know the exact labels for each function in the device. The labels are also provided in this section.

The LG QRemote SDK provides a sample application implemented according to the workflow. The code analysis of the sample application can be found in Sample Tutorials.

Basic Workflow

The following figure illustrates the basic workflow of the applications developed using the LG QRemote SDK. It shows the typical order of the commands while working with the LG QRemote APIs.

 

 

Applications which want to control IR LED on the LG smartphones have to create an instance of the IRBlaster class. The IRBlaster class is in charge of communication with the background IR services.

 

getIRBlaster() is an static method which creates a new instance of IRBlaster and binds the application to the IR services. If no error has occurred, the method returns the new instance of IRBlaster. If not, null will be returned.

 

 
IRBlaster mIR = IRBlaster.getIRBlaster(this, anIRBlasterCallback);

 

To communicate with the IR services, applications need to implement the IRBlasterCallback interface. All events from the IR services will be taken by IRBlasterCallback. When the binding process is completed, the IR services send a ready event to the IR Blaster, and then theIRBlasterReady() callback method of IRBlasterCallback is invoked. You should implement what you want to do after setting up the IR services in the IRBlasterReady() callback method.

 

 
IRBlasterCallback mIrBlasterReadyCallback = new IRBlasterCallback() {
    @Override
    public void IRBlasterReady() {
        Log.d(TAG,"IR(infrared) Blaster is really ready");
        /* Do something after the IR services are ready */
   }
    …
}

 

All of the jobs using the IR LED should be done after receiving the IRBlasterReady() callback. You can do any functions related to the IR LED, such as sending IR signals or Learning IR data, until your application is unbound from the IR services. See the following sections to learn more about what you can do during this period.

 

Please remember that close() of IRBlaster must be called when the applications no longer use the IR services. This method unbinds the instance ofIRBlaster from the IR services.

Adding and Deleting Devices

QRemote has an internal database that stores functional IR codes for various devices. To use the database, the first thing we have to do is to register a device through registration process of QRemote. QRemote is in charge of device registration, so you need to call the registration screen of QRemote in your application.

 

The following code starts the registration process.

 

 
int result = mIR.addDevice();

With the above code, you can see the registration screen like the following figure. Categories for controllable devices are shown in the screen. Users should select a category and then register a device.

 

 

Categories can differ from the above figure because the range of controllable devices depends on your mobile device.

 

You can skip the category selection phase if you want to add a TV or a cable box. Use the following code:

 

 
mIR.addTvDevice();     // starts TV registration process
mIR.addStbDevice();    // starts cable box registration process

 

QRemote detects registered devices according their location (living room, bedroom and so on), but addDevice() does not specify the location. Therefore devices added by addDevice() cannot be shown in QRemote. To use the device added by your application in QRemote, useaddDeviceDefaultRoom() instead of addDevice().

 

You can delete a device using deleteDevice() or deleteAnyDevice(). To delete a device registered by QRemote, you must calldeleteAnyDevice(). deleteDevice() does not have a permission to manage devices of QRemote.

The following code deletes the last registered device.

 

 
Device[] devices = mIR.getDevices();
if(devices != null) {
    int result = mIR.deleteAnyDevice(devices[devices.length – 1].Id);
    if(result != ResultCode.SUCCESS)
        Log.e("test", "Cannot delete the device.");
}

Using Configured Devices

Applications call getDevices() of the IRBlaster instance to get the configured devices and their IR functions. The IR Blaster relays the command to the IR services, and the IR services return the configured device list.

 

 
			Devices[] mDevices = mIR.getDevices();

 

The list also have the IR functions supported by each configured device. The device ID, device name, vendor name, and the supported IR function IDs of the device can be retrieved from the list. You can send IR command by calling sendIR() of IRBlaster with an IRAction instance as the argument. TheIRAction instance includes the device ID and IR function ID to control the device.

 

 
mIR.sendIR(new IRAction(mDeviceId, mFunctionID);

 

The IR services send IR signals according to the command, and return the result code. You should handle the result code if the command fails. The meaning of each result code can be found in Result Codes.

Sending Raw IR Data

Before implementing sending raw IR data, refer to Supported Devices.


If you have raw IR data of your device, you can send it without the configured devices. That means it is not needed to check the device ID and the IR function ID. LG QRemote SDK provides a way to send already known IR signal.

 

 
int[] irdata = { 3000, 2500, /* all IR codes ... */ , 780 };
mIR.sendIRPattern(38000, irdata);

 

irdata in the above code block describes the timing information of IR signals to be sent. It has alternating IR light on/off patterns in microseconds. In the above code example, IR light will be on for 3000 microseconds and then off for 2500 microseconds, and so on.

The usage of sendIRPattern() is identical to ConsumerIrManager.transmit() of Android. Refer to Android Developer website.

Learning IR Data

The learning feature is only supported in some LG smartphones. Check if the device can use the learning feature by usingisLearningSupported(), or refer to Supported Devices.


LG QRemote SDK provides APIs for the IR learning feature. To learn IR data, you have to start a learning process. Then the IR services will calllearnedIRCompleted() of IRBlasterCallback when the learning process is complete or canceled.

The following figure shows the learning process using the LG QRemote SDK.

 

 

To learn IR data, please put your source remote control 4 inches in front of the IR LED on your smartphone. If QRemote SDK cannot recognize the IR signal within 30 seconds, the learning process is canceled and returns a timeout error.

There might be some interference when there is an over-abundance of light.


After startIrLearning() is called, the IR Blaster asks the IR services to start a learning process.

If the process is complete, the IR Blaster returns the result status within the learnedIRComplete() callback. The result status shows whether the IR learning is successful or not.

 

 
mIR.startIrLearning();

…

IRBlasterCallback mIrBlasterReadyCallback = new IRBlasterCallback() {
    @Override
    public void learnIRCompleted(int status) {
        Log.d(TAG,"Learn IR data");
        /* Check the result status and do something */
    }
    …
}

 

The result status shows ResultCode.SUCCESS if the IRBlaster learned the IR data successfully. If there are any problems, the result status shows the cause of the problem, such as failed, timeout, or aborted. See Result Codes to view a detailed description of each cause.

 

Regardless of the result status, the learning process should end in a maximum of 30 seconds. If the user wants to cancel the process within 30 seconds,stopIrLearning() should be used. Then the IR services call learnIRCompleted() with the result status of ResultCode.IRLEARNING_ABORTED. See the following figure for cancelation process of IR learning.

 

Sending Learned IR Data

The learning feature is only supported in some LG smartphones. Check if the device can use the learning feature by usingisLearningSupported(), or refer to Supported Devices.


The learned IR data is temporarily stored in the IR services during the current service session. We provide two ways to use the learned IR data. One is adding the learned IR data to a device as a function and then sending IR signals through the function. The other is storing the learned IR data in a variable and then sending directly IR signals.

Adding learned IR data to a device

Use addLearnedIRFunction() to add a new IR function, or editIRFunctionWithLearnedData() to modify an existing IR function.

 

 
learnedFunctionId = mIR.addLearnedIrFunction
                                (deviceId, learnedFunctionName);

 

or

 

 
mIR.editIrFunctionWithLearnedData(deviceId, learnedFunctionId);

 

Once the learned IR data is added to a device, it can be used as an IR function in that device. Therefore it is possible to send the learned IR data usingsendIR().

The following code block shows how to add an IR function with name of ‘3D View’ to a device and to send the learned IR data for 200 milliseconds.

 

 
learnedFunctionId = mIR.addLearnedIrFunction(deviceId, "3D View");
mIR.sendIR(new IRAction(deviceId, learnedFunctionId, 200));

Storing the learned IR data in a variable

Retrieve the last learned IR data using getLastLearnedData(). The retrieved data is an instance of LearnedIrData, and it has a unique ID and a byte array, which conforms LG’s learned IR data format. You can send IR signals for the learned IR data using sendIrWithLearnedData().

getLastLearnedData() retrieves only the latest learned IR data. If you do not store the data, the last learned IR data will be discarded when the device learns a new IR data.


The following sends the IR signals for the learned IR data.

 

 
LearnedIrData learnedIr = mIR.getLastLearnedData();
if(learnedIr != null && learnedIr.data != null) {
    int result = mIR.sendIrWithLearnedData
                         (learnedIr.Data, learnedIr.Id, 200, false);
    if(result != ResultCode.SUCCESS)
        Log.e("test", "cannot send the last learned IR data: "
                         + ResultCode.getString(result));
}

 

The first and the second arguments of sendIrWithLearnedData() are ID and data of learned IR data. They should be identical to those of the instance retrieved using getLastLearnedData(). If the ID and the data do not match, sendIrWithLearnedData() does not work properly. The third argument of sendIrWithLearnedData() is time duration in milliseconds, it is valid only if the last argument is false. If the last argument is true,sendIrWithLearnedData() ignores the third argument, and IR signals will be transmitted during the certain duration time.

 

Every device supporting LG QRemote SDK revision 4 or higher can send IR signals which has been learned by other device. A device can share its learned IR data with other devices through files or something. The other device can read the learned IR data and then send the signal usingsendIrWithLearnedData().

If you do not want to use any protocol to share data, copy and paste the ID and data of the learned IR data. Then you can use them as hardcoded data.

Creating a New Device

The learning feature is only supported in some LG smartphones. Check if the device can use the learning feature by using isLearningSupported(), or refer to Supported Devices.


Developers can provide a functionality to create a new device. The use of createDevice() makes it possible.

 

 
Device myDevice = mIR.createDevice("Universal", "MyBrand", "MyRemote");

 

It returns a Device instance, which can be handled as an existing device, for example ‘LG TV’. Adding IR functions to a newly created device is identical to adding IR functions to an existing device. See Sending Learned IR Data.

IR Function Labels

Table 1 and Table 2 map commonly used IR functions with their raw names (labels).

 

Some labels may not reflect real behavior of those IR functions. It is recommended to use key IDs as references to the real behavior of IR functions.

 

These key IDs and labels are defined in IRFunctionLabels. You can access labels using key IDs in your applications.

 

Table 1. IR Function Labels

Key ID

Labels

Supported Device

IR_FUNCTION_LABEL_POWER_[Device type]

POWER

All

IR_FUNCTION_LABEL_POWER_ON_[Device type]

POWER ON

All

IR_FUNCTION_LABEL_POWER_OFF_[Device type]

POWER OFF

All

IR_FUNCTION_LABEL_CHANNEL_UP_[Device type]

CHANNEL +

TVs, Set-top boxes

IR_FUNCTION_LABEL_CHANNEL_DOWN_[Device type]

CHANNEL -

TVs, Set-top boxes

IR_FUNCTION_LABEL_VOLUME_UP_[Device type]

VOLUME +

TVs, Set-top boxes, Audios, DVDs

IR_FUNCTION_LABEL_VOLUME_DOWN_[Device type]

VOLUME -

TVs, Set-top boxes, Audios, DVDs

IR_FUNCTION_LABEL_MUTE_[Device type]

MUTE

TVs, Set-top boxes, Audios

IR_FUNCTION_LABEL_DIGIT_1_[Device type]

DIGIT 1

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_2_[Device type]

DIGIT 2

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_3_[Device type]

DIGIT 3

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_4_[Device type]

DIGIT 4

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_5_[Device type]

DIGIT 5

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_6_[Device type]

DIGIT 6

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_7_[Device type]

DIGIT 7

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_8_[Device type]

DIGIT 8

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_9_[Device type]

DIGIT 9

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_DIGIT_0_[Device type]

DIGIT 0

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_LAST_[Device type]

LAST (CHANNEL, RECALL)

TVs, Set-top boxes

IR_FUNCTION_LABEL_DELIMITER_[Device type]

DELIMITER

TVs, Set-top boxes

IR_FUNCTION_LABEL_RED_[Device type]

RED

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_GREEN_[Device type]

GREEN

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_YELLOW_[Device type]

YELLOW

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_BLUE_[Device type]

BLUE

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_EXIT_[Device type]

EXIT

TVs, Set-top boxes

IR_FUNCTION_LABEL_BACK_[Device type]

BACK

TVs, Set-top boxes, DVDs, Projectors

IR_FUNCTION_LABEL_HOME_[Device type]

HOME

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_MENU_[Device type]

MENU

TVs, Set-top boxes, DVDs

IR_FUNCTION_LABEL_CURSOR_UP_[Device type]

CURSOR UP

TVs, Set-top boxes, DVDs, Projectors

IR_FUNCTION_LABEL_CURSOR_DOWN_[Device type]

CURSOR DOWN

TVs, Set-top boxes, DVDs, Projectors

IR_FUNCTION_LABEL_CURSOR_LEFT_[Device type]

CURSOR LEFT

TVs, Set-top boxes, DVDs, Projectors

IR_FUNCTION_LABEL_CURSOR_RIGHT_[Device type]

CURSOR RIGHT

TVs, Set-top boxes, DVDs, Projectors

IR_FUNCTION_LABEL_MENU_SELECT_[Device type]

MENU SELECT (OK)

TVs, Set-top boxes, DVDs, Projectors

IR_FUNCTION_LABEL_GUIDE_[Device type]

GUIDE

Set-top boxes

IR_FUNCTION_LABEL_DVR_MENU_[Device type]

PVR MENU

Set-top boxes

IR_FUNCTION_LABEL_QUICK_SKIP_[Device type]

QUICK SKIP

Set-top boxes

IR_FUNCTION_LABEL_PLAY_[Device type]

PLAY

Set-top boxes, DVDs, Audios

IR_FUNCTION_LABEL_STOP_[Device type]

STOP

Set-top boxes, DVDs, Audios

IR_FUNCTION_LABEL_PAUSE_[Device type]

PAUSE

Set-top boxes, DVDs, Audios

IR_FUNCTION_LABEL_REWIND_[Device type]

REWIND

Set-top boxes, DVDs, Audios

IR_FUNCTION_LABEL_FASTFORWARD_[Device type]

FAST FORWARD

Set-top boxes, DVDs, Audios

IR_FUNCTION_LABEL_RECORD_[Device type]

RECORD

Set-top boxes

IR_FUNCTION_LABEL_MODE_[Device type]

INPUT

Audios

IR_FUNCTION_LABEL_EJECT_[Device type]

OPEN/CLOSE | EJECT

DVDs, Audios

IR_FUNCTION_LABEL_SKIP_NEXT_[Device type]

SKIP FORWARD

DVDs, Audios

IR_FUNCTION_LABEL_SKIP_PREVIOUS_[Device type]

SKIP REVERSE

DVDs, Audios

IR_FUNCTION_LABEL_TITLE_[Device type]

TITLE (TOP) MENU

DVDs

IR_FUNCTION_LABEL_AUDIO_[Device type]

SAP

DVDs

IR_FUNCTION_LABEL_SUBTITLE_[Device type]

SUBTITLE

DVDs

IR_FUNCTION_LABEL_INPUT_[Device type]

INPUT

Projectors

IR_FUNCTION_LABEL_AUTO_FOCUS_[Device type]

Focus|Autofocus

Projectors

IR_FUNCTION_LABEL_KEYSTONE_[Device type]

Keystone

Projectors

IR_FUNCTION_LABEL_BLACKSCREEN_[Device type]

Blackscreen

Projectors

IR_FUNCTION_LABEL_SCREEN_SIZE_[Device type]

Screen Size

Projectors

IR_FUNCTION_LABEL_TEMP_UP_[Device type]

SKIP FORWARD

Air conditioners

IR_FUNCTION_LABEL_TEMP_DOWN_[Device type]

SKIP REVERSE

Air conditioners

IR_FUNCTION_LABEL_FAN_[Device type]

BLUE

Air conditioners

IR_FUNCTION_LABEL_FAN_UP_[Device type]

PAGE -

Air conditioners

IR_FUNCTION_LABEL_FAN_DOWN_[Device type]

FAVORITE

Air conditioners

IR_FUNCTION_LABEL_HORIZONTAL_SWING_[Device type]

PIP INPUT

Air conditioners

IR_FUNCTION_LABEL_VERTICAL_SWING_[Device type]

PIP ON

Air conditioners

IR_FUNCTION_LABEL_SLEEP_[Device type]

PIP MULTI

Air conditioners

IR_FUNCTION_LABEL_TURBO_[Device type]

PIP OFF

Air conditioners

IR_FUNCTION_LABEL_MODE1_[Device type]

DISPLAY (INFO | OSD)

Air conditioners

IR_FUNCTION_LABEL_MODE2_[Device type]

FORMAT (ASPECT)

Air conditioners

IR_FUNCTION_LABEL_MODE3_[Device type]

SAP

Air conditioners

IR_FUNCTION_LABEL_MODE4_[Device type]

SURROUND

Air conditioners

IR_FUNCTION_LABEL_MODE5_[Device type]

RANDOM

Air conditioners

 

For Japanese region, there are additional IR functions as follows:

 

Table 2. Additional IR Function Labels for Japanese Region

Key ID

Labels

Supported Device

IR_FUNCTION_LABEL_DIGIT_11_[Device type]

DIGIT 11

TVs

IR_FUNCTION_LABEL_DIGIT_12_[Device type]

DIGIT 12

TVs

IR_FUNCTION_LABEL_DTV_[Device type]

DTV

TVs

IR_FUNCTION_LABEL_BS_[Device type]

BROADCAST SAT

TVs

IR_FUNCTION_LABEL_CS_[Device type]

COM SAT

TVs

IR_FUNCTION_LABEL_CS2_[Device type]

COM SAT2

TVs

IR_FUNCTION_LABEL_JAPAN_BS_1_[Device type]

Broadcast Sat 1

TVs

IR_FUNCTION_LABEL_JAPAN_BS_2_[Device type]

Broadcast Sat 2

TVs

IR_FUNCTION_LABEL_JAPAN_BS_3_[Device type]

Broadcast Sat 3

TVs

IR_FUNCTION_LABEL_JAPAN_BS_4_[Device type]

Broadcast Sat 4

TVs

IR_FUNCTION_LABEL_JAPAN_BS_5_[Device type]

Broadcast Sat 5

TVs

IR_FUNCTION_LABEL_JAPAN_BS_6_[Device type]

Broadcast Sat 6

TVs

IR_FUNCTION_LABEL_JAPAN_BS_7_[Device type]

Broadcast Sat 7

TVs

IR_FUNCTION_LABEL_JAPAN_BS_8_[Device type]

Broadcast Sat 8

TVs

IR_FUNCTION_LABEL_JAPAN_BS_9_[Device type]

Broadcast Sat 9

TVs

IR_FUNCTION_LABEL_JAPAN_BS_10_[Device type]

Broadcast Sat 10

TVs

IR_FUNCTION_LABEL_JAPAN_BS_11_[Device type]

Broadcast Sat 11

TVs

IR_FUNCTION_LABEL_JAPAN_BS_12_[Device type]

Broadcast Sat 12

TVs

IR_FUNCTION_LABEL_JAPAN_CS_1_[Device type]

Comm Sat 1

TVs

IR_FUNCTION_LABEL_JAPAN_CS_2_[Device type]

Comm Sat 2

TVs

IR_FUNCTION_LABEL_JAPAN_CS_3_[Device type]

Comm Sat 3

TVs

IR_FUNCTION_LABEL_JAPAN_CS_4_[Device type]

Comm Sat 4

TVs

IR_FUNCTION_LABEL_JAPAN_CS_5_[Device type]

Comm Sat 5

TVs

IR_FUNCTION_LABEL_JAPAN_CS_6_[Device type]

Comm Sat 6

TVs

IR_FUNCTION_LABEL_JAPAN_CS_7_[Device type]

Comm Sat 7

TVs

IR_FUNCTION_LABEL_JAPAN_CS_8_[Device type]

Comm Sat 8

TVs

IR_FUNCTION_LABEL_JAPAN_CS_9_[Device type]

Comm Sat 9

TVs

IR_FUNCTION_LABEL_JAPAN_CS_10_[Device type]

Comm Sat 10

TVs

IR_FUNCTION_LABEL_JAPAN_CS_11_[Device type]

Comm Sat 11

TVs

IR_FUNCTION_LABEL_JAPAN_CS_12_[Device type]

Comm Sat 12

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_1_[Device type]

Comm Sat2 1

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_2_[Device type]

Comm Sat2 2

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_3_[Device type]

Comm Sat2 3

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_4_[Device type]

Comm Sat2 4

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_5_[Device type]

Comm Sat2 5

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_6_[Device type]

Comm Sat2 6

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_7_[Device type]

Comm Sat2 7

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_8_[Device type]

Comm Sat2 8

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_9_[Device type]

Comm Sat2 9

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_10_[Device type]

Comm Sat2 10

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_11_[Device type]

Comm Sat2 11

TVs

IR_FUNCTION_LABEL_JAPAN_CS2_12_[Device type]

Comm Sat2 12

TVs

 

Device type in Key IDs should be one of the following:

 

Table 3. Device Types

Device Type

Description

TV

TVs

STB

Set-top boxes (cable boxes)

Audio

Audio systems

DVD

DVD players

PROJECTOR

Projectors

AIRCON

Air conditioners

Result Codes

The LG QRemote APIs can return one of the return codes in Table 4.

 

Table 4. Result Codes Description

Result code

Description

SUCCESS (0)

Success

ERROR (1)

Undefined error happened (some general error, when none of below specific errors can be identified)

OUT_OF_MEMORY (7)

Out of memory in SDK

MAXIMUN_DEVICES_REACHED (8)

Maximum number of devices has been reached

SERVICES_NOT_READY (9)

IR services are not ready, wait for the initialization process

INVALID_AUTHENTICATION_KEY (10)

Authentication Key is invalid

ERROR_OPENING_DATABASE (11)

Learning IR data is failed

IRLEARNING_FAILED (12)

Error occurred while learning IR data

IRLEARNING_TIMEOUT (13)

Learning IR data has not completed in 30 seconds

IRLEARNING_ABORTED (14)

Learning process is canceled

MAXIMUN_LEARNCODES_REACHED (15)

Maximum number of learned functions has been reached

DELETE_DEVICE_ERROR (17)

There is no permission to delete the selected device

IR_PORT_DISABLED (18)

Remote control is unavailable by server policy

 

You can translate the result code into the string using the ResultCode.getString() method as follows:

 

 
ResultCode.getString(mIR.addDevice());
Navigation