From 1af73a6ce49b0eb24c940459015084990e0a9210 Mon Sep 17 00:00:00 2001 From: Cristian Barbarosie Date: Wed, 5 Apr 2023 07:59:44 +0100 Subject: [PATCH] docs(sensor_plus): improve description of accelerometer (#1425) Co-authored-by: Joachim Nohl <43643339+nohli@users.noreply.github.com> --- docs/sensors_plus/usage.mdx | 31 +++++++++++++------ .../sensors_plus/example/lib/main.dart | 30 +++++++++--------- 2 files changed, 36 insertions(+), 25 deletions(-) diff --git a/docs/sensors_plus/usage.mdx b/docs/sensors_plus/usage.mdx index e1643583c2..2afcd1ccb6 100644 --- a/docs/sensors_plus/usage.mdx +++ b/docs/sensors_plus/usage.mdx @@ -11,12 +11,23 @@ file](https://plus.fluttercommunity.dev/docs/overview). This will expose such classes of sensor events through a set of streams: -- `AccelerometerEvent` describes the velocity of the device, including the - effects of gravity. Put simply, you can use accelerometer readings to tell if - the device is moving in a particular direction. -- `UserAccelerometerEvent` also describes the velocity of the device, but don't - include gravity. They can also be thought of as just the user's affect on the - device. +- `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. @@ -30,15 +41,15 @@ respectively. ```dart import 'package:sensors_plus/sensors_plus.dart'; -accelerometerEvents.listen((AccelerometerEvent event) { +userAccelerometerEvents.listen((UserAccelerometerEvent event) { print(event); }); -// [AccelerometerEvent (x: 0.0, y: 9.8, z: 0.0)] +// [UserAccelerometerEvent (x: 0.0, y: 0.0, z: 0.0)] -userAccelerometerEvents.listen((UserAccelerometerEvent event) { +accelerometerEvents.listen((AccelerometerEvent event) { print(event); }); -// [UserAccelerometerEvent (x: 0.0, y: 0.0, z: 0.0)] +// [AccelerometerEvent (x: 0.0, y: 9.8, z: 0.0)] gyroscopeEvents.listen((GyroscopeEvent event) { print(event); diff --git a/packages/sensors_plus/sensors_plus/example/lib/main.dart b/packages/sensors_plus/sensors_plus/example/lib/main.dart index 893d8373e8..2045bc2965 100644 --- a/packages/sensors_plus/sensors_plus/example/lib/main.dart +++ b/packages/sensors_plus/sensors_plus/example/lib/main.dart @@ -44,21 +44,21 @@ class _MyHomePageState extends State { static const int _snakeColumns = 20; static const double _snakeCellSize = 10.0; - List? _accelerometerValues; List? _userAccelerometerValues; + List? _accelerometerValues; List? _gyroscopeValues; List? _magnetometerValues; final _streamSubscriptions = >[]; @override Widget build(BuildContext context) { + final userAccelerometer = _userAccelerometerValues + ?.map((double v) => v.toStringAsFixed(1)) + .toList(); final accelerometer = _accelerometerValues?.map((double v) => v.toStringAsFixed(1)).toList(); final gyroscope = _gyroscopeValues?.map((double v) => v.toStringAsFixed(1)).toList(); - final userAccelerometer = _userAccelerometerValues - ?.map((double v) => v.toStringAsFixed(1)) - .toList(); final magnetometer = _magnetometerValues?.map((double v) => v.toStringAsFixed(1)).toList(); @@ -90,7 +90,7 @@ class _MyHomePageState extends State { child: Row( mainAxisAlignment: MainAxisAlignment.spaceBetween, children: [ - Text('Accelerometer: $accelerometer'), + Text('UserAccelerometer: $userAccelerometer'), ], ), ), @@ -99,7 +99,7 @@ class _MyHomePageState extends State { child: Row( mainAxisAlignment: MainAxisAlignment.spaceBetween, children: [ - Text('UserAccelerometer: $userAccelerometer'), + Text('Accelerometer: $accelerometer'), ], ), ), @@ -138,28 +138,28 @@ class _MyHomePageState extends State { void initState() { super.initState(); _streamSubscriptions.add( - accelerometerEvents.listen( - (AccelerometerEvent event) { + userAccelerometerEvents.listen( + (UserAccelerometerEvent event) { setState(() { - _accelerometerValues = [event.x, event.y, event.z]; + _userAccelerometerValues = [event.x, event.y, event.z]; }); }, ), ); _streamSubscriptions.add( - gyroscopeEvents.listen( - (GyroscopeEvent event) { + accelerometerEvents.listen( + (AccelerometerEvent event) { setState(() { - _gyroscopeValues = [event.x, event.y, event.z]; + _accelerometerValues = [event.x, event.y, event.z]; }); }, ), ); _streamSubscriptions.add( - userAccelerometerEvents.listen( - (UserAccelerometerEvent event) { + gyroscopeEvents.listen( + (GyroscopeEvent event) { setState(() { - _userAccelerometerValues = [event.x, event.y, event.z]; + _gyroscopeValues = [event.x, event.y, event.z]; }); }, ),