Chapter 15
Sensors

INScore supports various sensors, which can be viewed as objects or as signals. When created as a signal node, a sensor behaves like any signal but may provide some additional features (like calibration). When created as a score element, a sensor has no graphical appearance and provides specific sensor events and features.

Table 15 gives the list of supported sensors names.





namevalues description



accelerometerx, y, z acceleration on the x, y, and z axis
ambient lightlight level ambient light value
compassazimuth, azimuth is in degrees from magnetic north in a clockwise direction
gyroscopex, y, z the angular velocity around the x, y, and z axis
lightlux the light level measured as lux
magnetometerx, y, z the raw magnetic flux density measured on th x, y and z axis
orientationorientationthe device orientation
proximityclose a boolean value
rotationx, y, z the rotation around the x, y and z axis
tiltx, y the amount of tilt on the x and y axis.




Table 15.1: Sensors names and description

NOTE
All the sensors won’t likely be available on a given device. In case a sensor is not supported, an error message is generated at creation request and the creation process fails.

15.1 Sensors as signals

A sensor is viewed as a signal when created in a signal node using pre-defined signal names which are listed in table 15.1. Values provided on different axis (e.g. acceleration on the x, y, and z axis) are available from the sensor subnodes, also listed in table 15.1.





sensorsignal name subnodes



accelerometeraccelerometerx, y, z
ambient lightambientlight none
compasscompass none
gyroscopegyroscope x, y, z
lightlight none
magnetometermagnetometerx, y, z
orientationorientation none
proximityproximity none
rotationrotation x, y, [z]
tilttilt x, y




Table 15.2: Sensor’s signal names and subnodes

EXAMPLE
Creating a rotation sensor with a 200 values buffer size.

/ITL/scene/signal/rotation size 200;

Getting accelerometer values on the x axis.

/ITL/scene/signal/accelerometer/x get;

NOTE
The rotation sensor may or may not have a z component however, the z signal is always present but set to 0 when no z component is available. A specific message is provided to get the z component status (see section 15.6.3 p.151).

15.2 Sensors as nodes

A sensor is viewed as a regular INScore node when created outside a signal node and using one of the sensors types defined below. A sensor node has no graphical appearance but has the position attributes of an INScore object (x, y, z and scale).

sensorSet PICT

Values generated by a sensor are available using its x, y and z attributes. Depending on the sensor type, y and z may be useless. Note also that events generated in the context of a sensor have the variables $x, $y and $z set with the current sensor values (see section 16.5.2 p.168).

EXAMPLE
Creating a proximity sensor, querying it’s value and watching the value changes.

/ITL/scene/sensor set proximity;
/ITL/scene/sensor get x;
/ITL/scene/sensor watch newData (/ITL/scene/score show ’$x’);

15.3 Values

Values generated by the sensors depends on the sensor type and on the the sensor instance (i.e. whether created as signal or as node). Table 15.3 presents the values range for the node and the signal instances. The rationale is that nodes values are raw sensor values while signal values are mapped to the signal range i.e. [-1,1]. Actually, the mapping of the raw values depends on the sensor calibration that can be automatically or manually adjusted. See the section about calibration below.






sensornode values signal valuescomment




accelerometer[-v,v] [-1,1] depends on the calibration
ambient light0,1,2,3,4,5 [-1,1] see the note about ambient light below
compass[-180,180] [-1,1]
gyroscope[-v,v] [-1,1] depends on the calibration
light[0,v] [-1,1] depends on the calibration
magnetometer[-v,v] [-1,1]
orientation0,1,2,3,4,5,6 [-1,1] see the note about orientation below
proximity0,1 [-1,1] a boolean value mapped to -1, 1
rotationx [-90, 90] [-1,1]
y [-180, 180] [-1,1]
z [-180, 180] [-1,1]
tilt[-90,90] [-1,1]





Table 15.3: Sensor’s values as node and as signal

NOTE ABOUT AMBIENT LIGHT
Ambient light is measured using discrete values ranging from 0 to 5, where 0 means undefined and 1 to 5 goes from dark to very bright.
A value v is mapped to (v*0.4-1)

NOTE ABOUT ORIENTATION
Orientation is measured using discrete values ranging from 0 to 6, where 0 means undefined and 1 to 6 represents the following orientations:

A value v is mapped to (v∕3-1)
In a given way and from values 2 to 5, the device may be viewed as rotating clockwise. A counter-clockwise option is also supported, see section 15.6.4 p.151.

15.4 Calibration

Calibration of sensor values may be viewed as scaling and makes use of the common object’s scale attribute. By default, the scale value is 1.0 when the sensor is a regular node. For signal nodes, the default scale value is given by the table 15.4. These values have been choosen to map the raw values to the signal range but of course this mapping depends on the device and may greatly vary. In order to accommodate these variations but also to cope with different requirements, scaling can be manually adjusted to any arbitrary value using the scale message, or automatically adjusted to measured peak values using the autoscale message.





sensorsignal scalecomment



accelerometer 1/g where g is the gravity on earth i.e. 9.81
ambient light 0.4 see the note about ambient light above
compass 1 / 180
gyroscope 1 / 90
light 1 / 200 an arbitrary lux value (considered as
magnetometer 10000
orientation 1/3 see the note about orientation above
proximity 1.0 the false value is shifted to -1
rotation 1 / 180 for the x value, the scale is multiplied by 2
tilt 1 / 90




Table 15.4: Sensor as signal default scaling

NOTE ABOUT AUTO-SCALING
Auto-scaling consists in measuring the peak of the absolute values of a sensor during a period. The sensor scale value is next adjusted to 1∕peak (see also the sensor common messages in section 15.5). Auto-scaling is supported by all the sensors, although

15.5 Sensor common messages

All sensors support a common set of message.

sensorCommon PICT

15.6 Sensor specific messages

15.6.1 Accelerometer sensor

accelerometerMsg PICT

NOTE ABOUT MODES
Acceleration caused by gravity and acceleration caused by the user moving the device are physically impossible to distinguish because of general relativity. Most devices use sensor fusion to figure out which parts of the acceleration is caused by gravity, for example by using a rotation sensor to calculate the gravity direction and assuming a fixed magnitude for gravity. Therefore the result is only an approximation and may be inaccurate. The combined mode is the most accurate one, as it does not involve approximating the gravity.

15.6.2 Magnetometer sensor

magnetometerMsg PICT

The magnetometer can report on either raw magnetic flux values or geomagnetic flux values. The primary difference between raw and geomagnetic values is that extra processing is done to eliminate local magnetic interference from the geomagnetic values so they represent only the effect of the Earth’s magnetic field. This process is not perfect and the accuracy of each reading may change. Default value is raw.

15.6.3 Rotation sensor

rotationMsg PICT

z angle availability of the rotation sensor can be queried using hasZ. The returned value is a boolean value.

15.6.4 Orientation sensor

orientationMsg PICT





valueclockwise counter clockwise



1 Top edge up Top edge up
2 Face up Face up
3 Left edge up Right edge up
4 Face down Face down
5 Right edge up Left edge up
6 Top edge downTop edge down




Table 15.5: Device positions and values in different modes.

15.6.5 Tilt sensor

tiltMsg PICT