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

MethodDescriptionSupported 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/getSensorDataSubscribes the sensor data from the magic remote.No
sensor/resetQuaternionResets 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

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

NameRequiredTypeDescription
subscribeRequiredBooleanFlag 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.
sensorTypeRequiredStringAmong 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
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode contains the error code if the method fails. The method will return errorCode only if it fails.
errorTextOptionalStringerrorText contains the error text if the method fails. The method will return errorText only if it fails.
subscribedOptionalBooleanFlag 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 codeError textError description
1001, 1002, 1003, 1004, 1005, 1006See the Error Code Reference for more details.See the Error Code Reference for more details.

Subscription Returns

NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
intervalRequiredNumberActual time interval (current time - previous time)
coordinateOptionalObjectCoordinates information object
gyroscopeOptionalObjectGyroscope sensor information object
accelerationOptionalObjectAccelerometer sensor information object
gameRotationVectorOptionalObjectQuaternion sensor information object
gravityOptionalObjectGravity sensor information object
linearAccelerationOptionalObjectLinearAcceleration sensor information object
accelerometerUncalibratedOptionalObjectAccelerometer (Uncalibrated) sensor information object
gyroscopeUncalibratedOptionalObjectGyroscope (Uncalibrated) sensor information object
pedometerOptionalObjectPedometer sensor information object
motionDetectorOptionalObjectMotion 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

NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode contains the error code if the method fails. The method will return errorCode only if it fails.
errorTextOptionalStringerrorText 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 codeError textError description
1003See 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
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
isAliveRequiredBooleanFlag 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
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
intervalRequiredNumberCurrent getSensorEventData subscribe callback interval (Unit:msec)
minIntervalRequiredNumberSupported getSensorEventData subscribe minimum callback interval (Unit:msec)
maxIntervalRequiredNumberSupported 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

NameRequiredTypeDescription
intervalRequiredIntSet 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
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode contains the error code if the method fails. The method will return errorCode only if it fails.
errorTextOptionalStringerrorText 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 codeError textError description
1006See 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
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode contains the error code if the method fails. The method will return errorCode only if it fails.
errorTextOptionalStringerrorText contains the error text if the method fails. The method will return errorText only if it fails.

Error reference

Error codeError textError description
1003See 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 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

NameRequiredTypeDescription
callbackIntervalRequiredNumberCallback interval:
  • 1: 100 pkt/sec
  • 2: 50 pkt/sec
  • 3: 33 pkt/sec
  • 4: 10 pkt/sec
subscribeRequiredBooleanFlag 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

NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode 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.
errorTextOptionalStringerrorText 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.
subscribedOptionalBooleanFlag 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 CodeError Text
1001Magic remote is not ready
1002Undefined callback interval
1003Subscription add fail
1004invalid parameter

Subscription Returns

NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
deviceIdRequiredStringMagic remote device ID
coordinateRequiredObjectCoordinates information object
gyroscopeRequiredObjectGyroscope sensor information object
accelerationRequiredObjectAccelerometer sensor information object
quaternionRequiredObjectQuaternion 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

NameRequiredTypeDescription
returnValueRequiredBooleanFlag that indicates success/failure of the request.
  • true: Success
  • false: Failure
errorCodeOptionalNumbererrorCode 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.
errorTextOptionalStringerrorText 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 CodeError Text
1001Magic remote is not ready
1003MotionEngine is not ready
1004Device 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
}
NameRequiredTypeDescription
xRequirednumberX coordinate
yRequirednumberY coordinate

gyroscope object

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

{
  "x": number,
  "y": number,
  "z": number
}
NameRequiredTypeDescription
xRequirednumberX-axis value
yRequirednumberY-axis value
zRequirednumberZ-axis value

acceleration object

Object that holds the acceleration sensor information from magic remote.

{
  "x": number,
  "y": number,
  "z": number
}
NameRequiredTypeDescription
xRequirednumberX-axis value
yRequirednumberY-axis value
zRequirednumberZ-axis value

quaternion object

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

{
  "q0": number,
  "q1": number,
  "q2": number,
  "q3": number
}
NameRequiredTypeDescription
q0Requirednumberx value
q1Requirednumbery value
q2Requirednumberz value
q3Requirednumberw 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
 }
NameRequiredTypeDescription
x_biasRequirednumberx bias value
y_biasRequirednumbery bias value
z_biasRequirednumberz bias value
x_uncalibRequirednumberx uncalibrated value
y_uncalibRequirednumbery uncalibrated value
z_uncalibRequirednumberz 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
 }
NameRequiredTypeDescription
x_biasRequirednumberx bias value
y_biasRequirednumbery bias value
z_biasRequirednumberz bias value
x_uncalibRequirednumberx uncalibrated value
y_uncalibRequirednumbery uncalibrated value
z_uncalibRequirednumberz uncalibrated value

linearAcceleration object

The object that holds the LinearAcceleration sensor information.

{
  "x": number,
  "y": number,
  "z": number
}
NameRequiredTypeDescription
xRequirednumberX-axis value
yRequirednumberY-axis value
zRequirednumberZ-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
}
NameRequiredTypeDescription
xRequirednumberx value
yRequirednumbery value
zRequirednumberz value
wRequirednumberw value
eulerRequiredobjectPitch, roll, yaw value

gravity object

The object that holds the gravity sensor information.

{
  "x": number,
  "y": number,
  "z": number
}
NameRequiredTypeDescription
xRequirednumberX-axis value
yRequirednumberY-axis value
zRequirednumberZ-axis value

pedometer object

The object that holds the pedometer sensor information.

{
  "stepDetected": number,
  "stepCount": number,
  "stepDetectedLatency": number
}
NameRequiredTypeDescription
stepDetectedRequirednumberIf step is detected (1.0) or not (0.0)
stepCountRequirednumberNumber of steps taken by the user since the last reboot while the sensor was activated.
stepDetectedLatencyRequirednumberNumber 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,
}
NameRequiredTypeDescription
significationMotionRequirednumberThe 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 codeError textError description
1001Subscription add failThe subscription request method of the subscription API is incorrect.
1002Invalid parameterThe parameter name of the getSensorEvent API is entered incorrectly.
1003Magic remote is not readyAPI call is made in a magnetic remote sleep state. In this case, the magic remote should be made active.
1004Already add subscriptionA client that has already subscribed requests subscription again without cancelling.
1005Over subscription app/service numberThe number of subscription-requesting clients exceeds the maximum value.
1006Wrong callback intervalThe set interval is outside the allowed interval range.
No Headings