- 05 May 2022
- 4 Minutes to read
- Updated on 05 May 2022
- 4 Minutes to read
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 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.
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.
values is an empty array.
Each sensor variable also includes an
active boolean property, which denotes if the sensor poller is active or not.
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
valuesarray) 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.
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
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,
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
values variables when getting a single sensor value.
Every sensor has a flow function to reset the collected values, e.g. Reset accelerometer. This sets the sensor's
null. Optionally, you can also reset the
values array, setting it to an empty array.
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
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.
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.
It is up to the developer to handle these events by adding the relevant event nodes e.g. to the global logic canvas.