Keyboard computers

Raspberry Pi keyboard computers are complete personal computers built into a

keyboard. They include the same system-on-chip (SoC) as Raspberry Pi single-board
computers (SBC). Raspberry Pi offers three keyboard computers:

Raspberry Pi 400, based on Raspberry Pi 4 (4 GB), released 2020.

Raspberry Pi 500, based on Raspberry Pi 5 (8 GB), released 2024.

Raspberry Pi 500+, based on Raspberry Pi 5 (16 GB), released 2025.

Raspberry Pi keyboard computers come in different regional variants affecting

keyboard layout and required power supply.

Features
Edit this on GitHub

The features of your Raspberry Pi keyboard computer depend on the model.

Raspberry Pi 500 and Raspberry Pi 500+ are faster than Raspberry Pi 400 due to the
Cortex-A76 CPU, increased RAM, and upgraded GPU. The main differences between
the Raspberry Pi 400 keyboard computer and the Raspberry Pi 500 and 500+ keyboard
computers are:

Processor. Raspberry Pi 400 uses Cortex-A72 at 1.8 GHz; both Raspberry Pi 500
and 500+ use Cortex-A76 at 2.4 GHz, providing higher performance and eVciency.

Memory (RAM). Raspberry Pi 400 includes 4 GB of RAM; Raspberry Pi 500 includes

8 GB of RAM; Raspberry Pi 500+ includes 16 GB of RAM, providing smoother
multitasking and support for more demanding applications.

GPU. Raspberry Pi 400 includes VideoCore VI at 500 MHz; both Raspberry Pi 500
and 500+ include VideoCore VII at 910 MHz, providing faster graphics and
improved video decoding.

HDR video. All Raspberry Pi keyboard computers include two micro-HDMI ports,
providing 4K displays, but Raspberry Pi 500 and 500+ also support HDR on HDMI
outputs.

Power button. Raspberry Pi 400 doesn’t have a power button and is instead turned
on and off with a combination of key presses; both Raspberry Pi 500 and 500+ do
have a power button.

SoC. Raspberry Pi 400 includes the Broadcom chip, BCM2711; both Raspberry Pi
500 and 500+ use the Broadcom chip, BCM2712, in combination with the RP1 I/O
controller.

Raspberry Pi 500+ offers additional features, including:

Mechanical keys with customisable RGB LEDs and replaceable keycaps. For more
information, see Raspberry Pi 500+ mechanical keys. For instructions, see
Customise your backlighting and Change your keycaps.

Internal 256 GB M.2 SSD, which is replaceable. This SSD comes installed with
Raspberry Pi OS. For instructions, see Replace your M.2 SSD.

More RAM (16 GB). For a comparison, see the following table.

Raspberry Pi 400 Raspberry Pi 500 Raspberry Pi 500+

Dimensions 286 × 122 × 23 mm 286 × 122 × 23 mm 312 × 123 × 35 mm

Keys 78, 79, or 83 78, 79, or 83 84, 85, or 88

:
 membrane keys membrane keys mechanical keys
depending on depending on depending on
regional variant regional variant regional variant

Processor Quad-core 64-bit Quad-core 64-bit Quad-core 64-bit

Arm processor Arm processor Arm processor
(Cortex-A72 at 1.8 (Cortex-A76 at 2.4 (Cortex-A76 at 2.4
GHz) GHz) GHz)

SoC and I/O BCM2711 SoC BCM2712 SoC and BCM2712 SoC and
controller RP1 I/O controller RP1 I/O controller

Memory (RAM) 4 GB synchronous 8 GB synchronous 16 GB synchronous

dynamic RAM dynamic RAM dynamic RAM
(SDRAM) (SDRAM) (SDRAM)

GPU VideoCore VI at 500 VideoCore VII at VideoCore VII at

MHz 910 MHz 910 MHz

Video output Two micro-HDMI Two micro-HDMI Two micro-HDMI

ports that provide ports that provide ports that provide
either a single 4K 4K displays at 60 4K displays at 60
display at 60 Hz or Hz plus HDR Hz plus HDR
two 4K displays at support support
30Hz

Thermal control Aluminium Aluminium Aluminium

integrated heatsink integrated heatsink integrated heatsink

Wireless Dual-band Wi-Fi and Dual-band Wi-Fi and Dual-band Wi-Fi and
connectivity BLE BLE BLE

USB ports Two USB 3.0 ports; Two USB 3.0 ports; Two USB 3.0 ports;
one USB 2.0 port one USB 2.0 port one USB 2.0 port

Gigabit Ethernet Yes Yes Yes

GPIO Horizontal 40-pin Horizontal 40-pin Horizontal 40-pin

GPIO header GPIO header GPIO header

Storage microSD card slot microSD card slot microSD card slot
and M.2 SSD drive

Power input 5 V at 3 A (15 W) 5 V at 5 A (25 W) 5 V at 5 A (25 W)

through USB-C through USB-C through USB-C

Power button Key combination Dedicated button Dedicated button

(Fn + F10)

Customisability Key remapping Key remapping; RGB

backlighting; ability
to change keycaps

Keyboard computer kits

Raspberry Pi keyboard computers are available as standalone keyboards or as part of
a kit, including basic accessories to get started.

Raspberry Pi 400 kit

Raspberry Pi 400 keyboard computer.

15 W Raspberry Pi USB-C power supply.

Raspberry Pi USB mouse.

16 GB microSD card, pre-programmed with Raspberry Pi OS.

micro-HDMI cable.
:
 Beginner’s Guide book.

Raspberry Pi 500 kit

Raspberry Pi 500 keyboard computer.

27 W Raspberry Pi USB-C power supply.

Raspberry Pi USB mouse.

32 GB A2-class microSD card, pre-programmed with Raspberry Pi OS.

micro-HDMI cable.

Beginner’s Guide book.

Raspberry Pi 500+ kit

Raspberry Pi 500+ keyboard computer, including an SSD pre-programmed with
Raspberry Pi OS.

27 W Raspberry Pi USB-C power supply.

Raspberry Pi USB mouse.

micro-HDMI cable.

Spudger (opening tool) for access to the M.2 SSD (also provided with the
standalone keyboard).

Keycap puller for removing keycaps (also provided with the standalone keyboard).

Beginner’s Guide book.

Getting started
To get up and running with your Raspberry Pi keyboard computer, you can follow the
instructions at Getting started with your Raspberry Pi.

If you have a Raspberry Pi 500+ or got your 400 or 500 as part of a kit that includes a
microSD card pre-programmed with Raspberry Pi OS, you can skip ahead in the
instructions to Set up your Raspberry Pi.

Raspberry Pi 500+ mechanical keys

Each key on Raspberry Pi 500+ has its own mechanical switch underneath the keycap
that registers a key press. Raspberry Pi 500+ uses Gateron KS-33 low-progle
mechanical switches. By default, Gateron KS-33 switches use coloured stems to
indicate switch type (clicky, tactile, or linear). Raspberry Pi 500+ uses clicky Gateron
KS-33 switches with a custom grey stem.

Keycaps attach to the cross-shaped stem on top of the Gateron switches. These
switches have Cherry MX-compatible, cross-shaped stems, which is the industry
standard. For guidance and instructions on removing and replacing keycaps on your
Raspberry Pi 500+, see Change your keycaps on this page.

Raspberry Pi 500+ customisation

Raspberry Pi 500+ is the most recent keyboard computer. It offers the following
customisation options:

Replaceable M.2 SSD storage. For instructions, see Replace your M.2 SSD.

Keycap set changes. For instructions, see Change your keycaps.

:
 Backlighting presets, colours, and brightness. For instructions, see Customise your
backlighting.

For more advanced users, Raspberry Pi 500+ also allows:

LED congguration beyond the built-in presets.

On-the-iy key remapping.

For more information, see Advanced software settings.

Replace your M.2 SSD

You can expand storage capacity by replacing the M.2 SSD in your Raspberry Pi 500+.
You can also use this slot to install a different PCIe peripheral. The Raspberry Pi 500+
supports devices that use the M.2 M key edge connector in the form factors 2230,
2242, 2260, and 2280.

To complete this procedure, you need a cross head screwdriver, a iat head
screwdriver, and the provided plastic opening tool (spudger).

1. Unscrew the keyboard. Locate the gve screws on the bottom of the keyboard and
unscrew them using a cross head screwdriver. Keep the screws in a safe place.

2. Loosen the top of the keyboard from the bottom of the keyboard. Position the
spudger into the indentation at the front of the keyboard and then angle the
spudger upwards to start splitting the keyboard.
:
 3. Detach the top of the keyboard from the bottom of the keyboard. Wedge and
swipe the spudger along the opening groove at the front of the keyboard to detach
the top of the keyboard from the bottom.

4. Open the keyboard. Place the bottom of the keyboard on a iat surface and fold
(don’t lift) the top of the keyboard over to lay it face down on the same surface. Be
careful not to pull the top and bottom parts away from each other entirely because
they’re attached with a iexible cable.
:
 5. Release the M.2 SSD. By hand or with a iat head screwdriver, turn the screw on the
right side of the M.2 SSD anticlockwise to loosen it. Remove the screw and keep it
in a safe place. The M.2 SSD springs up when you remove the screw.

On this page
Documentation Features
Keyboard computer kits
Search ⌘ K
Getting started
Raspberry Pi 500+
Computers
mechanical keys

Getting started Raspberry Pi 500+

customisation
Raspberry Pi OS
Replace your M.2 SSD
Congguration Change your keycaps
Customise your
[Link]
backlighting
The Linux kernel Advanced software settings

Remote access

Camera software

AI Kit and AI HAT+

software
j. Pull out the M.2 SSD. Pull the M.2 SSD away from and then out of the keyboard.
Raspberry Pi computer
hardware

Keyboard computers

Features

Keyboard
computer kits

Getting started

Raspberry Pi 500+
mechanical keys

Raspberry Pi 500+
customisation
:
 Advanced software
settings

Compute Module
hardware

Processors

Software sources

Legacy [Link]
options

Accessories

Microcontrollers

Services

Pico C SDK

Datasheets

Product Information Portal

7. Add a new M.2 SSD. Insert another M.2 SSD by sliding it into the slot at the left
Tutorials
side. The SSD card gts in only one orientation. Hold the newly inserted M.2 SSD
down and replace the screw on the right side of it, turning the screw clockwise to
tighten.

k. Close the keyboard. Fold the top of the keyboard back onto the bottom of the
keyboard and click it back into place.

9. Screw the keyboard shut. Place and turn the gve screws back into place with your
cross head screwdriver.

Change your keycaps

You can swap out the default keycaps on your Raspberry Pi 500+ for custom sets.
Because the Gateron KS-33 switches on Raspberry Pi 500+ use the industry standard
Cherry MX stem shape, most third-party keycaps that are designed for Cherry MX are
compatible. Avoid taller progles that could hit the keyboard frame or produce too
much noise. For more guidance on choosing alternative keycaps, see Keyboard layout,
Keycap progles, and Lighting in this section.

To remove a keycap:

1. Insert the prongs of the keycap puller on opposite sides of a keycap that you want
to remove or replace. Allow the prongs to fall below the keycap.

2. Press the sides of the prongs to grip the keycap, ensuring equal pressure on both
sides.

3. Gently pull the keycap straight up off of the keyboard. Avoid pulling at an angle.

NOTE

You can also remove keycaps to allow you to clean underneath them.

You can now replace the keycap with another one, or reinstall the same keycap in its
original place:

1. Align the keycap by lining up its cross-shaped stem underneath it with the cross-
shaped stem on the corresponding switch.

2. Press the keycap down gently but grmly until the keycap is fully seated and feels
secure.

Keyboard layout
:
 Keycaps are available in various languages, with US layouts being the most widely
available, followed by UK layouts. Other languages can be harder to source.

The Raspberry Pi 500+ keyboard has a modiged 75% layout, which means that some
keys are non-standard and might not have matching keycaps in typical sets:

Power key. The power key in the top-right corner of the keyboard might not be
included in other keycap sets.

Lighting labels. The lighting labels on the F4, F5, and F6 keys of Raspberry Pi 500+
are non-standard.

Volume labels. The volume labels on the F10, F11, and F12 keys of Raspberry Pi
500+ are non-standard.

System Request key. The SysRq key on Raspberry Pi 500+ is non-standard.

Insert key. The Ins key on Raspberry Pi 500+ is non-standard.

Command key. The Cmd key typically says Win on keycap sets, and third-party
keycap sets don’t include the Raspberry Pi logo.

Keycap pro7les

The low-progle keycaps included on Raspberry Pi 500+ perform like traditional

mechanical keys while also keeping the keyboard compact. We recommend DSA or
Cherry progles for replacement keycaps:

DSA keycaps have a iat progle and can be swapped across rows.

Cherry keycaps are generally compatible, but have different sculpted progles for
ergonomics. This means that each row can have a slightly different height or angle.
For a consistent feel, check row alignment.

NOTE

XDA, OEM, and SA keycaps aren’t recommended because they’re taller, and can
therefore produce more noise or come into contact with the keyboard frame.

Lighting

The LEDs on the Raspberry Pi 500+ keyboard light the top half of the keycaps, which
means that fully opaque keycaps might block illumination.

Customise your backlighting

Raspberry Pi 500+ has most backlighting turned off by default. The only lighting that’s
enabled by default includes:

The activity LED behind the power button when the Raspberry Pi 500+ keyboard is
on. This LED:

Is red when Raspberry Pi 500+ is receiving power but is turned off.

Is green when Raspberry Pi 500+ is turned on.

Blinks with SD card activity.

The rainbow lighting animation that travels through the keys when you start up the
Raspberry Pi 500+ keyboard. Advanced users can turn this off for particular
backlighting presets using the congguration software. For more information, see
Change preset startup animation in Advanced software settings.

The Caps Lock indicator that lights up when active.

Raspberry Pi 500+ supports other RGB backlighting presets, powered by Vial QMK
:
 grmware. For instructions, see Choose backlight preset.

Choose backlight preset

Raspberry Pi 500+ comes with seven presets, which are the saved lighting progles on
your Raspberry Pi 500+ keyboard. To cycle forwards through these presets, press Fn +
F4 on the keyboard; to cycle backwards through these presets, press Fn + Shift + F4
on the keyboard.

Preset name Description

0 Off The default preset that only lights the power key, the startup
animation, and the Caps Lock indicator.

1 Solid Colour Solid white backlight.

White

2 Solid Colour Solid colour backlight, which you can change using Fn + F3.

3 Gradient Left Fixed rainbow backlight.

Right

4 Cycle Pinwheel Animated rainbow backlight, where the keys cycle through
different colours in a rainbow pattern across the keyboard.

5 Typing Heatmap The more you press a key, the closer to red it gets and the more
the keys around it light up.

6 Solid Reactive Reactive keyboard, where the keys light up when you press
Simple them. You can choose which colour using Fn + F3.

Backlight controls

You can customise the RGB backlighting colour (depending on the preset) and
brightness using the following keyboard shortcuts:

Change colour. Press Fn + F3 to cycle forwards through 16 backlight colours; press

Fn + Shift + F3 to cycle backwards through the colours.

Adjust brightness. Press Fn + F5 to reduce the brightness; press Fn + F6 to

increase the brightness.

NOTE

The Shift key on your keyboard either cycles backwards through available options,
or inverts the key function. For example, Fn + Shift + F5 increases the brightness
instead of decreasing it.

Advanced software settings

Raspberry Pi offers grmware that controls the built-in keyboard on Raspberry Pi 500
and 500+. With this tool, you can:

Enable and conggure advanced LED settings for Raspberry Pi 500+. For more
information, see Advanced led settings.

Remap keys on both Raspberry Pi 500 and 500+. For more information, see Remap
keys on your keyboard.

Play a Flappy Bird-style game on Raspberry Pi 500+. For information, see Flappy
Bird game.

For more information and options beyond those described in this page, see the
README for the conggurator tool on GitHub.

Firmware setup
:
 To use software-controlled lighting and to remap keys, you must grst update the
keyboard grmware and install the congguration tool:

1. Install the grmware update package. Run the following command: sudo apt
install rpi-keyboard-fw-update.

2. Update to the latest keyboard grmware update, which checks for and installs the
grmware required for advanced functionality. Run the following command: sudo
rpi-keyboard-fw-update.

3. Install the congguration tool, which allows you to adjust LEDs and remap keys. Run
the following command: sudo apt install rpi-keyboard-config.

You can see the keyboard grmware source code in the Vial QMK repository on GitHub.

Basic information commands

Use the following commands as appropriate to view the current state of your keyboard
computer before customising its lighting or remapping its keys.

Command Description

rpi-keyboard-config info - View keyboard model, lock status, and layout diagram.
-ascii If you don’t need the layout diagram, remove --ascii
from the command.

rpi-keyboard-config help List all available commands with brief descriptions.

rpi-keyboard-config list- List all available lighting effects, which can be applied
effects temporarily or to a preset.

rpi-keyboard-config preset List all current presets, numbered 0 to 6.

get

Advanced LED settings

Advanced users can customise Raspberry Pi 500+ backlighting beyond the basic
presets. Specigcally, the rpi-keyboard-config software allows you to:

Add other lighting effects to your Raspberry Pi 500+, temporarily or as presets. For
information, see Lighting effects.

Set a different startup animation for each preset. For information, see Change
preset startup animation.

Add speed, saturation, and hue parameters to an effect or preset. For information,
see Effect and preset parameters.

Control global hue and brightness. For information, see Global lighting controls.

Control individual LED lighting by congguring and then applying the direct effect.
For information, see Individual LED controls.

NOTE

Advanced LED settings are only available for Raspberry Pi 500+ because only this
model of keyboard computer has backlit keys.

Lighting effects

You can control Raspberry Pi 500+ backlighting through various effects and
parameters. With the exception of the power button, which is unaffected by any effect,
keyboard lighting effects are controlled through the congguration software. With this
software, you can:

Temporarily apply an effect to the keyboard until you shut down and restart the
:
 keyboard, or until you start to cycle through the presets again. Cycling through the
presets continues from the last preset before you applied a temporary effect.

Assign an effect to one of the seven keyboard presets. The default presets are
listed in Choose backlight preset. You can also add parameters and startup
animations to presets.

Use the following commands to choose, apply, and view a temporary effect on your
keyboard.

Command Description

rpi-keyboard-config list- List available lighting effects.

effects

rpi-keyboard-config effect Temporarily apply an effect, replacing effect-name

"effect-name" with the name of the effect, as listed in the output
of the previous command.

rpi-keyboard-config effect View the currently active effect.

You can also adjust the following parameters for an effect: speed, saturation, and hue.
For example, the following command changes the speed of the "Cycle Spiral"
effect to 42.

$ rpi-keyboard-config effect "Cycle Spiral" --speed 42

Any parameter you add must be a number between 0 and 255. For more information
about these parameters, including when they are and aren’t useful to add, see Effect
and preset parameters.

View presets

You can use the congguration software to check which preset you’re on, move
between them, or see details about each one. Each preset has an index number
between 0 and 6, representing the seven available slots.

Command Description Example (assuming default

presets)

rpi-keyboard-config Show the index of the If you’re currently on the

preset index current preset. Gradient Left Right preset,
this command tells you that
you’re on preset 3.

rpi-keyboard-config Skip to a different position The following command

preset index X in the preset cycle, where X takes you to the Typing
is the index of the preset (a Heatmap preset: rpi-
number between 0 and 6). keyboard-config preset
index 5.

rpi-keyboard-config List all current presets. This command lists the

preset get seven presets, numbered 0
to 6. Default presets are
summarised in Choose
backlight preset.

rpi-keyboard-config Show details about a The following command

preset get X specigc preset, where X is tells you that preset 5 is the
the index of the preset (a Typing Heatmap preset:
number between 0 and 6). rpi-keyboard-config
preset get 5.

Reassign presets

You can reassign presets to use different effects. For information about effects,
including how to obtain a list of available effects, see Lighting effects.
:
 NOTE

Changes you make to presets persist every time you restart your Raspberry Pi
500+. You can reset your presets to default at any time using the instructions in
Reset presets and LED customisations.

The following example changes the Gradient Left Right (3) preset to an effect that you
specify in the quotation marks.

$ rpi-keyboard-config preset set 3 "effect-name"

While reassigning a preset, you can add one or more of the following parameters:
speed, hue, or saturation. You can also set a specigc startup animation for that preset.
For information about these options, see Effect and preset parameters and Change
preset startup animation.

For example, the following command replaces the default Gradient Left Right preset
with the Rainbow Beacon effect at a speed of 140. It would also replace the default
startup animation for that preset so that the startup animation gnishes on white LEDs
and then fades into the Rainbow Beacon effect.

$ rpi-keyboard-config preset set 3 "Rainbow Beacon" --speed 140 --sta

rtup-animation "START_ANIM_W_FADE_SAT"

Change preset startup animation

For each preset, you can specify a startup animation with the following command:

$ --startup-animation "name_of_animation"

Replace name_of_animation with one of the following gve possible startup

animations:

Startup animation Description

name

START_ANIM_NONE No startup animation.

START_ANIM_B_NO_ Pulsing rainbow animation followed by blank LEDs and then

FADE immediately into the chosen effect.

START_ANIM_B_FAD Pulsing rainbow animation followed by blank LEDs fading into the
E_VAL chosen effect. This is the default startup animation.

START_ANIM_W_NO_ Pulsing rainbow animation followed by white LEDs and then

FADE immediately into the chosen effect.

START_ANIM_W_FAD Pulsing rainbow animation followed by white LEDs fading into the
E_SAT chosen effect.

For example, the following command would replace the startup animation for preset 3
with a pulsing rainbow animation that gnishes on white LEDs and then fades into the
preset:

$ rpi-keyboard-config preset set 3 --startup-animation "START_ANIM_W_

FADE_SAT"

Effect and preset parameters

You can add the following speed, saturation, and hue parameters to any effect or
preset:

Speed. To set the speed, add --speed X to the command, where X is a number
between 0 and 255. If you don’t add the speed parameter, the default speed is 128.

Saturation. To set the saturation, add --sat X to the command, where X is a

:
 number between 0 and 255. If you don’t add the saturation parameter, the default is
255 (maximum saturation).

Hue. To set the hue, add --hue X to the command, where X is a number between 0
and 255. If you don’t set a hue, the default is to use the global hue of the keyboard,
which is set with Fn + F3 on the keyboard. For more information, see Backlight
controls.

Some effects and presets are unaffected by some parameters. For example, a solid
colour is a static effect and so isn’t affected by a speed change.

Global lighting controls

Hue and brightness are managed on a range of 0 to 255. You can view and set the hue
and brightness of your Raspberry Pi 500+ by adding hue and brightness to the rpi-
keyboard-config command.

Command Description

rpi-keyboard-config hue Show the current global hue (colour) of your

Raspberry Pi 500+.

rpi-keyboard-config hue X Set the global hue, where X is a number between 0

and 255.

rpi-keyboard-config Show the current lighting brightness of your

brightness Raspberry Pi 500+.

rpi-keyboard-config Set the lighting brightness, where X is a number

brightness X between 0 and 255.

Individual LED controls

You can customise the backlighting of individual LEDs on your Raspberry Pi 500+.
This is useful for precise visual tweaks and for creating unique backlight patterns.

All the individual LED customisations that you can make are applied to an effect called
direct. You then apply the direct effect either:

Temporarily using the instructions in Lighting effects.

By assigning it to a preset using the instructions on Reassign presets.

If the direct effect is not already applied by one of the preceding methods, it is
automatically temporarily applied when running any of the individual LED
customisations.

The following table lists commands to set LED colours (globally or for each LED), and
save and load LED conggurations.

Command Description

rpi-keyboard-config leds Turn off all LEDs except the power button.
clear

rpi-keyboard-config leds Specify the colour of all the LEDs. Replace

set --colour <colour> <colour> with either with the common colour name
(for example, red), HSV numbers ranging from 0 to
255 in quotation marks (for example, "0,255,255"),
or RGB numbers in quotation marks (for example,
"rgb(255,0,0)").

rpi-keyboard-config led set Specify the colour of a specigc LED, where the LED
"<row>,<column>" --colour is the row and column co-ordinates ("<row>,
<colour> <column>"). You can check the LED row and
column co-ordinates, as well as what each of the
keys is currently set to, with the following
command: rpi-keyboard-config info --ascii.
:
 rpi-keyboard-config leds Save your LED congguration. To use the saved
save congguration, you can then either assign the direct
effect to a preset using the instructions in Reassign
presets, or load the congguration directly using the
load command, below.

rpi-keyboard-config leds Temporarily apply the direct effect to load the

load saved LED congguration. This is useful if you
haven’t assigned the direct effect to a preset.

In the following example, the specigc LED referenced by the row and column co-
ordinates ("2,6") is set to green with hue-saturation-value (HSV) numbers
("85,255,255"):

$ rpi-keyboard-config led set "2,6" --colour "85,255,255"

Reset presets and LED customisations

The following command resets your presets to the default settings and clears your
saved LED customisations:

$ rpi-keyboard-config reset-presets

Remap keys on your keyboard

Advanced users can remap the keys on both a Raspberry Pi 500 and 500+, allowing
you to customise your keyboard layout to match your workiow or gaming needs.

Use the rpi-keyboard-config software to:

List all keycodes available for remapping. For information, see List keycodes.

Check the current keymap. For information, see View keymap.

Remap the keys on your keyboard. For information, see Remap keys.

Watch key presses in the congguration software. For information, see Watch key
presses.

Edit up to four key-mapping layers. For information, see Manage layers.

Reset your keyboard to the default key mapping. For information, see Reset to
default keyboard layout.

The Raspberry Pi 500 and 500+ are compatible with Vial. You can use the Vial web UI
to remap your keys. For information, see Remap keys with Vial.

List keycodes

To remap your keyboard, you need to know the keycodes for the keys you want to
assign on your Raspberry Pi 500 or 500+. The following command lists all possible
keycodes:

$ rpi-keyboard-config list-keycodes

You can also list only the keycodes in a specigc category using --category. For
example, the following command lists all the keycodes for the basic category:

$ rpi-keyboard-config list-keycodes --category basic

View keymap

Use the following command to see how keys are currently mapped on all positions on
your keyboard:
:
 $ rpi-keyboard-config key get-all

Use the following command to see the keycode for a specigc key at a position that
you specify with the key’s row and column co-ordinates. Replace <row> and <column>
with the appropriate numbers:

$ rpi-keyboard-config key get <row> <column>

NOTE

You can check a key’s row-column co-ordinates using rpi-keyboard-config

info --ascii. This provides a layout diagram of the keyboard.

For example, to get the keycode for the Q key (with the row-column co-ordinates 2 2)
on your keyboard:

$ rpi-keyboard-config key 2 2

Remap keys

Use the following command to set a different keycode at a position that you specify
with the key’s row and column. Replace <row> and <column> with the appropriate
numbers, and replace <keycode> with the keycode that you want to map to the
speciged key.

$ rpi-keyboard-config key set <row> <column> <keycode>

NOTE

You can check a key’s row-column co-ordinates using rpi-keyboard-config

info --ascii. You can check a key’s keycode using rpi-keyboard-config
list-keycodes.

For example, if you wanted to remap Q (with the row-column co-ordinates 2 2) on your
keyboard as R (with the keycode KC_R):

$ rpi-keyboard-config key set 2 2 KC_R

Watch key presses

You can read the state of keys to monitor key activity inside the congguration tool to
tell you which keys are pressed and released. Before you can do this, you must unlock
the keyboard.

To check the lock status of your keyboard:

$ rpi-keyboard-config info

To unlock your keyboard so that you can then watch key presses:

$ rpi-keyboard-config unlock

The congguration tool guides you through holding down specigc keys until a
countdown completes. By default, the keys are Enter + Escape, which light up in red to
guide you. If you’ve remapped these keys, the unlock sequence uses the physical
positions of those keys, not their new labels; the command tells you which remapped
keys to press for your setup.

When the keyboard is unlocked, you can monitor key activity with the following
command:

$ rpi-keyboard-config key watch

:
 This prints to the terminal whenever a key is pressed or released. For LED feedback,
the keys on the keyboard also light up red as you press them. To remove the light-up
functionality while watching key presses, add --no-leds to the above command:

$ rpi-keyboard-config key watch --no-leds

Lock your keyboard when you’re done. The following lock command doesn’t require
any congrmation; it locks the keyboard immediately.

$ rpi-keyboard-config lock

Manage layers

You can set different key mappings on different layers. There are four layers that you
can edit, numbered 0–3; the default layer is 0. By default, the Fn key changes the
keyboard from layer 0 to layer 1. You can add --layer to any of the following
commands, as appropriate:

rpi-keyboard-config key get-all

rpi-keyboard-config key get

rpi-keyboard-config key set

Reset to default keyboard layout

The following command resets your keyboard layout to the default key mappings,
including resetting all layers:

$ rpi-keyboard-config reset-keymap

Remap keys with Vial

Vial works with your keyboard grmware to conggure your keyboard in real time.

1. On your Raspberry Pi 500 or 500+, go to Vial web interface.

2. In the window that appears, select your keyboard and click Connect.

3. Use the Vial web interface to change your key mappings.

For information about how to use Vial, see the Vial documentation.

NOTE

We recommend that you use Vial only for working with the key mapping and not
for customising the RGB LEDs.

Return to default settings

Your software-controlled preferences are saved in iash memory and persist after
reboot and grmware updates. To reset your backlight settings and keyboard layout,
wipe the iash area that they’re stored in with the following command:

$ sudo rpi-keyboard-fw-update -w -i

This clears all customisations and restores the keyboard to default backlighting and
key mapping.

If the keyboard layout has been misconggured to the extent that input on the
Raspberry Pi 500+ is no longer possible, you can still complete a reset to default
settings by connecting an external USB keyboard to one of the available USB ports
and entering the command from that device instead.
:
 Flappy Bird game
For a bit of fun, the following command allows you to use the keyboard backlighting to
play a basic Flappy Bird-style game on Raspberry Pi 500+:

$ rpi-keyboard-config game

The game uses your keyboard backlighting as the "screen", and the lights iash in
patterns to represent the bird and pipes. Your goal is to keep the bird from hitting
pipes, similar to the original Flappy Bird. Press the space bar to iy over pipes (lit-up
LEDs). Your "bird" continues to drop until you press the space bar. Your score is
determined by the number of pipes you’ve successfully passed, which is indicated by
the number of purple LEDs along the top of the keyboard.

To exit the game, press Q on your keyboard.

You can view and edit the Raspberry Pi documentation source on Github. Please read our usage and contributions policy before you make a Pull
Request.

Raspberry Pi documentation is copyright © 2012-2025 Raspberry Pi Ltd and is licensed under a Creative Commons Attribution-ShareAlike 4.0
International (CC BY-SA) licence.

Some content originates from the eLinux wiki, and is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported licence.

The terms HDMI, HDMI High-Degnition Multimedia Interface, HDMI trade dress and the HDMI Logos are trademarks or registered trademarks of
HDMI Licensing Administrator, Inc
: