> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimalmacropad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced: Customize MinimalPad Firmware Source Files

> Edit the MinimalPad keymap source to change dial rotation, create firmware macros, and modify compiled behaviour beyond what a configurator supports.

Some MinimalPad behaviors are compiled into the firmware and cannot be changed from either configurator. This page explains how to modify the firmware source files for those cases — encoder rotation, firmware macros, and default boot behavior. For everything else, [Studio for Mac](/mac/overview) or [Studio for browser](/browser/overview) is the right tool.

<Warning>
  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 a configurator without building firmware.
</Warning>

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](https://github.com/TimoWielink/zmk-config-minimalpad). The files you are most likely to edit are:

| File                                          | Purpose                                                           |
| --------------------------------------------- | ----------------------------------------------------------------- |
| `boards/shields/minimalpad/minimalpad.keymap` | Key bindings and encoder sensor-bindings for each layer           |
| `config/west.yml`                             | ZMK module dependencies                                           |
| `build.yaml`                                  | What GitHub Actions builds: the `minimalpad_with_studio` firmware |

## 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:

```c theme={null}
default_layer {
    display-name = "Default";
    bindings = <
        &kp LG(SPACE)      &kp LC(UP)         &kp LC(LG(SPACE))  &kp LC(LG(Q))
        &kp LG(C)          &kp LG(V)          &kp LG(Z)          &kp LG(LS(Z))
        &kp LG(LS(N4))     &kp LG(LS(N5))     &kp C_BRI_DN       &kp C_BRI_UP
        &kp C_PREV         &kp C_PP           &kp C_NEXT         &mo BTLED
        &kp C_MUTE
    >;
    sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>;
};
```

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):**

```c theme={null}
sensor-bindings = <&inc_dec_kp C_VOL_UP C_VOL_DN>;
```

CW turns volume up; CCW turns volume down.

**Example — Scroll up/down:**

```c theme={null}
sensor-bindings = <&inc_dec_kp PG_UP PG_DN>;
```

**Example — Custom RGB brightness on a layer** (using a named `sensor-rotate` behavior, as in the default `btled_layer`):

```c theme={null}
rgb_encoder: rgb_encoder {
    compatible = "zmk,behavior-sensor-rotate";
    #sensor-binding-cells = <0>;
    bindings = <&rgb_ug RGB_BRI>, <&rgb_ug RGB_BRD>;
};
```

Then reference it in the layer: `sensor-bindings = <&rgb_encoder>;`

<Note>
  `&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.
</Note>

After editing, commit your changes, let GitHub Actions build the firmware, download the build, and flash `minimalpad_with_studio.uf2`. See [Build your own firmware](/firmware/build-your-own) and [Update the firmware](/firmware/update).

## 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:

```c theme={null}
behaviors {
    my_macro: my_macro {
        compatible = "zmk,behavior-macro";
        #binding-cells = <0>;
        bindings = <&kp H &kp E &kp L &kp L &kp O>;
    };
};
```

2. Assign it to a key position in a layer's `bindings` array:

```c theme={null}
&my_macro
```

3. Build and flash the new firmware.

<Note>
  Macro sequences are compiled into the firmware. Once flashed, the macro itself cannot be edited from a configurator — only which key it sits on. To update the sequence, edit the source and reflash.
</Note>

For the full macro behavior reference, including wait times, tap-then-hold, and parameter macros, see the [ZMK Macros documentation](https://zmk.dev/docs/behaviors/macros).

## 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](https://zmk.dev/docs) 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 your own firmware](/firmware/build-your-own).
3. Download the build and flash `minimalpad_with_studio.uf2`. See [Update the firmware](/firmware/update).

<Note>
  Keys you changed and saved from a configurator keep that setting after you flash, even if you change them in the keymap file. Change those keys in the configurator instead. A dial you changed in Studio for Mac keeps that setting too; choose **As it came** or **Same as Default** there to use the keymap file's dial again.
</Note>