feat(lis2mdl): Add OLED digital compass example.

[Kaanoz-en]

Summary

Closes #328

Adds a new hardware example demonstrating a digital compass by combining the LIS2MDL magnetometer and the SSD1327 OLED display.

Changes

• Added lib/lis2mdl/examples/compass_display.py.
• Implemented a 3D calibration sequence on startup (calibrate_minmax_3d()) with on-screen user instructions.
• Created a dynamic, round-screen optimized UI featuring:
  • An outer compass ring with N, E, S, W cardinal points.
  • A real-time animated needle using trigonometric math (sin/cos).
  • Text readouts for both the exact degree heading and the cardinal direction label.
• Ensured proper hardware cleanup (display.power_off()) in the finally block according to project conventions.
• Kept UI math efficient and grouped layout constants cleanly at the top of the file.

Checklist

• ruff check passes
• python -m pytest tests/ -k mock -v passes (no mock test broken)
• Tested on hardware (if applicable)
• README updated (if adding/changing public API)
• Examples added/updated (if applicable)
• Commit messages follow <scope>: <Description.> format

[Copilot]

Pull request overview

Adds a new lis2mdl hardware example that combines the LIS2MDL magnetometer with an SSD1327 OLED to render a live digital compass display, including a startup calibration flow.

Changes:

• Added lib/lis2mdl/examples/compass_display.py example integrating LIS2MDL heading + SSD1327 drawing loop.
• Implements a startup 3D min/max calibration routine with on-screen prompts.
• Renders a compass UI (ring, cardinal points, needle, numeric heading + direction label).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

framebuf.FrameBuffer on MicroPython typically doesn’t provide an ellipse() method, and the ssd1327 driver doesn’t add one either. Calling display.framebuf.ellipse(...) will raise AttributeError on most ports. Consider replacing this with a small helper that draws a circle using pixel()/line() (e.g., midpoint circle algorithm or a low-resolution polygon approximation), or drop the ring if you want to keep the example minimal.

[Kaanoz-en]

Good catch! I implemented the midpoint circle algorithm to keep the UI clean while avoiding the AttributeError.

[nedseb]

💡 Suggestion: cette PR utilise le SSD1327 directement avec framebuf. Le projet a maintenant steami_screen qui fournit un widget screen.compass(heading) prêt à l'emploi (voir lib/steami_screen/examples/compass_demo.py).

Tu pourrais simplifier ton code en utilisant :

from steami_screen import Screen, SSD1327Display
display = SSD1327Display(ssd1327.WS_OLED_128X128_SPI(spi, dc, res, cs))
screen = Screen(display)

screen.clear()
screen.compass(heading)
screen.show()

Cela remplacerait tout le code de dessin manuel (cercles, aiguille, labels cardinaux). Pas obligatoire pour cette PR, mais à considérer.

[Charly-sketch]

Revue — LIS2MDL Compass Display Example

Bon ajout global L’exemple est visuellement intéressant, exploite bien le SSD1327 et démontre une vraie utilisation du LIS2MDL (heading + direction).
Mais il y a plusieurs petit points à corriger pour être conforme aux conventions du repo et à la qualité attendue.

1. README non mis à jour

L’exemple compass_display.py n’est pas ajouté dans le README du driver lis2mdl.

À faire :
Ajouter une ligne dans le tableau :

compass_display.py | Graphical compass with OLED display

2. PR description — issue non liée

La PR ne contient pas :

Closes #328

Obligatoire selon les conventions GitHub du projet.

3. Commentaire en français dans le code

Dans le code :

# Si tu préfères l'initiale française pour Ouest...

À corriger :
Tu n'auras plus besoin de cet partie si tu utilise le widget compass

4. Import inutilisé

from math import cos, pi, sin

cos n’est jamais utilisé

À corriger :
Tu n'auras plus besoin de cet import si tu utilise le widget compass

Points positifs ✓

• Très bon rendu visuel (compass + needle)
• Utilisation correcte de heading_flat_only() ✔️
• Bonne gestion du refresh (sleep_ms(50))
• Affichage direction + degrés
• Calibration intégrée (bonne idée UX)
• Code globalement lisible et structuré

Résumé des corrections à faire

• Ajouter l’exemple dans le README
• Ajouter Closes #328 dans la PR
• Supprimer le commentaire en français
• Supprimer cos inutilisé

[Kaanoz-en]

I've updated the PR to address all your points and improve the code structure. Here is a summary of the changes:

I added compass_display.py to the examples table in the lis2mdl README and included Closes #328 in the commit message to properly link the issue. I completely refactored the example to use the newly available steami_screen.compass() widget. It’s a great addition to the repo, and it significantly simplified the code. Just a quick clarification on the previous version! The cos function was actually being used in the manual drawing logic to calculate the Y-coordinate of the needle tip (end_y = CENTER_Y - int(NEEDLE_LENGTH * cos(heading_rad))). However, since I've now migrated to the steami_screen widget, all manual trigonometric calculations (sin, cos, pi) are completely obsolete and have been safely removed. I also removed the french comment that I wrote by mistake.

Everything is pushed and tested.

[MatteoCnda1]

Great example, the code is clean and well structured! The use of screen.compass() is exactly what we'd expect for this kind of example. A few small suggestions to align it perfectly with the project conventions:

1. Calibration phase (Line 30 - 41)
   The calibration still uses raw_display.text() directly. To stay consistent with the rest of the code that uses steami_screen, you could replace it with:

screen.clear()
screen.title("Calibrating...")
screen.subtitle("Move in 8-shape")
screen.show()

This would also allow removing the CALIB_MSG1_X etc. constants which would no longer be needed.

2. Direction label
   direction is computed but only printed to serial. It would be a nice touch to also display it on screen with screen.subtitle(direction) — it would make the example even more complete visually!

This is a really nice example, these are minor adjustments and the overall code is very solid 👍

[Kaanoz-en]

Great example, the code is clean and well structured! The use of screen.compass() is exactly what we'd expect for this kind of example. A few small suggestions to align it perfectly with the project conventions:

1. Calibration phase (Line 30 - 41)
   The calibration still uses raw_display.text() directly. To stay consistent with the rest of the code that uses steami_screen, you could replace it with:

screen.clear() screen.title("Calibrating...") screen.subtitle("Move in 8-shape") screen.show()

This would also allow removing the CALIB_MSG1_X etc. constants which would no longer be needed.

2. Direction label
   direction is computed but only printed to serial. It would be a nice touch to also display it on screen with screen.subtitle(direction) — it would make the example even more complete visually!

This is a really nice example, these are minor adjustments and the overall code is very solid 👍

Thank you for your review ! I tried to replace raw_display.text() like you stated it but for some reason I didn't manage to make it work so I kept it that way. In addition, I also thought that displaying the direction directly on the screen would be a nice addition, but we discussed it with Charly and the fact that I'm using the steami_screen library doesn't allow me to display both the compass and the direction on the screen. Moreover, as it is only an exemple, we decided that it would be enough to show the compass on the screen and to print the direction in the serial plot. Hope that helps !

[Charly-sketch]

Review & corrections applied

Corrections

Fix	Description
Add depedency	Add the depedency for the compass_display example.

This is a really nice example, it just lacked the depedency in the readme. Good job !

[semantic-release-updater]

🎉 This PR is included in version 0.17.0 🎉

The release is available on:

• v0.17.0
• GitHub release

Your semantic-release bot 📦🚀