Magic Remote

Service URI - luna://com.webos.service.mrcu

Provides methods related to the magic remote sensor. This is used to check the sensor data from the magic remote or to stop receiving sensor data from the magic remote.
This API includes methods for the Motion Sensor that provide cursor outputs and different types of motion data. For more information about the Motion Sensor, such as use cases and how to implement it in an app, see Motion Sensor Overview.

Caution

sensor/getSensorData and sensor/resetQuaternion are likely to be deprecated soon. Therefore, it is strongly recommended you do not use these methods.

Methods

Method	Description	Supported in Emulator
getAPIVersion^*	Gets the MRCU API Version.	No
sensor2/getSensorEventData^*	Subscribes to the sensor data from the Magic Remote.	No
sensor2/cancelSensorDataSubscribe^*	Cancels the subscription of the app or service that is currently subscribing.	No
sensor2/getSensorState^*	Notifies the current status of the motion sensor on the remote control.	No
sensor2/getSensorInterval^*	Changes the callback interval of the motion sensor to the desired value within the corresponding interval range.	No
sensor2/setSensorInterval^*	Sets the callback interval.	No
sensor2/resetQuaternion^*	Resets the quaternion sensor of the Magic Remote.	No
sensor/getSensorData	Subscribes the sensor data from the magic remote.	No
sensor/resetQuaternion	Resets the magic remote's quaternion data.	No

^* This method is supported only on webOS TV 24.

getAPIVersion

Description

Gets MRCU API version.
This method gives the version of the API provided by the MRCU service. API usability may change by API version, and implementation may vary. If there is a singularity, an explanation about the change will be added to this specification with version.

Parameters

None

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
version	Required	String	MRCU API Version.

Example

var handle = webOS.service.request("luna://com.webos.service.mrcu", {
  method: "getAPIVersion",
  parameters: {},
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    if (inResponse.returnValue === true) {
      return;
    }
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

{
  "returnValue": true,
  "version": "1.0"
}

sensor2/getSensorEventData

Description

Subscribes the sensor data from the magic remote.
The data includes point coordinates, gyroscope sensor, accelerometer sensor and quaternion value. You can get the sensor data by subscribing a callback function with specified intervals.

Parameters

Name	Required	Type	Description
subscribe	Required	Boolean	Flag that decides whether to subscribe or not. true: Subscribe false: Do not subscribe. Call the method only once. (Default) Caution Do not set this to false. One-time calling does not work correctly at the moment.
sensorType	Required	String	Among the parameters provided by the motion sensor, a desired parameter may be requested as a string. If there are multiple desired parameters, the parameter name can be transferred to string. Available parameters are: "coordinate" "gyroscope" "acceleration" "gameRotationVector" "gravity" "linearAcceleration" "accelerometerUncalibrated" "gyroscopeUncalibrated" "pedometer" "motionDetector" "all" (Including all of the above 10 parameters)

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
errorText	Optional	String	errorText contains the error text if the method fails. The method will return errorText only if it fails.
subscribed	Optional	Boolean	Flag that indicates whether the subscription is enabled or not. true: Enabled false: Disabled

Remarks

Subscription is disabled if this interface returns false. So, to keep the subscription enabled, subscribe the sensor data again. This service provides subscribe for the subscription.

Error reference

Error code	Error text	Error description
1001, 1002, 1003, 1004, 1005, 1006	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Subscription Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
interval	Required	Number	Actual time interval (current time - previous time)
coordinate	Optional	Object	Coordinates information object
gyroscope	Optional	Object	Gyroscope sensor information object
acceleration	Optional	Object	Accelerometer sensor information object
gameRotationVector	Optional	Object	Quaternion sensor information object
gravity	Optional	Object	Gravity sensor information object
linearAcceleration	Optional	Object	LinearAcceleration sensor information object
accelerometerUncalibrated	Optional	Object	Accelerometer (Uncalibrated) sensor information object
gyroscopeUncalibrated	Optional	Object	Gyroscope (Uncalibrated) sensor information object
pedometer	Optional	Object	Pedometer sensor information object
motionDetector	Optional	Object	Motion Detector information object

Note

If there are more than two request parameters, the parameter name to be requested to sensorTypecan be transferred including the delimiter or sent with the parameter name attached without the delimiter. For Example, even if sensorType is gyroscopeacceleter,gyroscope, acceleter, the API request results are the same.

Example

var subscriptionHandle = webOS.service.request(
  "luna://com.webos.service.mrcu",
  {
    method: "sensor2/getSensorEventData",
    parameters: { sensorType: "all", subscribe: true },
    onSuccess: function (inResponse) {
      if (typeof inResponse.subscribed !== "undefined") {
        if (!inResponse.subscribed) {
          console.log("Failed to subscribe");
        }
      }
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
    },
  }
);
 
// If you need to unsubscribe the data, use cancel() method as below
subscriptionHandle.cancel();

Return example

When subscription enabled

{
  "subscribed": true,
  "returnValue": true
}

Subscription return

{
  "returnValue": true,
  "gyroscopeUncalibrated": {
    "y_bias": 0.00045741553185507655,
    "z_bias": 0.0037106915842741728,
    "x_uncalib": -0.68176925182342529,
    "y_uncalib": -0.14487597346305847,
    "x_bias": 0.0029623473528772593,
    "z_uncalib": -0.12570120394229889
  },
  "coordinate": {
    "y": 1074,
    "x": 99
  },
  "motionDetector": {
    "significantMotion": 0
  },
  "interval": 995.0,
  "gravity": {
    "z": 9.7079868316650391,
    "y": -0.85266518592834473,
    "x": -0.16893911361694336
  },
  "linearAcceleration": {
    "z": 1.6079120635986328,
    "y": 0.98088634014129639,
    "x": -0.23738378286361694
  },
  "gyroscope": {
    "z": -0.12941189110279083,
    "y": -0.14533339440822601,
    "x": -0.68473160266876221
  },
  "pedometer": {
    "stepDetected": 0,
    "stepCount": 4,
    "stepDetectedLatency": 0
  },
  "gameRotationVector": {
    "z": 0.61527740955352783,
    "w": 0.78128117322921753,
    "y": -0.02904123067855835,
    "euler": {
      "pitch": 7.0074191093444824,
      "roll": -9.8386898040771484,
      "yaw": -77.046409606933594
    },
    "x": 0.10094617307186127
  },
  "accelerometer": {
    "z": 11.315898895263672,
    "y": 0.12822112441062927,
    "x": -0.4063228964805603
  },
  "accelerometerUncalibrated": {
    "y_bias": -0.082731291651725769,
    "z_bias": 0.066136360168457031,
    "x_uncalib": -0.31842881441116333,
    "y_uncalib": 0.045489832758903503,
    "x_bias": 0.087894082069396973,
    "z_uncalib": 11.382035255432129
  }
}

sensor2/cancelSensorDataSubscribe

Description

Cancels the subscription of the app or service that is currently subscribing (app/service termination state).

Parameters

None

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
errorText	Optional	String	errorText contains the error text if the method fails. The method will return errorText only if it fails.

Note

If subscription of getSensorEventData is no longer necessary, subscription cancellation should be performed.

Error reference

Error code	Error text	Error description
1003	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

var handle = webOS.service.request("luna://com.webos.service.mrcu", {
  method: "sensor2/cancelSensorDataSubscribe",
  parameters: {},
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

{
  "returnValue": true
}

sensor2/getSensorState

Description

Notifies the current status of the motion sensor on the remote control (whether getSensorEventData is available).

Parameters

None

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
isAlive	Required	Boolean	Flag that indicates if the motion sensor is enabled or disabled.. true: Enabled false: Disabled

Example

var handle = webOS.service.request("luna://com.webos.service.mrcu", {
  method: "sensor2/getSensorState",
  parameters: {},
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    if (inResponse.isAlive === true) {
      return;
    }
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

{
  "isAlive": true,
  "returnValue": true
}

sensor2/getSensorInterval

Description

Notifies the min/max value of the current sensor callback interval and the callback interval supported by the Motion Sensor.

Parameters

None

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
interval	Required	Number	Current getSensorEventData subscribe callback interval (Unit:msec)
minInterval	Required	Number	Supported getSensorEventData subscribe minimum callback interval (Unit:msec)
maxInterval	Required	Number	Supported getSensorEventData subscribe maximum callback interval (Unit:msec)

Note

The initial callback interval is 1000ms, but if you have a history of SDK use, the callback interval does not initialize even if you cancel the subscription, so it is necessary to check the callback interval before calling the setSensorInterval method.
A value should be set within the range of support for the callback interval.

Example

var handle = webOS.service.request("luna://com.webos.service.mrcu", {
  method: "sensor2/getSensorInterval",
  parameters: {},
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

{
  "minInterval": 10,
  "returnValue": true,
  "interval": 10,
  "maxInterval": 1000
}

sensor2/setSensorInterval

Description

Changes the callback interval of the motion sensor to the desired value within the corresponding interval range (min:10ms, max:1000ms).

Parameters

Name	Required	Type	Description
interval	Required	Int	Set the callback interval you want to change and enter it in the form of an integer in msec. The possible interval range is from 10 ms to 1000 ms.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
errorText	Optional	String	errorText contains the error text if the method fails. The method will return errorText only if it fails.

Note

Even during subscription, the callback interval can be changed in real time using thesetSensorInterval method.

Error reference

Error code	Error text	Error description
1006	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Example

var handle = webOS.service.request("luna://com.webos.service.mrcu", {
  method: "sensor2/setSensorInterval",
  parameters: { interval: 10 },
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

{
  "returnValue": true
}

sensor2/resetQuaternion

Description

Resets the quaternion sensor of the Magic Remote.
Sometimes you need to reset the sensor before the user action, such as when a game starts or magic remote wakes up from sleep mode.

Parameters

None

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method will return errorCode only if it fails.
errorText	Optional	String	errorText contains the error text if the method fails. The method will return errorText only if it fails.

Error reference

Error code	Error text	Error description
1003	See the Error Code Reference for more details.	See the Error Code Reference for more details.

Note

This is called a “recenter” function as it resets the user's heading. During the use of the Magic Remote, a user may lose the center and be misaligned. At the time, this function can reset the user's heading to the center.

Example

var handle = webOS.service.request("luna://com.webos.service.mrcu", {
  method: "sensor2/resetQuaternion",
  parameters: {},
  onSuccess: function (inResponse) {
    console.log("Result: " + JSON.stringify(inResponse));
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Return Example

{
  "returnValue": true
}

sensor/getSensorData

Description

Parameters

Name	Required	Type	Description
callbackInterval	Required	Number	Callback interval: 1: 100 pkt/sec 2: 50 pkt/sec 3: 33 pkt/sec 4: 10 pkt/sec
subscribe	Required	Boolean	Flag that decides whether to subscribe or not. true: Subscribe false: Do not subscribe. Call the method only once. (Default) Caution Do not set this to false, one-time calling does not work correctly now.

Note

In webOS TV 1.x, the sensor/getSensorData method requires more parameters, which are sleep and autoAlign. If you use the sensor/getSensorData method in webOS TV 1.x, set sleep and autoAlignparameters as below:

sleep: true
autoAlign: false

You can find out webOS TV version that user uses via getSystemInfo() method.

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Reference of this method for more details.
errorText	Optional	String	errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Reference of this method for more details.
subscribed	Optional	Boolean	Flag that indicates whether the subscription is enabled or not. true: Enabled false: Disabled

Remarks

Subscription is disabled if this interface returns false. So, to keep the subscription, subscribe the sensor data again. This service provides subscribe for the subscription.

Error reference

Error Code	Error Text
1001	Magic remote is not ready
1002	Undefined callback interval
1003	Subscription add fail
1004	invalid parameter

Subscription Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
deviceId	Required	String	Magic remote device ID
coordinate	Required	Object	Coordinates information object
gyroscope	Required	Object	Gyroscope sensor information object
acceleration	Required	Object	Accelerometer sensor information object
quaternion	Required	Object	Quaternion sensor information object

Example

var webOSTVVersion = "2.0.0";
// Get webOS TV version
var request = webOS.service.request(
  "luna://com.webos.service.tv.systemproperty",
  {
    method: "getSystemInfo",
    parameters: { keys: ["sdkVersion"] },
    onSuccess: function (inResponse) {
      webOSTVVersion = inResponse.sdkVersion;
      console.log("webOS TV Version: " + inResponse.sdkVersion);
      //To-Do something
    },
    onFailure: function (inError) {
      console.log("Failed to get webOS TV Version: " + inResponse.errorText);
      // To-Do something
    },
  }
);
 
// Set parameters by webOS TV version
var options;
if (webOSTVVersion == "2.0.0") {
  options.callbackInterval = 1;
  options.subscribe = true;
} else {
  options.callbackInterval = 1;
  options.subscribe = true;
  options.sleep = true;
  options.autoAlign = false;
}
 
// Call sensor/getSensorData with subscription
var subscriptionHandle = webOS.service.request(
  "luna://com.webos.service.mrcu",
  {
    method: "sensor/getSensorData",
    parameters: options,
    onSuccess: function (inResponse) {
      if (typeof inResponse.subscribed !== "undefined") {
        if (!inResponse.subscribed) {
          console.log("Failed to subscribe");
          return;
        }
      }
      console.log("Result: " + JSON.stringify(inResponse));
      // To-Do something
    },
    onFailure: function (inError) {
      console.log("[" + inError.errorCode + "]: " + inError.errorText);
      // To-Do something
    },
  }
);
 
// If you need to unsubscribe the data, use cancel() method as below
subscriptionHandle.cancel();

Return example

When subscription enabled

{
  "subscribed": true,
  "returnValue": true
}

Subscription return

{
  "deviceId": 0,
  "coordinate": {
    "x": 1101,
    "y": 518
  },
  "gyroscope": {
    "z": -1.682723,
    "x": 0.3041,
    "y": -0.582472
  },
  "acceleration": {
    "z": 12.035406,
    "x": 9.713932,
    "y": 5.446675
  },
  "returnValue": true,
  "quaternion": {
    "q0": 0.042376,
    "q1": 0.088355,
    "q2": 0.937461,
    "q3": 0.334014
  }
}

sensor/resetQuaternion

Description

Resets the quaternion sensor of the magic remote.
Sometimes you need to reset the sensor before the user action, such as when a game starts or magic remote wakes up from sleep mode.

Parameters

None

Call returns

Name	Required	Type	Description
returnValue	Required	Boolean	Flag that indicates success/failure of the request. true: Success false: Failure
errorCode	Optional	Number	errorCode contains the error code if the method fails. The method will return errorCode only if it fails. See the Error Reference of this method for more details.
errorText	Optional	String	errorText contains the error text if the method fails. The method will return errorText only if it fails. See the Error Reference of this method for more details.

Error reference

Error Code	Error Text
1001	Magic remote is not ready
1003	MotionEngine is not ready
1004	Device is no added to the MotionEngine

Note

MotionEngine calculates numeric data from the sensor data of Magic Remote.

Example

var request = webOS.service.request("luna://com.webos.service.mrcu", {
  method: "sensor/resetQuaternion",
  onSuccess: function (inResponse) {
    console.log("Succeeded to reset the quaternion sensor");
    // To-Do something
  },
  onFailure: function (inError) {
    console.log("[" + inError.errorCode + "]: " + inError.errorText);
    // To-Do something
  },
});

Object

coordinate object

The object that holds the coordinates information from the magic remote.

{
  "x": number,
  "y": number
}

Name	Required	Type	Description
x	Required	number	X coordinate
y	Required	number	Y coordinate

gyroscope object

The object that holds the gyroscope sensor information from the magic remote.

{
  "x": number,
  "y": number,
  "z": number
}

Name	Required	Type	Description
x	Required	number	X-axis value
y	Required	number	Y-axis value
z	Required	number	Z-axis value

acceleration object

Object that holds the acceleration sensor information from magic remote.

{
  "x": number,
  "y": number,
  "z": number
}

Name	Required	Type	Description
x	Required	number	X-axis value
y	Required	number	Y-axis value
z	Required	number	Z-axis value

quaternion object

The object that holds the quaternion sensor information from the magic remote.

{
  "q0": number,
  "q1": number,
  "q2": number,
  "q3": number
}

Name	Required	Type	Description
q0	Required	number	x value
q1	Required	number	y value
q2	Required	number	z value
q3	Required	number	w value

gyroscopeUncalibrated object

The object that holds the Gyroscope(Uncalibrated) sensor information.

{  
    "x_bias": number,
    "y_bias": number,
    "z_bias": number,
    "x_uncalib": number,
    "y_uncalib": number,   
    "z_uncalib": number
 }

Name	Required	Type	Description
x_bias	Required	number	x bias value
y_bias	Required	number	y bias value
z_bias	Required	number	z bias value
x_uncalib	Required	number	x uncalibrated value
y_uncalib	Required	number	y uncalibrated value
z_uncalib	Required	number	z uncalibrated value

accelerometerUncalibrated object

The object that holds the accelerometer(Uncalibrated) sensor information.

{  
    "x_bias": number,
    "y_bias": number,
    "z_bias": number,
    "x_uncalib": number,
    "y_uncalib": number,   
    "z_uncalib": number
 }

Name	Required	Type	Description
x_bias	Required	number	x bias value
y_bias	Required	number	y bias value
z_bias	Required	number	z bias value
x_uncalib	Required	number	x uncalibrated value
y_uncalib	Required	number	y uncalibrated value
z_uncalib	Required	number	z uncalibrated value

linearAcceleration object

The object that holds the LinearAcceleration sensor information.

{
  "x": number,
  "y": number,
  "z": number
}

Name	Required	Type	Description
x	Required	number	X-axis value
y	Required	number	Y-axis value
z	Required	number	Z-axis value

gameRotationVector object

The object that holds the Quaternion sensor information object. It is an object having the same nature as the quotient value.

{
  "x": number,
  "y": number,
  "z": number,
  "w": number,
  "euler": object
}

Name	Required	Type	Description
x	Required	number	x value
y	Required	number	y value
z	Required	number	z value
w	Required	number	w value
euler	Required	object	Pitch, roll, yaw value

gravity object

The object that holds the gravity sensor information.

{
  "x": number,
  "y": number,
  "z": number
}

Name	Required	Type	Description
x	Required	number	X-axis value
y	Required	number	Y-axis value
z	Required	number	Z-axis value

pedometer object

The object that holds the pedometer sensor information.

{
  "stepDetected": number,
  "stepCount": number,
  "stepDetectedLatency": number
}

Name	Required	Type	Description
stepDetected	Required	number	If step is detected (1.0) or not (0.0)
stepCount	Required	number	Number of steps taken by the user since the last reboot while the sensor was activated.
stepDetectedLatency	Required	number	Number of samples in the past where the peak of the step was detected.

motionDetector object

The object that holds the Motion Detector information.

{
  "significationMotion": number,
}

Name	Required	Type	Description
significationMotion	Required	number	The detector outputs a value of 1.0 when a motion is detected and reset itself immediately after the event is output.

Error code reference

Error code	Error text	Error description
1001	Subscription add fail	The subscription request method of the subscription API is incorrect.
1002	Invalid parameter	The parameter name of the getSensorEvent API is entered incorrectly.
1003	Magic remote is not ready	API call is made in a magnetic remote sleep state. In this case, the magic remote should be made active.
1004	Already add subscription	A client that has already subscribed requests subscription again without cancelling.
1005	Over subscription app/service number	The number of subscription-requesting clients exceeds the maximum value.
1006	Wrong callback interval	The set interval is outside the allowed interval range.

No Headings

webOS News

LG Electronics Announces Call for Participants for the LG webOS Hackathon 2024

LG Smart TVs Unlock Limitless Entertainment and Personal Growth With New Apps

Magic Remote

getAPIVersion

sensor2/getSensorEventData

sensor2/cancelSensorDataSubscribe

sensor2/getSensorState

sensor2/getSensorInterval

sensor2/setSensorInterval

sensor2/resetQuaternion

sensor/getSensorData

sensor/resetQuaternion

Object

coordinate object

gyroscope object

acceleration object

quaternion object

gyroscopeUncalibrated object

accelerometerUncalibrated object

linearAcceleration object

gameRotationVector object

gravity object

pedometer object

motionDetector object

Error code reference