The firmware for the minipad, an RP2040-based 2-3-key keypad for the rhythm game osu!.
This firmware is designed specifically to work with our open-source PCB,
which can be found in our GitHub repository here.
Features • Installation • Development Setup
Serial Protocol • Licenses
Although this firmware is made for the aforementioned PCB, it can be used for different kinds of (hall effect or not) keypad/keyboard projects due to it's support of both digital and hall effect buttons, as well as no real limitation on how many keys to use.
Here is a list of features that are both planned and available:
- A fully dynamic amount of hall effect and digital keys (only limited by the RP2040)
- Rapid Trigger (explained here) with 0.01mm resolution
- Flexible, configurable travel distance of switches
- Adjustable actuation point (0.01mm resolution)
- Software-based low pass filter for analog stability
- Configurable keychar pressed upon key interaction
- Serial communication protocol for configuration
- A command-line tool for configuration, minitool
- Support for RGB lights, including configurable colors and effects
- Usage of multiplexers to allow for more keys to be used on the hardware
To flash this firmware on your minipad or other RP2040 board, please refer to our firmware installation guide. In there, you can find the instructions on how to initially load the firmware on the keypad, and how to update it later on.
Setting up this project is really simple. The repository is set up using PlatformIO, an IDE in form of an extension for Visual Studio Code.
You can find a download link for Visual Studio Code here. In there, search and install the extension PlatformIO.
After that is done, clone the repository with git clone https://github.com/minipadkb/minipad-firmware and open the cloned folder using Visual Studio Code. PlatformIO will perform an installation of all dependencies for this project (Arduino-Pico framework, various drivers, ...). This might take up some time, depending on your network connection.
If you are not familiar with the usage of PlatformIO, a Quick Start guide can be found here.
Note: Uploading the firmware only works if the micro controller is set into bootloader mode. This can be done using the BOOTSEL button on development boards or setting the minipad into bootloader mode/flashing directly via minitool. Help on the latter can be found here.
The firmware is being configured and accessed from the host device via Serial communication at a baud rate of 115200. There is a command-line utility tool called "minitool" for communicating with the firmware. You can find the git repository here.
All data sent via the serial interface is being interpreted as a command with the following syntax:
command arg0 arg1 arg2 .... The command and it's arguments are split by whitespaces, ending with a newline character.
There is a differention between a global and key-related command. As for keys, namingly hall effect keys (identifier hkey) and digital keys (identifier dkey), the command syntax looks the following: identifier.command arg0 arg1 arg2 ....
Either a single key or all keys at one can be targetted. If you wish to target a single key, you can put the one-based index of the key after the identifier. (e.g. hkey1, dkey3)
Here is a list of commands and examples for them:
Global commands
Command: boot
Syntax: boot
Example: boot
Description: Sets the device into bootloader mode.
Command: save
Syntax: save
Example: save
Description: Writes the current configuration of the keypad to the EEPROM.
Command: get
Syntax: get
Example: get
Description: Returns the configuration of the keypad, in the GET key=value format.
Command: name
Syntax: name <string>
Example: name mini's minipad
Description: Sets the name of the minipad, used to distinguish different devices visually.
Command: out
Syntax: out
Example: out
Description: Returns the sensor values and magnet distance of all Hall Effect keys.
Command: echo (debug-exclusive)
Syntax: echo <string>
Example: echo I am a string.
Description: Echoes the specified string, used for development purposes.
Key-related commands
Command: hkey.rt
Syntax: hkey.rt <bool>
Example: hkey.rt 1
Description: Enables/Disables Rapid Trigger functionality on the specified key.
Command: hkey.crt
Syntax: hkey.crt <bool>
Example: hkey.crt false
Description: Enables/Disables Continuous Rapid trigger functionality on the specified key.
Command: hkey.rtus
Syntax: hkey.rtus <uint16>
Example: hkey.rtus 45
Description: Sets the sensitivity for an upwards movement of the Rapid Trigger feature on the key. The unit of the value is 0.01mm.
Command: hkey.rtds
Syntax: hkey.rtds <uint16>
Example: hkey.rtds 10
Description: Sets the sensitivity for a downwards movement of the Rapid Trigger feature on the key. The unit of the value is 0.01mm.
Command: hkey.lh
Syntax: hkey.lh <uint16>
Example: hkey.lh 250
Description: Sets the lower hysteresis for the actuation point below which the key is being pressed. The unit of the value is 0.01mm.
Command: hkey.uh
Syntax: hkey.uh <uint16>
Example: hkey.uh 320
Description: Sets the upper hysteresis for the actuation point above which the key is no longer being pressed. The unit of the value is 0.01mm.
Command: hkey.char, dkey.char
Syntax: ?key.char <uint8/character>
Example: dkey.char 97 or dkey.char a
Description: Sets the character pressed when the specified key is pressed down. The value is the ASCII number of the character.
Command: hkey.hid, dkey.hid
Syntax: ?key.hid <bool>
Example: dkey.hid false
Description: Enables/Disables the HID output (meaning whether the key signal is sent to the host device) on the specified key.
As the firmware is distributed under the GPL-3 license, commercial usage is allowed for anyone, given that your source code and any changes made are released to the public.
Furthermore, we'd like every company or individuals using the firmware commercially to consider donating us a part of their profit made. This would help us funding the Minipad Project, as well as allowing us to spend more of our free-time to work and maintain this project.
If you're considering financially supporting us, please send a DM to @minisbett on Discord, or reach out to them via Twitter.
We're more than happy to help you get along with the firmware, as well as adjusting it to work on your hardware!
| Component | Original Repository | Forked Repository | License |
|---|---|---|---|
| Arduino Pico | earlephilhower/arduino-pico | minipadkb/arduino-pico |  |
| Keyboard | earlephilhower/Keyboard | minipadKB/Keyboard |  |
| Pico SDK | raspberrypi/pico-sdk | minipadKB/pico-sdk |  |
