Skip to content

Home

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

KeSp — Keyboard ESP Framework

KeSp is an open-source firmware framework for building custom keyboards on the ESP32-S3 microcontroller. It provides matrix scanning, USB HID, Bluetooth LE, OLED/round display support, LED strip animations, a CDC serial protocol for remapping, and persistent keymap storage — all configurable through a single board.h file.

Features

  • 5×13 matrix scanning with anti-ghosting and configurable debounce
  • USB HID composite device (keyboard + mouse + CDC serial)
  • Bluetooth LE HID with configurable connection parameters
  • 10 layers with per-key remapping via CDC protocol
  • 20 macros (up to 6 keys each), stored in NVS
  • OLED (I2C) or round display (SPI) support via LVGL
  • WS2812 LED strip with 7 animation modes
  • Key statistics and bigram tracking with NVS persistence
  • CDC serial protocol for configuration from companion software
  • Physical layout JSON served to remapping software at connection time
  • DFU (Device Firmware Update) mode
  • Deep sleep with configurable timeout
  • N-key rollover (6KRO fallback on mobile)

Wiki Pages

Page Description
Getting Started Prerequisites, first build, first flash
Creating a New Board Step-by-step guide to add your own keyboard
board.h Reference Complete macro reference for board configuration
Keymap System Layers, key definitions, macros, NVS storage
CDC Protocol All serial commands for remapping software
Display System OLED, round display, LED strip configuration
Build and Flash Build system, multi-board builds, release process
Architecture Task model, boot sequence, code structure

Quick Start

# Clone
git clone https://github.com/mornepousse/KeSp_firmware.git
cd KeSp_firmware

# Build for a specific board
idf.py -DBOARD=kase_v2 build

# Flash
idf.py -p /dev/ttyUSB0 flash

Reference Implementation

The KaSe keyboard is the reference board implementation, available in three variants:

  • kase_v1 — Round SPI display (GC9A01), LED strip, position mapping
  • kase_v2 — OLED I2C display (SSD1306), minimal
  • kase_v2_debug — V2 with swapped debug GPIOs

License

MIT

KeSp Wiki

Clone this wiki locally