pi-keys-generator

name

pi-keys-generator

description

This skill generates Python scripts and shell scripts to control RGB LEDs on the Raspberry Pi 500+ keyboard. Use this skill when the user asks to create keyboard lighting effects, animations, color patterns, notification systems, or any program that controls the Pi 500+ keyboard LEDs. This skill should be used for requests like "turn F1-F12 keys blue", "create a typing speed indicator", or "make an email notification effect".

Pi Keys Generator

Overview

This skill generates Python and shell scripts for controlling RGB LEDs on the Raspberry Pi 500+ keyboard using the RPiKeyboardConfig Python library and rpi-keyboard-config command-line tool.

When to Use This Skill

• Creating scripts to set specific keys to specific colors
• Building keyboard LED animations (rainbow, breathing, waves)
• Developing notification systems (flash keys for alerts)
• Making typing-reactive effects
• Setting up preset configurations
• Any task involving Pi 500+ keyboard LED control

Output Locations

Save generated files to these locations if the directories exist:

• Python scripts: $MOVING_RAINBOW_HOME/src/pi-500-keyboard/examples/
• Shell scripts: $MOVING_RAINBOW_HOME/src/pi-500-keyboard/scripts/

If the directories do not exist, save to the user's current working directory.

Script Generation Guidelines

Python Script Template

All Python scripts controlling the keyboard follow this structure:

#!/usr/bin/env python3
"""
Script description here.
"""
from RPiKeyboardConfig import RPiKeyboardConfig
import colorsys
import time

def rgb_to_hsv(r, g, b):
    """Convert RGB (0-255) to HSV (0-255 scale for all components)."""
    h, s, v = colorsys.rgb_to_hsv(r / 255.0, g / 255.0, b / 255.0)
    return (int(h * 255), int(s * 255), int(v * 255))

# Define colors in RGB format
RED = rgb_to_hsv(255, 0, 0)
GREEN = rgb_to_hsv(0, 255, 0)
BLUE = rgb_to_hsv(0, 0, 255)
OFF = (0, 0, 0)

def main():
    keyboard = RPiKeyboardConfig()

    try:
        # Save current preset to restore later
        current_preset = keyboard.get_current_preset_index()

        # Enable direct LED control
        keyboard.set_led_direct_effect()

        # === Main logic here ===

    except KeyboardInterrupt:
        print("\nInterrupted by user")
    finally:
        # Cleanup: restore previous state
        keyboard.rgb_clear()
        keyboard.send_leds()
        keyboard.set_current_preset_index(current_preset, save_index=False)
        keyboard.close()

if __name__ == "__main__":
    main()

Shell Script Template

Shell scripts use the rpi-keyboard-config command:

#!/bin/bash
# Script description here

# Set an effect
rpi-keyboard-config effect <effect_id> [--speed 255] [--hue 128] [--sat 255]

# Set a preset
rpi-keyboard-config preset index <0-6>

# Set all LEDs to a color (HSV format: "hue,sat,val")
rpi-keyboard-config leds set --colour "128,255,255"

# Set all LEDs to a color (RGB format)
rpi-keyboard-config leds set --colour "rgb(255,0,0)"

# Clear all LEDs
rpi-keyboard-config leds clear

# Set brightness (0-255)
rpi-keyboard-config brightness 255

Color Reference (HSV)

Colors use HSV format with values 0-255:

Color	Hue Value
Red	0
Orange	21
Yellow	43
Green	85
Cyan	128
Blue	170
Purple	213

Saturation: 255 = full color, 0 = white Value: 255 = full brightness, 0 = off

Using RGB Colors (Recommended)

While the RPiKeyboardConfig library requires HSV colors, you can define colors in the more familiar RGB format and convert them using Python's built-in colorsys module.

RGB to HSV Conversion Helper

Add this helper function to your scripts:

import colorsys

def rgb_to_hsv(r, g, b):
    """Convert RGB (0-255) to HSV (0-255 scale for all components)."""
    h, s, v = colorsys.rgb_to_hsv(r / 255.0, g / 255.0, b / 255.0)
    return (int(h * 255), int(s * 255), int(v * 255))

Defining Colors in RGB

# Define colors in familiar RGB format
RED = rgb_to_hsv(255, 0, 0)
GREEN = rgb_to_hsv(0, 255, 0)
BLUE = rgb_to_hsv(0, 0, 255)
YELLOW = rgb_to_hsv(255, 255, 0)
CYAN = rgb_to_hsv(0, 255, 255)
MAGENTA = rgb_to_hsv(255, 0, 255)
ORANGE = rgb_to_hsv(255, 165, 0)
WHITE = rgb_to_hsv(255, 255, 255)
OFF = (0, 0, 0)

# Use with the keyboard API
keyboard.set_led_by_matrix(matrix=[0, 1], colour=RED)

This approach is preferred because:

• RGB values are more intuitive and widely understood
• Easy to use web color pickers to find RGB values
• No need to memorize HSV hue values

Key Matrix Reference

Common key positions (row, column):

Key	Matrix Position
ESC	[0, 0]
F1-F12	[0, 1] through [0, 12]
W	[2, 2]
A	[3, 1]
S	[3, 2]
D	[3, 3]
Space	[5, 6]
Arrow Up	[4, 15]
Arrow Left	[5, 14]
Arrow Down	[5, 15]
Arrow Right	[5, 16]

For the complete matrix layout, use: rpi-keyboard-config info --ascii

Common Patterns

Set Specific Keys to a Color

# Set function keys F1-F4 to blue (using RGB conversion)
BLUE = rgb_to_hsv(0, 0, 255)
f_keys = [[0, 1], [0, 2], [0, 3], [0, 4]]
for pos in f_keys:
    keyboard.set_led_by_matrix(matrix=pos, colour=BLUE)
keyboard.send_leds()

Flash Effect for Notifications

def flash_keyboard(keyboard, color, times=3, delay=0.2):
    """Flash entire keyboard a color."""
    for _ in range(times):
        for led in keyboard.get_leds():
            keyboard.set_led_by_idx(idx=led.idx, colour=color)
        keyboard.send_leds()
        time.sleep(delay)
        keyboard.rgb_clear()
        keyboard.send_leds()
        time.sleep(delay)

Rainbow Animation

def rainbow_wave(keyboard, duration=10):
    """Animate rainbow across keyboard."""
    start = time.time()
    while time.time() - start < duration:
        for led in keyboard.get_leds():
            hue = (led.x * 3 + int(time.time() * 50)) % 256
            keyboard.set_led_by_idx(idx=led.idx, colour=(hue, 255, 255))
        keyboard.send_leds()
        time.sleep(0.03)

Integration with External Events

# Example: Check for condition and flash
def check_and_notify(keyboard, check_function, color):
    """Flash keyboard when condition is true."""
    if check_function():
        flash_keyboard(keyboard, color)
        return True
    return False

Effect IDs Quick Reference

ID	Effect	Reactive
0	OFF	No
2	Solid Color	No
6	Breathing	No
19	Cycle Pinwheel	No
24	Raindrops	No
25	Jellybean Raindrops	No
29	Typing Heatmap	Yes
30	Digital Rain	No
31	Solid Reactive Simple	Yes
39	Splash	Yes
40	Multisplash	Yes

API Reference

For detailed API documentation including all methods and parameters, consult references/api_reference.md.

Key methods:

• keyboard.set_led_by_matrix(matrix=[row, col], colour=(h, s, v)) - Set LED by position
• keyboard.set_led_by_idx(idx=n, colour=(h, s, v)) - Set LED by index
• keyboard.send_leds() - Apply queued LED changes
• keyboard.rgb_clear() - Turn off all LEDs
• keyboard.set_led_direct_effect() - Enable direct LED control
• keyboard.get_leds() - Get list of all LEDs
• keyboard.set_brightness(n) - Set global brightness (0-255)
• keyboard.close() - Close connection (always call in finally block)

Example Prompts and Responses

Prompt: "Create a script that turns the F1-F12 keys blue"

Generate a Python script that:

1. Initializes keyboard connection
2. Enables direct LED mode
3. Sets keys at matrix positions [0,1] through [0,12] to blue (hue=170)
4. Includes proper cleanup

Prompt: "Make a typing speed indicator that changes key colors"

Generate a Python script that:

1. Uses pynput to track keystrokes
2. Calculates typing speed (WPM)
3. Maps speed to hue (slow=blue, fast=red)
4. Updates all key colors based on current speed

Prompt: "Create a notification effect when I get an email"

Generate a Python script that:

1. Monitors for a trigger (file, IMAP, or webhook)
2. Saves current preset
3. Flashes keyboard purple 3 times
4. Restores previous preset