RFC: Packages for Addons like Shield and Hats

[projectgus]

(This is a design proposal, circulated for discussion, suggestions, and constructive criticism. Please comment on this issue.)

User Story

"As a new MicroPython user, I want to quickly get started using this <shield/hat/etc> with my MicroPython board."

Summary

Document and implement a standard method to package "addon" products. These connect to a supported board in a standard way, and interface it to some lower-level hardware (i.e. some chip). Examples: Arduino Shields, Pi Pico Hats (pHATs), Featherwings, Pmods.

(EDIT: We thought some vendors were using pHAT for "Pico Hats", but actually these are used for Pi Zero... So another name will be needed!)

Some specific examples of this type of addon:

• WaveShare Pico LoRa SX1262 (interface to supported LoRa SX1262 modem.)
• Adafruit SSD1306 Featherwing (interface to supported SSD1306 display driver.)

The goal is to provide an easier and quicker setup experience when getting started with addons such as these.

Structure

Each addon is either a shield, phat, fwing, or pmod.

To form a package structure, files are placed under driver/<type>/<type>-<manufacturer>-<product name>/ with a similar module name.

Example

For the WaveShare Pico LoRa SX1262 pHAT mentioned above, this would be the file structure in micropython-lib:

- driver/
  - phat/
    - phat-waveshare-pico-lora-sx1262/
      - README.md  
      - manifest.py
      - phat_waveshare_pico_lora_sx1262.py

Therefore the package name for mip install will be phat-waveshare-pico-lora-sx1262.

Once installed, usage would be something like:

from phat_waveshare_pico_lora_sx1262 import Modem

modem = Modem()
# do lora things here

(For comparison this is the constructor currently needed for this pHAT. Some of these settings - for example dio3_tcxo_millivolts=3300 - can only be determined by reading the Waveshare schematic and the datasheet for the included TCXO.)

This structure should still allow some flexibility around "families" of addons, for example if there are multiple addons that differ only in a very small way then it might be better to implement and install them as a single package.

Requirements

Guidelines for whether an "addon" product package is suitable for micropython-lib:

• Hardware must be one of the addon types supported by MicroPython boards. Currently: Arduino Shields, Pi Pico Hats (pHATs), Featherwings, Pmods.[1]
• Hardware must be compatible as per the published specification of the addon type.[2]
• Hardware has to be available to the general public and in stock at the time it's added to micropython-lib, with publicly accessible documentation.
• The addon package must wrap existing driver(s). If a lower layer generic chip driver is missing then it should be added as a separate driver.
• The addon package must simplify using the hardware. If no (or trivially few) parameters such as pins, chip configuration, etc. is simplified for the user then the lower layer chip driver should be used directly instead.
• Where any trademarks exist[3], usage has to be compliant with trademark holder's guidelines.

Suggest including these requirements formally in the documentation from the outset, as anticipate some manufacturers will view inclusion as an easy marketing strategy (which is great for everyone, provided they can meet the requirements above.)

[1] Arduino Shields and pHATs can be implemented immediately. Featherwings and Pmods will require board-level changes to pins.csv as the pinout information is not exposed to MicroPython in a standard form.
[2] Official specifications exist for Feather and Pmod. For the others, it may be a "best effort" at compatibility only.
[3] FeatherWing is a US registered trademark of Limor Fried, Arduino is a registered trademark of Arduino, Pmod is a trademark of Digilent.

---

This work was funded through GitHub Sponsors.

[tannewt]

We have something similar for FeatherWings: https://github.com/adafruit/Adafruit_CircuitPython_FeatherWing/ These are classes that handle the initialization for a specific wing.

However, I don't think these libraries get used that often. Instead, I think people start from examples in the corresponding learn guide and that includes the init code. This is an example: https://learn.adafruit.com/adafruit-oled-featherwing/python-usage#example-code-3040599 The "Project Bundle" link will be a zip with the example code and all libraries it uses.

Our drivers also have examples that get packaged with them: https://github.com/adafruit/Adafruit_CircuitPython_DisplayIO_SSD1306/tree/main/examples We tend to have one example for each tested version of hardware.

So, I'm not sure a package is actually what people need. Instead, a quick tutorial with sample code may be more useful.

[projectgus]

So, I'm not sure a package is actually what people need. Instead, a quick tutorial with sample code may be more useful.

That is a valuable perspective, thanks @tannewt.

Viewed from this perspective, some of this idea may be trying to find a technical solution to some vendors' lack of documentation. 😆 . Although the MP case is a bit more complex, as we have more combinations of boards/modules from different vendors.

Our drivers also have examples that get packaged with them

Fully agree this is an excellent practice, and maybe this effort is better spent expanding or creating examples for the existing MP drivers.

The complexity really does come from the combinations - for example a driving motivation for this was that the new lora packages have examples, but getting the example to work with some particular modems (for example the Waveshare one I used as an example) still requires some hardware-specific settings that are hard for a beginner to divine (heck, they were hard for the driver developer to divine!)

Your suggestion is a good one, though. Maybe an additional doc attached to each driver with code snippets and descriptions for the variations in commonly encountered hardware is enough to help these situations.

[Josverl]

I think this could be useful, but to me good code without documentation would not achieve the full potential. It would require a user to reverse engineer the 'driver packs' which may be a quite steep learning curve for the intended audiences. Especially as mpy code tends to use short variable names, and omit comments and docstrings more than needed.

[projectgus]

Closing this out as it seems from discussion last year that as proposed it's not a big improvement on the status quo.