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
- : 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
- : 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 for Android Kitkat and 65538 for Android Lollipop and above. 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.