Following finalized naming in uasyncio.
|6 years ago|
|README.md||6 years ago|
|button_led.py||6 years ago|
|button_reaction.py||6 years ago|
|hwconfig_console.py||6 years ago|
|hwconfig_dragonboard410c.py||6 years ago|
|hwconfig_esp8266_esp12.py||6 years ago|
|hwconfig_pyboard.py||6 years ago|
|hwconfig_z_96b_carbon.py||6 years ago|
|hwconfig_z_frdm_k64f.py||6 years ago|
|soft_pwm.py||6 years ago|
|soft_pwm2_uasyncio.py||6 years ago|
|soft_pwm_uasyncio.py||6 years ago|
This directory shows the best practices for using MicroPython hardware API
machine module strives to provide consistent API
across various boards, with the aim to enable writing portable applications,
which would work from a board to board, from a system to another systems.
This is inherently a hard problem, because hardware is different from one
board type to another, and even from examplar of board to another. For
example, if your app requires an external LED, one user may connect it
to one GPIO pin, while another user may find it much more convinient to
use another pin. This of course applies to relays, buzzers, sensors, etc.
With complications above in mind, it's still possible to write portable applications by using "low[est] denominator" subset of hardware API and following simple rules outlined below. The applications won't be able to rely on advanced hardware capabilities of a particular board and will be limited to generic capabilities, but it's still possible to write many useful applications in such a way, with the obvious benefit of "write once - run everywhere" approach (only configuration for a particular board is required).
The key to this approach is splitting your application into (at least) 2 parts:
- main application logic
- hardware configuration
The key point is that hardware configuration should be a separate file
(module in Python terms). A good name would be
hwconfig.py, and that's
how we'll call it from now on. Another key point is that main application
should never instantiate (construct) hardware objects directly. Instead,
they should be defined in
hwconfig.py, and main application should
import and reference hardware objects via this module. The simplest
application of this idea would look like:
from machine import Pin LED = Pin("A3", Pin.OUT)
from hwconfig import * import utime while True: LED.value(1) utime.sleep_ms(500) LED.value(0) utime.sleep_ms(500)
To deploy this application to a particular board, a user will need:
hwconfig.pyto adjust Pin and other hardware peripheral parameters and locations.
- Actually deploy
app.pyto a board (e.g. copy to board's filesystem, or build new firmware with these modules frozen into it).
Note that there's no need to edit the main application code! (Which may
be complex, while
hwconfig.py should usually remain short enough, and
focused solely on hardware configuration).
An obvious improvement to this approach is the following. There're few
well-known boards which run MicroPython, and most of them include an
onboard LED. So, to help users of these boards to do configuration
quickly (that's especially important for novice users, for who may
be stumped by the need to reach out to a board reference to find LED
hwconfig.py your application ships may include
commented out sections with working configurations for different
boards. The step 1 above then will be:
- Look thru
hwconfig.pyto find a section which either exactly matches your board, or the closest to it. Uncomment, and if any adjustments required, apply them.
It's important to keep in mind that adjustments may be always required, and that there may be users whose configuration doesn't match any of the available. So, always include a section or instructions for them. Consider for example that even on a supported board, user may want to blink not an on-board LED, but the one they connected externally. MicroPython's Hardware API offers portability not just among "supported" boards, but to any board at all, so make sure users can enjoy it.
There's next step of improvement to make. While having one
with many sections would work for smaller projects with few hardware
objects, it may become more cumbersome to maintain both on programmer's
and user's sides for larger projects. Then instead of single
hwconfig.py file, you can provide few "template" ones for well-known
Then step 1 above will be:
- Look thru available
hwconfig_*.pyfiles and find one which matches your board the best, then rename to
hwconfig.pyand make adjustments, if any.
Again, please keep in mind that there may be users whose hardware will be
completely unlike you heard of. Give them some helpful hints too, perhaps
hwconfig_custom.py with some instructions.
That's where we stop with improvements to the "separate file for hardware
configuration" idea, as it is already pretty flexible and viable. An
application in this directory shows it in practice, using slightly less
trivial example than just a blinking LED:
soft_pwm.py implements a
software PWM (pulse width modulation) to produce an LED fade-in/fade-out
effect - without any dependence on hardware PWM availability.
Note that improvements to board configuration handling may continue further.
For example, one may invent a "configuration manager" helper module which will
try to detect current board (among well-known ones), and load appropriate
hwconfig_*.py - this assumes that a user would lazily deploy them all
(or that application will be automatically installed, e.g. using MicroPython's
upip package manager). The key point in this case remains the same as
elaborated above - always assume there can, and will be a custom configuration,
and it should be well supported. So, any automatic detection should be
overridable by a user, and instructions how to do so are among the most
important you may provide for your application.
By following these best practices, you will use MicroPython at its full potential, and let users enjoy it too. Good luck!