https://github.com/veeso/gpio2key
a Linux utility written in Rust that maps GPIO pins to keyboard key events using the evdev interface
https://github.com/veeso/gpio2key
gpio raspberry-pi raspberrypi retrogaming retropie rust rust-lang
Last synced: 6 months ago
JSON representation
a Linux utility written in Rust that maps GPIO pins to keyboard key events using the evdev interface
- Host: GitHub
- URL: https://github.com/veeso/gpio2key
- Owner: veeso
- License: mit
- Created: 2025-12-15T16:24:29.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-12-26T13:00:06.000Z (6 months ago)
- Last Synced: 2025-12-28T01:00:10.164Z (6 months ago)
- Topics: gpio, raspberry-pi, raspberrypi, retrogaming, retropie, rust, rust-lang
- Language: Rust
- Homepage:
- Size: 62.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# gpio2key
[](https://opensource.org/licenses/MIT)
[](https://github.com/veeso/gpio2key/stargazers)
[](https://crates.io/crates/gpio2key)
[](https://crates.io/crates/gpio2key)
[](https://ko-fi.com/veeso)
[](https://conventionalcommits.org)
[](https://github.com/veeso/gpio2key/actions/workflows/cargo.yml)
## Introduction
gpio2key is a Raspberry Pi and Linux utility written in Rust that maps GPIO pins to keyboard key events using the evdev interface.
It is particularly useful for embedded systems like Raspberry Pi, where physical buttons connected to GPIO pins can
be used to simulate keyboard input.
In my case I've done this to mod the LEGO Gameboy to add physical buttons using a Raspberry Pi Zero 2W on RetroPie OS.
## Usage
```bash
gpio2key --config config.toml
```
Other options:
- `--config `: Path to the configuration file (default: `config.toml`)
- `--device `: Path to the GPIO character device representing the GPIO chip (default: `/dev/gpiochip0`)
- `--keyboard-name `: Set the name of the virtual keyboard device (default: `gpio2key`)
- `--log-level `: Set the logging level (options: `error`, `warn`, `info`, `debug`, `trace`; default: `info`)
- `--raspberry`: Enable Raspberry Pi specific GPIO setup. This will also setup gpio as pull-up inputs.
- `--help`: Show help information
> [!NOTE]
>
> On Linux, there is no way from `gpio-cdev` to set pull-up or pull-down resistors on GPIO pins.
> So you need to set them up manually before running the program, or use a hardware solution (e.g. external resistors).
> If you are using a Raspberry Pi, you can use the `--raspberry` flag to automatically set GPIO pins as pull-up inputs using the `rppal` crate.
## Configuration
Default configuration file path is `config.toml`, but can be overridden with the `--config` command line argument.
```toml
default_debounce_ms = 20 # default debounce time in milliseconds
default_active_low = true # default active_low setting for keys; if true, key is active when GPIO is low
poll_interval_ms = 5 # polling interval in milliseconds
[[key]]
gpio = 17
keycode = "A"
active_low = true # `default_active_low` by default
debounce_ms = 20 # `default_debounce_ms` by default
repeat = false # disabled by default
[[key]]
gpio = 22
keycode = "UP"
repeat = true
repeat_delay_ms = 300
repeat_rate_ms = 80
[[powerswitch]]
gpio = 27
active_low = false
```
### Parameters
#### Global Settings
- `default_debounce_ms`: Default debounce time in milliseconds for keys (default: `20`)
- `default_active_low`: Default active_low setting for keys; if true, keys are active when GPIO is low (default: `true`)
- `poll_interval_ms`: Polling interval in milliseconds for checking GPIO states (default: `5`)
#### Keys
Keys are defined in the `[[key]]` array.
A key is mapped to a GPIO pin and generates key events when the pin state changes.
Each key can have the following parameters:
- `gpio`: GPIO pin number (required)
- `keycode`: Key code as defined in `input-event-codes.h` (required)
- `active_low`: If true, the key is active when the GPIO pin is low (default: `default_active_low`)
- `debounce_ms`: Debounce time in milliseconds (default: `default_debounce_ms`)
- `repeat`: If true, the key will auto-repeat when held down (default: `false`)
- `repeat_delay_ms`: Delay before auto-repeat starts in milliseconds (default: `500`)
- `repeat_rate_ms`: Interval between auto-repeats in milliseconds (default: `30`)
#### Power Switches
Power switches are defined in the `[[powerswitch]]` array.
A power switch is mapped to a GPIO pin and triggers a system shutdown when activated.
In order to use this feature, the program must be run with sufficient privileges to execute shutdown commands.
Each power switch can have the following parameter:
- `gpio`: GPIO pin number (required)
- `active_low`: If true, the power switch is active when the GPIO pin is low (default: `true`)
## Build for RetroPie
For building on RetroPie and ARM32 systems, you need to follow these steps:
```bash
rustup target add armv7-unknown-linux-musleabihf
sudo apt install -y musl-tools gcc-arm-linux-gnueabihf
cargo build --release --target armv7-unknown-linux-musleabihf
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.