adding compass example

README.rst

@@ -6,7 +6,6 @@ Introduction
     :target: https://micropython-lis3mdl.readthedocs.io/en/latest/
     :alt: Documentation Status
 
-
 .. image:: https://img.shields.io/badge/micropython-Ok-purple.svg
     :target: https://micropython.org
     :alt: micropython

docs/conf.py

@@ -9,8 +9,6 @@
 sys.path.insert(0, os.path.abspath(".."))
 
 try:
-    # Inject mock modules so that we can build the
-    # documentation without having the real stuff available
     from mock import Mock
 
     to_be_mocked = [
@@ -41,9 +39,7 @@
     "MicroPython": ("https://docs.micropython.org/en/latest/", None),
 }
 
-# autodoc_mock_imports = ["digitalio", "busio"]
 autoclass_content = "both"
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 source_suffix = ".rst"
 master_doc = "index"

docs/examples.rst

@@ -42,3 +42,12 @@ Example showing the Operation mode setting
 .. literalinclude:: ../examples/lis3mdl_operation_mode.py
     :caption: examples/lis3mdl_operation_mode.py
     :lines: 5-
+
+Compass Example
+------------------------
+
+Example showing how to use the LIS3MDL as a compass
+
+.. literalinclude:: ../examples/lis3mdl_compass.py
+    :caption: examples/lis3mdl_compass.py
+    :lines: 5-

examples.json

@@ -1,10 +1,29 @@
 {
   "urls": [
-    ["micropython_lis3mdl/examples/lis3mdl_data_rate.py", "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_data_rate.py"],
-    ["micropython_lis3mdl/examples/lis3mdl_scale_range.py", "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_scale_range.py"],
-    ["micropython_lis3mdl/examples/lis3mdl_simpletest.py", "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_simpletest.py"],
-    ["micropython_lis3mdl/examples/lis3mdl_low_power_mode.py", "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_low_power_mode.py"],
-    ["micropython_lis3mdl/examples/lis3mdl_operation_mode.py", "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_operation_mode.py"]
+    [
+      "micropython_lis3mdl/examples/lis3mdl_data_rate.py",
+      "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_data_rate.py"
+    ],
+    [
+      "micropython_lis3mdl/examples/lis3mdl_scale_range.py",
+      "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_scale_range.py"
+    ],
+    [
+      "micropython_lis3mdl/examples/lis3mdl_simpletest.py",
+      "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_simpletest.py"
+    ],
+    [
+      "micropython_lis3mdl/examples/lis3mdl_low_power_mode.py",
+      "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_low_power_mode.py"
+    ],
+    [
+      "micropython_lis3mdl/examples/lis3mdl_operation_mode.py",
+      "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_operation_mode.py"
+    ],
+    [
+      "micropython_lis3mdl/examples/lis3mdl_compass.py",
+      "github:jposada202020/MicroPython_LIS3MDL/examples/lis3mdl_compass.py"
+    ]
   ],
   "version": "1"
 }

examples/lis3mdl_compass.py

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
+# SPDX-FileCopyrightText: Copyright (c) 2023 Jose D. Montoya
+#
+# SPDX-License-Identifier: MIT
+
+import time
+from math import atan2, degrees
+from machine import Pin, I2C
+from micropython_lis3mdl import lis3mdl
+
+i2c = I2C(1, sda=Pin(2), scl=Pin(3))  # Correct I2C pins for RP2040
+lis = lis3mdl.LIS3MDL(i2c)
+
+
+def vector_2_degrees(x, y):
+    angle = degrees(atan2(y, x))
+    if angle < 0:
+        angle += 360
+    return angle
+
+
+def get_heading(_sensor):
+    magnet_x, magnet_y, _ = _sensor.magnetic
+    return vector_2_degrees(magnet_x, magnet_y)
+
+
+while True:
+    print(f"heading: {get_heading(lis):.2f} degrees")
+    time.sleep(0.2)

micropython_lis3mdl/lis3mdl.py

@@ -8,7 +8,7 @@
 MicroPython Driver for the ST LIS3MDL magnetometer
 
 
-* Author(s): Jose D. Montoya
+* Author: Jose D. Montoya
 
 
 """
@@ -139,7 +139,7 @@ def __init__(self, i2c, address: int = 0x1C) -> None:
         self._address = address
 
         if self._device_id != 0x3D:
-            raise RuntimeError("Failed to find LIS3MDL")
+            raise RuntimeError("Failed to find the LIS3MDL sensor")
 
         self._operation_mode = CONTINUOUS
         self._scale_cached_factor = scale_range_factor[self._scale_range]