键盘电脑
树莓派键盘电脑是集成于键盘中的完整个人电脑，其搭载的系统级芯片（SoC）与经典树莓派单板计算机（SBC）相同。
键盘电脑使用 <X00> 形式的型号标识，其中 X 表示对应的经典单板计算机（SBC）系列设备。例如，树莓派400 就是树莓派4 的键盘版本。
树莓派提供三款键盘电脑：
树莓派键盘电脑存在不同区域版本，涉及键盘布局与电源适配要求。
功能特性
树莓派键盘电脑的功能特性取决于具体型号。
树莓派500和树莓派500+凭借Cortex-A76处理器、更大内存及升级版GPU，运行速度优于树莓派400。树莓派400键盘电脑与树莓派500/500+键盘电脑的主要差异在于：
- 处理器：树莓派400采用1.8 GHz Cortex-A72；树莓派500与500+均采用2.4 GHz Cortex-A76，提供更强性能与效率。
- 内存（RAM）：树莓派400配备4 GB RAM；树莓派500配备8 GB RAM； 树莓派500+配备16GB内存，可实现更流畅的多任务处理并支持更高要求的应用程序。
- GPU 树莓派400搭载500 MHz VideoCore VI显卡；树莓派500和500+均搭载910 MHz VideoCore VII显卡，提供更快的图形处理和更优的视频解码性能。
- HDR视频支持 所有树莓派键盘电脑均配备两个微型HDMI接口，支持4K显示输出，其中树莓派500和500+还支持HDMI输出的HDR功能。
- 电源按钮 树莓派400未设置物理电源按钮，需通过组合按键操作开关机(Fn + F10)；树莓派500和500+均配备专用电源键。
- SoC。树莓派400搭载博通BCM2711芯片；树莓派500和500+均采用博通BCM2712芯片，并配合RP1 I/O控制器使用。
树莓派500+提供以下新增功能：
- 机械键盘配备可定制RGB背光LED及可更换键帽。详情参见 树莓派500+机械键盘。操作指南请参阅 自定义背光效果 及 更换键帽。
- 内置 256 GB M.2 固态硬盘，预装树莓派操作系统且可更换。操作指南详见 更换 M.2 固态硬盘。
- 更大内存（16 GB）。对比详情请参阅下表。
技术规格
下表列出各键盘电脑型号之间 的主要相同点与差异。
| Raspberry Pi 400 | Raspberry Pi 500 | Raspberry Pi 500+ | |
|---|---|---|---|
| 尺寸 | 286 × 122 × 23 毫米 | 286 × 122 × 23 毫米 | 312 × 123 × 35 毫米 |
| 按键 | 78、79 或 83 个薄膜按键（根据地区版本而定） | 78、79 或 83 个薄膜按键（根据地区版本而定） | 84、85 或 88 个机械按键（根据区域版本而定） |
| 处理器 | 四核 64 位 Arm 处理器（Cortex-A72，1.8 GHz） | 四核 64 位 Arm 处理器（Cortex-A76，2.4 GHz） | 四核 64 位 Arm 处理器（Cortex-A76，2.4 GHz） |
| SoC 与 I/O 控制器 | BCM2711 SoC | BCM2712 SoC 与 RP1 I/O 控制器 | BCM2712 SoC 与 RP1 I/O 控制器 |
| 内存（RAM） | 4 GB SDRAM | 8 GB SDRAM | 16 GB SDRAM |
| GPU | VideoCore VI 500 MHz | VideoCore VII 910 MHz | VideoCore VII 910 MHz |
| 视频输出 | 2个微型HDMI端口，可支持单台4K显示器以60Hz刷新率输出，或两台4K显示器以30Hz刷新率输出 | 2个微型HDMI端口，支持60Hz刷新率的4K显示器及HDR技术 | 两个微型HDMI端口，支持60Hz刷新率的4K显示器及HDR技术 |
| 散热控制 | 铝制一体化散热器 | 铝制一体化散热器 | 铝制一体化散热器 |
| 无线连接 | 双频（2.4 GHz 或 5 GHz）802.11ac Wi-Fi（120 Mb/s）与蓝牙（5 及 BLE） | 双频（2.4 GHz 或 5 GHz）802.11ac Wi-Fi（300 Mb/s）与蓝牙（5 及 BLE） | 双频（2.4 GHz 或 5 GHz）802.11ac Wi-Fi（300 Mb/s）与蓝牙（5 及 BLE） |
| USB接口 | 2个USB 3.0接口；1个USB 2.0接口 | 2个USB 3.0接口；1个USB 2.0接口 | 2个USB 3.0接口；1个USB 2.0接口 |
| 千兆（1 Gb/s）以太网（RJ45） | 支持 | 支持 | 支持 |
| GPIO | 水平40针GPIO接口 | 水平40针GPIO接口 | 水平40针GPIO接口 |
| 存储 | microSD卡槽 | microSD卡槽 | microSD卡槽与M.2 SSD硬盘（256 GB） |
| 电源输入 | 通过USB-C接口输入5V/3A（15W） | 通过USB-C接口输入5V/5A（25W），外设电流上限 600 mA | 通过USB-C接口输入5V/5A（25W） |
| 电源按钮 | 组合键（Fn + F10） | 专用按钮 | 专用按钮 |
| 可定制性 | — | 键位映射 | 键位映射；RGB背光；可更换键帽 |
键盘电脑与套装
树莓派键盘电脑可单独购买键盘，也可选择套装形式，套装包含入门所需的基础配件。
树莓派400 与套装
树莓派400 键盘电脑于 2020 年发布，基于树莓派4（4 GB 内存）。
树莓派400
树莓派400套装包含以下内容：
- 树莓派400键盘电脑
- 15W 树莓派 USB-C 电源适配器
- 树莓派 USB 鼠标
- 16 GB microSD卡（预装树莓派 操作系统）
- micro-HDMI线缆
- 《入门指南》书籍
树莓派500 与套装
树莓派500 键盘电脑于 2024 年发布，基于树莓派5（8 GB 内存）。
树莓派500
树莓派500套装包含以下内容：
- 树莓派500键盘电脑
- 27W树莓派USB-C电源适配器
- 树莓派USB鼠标
- 32 GB A2级microSD卡，预装树莓派操作系统。
- micro-HDMI线缆。
- 《入门指南》书籍。
树莓派500+ 与套装
树莓派500+ 键盘电脑于 2025 年发布，基于树莓派5（16 GB 内存）。
树莓派500+
树莓派500+套装包含以下内容：
- 树莓派500+键盘电脑，含预装树莓派操作系统的固态硬盘。
- 27W树莓派USB-C电源适配器。
- 树莓派USB鼠标。
- 微型HDMI线缆。
- M.2固态硬盘拆卸工具（开壳钳，独立键盘套装亦含此配件）。
- 键帽拆卸器（独立键盘套装亦含此配件）。
- 《入门指南》书籍。
入门指南
本节将引导您使用树莓派操作系统 (OS)、Wi-Fi 和外设（鼠标与显示器）完成树莓派键盘计算机的设置，使其可以像台式电脑一样使用。有关设置树莓派的更详细指导，或希望采用其他设置方式，请参阅设置您的树莓派。
如果您符合以下任一情况，可以跳过步骤 1 并从步骤 2 开始：
- 您持有树莓派500+，其内置的 M.2 固态硬盘已预装 Raspberry Pi OS。
- 您通过套装购买树莓派400 或 500，套装内附带已预装 Raspberry Pi OS 的 microSD 卡。
首批树莓派500+ 键盘计算机预装的是上一代 Raspberry Pi OS（Bookworm）；较新的树莓派500+ 预装最新版 Raspberry Pi OS（Trixie）。
硬件前提
如果您不是通过键盘计算机套装进行设置，则需要以下硬件：
- 一台树莓派400、500 或 500+。
- 适合您树莓派键盘计算机的官方树莓派电源适配器。
- 一张至少 32 GB 的 microSD 卡，以及将其连接到另一台计算机的读卡方式。以下情况需要 microSD 卡：
- 您没有使用键盘计算机套装来设置树莓派400 或 500。
- 您持有树莓派500+，并希望使用 microSD 卡而不是预装的 M.2 固态硬盘作为启动介质。
- 一台运行 Windows、macOS 或 Linux 的计算机，用于准备 microSD 卡。如果您从树莓派500+ 内置的 M.2 固态硬盘启动，则无需此设备。
- 如需连接网络，还需以下任一项或两项：
- 您的 Wi-Fi 凭据（SSID 和密码）。
- 一根以太网线。
- 一个连接到树莓派键盘计算机的 USB 鼠标。
- 一台连接到树莓派键盘计算机的显示器（及相应电源线）。为方便起见，我们推荐树莓派显示器，它可通过您的树莓派键盘计算机供电。
- 一根用于连接显示器与树莓派键盘计算机的 micro-HDMI 转 HDMI 线缆。
步骤 1. 准备启动介质
仅当您 的键盘计算机并非来自套装，或者您持有树莓派500+ 并希望使用 microSD 卡而非预装 M.2 固态硬盘时，才需要执行此步骤。
- 在您的计算机上安装并启动 Raspberry Pi Imager。您可以使用该工具将树莓派操作系统写入 microSD 卡，使其成为树莓派键盘计算机的启动介质。
- 按照 Imager 中的说明配置树莓派设备、操作系统、存储设备、自定义选项和 Imager 选项。关于需要配置哪些内容，请参阅使用 Imager 安装中的步骤 2 至步骤 4。
- 将镜像写入 microSD 卡。这会将存储设备变为您的启动介质。
- Raspberry Pi Imager 完成写入后，安全地从计算机中取出 microSD 卡，然后将其插入树莓派键盘计算机。从键盘计算机背面看，microSD 卡槽位于 USB 端口右侧、电源端口左侧。
如果您遇到任何问题、希望对设备进行更详细的设置，或打算采用其他方式开始使用树莓派，请参阅设置您的树莓派。
步骤 2. 连接外设
若要将键盘计算机用作台式电脑，可以将以下外设直接连接到键盘计算机背面：
- 一个 USB 鼠标，可接入白色的 USB 2.0 端口，从而把更快的 USB 3.0 端口留给可能需要更快速度的外设。
- 按需连接一台或两台显示器。
- 可选的扬声器或耳机，用于音频输出。
- 音频可通过 micro HDMI、USB 或蓝牙输出。
- 官方树莓派显示器配有两个前置扬声器，您也可以通过显示器背面的 3.5 mm 音频插孔连接扬声器或耳机。
步骤 3. 连接电源
为树莓派键盘计算机接通电源即可开机。
- 在树莓派400和树莓派500上，LED 状态指示灯会亮起，Raspberry Pi OS 进入首次启动设置流程。
- 在**树莓派500+**上，键盘背光会亮起，Raspberry Pi OS 进入首次启动设置流程。
树莓派键盘计算机的启动过程可能需要 60 至 90 秒，期间您无需进行任何操作。
如果您使用预编程的 SD 卡或固态硬盘，首次启动时会打开配置向导，帮助您配置键盘计算机。更多信息请参阅首次启动时的配置。
之后，您可以在树莓派400 上使用 Fn + F10 组合键，或在树莓派500 和 500+ 上使用右上角的电源按钮来开机和关机。
步骤 4. 连接网络（可选）
按上述说明完成键盘计算机的设置后，您可以将其连接到网络。这可以是有线（以太网）连接，也可以是无线（Wi-Fi）连接。两者的详细说明请参阅设置您的树莓派页面中的连接网络。
无线网络通常在步骤 1 中配置，但您也可以从桌面或命令行配置无线连接。
如果您因为使用预编程的 SD 卡或固态硬盘而跳过了步骤 1 ，可以在首次启动时通过配置向导配置 Wi-Fi。更多信息请参阅首次启动时的配置。
树莓派500+机械键盘
树莓派500+的每个按键下方均配备独立机械开关以检测按压动作。该设备采用Gateron KS-33低轴机械开关。默认情况下，KS-33开关通过彩色轴杆区分类型（清音轴、段感轴或直线轴）。树莓派500+采用带定制灰色轴杆的Gateron KS-33清音轴。
键帽通过十字形轴杆安装在Gateron开关顶部。这些开关采用符合Cherry MX标准的十字形轴杆，属于行业通用规格。有关树莓派500+键帽拆装指南，请参阅本页 更换键帽 章节。
树莓派500+定制指南
树莓派500+是最新款键盘电脑，提供以下定制选项：
针对高级用户，树莓派500+还支持：
- 超 出内置预设的LED配置
- 实时键位映射
更多信息请参阅 高级软件设置。
更换 M.2 固态硬盘
您可通过更换树莓派 500+ 内的 M.2 固态硬盘来扩展存储容量，亦可利用此插槽安装其他 PCIe 外设。树莓派 500+ 支持采用 M.2 M 键接口的 2230、2242、2260 及 2280 规格设备。
完成此操作需准备十字螺丝刀、一字螺丝刀及随附的塑料撬棒。
- 拆卸键盘 找到键盘底部的五颗螺丝，使用十字螺丝刀拧下。请妥善保管螺丝。
- 分离键盘上下壳体 将撬棒插入键盘前端凹槽，向上撬起使上下壳体分离。
- 分离键盘上下壳体。沿键盘前端开槽处撬动撬棒并滑动，使上壳体与下壳体脱离。
- 展开键盘 将键盘底部置于平坦表面，将键盘顶部向下折叠（勿抬起）使其面朝下平放。注意勿完全分离上下两部分，因其通过柔性线缆连接。
- 释放M.2固态硬盘 用手或平头螺丝刀逆时针旋转M.2固态硬盘右侧的螺丝使其松动。取下螺丝并妥善保管。卸下螺丝后M.2固态硬盘会弹起。
- 拔出M.2 SSD 将M.2 SSD沿键盘边缘向外拉出。
- 安装新M.2 SSD 将另一块M.2 SSD从左侧插槽滑入。SSD卡仅支持单一方向安装。按住新插入的M.2 SSD，旋紧其右侧螺丝（顺时针方向）。
- 合上键盘 将键盘顶盖折回底部，卡入到位。
- 拧紧键盘螺丝 用十字螺丝刀将五颗螺丝重新旋入原位。
更换键帽
您可以将树莓派500+的默认键帽替换为定制键帽组。由于树莓派500+采用的Gateron KS-33轴体使用行业标准的Cherry MX轴杆形状，大多数为Cherry MX设计的第三方键帽均可兼容。请避免选用过高的键帽，以免撞击键盘框架或产生过大噪音。有关替代键帽选择的更多指导，请参阅本节中的 键盘布局、键帽轮廓 和 灯光效果部分。
拆卸键帽步骤：
- 将键帽拔取器的双爪插入需拆卸键帽的两侧，确保双爪完全插入键帽下方。
- 同时按压卡针两侧夹紧键帽，确保施力均匀。
- 垂直向上轻拉键帽脱离键盘，避免倾斜角度操作。
拆卸键帽亦可清洁键帽下方区域。
更换新键帽或复位原键帽时：
- 将键帽底部的十字形凸起与对应开关的十字形凸起对齐。
- 轻柔而有力地按压键帽，直至完全卡入到位并感觉稳固。
键盘布局
键帽提供多种语言版本，其中美式布局最为常见，其次是英式布局。其他语言版本可能较难获取。
树莓派500+键盘采用改良版75%布局，部分按键为非标准设计，常规键帽套装可能无法匹配：
- 电源键。键盘右上角的电源键可能未包含在其他键帽套装中。
- 灯光标识键。树莓派500+键盘上F4、F5、F6键的灯光标识为非标准设计。
- 音量标识键。树莓派500+键盘上F10、F11、F12键的音量标识为非标准设计。
- 系统请求键。树莓派500+的SysRq键为非标准设计。
- 插入键。树莓派500+的Ins键为非标准设计。
- 命令键。该键在常规键帽套装上通常标注为Win，且第三方键帽套装不包含树莓派标志。
键帽轮廓
树莓派500+配备的低轮廓键帽兼具传统机械键盘的性能，同时保持键盘紧凑设计。我们推荐使用DSA或Cherry轮廓的替换键帽：
- DSA键帽采用平坦轮廓，可跨行互换。
- Cherry键帽通常兼容，但采用符合人体工学的立体轮廓设计。这意味着每行键帽可能存在细微高度或角度差异。为保持一致手感，请注意行间对齐。
XDA、OEM和SA键帽因高度较高，可能产生更多噪音或与键盘框架发生碰撞，故不推荐使用。
背光系统
树莓派500+键盘的LED灯位于键帽顶部，因此完全不透光的键帽可能阻挡背光。
自定义背光效果
Raspberry Pi 500+ 默认关闭大部分背光功能，仅开启以下照明：
- 键盘通电时电源键后方的活动指示灯：
- 红色：Raspberry Pi 500+ 接通电源但处于关闭状态
- 设备开启时呈绿色
- SD卡读写时同步闪烁
- 键盘启动时在按键间流动的彩虹动画。高级用户可通过配置软件在特定背光预设中关闭此动画。详情参见 高级软件设置 中的 更改预设启动动画。
- Caps Lock指示灯在启用时亮起。
Raspberry Pi 500+支持其他RGB背光预设，由Vial QMK固件驱动。操作指南详见 选择背光预设。
选择背光预设
树莓派500+内置七种预设模式，即存储在键盘中的背光配置文件。向前循环切换预设请按键盘上的Fn + F4；向后循环切换请按键盘上的Fn + Shift + F4。
| 预设名称 | 描述 | |
|---|---|---|
| 0 | 关闭 | 默认预设，仅点亮电源键、启动动画和大写锁定指示灯。 |
| 1 | 纯白背光 | 纯白色背光。 |
| 2 | 纯色背光 | 纯色背光，可通过 Fn + F3 键更改颜色。 |
| 3 | 左右渐变 | 固定彩虹背光。 |
| 4 | 循环彩虹 | 动态彩虹背光，键盘按键以彩虹模式循环变色。 |
| 5 | 输入热力图 | 按键使用频率越高，颜色越偏红，周边按键亮度也随之增强。 |
| 6 | 纯色响应式简约 | 响应式键盘，按键触发时点亮。可通过Fn + F3选择颜色。 |
背光控制
您可通过以下快捷键自定义RGB背光颜色（取决于预设模式）和亮度：
- 更改颜色：按 Fn + F3 向前循环切换16种背光颜色；按 Fn + Shift + F3 向后循环切换颜色。
- 调节亮度：按 Fn + F5 降低亮度；按 Fn + F6 提高亮度。
键盘上的 Shift 键可实现两种功能：向后循环切换选项，或反转按键功能。例如 Fn + Shift + F5 将提高亮度而非降低。
高级软件设置
树莓派提供固件以控制树莓派500和500+的内置键盘。通过此工具可实现：
- 为树莓派500+启用并配置高级LED设置。详情参见 高级LED设置。
- 重新映射树莓派500和500+的键位。详情请参阅 键位重映射。
- 在树莓派500和500+上使用 Vial 重新映射按键。详情请参阅 使用Vial重新映射按键。
- 在树莓派500+上运行《Flappy Bird》风格游戏。详情请参阅 [Flappy Bird游戏](#Flappy Bird游戏)。
若需了解本页未涵盖的更多信息与选项，请参阅GitHub上的配置工具README文档。
固件设置
要使用软件控制的灯光效果和键位映射功能，必须先更新键盘固件并安装配置工具：.
安装固件更新包。运行命令：sudo apt install rpi-keyboard-fw-update。.
更新至最新键盘固件，该工具会自动检测并安装高级功能所需的固件。运行命令：sudo rpi-keyboard-fw-update。.
安装配置工具，用于调节LED灯光和键位映射。运行命令：sudo apt install rpi-keyboard-config。
您可在GitHub上的Vial QMK仓库查看键盘固件源代码。
基础信息命令
在自定义键盘灯光或重新映射按键前，请酌情使用以下命令查看键盘计算机的当前状态：
| 命令 | 说明 |
|---|---|
rpi-keyboard-config info --ascii | 查看键盘型号、锁定状态和布局图。若无需布局图，请从命令中移除 --ascii 参数。 |
rpi-keyboard-config help | 列出所有可用命令及其简要说明。 |
rpi-keyboard-config list-effects | 列出所有可用灯光效果，可临时应用或保存至预设。 |
rpi-keyboard-config preset get | 列出当前所有预设（编号0至6）。 |
高级LED设置
高级用户可自定义树莓派500+背光效果，超越基础预设范围。具体而言，rpi-keyboard-config软件支持以下操作：
- 为树莓派500+添加其他灯光效果，可临时启用或设为预设。详情参见 灯光效果。
- 为每个预设设置不同的启动动画。详情请参阅 更改预设启动动画。
- 为特效或预设添加速度、饱和度和色调参数。详情请参阅 效果与预设参数。
- 控制全局色调和亮度。详情请参阅 全局灯光控制。
- 通过配置并应用
direct特效来控制单个LED照明。详情请参阅 单个LED控制。
高级LED设置仅适用于树莓派500+键盘电脑，因该型号为唯一配备背光按键的机型。
灯光效果
您可通过多种效果和参数控制树莓派500+的背光。除不受任何效果影响的电源键外，键盘灯光效果均通过配置软件控制。使用该软件可实现：
- 临时应用效果至关机重启前，或直至再次循环预设模式。循环预设将从应用临时效果前的最后预设继续。
- 将效果分配至七个键盘预设之一。默认预设详见 选择背光预设。您还可为预设添加参数和启动动画。
使用以下命令选择、应用并查看键盘的临时效果：
| 命令 | 描述 |
|---|---|
rpi-keyboard-config list-effects | 列出可用灯光效果。 |
rpi-keyboard-config effect "effect-name" | 临时应用效果，将effect-name替换为前一条命令输出中的效果名称。 |
rpi-keyboard-config effect | 查看当前激活的效果。 |
您还可调整效果的以下参数：速度、饱和度和色调。例如，以下命令将 "Cycle Spiral" 效果的速度改为 42：
rpi-keyboard-config effect "Cycle Spiral" --speed 42
添加的参数必须是 0 到 255 之间的数值。有关这些参数的详细说明（包括适用场景），请参阅 效果与预设参数。
查看预设
可通过配置软件查看当前预设状态、切换预设或查看详细信息。每个预设拥有0至6之间的索引号，代表七个可用槽位。
| 命令 | 描述 | 示例（假设使用默认预设） |
|---|---|---|
rpi-keyboard-config preset index | 显示当前预设索引号 | 若当前处于渐变左右预设，该命令将显示您处于第3个预设 |
rpi-keyboard-config preset index X | 跳转至预设循环中的指定位置，其中X为预设索引（取值范围0至6） | 以下命令可跳转至打字热力图预设：rpi-keyboard-config preset index 5 |
rpi-keyboard-config preset get | 列出所有当前预设 | 此命令将列出编号为0至6的七个预设。默认预设已在 选择背光预设 中概述 |
rpi-keyboard-config preset get X | 显示特定预设详情，其中X为预设索引（取值范围为0至6） | 以下命令将告知预设5即为打字热力图预设：rpi-keyboard-config preset get 5。 |
重新分配预设
您可以重新分配预设以使用不同的效果。有关效果的详细信息（包括如何获取可用效果列表），请参阅 灯光效果>>。
注意：您对预设所做的更改将在每次重启树莓派 500+ 时持续生效。您可随时通过 重置预设及LED自定义设置 中的说明将预设重置为默认值。
以下示例将渐变左右（3）预设更改为您在引号中指定的效果。
rpi-keyboard-config preset set 3 "效果名称"
重新分配预设时，可添加以下参数之一或多项：速度、色相或饱和度。您还可为该预设设置特定启动动画。相关选项详见 效果与预设参数 及 更改预设启动动画。
例如，以下命令将默认的渐变 左右预设替换为速度为140的彩虹灯塔效果。同时替换该预设的默认启动动画，使其在白色LED完成后渐变过渡至彩虹灯塔效果。
rpi-keyboard-config preset set 3 "Rainbow Beacon" --speed 140 --startup-animation "START_ANIM_W_FADE_SAT"
更改预设启动动画
可通过以下命令为每个预设指定启动动画：
--startup-animation "name_of_animation"
将name_of_animation替换为以下五种启动动画之一：
| 启动动画名称 | 描述 |
|---|---|
START_ANIM_NONE | 无启动动画 |
START_ANIM_B_NO_FADE | 彩虹脉冲动画后转为空白LED状态，随即切入选定效果 |
START_ANIM_B_FADE_VAL | 彩虹脉冲动画后转为空白LED渐变效果，最终过渡至选定效果。此为默认启动动画 |
START_ANIM_W_NO_FADE | 彩虹脉冲动画后转为白色LED，随即直接进入选定效果 |
START_ANIM_W_FADE_SAT | 彩虹脉冲动画后转为白色LED渐变过渡至选定效果 |
例如，以下命令将把预设3的启动动画替换为脉冲彩虹动画，该动画以白色LED结束，随后淡入预设效果：
rpi-keyboard-config preset set 3 --startup-animation "START_ANIM_W_FADE_SAT"
效果与预设参数
您可为任意效果或预设添加以下速度、饱和度和色相参数：
- 速度。设置速度时，在命令中添加
--speed X，其中X为 0 至 255 之间的数值。若未添加速度参数，默认速度为 128。 - 饱和度：通过在命令中添加
--sat X设置饱和度，其中X为 0 至 255 之间的数值。若未添加饱和度参数，默认值为 255（最大饱和度）。 - 色相： 设置色相时，请在命令中添加
--hue X，其中X为 0 至 255 之间的数值。若未设置色相，则默认采用键盘全局色相（通过键盘 Fn + F3 设置）。更多信息请参阅 背光控制。
部分效果和预设不受某些参数影响。例如纯色效果属于静态效果，因此不受速度变化影响。
全局灯光控制
色调与亮度均采用0至255的数值范围管理。通过在rpi-keyboard-config命令中添加hue和brightness参数，可查看并设置树莓派500+的色调与亮度。
| 命令 | 说明 |
|---|---|
rpi-keyboard-config hue | 显示树莓派500+当前全局色调（颜色） |
rpi-keyboard-config hue X | 设置全局色调，其中X为0至255之间的数值 |
rpi-keyboard-config brightness | 显示树莓派500+当前背光亮度 |
rpi-keyboard-config brightness X | 设置背光亮度，其中X为0至255之间的数值 |
单个LED控制
您可自定义树莓派500+上单个LED的背光效果，这有助于实现精准的视觉调整和创建独特的背光图案。
所有可进行的单个LED自定义设置均应用于名为direct的效果。您可通过以下方式应用direct效果：
若未通过前述方式应用direct效果，执行任何单个LED自定义操作时该效果将自动临时生效。
下表列出设置LED颜色（全局或单个LED）、保存及加载LED配置的命令。
| 命令 | 描述 |
|---|---|
rpi-keyboard-config leds clear | 关闭除电源键外的所有LED |
rpi-keyboard-config leds set --colour <colour> | 指定所有LED的颜色。将<colour>替换为通用颜色名称（例如red）、带引号的HSV数值（范围0-255，例如"0,255,255"），或带引号的RGB数值（例如"rgb(255,0,0)"） |
rpi-keyboard-config led set "<row>,<column>" --colour <colour> | 指定特定LED的颜色，其中LED由行号和列号坐标表示（"<row>,<column>"）。可通过以下命令查看LED行/列坐标及当前按键设置：rpi-keyboard-config info --ascii。 |
rpi-keyboard-config leds save | 存LED配置。要使用保存的配置，可参照 重新分配预设 中的说明将direct效果分配给预设，或直接使用下文load命令加载配置 |
rpi-keyboard-config leds load | 临时应用direct效果以加载保存的LED配置。若尚未将direct效果分配至预设，此操作尤为实用 |
在下面的示例中，通过行和列坐标（"2,6"）指定的特定LED被设置为绿色，采用色相-饱和度-明度（HSV）数值（"85,255,255"）：
rpi-keyboard-config led set “2,6” --colour “85,255,255”
重置预设及LED自定义设置
以下命令将重置预设至默认值并清除已保存的LED自定义配置：
rpi-keyboard-config reset-presets
键盘按键重新映射
高级用户可对树莓派 500 和 500+ 的按键进行重新映射，从而根据工作流程或游戏需求定制键盘布局。
使用 rpi-keyboard-config 软件可实现：
- 列出所有可重映射的键码。详情参见 列出键码。
- 检查当前键位映射。详情参见 查看键位映射。
- 重映射键盘按键。详情参见 键位重映射。
- 在配置软件中监视按键操作。详情参见 监控按键状态。
- 编辑最多四个键位映射层。详情参见 层级管理。
- 在树莓派500和500+上使用 Vial 重新映射按键。详情请参阅 使用Vial重新映射按键。
- 将键盘重置为默认键位映射。详情参见 恢复默认键盘布局。
列出键码
要重映射键盘，您需要了解树莓派500或500+上目标按键的键码。以下命令可列出所有可用键码：
rpi-keyboard-config list-keycodes
您也可通过--category参数仅列出特定类别的键码。例如下列命令将列出basic类别的所有键码：
rpi-keyboard-config list-keycodes --category basic
查看键位映射
使用以下命令查看键盘当前所有位置的键位映射情况：
rpi-keyboard-config key get-all
使用以下命令可通过键位行号和列号坐标查询特定键位的键码。请将<row>和<column>替换为实际数值：
rpi-keyboard-config key get <row> <column>
可通过 rpi-keyboard-config info --ascii 命令查看键位坐标。该命令会显示键盘布局示意图。
例如，获取键盘上 Q 键（坐标 2 2）的键码：
rpi-keyboard-config key 2 2
键位重映射
使用以下命令可通过键位行号和列号指定位置，为其设置不同的键码。请将<row>和<column>替换为实际数值，并将<keycode>替换为要映射至该键的键码。
rpi-keyboard-config key set <row> <column> <keycode>
可通过 rpi-keyboard-config info --ascii 命令查看按键的行-列坐标，通过 rpi-keyboard-config list-keycodes 命令查看按键代码。
例如，若需将键盘上坐标为2 2的Q键映射为键码KC_R的R键：
rpi-keyboard-config key set 2 2 KC_R
监控按键状态
您可在配置工具中读取按键状态以监控按键活动，从而识别哪些按键被按下或释放。执行此操作前必须先解锁键盘。
检查键盘锁定状态：
rpi-keyboard-config info
解锁键盘以便监控按键操作：
rpi-keyboard-config unlock
配置工具将引导您按住特定按键直至倒计时结束。默认按键为Enter + Escape，此时按键会亮起红色指示灯。若您已重新映射这些按键，解锁序列将依据物理位置而非新标签执行；命令会告知您当前设置下需按下的映射按键。
解锁后可通过以下命令监控键盘活动：
rpi-keyboard-config key watch
该命令会在按键按下或释放时实时输出终端日志。配合LED反馈功能，按键按下时键盘对应区域将亮起红光。若需在监控时关闭灯光提示，请在上述命令后添加--no-leds参数：
rpi-keyboard-config key watch --no-leds
操作完成后请锁定键盘。以下lock命令无需确认即可立即锁定键盘：
rpi-keyboard-config lock
层级管理
您可在不同层级设置不同的键位映射。可编辑的层级共有四个，编号为0-3；默认层级为0。默认情况下，Fn键可将键盘从层级0切换至层级1。您可根据需要在以 下命令中添加--layer参数：
rpi-keyboard-config key get-allrpi-keyboard-config key getrpi-keyboard-config key set
使用Vial重新映射按键
您可以通过 Vial 网页界面重新映射按键。Vial 通过键盘固件实现实时键盘配置。
- 在树莓派500或500+上访问 Vial 网页界面。
- 在弹出窗口中选择您的键盘型号，然后选择 连接。
- 使用 Vial 网页界面修改按键映射。
使用指南详见 Vial 文档。
建议仅使用 Vial 调整按键映射，勿用于自定义 RGB LED 灯光效果。
恢复默认键盘布局
以下命令将键盘布局重置为默认键位映射，包括重置所有层级：
rpi-keyboard-config reset-keymap
恢复默认设置
软件控制的偏好设置存储于闪存中，重启及固件更新后仍会保留。若需重置背光设置和键盘布局，请使用以下命令清除存储区域：
sudo rpi-keyboard-fw-update -w -i
此操作将清除所有自定义设置，使键盘恢复默认背光效果和键位映射。
若键盘布局配置错误导致无法在树莓派500+上输入，您仍可通过连接外部USB键盘至可用USB端口，在该设备上输入命令完成默认设置重置。
Flappy Bird游戏
为增添趣味，执行以下命令可在树莓派500+上通过键盘背光玩基础版《Flappy Bird》游戏：
rpi-keyboard-config game
游戏将键盘背光作为 "屏幕"，通过灯光闪烁模式呈现小鸟与管道。游戏目标是避免小鸟撞上管道，玩法与原版《Flappy Bird》相同。按空格键使小鸟飞越管道（亮起的LED灯）。若未按空格键，小鸟将持续下坠。得分由成功穿越的管道数量决定，对应键盘顶部紫色LED灯的数量。
按键盘上的Q键即可退出游戏。
中文翻译版以英文版相同知识授权方式共享：CC-BY-SA 4.0。交流 Q群：498908352