Home

Awesome

PicoMK <!-- omit in toc -->

PicoMK is a highly configurable mechanical keyboard firmware designed for Raspberry Pi Foundation's RP2040. The chip features two Cortex-M0 processors. Based on the smp branch of FreeRTOS, PicoMK supports multicore execution on RP2040. It currently powers these boards:

Table of Contents

Features

Quick Start

Get the Code

This guide assumes you're using one of the followings: Linux (including Raspbian), Windows WSL, MacOS.

First, install the dependencies for pico-sdk

Then checkout the code

git clone https://github.com/zli117/PicoMK.git
cd PicoMK
git submodule update --init && git -C pico-sdk submodule update --init

The last command will checkout all the dependencies such as pico-sdk and FreeRTOS, so it might take a while depending on your internet connection.

Build a Firmware

To create a custom firmware, you can make a copy of the existing config in the configs/ folder. For this guide, we will copy the default config in configs/default.

mkdir -p configs/tutorial/my_new_config
cp configs/default/* configs/tutorial/my_new_config

Each config consists of two files: config.h and layout.cc. Please see the comments in the file and the documentations for information on how to configure them.

The following commands builds the firmware:

mkdir build
cd build
cmake -DBOARD_CONFIG=<board_config> ..
make -j 4

<board_config> is the relative path of the custom config folder we have just created w.r.t the configs/ folder. In our case, to build the configs/tutorial/my_new_config config, you can use this command:

cmake -DBOARD_CONFIG=tutorial/my_new_config ..

Once you successfully build the firmware, you can find the firmware.uf2 file under the current (build/) folder. Now take the Pico board (or other RP2040 boards you have) and put it into the bootloader mode (for Pico board, you can just hold down the bootsel button and replug the USB cable). Mount the board as USB mass storage device, if not done automatically. Copy over the firmware.uf2 to the storage device folder and you're all set.

Please take a look at the following documentations on how to customize different parts of the firmware, including implementing your own custom keycode handler and more.

Build and install the Linux Kernel Module (for Raspberry Pi OS)

The Kernel Module works for the latest kernel on Raspberry Pi OS (6.1.21).

  1. Install kernel headers:
    sudo apt install raspberrypi-kernel-headers
    
  2. Build the driver and device tree overlay:
    cd linux/
    make -j
    make device_tree
    
  3. Install the driver:
    sudo -E make install
    sudo depmod -a
    
  4. Copy over the device tree overlay:
    sudo cp spi1-picomk.dtbo /boot/overlays
    
  5. Add this line to the /boot/config.txt to enable the overlay. Make sure SPI1 is not enabled.
    dtoverlay=spi1-picomk
    
  6. Add this line to the /etc/modules file for loading the kernel module:
    spi_picomk
    

Documentations

Anatomy of layout.cc

Basic intro to configuring a keyboard layout with layout.cc file.

Inter-Board Protocol (IBP)

Details on the Inter-Board Protocol and how it's designed.

Devices and Registration Functions

Description of the currently supported devices and their registration functions.

Configuration Menu

Information on how the config menu works and how to add more to it.

Design and Tradeoffs

Documents the overall code design, and some decisions.

Example Configurations

NameDescription
defaultDefault config for the Pico-Keyboard
examples/home_screenAn example of customizing the home screen, and overall how to customize a default device and register it.
examples/bare_minimumShow that registration is like conditional compilation. If you don't register something, it'll be stripped from the binary. default config binary size: 542208 bytes, examples/bare_minimum binary size: 394240 bytes
examples/custom_keycodeCreate three custom keycodes that translate keyboard up/down/enter keys to config mode curser up/down/select.
cyberkeeb_2040Example for setting up IBP for sending keycodes to Pi Zero.

Future Roadmaps