<commit_before>Compass
*******

.. py:module:: microbit.compass

This module lets you access the build-in electronic compass. Before using,
the compass should be calibrated, otherwise the readings may be wrong.


Functions
=========

.. py:function:: calibrate()

    Starts the calibration process. After this is called, the user should
    lay the board flat on the table and rotate it horizontally, until the
    process is finished.

.. py:function:: is_calibrated()

    Returns ``True`` if the compass has been successfully calibrated, and
    returns ``False`` otherwise.


.. py:function:: is_calibrating()

    Returns ``True`` if the calibration process is in progress, and ``False``
    if it has finished or hasn't been started yet.


.. py:function:: clear_calibrarion()

    Undoes the calibration, making the compass uncalibrated again.


.. py:function:: get_x()

    Gives the reading on the ``x`` axis of the compass.


.. py:function:: get_y()

    Gives the reading on the ``y`` axis of the compass.


.. py:function:: get_z()

    Gives the reading on the ``z`` axis of the compass (vertical).


.. py:function:: heading()

    Gives the compass heading, calculated from the above readings.


Example
=======

.. include:: ../examples/compass.py
    :code: python<commit_msg>More details about compass return values<commit_after>Compass
*******

.. py:module:: microbit.compass

This module lets you access the build-in electronic compass. Before using,
the compass should be calibrated, otherwise the readings may be wrong.


Functions
=========

.. py:function:: calibrate()

    Starts the calibration process. After this is called, the user should
    lay the board flat on the table and rotate it horizontally, until the
    process is finished.

.. py:function:: is_calibrated()

    Returns ``True`` if the compass has been successfully calibrated, and
    returns ``False`` otherwise.


.. py:function:: is_calibrating()

    Returns ``True`` if the calibration process is in progress, and ``False``
    if it has finished or hasn't been started yet.


.. py:function:: clear_calibrarion()

    Undoes the calibration, making the compass uncalibrated again.


.. py:function:: get_x()

    Gives the reading of the magnetic force on the ``x`` axis, as a
    positive or negative integer, depending on the direction of the
    force.


.. py:function:: get_y()

    Gives the reading of the magnetic force on the ``x`` axis, as a
    positive or negative integer, depending on the direction of the
    force.


.. py:function:: get_z()

    Gives the reading of the magnetic force on the ``x`` axis, as a
    positive or negative integer, depending on the direction of the
    force.


.. py:function:: heading()

    Gives the compass heading, calculated from the above readings, as an
    integer in the range from 0 to 360, representing the angle in degrees,
    clockwise, with north as 0.


Example
=======

.. include:: ../examples/compass.py
    :code: python
{'fraction_non_alphanumeric': 0.10287241148964596, 'fraction_numerical': 0.0016700066800267202, 'mean_word_length': 3.4634873323397914, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2046552', 'n_tokens_mistral': 858, 'n_tokens_neox': 780, 'n_words': 375}