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.
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 |
|---|---|---|
Gets the MRCU API Version. | No | |
Subscribes to the sensor data from the Magic Remote. | No | |
Cancels the subscription of the app or service that is currently subscribing. | No | |
Notifies the current status of the motion sensor on the remote control. | No | |
Changes the callback interval of the motion sensor to the desired value within the corresponding interval range. | No | |
Sets the callback interval. | No | |
Resets the quaternion sensor of the Magic Remote. | No | |
Subscribes to the sensor data from the Magic Remote. | No | |
Resets the Magic Remote's quaternion data. | No |
* This method is supported on webOS TV 24 or higher.
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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
version | Yes | 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 to 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 | Yes | Boolean | Flag that decides whether to subscribe or not.
Caution Do not set this to `false`. One-time calling does not work correctly at the moment. |
sensorType | Yes | 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:
|
Call returns
| Name | Required | Type | Description |
|---|---|---|---|
returnValue | Yes | Boolean | Flag that indicates success/failure of the request.
|
errorCode | No | Number | `errorCode` contains the error code if the method fails. The method returns `errorCode` only if it fails. |
errorText | No | String | `errorText` contains the error text if the method fails. The method returns `errorText` only if it fails. |
subscribed | No | Boolean | Flag that indicates whether the subscription is enabled or not.
|
Remarks
Subscription is disabled if this interface returns `false`. So, to keep the subscription enabled, subscribes to the sensor data again. This service provides `subscribe` for the subscription.
Error code 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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
interval | Yes | Number | Actual time interval (current time - previous time) |
No | Object | Coordinates information object | |
No | Object | Gyroscope sensor information object | |
No | Object | Accelerometer sensor information object | |
No | Object | Quaternion sensor information object | |
No | Object | Gravity sensor information object | |
No | Object | LinearAcceleration sensor information object | |
No | Object | Accelerometer (Uncalibrated) sensor information object | |
No | Object | Gyroscope (Uncalibrated) sensor information object | |
No | Object | Pedometer sensor information object | |
No | Object | Motion Detector information object |
If there are more than two request parameters, the parameter name to be requested to `sensorType` can 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 returns
{
"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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
errorCode | No | Number | `errorCode` contains the error code if the method fails. The method returns `errorCode` only if it fails. |
errorText | No | String | `errorText` contains the error text if the method fails. The method returns `errorText` only if it fails. |
If subscription of `getSensorEventData` is no longer necessary, subscription cancellation should be performed.
Error code 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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
isAlive | Yes | Boolean | Flag that indicates if the motion sensor is enabled or 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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
interval | Yes | Number | Current `getSensorEventData` subscribe callback interval (Unit:msec) |
minInterval | Yes | Number | Supported `getSensorEventData` subscribe minimum callback interval (Unit:msec) |
maxInterval | Yes | Number | Supported `getSensorEventData` subscribe maximum callback interval (Unit:msec) |
The initial callback interval is 1000 ms, but if you have a history of SDK usage, 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 supported range 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:10 ms, max:1000 ms).
Parameters
Name | Required | Type | Description |
|---|---|---|---|
interval | Yes | Number | 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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
errorCode | No | String | `errorCode` contains the error code if the method fails. The method returns `errorCode` only if it fails. |
errorText | No | String | `errorText` contains the error text if the method fails. The method returns `errorText` only if it fails. |
Even during subscription, the callback interval can be changed in real time using the `setSensorInterval` method.
Error code 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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
errorCode | No | String | `errorCode` contains the error code if the method fails. The method returns `errorCode` only if it fails. |
errorText | No | String | `errorText` contains the error text if the method fails. The method returns `errorText` only if it fails. |
Error code reference
| Error code | Error text | Error description |
|---|---|---|
1003 | See the Error code reference for more details. | See the Error code reference for more details. |
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
Subscribes to 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 |
|---|---|---|---|
callbackInterval | Yes | Number | Callback interval:
|
subscribe | Yes | Boolean | Flag that decides whether to subscribe or not.
Caution Do not set this to `false`, one-time calling does not work correctly now. |
On 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 `autoAlign` parameters 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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
errorCode | No | String | `errorCode` contains the error code if the method fails. The method returns `errorCode` only if it fails. See the Error code reference of this method for more details. |
errorText | No | String | `errorText` contains the error text if the method fails. The method returns `errorText` only if it fails. See the Error code reference of this method for more details. |
subscribed | No | Boolean | Flag that indicates whether the subscription is enabled or not.
|
Remarks
Subscription is disabled if this interface returns false. So, to keep the subscription, subscribes to the sensor data again. This service provides `subscribe` for the subscription.
Error code 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 | Yes | Boolean | Flag that indicates success/failure of the request.
|
deviceId | Yes | String | Magic Remote device ID |
Yes | Object | Coordinates information object | |
Yes | Object | Gyroscope sensor information object | |
Yes | Object | Accelerometer sensor information object | |
Yes | 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: " + inError.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 returns
{
"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 the Magic Remote wakes up from sleep mode.
Parameters
None
Call returns
| Name | Required | Type | Description |
|---|---|---|---|
returnValue | Yes | Boolean | Flag that indicates success/failure of the request.
|
errorCode | No | Number | `errorCode` contains the error code if the method fails. The method returns `errorCode` only if it fails. See the Error code reference of this method for more details. |
errorText | No | String | `errorText` contains the error text if the method fails. The method returns `errorText` only if it fails. See the Error code reference of this method for more details. |
Error code reference
Error code | Error text |
|---|---|
1001 | Magic Remote is not ready |
1003 | MotionEngine is not ready |
1004 | Device is no added to the MotionEngine |
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
},
});See also
Object
coordinate object
The object that holds the coordinates information from the Magic Remote.
{
"x": number,
"y": number
}Name | Required | Type | Description |
|---|---|---|---|
x | Yes | Number | X coordinate |
y | Yes | 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 | Yes | Number | X-axis value |
y | Yes | Number | Y-axis value |
z | Yes | Number | Z-axis value |
acceleration object
Object that holds the acceleration sensor information from the Magic Remote.
{
"x": number,
"y": number,
"z": number
}Name | Required | Type | Description |
|---|---|---|---|
x | Yes | Number | X-axis value |
y | Yes | Number | Y-axis value |
z | Yes | 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 | Yes | Number | x value |
q1 | Yes | Number | y value |
q2 | Yes | Number | z value |
q3 | Yes | 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 | Yes | Number | x bias value |
y_bias | Yes | Number | y bias value |
z_bias | Yes | Number | z bias value |
x_uncalib | Yes | Number | x uncalibrated value |
y_uncalib | Yes | Number | y uncalibrated value |
z_uncalib | Yes | 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 | Yes | Number | x bias value |
y_bias | Yes | Number | y bias value |
z_bias | Yes | Number | z bias value |
x_uncalib | Yes | Number | x uncalibrated value |
y_uncalib | Yes | Number | y uncalibrated value |
z_uncalib | Yes | 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 | Yes | Number | X-axis value |
y | Yes | Number | Y-axis value |
z | Yes | 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 | Yes | Number | x value |
y | Yes | Number | y value |
z | Yes | Number | z value |
w | Yes | Number | w value |
euler | Yes | 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 | Yes | Number | X-axis value |
y | Yes | Number | Y-axis value |
z | Yes | 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 | Yes | Number | If step is detected (1.0) or not (0.0) |
stepCount | Yes | Number | Number of steps taken by the user since the last reboot while the sensor was activated. |
stepDetectedLatency | Yes | 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 | Yes | 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. |