Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Sensor

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. Then you can use the start and stop methods on that instance.

Enabling the API

In order to use this API you must include the following extension in your build.yml.

extensions: ["sensor"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

getAllProperties(CallBackHandler callback)

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

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

: STRING

Synchronous Return:

HASH :
Map of all available properties
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- : STRING

Method Access:

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

getProperties(ARRAY arrayofNames, CallBackHandler callback)

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

arrayofNames : ARRAY

List of properties I want to know about

Object : STRING

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

: STRING

Synchronous Return:

HASH :
Map of properties I want to know about
: this method also supports async callbacks - check the Callback tab for callback return parameters.
- : STRING

Method Access:

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

getProperty(STRING propertyName, CallBackHandler callback)

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

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyName : STRING

The property to return info about.
callback : CallBackHandler Optional

Async Callback Returning Parameters: STRING

Synchronous Return:

STRING :
The property to return info about.
: this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

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

makeSensorByType(STRING type)

Return the new sensor object by type.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

type : STRING

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

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.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Sensor.makeSensorByType(STRING type)
- Ruby: Rho::Sensor.makeSensorByType(STRING type)

readData()

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

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Synchronous Return:

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

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyMap : HASH

Map of properties I want to set

Object : STRING

Synchronous Return:

Void

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

propertyName : STRING

The one property name that I want to set
propertyValue : STRING

The one property value that I want to set

Synchronous Return:

Void

Method Access:

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

start(CallBackHandler callback)

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

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Optional

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²⁾
accelerometer_y : FLOAT

Y co-ordinate value of the Accelerometer sensor in SI units (m/s²⁾
accelerometer_z : FLOAT

Z co-ordinate value of the Accelerometer sensor in SI units (m/s²⁾
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²⁾
gravity_y : FLOAT

Y co-ordinate value of the gravity sensor in SI units (m/s²⁾
gravity_z : FLOAT

Z co-ordinate value of the gravity sensor in SI units (m/s²⁾
linearacceleration_x : FLOAT

X co-ordinate value of the linear acceleration sensor in SI units (m/s²⁾
linearacceleration_y : FLOAT

Y co-ordinate value of the linear acceleration sensor in SI units (m/s²⁾
linearacceleration_z : FLOAT

Z co-ordinate value of the linear acceleration sensor in SI units (m/s²⁾
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.

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

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

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Synchronous Return:

Void

Method Access:

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

Properties

minimumGap : INTEGER

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Default: 200

Property Access:

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

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

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

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

type : STRING Read Only

Description
Access

Type of current sensor: Accelerometer, Magnetometer, etc.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Property Access:

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

Constants

SENSOR_TYPE_ACCELEROMETER: Accelerometer sensor type.
SENSOR_TYPE_TILT_ANGLE: TiltAngle sensor type.
SENSOR_TYPE_DEVICE_ORIENTATION: DeviceOrientation sensor type.
SENSOR_TYPE_MOTION: Motion sensor type.
SENSOR_TYPE_ECOMPASS: ECompass sensor type.
SENSOR_TYPE_MAGNETOMETER: Magnetometer sensor type.
SENSOR_TYPE_GYROSCOPE: Gyroscope sensor type.
SENSOR_TYPE_AMBIENT_LIGHT: AmbientLight sensor type.
SENSOR_TYPE_PROXIMITY: Proximity sensor type.
SENSOR_TYPE_PROXIMITY_LONG_RANGE: ProximityLongRange sensor type.
SENSOR_TYPE_PRESSURE: Pressure sensor type.
SENSOR_TYPE_TEMPERATURE: Temperature sensor type.
SENSOR_TYPE_HUMIDITY: Humidity sensor type.
SENSOR_TYPE_GRAVITY: Gravity sensor type.
SENSOR_TYPE_LINEAR_ACCELERATION: LinearAcceleration sensor type.
SENSOR_TYPE_ROTATION: Rotation sensor type.
SENSOR_TYPE_ORIENTATION: Orientation sensor type.
SENSOR_STATUS_NOT_READY: Sensor is not ready for start – may be some type of sensor require time for initializing / calibrating of HW etc.
SENSOR_STATUS_READY: Sensor is ready to start listening.
SENSOR_STATUS_STARTED: Sensor already started to listening.
SENSOR_STATUS_ERROR: Sensor in error state.

Examples

Basic Example

The below example gets the Accelerometer values for every 500 milliseconds.

Ruby

#/app/Model
def index
    @accelerometer_sensor = Rho::Sensor.makeSensorByType(Rho::Sensor::SENSOR_TYPE_ACCELEROMETER)
    if @accelerometer_sensor != nil
        @accelerometer_sensor.minimumGap = 500
        @accelerometer_sensor.start(url_for(:action => :myevent))
    else
       puts "Warning: This device has not Accelerometer sensor !"
    end    
end

def stop_listening_accelerator
    if @accelerometer_sensor != nil
        @accelerometer_sensor.stop
    end    
end

def myevent       
    puts "Accelerometer params: #{@params}"
    puts "X is #{@params['accelerometer_x']}"
    puts "Y is #{@params['accelerometer_y']}"  
    puts "Z is #{@params['accelerometer_z']}"      
end

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.