javax.microedition.sensor
Interface ChannelInfo

public interface ChannelInfo

The object implementing this interface provides information about the data properties of the channel.

If the sensor is measuring different properties or dimensions simultaneously, those values are considered as separate channels. Synonyms for the concept "channel" could be "axis" or "degree of freedom". Measurement data from each channel is delivered in a separate Data object. The Data object contains the information about the channel of its origin and it can be retrieved with the Data.getChannelInfo() method.

The following information is mandatory for all ChannelInfo objects:

• the name
• the accuracy
• the data type
• measurement ranges
• the scale
• the unit

The standard channel names listed in the following table MUST be used, if they are suitable. Names are case-sensitive and MUST follow the given format. If names listed here don't match the needs, new names can be defined. The name MUST NOT be null or an empty string. The name MUST be chosen to be unique. Prefixing the channel name with the same inverted domain name as is used in naming Java packages, does this, for example:

com.some_company.quaternion

Channel names to be used

Name	Short description
axis_x	Acceleration/velocity to axis x direction
axis_y	Acceleration/velocity to axis y direction
axis_z	Acceleration/velocity to axis z direction
heading	The angle between the direction of a compass needle and a specified meridian, due north
pitch	The deviation from a stable attitude by movement of the longitudinal axis about the lateral axis
roll	The deviation of display plane of the horizontal plane
rot_x	The rotation around axis x
rot_y	The rotation around axis y
rot_z	The rotation around axis z
button_1..button_128	Custom buttons of a joystick
fire_1..fire_4	Fire buttons of a joystick
button_right	The right button of a mouse
button_left	The left button of a mouse
button_middle	The middle button of a mouse

In the case of one-channel sensors like a thermometer, a barometer, or a humiditymeter, the channel name SHOULD be the same as the quantity of the sensor.

With sensors, which are measuring values related to an orientation of the device, such as accelerometers and magnetometers, it is good to agree on conventions of how the axes are typically oriented relative to the device.

It is generally recommended that the longitudinal axis is aligned with the bottom-to-top direction of the screen. This means that the pitch is positive when the top of the screen is up and the bottom of the screen down (i.e., when a roll is zero). The roll is positive when the device is tilted clockwise looking from the direction of the bottom of the screen, i.e., when the left side of the screen is up and the right side of the screen is down (i.e., when a pitch is zero).

The x, y and z axis orientations are defined in Sensor definitions. The x-axis direction is positive towards the right, and the y-axis direction is positive upwards. The z-axis direction is orthogonal to the plane of the screen and move towards a user is positive.

Field Summary

static int	TYPE_DOUBLE Constant used to indicate the double data type.
static int	TYPE_INT Constant used to indicate the int data type.
static int	TYPE_OBJECT Constant used to indicate the Object data type.

Method Summary

float	getAccuracy() Returns the accuracy of this channel of the sensor as a percentage of reading (=data value).
int	getDataType() Returns the data type of the channel.
MeasurementRange[]	getMeasurementRanges() This method returns all the measurement ranges of this channel of the sensor.
java.lang.String	getName() Returns the name of the channel.
int	getScale() Returns the scale used for the measurement values of this channel.
Unit	getUnit() Returns the unit, in which data values are presented.

Field Detail

TYPE_OBJECT

static final int TYPE_OBJECT

Constant used to indicate the Object data type. Object values could be, for example, Character, String, or byte array.

See Also:

Constant Field Values

TYPE_INT

static final int TYPE_INT

Constant used to indicate the int data type.

See Also:

Constant Field Values

TYPE_DOUBLE

static final int TYPE_DOUBLE

Constant used to indicate the double data type.

See Also:

Constant Field Values

Method Detail

getAccuracy

float getAccuracy()

Returns the accuracy of this channel of the sensor as a percentage of reading (=data value). Because this accuracy value describes the relative measurement error, greater values indicate a less accurate sensor. The accuracy value is within:

0 <= accuracy < 1

This method returns the accuracy, which can be used to calculate the maximum uncertainty. The accuracy multiplied with the data value MUST be greater than or equal to the standard deviation. The probability of the actual value residing within the defined value range, if measurements are normally distributed:

 P( data value - accuracy * data value - OFFSET_ERROR <= actual value
 <=  data value + accuracy * data value + OFFSET_ERROR) > 68%
 

OFFSET_ERROR is the error that is independent of the measured value. This formula MUST hold in all the measurement ranges of the sensor.

A relation between an uncertainty of the Data and accuracy can be depicted roughly with the following formula:

 | accuracy * data value + OFFSET_ERROR | >= | uncertainty |
 

In the context of this API the formula is

 | getAccuracy() * data.getDoubleValues()[i] + OFFSET_ERROR | >= 
 | data.getUncertainty(i) |
 

Returns:

the accuracy of the channel of the sensor. If the accuracy is not known, a value of -1 is returned.

getDataType

int getDataType()

Returns the data type of the channel. The type alternatives are:

• TYPE_INT
• TYPE_DOUBLE
• TYPE_OBJECT

Returns:

the data type of the channel

getMeasurementRanges

MeasurementRange[] getMeasurementRanges()

This method returns all the measurement ranges of this channel of the sensor. The sensor may use different measurement ranges, dedicated to special value ranges. The measurement range is defined with the smallest and the largest possible value and the resolution. For more information see class MeasurementRange. If the data type of the channel is TYPE_OBJECT, this method returns a zero-length MeasurementRange array.

If the scaling is used, the measurement range values MUST use the same scaling factor, too. See method getScale() for more details.

Returns:

all measurement ranges of the channel

getName

java.lang.String getName()

Returns the name of the channel.

Returns:

the name of the channel

getScale

int getScale()

Returns the scale used for the measurement values of this channel. The scale can be used as a substitute for prefixing the unit. The scale is expressed as an exponent of ten. If no scaling is needed, the scale MUST be zero.

Either the unit or data values are affected with the scaling factor. If, for example, the unit is meter and the scale is -3, the unit can be interpreted as "mm". If the SI prefix is added to the unit, data values remain as they are. If the unit is not changed, then data values must be multiplied with 10^(scale). In this example, if data values are presented in meters and scale is -3, then the data values must be multiplied with 10^-3, which means dividing by 1000.

If the data type of the channel is int this results in a fixed-point representation in which the amount of decimals remains always the same. Using a fixed-point representation can have a favorable effect on performance. With floating point data type, the scaling factor is often used for convenience. With either very small, or very large values the presentation can be more readable when the values can be presented in moderate numbers.

All the following methods MUST return values in the same scale:

• getMeasurementRanges(), both limits and a resolution
• Data.getIntValues()/Data.getDoubleValues()
• Data.getUncertainty()
• LimitCondition.getLimit()
• RangeCondition.getLowerLimit()
• RangeCondition.getUpperLimit()

NOTE: when Condition objects are present in the sensor URL for PushRegistry, the values of limits MUST be presented in basic units, in resolved format as a single value with the scaling factor of 0. The URL scheme is described in SensorConnection. <limit> maps to LimitCondition and <range> to RangeCondition.

Returns:

scale, the scaling factor influencing the interpreting of measured data values

getUnit

Unit getUnit()

Returns the unit, in which data values are presented. Recommended units are listed in the class Unit.

Returns:

the unit, in which data values of the channel are presented.