From c2c3560e233b13b356d55f5a578c7e1f2ec491e8 Mon Sep 17 00:00:00 2001 From: Anomalocaridid <29845794+Anomalocaridid@users.noreply.github.com> Date: Thu, 17 Aug 2023 15:55:13 -0400 Subject: [PATCH] update display docs --- docs/en/{OLED_Display.md => Display.md} | 97 +++++++++++++++++-------- 1 file changed, 68 insertions(+), 29 deletions(-) rename docs/en/{OLED_Display.md => Display.md} (65%) diff --git a/docs/en/OLED_Display.md b/docs/en/Display.md similarity index 65% rename from docs/en/OLED_Display.md rename to docs/en/Display.md index 266cc46fc..1d5100caa 100644 --- a/docs/en/OLED_Display.md +++ b/docs/en/Display.md @@ -1,48 +1,87 @@ -# OLED Display +# Display Not enough screen space? Add a display to your keyboard! -This documentation concerns the recommended OLED extension. +This documentation concerns the recommended Display extension. *Note:* -Driving an OLED display can bind up a considerable amount of CPU time and RAM. +Driving a display can bind up a considerable amount of CPU time and RAM. Be aware of the performance degradation that can occur. ## Preparation -First of all you need to download a few libraries that will make it possible for your OLED to work. +First of all you need to download a few libraries that will make it possible for your display to work. You can get them with the [Adafruit CircuitPython Libraries bundle](https://circuitpython.org/libraries). Make sure you to choose the one that matches your version of CircuitPython. Create a `lib` directory under the CircuitPython drive and copy the following from the library bundle there: * `adafruit_display_text/` -* `adafruit_displayio_ssd1306.mpy` + +Depending on which kind of display your keyboard has, you may also need a display-specific library. See the below table: + +| Display Type | Library to use | +| ------------------------------------------------------------ | -------------------------------- | +| SSD1306 | `adafruit_displayio_ssd1306.mpy` | +| SH1106 | `adafruit_displayio_ssh1106.mpy` | +| Already initialized (e.g. available through `board.DISPLAY`) | None | ## Configuration -Here's how you may initialize the extension: +Here's how you may initialize the extension. Note that this includes examples of all currently supported display types and you only need the one that corresponds to your display: ```python import board import busio -from kmk.extensions.oled import Oled, TextEntry, ImageEntry + +# For SSD1306 +from kmk.extensions.display import Display, SSD1306, TextEntry, ImageEntry # Replace SCL and SDA according to your hardware configuration. i2c_bus = busio.I2C(board.GP_SCL, board.GP_SDA) -oled = Oled( +driver = SSD1306( # Mandatory: i2c=i2c_bus, # Optional: device_address=0x3C, +) + +# For SH1106 +from kmk.extensions.display import Display, SH1106, TextEntry, ImageEntry + +# Replace SCK and MOSI according to your hardware configuration. +spi_bus = busio.SPI(board.GP_SCK, board.GP_MOSI) + +# Replace command, chip_select, and reset according to your hardware configuration. +driver = SH1106( + # Mandatory: + spi=spi_bus, + command=board.GP_DC, + chip_select=board.GP_CS, + reset=board.GP_RESET, +) + +# For displays initialized by CircuitPython by default +from kmk.extensions.display import Display, BuiltInDisplay, TextEntry, ImageEntry + +# The value to pass may differ between different boards +driver = BuiltInDisplay( + display=board.DISPLAY +) + +# For all display types +display = Display( + # Mandatory: + display=driver, + # Optional: width=128, # screen size - height=64, # screen size + height=32, # screen size flip = False, # flips your display content flip_left = False, # flips your display content on left side split flip_right = False, # flips your display content on right side split - dim_time=10, # time in seconds to reduce screen brightness - dim_target=0.1, # set level for brightness decrease - off_time=0, # time in seconds to turn off screen - brightness=1, # initial screen brightness level + brightness=0.8, # initial screen brightness level brightness_step=0.1, # used for brightness increase/decrease keycodes + dim_time=20, # time in seconds to reduce screen brightness + dim_target=0.1, # set level for brightness decrease + off_time=60, # time in seconds to turn off screen powersave_dim_time=10, # time in seconds to reduce screen brightness powersave_dim_target=0.1, # set level for brightness decrease powersave_off_time=30, # time in seconds to turn off screen @@ -58,42 +97,42 @@ have to be placed in the root of the CircuitPython drive. **Placing it in separate a seperate directory may cause issues.** ```python -oled.entries = [ +display.entries = [ ImageEntry(image="1.bmp", x=0, y=0), ] -keyboard.extensions.append(oled) +keyboard.extensions.append(display) ``` You can also make your images appear only on specific layers, ```python -oled.entries = [ +display.entries = [ ImageEntry(image="1.bmp", x=0, y=0, layer=0), ImageEntry(image="2.bmp", x=0, y=0, layer=1), ] -keyboard.extensions.append(oled) +keyboard.extensions.append(display) ``` and/or side of your split keyboard. ```python -oled.entries = [ +display.entries = [ ImageEntry(image="L1.bmp", x=0, y=0, side="L"), ImageEntry(image="R1.bmp", x=0, y=0, side="R"), ] -keyboard.extensions.append(oled) +keyboard.extensions.append(display) ``` ## Text You're able to freely positon your text to place it wherever you want just by changing x and y values. ```python -oled.entries = [ +display.entries = [ TextEntry(text="Layer = 1", x=0, y=0), TextEntry(text="Macros", x=0, y=12), TextEntry(text="Hey there!", x=0, y=24), ] -keyboard.extensions.append(oled) +keyboard.extensions.append(display) ``` ### X and Y anchors @@ -106,31 +145,31 @@ For more infos about anchors check the [Adafruit docs](https://learn.adafruit.co Notable difference: KMK uses strings ("T", "M","B" and "L", "M", "R") instead of numbers. ```python -oled.entries = [ +display.entries = [ TextEntry(text="Layer = 1", x=128, y=0, x_anchor="R", y_anchor="T"), # text in Top Right corner TextEntry(text="Macros", x=128, y=64, x_anchor="R", y_anchor="B"), # text in Bottom Right corner TextEntry(text="Hey there!", x=64, y=32, x_anchor="M", y_anchor="M"), # text in the Middle of screen ] -keyboard.extensions.append(oled) +keyboard.extensions.append(display) ``` ### Split Same as with images you can change displaying according to current layer or side of split keyboard. ```python -oled.entries = [ +display.entries = [ TextEntry(text="Longer text that", x=0, y=0, layer=0), TextEntry(text="has been divided", x=0, y=12, layer=0, side="L"), TextEntry(text="for an example", x=0, y=24, layer=0, side="R"), ] -keyboard.extensions.append(oled) +keyboard.extensions.append(display) ``` ### Inverting Inverts colours of your text. Comes in handy, for example, as a good layer indicator. ```python -oled_ext = Oled( +display_ext = Display( entries=[ TextEntry(text='0 1 2 4', x=0, y=0), TextEntry(text='0', x=0, y=0, inverted=True, layer=0), @@ -148,14 +187,14 @@ from kmk.kmk_keyboard import KMKKeyboard from kmk.keys import KC from kmk.scanners import DiodeOrientation from kmk.modules.layers import Layers -from kmk.extensions.oled import Oled, TextEntry, ImageEntry +from kmk.extensions.display import Display, TextEntry, ImageEntry keyboard = KMKKeyboard() layers = Layers() keyboard.modules.append(layers) i2c_bus = busio.I2C(board.GP21, board.GP20) -oled = Oled( +display = Display( entries=[ TextEntry(text='Layer: ', x=0, y=32, y_anchor='B'), TextEntry(text='BASE', x=40, y=32, y_anchor='B', layer=0), @@ -176,5 +215,5 @@ oled = Oled( brightness=1, ) -keyboard.extensions.append(oled) +keyboard.extensions.append(display) ```