Sensor

Overview

The Sensors extension is used to retrieve the raw data values of the specified sensors (accelerometer, tilt angle, device orientation, motion, eCompass, magnetometer, gyroscope, ambient light, proximity, proximity long range, pressure, temperature, humidity, gravity, linear acceleration, rotation, orientation etc.) from the device. To use this, you have to first call makeSensorByType to get an instance of that sensor. Note: If the value of proximitySensorType property is different then user need to set the right proximitySensorType property value before calling makeSensorByType for getting an instance of that sensor. Then you can use the start and stop methods on that instance.

Enabling the API

There are two methods of enabling the Sensor API:

• Include all ebapi modules
• Include only the required API modules

For either of these methods, you'll need to include files from the /Enterprise Browser/JavaScript Files/Enterprise Browser directory on the computer that you installed the Enterprise Browser.

Include all JS API modules

To include all JS APIs, copy the ebapi-modules.js file to a location accessible by the app's files and include a reference to the JavaScript file in the app's HTML. For instance, to include the modules file in the app's index.html, copy the file to the same directory as that index.html and add the following line to the HTML's HEAD section:

<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

Note: that the pathing for this file is relative to the current page.

This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion.

Include only the required modules

To include single APIs, you must first include the ebapi.js in your HTML as well as the API file you want to use. For instance, to use the Sensor API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML.

<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.sensor.js"></script>

The ebapi.js file is necessary for all single API inclusions.

Methods

getAllProperties()

This method will return all of object/value pairs for the propertyNames of the API class.

Parameters

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• : STRING

Returns

Synchronous Return:

• HASH : Map of all available properties
  • : STRING

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Instance Method: This method can be accessed via an instance object of this class:
  • myObject.getAllProperties()

getProperties(ARRAY arrayofNames)

This method will return a set of object/value pairs for the list of the propertyName that is passed in. The propertyNames must be a valid property of the API class.

Parameters

• arrayofNames : ARRAY

  List of properties I want to know about

• Object : STRING

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• : STRING

Returns

Synchronous Return:

• HASH : Map of properties I want to know about
  • : STRING

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Instance Method: This method can be accessed via an instance object of this class:
  • myObject.getProperties(ARRAY arrayofNames)

getProperty(STRING propertyName)

This method will return the value of the propertyName that is passed in. The propertyName must be a valid property of the API class.

Parameters

• propertyName : STRING

  The property to return info about.

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: STRING

Returns

Synchronous Return:

• STRING : The property to return info about.

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Instance Method: This method can be accessed via an instance object of this class:
  • myObject.getProperty(STRING propertyName)

makeSensorByType(STRING type)

Return the new sensor object by type.

Parameters

• type : STRING

  Sensor type. Use the appropriate constants to get the sensor type. In the case of accelerometer use SENSOR_TYPE_ACCELEROMETER.

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: SELF_INSTANCE

Returns

Synchronous Return:

• SELF_INSTANCE : Returns a sensor object for the sensor type passed as parameter. You can use the type field along with the Rho.Sensor Constants to see what type of sensor is returned.

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Class Method: This method can only be accessed via the API class object.
  • EB.Sensor.makeSensorByType(STRING type)

readData()

Read current sensor data from the sensor object retrieved by using makeSensorByType.

Parameters

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

Returns

Synchronous Return:

• HASH : Current sensor data - format is the same with callback specified for start method.

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Instance Method: This method can be accessed via an instance object of this class:
  • myObject.readData()

setProperties(HASH propertyMap)

This method will set the values of a list of properties for the API class. The propertyName must be a valid property for the class and must also not be read only.

Parameters

• propertyMap : HASH

  Map of properties I want to set

• Object : STRING

• callback : CallBackHandler

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Instance Method: This method can be accessed via an instance object of this class:
  • myObject.setProperties(HASH propertyMap)

setProperty(STRING propertyName, STRING propertyValue)

This method will set the value of a property for the API class. The propertyName must be a valid property for the class and must also not be read only.

Parameters

• propertyName : STRING

  The one property name that I want to set

• propertyValue : STRING

  The one property value that I want to set

• callback : CallBackHandler

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Instance Method: This method can be accessed via an instance object of this class:
  • myObject.setProperty(STRING propertyName, STRING propertyValue)

start()

This enables the sensor data retrieval. Call start on the instance returned from the makeSensorByType.

Parameters

• callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

• status : STRING

  Status: ok, error.

• message : STRING

  Only if status=error, contain error message.

• accelerometer_x : FLOAT

  X co-ordinate value of the Accelerometer sensor in SI units (m/s^2)

• accelerometer_y : FLOAT

  Y co-ordinate value of the Accelerometer sensor in SI units (m/s^2)

• accelerometer_z : FLOAT

  Z co-ordinate value of the Accelerometer sensor in SI units (m/s^2)

• tiltangle_x : FLOAT

  X co-ordinate value of the tiltangle sensor in degrees units.

• tiltangle_y : FLOAT

  Y co-ordinate value of the tiltangle sensor in degrees units.

• tiltangle_z : FLOAT

  Z co-ordinate value of the tiltangle sensor in degrees units.

• deviceorientation_value : STRING

  The values of the Orientation sensor. Possible values include Portrait Down, Portrait Up, Landscape Left, Landscape Right, Face Up, Face Down. Applicable only for Symbol Windows Mobile/CE devices with Sensor support.

• motion_value : STRING

  Value from the Motion sensor.

• ecompass_value : STRING

  Value from the E-Compass sensor.

• magnetometer_x : FLOAT

  X value of the magnetometer sensor in micro-Tesla (uT) units.

• magnetometer_y : FLOAT

  Y value of the magnetometer sensor in micro-Tesla (uT) units.

• magnetometer_z : FLOAT

  Z value of the magnetometer sensor in micro-Tesla (uT) units.

• gyroscope_x : FLOAT

  X co-ordinate value of the gyroscope sensor in radians/second.

• gyroscope_y : FLOAT

  X co-ordinate value of the gyroscope sensor in radians/second.

• gyroscope_z : FLOAT

  X co-ordinate value of the gyroscope sensor in radians/second.

• ambientlight_value : STRING

  Value of the ambient Light sensor in SI lux units.

• proximity_value : STRING

  Value of the proximity sensor in centimeters.

• proximitylongrange_value : STRING

  Value of the proximitylongrange sensor.

• pressure_value : STRING

  Value of the pressure sensor in hPa (millibar) units.

• temperature_value : STRING

  Value of the temperature sensor in degree Celsius units.

• humidity_value : STRING

  Value of the humidity sensor as a percentage.

• gravity_x : FLOAT

  X co-ordinate value of the gravity sensor in SI units (m/s^2)

• gravity_y : FLOAT

  Y co-ordinate value of the gravity sensor in SI units (m/s^2)

• gravity_z : FLOAT

  Z co-ordinate value of the gravity sensor in SI units (m/s^2)

• linearacceleration_x : FLOAT

  X co-ordinate value of the linear acceleration sensor in SI units (m/s^2)

• linearacceleration_y : FLOAT

  Y co-ordinate value of the linear acceleration sensor in SI units (m/s^2)

• linearacceleration_z : FLOAT

  Z co-ordinate value of the linear acceleration sensor in SI units (m/s^2)

• rotation_x : FLOAT

  X co-ordinate value of the rotation sensor as a combination of an angle and an axis.

• rotation_y : FLOAT

  Y co-ordinate value of the rotation sensor as a combination of an angle and an axis.

• rotation_z : FLOAT

  Z co-ordinate value of the rotation sensor as a combination of an angle and an axis.

• orientation_x : FLOAT

  X co-ordinate value of the orientation sensor in degrees units.

• orientation_y : FLOAT

  Y co-ordinate value of the orientation sensor in degrees units.

• orientation_z : FLOAT

  Z co-ordinate value of the orientation sensor in degrees units.

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Instance Method: This method can be accessed via an instance object of this class:
  • myObject.start()

stop()

Stops listening to the sensor retrieved by using makeSensorType. On Windows Mobile/CE its recommended to call stop on all retrieved sensor objects before exiting a page.

Parameters

• callback : CallBackHandler

Returns

Synchronous Return:

• Void

Platforms

• Android
• Windows Mobile
• Windows CE

Method Access:

• Instance Method: This method can be accessed via an instance object of this class:
  • myObject.stop()

Properties

minimumGap

Type

INTEGER

Description

The minimum amount of time gap between two sensor update events, specified in milliseconds. The interval cannot be set to less than 200 milliseconds, if a value of less than 200 milliseconds is specified, the interval will be defaulted to 200 milliseconds.

Params

Default: 200

Access

• Instance: This property can be accessed via an instance object of this class: myObject.minimumGap

Platforms

• Android
• Windows Mobile
• Windows CE

proximitySensorType

Type

INTEGER

Description

A constant describing a proximity sensor type. The default value of proximitySensorType is 8. On TC8000 Android device, the default value of proximitySensorType is 22. Note: This must be called before invoking makeSensorByType method if the value of proximitySensorType is different.

Access

• Default Instance: This property should only be accessed via the API class object.
  • EB.Sensor.proximitySensorType

Platforms

• Android

status

Type

STRING Read Only

Description

Current status: not_ready, ready, started, error etc.

Access

• Instance: This property can be accessed via an instance object of this class: myObject.status

Platforms

• Android
• Windows Mobile
• Windows CE

type

Type

STRING Read Only

Description

Type of current sensor: Accelerometer, Magnetometer, etc.

Access

• Instance: This property can be accessed via an instance object of this class: myObject.type

Platforms

• Android
• Windows Mobile
• Windows CE

Constants

• SENSOR_TYPE_ACCELEROMETERAccelerometer sensor type.
• SENSOR_TYPE_TILT_ANGLETiltAngle sensor type.
• SENSOR_TYPE_DEVICE_ORIENTATIONDeviceOrientation sensor type.
• SENSOR_TYPE_MOTIONMotion sensor type.
• SENSOR_TYPE_ECOMPASSECompass sensor type.
• SENSOR_TYPE_MAGNETOMETERMagnetometer sensor type.
• SENSOR_TYPE_GYROSCOPEGyroscope sensor type.
• SENSOR_TYPE_AMBIENT_LIGHTAmbientLight sensor type.
• SENSOR_TYPE_PROXIMITYProximity sensor type.
• SENSOR_TYPE_PROXIMITY_LONG_RANGEProximityLongRange sensor type.
• SENSOR_TYPE_PRESSUREPressure sensor type.
• SENSOR_TYPE_TEMPERATURETemperature sensor type.
• SENSOR_TYPE_HUMIDITYHumidity sensor type.
• SENSOR_TYPE_GRAVITYGravity sensor type.
• SENSOR_TYPE_LINEAR_ACCELERATIONLinearAcceleration sensor type.
• SENSOR_TYPE_ROTATIONRotation sensor type.
• SENSOR_TYPE_ORIENTATIONOrientation sensor type.
• SENSOR_STATUS_NOT_READYSensor is not ready for start - may be some type of sensor require time for initializing / calibrating of HW etc.
• SENSOR_STATUS_READYSensor is ready to start listening.
• SENSOR_STATUS_STARTEDSensor already started to listening.
• SENSOR_STATUS_ERRORSensor in error state.

Remarks

General

As this extension returns the raw sensor values reported by the operating system the values might differ between platforms. Also as some of the sensor values change rapidly the minimum gap between two updates should be specified as a reasonable value, otherwise there can be a performance impact.

Supporting Sensors

In Android, as supported sensors could vary from product to product so please refer to Device's PRD/TRD for the list of supported sensors in that particular device.