mkbd65/vial-qmk
Watch
1
0
Fork
You've already forked vial-qmk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[docs] Organize driver & feature docs into subfolders (#23848)

Browse source 
Co-authored-by: Nick Brassel <nick@tzarc.org>
This commit is contained in:
Ryan 2024-06-02 12:42:24 +10:00 • committed by GitHub
commit 78a0adfbb4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
97 changed files with 282 additions and 285 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/ChangeLog/20210828.md
View file

@ -10,11 +10,11 @@ It is also now possible to define combos that have keys overlapping with other c
### Key Overrides ([#11422](https://github.com/qmk/qmk_firmware/pull/11422)) {#key-overrides}
QMK now has a new feature: [key overrides](../feature_key_overrides). This feature allows for overriding the output of key combinations involving modifiers. As an example, pressing <kbd>Shift+2</kbd> normally results in an <kbd>@</kbd> on US-ANSI keyboard layouts -- the new key overrides allow for adding similar functionality, but for any <kbd>modifier + key</kbd> press.
QMK now has a new feature: [key overrides](../features/key_overrides). This feature allows for overriding the output of key combinations involving modifiers. As an example, pressing <kbd>Shift+2</kbd> normally results in an <kbd>@</kbd> on US-ANSI keyboard layouts -- the new key overrides allow for adding similar functionality, but for any <kbd>modifier + key</kbd> press.
To illustrate, it's now possible to use the key overrides feature to translate <kbd>Shift + Backspace</kbd> into <kbd>Delete</kbd> -- an often-requested example of where this functionality comes in handy.
There's far more to describe that what lives in this changelog, so head over to the [key overrides documentation](../feature_key_overrides) for more examples and info.
There's far more to describe that what lives in this changelog, so head over to the [key overrides documentation](../features/key_overrides) for more examples and info.
### Digitizer support ([#12851](https://github.com/qmk/qmk_firmware/pull/12851))

4
docs/ChangeLog/20211127.md
View file

@ -31,7 +31,7 @@ QMK now has core-supplied support for the following pointing device peripherals:
| `POINTING_DEVICE_DRIVER = pimoroni_trackball` | Pimoroni Trackball |
| `POINTING_DEVICE_DRIVER = pmw3360` | PMW 3360 |
See the new documentation for the [Pointing Device](../feature_pointing_device) feature for more information on specific configuration for each driver.
See the new documentation for the [Pointing Device](../features/pointing_device) feature for more information on specific configuration for each driver.
### Dynamic Tapping Term ([#11036](https://github.com/qmk/qmk_firmware/pull/11036)) {#dynamic-tapping-term}
@ -116,7 +116,7 @@ Related to the previous section -- RGB Matrix modes have now been made to be opt
Most keyboards keep their original functionality, but over time the QMK maintainers have found that removal of animations ends up being the quickest way to free up space... and some keyboards have had animations such as reactive effects disabled by default in order to still fit within the flash space available.
The full list of configurables to turn specific animations back on can be found at on the [RGB Matrix documentation](../feature_rgb_matrix#rgb-matrix-effects) page.
The full list of configurables to turn specific animations back on can be found at on the [RGB Matrix documentation](../features/rgb_matrix#rgb-matrix-effects) page.
### OLED task refactoring ([#14864](https://github.com/qmk/qmk_firmware/pull/14864)) {#oled-task-refactor}

2
docs/ChangeLog/20220226.md
View file

@ -12,7 +12,7 @@ Something something *Lets go gamers!*
Pointing devices can now be shared across a split keyboard with support for a single pointing device or a pointing device on each side.
See the [Pointing Device](../feature_pointing_device) documentation for further configuration options.
See the [Pointing Device](../features/pointing_device) documentation for further configuration options.
## Changes Requiring User Action {#changes-requiring-user-action}

4
docs/ChangeLog/20220528.md
View file

@ -8,7 +8,7 @@ This is a new feature that allows for capslock-like functionality that turns its
For instance, if you wish to type "QMK" without holding shift the entire time, you can either tap both left and right shift, or double-tap shift, to turn on _Caps Word_ -- then type `qmk` (lowercase) without holding shift. Once you hit any key other than `a`--`z`, `0`--`9`, `-`, `_`, delete, or backspace, this will go back to normal typing!
There are other activation mechanisms as well as configurable options like timeout and the like -- see the [Caps Word documentation](../feature_caps_word) for more information.
There are other activation mechanisms as well as configurable options like timeout and the like -- see the [Caps Word documentation](../features/caps_word) for more information.
### Quantum Painter ([#10174](https://github.com/qmk/qmk_firmware/pull/10174)) {#quantum-painter}
@ -26,7 +26,7 @@ Quantum Painter is not supported on AVR due to complexity and size constraints.
### Encoder Mapping ([#13286](https://github.com/qmk/qmk_firmware/pull/13286)) {#encoder-mapping}
One of the long-standing complaints with Encoders is that there has been no easy way to configure them in user keymaps. [#13286](https://github.com/qmk/qmk_firmware/pull/13286) added support for [Encoder Mapping](../feature_encoders#encoder-map), which allows users to define encoder functionality in a similar way to their normal keymap.
One of the long-standing complaints with Encoders is that there has been no easy way to configure them in user keymaps. [#13286](https://github.com/qmk/qmk_firmware/pull/13286) added support for [Encoder Mapping](../features/encoders#encoder-map), which allows users to define encoder functionality in a similar way to their normal keymap.
::: warning
This is not yet supported by QMK Configurator. It is also unlikely to ever be supported by VIA.

2
docs/ChangeLog/20220827.md
View file

@ -83,7 +83,7 @@ The now-EOL kbfirmware allowed people who aren't set up with QMK the ability to
QMK has had the ability to write to internal MCU flash in order to emulate EEPROM for some time now, but it was only limited to a small number of MCUs. The base HAL used by QMK for a large number of ARM devices provides a "proper" embedded MCU flash driver, so _@tzarc_ decoupled the wear-leveling algorithm from the old flash writing code, improved it, wrote some tests, and enabled its use for a much larger number of other devices... including RP2040's XIP flash, and external SPI NOR Flash.
See the [EEPROM Driver](../eeprom_driver) documentation for more information.
See the [EEPROM Driver](../drivers/eeprom) documentation for more information.
### Pointing Device Improvements ([#16371](https://github.com/qmk/qmk_firmware/pull/16371), [#17111](https://github.com/qmk/qmk_firmware/pull/17111), [#17176](https://github.com/qmk/qmk_firmware/pull/17176), [#17482](https://github.com/qmk/qmk_firmware/pull/17482), [#17776](https://github.com/qmk/qmk_firmware/pull/17776), [#17613](https://github.com/qmk/qmk_firmware/pull/17613)) {#pointing-device-improvements}

4
docs/ChangeLog/20221126.md
View file

@ -4,7 +4,7 @@
### Autocorrect ([#15699](https://github.com/qmk/qmk_firmware/pull/15699)) {#autocorrect}
_@getreuer_ in their infinite wisdom decided that autocorrect was a feature needed by QMK. As is customary, _@drashna_ adapted it to core and got it into a state that everyone else can use it. See [Feature: Autocorrect](../feature_autocorrect) for more ifnormation (grin).
_@getreuer_ in their infinite wisdom decided that autocorrect was a feature needed by QMK. As is customary, _@drashna_ adapted it to core and got it into a state that everyone else can use it. See [Feature: Autocorrect](../features/autocorrect) for more ifnormation (grin).
## Changes Requiring User Action {#changes-requiring-user-action}
@ -132,7 +132,7 @@ The equivalent transformations should be done for LED Matrix boards.
### Unicode mode refactoring {#unicode-mode-renaming}
Unicode modes were renamed in order to prevent collision with equivalent keycodes. The available values for `UNICODE_SELECTED_MODES` changed -- see [Feature: Unicode](../feature_unicode#setting-the-input-mode) for the new list of values and how to configure them.
Unicode modes were renamed in order to prevent collision with equivalent keycodes. The available values for `UNICODE_SELECTED_MODES` changed -- see [Feature: Unicode](../features/unicode#setting-the-input-mode) for the new list of values and how to configure them.
## Notable core changes {#notable-core}

2
docs/ChangeLog/20230226.md
View file

@ -106,7 +106,7 @@ void leader_end_user(void) {
}
```
For more information please see the [Leader Key documentation](../feature_leader_key).
For more information please see the [Leader Key documentation](../features/leader_key).
### Updated Keyboard Codebases {#updated-keyboard-codebases}

4
docs/ChangeLog/20230528.md
View file

@ -24,7 +24,7 @@ Of note for keyboard designers:
A new pair of keys has been added to QMK -- namely `QK_REPEAT_KEY` and `QK_ALT_REPEAT_KEY` (shortened: `QK_REP`/`QK_AREP`). These allow you to repeat the last key pressed, or in the case of the alternate key, press the "opposite" of the last key. For example, if you press `KC_LEFT`, pressing `QK_REPEAT_KEY` afterwards repeats `KC_LEFT`, but pressing `QK_ALT_REPEAT_KEY` instead sends `KC_RIGHT`.
The full list of default alternate keys is available on the [Repeat Key](../feature_repeat_key) documentation.
The full list of default alternate keys is available on the [Repeat Key](../features/repeat_key) documentation.
To enable these keys, in your keymap's `rules.mk`, add:
@ -93,7 +93,7 @@ Additionally, this ensures that builds on QMK Configurator produce some sort of
The "classic" OLED driver picked up support for additional sizes of OLED displays, support for the SH1107 controller, and SPI-based OLED support.
Other configurable items are available and can be found on the [OLED Driver page](../feature_oled_driver).
Other configurable items are available and can be found on the [OLED Driver page](../features/oled_driver).
## Full changelist {#full-changelist}

2
docs/ChangeLog/20230827.md
View file

@ -42,7 +42,7 @@ AVR sees minimal (if any) benefit -- `double` was interpreted as `float` on AVR
### Remove encoder in-matrix workaround code ([#20389](https://github.com/qmk/qmk_firmware/pull/20389)) {#remove-encoder-in-matrix-workaround-code}
Some keyboards "hacked" encoder support into spare slots in the key matrix in order to interoperate with VIA. This workaround is no longer necessary, and the code has been removed. If you have a keyboard that uses this workaround, you will need to update your keymap to use the new [Encoder Map](../feature_encoders#encoder-map) API instead.
Some keyboards "hacked" encoder support into spare slots in the key matrix in order to interoperate with VIA. This workaround is no longer necessary, and the code has been removed. If you have a keyboard that uses this workaround, you will need to update your keymap to use the new [Encoder Map](../features/encoders#encoder-map) API instead.
### Unicodemap keycodes rename ([#21092](https://github.com/qmk/qmk_firmware/pull/21092)) {#unicodemap-keycodes-rename}

2
docs/ChangeLog/20240225.md
View file

@ -120,7 +120,7 @@ In some cases, accidental automatic activation of the mouse layer made it diffic
### DIP Switch Mapping ([#22543](https://github.com/qmk/qmk_firmware/pull/22543)) {#dip-switch-map}
Much like Encoder Mapping, DIP Switch Mapping allows for specifying a table of actions to execute when a DIP switch state changes. See the [DIP Switch Documentation](../feature_dip_switch#dip-switch-map) for more information.
Much like Encoder Mapping, DIP Switch Mapping allows for specifying a table of actions to execute when a DIP switch state changes. See the [DIP Switch Documentation](../features/dip_switch#dip-switch-map) for more information.
```c
#if defined(DIP_SWITCH_MAP_ENABLE)

112
docs/_sidebar.json
View file

@ -103,45 +103,45 @@
{
"text": "Advanced Keycodes",
"items": [
{ "text": "Command", "link": "/feature_command" },
{ "text": "Dynamic Macros", "link": "/feature_dynamic_macros" },
{ "text": "Grave Escape", "link": "/feature_grave_esc" },
{ "text": "Leader Key", "link": "/feature_leader_key" },
{ "text": "Command", "link": "/features/command" },
{ "text": "Dynamic Macros", "link": "/features/dynamic_macros" },
{ "text": "Grave Escape", "link": "/features/grave_esc" },
{ "text": "Leader Key", "link": "/features/leader_key" },
{ "text": "Mod-Tap", "link": "/mod_tap" },
{ "text": "Macros", "link": "/feature_macros" },
{ "text": "Mouse Keys", "link": "/feature_mouse_keys" },
{ "text": "Programmable Button", "link": "/feature_programmable_button" },
{ "text": "Repeat Key", "link": "/feature_repeat_key" },
{ "text": "Space Cadet Shift", "link": "/feature_space_cadet" },
{ "text": "Mouse Keys", "link": "/features/mouse_keys" },
{ "text": "Programmable Button", "link": "/features/programmable_button" },
{ "text": "Repeat Key", "link": "/features/repeat_key" },
{ "text": "Space Cadet Shift", "link": "/features/space_cadet" },
{ "text": "US ANSI Shifted Keys", "link": "/keycodes_us_ansi_shifted" }
]
},
{
"text": "Software Features",
"items": [
{ "text": "Auto Shift", "link": "/feature_auto_shift" },
{ "text": "Autocorrect", "link": "/feature_autocorrect" },
{ "text": "Caps Word", "link": "/feature_caps_word" },
{ "text": "Combos", "link": "/feature_combo" },
{ "text": "Auto Shift", "link": "/features/auto_shift" },
{ "text": "Autocorrect", "link": "/features/autocorrect" },
{ "text": "Caps Word", "link": "/features/caps_word" },
{ "text": "Combos", "link": "/features/combo" },
{ "text": "Debounce API", "link": "/feature_debounce_type" },
{ "text": "Digitizer", "link": "/feature_digitizer" },
{ "text": "Digitizer", "link": "/features/digitizer" },
{ "text": "EEPROM", "link": "/feature_eeprom" },
{ "text": "Key Lock", "link": "/feature_key_lock" },
{ "text": "Key Overrides", "link": "/feature_key_overrides" },
{ "text": "Key Lock", "link": "/features/key_lock" },
{ "text": "Key Overrides", "link": "/features/key_overrides" },
{ "text": "Layers", "link": "/feature_layers" },
{ "text": "One Shot Keys", "link": "/one_shot_keys" },
{ "text": "OS Detection", "link": "/feature_os_detection" },
{ "text": "Raw HID", "link": "/feature_rawhid" },
{ "text": "Secure", "link": "/feature_secure" },
{ "text": "Send String", "link": "/feature_send_string" },
{ "text": "Sequencer", "link": "/feature_sequencer" },
{ "text": "Swap Hands", "link": "/feature_swap_hands" },
{ "text": "Tap Dance", "link": "/feature_tap_dance" },
{ "text": "OS Detection", "link": "/features/os_detection" },
{ "text": "Raw HID", "link": "/features/rawhid" },
{ "text": "Secure", "link": "/features/secure" },
{ "text": "Send String", "link": "/features/send_string" },
{ "text": "Sequencer", "link": "/features/sequencer" },
{ "text": "Swap Hands", "link": "/features/swap_hands" },
{ "text": "Tap Dance", "link": "/features/tap_dance" },
{ "text": "Tap-Hold Configuration", "link": "/tap_hold" },
{ "text": "Tri Layer", "link": "/feature_tri_layer" },
{ "text": "Unicode", "link": "/feature_unicode" },
{ "text": "Tri Layer", "link": "/features/tri_layer" },
{ "text": "Unicode", "link": "/features/unicode" },
{ "text": "Userspace", "link": "/feature_userspace" },
{ "text": "WPM Calculation", "link": "/feature_wpm" }
{ "text": "WPM Calculation", "link": "/features/wpm" }
]
},
{
@ -157,35 +157,35 @@
{ "text": "Quantum Painter LVGL Integration", "link": "/quantum_painter_lvgl" }
]
},
{ "text": "HD44780 LCD Driver", "link": "/feature_hd44780" },
{ "text": "ST7565 LCD Driver", "link": "/feature_st7565" },
{ "text": "OLED Driver", "link": "/feature_oled_driver" }
{ "text": "HD44780 LCD Driver", "link": "/features/hd44780" },
{ "text": "ST7565 LCD Driver", "link": "/features/st7565" },
{ "text": "OLED Driver", "link": "/features/oled_driver" }
]
},
{
"text": "Lighting",
"items": [
{ "text": "Backlight", "link": "/feature_backlight" },
{ "text": "LED Matrix", "link": "/feature_led_matrix" },
{ "text": "RGB Lighting", "link": "/feature_rgblight" },
{ "text": "RGB Matrix", "link": "/feature_rgb_matrix" }
{ "text": "Backlight", "link": "/features/backlight" },
{ "text": "LED Matrix", "link": "/features/led_matrix" },
{ "text": "RGB Lighting", "link": "/features/rgblight" },
{ "text": "RGB Matrix", "link": "/features/rgb_matrix" }
]
},
{ "text": "Audio", "link": "/feature_audio" },
{ "text": "Bluetooth", "link": "/feature_bluetooth" },
{ "text": "Bootmagic Lite", "link": "/feature_bootmagic" },
{ "text": "Audio", "link": "/features/audio" },
{ "text": "Bluetooth", "link": "/features/bluetooth" },
{ "text": "Bootmagic Lite", "link": "/features/bootmagic" },
{ "text": "Converters", "link": "/feature_converters" },
{ "text": "Custom Matrix", "link": "/custom_matrix" },
{ "text": "DIP Switch", "link": "/feature_dip_switch" },
{ "text": "Encoders", "link": "/feature_encoders" },
{ "text": "Haptic Feedback", "link": "/feature_haptic_feedback" },
{ "text": "Joystick", "link": "/feature_joystick" },
{ "text": "LED Indicators", "link": "/feature_led_indicators" },
{ "text": "MIDI", "link": "/feature_midi" },
{ "text": "Pointing Device", "link": "/feature_pointing_device" },
{ "text": "PS/2 Mouse", "link": "/feature_ps2_mouse" },
{ "text": "Split Keyboard", "link": "/feature_split_keyboard" },
{ "text": "Stenography", "link": "/feature_stenography" }
{ "text": "DIP Switch", "link": "/features/dip_switch" },
{ "text": "Encoders", "link": "/features/encoders" },
{ "text": "Haptic Feedback", "link": "/features/haptic_feedback" },
{ "text": "Joystick", "link": "/features/joystick" },
{ "text": "LED Indicators", "link": "/features/led_indicators" },
{ "text": "MIDI", "link": "/features/midi" },
{ "text": "Pointing Device", "link": "/features/pointing_device" },
{ "text": "PS/2 Mouse", "link": "/features/ps2_mouse" },
{ "text": "Split Keyboard", "link": "/features/split_keyboard" },
{ "text": "Stenography", "link": "/features/stenography" }
]
},
{
@ -226,19 +226,19 @@
"text": "Drivers",
"link": "hardware_drivers",
"items": [
{ "text": "ADC Driver", "link": "/adc_driver" },
{ "text": "APA102 Driver", "link": "/apa102_driver" },
{ "text": "Audio Driver", "link": "/audio_driver" },
{ "text": "I2C Driver", "link": "/i2c_driver" },
{ "text": "SPI Driver", "link": "/spi_driver" },
{ "text": "WS2812 Driver", "link": "/ws2812_driver" },
{ "text": "EEPROM Driver", "link": "/eeprom_driver" },
{ "text": "Flash Driver", "link": "/flash_driver" },
{ "text": "'serial' Driver", "link": "/serial_driver" },
{ "text": "UART Driver", "link": "/uart_driver" }
{ "text": "ADC Driver", "link": "/drivers/adc" },
{ "text": "APA102 Driver", "link": "/drivers/apa102" },
{ "text": "Audio Driver", "link": "/drivers/audio" },
{ "text": "EEPROM Driver", "link": "/drivers/eeprom" },
{ "text": "Flash Driver", "link": "/drivers/flash" },
{ "text": "I2C Driver", "link": "/drivers/i2c" },
{ "text": "'serial' Driver", "link": "/drivers/serial" },
{ "text": "SPI Driver", "link": "/drivers/spi" },
{ "text": "UART Driver", "link": "/drivers/uart" },
{ "text": "WS2812 Driver", "link": "/drivers/ws2812" }
]
},
{ "text": "GPIO Controls", "link": "/gpio_control" },
{ "text": "GPIO Controls", "link": "/drivers/gpio" },
{ "text": "Keyboard Guidelines", "link": "/hardware_keyboard_guidelines" }
]
},

2
docs/cli_commands.md
View file

@ -749,7 +749,7 @@ options:
## `qmk generate-rgb-breathe-table`
This command generates a lookup table (LUT) header file for the [RGB Lighting](feature_rgblight) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`.
This command generates a lookup table (LUT) header file for the [RGB Lighting](features/rgblight) feature's breathing animation. Place this file in your keyboard or keymap directory as `rgblight_breathe_table.h` to override the default LUT in `quantum/rgblight/`.
**Usage**:

12
docs/config_options.md
View file

@ -207,7 +207,7 @@ If you define these options you will enable the associated feature, which may in
* `#define TAP_HOLD_CAPS_DELAY 80`
* Sets the delay for Tap Hold keys (`LT`, `MT`) when using `KC_CAPS_LOCK` keycode, as this has some special handling on MacOS. The value is in milliseconds, and defaults to 80 ms if not defined. For macOS, you may want to set this to 200 or higher.
* `#define KEY_OVERRIDE_REPEAT_DELAY 500`
* Sets the key repeat interval for [key overrides](feature_key_overrides).
* Sets the key repeat interval for [key overrides](features/key_overrides).
* `#define LEGACY_MAGIC_HANDLING`
* Enables magic configuration handling for advanced keycodes (such as Mod Tap and Layer Tap)
@ -217,14 +217,14 @@ If you define these options you will enable the associated feature, which may in
* `#define WS2812_DI_PIN D7`
* pin the DI on the WS2812 is hooked-up to
* `#define RGBLIGHT_LAYERS`
* Lets you define [lighting layers](feature_rgblight#lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
* Lets you define [lighting layers](features/rgblight#lighting-layers) that can be toggled on or off. Great for showing the current keyboard layer or caps lock state.
* `#define RGBLIGHT_MAX_LAYERS`
* Defaults to 8. Can be expanded up to 32 if more [lighting layers](feature_rgblight#lighting-layers) are needed.
* Defaults to 8. Can be expanded up to 32 if more [lighting layers](features/rgblight#lighting-layers) are needed.
* Note: Increasing the maximum will increase the firmware size and slow sync on split keyboards.
* `#define RGBLIGHT_LAYER_BLINK`
* Adds ability to [blink](feature_rgblight#lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
* Adds ability to [blink](features/rgblight#lighting-layer-blink) a lighting layer for a specified number of milliseconds (e.g. to acknowledge an action).
* `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF`
* If defined, then [lighting layers](feature_rgblight#overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off.
* If defined, then [lighting layers](features/rgblight#overriding-rgb-lighting-onoff-status) will be shown even if RGB Light is off.
* `#define RGBLIGHT_LED_COUNT 12`
* number of LEDs
* `#define RGBLIGHT_SPLIT`
@ -358,7 +358,7 @@ There are a few different ways to set handedness for split keyboards (listed in
* `#define SPLIT_TRANSACTION_IDS_KB .....`
* `#define SPLIT_TRANSACTION_IDS_USER .....`
* Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](feature_split_keyboard#custom-data-sync) for more information.
* Allows for custom data sync with the slave when using the QMK-provided split transport. See [custom data sync between sides](features/split_keyboard#custom-data-sync) for more information.
# The `rules.mk` File

2
docs/custom_quantum_functions.md
View file

@ -206,7 +206,7 @@ Similar to `matrix_scan_*`, these are called as often as the MCU can handle. To
### Example `void housekeeping_task_user(void)` implementation
This example will show you how to use `void housekeeping_task_user(void)` to turn off [RGB Light](feature_rgblight). For RGB Matrix, the [builtin](feature_rgb_matrix#additional-configh-options) `RGB_MATRIX_TIMEOUT` should be used.
This example will show you how to use `void housekeeping_task_user(void)` to turn off [RGB Light](features/rgblight). For RGB Matrix, the [builtin](features/rgb_matrix#additional-configh-options) `RGB_MATRIX_TIMEOUT` should be used.
First, add the following lines to your keymap's `config.h`:

2
docs/documentation_best_practices.md
View file

@ -69,4 +69,4 @@ This page describes my cool feature. You can use my cool feature to make coffee
|KC_SUGAR||Order Sugar|
```
Place your documentation into `docs/feature_<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.json`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.
Place your documentation into `docs/features/<my_cool_feature>.md`, and add that file to the appropriate place in `docs/_sidebar.json`. If you have added any keycodes be sure to add them to `docs/keycodes.md` with a link back to your feature page.

4
docs/driver_installation_zadig.md
View file

@ -8,8 +8,8 @@ We recommend the use of the [Zadig](https://zadig.akeo.ie/) utility. If you have
## Installation
Put your keyboard into bootloader mode, either by hitting the `QK_BOOT` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic Lite](feature_bootmagic) docs for more details). Some boards use [Command](feature_command) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in.
Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](feature_bootmagic) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure.
Put your keyboard into bootloader mode, either by hitting the `QK_BOOT` keycode (which may be on a different layer), or by pressing the reset switch that's usually located on the underside of the board. If your keyboard has neither, try holding Escape or Space+`B` as you plug it in (see the [Bootmagic Lite](features/bootmagic) docs for more details). Some boards use [Command](features/command) instead of Bootmagic; in this case, you can enter bootloader mode by hitting Left Shift+Right Shift+`B` or Left Shift+Right Shift+Escape at any point while the keyboard is plugged in.
Some keyboards may have specific instructions for entering the bootloader. For example, the [Bootmagic Lite](features/bootmagic) key (default: Escape) might be on a different key, e.g. Left Control; or the magic combination for Command (default: Left Shift+Right Shift) might require you to hold something else, e.g. Left Control+Right Control. Refer to the board's README file if you are unsure.
To put a device in bootloader mode with USBaspLoader, tap the `RESET` button while holding down the `BOOT` button.
Alternatively, hold `BOOT` while inserting the USB cable.

173
docs/drivers/adc.md Normal file
View file

@ -0,0 +1,173 @@
# ADC Driver
QMK can leverage the Analog-to-Digital Converter (ADC) on supported MCUs to measure voltages on certain pins. This can be useful for implementing things such as battery level indicators for Bluetooth keyboards, or volume controls using a potentiometer, as opposed to a [rotary encoder](../features/encoders).
This driver currently supports both AVR and a limited selection of ARM devices. The values returned are 10-bit integers (0-1023) mapped between 0V and VCC (usually 5V or 3.3V for AVR, 3.3V only for ARM), however on ARM there is more flexibility in control of operation through `#define`s if you need more precision.
## Usage
To use this driver, add the following to your `rules.mk`:
```make
ANALOG_DRIVER_REQUIRED = yes
```
Then place this include at the top of your code:
```c
#include "analog.h"
```
## Channels
### AVR
|Channel|AT90USB64/128|ATmega16/32U4|ATmega32A|ATmega328/P|
|-------|-------------|-------------|---------|----------|
|0 |`F0` |`F0` |`A0` |`C0` |
|1 |`F1` |`F1` |`A1` |`C1` |
|2 |`F2` | |`A2` |`C2` |
|3 |`F3` | |`A3` |`C3` |
|4 |`F4` |`F4` |`A4` |`C4` |
|5 |`F5` |`F5` |`A5` |`C5` |
|6 |`F6` |`F6` |`A6` |* |
|7 |`F7` |`F7` |`A7` |* |
|8 | |`D4` | | |
|9 | |`D6` | | |
|10 | |`D7` | | |
|11 | |`B4` | | |
|12 | |`B5` | | |
|13 | |`B6` | | |
<sup>\* The ATmega328/P possesses two extra ADC channels; however, they are not present on the DIP pinout, and are not shared with GPIO pins. You can use `adc_read()` directly to gain access to these.</sup>
### ARM
#### STM32
Note that some of these pins are doubled-up on ADCs with the same channel. This is because the pins can be used for either ADC.
Also note that the F0 and F3 use different numbering schemes. The F0 has a single ADC and the channels are 0-indexed, whereas the F3 has 4 ADCs and the channels are 1-indexed. This is because the F0 uses the `ADCv1` implementation of the ADC, whereas the F3 uses the `ADCv3` implementation.
|ADC|Channel|STM32F0xx|STM32F1xx|STM32F3xx|STM32F4xx|
|---|-------|---------|---------|---------|---------|
|1 |0 |`A0` |`A0` | |`A0` |
|1 |1 |`A1` |`A1` |`A0` |`A1` |
|1 |2 |`A2` |`A2` |`A1` |`A2` |
|1 |3 |`A3` |`A3` |`A2` |`A3` |
|1 |4 |`A4` |`A4` |`A3` |`A4` |
|1 |5 |`A5` |`A5` |`F4` |`A5` |
|1 |6 |`A6` |`A6` |`C0` |`A6` |
|1 |7 |`A7` |`A7` |`C1` |`A7` |
|1 |8 |`B0` |`B0` |`C2` |`B0` |
|1 |9 |`B1` |`B1` |`C3` |`B1` |
|1 |10 |`C0` |`C0` |`F2` |`C0` |
|1 |11 |`C1` |`C1` | |`C1` |
|1 |12 |`C2` |`C2` | |`C2` |
|1 |13 |`C3` |`C3` | |`C3` |
|1 |14 |`C4` |`C4` | |`C4` |
|1 |15 |`C5` |`C5` | |`C5` |
|1 |16 | | | | |
|2 |0 | |`A0`¹ | |`A0`² |
|2 |1 | |`A1`¹ |`A4` |`A1`² |
|2 |2 | |`A2`¹ |`A5` |`A2`² |
|2 |3 | |`A3`¹ |`A6` |`A3`² |
|2 |4 | |`A4`¹ |`A7` |`A4`² |
|2 |5 | |`A5`¹ |`C4` |`A5`² |
|2 |6 | |`A6`¹ |`C0` |`A6`² |
|2 |7 | |`A7`¹ |`C1` |`A7`² |
|2 |8 | |`B0`¹ |`C2` |`B0`² |
|2 |9 | |`B1`¹ |`C3` |`B1`² |
|2 |10 | |`C0`¹ |`F2` |`C0`² |
|2 |11 | |`C1`¹ |`C5` |`C1`² |
|2 |12 | |`C2`¹ |`B2` |`C2`² |
|2 |13 | |`C3`¹ | |`C3`² |
|2 |14 | |`C4`¹ | |`C4`² |
|2 |15 | |`C5`¹ | |`C5`² |
|2 |16 | | | | |
|3 |0 | |`A0`¹ | |`A0`² |
|3 |1 | |`A1`¹ |`B1` |`A1`² |
|3 |2 | |`A2`¹ |`E9` |`A2`² |
|3 |3 | |`A3`¹ |`E13` |`A3`² |
|3 |4 | |`F6`¹ | |`F6`² |
|3 |5 | |`F7`¹ |`B13` |`F7`² |
|3 |6 | |`F8`¹ |`E8` |`F8`² |
|3 |7 | |`F9`¹ |`D10` |`F9`² |
|3 |8 | |`F10`¹ |`D11` |`F10`² |
|3 |9 | | |`D12` |`F3`² |
|3 |10 | |`C0`¹ |`D13` |`C0`² |
|3 |11 | |`C1`¹ |`D14` |`C1`² |
|3 |12 | |`C2`¹ |`B0` |`C2`² |
|3 |13 | |`C3`¹ |`E7` |`C3`² |
|3 |14 | | |`E10` |`F4`² |
|3 |15 | | |`E11` |`F5`² |
|3 |16 | | |`E12` | |
|4 |1 | | |`E14` | |
|4 |2 | | |`E15` | |
|4 |3 | | |`B12` | |
|4 |4 | | |`B14` | |
|4 |5 | | |`B15` | |
|4 |6 | | |`E8` | |
|4 |7 | | |`D10` | |
|4 |8 | | |`D11` | |
|4 |9 | | |`D12` | |
|4 |10 | | |`D13` | |
|4 |11 | | |`D14` | |
|4 |12 | | |`D8` | |
|4 |13 | | |`D9` | |
|4 |14 | | | | |
|4 |15 | | | | |
|4 |16 | | | | |
<sup>¹ As of ChibiOS 20.3.4, the ADC driver for STM32F1xx devices supports only ADC1, therefore any configurations involving ADC2 or ADC3 cannot actually be used. In particular, pins `F6`…`F10`, which are present at least on some STM32F103x[C-G] devices, cannot be used as ADC inputs because of this driver limitation.</sup>
<sup>² Not all STM32F4xx devices have ADC2 and/or ADC3, therefore some configurations shown in this table may be unavailable; in particular, pins `F4`…`F10` cannot be used as ADC inputs on devices which do not have ADC3. Check the device datasheet to confirm which pin functions are supported.</sup>
#### RP2040
RP2040 has only a single ADC (`ADCD1` in ChibiOS); in the QMK API the index for that ADC is 0.
|Channel|Pin |
|-------|-------------------|
|0 |`GP26` |
|1 |`GP27` |
|2 |`GP28` |
|3 |`GP29` |
|4 |Temperature sensor*|
<sup>* The temperature sensor is disabled by default and needs to be enabled by the RP2040-specific function: `adcRPEnableTS(&ADCD1)`. The ADC must be initialized before calling that function; an easy way to ensure that is to perform a dummy conversion.</sup>
## Functions
### AVR
|Function |Description |
|----------------------------|-------------------------------------------------------------------------------------------------------------------|
|`analogReference(mode)` |Sets the analog voltage reference source. Must be one of `ADC_REF_EXTERNAL`, `ADC_REF_POWER` or `ADC_REF_INTERNAL`.|
|`analogReadPin(pin)` |Reads the value from the specified pin, eg. `F6` for ADC6 on the ATmega32U4. |
|`pinToMux(pin)` |Translates a given pin to a mux value. If an unsupported pin is given, returns the mux value for "0V (GND)". |
|`adc_read(mux)` |Reads the value from the ADC according to the specified mux. See your MCU's datasheet for more information. |
### ARM
|Function |Description |
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`analogReadPin(pin)` |Reads the value from the specified pin, eg. `A0` for channel 0 on the STM32F0 and ADC1 channel 1 on the STM32F3. Note that if a pin can be used for multiple ADCs, it will pick the lower numbered ADC for this function. eg. `C0` will be channel 6 of ADC 1 when it could be used for ADC 2 as well.|
|`analogReadPinAdc(pin, adc)`|Reads the value from the specified pin and ADC, eg. `C0, 1` will read from channel 6, ADC 2 instead of ADC 1. Note that the ADCs are 0-indexed for this function. |
|`pinToMux(pin)` |Translates a given pin to a channel and ADC combination. If an unsupported pin is given, returns the mux value for "0V (GND)". |
|`adc_read(mux)` |Reads the value from the ADC according to the specified pin and ADC combination. See your MCU's datasheet for more information. |
## Configuration
## ARM
The ARM implementation of the ADC has a few additional options that you can override in your own keyboards and keymaps to change how it operates. Please consult the corresponding `hal_adc_lld.h` in ChibiOS for your specific microcontroller for further documentation on your available options.
|`#define` |Type |Default |Description |
|---------------------|------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`ADC_CIRCULAR_BUFFER`|`bool`|`false` |If `true`, then the implementation will use a circular buffer. |
|`ADC_NUM_CHANNELS` |`int` |`1` |Sets the number of channels that will be scanned as part of an ADC operation. The current implementation only supports `1`. |
|`ADC_BUFFER_DEPTH` |`int` |`2` |Sets the depth of each result. Since we are only getting a 10-bit result by default, we set this to 2 bytes so we can contain our one value. This could be set to 1 if you opt for an 8-bit or lower result.|
|`ADC_SAMPLING_RATE` |`int` |`ADC_SMPR_SMP_1P5` |Sets the sampling rate of the ADC. By default, it is set to the fastest setting. |
|`ADC_RESOLUTION` |`int` |`ADC_CFGR1_RES_10BIT` or `ADC_CFGR_RES_10BITS`|The resolution of your result. We choose 10 bit by default, but you can opt for 12, 10, 8, or 6 bit. Different MCUs use slightly different names for the resolution constants. |

49
docs/drivers/apa102.md Normal file
View file

@ -0,0 +1,49 @@
# APA102 Driver {#apa102-driver}
This driver provides support for APA102 addressable RGB LEDs. They are similar to the [WS2812](ws2812) LEDs, but have increased data and refresh rates.
## Usage {#usage}
In most cases, the APA102 driver code is automatically included if you are using either the [RGBLight](../features/rgblight) or [RGB Matrix](../features/rgb_matrix) feature with the `apa102` driver set, and you would use those APIs instead.
However, if you need to use the driver standalone, add the following to your `rules.mk`:
```make
APA102_DRIVER_REQUIRED = yes
```
You can then call the APA102 API by including `apa102.h` in your code.
## Basic Configuration {#basic-configuration}
Add the following to your `config.h`:
|Define |Default |Description |
|---------------------------|-------------|------------------------------------------------------------------|
|`APA102_DI_PIN` |*Not defined*|The GPIO pin connected to the DI pin of the first LED in the chain|
|`APA102_CI_PIN` |*Not defined*|The GPIO pin connected to the CI pin of the first LED in the chain|
|`APA102_DEFAULT_BRIGHTNESS`|`31` |The default global brightness level of the LEDs, from 0 to 31 |
## API {#api}
### `void apa102_setleds(rgb_led_t *start_led, uint16_t num_leds)`
Send RGB data to the APA102 LED chain.
#### Arguments {#api-apa102-setleds-arguments}
- `rgb_led_t *start_led`
A pointer to the LED array.
- `uint16_t num_leds`
The length of the LED array.
---
### `void apa102_set_brightness(uint8_t brightness)`
Set the global brightness.
#### Arguments {#api-apa102-set-brightness-arguments}
- `uint8_t brightness`
The brightness level to set, from 0 to 31.

239
docs/drivers/audio.md Normal file
View file

@ -0,0 +1,239 @@
# Audio Driver {#audio-driver}
The [Audio feature](../features/audio) breaks the hardware specifics out into separate, exchangeable driver units, with a common interface to the audio-"core" - which itself handles playing songs and notes while tracking their progress in an internal state, initializing/starting/stopping the driver as needed.
Not all MCUs support every available driver, either the platform-support is not there (yet?) or the MCU simply does not have the required hardware peripheral.
## AVR {#avr}
Boards built around an Atmega32U4 can use two sets of PWM capable pins, each driving a separate speaker.
The possible configurations are:
| | Timer3 | Timer1 |
|--------------|-------------|--------------|
| one speaker | C4,C5 or C6 | |
| one speaker | | B4, B5 or B7 |
| two speakers | C4,C5 or C6 | B4, B5 or B7 |
Currently there is only one/default driver for AVR based boards, which is automatically configured to:
```make
AUDIO_DRIVER = pwm_hardware
```
## ARM {#arm}
For Arm based boards, QMK depends on ChibiOS - hence any MCU supported by the later is likely usable, as long as certain hardware peripherals are available.
Supported wiring configurations, with their ChibiOS/MCU peripheral requirement are listed below;
piezo speakers are marked with :one: for the first/primary and :two: for the secondary.
| driver | GPTD6<br>Tim6 | GPTD7<br>Tim7 | GPTD8<br>Tim8 | PWMD1<sup>1</sup><br>Tim1_Ch1 |
|--------------|------------------------------------------|------------------------|---------------|-------------------------------|
| dac_basic | A4+DACD1 = :one: | A5+DACD2 = :one: | state | |
| | A4+DACD1 = :one: + Gnd | A5+DACD2 = :two: + Gnd | state | |
| | A4+DACD1 = :two: + Gnd | A5+DACD2 = :one: + Gnd | state | |
| | A4+DACD1 = :one: + Gnd | | state | |
| | | A5+DACD2 = :one: + Gnd | state | |
| dac_additive | A4+DACD1 = :one: + Gnd | | | |
| | A5+DACD2 = :one: + Gnd | | | |
| | A4+DACD1 + A5+DACD2 = :one: <sup>2</sup> | | | |
| pwm_software | state-update | | | any = :one: |
| pwm hardware | state-update | | | A8 = :one: <sup>3</sup> |
<sup>1</sup>: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet
<sup>2</sup>: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set
<sup>3</sup>: TIM1_CH1 = A8 on STM32F103C8, other combinations are possible, see Data-sheet. configured with: AUDIO_PWM_DRIVER and AUDIO_PWM_CHANNEL
### DAC basic {#dac-basic}
The default driver for ARM boards, in absence of an overriding configuration.
This driver needs one Timer per enabled/used DAC channel, to trigger conversion; and a third timer to trigger state updates with the audio-core.
Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8:
```c
//halconf.h:
#define HAL_USE_DAC TRUE
#define HAL_USE_GPT TRUE
#include_next <halconf.h>
```
```c
// mcuconf.h:
#include_next <mcuconf.h>
#undef STM32_DAC_USE_DAC1_CH1
#define STM32_DAC_USE_DAC1_CH1 TRUE
#undef STM32_DAC_USE_DAC1_CH2
#define STM32_DAC_USE_DAC1_CH2 TRUE
#undef STM32_GPT_USE_TIM6
#define STM32_GPT_USE_TIM6 TRUE
#undef STM32_GPT_USE_TIM7
#define STM32_GPT_USE_TIM7 TRUE
#undef STM32_GPT_USE_TIM8
#define STM32_GPT_USE_TIM8 TRUE
```
::: tip
Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable).
:::
You can also change the timer used for the overall audio state by defining the driver. For instance:
```c
#define AUDIO_STATE_TIMER GPTD9
```
### DAC additive {#dac-additive}
only needs one timer (GPTD6, Tim6) to trigger the DAC unit to do a conversion; the audio state updates are in turn triggered during the DAC callback.
Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6:
```c
//halconf.h:
#define HAL_USE_DAC TRUE
#define HAL_USE_GPT TRUE
#include_next <halconf.h>
```
```c
// mcuconf.h:
#include_next <mcuconf.h>
#undef STM32_DAC_USE_DAC1_CH1
#define STM32_DAC_USE_DAC1_CH1 TRUE
#undef STM32_DAC_USE_DAC1_CH2
#define STM32_DAC_USE_DAC1_CH2 TRUE
#undef STM32_GPT_USE_TIM6
#define STM32_GPT_USE_TIM6 TRUE
```
### DAC Config
| Define | Defaults | Description |
| -------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUDIO_DAC_SAMPLE_MAX` | `4095U` | Highest value allowed. Lower value means lower volume. And 4095U is the upper limit, since this is limited to a 12 bit value. Only effects non-pregenerated samples. |
| `AUDIO_DAC_OFF_VALUE` | `AUDIO_DAC_SAMPLE_MAX / 2` | The value of the DAC when not playing anything. Some setups may require a high (`AUDIO_DAC_SAMPLE_MAX`) or low (`0`) value here. |
| `AUDIO_MAX_SIMULTANEOUS_TONES` | __see next table__ | The number of tones that can be played simultaneously. A value that is too high may freeze the controller or glitch out when too many tones are being played. |
| `AUDIO_DAC_SAMPLE_RATE` | __see next table__ | Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality. |
| `AUDIO_DAC_BUFFER_SIZE` | __see next table__ | Number of samples generated every refill. Too few may cause excessive CPU load; too many may cause freezes, RAM or flash exhaustion or lags during matrix scanning. |
There are a number of predefined quality settings that you can use, with "sane minimum" being the default. You can use custom values by simply defining the sample rate, number of simultaneous tones and buffer size, instead of using one of the listed presets.
| Define | Sample Rate | Simultaneous tones | Buffer size |
| --------------------------------- | ----------- | ------------------- | ----------- |
| `AUDIO_DAC_QUALITY_VERY_LOW` | `11025U` | `8` | `64U` |
| `AUDIO_DAC_QUALITY_LOW` | `22050U` | `4` | `128U` |
| `AUDIO_DAC_QUALITY_HIGH` | `44100U` | `2` | `256U` |
| `AUDIO_DAC_QUALITY_VERY_HIGH` | `88200U` | `1` | `256U` |
| `AUDIO_DAC_QUALITY_SANE_MINIMUM` | `16384U` | `8` | `64U` |
#### Notes on buffer size {#buffer-size}
By default, the buffer size attempts to keep to these constraints:
* The interval between buffer refills can't be too short, since the microcontroller would then only be servicing buffer refills and would freeze up.
* On the additive driver, the interval between buffer refills can't be too long, since matrix scanning would suffer lengthy pauses every so often, which would delay key presses or releases or lose some short taps altogether.
* The interval between buffer refills is kept to a minimum, which allows notes to stop as soon as possible after they should.
* For greater compatibility, the buffer size should be a power of 2.
* The buffer size being too large causes resource exhaustion leading to build failures or freezing at runtime: RAM usage (on the additive driver) or flash usage (on the basic driver).
You can lower the buffer size if you need a bit more space in your firmware, or raise it if your keyboard freezes up.
```c
/* zero crossing (or approach, whereas zero == DAC_OFF_VALUE, which can be configured to anything from 0 to DAC_SAMPLE_MAX)
* ============================*=*========================== AUDIO_DAC_SAMPLE_MAX
* * *
* * *
* ---------------------------------------------------------
* * * } AUDIO_DAC_SAMPLE_MAX/100
* --------------------------------------------------------- AUDIO_DAC_OFF_VALUE
* * * } AUDIO_DAC_SAMPLE_MAX/100
* ---------------------------------------------------------
* *
* * *
* * *
* =====*=*================================================= 0x0
*/
```
### PWM hardware {#pwm-hardware}
This driver uses the ChibiOS-PWM system to produce a square-wave on specific output pins that are connected to the PWM hardware.
The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function.
A configuration example for the STM32F103C8 would be:
```c
//halconf.h:
#define HAL_USE_PWM TRUE
#define HAL_USE_PAL TRUE
#include_next <halconf.h>
```
```c
// mcuconf.h:
#include_next <mcuconf.h>
#undef STM32_PWM_USE_TIM1
#define STM32_PWM_USE_TIM1 TRUE
```
If we now target pin A8, looking through the data-sheet of the STM32F103C8, for the timers and alternate functions
- TIM1_CH1 = PA8 <- alternate0
- TIM1_CH2 = PA9
- TIM1_CH3 = PA10
- TIM1_CH4 = PA11
with all this information, the configuration would contain these lines:
```c
//config.h:
#define AUDIO_PIN A8
#define AUDIO_PWM_DRIVER PWMD1
#define AUDIO_PWM_CHANNEL 1
```
ChibiOS uses GPIOv1 for the F103, which only knows of one alternate function.
On 'larger' STM32s, GPIOv2 or GPIOv3 are used; with them it is also necessary to configure `AUDIO_PWM_PAL_MODE` to the correct alternate function for the selected pin, timer and timer-channel.
You can also use the Complementary output (`TIMx_CHyN`) for PWM on supported controllers. To enable this functionality, you will need to make the following changes:
```c
// config.h:
#define AUDIO_PWM_COMPLEMENTARY_OUTPUT
```
### PWM software {#pwm-software}
This driver uses the PWM callbacks from PWMD1 with TIM1_CH1 to toggle the selected AUDIO_PIN in software.
During the same callback, with AUDIO_PIN_ALT_AS_NEGATIVE set, the AUDIO_PIN_ALT is toggled inversely to AUDIO_PIN. This is useful for setups that drive a piezo from two pins (instead of one and Gnd).
You can also change the timer used for software PWM by defining the driver. For instance:
```c
#define AUDIO_STATE_TIMER GPTD8
```
### Testing Notes {#testing-notes}
While not an exhaustive list, the following table provides the scenarios that have been partially validated:
| | DAC basic | DAC additive | PWM hardware | PWM software |
| ------------------------ | ------------------ | ------------------ | ------------------ | ------------------ |
| Atmega32U4 | :o: | :o: | :heavy_check_mark: | :o: |
| RP2040 | :x: | :x: | :heavy_check_mark: | ? |
| STM32F103C8 (bluepill) | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: |
| STM32F303CCT6 (proton-c) | :heavy_check_mark: | :heavy_check_mark: | ? | :heavy_check_mark: |
| STM32F405VG | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| L0xx | :x: (no Tim8) | ? | ? | ? |
:heavy_check_mark: : works and was tested
:o: : does not apply
:x: : not supported by MCU
*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.*

180
docs/drivers/eeprom.md Normal file
View file

@ -0,0 +1,180 @@
# EEPROM Driver Configuration {#eeprom-driver-configuration}
The EEPROM driver can be swapped out depending on the needs of the keyboard, or whether extra hardware is present.
Selecting the EEPROM driver is done in your keyboard's `rules.mk`:
Driver | Description
-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`EEPROM_DRIVER = vendor` (default) | Uses the on-chip driver provided by the chip manufacturer. For AVR, this is provided by avr-libc. This is supported on ARM for a subset of chips -- STM32F3xx, STM32F1xx, and STM32F072xB will be emulated by writing to flash. STM32L0xx and STM32L1xx will use the onboard dedicated true EEPROM. Other chips will generally act as "transient" below.
`EEPROM_DRIVER = i2c` | Supports writing to I2C-based 24xx EEPROM chips. See the driver section below.
`EEPROM_DRIVER = spi` | Supports writing to SPI-based 25xx EEPROM chips. See the driver section below.
`EEPROM_DRIVER = transient` | Fake EEPROM driver -- supports reading/writing to RAM, and will be discarded when power is lost.
`EEPROM_DRIVER = wear_leveling` | Frontend driver for the wear_leveling system, allowing for EEPROM emulation on top of flash -- both in-MCU and external SPI NOR flash.
## Vendor Driver Configuration {#vendor-eeprom-driver-configuration}
#### STM32 L0/L1 Configuration {#stm32l0l1-eeprom-driver-configuration}
::: warning
Resetting EEPROM using an STM32L0/L1 device takes up to 1 second for every 1kB of internal EEPROM used.
:::
`config.h` override | Description | Default Value
------------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------
`#define STM32_ONBOARD_EEPROM_SIZE` | The size of the EEPROM to use, in bytes. Erase times can be high, so it's configurable here, if not using the default value. | Minimum required to cover base _eeconfig_ data, or `1024` if VIA is enabled.
## I2C Driver Configuration {#i2c-eeprom-driver-configuration}
Currently QMK supports 24xx-series chips over I2C. As such, requires a working i2c_master driver configuration. You can override the driver configuration via your config.h:
`config.h` override | Description | Default Value
------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------
`#define EXTERNAL_EEPROM_I2C_BASE_ADDRESS` | Base I2C address for the EEPROM -- shifted left by 1 as per i2c_master requirements | 0b10100000
`#define EXTERNAL_EEPROM_I2C_ADDRESS(addr)` | Calculated I2C address for the EEPROM | `(EXTERNAL_EEPROM_I2C_BASE_ADDRESS)`
`#define EXTERNAL_EEPROM_BYTE_COUNT` | Total size of the EEPROM in bytes | 8192
`#define EXTERNAL_EEPROM_PAGE_SIZE` | Page size of the EEPROM in bytes, as specified in the datasheet | 32
`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | The number of bytes to transmit for the memory location within the EEPROM | 2
`#define EXTERNAL_EEPROM_WRITE_TIME` | Write cycle time of the EEPROM, as specified in the datasheet | 5
`#define EXTERNAL_EEPROM_WP_PIN` | If defined the WP pin will be toggled appropriately when writing to the EEPROM. | _none_
Some I2C EEPROM manufacturers explicitly recommend against hardcoding the WP pin to ground. This is in order to protect the eeprom memory content during power-up/power-down/brown-out conditions at low voltage where the eeprom is still operational, but the i2c master output might be unpredictable. If a WP pin is configured, then having an external pull-up on the WP pin is recommended.
Default values and extended descriptions can be found in `drivers/eeprom/eeprom_i2c.h`.
Alternatively, there are pre-defined hardware configurations for available chips/modules:
Module | Equivalent `#define` | Source
-----------------|---------------------------------|------------------------------------------
CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512` | <https://www.sparkfun.com/products/14764>
RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C` | <https://www.sparkfun.com/products/14764>
24LC32A EEPROM | `#define EEPROM_I2C_24LC32A` | <https://www.microchip.com/en-us/product/24LC32A>
24LC64 EEPROM | `#define EEPROM_I2C_24LC64` | <https://www.microchip.com/en-us/product/24LC64>
24LC128 EEPROM | `#define EEPROM_I2C_24LC128` | <https://www.microchip.com/en-us/product/24LC128>
24LC256 EEPROM | `#define EEPROM_I2C_24LC256` | <https://www.sparkfun.com/products/525>
MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895>
::: tip
If you find that the EEPROM is not cooperating, ensure you've correctly shifted up your EEPROM address by 1. For example, the datasheet might state the address as `0b01010000` -- the correct value of `EXTERNAL_EEPROM_I2C_BASE_ADDRESS` needs to be `0b10100000`.
:::
## SPI Driver Configuration {#spi-eeprom-driver-configuration}
Currently QMK supports 25xx-series chips over SPI. As such, requires a working spi_master driver configuration. You can override the driver configuration via your config.h:
`config.h` override | Default Value | Description
-----------------------------------------------|---------------|-------------------------------------------------------------------------------------
`#define EXTERNAL_EEPROM_SPI_SLAVE_SELECT_PIN` | _none_ | SPI Slave select pin in order to inform that the EEPROM is currently being addressed
`#define EXTERNAL_EEPROM_SPI_CLOCK_DIVISOR` | `64` | Clock divisor used to divide the peripheral clock to derive the SPI frequency
`#define EXTERNAL_EEPROM_BYTE_COUNT` | `8192` | Total size of the EEPROM in bytes
`#define EXTERNAL_EEPROM_PAGE_SIZE` | `32` | Page size of the EEPROM in bytes, as specified in the datasheet
`#define EXTERNAL_EEPROM_ADDRESS_SIZE` | `2` | The number of bytes to transmit for the memory location within the EEPROM
Default values and extended descriptions can be found in `drivers/eeprom/eeprom_spi.h`.
Alternatively, there are pre-defined hardware configurations for available chips/modules:
Module | Equivalent `#define` | Source
-----------------|---------------------------------|------------------------------------------
MB85RS64V FRAM | `define EEPROM_SPI_MB85RS64V` | <https://www.adafruit.com/product/1897>
::: warning
There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero.
:::
## Transient Driver configuration {#transient-eeprom-driver-configuration}
The only configurable item for the transient EEPROM driver is its size:
`config.h` override | Description | Default Value
------------------------------- | ----------------------------------------- | -------------
`#define TRANSIENT_EEPROM_SIZE` | Total size of the EEPROM storage in bytes | 64
Default values and extended descriptions can be found in `drivers/eeprom/eeprom_transient.h`.
## Wear-leveling Driver Configuration {#wear_leveling-eeprom-driver-configuration}
The wear-leveling driver uses an algorithm to minimise the number of erase cycles on the underlying MCU flash memory.
There is no specific configuration for this driver, but the wear-leveling system used by this driver may need configuration. See the [wear-leveling configuration](#wear_leveling-configuration) section for more information.
# Wear-leveling Configuration {#wear_leveling-configuration}
The wear-leveling driver has a few possible _backing stores_ that may be used by adding to your keyboard's `rules.mk` file:
Driver | Description
----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`WEAR_LEVELING_DRIVER = embedded_flash` | This driver is used for emulating EEPROM by writing to embedded flash on the MCU.
`WEAR_LEVELING_DRIVER = spi_flash` | This driver is used to address external SPI NOR Flash peripherals.
`WEAR_LEVELING_DRIVER = rp2040_flash` | This driver is used to write to the same storage the RP2040 executes code from.
`WEAR_LEVELING_DRIVER = legacy` | This driver is the "legacy" emulated EEPROM provided in historical revisions of QMK. Currently used for STM32F0xx and STM32F4x1, but slated for deprecation and removal once `embedded_flash` support for those MCU families is complete.
::: warning
All wear-leveling drivers require an amount of RAM equivalent to the selected logical EEPROM size. Increasing the size to 32kB of EEPROM requires 32kB of RAM, which a significant number of MCUs simply do not have.
:::
## Wear-leveling Embedded Flash Driver Configuration {#wear_leveling-efl-driver-configuration}
This driver performs writes to the embedded flash storage embedded in the MCU. In most circumstances, the last few of sectors of flash are used in order to minimise the likelihood of collision with program code.
Configurable options in your keyboard's `config.h`:
`config.h` override | Default | Description
-----------------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_ | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration.
`#define WEAR_LEVELING_EFL_FLASH_SIZE` | _unset_ | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting.
`#define WEAR_LEVELING_LOGICAL_SIZE` | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
`#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
`#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly.
::: warning
If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding.
:::
## Wear-leveling SPI Flash Driver Configuration {#wear_leveling-flash_spi-driver-configuration}
This driver performs writes to an external SPI NOR Flash peripheral. It also requires a working configuration for the SPI NOR Flash peripheral -- see the [flash driver](flash) documentation for more information.
Configurable options in your keyboard's `config.h`:
`config.h` override | Default | Description
----------------------------------------------------|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------
`#define WEAR_LEVELING_EXTERNAL_FLASH_BLOCK_COUNT` | `1` | Number of blocks in the external flash used by the wear-leveling algorithm.
`#define WEAR_LEVELING_EXTERNAL_FLASH_BLOCK_OFFSET` | `0` | The index first block in the external flash used by the wear-leveling algorithm.
`#define WEAR_LEVELING_LOGICAL_SIZE` | `((block_count*block_size)/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. Result must be <= 64kB.
`#define WEAR_LEVELING_BACKING_SIZE` | `(block_count*block_size)` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size.
`#define BACKING_STORE_WRITE_SIZE` | `8` | The write width used whenever a write is performed on the external flash peripheral.
::: warning
There is currently a limit of 64kB for the EEPROM subsystem within QMK, so using a larger flash is not going to be beneficial as the logical size cannot be increased beyond 65536. The backing size may be increased to a larger value, but erase timing may suffer as a result.
:::
## Wear-leveling RP2040 Driver Configuration {#wear_leveling-rp2040-driver-configuration}
This driver performs writes to the same underlying storage that the RP2040 executes its code.
Configurable options in your keyboard's `config.h`:
`config.h` override | Default | Description
------------------------------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------------
`#define WEAR_LEVELING_RP2040_FLASH_SIZE` | `PICO_FLASH_SIZE_BYTES` | Number of bytes of flash on the board.
`#define WEAR_LEVELING_RP2040_FLASH_BASE` | `(flash_size-sector_size)` | The byte-wise location that the backing storage should be located.
`#define WEAR_LEVELING_LOGICAL_SIZE` | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM.
`#define WEAR_LEVELING_BACKING_SIZE` | `8192` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size as well as the sector size.
`#define BACKING_STORE_WRITE_SIZE` | `2` | The write width used whenever a write is performed on the external flash peripheral.
## Wear-leveling Legacy EEPROM Emulation Driver Configuration {#wear_leveling-legacy-driver-configuration}
This driver performs writes to the embedded flash storage embedded in the MCU much like the normal Embedded Flash Driver, and is only for use with STM32F0xx and STM32F4x1 devices. This flash implementation is still currently provided as the EFL driver is currently non-functional for the previously mentioned families.
By default, `1024` bytes of emulated EEPROM is provided:
MCU | EEPROM Provided | Flash Used
----------|-----------------|--------------
STM32F042 | `1024` bytes | `2048` bytes
STM32F070 | `1024` bytes | `2048` bytes
STM32F072 | `1024` bytes | `2048` bytes
STM32F401 | `1024` bytes | `16384` bytes
STM32F411 | `1024` bytes | `16384` bytes
Under normal circumstances configuration of this driver requires intimate knowledge of the MCU's flash structure -- reconfiguration is at your own risk and will require referring to the code.

Some files were not shown because too many files have changed in this diff Show more