Skip to content

Display System

Jump to bottom
Mae PUGIN edited this page Mar 21, 2026 · 1 revision

Display System

KeSp supports two display backends, selected at compile time via board.h. Both use LVGL for rendering.

Display Backends

I2C OLED (SSD1306)

Selected with BOARD_DISPLAY_BACKEND_OLED. Typical configuration:

#define BOARD_DISPLAY_BACKEND_OLED
#define DISPLAY_BUS_I2C
#define BOARD_DISPLAY_WIDTH   128
#define BOARD_DISPLAY_HEIGHT  64
#define BOARD_I2C_HOST        I2C_NUM_0
#define BOARD_I2C_SDA         GPIO_NUM_15
#define BOARD_I2C_SCL         GPIO_NUM_7
#define BOARD_I2C_ADDR        0x3C
#define BOARD_I2C_CLK_HZ     400000
#define BOARD_I2C_PULLUPS     true
#define UI_SCALE              1
#define UI_FONT               lv_font_montserrat_14

Features:

  • 128x64 monochrome
  • Layer name display
  • BLE connection status with blink indicator
  • USB connection indicator
  • Boot splash (3 seconds)
  • Mouse activity indicator
  • DFU progress bar

SPI Round Display (GC9A01)

Selected with BOARD_DISPLAY_BACKEND_ROUND. Typical configuration:

#define BOARD_DISPLAY_BACKEND_ROUND
#define DISPLAY_BUS_SPI
#define BOARD_DISPLAY_WIDTH   240
#define BOARD_DISPLAY_HEIGHT  240
#define BOARD_SPI_HOST        SPI2_HOST
#define BOARD_SPI_SCLK        GPIO_NUM_41
#define BOARD_SPI_MOSI        GPIO_NUM_42
#define BOARD_SPI_CS          GPIO_NUM_1
#define BOARD_SPI_DC          GPIO_NUM_2
#define BOARD_SPI_CLK_HZ     20000000
#define UI_SCALE              2
#define UI_FONT               lv_font_montserrat_28

Additional features (beyond OLED):

  • Full-color 240x240 circular display
  • Keys-per-minute (KPM) visualization
  • Tamagotchi virtual pet (reacts to typing activity)
  • Richer boot splash

Display API

Defined in main/display/status_display.h:

Function Description
status_display_start() Initialize display subsystem and LVGL
status_display_update() Periodic refresh (called from display task)
status_display_refresh_all() Full redraw
status_display_sleep() Turn off display (power save)
status_display_wake() Turn on display
status_display_update_layer_name() Update layer name on screen
status_display_show_DFU_prog() Show DFU progress bar
status_display_notify_mouse_activity() Flash mouse indicator
status_display_force_disable() Emergency disable (heap corruption)
draw_separator_line() Draw visual divider

Display Sleep

The display automatically turns off after BOARD_DISPLAY_SLEEP_MS milliseconds of keyboard inactivity. Any keypress wakes it.

#define BOARD_DISPLAY_SLEEP_MS  60000  // 60 seconds

Timing Overrides

These defaults can be overridden in board.h:

Macro Default Description
BT_BLINK_INTERVAL_MS 500 BLE status blink rate
SPLASH_DURATION_MS 3000 Boot splash duration
MOUSE_INDICATOR_MS 200 Mouse activity flash duration

LED Strip

Enabled with BOARD_HAS_LED_STRIP 1 in board.h. Uses WS2812/NeoPixel LEDs.

Configuration

#define BOARD_HAS_LED_STRIP       1
#define BOARD_LED_STRIP_GPIO      GPIO_NUM_4
#define BOARD_LED_STRIP_NUM_LEDS  17

Animation Modes

Mode Enum Description
Off LED_ANIM_OFF All LEDs off
Static LED_ANIM_STATIC Solid color
Breathe LED_ANIM_BREATHE Pulsing brightness
Rainbow LED_ANIM_RAINBOW Cycling rainbow
Chase LED_ANIM_CHASE Moving dot pattern
Reactive LED_ANIM_REACTIVE Flash on keypress
KPM Bar LED_ANIM_KPM_BAR Keys-per-minute bar graph

LED Strip API

Function Description
led_strip_start_task() Create animation FreeRTOS task
led_strip_set_animation(type) Change animation mode
led_strip_get_animation() Get current mode
led_strip_set_color(r, g, b) Set static color
led_strip_set_brightness(0-255) Set brightness
led_strip_notify_keypress() Trigger reactive flash
led_strip_update() Called by animation task
led_strip_test() Blocking RGB test on boot

Frame Rate

#ifndef LED_STRIP_FRAME_MS
#define LED_STRIP_FRAME_MS 20  // 50 FPS
#endif

Adding a New Display Backend

To add support for a new display controller:

  1. Create main/display/your_display.c implementing the init/flush functions
  2. Add a new backend macro: BOARD_DISPLAY_BACKEND_YOUR_DISPLAY
  3. Add the appropriate #ifdef branches in status_display.c
  4. Add the source file to main/CMakeLists.txt
  5. Define the required bus macros (I2C or SPI) in your board.h

KeSp Wiki

Clone this wiki locally