### Install QMK CLI and Setup Firmware

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/readme.md

Installs the QMK command-line interface and sets up the Keychron firmware repository. Ensure Python 3 is installed.

```bash
python3 -m pip install qmk
qmk setup Keychron/qmk_firmware
```

--------------------------------

### Install and Setup QMK CLI

Source: https://context7.com/keychron/qmk_firmware/llms.txt

Installs the QMK CLI tool and sets up the firmware repository. Run `qmk doctor -y` to validate your build environment and automatically fix issues.

```bash
# Install QMK CLI (Python package)
pip install qmk

# Clone the firmware repository
qmk setup                       # clones qmk/qmk_firmware and installs udev rules

# Validate the build environment; auto-fix detected problems
qmk doctor -y

# Open a shell already cd'd to the QMK home directory
qmk cd
```

--------------------------------

### Install QMK CLI with Homebrew

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli.md

Use this command to install the QMK CLI if you have Homebrew installed. It's recommended to set the QMK_HOME environment variable to specify the firmware location and then run `qmk setup` to clone the repository and configure your build environment.

```bash
brew install qmk/qmk/qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```

--------------------------------

### Keyboard Initialization Hooks

Source: https://context7.com/keychron/qmk_firmware/llms.txt

Three ordered callbacks handle setup at different firmware boot stages: before USB starts (`keyboard_pre_init_user`), mid-boot (`matrix_init_user`), and after all features are ready (`keyboard_post_init_user`).

```APIDOC
## Keyboard Initialization Hooks

Three ordered callbacks handle setup at different firmware boot stages: before USB starts (`keyboard_pre_init_user`), mid-boot (`matrix_init_user`), and after all features are ready (`keyboard_post_init_user`).

```c
// Runs before USB and most hardware — configure GPIO early
void keyboard_pre_init_user(void) {
    gpio_set_pin_output(B0);  // Status LED pin
    gpio_write_pin_low(B0);
}

// Runs after matrix init but before features — rarely needed
void matrix_init_user(void) { }

// Runs last — safest place for feature configuration
void keyboard_post_init_user(void) {
    // Start with teal underglow, breathing mode, without writing to EEPROM
    rgblight_enable_noeeprom();
    rgblight_sethsv_noeeprom(180, 255, 200);
    rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3);

    // Debug output (requires CONSOLE_ENABLE = yes in rules.mk)
    debug_enable   = true;
    debug_matrix   = false;
    debug_keyboard = false;
}
```
```

--------------------------------

### Install QMK CLI with uv

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli.md

Install and manage the QMK CLI as a uv tool. After installation, set the QMK_HOME environment variable and run `qmk setup` to clone the firmware repository and configure your build environment. Updates can be managed with `uv tool upgrade qmk`.

```bash
uv tool install qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```

--------------------------------

### Compile Firmware Example (Layout Directory)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_commands.md

Example of compiling firmware from a layout directory, specifying the target keyboard.

```bash
$ cd ~/qmk_firmware/layouts/community/60_ansi/mechmerlin-ansi
$ qmk compile -kb dz60
Ψ Compiling keymap with make dz60:mechmerlin-ansi
...
```

--------------------------------

### Keyboard README.md Template Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/documentation_templates.md

Template for a keyboard's readme.md file. Includes keyboard name, image, description, maintainer, hardware details, and build/flash commands. Use this to guide users on how to build and flash the firmware for the specific keyboard.

```markdown
# Planck

![Planck](https://i.imgur.com/q2M3uEU.jpg)

A compact 40% (12x4) ortholinear keyboard kit made and sold by OLKB and Massdrop. [More info on qmk.fm](https://qmk.fm/planck/)

* Keyboard Maintainer: [Jack Humbert](https://github.com/jackhumbert)
* Hardware Supported: Planck PCB rev1, rev2, rev3, rev4, Teensy 2.0
* Hardware Availability: [OLKB.com](https://olkb.com), [Massdrop](https://www.massdrop.com/buy/planck-mechanical-keyboard?mode=guest_open)

Make example for this keyboard (after setting up your build environment):

    make planck/rev4:default

Flashing example for this keyboard:

    make planck/rev4:default:flash

See the [build environment setup](getting_started_build_tools) and the [make instructions](getting_started_make_guide) for more information. Brand new to QMK? Start with our [Complete Newbs Guide](newbs).

## Bootloader

Enter the bootloader in 3 ways:

* **Bootmagic reset**: Hold down the key at (0,0) in the matrix (usually the top left key or Escape) and plug in the keyboard
* **Physical reset button**: Briefly press the button on the back of the PCB - some may have pads you must short instead
* **Keycode in layout**: Press the key mapped to `QK_BOOT` if it is available
```

--------------------------------

### Install QMK CLI with pip

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli.md

Manually install QMK using pip if other methods are not suitable. Ensure Python 3.9 or later is installed. Set the QMK_HOME environment variable to define the firmware location and then execute `qmk setup` to clone the repository and prepare your build environment.

```bash
python3 -m pip install qmk
export QMK_HOME='~/qmk_firmware' # Optional, set the location for `qmk_firmware`
qmk setup  # This will clone `qmk/qmk_firmware` and optionally set up your build environment
```

--------------------------------

### Compile Firmware Example (Keymap Directory)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_commands.md

Example of compiling firmware when located directly within a keymap directory.

```bash
$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
$ qmk compile
Ψ Compiling keymap with make gh60/satan:colemak
...
```

--------------------------------

### Example of Importing KBFirmware JSON

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/hand_wire.md

This example demonstrates the output after running the `qmk import-kbfirmware` command. It shows the process of importing a keyboard configuration and suggests next steps for development.

```bash
$ qmk import-kbfirmware ~/Downloads/gh62.json
Ψ Importing gh62.json.

⚠ Support here is basic - Consider using 'qmk new-keyboard' instead
Ψ Imported a new keyboard named gh62.
Ψ To start working on things, `cd` into keyboards/gh62,
Ψ or open the directory in your preferred text editor.
Ψ And build with qmk compile -kb gh62 -km default.
```

--------------------------------

### Install QMK CLI on Linux/WSL (uv)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

Installs the QMK CLI using uv, creating an isolated virtual environment. Requires uv to be installed separately.

```sh
uv tool install qmk
```

--------------------------------

### Compile Firmware Example (Optional Keymap)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_commands.md

Example of compiling firmware when specifying an optional keymap argument, useful when not in a keymap directory.

```bash
$ cd ~/qmk_firmware/keyboards/clueboard/66/rev4
$ qmk compile -km 66_iso
Ψ Compiling keymap with make clueboard/66/rev4:66_iso
...
```

--------------------------------

### Command Line Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/__capabilities.md

An example of a command-line instruction for the Teensy Loader.

```bash
teensy_loader_cli -v -mmcu=<mcu> <filename>
```

--------------------------------

### Start Local Documentation Server

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_commands.md

Starts a local HTTP server to browse and edit QMK documentation with live reload. Requires Node.js and Yarn. The `-b` flag opens the server in your default browser.

```bash
usage: qmk docs [-h] [-b] [-p PORT]
```

--------------------------------

### Install QMK CLI on Linux/WSL (pip)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

Installs the QMK CLI using pip for the current user. Ensure Python 3 and pip are installed.

```sh
python3 -m pip install --user qmk
```

--------------------------------

### Compile Firmware Example (Keyboard Directory)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_commands.md

Example of compiling firmware from within a keyboard's directory. The command automatically detects the keyboard and keymap.

```bash
$ qmk config compile.keymap=default
$ cd ~/qmk_firmware/keyboards/planck/rev6
$ qmk compile
Ψ Compiling keymap with make planck/rev6:default
...
```

--------------------------------

### Install QMK CLI on FreeBSD

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

Use this command to install the QMK CLI package on FreeBSD systems. Remember to check the post-installation instructions.

```sh
pkg install -g "py*-qmk"
```

--------------------------------

### Install QMK CLI on macOS

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

Installs the QMK CLI and dependencies using Homebrew. This command adds the QMK tap and installs the qmk formula.

```sh
brew install qmk/qmk/qmk
```

--------------------------------

### Install QMK CLI on Arch-based Linux (AUR)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

Installs the QMK CLI from the Arch User Repository (AUR) using an AUR helper like yay.

```sh
yay -S qmk-git
```

--------------------------------

### PS/2 Mouse Configuration Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/ps2_mouse.md

Example configuration for a PS/2 mouse, specifying clock and data pins, driver, and enabling mouse functionality.

```json
    "ps2": {
        "clock_pin": "GP1",
        "data_pin": "GP0",
        "driver": "vendor",
        "enabled": true,
        "mouse_enabled": true
    }
```

--------------------------------

### Example QMK CLI Subcommand: Hello World

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_development.md

A basic example of a QMK CLI subcommand using MILC. It defines a command-line argument for a name and logs a greeting. The configuration for the name can be set via arguments, qmk.ini, or defaults.

```python
வைகள் QMK Python Hello World

This is an example QMK CLI script.

```

```python
from milc import cli


@cli.argument('-n', '--name', default='World', help='Name to greet.')
@cli.subcommand('QMK Hello World.')
def hello(cli):
    """Log a friendly greeting.
    """
    cli.log.info('Hello, %s!', cli.config.hello.name)
```

--------------------------------

### Example Usage

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/leader_key.md

This example demonstrates how to use the leader key feature to play sounds upon starting, succeeding, or failing a leader sequence.

```APIDOC
## Example {#example}

This example will play the Mario "One Up" sound when you hit `QK_LEAD` to start the leader sequence. When the sequence ends, it will play "All Star" if it completes successfully or "Rick Roll" you if it fails (in other words, no sequence matched).

```c
#ifdef AUDIO_ENABLE
float leader_start_song[][2] = SONG(ONE_UP_SOUND);
float leader_succeed_song[][2] = SONG(ALL_STAR);
float leader_fail_song[][2] = SONG(RICK_ROLL);
#endif

void leader_start_user(void) {
#ifdef AUDIO_ENABLE
    PLAY_SONG(leader_start_song);
#endif
}

void leader_end_user(void) {
    bool did_leader_succeed = false;

    if (leader_sequence_one_key(KC_E)) {
        SEND_STRING(SS_LCTL(SS_LSFT("t")));
        did_leader_succeed = true;
    } else if (leader_sequence_two_keys(KC_E, KC_D)) {
        SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c"));
        did_leader_succeed = true;
    }

#ifdef AUDIO_ENABLE
    if (did_leader_succeed) {
        PLAY_SONG(leader_succeed_song);
    } else {
        PLAY_SONG(leader_fail_song);
    }
#endif
}
```
```

--------------------------------

### Proton-C DAC Audio Configuration Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/audio.md

Example configuration for the Proton-C board, which has a built-in piezo wired to A4+A5. This setup uses both pins for audio output.

```c
#define AUDIO_PIN A5
#define AUDIO_PIN_ALT A4
#define AUDIO_PIN_ALT_AS_NEGATIVE
```

--------------------------------

### Run QMK Setup

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

Execute this command in your terminal or QMK MSYS to initialize the QMK build environment. It's generally recommended to answer 'y' to all prompts.

```sh
qmk setup
```

--------------------------------

### Clone QMK Firmware Repository

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/getting_started_docker.md

Clone the QMK firmware repository and its submodules to get started.

```bash
git clone --recurse-submodules https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
```

--------------------------------

### Initialize Git SVN for ChibiOS

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/chibios_upgrade_instructions.md

Initializes Git SVN for ChibiOS. This is a one-time setup and may require installing the `git-svn` package.

```bash
git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/
```

```bash
git remote add qmk git@github.com:qmk/ChibiOS.git
```

--------------------------------

### Create QMK Project Structure and Files

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_building_firmware_workflow.md

Use these commands to set up the necessary directory structure and initial template files for your QMK keymap project.

```bash
mkdir -p ~/qmk_keymap/.github/workflows
touch ~/qmk_keymap/.github/workflows/build.yml
touch ~/qmk_keymap/config.h
echo "SRC += source.c" > ~/qmk_keymap/rules.mk
echo "#include QMK_KEYBOARD_H" > ~/qmk_keymap/source.c
```

--------------------------------

### Initialize and Draw Surface

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/quantum_painter.md

Example of initializing an RGB565 surface and setting it up for drawing. The `qp_init` function is called with the surface device and rotation.

```c
static painter_device_t my_surface;
static uint8_t my_framebuffer[SURFACE_REQUIRED_BUFFER_BYTE_SIZE(240, 80, 16)]; // Allocate a buffer for a 16bpp 240x80 RGB565 display
void keyboard_post_init_kb(void) {
    my_surface = qp_rgb565_make_surface(240, 80, my_framebuffer);
    qp_init(my_surface, QP_ROTATION_0);
    keyboard_post_init_user();
}
```

--------------------------------

### Software Timers Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/ref_functions.md

Read timer values and check elapsed time. Use timer_read() to get the current timer value and timer_elapsed() to check if a duration has passed.

```c
static uint16_t key_timer;
key_timer = timer_read();

if (timer_elapsed(key_timer) < 100) {
  // do something if less than 100ms have passed
} else {
  // do something if 100ms or more have passed
}
```

--------------------------------

### Custom Keycode for MIDI CC Message

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/midi.md

Example implementation of a custom keycode in `process_record_user` to send MIDI Control Change (CC) messages. This is useful for emulating MIDI controllers and requires advanced MIDI setup.

```c
#include QMK_KEYBOARD_H

extern MidiDevice midi_device;

// MIDI CC codes for generic on/off switches (80, 81, 82, 83)
// Off: 0-63
// On:  64-127

#define MIDI_CC_OFF 0
#define MIDI_CC_ON  127

enum custom_keycodes {
    MIDI_CC80 = SAFE_RANGE,
};

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    switch (keycode) {
        case MIDI_CC80:
            if (record->event.pressed) {
                midi_send_cc(&midi_device, midi_config.channel, 80, MIDI_CC_ON);
            } else {
                midi_send_cc(&midi_device, midi_config.channel, 80, MIDI_CC_OFF);
            }
            return true;
    }
    return true;
};

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    LAYOUT(
        // ...
        MIDI_CC80,
        // ...
    )
};
```

--------------------------------

### Previewing Documentation Changes

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/contributing.md

Run this command from the qmk_firmware/ folder to preview your documentation changes locally. It will typically open a web server in your browser.

```bash
qmk docs -b
```

--------------------------------

### Leader Key Sequence with Audio Feedback

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/leader_key.md

This example demonstrates how to use the leader key feature to play specific audio cues. It plays a 'One Up' sound when the leader sequence starts, 'All Star' on successful completion, and 'Rick Roll' on failure. Ensure AUDIO_ENABLE is defined for sound playback.

```c
#ifdef AUDIO_ENABLE
float leader_start_song[][2] = SONG(ONE_UP_SOUND);
float leader_succeed_song[][2] = SONG(ALL_STAR);
float leader_fail_song[][2] = SONG(RICK_ROLL);
#endif

void leader_start_user(void) {
#ifdef AUDIO_ENABLE
    PLAY_SONG(leader_start_song);
#endif
}

void leader_end_user(void) {
    bool did_leader_succeed = false;

    if (leader_sequence_one_key(KC_E)) {
        SEND_STRING(SS_LCTL(SS_LSFT("t")));
        did_leader_succeed = true;
    } else if (leader_sequence_two_keys(KC_E, KC_D)) {
        SEND_STRING(SS_LGUI("r") "cmd\n" SS_LCTL("c"));
        did_leader_succeed = true;
    }

#ifdef AUDIO_ENABLE
    if (did_leader_succeed) {
        PLAY_SONG(leader_succeed_song);
    } else {
        PLAY_SONG(leader_fail_song);
    }
#endif
}
```

--------------------------------

### Linux/WSL Git Installation Commands

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_building_firmware_workflow.md

Commands to install Git on various Linux distributions and WSL. Ensure Git is installed if not already present.

```bash
sudo apt install -y git
```

```bash
sudo yum -y install git
```

```bash
sudo pacman --needed --noconfirm -S git
```

```bash
sudo xbps-install -y git
```

```bash
sudo eopkg -y install git
```

```bash
sudo equo install dev-vcs/git
```

```bash
sudo emerge dev-vcs/git
```

--------------------------------

### Initialize and Draw Image

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/quantum_painter.md

Example of initializing an image handle and drawing it on keyboard post-initialization.

```c
// Draw an image on the bottom-right of the 240x320 display on initialisation
static painter_image_handle_t my_image;
void keyboard_post_init_kb(void) {
```

--------------------------------

### Install ARM GCC Toolchain using xPack

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/arm_debugging.md

Installs the ARM GCC toolchain globally using the xPack package manager. Ensure Node.js and npm are installed first.

```bash
xpm install --global @xpack-dev-tools/arm-none-eabi-gcc
```

--------------------------------

### QMK Compile Output Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

This output indicates a successful firmware compilation and creation of the .hex file for flashing.

```sh
Linking: .build/clueboard_66_rev3_default.elf                                                       [OK]
Creating load file for flashing: .build/clueboard_66_rev3_default.hex                               [OK]
Copying clueboard_66_rev3_default.hex to qmk_firmware folder                                        [OK]
Checking file size of clueboard_66_rev3_default.hex                                                 [OK]
 * The firmware size is fine - 26356/28672 (2316 bytes free)
```

--------------------------------

### GeminiPR Examples

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/stenography.md

Examples of steno strokes and their corresponding GeminiPR packet representations.

```text
- EUBG    = 10000000 00000000 00000000 00001100 00101000 00000000
```

```text
- WAZ     = 10000000 00000010 00100000 00000000 00000000 00000001
```

```text
- PHAPBGS = 10000000 00000101 00100000 00000000 01101010 00000000
```

--------------------------------

### Build Keychron Firmware using Make

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/readme.md

Alternative method to build firmware using the 'make' command. Specify the keyboard, keymap, and optionally the action (e.g., flash).

```bash
make keychron/q1_he/ansi_encoder:keychron
```

```bash
make keychron/k8_pro/ansi/rgb:keychron
```

```bash
make keychron/v1_max/ansi_encoder:keychron:flash
```

--------------------------------

### SPI Transaction Start

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/drivers/spi.md

Starts an SPI transaction with a specified slave device and configuration.

```APIDOC
## spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor)

### Description
Start an SPI transaction.

### Method
bool

### Endpoint
spi_start

### Parameters
#### Arguments
- **slavePin** (pin_t) - The GPIO pin connected to the desired device's `SS` line.
- **lsbFirst** (bool) - Determines the endianness of the transmission. If `true`, the least significant bit of each byte is sent first.
- **mode** (uint8_t) - The SPI mode to use:

  |Mode|Clock Polarity      |Clock Phase            |
  |----|--------------------|-----------------------|
  |`0` |Leading edge rising |Sample on leading edge |
  |`1` |Leading edge rising |Sample on trailing edge|
  |`2` |Leading edge falling|Sample on leading edge |
  |`3` |Leading edge falling|Sample on trailing edge|
- **divisor** (uint16_t) - The SPI clock divisor, will be rounded up to the nearest power of two. This number can be calculated by dividing the MCU's clock speed by the desired SPI clock speed. For example, an MCU running at 8 MHz wanting to talk to an SPI device at 4 MHz would set the divisor to `2`.

### Return Value
`true` if the operation was successful, otherwise `false` if the supplied parameters are invalid or the SPI peripheral is already in use.
```

--------------------------------

### Basic QMK Firmware Flash

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_flashing.md

Run this command to compile and flash your configured keyboard firmware. Ensure your keyboard and keymap are set up in your build environment.

```bash
qmk flash
```

--------------------------------

### TX Bolt Examples

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/stenography.md

Examples of steno strokes and their corresponding TX Bolt packet representations.

```text
- EUBG    = 01110000 10101000
```

```text
- WAZ     = 00010000 01000010 11001000
```

```text
- PHAPBGS = 00101000 01000010 10101100 11000010
```

--------------------------------

### Build QMK Firmware for Keychron K5 Max

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/k5_max/readme.md

Use these make commands to build the firmware for different layouts (ANSI, ISO, JIS) and RGB/white backlighting options for the Keychron K5 Max. Ensure your build environment is set up correctly.

```bash
make keychron/k5_max/ansi/rgb:keychron
```

```bash
make keychron/k5_max/ansi/white:keychron
```

```bash
make keychron/k5_max/iso/rgb:keychron
```

```bash
make keychron/k5_max/iso/white:keychron
```

```bash
make keychron/k5_max/jis/rgb:keychron
```

```bash
make keychron/k5_max/jis/white:keychron
```

--------------------------------

### Install Pillow on Windows

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/ChangeLog/20220528.md

Run these commands in QMK MSYS or msys2 on Windows to install or upgrade Pillow and QMK.

```shell
pacman --needed --noconfirm --disable-download-timeout -S mingw-w64-x86_64-python-pillow
python3 -m pip install --upgrade qmk
```

--------------------------------

### Initialize HD44780 Display and Print "Hello, world!"

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/hd44780.md

Initializes the HD44780 display with a blinking cursor and prints "Hello, world!". This should be called once during keyboard initialization.

```c
void keyboard_post_init_user(void) {
    hd44780_init(true, true); // Show blinking cursor
    hd44780_puts_P(PSTR("Hello, world!\n"));
}
```

--------------------------------

### List Available Bootloaders

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_commands.md

List all available bootloaders that can be used with the `qmk flash` command.

```bash
qmk flash -b
```

--------------------------------

### Minimal Printf Usage Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/squeezing_avr.md

Examples of `sprintf` and `snprintf` usage that would require the standard `printf` implementation, not the minimal one.

```c
sprintf(wpm_str, "%03d", get_current_wpm());
snprintf(keylog_str, sizeof(keylog_str), "%dx%d, k%2d : %c");
```

--------------------------------

### Build Keychron K3 Max Firmware

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/k3_max/readme.md

Use these make commands to build firmware for different layouts (ANSI, ISO, JIS) and RGB/white backlighting configurations. Ensure your QMK build environment is set up.

```bash
make keychron/k3_max/ansi/rgb:keychron
```

```bash
make keychron/k3_max/ansi/white:keychron
```

```bash
make keychron/k3_max/iso/rgb:keychron
```

```bash
make keychron/k3_max/iso/white:keychron
```

```bash
make keychron/k3_max/jis/rgb:keychron
```

```bash
make keychron/k3_max/jis/white:keychron
```

--------------------------------

### Color Constants and Examples

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/features/rgblight.md

Predefined RGB and HSV color constants for common colors, and example usage of color setting functions.

```APIDOC
## Color Constants

These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions.

### RGB Constants
`RGB_AZURE`, `RGB_BLACK`/`RGB_OFF`, `RGB_BLUE`, `RGB_CHARTREUSE`, `RGB_CORAL`, `RGB_CYAN`, `RGB_GOLD`, `RGB_GOLDENROD`, `RGB_GREEN`, `RGB_MAGENTA`, `RGB_ORANGE`, `RGB_PINK`, `RGB_PURPLE`, `RGB_RED`, `RGB_SPRINGGREEN`, `RGB_TEAL`, `RGB_TURQUOISE`, `RGB_WHITE`, `RGB_YELLOW`

### HSV Constants
`HSV_AZURE`, `HSV_BLACK`/`HSV_OFF`, `HSV_BLUE`, `HSV_CHARTREUSE`, `HSV_CORAL`, `HSV_CYAN`, `HSV_GOLD`, `HSV_GOLDENROD`, `HSV_GREEN`, `HSV_MAGENTA`, `HSV_ORANGE`, `HSV_PINK`, `HSV_PURPLE`, `HSV_RED`, `HSV_SPRINGGREEN`, `HSV_TEAL`, `HSV_TURQUOISE`, `HSV_WHITE`, `HSV_YELLOW`

These constants are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h).

## Example Usage

```c
rgblight_setrgb(RGB_ORANGE);
rgblight_sethsv_noeeprom(HSV_GREEN);
rgblight_setrgb_at(RGB_GOLD, 3);
rgblight_sethsv_range(HSV_WHITE, 0, 6);
```
```

--------------------------------

### Build Firmware for Keychron Q1v1

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/q1v1/readme.md

Use these make commands to build firmware for various Keychron Q1v1 configurations. Ensure your build environment is set up correctly.

```bash
make keychron/q1v1/ansi:default
```

```bash
make keychron/q1v1/ansi_encoder:default
```

```bash
make keychron/q1v1/iso:default
```

```bash
make keychron/q1v1/iso_encoder:default
```

--------------------------------

### Build Keychron Q60 Max Firmware

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/q60_max/readme.md

Use this command to create the firmware file for the Keychron Q60 Max keyboard. Ensure your build environment is set up correctly.

```bash
make keychron/q60_max/ansi/rgb:keychron
```

--------------------------------

### Install OpenOCD using xPack

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/arm_debugging.md

Installs OpenOCD globally using the xPack package manager. OpenOCD is required for SWD communication with GDB.

```bash
xpm install --global @xpack-dev-tools/openocd
```

--------------------------------

### AVRDUDE Output Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/isp_flashing_guide.md

This is an example of successful output from avrdude after flashing a device. It confirms initialization, reading, writing, and verification of the flash memory.

```text
avrdude: AVR device initialized and ready to accept instructions

Reading | ################################################## | 100% 0.00s

avrdude: Device signature = 0x1e9587 (probably m32u4)
avrdude: NOTE: "flash" memory has been specified, an erase cycle will be performed
         To disable this feature, specify the -D option.
avrdude: erasing chip
avrdude: reading input file "Caterina-Micro.hex"
avrdude: writing flash (32730 bytes):

Writing | ################################################## | 100% 11.58s

avrdude: 32730 bytes of flash written
avrdude: verifying flash memory against Caterina-Micro.hex:
avrdude: load data flash data from input file Caterina-Micro.hex:
avrdude: input file Caterina-Micro.hex contains 32730 bytes
avrdude: reading on-chip flash data:

Reading | ################################################## | 100% 10.33s

avrdude: verifying ...
avrdude: 32730 bytes of flash verified

avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)

avrdude done.  Thank you.
```

--------------------------------

### Build Firmware for Keychron Q1v2

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/q1v2/readme.md

Use these make commands to build firmware for different layouts of the Keychron Q1v2. Ensure your build environment is set up correctly.

```bash
make keychron/q1v2/ansi:keychron
```

```bash
make keychron/q1v2/ansi_encoder:keychron
```

```bash
make keychron/q1v2/iso:keychron
```

```bash
make keychron/q1v2/iso_encoder:keychron
```

```bash
make keychron/q1v2/jis:keychron
```

```bash
make keychron/q1v2/jis_encoder:keychron
```

--------------------------------

### Import KBFirmware JSON to QMK

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/hand_wire.md

Use this command to import a configuration exported from the Keyboard Firmware Builder into a modern QMK Firmware environment. This is a basic import and may require further setup.

```bash
qmk import-kbfirmware /path/to/export.json
```

--------------------------------

### Generate New QMK Keyboard Project

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/porting_your_keyboard_to_qmk.md

Use this command to create a new keyboard directory and bootstrap the QMK project. It prompts for keyboard name, attribution, base layout, and microcontroller details.

```bash
$ qmk new-keyboard
Ψ Generating a new QMK keyboard directory

Ψ Name Your Keyboard Project
Ψ For more information, see:
https://docs.qmk.fm/hardware_keyboard_guidelines#naming-your-keyboard-project
Keyboard Name? mycoolkeeb
Ψ Attribution
Ψ Used for maintainer, copyright, etc.
Your GitHub Username? [jsmith] 
Ψ More Attribution
Ψ Used for maintainer, copyright, etc.
Your Real Name? [John Smith] 
Ψ Pick Base Layout
Ψ As a starting point, one of the common layouts can be used to
bootstrap the process
Default Layout?
    1. 60_abnt2
    ...
    65. none of the above
Please enter your choice: [65] 
Ψ What Powers Your Project
Ψ Is your board using a separate development board, such as a Pro Micro,
or is the microcontroller integrated onto the PCB?

For more information, see:
https://docs.qmk.fm/compatible_microcontrollers
Using a Development Board? [y/n] y
Ψ Select Development Board
Ψ For more information, see:
https://docs.qmk.fm/compatible_microcontrollers
Development Board?
    1. bit_c_pro
    ...
    14. promicro
    ...
    18. svlinky
Please enter your choice: [14] 
Ψ Created a new keyboard called mycoolkeeb.
Ψ Build Command: qmk compile -kb mycoolkeeb -km default.
Ψ Project Location: /Users/jsmith/qmk_firmware/keyboards/mycoolkeeb.
Ψ Now update the config files to match the hardware!

```

--------------------------------

### Start SPI Transaction

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/drivers/spi.md

Starts an SPI transaction with a specified slave device. Ensure the slavePin, lsbFirst, mode, and divisor parameters are valid.

```c
bool spi_start(pin_t slavePin, bool lsbFirst, uint8_t mode, uint16_t divisor);
```

--------------------------------

### Build Keychron Q5 Firmware

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/q5/readme.md

Use these make commands to build firmware for different Keychron Q5 layouts. Ensure your build environment is set up correctly.

```bash
make keychron/q5/ansi:keychron
```

```bash
make keychron/q5/ansi_encoder:keychron
```

```bash
make keychron/q5/iso:keychron
```

```bash
make keychron/q5/iso_encoder:keychron
```

--------------------------------

### Install Windows Build Tools using xPack

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/arm_debugging.md

Installs essential Windows build tools globally via xPack. This is required for Windows users.

```bash
xpm install --global @gnu-mcu-eclipse/windows-build-tools
```

--------------------------------

### Build Keychron Q0 Max Firmware

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/q0_max/readme.md

Use this command to create the firmware file for the Keychron Q0 Max. Ensure your build environment is set up correctly.

```bash
make keychron/q0_max/encoder:keychron
```

--------------------------------

### ST-Flash Write Output Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/isp_flashing_guide.md

This is an example of the expected output when successfully writing the bootloader using st-flash. It indicates the flash memory is being erased and written.

```text
st-flash 1.7.0
2022-03-08T12:16:30 INFO common.c: F1xx Medium-density: 20 KiB SRAM, 64 KiB flash in at least 1 KiB pages.
file generic_boot20_pc13.bin md5 checksum: 333c30605e739ce9bedee5999fdaf81b, stlink checksum: 0x0008e534
2022-03-08T12:16:30 INFO common.c: Attempting to write 7172 (0x1c04) bytes to stm32 address: 134217728 (0x8000000)
2022-03-08T12:16:30 INFO common.c: Flash page at addr: 0x08000000 erased
2022-03-08T12:16:30 INFO common.c: Flash page at addr: 0x08000400 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08000800 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08000c00 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001000 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001400 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001800 erased
2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001c00 erased
2022-03-08T12:16:31 INFO common.c: Finished erasing 8 pages of 1024 (0x400) bytes
2022-03-08T12:16:31 INFO common.c: Starting Flash write for VL/F0/F3/F1_XL
2022-03-08T12:16:31 INFO flash_loader.c: Successfully loaded flash loader in sram
2022-03-08T12:16:31 INFO flash_loader.c: Clear DFSR
  8/  8 pages written
2022-03-08T12:16:31 INFO common.c: Starting verification of write complete
2022-03-08T12:16:31 INFO common.c: Flash written and verified! jolly good!
2022-03-08T12:16:31 WARN common.c: NRST is not connected
```

--------------------------------

### Build Keychron Q60 Firmware

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/q60/readme.md

Use this command to create the firmware for the Keychron Q60 keyboard. Ensure your build environment is set up correctly.

```bash
make keychron/q60/ansi:keychron
```

--------------------------------

### Build Firmware for Keychron K1 Max

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/k1_max/readme.md

Use these make commands to build firmware for various layouts (ANSI, ISO, JIS) and RGB configurations (RGB, white). Ensure your build environment is set up correctly.

```bash
make keychron/k1_max/ansi/rgb:keychron
```

```bash
make keychron/k1_max/ansi/white:keychron
```

```bash
make keychron/k1_max/iso/rgb:keychron
```

```bash
make keychron/k1_max/iso/white:keychron
```

```bash
make keychron/k1_max/jis/rgb:keychron
```

```bash
make keychron/k1_max/jis/white:keychron
```

--------------------------------

### Generate Compilation Database Example

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_commands.md

Example of generating a compilation database. This process involves cleaning the build, gathering build instructions, and writing the database file.

```bash
$ cd ~/qmk_firmware/keyboards/gh60/satan/keymaps/colemak
$ qmk compile --compiledb
Ψ Making clean
Ψ Gathering build instructions from make ........
Ψ Found 63 compile commands
Ψ Writing build database to /Users/you/src/qmk_firmware/compile_commands.json
Ψ Compiling keymap with make ........
... build log continues ...
```

--------------------------------

### Install QMK CLI on Windows (MSYS2)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

Installs the QMK CLI and necessary dependencies using pacman within the MSYS2 environment. Ensure you are in a MinGW 64-bit terminal.

```sh
pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-python-qmk
```

--------------------------------

### Keyboard Initialization Hooks

Source: https://context7.com/keychron/qmk_firmware/llms.txt

Use these callbacks to configure hardware and features at different stages of the firmware boot process. keyboard_pre_init_user is for early hardware setup, matrix_init_user is rarely needed, and keyboard_post_init_user is the safest for feature configuration.

```c
// Runs before USB and most hardware — configure GPIO early
void keyboard_pre_init_user(void) {
    gpio_set_pin_output(B0);  // Status LED pin
    gpio_write_pin_low(B0);
}

// Runs after matrix init but before features — rarely needed
void matrix_init_user(void) { }
```

```c
// Runs last — safest place for feature configuration
void keyboard_post_init_user(void) {
    // Start with teal underglow, breathing mode, without writing to EEPROM
    rgblight_enable_noeeprom();
    rgblight_sethsv_noeeprom(180, 255, 200);
    rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3);

    // Debug output (requires CONSOLE_ENABLE = yes in rules.mk)
    debug_enable   = true;
    debug_matrix   = false;
    debug_keyboard = false;
}
```

--------------------------------

### Install QMK CLI on Arch-based Linux (Official Repo)

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/newbs_getting_started.md

Installs the QMK CLI from the official Arch Linux repositories. Note that some optional dependencies might be marked as required.

```sh
sudo pacman -S qmk
```

--------------------------------

### Read Entire Configuration

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/cli_configuration.md

Display the entire current QMK CLI configuration. This is useful for reviewing all set values.

```bash
qmk config
```

--------------------------------

### Example of Modified MAX3421E Pin Definitions

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/lib/usbhost/USB_Host_Shield_2.0/README.md

This example shows how to reconfigure the MAX3421E pins if the SS pin is rerouted to pin 7. Ensure the corresponding jumper on the shield is modified.

```C++
typedef MAX3421e<P7, P9> MAX3421E;
```

--------------------------------

### Implement Keyboard Post Initialization

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/docs/custom_quantum_functions.md

Implement `keyboard_post_init_user` to customize features after all initialization is complete. This is suitable for tasks like configuring RGB underglow.

```c
void keyboard_post_init_user(void) {
  // Call the post init code.
  rgblight_enable_noeeprom(); // enables Rgb, without saving settings
  rgblight_sethsv_noeeprom(180, 255, 255); // sets the color to teal/cyan without saving
  rgblight_mode_noeeprom(RGBLIGHT_MODE_BREATHING + 3); // sets mode to Fast breathing without saving
}
```

--------------------------------

### Build Firmware for Keychron Q65 Max

Source: https://github.com/keychron/qmk_firmware/blob/2025q3/keyboards/keychron/q65_max/readme.md

Use this command to create firmware for the Keychron Q65 Max keyboard. Ensure your build environment is set up correctly.

```bash
make keychron/q65_max/ansi_encoder:keychron
```