Pub Bunker

sensors_plus

v6.1.2

Flutter plugin for accessing accelerometer, gyroscope, and magnetometer sensors.

Package archive: https://pubdev.letsnova.ru/api/archives/sensors_plus/6.1.2.tar.gz

Installdart pub add sensors_plus
Readme Changelog Versions

Readme

sensors_plus

sensors_plus pub points pub package

A Flutter plugin to access the accelerometer, gyroscope, magnetometer and barometer sensors.

Platform Support

Android iOS MacOS Web Linux Windows
✅ ✅ ❌ ✅* ❌ ❌

* Currently it is not possible to set sensors sampling rate on web

Requirements

  • Flutter >=3.19.0
  • Dart >=3.3.0 <4.0.0
  • iOS >=12.0
  • MacOS >=10.14
  • Android compileSDK 34
  • Java 17
  • Android Gradle Plugin >=8.3.0
  • Gradle wrapper >=8.4

Usage

Add sensors_plus as a dependency in your pubspec.yaml file.

On iOS you must also include a key called NSMotionUsageDescription in your app's Info.plist file. This key provides a message that tells the user why the app is requesting access to the device’s motion data. The plugin itself needs access to motion data to get barometer data.

Example Info.plist entry:

<key>NSMotionUsageDescription</key>
                <string>This app requires access to the barometer to provide altitude information.</string>

[!CAUTION]

Adding NSMotionUsageDescription is a requirement and not doing so will crash your app when it attempts to access motion data.

The plugin exposes such classes of sensor events through a set of streams:

  • UserAccelerometerEvent describes the acceleration of the device, in m/s2. 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/s2, 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.
  • BarometerEvent describes the atmospheric pressure surrounding the device, in hPa. An altimeter is an example usage of this data. Not supported on web browsers.

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

[!NOTE]

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

Example

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)]
                
                barometerEvents.listen(
                  (BarometerEvent event) {
                    print(event);
                  },
                  onError: (error) {
                    // Logic to handle error
                    // Needed for Android in case sensor is not available
                    },
                  cancelOnError: true,
                );
                // [BarometerEvent (pressure: 1000.0)]

Alternatively, every stream allows to specify the sampling rate for its sensor using one of predefined constants or using a custom value.

[!NOTE]

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 the description for the samplingPeriodUs parameter). In reality delay varies depending on Android version, device hardware and vendor's OS customisations.

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

For more detailed instruction check out the documentation linked below. Also see the example subdirectory for an example application that uses the sensor data.

Platform Restrictions and Considerations

The following lists the restrictions for the sensors on certain platforms due to limitations of the platform.

  • Magnetometer and Barometer missing for web

    The Magnetometer API is currently not supported by any modern web browsers. Check browser compatibility matrix on MDN docs for Magnetormeter API.

    The Barometer API does not exist for web platforms as can be seen at MDN docs forn Sensors API.

    Developers should consider alternative methods or inform users about the limitation when their application runs on a web platform.

[!NOTE]

Plugin won't crash the app in the case of usage on these platforms, but it is highly recommended to add onError() to handle such cases gracefully.

  • Sampling periods for web

    Currently it is not possible to set sensors sampling rate on web. Calls to event streams at specied sampling periods will have the sampling period ignored.

  • Barometer sampling period limitation for iOS

    On iOS devices, barometer updates are CMAltimeter which provides updates at regular intervals that cannot be controlled by the user. Calls to barometerEventStream at specied sampling periods will have the sampling period ignored.

Learn more

Changelog

6.1.2

  • DOCS(all): improve documentation across multiple README files (#3630). (643e12df)

6.1.1

  • REFACTOR(all): Use range of flutter_lints for broader compatibility (#3371). (8a303add)

6.1.0

  • FEAT(sensors_plus): Add Swift Package Manager support (#3170). (3a0798c4)

6.0.1

  • DOCS(sensors_plus): Update plugin requirements in README (#3164). (82d95db4)

6.0.0

Note: This release has breaking changes. Starting with this release on iOS it is required to add NSMotionUsageDescription entry in the Info.plist file. More info available in the README file.

  • BREAKING FEAT(sensors_plus): Add support for platform timestamp in event (#2506). (8b3df176)
  • BREAKING FEAT(sensors_plus): Add barometer support for all platforms (#3079). (5fa797d0)
  • REFACTOR(all): Remove website files, configs, mentions (#3018). (ecc57146)
  • FIX(all): changed homepage url in pubspec.yaml (#3099). (66613656)

5.0.1

  • REFACTOR(sensors_plus): Migrate Android example to use the new plugins declaration (#2743). (e884a9e9)
  • FIX(sensors_plus): WASM-compatible conditional imports (#2824). (823a7d78)

5.0.0

Note: This release has breaking changes.

In this release plugin migrated migrated from dart:html to js_interop, meaning that it now supports WASM!

Plugin now requires the following:

  • Flutter >=3.19.0

  • Dart >=3.3.0

  • compileSDK 34 for Android part

  • Java 17 for Android part

  • Gradle 8.4 for Android part

  • BREAKING FEAT(sensors_plus): Migrate to dart:js_interop (#2697). (48edfa20)

  • BREAKING BUILD(sensors_plus): Target Java 17 on Android (#2729). (7a83e355)

  • BREAKING BUILD(sensors_plus): Update to target and compile SDK 34 (#2708). (f110dfd)

  • FIX(sensors_plus): Add try-catch for release builds (#2718). (c37acd67)

  • FIX(sensors_plus): Add iOS Privacy Info (#2585). (9b7198a9)

  • FEAT(sensors_plus): Update min iOS target to 12 (#2661). (ca5d660f)

4.0.2

  • FIX(sensors_plus): Close magnetometerStreamController on web (#2456). (64200667)

4.0.1+1

  • DOCS(sensors_plus): Update README to mention how sampling rate works on Android (#2452). (4d8ce2f8)

4.0.1

Note: This release has breaking changes.

  • BREAKING FIX(sensors_plus): Use magnetometer instead of deviceMotion on iOS (#2250). (d1751024)
  • FEAT(sensors_plus): Configurable sample rate on Android and iOS (#2248). (82ffe46c)
  • DOCS(sensors_plus): Add info about sensors sampling rate configuration (#2393). (35900ead)

4.0.0

This release was retracted due to #2251.

3.1.0

Info: This release is a replacement for release 4.0.0, which was retracted due to issue (#2251). As breaking change was reverted the major release was also reverted in favor of this one.

  • FIX(sensors_plus): Change Kotlin version from 1.9.10 to 1.7.22 (#2253). (10fade07)
  • FIX(sensors_plus): Close stream controllers onCancel on web (#2249). (476e17bc)
  • FIX(sensors_plus): Revert bump compileSDK to 34 (#2233). (8574422a)
  • FIX(sensors_plus): Error handling of native crashes (e.g. missing hardware) (#1987). (ee942290)
  • FEAT(sensors_plus): Remove deprecated VALID_ARCHS iOS property (#2027). (8ba4197e)

3.0.3

3.0.2

  • FIX(sensors_plus): Fix issues with emitting multiple sensors events on iOS (#1859). (d33b20fa)

3.0.1

  • FIX(sensors_plus): Fix crash on Android if device has no requested sensor (#1405). (a078b4e8)
  • FIX: Add jvm target compatibility to Kotlin plugins (#1798). (1b7dc432)
  • DOCS(sensor_plus): Add info about possible error cases (#1830). (58d512de)
  • DOCS(all): Update READMEs (#1828). (57d9c884)
  • CHORE(sensors_plus): Win32 dependency upgrade (#1805). (3f68800)

3.0.0

Note: This release has breaking changes.

  • CHORE(sensors_plus): Update Flutter dependencies, set Flutter >=3.3.0 and Dart to >=2.18.0 <4.0.0
  • BREAKING FIX(all): Add support of namespace property to support Android Gradle Plugin (AGP) 8 (#1727). Projects with AGP < 4.2 are not supported anymore. It is highly recommended to update at least to AGP 7.0 or newer.
  • BREAKING CHORE(sensors_plus): Bump min Android to 4.4 (API 19) and iOS to 11, update podspec file (#1774).
  • REFACTOR(sensors_plus): Remove manual dependency_override in example app.

2.0.5

  • FIX(all): Revert addition of namespace to avoid build fails on old AGPs (#1725).

2.0.4

  • FIX(sensors_plus): Add compatibility with AGP 8 (Android Gradle Plugin) (#1705).

2.0.3

  • DOCS(sensor_plus): improve description of accelerometer (#1425).

2.0.2

  • DOCS: Updates for READMEs and website pages (#1389).

2.0.1

  • FIX: Increase min Flutter version to fix dartPluginClass registration (#1275).

2.0.0

Note: This release has breaking changes.

  • FIX: lint warnings - add missing dependency for tests (#1233).
  • DOCS: Update website docs and README (#1247).
  • BREAKING REFACTOR: two-package federated architecture (#1237).

1.4.1

  • CHORE: Version tagging using melos.

1.4.0

  • iOS: Corrects magnetometer implementation, returning calibrated values from DeviceMotion sensor rather than raw sensor samples

1.3.4+1

  • Add issue_tracker link.

1.3.4

  • Additonal fixes for crash issue: "Error: Sending a message before the FlutterEngine has been run."

1.3.3

  • Fix: "crash on iOS: Sending a message before the FlutterEngine has been run"

1.3.2

  • Fix: Android no longer crashes when app is closed if streams weren't listened to
  • Update flutter_lints to 2.0.1
  • Fix analyzer warnings

1.3.1

  • Fix: unregister listeners on Android in onDetachFromEngine to not receive sensors events after app was killed

1.3.0

  • Android: Migrate to Kotlin
  • Android: Update dependencies, build config updates

1.2.2

  • Fix example embedding issues

1.2.1

  • Upgrade Android compile SDK version
  • Several code improvements

1.2.0

  • migrate integration_test to flutter sdk

1.1.0

  • Adds magnetometer support

1.0.2

  • Android: migrate to mavenCentral

1.0.1

  • Improve documentation

1.0.0

  • Migrated to null-safety

0.6.0

  • Renamed Method Channel

0.5.0

  • Transfer to plus-plugins monorepo

0.4.2+5

  • Transfer package to Flutter Community under new name sensors_plus.

0.4.2+4

  • Update package:e2e -> package:integration_test

0.4.2+3

  • Update package:e2e reference to use the local version in the flutter/plugins repository.

0.4.2+2

  • Post-v2 Android embedding cleanup.

0.4.2+1

  • Update lower bound of dart dependency to 2.1.0.

0.4.2

  • Remove Android dependencies fallback.
  • Require Flutter SDK 1.12.13+hotfix.5 or greater.
  • Fix CocoaPods podspec lint warnings.

0.4.1+10

0.4.1+9

  • Replace deprecated getFlutterEngine call on Android.

0.4.1+8

  • Make the pedantic dev_dependency explicit.

0.4.1+7

  • Fixed example userAccelerometerEvent in documentation

0.4.1+6

  • Migrate from deprecated BinaryMessages to ServicesBinding.instance.defaultBinaryMessenger.
  • Require Flutter SDK 1.12.13+hotfix.5 or greater (current stable).

0.4.1+5

  • Fix example setState() called after dispose() by canceling the timer.

0.4.1+4

  • Remove the deprecated author: field from pubspec.yaml
  • Migrate the plugin to the pubspec platforms manifest.
  • Require Flutter SDK 1.10.0 or greater.

0.4.1+3

  • Improve documentation and add unit test coverage.

0.4.1+2

  • Remove AndroidX warnings.

0.4.1+1

  • Include lifecycle dependency as a compileOnly one on Android to resolve potential version conflicts with other transitive libraries.

0.4.1

  • Support the v2 Android embedder.
  • Update to AndroidX.
  • Migrate to using the new e2e test binding.
  • Add a e2e test.

0.4.0+3

  • Update and migrate iOS example project.
  • Define clang module for iOS.

0.4.0+2

0.4.0+1

  • Log a more detailed warning at build time about the previous AndroidX migration.

0.4.0

  • Breaking change. Migrate from the deprecated original Android Support Library to AndroidX. This shouldn't result in any functional changes, but it requires any Android apps using this plugin to also migrate if they're using the original support library.

0.3.5

  • Added missing test package dependency.

0.3.4

  • Make sensors Dart 2 compliant.

0.3.3

  • Updated Gradle tooling to match Android Studio 3.1.2.

0.3.2

  • Added user acceleration sensor events (i.e. accelerometer without gravity).

0.3.1

  • Fixed Dart 2 type error with iOS sensor events.

0.3.0

  • Breaking change. Set SDK constraints to match the Flutter beta release.

0.2.1

  • Fixed warnings from the Dart 2.0 analyzer.
  • Simplified and upgraded Android project template to Android SDK 27.
  • Updated package description.

0.2.0

  • Breaking change. Upgraded to Gradle 4.1 and Android Studio Gradle plugin 3.0.1. Older Flutter projects need to upgrade their Gradle setup as well in order to use this version of the plugin. Instructions can be found here.

0.1.1

  • Added FLT prefix to iOS types.

0.1.0

  • Initial Open Source release.