Xamarin.Essentials: BrújulaXamarin.Essentials: Compass

La clase Compass permite supervisar la dirección del norte magnético del dispositivo.The Compass class lets you monitor the device's magnetic north heading.

Primeros pasosGet started

Para empezar a usar esta API, lea la guía de introducción para Xamarin.Essentials con el fin de asegurarse de que la biblioteca está correctamente instalada y configurada en los proyectos.To start using this API, read the getting started guide for Xamarin.Essentials to ensure the library is properly installed and set up in your projects.

Uso de CompassUsing Compass

Agregue una referencia a Xamarin.Essentials en su clase:Add a reference to Xamarin.Essentials in your class:

using Xamarin.Essentials;

La funcionalidad Compass funciona mediante una llamada a los métodos Start y Stop para realizar escuchas de los cambios realizados en la brújula.The Compass functionality works by calling the Start and Stop methods to listen for changes to the compass. Los cambios se enviarán a través del evento ReadingChanged.Any changes are sent back through the ReadingChanged event. A continuación se muestra un ejemplo:Here is an example:

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
        }
    }
}

Velocidad de sensorSensor Speed

  • Más rápido: obtener los datos del sensor tan rápido como sea posible (no se garantiza la devolución en el subproceso de interfaz de usuario).Fastest – Get the sensor data as fast as possible (not guaranteed to return on UI thread).
  • Juego: velocidad adecuada para juegos (no se garantiza la devolución en el subproceso de interfaz de usuario).Game – Rate suitable for games (not guaranteed to return on UI thread).
  • Normal: velocidad predeterminada adecuada para los cambios de orientación de pantalla.Normal – Default rate suitable for screen orientation changes.
  • Interfaz de usuario: velocidad adecuada para la interfaz de usuario general.UI – Rate suitable for general user interface.

Si no se garantiza la ejecución del controlador de eventos en el subproceso de interfaz de usuario y si el controlador de eventos necesita tener acceso a elementos de la interfaz de usuario, use el método MainThread.BeginInvokeOnMainThread para ejecutar ese código en el subproceso de interfaz de usuario.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 method to run that code on the UI thread.

Detalles de implementación de la plataformaPlatform Implementation Specifics

Android no proporciona una API para recuperar la dirección de la brújula.Android does not provide a API for retrieving the compass heading. El acelerómetro y el magnetómetro se usan para calcular la dirección del norte magnético, lo que recomienda Google.We utilize the accelerometer and magnetometer to calculate the magnetic north heading, which is recommended by Google.

En casos poco habituales, es posible que vea resultados incoherentes porque sea necesario calibrar los sensores, lo que implica mover el dispositivo describiendo un ocho.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. La mejor manera de hacerlo es abrir Google Maps, pulsar en el punto de la ubicación y seleccionar Calibrar la brújula.The best way of doing this is to open Google Maps, tap on the dot for your location, and select Calibrate compass.

Tenga en cuenta que la ejecución simultánea de varios sensores desde la aplicación puede ajustar la velocidad del sensor.Be aware that running multiple sensors from your app at the same time may adjust the sensor speed.

Filtro de paso bajoLow Pass Filter

Debido a la forma de calcular y actualizar los valores de la brújula de Android, es posible que sea necesario suavizarlos.Due to how the Android compass values are updated and calculated there may be a need to smooth out the values. Se puede aplicar un filtro de paso bajo que calcula el promedio de los valores de seno y coseno de los ángulos, y se puede activar si se sobrecarga el método Start, que acepta el parámetro bool applyLowPassFilter: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:

Compass.Start(SensorSpeed.UI, applyLowPassFilter: true);

Esto solo se aplica a la plataforma Android; el parámetro se ignora en iOS y UWP.This is only applied on the Android platform, and the parameter is ignored on iOS and UWP. Puede leer más información aquí.More information can be read here.

APIAPI