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^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 Zebra 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 units
gyroscope_y : FLOAT
X co-ordinate value of the gyroscope sensor in radians/second units
gyroscope_z : FLOAT
X co-ordinate value of the gyroscope sensor in radians/second units
ambientlight_value : STRING
Value of the ambient Light sensor in SI lux units
proximity_value : STRING
Value of the proximity sensor in centimeters units
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 in percent units
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

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 milli seconds is specified, the interval will be defaulted to 200 milli seconds.

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 initialising/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 milli seconds.

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.