diff --git a/.snippets/34.md b/.snippets/34.md new file mode 100644 index 0000000..800ba59 --- /dev/null +++ b/.snippets/34.md @@ -0,0 +1,16 @@ +## Update README for mpremote and package usage + + +This change updates the manual package installation instructions to use `mpremote` over `rshell`. + +In the PyPI section the usage of `twine check` before `twine upload` is recommended. + +An example instruction on how to install a specific version with `upip` was added. + +The package usage example and the corresponding `main.py` example files are extended to set the LED pin based on the board extracted from `os.uname()`. + +This closes [#34](https://github.com/brainelectronics/micropython-package-template/issues/34) diff --git a/README.md b/README.md index 7b19e2b..50ff73b 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,16 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![codecov](https://codecov.io/github/brainelectronics/micropython-package-template/branch/main/graph/badge.svg)](https://app.codecov.io/github/brainelectronics/micropython-package-template) [![CI](https://github.com/brainelectronics/micropython-package-template/actions/workflows/release.yml/badge.svg)](https://github.com/brainelectronics/micropython-package-template/actions/workflows/release.yml) +![Humans](https://img.shields.io/badge/Created_by-Humans-blue?style=flat +) -MicroPython PyPi package template project with auto deploy +MicroPython (PyPI) package template project with auto deploy --------------- ## General -MicroPython PyPi package template with GitHub Action based testing and deploy +MicroPython (PyPI) package template with GitHub Action based testing and deploy 📚 The latest documentation is available at [MicroPython Package Template ReadTheDocs][ref-rtd-micropython-package-template] 📚 @@ -23,17 +25,19 @@ MicroPython PyPi package template with GitHub Action based testing and deploy - [Installation](#installation) - [Install required tools](#install-required-tools) - [Setup](#setup) - - [Install package](#install-package) + - [Install package from the web](#install-package-from-the-web) - [General](#general) - [Specific version](#specific-version) - [Test version](#test-version) - [Manually](#manually) - [Upload files to board](#upload-files-to-board) + - [mpremote](#mpremote) + - [rshell](#rshell) - [Usage](#usage) -- [Create a PyPi \(micropython\) package](#create-a-pypi-micropython-package) +- [Create a PyPI \(micropython\) package](#create-a-pypi-micropython-package) - [Setup](#setup-1) - [Create a distribution](#create-a-distribution) - - [Upload to PyPi](#upload-to-pypi) + - [Upload to PyPI](#upload-to-pypi) - [Contributing](#contributing) - [Unittests](#unittests) - [Steps after using this template](#steps-after-using-this-template) @@ -60,14 +64,21 @@ 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 +### Install package from the web -Connect the MicroPython device to a network (if possible) +Connect the MicroPython device to a network, otherwise check the section [Manually](#manually) down below. ```python import network @@ -86,13 +97,24 @@ import mip mip.install("github:brainelectronics/micropython-package-template") ``` -For MicroPython versions below 1.19.1 use the `upip` package instead of `mip` +For MicroPython versions below `1.19.1` use the `upip` package instead of `mip` ```python import upip upip.install('micropython-package-template') ``` +Run this code on the MicroPython device to check the used MicroPython version + +```python +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 @@ -105,7 +127,7 @@ mip.install("github:brainelectronics/micropython-package-template", version="fea mip.install("github:brainelectronics/micropython-package-template", version="0.6.0") ``` -For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`. +For MicroPython versions below `1.19.1` use the `upip` package instead of `mip`. With `upip` always the latest available version will be installed. ```python @@ -125,28 +147,46 @@ import mip mip.install("github:brainelectronics/micropython-package-template", version="0.6.0-rc9.dev13") ``` -For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`. -With `upip` always the latest available version will be installed. +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. ```python 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][ref-brainelectronics-test-pypiserver] +See also [brainelectronics Test PyPI Server in Docker][ref-brainelectronics-test-pypiserver] for a test PyPi server running on Docker. ### Manually +See [Install required tools](#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 [Remote MicroPython shell][ref-remote-upy-shell] +using [mpremote][ref-mpremote] or [Remote MicroPython shell][ref-remote-upy-shell]. + +##### mpremote + +`mpremote` will auto-detect the MicroPython device. Check the [mpremote][ref-mpremote] documentation for further details. + +```bash +mpremote fs mkdir :/lib +mpremote fs cp -r be_upy_blink/ :/lib/ +mpremote fs cp examples/boot.py examples/main.py : +mpremote fs ls : +``` + +##### rshell Open the remote shell with the following command. Additionally use `-b 115200` -in case no CP210x is used but a CH34x. +in case no `CP210x` USB to UART bridge is used but a `CH34x`. ```bash rshell --port /dev/tty.SLAB_USBtoUART --editor nano @@ -167,17 +207,35 @@ cp examples/boot.py /pyboard ## Usage +This is just a very lightweight MicroPython package template with a minimal functional library. + ```python from be_upy_blink import flash_led from machine import Pin - -led_pin = Pin(4, Pin.OUT) +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 +## Create a PyPI (micropython) package ### Setup @@ -207,7 +265,11 @@ python setup.py sdist A new folder `dist` will be created. The [`sdist_upip`](sdist_upip.py) will be used to create everything necessary. -### Upload to PyPi +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][ref-pypi] and [test.pypi.org][ref-test-pypi] are different** @@ -219,6 +281,7 @@ For testing purposes add `--repository testpypi` to upload it to [test.pypi.org][ref-test-pypi] ```bash +twine check dist/*.tar.gz twine upload dist/micropython-package-template-*.tar.gz -u PYPI_USERNAME -p PYPI_PASSWORD ``` @@ -263,6 +326,7 @@ should be done and changes to these file being made | `.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 | | @@ -278,6 +342,7 @@ Based on the [PyPa sample project][ref-pypa-sample]. [ref-rtd-micropython-package-template]: https://micropython-package-template.readthedocs.io/en/latest/ +[ref-mpremote]: https://docs.micropython.org/en/v1.28.0/reference/mpremote.html [ref-remote-upy-shell]: https://github.com/dhylands/rshell [ref-brainelectronics-test-pypiserver]: https://github.com/brainelectronics/test-pypiserver [ref-pypa-sample]: https://github.com/pypa/sampleproject diff --git a/be_upy_blink/version.py b/be_upy_blink/version.py index f0aa609..02b1be4 100644 --- a/be_upy_blink/version.py +++ b/be_upy_blink/version.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 # -*- coding: UTF-8 -*- -__version_info__ = ("0", "13", "1") +__version_info__ = ("0", "14", "0") __version__ = '.'.join(__version_info__) diff --git a/examples/main.py b/examples/main.py index 5d9de34..6df52db 100644 --- a/examples/main.py +++ b/examples/main.py @@ -8,12 +8,31 @@ from be_upy_blink import flash_led from machine import Pin +try: + from os import uname +except ImportError: + # u-packages might be deprecated in future + from uos import uname from time import sleep def loop(): - # set pin D4 as output (blue LED) and turn it off - led_pin = Pin(4, Pin.OUT) + os_info = uname() + + # set pin as output + 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 extend main.py") + + # turn it off led_pin.value(0) # loop forever diff --git a/package.json b/package.json index 29231f0..b90a526 100644 --- a/package.json +++ b/package.json @@ -14,5 +14,5 @@ ] ], "deps": [], - "version": "0.13.1" + "version": "0.14.0" } \ No newline at end of file