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];
});
},
),