MicroPython package template

MicroPython (PyPI) package template project with auto deploy

---

General

MicroPython (PyPI) package template with GitHub Action based testing and deploy

📚 The latest documentation is available at MicroPython Package Template ReadTheDocs 📚

• Installation - Install required tools

• Setup - Install package from the web - General - Specific version - Test version - Manually - Upload files to board - mpremote - rshell

• Usage

• Create a PyPI (micropython) package - Setup - Create a distribution - Upload to PyPI

• Contributing - Unittests

• Steps after using this template

• Credits

Installation

Install required tools

Python3 must be installed on your system. Check the current Python version with the following command

python --version
python3 --version

Depending on which command Python 3.x.y (with x.y as some numbers) is returned, use that command to proceed.

python3 -m venv .venv
source .venv/bin/activate

# to interact with a MicroPython board
pip install -r requirements.txt

# to run all tests or contribute to this repo
pip install -r requirements-test.txt

# to create and deploy a new version of this package
pip install -r requirements-deploy.txt

Setup

Install package from the web

Connect the MicroPython device to a network, otherwise check the section Manually down below.

import network
station = network.WLAN(network.STA_IF)
station.active(True)
station.connect('SSID', 'PASSWORD')
station.isconnected()

General

Install the latest package version of this lib on the MicroPython device

import mip
mip.install("github:brainelectronics/micropython-package-template")

For MicroPython versions below 1.19.1 use the upip package instead of mip

import upip
upip.install('micropython-package-template')

Run this code on the MicroPython device to check the used MicroPython version

try:
    from os import uname
except ImportError:
    # u-packages might be deprecated in future
    from uos import uname
os.uname().version

Specific version

Install a specific, fixed package version of this lib on the MicroPython device

import mip
# install a verions of a specific branch
mip.install("github:brainelectronics/micropython-package-template", version="feature/initial-implementation")
# install a tag version
mip.install("github:brainelectronics/micropython-package-template", version="0.6.0")

# install pre-compiled package
mip.install("github:brainelectronics/micropython-package-template/package_mpy.json")
mip.install("github:brainelectronics/micropython-package-template/package_mpy.json", version="feature/provide-mpy-cross-files")
mip.install("github:brainelectronics/micropython-package-template/package_mpy.json", version="0.15.0")

For MicroPython versions below 1.19.1 use the upip package instead of mip. ⚠️ There are no pre-compiled .mpy packages available.

import upip
upip.install('micropython-package-template==0.12.0')

Test version

Install a specific release candidate version uploaded to Test Python Package Index on every PR on the MicroPython device. If no specific version is set, the latest stable version will be used.

import mip
mip.install("github:brainelectronics/micropython-package-template", version="0.6.0-rc9.dev13")
mip.install("github:brainelectronics/micropython-package-template/package_mpy.json", version="0.15.0-rc5.dev37")

For MicroPython versions below 1.19.1 use the upip package instead of mip. If no specific version is set, upip will always install the latest available version. ⚠️ There are no pre-compiled .mpy packages available.

import upip
# overwrite index_urls to only take artifacts from test.pypi.org
upip.index_urls = ['https://test.pypi.org/pypi']
upip.install('micropython-package-template')

# install a specific version
upip.install("micropython-package-template==0.12.0rc37.dev29")

See also brainelectronics Test PyPI Server in Docker for a test PyPi server running on Docker.

Manually

See Install required tools section on how to install the tools used onwards.

Upload files to board

Copy the module to the MicroPython board and import them as shown below using mpremote or Remote MicroPython shell.

mpremote

mpremote will auto-detect the MicroPython device. Check the mpremote documentation for further details.

mpremote fs mkdir :/lib
mpremote fs cp -rf be_upy_blink/*.py :/lib/
mpremote fs cp -f examples/boot.py examples/main.py :
mpremote fs ls :

Or use the latest package files as defined in the package.json or package_mpy.json file from remote or as part of this repo

# install files as defined in (default) package.json
mpremote mip install package.json

# install *.mpy files as defined in "package_mpy.json" on tag "0.15.0-rc5.dev37"
mpremote mip install github:brainelectronics/micropython-package-template/package_mpy.json@0.15.0-rc5.dev37

rshell

Open the remote shell with the following command. Additionally use -b 115200 in case no CP210x USB to UART bridge is used but a CH34x.

rshell --port /dev/tty.SLAB_USBtoUART --editor nano

Perform the following command inside the rshell to copy all files and folders to the device

mkdir /pyboard/lib
mkdir /pyboard/lib/be_upy_blink

cp be_upy_blink/* /pyboard/lib/be_upy_blink

cp examples/main.py /pyboard
cp examples/boot.py /pyboard

Usage

This is just a very lightweight MicroPython package template with a minimal functional library.

from be_upy_blink import flash_led
from machine import Pin
try:
    from os import uname
except ImportError:
    from uos import uname

os_info = uname()

if 'pyboard' in os_info:
        led_pin = Pin(1, Pin.OUT)
elif 'esp8266' in os_info:
        led_pin = Pin(2, Pin.OUT)
elif 'esp32' in os_info:
        led_pin = Pin(2, Pin.OUT)
elif 'rp2' in os_info:
        # RP2 has the LED on pin 25, Pico W on a custom pin routed to "LED"
        led_pin = Pin("LED", Pin.OUT)
else:
        raise Exception("Unknown board, manually set pin here")

flash_led(pin=led_pin, amount=3)
# flash_led(pin=led_pin, amount=3, on_time=1, off_time=3)

Create a PyPI (micropython) package

Setup

Install the required python package with the following command in a virtual environment to avoid any conflicts with other packages installed on your local system.

python3 -m venv .venv
source .venv/bin/activate

pip install twine

Create a distribution

This module overrides distutils (also compatible with setuptools) sdist command to perform pre- and post-processing as required for MicroPython’s upip package manager. This script is taken from pfalcon’s picoweb and updated to be PEP8 conform.

python setup.py sdist

A new folder dist will be created. The sdist_upip will be used to create everything necessary.

The dist/*.orig file is the non stripped version of the created package. It contains further files which are necessary for a Python package but not required by MicroPython board and would use unnecessary flash on the device.

Upload to PyPI

Be aware: pypi.org and test.pypi.org are different

You can NOT login to test.pypi.org with the pypi.org account unless you created the same on the other. See invalid auth help page of test pypi

For testing purposes add --repository testpypi to upload it to test.pypi.org

twine check dist/*.tar.gz
twine upload dist/micropython-package-template-*.tar.gz -u PYPI_USERNAME -p PYPI_PASSWORD

Contributing

Unittests

Run the unittests locally with the following command after installing this package in a virtual environment

# create a report directory where all generated report files are placed
python create_report_dirs.py

# run all tests
nose2 --config tests/unittest.cfg

# run only one specific tests
nose2 tests.test_blink.TestBlink.test_flash_led

Generate the coverage files with

coverage html

The coverage report is placed at reports/coverage/html/index.html

Steps after using this template

In order to use this template for a new MicroPython package to following steps should be done and changes to these file being made

File	Changes	More details
.coveragerc	Path to version.py file	Omit version file from coverage
.coveragerc	Path to include folder	Include the package folder for coverage
.github/workflows/release.yml	Path to version.py file	Use package version file to set changelog based version
.github/workflows/test-release.yml	Path to version.py file	Use package version file to set changelog based version
.github/workflows/test.yml	Path to version.py file	Use package version file to set changelog based version
.pre-commit-config.yaml	Path to version.py file	Use package version file for validation against latest changelog based version
LICENSE.txt	Year and/or type of license
README.md	Links in header section and installation instructions
changelog.md	Cleanup changelog from informations of template	Keep usage of SemVer
docs/DOCUMENTATION.md	Kink to ReadTheDocs
docs/conf.py	List to modules to be mocked, package import, path to version.py file, update author, project and linkcheck_ignore
docs/index.rst	Header name and included modules	Replace be_upy_blink with new .rst file of new package
docs/NEW_MODULE_NAME.rst	Create a new .rst file named as the package	Use docs/be_upy_blink.rst as template
package.json	Files and paths to new package and repo	Used by mip
setup.py	Path to version.py file, name, description, url, author, author_email, keywords, project_urls, packages, install_requires	Used to create the package and its informations published at e.g. PyPI

Credits

Based on the PyPa sample project.