PRK Firmware is a framework for DIY-keyboards written and configured in PicoRuby which is an alternative mruby implementation targeting on one-chip microcontroller.
- A "keymap" can be configured in Ruby which is a concise, readable and happy language
- RP2040 is the target platform microcontroller
- You can write your own "action" which will be invoked when you tap or hold a key (example(TBD))
The following boards have been confirmed to work as of now:
- Raspberry Pi Pico
- Sparkfun Pro Micro RP2040 (
DEV-17177now it's DEV-18288)
(left: Raspberry Pi Pico / right: Sparkfun Pro Micro RP2040)
- Unsplit keyboard
- Split keyboard
- Symmetrical type. eg) Crkbd
- Asymmetrical type. eg) ???
- UART communication between left and right
- I2C communication between left and right
- Macros
- Media keys
- RGBLED. An example on picoruby/prk_crkbd
- OLED display
- Rotary encoder. An example on prk_helix_rev3/keymap.rb
- Mouse / Trackball
- Debugging over a serial port
There are two ways to install PRK Firmware:
Anyhow, you should:
- Be knowledgeable how to install a UF2 file into Raspi Pico on https://www.raspberrypi.org/documentation/rp2040/getting-started/#getting-started-with-c
- https://learn.sparkfun.com/tutorials/pro-micro-rp2040-hookup-guide will also be helpful if you use Sparkfun Pro Micro RP2040
-
Download the newest release binary from Releases
-
Unzip it. You should get a file that looks like
prk_firmware-0.9.0-20210910-xxxxxxxx.uf2
-
Flash the uf2 into RP2040
-
PRKFirmware
mass storage drive should be mounted, then drag and drop yourkeymap.rb
Your keyboard will automatically reboot. Enjoy!
(See also Contributing)
You may not want PRK Firmware to be a mass storage device in case that your employer doesn't allow you to bring a USB memory 🙈
-
Install CRuby (MRI) because "Static type checking" by Steep will be invoked in build process
-
Setup Raspberry Pi Pico C/C++ SDK
- Follow the instructions on https://github.com/raspberrypi/pico-sdk#quick-start-your-own-project
- Make sure you have
PICO_SDK_PATH
environment variable
- Make sure you have
- Follow the instructions on https://github.com/raspberrypi/pico-sdk#quick-start-your-own-project
-
Clone the
prk_firmware
(this repository) wherever you likegit clone --recursive https://github.com/picoruby/prk_firmware.git # Don't forget --recursive cd prk_firmware
-
Clone a keymap repository, for example, "meishi2" which is a 2x2 matrix card-shaped keyboard in
keyboards
directorycd keyboards git clone https://github.com/picoruby/prk_meishi2.git
-
(Option) Edit
prk_meishi2/keymap.rb
as you wish -
Build with
cmake
andmake
cd [path]/[to]/prk_meishi2/build cmake -DPRK_NO_MSC=1 ../../.. make
(Defining PRK_NO_MSC macro will avoid implementing mass storage feature)
Now you should have
prk_firmware-[version]-[date]-no_msc.uf2
file inprk_firmware/keyboards/prk_meishi2/build/
directory which includes your keymap in code. -
(Troubleshooting) If you got an error on
cmake -DPRK_NO_MSC=1 ../../..
- Try this procedure once
- Then, redo
cmake
again
-
Install that
.uf2
file into RP2040
- On macOS, you can use docker to build it
docker build -o keyboards --build-arg KEYBOARD=prk_meishi2 .
- Make sure installing your setup on both side
-
You can see debug print on a "USB Serial Port" (so-called "COM Port" in Windows) that will be helpful if your
keymap.rb
doesn't work wellBaud: 115200 Data bits: 8 Parity: None Stop bits: 1 Flow control: None
# in the top directory of prk_firmware
./setup.sh
cd build
make
Then patch and send a pull request.
You can use Dockerfile to build if you prefer.
- It's possible that your Ruby code can't be compiled as you wish
- Remember that "Ruby" in PRK is neither CRuby nor even mruby
- PicoRuby doesn't support some Ruby syntax and may have bugs. It would be great if you send a patch, too!
- Unlike QMK Firmware, prk_firmware repository doesn't include individual keymaps
-
Raspberrypi Pi Pico
-
Sparkfun Pro Micro RP2040
Feel free to reach out to me if you want me to link your keymap on this README.
-
Q: Can I use Sparkfun Pro Micro RP2040 as a drop-in replacement instead of a Pro Micro without having to modify the CRKBD PCB?
A: Yes you can! However, note that exising LEDs on your CRKBD may not blink
RGBLED feature is still not implemented on PRK. And don't expect your existing CRKBS's LEDs will blink even if the feature is readybecause the logic voltage of RP2040 is 3.3V while 5V on "normal Pro Micro". It depends on the specificaion of LED.In terms of 3.3V, you should be careful of the same thing which is warned on Proton-C: https://qmk.fm/proton-c/
Some of the PCBs compatible with Pro Micro have VCC (3.3V) and RAW (5V) pins connected (shorted) on the pcb. Using the Proton C will short 5V power from USB and regulated 3.3V which is connected directly to the MCU. Shorting those pins may damage the MCU on the Proton C.
So far, it appears that this is only an issue on the Gherkin PCBs, but other PCBs may be affected in this way.
In this case, you may want to not hook up the RAW pin at all.
-
Q: PRK Firmware no longer works after pulling the newest master branch, why?
A: It likely happens when submodules like PicoRuby were also updated, try
git submodule update --recursive
. Besides, PRK may get a breaking change as it is still a beta version. Take a good look at CHANGELOG.md
Copyright © 2021 HASUMI Hitoshi. See MIT-LICENSE for further details.