docs: Document @micropython.native usage policy.#406
Merged
Conversation
Closes #405. Add a guideline to CONTRIBUTING.md: @micropython.native must not be used in driver code (I2C/SPI bus time dominates, native compilation gains nothing) but may be used in examples on rendering hot-paths where a measurable speedup is expected. Remove the unnecessary @micropython.native from compute_display() in radar_screen.py — the function does 3 comparisons with no loop, so native compilation provides no benefit. Also remove the now-unused `import micropython`.
Contributor
There was a problem hiding this comment.
Pull request overview
Documents a project-wide policy for when @micropython.native should (and should not) be used, and removes an unnecessary usage from a VL53L1X example to align with that policy.
Changes:
- Add a CONTRIBUTING.md guideline discouraging
@micropython.nativein drivers and clarifying when it’s acceptable in examples. - Remove
@micropython.native(and the now-unusedimport micropython) fromcompute_display()inradar_screen.py.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| lib/vl53l1x/examples/radar_screen.py | Removes unused micropython import and drops @micropython.native from a non-hot-path helper. |
| CONTRIBUTING.md | Adds a coding-conventions bullet documenting the @micropython.native usage policy. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Apply the policy documented in this PR to the three examples with tight pixel loops: - tamagotchi.py: draw_character() — 4 nested loops, pixel by pixel - spirit_level.py: fill_circle() — double loop with x*x + y*y test - maze_game.py: draw_maze() — double loop over 11x11 grid
…ple. draw_cube() runs 12 math.sin/cos calls + floating-point arithmetic per frame in a tight animation loop. Native compilation reduces the per-frame overhead significantly on the STM32WB55.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #405.
@micropython.nativeis forbidden in driver code, accepted case-by-case in examples on rendering hot-paths.@micropython.nativefromcompute_display()inradar_screen.py— 3 comparisons, no loop, no measurable benefit. Also remove the now-unusedimport micropython.Policy
@micropython.nativedevice.py)Test plan
make lintpassesradar_screen.pystill runs correctly without the decorator (the function is identical, just interpreted as bytecode instead of native)