[README.md] Did some documentation work in the Readme

Also improved memory usage a little bit by import the sleep method only, not the whole time library

README.md

@@ -1,3 +1,60 @@
-# pico-lcd-welcome
+# WelcomeScreen
 
-A simple library providing a customizable welcome screen fading over an LCD
+A simple library providing a customizable welcome screen fading over an LCD.
+Running on a Raspberry Pi Pico.
+
+For execution at startup of any kind of device, for a nice and user-friendly startup!
+
+Support for both 2x16 and 4x20 LCD displays with an I2C backpack (PCF8574T used for development).
+
+
+## How it looks
+
+If you create an instance of the WelcomeScreen class (the only class brought to you by this library), you have several options to make WelcomeScreen adapt to your needs. 
+
+The default behaviour though is the following: First, the string "Starting..." fades over the display in the first/second row (depending on whether the LCD has 2 or 4 lines) one time. In the second/third row, there's a persistent sample text which can easily replaced (e.g. with your device's name, it's function, ...) if you want to.
+
+After that, the whole text displayed is faded out to the bottom, and the flow goes back to whereever the screen has been started.
+
+
+## What it needs
+
+This library is nearly standalone, but it depends on a LCD library for displaying it's content. I used the [PCF8574T](https://git.privacynerd.de/BlueFox/micropython-libraries/src/branch/main/PCF8574T) library for this.
+
+For the examples to work, follow this Wiring:
+
+| Device Pin             | Pi Pico Pin |
+| ---------------------- | ----------- |
+| Interrupt BTN Pin 1    | 3.3V        |
+| Interrupt BTN Pin 2    | GPIO14      |
+| Interrupt SWITCH Pin 1 | 3.3V        |
+| Interrupt SWITCH Pin 2 | GPIO15      |
+| LCD SDA                | GPIO8       |
+| LCD SCL                | GPIO9       |
+| LCD GND                | GND         |
+| LCD VCC                | 5V          |
+
+
+## How to use it
+
+There are examples which can be found in the [examples](examples) folder. 
+For basic usage, you just have to create an LCD object, use it to create a WelcomeScreen object and run the show() method!
+
+```python3
+from WelcomeScreen import WelcomeScreen
+from machine import I2C, Pin  # micropython's built-in library
+from PCF8574T import I2C_LCD  # https://git.privacynerd.de/BlueFox/micropython-libraries/src/branch/main/PCF8574T
+
+LCD = I2C_LCD(I2C(0, sda=Pin(8), scl=Pin(9), freq=400000), 0x27, 2,16)
+
+ws = WelcomeScreen(LCD).show()
+
+lcd.putstr("Now your program")
+```
+
+For extended usage, in the [WelcomeScreen.py](WelcomeScreen.py) file you can find a more detailed listing of what parameters exist, how to use them and what they do.
+
+
+## License
+
+This project is licensed under GPL-3.0-or-later. See [LICENSE](LICENSE).

WelcomeScreen.py

@@ -16,7 +16,7 @@ You should have received a copy of the GNU General Public License
 along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
-import time
+from time import sleep
 
 
 class WelcomeScreen:
@@ -47,13 +47,13 @@ class WelcomeScreen:
     # ---
     # cycles says how often the Starting text goes through
     # ---
-    # wait_after_cycles is an integer number defining how long to wait before returning / if fading
-    # out is activated, the time to wait between end of the cycling animation and the fade out animation
+    # wait_after_cycles is a number in seconds (can be float) defining how long to wait before returning OR
+    # if fading out is activated, the time to wait between end of the cycling animation and the fade out animation
     # ---
     # fade_down is a dict with following keys:
     # - "enabled"      - REQUIRED - wether fading is enabled (default: true)
-    # - "wait_between" - OPTIONAL - the time to wait between each line fade
-    # - "wait_after"   - OPTIONAL - the time to wait after the fade out
+    # - "wait_between" - OPTIONAL - the time in seconds to wait between each line fade
+    # - "wait_after"   - OPTIONAL - the time in seconds to wait after the fade out
     # ---
     # interruptable influences wether the program can be interrupted by pins in the self.interrupt_pins list
     # if this list is empty, even when interruptable is set to true, nothing will be able to interrupt!
@@ -100,7 +100,7 @@ class WelcomeScreen:
         self.lcd.move_to(0,y_offset)
         self.lcd.putstr(self.started_msg.center(16))
         
-        time.sleep(wait_after_cycles)
+        sleep(wait_after_cycles)
         
         # now fade down if enabled via the params
         if fade_down["enabled"]:
@@ -122,4 +122,5 @@ class WelcomeScreen:
                 old_display = old_display[:-self.columns]
                 lines_before = " " * (self.columns*self.lines-len(old_display))
                 self.lcd.putstr(lines_before + old_display)
-    
+                sleep(wait_between)
+            sleep(wait_after)

examples/basic.py

@@ -0,0 +1,18 @@
+from WelcomeScreen import WelcomeScreen
+from machine import I2C, Pin  # micropython's built-in library
+from PCF8574T import I2C_LCD  # https://git.privacynerd.de/BlueFox/micropython-libraries/src/branch/main/PCF8574T
+
+LCD_SDA = Pin(8)                              # just some standard I2C serial data (SDA) outputs (on I2C channel 0 on Pi Pico)
+LCD_SCL = Pin(9)                              # just some standard I2C serial clock (SCL) outputs (on I2C channel 0 on Pi Pico)
+LCD_I2C_ADDR     = 0x27  # the i2c adress of the display (yours might be different to this one)
+LCD_I2C_NUM_ROWS = 2     # how many rows for character display has the display?
+LCD_I2C_NUM_COLS = 16    # and how many characters can it display per row?
+LCD = I2C_LCD(I2C(0, sda=LCD_SDA, scl=LCD_SCL, freq=400000),
+              LCD_I2C_ADDR,
+              LCD_I2C_NUM_ROWS,
+              LCD_I2C_NUM_COLS)
+
+ws = WelcomeScreen(LCD)
+ws.show()
+
+lcd.putstr("Now your program")

examples/complete.py

@@ -0,0 +1,21 @@
+from WelcomeScreen import WelcomeScreen
+from machine import I2C, Pin  # micropython's built-in library
+from PCF8574T import I2C_LCD  # https://git.privacynerd.de/BlueFox/micropython-libraries/src/branch/main/PCF8574T
+
+BTN = Pin(14, Pin.IN, Pin.PULL_DOWN)        # a interrupt btn
+SWITCH = Pin(15, Pin.IN, Pin.PULL_DOWN)        # another interrupt pin (switches also work -> it listens to changes, not high/low!)
+
+LCD_SDA = Pin(8)                              # just some standard I2C serial data (SDA) outputs (on I2C channel 0 on Pi Pico)
+LCD_SCL = Pin(9)                              # just some standard I2C serial clock (SCL) outputs (on I2C channel 0 on Pi Pico)
+LCD_I2C_ADDR     = 0x27  # the i2c adress of the display (yours might be different to this one)
+LCD_I2C_NUM_ROWS = 2     # how many rows for character display has the display?
+LCD_I2C_NUM_COLS = 16    # and how many characters can it display per row?
+LCD = I2C_LCD(I2C(0, sda=LCD_SDA, scl=LCD_SCL, freq=400000),
+              LCD_I2C_ADDR,
+              LCD_I2C_NUM_ROWS,
+              LCD_I2C_NUM_COLS)
+
+ws = WelcomeScreen(LCD, interrupt_pins=[BTN, SWITCH], subtitle="Custom name", starting_msg="Custom etc...", started_msg="Woo-hoo!")
+ws.show(cycles=2, wait_after_cycles=2, fade_down={"enabled":True, "wait_between":0.5, "wait_after":0.2}, interruptable=True)
+
+LCD.putstr("Now your program")