Samsung Electronics logo

Samsung Web API: Motion

© 2014 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

This API defines interfaces and methods to manage motion data from various sensors on the device.

The following motion functionalities are provided:

  • Start and stop notification of the motion data change.
  • Get current motion data.

Table of Contents

Summary of Interfaces and Methods

Interface Method
MotionManagerObject
MotionManager void getMotionInfo(MotionType type, MotionInfoSuccessCallback successCallback, ErrorCallback? errorCallback)
void start(MotionType type, MotionInfoSuccessCallback? successCallback)
void stop(MotionType type)
void setAccumulativePedometerListener(MotionInfoSuccessCallback changeCallback)
void unsetAccumulativePedometerListener()
MotionInfo
MotionPedometerInfo
MotionAccumulativePedometerInfo
MotionInfoSuccessCallback void onsuccess(MotionInfo? motionInfo)

1. Type Definitions

1.1. MotionType

Supported motion types. 

    enum MotionType { "PEDOMETER", "WRIST_UP" };

The motion types defined by this enumerator are:

  • PEDOMETER - Pedometer data
  • WRIST_UP - Wrist up gesture

1.2. PedometerStepStatus

Step status of the pedometer user. 

    enum PedometerStepStatus { "NOT_MOVING", "WALKING", "RUNNING" };

2. Interfaces

2.1. MotionManagerObject

The MotionManagerObject interface defines what is instantiated by the WebAPIs object. The webapis.motion object allows access to the motion data. 

    [NoInterfaceObject] interface MotionManagerObject {
        readonly attribute MotionManager motion;
    };
    WebAPIs  implements MotionManagerObject;

2.2. MotionManager

The MotionManagerObject interface provides methods to access motion data. 

    [NoInterfaceObject] interface MotionManager {

        void getMotionInfo(MotionType type, MotionInfoSuccessCallback successCallback,
                                optional ErrorCallback? errorCallback );

        void start(MotionType type, optional MotionInfoSuccessCallback? successCallback);

        void stop(MotionType type);

        void setAccumulativePedometerListener(MotionInfoSuccessCallback changeCallback);

        void unsetAccumulativePedometerListener(); 
    };

METHODS

getMotionInfo

Gets the current motion data for the requested type.

Signature
void getMotionInfo(MotionType type, MotionInfoSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Note that the getMotionInfo method only supports the PEDOMETER type. When MotionType is not equal to PEDOMETER, TypeMismtatchError is thrown.

The start method should be called before calling the getMotionInfo method for turning on the pedometer sensor.

The ErrorCallback is launched with these error types:

  • ServiceNotAvailableError : If the getMotionInfo method is called without calling the start method with PEDOMETER.
Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: MotionType.
    • Description: Motion type to read data for
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MotionInfoSuccessCallback.
    • Description: Callback method to be invoked when the motion data has been read
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Callback method to be invoked when an error occurs
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type UnknownError, if registering the success callback fails because of an unknown error.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function onsuccessCB(pedometerInfo) {
                console.log("Step status : " + pedometerInfo.stepStatus);
                console.log("Cumulative total step count : " + pedometerInfo.cumulativeTotalStepCount);
 } 

 function onerrorCB(error) {
                console.log("Error occurs");
 } 

 webapis.motion.getMotionInfo("PEDOMETER", onsuccessCB, onerrorCB);

start

Starts and registers a change listener to be called when the motion data for a given motion type changes.

Signature
void start(MotionType type, optional MotionInfoSuccessCallback? successCallback);
Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: MotionType.
    • Description: The motion type to register a listener for
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: MotionInfoSuccessCallback.
    • Description: Callback method to be invoked when the motion data changes
      Note that the listener is not called for the successful start of a motion sensor
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type UnknownError, if registering the listener fails because of an unknown error.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function onchangedCB(pedometerInfo) {
                console.log("Step status : " + pedometerInfo.stepStatus);
                console.log("Cumulative total step count : " + pedometerInfo.cumulativeTotalStepCount);
 } 

 webapis.motion.start("PEDOMETER", onchangedCB);

stop

Stops and unregisters a previously registered listener for changed motion data.

Signature
void stop(MotionType type);
Parameters
  • type
    • Optional: No.
    • Nullable: No.
    • Type: MotionType.
    • Description: Motion type to unregister the listener for
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type UnknownError, if unregistering the listener fails because of an unknown error.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 webapis.motion.stop("PEDOMETER");

setAccumulativePedometerListener

Registers a listener to be called when the accumulative pedometer data changes.

Signature
void setAccumulativePedometerListener(MotionInfoSuccessCallback changeCallback);

Note that setAccumulativePedometerListener method don't need to call the start method of a motion sensor

Parameters
  • changeCallback
    • Optional: No.
    • Nullable: No.
    • Type: MotionInfoSuccessCallback.
    • Description: Callback method to be invoked when the accumulative pedometer data changes. Callback will be invoked with MotionAccumulativePedometerInfo as argument.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type UnknownError, if registering the listener fails because of an unknown error.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 function onchangedCB(pedometerInfo) {
        console.log("Step status : " + pedometerInfo.stepStatus);
        console.log("Accumulative total step count : " + pedometerInfo.accumulativeTotalStepCount);
 } 

 webapis.motion.setAccumulativePedometerListener(onchangedCB);

unsetAccumulativePedometerListener

Unregisters a previously registered listener for the accumulative pedometer data.

Signature
void unsetAccumulativePedometerListener();
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type UnknownError, if unregistering the listener fails because of an unknown error.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 webapis.motion.unsetAccumulativePedometerListener();

2.3. MotionInfo

The MotionInfo interface is a common abstract interface used by different types of motion information objects. 

    [NoInterfaceObject] interface MotionInfo {
     };

2.4. MotionPedometerInfo

The MotionPedometerInfo interface represents pedometer motion data. 

    [NoInterfaceObject] interface MotionPedometerInfo : MotionInfo {

        readonly attribute PedometerStepStatus stepStatus;

        readonly attribute double speed;

        readonly attribute double walkingFrequency;

        readonly attribute double cumulativeDistance;

        readonly attribute double cumulativeCalorie;

        readonly attribute double cumulativeTotalStepCount;

        readonly attribute double cumulativeWalkStepCount;

        readonly attribute double cumulativeRunStepCount;
    };

ATTRIBUTES

readonly PedometerStepStatus stepStatus

An attribute to indicate the status of current steps.

This attribute is read-only.

readonly double speed

An attribute to indicate the current speed in km/h.

This attribute is read-only.

readonly double walkingFrequency

An attribute to indicate the step count per second.

This attribute is read-only.

readonly double cumulativeDistance

An attribute to indicate the cumulative distance traveled since the last start method call in meters.

This attribute is read-only.

readonly double cumulativeCalorie

An attribute to indicate the cumulative calories burned since the last start method call in kcal.

This attribute is read-only.

readonly double cumulativeTotalStepCount

An attribute to indicate the cumulative step count of a walk and the run since the last start method call. The value is the sum of all below step counts.

This attribute is read-only.

readonly double cumulativeWalkStepCount

An attribute to indicate the cumulative walk step count since the last start method call.

This attribute is read-only.

readonly double cumulativeRunStepCount

An attribute to indicate the cumulative run step count since the last start method call.

This attribute is read-only.

2.5. MotionAccumulativePedometerInfo

The MotionAccumulativePedometerInfo interface represents pedometer motion data since the device booing. 

    [NoInterfaceObject] interface MotionAccumulativePedometerInfo : MotionInfo {

        readonly attribute PedometerStepStatus stepStatus;

        readonly attribute double speed;

        readonly attribute double walkingFrequency;

        readonly attribute double accumulativeDistance;

        readonly attribute double accumulativeCalorie;

        readonly attribute double accumulativeTotalStepCount;

        readonly attribute double accumulativeWalkStepCount;

        readonly attribute double accumulativeRunStepCount;
    };

ATTRIBUTES

readonly PedometerStepStatus stepStatus

An attribute to indicate the status of current steps.

This attribute is read-only.

readonly double speed

An attribute to indicate the current speed in km/h.

This attribute is read-only.

readonly double walkingFrequency

An attribute to indicate the step count per second.

This attribute is read-only.

readonly double accumulativeDistance

An attribute to indicate the accumulative distance traveled since the device booting in meters.

This attribute is read-only.

readonly double accumulativeCalorie

An attribute to indicate the accumulative calories burned since the device booting in kcal.

This attribute is read-only.

readonly double accumulativeTotalStepCount

An attribute to indicate the accumulative step count of a walk and the run since the device booting. The value is the sum of accumulativeWalkStepCount and accumulativeRunStepCount.

This attribute is read-only.

readonly double accumulativeWalkStepCount

An attribute to indicate the accumulative walk step count since the device booting.

This attribute is read-only.

readonly double accumulativeRunStepCount

An attribute to indicate the accumulative run step count since the device booting.

This attribute is read-only.

2.6. MotionInfoSuccessCallback

The MotionInfoSuccessCallback interface is a callback interface that is invoked when the motion data has changed. For example, see MotionManager interface 

    [Callback=FunctionOnly, NoInterfaceObject] interface MotionInfoSuccessCallback {
        void onsuccess(optional MotionInfo? motionInfo);
    };

METHODS

onsuccess

Called when the motion data has changed.

Signature
void onsuccess(optional MotionInfo? motionInfo);
Parameters
  • motionInfo
    • Optional: Yes.
    • Nullable: Yes.
    • Type: MotionInfo.
    • Description: The current motion data. Note that null is passed for the WRIST_UP type.

3. Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml. For each URL, the list of functions covered is provided.

http://developer.samsung.com/tizen/feature/pedometer

To guarantee the running of this application on a device with pedometer, define the following requirements in the config file:

http://developer.samsung.com/tizen/feature/wrist_up

To guarantee the running of this application on a device with wrist up, define the following requirements in the config file:

4. Full WebIDL 

module Motion {

    enum MotionType { "PEDOMETER", "WRIST_UP" };

    enum PedometerStepStatus { "NOT_MOVING", "WALKING", "RUNNING" };

    [NoInterfaceObject] interface MotionManagerObject {
        readonly attribute MotionManager motion;
    };
    WebAPIs  implements MotionManagerObject;

    [NoInterfaceObject] interface MotionManager {

        void getMotionInfo(MotionType type, MotionInfoSuccessCallback successCallback,
                                optional ErrorCallback? errorCallback );

        void start(MotionType type, optional MotionInfoSuccessCallback? successCallback);

        void stop(MotionType type);

        void setAccumulativePedometerListener(MotionInfoSuccessCallback changeCallback);

        void unsetAccumulativePedometerListener(); 
    };

    [NoInterfaceObject] interface MotionInfo {
     };

    [NoInterfaceObject] interface MotionPedometerInfo : MotionInfo {

        readonly attribute PedometerStepStatus stepStatus;

        readonly attribute double speed;

        readonly attribute double walkingFrequency;

        readonly attribute double cumulativeDistance;

        readonly attribute double cumulativeCalorie;

        readonly attribute double cumulativeTotalStepCount;

        readonly attribute double cumulativeWalkStepCount;

        readonly attribute double cumulativeRunStepCount;
    };

    [NoInterfaceObject] interface MotionAccumulativePedometerInfo : MotionInfo {

        readonly attribute PedometerStepStatus stepStatus;

        readonly attribute double speed;

        readonly attribute double walkingFrequency;

        readonly attribute double accumulativeDistance;

        readonly attribute double accumulativeCalorie;

        readonly attribute double accumulativeTotalStepCount;

        readonly attribute double accumulativeWalkStepCount;

        readonly attribute double accumulativeRunStepCount;
    };

    [Callback=FunctionOnly, NoInterfaceObject] interface MotionInfoSuccessCallback {
        void onsuccess(optional MotionInfo? motionInfo);
    };
};