diff --git a/docs/platform-integration/device/sensors.md b/docs/platform-integration/device/sensors.md index 81795681c0..09198f0cb8 100644 --- a/docs/platform-integration/device/sensors.md +++ b/docs/platform-integration/device/sensors.md @@ -54,6 +54,14 @@ The accelerometer sensor measures the acceleration of the device along its three The interface provides access to the sensor, and is available through the property. Both the `IAccelerometer` interface and `Accelerometer` class are contained in the `Microsoft.Maui.Devices.Sensors` namespace. +### Get started + +To access the accelerometer functionality the following platform-specific setup maybe required: + +[!INCLUDE [Android sensor high sampling rate](../includes/android-sensors.md)] + +### Monitor the accelerometer sensor + To start monitoring the accelerometer sensor, call the method. .NET MAUI sends accelerometer data changes to your app by raising the event. Use the method to stop monitoring the sensor. You can detect the monitoring state of the accelerometer with the property, which will be `true` if the accelerometer was started and is currently being monitored. The following code example demonstrates monitoring the accelerometer for changes: @@ -170,6 +178,9 @@ Even though this article is listing **shake** as a sensor, it isn't. The [accele The interface provides access to the sensor, and is available through the property. Both the `IAccelerometer` interface and `Accelerometer` class are contained in the `Microsoft.Maui.Devices.Sensors` namespace. +> [!NOTE] +> If your app needs to gather accelerometer sensor data using the sensor speed, you must declare the `HIGH_SAMPLING_RATE_SENSORS` permission. For more information, see [Accelerometer](#accelerometer). + The detect shake API uses raw readings from the accelerometer to calculate acceleration. It uses a simple queue mechanism to detect if 3/4ths of the recent accelerometer events occurred in the last half second. Acceleration is calculated by adding the square of the X, Y, and Z ($x^2+y^2+z^2$) readings from the accelerometer and comparing it to a specific threshold. To start monitoring the accelerometer sensor, call the method. When a shake is detected, the event is raised. Use the method to stop monitoring the sensor. You can detect the monitoring state of the accelerometer with the `IAccelerometer.IsMonitoring` property, which will be `true` if the accelerometer was started and is currently being monitored. @@ -190,6 +201,14 @@ The gyroscope sensor measures the angular rotation speed around the device's thr The interface provides access to the sensor, and is available through the property. Both the `IGyroscope` interface and `Gyroscope` class are contained in the `Microsoft.Maui.Devices.Sensors` namespace. +### Get started + +To access the gyroscope functionality the following platform-specific setup maybe required: + +[!INCLUDE [Android sensor high sampling rate](../includes/android-sensors.md)] + +### Monitor the gyroscope sensor + To start monitoring the gyroscope sensor, call the method. .NET MAUI sends gyroscope data changes to your app by raising the event. The data provided by this event is measured in rad/s (radian per second). Use the method to stop monitoring the sensor. You can detect the monitoring state of the gyroscope with the property, which will be `true` if the gyroscope was started and is currently being monitored. The following code example demonstrates monitoring the gyroscope: @@ -206,6 +225,14 @@ The magnetometer sensor indicates the device's orientation relative to Earth's m The interface provides access to the sensor, and is available through the property. Both the `IMagnetometer` interface and `Magnetometer` class are contained in the `Microsoft.Maui.Devices.Sensors` namespace. +### Get started + +To access the magnetometer functionality the following platform-specific setup maybe required: + +[!INCLUDE [Android sensor high sampling rate](../includes/android-sensors.md)] + +### Monitor the magnetometer sensor + To start monitoring the magnetometer sensor, call the method. .NET MAUI sends magnetometer data changes to your app by raising the event. The data provided by this event is measured in $µT$ (microteslas). Use the method to stop monitoring the sensor. You can detect the monitoring state of the magnetometer with the property, which will be `true` if the magnetometer was started and is currently being monitored. The following code example demonstrates monitoring the magnetometer: diff --git a/docs/platform-integration/includes/android-sensors.md b/docs/platform-integration/includes/android-sensors.md new file mode 100644 index 0000000000..4795ad9d11 --- /dev/null +++ b/docs/platform-integration/includes/android-sensors.md @@ -0,0 +1,49 @@ +--- +ms.topic: include +ms.date: 11/08/2023 +--- + + +# [Android](#tab/android) + +If your app targets Android 12+ (API 31+), the system places a 200 Hz limit on the refresh rate of data from this sensor. If your app needs to gather sensor data using the sensor speed, you must declare the `HIGH_SAMPLING_RATE_SENSORS` permission. You can configure the permission in the following ways: + +- Add the assembly-based permission: + + Open the _Platforms/Android/MainApplication.cs_ file and add the following assembly attribute after `using` directives: + + ```csharp + [assembly: UsesPermission(Android.Manifest.Permission.HighSamplingRateSensors)] + ``` + + \- or - + +- Update the Android Manifest: + + Open the _Platforms/Android/AndroidManifest.xml_ file and add the following line in the `manifest` node: + + ```xml + + ``` + + + +> [!NOTE] +> If a user turns off microphone access using the [device toggles](https://developer.android.com/training/permissions/explaining-access#toggles), motion and position sensors are always rate-limited, regardless of whether you declare the `HIGH_SAMPLING_RATE_SENSORS` permission. + +# [iOS/Mac Catalyst](#tab/macios) + +No setup is required. + +# [Windows](#tab/windows) + +No setup is required. + +----- +