Skip to main content
Some MinimalPad behaviors are compiled into the firmware and cannot be changed from the browser. This page explains how to modify the firmware source files for those cases — encoder rotation, firmware macros, and default boot behavior. For everything else, MinimalPad Studio is the right tool. See Firmware vs Studio if you are unsure which approach you need.
This page is for advanced users who need to edit firmware source code. Most key customization — including assigning keys, managing layers, and controlling RGB — can be done directly in Studio without building firmware.
To make advanced changes, you edit the firmware source files in your forked repository, build new firmware using GitHub Actions, and flash the result to your device.

​
When Advanced Customization Is Needed

  • Changing encoder rotation — what happens when you turn the encoder clockwise or counter-clockwise
  • Creating or editing firmware macros — multi-step key sequences defined in the keymap source
  • Changing default boot behavior — which layer the device starts on

​
Key Source Files

All source files live in the firmware repository. The files you are most likely to edit are:

​
Understanding the Keymap Structure

The keymap file uses ZMK behaviors to define what each position does. Common behaviors include:
  • &kp — a standard key press (e.g., &kp C_VOL_UP)
  • &mo — momentarily activate a layer while held
  • &bt — Bluetooth profile actions
  • &rgb_ug — RGB underglow controls
  • &out — toggle between USB and Bluetooth output
Each layer has a bindings array listing all 17 positions: 16 keys in the 4×4 grid, followed by the encoder press on the last line. After the bindings array, sensor-bindings defines the encoder rotation behavior for that layer. Here is the structure of a layer in the default keymap:
The sensor-bindings line defines: CW = C_VOL_UP, CCW = C_VOL_DN.

​
Changing Encoder Rotation

Encoder rotation is controlled by the sensor-bindings line in each layer. To change it:
  1. Open boards/shields/minimalpad/minimalpad.keymap in your fork.
  2. Find the sensor-bindings line in the layer you want to change.
  3. Replace the two behaviors with your desired CW and CCW actions.
Example — Volume control (the default):
CW turns volume up; CCW turns volume down. Example — Scroll up/down:
Example — Custom RGB brightness on a layer (using a named sensor-rotate behavior, as in the default btled_layer):
Then reference it in the layer: sensor-bindings = <&rgb_encoder>;
&inc_dec_kp works for standard key presses. For RGB or other non-keypress behaviors, define a zmk,behavior-sensor-rotate block as shown above.
After editing, commit your changes, let GitHub Actions build the firmware, download the minimalpad_with_studio artifact, and flash it. See Build with GitHub Actions and Install Firmware.

​
Creating a Firmware Macro

Firmware macros let you emit a precise sequence of key events — useful for text snippets, complex shortcuts, or application-specific sequences. They are defined in the keymap file and compiled into the firmware. Basic steps:
  1. Define a &macro behavior block in the behaviors section of the keymap file:
  1. Assign it to a key position in a layer’s bindings array:
  1. Build and flash the new firmware.
Macro sequences are compiled into the firmware. Once flashed, the macro itself cannot be edited from Studio — only its key assignment position can be changed. To update the sequence, edit the source and reflash.
For the full macro behavior reference, including wait times, tap-then-hold, and parameter macros, see the ZMK Macros documentation.

​
Full ZMK Reference

MinimalPad uses standard ZMK firmware. For anything beyond the examples above — custom behaviors, combos, hold-tap configuration, and more — the ZMK documentation is the authoritative reference.

​
After Editing

Once you have made your changes:
  1. Commit and push to your forked repository.
  2. GitHub Actions builds the firmware automatically. See Build with GitHub Actions.
  3. Download the minimalpad_with_studio artifact and flash it. See Install Firmware.