From 26c4b237430ca3a55813a4a8da98a9ac911f1fe1 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Mon, 9 Aug 2021 12:37:16 -0700 Subject: [PATCH 1/5] Port sensor related essentials to sensor.md --- docs/TOC.yml | 5 + docs/essentials/accelerometer.md | 81 --- docs/essentials/barometer.md | 91 ---- docs/essentials/compass.md | 89 ---- docs/essentials/detect-shake.md | 70 --- docs/essentials/gyroscope.md | 68 --- docs/essentials/includes/sensor-speed.md | 13 - docs/essentials/index.md | 94 ++-- docs/essentials/magnetometer.md | 70 --- docs/essentials/main-thread.md | 2 +- docs/essentials/orientation-sensor.md | 102 ---- docs/essentials/platform-feature-support.md | 84 +-- docs/essentials/sensors.md | 545 ++++++++++++++++++++ 13 files changed, 645 insertions(+), 669 deletions(-) delete mode 100644 docs/essentials/accelerometer.md delete mode 100644 docs/essentials/barometer.md delete mode 100644 docs/essentials/compass.md delete mode 100644 docs/essentials/detect-shake.md delete mode 100644 docs/essentials/gyroscope.md delete mode 100644 docs/essentials/includes/sensor-speed.md delete mode 100644 docs/essentials/magnetometer.md delete mode 100644 docs/essentials/orientation-sensor.md create mode 100644 docs/essentials/sensors.md diff --git a/docs/TOC.yml b/docs/TOC.yml index ac185ff87..180a85cb9 100644 --- a/docs/TOC.yml +++ b/docs/TOC.yml @@ -26,3 +26,8 @@ items: - name: Customize controls href: user-interface/handlers/customize.md + - name: Device features + expanded: true + items: + - name: Sensors + href: essentials/sensors.md diff --git a/docs/essentials/accelerometer.md b/docs/essentials/accelerometer.md deleted file mode 100644 index e820feaa2..000000000 --- a/docs/essentials/accelerometer.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Accelerometer" -description: "The Accelerometer class in Microsoft.Maui.Essentials lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in 3D space." -ms.date: 08/02/2021 -no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials", "A", "G", "X", "Y", "Z"] ---- - -# Accelerometer - -The `Microsoft.Maui.Essentials.Accelerometer` class lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in 3D space. - -## Get started - -[!INCLUDE [get-started](includes/get-started.md)] - -## Using Accelerometer - -[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] - -The accelerometer functionality works by calling the `Start` and `Stop` methods to listen for changes to the acceleration. Any changes are sent back through the `ReadingChanged` event. Here's a sample of using the accelerometer: - -```csharp -public class AccelerometerTest -{ - // Set speed delay for monitoring changes. - SensorSpeed speed = SensorSpeed.UI; - - public AccelerometerTest() - { - // Register for reading changes, be sure to unsubscribe when finished - Accelerometer.ReadingChanged += Accelerometer_ReadingChanged; - } - - void Accelerometer_ReadingChanged(object sender, AccelerometerChangedEventArgs e) - { - var data = e.Reading; - Console.WriteLine($"Reading: X: {data.Acceleration.X}, Y: {data.Acceleration.Y}, Z: {data.Acceleration.Z}"); - // Process Acceleration X, Y, and Z - } - - public void ToggleAccelerometer() - { - try - { - if (Accelerometer.IsMonitoring) - Accelerometer.Stop(); - else - Accelerometer.Start(speed); - } - catch (FeatureNotSupportedException fnsEx) - { - // Feature not supported on device - } - catch (Exception ex) - { - // Other error has occurred. - } - } -} -``` - -Accelerometer readings are reported back in **G**. A **G** is a unit of gravitation force equal to the gravity exerted by the earth's gravitational field $(9.81 m/s^2)$. - -The coordinate-system is defined relative to the screen of the device in its default orientation. The axes aren't swapped when the device's screen orientation changes. - -The **X** axis is horizontal and points to the right, the **Y** axis is vertical and points up and the **Z** axis points towards the outside of the front face of the screen. In this system, coordinates behind the screen have negative **Z** values. - -Examples: - -- When the device lies flat on a table and is pushed on its left side toward the right, the **X** acceleration value is positive. - -- When the device lies flat on a table, the acceleration value is +1.00 G or $(+9.81 m/s^2)$, which correspond to the acceleration of the device $(0 m/s^2)$ minus the force of gravity $(-9.81 m/s^2)$ and normalized as in G. - -- When the device lies flat on a table and is pushed toward the sky with an acceleration of **A** $m/s^2$, the acceleration value is equal to $A+9.81$ which corresponds to the acceleration of the device $(+A m/s^2)$ minus the force of gravity $(-9.81 m/s^2)$ and normalized in **G**. - -[!INCLUDE [sensor-speed](includes/sensor-speed.md)] - -## API - -- [Accelerometer source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/Accelerometer) - diff --git a/docs/essentials/barometer.md b/docs/essentials/barometer.md deleted file mode 100644 index 5a9ede43e..000000000 --- a/docs/essentials/barometer.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "Barometer" -description: "Describes the Barometer class in the Microsoft.Maui.Essentials namespace, which lets you monitor the device's barometer sensor." -ms.date: 08/04/2021 -no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] ---- - -# Barometer - -The `Barometer` class lets you monitor the device's barometer sensor, which measures pressure. - -## Get started - -[!INCLUDE [get-started](includes/get-started.md)] - -## Using Barometer - -[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] - -The Barometer functionality works by calling the `Start` and `Stop` methods to listen for changes to the barometer's pressure reading. The pressure reading is represented in hectopascals. Any changes are sent back through the `ReadingChanged` event. The following code example demonstrates reading the barometer sensor: - -```csharp -public class BarometerTest -{ - // Set speed delay for monitoring changes. - SensorSpeed speed = SensorSpeed.UI; - - public BarometerTest() - { - // Register for reading changes. - Barometer.ReadingChanged += Barometer_ReadingChanged; - } - - void Barometer_ReadingChanged(object sender, BarometerChangedEventArgs e) - { - var data = e.Reading; - // Process Pressure - Console.WriteLine($"Reading: Pressure: {data.PressureInHectopascals} hectopascals"); - } - - public void ToggleBarometer() - { - try - { - if (Barometer.IsMonitoring) - Barometer.Stop(); - else - Barometer.Start(speed); - } - catch (FeatureNotSupportedException fnsEx) - { - // Feature not supported on device - } - catch (Exception ex) - { - // Other error has occurred. - } - } -} -``` - -[!INCLUDE [sensor-speed](includes/sensor-speed.md)] - -## Platform implementation specifics - -This section describes platform-specific implementation details related to the barometer. - - - -# [Android](#tab/android) - -No platform-specific implementation details. - -# [iOS](#tab/ios) - -This API uses [CMAltimeter](https://developer.apple.com/documentation/coremotion/cmaltimeter#//apple_ref/occ/cl/CMAltimeter) to monitor pressure changes, which is a hardware feature that was added to iPhone 6 and newer devices. A `FeatureNotSupportedException` will be thrown on devices that don't support the altimeter. - -`SensorSpeed` is not used as it is not supported on iOS. - -# [Windows](#tab/windows) - -No platform-specific implementation details. - ------ - - - -## API - -- [Barometer source code](https://github.com/dotnet/maui/tree/main/src/Essentials/src/Barometer) - diff --git a/docs/essentials/compass.md b/docs/essentials/compass.md deleted file mode 100644 index 5d8038e29..000000000 --- a/docs/essentials/compass.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Compass" -description: "Describes the Compass class in Microsoft.Maui.Essentials, which lets you monitor the device's magnetic north heading." -ms.date: 11/04/2018 -no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] ---- - -# Compass - -The `Compass` class lets you monitor the device's magnetic north heading. - -## Get started - -[!INCLUDE [get-started](includes/get-started.md)] - -## Using Compass - -[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] - -The Compass functionality works by calling the `Start` and `Stop` methods to listen for changes to the compass. Any changes are sent back through the `ReadingChanged` event. Here is an example: - -```csharp -public class CompassTest -{ - // Set speed delay for monitoring changes. - SensorSpeed speed = SensorSpeed.UI; - - public CompassTest() - { - // Register for reading changes, be sure to unsubscribe when finished - Compass.ReadingChanged += Compass_ReadingChanged; - } - - void Compass_ReadingChanged(object sender, CompassChangedEventArgs e) - { - var data = e.Reading; - Console.WriteLine($"Reading: {data.HeadingMagneticNorth} degrees"); - // Process Heading Magnetic North - } - - public void ToggleCompass() - { - try - { - if (Compass.IsMonitoring) - Compass.Stop(); - else - Compass.Start(speed); - } - catch (FeatureNotSupportedException fnsEx) - { - // Feature not supported on device - } - catch (Exception ex) - { - // Some other exception has occurred - } - } -} -``` - -[!INCLUDE [sensor-speed](includes/sensor-speed.md)] - -## Platform implementation specifics - -# [Android](#tab/android) - -Android does not provide an API for retrieving the compass heading. We utilize the accelerometer and magnetometer to calculate the magnetic north heading, which is recommended by Google. - -In rare instances, you maybe see inconsistent results because the sensors need to be calibrated, which involves moving your device in a figure-8 motion. The best way of doing this is to open Google Maps, tap on the dot for your location, and select **Calibrate compass**. - -Running multiple sensors from your app at the same time may adjust the sensor speed. - -## Low Pass Filter - -Due to how the Android compass values are updated and calculated there may be a need to smooth out the values. A _Low Pass Filter_ can be applied that averages the sine and cosine values of the angles and can be turned on by using the `Start` method overload, which accepts the `bool applyLowPassFilter` parameter: - -```csharp -Compass.Start(SensorSpeed.UI, applyLowPassFilter: true); -``` - -This is only applied on the Android platform, and the parameter is ignored on iOS and UWP. More information can be read [here](https://github.com/xamarin/Essentials/pull/354#issuecomment-405316860). - --------------- - -## API - -- [Compass source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Compass) - diff --git a/docs/essentials/detect-shake.md b/docs/essentials/detect-shake.md deleted file mode 100644 index 2ca85b2b2..000000000 --- a/docs/essentials/detect-shake.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Detect Shake" -description: "The Accelerometer class in Microsoft.Maui.Essentials enables you to detect a shake movement of the device." -ms.date: 05/28/2019 -no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] ---- - -# Detect Shake - -The `[Accelerometer](accelerometer.md)` class lets you monitor the device's accelerometer sensor, which indicates the acceleration of the device in three-dimensional space. Additionally, it enables you to register for events when the user shakes the device. - -## Get started - -[!INCLUDE [get-started](includes/get-started.md)] - -## Using Detect Shake - -[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] - -To detect a shake of the device you must use the Accelerometer functionality by calling the `Start` and `Stop` methods to listen for changes to the acceleration and to detect a shake. Any time a shake is detected a `ShakeDetected` event will fire. It is recommended to use `Game` or faster for the `SensorSpeed`. Here is sample usage: - -```csharp - -public class DetectShakeTest -{ - // Set speed delay for monitoring changes. - SensorSpeed speed = SensorSpeed.Game; - - public DetectShakeTest() - { - // Register for reading changes, be sure to unsubscribe when finished - Accelerometer.ShakeDetected += Accelerometer_ShakeDetected ; - } - - void Accelerometer_ShakeDetected (object sender, EventArgs e) - { - // Process shake event - } - - public void ToggleAccelerometer() - { - try - { - if (Accelerometer.IsMonitoring) - Accelerometer.Stop(); - else - Accelerometer.Start(speed); - } - catch (FeatureNotSupportedException fnsEx) - { - // Feature not supported on device - } - catch (Exception ex) - { - // Other error has occurred. - } - } -} -``` - -[!INCLUDE [sensor-speed](includes/sensor-speed.md)] - -## Implementation Details - -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 readings from the accelerometer and comparing it to a specific threashold. - -## API - -- [Accelerometer source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Accelerometer) - diff --git a/docs/essentials/gyroscope.md b/docs/essentials/gyroscope.md deleted file mode 100644 index e4412ec75..000000000 --- a/docs/essentials/gyroscope.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: "Gyroscope" -description: "The Gyroscope class in Microsoft.Maui.Essentials lets you monitor the device's gyroscope sensor, which measures rotation around the device's three primary axes." -ms.date: 11/04/2018 -no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] ---- - -# Gyroscope - -The `Gyroscope` class lets you monitor the device's gyroscope sensor which is the rotation around the device's three primary axes. - -## Get started - -[!INCLUDE [get-started](includes/get-started.md)] - -## Using Gyroscope - -[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] - -The Gyroscope functionality works by calling the `Start` and `Stop` methods to listen for changes to the gyroscope. Any changes are sent back through the `ReadingChanged` event in rad/s. Here is sample usage: - -```csharp - -public class GyroscopeTest -{ - // Set speed delay for monitoring changes. - SensorSpeed speed = SensorSpeed.UI; - - public GyroscopeTest() - { - // Register for reading changes. - Gyroscope.ReadingChanged += Gyroscope_ReadingChanged; - } - - void Gyroscope_ReadingChanged(object sender, GyroscopeChangedEventArgs e) - { - var data = e.Reading; - // Process Angular Velocity X, Y, and Z reported in rad/s - Console.WriteLine($"Reading: X: {data.AngularVelocity.X}, Y: {data.AngularVelocity.Y}, Z: {data.AngularVelocity.Z}"); - } - - public void ToggleGyroscope() - { - try - { - if (Gyroscope.IsMonitoring) - Gyroscope.Stop(); - else - Gyroscope.Start(speed); - } - catch (FeatureNotSupportedException fnsEx) - { - // Feature not supported on device - } - catch (Exception ex) - { - // Other error has occurred. - } - } -} -``` - -[!INCLUDE [sensor-speed](includes/sensor-speed.md)] - -## API - -- [Gyroscope source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Gyroscope) - diff --git a/docs/essentials/includes/sensor-speed.md b/docs/essentials/includes/sensor-speed.md deleted file mode 100644 index d27feda96..000000000 --- a/docs/essentials/includes/sensor-speed.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -ms.topic: include -ms.date: 08/02/2021 ---- - -## Sensor Speed - -- **Fastest** – Get the sensor data as fast as possible (not guaranteed to return on UI thread). -- **Game** – Rate suitable for games (not guaranteed to return on UI thread). -- **Default** – Default rate suitable for screen orientation changes. -- **UI** – Rate suitable for general user interface. - -If your event handler is not guaranteed to run on the UI thread, and if the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](../main-thread.md) method to run that code on the UI thread. diff --git a/docs/essentials/index.md b/docs/essentials/index.md index bf4bbc9a0..ac4b4f86c 100644 --- a/docs/essentials/index.md +++ b/docs/essentials/index.md @@ -19,48 +19,58 @@ Follow the [getting started guide](get-started.md) to install the **Xamarin.Esse Follow the guides to integrate these Xamarin.Essentials features into your applications: -* [Accelerometer](accelerometer.md?context=xamarin/xamarin-forms) – Retrieve acceleration data of the device in three dimensional space. -* [App Actions](app-actions.md?context=xamarin/xamarin-forms) – Get and set shortcuts for the application. -* [App Information](app-information.md?context=xamarin/xamarin-forms) – Find out information about the application. -* [App Theme](app-theme.md?context=xamarin/xamarin-forms) – Detect the current theme requested for the application. -* [Barometer](barometer.md?context=xamarin/xamarin-forms) – Monitor the barometer for pressure changes. -* [Battery](battery.md?context=xamarin/xamarin-forms) – Easily detect battery level, source, and state. -* [Clipboard](clipboard.md?context=xamarin/xamarin-forms) – Quickly and easily set or read text on the clipboard. -* [Color Converters](color-converters.md?context=xamarin/xamarin-forms) – Helper methods for System.Drawing.Color. -* [Compass](compass.md?context=xamarin/xamarin-forms) – Monitor compass for changes. -* [Connectivity](connectivity.md?context=xamarin/xamarin-forms) – Check connectivity state and detect changes. -* [Contacts](contacts.md?context=xamarin/xamarin-forms) – Retrieve information about a contact on the device. -* [Detect Shake](detect-shake.md?context=xamarin/xamarin-forms) – Detect a shake movement of the device. -* [Device Display Information](device-display.md?context=xamarin/xamarin-forms) – Get the device's screen metrics and orientation. -* [Device Information](device-information.md?context=xamarin/xamarin-forms) – Find out about the device with ease. -* [Email](email.md?context=xamarin/xamarin-forms) – Easily send email messages. -* [File Picker](file-picker.md?context=xamarin/xamarin-forms) – Allow user to pick files from the device. -* [File System Helpers](file-system-helpers.md?context=xamarin/xamarin-forms) – Easily save files to app data. -* [Flashlight](flashlight.md?context=xamarin/xamarin-forms) – A simple way to turn the flashlight on/off. -* [Geocoding](geocoding.md?context=xamarin/xamarin-forms) – Geocode and reverse geocode addresses and coordinates. -* [Geolocation](geolocation.md?context=xamarin/xamarin-forms) – Retrieve the device's GPS location. -* [Gyroscope](gyroscope.md?context=xamarin/xamarin-forms) – Track rotation around the device's three primary axes. -* [Haptic Feedback](haptic-feedback.md?context=xamarin/xamarin-forms) – Control click and long press haptics. -* [Launcher](launcher.md?context=xamarin/xamarin-forms) – Enables an application to open a URI by the system. -* [Magnetometer](magnetometer.md?context=xamarin/xamarin-forms) – Detect device's orientation relative to Earth's magnetic field. -* [MainThread](main-thread.md?content=xamarin/xamarin-forms) – Run code on the application's main thread. -* [Maps](maps.md?content=xamarin/xamarin-forms) – Open the maps application to a specific location. -* [Media Picker](media-picker.md?context=xamarin/xamarin-forms) – Allow user to pick or take photos and videos. -* [Open Browser](open-browser.md?context=xamarin/xamarin-forms) – Quickly and easily open a browser to a specific website. -* [Orientation Sensor](orientation-sensor.md?context=xamarin/xamarin-forms) – Retrieve the orientation of the device in three dimensional space. -* [Permissions](permissions.md?context=xamarin/xamarin-forms) – Check and request permissions from users. -* [Phone Dialer](phone-dialer.md?context=xamarin/xamarin-forms) – Open the phone dialer. -* [Platform Extensions](platform-extensions.md?context=xamarin/xamarin-forms) – Helper methods for converting Rect, Size, and Point. -* [Preferences](preferences.md?context=xamarin/xamarin-forms) – Quickly and easily add persistent preferences. -* [Screenshot](Screenshot.md?context=xamarin/xamarin-forms) – Take a capture of the current display of the application. -* [Secure Storage](secure-storage.md?context=xamarin/xamarin-forms) – Securely store data. -* [Share](share.md?context=xamarin/xamarin-forms) – Send text and website links to other apps. -* [SMS](sms.md?context=xamarin/xamarin-forms) – Create an SMS message for sending. -* [Text-to-Speech](text-to-speech.md?context=xamarin/xamarin-forms) – Vocalize text on the device. -* [Unit Converters](unit-converters.md?context=xamarin/xamarin-forms) – Helper methods to convert units. -* [Version Tracking](version-tracking.md?context=xamarin/xamarin-forms) – Track the applications version and build numbers. -* [Vibrate](vibrate.md?context=xamarin/xamarin-forms) – Make the device vibrate. -* [Web Authenticator](web-authenticator.md?context=xamarin/xamarin-forms) - Start web authentication flows and listen for a callback. +- **Sensors** + - [Accelerometer](sensors.md#accelerometer)\ + Retrieve acceleration data of the device in three dimensional space. + - [Barometer](sensors.md#barometer)\ + Monitor the barometer for pressure changes. + - [Compass](sensors.md#compass)\ + Monitor compass for changes. + - [Detect Shake](sensors.md#shake)\ + Detect a shake movement of the device. + - [Gyroscope](sensors.md#gyroscope)\ + Track rotation around the device's three primary axes. + - [Magnetometer](sensors.md#magnetometer)\ + Detect device's orientation relative to Earth's magnetic field. + - [Orientation](sensors.md#orientation)\ + Retrieve the orientation of the device in three dimensional space. + +- **TODO** + - [App Actions](app-actions.md?context=xamarin/xamarin-forms) – Get and set shortcuts for the application. + - [App Information](app-information.md?context=xamarin/xamarin-forms) – Find out information about the application. + - [App Theme](app-theme.md?context=xamarin/xamarin-forms) – Detect the current theme requested for the application. + - [Battery](battery.md?context=xamarin/xamarin-forms) – Easily detect battery level, source, and state. + - [Clipboard](clipboard.md?context=xamarin/xamarin-forms) – Quickly and easily set or read text on the clipboard. + - [Color Converters](color-converters.md?context=xamarin/xamarin-forms) – Helper methods for System.Drawing.Color. + - [Connectivity](connectivity.md?context=xamarin/xamarin-forms) – Check connectivity state and detect changes. + - [Contacts](contacts.md?context=xamarin/xamarin-forms) – Retrieve information about a contact on the device. + - [Device Display Information](device-display.md?context=xamarin/xamarin-forms) – Get the device's screen metrics and orientation. + - [Device Information](device-information.md?context=xamarin/xamarin-forms) – Find out about the device with ease. + - [Email](email.md?context=xamarin/xamarin-forms) – Easily send email messages. + - [File Picker](file-picker.md?context=xamarin/xamarin-forms) – Allow user to pick files from the device. + - [File System Helpers](file-system-helpers.md?context=xamarin/xamarin-forms) – Easily save files to app data. + - [Flashlight](flashlight.md?context=xamarin/xamarin-forms) – A simple way to turn the flashlight on/off. + - [Geocoding](geocoding.md?context=xamarin/xamarin-forms) – Geocode and reverse geocode addresses and coordinates. + - [Geolocation](geolocation.md?context=xamarin/xamarin-forms) – Retrieve the device's GPS location. + - [Haptic Feedback](haptic-feedback.md?context=xamarin/xamarin-forms) – Control click and long press haptics. + - [Launcher](launcher.md?context=xamarin/xamarin-forms) – Enables an application to open a URI by the system. + - [MainThread](main-thread.md?content=xamarin/xamarin-forms) – Run code on the application's main thread. + - [Maps](maps.md?content=xamarin/xamarin-forms) – Open the maps application to a specific location. + - [Media Picker](media-picker.md?context=xamarin/xamarin-forms) – Allow user to pick or take photos and videos. + - [Open Browser](open-browser.md?context=xamarin/xamarin-forms) – Quickly and easily open a browser to a specific website. + - [Permissions](permissions.md?context=xamarin/xamarin-forms) – Check and request permissions from users. + - [Phone Dialer](phone-dialer.md?context=xamarin/xamarin-forms) – Open the phone dialer. + - [Platform Extensions](platform-extensions.md?context=xamarin/xamarin-forms) – Helper methods for converting Rect, Size, and Point. + - [Preferences](preferences.md?context=xamarin/xamarin-forms) – Quickly and easily add persistent preferences. + - [Screenshot](Screenshot.md?context=xamarin/xamarin-forms) – Take a capture of the current display of the application. + - [Secure Storage](secure-storage.md?context=xamarin/xamarin-forms) – Securely store data. + - [Share](share.md?context=xamarin/xamarin-forms) – Send text and website links to other apps. + - [SMS](sms.md?context=xamarin/xamarin-forms) – Create an SMS message for sending. + - [Text-to-Speech](text-to-speech.md?context=xamarin/xamarin-forms) – Vocalize text on the device. + - [Unit Converters](unit-converters.md?context=xamarin/xamarin-forms) – Helper methods to convert units. + - [Version Tracking](version-tracking.md?context=xamarin/xamarin-forms) – Track the applications version and build numbers. + - [Vibrate](vibrate.md?context=xamarin/xamarin-forms) – Make the device vibrate. + - [Web Authenticator](web-authenticator.md?context=xamarin/xamarin-forms) - Start web authentication flows and listen for a callback. ## [Troubleshooting](troubleshooting.md?context=xamarin/xamarin-forms) diff --git a/docs/essentials/magnetometer.md b/docs/essentials/magnetometer.md deleted file mode 100644 index c308331ec..000000000 --- a/docs/essentials/magnetometer.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Magnetometer" -description: "The Magnetometer class in Microsoft.Maui.Essentials lets you monitor the device's magnetometer sensor, which indicates the device's orientation relative to Earth's magnetic field." -ms.date: 11/04/2018 -no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] ---- - -# Magnetometer - -The `Magnetometer` class lets you monitor the device's magnetometer sensor which indicates the device's orientation relative to Earth's magnetic field. - -## Get started - -[!INCLUDE [get-started](includes/get-started.md)] - -## Using Magnetometer - -[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] - -The Magnetometer functionality works by calling the `Start` and `Stop` methods to listen for changes to the magnetometer. Any changes are sent back through the `ReadingChanged` event. Here is sample usage: - -```csharp - -public class MagnetometerTest -{ - // Set speed delay for monitoring changes. - SensorSpeed speed = SensorSpeed.UI; - - public MagnetometerTest() - { - // Register for reading changes. - Magnetometer.ReadingChanged += Magnetometer_ReadingChanged; - } - - void Magnetometer_ReadingChanged(object sender, MagnetometerChangedEventArgs e) - { - var data = e.Reading; - // Process MagneticField X, Y, and Z - Console.WriteLine($"Reading: X: {data.MagneticField.X}, Y: {data.MagneticField.Y}, Z: {data.MagneticField.Z}"); - } - - public void ToggleMagnetometer() - { - try - { - if (Magnetometer.IsMonitoring) - Magnetometer.Stop(); - else - Magnetometer.Start(speed); - } - catch (FeatureNotSupportedException fnsEx) - { - // Feature not supported on device - } - catch (Exception ex) - { - // Other error has occurred. - } - } -} -``` - -All data is returned in µT (microteslas). - -[!INCLUDE [sensor-speed](includes/sensor-speed.md)] - -## API - -- [Magnetometer source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/Magnetometer) - diff --git a/docs/essentials/main-thread.md b/docs/essentials/main-thread.md index 2926b4f01..5b29140e5 100644 --- a/docs/essentials/main-thread.md +++ b/docs/essentials/main-thread.md @@ -13,7 +13,7 @@ The `MainThread` class allows applications to run code on the main thread of exe Most operating systems — including iOS, Android, and the Universal Windows Platform — use a single-threading model for code involving the user interface. This model is necessary to properly serialize user-interface events, including keystrokes and touch input. This thread is often called the _main thread_ or the _user-interface thread_ or the _UI thread_. The disadvantage of this model is that all code that accesses user interface elements must run on the application's main thread. -Applications sometimes need to use events that call the event handler on a secondary thread of execution. (The Xamarin.Essentials classes [`Accelerometer`](accelerometer.md), [`Compass`](compass.md), [`Gyroscope`](gyroscope.md), [`Magnetometer`](magnetometer.md), and [`OrientationSensor`](orientation-sensor.md) all might return information on a secondary thread when used with faster speeds.) If the event handler needs to access user-interface elements, it must run that code on the main thread. The `MainThread` class allows the application to run this code on the main thread. +Applications sometimes need to use events that call the event handler on a secondary thread of execution. (The Xamarin.Essentials classes [`Accelerometer`](sensors.md#accelerometer), [`Compass`](sensors.md#compass), [`Gyroscope`](sensors.md#gyroscope), [`Magnetometer`](sensors.md#magnetometer), and [`OrientationSensor`](sensors.md#orientation) all might return information on a secondary thread when used with faster speeds.) If the event handler needs to access user-interface elements, it must run that code on the main thread. The `MainThread` class allows the application to run this code on the main thread. ## Get started diff --git a/docs/essentials/orientation-sensor.md b/docs/essentials/orientation-sensor.md deleted file mode 100644 index 2157c8122..000000000 --- a/docs/essentials/orientation-sensor.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "OrientationSensor" -description: "The OrientationSensor class lets you monitor the orientation of a device in three-dimensional space." -ms.date: 11/04/2018 -no-loc: ["Microsoft.Maui", "Microsoft.Maui.Essentials"] ---- -# OrientationSensor - -The `OrientationSensor` class lets you monitor the orientation of a device in three dimensional space. - -> [!NOTE] -> This class is for determining the orientation of a device in 3D space. If you need to determine if the device's video display is in portrait or landscape mode, use the `Orientation` property of the `ScreenMetrics` object available from the [`DeviceDisplay`](device-display.md) class. - -## Get started - -[!INCLUDE [get-started](includes/get-started.md)] - -## Using OrientationSensor - -[!INCLUDE [essentials-namespace](includes/essentials-namespace.md)] - -The `OrientationSensor` is enabled by calling the `Start` method to monitor changes to the device's orientation, and disabled by calling the `Stop` method. Any changes are sent back through the `ReadingChanged` event. Here is a sample usage: - -```csharp - -public class OrientationSensorTest -{ - // Set speed delay for monitoring changes. - SensorSpeed speed = SensorSpeed.UI; - - public OrientationSensorTest() - { - // Register for reading changes, be sure to unsubscribe when finished - OrientationSensor.ReadingChanged += OrientationSensor_ReadingChanged; - } - - void OrientationSensor_ReadingChanged(object sender, OrientationSensorChangedEventArgs e) - { - var data = e.Reading; - Console.WriteLine($"Reading: X: {data.Orientation.X}, Y: {data.Orientation.Y}, Z: {data.Orientation.Z}, W: {data.Orientation.W}"); - // Process Orientation quaternion (X, Y, Z, and W) - } - - public void ToggleOrientationSensor() - { - try - { - if (OrientationSensor.IsMonitoring) - OrientationSensor.Stop(); - else - OrientationSensor.Start(speed); - } - catch (FeatureNotSupportedException fnsEx) - { - // Feature not supported on device - } - catch (Exception ex) - { - // Other error has occurred. - } - } -} -``` - -`OrientationSensor` readings are reported back in the form of a [`Quaternion`](xref:System.Numerics.Quaternion) that describes the orientation of the device based on two 3D coordinate systems: - -The device (generally a phone or tablet) has a 3D coordinate system with the following axes: - -- The positive X axis points to the right of the display in portrait mode. -- The positive Y axis points to the top of the device in portrait mode. -- The positive Z axis points out of the screen. - -The 3D coordinate system of the Earth has the following axes: - -- The positive X axis is tangent to the surface of the Earth and points east. -- The positive Y axis is also tangent to the surface of the Earth and points north. -- The positive Z axis is perpendicular to the surface of the Earth and points up. - -The `Quaternion` describes the rotation of the device's coordinate system relative to the Earth's coordinate system. - -A `Quaternion` value is very closely related to rotation around an axis. If an axis of rotation is the normalized vector (ax, ay, az), and the rotation angle is Θ, then the (X, Y, Z, W) components of the quaternion are: - -(ax·sin(Θ/2), ay·sin(Θ/2), az·sin(Θ/2), cos(Θ/2)) - -These are right-hand coordinate systems, so with the thumb of the right hand pointed in the positive direction of the rotation axis, the curve of the fingers indicate the direction of rotation for positive angles. - -Examples: - -- When the device lies flat on a table with its screen facing up, with the top of the device (in portrait mode) pointing north, the two coordinate systems are aligned. The `Quaternion` value represents the identity quaternion (0, 0, 0, 1). All rotations can be analyzed relative to this position. - -- When the device lies flat on a table with its screen facing up, and the top of the device (in portrait mode) pointing west, the `Quaternion` value is (0, 0, 0.707, 0.707). The device has been rotated 90 degrees around the Z axis of the Earth. - -- When the device is held upright so that the top (in portrait mode) points towards the sky, and the back of the device faces north, the device has been rotated 90 degrees around the X axis. The `Quaternion` value is (0.707, 0, 0, 0.707). - -- If the device is positioned so its left edge is on a table, and the top points north, the device has been rotated –90 degrees around the Y axis (or 90 degrees around the negative Y axis). The `Quaternion` value is (0, -0.707, 0, 0.707). - -[!INCLUDE [sensor-speed](includes/sensor-speed.md)] - -## API - -- [OrientationSensor source code](https://github.com/xamarin/Essentials/tree/main/Xamarin.Essentials/OrientationSensor) - diff --git a/docs/essentials/platform-feature-support.md b/docs/essentials/platform-feature-support.md index 740966991..b9eac2920 100644 --- a/docs/essentials/platform-feature-support.md +++ b/docs/essentials/platform-feature-support.md @@ -37,45 +37,45 @@ Icon Guide: | Feature | Android | iOS | UWP | watchOS | tvOS | Tizen | macOS | |-------------------------------------------------------------------------------|:-------:|:---:|:---:|:-------:|:----:|:-----:|:-----:| -| [Accelerometer](accelerometer.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | -| [App Actions](app-actions.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ❌ | -| [App Information](app-information.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | ✔️ | -| [App Theme](app-theme.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | -| [Barometer](barometer.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | -| [Battery](battery.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ⚠️ | ❌ | ⚠️ | ✔️ | -| [Clipboard](clipboard.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ✔️ | -| [Color Converters](color-converters.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Compass](compass.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | -| [Connectivity](connectivity.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | ✔️ | -| [Contacts](contacts.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | -| [Detect Shake](detect-shake.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | -| [Device Display Information](device-display.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ✔️ | -| [Device Information](device-information.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Email](email.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [File Picker](file-picker.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [File System Helpers](file-system-helpers.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Flashlight](flashlight.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | -| [Geocoding](geocoding.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Geolocation](geolocation.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Gyroscope](gyroscope.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | -| [Haptic Feedback](haptic-feedback.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Launcher](launcher.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Magnetometer](magnetometer.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | -| [MainThread](main-thread.md?content=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Maps](maps.md?content=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | -| [Media Picker](media-picker.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ⚠️ | -| [Open Browser](open-browser.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Orientation Sensor](orientation-sensor.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | -| [Permissions](permissions.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Phone Dialer](phone-dialer.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Platform Extensions](platform-extensions.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Preferences](preferences.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Screenshot](screenshot.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ❌ | -| [Secure Storage](secure-storage.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Share](share.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [SMS](sms.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | -| [Text-to-Speech](text-to-speech.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Unit Converters](unit-converters.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Version Tracking](version-tracking.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | -| [Vibrate](vibrate.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | -| [Web Authenticator](web-authenticator.md?context=xamarin/xamarin-forms) | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | ✔️ | +| [Accelerometer](sensors.md#accelerometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [App Actions](app-actions.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ❌ | +| [App Information](app-information.md) | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | ✔️ | +| [App Theme](app-theme.md) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | +| [Barometer](sensors.md#barometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [Battery](battery.md) | ✔️ | ✔️ | ✔️ | ⚠️ | ❌ | ⚠️ | ✔️ | +| [Clipboard](clipboard.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ✔️ | +| [Color Converters](color-converters.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Compass](sensors.md#compass) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | +| [Connectivity](connectivity.md) | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | ✔️ | +| [Contacts](contacts.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | +| [Detect Shake](sensors.md#shake) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | +| [Device Display Information](device-display.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ✔️ | +| [Device Information](device-information.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Email](email.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [File Picker](file-picker.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [File System Helpers](file-system-helpers.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Flashlight](flashlight.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | +| [Geocoding](geocoding.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Geolocation](geolocation.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [Gyroscope](sensors.md#gyroscope) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [Haptic Feedback](haptic-feedback.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [Launcher](launcher.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [Magnetometer](sensors.md#magnetometer) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [MainThread](main-thread.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Maps](maps.md) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ✔️ | +| [Media Picker](media-picker.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ⚠️ | +| [Open Browser](open-browser.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [Orientation Sensor](sensors.md#orientation) | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | +| [Permissions](permissions.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Phone Dialer](phone-dialer.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [Platform Extensions](platform-extensions.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Preferences](preferences.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Screenshot](screenshot.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ❌ | ❌ | +| [Secure Storage](secure-storage.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Share](share.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [SMS](sms.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ✔️ | +| [Text-to-Speech](text-to-speech.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Unit Converters](unit-converters.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Version Tracking](version-tracking.md) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | +| [Vibrate](vibrate.md) | ✔️ | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ | +| [Web Authenticator](web-authenticator.md) | ✔️ | ✔️ | ✔️ | ❌ | ✔️ | ❌ | ✔️ | diff --git a/docs/essentials/sensors.md b/docs/essentials/sensors.md new file mode 100644 index 000000000..0ee926bd3 --- /dev/null +++ b/docs/essentials/sensors.md @@ -0,0 +1,545 @@ +--- +title: Accessing device sensors overview +description: #Required; article description that is displayed in search results. +ms.topic: overview +ms.date: 08/09/2021 +ms.custom: template-overview +show_latex: true +--- + +# Accessing device sensors + +Devices have all sorts of sensors available to you. Some sensors can detect movement, others changes in the environment, such as light. Monitoring and reacting to these sensors makes your app dynamic in adapting to how the device is being used. You can also respond to changes in the sensors and alert the user. This article gives you a brief overview of the common sensors supported by .NET Multi-User Application (.NET MAUI). + +## Sensor speed + +It's important to note that the sensor is updated according to speed you set when you start monitoring the sensor. However, monitoring too many sensors at once may affect the rate the sensor data is returned. + +- `Fastest`\ +Get the sensor data as fast as possible (not guaranteed to return on UI thread). + +- `Game`\ +Rate suitable for games (not guaranteed to return on UI thread). + +- `Default`\ +Default rate suitable for screen orientation changes. + +- `UI`\ +Rate suitable for general user interface. + +## Sensor event handlers + +Event handlers added to sensor events aren't guaranteed to run on the UI thread. If the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](main-thread.md) method to run that code on the UI thread. + +## Accelerometer + +The accelerometer sensor measures the acceleration of the device along its three axes. The data reported by the sensor represents how the user is moving the device. + +To start monitoring the accelerometer sensor, call the `Accelerometer.Start` method. .NET MAUI sends accelerometer data changes to your app by raising the `Accelerometer.ReadingChanged` event. Use the `Accelerometer.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the accelerometer with the `Accelerometer.IsMonitoring` 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: + +```csharp +using Microsoft.Maui.Essentials; +using System; + +namespace HelloMaui.Sensors +{ + public class AccelerometerTest + { + public void ToggleAccelerometer() + { + const SensorSpeed speed = SensorSpeed.UI; + + try + { + if (Accelerometer.IsMonitoring) + { + Accelerometer.Stop(); + Accelerometer.ReadingChanged -= Accelerometer_ReadingChanged; + } + else + { + Accelerometer.ReadingChanged += Accelerometer_ReadingChanged; + Accelerometer.Start(speed); + } + } + catch (FeatureNotSupportedException fnsEx) + { + // Feature not supported on device + } + catch (Exception ex) + { + // Other error has occurred. + } + } + + void Accelerometer_ReadingChanged(object sender, AccelerometerChangedEventArgs e) + { + AccelerometerData data = e.Reading; + + // Process Acceleration X, Y, Z + Console.WriteLine($"Reading: X: {data.Acceleration.X}, Y: {data.Acceleration.Y}, Z: {data.Acceleration.Z}"); + } + } +} +``` + +Accelerometer readings are reported back in **G**. A **G** is a unit of gravitation force equal to the gravity exerted by the earth's gravitational field $(9.81 m/s^2)$. + +The coordinate-system is defined relative to the screen of the device in its default orientation. The axes aren't swapped when the device's screen orientation changes. + +The **X** axis is horizontal and points to the right, the **Y** axis is vertical and points up and the **Z** axis points towards the outside of the front face of the screen. In this system, coordinates behind the screen have negative **Z** values. + +Examples: + +- When the device lies flat on a table and is pushed on its left side toward the right, the **X** acceleration value is positive. + +- When the device lies flat on a table, the acceleration value is +1.00 G or $(+9.81 m/s^2)$, which correspond to the acceleration of the device $(0 m/s^2)$ minus the force of gravity $(-9.81 m/s^2)$ and normalized as in G. + + +- When the device lies flat on a table and is pushed toward the sky with an acceleration of **A** $m/s^2$, the acceleration value is equal to $A+9.81$ which corresponds to the acceleration of the device $(+A m/s^2)$ minus the force of gravity $(-9.81 m/s^2)$ and normalized in **G**. + +### Platform-specific information (Accelerometer) + +There isn't any platform-specific information for the accelerometer. + +## Barometer + +The barometer sensor measures the ambient air pressure. The data reported by the sensor represents the current air pressure. This data is reported the first time you start monitoring the sensor and then each time the pressure changes. + +To start monitoring the barometer sensor, call the `Barometer.Start` method. .NET MAUI sends air pressure readings to your app by raising the `Barometer.ReadingChanged` event. Use the `Barometer.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the barometer with the `Barometer.IsMonitoring` property, which will be `true` if the barometer is currently being monitored. + +The pressure reading is represented in hectopascals. + +The following code example demonstrates monitoring the barometer for changes: + +```csharp +using Microsoft.Maui.Essentials; +using System; + +namespace HelloMaui.Sensors +{ + public class BarometerTest + { + public void ToggleBarometer() + { + const SensorSpeed speed = SensorSpeed.UI; + + try + { + if (Barometer.IsMonitoring) + { + Barometer.Stop(); + Barometer.ReadingChanged -= Barometer_ReadingChanged; + } + else + { + Barometer.ReadingChanged += Barometer_ReadingChanged; + Barometer.Start(speed); + } + } + catch (FeatureNotSupportedException fnsEx) + { + // Feature not supported on device + } + catch (Exception ex) + { + // Other error has occurred. + } + } + + void Barometer_ReadingChanged(object sender, BarometerChangedEventArgs e) + { + var data = e.Reading; + + // Process Pressure + Console.WriteLine($"Reading: Pressure: {data.PressureInHectopascals} hectopascals"); + } + } +} + +``` + +### Platform-specific information (Barometer) + +This section describes platform-specific implementation details related to the barometer. + + +# [Android](#tab/android) + +No platform-specific implementation details. + +# [iOS](#tab/ios) + +This API uses [CMAltimeter](https://developer.apple.com/documentation/coremotion/cmaltimeter#//apple_ref/occ/cl/CMAltimeter) to monitor pressure changes, which is a hardware feature that was added to iPhone 6 and newer devices. A `FeatureNotSupportedException` will be thrown on devices that don't support the altimeter, the sensor used to report air pressure. + +`SensorSpeed` isn't used by this API, as it isn't supported on iOS. + +# [Windows](#tab/windows) + +No platform-specific implementation details. + +----- + + +## Compass + +The compass sensor monitor the device's magnetic north heading. + +To start monitoring the compass sensor, call the `Compass.Start` method. .NET MAUI sends air pressure readings to your app by raising the `Compass.ReadingChanged` event. Use the `Compass.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the compass with the `Compass.IsMonitoring` property, which will be `true` if the compass is currently being monitored. + +The following code example demonstrates monitoring the compass for changes: + +```csharp +using Microsoft.Maui.Essentials; +using System; + +namespace HelloMaui.Sensors +{ + public class CompassTest + { + public void ToggleCompass() + { + const SensorSpeed speed = SensorSpeed.UI; + + try + { + if (Compass.IsMonitoring) + { + Compass.Stop(); + Compass.ReadingChanged -= Compass_ReadingChanged; + } + else + { + Compass.ReadingChanged += Compass_ReadingChanged; + Compass.Start(speed); + } + } + catch (FeatureNotSupportedException fnsEx) + + { + // Feature not supported on device + } + catch (Exception ex) + { + // Some other exception has occurred + } + } + + void Compass_ReadingChanged(object sender, CompassChangedEventArgs e) + { + var data = e.Reading; + + // Process Heading Magnetic North + Console.WriteLine($"Reading: {data.HeadingMagneticNorth} degrees"); + } + } +} +``` + +### Platform-specific information (Compass) + +This section describes platform-specific implementation details related to the compass. + + +# [Android](#tab/android) + +Android doesn't provide an API for retrieving the compass heading. .NET MAUI uses the accelerometer and magnetometer sensors to calculate the magnetic north heading, which is recommended by Google. + +In rare instances, you maybe see inconsistent results because the sensors need to be calibrated. Recalibrating the compass on Android varies by phone model and Android version. You'll need to search the internet on how to recalibrate the compass. Here are two links that may help in recalibrating the compass: + +- [Google Help Center: Find and improve your location’s accuracy](https://support.google.com/maps/answer/2839911) +- [Stack Exchange Android Enthusiasts: How can I calibrate the compass on my phone?](https://android.stackexchange.com/questions/10145/how-can-i-calibrate-the-compass-on-my-phone) + +Running multiple sensors from your app at the same time may impair the sensor speed. + +### Lowpass filter + +Because of how the Android compass values are updated and calculated, there may be a need to smooth out the values. A _Lowpass filter_ can be applied that averages the sine and cosine values of the angles and can be turned on by using the `Start` method overload, which accepts the `bool applyLowPassFilter` parameter: + +```csharp +Compass.Start(SensorSpeed.UI, applyLowPassFilter: true); +``` + +This is only applied on the Android platform, and the parameter is ignored on iOS and Windows. For more information, see [this GitHub issue comment](https://github.com/xamarin/Essentials/pull/354#issuecomment-405316860). + +# [iOS](#tab/ios) + +No platform-specific implementation details. + +# [Windows](#tab/windows) + +No platform-specific implementation details. + +----- + + +## Shake + +Even though this article is listing **shake** as a sensor, it isn't. The [accelerometer](#accelerometer) is used to detect when the device is shaken. + +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 `Accelerometer.Start` method. .NET MAUI sends accelerometer data changes to your app by raising the `Accelerometer.ReadingChanged` event. Use the `Accelerometer.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the accelerometer with the `Accelerometer.IsMonitoring` property, which will be `true` if the accelerometer was started and is currently being monitored. + +When a shake is detected, a `ShakeDetected` event is raised. It's recommended to use `Game` or faster for the `SensorSpeed`. The following code example demonstrates reacting to the `ShakeDetected` event: + +```csharp +using Microsoft.Maui.Essentials; +using System; + +namespace HelloMaui.Sensors +{ + public class ShakeTest + { + public void ToggleAccelerometer() + { + const SensorSpeed speed = SensorSpeed.Game; + + try + { + if (Accelerometer.IsMonitoring) + { + Accelerometer.Stop(); + Accelerometer.ShakeDetected -= Accelerometer_ShakeDetected; + } + else + { + Accelerometer.ShakeDetected += Accelerometer_ShakeDetected; + Accelerometer.Start(speed); + } + } + catch (FeatureNotSupportedException fnsEx) + { + // Feature not supported on device + } + catch (Exception ex) + { + // Other error has occurred. + } + } + + void Accelerometer_ShakeDetected(object sender, EventArgs e) + { + // Process shake event + Console.WriteLine("Device shake detected!"); + } + } +} +``` + +### Platform-specific information (Shake) + +There isn't any platform-specific information for the accelerometer sensor and shake detection. + +## Gyroscope + +The gyroscope sensor measures the angular rotation speed around the device's three primary axes. + +To start monitoring the gyroscope sensor, call the `Gyroscope.Start` method. .NET MAUI sends gyroscope data changes to your app by raising the `Gyroscope.ReadingChanged` event. The data provided by this event is measured in rad/s (radian per second). Use the `Gyroscope.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the gyroscope with the `Gyroscope.IsMonitoring` property, which will be `true` if the gyroscope was started and is currently being monitored. + +```csharp +using Microsoft.Maui.Essentials; +using System; + +namespace HelloMaui.Sensors +{ + public class GyroscopeTest + { + public void ToggleGyroscope() + { + const SensorSpeed speed = SensorSpeed.UI; + + try + { + if (Gyroscope.IsMonitoring) + { + Gyroscope.Stop(); + Gyroscope.ReadingChanged -= Gyroscope_ReadingChanged; + } + else + { + Gyroscope.ReadingChanged += Gyroscope_ReadingChanged; + Gyroscope.Start(speed); + } + } + catch (FeatureNotSupportedException fnsEx) + { + // Feature not supported on device + } + catch (Exception ex) + { + // Other error has occurred. + } + } + + void Gyroscope_ReadingChanged(object sender, GyroscopeChangedEventArgs e) + { + GyroscopeData data = e.Reading; + + // Process Angular Velocity X, Y, and Z reported in rad/s + Console.WriteLine($"Reading: X: {data.AngularVelocity.X}, Y: {data.AngularVelocity.Y}, Z: {data.AngularVelocity.Z}"); + } + } +} +``` + +### Platform-specific information (Gyroscope) + +There isn't any platform-specific information for the gyroscope sensor. + +## Magnetometer + +The magnetometer sensor indicates the device's orientation relative to Earth's magnetic field. + +To start monitoring the magnetometer sensor, call the `Magnetometer.Start` method. .NET MAUI sends magnetometer data changes to your app by raising the `Magnetometer.ReadingChanged` event. The data provided by this event is measured in rad/s (radian per second). Use the `Magnetometer.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the magnetometer with the `Magnetometer.IsMonitoring` property, which will be `true` if the magnetometer was started and is currently being monitored. + +All data is returned in $µT$ (microteslas). + +```csharp +using Microsoft.Maui.Essentials; +using System; + +namespace HelloMaui.Sensors +{ + public class MagnetometerTest + { + public void ToggleMagnetometer() + { + const SensorSpeed speed = SensorSpeed.UI; + + try + { + if (Magnetometer.IsMonitoring) + { + Magnetometer.Stop(); + Magnetometer.ReadingChanged -= Magnetometer_ReadingChanged; + } + else + { + Magnetometer.ReadingChanged += Magnetometer_ReadingChanged; + Magnetometer.Start(speed); + } + } + catch (FeatureNotSupportedException fnsEx) + { + // Feature not supported on device + } + catch (Exception ex) + { + // Other error has occurred. + } + } + + void Magnetometer_ReadingChanged(object sender, MagnetometerChangedEventArgs e) + { + MagnetometerData data = e.Reading; + + // Process MagneticField X, Y, and Z + Console.WriteLine($"Reading: X: {data.MagneticField.X}, Y: {data.MagneticField.Y}, Z: {data.MagneticField.Z}"); + } + } +} +``` + +### Platform-specific information (Magnetometer) + +There isn't any platform-specific information for the magnetometer sensor. + +## Orientation + +The orientation sensor monitors the orientation of a device in 3D space. + +> [!NOTE] +> This sensor isn't used for determining if the device's video display is in portrait or landscape mode, use the `Orientation` property of the `ScreenMetrics` object available from the [`DeviceDisplay`](device-display.md) class. + +To start monitoring the orientation sensor, call the `OrientationSensor.Start` method. .NET MAUI sends orientation data changes to your app by raising the `Magnetometer.ReadingChanged` event. The data provided by this event is measured in rad/s (radian per second). Use the `OrientationSensor.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the orientation with the `OrientationSensor.IsMonitoring` property, which will be `true` if the orientation was started and is currently being monitored. + +```csharp +using Microsoft.Maui.Essentials; +using System; + +namespace HelloMaui.Sensors +{ + public class OrientationTest + { + public void ToggleOrientation() + { + const SensorSpeed speed = SensorSpeed.UI; + + try + { + if (OrientationSensor.IsMonitoring) + { + OrientationSensor.Stop(); + OrientationSensor.ReadingChanged -= OrientationSensor_ReadingChanged; + } + else + { + OrientationSensor.ReadingChanged += OrientationSensor_ReadingChanged; + OrientationSensor.Start(speed); + } + } + catch (FeatureNotSupportedException fnsEx) + { + // Feature not supported on device + } + catch (Exception ex) + { + // Other error has occurred. + } + } + + void OrientationSensor_ReadingChanged(object sender, OrientationSensorChangedEventArgs e) + { + OrientationSensorData data = e.Reading; + + // Process Orientation quaternion (X, Y, Z, and W) + Console.WriteLine($"Reading: X: {data.Orientation.X}, Y: {data.Orientation.Y}, Z: {data.Orientation.Z}"); + } + } +} + +``` + +`OrientationSensor` readings are reported back in the form of a [`Quaternion`](xref:System.Numerics.Quaternion) that describes the orientation of the device based on two 3D coordinate systems: + +The device (generally a phone or tablet) has a 3D coordinate system with the following axes: + +- The positive X-axis points to the right of the display in portrait mode. +- The positive Y-axis points to the top of the device in portrait mode. +- The positive Z-axis points out of the screen. + +The 3D coordinate system of the Earth has the following axes: + +- The positive X-axis is tangent to the surface of the Earth and points east. +- The positive Y-axis is also tangent to the surface of the Earth and points north. +- The positive Z-axis is perpendicular to the surface of the Earth and points up. + +The `Quaternion` describes the rotation of the device's coordinate system relative to the Earth's coordinate system. + +A `Quaternion` value is closely related to rotation around an axis. If an axis of rotation is the normalized vector ($ax, ay, az), and the rotation angle is Θ, then the (X, Y, Z, W) components of the quaternion are: + +(ax·sin(Θ/2), ay·sin(Θ/2), az·sin(Θ/2), cos(Θ/2)) + +These are right-hand coordinate systems, so with the thumb of the right hand pointed in the positive direction of the rotation axis, the curve of the fingers indicate the direction of rotation for positive angles. + +Examples: + +- When the device lies flat on a table with its screen facing up, with the top of the device (in portrait mode) pointing north, the two coordinate systems are aligned. The `Quaternion` value represents the identity quaternion (0, 0, 0, 1). All rotations can be analyzed relative to this position. + +- When the device lies flat on a table with its screen facing up, and the top of the device (in portrait mode) pointing west, the `Quaternion` value is (0, 0, 0.707, 0.707). The device has been rotated 90 degrees around the Z axis of the Earth. + +- When the device is held upright so that the top (in portrait mode) points towards the sky, and the back of the device faces north, the device has been rotated 90 degrees around the X axis. The `Quaternion` value is (0.707, 0, 0, 0.707). + +- If the device is positioned so its left edge is on a table, and the top points north, the device has been rotated -90 degrees around the Y axis (or 90 degrees around the negative Y axis). The `Quaternion` value is (0, -0.707, 0, 0.707). + +### Platform-specific information (Orientation) + +There isn't any platform-specific information for the magnetometer sensor. + +## Next steps + +- [Write an overview](contribute-how-to-write-overview.md) +- [Links](links-how-to.md) From d052df5a51fa9dc3d5ec2d06f39f3b692abf6716 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Mon, 9 Aug 2021 12:57:01 -0700 Subject: [PATCH 2/5] Updates to latex;intro --- docs/essentials/sensors.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/essentials/sensors.md b/docs/essentials/sensors.md index 0ee926bd3..343397c0a 100644 --- a/docs/essentials/sensors.md +++ b/docs/essentials/sensors.md @@ -13,7 +13,7 @@ Devices have all sorts of sensors available to you. Some sensors can detect move ## Sensor speed -It's important to note that the sensor is updated according to speed you set when you start monitoring the sensor. However, monitoring too many sensors at once may affect the rate the sensor data is returned. +Sensor speed sets the speed in which a sensor will return data to your app. When you start a sensor, you provide the desired sensor speed. However, monitoring too many sensors at once may affect the rate sensor data is returned to your app. - `Fastest`\ Get the sensor data as fast as possible (not guaranteed to return on UI thread). @@ -27,9 +27,9 @@ Default rate suitable for screen orientation changes. - `UI`\ Rate suitable for general user interface. -## Sensor event handlers +### Sensor event handlers -Event handlers added to sensor events aren't guaranteed to run on the UI thread. If the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](main-thread.md) method to run that code on the UI thread. +Event handlers added to sensors with either `Game` or `Fastest` sensor speeds aren't guaranteed to run on the UI thread. If the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](main-thread.md) method to run that code on the UI thread. ## Accelerometer @@ -519,9 +519,9 @@ The 3D coordinate system of the Earth has the following axes: The `Quaternion` describes the rotation of the device's coordinate system relative to the Earth's coordinate system. -A `Quaternion` value is closely related to rotation around an axis. If an axis of rotation is the normalized vector ($ax, ay, az), and the rotation angle is Θ, then the (X, Y, Z, W) components of the quaternion are: +A `Quaternion` value is closely related to rotation around an axis. If an axis of rotation is the normalized vector ($a_x, a_y, a_z$), and the rotation angle is $\theta$, then the (X, Y, Z, W) components of the quaternion are: -(ax·sin(Θ/2), ay·sin(Θ/2), az·sin(Θ/2), cos(Θ/2)) +$(a_x \times \sin(\theta/2), a_y \times \sin(\theta/2), a_z \times \sin(\theta/2), \cos(\theta/2)$ These are right-hand coordinate systems, so with the thumb of the right hand pointed in the positive direction of the rotation axis, the curve of the fingers indicate the direction of rotation for positive angles. @@ -538,8 +538,3 @@ Examples: ### Platform-specific information (Orientation) There isn't any platform-specific information for the magnetometer sensor. - -## Next steps - -- [Write an overview](contribute-how-to-write-overview.md) -- [Links](links-how-to.md) From cf1042dab8ec9d26593ccba2d71694f8463ace4d Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Mon, 9 Aug 2021 13:01:12 -0700 Subject: [PATCH 3/5] add description --- docs/essentials/sensors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/essentials/sensors.md b/docs/essentials/sensors.md index 343397c0a..9d947f410 100644 --- a/docs/essentials/sensors.md +++ b/docs/essentials/sensors.md @@ -1,6 +1,6 @@ --- title: Accessing device sensors overview -description: #Required; article description that is displayed in search results. +description: "Learn how to use and monitor sensors provided by your device, with .NET MAUI. You can monitor the following sensors: accelerometer, barometer, compass, shake, gyroscope, magnetometer, orientation." ms.topic: overview ms.date: 08/09/2021 ms.custom: template-overview @@ -29,7 +29,7 @@ Rate suitable for general user interface. ### Sensor event handlers -Event handlers added to sensors with either `Game` or `Fastest` sensor speeds aren't guaranteed to run on the UI thread. If the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](main-thread.md) method to run that code on the UI thread. +Event handlers added to sensors with either the `Game` or `Fastest` speeds **aren't** guaranteed to run on the UI thread. If the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](main-thread.md) method to run that code on the UI thread. ## Accelerometer From 5192be2ec0138b0f0baf3c01972d8eb941a24b9e Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Tue, 10 Aug 2021 10:56:10 -0700 Subject: [PATCH 4/5] Fix copy\paste errors+more --- docs/essentials/sensors.md | 113 ++++++++++++++++++++++++++++++++----- 1 file changed, 98 insertions(+), 15 deletions(-) diff --git a/docs/essentials/sensors.md b/docs/essentials/sensors.md index 9d947f410..0ae6d8d2c 100644 --- a/docs/essentials/sensors.md +++ b/docs/essentials/sensors.md @@ -13,7 +13,7 @@ Devices have all sorts of sensors available to you. Some sensors can detect move ## Sensor speed -Sensor speed sets the speed in which a sensor will return data to your app. When you start a sensor, you provide the desired sensor speed. However, monitoring too many sensors at once may affect the rate sensor data is returned to your app. +Sensor speed sets the speed in which a sensor will return data to your app. When you start a sensor, you provide the desired sensor speed with the `SensorSpeed` enumeration. - `Fastest`\ Get the sensor data as fast as possible (not guaranteed to return on UI thread). @@ -27,6 +27,9 @@ Default rate suitable for screen orientation changes. - `UI`\ Rate suitable for general user interface. +> [!WARNING] +> Monitoring too many sensors at once may affect the rate sensor data is returned to your app. + ### Sensor event handlers Event handlers added to sensors with either the `Game` or `Fastest` speeds **aren't** guaranteed to run on the UI thread. If the event handler needs to access user-interface elements, use the [`MainThread.BeginInvokeOnMainThread`](main-thread.md) method to run that code on the UI thread. @@ -102,7 +105,23 @@ Examples: ### Platform-specific information (Accelerometer) -There isn't any platform-specific information for the accelerometer. +This section describes platform-specific implementation details related to the accelerometer sensor. + + +# [Android](#tab/android) + +No platform-specific implementation details. + +# [iOS](#tab/ios) + +No platform-specific implementation details. + +# [Windows](#tab/windows) + +No platform-specific implementation details. + +----- + ## Barometer @@ -163,7 +182,7 @@ namespace HelloMaui.Sensors ### Platform-specific information (Barometer) -This section describes platform-specific implementation details related to the barometer. +This section describes platform-specific implementation details related to the barometer sensor. # [Android](#tab/android) @@ -187,7 +206,7 @@ No platform-specific implementation details. The compass sensor monitor the device's magnetic north heading. -To start monitoring the compass sensor, call the `Compass.Start` method. .NET MAUI sends air pressure readings to your app by raising the `Compass.ReadingChanged` event. Use the `Compass.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the compass with the `Compass.IsMonitoring` property, which will be `true` if the compass is currently being monitored. +To start monitoring the compass sensor, call the `Compass.Start` method. .NET MAUI raises the `Compass.ReadingChanged` event when the compass heading changes. Use the `Compass.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the compass with the `Compass.IsMonitoring` property, which will be `true` if the compass is currently being monitored. The following code example demonstrates monitoring the compass for changes: @@ -240,7 +259,7 @@ namespace HelloMaui.Sensors ### Platform-specific information (Compass) -This section describes platform-specific implementation details related to the compass. +This section describes platform-specific implementation details related to the compass feature. # [Android](#tab/android) @@ -281,9 +300,11 @@ Even though this article is listing **shake** as a sensor, it isn't. The [accele 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 `Accelerometer.Start` method. .NET MAUI sends accelerometer data changes to your app by raising the `Accelerometer.ReadingChanged` event. Use the `Accelerometer.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the accelerometer with the `Accelerometer.IsMonitoring` property, which will be `true` if the accelerometer was started and is currently being monitored. +To start monitoring the accelerometer sensor, call the `Accelerometer.Start` method. When a shake is detected, the `Accelerometer.ShakeDetected` event is raised. Use the `Accelerometer.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the accelerometer with the `Accelerometer.IsMonitoring` property, which will be `true` if the accelerometer was started and is currently being monitored. + +It's recommended to use `Game` or faster for the `SensorSpeed`. -When a shake is detected, a `ShakeDetected` event is raised. It's recommended to use `Game` or faster for the `SensorSpeed`. The following code example demonstrates reacting to the `ShakeDetected` event: +The following code example demonstrates reacting to the `ShakeDetected` event: ```csharp using Microsoft.Maui.Essentials; @@ -331,7 +352,23 @@ namespace HelloMaui.Sensors ### Platform-specific information (Shake) -There isn't any platform-specific information for the accelerometer sensor and shake detection. +This section describes platform-specific implementation details related to the accelerometer's shake feature. + + +# [Android](#tab/android) + +No platform-specific implementation details. + +# [iOS](#tab/ios) + +No platform-specific implementation details. + +# [Windows](#tab/windows) + +No platform-specific implementation details. + +----- + ## Gyroscope @@ -387,15 +424,29 @@ namespace HelloMaui.Sensors ### Platform-specific information (Gyroscope) -There isn't any platform-specific information for the gyroscope sensor. +This section describes platform-specific implementation details related to the gyroscope sensor. + + +# [Android](#tab/android) + +No platform-specific implementation details. + +# [iOS](#tab/ios) + +No platform-specific implementation details. + +# [Windows](#tab/windows) + +No platform-specific implementation details. + +----- + ## Magnetometer The magnetometer sensor indicates the device's orientation relative to Earth's magnetic field. -To start monitoring the magnetometer sensor, call the `Magnetometer.Start` method. .NET MAUI sends magnetometer data changes to your app by raising the `Magnetometer.ReadingChanged` event. The data provided by this event is measured in rad/s (radian per second). Use the `Magnetometer.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the magnetometer with the `Magnetometer.IsMonitoring` property, which will be `true` if the magnetometer was started and is currently being monitored. - -All data is returned in $µT$ (microteslas). +To start monitoring the magnetometer sensor, call the `Magnetometer.Start` method. .NET MAUI sends magnetometer data changes to your app by raising the `Magnetometer.ReadingChanged` event. The data provided by this event is measured in $µT$ (microteslas). Use the `Magnetometer.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the magnetometer with the `Magnetometer.IsMonitoring` property, which will be `true` if the magnetometer was started and is currently being monitored. ```csharp using Microsoft.Maui.Essentials; @@ -445,7 +496,23 @@ namespace HelloMaui.Sensors ### Platform-specific information (Magnetometer) -There isn't any platform-specific information for the magnetometer sensor. +This section describes platform-specific implementation details related to the magnetometer sensor. + + +# [Android](#tab/android) + +No platform-specific implementation details. + +# [iOS](#tab/ios) + +No platform-specific implementation details. + +# [Windows](#tab/windows) + +No platform-specific implementation details. + +----- + ## Orientation @@ -454,7 +521,7 @@ The orientation sensor monitors the orientation of a device in 3D space. > [!NOTE] > This sensor isn't used for determining if the device's video display is in portrait or landscape mode, use the `Orientation` property of the `ScreenMetrics` object available from the [`DeviceDisplay`](device-display.md) class. -To start monitoring the orientation sensor, call the `OrientationSensor.Start` method. .NET MAUI sends orientation data changes to your app by raising the `Magnetometer.ReadingChanged` event. The data provided by this event is measured in rad/s (radian per second). Use the `OrientationSensor.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the orientation with the `OrientationSensor.IsMonitoring` property, which will be `true` if the orientation was started and is currently being monitored. +To start monitoring the orientation sensor, call the `OrientationSensor.Start` method. .NET MAUI sends orientation data changes to your app by raising the `OrientationSensor.ReadingChanged` event. Use the `OrientationSensor.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the orientation with the `OrientationSensor.IsMonitoring` property, which will be `true` if the orientation was started and is currently being monitored. ```csharp using Microsoft.Maui.Essentials; @@ -537,4 +604,20 @@ Examples: ### Platform-specific information (Orientation) -There isn't any platform-specific information for the magnetometer sensor. +This section describes platform-specific implementation details related to the orientation sensor. + + +# [Android](#tab/android) + +No platform-specific implementation details. + +# [iOS](#tab/ios) + +No platform-specific implementation details. + +# [Windows](#tab/windows) + +No platform-specific implementation details. + +----- + From e6e026d357885feec5dfa1ddecdd802bdb99a4b1 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Tue, 10 Aug 2021 11:01:11 -0700 Subject: [PATCH 5/5] more feedback --- docs/TOC.yml | 2 +- docs/essentials/sensors.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/TOC.yml b/docs/TOC.yml index 180a85cb9..5a5e2a57a 100644 --- a/docs/TOC.yml +++ b/docs/TOC.yml @@ -26,7 +26,7 @@ items: - name: Customize controls href: user-interface/handlers/customize.md - - name: Device features + - name: Platform integration expanded: true items: - name: Sensors diff --git a/docs/essentials/sensors.md b/docs/essentials/sensors.md index 0ae6d8d2c..4fb5a0d49 100644 --- a/docs/essentials/sensors.md +++ b/docs/essentials/sensors.md @@ -9,7 +9,7 @@ show_latex: true # Accessing device sensors -Devices have all sorts of sensors available to you. Some sensors can detect movement, others changes in the environment, such as light. Monitoring and reacting to these sensors makes your app dynamic in adapting to how the device is being used. You can also respond to changes in the sensors and alert the user. This article gives you a brief overview of the common sensors supported by .NET Multi-User Application (.NET MAUI). +Devices have all sorts of sensors that are available to you. Some sensors can detect movement, others changes in the environment, such as light. Monitoring and reacting to these sensors makes your app dynamic in adapting to how the device is being used. You can also respond to changes in the sensors and alert the user. This article gives you a brief overview of the common sensors supported by .NET Multi-User Application (.NET MAUI). ## Sensor speed @@ -204,7 +204,7 @@ No platform-specific implementation details. ## Compass -The compass sensor monitor the device's magnetic north heading. +The compass sensor monitors the device's magnetic north heading. To start monitoring the compass sensor, call the `Compass.Start` method. .NET MAUI raises the `Compass.ReadingChanged` event when the compass heading changes. Use the `Compass.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the compass with the `Compass.IsMonitoring` property, which will be `true` if the compass is currently being monitored. @@ -519,7 +519,7 @@ No platform-specific implementation details. The orientation sensor monitors the orientation of a device in 3D space. > [!NOTE] -> This sensor isn't used for determining if the device's video display is in portrait or landscape mode, use the `Orientation` property of the `ScreenMetrics` object available from the [`DeviceDisplay`](device-display.md) class. +> This sensor isn't used for determining if the device's video display is in portrait or landscape mode. Use the `Orientation` property of the `ScreenMetrics` object available from the [`DeviceDisplay`](device-display.md) class. To start monitoring the orientation sensor, call the `OrientationSensor.Start` method. .NET MAUI sends orientation data changes to your app by raising the `OrientationSensor.ReadingChanged` event. Use the `OrientationSensor.Stop` method to stop monitoring the sensor. You can detect the monitoring state of the orientation with the `OrientationSensor.IsMonitoring` property, which will be `true` if the orientation was started and is currently being monitored.