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 to the sensor data from the Magic Remote.

No

sensor/resetQuaternion

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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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

NameRequiredTypeDescription
subscribe
Yes
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
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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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.
  • true: Enabled
  • false: Disabled

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 codeError textError 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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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
Note

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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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.
Note

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

Error code reference

Error codeError textError 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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
isAlive
Yes
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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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)
Note
  • 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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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.
Note

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

Error code reference

Error codeError textError 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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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 codeError textError 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

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

NameRequiredTypeDescription
callbackInterval
Yes
Number
Callback interval:
  • 1: 100 pkt/sec
  • 2: 50 pkt/sec
  • 3: 33 pkt/sec
  • 4: 10 pkt/sec
subscribe
Yes
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

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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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.
  • true: Enabled
  • false: Disabled

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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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

NameRequiredTypeDescription
returnValue
Yes
Boolean
Flag that indicates success/failure of the request.
  • true: Success
  • false: Failure
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

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
  },
});

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.

No Headings