Agent Skills: Pi Keys Generator

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