在本指南中，我们将深入探讨树莓派 500+ 键盘上的所有自定义 RGB 功能。如果你有一个树莓派 500+，你可能已经玩过一些自带的 RGB 预设，但我们可以做得更多。我们将从内置的终端命令开始，尝试各种预设和效果，然后进入自定义Python脚本，创建你自己的动画、反应式灯光，甚至小游戏或通知系统。到最后，你将完全控制键盘上的每一个 LED，并可以有一堆创意想法来使用它们。
如果你在寻找本指南中使用的代码片段的 ZIP 文件，可以在这里找到！
https://shumeipai.nxez.com/wp-content/uploads/2025/11/pi500plus-rgb.zip
要跟随本指南，你需要：
– 树莓派 500+
– USB-C 电源
– 鼠标
– 显示器
– Micro-HDMI 转 HDMI 线
安装 RGB 库
一如既往，让我们先更新软件包和软件包列表：
sudo apt update && sudo apt upgrade
为了处理所有的 RGB 交互，我们将使用官方的Raspberry Pi键盘配置库。如果你使用的是 Raspberry Pi OS Trixie，这个库可能已经预装了。你可以用以下命令安装（或确保它是最新的）：
sudo apt install rpi-keyboard-config
然后非常重要的一点是，确保你的键盘固件是最新的：
sudo apt install rpi-keyboard-fw-update sudo rpi-keyboard-fw-update
使用终端命令控制 RGB
我们将从一些基本的终端命令开始，然后逐步增加复杂性。从基础开始是值得的，因为这里的大多数命令在更高级的章节中也是很重要的。
如果你按下 FN + F4，你会循环浏览键盘上存储的一堆预设颜色。值得注意的是，默认情况下，树莓派 500+ 可以存储 7 个这样的预设。
在终端中，我们可以用以下命令选择我们想要的预设：
rpi-keyboard-config preset index 3
这将把键盘设置为预设3，我们可以选择从预设0到预设6的任何数字。这个命令本质上等同于按下 FN + F4，只是通过终端来完成。
这些预设中的默认效果很不错，但还有很多其他效果可供选择！
这里有一个快速的区别：效果是编程到键盘中的 RGB 模式/颜色/布局，而预设是可以存储这些效果的槽位，方便访问。
输入以下命令查看所有可用效果的列表：
rpi-keyboard-config list-effects
你可以用以下命令查看一个效果：
rpi-keyboard-config effect 25
上面的命令查看效果编号 25，但你应该多尝试一些，有很多很酷的效果！我们最喜欢的是 25、29 和 40。
有些预设还有可以改变其行为的输入。你可以用修改后的命令设置效果的速度、饱和度和色调：
rpi-keyboard-config effect 30 --speed 255 --sat 255 --hue 255
这些命令接受0到255之间的数字。你可以像上面的命令那样设置所有选项，或者只设置两个或一个：
rpi-keyboard-config effect 30 --hue 255 rpi-keyboard-config effect 30 --speed 255 --hue 255
能够在终端中查看这些命令是好的，但如果你真的想开始自定义键盘，你可以将一个效果分配给键盘的预设槽位：
rpi-keyboard-config preset set 2 25
在上面的命令中，我们将效果编号25设置为预设槽位2。你现在应该可以使用FN+F4键循环浏览预设槽位，并在槽位2中看到你保存的效果！
如果你想知道什么效果被分配到了什么槽位，可以使用以下命令：
rpi-keyboard-config preset get
默认情况下，预设槽位0将是空的。这个预设槽位是树莓派 500+ 开机时加载的默认槽位——如果你把你最喜欢的效果分配到这个槽位，每次你打开Pi时，它都会自动显示。
如果你在键盘上按下FN+F5和FN+F6，你可以控制效果的总体亮度。这也可以在终端中完成：
rpi-keyboard-config brightness 255
亮度可以用0到255之间的任何数字设置。
现在，让我们开始进入有趣和自定义的部分！首先，运行 clear 命令清除所有当前的 LED 颜色，这样我们可以从一个空白画布开始：
rpi-keyboard-config leds clear
让我们用一个基本命令将键盘上的所有 LED 设置为特定颜色：
rpi-keyboard-config leds set --colour "0,255,255"
上面的命令使用HSV格式表示颜色。如果你不喜欢，你可以选择使用 RGB 格式：
rpi-keyboard-config leds set --colour "rgb(255,0,0)"
这两个命令实现的效果相同；它们只是用不同的方式表示红色。还要注意，通常HSV中的色调值范围是0到360，在这个库中，它只接受 0 到 255 之间的数字。所以青色（通常是180）会被缩小到128。
现在让我们设置单个LED的颜色！再次运行LEDs clear命令从一个空白画布开始可能是明智的。然后我们可以用以下命令将W键设置为水绿色：
rpi-keyboard-config led set "2,3" --colour "rgb(0,255,255)"
这与之前的命令非常相似，但这次我们使用行和列来指定要点亮的键。
你可以用以下命令生成一个很好的可视化效果，显示每个键的行号和列号：
rpi-keyboard-config info --ascii
在右边的图片中，我们用这个命令分配了一些颜色。如果你用这个创建了一个自定义 RGB 布局并希望保存它，你可以用 save 命令：
rpi-keyboard-config leds save
这将把你的自定义布局保存为效果 1。即使你重启树莓派，你的布局仍然会保存到这个效果中，你也可以像往常一样把它分配给键盘预设槽位。
不幸的是，一次只能保存一个自定义布局——你只能保存到效果1。我们稍后会看看如何用 Python 脚本创建无限多的自定义布局。
最后，如果你想将所有效果和预设重置为默认值，可以使用以下命令：
rpi-keyboard-config reset-presets
为了好玩的话，你可以玩一个 Flappy Birds 游戏：
rpi-keyboard-config game
从 Python 脚本设置颜色
现在让我们通过 Python 脚本来看看我们刚才做的事情。为什么我们要这样做呢？终端命令方法有什么问题？嗯，最大的缺点是通过终端更新一个键的颜色大约需要一秒钟——而且我们一次只能用一条命令更新一个键的颜色。我们的板上有 84 个键，这意味着要随机给每个键分配一个颜色，需要 84 秒！
用Python脚本方法，我们可以一次性更新所有的键，而且每秒可以更新很多次！除此之外，它是 Python！我们可以制作动画，添加集成，制作互动布局！
如果你还没有这样做，去下载包含所有Python脚本的zip文件，并将其解压到一个方便的位置。
https://core-electronics.com.au/attachments/uploads/pi500plus-rgb.zip
打开simple_colour.py。这个脚本是一个简化版的颜色控制演示。首先，它导入了 rpi-keyboard-config 库，然后初始化了键盘，并设置了LED控制模式（告诉键盘我们即将开始发送RGB命令）。这些是任何控制 RGB 的脚本的重要第一步。
from RPiKeyboardConfig import RPiKeyboardConfigimport time # Initialise the keyboard keyboard = RPiKeyboardConfig() # Set LED direct control mode keyboard.set_led_direct_effect()
然后在 while True 循环中，我们首先设置W键的颜色。这里我们用HSV将W键设置为紫色，并用与终端方法相同的行和列系统。
while True:
# Set LED by matrix position (HSV format: hue, saturation, value)
keyboard.set_led_by_matrix(matrix=[2, 3], colour=(180, 255, 255)) # Purple
但这实际上并没有设置键的颜色，而是将其排队。你可以用这个命令排队尽可能多的键颜色，而且可以给每个键排队一个颜色变化。要实际推送这些排队的键颜色并更新板上的颜色，我们使用 send_leds() 命令。
然后在短暂的延迟后，我们重复同样的过程，但这一次用橙色。这段代码的最终结果是，它将使W键闪烁橙色和紫色。
# Set individual LED by index keyboard.set_led_by_idx(idx=33, colour=(20, 255, 255)) # Orange # Send LED updates to keyboard (required after setting colours) keyboard.send_leds() time.sleep(0.5)
这行有一个小的区别。这里我们通过ID而不是行和列来设置W键。这个ID系统只是另一种表示键的方式。从键盘的顶部行开始，从左到右数键（但不要数电源按钮）。一旦你到达键盘的右侧，向下移动一行并继续从左到右数。如果你这样做一次，你应该会落在 W 上，并数到33——所以 W 的 ID 是 33。
这个脚本中还有一个最后的有用命令：
print(keyboard.get_leds())
这个命令将返回键盘上每个 LED 的当前颜色。如果你在做任何与动画相关的事情，这是一个非常有用的工具，因为你可以获取板的当前状态并从该点开始动画。
这个演示脚本中的行是你可以用来出去并制作几乎任何自定义效果的基本构建块！例如，如果你打开并运行 game_of_life.py，你将在键盘上以随机颜色运行一个生命游戏模拟。这个脚本使用与简单演示相同的基本构建块；它只是有额外的代码决定要点亮哪些LED。
https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life
另一个例子是fire.py。这是一个非常基本的火焰模拟，生成余烬并模拟它们上升和改变颜色。同样，它使用相同的构建块，大部分代码都用于计算要点亮哪些键以及什么颜色。
现在，创建这样的动画需要很多工作，有时需要相当多的数学。一个很好的选择可能是尝试使用像 ChatGPT 或 Claude 这样的 LLM。如果你复制并粘贴给他们任何这些演示脚本，他们很可能能够帮助你为其他自定义效果生成代码。
例如，我们能够把这个火焰演示脚本并让它添加一些叫做插值的东西。如果你运行 fire_interpolated.py，你会发现这使得动画更加平滑，如果你打算让LLM帮你写代码，可能值得让他们也添加插值。
在这一点上，我们想知道这对我们的Pi有多大影响，以及我们能以多快的速度更新RGB。为了测试这一点，我们写了 speed_test.py，它以尽可能快的速度将每个键闪烁为随机颜色。
运行这个，我们发现键盘能够以超过 30fps 的速度更新！这比通过终端方法大约每秒 1 个键要快得多。
我们还用以下命令打开了一个资源管理器：
htop
在运行这段代码时，我们发现它使用了大约 5% 到 10% 的CPU——不算多，但也不算可以忽略不计。这个使用量当然会根据你的效果有多复杂以及你更新它的速度来决定是多或少。
简单的通知系统
我们在终端中做的很多事情也可以通过库来完成——包括设置预设。在项目文件夹中，你会发现flash_demo.py。这个简短的脚本在Pi 500+键盘上创建了一个小的“闪光”效果，在随机间隔触发——展示了你如何暂时覆盖你正常的RGB预设，显示一个动画，然后直接恢复它。让我们一步一步地分解它。
我们首先导入所需的包并设置我们的键盘对象：
import random import time from RPiKeyboardConfig import RPiKeyboardConfig keyboard = RPiKeyboardConfig()
这里，random和time是标准的Python库，RPiKeyboardConfig是直接与键盘灯光系统对话的官方库。最后一行初始化这个库，这样我们就可以开始向它发送命令了。
现在我们进入主循环：
while True:
# Generate a random number between 1 and 5
random_number = random.randint(1, 5)
print(f"Random number: {random_number}")
这个循环使脚本持续运行。每次通过它都会生成一个新的1到5之间的随机数。这就是我们决定何时做我们的“闪光”效果的方式——只有当数字出现3时。
在那个条件里面，魔法发生了：
if random_number == 3:
# 1) Save the preset slot index
current_idx = keyboard.get_current_preset_index()
# 2) Switch to direct LED mode
keyboard.set_led_direct_effect()
第一行记住你当前正在使用的预设，以便以后可以恢复。然后我们将键盘切换到直接LED模式，这基本上给了我们对板上每个LED的原始控制权。
接下来我们用随机颜色填充键盘：
# 3) Fill with random colours
all_leds = keyboard.get_leds()
for led in all_leds:
h = random.randint(0, 255)
s = 255
v = 255
keyboard.set_led_by_idx(idx=led.idx, colour=(h, s, v))
keyboard.send_leds()
我们获取板上所有LED的列表，为每个生成随机的颜色值（使用全饱和度和亮度），然后将这些颜色发送到键盘。这是“闪光”时刻。
在保持闪光一秒后，我们清除一切并恢复正常的预设：
# 4) Hold the flash
time.sleep(1)
# 5) Clear LEDs
keyboard.rgb_clear()
keyboard.send_leds()
# 6) Restore preset
if current_idx is not None:
keyboard.set_current_preset_index(current_idx, save_index=False)
print(f"Restored preset index {current_idx}")
这个短暂的停顿保持闪光可见，然后脚本擦除LED并重新加载你保存的预设，这样它看起来和之前完全一样。
最后，我们在运行下一个循环之前等待一秒。
# Wait 1 second before next iteration time.sleep(1)
现在，这可能看起来有点奇怪，但我们实际上在这里建立了一个简单的通知或提醒系统。你可以让你最喜欢的灯光预设运行，然后——比如说门铃响了——一个Python集成可以闪烁你的键盘来提醒你。或者也许你把它连接到 Home Assistant，在你的桌子上显示信息；这几乎就像在你的键盘中内置了一个低分辨率的屏幕。你甚至可以设置内置的计时器，比如番茄钟跟踪器或系统提醒。有无数种创造性的方式来使用这种方法，通过读取和加载预设，你可以制作出各种适合你设置的互动灯光效果。
创建互动效果
我们可以预先编程花哨的LED颜色和动画，但我们在用 Python ——我们可以做更复杂的事情，比如对键盘输入做出反应。
我们一直在使用的键盘库确实原生支持检测按键，但它也包括一个安全功能，要求你在每次Pi重启后按下回车和退出键来解锁键盘，然后才能检测到它们。
这不是一个大问题，但我们正在研究让这些 Python 脚本在启动时自动运行，而这个额外的手动步骤有点麻烦。因此，我们将使用 Pynput，它完成同样的任务。你可以用以下命令安装它：
pip install pynput --break-system-packages
在脚本 snake.py 中，你会发现（正如名字所示）一个使用 pynput 进行控制的贪吃蛇游戏。按照 Thonny shell 中的说明开始玩吧！
让我们把所有东西放在一起，做一些真正酷的东西——一个键盘的屏保。打开 screensaver.py 脚本，你会看到到底发生了什么。
在幕后发生了很多事情，但简单来说，这个脚本监视键盘活动，如果五秒内没有注册到任何输入，它就会开始行动。它保存你当前使用的预设，逐渐降低键盘的亮度（使用我们之前在终端中使用的相同的全局亮度命令），然后开始显示一个柔和的“萤火虫”动画。一旦你再次按下键，它就会恢复你原来的预设和亮度——一个为你的键盘设计的整洁的小屏保。
开机自动运行脚本
我们一直在 Thonny 中运行这个，但在日常使用中这并不实用。有一种方法可以让这个 Python 脚本在启动时自动运行，这样它就可以在后台做它的事情。首先，我们需要把脚本放在一个容易访问的地方，或者我们知道路径的地方。如果你想按照这些命令中的确切位置操作，把你的 Python 脚本复制到 /home/pi（打开文件夹浏览器时默认打开的文件夹）。
我们需要用 chmod 使其可执行：
chmod +x /home/pi/fire.py
我们的脚本叫做fire.py，所以你应该把它改成你的脚本叫什么。然后，打开一个新的终端窗口，用以下命令编辑crontab文件：
crontab -e
第一次这样做时，你可能需要选择一个编辑器来使用。输入1来使用nano编辑器。一旦你进入文件，用箭头键导航到文件的底部，在新的一行中输入以下内容：
@reboot sleep 10 && /usr/bin/python3 /home/pi/fire.py &
你可能需要修改这行。我们设备的用户名是“pi”，所以我们有 /home/pifire.py，但你需要把pi换成你的用户名。同样，我们的脚本叫做fire.py，所以你也需要把它改成你给脚本起的名字。
一旦你正确输入了这行，按 ctrl + x，然后y，然后enter来保存它。下次你重启时，这应该会自动开始！
下一步？
现在我们已经完全控制了树莓派 500+键盘上的每一个LED——无论是通过输入终端命令，构建自定义颜色布局，还是在 Python 中编写整个动画和互动效果。想到一个紧凑的桌面计算机的键盘可以兼作一个完全可编程的显示器和输入系统，真是令人兴奋。
我们真的只是触及了这个键盘能做什么的表面，你可能会发现一些用途和应用让我们的演示相形见绌。如果你在寻找更多的信息，官方的键盘文档更深入地介绍了系统的工作原理，如果你想了解每一个可用的命令，这非常值得一读。
https://www.raspberrypi.com/documentation/computers/keyboard-computers.html
你也可以在 GitHub 上探索 rpi-keyboard-config Python 库——这是我们在整个指南中使用的同一个包，里面还有很多隐藏的功能。
https://github.com/raspberrypi/rpi-keyboard-config
发表评论