:mod:`bmm150` --- BMM150 3-axis magnetometer
============================================

.. module:: bmm150
   :synopsis: Bosch BMM150 3-axis geomagnetic sensor driver

Driver for the Bosch BMM150 3-axis geomagnetic sensor over I2C. On
construction the driver soft-resets the device, switches it into normal
operating mode at the requested ODR, and reads the trim registers used by
the Bosch compensation equations to convert raw readings into calibrated
magnetic-field values.

.. note::

   SPI mode is not supported by this driver; passing a non-I2C bus raises
   ``ValueError``.

Example::

    import time
    from machine import Pin, I2C
    from bmm150 import BMM150

    imu = BMM150(I2C(1, scl=Pin(15), sda=Pin(14)))

    while True:
        print("magnetometer: x:{:>8.3f} y:{:>8.3f} z:{:>8.3f}".format(*imu.magnet()))
        time.sleep_ms(100)

Classes
-------

.. class:: BMM150(bus: machine.I2C, cs: machine.Pin | None = None, address: int = 0x10, magnet_odr: int = 30)

   Construct a ``BMM150`` instance, soft-reset the chip, verify its chip
   ID, configure it for normal mode at ``magnet_odr`` Hz and read the
   factory trim registers.

   ``bus``
      A configured :py:class:`machine.I2C` bus the sensor is attached to.

   ``cs``
      Reserved for SPI mode. Must be left as ``None``; SPI is not
      currently implemented and supplying a non-I2C bus raises
      ``ValueError``.

   ``address``
      7-bit I2C address of the device. Defaults to ``0x10``.

   ``magnet_odr``
      Magnetometer output data rate in Hz. Must be one of
      ``2``, ``6``, ``8``, ``10``, ``15``, ``20``, ``25`` or ``30``;
      anything else raises ``ValueError``.

   .. method:: magnet_raw() -> tuple[int, int, int, int]

      Poll the data-ready flag and return the raw signed
      ``(x, y, z, hall)`` readings as integers, with the sub-LSB bits
      already shifted out. Raises ``OSError("Data not ready")`` if no
      sample becomes available within ten retries.

   .. method:: magnet() -> tuple[float, float, float]

      Read a fresh sample via :meth:`magnet_raw` and return the
      compensated magnetic-field vector ``(x, y, z)``. The compensation
      uses the trim values read at construction and matches the reference
      C driver supplied by Bosch.