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

Sensor

Methods9
Methods - Class
makeSensorByType
Methods - Instance
getAllPropertiesgetPropertiesgetPropertyreadDatasetPropertiessetPropertystartstop
Properties3
Instance Properties
minimumGapstatustype
Constants22
SENSOR_TYPE_ACCELEROMETERSENSOR_TYPE_TILT_ANGLESENSOR_TYPE_DEVICE_ORIENTATIONSENSOR_TYPE_MOTIONSENSOR_TYPE_ECOMPASSSENSOR_TYPE_MAGNETOMETERSENSOR_TYPE_GYROSCOPESENSOR_TYPE_AMBIENT_LIGHTSENSOR_TYPE_PROXIMITYSENSOR_TYPE_PROXIMITY_LONG_RANGESENSOR_TYPE_PRESSURESENSOR_TYPE_TEMPERATURESENSOR_TYPE_HUMIDITYSENSOR_TYPE_GRAVITYSENSOR_TYPE_LINEAR_ACCELERATIONSENSOR_TYPE_ROTATIONSENSOR_TYPE_ORIENTATIONSENSOR_STATUS_NOT_READYSENSOR_STATUS_READYSENSOR_STATUS_STARTEDSENSOR_STATUS_ERRORSENSOR_STATUS_OK
Examples1
Basic Example
Remarks2
GeneralSupporting Sensors

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.

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.

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.

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.

    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.

    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.

    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.

    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.

    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/s2)

      • accelerometer_y : FLOAT

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

      • accelerometer_z : FLOAT

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

      • 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/s2)

      • gravity_y : FLOAT

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

      • gravity_z : FLOAT

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

      • linearacceleration_x : FLOAT

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

      • linearacceleration_y : FLOAT

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

      • linearacceleration_z : FLOAT

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

      • 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.

    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.

    Default: 200

    Property Access:

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

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

    Property Access:

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

    Type of current sensor: Accelerometer, Magnetometer, etc.

    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.

    SENSOR_STATUS_OK

    Sensor in ok state.

    Examples

    Basic Example

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

    #/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.