minipadkb/minipad-firmware

The Firmware of the minipad, a Hall Effect keypad with osu! and Rapid Trigger in mind.

minipad-firmware

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

Made with ❤️ by Project Minipad

Features ⌨️

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

Planned Features 🗒️

• Support for RGB lights, including configurable colors and effects
• Usage of multiplexers to allow for more keys to be used on the hardware

Installation ⚡

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.

Setup for development 💻

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.

Minipad Serial Protocol (MSP) 🔗

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.

Commercial usage 💵

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!

Licenses 🔑

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

minipad-firmware's Issues

qol: Rename/Refactor `ANALOG_RESOLUTION_SQUARED` in `KeypadHandler`

e4

qol: Add versioning (and migration?) to the configuration

Right now, handling new configuration layout through firmware updates is handled by comparing the hardcoded ``Configuration` struct version with the one saved in the EEPROM. If it does not match, it resets the whole configuration.

This might be annoying for users since on many firmware updates their config would reset. There should be a more modular versioning system or a system alike. What would also be nice is if there could be some sort of migration for the settings that stay untouched.

qol: Migrate constant default configuration values to the structs

The default config initialization might look less clumsy if constant values (e.g. rapid trigger state, led colors, ...) are defined in the struct directly, using the getDefaultConfig function only to assign dynamically created/calculated values to their fields.

qol: Replace raw->distance `map()` with LUT

Currently, the mapping from raw sensor readings to the distance is done using Arduino's map() function.
It looks as follows:

long map(long x, long in_min, long in_max, long out_min, long out_max) {
  return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
}

It uses longs, which isn't optimal considering we only use uint16_t here.
Furthermore it performs a division which has a significant impact on the scan rate / performance of the mapping.

This could be fixed by introducing a lookup table.

feat: make analog values much more accurate by applying proper gauss-correction

The relation between the distance of a magnet and the strength of the magnetic field (gauss) is not linear.
Instead, it depends on various properties of the magnet, as well as the functionality of the sensor.

On the Discord, we've been working on a lookup table for the SLSS49E and KS-20 switches for months and the goal is to implement it into the firmware in order to allow for a much, much nicer accuracy.