QMK Firmware

https://docs.qmk.fm
Admin
QMK Firmware is an open-source community project developing firmware and tools for custom mechanical...
Tokens:362,653
Snippets:4,563
Trust Score:9.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run QMK Setup

Source: https://docs.qmk.fm/newbs_getting_started

Execute this command after installing QMK MSYS to complete the setup process. It is recommended to answer 'y' to all prompts for a standard installation.

```shell
qmk setup
```

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

### Implement keyboard_pre_init_user for Hardware Setup

Source: https://docs.qmk.fm/custom_quantum_functions

Initialize hardware pins early in the startup process, before USB is active. This example sets specific GPIO pins as output for LEDs.

```c
void keyboard_pre_init_user(void) {
  // Call the keyboard pre init code.

  // Set our LED pins as output
  gpio_set_pin_output(B0);
  gpio_set_pin_output(B1);
  gpio_set_pin_output(B2);
  gpio_set_pin_output(B3);
  gpio_set_pin_output(B4);
}
```

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

### Install QMK CLI with Help

Source: https://docs.qmk.fm/cli

Installs the QMK CLI and displays help options for the bootstrapper script.

```bash
curl -fsSL https://install.qmk.fm | sh -s -- --help
```

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

### Example Build Command

Source: https://docs.qmk.fm/feature_userspace

An example of building a keymap named 'jack', which will include the `/users/jack/` folder and its contents.

```bash
make planck:jack

```

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

### Leader Key Sequence with Audio Feedback

Source: https://docs.qmk.fm/features/leader_key

This example demonstrates how to play specific songs when a leader key sequence starts, succeeds, or fails. It requires the AUDIO_ENABLE option to be configured.

```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
}
```

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

### Install QMK CLI

Source: https://docs.qmk.fm/cli

Installs the QMK CLI and necessary dependencies using the recommended bootstrapper script.

```bash
curl -fsSL https://install.qmk.fm | sh
```

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

### Start Local Documentation Server

Source: https://docs.qmk.fm/cli_commands

Starts a local HTTP server for browsing and editing QMK documentation. Provides live reload capability. Requires Node.js and Yarn.

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

options:
  -h, --help       show this help message and exit
  -b, --browser    Open the docs in the default browser.
  -p, --port PORT  Port number to use.
```

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

### Example Firmware Filename

Source: https://docs.qmk.fm/newbs_flashing

An example illustrating the QMK firmware file naming convention for a specific keyboard and keymap.

```text
planck_rev5_default.hex
```

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

### Compile Firmware Example (Layout Directory)

Source: https://docs.qmk.fm/cli_commands

Example demonstrating how to compile firmware from within a layout directory. This shows the command execution and the expected output indicating the compilation process.

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

```

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

### Keymap README Example

Source: https://docs.qmk.fm/documentation_templates

Example of a keymap README file, including an image link and a descriptive text.

```markdown
# Default Clueboard Layout

This is the default layout that comes flashed on every Clueboard. For the most
part it's a straightforward and easy to follow layout. The only unusual key is
the key in the upper left, which sends Escape normally, but Grave when any of
the Ctrl, Alt, or GUI modifiers are held down.
```

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

### Keyboard README Example

Source: https://docs.qmk.fm/documentation_templates

Example of a keyboard README file for the Planck keyboard, including hardware details, build, and flashing instructions.

```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
```

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

### Compile Firmware Example (Keyboard Directory)

Source: https://docs.qmk.fm/cli_commands

Example demonstrating how to compile firmware from within a keyboard's directory. This shows the command execution and the expected output indicating the compilation process.

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

```

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

```

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

```

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

### Page Opening Example

Source: https://docs.qmk.fm/documentation_best_practices

A typical documentation page should start with an H1 heading and a single paragraph description. Keep headings concise to avoid issues with the Table of Contents.

```markdown
# My Page Title

This page covers my super cool feature. You can use this feature to make coffee, squeeze fresh oj, and have an egg mcmuffin and hashbrowns delivered from your local macca's by drone.
```

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

### EEPROM Datablock Example

Source: https://docs.qmk.fm/feature_eeprom

An example demonstrating how to define, initialize, read, and write custom configuration data using the EEPROM datablock API.

```APIDOC
## EEPROM Datablock Example

### Configuration in `config.h`
```c
#define EECONFIG_USER_DATA_SIZE 8
```

### Keymap Implementation (`keymap.c`)
```c
#include "debug.h"
#include "timer.h"
#include "eeconfig.h"

typedef struct my_config_t {
    uint64_t data;
} my_config_t;

static my_config_t config;

void keyboard_post_init_user(void) {
    if (!eeconfig_is_user_datablock_valid()) {
        eeconfig_init_user_datablock();
    }

    eeconfig_read_user_datablock(&config, 0, sizeof(my_config_t));
}

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    if (!record->event.pressed) {
        config.data += 1;
        eeconfig_update_user_datablock(&config, 0, sizeof(my_config_t));
    }

    return true;
}

void housekeeping_task_user(void) {
    static uint32_t last_sync = 0;
    if (timer_elapsed32(last_sync) > 1000) {
        last_sync = timer_read32();

        dprintf("Config: %ld\n", config.data);
    }
}
```
```

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

### QMK Keyboard Configuration Example

Source: https://docs.qmk.fm/hardware_keyboard_guidelines

Example of conditional configuration using post_config.h based on a macro defined in config.h. This allows for device-specific adjustments, such as power consumption for iOS devices.

```c
#define IOS_DEVICE_ENABLE

```

```c
#ifndef IOS_DEVICE_ENABLE
  // USB_MAX_POWER_CONSUMPTION value for this keyboard
  #define USB_MAX_POWER_CONSUMPTION 400
#else
  // fix iPhone and iPad power adapter issue
  // iOS devices need less than 100
  #define USB_MAX_POWER_CONSUMPTION 100
#endif

#ifdef RGBLIGHT_ENABLE
  #ifndef IOS_DEVICE_ENABLE
    #define RGBLIGHT_LIMIT_VAL 200
    #define RGBLIGHT_VAL_STEP 17
  #else
    #define RGBLIGHT_LIMIT_VAL 35
    #define RGBLIGHT_VAL_STEP 4
  #endif
  #ifndef RGBLIGHT_HUE_STEP
    #define RGBLIGHT_HUE_STEP 10
  #endif
  #ifndef RGBLIGHT_SAT_STEP
    #define RGBLIGHT_SAT_STEP 17
  #endif
#endif

```

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

### Initialize ChibiOS SVN Repository

Source: https://docs.qmk.fm/chibios_upgrade_instructions

Initializes the local Git repository to track the ChibiOS SVN repository. This is a one-time setup. Ensure 'git-svn' is installed.

```bash
git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/
git remote add qmk git@github.com:qmk/ChibiOS.git
```

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

### Tap Dance: Quad Function Example Setup

Source: https://docs.qmk.fm/features/tap_dance

This snippet provides the necessary type definitions and enums for setting up a 'Quad Function Tap-Dance', allowing a single key to have up to four distinct functions based on tap and hold combinations.

```C
typedef enum {
    TD_NONE,
    TD_UNKNOWN,
    TD_SINGLE_TAP,
    TD_SINGLE_HOLD,
    TD_DOUBLE_TAP,
    TD_DOUBLE_HOLD,
    TD_DOUBLE_SINGLE_TAP, // Send two single taps
    TD_TRIPLE_TAP,
    TD_TRIPLE_HOLD
} td_state_t;

typedef struct {
    bool is_press_action;
    td_state_t state;
} td_tap_t;

// Tap dance enums
enum {
    X_CTL,
    SOME_OTHER_DANCE
};

td_state_t cur_dance(tap_dance_state_t *state);

```

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

### Install Linux udev Rules

Source: https://docs.qmk.fm/faq_build

Run this script to install the necessary udev rules for proper device communication on Linux systems. This is the recommended method for handling permissions.

```bash
util/install_udev.sh

```

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

### Planck Hand Swap Configuration Example

Source: https://docs.qmk.fm/features/swap_hands

Example `hand_swap_config` for a Planck keyboard. This configuration maps matrix positions to new column/row values for hand swapping.

```c
const keypos_t PROGMEM hand_swap_config[MATRIX_ROWS][MATRIX_COLS] = {
  {{11, 0}, {10, 0}, {9, 0}, {8, 0}, {7, 0}, {6, 0}, {5, 0}, {4, 0}, {3, 0}, {2, 0}, {1, 0}, {0, 0}},
  {{11, 1}, {10, 1}, {9, 1}, {8, 1}, {7, 1}, {6, 1}, {5, 1}, {4, 1}, {3, 1}, {2, 1}, {1, 1}, {0, 1}},
  {{11, 2}, {10, 2}, {9, 2}, {8, 2}, {7, 2}, {6, 2}, {5, 2}, {4, 2}, {3, 2}, {2, 2}, {1, 2}, {0, 2}},
  {{11, 3}, {10, 3}, {9, 3}, {8, 3}, {7, 3}, {6, 3}, {5, 3}, {4, 3}, {3, 3}, {2, 3}, {1, 3}, {0, 3}},
};
```

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

### Leader Key Sequence Example with Per-Key Timing

Source: https://docs.qmk.fm/features/leader_key

An example of a leader key sequence that benefits from per-key timing, demonstrating a triple-tap scenario.

```c
if (leader_sequence_three_keys(KC_C, KC_C, KC_C)) {
    SEND_STRING("Per key timing is great!!!");
}
```

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

### RP2040 PIO Driver Example Configuration in info.json

Source: https://docs.qmk.fm/features/ps2_mouse

Example `info.json` content specifying pins and driver for the PS/2 mouse on an RP2040 microcontroller. Note the strict requirement for clock pin to be directly after data pin.

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

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

### Enum Naming Convention Example

Source: https://docs.qmk.fm/contributing

Demonstrates the standard naming convention for enums in QMK documentation, using 'my_layers' as an example. Ensure consistency with existing documentation.

```c
enum my_layers {
  _FIRST_LAYER,
  _SECOND_LAYER
};
```

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

### Install/Upgrade QMK CLI on Linux or WSL

Source: https://docs.qmk.fm/ChangeLog/20220528

On Linux or Windows Subsystem for Linux (WSL), use pip to install or upgrade the QMK CLI. This command installs the package for the current user.

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

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

### LED Matrix Layout Example

Source: https://docs.qmk.fm/reference_info_json

Specifies the configuration for individual LEDs, including their flags and positions. This is a required setting for the LED Matrix.

```json
{"matrix": [2, 1], "x": 20, "y": 48, "flags": 2}
```

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

### Define Custom Keycodes

Source: https://docs.qmk.fm/contributing

Example of defining custom keycodes using an enum. Ensure custom keycodes start from SAFE_RANGE to avoid conflicts.

```c
enum my_keycodes {
  FIRST_LAYER = SAFE_RANGE,
  SECOND_LAYER
};
```

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

### Enumerate Drivers with pnputil

Source: https://docs.qmk.fm/driver_installation_zadig

Lists all installed driver packages on the system. Useful for verifying the 'Inf name' before deletion.

```bash
pnputil /enum-drivers
```

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

### Configure Multiple PMW33XX Sensors

Source: https://docs.qmk.fm/features/pointing_device

Example of configuring two PMW33XX sensors using `PMW33XX_CS_PINS` in `config.h` and handling their reports in `keyboard.c`. This setup allows for independent CPI settings per sensor and merging of motion data.

```c
#define PMW33XX_CS_PINS { B5, B6 }
// in keyboard.c:
#ifdef POINTING_DEVICE_ENABLE
void pointing_device_init_kb(void) {
    pmw33xx_init(1);         // index 1 is the second device.
    pmw33xx_set_cpi(0, 800); // applies to first sensor
    pmw33xx_set_cpi(1, 800); // applies to second sensor
    pointing_device_init_user();
}

// Contains report from sensor #0 already, need to merge in from sensor #1
report_mouse_t pointing_device_task_kb(report_mouse_t mouse_report) {
    pmw33xx_report_t report = pmw33xx_read_burst(1);
    if (!report.motion.b.is_lifted && report.motion.b.is_motion) {
// From quantum/pointing_device_drivers.c
#define constrain_hid(amt) ((amt) < -127 ? -127 : ((amt) > 127 ? 127 : (amt)))
        mouse_report.x = constrain_hid(mouse_report.x + report.delta_x);
        mouse_report.y = constrain_hid(mouse_report.y + report.delta_y);
    }
    return pointing_device_task_user(mouse_report);
}
#endif
```

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

### Install ARM Toolchain using xPack Manager

Source: https://docs.qmk.fm/arm_debugging

Installs the ARM embedded GCC toolchain globally using the xPack Manager. Ensure Node.js and xPack Manager are installed first.

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

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

### Preview Documentation Locally

Source: https://docs.qmk.fm/contributing

Command to run a local preview of the QMK documentation. This command should be executed from the `qmk_firmware/` directory.

```bash
qmk docs -b
```

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

### Install Pillow for QMK CLI on Windows

Source: https://docs.qmk.fm/ChangeLog/20220528

On Windows, use QMK MSYS or msys2 to install the Pillow dependency for the QMK CLI. This command ensures the necessary Python package is installed.

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

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

### GeminiPR Example: PHAPBGS

Source: https://docs.qmk.fm/features/stenography

Example of the steno stroke 'PHAPBGS' and its corresponding GeminiPR packet.

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

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

### Select a Quantum Painter Driver

Source: https://docs.qmk.fm/quantum_painter

This example shows how to select a specific driver for a display panel in rules.mk. Replace '...' with the appropriate driver name from the documentation.

```make
QUANTUM_PAINTER_DRIVERS += gc9a01_spi
```

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

### GeminiPR Example: WAZ

Source: https://docs.qmk.fm/features/stenography

Example of the steno stroke 'WAZ' and its corresponding GeminiPR packet.

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

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

### QMK Keyboard Folder Structure Example

Source: https://docs.qmk.fm/hardware_keyboard_guidelines

Illustrates how QMK uses sub-folders for organization and managing different revisions of a keyboard. A `keyboard.json` file indicates a compilable keyboard.

```text
qmk_firmware/keyboards/top_folder/sub_1/sub_2/sub_3/sub_4
```

```text
qmk_firmware/
  keyboards/
    clueboard ← This is the organization folder, there's no `keyboard.json` file 
      60 ← This is a compilable keyboard - it has a `keyboard.json` file
      66 ← This is not a compilable keyboard - a revision must be specified 
        rev1 ← compilable: `make clueboard/66/rev1`
        rev2 ← compilable: `make clueboard/66/rev2`
        rev3 ← compilable: `make clueboard/66/rev3`
```

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

### GeminiPR Example: EUBG

Source: https://docs.qmk.fm/features/stenography

Example of the steno stroke 'EUBG' and its corresponding GeminiPR packet.

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

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

### Create QMK Userspace Files

Source: https://docs.qmk.fm/newbs_building_firmware_workflow

Run these commands to set up the basic directory structure and template files for your QMK userspace repository. This includes the GitHub Actions workflow directory, a build configuration file, and initial source files.

```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
```

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

### TX Bolt Example: PHAPBGS

Source: https://docs.qmk.fm/features/stenography

Example of the steno stroke 'PHAPBGS' and its corresponding TX Bolt packet.

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

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

### Initialize Display and Attach LVGL

Source: https://docs.qmk.fm/quantum_painter_lvgl

Example of initializing a display and attaching LVGL within the keyboard's post-initialization function. Drawing operations should occur after a successful attachment.

```c
static painter_device_t display;
void keyboard_post_init_kb(void) {
    display = qp_make_.......;         // Create the display
    qp_init(display, QP_ROTATION_0);   // Initialise the display

    if (qp_lvgl_attach(display)) {     // Attach LVGL to the display
        ...Your code to draw           // Run LVGL specific code to draw
    }
}
```

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

### TX Bolt Example: WAZ

Source: https://docs.qmk.fm/features/stenography

Example of the steno stroke 'WAZ' and its corresponding TX Bolt packet.

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

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

### TX Bolt Example: EUBG

Source: https://docs.qmk.fm/features/stenography

Example of the steno stroke 'EUBG' and its corresponding TX Bolt packet.

```text
EUBG = 01110000 10101000
```

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

### Example QMK CLI Subcommand: Hello World

Source: https://docs.qmk.fm/cli_development

This Python script demonstrates a basic QMK CLI subcommand using the MILC framework. It defines a command-line argument for a name and logs a greeting.

```python
"""QMK Python Hello World

This is an example QMK CLI script.
"""
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)

```

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

### Import Keyboard Firmware using qmk import-kbfirmware

Source: https://docs.qmk.fm/cli_commands

Creates a new keyboard based on a Keyboard Firmware Builder export. Note that support is basic, and 'qmk new-keyboard' might be a better alternative.

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

```text
Ψ 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.
```

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

### Build Process Output

Source: https://docs.qmk.fm/faq_misc

This output shows the successful linking of an ELF file and the creation of a .hex file for flashing. It also displays the size of the generated firmware file.

```text
Linking: .build/planck_rev4_cbbrowne.elf                                                            [OK]
Creating load file for Flash: .build/planck_rev4_cbbrowne.hex                                       [OK]

Size after:
   text    data     bss     dec     hex filename
      0   22396       0   22396    577c planck_rev4_cbbrowne.hex
```

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

### Complex Docstring Example

Source: https://docs.qmk.fm/coding_conventions_python

An example of a more detailed docstring that includes a blank line after the initial description, followed by additional explanatory text.

```python
def my_awesome_function():
    """
    Return the number of seconds since 1970 Jan 1 00:00 UTC.

    This function always returns an integer number of seconds.
    """
    return int(time.time())
```

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

### EEPROM Datablock Example: User Configuration

Source: https://docs.qmk.fm/feature_eeprom

Demonstrates how to define, initialize, read, and update a custom configuration structure stored in the user datablock of EEPROM. Includes validation check on initialization and periodic updates.

```c
#include "debug.h"
#include "timer.h"
#include "eeconfig.h"

typedef struct my_config_t {
    uint64_t data;
} my_config_t;

static my_config_t config;

void keyboard_post_init_user(void) {
    if (!eeconfig_is_user_datablock_valid()) {
        eeconfig_init_user_datablock();
    }

    eeconfig_read_user_datablock(&config, 0, sizeof(my_config_t));
}

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
    if (!record->event.pressed) {
        config.data += 1;
        eeconfig_update_user_datablock(&config, 0, sizeof(my_config_t));
    }

    return true;
}

void housekeeping_task_user(void) {
    static uint32_t last_sync = 0;
    if (timer_elapsed32(last_sync) > 1000) {
        last_sync = timer_read32();

        dprintf("Config: %ld\n", config.data);
    }
}
```

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

### Flashing with QMK CLI (UF2 Bootloader)

Source: https://docs.qmk.fm/flashing

Use the QMK CLI to flash firmware when the device is in UF2 bootloader mode. Ensure the correct keyboard and keymap are specified.

```bash
qmk flash --keyboard handwired/onekey/bluepill_uf2boot --keymap default
```

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

### Install OpenOCD using xPack Manager

Source: https://docs.qmk.fm/arm_debugging

Installs OpenOCD globally using the xPack Manager. OpenOCD is necessary for SWD access from GDB.

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

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

### Create a New Keyboard with qmk new-keyboard

Source: https://docs.qmk.fm/cli_commands

Use this command to create a new keyboard project from templates. Arguments not provided will prompt for input. The user.name from .gitconfig is used as a default username if -u is not passed.

```bash
qmk new-keyboard [-kb KEYBOARD] [-t {atmega32u4,STM32F303,etc}] [-l {60_ansi,75_iso,etc}] -u USERNAME
```

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

### Example of SRC and LIB_SRC Usage

Source: https://docs.qmk.fm/config_options

Demonstrates how to use SRC and LIB_SRC to control the order of file compilation and linking. Files in LIB_SRC are linked after those in SRC.

```makefile
SRC += a.c
LIB_SRC += lib_b.c
SRC += c.c
LIB_SRC += lib_d.c
```

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

### Read Entire Configuration

Source: https://docs.qmk.fm/cli_configuration

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

```bash
qmk config
```

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

### Generate a New QMK Keyboard Project

Source: https://docs.qmk.fm/porting_your_keyboard_to_qmk

Use this command to create a new keyboard directory with default configuration files. 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!
```

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

### Show Build Options

Source: https://docs.qmk.fm/getting_started_make_guide

Displays the build options configured in the `rules.mk` file. Provides insight into compiler flags and build settings.

```bash
make show_build_options
```

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

### Generate QMK Documentation

Source: https://docs.qmk.fm/cli_commands

Generates QMK documentation for production. Use the -s flag to serve the static site. Requires node and yarn.

```bash
usage: qmk generate-docs [-h] [-s]

options:
  -h, --help   show this help message and exit
  -s, --serve  Serves the generated docs once built.
```

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

### Install Windows Build Tools using xPack Manager

Source: https://docs.qmk.fm/arm_debugging

Installs essential Windows build tools globally using the xPack Manager. This is required for Windows users.

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

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

### Select Generic RP2040 Board Configuration

Source: https://docs.qmk.fm/platformdev_rp2040

Add this line to your keyboard's rules.mk file to select the generic RP2040 board configuration, which requires manual configuration of pins and drivers.

```makefile
BOARD = GENERIC_RP_RP2040
```

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

### List Bootloaders

Source: https://docs.qmk.fm/cli_commands

List available bootloaders for the `qmk flash` command.

```bash
qmk flash -b
```

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

### Navigate to QMK Firmware Directory

Source: https://docs.qmk.fm/cli_commands

Opens a new shell session within the `qmk_firmware` directory. Typing 'exit' in the new shell will return you to the parent shell.

```bash
qmk cd
```

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

### Implement keyboard_post_init_user for RGB Underglow

Source: https://docs.qmk.fm/custom_quantum_functions

This function runs after all other keyboard initialization. It's useful for setting up features like RGB underglow configuration, including enabling, setting color, and mode, without saving settings to EEPROM.

```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
}
```

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

### Start Left Scrolling

Source: https://docs.qmk.fm/features/oled_driver

Initiates leftward scrolling for the entire display. Returns true if scrolling was already active or successfully started. Note: Display content cannot be modified while scrolling.

```c
bool oled_scroll_left(void);
```

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

### Start Right Scrolling

Source: https://docs.qmk.fm/features/oled_driver

Initiates rightward scrolling for the entire display. Returns true if scrolling was already active or successfully started. Note: Display content cannot be modified while scrolling.

```c
bool oled_scroll_right(void);
```

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

### Basic QMK Flash Command

Source: https://docs.qmk.fm/newbs_flashing

Run this command to compile and flash your configured keyboard firmware.

```shell
qmk flash
```

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

### Start SPI Transaction

Source: https://docs.qmk.fm/drivers/spi

Starts an SPI transaction with a specified slave device. Configures endianness, SPI mode, and clock divisor. Returns false if parameters are invalid or the peripheral is in use.

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

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

### Custom get_flow_tap_term() Example

Source: https://docs.qmk.fm/tap_hold

Customize Flow Tap timeouts per key or based on the previous key. This example sets shorter timeouts for specific control keys and disables Flow Tap otherwise.

```c
uint16_t get_flow_tap_term(uint16_t keycode, keyrecord_t* record, 
                           uint16_t prev_keycode) {
    if (is_flow_tap_key(keycode) && is_flow_tap_key(prev_keycode)) {
        switch (keycode) {
            case LCTL_T(KC_F):
            case RCTL_T(KC_H):
              return FLOW_TAP_TERM - 25;  // Short timeout on these keys.

            default:
              return FLOW_TAP_TERM;  // Longer timeout otherwise.
        }
    }
    return 0;  // Disable Flow Tap.
}
```

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

### Importing KBFirmware JSON to QMK

Source: https://docs.qmk.fm/hand_wire

Use this command to import a firmware configuration exported from the Keyboard Firmware Builder into a modern QMK environment. Ensure you have QMK installed and the `qmk` command-line tool available.

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

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

### Enable WPM System

Source: https://docs.qmk.fm/features/wpm

Add this line to your rules.mk file to enable the WPM feature.

```makefile
WPM_ENABLE = yes

```

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

### Initialize HD44780 and Display Text

Source: https://docs.qmk.fm/features/hd44780

Call `hd44780_init` in `keyboard_post_init_user` to initialize the display and `hd44780_puts_P` to print text. The `true` arguments to `hd44780_init` enable a blinking cursor.

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

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

### rgb_matrix_get_mode

Source: https://docs.qmk.fm/features/rgb_matrix

Gets the currently running effect.

```APIDOC
## rgb_matrix_get_mode

### Description
Get the currently running effect.

### Method
uint8_t

### Endpoint
N/A

### Parameters
None

### Return Value
The index of the currently running effect.
```

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

### Flashing with QMK CLI (RP2040 Bootloader)

Source: https://docs.qmk.fm/flashing

Flash firmware using the QMK CLI for RP2040-based keyboards in bootloader mode. Specify the correct keyboard and keymap for the flashing process.

```bash
qmk flash --keyboard handwired/onekey/rpi_pico --keymap default
```

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

### Basic Unicode Keycode Example

Source: https://docs.qmk.fm/features/unicode

Use the `UC(c)` keycode in your keymap to input specific Unicode characters, where 'c' is the hexadecimal code point. For example, `UC(0x40B)` outputs 'Ћ' and `UC(0x30C4)` outputs 'ツ'.

```c
UC(0x40B)  // Outputs Ћ
UC(0x30C4)  // Outputs ツ
```

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

### rgb_matrix_get_sat

Source: https://docs.qmk.fm/features/rgb_matrix

Gets the current global effect saturation.

```APIDOC
## rgb_matrix_get_sat

### Description
Get the current global effect saturation.

### Method
uint8_t

### Endpoint
N/A

### Parameters
None

### Return Value
The current saturation value, from 0 to 255.
```

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

### Initialize Git Repository and Commit Files

Source: https://docs.qmk.fm/newbs_building_firmware_workflow

Initializes a new Git repository, stages all changes, commits them with a message, sets the main branch, and adds a remote origin for pushing.

```bash
cd ~/qmk_keymap
git init
git add -A
git commit -m "Initial QMK keymap commit"
git branch -M main
git remote add origin https://github.com/gh-username/qmk_keymap.git
git push -u origin main
```

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

### rgb_matrix_get_hue

Source: https://docs.qmk.fm/features/rgb_matrix

Gets the current global effect hue.

```APIDOC
## rgb_matrix_get_hue

### Description
Get the current global effect hue.

### Method
uint8_t

### Endpoint
N/A

### Parameters
None

### Return Value
The current hue value, from 0 to 255.
```

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

### Check Environment for Build/Flash Problems

Source: https://docs.qmk.fm/cli_commands

Examine the current environment for potential QMK build or flash issues and prompt for automatic fixes.

```bash
qmk doctor
```

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

### rgb_matrix_get_val

Source: https://docs.qmk.fm/features/rgb_matrix

Gets the current global effect value (brightness).

```APIDOC
## rgb_matrix_get_val

### Description
Get the current global effect value (brightness).

### Method
uint8_t

### Endpoint
N/A

### Parameters
None

### Return Value
The current brightness value, from 0 to 255.
```

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

### Initialize and Read User Configuration

Source: https://docs.qmk.fm/feature_eeprom

Initializes the keyboard and reads user configuration from EEPROM upon startup. It populates the `user_config` structure and applies settings like RGB layer indication if enabled.

```c
void keyboard_post_init_user(void) {
  // Call the keymap level matrix init.

  // Read the user config from EEPROM
  user_config.raw = eeconfig_read_user();

  // Set default layer, if enabled
  if (user_config.rgb_layer_change) {
    rgblight_enable_noeeprom();
    rgblight_sethsv_noeeprom(HSV_CYAN);
    rgblight_mode_noeeprom(1);
  }
}
```

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

### rgb_matrix_is_enabled

Source: https://docs.qmk.fm/features/rgb_matrix

Gets the current enabled state of the RGB Matrix.

```APIDOC
## rgb_matrix_is_enabled

### Description
Get the current enabled state of RGB Matrix.

### Method
bool

### Endpoint
N/A

### Parameters
None

### Return Value
`true` if RGB Matrix is enabled.
```

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

### Westberrytech Support

Source: https://docs.qmk.fm/ChangeLog/20211127

Example of a pull request related to Westberrytech support.

```c
# Westberrytech pr (#14422)
```

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

### Print QMK Version to Console

Source: https://docs.qmk.fm/features/command

Print the running QMK version to the console by pressing the Command combination followed by `V`. This is configured via `MAGIC_KEY_VERSION` in `config.h`.

```c
#define MAGIC_KEY_VERSION V
```

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

### Checkout QMK Firmware Repository

Source: https://docs.qmk.fm/newbs_building_firmware_workflow

Checks out the main QMK firmware repository, ensuring submodules are also checked out recursively.

```yaml
uses: actions/checkout@v3
with:
  repository: qmk/qmk_firmware
  submodules: recursive
```

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

### Custom Mouse Keycode Example

Source: https://docs.qmk.fm/features/pointing_device

This example demonstrates how to create a custom keycode to simulate mouse clicks and scrolling. It sets vertical and horizontal scroll values and toggles the primary mouse button. Note that the mouse report is reset after sending, so scrolling effects are applied only once per event.

```c
case MS_SPECIAL:
    report_mouse_t currentReport = pointing_device_get_report();
    if (record->event.pressed) {
        currentReport.v = 127;
        currentReport.h = 127;
        currentReport.buttons |= MOUSE_BTN1;  // this is defined in report.h
    } else {
        currentReport.v = -127;
        currentReport.h = -127;
        currentReport.buttons &= ~MOUSE_BTN1;
    }
    pointing_device_set_report(currentReport);
    pointing_device_send();
    break;
```

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

### F405 MCU Support

Source: https://docs.qmk.fm/ChangeLog/20211127

Example of an initial pass for F405 MCU support.

```c
# Initial pass of F405 support (#14584)
```

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

### Include Quantum Painter Header

Source: https://docs.qmk.fm/quantum_painter

Include the `qp.h` header file to use any of the Quantum Painter APIs. This is a prerequisite for device initialization and drawing operations.

```c
#include <qp.h>
```

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

### HT32 MCU Support

Source: https://docs.qmk.fm/ChangeLog/20211127

Example of adding support for the HT32 MCU to the core.

```c
# Add HT32 support to core (#14388)
```

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

### Leader Key Callbacks

Source: https://docs.qmk.fm/features/leader_key

User-defined callbacks for when the leader sequence starts and ends.

```APIDOC
## `void leader_start_user(void)`

### Description
User callback, invoked when the leader sequence begins.

### Method
Callback Function

### Parameters
None

### Return Value
None

## `void leader_end_user(void)`

### Description
User callback, invoked when the leader sequence ends.

### Method
Callback Function

### Parameters
None

### Return Value
None
```

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

### Compile Clueboard 66% Firmware

Source: https://docs.qmk.fm/newbs_getting_started

An example of compiling the default keymap for a Clueboard 66% Rev3 keyboard. This demonstrates the format for the qmk compile command.

```shell
qmk compile -kb clueboard/66/rev3 -km default
```

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

### Build a Keymap using Docker

Source: https://docs.qmk.fm/getting_started_docker

Compile a specific keyboard and keymap using the Docker build script. The resulting firmware file will be saved in the QMK directory.

```bash
util/docker_build.sh <keyboard>:<keymap>
# For example: util/docker_build.sh planck/rev6:default
```
Tokens:
Raw