Autogenerated: Convert PyPi packaging and add Readme Updates

Author: malcolm-sparkfun

README.md

@@ -1,130 +1,161 @@
-Qwiic_OLED_Base_Py
-===================
+![Qwiic OLED - Python Package](docs/images/gh-banner.png "qwiic OLED Python Package")
 
-<p align="center">
-   <img src="https://cdn.sparkfun.com/assets/custom_pages/2/7/2/qwiic-logo-registered.jpg"  width=200>  
-   <img src="https://www.python.org/static/community_logos/python-logo-master-v3-TM.png"  width=240>   
-</p>
-<p align="center">
-	<a href="https://pypi.org/project/sparkfun-qwiic-oled-base/" alt="Package">
-		<img src="https://img.shields.io/pypi/pyversions/sparkfun_qwiic_oled_base.svg" /></a>
-	<a href="https://github.com/sparkfun/Qwiic_OLED_Base_Py/issues" alt="Issues">
-		<img src="https://img.shields.io/github/issues/sparkfun/Qwiic_OLED_Base_Py.svg" /></a>
-	<a href="https://qwiic-oled-base-py.readthedocs.io/en/latest/index.html" alt="Documentation">
-		<img src="https://readthedocs.org/projects/qwiic-oled-base-py/badge/?version=latest&style=flat" /></a>
-	<a href="https://github.com/sparkfun/Qwiic_OLED_Base_Py/blob/master/LICENSE" alt="License">
-		<img src="https://img.shields.io/badge/license-MIT-blue.svg" /></a>
-	<a href="https://twitter.com/intent/follow?screen_name=sparkfun">
-        	<img src="https://img.shields.io/twitter/follow/sparkfun.svg?style=social&logo=twitter"
-           	 alt="follow on Twitter"></a>
-	
-</p>
+# SparkFun Qwiic OLED - Python Package
+
+![PyPi Version](https://img.shields.io/pypi/v/sparkfun_qwiic_oled)
+![GitHub issues](https://img.shields.io/github/issues/sparkfun/qwiic_oled_py)
+![License](https://img.shields.io/github/license/sparkfun/qwiic_oled_py)
+![X](https://img.shields.io/twitter/follow/sparkfun)
+[![API](https://img.shields.io/badge/API%20Reference-blue)](https://docs.sparkfun.com/qwiic_oled_base_py/classqwiic__oled_1_1qwiic__oled__base_1_1_qwiic_oled_base.html)
 
-<img src="https://cdn.sparkfun.com//assets/parts/1/2/6/2/1/14532-SparkFun_Micro_OLED_Breakout__Qwiic_-01.jpg" align="right" width=200 alt="SparkFun Qwiic Micro OLED Breakout">
+The SparkFun Qwiic OLED Module provides a simple and cost effective solution for adding OLED capabilities to your project. Implementing a SparkFun Qwiic I2C interface, these sensors can be rapidly added to any project with boards that are part of the SparkFun Qwiic ecosystem.
 
-The base (superclass/parent) Python package for the [Qwiic_Micro_OLED_Py](https://github.com/sparkfun/Qwiic_Micro_OLED_Py) and [Qwiic_OLED_Display_Py](https://github.com/sparkfun/Qwiic_OLED__Display_Py) derived (subclass/child) Python packages, which are intended for the qwiic [Micro OLED](https://www.sparkfun.com/products/14532) and [OLED Display](https://www.sparkfun.com/products/17153) boards.
+This repository implements a Python package for the SparkFun Qwiic OLED. This package works with Python, MicroPython and CircuitPython.
 
-This package is a port of the [SparkFun Micro OLED Breakout Arduino Library](https://github.com/sparkfun/SparkFun_Micro_OLED_Arduino_Library)
+### Contents
 
-This package can be used in conjunction with the overall [SparkFun qwiic Python Package](https://github.com/sparkfun/Qwiic_Py)
+* [About](#about-the-package)
+* [Getting Started](#getting-started)
+* [Installation](#installation)
+* [Supported Platforms](#supported-platforms)
+* [Documentation](https://docs.sparkfun.com/qwiic_oled_base_py/classqwiic__oled_1_1qwiic__oled__base_1_1_qwiic_oled_base.html)
+* [Examples](#examples)
+
+## About the Package
+
+This python package enables the user to access the features of the OLED via a single Qwiic cable. This includes displaying a splashscreen, drawing shapes, writing different fonts, moving the cursor and more. The capabilities of the OLED are each demonstrated in the included examples.
 
 New to qwiic? Take a look at the entire [SparkFun qwiic ecosystem](https://www.sparkfun.com/qwiic).
 
-<br>
-<img src="https://cdn.sparkfun.com//assets/parts/1/6/1/3/5/17153-SparkFun_Qwiic_OLED_Display__0.91_in__128x32_-01.jpg" align="right" width=200 alt="SparkFun Qwiic OLED Display">
+### Supported SparkFun Products
 
-## Contents
+This Python package supports the following SparkFun qwiic products on Python, MicroPython and Circuit python. 
 
-* [Supported Platforms](#supported-platforms)
-* [Dependencies](#dependencies)
-* [Installation](#installation)
-* [Documentation](#documentation)
-* [Example Use](#example-use)
+* [SparkFun OLED Sensor - OLED](http://www.sparkfun.com/qwiic)
+
+### Supported Platforms
+
+| Python | Platform | Boards |
+|--|--|--|
+| Python | Linux | [Raspberry Pi](https://www.sparkfun.com/raspberry-pi-5-8gb.html) , [NVIDIA Jetson Orin Nano](https://www.sparkfun.com/nvidia-jetson-orin-nano-developer-kit.html) via the [SparkFun Qwiic SHIM](https://www.sparkfun.com/sparkfun-qwiic-shim-for-raspberry-pi.html) |
+| MicroPython | Raspberry Pi - RP2, ESP32 | [SparkFun RP2040 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-rp2040.html), [SparkFun RP2350 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-rp2350.html), [SparkFun ESP32 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-esp32-wroom-usb-c.html)
+|CircuitPython | Raspberry Pi - RP2, ESP32 | [SparkFun RP2040 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-rp2040.html), [SparkFun RP2350 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-rp2350.html), [SparkFun ESP32 Thing+](https://www.sparkfun.com/sparkfun-thing-plus-esp32-wroom-usb-c.html)
+
+> [!NOTE]
+> The listed supported platforms and boards are the primary platform targets tested. It is fully expected that this package will work across a wide variety of Python enabled systems. 
+
+## Installation 
 
-Supported Platforms
---------------------
-The qwiic Python package current supports the following platforms:
-* [Raspberry Pi](https://www.sparkfun.com/search/results?term=raspberry+pi)
-* [NVidia Jetson Nano](https://www.sparkfun.com/products/15297)
-* [Google Coral Development Board](https://www.sparkfun.com/products/15318)
+The first step to using this package is installing it on your system. The install method depends on the python platform. The following sections outline installation on Python, MicroPython and CircuitPython.
 
-Dependencies
-================
-This driver package depends on the qwiic I2C driver: 
-[Qwiic_I2C_Py](https://github.com/sparkfun/Qwiic_I2C_Py)
+### Python 
 
-Documentation
--------------
-The SparkFun qwiic OLED Base module documentation is hosted at [ReadTheDocs](https://qwiic-oled-base-py.readthedocs.io/en/latest/index.html)
+#### PyPi Installation
 
-Installation
---------------
+The package is primarily installed using the `pip3` command, downloading the package from the Python Index - "PyPi". 
 
-### PyPi Installation
-This repository is hosted on PyPi as the [sparkfun-qwiic-oled-base](https://pypi.org/project/sparkfun-qwiic-oled-base/) package. On systems that support PyPi installation via pip, this library is installed using the following commands
+Note - the below instructions outline installation on a Linux-based (Raspberry Pi) system.
 
-For all users (note: the user must have sudo privileges):
+First, setup a virtual environment from a specific directory using venv:
 ```sh
-sudo pip install sparkfun-qwiic-oled-base
+python3 -m venv path/to/venv
 ```
-For the current user:
+You can pass any path as path/to/venv, just make sure you use the same one for all future steps. For more information on venv [click here](https://docs.python.org/3/library/venv.html).
 
+Next, install the qwiic package with:
 ```sh
-pip install sparkfun_qwiic_oled_base
+path/to/venv/bin/pip3 install sparkfun-qwiic-oled
+```
+Now you should be able to run any example or custom python scripts that have `import qwiic_oled` by running e.g.:
+```sh
+path/to/venv/bin/python3 example_script.py
 ```
 
-### Local Installation
-To install, make sure the setuptools package is installed on the system.
+### MicroPython Installation
+If not already installed, follow the [instructions here](https://docs.micropython.org/en/latest/reference/mpremote.html) to install mpremote on your computer.
 
-Direct installation at the command line:
+Connect a device with MicroPython installed to your computer and then install the package directly to your device with mpremote mip.
 ```sh
-python setup.py install
+mpremote mip install github:sparkfun/qwiic_oled_py
 ```
 
-To build a package for use with pip:
+If you would also like to install the examples for this repository, issue the following mip command as well:
 ```sh
-python setup.py sdist
- ```
-A package file is built and placed in a subdirectory called dist. This package file can be installed using pip.
+mpremote mip install github:sparkfun/qwiic_oled_py@examples
+```
+
+### CircuitPython Installation
+If not already installed, follow the [instructions here](https://docs.circuitpython.org/projects/circup/en/latest/#installation) to install CircUp on your computer.
+
+Ensure that you have the latest version of the SparkFun Qwiic CircuitPython bundle. 
 ```sh
-cd dist
-pip install sparkfun_oled_base-<version>.tar.gz
+circup bundle-add sparkfun/Qwiic_Py
 ```
-  
+
+Finally, connect a device with CircuitPython installed to your computer and then install the package directly to your device with circup.
+```sh
+circup install --py qwiic_oled
+```
+
+If you would like to install any of the examples from this repository, issue the corresponding circup command from below. (NOTE: The below syntax assumes you are using CircUp on Windows. Linux and Mac will have different path seperators. See the [CircUp "example" command documentation](https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/example-command) for more information)
+
+```sh
+circup example qwiic_oled\ex1_splash_screen
+circup example qwiic_oled\ex2_hello_world
+circup example qwiic_oled\ex3_demo
+circup example qwiic_oled\ex4_cube
+circup example qwiic_oled\ex5_micro_bitmap
+```
+
 Example Use
-------------
-This example is intended to be used with the [Micro OLED Breakout](https://www.sparkfun.com/products/14532) board. (See the <a href="https://github.com/sparkfun/Qwiic_OLED_Base_Py/tree/main/examples">examples directory</a> for more detailed use cases.)
+ ---------------
+Below is a quickstart program to print readings from the OLED.
+
+See the examples directory for more detailed use examples and [examples/README.md](https://github.com/sparkfun/qwiic_oled_py/blob/main/examples/README.md) for a summary of the available examples.
 
 ```python
-import qwiic_oled_base
+
+import qwiic_oled
+import time
 import sys
 
 
-def runExample():
+userOLED = qwiic_oled.QwiicMicroOled()   # Micro OLED             https://www.sparkfun.com/products/14532
 
-    #  These lines of code are all you need to initialize the OLED display and print text on the screen.
+def runExample():
 
-    print("\nSparkFun Micro OLED Hello Example\n")
-    myOLED = qwiic_oled_base.QwiicOledBase()
+    print("\nOLED Display - Splash screen example\n")
+    myOLED = userOLED
 
-    if myOLED.is_connected() == False:
-        print("The Qwiic Micro OLED device isn't connected to the system. Please check your connection", \
+    if not myOLED.connected:
+        print("The OLED Display isn't connected to the system. Please check your connection", \
             file=sys.stderr)
         return
 
-    #  Before you can start using the OLED, call begin() to init all of the pins and configure the OLED.
     myOLED.begin()
 
+    myOLED.clear(myOLED.ALL) #  Clear the display's memory (gets rid of artifacts)
+  
+    myOLED.display()  #  Display buffer contents
+    time.sleep(3)
+
     myOLED.clear(myOLED.PAGE)  #  Clear the display's buffer
 
-    myOLED.print("Hello World")  #  Add "Hello World" to buffer
+    myOLED.display()
+    time.sleep(3)
+
+    qwiic_oled.oled_logos.add_logo(myOLED._screenbuffer)
 
-    #  To actually draw anything on the display, you must call the display() function. 
     myOLED.display()
 
-runExample()
-```
+if __name__ == '__main__':
+    try:
+        runExample()
+    except (KeyboardInterrupt, SystemExit) as exErr:
+        print("\nEnding OLED bitmap Example")
+        sys.exit(0)
 
+```
 <p align="center">
 <img src="https://cdn.sparkfun.com/assets/custom_pages/3/3/4/dark-logo-red-flame.png" alt="SparkFun - Start Something">
 </p>

docs/images/gh-banner.png

@@ -0,0 +1,21 @@
+# Sparkfun OLED Examples Reference
+Below is a brief summary of each of the example programs included in this repository. To report a bug in any of these examples or to request a new feature or example [submit an issue in our GitHub issues.](https://github.com/sparkfun/qwiic_oled_py/issues). 
+
+NOTE: Any numbering of examples is to retain consistency with the Arduino library from which this was ported. 
+
+## Ex1 Splash Screen
+Simple Example for an OLED Display that displays the SparkFun splash screen
+
+## Ex2 Hello World
+"Hello World" Example for an OLED Display
+
+## Ex3 Demo
+An example showing various features of the display driver for Qwiic OLED displays
+
+## Ex4 Cube
+Cube Example for a Qwiic OLED Device
+
+## Ex5 Micro Bitmap
+Example for the Qwiic Micro OLED display that displays Bender's face!
+
+

examples/README.md

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools"]
+
+[project]
+name = "sparkfun_qwiic_oled_base"
+version = "0.0.2"
+description = "SparkFun Electronics qwiic OLED Base package"
+readme = "DESCRIPTION.rst"
+
+authors = [{name="Sparkfun Electronics", email="info@sparkfun.com"}]
+dependencies = ["sparkfun_qwiic_i2c"]
+
+classifiers=[
+    # How mature is this project? Common values are
+    #   3 - Alpha
+    #   4 - Beta
+    #   5 - Production/Stable
+    "Development Status :: 5 - Production/Stable",
+
+    # Indicate who your project is intended for
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+
+    # Pick your license as you wish (should match "license" above)
+    "License :: OSI Approved :: MIT License",
+
+    # Specify the Python versions you support here. In particular, ensure
+    # that you indicate whether you support Python 2, Python 3 or both.
+    "Programming Language :: Python :: 3.5",
+    "Programming Language :: Python :: 3.6",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: MicroPython",
+    # NOTE: CircuitPython is also supported, but no classifier exists for it
+]
+
+keywords = ["electronics, maker"]
+
+[project.urls]
+homepage = "http://www.sparkfun.com/qwiic"
+
+[tool.setuptools]
+packages = ["qwiic_oled"]

pyproject.toml

@@ -0,0 +1 @@
+sparkfun_qwiic_i2c