# 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 tab:sensors gives the list of supported sensors names.

name values description
accelerometer x, y, z acceleration on the x, y, and z axis
ambient light light level ambient light value
compass azimuth, azimuth is in degrees from magnetic north in a clockwise direction
gyroscope x, y, z the angular velocity around the x, y, and z axis
light lux the light level measured as lux
magnetometer x, y, z the raw magnetic flux density measured on th x, y and z axis
orientation orientation the device orientation
proximity close a boolean value
rotation x, y, z the rotation around the x, y and z axis
tilt x, y the amount of tilt on the x and y axis.

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.

## 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 tab:sensorsig. Values provided on different axis (e.g. acceleration on the x, y, and z axis) are available from the sensor subnodes, also listed this table.

sensor signal name subnodes
accelerometer accelerometer x, y, z
ambient light ambientlight none
compass compass none
gyroscope gyroscope x, y, z
light light none
magnetometer magnetometer x, y, z
orientation orientation none
proximity proximity none
rotation rotation x, y, [z]
tilt tilt x, y

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 Rotation).

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

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 sensorvar). 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');


## 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 tab:sensorsval 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.

sensor node values signal values comment
accelerometer [-v,v] [-1,1] depends on the calibration
ambient light {0,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]
orientation {0,1,2,3,4,5,6} [-1,1] see the note about orientation below
proximity {0,1} [-1,1] a boolean value mapped to -1, 1
rotation x [-90, 90] [-1,1]
y [-180, 180] [-1,1]
z [-180, 180] [-1,1]
tilt [-90,90] [-1,1]

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:

• 1: the Top edge of the device is pointing up.
• 2: the Face of the device is pointing up.
• 3: the Left edge of the device is pointing up.
• 4: the Face of the device is pointing down.
• 5: the Right edge of the device is pointing up.
• 6: the Top edge of the device is pointing down.

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

## 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 tab:sensorsscales. 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.

sensor signal scale comment
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

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 sensorCommonMsgs). Auto-scaling is supported by all the sensors, although

## Sensor common messages

All sensors support a common set of message.

sensorCommon
• run: takes a boolean value as parameter. When true, the sensor starts to generate values. Default value is false.
• smooth: applies exponential smoothing to the sensor values. At a time $t$, the sensor value is computed as: $s_t = \alpha.v_t + (1-\alpha).s_{t-1}$ where $v_t$ is the current sensor value and $0 \leqslant \alpha \leqslant 1$. The parameter is the smoothing factor $\alpha$. Default value is 1.
• scale: sensor values are multiplied by the scale. Default scale is dependent on the sensor type. See table tab:sensorsscales for the default scale values.
• autoscale: start or stop the auto-scaling process. Default value is false. See the note about auto scaling above. Note that a sensor must be running for the auto-scaling process to take effect.
• reset: reset the smoothing factor and the scale to their default values.

## Sensor specific messages

### Accelerometer sensor

accelerometerMsg
• mode: the acceleration mode controls how acceleration values are reported.

• gravity: only the acceleration caused by gravity is reported. Movements of the device caused by the user have no effect other than changing the direction when the device is rotated.

• user: only the acceleration caused by the user moving the device is reported, the effect of gravity is canceled out. A device at rest therefore should report values of, or close to, zero.
• combined: both the acceleration caused by gravity and the acceleration caused by the user moving the device is reported combined.

Default value is combined.

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.

### Magnetometer sensor

magnetometerMsg

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.

### Rotation sensor

rotationMsg

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

### Orientation sensor

orientationMsg
• mode: selects how the device position is mapped to successive values. Default value is clockwise. See table tab:orientations for the detail of the positions and values.

value clockwise 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 down Top edge down

Device positions and values in different modes.

### Tilt sensor

tiltMsg
• calibrate: calibrates the tilt sensor: uses the current tilt angles as 0.