{"id":43789309,"url":"https://github.com/raspberrypi/rpi-keyboard-config","last_synced_at":"2026-02-05T20:02:16.010Z","repository":{"id":336564872,"uuid":"1055676546","full_name":"raspberrypi/rpi-keyboard-config","owner":"raspberrypi","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-03T13:53:36.000Z","size":39,"stargazers_count":10,"open_issues_count":4,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-02-05T14:36:12.581Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raspberrypi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-12T16:16:13.000Z","updated_at":"2025-12-25T22:54:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/raspberrypi/rpi-keyboard-config","commit_stats":null,"previous_names":["raspberrypi/rpi-keyboard-config"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/raspberrypi/rpi-keyboard-config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-keyboard-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-keyboard-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-keyboard-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-keyboard-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raspberrypi","download_url":"https://codeload.github.com/raspberrypi/rpi-keyboard-config/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raspberrypi%2Frpi-keyboard-config/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29132521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T19:36:52.185Z","status":"ssl_error","status_checked_at":"2026-02-05T19:35:40.941Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-05T20:02:14.817Z","updated_at":"2026-02-05T20:02:16.003Z","avatar_url":"https://github.com/raspberrypi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RPi Keyboard Config\n\nA Python library and command-line tool for configuring Raspberry Pi keyboards, including keymap customisation and RGB LED control.\n\n## Supported Keyboards\n\n- **Raspberry Pi 500** (USB VID: 2e8a, PID: 0010)\n- **Raspberry Pi 500+** (USB VID: 2e8a, PID: 0011)\n\n## Features\n\n- **Keymap Configuration**: Set custom keycodes for any key position\n- **RGB LED Control**: Control individual LEDs\n- **Effects**: Built-in lighting effects (solid, gradient, pinwheel, heatmap, reactive, etc.)\n- **Presets**: Change the preset effects that can be cycled through by pressing Fn+F4\n- **Key Monitoring**: Watch for key presses\n- **Demos**: Flappy Bird game and LED random test pattern\n\n## Installation\n\n```bash\nsudo apt install rpi-keyboard-config\n```\n\nThe Debian package automatically installs udev rules.\n\n### Keyboard Firmware\n\nThe keyboard must have the latest firmware to be compatible. Use \u003chttps://github.com/raspberrypi/keyboard-firmware\u003e to update the firmware:\n\n```bash\nsudo rpi-keyboard-fw-update\n```\n\n## Command Line Usage\n\n### Basic Information\n\n```bash\n# Show keyboard information\nrpi-keyboard-config info\n\n# Show keyboard information with ASCII art layout\nrpi-keyboard-config info --ascii\n\n# Get firmware version only\nrpi-keyboard-config get-version\n```\n\n### Keymap Configuration\n\nKey mappings can be dynamically changed using `rpi-keyboard-config key` or \u003chttps://vial.rocks/\u003e.\n\n```bash\n# Get keycode for a specific key position\nrpi-keyboard-config key get \u003crow\u003e \u003ccol\u003e [--layer \u003clayer\u003e]\n\n# Set keycode for a specific key position\nrpi-keyboard-config key set \u003crow\u003e \u003ccol\u003e \u003ckeycode\u003e [--layer \u003clayer\u003e]\n\n# List keycodes for all keys\nrpi-keyboard-config key get-all [--layer \u003clayer\u003e]\n\n# Examples\nrpi-keyboard-config key get 2 3              # Get key at row 2, col 3\nrpi-keyboard-config key set 2 3 KC_A         # Set key to 'A'\nrpi-keyboard-config key get-all              # List all keys and their keycodes\n\n# Reset keymap to defaults\nrpi-keyboard-config reset-keymap\n```\n\n### Keyboard Lock/Unlock\n\nOnly required for a handful of operations e.g. key monitoring. See \u003chttps://get.vial.today/docs/security.html\u003e for more details.\n\n```bash\n# Unlock keyboard\nrpi-keyboard-config unlock\n\n# Lock keyboard\nrpi-keyboard-config lock\n```\n\n### Key Monitoring\n\nNote: Key monitoring requires the keyboard to be unlocked first.\n\n```bash\n# Watch for key presses and show details\nrpi-keyboard-config key watch [--layer \u003clayer\u003e] [--no-leds] [--exit-key \u003ckey\u003e]\n\n# Examples\nrpi-keyboard-config key watch                   # Watch with LED feedback (Pi 500+ only)\nrpi-keyboard-config key watch --no-leds         # Watch without LED feedback\n```\n\n### LED Control (Raspberry Pi 500+ only)\n\n### Global Hue and Brightness Control\n\nThe default keys on the Pi 500+ to increase and decrease the global hue are Fn+F3 and Fn+Shift+F3 respectively.\nThe default keys on the Pi 500+ to increase and decrease the global brightness are Fn+F6 and Fn+F5 respectively.\n\n```bash\n# Get current global hue\nrpi-keyboard-config hue\n\n# Set global hue (affects compatible effects)\nrpi-keyboard-config hue \u003c0-255\u003e\n\n# Example\nrpi-keyboard-config hue 85      # Set to green hue\n\n# Get current global brightness\nrpi-keyboard-config brightness\n\n# Set global brightness\nrpi-keyboard-config brightness \u003c0-255\u003e\n\n# Example\nrpi-keyboard-config brightness 255     # Set to maximum brightness\n```\n\n### RGB Effects\n\nA selection of effects to control the RGB are available. The tool allows you to show an effect on the keyboard temporarily (until the keyboard shuts down, the Fn+F4 key is pressed or something triggers a new effect). A preset on the keyboard can also be set, which is an effect at a given preset index. Pressing Fn+F4 will cycle through the presets and the previously selected preset will be restored after reboot.\nTemporary effects are stored at preset index 7 which cannot be cycled through.\n\n```bash\n# Show current effect\nrpi-keyboard-config effect\n\n# Set effect with parameters\nrpi-keyboard-config effect \u003ceffect\u003e [--hue \u003c0-255\u003e] [--sat \u003c0-255\u003e] [--speed \u003c0-255\u003e]\n# Adding --hue will fix the hue at the specified value, otherwise the effect will use the global hue value\n\n# Show available RGB effects\nrpi-keyboard-config list-effects\n\n# Examples\nrpi-keyboard-config effect \"Solid Color\" --hue 0 --sat 255           # Solid red (fixed hue)\nrpi-keyboard-config effect \"Cycle Pinwheel\" --speed 200     # Fast pinwheel\nrpi-keyboard-config effect \"Typing Heatmap\"                  # Heat map effect\n```\n\nNote: The value component of HSV cannot be set, this is controlled by the brightness of the keyboard. Some effects may ignore the set hue and saturation.\n\n### RGB Presets\n\nPresets can be cycled through by default by pressing Fn+F4. The previously shown preset will be restored on reboot.\n\n```bash\n# Get current preset index\nrpi-keyboard-config preset index\n\n# Set preset index\nrpi-keyboard-config preset index \u003c0-7\u003e\n\n# Get preset configuration\nrpi-keyboard-config preset get [index]               # If no index, shows all presets\nrpi-keyboard-config preset get 2                     # Show preset 2 configuration\n\n# Set preset configuration\nrpi-keyboard-config preset set \u003cindex\u003e [effect] [--hue \u003c0-255\u003e] [--sat \u003c0-255\u003e] [--speed \u003c0-255\u003e] [--startup-animation \u003canimation\u003e]\n\n# Revert to saved preset index (useful after setting a temporary effect)\nrpi-keyboard-config preset revert\n\n# Examples\nrpi-keyboard-config preset set 0 \"Solid Color\" --hue 0 --sat 255     # Set preset 0 to solid red\nrpi-keyboard-config preset set 3 \"Cycle Pinwheel\" --speed 150        # Set preset 3 to medium-speed pinwheel\nrpi-keyboard-config preset set 2 --hue 85 --sat 255                  # Change preset 2 hue to green, keep current effect\nrpi-keyboard-config preset index 2                                   # Switch to preset 2\n\n# Only cycle through the first 3 presets before looping back to the start\nrpi-keyboard-config preset set 3 skip\n\n# Set the startup animation\nrpi-keyboard-config preset set 0 \"Solid Color\" --startup-animation \"START_ANIM_W_FADE_SAT\"\n```\n\n#### Startup animation options\n\n| Animation Name             | Description                                 |\n|---------------------------|---------------------------------------------|\n| START_ANIM_NONE           | No startup animation                        |\n| START_ANIM_B_NO_FADE      | Show the startup animation finishing with blank LEDs then go straight to the preset |\n| START_ANIM_B_FADE_VAL     | START_ANIM_B_NO_FADE but fade in the preset with increasing brightness          |\n| START_ANIM_W_NO_FADE      | Show the startup animation finishing with all the LEDs white then go straight to the preset |\n| START_ANIM_W_FADE_SAT     | START_ANIM_W_NO_FADE but fade in with increasing saturation          |\n\n#### LED Operations\n\nIf the currently shown preset is not the direct led effect then the keyboard will be set to a temporary direct led effect.\n\n```bash\n# Clear all LEDs\nrpi-keyboard-config leds clear\n\n# Set all LEDs to a colour (HSV format by default)\nrpi-keyboard-config leds set --colour red\nrpi-keyboard-config leds set --colour \"128,255,255\"     # HSV values\nrpi-keyboard-config leds set --colour \"#FF0000\"         # RGB hex\nrpi-keyboard-config leds set --colour \"rgb(255,0,0)\"    # RGB values\n\n# Get current LED states\nrpi-keyboard-config leds get\n\n# Get saved LED states from EEPROM\nrpi-keyboard-config leds get-saved\n\n# Save current LED configuration to EEPROM\nrpi-keyboard-config leds save\n\n# Load saved LED configuration from EEPROM\nrpi-keyboard-config leds load\n```\n\n#### Individual LED Control\n\n```bash\n# Set individual LED by index\nrpi-keyboard-config led set \u003cindex\u003e --colour \u003ccolour\u003e\n\n# Set LED by matrix position\nrpi-keyboard-config led set \u003crow\u003e,\u003ccol\u003e --colour \u003ccolour\u003e\n\n# Examples\nrpi-keyboard-config led set 5 --colour blue        # Set LED index 5 to blue\nrpi-keyboard-config led set 2,3 --colour green     # Set LED at matrix [2,3] to green\nrpi-keyboard-config led set 10 --colour \"170,255,255\"  # Set LED 10 to cyan (HSV)\n```\n\n### Reset Operations\n\n```bash\n# Reset RGB presets and direct LEDs\nrpi-keyboard-config reset-presets\n\n# Reset keymap to defaults\nrpi-keyboard-config reset-keymap\n```\n\n### Colour Formats\n\nColours can be specified in several formats:\n\n- **Named colours**: `red`, `green`, `blue`, `yellow`, `cyan`, `magenta`, `white`, `orange`, `purple`, `pink`\n- **HSV values** (default): `128,255,255` (hue, saturation, value)\n- **RGB Hex colours**: `#FF0000`\n- **RGB values** (explicit): `rgb(255,0,0)` - must use `rgb()` prefix\n\n### QMK Keycode Listing\n\n```bash\n# List all keycodes\nrpi-keyboard-config list-keycodes\n\n# Filter by category\nrpi-keyboard-config list-keycodes --category basic      # Letters, numbers, basic symbols\nrpi-keyboard-config list-keycodes --category modifiers  # Ctrl, Shift, Alt, etc.\n\n# Search by name (case-insensitive)\nrpi-keyboard-config list-keycodes --filter \"slash\"\n```\n\n### Games and Demos\n\n```bash\n# Play Flappy Bird game on the keyboard LEDs (Pi 500+ only)\nrpi-keyboard-config game\n\n# Run random LED test pattern (Pi 500+ only)\nrpi-keyboard-config random-leds\n```\n\n## Python Library Usage\n\n### Basic Setup\n\n```python\nfrom RPiKeyboardConfig import RPiKeyboardConfig\n\n# Initialise the keyboard\nkeyboard = RPiKeyboardConfig()\n```\n\n### Keyboard Information\n\n```python\n# Get keyboard model and info\nprint(f\"Model: {keyboard.model}\")           # \"PI500\" or \"PI500PLUS\"\nprint(f\"Variant: {keyboard.variant}\")       # \"ISO\", \"ANSI\", or \"JIS\"\n\n# Get firmware version\nversion = keyboard.get_firmware_version()\nprint(f\"Firmware: {version[0]}.{version[1]}.{version[2]}\")\n\n# Get ASCII art of current keyboard layout\nascii_map = keyboard.get_ascii_keycode_map(layer=0)\nprint(ascii_map)\n```\n\n### Keymap Configuration\n\n```python\n# Get keycode for a key\nkeycode = keyboard.get_keycode(matrix=[2, 3], layer=0)\nprint(f\"Key at [2,3] has keycode: {keycode}\")\n\n# Set keycode for a key\nkeyboard.set_keycode(matrix=[2, 3], layer=0, keycode=4)  # Set to 'A'\n\n# Get keycodes for all keys\nall_keynames = keyboard.get_all_keynames(layer=0)\nfor data in all_keynames:\n    pos = data['position']\n    print(f\"Key at row {pos[0]:2d}, col {pos[1]:2d}: Keycode {data['keycode']:5d} -\u003e {data['name']}\")\n\n# Reset keymap to defaults\nkeyboard.reset_keymap()\n```\n\n### Key Monitoring and Unlock\n\n```python\n# Check if keyboard needs unlocking\nunlocked, unlock_in_progress, unlock_keys = keyboard.get_unlock_status()\nif not unlocked:\n    print(\"Unlocking keyboard...\")\n    keyboard.unlock()\n\n# Get switch matrix state (currently pressed keys) - requires unlock\nif unlocked:\n    active_keys = keyboard.get_switch_matrix_state()\n    print(f\"Currently pressed keys: {active_keys}\")\n\n# Lock the keyboard\nkeyboard.lock()\n```\n\n### LED Control (Raspberry Pi 500+ only)\n\n#### Basic LED Operations\n\n```python\n# Set LED direct control mode\nkeyboard.set_led_direct_effect()\n\n# Set individual LED by index (HSV format: hue, saturation, value)\nkeyboard.set_led_by_idx(idx=5, colour=(0, 255, 255))      # Red\nkeyboard.set_led_by_idx(idx=6, colour=(85, 255, 255))     # Green\nkeyboard.set_led_by_idx(idx=7, colour=(170, 255, 255))    # Cyan\n\n# Set LED by matrix position\nkeyboard.set_led_by_matrix(matrix=[2, 3], colour=(42, 255, 255))  # Orange\n\n# Send LED updates to keyboard (required after setting colours)\nkeyboard.send_leds()\n\n# Clear all LEDs\nkeyboard.rgb_clear()\n```\n\n#### Advanced LED Operations\n\n```python\n# Get current LED states\ncurrent_leds = keyboard.get_current_direct_leds()\nfor i, (h, s, v) in enumerate(current_leds):\n    print(f\"LED {i}: HSV({h}, {s}, {v})\")\n\n# Get individual LED info\nled_info = keyboard.get_led_info(idx=5)\nprint(f\"LED 5: {led_info}\")\n\n# Get all LED configurations\nall_leds = keyboard.get_leds()\nfor led in all_leds:\n    print(f\"LED {led.idx}: matrix={led.matrix}, colour={led.colour}\")\n\n# Save current LED configuration to EEPROM\nkeyboard.save_direct_leds()\n\n# Load saved LED configuration from EEPROM\nkeyboard.load_direct_leds()\n\n# Get saved LED configurations\nsaved_leds = keyboard.get_saved_direct_leds()\n```\n\n### Global Hue and Brightness Control\n\n```python\n# Get current global hue\ncurrent_hue = keyboard.get_hue()\nprint(f\"Current hue: {current_hue}\")\n\n# Set global hue (affects compatible effects)\nkeyboard.set_hue(85)  # Set to green hue\n\n# Get current global brightness\ncurrent_brightness = keyboard.get_brightness()\nprint(f\"Current brightness: {current_brightness}\")\n\n# Set global brightness\nkeyboard.set_brightness(128)  # Set to medium brightness\n```\n\n### RGB Effects and Presets\n\n```python\n# Get supported effects\neffects = keyboard.get_supported_effects()\nprint(f\"Supported effects: {effects}\")\n\n# Get current effect\ncurrent_effect = keyboard.get_current_effect()\nprint(f\"Current effect: {current_effect}\")\n\n# Create and set a preset\nfrom RPiKeyboardConfig.keyboard import Preset\nfrom RPiKeyboardConfig.effects import get_vial_effect_id\n\n# Create a solid red preset\nsolid_effect_id = get_vial_effect_id(\"solid color\")\nred_preset = Preset(\n    effect=solid_effect_id,\n    speed=128,\n    hue=0,        # Red hue\n    sat=255,      # Full saturation\n    val=255,      # Full brightness\n    fixed_hue=True,\n    startup_animation=\"START_ANIM_B_FADE_VAL\"\n)\n\n# Set preset at index 0\nkeyboard.set_preset(0, red_preset)\n\n# Switch to preset\nkeyboard.set_current_preset_index(0, save_index=True)\n\n# Get preset configuration\npreset = keyboard.get_preset(0)\nprint(f\"Preset 0: {preset}\")\n\n# Revert to saved preset\nkeyboard.revert_to_saved_preset()\n\n# Reset all presets and direct LEDs\nkeyboard.reset_presets_and_direct_leds()\n```\n\n## QMK Keycode Reference\n\nThe library supports standard QMK keycodes. Use `rpi-keyboard-config list-keycodes` to see all available keycodes, or visit the [QMK documentation](https://docs.qmk.fm/#/keycodes) for complete reference.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraspberrypi%2Frpi-keyboard-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraspberrypi%2Frpi-keyboard-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraspberrypi%2Frpi-keyboard-config/lists"}