Merge pull request #1 from brainelectronics/feature/initial-implementation

Initial implementation

Author: brainelectronics

.coveragerc

@@ -10,11 +10,13 @@ omit =
     .tox/*,
     build/*,
     dist/*,
-    version.py
+    version.py,
+    lcd_i2c/const.py,
+    lcd_i2c/typing.py,
 
 [report]
 # include = src/*
-include = be_upy_blink/*
+include = lcd_i2c/*
 # Regexes for lines to exclude from consideration
 
 ignore_errors = True

.editorconfig

@@ -15,6 +15,10 @@ trim_trailing_whitespace = true
 [*.py]
 indent_size = 4
 
+[*.json]
+indent_size = 4
+
+# 2 space indentation
 [*.yml]
 indent_size = 2
 

.flake8

@@ -45,7 +45,6 @@ exclude =
     libs_external
     sdist_upip.py
     setup.py
-    update_version.py
 
 # Provide a comma-separated list of glob patterns to add to the list of excluded ones.
 # extend-exclude =

.github/workflows/release.yml

@@ -30,7 +30,7 @@ jobs:
         run: |
           changelog2version \
             --changelog_file changelog.md \
-            --version_file be_upy_blink/version.py \
+            --version_file lcd_i2c/version.py \
             --version_file_type py \
             --debug
           python setup.py sdist

.github/workflows/test-release.yaml

@@ -27,7 +27,7 @@ jobs:
         run: |
           changelog2version \
             --changelog_file changelog.md \
-            --version_file be_upy_blink/version.py \
+            --version_file lcd_i2c/version.py \
             --version_file_type py \
             --additional_version_info="-rc${{ github.run_number }}.dev${{ github.event.number }}" \
             --debug

.github/workflows/test.yml

@@ -44,7 +44,7 @@ jobs:
         run: |
           changelog2version \
             --changelog_file changelog.md \
-            --version_file be_upy_blink/version.py \
+            --version_file lcd_i2c/version.py \
             --version_file_type py \
             --debug
           python setup.py sdist

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 brainelectronics and contributors
+Copyright (c) 2023 brainelectronics and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -1,19 +1,22 @@
-# MicroPython package template
+# MicroPython I2C LCD
 
-[![Downloads](https://pepy.tech/badge/micropython-package-template)](https://pepy.tech/project/micropython-package-template)
-![Release](https://img.shields.io/github/v/release/brainelectronics/micropython-package-template?include_prereleases&color=success)
+[![Downloads](https://pepy.tech/badge/micropython-i2c-lcd)](https://pepy.tech/project/micropython-i2c-lcd)
+![Release](https://img.shields.io/github/v/release/brainelectronics/micropython-i2c-lcd?include_prereleases&color=success)
 ![MicroPython](https://img.shields.io/badge/micropython-Ok-green.svg)
 [![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)
+[![codecov](https://codecov.io/github/brainelectronics/micropython-i2c-lcd/branch/main/graph/badge.svg)](https://app.codecov.io/github/brainelectronics/micropython-i2c-lcd)
+[![CI](https://github.com/brainelectronics/micropython-i2c-lcd/actions/workflows/release.yml/badge.svg)](https://github.com/brainelectronics/micropython-i2c-lcd/actions/workflows/release.yml)
 
-MicroPython PyPi package template project with auto deploy
+Micropython package to control HD44780 LCD displays 1602 and 2004 via I2C
 
 ---------------
 
 ## General
 
-MicroPython PyPi package template with GitHub Action based testing and deploy
+Micropython package to control HD44780 LCD displays 1602 and 2004 via I2C
+
+📚 The latest documentation is available at
+[MicroPython I2C LCD ReadTheDocs][ref-rtd-micropython-i2c-lcd] 📚
 
 <!-- MarkdownTOC -->
 
@@ -27,12 +30,6 @@ MicroPython PyPi package template with GitHub Action based testing and deploy
 	- [Manually](#manually)
 		- [Upload files to board](#upload-files-to-board)
 - [Usage](#usage)
-- [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)
-- [Contributing](#contributing)
-	- [Unittests](#unittests)
 - [Credits](#credits)
 
 <!-- /MarkdownTOC -->
@@ -76,18 +73,35 @@ station.isconnected()
 
 Install the latest package version of this lib on the MicroPython device
 
+```python
+import mip
+mip.install("github:brainelectronics/micropython-i2c-lcd")
+```
+
+For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`
+
 ```python
 import upip
-upip.install('micropython-package-template')
+upip.install('micropython-i2c-lcd')
 ```
 
 #### Specific version
 
 Install a specific, fixed package version of this lib on the MicroPython device
 
+```python
+import mip
+# install a verions of a specific branch
+mip.install("github:brainelectronics/micropython-i2c-lcd", version="feature/initial-implementation")
+# install a tag version
+mip.install("github:brainelectronics/micropython-i2c-lcd", version="0.1.0")
+```
+
+For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`
+
 ```python
 import upip
-upip.install('micropython-package-template==0.1.1')
+upip.install('micropython-i2c-lcd==0.1.0')
 ```
 
 #### Test version
@@ -97,16 +111,20 @@ Install a specific release candidate version uploaded to
 MicroPython device. If no specific version is set, the latest stable version
 will be used.
 
+```python
+import mip
+mip.install("github:brainelectronics/micropython-i2c-lcd", version="0.1.0-rc3.dev1")
+```
+
+For MicroPython versions below 1.19.1 use the `upip` package instead of `mip`
+
 ```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==0.2.0rc1.dev6')
+upip.install('micropython-i2c-lcd==0.1.0rc3.dev1')
 ```
 
-See also [brainelectronics Test PyPi Server in Docker][ref-brainelectronics-test-pypiserver]
-for a test PyPi server running on Docker.
-
 ### Manually
 
 #### Upload files to board
@@ -126,9 +144,9 @@ folders to the device
 
 ```bash
 mkdir /pyboard/lib
-mkdir /pyboard/lib/be_upy_blink
+mkdir /pyboard/lib/lcd_i2c
 
-cp be_upy_blink/* /pyboard/lib/be_upy_blink
+cp lcd_i2c/* /pyboard/lib/lcd_i2c
 
 cp examples/main.py /pyboard
 cp examples/boot.py /pyboard
@@ -137,93 +155,32 @@ cp examples/boot.py /pyboard
 ## Usage
 
 ```python
-from be_upy_blink import flash_led
-from machine import Pin
-
-led_pin = Pin(4, Pin.OUT)
-
-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.
-
-```bash
-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][ref-pfalcon-picoweb-sdist-upip] and updated to be PEP8
-conform.
-
-```bash
-python setup.py sdist
-```
-
-A new folder `dist` will be created. The [`sdist_upip`](sdist_upip.py) will be
-used to create everything necessary.
+from lcd_i2c import LCD
+from machine import I2C, Pin
 
-### Upload to PyPi
+I2C_ADDR = 0x27
+NUM_ROWS = 2
+NUM_COLS = 16
 
-**Be aware: [pypi.org][ref-pypi] and [test.pypi.org][ref-test-pypi] are different**
+# define custom I2C interface, default is 'I2C(0)'
+# check the docs of your device for further details and pin infos
+i2c = I2C(1, scl=Pin(3), sda=Pin(2), freq=800_000)
+lcd = LCD(addr=I2C_ADDR, cols=NUM_COLS, rows=NUM_ROWS, i2c=i2c)
 
-You can **NOT** login to [test.pypi.org][ref-test-pypi] with the
-[pypi.org][ref-pypi] account unless you created the same on the other. See
-[invalid auth help page of **test** pypi][ref-invalid-auth-test-pypi]
-
-For testing purposes add `--repository testpypi` to
-upload it to [test.pypi.org][ref-test-pypi]
-
-```bash
-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
-
-```bash
-# 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
-
-```bash
-python create_report_dirs.py
-coverage html
+lcd.begin()
+lcd.print("Hello World")
 ```
 
-The coverage report is placed at `reports/coverage/html/index.html`
+For further examples check the `examples` folder or the Example chapter in the
+docs.
 
 ## Credits
 
-Based on the [PyPa sample project][ref-pypa-sample].
+Based on [Frank de Brabanders Arduino LiquidCrystal I2C Library][ref-arduino-lcd-i2c-library].
 
 <!-- Links -->
+[ref-rtd-micropython-i2c-lcd]: https://micropython-i2c-lcd.readthedocs.io/en/latest/
 [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
-[ref-pfalcon-picoweb-sdist-upip]: https://github.com/pfalcon/picoweb/blob/b74428ebdde97ed1795338c13a3bdf05d71366a0/sdist_upip.py
+[ref-arduino-lcd-i2c-library]: https://github.com/fdebrabander/Arduino-LiquidCrystal-I2C-library
 [ref-test-pypi]: https://test.pypi.org/
 [ref-pypi]: https://pypi.org/
-[ref-invalid-auth-test-pypi]: https://test.pypi.org/help/#invalid-auth