fix(steami_screen): Improve gauge reactivity and readability.

[MatteoCnda1]

Summary

Improve gauge_demo.py reactivity and readability on hardware. Closes #370

Changes

• Added arc_width optional parameter to gauge() in device.py
  • Defaults to max(5, radius // 9) if not provided — no breaking change
• Reduced _draw_arc() oversampling from x2 to x1.5 for faster rendering
• Updated gauge_demo.py:
  • Dynamic arc color based on distance zones (WHITE / YELLOW / LIGHT)
  • Dynamic arc width — thicker when close, thinner when far
  • Moving average smoothing over 5 samples to avoid abrupt jumps
  • Redraw only when distance changes by more than 5mm (REDRAW_THRESHOLD)
  • Replaced screen.value() with screen.text() at scale=1 for readability
  • Added try/finally to clear display on exit

Checklist

• ruff check passes
• python -m pytest tests/ -k mock -v passes
• Tested on hardware (STM32WB55 / STeaMi board)
• Examples added/updated (lib/steami_screen/examples/gauge_demo.py)
• Commit messages follow <scope>: <Description.> format

[Charly-sketch]

Good work on this improvement pass.
The example is clearly moving in the right direction: readability is better, the gauge feels more dynamic, and the intent to improve hardware responsiveness is visible. The PR brings useful refinements and the overall direction is solid.

There are however a few points that should be addressed before merging:

---

1. device.py changes are difficult to review because formatting/lint cleanup is mixed with functional edits

device.py appears to have gone through a broad lint/format pass in the same commit as the actual gauge modifications. As a result, it becomes unnecessarily hard to isolate what was functionally changed in gauge() and _draw_arc() from what is only whitespace/reformatting.

For core library files, it is much easier to review and validate behavior when formatting-only changes are split from logic changes.

Suggested fix:
Please separate pure lint/style cleanup from behavioral modifications, either by:

• splitting this into dedicated commits, or
• rebasing the PR so the functional diff remains easy to inspect.

This makes future maintenance and regression review significantly easier.

---

2. sleep_ms(10) still seems too aggressive compared to the actual OLED refresh cost

One of the original goals of the issue was to avoid queuing frames and align the polling loop with the real rendering speed observed on hardware.

The loop still polls every 10 ms:

sleep_ms(10)

Even if redraws are threshold-limited, this still means the MCU continuously checks the sensor at a much higher rate than the display can visually update, which may create unnecessary CPU activity for little practical benefit.

Suggested fix:
Please benchmark the effective visible frame rate and consider using a slower loop cadence (20–40 ms range for example), which should better match the SSD1327 redraw time while remaining visually fluid.

---

3. @micropython.native on redraw() is not necessarily the best optimization target

The redraw() function is decorated with @micropython.native, but most of the execution time here is not raw Python arithmetic — it is dominated by:

• screen clearing,
• arc drawing,
• SPI transfers,
• full display flush.

So the native decorator is unlikely to provide a meaningful real-world speedup compared to the actual display I/O bottleneck.

It also makes the example a little less straightforward for readers, especially in a high-level demo whose goal is to showcase steami_screen.

Suggested fix:
Either:

• remove the decorator if no measurable gain is observed, or
• document with a short benchmark note that this was hardware-measured and actually beneficial.

Optimization should ideally target the rendering path first, not the Python wrapper call.

---

4. The example still performs a full redraw, not a partial redraw

Although redraws are now conditional on distance variation, each accepted update still does:

screen.clear()
...
screen.gauge(...)
screen.text(...)
screen.subtitle(...)
screen.show()

So the full frame is erased and rebuilt every time.

This means the PR reduces how often redraw happens, but not how expensive each redraw is.

Given that the original hardware complaint was rendering sluggishness, the main bottleneck is still present: full-screen refresh + full arc recomputation.

Suggested fix:
A partial redraw strategy would be preferable here:

• redraw only the changed arc delta,
• redraw only the center numeric text when needed,
• keep static labels persistent.

If implementing this is too large for this PR, then this limitation should at least be explicitly acknowledged and a follow-up issue should be opened, because the current optimization remains only a partial improvement.

---

5. New public API parameter arc_width should be covered more explicitly

Adding arc_width to Screen.gauge() is a good idea and gives more flexibility to the widget API.

However, since this modifies a public reusable widget and not just the example, it should ideally be accompanied by:

• a dedicated mock test validating custom arc widths,
• or at minimum a quick validation that existing widget behavior is unchanged when arc_width is omitted.

This avoids silent regressions in one of the core steami_screen primitives.

---

6. Dynamic grayscale zones may have limited visual distinction on SSD1327

The dynamic zone idea is good, but on the SSD1327 backend WHITE, YELLOW, and LIGHT all degrade to grayscale intensities.

This means the practical visual difference between medium and far zones may remain subtle on the monochrome OLED, especially depending on viewing angle and OLED brightness.

Not blocking, but worth validating on hardware that the three states are actually perceptible enough to justify the added logic.

Suggested fix:
If grayscale contrast is not strong enough, varying only arc thickness or adding textual state feedback may communicate the distance zone more clearly than relying on pseudo-color transitions.

---

Overall this is good work and the PR is clearly improving the example in several areas.
The main remaining concern is that the rendering path is still not truly optimized yet, only throttled, so I would like to see the points above addressed or at least clarified before merge.

Still, the direction is good and this is a valuable iteration on the demo.

[semantic-release-updater]

🎉 This PR is included in version 0.25.1 🎉

The release is available on:

• v0.25.1
• GitHub release

Your semantic-release bot 📦🚀