Device sensors

Changelog Bugs and feature requests AppGyver Academy
Search…
Device sensors
How to access device sensor data, such as geolocation and accelerometer.
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.