Appendix E. Sensor definitions

Sensor definitions mean information that is needed in populating a `SensorInfo` and a `ChannelInfo` objects. All the information cannot be defined, because it is vendor specific. This appendix will describe some of the needed information such as a data type, a unit, and measurement rates. The example sensors are selected based on expected popularity and frequency. Needed quantities and context types are given in Appendix A. Finding sensors.

The goal of these recommendations is to help in unifying the sensor implementations accross different manufacturer platforms.

An accelerometer

An accelerometer is measuring acceleration of the device. The context type is `SensorInfo.CONTEXT_TYPE_USER` , because the acceleration is caused by the user moving the device.

Table E.1. Parameter values with the measurement range [-2g,2g]

Channel name

Data type

Scale

MeasurementRange

Resolution

Symbol of the unit

axis_x

double

0

[-19.61, +19.61]

8-bit/12-bit

m/s^2

axis_y

double

0

[-19.61, +19.61]

8-bit/12-bit

m/s^2

axis_z

double

0

[-19.61, +19.61]

8-bit/12-bit

m/s^2

Table E.2. Parameter values with the measurement range [-6g,6g]

Channel name

Data type

Scale

MeasurementRange

Resolution

Symbol of the unit

axis_x

double

0

[-58.84, +58.84]

8-bit/12-bit

m/s^2

axis_y

double

0

[-58.84, +58.84]

8-bit/12-bit

m/s^2

axis_z

double

0

[-58.84, +58.84]

8-bit/12-bit

m/s^2

The accelerometer is a public sensor and does not require permissions.

Axes of a phone with an accelerometer

 The x and y axis define a plane called the phone main plane. The direction of z axis is perpendicular to the phone main plane -x is to the left from the phone, +x is to the right. In the stationary position x is positive if the phone is lying down on the side with the display to the left and number pad to the right -y is down, +y is up. In the stationary position y is positive if the phone is standing straight up with display up on a table. -z is away from the user, +z towards the user. In stationary position z is positive if the phone is lying on a table with the display upwards.

Figure E.1: A mono-display device and its co-ordinate axes

Necessary configurations of an accelerometer: an example

Table E.3. ChannelInfo information of axis_x:

 Field Value Name "axis_x" Accuracy 0.025 Data type ChannelInfo.TYPE_DOUBLE Measurement range [-19.61,19.61],[-58.84,58.84] Resolution 0.01 in [-19.61,19.61]; 0.003 in [-58.84,58.84] Unit "m/s^2"

Table E.4. ChannelInfo information of axis_y:

 Field Value Name "axis_y" Accuracy 0.025 Data type ChannelInfo.TYPE_DOUBLE Measurement range [-19.61,19.61],[-58.84,58.84] Resolution 0.01 in [-19.61,19.61]; 0.003 in [-58.84,58.84] Unit "m/s^2"

Table E.5. ChannelInfo information of axis_z:

 Field Value Name "axis_z" Accuracy 0.025 Data type ChannelInfo.TYPE_DOUBLE Measurement range [-19.61,19.61],[-58.84,58.84] Resolution 0.01 in [-19.61,19.61]; 0.003 in [-58.84,58.84] Unit "m/s^2"

Table E.6. SensorInfo of an accelerometer:

 Field Value Quantity "acceleration" Context type SensorInfo.CONTEXT_TYPE_USER Connection type SensorInfo.CONN_EMBEDDED Model vendor specific (e.g. "LinearAccelerometerA") URL "sensor:acceleration;contextType=user;model=LinearAccelerometerA" Description "acceleration sensor. axis_x channel gives acceleration in x axis direction, where move to left gives negative values and to right positive values. axis_y channel gives acceleration in y axis direction, where move upwards gives positive value and downwards negative value. Axis_z channel gives acceleration in z axis direction, where move toward the user is positive and away is negative. The sensor is always on."

An ambient light sensor

An ambient light sensor measures the intensity of the ambient light, as the total luminous flux incident on a surface. A used unit is lux (lx).

Table E.7. Sensor information of an "ambient_light" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

ambient_light

int

0

[0,65535]

lx

The largest value of the measurement range achieved with the available 16 bits is:

2^16 -1 = 65536 -1 =65535

The ambient light sensor is a public sensor and does not require permissions.

A battery charge sensor

The battery charge sensor measures the battery charge level of the device. It shall represent the charge level as a percentage of the maximum charge level of the battery:

0% =empty, 100% = full.

Table E.8. Sensor information of a "battery_charge" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

battery_charge

int

0

[0,100]

%

The battery charge sensor is a public sensor and requires no permissions.

A charger state sensor

This sensor indicates if the device is connected to a charger or not:

Table E.9. Sensor information of a "charger_state" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

charger_state

int

0

[0,1]

boolean

A "not charged" state equals 0.

A "charged" state equals 1.

Accuracy is -1, and thus uncertainty values are always 0.

The "charger_state" sensor is a public sensor and does not require permissions.

A double tap sensor

This sensor indicates if the device is double tapped and also the direction of tapping:

Table E.10. Sensor information of a "double_tap" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

double_tap

int

0

[1,63]

int

1 equals axis_x plus direction

2 equals axis_x minus direction

3 equals axis_x direction unknown

4 equals axis_y plus direction

8 equals axis_y minus direction

12 equals axis_y direction unknown

16 equals axis_z plus direction

32 equals axis_z minus direction

48 equals axis_z direction unknown

63 equals direction unknown

Figure E.2. illustrates the axes and directions. The "double_tap" sensor is a public sensor and does not require permissions.

A fingerprint sensor

The fingerprint sensor is used to identify the user. The data from the sensor can be offered in various formats. It can be low level information, such as a byte array, or more processed data, such as an identity. The Object type to be returned is not specified.

Table E.11. Sensor information of a "fingerprint" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

id

Object

0

-

id

finger_id

int

0

[-5,5]

finger_id

The id Object must be unique. Every finger must also have a unique id since several fingerprints can be saved for one user.

Table E.12. Finger ids:

 Finger id Left little finger -5 Left ring finger -4 Left middle finger -3 Left index finger -2 Left thumb -1 Not identified 0 Right thumb 1 Right index finger 2 Right middle finger 3 Right ring finger 4 Right little finger 5

To be able to report errors in data reading, following codes are to be used. The fingerprint sensor does not have to support all the error codes defined, but MUST NOT define a new error code whose meaning overlaps with any of the codes listed here. The fingerprint sensor MAY also define a new proprietary error code if the desired error type is missing.

Table E.13. Error codes:

Error code as int value

Meaning

1

The data is not from a live finger

2

Finger was swept too fast

3

Finger was swept too slowly

4

Finger position was too far in the left

5

Finger position was too far in the right

6

Finger was positioned too close to the top of the sensor

7

Finger was positioned too close to the bottom of the sensor

8

Finger was pressed too lightly

9

Finger was pressed too heavily

10

Finger was rotated too much during measurement

11

Finger was swept in skew angle

The fingerprint sensor is a private sensor and requires permission javax.microedition.sensor.PrivateSensor.

A flip state sensor

The flip state sensor indicates the state of the flip of the device: open or closed. The two states are applicable to devices that can have 2 different physical states, for example, a clamshell type device.

Table E.14. Sensor information of a "flip_state" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

flip_state

int

0

[0,1]

boolean

The closed state equals 0

The opened state equals 1

Accuracy is -1, and thus uncertainty is always 0.

The flip state sensor is a public sensor and requires no permissions.

A heart rate and RR interval sensors

Two types of sensors measuring heart rate are defined:

1. `heart_rate`

2. `RR_interval`

The `heart_rate` sensor is giving data as averaged beats per minute.

Table E.15. Sensor information of a "heart_rate" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

heart_rate

int

0

[0,240]

bpm

For more serious health application it is important to measure, for example, RR interval changes; RR intervals can be got with the `RR_interval` sensor.

Table E.16. Sensor information of a "RR_interval" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

RR_interval

int

-3

[0,10000]

s

In normal cases the range for RR intervals is [250ms, 2500ms].

Both the `heart_rate` and `RR_interval` sensors are private sensors and require permission javax.microedition.sensor.PrivateSensor.

A network field intensity sensor (a signal strength sensor)

The network field intensity sensor measures the strength of the current network connection. The quality or strength of the current network signal is expressed as a percentage: 0 =no signal, 100 =best signal

The actual field intensity values are measured in dBm units. When converting dBm to % value, the result must comply with the number of bars shown in the device screen.

Table E.17. Sensor information of a "network_field_intensity" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

network_field_intensity

int

0

[0,100]

%

The network field intensity sensor is a public sensor and requires no permissions.

Necessary configurations of a network field intensity sensor: an example

Table E.18. ChannelInfo of a "network_field_intensity" sensor:

 Field Value Name "network_field_intensity" Accuracy 0.02 Data type ChannelInfo.TYPE_INT Measurement range [0,100] Resolution 1 Unit "%"

Table E.19. SensorInfo of a "network_field_intensity" sensor:

 Field Value Quantity "network_field_intensity" Context type SensorInfo.CONTEXT_TYPE_DEVICE Connection type SensorInfo.CONN_EMBEDDED Model vendor specific (e.g. "generic2") URL "sensor:network_field_intensity;contextType=device;model=generic2" Description "network_field_intensity sensor. network_field_intensity channel gives signal strength of the used network. The sensor is always on."

A proximity sensor

The proximity sensor is a sensor giving the distance between the person and the device. An accuracy and a measurement range varies a lot depending on technique used, whether for example optical, capacitive, or pyroelectric.

Table E.20. Sensor information of a "proximity" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

proximity

double

0

[0,2.5]

m

The proximity sensor is a public sensor and does not require permissions.

An orientation sensor

The orientation sensor provides coarse-grained information of an orientation of a device. The information can be used to detect, for example, a switch from a portrait to a landscape orientation.

Table E.21. Sensor information of an "orientation" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

orientation

int

0

[0,32]

unit

The predefined states are:

Figure E.3: Orientation states, the phone in A is in upright position.

Table E.22. The data value constants of orientation:

Orientation

Value

undefined

0

A

1

B

2

C

3

D

4

E

5

F

6

The orientation sensor is a public sensor and does not require permissions.

A rotation sensor

A rotation sensor provides a very detailed information about the orientation of the device. When an accelerometer was handled, the x, y, and z directions were fixed. Rotations are done around these axes accordingly. Games and UI elements can use a rotation sensor as an input modality.

Table E.23. Information of a "rot_x" channel:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

rot_x

int

0

[0,359]

degree

Figure E.4: Rotation around x axis and corresponding "rot_x" channel data values.

Table E.24. Information of a "rot_y" channel:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

rot_y

int

0

[0,359]

degree

Figure E.5: Rotation around y axis and corresponding "rot_y" channel data values.

Table E.25. Information of a "rot_z" channel:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

rot_z

int

0

[0,359]

degree

Figure E.6: Rotation around z axis and corresponding "rot_z" channel data values.

Data value equals 0, when it cannot be defined. In the case of an accelerometer, the rotation value cannot be defined when the corresponding axis is parallel to the gravitational force or the device is in free fall. In the case of the magnetometer, it is difficult to measure values, when the axis is parallel to the magnetic field. Validity must be set on to get information about invalid values. Setting is done by calling `SensorConnection.getData()` / `SensorConnection.setDataListener()` with `isValidityIncluded` as `true` .

The rotation sensor is a public sensor and does not require permissions.

A sound level setting sensor

The sound level sensor represents the current sound level setting of the device as a percentage of the maximum sound volume setting:

0 =MUTE, 100 = MAX

Table E.26. Sensor information of a "sound_level_setting" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

sound_level_setting

int

0

[0,100]

%

The sound level setting sensor is a public sensor and does not require permissions.

A step counter

The step counter provides the count of taken steps cumulatively. The count is reset when the data retrieval is restarted. In the asynchronous mode, the `DataListener` is notified by each step. In the synchronous mode, the current sum of steps is returned immediately.

Table E.27. Sensor information of a "step_count" sensor:

Channel name

Data type

Scale

MeasurementRange

Symbol of the unit

step_count

int

0

[0, `Integer.MAX_VALUE`]

unit

The step counter is a public sensor and does not require permissions.

Boolean value sensors

If the sensor is returning boolean-type values, such as "on"/"off", "active"/"idle" or `true` / `false` , it must instead of using `Boolean` objects, use `int` values and `boolean` unit.

The value of 0 indicates "off","idle", and `false` , whereas the value of 1 indicates "on", "active", and `true` .

Car related sensors

JSR 298 defines the set of car related sensors, please refer to the Telematics API for Java ME specification (JSR 298) for more information. The specification can be downloaded from JSR 298 web page .

The subset of JSR 256 has been borrowed for JSR 298 to avoid overlapping functionality. The subset contains the core functionality to fetch data from a sensor. The other way to do this is to have both the JSR 256 and JSR 298 implemented in the same device. The car related sensors have a `SensorInfo.CONTEXT_TYPE_VEHICLE` context type.