Get the compass heading

Read the direction that the device faces, relative to magnetic north or true north, from the compass sensor.

Use the CompassSensor device to get the heading of the device that your application runs on. Use it to rotate a map or to point content toward a real-world direction.

The heading is in degrees:

  • 0 is north
  • 90 is east
  • 180 is south
  • 270 is west

The compass sensor replaces the legacy Input.compass API. Use only one of these APIs in a project. Both use the same platform heading service, so if you disable one, the other also stops getting updates.

Read the heading

Like other sensors, the compass sensor is disabled by default, and its readings are valid only while it's enabled.

To read the heading:

  1. Enable the sensor with InputSystem.EnableDevice.
  2. Check the headingAccuracy control. A negative value means that the reading is unreliable.
  3. Read the heading from the magneticHeading control, or from the trueHeading control.
  4. When you no longer need heading updates, disable the sensor with InputSystem.DisableDevice.

Example: Log the compass heading

The following example logs the heading when it changes by at least 1 degree, and ignores unreliable readings:

using UnityEngine;
using UnityEngine.InputSystem;

/// <summary>
/// Example script that logs the compass heading when it changes by at least 1 degree.
/// </summary>
public class ReadCompassHeadingExample : MonoBehaviour
{
    /// <summary>
    /// Report the heading relative to true north instead of magnetic north.
    /// On Android, this needs a recent reading from the location sensor.
    /// </summary>
    public bool useTrueHeading;

    float m_LastHeading = -1;

    void OnEnable()
    {
        if (useTrueHeading && LocationSensor.current != null)
            InputSystem.EnableDevice(LocationSensor.current);
        if (CompassSensor.current != null)
            InputSystem.EnableDevice(CompassSensor.current);
    }

    void OnDisable()
    {
        if (CompassSensor.current != null)
            InputSystem.DisableDevice(CompassSensor.current);
        if (useTrueHeading && LocationSensor.current != null)
            InputSystem.DisableDevice(LocationSensor.current);
    }

    void Update()
    {
        var compass = CompassSensor.current;
        if (compass == null || !compass.enabled)
            return;

        // A negative accuracy means that the reading is unreliable.
        if (compass.headingAccuracy.ReadValue() < 0)
            return;

        // 0 is north, 90 is east, 180 is south, and 270 is west.
        var heading = useTrueHeading ? compass.trueHeading.ReadValue() : compass.magneticHeading.ReadValue();

        // Log the heading when it changes by at least 1 degree.
        if (m_LastHeading >= 0 && Mathf.Abs(Mathf.DeltaAngle(heading, m_LastHeading)) < 1f)
            return;

        m_LastHeading = heading;
        Debug.Log($"Heading: {heading:F0} degrees");
    }
}

Sensor controls

The compass sensor has the following controls:

Control Description
magneticHeading Heading relative to magnetic north, in degrees.
trueHeading Heading relative to true (geographic) north, in degrees. To learn when this value is available, refer to Get the heading relative to true north.
headingAccuracy Accuracy of the heading, in degrees. A negative value means that the reading is unreliable.
rawVector Raw geomagnetic field on the x, y, and z axes of the device, in microteslas. On iOS, the axes are rotated to match the screen orientation. On the Web platform, this value is always (0, 0, 0).
timestamp Time of the most recent reading, in seconds. On the Web platform, this is the time that the reading was received, because no measurement time is available.

Get the heading relative to true north

True north is the direction of the geographic North Pole. It differs from magnetic north by an amount that depends on where the device is, so calculating it requires the device location.

On Android, trueHeading is equal to magneticHeading until the location sensor delivers a reading. After that, trueHeading is corrected for the location of the device.

On iOS, trueHeading is valid only while the location sensor is also enabled and the user allowed location access.

On the Web platform, trueHeading is always equal to magneticHeading, because browsers don't report true north.

To get a heading relative to true north on Android and iOS, enable the location sensor as well as the compass sensor. In the example, enable Use True Heading.

Whether trueHeading needs the location sensor depends on the platform, so test the behavior on each platform that you target.

Additional resources