Composer gives you access to many kinds of device sensors. The current list is:

• Accelerometer – device's current acceleration

• Barometer – current atmospheric pressure

• Compass – device's current heading

• Geolocation – device's current GPS position

• Gyroscope – device's current orientation

• Magnetometer – strength and direction of the Earth's magnetic field relative to the device

Note that all sensors are not available on every device.

There are two concepts that work together to allow you to access sensor data: sensor variables and sensor flow functions.

Sensor variables

Sensor variables are special, app-wide variables that store data gathered by the device's sensors. You can access sensor variables via formula functions under the sensorVars namespace, e.g. sensorVars.geolocation.

Collected values

Each sensor variable has a latestValue property, which contains the latest sensor value obtained, and a values array, which contains a number of historical values.

The schema of a sensor value depends on the sensor, but every value always has a timestamp property, making it easy to check when the latest value was retrieved.

By default, the sensors are not active. latestValue is undefined and values is an empty array.

Active state

Each sensor variable also includes an active boolean property, which denotes if the sensor poller is active or not.

Reference documentation

Please see the Sensor variables reference documentation for a full description of the available sensor variables and their schemas

Sensor flow functions

For each sensor, the following flow functions are available:

• Start sensor poller – start the poller for the given sensor

• Stop sensor poller – stop the poller for the given sensor

• Get single sensor value – get a single value for the given sensor, independently from the poller

• Reset sensor – resets latestValue (and optionally, empties the values array) for the given sensor

Start sensor poller

Every sensor has a flow function that will start a poller for that sensor, e.g. Start accelerometer poller. You can also define a custom polling interval, the number of historical values to store in the values array, and for certain sensors like geolocation, additional polling options.

When the poller has been started, it fetches a new value for the sensor from the native API. For example, say you've started an accelerometer poller with an update interval of 10 ms. Then, every 10 ms, sensorVars.accelerometer.latestValue would update with the latest accelerometer reading, and sensorVars.accelerometer.values array would get a new item.

Once the values array has as many historical values as was defined when starting the poller, the oldest entry is removed when the new entry is added.

Stop sensor poller

Conversely, every sensor has a flow function that will stop an active poller, e.g. Stop accelerometer poller.

Stopping a sensor poller means that no new values will be recorded, but both latestValue and values will be preserved.

Get single sensor value

Every sensor has a flow function to get a single value, e.g. Get single accelerometer value. This causes a native API call to be made to fetch a new value for the sensor, which is then outputted by the flow function.

Getting a single value happens independently from any active pollers. Thus, if I have an active geolocation poller with an update interval of 60 seconds, and I call Get single geolocation value 20 seconds after the last update, sensorVars.geolocation.latestValue and values will update with a new location value as soon as the native API resolves, and then again when the update interval triggers.

Optionally, you can choose to not update the latestValue and values variables when getting a single sensor value.

Reset sensor

Every sensor has a flow function to reset the collected values, e.g. Reset accelerometer. This sets the sensor's latestValue to null. Optionally, you can also reset the values array, setting it to an empty array.

Error handling

Trying to access the device sensors can result in an error, e.g. if the user has not given the necessary permissions, if the sensor is not present on the device or if the native API cannot return a value for some reason.

Error handling happens on two levels: flow functions and the onPollerError event.

Start sensor poller errors

The Start sensor poller flow function triggers its error output if the poller cannot be started.

Calling a Start sensor poller flow function when there's an active poller doesn't result in an error, but rather stops the previously active poller and starts a new one.

Stop sensor poller errors

The Stop sensor poller flow function triggers its error output if there's no active poller to stop.

Get single sensor value errors

The Get single sensor value flow function triggers its error output if a new sensor value cannot be retrieved from the native API.

Reset sensor errors

The Reset sensor flow function does not have an error output.

onPollerError event

If an active sensor poller cannot get a new sensor value when the update interval triggers, an error event with the ID sensor:<sensorName>:onPollerError is triggered, e.g. sensor:geolocation:onPollerError.

It is up to the developer to handle these events by adding the relevant event nodes e.g. to the global logic canvas.