DeviceMotion API

This plugin provides access to the device's accelerometer. The accelerometer is a motion sensor that detects the change (delta) in movement relative to the current device orientation, in three dimensions along the x, y, and z axis.

Original documentation: Cordova Accelerometer.

Remark: Usage of cordova API needs http://tizen.org/privilege/filesystem.read privilege.

Since: 3.0

Table of Contents


Summary of Interfaces and Methods

Interface Method
AccelerometerManagerObject
Accelerometer
DOMString watchAcceleration (AccelerometerSuccessCallback onsuccess, ErrorCallback onerror, optional AccelerationOptions? options)
void clearWatch (DOMString watchID)
Acceleration
AccelerationOptions
AccelerometerSuccessCallback
void onsuccess (Acceleration acceleration)
ErrorCallback
void onerror (DOMException error)

1. Interfaces

1.1. AccelerometerManagerObject

The navigator.accelerometer object allows access to the functionality of the DeviceMotion API.
  [NoInterfaceObject] interface AccelerometerManagerObject {
    readonly attribute Accelerometer accelerometer;
  };
  Navigator implements AccelerometerManagerObject;

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

1.2. Accelerometer

The Accelerometer object captures device motion in the x, y, and z direction.
  [NoInterfaceObject] interface Accelerometer {
    void getCurrentAcceleration(AccelerometerSuccessCallback onsuccess, ErrorCallback onerror) raises(TypeError);
    DOMString watchAcceleration(AccelerometerSuccessCallback onsuccess, ErrorCallback onerror, optional AccelerationOptions? options)
                                raises(TypeError);
    void clearWatch(DOMString watchID) raises(TypeError);
  };

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Methods

getCurrentAcceleration
Gets the current acceleration along the x, y, and z axes.
void getCurrentAcceleration(AccelerometerSuccessCallback onsuccess, ErrorCallback onerror);

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Parameters:

  • onsuccess: The callback method to be invoked with current acceleration values.
  • onerror: The callback method called when errors occur.

Exceptions:

  • TypeError
    • if any of the input parameters contains an invalid value.

Code example:

function onSuccess(acceleration)
{
  console.log("Acceleration X: " + acceleration.x + "\n" +
              "Acceleration Y: " + acceleration.y + "\n" +
              "Acceleration Z: " + acceleration.z + "\n" +
              "Timestamp: " + acceleration.timestamp);
}

function onError()
{
  console.log("onError!");
}

navigator.accelerometer.getCurrentAcceleration(onSuccess, onError);

Output example:

Acceleration X: 0.00
Acceleration Y: 0.00
Acceleration Z: 9.82
Timestamp: 1456480118000
watchAcceleration
Gets the acceleration along the x, y, and z axes at a regular interval.
DOMString watchAcceleration(AccelerometerSuccessCallback onsuccess, ErrorCallback onerror, optional AccelerationOptions? options);

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Parameters:

  • onsuccess: The callback method to be invoked with current acceleration values.
  • onerror: The callback method called when errors occur.
  • options [optional] [nullable]: Specifies the interval of calling successcallback in milliseconds. If not provided, default value for frequency is 10000 (10 seconds).

Return value:

    DOMString: DOMString The watch id that must be passed to clearWatch to stop watching.

Exceptions:

  • TypeError
    • if any of the input parameters contains an invalid value.

Code example:

function onSuccess(acceleration)
{
  console.log("Acceleration X: " + acceleration.x + "\n" +
              "Acceleration Y: " + acceleration.y + "\n" +
              "Acceleration Z: " + acceleration.z + "\n" +
              "Timestamp: " + acceleration.timestamp);
  console.log("Please wait 3 seconds for the next measurement...");
}

function onError()
{
  console.log("onError!");
}

var options = {frequency: 3000};  /* Update every 3 seconds. */

var watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);

Output example:

Acceleration X: 0.00
Acceleration Y: 0.00
Acceleration Z: 9.82
Timestamp: 1456480118000
Please wait 3 seconds for the next measurement...
Acceleration X: 0.00
Acceleration Y: 0.00
Acceleration Z: 9.82
Timestamp: 1456480121000
Please wait 3 seconds for the next measurement...
(...)
clearWatch
Stop watching the Acceleration referenced by the watchID parameter.
void clearWatch(DOMString watchID);

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Parameters:

Exceptions:

  • TypeError
    • if any of the input parameters contains an invalid value.

Code example:

var counter = 0, watchID;

function onSuccess(acceleration)
{
  console.log("Acceleration X: " + acceleration.x + "\n" +
              "Acceleration Y: " + acceleration.y + "\n" +
              "Acceleration Z: " + acceleration.z + "\n" +
              "Timestamp: " + acceleration.timestamp);
  if (3 == ++counter)
  {
    navigator.accelerometer.clearWatch(watchID);
  }
}

function onError()
{
  console.log("onError!");
}

var options = {frequency: 30};  /* Update every 0.03 seconds. */

watchID = navigator.accelerometer.watchAcceleration(onSuccess, onError, options);

Output example:

Acceleration X: 0.00
Acceleration Y: 0.00
Acceleration Z: 9.82
Timestamp: 1456483774000
Acceleration X: 0.00
Acceleration Y: 0.00
Acceleration Z: 9.82
Timestamp: 1456483774030
Acceleration X: 0.00
Acceleration Y: 0.00
Acceleration Z: 9.82
Timestamp: 1456483774060

1.3. Acceleration

Contains Accelerometer data captured at a specific point in time. Acceleration values include the effect of gravity (9.81 m/s^2), so that when a device lies flat and facing up, x, y, and z values returned should be 0, 0, and 9.81.
  [NoInterfaceObject] interface Acceleration {
    readonly attribute double x;
    readonly attribute double y;
    readonly attribute double z;
    readonly attribute long timestamp;
  };

Since: 3.0

Privilege level: public

Privilege: http://tizen.org/privilege/filesystem.read

Attributes

  • readonly double x
    Amount of acceleration on the x-axis. (in m/s^2)

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • readonly double y
    Amount of acceleration on the y-axis. (in m/s^2)

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • readonly double z
    Amount of acceleration on the z-axis. (in m/s^2)

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

  • readonly long timestamp
    Creation timestamp in milliseconds.

    Since: 3.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/filesystem.read

1.4. AccelerationOptions

An optional parameter to customize the retrieval of accelerometer values.
  dictionary AccelerationOptions {
    long frequency;
  };

Since: 3.0

Dictionary members

long frequency
Interval defining how often to retrieve Acceleration in milliseconds.

Since: 3.0

1.5. AccelerometerSuccessCallback

The AccelerometerSuccessCallback interface provides a SuccessCallback for the getCurrentAcceleration and watchAcceleration methods.
  [Callback=FunctionOnly, NoInterfaceObject] interface AccelerometerSuccessCallback {
    void onsuccess(Acceleration acceleration);
  };

Since: 3.0

Methods

onsuccess
void onsuccess(Acceleration acceleration);

Since: 3.0

Parameters:

  • acceleration: The acceleration at a single moment in time.

1.6. ErrorCallback

Basic error callback.
  [Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback {
    void onerror(DOMException error);
  };

Since: 3.0

Methods

onerror
Success
void onerror(DOMException error);

Since: 3.0

Parameters:

  • error: Error object containing some information about the error.

2. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee that the DeviceMotion application runs on a device with the DeviceMotion feature declare the following feature requirements in the config file:

  • http://tizen.org/feature/sensor.accelerometer
  • For more information, see Application Filtering.

    3. Full WebIDL

    module DeviceMotion {
      dictionary AccelerationOptions {
        long frequency;
      };
      Navigator implements AccelerometerManagerObject;
      [NoInterfaceObject] interface AccelerometerManagerObject {
        readonly attribute Accelerometer accelerometer;
      };
      [NoInterfaceObject] interface Accelerometer {
        void getCurrentAcceleration(AccelerometerSuccessCallback onsuccess, ErrorCallback onerror) raises(TypeError);
        DOMString watchAcceleration(AccelerometerSuccessCallback onsuccess, ErrorCallback onerror, optional AccelerationOptions? options)
                                    raises(TypeError);
        void clearWatch(DOMString watchID) raises(TypeError);
      };
      [NoInterfaceObject] interface Acceleration {
        readonly attribute double x;
        readonly attribute double y;
        readonly attribute double z;
        readonly attribute long timestamp;
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface AccelerometerSuccessCallback {
        void onsuccess(Acceleration acceleration);
      };
      [Callback=FunctionOnly, NoInterfaceObject] interface ErrorCallback {
        void onerror(DOMException error);
      };
    };