Using Sensors Plus

To use this plugin, add sensors_plus as a dependency in your pubspec.yaml file.

This will expose such classes of sensor events through a set of streams:

• UserAccelerometerEvent describes the acceleration of the device, in m/s². If the device is still, or is moving along a straight line at constant speed, the reported acceleration is zero. If the device is moving e.g. towards north and its speed is increasing, the reported acceleration is towards north; if it is slowing down, the reported acceleration is towards south; if it is turning right, the reported acceleration is towards east. The data of this stream is obtained by filtering out the effect of gravity from AccelerometerEvent.
• AccelerometerEvent describes the acceleration of the device, in m/s², including the effects of gravity. Unlike UserAccelerometerEvent, this stream reports raw data from the accelerometer (physical sensor embedded in the mobile device) without any post-processing. The accelerometer is unable to distinguish between the effect of an accelerated movement of the device and the effect of the surrounding gravitational field. This means that, at the surface of Earth, even if the device is completely still, the reading of AccelerometerEvent is an acceleration of intensity 9.8 directed upwards (the opposite of the graviational acceleration). This can be used to infer information about the position of the device (horizontal/vertical/tilted). AccelerometerEvent reports zero acceleration if the device is free falling.
• GyroscopeEvent describes the rotation of the device.
• MagnetometerEvent describes the ambient magnetic field surrounding the device. A compass is an example usage of this data.

These events are exposed through a BroadcastStream: accelerometerEvents, userAccelerometerEvents, gyroscopeEvents, and magnetometerEvents, respectively.

note

Some low end or old Android devices might not have all mentioned sensors. Plugin won't crash the app, but it is highly recommended to add onError() to handle such cases gracefully.

Plugin also supports setting of sampling rate for every sensor, but only on Android and iOS platforms. By default sampling rate is set to ~200ms, which is default sampling rate on Android devices. Plugin provides 4 constants which correspond to Android's sampling rate constants. Alternatively sampling rate parameter can be set as Dart's Duration() values. Be aware that values of sampling rate faster than default on Android requires a HIGH_SAMPLING_RATE_SENSORS permission declaration in app's AndroidManifest file.

info

On Android it is not guaranteed that events from sensors will arrive with specified sampling rate as it is noted in the official Android documentation (see description for the samplingPeriodUs parameter). In reality delay varies depending on Android version, device hardware and vendor's OS customisations.

danger

It is not recommended to set sampling rate to 1, 2 or 3 microseconds as these values are reserved in Android. With such values plugin will show warning in logs and change > value to 0.

Examples

import 'package:sensors_plus/sensors_plus.dart';

accelerometerEvents.listen(
  (AccelerometerEvent event) {
    print(event);
  },
  onError: (error) {
    // Logic to handle error
    // Needed for Android in case sensor is not available
    },
  cancelOnError: true,
);
// [AccelerometerEvent (x: 0.0, y: 9.8, z: 0.0)]

userAccelerometerEvents.listen(
  (UserAccelerometerEvent event) {
    print(event);
  },
  onError: (error) {
    // Logic to handle error
    // Needed for Android in case sensor is not available
    },
  cancelOnError: true,
);
// [UserAccelerometerEvent (x: 0.0, y: 0.0, z: 0.0)]

gyroscopeEvents.listen(
  (GyroscopeEvent event) {
    print(event);
  },
  onError: (error) {
    // Logic to handle error
    // Needed for Android in case sensor is not available
    },
  cancelOnError: true,
);
// [GyroscopeEvent (x: 0.0, y: 0.0, z: 0.0)]

magnetometerEvents.listen(
  (MagnetometerEvent event) {
    print(event);
  },
  onError: (error) {
    // Logic to handle error
    // Needed for Android in case sensor is not available
    },
  cancelOnError: true,
);
// [MagnetometerEvent (x: -23.6, y: 6.2, z: -34.9)]

Subscribing to sensor data with defined sampling rate:

magnetometerEvents(samplingPeriod: SensorInterval.uiInterval).listen(
  (MagnetometerEvent event) {
    print(event);
  },
  onError: (error) {
    // Logic to handle error
    // Needed for Android in case sensor is not available
    },
  cancelOnError: true,
);

Also see the example subdirectory for an example application that uses the sensor data.