-
-?> **Basic** [QMK Configurator](newbs_building_firmware_configurator.md)
-User friendly graphical interfaces, no programming knowledge required. - -?> **Advanced** [Use The Source](newbs.md)
-More powerful, but harder to use. - -
-
-## Make It Yours
-
-QMK has lots of features to explore, and a good deal of reference documentation to dig through. Most features are taken advantage of by modifying your [keymap](keymap.md), and changing the [keycodes](keycodes.md).
-
-## Need help?
-
-Check out the [support page](support.md) to see how you can get help using QMK.
-
-## Give Back
-
-There are a lot of ways you can contribute to the QMK Community. The easiest way to get started is to use it and spread the word to your friends.
-
-* Help people out on our forums and chat rooms:
- * [/r/olkb](https://www.reddit.com/r/olkb/)
- * [Discord Server](https://discord.gg/Uq7gcHh)
-* Contribute to our documentation by clicking "Edit This Page" at the bottom
-* [Translate our documentation into your language](translating.md)
-* [Report a bug](https://github.com/qmk/qmk_firmware/issues/new/choose)
-* [Open a Pull Request](contributing.md)
diff --git a/docs/__capabilities.md b/docs/__capabilities.md
index 469da462eb..873ca44664 100644
--- a/docs/__capabilities.md
+++ b/docs/__capabilities.md
@@ -6,8 +6,6 @@ This page lays out the capabilities used by the QMK Firmware documentation, in o
Unrelated to styling, high-level tech.
-* I18n -- translations to other languages: [_langs.md](_langs.md)
-* Sidebar -- listing of pages by category: [_summary.md](_summary.md)
* Title anchors -- `:id=some-anchor-name`, used for direct linking to sections
* Links to anchors:
* Style 1: [early initialization](platformdev_chibios_earlyinit.md?id=board-init)
@@ -40,7 +38,10 @@ Unrelated to styling, high-level tech.
--User friendly graphical interfaces, no programming knowledge required. - -?> **Advanced** [Use The Source](newbs.md)
-More powerful, but harder to use. - -
+
+
+
+
### Lists
@@ -83,7 +84,7 @@ Nested mixed:
* `lib/python/qmk/cli/generate/config_h.py`
* `lib/python/qmk/cli/generate/rules_mk.py`
-### Emoji :id=emoji
+### Emoji {#emoji}
#### Direct:
@@ -126,6 +127,26 @@ Command+`
!> Notification, damnit!
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
### Keyboard keys
,
@@ -242,6 +263,20 @@ Content three
+::::tabs
+=== tab a
+a content 2
+=== tab b
+b content 2
+=== tab c
+:::tabs
+== nested tab a
+nested a content 2
+== nested tab b
+nested b content 2
+:::
+::::
+
## Details sections
Expandable:
@@ -254,4 +289,10 @@ Expandable:
This is some inner content.
+## Embed
+
+[example embed](__capabilities_inc.md ':include')
+
+
+
[1]: https://en.wikipedia.org/wiki/Eclipse_(software)
diff --git a/docs/__capabilities_inc.md b/docs/__capabilities_inc.md
new file mode 100644
index 0000000000..d2cf010d36
--- /dev/null
+++ b/docs/__capabilities_inc.md
@@ -0,0 +1 @@
+Lorem ipsum dolor sit amet.
diff --git a/docs/_aliases.json b/docs/_aliases.json
new file mode 100644
index 0000000000..0dfcdea1e2
--- /dev/null
+++ b/docs/_aliases.json
@@ -0,0 +1,77 @@
+{
+ "/adding_a_keyboard_to_qmk": "/hardware_keyboard_guidelines",
+ "/build_environment_setup": "/newbs_getting_started",
+ "/cli_dev_configuration": "/cli_configuration",
+ "/dynamic_macros": "/feature_dynamic_macros",
+ "/feature_common_shortcuts": "/feature_advanced_keycodes",
+ "/flashing_bootloadhid": "/flashing",
+ "/getting_started_build_tools": "/newbs_getting_started",
+ "/getting_started_getting_help": "/support",
+ "/glossary": "/reference_glossary",
+ "/key_lock": "/feature_key_lock",
+ "/make_instructions": "/getting_started_make_guide",
+ "/python_development": "/cli_development",
+ "/space_cadet_shift": "/feature_space_cadet_shift",
+ "/tap_dance": "/feature_tap_dance",
+ "/tutorial": "/newbs",
+ "/unicode": "/feature_unicode",
+
+ "/features/bluetooth": "/features/wireless",
+
+ "/adc_driver": "/drivers/adc",
+ "/apa102_driver": "/drivers/apa102",
+ "/audio_driver": "/drivers/audio",
+ "/eeprom_driver": "/drivers/eeprom",
+ "/feature_audio": "/features/audio",
+ "/feature_auto_shift": "/features/auto_shift",
+ "/feature_autocorrect": "/features/autocorrect",
+ "/feature_backlight": "/features/backlight",
+ "/feature_bluetooth": "/features/wireless",
+ "/feature_bootmagic": "/features/bootmagic",
+ "/feature_caps_word": "/features/caps_word",
+ "/feature_combo": "/features/combo",
+ "/feature_command": "/features/command",
+ "/feature_digitizer": "/features/digitizer",
+ "/feature_dip_switch": "/features/dip_switch",
+ "/feature_dynamic_macros": "/features/dynamic_macros",
+ "/feature_encoders": "/features/encoders",
+ "/feature_grave_esc": "/features/grave_esc",
+ "/feature_haptic_feedback": "/features/haptic_feedback",
+ "/feature_hd44780": "/features/hd44780",
+ "/feature_joystick": "/features/joystick",
+ "/feature_key_lock": "/features/key_lock",
+ "/feature_key_overrides": "/features/key_overrides",
+ "/feature_leader_key": "/features/leader_key",
+ "/feature_led_indicators": "/features/led_indicators",
+ "/feature_led_matrix": "/features/led_matrix",
+ "/feature_midi": "/features/midi",
+ "/feature_mouse_keys": "/features/mouse_keys",
+ "/feature_oled_driver": "/features/oled_driver",
+ "/feature_os_detection": "/features/os_detection",
+ "/feature_pointing_device": "/features/pointing_device",
+ "/feature_programmable_button": "/features/programmable_button",
+ "/feature_ps2_mouse": "/features/ps2_mouse",
+ "/feature_rawhid": "/features/rawhid",
+ "/feature_repeat_key": "/features/repeat_key",
+ "/feature_rgb_matrix": "/features/rgb_matrix",
+ "/feature_rgblight": "/features/rgblight",
+ "/feature_secure": "/features/secure",
+ "/feature_send_string": "/features/send_string",
+ "/feature_sequencer": "/features/sequencer",
+ "/feature_space_cadet": "/features/space_cadet",
+ "/feature_split_keyboard": "/features/split_keyboard",
+ "/feature_st7565": "/features/st7565",
+ "/feature_stenography": "/features/stenography",
+ "/feature_swap_hands": "/features/swap_hands",
+ "/feature_tap_dance": "/features/tap_dance",
+ "/feature_tri_layer": "/features/tri_layer",
+ "/feature_unicode": "/features/unicode",
+ "/feature_wpm": "/features/wpm",
+ "/flash_driver": "/drivers/flash",
+ "/gpio_control": "/drivers/gpio",
+ "/i2c_driver": "/drivers/i2c",
+ "/serial_driver": "/drivers/serial",
+ "/spi_driver": "/drivers/spi",
+ "/uart_driver": "/drivers/uart",
+ "/ws2812_driver": "/drivers/ws2812"
+}
diff --git a/docs/_langs.md b/docs/_langs.md
deleted file mode 100644
index 8b08c34513..0000000000
--- a/docs/_langs.md
+++ /dev/null
@@ -1,4 +0,0 @@
-- Translations
- - [:uk: English](/)
- - [:cn: 简体中文](/zh-cn/)
- - [:jp: 日本語](/ja/)
diff --git a/docs/_sidebar.json b/docs/_sidebar.json
new file mode 100644
index 0000000000..d237b0e1d0
--- /dev/null
+++ b/docs/_sidebar.json
@@ -0,0 +1,315 @@
+[
+ {
+ "text": "Tutorial",
+ "items": [
+ { "text": "Introduction", "link": "/newbs" },
+ { "text": "Setup", "link": "/newbs_getting_started" },
+ { "text": "Building Your First Firmware", "link": "/newbs_building_firmware" },
+ { "text": "Flashing Firmware", "link": "/newbs_flashing" },
+ { "text": "Getting Help/Support", "link": "/support" },
+ { "text": "External Userspace", "link": "/newbs_external_userspace" },
+ { "text": "Other Resources", "link": "/newbs_learn_more_resources" },
+ { "text": "Syllabus", "link": "/syllabus" }
+ ]
+ },
+ {
+ "text": "FAQs",
+ "items": [
+ { "text": "General FAQ", "link": "/faq_general" },
+ { "text": "Build/Compile QMK", "link": "/faq_build" },
+ { "text": "Troubleshooting QMK", "link": "/faq_misc" },
+ { "text": "Debugging QMK", "link": "/faq_debug" },
+ { "text": "Keymap FAQ", "link": "/faq_keymap" },
+ { "text": "Squeezing Space from AVR", "link": "/squeezing_avr" },
+ { "text": "Glossary", "link": "/reference_glossary" }
+ ]
+ },
+ {
+ "text": "Licensing",
+ "items": [
+ { "text": "License Violations", "link": "/license_violations" },
+ { "text": "Proprietary Libraries", "link": "/proprietary_libs" }
+ ]
+ },
+ {
+ "text": "Configurator",
+ "items": [
+ { "text": "Overview", "link": "/newbs_building_firmware_configurator" },
+ { "text": "Step by Step", "link": "/configurator_step_by_step" },
+ { "text": "Troubleshooting", "link": "/configurator_troubleshooting" },
+ { "text": "Architecture", "link": "/configurator_architecture" },
+ {
+ "text": "QMK API",
+ "items": [
+ { "text": "Overview", "link": "/api_overview" },
+ { "text": "API Documentation", "link": "/api_docs" },
+ { "text": "Keyboard Support", "link": "/reference_configurator_support" },
+ { "text": "Adding Default Keymaps", "link": "/configurator_default_keymaps" }
+ ]
+ }
+ ]
+ },
+ {
+ "text": "CLI",
+ "items": [
+ { "text": "Overview", "link": "/cli" },
+ { "text": "Configuration", "link": "/cli_configuration" },
+ { "text": "Commands", "link": "/cli_commands" },
+ { "text": "Tab Completion", "link": "/cli_tab_complete" }
+ ]
+ },
+ {
+ "text": "Using QMK",
+ "items": [
+ {
+ "text": "Guides",
+ "items": [
+ { "text": "Customizing Functionality", "link": "/custom_quantum_functions" },
+ { "text": "Driver Installation with Zadig", "link": "/driver_installation_zadig" },
+ { "text": "Community Modules", "link": "/features/community_modules" },
+ { "text": "Keymap Overview", "link": "/keymap" },
+ {
+ "text": "Development Environments",
+ "items": [{ "text": "Docker Guide", "link": "/getting_started_docker" }]
+ },
+ { "text": "Flashing", "link": "/flashing" },
+ {
+ "text": "IDEs",
+ "items": [
+ { "text": "Using Eclipse with QMK", "link": "/other_eclipse" },
+ { "text": "Using VSCode with QMK", "link": "/other_vscode" }
+ ]
+ },
+ {
+ "text": "Git Best Practices",
+ "items": [
+ { "text": "Introduction", "link": "/newbs_git_best_practices" },
+ { "text": "Your Fork", "link": "/newbs_git_using_your_master_branch" },
+ { "text": "Merge Conflicts", "link": "/newbs_git_resolving_merge_conflicts" },
+ { "text": "Fixing Your Branch", "link": "/newbs_git_resynchronize_a_branch" }
+ ]
+ }
+ ]
+ },
+ {
+ "text": "Simple Keycodes",
+ "items": [
+ { "text": "Full List", "link": "/keycodes" },
+ { "text": "Basic Keycodes", "link": "/keycodes_basic" },
+ { "text": "Language-Specific Keycodes", "link": "/reference_keymap_extras" },
+ { "text": "Modifier Keys", "link": "/feature_advanced_keycodes" },
+ { "text": "Quantum Keycodes", "link": "/quantum_keycodes" },
+ { "text": "Magic Keycodes", "link": "/keycodes_magic" }
+ ]
+ },
+ {
+ "text": "Advanced Keycodes",
+ "items": [
+ { "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": "/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": "/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": "/features/digitizer" },
+ { "text": "EEPROM", "link": "/feature_eeprom" },
+ { "text": "Key Lock", "link": "/features/key_lock" },
+ { "text": "Key Overrides", "link": "/features/key_overrides" },
+ { "text": "Layers", "link": "/feature_layers" },
+ { "text": "Layer Lock", "link": "/features/layer_lock" },
+ { "text": "One Shot Keys", "link": "/one_shot_keys" },
+ { "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": "/features/tri_layer" },
+ { "text": "Unicode", "link": "/features/unicode" },
+ { "text": "Userspace", "link": "/feature_userspace" },
+ { "text": "WPM Calculation", "link": "/features/wpm" }
+ ]
+ },
+ {
+ "text": "Hardware Features",
+ "items": [
+ {
+ "text": "Displays",
+ "items": [
+ {
+ "text": "Quantum Painter",
+ "link": "quantum_painter",
+ "items": [
+ { "text": "Quantum Painter LVGL Integration", "link": "/quantum_painter_lvgl" }
+ ]
+ },
+ { "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": "/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": "/features/audio" },
+ { "text": "Battery", "link": "/features/battery" },
+ { "text": "Bootmagic", "link": "/features/bootmagic" },
+ { "text": "Converters", "link": "/feature_converters" },
+ { "text": "Custom Matrix", "link": "/custom_matrix" },
+ { "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" },
+ { "text": "Wireless", "link": "/features/wireless" }
+ ]
+ },
+ {
+ "text": "Keyboard Building",
+ "items": [
+ { "text": "Easy Maker for One Offs", "link": "/easy_maker" },
+ { "text": "Porting Keyboards", "link": "/porting_your_keyboard_to_qmk" },
+ { "text": "Hand Wiring Guide", "link": "/hand_wire" },
+ { "text": "ISP Flashing Guide", "link": "/isp_flashing_guide" }
+ ]
+ }
+ ]
+ },
+ {
+ "text": "Developing QMK",
+ "items": [
+ { "text": "PR Checklist", "link": "/pr_checklist" },
+ {
+ "text": "Breaking Changes",
+ "items": [
+ { "text": "Overview", "link": "/breaking_changes" },
+ { "text": "My Pull Request Was Flagged", "link": "/breaking_changes_instructions" },
+ {
+ "text": "Most Recent ChangeLog",
+ "link": "/ChangeLog/20250831"
+ },
+ { "text": "Past Breaking Changes", "link": "/breaking_changes_history" },
+ { "text": "Deprecation Policy", "link": "/support_deprecation_policy" }
+ ]
+ },
+
+ {
+ "text": "C Development",
+ "items": [
+ { "text": "ARM Debugging Guide", "link": "/arm_debugging" },
+ { "text": "Coding Conventions", "link": "/coding_conventions_c" },
+ { "text": "Compatible Microcontrollers", "link": "/compatible_microcontrollers" },
+ {
+ "text": "Drivers",
+ "link": "hardware_drivers",
+ "items": [
+ { "text": "ADC Driver", "link": "/drivers/adc" },
+ { "text": "APA102 Driver", "link": "/drivers/apa102" },
+ { "text": "Audio Driver", "link": "/drivers/audio" },
+ { "text": "Battery Driver", "link": "/drivers/battery" },
+ { "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": "/drivers/gpio" },
+ { "text": "Keyboard Guidelines", "link": "/hardware_keyboard_guidelines" }
+ ]
+ },
+
+ {
+ "text": "Python Development",
+ "items": [
+ { "text": "Coding Conventions", "link": "/coding_conventions_python" },
+ { "text": "QMK CLI Development", "link": "/cli_development" }
+ ]
+ },
+
+ {
+ "text": "Configurator Development",
+ "items": [
+ {
+ "text": "QMK API",
+ "items": [
+ { "text": "Development Environment", "link": "/api_development_environment" },
+ { "text": "Architecture Overview", "link": "/api_development_overview" }
+ ]
+ }
+ ]
+ },
+
+ {
+ "text": "Hardware Platform Development",
+ "items": [
+ {
+ "text": "Arm/ChibiOS",
+ "items": [
+ { "text": "Selecting an MCU", "link": "/platformdev_selecting_arm_mcu" },
+ { "text": "Early initialization", "link": "/platformdev_chibios_earlyinit" },
+ { "text": "Raspberry Pi RP2040", "link": "/platformdev_rp2040" },
+ { "text": "Proton C", "link": "/platformdev_proton_c" },
+ { "text": "WeAct Blackpill F4x1", "link": "/platformdev_blackpill_f4x1" }
+ ]
+ }
+ ]
+ },
+
+ {
+ "text": "QMK Reference",
+ "items": [
+ { "text": "Contributing to QMK", "link": "/contributing" },
+ { "text": "Config Options", "link": "/config_options" },
+ { "text": "Data Driven Configuration", "link": "/data_driven_config" },
+ { "text": "Make Documentation", "link": "/getting_started_make_guide" },
+ { "text": "Documentation Best Practices", "link": "/documentation_best_practices" },
+ { "text": "Documentation Templates", "link": "/documentation_templates" },
+ { "text": "Community Layouts", "link": "/feature_layouts" },
+ { "text": "Unit Testing", "link": "/unit_testing" },
+ { "text": "Useful Functions", "link": "/ref_functions" },
+ { "text": "info.json Format", "link": "/reference_info_json" }
+ ]
+ },
+
+ {
+ "text": "For a Deeper Understanding",
+ "items": [
+ { "text": "How Keyboards Work", "link": "/how_keyboards_work" },
+ { "text": "How a Matrix Works", "link": "/how_a_matrix_works" },
+ { "text": "Understanding QMK", "link": "/understanding_qmk" }
+ ]
+ }
+ ]
+ }
+]
diff --git a/docs/_summary.md b/docs/_summary.md
deleted file mode 100644
index fb584955ce..0000000000
--- a/docs/_summary.md
+++ /dev/null
@@ -1,204 +0,0 @@
-* Tutorial
- * [Introduction](newbs.md)
- * [Setup](newbs_getting_started.md)
- * [Building Your First Firmware](newbs_building_firmware.md)
- * [Flashing Firmware](newbs_flashing.md)
- * [Getting Help/Support](support.md)
- * [External Userspace](newbs_external_userspace.md)
- * [Other Resources](newbs_learn_more_resources.md)
- * [Syllabus](syllabus.md)
-
-* FAQs
- * [General FAQ](faq_general.md)
- * [Build/Compile QMK](faq_build.md)
- * [Troubleshooting QMK](faq_misc.md)
- * [Debugging QMK](faq_debug.md)
- * [Keymap FAQ](faq_keymap.md)
- * [Squeezing Space from AVR](squeezing_avr.md)
- * [Glossary](reference_glossary.md)
-
-* Configurator
- * [Overview](newbs_building_firmware_configurator.md)
- * [Step by Step](configurator_step_by_step.md)
- * [Troubleshooting](configurator_troubleshooting.md)
- * [Architecture](configurator_architecture.md)
- * QMK API
- * [Overview](api_overview.md)
- * [API Documentation](api_docs.md)
- * [Keyboard Support](reference_configurator_support.md)
- * [Adding Default Keymaps](configurator_default_keymaps.md)
-
-* CLI
- * [Overview](cli.md)
- * [Configuration](cli_configuration.md)
- * [Commands](cli_commands.md)
- * [Tab Completion](cli_tab_complete.md)
-
-* Using QMK
- * Guides
- * [Customizing Functionality](custom_quantum_functions.md)
- * [Driver Installation with Zadig](driver_installation_zadig.md)
- * [Keymap Overview](keymap.md)
- * Development Environments
- * [Docker Guide](getting_started_docker.md)
- * Flashing
- * [Flashing](flashing.md)
- * [Flashing ATmega32A (ps2avrgb)](flashing_bootloadhid.md)
- * IDEs
- * [Using Eclipse with QMK](other_eclipse.md)
- * [Using VSCode with QMK](other_vscode.md)
- * Git Best Practices
- * [Introduction](newbs_git_best_practices.md)
- * [Your Fork](newbs_git_using_your_master_branch.md)
- * [Merge Conflicts](newbs_git_resolving_merge_conflicts.md)
- * [Fixing Your Branch](newbs_git_resynchronize_a_branch.md)
-
- * Simple Keycodes
- * [Full List](keycodes.md)
- * [Basic Keycodes](keycodes_basic.md)
- * [Language-Specific Keycodes](reference_keymap_extras.md)
- * [Modifier Keys](feature_advanced_keycodes.md)
- * [Quantum Keycodes](quantum_keycodes.md)
- * [Magic Keycodes](keycodes_magic.md)
-
- * Advanced Keycodes
- * [Command](feature_command.md)
- * [Dynamic Macros](feature_dynamic_macros.md)
- * [Grave Escape](feature_grave_esc.md)
- * [Leader Key](feature_leader_key.md)
- * [Mod-Tap](mod_tap.md)
- * [Macros](feature_macros.md)
- * [Mouse Keys](feature_mouse_keys.md)
- * [Programmable Button](feature_programmable_button.md)
- * [Repeat Key](feature_repeat_key.md)
- * [Space Cadet Shift](feature_space_cadet.md)
- * [US ANSI Shifted Keys](keycodes_us_ansi_shifted.md)
-
- * Software Features
- * [Auto Shift](feature_auto_shift.md)
- * [Autocorrect](feature_autocorrect.md)
- * [Caps Word](feature_caps_word.md)
- * [Combos](feature_combo.md)
- * [Debounce API](feature_debounce_type.md)
- * [Digitizer](feature_digitizer.md)
- * [EEPROM](feature_eeprom.md)
- * [Key Lock](feature_key_lock.md)
- * [Key Overrides](feature_key_overrides.md)
- * [Layers](feature_layers.md)
- * [One Shot Keys](one_shot_keys.md)
- * [OS Detection](feature_os_detection.md)
- * [Raw HID](feature_rawhid.md)
- * [Secure](feature_secure.md)
- * [Send String](feature_send_string.md)
- * [Sequencer](feature_sequencer.md)
- * [Swap Hands](feature_swap_hands.md)
- * [Tap Dance](feature_tap_dance.md)
- * [Tap-Hold Configuration](tap_hold.md)
- * [Tri Layer](feature_tri_layer.md)
- * [Unicode](feature_unicode.md)
- * [Userspace](feature_userspace.md)
- * [WPM Calculation](feature_wpm.md)
-
- * Hardware Features
- * Displays
- * [Quantum Painter](quantum_painter.md)
- * [Quantum Painter LVGL Integration](quantum_painter_lvgl.md)
- * [HD44780 LCD Driver](feature_hd44780.md)
- * [ST7565 LCD Driver](feature_st7565.md)
- * [OLED Driver](feature_oled_driver.md)
- * Lighting
- * [Backlight](feature_backlight.md)
- * [LED Matrix](feature_led_matrix.md)
- * [RGB Lighting](feature_rgblight.md)
- * [RGB Matrix](feature_rgb_matrix.md)
- * [Audio](feature_audio.md)
- * [Bluetooth](feature_bluetooth.md)
- * [Bootmagic Lite](feature_bootmagic.md)
- * [Converters](feature_converters.md)
- * [Custom Matrix](custom_matrix.md)
- * [DIP Switch](feature_dip_switch.md)
- * [Encoders](feature_encoders.md)
- * [Haptic Feedback](feature_haptic_feedback.md)
- * [Joystick](feature_joystick.md)
- * [LED Indicators](feature_led_indicators.md)
- * [MIDI](feature_midi.md)
- * [Pointing Device](feature_pointing_device.md)
- * [PS/2 Mouse](feature_ps2_mouse.md)
- * [Split Keyboard](feature_split_keyboard.md)
- * [Stenography](feature_stenography.md)
-
- * Keyboard Building
- * [Easy Maker for One Offs](easy_maker.md)
- * [Porting Keyboards](porting_your_keyboard_to_qmk.md)
- * [Hand Wiring Guide](hand_wire.md)
- * [ISP Flashing Guide](isp_flashing_guide.md)
-
-* Developing QMK
- * [PR Checklist](pr_checklist.md)
- * Breaking Changes
- * [Overview](breaking_changes.md)
- * [My Pull Request Was Flagged](breaking_changes_instructions.md)
- * [Most Recent ChangeLog](ChangeLog/20240225.md "QMK v0.24.0 - 2024 Feb 25")
- * [Past Breaking Changes](breaking_changes_history.md)
-
- * C Development
- * [ARM Debugging Guide](arm_debugging.md)
- * [Coding Conventions](coding_conventions_c.md)
- * [Compatible Microcontrollers](compatible_microcontrollers.md)
- * [Drivers](hardware_drivers.md)
- * [ADC Driver](adc_driver.md)
- * [APA102 Driver](apa102_driver.md)
- * [Audio Driver](audio_driver.md)
- * [I2C Driver](i2c_driver.md)
- * [SPI Driver](spi_driver.md)
- * [WS2812 Driver](ws2812_driver.md)
- * [EEPROM Driver](eeprom_driver.md)
- * [Flash Driver](flash_driver.md)
- * ['serial' Driver](serial_driver.md)
- * [UART Driver](uart_driver.md)
- * [GPIO Controls](gpio_control.md)
- * [Keyboard Guidelines](hardware_keyboard_guidelines.md)
-
- * Python Development
- * [Coding Conventions](coding_conventions_python.md)
- * [QMK CLI Development](cli_development.md)
-
- * Configurator Development
- * QMK API
- * [Development Environment](api_development_environment.md)
- * [Architecture Overview](api_development_overview.md)
-
- * Hardware Platform Development
- * Arm/ChibiOS
- * [Selecting an MCU](platformdev_selecting_arm_mcu.md)
- * [Early initialization](platformdev_chibios_earlyinit.md)
- * [Raspberry Pi RP2040](platformdev_rp2040.md)
- * [Proton C](platformdev_proton_c.md)
- * [WeAct Blackpill F4x1](platformdev_blackpill_f4x1.md)
-
- * QMK Reference
- * [Contributing to QMK](contributing.md)
- * [Translating the QMK Docs](translating.md)
- * [Config Options](config_options.md)
- * [Data Driven Configuration](data_driven_config.md)
- * [Make Documentation](getting_started_make_guide.md)
- * [Documentation Best Practices](documentation_best_practices.md)
- * [Documentation Templates](documentation_templates.md)
- * [Community Layouts](feature_layouts.md)
- * [Unit Testing](unit_testing.md)
- * [Useful Functions](ref_functions.md)
- * [info.json Format](reference_info_json.md)
-
- * For a Deeper Understanding
- * [How Keyboards Work](how_keyboards_work.md)
- * [How a Matrix Works](how_a_matrix_works.md)
- * [Understanding QMK](understanding_qmk.md)
-
- * QMK Internals (In Progress)
- * [Defines](internals/defines.md)
- * [Input Callback Reg](internals/input_callback_reg.md)
- * [Midi Device](internals/midi_device.md)
- * [Midi Device Setup Process](internals/midi_device_setup_process.md)
- * [Midi Util](internals/midi_util.md)
- * [Send Functions](internals/send_functions.md)
- * [Sysex Tools](internals/sysex_tools.md)
diff --git a/docs/adc_driver.md b/docs/adc_driver.md
deleted file mode 100644
index dd928e1e7f..0000000000
--- a/docs/adc_driver.md
+++ /dev/null
@@ -1,173 +0,0 @@
-# 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](feature_encoders.md).
-
-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` | | |
-
-\* 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.
-
-### 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 | | | | |
-
-¹ 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.
-
-² 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.
-
-#### 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*|
-
-
-* 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.
-
-## 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. |
diff --git a/docs/apa102_driver.md b/docs/apa102_driver.md
deleted file mode 100644
index 1da2de6ca3..0000000000
--- a/docs/apa102_driver.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# APA102 Driver :id=apa102-driver
-
-This driver provides support for APA102 addressable RGB LEDs. They are similar to the [WS2812](ws2812_driver.md) LEDs, but have increased data and refresh rates.
-
-## Usage :id=usage
-
-In most cases, the APA102 driver code is automatically included if you are using either the [RGBLight](feature_rgblight.md) or [RGB Matrix](feature_rgb_matrix.md) 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 :id=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 :id=api
-
-### `void apa102_setleds(rgb_led_t *start_led, uint16_t num_leds)`
-
-Send RGB data to the APA102 LED chain.
-
-#### Arguments :id=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 :id=api-apa102-set-brightness-arguments
-
- - `uint8_t brightness`
- The brightness level to set, from 0 to 31.
diff --git a/docs/api_development_overview.md b/docs/api_development_overview.md
index e55d034100..eb164bec52 100644
--- a/docs/api_development_overview.md
+++ b/docs/api_development_overview.md
@@ -4,7 +4,7 @@ This page attempts to introduce developers to the QMK Compiler. It does not go i
# Overview
-The QMK Compile API consists of a few movings parts:
+The QMK Compile API consists of a few moving parts:
diff --git a/docs/api_docs.md b/docs/api_docs.md
index 3324bc545b..f4ba19c42a 100644
--- a/docs/api_docs.md
+++ b/docs/api_docs.md
@@ -67,7 +67,7 @@ Once your compile job has finished you'll check the `result` key. The value of t
* `firmware_source_url`: A list of URLs for the full firmware source code
* `output`: The stdout and stderr for this compile job. Errors will be found here.
-## Constants :id=qmk-constants
+## Constants {#qmk-constants}
If you're writing a tool that leverages constants used within QMK, the API is used to publish "locked-in" versions of those constants in order to ensure that any third-party tooling has a canonical set of information to work with.
@@ -81,9 +81,13 @@ $ curl https://keyboards.develop.qmk.fm/v1/constants_metadata.json # For `develo
{"last_updated": "2022-11-26 12:00:00 GMT", "constants": {"keycodes": ["0.0.1", "0.0.2"]}}
```
-!> Versions exported by the `master` endpoint are locked-in. Any extra versions that exist on the `develop` endpoint which don't exist in `master` are subject to change.
+::: warning
+Versions exported by the `master` endpoint are locked-in. Any extra versions that exist on the `develop` endpoint which don't exist in `master` are subject to change.
+:::
-?> Only keycodes are currently published, but over time all other "externally visible" IDs are expected to appear on these endpoints.
+::: tip
+Only keycodes are currently published, but over time all other "externally visible" IDs are expected to appear on these endpoints.
+:::
To retrieve the constants associated with a subsystem, the endpoint format is as follows:
```
diff --git a/docs/api_overview.md b/docs/api_overview.md
index f851a48a4a..c8ec42e947 100644
--- a/docs/api_overview.md
+++ b/docs/api_overview.md
@@ -4,12 +4,12 @@ The QMK API provides an asynchronous API that Web and GUI tools can use to compi
## App Developers
-If you are an app developer interested in using this API in your application you should head over to [Using The API](api_docs.md).
+If you are an app developer interested in using this API in your application you should head over to [Using The API](api_docs).
## Keyboard Maintainers
-If you would like to enhance your keyboard's support in the QMK Compiler API head over to the [Keyboard Support](reference_configurator_support.md) section.
+If you would like to enhance your keyboard's support in the QMK Compiler API head over to the [Keyboard Support](reference_configurator_support) section.
## Backend Developers
-If you are interested in working on the API itself you should start by setting up a [Development Environment](api_development_environment.md), then check out [Hacking On The API](api_development_overview.md).
+If you are interested in working on the API itself you should start by setting up a [Development Environment](api_development_environment), then check out [Hacking On The API](api_development_overview).
diff --git a/docs/audio_driver.md b/docs/audio_driver.md
deleted file mode 100644
index 03c0a824df..0000000000
--- a/docs/audio_driver.md
+++ /dev/null
@@ -1,237 +0,0 @@
-# Audio Driver :id=audio-driver
-
-The [Audio feature](feature_audio.md) 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 :id=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 :id=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 | GPTD6Tim6 | GPTD7
Tim7 | GPTD8
Tim8 | PWMD11
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: 2 | | | | - | pwm_software | state-update | | | any = :one: | - | pwm hardware | state-update | | | A8 = :one: 3 | - - -1: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet -2: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set -3: TIM1_CH1 = A8 on STM32F103C8, other combinations are possible, see Data-sheet. configured with: AUDIO_PWM_DRIVER and AUDIO_PWM_CHANNEL - - - -### DAC basic :id=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
Tim6 | GPTD7
Tim7 | GPTD8
Tim8 | PWMD11
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: 2 | | | | + | pwm_software | state-update | | | any = :one: | + | pwm hardware | state-update | | | A8 = :one: 3 | + + +1: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet +2: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set +3: 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: + +::: code-group +```c [halconf.h] +#pragma once + +#define HAL_USE_DAC TRUE // [!code focus] +#define HAL_USE_GPT TRUE // [!code focus] + +#include_next
` on a Single Key
-See the [Grave Escape](feature_grave_esc.md) feature.
+See the [Grave Escape](features/grave_esc) feature.
## Eject on Mac OSX
diff --git a/docs/faq_misc.md b/docs/faq_misc.md
index 287ca7711d..133dbcf612 100644
--- a/docs/faq_misc.md
+++ b/docs/faq_misc.md
@@ -1,6 +1,6 @@
# Miscellaneous FAQ
-## How do I test my keyboard? :id=testing
+## How do I test my keyboard? {#testing}
Testing your keyboard is usually pretty straightforward. Press every single key and make sure it sends the keys you expect. You can use [QMK Configurator](https://config.qmk.fm/#/test/)'s test mode to check your keyboard, even if it doesn't run QMK.
diff --git a/docs/feature_advanced_keycodes.md b/docs/feature_advanced_keycodes.md
index 171243301d..a6f8bc8372 100644
--- a/docs/feature_advanced_keycodes.md
+++ b/docs/feature_advanced_keycodes.md
@@ -1,32 +1,43 @@
-# Modifier Keys :id=modifier-keys
+# Modifier Keys {#modifier-keys}
These allow you to combine a modifier with a keycode. When pressed, the keydown event for the modifier, then `kc` will be sent. On release, the keyup event for `kc`, then the modifier will be sent.
-|Key |Aliases |Description |
-|----------|----------------------------------|------------------------------------------------------|
-|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
-|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
-|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
-|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)` |Hold Left GUI and press `kc` |
-|`RCTL(kc)`| |Hold Right Control and press `kc` |
-|`RSFT(kc)`| |Hold Right Shift and press `kc` |
-|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
-|`RGUI(kc)`|`RCMD(kc)`, `LWIN(kc)` |Hold Right GUI and press `kc` |
-|`LSG(kc)` |`SGUI(kc)`, `SCMD(kc)`, `SWIN(kc)`|Hold Left Shift and GUI and press `kc` |
-|`LAG(kc)` | |Hold Left Alt and Left GUI and press `kc` |
-|`RSG(kc)` | |Hold Right Shift and Right GUI and press `kc` |
-|`RAG(kc)` | |Hold Right Alt and Right GUI and press `kc` |
-|`LCA(kc)` | |Hold Left Control and Alt and press `kc` |
-|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` |
-|`RSA(kc)` |`SAGR(kc)` |Hold Right Shift and Right Alt (AltGr) and press `kc` |
-|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` |
-|`LCAG(kc)`| |Hold Left Control, Alt and GUI and press `kc` |
-|`MEH(kc)` | |Hold Left Control, Shift and Alt and press `kc` |
-|`HYPR(kc)`| |Hold Left Control, Shift, Alt and GUI and press `kc` |
+|Key |Aliases |Description |
+|----------|-------------------------------|-------------------------------------------------------------------------------|
+|`LCTL(kc)`|`C(kc)` |Hold Left Control and press `kc` |
+|`LSFT(kc)`|`S(kc)` |Hold Left Shift and press `kc` |
+|`LALT(kc)`|`A(kc)`, `LOPT(kc)` |Hold Left Alt and press `kc` |
+|`LGUI(kc)`|`G(kc)`, `LCMD(kc)`, `LWIN(kc)`|Hold Left GUI and press `kc` |
+|`LCS(kc)` | |Hold Left Control and Left Shift and press `kc` |
+|`LCA(kc)` | |Hold Left Control and Left Alt and press `kc` |
+|`LCG(kc)` | |Hold Left Control and Left GUI and press `kc` |
+|`LSA(kc)` | |Hold Left Shift and Left Alt and press `kc` |
+|`LSG(kc)` | |Hold Left Shift and Left GUI and press `kc` |
+|`LAG(kc)` | |Hold Left Alt and Left GUI and press `kc` |
+|`LCSG(kc)`| |Hold Left Control, Left Shift and Left GUI and press `kc` |
+|`LCAG(kc)`| |Hold Left Control, Left Alt and Left GUI and press `kc` |
+|`LSAG(kc)`| |Hold Left Shift, Left Alt and Left GUI and press `kc` |
+|`RCTL(kc)`| |Hold Right Control and press `kc` |
+|`RSFT(kc)`| |Hold Right Shift and press `kc` |
+|`RALT(kc)`|`ROPT(kc)`, `ALGR(kc)` |Hold Right Alt and press `kc` |
+|`RGUI(kc)`|`RCMD(kc)`, `RWIN(kc)` |Hold Right GUI and press `kc` |
+|`RCA(kc)` | |Hold Right Control and Right Alt and press `kc` |
+|`RCS(kc)` | |Hold Right Control and Right Shift and press `kc` |
+|`RCG(kc)` | |Hold Right Control and Right GUI and press `kc` |
+|`RSA(kc)` | |Hold Right Shift and Right Alt and press `kc` |
+|`RSG(kc)` | |Hold Right Shift and Right GUI and press `kc` |
+|`RAG(kc)` | |Hold Right Alt and Right GUI and press `kc` |
+|`RCSG(kc)`| |Hold Right Control, Right Shift and Right GUI and press `kc` |
+|`RCAG(kc)`| |Hold Right Control, Right Alt and Right GUI and press `kc` |
+|`RSAG(kc)`| |Hold Right Shift, Right Alt and Right GUI and press `kc` |
+|`MEH(kc)` | |Hold Left Control, Left Shift and Left Alt and press `kc` |
+|`HYPR(kc)`| |Hold Left Control, Left Shift, Left Alt and Left GUI and press `kc`1|
-You can also chain them, for example `LCTL(LALT(KC_DEL))` or `C(A(KC_DEL))` makes a key that sends Control+Alt+Delete with a single keypress.
+1. More information on the Hyper key can be found on [this blog post by Brett Terpstra](https://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/).
-# Checking Modifier State :id=checking-modifier-state
+You can also chain them, for example `LCTL(LALT(KC_DEL))`, `C(A(KC_DEL))`, or `LCA(KC_DEL)` all make a key that sends Control+Alt+Delete with a single keypress.
+
+# Checking Modifier State {#checking-modifier-state}
The current modifier state can mainly be accessed with two functions: `get_mods()` for normal modifiers and modtaps and `get_oneshot_mods()` for one-shot modifiers (unless they're held, in which case they act like normal modifier keys).
@@ -35,7 +46,7 @@ The presence of one or more specific modifiers in the current modifier state can
Thus, to give an example, `01000010` would be the internal representation of LShift+RAlt.
For more information on bitwise operators in C, click [here](https://en.wikipedia.org/wiki/Bitwise_operations_in_C) to open the Wikipedia page on the topic.
-In practice, this means that you can check whether a given modifier is active with `get_mods() & MOD_BIT(KC_Useful for 128x64 displays centered on a 132x64 SH1106 IC. | -|`OLED_DISPLAY_CLOCK` |`0x80` |Set the display clock divide ratio/oscillator frequency. | -|`OLED_FONT_H` |`"glcdfont.c"` |The font code file to use for custom fonts | -|`OLED_FONT_START` |`0` |The starting character index for custom fonts | -|`OLED_FONT_END` |`223` |The ending character index for custom fonts | -|`OLED_FONT_WIDTH` |`6` |The font width | -|`OLED_FONT_HEIGHT` |`8` |The font height (untested) | -|`OLED_IC` |`OLED_IC_SSD1306` |Set to `OLED_IC_SH1106` or `OLED_IC_SH1107` if the corresponding controller chip is used. | -|`OLED_FADE_OUT` |*Not defined* |Enables fade out animation. Use together with `OLED_TIMEOUT`. | -|`OLED_FADE_OUT_INTERVAL` |`0` |The speed of fade out animation, from 0 to 15. Larger values are slower. | -|`OLED_SCROLL_TIMEOUT` |`0` |Scrolls the OLED screen after 0ms of OLED inactivity. Helps reduce OLED Burn-in. Set to 0 to disable. | -|`OLED_SCROLL_TIMEOUT_RIGHT`|*Not defined* |Scroll timeout direction is right when defined, left when undefined. | -|`OLED_TIMEOUT` |`60000` |Turns off the OLED screen after 60000ms of screen update inactivity. Helps reduce OLED Burn-in. Set to 0 to disable. | -|`OLED_UPDATE_INTERVAL` |`0` (`50` for split keyboards) |Set the time interval for updating the OLED display in ms. This will improve the matrix scan rate. | -|`OLED_UPDATE_PROCESS_LIMIT`|`1` |Set the number of dirty blocks to render per loop. Increasing may degrade performance. | - -### I2C Configuration -|Define |Default |Description | -|---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------| -|`OLED_DISPLAY_ADDRESS` |`0x3C` |The i2c address of the OLED Display | - -### SPI Configuration - -|Define |Default |Description | -|---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------| -|`OLED_DC_PIN` | Required |The pin used for the DC connection of the OLED Display. | -|`OLED_CS_PIN` | Required |The pin used for the CS connection of the OLED Display. | -|`OLED_RST_PIN` | *Not defined* |The pin used for the RST connection of the OLED Display (may be left undefined if the RST pin is not connected). | -|`OLED_SPI_MODE` |`3` (default) |The SPI Mode for the OLED Display (not typically changed). | -|`OLED_SPI_DIVISOR` |`2` (default) |The SPI Multiplier to use for the OLED Display. | - -## 128x64 & Custom sized OLED Displays - - The default display size for this feature is 128x32, and the defaults are set with that in mind. However, there are a number of additional presets for common sizes that we have added. You can define one of these values to use the presets. If your display doesn't match one of these presets, you can define `OLED_DISPLAY_CUSTOM` to manually specify all of the values. - -|Define |Default |Description | -|----------------------|---------------|---------------------------------------------------------------------------------------------------------------------------------------| -|`OLED_DISPLAY_128X64` |*Not defined* |Changes the display defines for use with 128x64 displays. | -|`OLED_DISPLAY_64X32` |*Not defined* |Changes the display defines for use with 64x32 displays. | -|`OLED_DISPLAY_64X48` |*Not defined* |Changes the display defines for use with 64x48 displays. | -|`OLED_DISPLAY_64X128` |*Not defined* |Changes the display defines for use with 64x128 displays. | -|`OLED_DISPLAY_128X128`|*Not defined* |Changes the display defines for use with 128x128 displays. | -|`OLED_DISPLAY_CUSTOM` |*Not defined* |Changes the display defines for use with custom displays.
Requires user to implement the below defines. | - -!> 64x128 and 128x128 displays default to the SH1107 IC type, as these heights are not supported by the other IC types. - -|Define |Default |Description | -| --------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------| -|`OLED_DISPLAY_WIDTH` |`128` |The width of the OLED display. | -|`OLED_DISPLAY_HEIGHT`|`32` |The height of the OLED display. | -|`OLED_MATRIX_SIZE` |`512` |The local buffer size to allocate.
`(OLED_DISPLAY_HEIGHT / 8 * OLED_DISPLAY_WIDTH)`. | -|`OLED_BLOCK_TYPE` |`uint16_t` |The unsigned integer type to use for dirty rendering. | -|`OLED_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.
`(sizeof(OLED_BLOCK_TYPE) * 8)`. | -|`OLED_BLOCK_SIZE` |`32` |The size of each block for dirty rendering
`(OLED_MATRIX_SIZE / OLED_BLOCK_COUNT)`. | -|`OLED_COM_PINS` |`COM_PINS_SEQ` |How the SSD1306 chip maps it's memory to display.
Options are `COM_PINS_SEQ`, `COM_PINS_ALT`, `COM_PINS_SEQ_LR`, & `COM_PINS_ALT_LR`.| -|`OLED_COM_PIN_COUNT` |*Not defined* |Number of COM pins supported by the controller.
If not defined, the value appropriate for the defined `OLED_IC` is used. | -|`OLED_COM_PIN_OFFSET`|`0` |Number of the first COM pin used by the OLED matrix. | -|`OLED_SOURCE_MAP` |`{ 0, ... N }` |Precalculated source array to use for mapping source buffer to target OLED memory in 90 degree rendering. | -|`OLED_TARGET_MAP` |`{ 24, ... N }`|Precalculated target array to use for mapping source buffer to target OLED memory in 90 degree rendering. | - -### 90 Degree Rotation - Technical Mumbo Jumbo - -```c -// OLED Rotation enum values are flags -typedef enum { - OLED_ROTATION_0 = 0, - OLED_ROTATION_90 = 1, - OLED_ROTATION_180 = 2, - OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180 -} oled_rotation_t; -``` - -OLED displays driven by SSD1306, SH1106 or SH1107 drivers only natively support in hardware 0 degree and 180 degree rendering. This feature is done in software and not free. Using this feature will increase the time to calculate what data to send over i2c to the OLED. If you are strapped for cycles, this can cause keycodes to not register. In testing however, the rendering time on an ATmega32U4 board only went from 2ms to 5ms and keycodes not registering was only noticed once we hit 15ms. - -90 degree rotation is achieved by using bitwise operations to rotate each 8 block of memory and uses two precalculated arrays to remap buffer memory to OLED memory. The memory map defines are precalculated for remap performance and are calculated based on the display height, width, and block size. For example, in the 128x32 implementation with a `uint8_t` block type, we have a 64 byte block size. This gives us eight 8 byte blocks that need to be rotated and rendered. The OLED renders horizontally two 8 byte blocks before moving down a page, e.g: - -| | | | | | | -|---|---|---|---|---|---| -| 0 | 1 | | | | | -| 2 | 3 | | | | | -| 4 | 5 | | | | | -| 6 | 7 | | | | | - -However the local buffer is stored as if it was Height x Width display instead of Width x Height, e.g: - -| | | | | | | -|---|---|---|---|---|---| -| 3 | 7 | | | | | -| 2 | 6 | | | | | -| 1 | 5 | | | | | -| 0 | 4 | | | | | - -So those precalculated arrays just index the memory offsets in the order in which each one iterates its data. - -Rotation on SH1106 and SH1107 is noticeably less efficient than on SSD1306, because these controllers do not support the “horizontal addressing mode”, which allows transferring the data for the whole rotated block at once; instead, separate address setup commands for every page in the block are required. The screen refresh time for SH1107 is therefore about 45% higher than for a same size screen with SSD1306 when using STM32 MCUs (on AVR the slowdown is about 20%, because the code which actually rotates the bitmap consumes more time). - -## OLED API - -```c -// OLED Rotation enum values are flags -typedef enum { - OLED_ROTATION_0 = 0, - OLED_ROTATION_90 = 1, - OLED_ROTATION_180 = 2, - OLED_ROTATION_270 = 3, // OLED_ROTATION_90 | OLED_ROTATION_180 -} oled_rotation_t; - -// Initialize the oled display, rotating the rendered output based on the define passed in. -// Returns true if the OLED was initialized successfully -bool oled_init(oled_rotation_t rotation); - -// Called at the start of oled_init, weak function overridable by the user -// rotation - the value passed into oled_init -// Return new oled_rotation_t if you want to override default rotation -oled_rotation_t oled_init_kb(oled_rotation_t rotation); -oled_rotation_t oled_init_user(oled_rotation_t rotation); - -// Send commands/data to screen -bool oled_send_cmd(const uint8_t *data, uint16_t size); -bool oled_send_cmd_P(const uint8_t *data, uint16_t size); -bool oled_send_data(const uint8_t *data, uint16_t size); - -// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering -void oled_clear(void); - -// Alias to oled_render_dirty to avoid a change in api. -#define oled_render() oled_render_dirty(false) - -// Renders all dirty blocks to the display at one time or a subset depending on the value of -// all. -void oled_render_dirty(bool all); - -// Moves cursor to character position indicated by column and line, wraps if out of bounds -// Max column denoted by 'oled_max_chars()' and max lines by 'oled_max_lines()' functions -void oled_set_cursor(uint8_t col, uint8_t line); - -// Advances the cursor to the next page, writing ' ' if true -// Wraps to the beginning when out of bounds -void oled_advance_page(bool clearPageRemainder); - -// Moves the cursor forward 1 character length -// Advance page if there is not enough room for the next character -// Wraps to the beginning when out of bounds -void oled_advance_char(void); - -// Writes a single character to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -// Main handler that writes character data to the display buffer -void oled_write_char(const char data, bool invert); - -// Writes a string to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -void oled_write(const char *data, bool invert); - -// Writes a string to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -// Advances the cursor to the next page, wiring ' ' to the remainder of the current page -void oled_write_ln(const char *data, bool invert); - -// Pans the buffer to the right (or left by passing true) by moving contents of the buffer -// Useful for moving the screen in preparation for new drawing -void oled_pan(bool left); - -// Returns a pointer to the requested start index in the buffer plus remaining -// buffer length as struct -oled_buffer_reader_t oled_read_raw(uint16_t start_index); - -// Writes a string to the buffer at current cursor position -void oled_write_raw(const char *data, uint16_t size); - -// Writes a single byte into the buffer at the specified index -void oled_write_raw_byte(const char data, uint16_t index); - -// Sets a specific pixel on or off -// Coordinates start at top-left and go right and down for positive x and y -void oled_write_pixel(uint8_t x, uint8_t y, bool on); - -#if defined(__AVR__) -// Writes a PROGMEM string to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -// Remapped to call 'void oled_write(const char *data, bool invert);' on ARM -void oled_write_P(const char *data, bool invert); - -// Writes a PROGMEM string to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -// Advances the cursor to the next page, wiring ' ' to the remainder of the current page -// Remapped to call 'void oled_write_ln(const char *data, bool invert);' on ARM -void oled_write_ln_P(const char *data, bool invert); - -// Writes a PROGMEM string to the buffer at current cursor position -void oled_write_raw_P(const char *data, uint16_t size); -#else -# define oled_write_P(data, invert) oled_write(data, invert) -# define oled_write_ln_P(data, invert) oled_write_ln(data, invert) -# define oled_write_raw_P(data, size) oled_write_raw(data, size) -#endif // defined(__AVR__) - -// Can be used to manually turn on the screen if it is off -// Returns true if the screen was on or turns on -bool oled_on(void); - -// Can be used to manually turn off the screen if it is on -// Returns true if the screen was off or turns off -bool oled_off(void); - -// Returns true if the oled is currently on, false if it is -// not -bool is_oled_on(void); - -// Sets the brightness level of the display -uint8_t oled_set_brightness(uint8_t level); - -// Gets the current brightness level of the display -uint8_t oled_get_brightness(void); - -// Basically it's oled_render, but with timeout management and oled_task_user calling! -void oled_task(void); - -// Called at the start of oled_task, weak function overridable by the user -bool oled_task_kb(void); -bool oled_task_user(void); - -// Set the specific 8 lines rows of the screen to scroll. -// 0 is the default for start, and 7 for end, which is the entire -// height of the screen. For 128x32 screens, rows 4-7 are not used. -void oled_scroll_set_area(uint8_t start_line, uint8_t end_line); - -// Sets scroll speed, 0-7, fastest to slowest. Default is three. -// Does not take effect until scrolling is either started or restarted -// the ssd1306 supports 8 speeds with the delay -// listed below between each frame of the scrolling effect -// 0=2, 1=3, 2=4, 3=5, 4=25, 5=64, 6=128, 7=256 -void oled_scroll_set_speed(uint8_t speed); - -// Begin scrolling the entire display right -// Returns true if the screen was scrolling or starts scrolling -// NOTE: display contents cannot be changed while scrolling -bool oled_scroll_right(void); - -// Begin scrolling the entire display left -// Returns true if the screen was scrolling or starts scrolling -// NOTE: display contents cannot be changed while scrolling -bool oled_scroll_left(void); - -// Turns off display scrolling -// Returns true if the screen was not scrolling or stops scrolling -bool oled_scroll_off(void); - -// Returns true if the oled is currently scrolling, false if it is -// not -bool is_oled_scrolling(void); - -// Inverts the display -// Returns true if the screen was or is inverted -bool oled_invert(bool invert); - -// Returns the maximum number of characters that will fit on a line -uint8_t oled_max_chars(void); - -// Returns the maximum number of lines that will fit on the OLED -uint8_t oled_max_lines(void); -``` - -!> Scrolling is unsupported on the SH1106 and SH1107. - -!> Scrolling does not work properly on the SSD1306 if the display width is smaller than 128. - -## SSD1306.h Driver Conversion Guide - -|Old API |Recommended New API | -|-------------------------|---------------------------------| -|`struct CharacterMatrix` |*removed - delete all references*| -|`iota_gfx_init` |`oled_init` | -|`iota_gfx_on` |`oled_on` | -|`iota_gfx_off` |`oled_off` | -|`iota_gfx_flush` |`oled_render` | -|`iota_gfx_write_char` |`oled_write_char` | -|`iota_gfx_write` |`oled_write` | -|`iota_gfx_write_P` |`oled_write_P` | -|`iota_gfx_clear_screen` |`oled_clear` | -|`matrix_clear` |*removed - delete all references*| -|`matrix_write_char_inner`|`oled_write_char` | -|`matrix_write_char` |`oled_write_char` | -|`matrix_write` |`oled_write` | -|`matrix_write_ln` |`oled_write_ln` | -|`matrix_write_P` |`oled_write_P` | -|`matrix_write_ln_P` |`oled_write_ln_P` | -|`matrix_render` |`oled_render` | -|`iota_gfx_task` |`oled_task` | -|`iota_gfx_task_user` |`oled_task_user` | diff --git a/docs/feature_os_detection.md b/docs/feature_os_detection.md deleted file mode 100644 index a50ee7ccc2..0000000000 --- a/docs/feature_os_detection.md +++ /dev/null @@ -1,130 +0,0 @@ -# OS Detection - -This feature makes a best guess at the host OS based on OS specific behavior during USB setup. It may not always get the correct OS, and shouldn't be relied on as for critical functionality. - -Using it you can have OS specific key mappings or combos which work differently on different devices. - -It is available for keyboards which use ChibiOS, LUFA and V-USB. - -## Usage - -In your `rules.mk` add: - -```make -OS_DETECTION_ENABLE = yes -``` - -It will automatically include the required headers file. -It declares `os_variant_t detected_host_os(void);` which you can call to get detected OS. - -It returns one of the following values: - -```c -enum { - OS_UNSURE, - OS_LINUX, - OS_WINDOWS, - OS_MACOS, - OS_IOS, -} os_variant_t; -``` - -?> Note that it takes some time after firmware is booted to detect the OS. -This time is quite short, probably hundreds of milliseconds, but this data may be not ready in keyboard and layout setup functions which run very early during firmware startup. - -## Callbacks :id=callbacks - -If you want to perform custom actions when the OS is detected, then you can use the `process_detected_host_os_kb` function on the keyboard level source file, or `process_detected_host_os_user` function in the user `keymap.c`. - -```c -bool process_detected_host_os_kb(os_variant_t detected_os) { - if (!process_detected_host_os_user(detected_os)) { - return false; - } - switch (detected_os) { - case OS_MACOS: - case OS_IOS: - rgb_matrix_set_color_all(RGB_WHITE); - break; - case OS_WINDOWS: - rgb_matrix_set_color_all(RGB_BLUE); - break; - case OS_LINUX: - rgb_matrix_set_color_all(RGB_ORANGE); - break; - case OS_UNSURE: - rgb_matrix_set_color_all(RGB_RED); - break; - } - - return true; -} -``` - -## OS detection stability - -The OS detection is currently handled while the USB device descriptor is being assembled. -The process is done in steps, generating a number of intermediate results until it stabilizes. -We therefore resort to debouncing the result until it has been stable for a given amount of milliseconds. -This amount can be configured, in case your board is not stable within the default debouncing time of 200ms. - -## KVM and USB switches - -Some KVM and USB switches may not trigger the USB controller on the keyboard to fully reset upon switching machines. -If your keyboard does not redetect the OS in this situation, you can force the keyboard to reset when the USB initialization event is detected, forcing the USB controller to be reconfigured. - -## Configuration Options - -* `#define OS_DETECTION_DEBOUNCE 200` - * defined the debounce time for OS detection, in milliseconds -* `#define OS_DETECTION_KEYBOARD_RESET` - * enables the keyboard reset upon a USB device reinitilization, such as switching devices on some KVMs - -## Debug - -If OS is guessed incorrectly, you may want to collect data about USB setup packets to refine the detection logic. - -To do so in your `config.h` add: - -```c -#define OS_DETECTION_DEBUG_ENABLE -``` - -And in your `rules.mk` add: - -```make -CONSOLE_ENABLE = yes -``` - -And also include `"os_detection.h"` in your `keymap.c`. - -Then you can define custom keycodes to store data about USB setup packets in EEPROM (persistent memory) and to print it later on host where you can run `qmk console`: - -```c -enum custom_keycodes { - STORE_SETUPS = SAFE_RANGE, - PRINT_SETUPS, -}; - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case STORE_SETUPS: - if (record->event.pressed) { - store_setups_in_eeprom(); - } - return false; - case PRINT_SETUPS: - if (record->event.pressed) { - print_stored_setups(); - } - return false; - } -} -``` - -Then please open an issue on Github with this information and tell what OS was not detected correctly and if you have any intermediate devices between keyboard and your computer. - - -## Credits - -Original idea is coming from [FingerprintUSBHost](https://github.com/keyboardio/FingerprintUSBHost) project. diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md deleted file mode 100644 index f55b308286..0000000000 --- a/docs/feature_pointing_device.md +++ /dev/null @@ -1,916 +0,0 @@ -# Pointing Device :id=pointing-device - -Pointing Device is a generic name for a feature intended to be generic: moving the system pointer around. There are certainly other options for it - like mousekeys - but this aims to be easily modifiable and hardware driven. You can implement custom keys to control functionality, or you can gather information from other peripherals and insert it directly here - let QMK handle the processing for you. - -To enable Pointing Device, add the following line in your rules.mk and specify one of the driver options below. - -```make -POINTING_DEVICE_ENABLE = yes -``` - -## Sensor Drivers - -There are a number of sensors that are supported by default. Note that only one sensor can be enabled by `POINTING_DEVICE_DRIVER` at a time. If you need to enable more than one sensor, then you need to implement it manually, using the `custom` driver. - -### ADNS 5050 Sensor - -To use the ADNS 5050 sensor, add this to your `rules.mk` - -```make -POINTING_DEVICE_DRIVER = adns5050 -``` - -The ADNS 5050 sensor uses a serial type protocol for communication, and requires an additional light source. - -| Setting (`config.h`) | Description | Default | -| -------------------- | ------------------------------------------------------------------ | -------------------------- | -| `ADNS5050_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor. | `POINTING_DEVICE_SCLK_PIN` | -| `ADNS5050_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor. | `POINTING_DEVICE_SDIO_PIN` | -| `ADNS5050_CS_PIN` | (Required) The pin connected to the Chip Select pin of the sensor. | `POINTING_DEVICE_CS_PIN` | - - - -The CPI range is 125-1375, in increments of 125. Defaults to 500 CPI. - -### ADNS 9800 Sensor - -To use the ADNS 9800 sensor, add this to your `rules.mk` - -```make -POINTING_DEVICE_DRIVER = adns9800 -``` - -The ADNS 9800 is an SPI driven optical sensor, that uses laser output for surface tracking. - -| Setting (`config.h`) | Description | Default | -| ----------------------- | ---------------------------------------------------------------------- | ------------------------ | -| `ADNS9800_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `2000000` | -| `ADNS9800_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` | -| `ADNS9800_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `3` | -| `ADNS9800_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ | -| `ADNS9800_CS_PIN` | (Required) Sets the Chip Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | - - -The CPI range is 800-8200, in increments of 200. Defaults to 1800 CPI. - -### Analog Joystick - -To use an analog joystick to control the pointer, add this to your `rules.mk` - -```make -POINTING_DEVICE_DRIVER = analog_joystick -``` - -The Analog Joystick is an analog (ADC) driven sensor. There are a variety of joysticks that you can use for this. - -| Setting (`config.h`) | Description | Default | -| --------------------------------- | -------------------------------------------------------------------------- | ------------- | -| `ANALOG_JOYSTICK_X_AXIS_PIN` | (Required) The pin used for the vertical/X axis. | _not defined_ | -| `ANALOG_JOYSTICK_Y_AXIS_PIN` | (Required) The pin used for the horizontal/Y axis. | _not defined_ | -| `ANALOG_JOYSTICK_AXIS_MIN` | (Optional) Sets the lower range to be considered movement. | `0` | -| `ANALOG_JOYSTICK_AXIS_MAX` | (Optional) Sets the upper range to be considered movement. | `1023` | -| `ANALOG_JOYSTICK_AUTO_AXIS` | (Optional) Sets ranges to be considered movement automatically. | _not defined_ | -| `ANALOG_JOYSTICK_SPEED_REGULATOR` | (Optional) The divisor used to slow down movement. (lower makes it faster) | `20` | -| `ANALOG_JOYSTICK_READ_INTERVAL` | (Optional) The interval in milliseconds between reads. | `10` | -| `ANALOG_JOYSTICK_SPEED_MAX` | (Optional) The maximum value used for motion. | `2` | -| `ANALOG_JOYSTICK_CLICK_PIN` | (Optional) The pin wired up to the press switch of the analog stick. | _not defined_ | -| `ANALOG_JOYSTICK_WEIGHTS` | (Optional) Use custom weights for lever positions. | _not defined_ | -| `ANALOG_JOYSTICK_CUTOFF` | (Optional) Cut off movement when joystick returns to start position. | _not defined_ | - -If `ANALOG_JOYSTICK_AUTO_AXIS` is used, then `ANALOG_JOYSTICK_AXIS_MIN` and `ANALOG_JOYSTICK_AXIS_MAX` are ignored. - -By default analog joystick implementation uses `x^2` weighting for lever positions. `ANALOG_JOYSTICK_WEIGHTS` allows to experiment with different configurations that might feel better. - -E.g. This is weights for `((x-0.4)^3+0.064)/0.282`: - -```c -#define ANALOG_JOYSTICK_WEIGHTS {0,2,4,5,7,8,9,10,12,13,14,15,15,16,17,18,18,19,19,20,20,21,21,21,22,22,22,22,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,23,24,24,24,24,24,24,25,25,25,26,26,26,27,28,28,29,29,30,31,32,33,34,35,36,37,38,40,41,43,44,46,48,49,51,53,56,58,60,62,65,68,70,73,76,79,82,85,89,92,96,100} -``` - -You can use following JS code to generate weights for different formulas: - -```js -JSON.stringify(Array.from(Array(101).keys()).map(x => Math.ceil((((x/100-0.4)**3+0.064)/0.282*100)))) -``` - -### Azoteq IQS5XX Trackpad - -To use a Azoteq IQS5XX trackpad, add this to your `rules.mk`: - -```make -POINTING_DEVICE_DRIVER = azoteq_iqs5xx -``` - -This supports the IQS525, IQS550 and IQS572 controllers, with the latter two being used in the TPS43 and TPS65 trackpads. - -#### Device settings - -Specific device profiles are provided which set the required values for dimensions and resolution. - -| Setting | Description | -| -------------------------------- | ---------------------------------------------------------- | -| `AZOTEQ_IQS5XX_TPS43` | (Pick One) Sets resolution/mm to TPS43 specifications. | -| `AZOTEQ_IQS5XX_TPS65` | (Pick One) Sets resolution/mm to TPS65 specifications. | - -?> If using one of the above defines you can skip to gesture settings. - -| Setting | Description | Default | -| -------------------------------- | ---------------------------------------------------------- | ------------- | -| `AZOTEQ_IQS5XX_WIDTH_MM` | (Required) Width of the trackpad sensor in millimeters. | _not defined_ | -| `AZOTEQ_IQS5XX_HEIGHT_MM` | (Required) Height of the trackpad sensor in millimeters. | _not defined_ | -| `AZOTEQ_IQS5XX_RESOLUTION_X` | (Optional) Specify X resolution for CPI calculation. | _not defined_ | -| `AZOTEQ_IQS5XX_RESOLUTION_Y` | (Optional) Specify Y resolution for CPI calculation. | _not defined_ | - -**`AZOTEQ_IQS5XX_RESOLUTION_X/Y`** fall back resolutions are provided within the driver based on controller model. - -| I2C Setting | Description | Default | -| ------------------------- | ------------------------------------------------------------------------------- | ------- | -| `AZOTEQ_IQS5XX_ADDRESS` | (Optional) Sets the I2C Address for the Azoteq trackpad | `0xE8` | -| `AZOTEQ_IQS5XX_TIMEOUT_MS`| (Optional) The timeout for i2c communication with in milliseconds. | `10` | - -#### Gesture settings - -| Setting | Description | Default | -| ----------------------------------------- | ------------------------------------------------------------------------------------ | ----------- | -| `AZOTEQ_IQS5XX_TAP_ENABLE` | (Optional) Enable single finger tap. (Left click) | `true` | -| `AZOTEQ_IQS5XX_TWO_FINGER_TAP_ENABLE` | (Optional) Enable two finger tap. (Right click) | `true` | -| `AZOTEQ_IQS5XX_PRESS_AND_HOLD_ENABLE` | (Optional) Emulates holding left click to select text. | `false` | -| `AZOTEQ_IQS5XX_SWIPE_X_ENABLE` | (Optional) Enable swipe gestures X+ (Mouse Button 5) / X- (Mouse Button 4) | `false` | -| `AZOTEQ_IQS5XX_SWIPE_Y_ENABLE` | (Optional) Enable swipe gestures Y+ (Mouse Button 3) / Y- (Mouse Button 6) | `false` | -| `AZOTEQ_IQS5XX_ZOOM_ENABLE` | (Optional) Enable zoom gestures Zoom Out (Mouse Button 7) / Zoom In (Mouse Button 8) | `false` | -| `AZOTEQ_IQS5XX_SCROLL_ENABLE` | (Optional) Enable scrolling using two fingers. | `true` | -| `AZOTEQ_IQS5XX_TAP_TIME` | (Optional) Maximum time in ms for tap to be registered. | `150` | -| `AZOTEQ_IQS5XX_TAP_DISTANCE` | (Optional) Maximum deviation in pixels before single tap is no longer valid. | `25` | -| `AZOTEQ_IQS5XX_HOLD_TIME` | (Optional) Minimum time in ms for press and hold. | `300` | -| `AZOTEQ_IQS5XX_SWIPE_INITIAL_TIME` | (Optional) Maximum time to travel initial distance before swipe is registered. | `150` | -| `AZOTEQ_IQS5XX_SWIPE_INITIAL_DISTANCE` | (Optional) Minimum travel in pixels before swipe is registered. | `300` | -| `AZOTEQ_IQS5XX_SWIPE_CONSECUTIVE_TIME` | (Optional) Maximum time to travel consecutive distance before swipe is registered. | `0` | -| `AZOTEQ_IQS5XX_SWIPE_CONSECUTIVE_DISTANCE`| (Optional) Minimum travel in pixels before a consecutive swipe is registered. | `2000` | -| `AZOTEQ_IQS5XX_SCROLL_INITIAL_DISTANCE` | (Optional) Minimum travel in pixels before scroll is registered. | `50` | -| `AZOTEQ_IQS5XX_ZOOM_INITIAL_DISTANCE` | (Optional) Minimum travel in pixels before zoom is registered. | `50` | -| `AZOTEQ_IQS5XX_ZOOM_CONSECUTIVE_DISTANCE` | (Optional) Maximum time to travel zoom distance before zoom is registered. | `25` | - -#### Rotation settings - -| Setting | Description | Default | -| ---------------------------- | ---------------------------------------------------------- | ------------- | -| `AZOTEQ_IQS5XX_ROTATION_90` | (Optional) Configures hardware for 90 degree rotation. | _not defined_ | -| `AZOTEQ_IQS5XX_ROTATION_180` | (Optional) Configures hardware for 180 degree rotation. | _not defined_ | -| `AZOTEQ_IQS5XX_ROTATION_270` | (Optional) Configures hardware for 270 degree rotation. | _not defined_ | - -### Cirque Trackpad - -To use the Cirque Trackpad sensor, add this to your `rules.mk`: - -```make -POINTING_DEVICE_DRIVER = cirque_pinnacle_i2c -``` - -or - -```make -POINTING_DEVICE_DRIVER = cirque_pinnacle_spi -``` - - -This supports the Cirque Pinnacle 1CA027 Touch Controller, which is used in the TM040040, TM035035 and the TM023023 trackpads. These are I2C or SPI compatible, and both configurations are supported. - -#### Common settings - -| Setting | Description | Default | -| ------------------------------------ | ---------------------------------------------------------- | ------------------------------------------- | -| `CIRQUE_PINNACLE_DIAMETER_MM` | (Optional) Diameter of the trackpad sensor in millimeters. | `40` | -| `CIRQUE_PINNACLE_ATTENUATION` | (Optional) Sets the attenuation of the sensor data. | `EXTREG__TRACK_ADCCONFIG__ADC_ATTENUATE_4X` | -| `CIRQUE_PINNACLE_CURVED_OVERLAY` | (Optional) Applies settings tuned for curved overlay. | _not defined_ | -| `CIRQUE_PINNACLE_POSITION_MODE` | (Optional) Mode of operation. | _not defined_ | -| `CIRQUE_PINNACLE_SKIP_SENSOR_CHECK` | (Optional) Skips sensor presence check | _not defined_ | - -**`CIRQUE_PINNACLE_ATTENUATION`** is a measure of how much data is suppressed in regards to sensitivity. The higher the attenuation, the less sensitive the touchpad will be. - -Default attenuation is set to 4X, although if you are using a thicker overlay (such as the curved overlay) you will want a lower attenuation such as 2X. The possible values are: -* `EXTREG__TRACK_ADCCONFIG__ADC_ATTENUATE_4X`: Least sensitive -* `EXTREG__TRACK_ADCCONFIG__ADC_ATTENUATE_3X` -* `EXTREG__TRACK_ADCCONFIG__ADC_ATTENUATE_2X` -* `EXTREG__TRACK_ADCCONFIG__ADC_ATTENUATE_1X`: Most sensitive - -**`CIRQUE_PINNACLE_POSITION_MODE`** can be `CIRQUE_PINNACLE_ABSOLUTE_MODE` or `CIRQUE_PINNACLE_RELATIVE_MODE`. Modes differ in supported features/gestures. - -* `CIRQUE_PINNACLE_ABSOLUTE_MODE`: Reports absolute x, y, z (touch pressure) coordinates and up to 5 hw buttons connected to the trackpad -* `CIRQUE_PINNACLE_RELATIVE_MODE`: Reports x/y deltas, scroll and up to 3 buttons (2 of them can be from taps, see gestures) connected to trackpad. Supports taps on secondary side of split. Saves about 2k of flash compared to absolute mode with all features. - -| I2C Setting | Description | Default | -| ------------------------- | ------------------------------------------------------------------------------- | ------- | -| `CIRQUE_PINNACLE_ADDR` | (Required) Sets the I2C Address for the Cirque Trackpad | `0x2A` | -| `CIRQUE_PINNACLE_TIMEOUT` | (Optional) The timeout for i2c communication with the trackpad in milliseconds. | `20` | - -| SPI Setting | Description | Default | -| ------------------------------ | ---------------------------------------------------------------------- | ------------------------ | -| `CIRQUE_PINNACLE_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `1000000` | -| `CIRQUE_PINNACLE_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` | -| `CIRQUE_PINNACLE_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `1` | -| `CIRQUE_PINNACLE_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ | -| `CIRQUE_PINNACLE_SPI_CS_PIN` | (Required) Sets the Chip Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | - -Default Scaling is 1024. Actual CPI depends on trackpad diameter. - -Also see the `POINTING_DEVICE_TASK_THROTTLE_MS`, which defaults to 10ms when using Cirque Pinnacle, which matches the internal update rate of the position registers (in standard configuration). Advanced configuration for pen/stylus usage might require lower values. - -#### Absolute mode settings - -| Setting | Description | Default | -|-----------------------------------------|-------------------------------------------------------------------------|-------------| -| `CIRQUE_PINNACLE_X_LOWER` | (Optional) The minimum reachable X value on the sensor. | `127` | -| `CIRQUE_PINNACLE_X_UPPER` | (Optional) The maximum reachable X value on the sensor. | `1919` | -| `CIRQUE_PINNACLE_Y_LOWER` | (Optional) The minimum reachable Y value on the sensor. | `63` | -| `CIRQUE_PINNACLE_Y_UPPER` | (Optional) The maximum reachable Y value on the sensor. | `1471` | -| `CIRQUE_PINNACLE_REACHABLE_CALIBRATION` | (Optional) Enable console messages to aide in calibrating above values. | not defined | - -#### Absolute mode gestures - -| Gesture Setting | Description | Default | -| ---------------------------------------------- | ------------------------------------------------------------------------------ | -------------------- | -| `CIRQUE_PINNACLE_TAP_ENABLE` | (Optional) Enable tap to click. This currently only works on the master side. | _not defined_ | -| `CIRQUE_PINNACLE_TAPPING_TERM` | (Optional) Length of time that a touch can be to be considered a tap. | `TAPPING_TERM`/`200` | -| `CIRQUE_PINNACLE_TOUCH_DEBOUNCE` | (Optional) Length of time that a touch can be to be considered a tap. | `TAPPING_TERM`/`200` | - -`POINTING_DEVICE_GESTURES_SCROLL_ENABLE` in this mode enables circular scroll. Touch originating in outer ring can trigger scroll by moving along the perimeter. Near side triggers vertical scroll and far side triggers horizontal scroll. - -Additionally, `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE` is supported in this mode. - -#### Relative mode gestures - -| Gesture Setting (`config.h`) | Description | Default | -| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| `CIRQUE_PINNACLE_TAP_ENABLE` | (Optional) Enable tap to "left click". Works on both sides of a split keyboard. | _not defined_ | -| `CIRQUE_PINNACLE_SECONDARY_TAP_ENABLE` | (Optional) Tap in upper right corner (half of the finger needs to be outside of the trackpad) of the trackpad will result in "right click". `CIRQUE_PINNACLE_TAP_ENABLE` must be enabled. | _not defined_ | - -Tapping term and debounce are not configurable in this mode since it's handled by trackpad internally. - -`POINTING_DEVICE_GESTURES_SCROLL_ENABLE` in this mode enables side scroll. Touch originating on the right side can trigger vertical scroll (IntelliSense trackpad style). - -### PAW 3204 Sensor - -To use the paw 3204 sensor, add this to your `rules.mk` - -```make -POINTING_DEVICE_DRIVER = paw3204 -``` - -The paw 3204 sensor uses a serial type protocol for communication, and requires an additional light source. - -| Setting (`config.h`) | Description | Default | -| -------------------- |--------------------------------------------------------------- | -------------------------- | -| `PAW3204_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor. | `POINTING_DEVICE_SCLK_PIN` | -| `PAW3204_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor. | `POINTING_DEVICE_SDIO_PIN` | - -The CPI range is 400-1600, with supported values of (400, 500, 600, 800, 1000, 1200 and 1600). Defaults to 1000 CPI. - -### Pimoroni Trackball - -To use the Pimoroni Trackball module, add this to your `rules.mk`: - -```make -POINTING_DEVICE_DRIVER = pimoroni_trackball -``` - -The Pimoroni Trackball module is a I2C based breakout board with an RGB enable trackball. - -| Setting (`config.h`) | Description | Default | -| ------------------------------------ | ---------------------------------------------------------------------------------- | ------- | -| `PIMORONI_TRACKBALL_ADDRESS` | (Required) Sets the I2C Address for the Pimoroni Trackball. | `0x0A` | -| `PIMORONI_TRACKBALL_TIMEOUT` | (Optional) The timeout for i2c communication with the trackball in milliseconds. | `100` | -| `PIMORONI_TRACKBALL_SCALE` | (Optional) The multiplier used to generate reports from the sensor. | `5` | -| `PIMORONI_TRACKBALL_DEBOUNCE_CYCLES` | (Optional) The number of scan cycles used for debouncing on the ball press. | `20` | -| `PIMORONI_TRACKBALL_ERROR_COUNT` | (Optional) Specifies the number of read/write errors until the sensor is disabled. | `10` | - -### PMW3320 Sensor - -To use the PMW3320 sensor, add this to your `rules.mk` - -```make -POINTING_DEVICE_DRIVER = pmw3320 -``` - -The PMW3320 sensor uses a serial type protocol for communication, and requires an additional light source (it could work without one, but expect it to be out of service early). - -| Setting | Description | Default | -| ------------------- | ------------------------------------------------------------------- | -------------------------- | -| `PMW3320_SCLK_PIN` | (Required) The pin connected to the clock pin of the sensor. | `POINTING_DEVICE_SCLK_PIN` | -| `PMW3320_SDIO_PIN` | (Required) The pin connected to the data pin of the sensor. | `POINTING_DEVICE_SDIO_PIN` | -| `PMW3320_CS_PIN` | (Required) The pin connected to the cable select pin of the sensor. | `POINTING_DEVICE_CS_PIN` | - -The CPI range is 500-3500, in increments of 250. Defaults to 1000 CPI. - -### PMW 3360 and PMW 3389 Sensor - -This drivers supports both the PMW 3360 and PMW 3389 sensor as well as multiple sensors of the same type _per_ controller, so 2 can be attached at the same side for split keyboards (or unsplit keyboards). - -To use the **PMW 3360** sensor, add this to your `rules.mk` - -```make -POINTING_DEVICE_DRIVER = pmw3360 -``` - -The CPI range is 100-12000, in increments of 100. Defaults to 1600 CPI. - -To use the **PMW 3389** sensor, add this to your `rules.mk` - -```make -POINTING_DEVICE_DRIVER = pmw3389 -``` - -The CPI range is 50-16000, in increments of 50. Defaults to 2000 CPI. - -Both PMW 3360 and PMW 3389 are SPI driven optical sensors, that use a built in IR LED for surface tracking. -If you have different CS wiring on each half you can use `PMW33XX_CS_PIN_RIGHT` or `PMW33XX_CS_PINS_RIGHT` in combination with `PMW33XX_CS_PIN` or `PMW33XX_CS_PINS` to configure both sides independently. If `_RIGHT` values aren't provided, they default to be the same as the left ones. - -| Setting (`config.h`) | Description | Default | -| ---------------------------- | ------------------------------------------------------------------------------------------- | ------------------------ | -| `PMW33XX_CS_PIN` | (Required) Sets the Chip Select pin connected to the sensor. | `POINTING_DEVICE_CS_PIN` | -| `PMW33XX_CS_PINS` | (Alternative) Sets the Chip Select pins connected to multiple sensors. | `{PMW33XX_CS_PIN}` | -| `PMW33XX_CS_PIN_RIGHT` | (Optional) Sets the Chip Select pin connected to the sensor on the right half. | `PMW33XX_CS_PIN` | -| `PMW33XX_CS_PINS_RIGHT` | (Optional) Sets the Chip Select pins connected to multiple sensors on the right half. | `{PMW33XX_CS_PIN_RIGHT}` | -| `PMW33XX_CPI` | (Optional) Sets counts per inch sensitivity of the sensor. | _varies_ | -| `PMW33XX_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `2000000` | -| `PMW33XX_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ | -| `PMW33XX_LIFTOFF_DISTANCE` | (Optional) Sets the lift off distance at run time | `0x02` | -| `ROTATIONAL_TRANSFORM_ANGLE` | (Optional) Allows for the sensor data to be rotated +/- 127 degrees directly in the sensor. | `0` | - -To use multiple sensors, instead of setting `PMW33XX_CS_PIN` you need to set `PMW33XX_CS_PINS` and also handle and merge the read from this sensor in user code. -Note that different (per sensor) values of CPI, speed liftoff, rotational angle or flipping of X/Y is not currently supported. - -```c -// in config.h: -#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 - -``` - -### Custom Driver - -If you have a sensor type that isn't supported above, a custom option is available by adding the following to your `rules.mk` - -```make -POINTING_DEVICE_DRIVER = custom -``` - -Using the custom driver will require implementing the following functions: - -```c -void pointing_device_driver_init(void) {} -report_mouse_t pointing_device_driver_get_report(report_mouse_t mouse_report) { return mouse_report; } -uint16_t pointing_device_driver_get_cpi(void) { return 0; } -void pointing_device_driver_set_cpi(uint16_t cpi) {} -``` - -!> Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/pointing_device_drivers.c`, but there may be cases where it's very specific to the hardware. So these functions are provided, just in case. - -## Common Configuration - -| Setting | Description | Default | -| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| `MOUSE_EXTENDED_REPORT` | (Optional) Enables support for extended mouse reports. (-32767 to 32767, instead of just -127 to 127). | _not defined_ | -| `POINTING_DEVICE_ROTATION_90` | (Optional) Rotates the X and Y data by 90 degrees. | _not defined_ | -| `POINTING_DEVICE_ROTATION_180` | (Optional) Rotates the X and Y data by 180 degrees. | _not defined_ | -| `POINTING_DEVICE_ROTATION_270` | (Optional) Rotates the X and Y data by 270 degrees. | _not defined_ | -| `POINTING_DEVICE_INVERT_X` | (Optional) Inverts the X axis report. | _not defined_ | -| `POINTING_DEVICE_INVERT_Y` | (Optional) Inverts the Y axis report. | _not defined_ | -| `POINTING_DEVICE_MOTION_PIN` | (Optional) If supported, will only read from sensor if pin is active. | _not defined_ | -| `POINTING_DEVICE_MOTION_PIN_ACTIVE_LOW` | (Optional) If defined then the motion pin is active-low. | _varies_ | -| `POINTING_DEVICE_TASK_THROTTLE_MS` | (Optional) Limits the frequency that the sensor is polled for motion. | _not defined_ | -| `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE` | (Optional) Enable inertial cursor. Cursor continues moving after a flick gesture and slows down by kinetic friction. | _not defined_ | -| `POINTING_DEVICE_GESTURES_SCROLL_ENABLE` | (Optional) Enable scroll gesture. The gesture that activates the scroll is device dependent. | _not defined_ | -| `POINTING_DEVICE_CS_PIN` | (Optional) Provides a default CS pin, useful for supporting multiple sensor configs. | _not defined_ | -| `POINTING_DEVICE_SDIO_PIN` | (Optional) Provides a default SDIO pin, useful for supporting multiple sensor configs. | _not defined_ | -| `POINTING_DEVICE_SCLK_PIN` | (Optional) Provides a default SCLK pin, useful for supporting multiple sensor configs. | _not defined_ | - -!> When using `SPLIT_POINTING_ENABLE` the `POINTING_DEVICE_MOTION_PIN` functionality is not supported and `POINTING_DEVICE_TASK_THROTTLE_MS` will default to `1`. Increasing this value will increase transport performance at the cost of possible mouse responsiveness. - -The `POINTING_DEVICE_CS_PIN`, `POINTING_DEVICE_SDIO_PIN`, and `POINTING_DEVICE_SCLK_PIN` provide a convenient way to define a single pin that can be used for an interchangeable sensor config. This allows you to have a single config, without defining each device. Each sensor allows for this to be overridden with their own defines. - -!> Any pointing device with a lift/contact status can integrate inertial cursor feature into its driver, controlled by `POINTING_DEVICE_GESTURES_CURSOR_GLIDE_ENABLE`. e.g. PMW3360 can use Lift_Stat from Motion register. Note that `POINTING_DEVICE_MOTION_PIN` cannot be used with this feature; continuous polling of `get_report()` is needed to generate glide reports. - -## Split Keyboard Configuration - -The following configuration options are only available when using `SPLIT_POINTING_ENABLE` see [data sync options](feature_split_keyboard.md?id=data-sync-options). The rotation and invert `*_RIGHT` options are only used with `POINTING_DEVICE_COMBINED`. If using `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` use the common configuration above to configure your pointing device. - -| Setting | Description | Default | -| ------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------- | -| `POINTING_DEVICE_LEFT` | Pointing device on the left side (Required - pick one only) | _not defined_ | -| `POINTING_DEVICE_RIGHT` | Pointing device on the right side (Required - pick one only) | _not defined_ | -| `POINTING_DEVICE_COMBINED` | Pointing device on both sides (Required - pick one only) | _not defined_ | -| `POINTING_DEVICE_ROTATION_90_RIGHT` | (Optional) Rotates the X and Y data by 90 degrees. | _not defined_ | -| `POINTING_DEVICE_ROTATION_180_RIGHT` | (Optional) Rotates the X and Y data by 180 degrees. | _not defined_ | -| `POINTING_DEVICE_ROTATION_270_RIGHT` | (Optional) Rotates the X and Y data by 270 degrees. | _not defined_ | -| `POINTING_DEVICE_INVERT_X_RIGHT` | (Optional) Inverts the X axis report. | _not defined_ | -| `POINTING_DEVICE_INVERT_Y_RIGHT` | (Optional) Inverts the Y axis report. | _not defined_ | - -!> If there is a `_RIGHT` configuration option or callback, the [common configuration](feature_pointing_device.md?id=common-configuration) option will work for the left. For correct left/right detection you should setup a [handedness option](feature_split_keyboard?id=setting-handedness), `EE_HANDS` is usually a good option for an existing board that doesn't do handedness by hardware. - - -## Callbacks and Functions - -| Function | Description | -| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -| `pointing_device_init_kb(void)` | Callback to allow for keyboard level initialization. Useful for additional hardware sensors. | -| `pointing_device_init_user(void)` | Callback to allow for user level initialization. Useful for additional hardware sensors. | -| `pointing_device_task_kb(mouse_report)` | Callback that sends sensor data, so keyboard code can intercept and modify the data. Returns a mouse report. | -| `pointing_device_task_user(mouse_report)` | Callback that sends sensor data, so user code can intercept and modify the data. Returns a mouse report. | -| `pointing_device_handle_buttons(buttons, pressed, button)` | Callback to handle hardware button presses. Returns a `uint8_t`. | -| `pointing_device_get_cpi(void)` | Gets the current CPI/DPI setting from the sensor, if supported. | -| `pointing_device_set_cpi(uint16_t)` | Sets the CPI/DPI, if supported. | -| `pointing_device_get_report(void)` | Returns the current mouse report (as a `report_mouse_t` data structure). | -| `pointing_device_set_report(mouse_report)` | Sets the mouse report to the assigned `report_mouse_t` data structured passed to the function. | -| `pointing_device_send(void)` | Sends the current mouse report to the host system. Function can be replaced. | -| `has_mouse_report_changed(new_report, old_report)` | Compares the old and new `report_mouse_t` data and returns true only if it has changed. | -| `pointing_device_adjust_by_defines(mouse_report)` | Applies rotations and invert configurations to a raw mouse report. | - - -## Split Keyboard Callbacks and Functions - -The combined functions below are only available when using `SPLIT_POINTING_ENABLE` and `POINTING_DEVICE_COMBINED`. The 2 callbacks `pointing_device_task_combined_*` replace the single sided equivalents above. See the [combined pointing devices example](feature_pointing_device.md?id=combined-pointing-devices) - -| Function | Description | -| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| `pointing_device_set_shared_report(mouse_report)` | Sets the shared mouse report to the assigned `report_mouse_t` data structured passed to the function. | -| `pointing_device_set_cpi_on_side(bool, uint16_t)` | Sets the CPI/DPI of one side, if supported. Passing `true` will set the left and `false` the right | -| `pointing_device_combine_reports(left_report, right_report)` | Returns a combined mouse_report of left_report and right_report (as a `report_mouse_t` data structure) | -| `pointing_device_task_combined_kb(left_report, right_report)` | Callback, so keyboard code can intercept and modify the data. Returns a combined mouse report. | -| `pointing_device_task_combined_user(left_report, right_report)` | Callback, so user code can intercept and modify. Returns a combined mouse report using `pointing_device_combine_reports` | -| `pointing_device_adjust_by_defines_right(mouse_report)` | Applies right side rotations and invert configurations to a raw mouse report. | - - -# Manipulating Mouse Reports - -The report_mouse_t (here "mouseReport") has the following properties: - -* `mouseReport.x` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ to the right, - to the left) on the x axis. -* `mouseReport.y` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ upward, - downward) on the y axis. -* `mouseReport.v` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing vertical scrolling (+ upward, - downward). -* `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left). -* `mouseReport.buttons` - this is a uint8_t in which all 8 bits are used. These bits represent the mouse button state - bit 0 is mouse button 1, and bit 7 is mouse button 8. - -To manually manipulate the mouse reports outside of the `pointing_device_task_*` functions, you can use: - -* `pointing_device_get_report()` - Returns the current report_mouse_t that represents the information sent to the host computer -* `pointing_device_set_report(report_mouse_t mouse_report)` - Overrides and saves the report_mouse_t to be sent to the host computer -* `pointing_device_send()` - Sends the mouse report to the host and zeroes out the report. - -When the mouse report is sent, the x, y, v, and h values are set to 0 (this is done in `pointing_device_send()`, which can be overridden to avoid this behavior). This way, button states persist, but movement will only occur once. For further customization, both `pointing_device_init` and `pointing_device_task` can be overridden. - -Additionally, by default, `pointing_device_send()` will only send a report when the report has actually changed. This prevents it from continuously sending mouse reports, which will keep the host system awake. This behavior can be changed by creating your own `pointing_device_send()` function. - -Also, you use the `has_mouse_report_changed(new_report, old_report)` function to check to see if the report has changed. - -## Examples - -### Custom Mouse Keycode - -In this example, a custom key is used to click the mouse and scroll 127 units vertically and horizontally, then undo all of that when released - because that's a totally useful function. - -```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; -``` - -Recall that the mouse report is set to zero (except the buttons) whenever it is sent, so the scrolling would only occur once in each case. - -### Drag Scroll or Mouse Scroll - -A very common implementation is to use the mouse movement to scroll instead of moving the cursor on the system. This uses the `pointing_device_task_user` callback to intercept and modify the mouse report before it's sent to the host system. - -```c -enum custom_keycodes { - DRAG_SCROLL = SAFE_RANGE, -}; - -bool set_scrolling = false; - -report_mouse_t pointing_device_task_user(report_mouse_t mouse_report) { - if (set_scrolling) { - mouse_report.h = mouse_report.x; - mouse_report.v = mouse_report.y; - mouse_report.x = 0; - mouse_report.y = 0; - } - return mouse_report; -} - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - if (keycode == DRAG_SCROLL && record->event.pressed) { - set_scrolling = !set_scrolling; - } - return true; -} -``` - -This allows you to toggle between scrolling and cursor movement by pressing the DRAG_SCROLL key. - -### Advanced Drag Scroll - -Sometimes, like with the Cirque trackpad, you will run into issues where the scrolling may be too fast. - -Here is a slightly more advanced example of drag scrolling. You will be able to change the scroll speed based on the values in set in `SCROLL_DIVISOR_H` and `SCROLL_DIVISOR_V`. This bit of code is also set up so that instead of toggling the scrolling state with set_scrolling = !set_scrolling, the set_scrolling variable is set directly to record->event.pressed. This way, the drag scrolling will only be active while the DRAG_SCROLL button is held down. - -```c -enum custom_keycodes { - DRAG_SCROLL = SAFE_RANGE, -}; - -bool set_scrolling = false; - -// Modify these values to adjust the scrolling speed -#define SCROLL_DIVISOR_H 8.0 -#define SCROLL_DIVISOR_V 8.0 - -// Variables to store accumulated scroll values -float scroll_accumulated_h = 0; -float scroll_accumulated_v = 0; - -// Function to handle mouse reports and perform drag scrolling -report_mouse_t pointing_device_task_user(report_mouse_t mouse_report) { - // Check if drag scrolling is active - if (set_scrolling) { - // Calculate and accumulate scroll values based on mouse movement and divisors - scroll_accumulated_h += (float)mouse_report.x / SCROLL_DIVISOR_H; - scroll_accumulated_v += (float)mouse_report.y / SCROLL_DIVISOR_V; - - // Assign integer parts of accumulated scroll values to the mouse report - mouse_report.h = (int8_t)scroll_accumulated_h; - mouse_report.v = (int8_t)scroll_accumulated_v; - - // Update accumulated scroll values by subtracting the integer parts - scroll_accumulated_h -= (int8_t)scroll_accumulated_h; - scroll_accumulated_v -= (int8_t)scroll_accumulated_v; - - // Clear the X and Y values of the mouse report - mouse_report.x = 0; - mouse_report.y = 0; - } - return mouse_report; -} - -// Function to handle key events and enable/disable drag scrolling -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case DRAG_SCROLL: - // Toggle set_scrolling when DRAG_SCROLL key is pressed or released - set_scrolling = record->event.pressed; - break; - default: - break; - } - return true; -} - -// Function to handle layer changes and disable drag scrolling when not in AUTO_MOUSE_DEFAULT_LAYER -layer_state_t layer_state_set_user(layer_state_t state) { - // Disable set_scrolling if the current layer is not the AUTO_MOUSE_DEFAULT_LAYER - if (get_highest_layer(state) != AUTO_MOUSE_DEFAULT_LAYER) { - set_scrolling = false; - } - return state; -} - -``` - - -## Split Examples - -The following examples make use the `SPLIT_POINTING_ENABLE` functionality and show how to manipulate the mouse report for a scrolling mode. - -### Single Pointing Device - -The following example will work with either `POINTING_DEVICE_LEFT` or `POINTING_DEVICE_RIGHT` and enables scrolling mode while on a particular layer. - -```c - -static bool scrolling_mode = false; - -layer_state_t layer_state_set_user(layer_state_t state) { - switch (get_highest_layer(state)) { - case _RAISE: // If we're on the _RAISE layer enable scrolling mode - scrolling_mode = true; - pointing_device_set_cpi(2000); - break; - default: - if (scrolling_mode) { // check if we were scrolling before and set disable if so - scrolling_mode = false; - pointing_device_set_cpi(8000); - } - break; - } - return state; -} - -report_mouse_t pointing_device_task_user(report_mouse_t mouse_report) { - if (scrolling_mode) { - mouse_report.h = mouse_report.x; - mouse_report.v = mouse_report.y; - mouse_report.x = 0; - mouse_report.y = 0; - } - return mouse_report; -} -``` - -### Combined Pointing Devices - -The following example requires `POINTING_DEVICE_COMBINED` and sets the left side pointing device to scroll only. - -```c -void keyboard_post_init_user(void) { - pointing_device_set_cpi_on_side(true, 1000); //Set cpi on left side to a low value for slower scrolling. - pointing_device_set_cpi_on_side(false, 8000); //Set cpi on right side to a reasonable value for mousing. -} - -report_mouse_t pointing_device_task_combined_user(report_mouse_t left_report, report_mouse_t right_report) { - left_report.h = left_report.x; - left_report.v = left_report.y; - left_report.x = 0; - left_report.y = 0; - return pointing_device_combine_reports(left_report, right_report); -} -``` - -# Troubleshooting - -If you are having issues with pointing device drivers debug messages can be enabled that will give you insights in the inner workings. To enable these add to your keyboards `config.h` file: - -```c -#define POINTING_DEVICE_DEBUG -``` - -?> The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md). - - ---- -# Automatic Mouse Layer :id=pointing-device-auto-mouse - -When using a pointing device combined with a keyboard the mouse buttons are often kept on a separate layer from the default keyboard layer, which requires pressing or holding a key to change layers before using the mouse. To make this easier and more efficient an additional pointing device feature may be enabled that will automatically activate a target layer as soon as the pointing device is active _(in motion, mouse button pressed etc.)_ and deactivate the target layer after a set time. - -Additionally if any key that is defined as a mouse key is pressed then the layer will be held as long as the key is pressed and the timer will be reset on key release. When a non-mouse key is pressed then the layer is deactivated early _(with some exceptions see below)_. Mod, mod tap, and one shot mod keys are ignored _(i.e. don't hold or activate layer but do not deactivate the layer either)_ when sending a modifier keycode _(e.g. hold for mod tap)_ allowing for mod keys to be used with the mouse without activating the target layer when typing. - -All of the standard layer keys (tap toggling, toggle, toggle on, one_shot, layer tap, layer mod) that activate the current target layer are uniquely handled to ensure they behave as expected _(see layer key table below)_. The target layer that can be changed at any point during by calling the `set_auto_mouse_layer(
-
-Changing the **Hue** cycles around the circle.-Changing the **Saturation** moves between the inner and outer sections of the wheel, affecting the intensity of the color.
-Changing the **Value** sets the overall brightness.
- - - -## Keycodes - -|Key |Aliases |Description | -|-------------------|----------|--------------------------------------------------------------------| -|`RGB_TOG` | |Toggle RGB lighting on or off | -|`RGB_MODE_FORWARD` |`RGB_MOD` |Cycle through modes, reverse direction when Shift is held | -|`RGB_MODE_REVERSE` |`RGB_RMOD`|Cycle through modes in reverse, forward direction when Shift is held| -|`RGB_HUI` | |Increase hue, decrease hue when Shift is held | -|`RGB_HUD` | |Decrease hue, increase hue when Shift is held | -|`RGB_SAI` | |Increase saturation, decrease saturation when Shift is held | -|`RGB_SAD` | |Decrease saturation, increase saturation when Shift is held | -|`RGB_VAI` | |Increase value (brightness), decrease value when Shift is held | -|`RGB_VAD` | |Decrease value (brightness), increase value when Shift is held | -|`RGB_MODE_PLAIN` |`RGB_M_P `|Static (no animation) mode | -|`RGB_MODE_BREATHE` |`RGB_M_B` |Breathing animation mode | -|`RGB_MODE_RAINBOW` |`RGB_M_R` |Rainbow animation mode | -|`RGB_MODE_SWIRL` |`RGB_M_SW`|Swirl animation mode | -|`RGB_MODE_SNAKE` |`RGB_M_SN`|Snake animation mode | -|`RGB_MODE_KNIGHT` |`RGB_M_K` |"Knight Rider" animation mode | -|`RGB_MODE_XMAS` |`RGB_M_X` |Christmas animation mode | -|`RGB_MODE_GRADIENT`|`RGB_M_G` |Static gradient animation mode | -|`RGB_MODE_RGBTEST` |`RGB_M_T` |Red, Green, Blue test animation mode | -|`RGB_MODE_TWINKLE` |`RGB_M_TW`|Twinkle animation mode | - -?> `RGB_*` keycodes cannot be used with functions like `tap_code16(RGB_HUI)` as they're not USB HID keycodes. If you wish to replicate similar behaviour in custom code within your firmware (e.g. inside `encoder_update_user()` or `process_record_user()`), the equivalent [RGB functions](#functions) should be used instead. - - -!> By default, if you have both the RGB Light and the [RGB Matrix](feature_rgb_matrix.md) feature enabled, these keycodes will work for both features, at the same time. You can disable the keycode functionality by defining the `*_DISABLE_KEYCODES` option for the specific feature. - -## Configuration - -Your RGB lighting can be configured by placing these `#define`s in your `config.h`: - -|Define |Default |Description | -|---------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------| -|`RGBLIGHT_HUE_STEP` |`8` |The number of steps to cycle through the hue by | -|`RGBLIGHT_SAT_STEP` |`17` |The number of steps to increment the saturation by | -|`RGBLIGHT_VAL_STEP` |`17` |The number of steps to increment the brightness by | -|`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level | -|`RGBLIGHT_SLEEP` |*Not defined* |If defined, the RGB lighting will be switched off when the host goes to sleep | -|`RGBLIGHT_SPLIT` |*Not defined* |If defined, synchronization functionality for split keyboards is added | -|`RGBLIGHT_DISABLE_KEYCODES`|*Not defined* |If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature| -|`RGBLIGHT_DEFAULT_MODE` |`RGBLIGHT_MODE_STATIC_LIGHT`|The default mode to use upon clearing the EEPROM | -|`RGBLIGHT_DEFAULT_HUE` |`0` (red) |The default hue to use upon clearing the EEPROM | -|`RGBLIGHT_DEFAULT_SAT` |`UINT8_MAX` (255) |The default saturation to use upon clearing the EEPROM | -|`RGBLIGHT_DEFAULT_VAL` |`RGBLIGHT_LIMIT_VAL` |The default value (brightness) to use upon clearing the EEPROM | -|`RGBLIGHT_DEFAULT_SPD` |`0` |The default speed to use upon clearing the EEPROM | -|`RGBLIGHT_DEFAULT_ON` |`true` |Enable RGB lighting upon clearing the EEPROM | - -## Effects and Animations - -Not only can this lighting be whatever color you want, -if `RGBLIGHT_EFFECT_xxxx` is defined, you also have a number of animation modes at your disposal: - -|Mode number symbol |Additional number |Description | -|-----------------------------|-------------------|---------------------------------------| -|`RGBLIGHT_MODE_STATIC_LIGHT` | *None* |Solid color (this mode is always enabled) | -|`RGBLIGHT_MODE_BREATHING` | 0,1,2,3 |Solid color breathing | -|`RGBLIGHT_MODE_RAINBOW_MOOD` | 0,1,2 |Cycling rainbow | -|`RGBLIGHT_MODE_RAINBOW_SWIRL`| 0,1,2,3,4,5 |Swirling rainbow | -|`RGBLIGHT_MODE_SNAKE` | 0,1,2,3,4,5 |Snake | -|`RGBLIGHT_MODE_KNIGHT` | 0,1,2 |Knight | -|`RGBLIGHT_MODE_CHRISTMAS` | *None* |Christmas | -|`RGBLIGHT_MODE_STATIC_GRADIENT`| 0,1,..,9 |Static gradient | -|`RGBLIGHT_MODE_RGB_TEST` | *None* |RGB Test | -|`RGBLIGHT_MODE_ALTERNATING` | *None* |Alternating | -|`RGBLIGHT_MODE_TWINKLE` | 0,1,2,3,4,5 |Twinkle | - -Check out [this video](https://youtube.com/watch?v=VKrpPAHlisY) for a demonstration. - -Note: For versions older than 0.6.117, The mode numbers were written directly. In `quantum/rgblight/rgblight.h` there is a contrast table between the old mode number and the current symbol. - - -### Effect and Animation Toggles - -Use these defines to add or remove animations from the firmware. When you are running low on flash space, it can be helpful to disable animations you are not using. - -|Define |Default |Description | -|------------------------------------|-------------|-------------------------------------------------------------------------| -|`RGBLIGHT_ANIMATIONS` |*Not defined*|Enable all additional animation modes. (deprecated) | -|`RGBLIGHT_EFFECT_ALTERNATING` |*Not defined*|Enable alternating animation mode. | -|`RGBLIGHT_EFFECT_BREATHING` |*Not defined*|Enable breathing animation mode. | -|`RGBLIGHT_EFFECT_CHRISTMAS` |*Not defined*|Enable christmas animation mode. | -|`RGBLIGHT_EFFECT_KNIGHT` |*Not defined*|Enable knight animation mode. | -|`RGBLIGHT_EFFECT_RAINBOW_MOOD` |*Not defined*|Enable rainbow mood animation mode. | -|`RGBLIGHT_EFFECT_RAINBOW_SWIRL` |*Not defined*|Enable rainbow swirl animation mode. | -|`RGBLIGHT_EFFECT_RGB_TEST` |*Not defined*|Enable RGB test animation mode. | -|`RGBLIGHT_EFFECT_SNAKE` |*Not defined*|Enable snake animation mode. | -|`RGBLIGHT_EFFECT_STATIC_GRADIENT` |*Not defined*|Enable static gradient mode. | -|`RGBLIGHT_EFFECT_TWINKLE` |*Not defined*|Enable twinkle animation mode. | - -!> `RGBLIGHT_ANIMATIONS` is being deprecated and animation modes should be explicitly defined. - -### Effect and Animation Settings - -The following options are used to tweak the various animations: - -|Define |Default |Description | -|------------------------------------|--------------------|-----------------------------------------------------------------------------------------------| -|`RGBLIGHT_EFFECT_BREATHE_CENTER` |*Not defined* |If defined, used to calculate the curve for the breathing animation. Valid values are 1.0 to 2.7 | -|`RGBLIGHT_EFFECT_BREATHE_MAX` |`255` |The maximum brightness for the breathing mode. Valid values are 1 to 255 | -|`RGBLIGHT_EFFECT_CHRISTMAS_INTERVAL`|`40` |How long (in milliseconds) to wait between animation steps for the "Christmas" animation | -|`RGBLIGHT_EFFECT_CHRISTMAS_STEP` |`2` |The number of LEDs to group the red/green colors by for the "Christmas" animation | -|`RGBLIGHT_EFFECT_KNIGHT_LED_NUM` |`RGBLIGHT_LED_COUNT`|The number of LEDs to have the "Knight" animation travel | -|`RGBLIGHT_EFFECT_KNIGHT_LENGTH` |`3` |The number of LEDs to light up for the "Knight" animation | -|`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by | -|`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls | -|`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | -|`RGBLIGHT_EFFECT_TWINKLE_LIFE` |`200` |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps) | -|`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127` |Adjusts how likely each LED is to twinkle (on each animation step) | - -### Example Usage to Reduce Memory Footprint - 1. Use `#undef` to selectively disable animations. The following would disable two animations and save about 4KiB: - -```diff - #undef RGBLIGHT_LED_COUNT -+#undef RGBLIGHT_EFFECT_STATIC_GRADIENT -+#undef RGBLIGHT_EFFECT_RAINBOW_SWIRL - #define RGBLIGHT_LED_COUNT 12 - #define RGBLIGHT_HUE_STEP 8 - #define RGBLIGHT_SAT_STEP 8 -``` - -### Animation Speed - -You can also modify the speeds that the different modes animate at: - -Here is a quick demo on Youtube (with NPKC KC60) (https://www.youtube.com/watch?v=VKrpPAHlisY). - -```c -// How long (in milliseconds) to wait between animation steps for each of the "Solid color breathing" animations -const uint8_t RGBLED_BREATHING_INTERVALS[] PROGMEM = {30, 20, 10, 5}; - -// How long (in milliseconds) to wait between animation steps for each of the "Cycling rainbow" animations -const uint8_t RGBLED_RAINBOW_MOOD_INTERVALS[] PROGMEM = {120, 60, 30}; - -// How long (in milliseconds) to wait between animation steps for each of the "Swirling rainbow" animations -const uint8_t RGBLED_RAINBOW_SWIRL_INTERVALS[] PROGMEM = {100, 50, 20}; - -// How long (in milliseconds) to wait between animation steps for each of the "Snake" animations -const uint8_t RGBLED_SNAKE_INTERVALS[] PROGMEM = {100, 50, 20}; - -// How long (in milliseconds) to wait between animation steps for each of the "Knight" animations -const uint8_t RGBLED_KNIGHT_INTERVALS[] PROGMEM = {127, 63, 31}; - -// How long (in milliseconds) to wait between animation steps for each of the "Twinkle" animations -const uint8_t RGBLED_TWINKLE_INTERVALS[] PROGMEM = {50, 25, 10}; - -// These control which hues are selected for each of the "Static gradient" modes -const uint8_t RGBLED_GRADIENT_RANGES[] PROGMEM = {255, 170, 127, 85, 64}; -``` - -## Lighting Layers - -?> **Note:** Lighting Layers is an RGB Light feature, it will not work for RGB Matrix. See [RGB Matrix Indicators](feature_rgb_matrix.md#indicators) for details on how to do so. - -By including `#define RGBLIGHT_LAYERS` in your `config.h` file you can enable lighting layers. These make -it easy to use your underglow LEDs as status indicators to show which keyboard layer is currently active, or the state of caps lock, all without disrupting any animations. [Here's a video](https://youtu.be/uLGE1epbmdY) showing an example of what you can do. - -### Defining Lighting Layers :id=defining-lighting-layers - -By default, 8 layers are possible. This can be expanded to as many as 32 by overriding the definition of `RGBLIGHT_MAX_LAYERS` in `config.h` (e.g. `#define RGBLIGHT_MAX_LAYERS 32`). Please note, if you use a split keyboard, you will need to flash both sides of the split after changing this. Also, increasing the maximum will increase the firmware size, and will slow sync on split keyboards. - -To define a layer, we modify `keymap.c` to list the LED ranges and the colors we want to overlay on them using an array of `rgblight_segment_t` using the `RGBLIGHT_LAYER_SEGMENTS` macro. We can define multiple layers and enable/disable them independently: - -```c -// Light LEDs 6 to 9 and 12 to 15 red when caps lock is active. Hard to ignore! -const rgblight_segment_t PROGMEM my_capslock_layer[] = RGBLIGHT_LAYER_SEGMENTS( - {6, 4, HSV_RED}, // Light 4 LEDs, starting with LED 6 - {12, 4, HSV_RED} // Light 4 LEDs, starting with LED 12 -); -// Light LEDs 9 & 10 in cyan when keyboard layer 1 is active -const rgblight_segment_t PROGMEM my_layer1_layer[] = RGBLIGHT_LAYER_SEGMENTS( - {9, 2, HSV_CYAN} -); -// Light LEDs 11 & 12 in purple when keyboard layer 2 is active -const rgblight_segment_t PROGMEM my_layer2_layer[] = RGBLIGHT_LAYER_SEGMENTS( - {11, 2, HSV_PURPLE} -); -// Light LEDs 13 & 14 in green when keyboard layer 3 is active -const rgblight_segment_t PROGMEM my_layer3_layer[] = RGBLIGHT_LAYER_SEGMENTS( - {13, 2, HSV_GREEN} -); -// etc.. -``` - -We combine these layers into an array using the `RGBLIGHT_LAYERS_LIST` macro, and assign it to the `rgblight_layers` variable during keyboard setup. Note that you can only define up to 8 lighting layers. Any extra layers will be ignored. Since the different lighting layers overlap, the order matters in the array, with later layers taking precedence: - -```c -// Now define the array of layers. Later layers take precedence -const rgblight_segment_t* const PROGMEM my_rgb_layers[] = RGBLIGHT_LAYERS_LIST( - my_capslock_layer, - my_layer1_layer, // Overrides caps lock layer - my_layer2_layer, // Overrides other layers - my_layer3_layer // Overrides other layers -); - -void keyboard_post_init_user(void) { - // Enable the LED layers - rgblight_layers = my_rgb_layers; -} -``` -Note: For split keyboards with two controllers, both sides need to be flashed when updating the contents of rgblight_layers. - -### Enabling and disabling lighting layers :id=enabling-lighting-layers - -Everything above just configured the definition of each lighting layer. -We can now enable and disable the lighting layers whenever the state of the keyboard changes: - -```c -bool led_update_user(led_t led_state) { - rgblight_set_layer_state(0, led_state.caps_lock); - return true; -} - -layer_state_t default_layer_state_set_user(layer_state_t state) { - rgblight_set_layer_state(1, layer_state_cmp(state, _DVORAK)); - return state; -} - -layer_state_t layer_state_set_user(layer_state_t state) { - rgblight_set_layer_state(2, layer_state_cmp(state, _FN)); - rgblight_set_layer_state(3, layer_state_cmp(state, _ADJUST)); - return state; -} -``` - -### Lighting layer blink :id=lighting-layer-blink - -By including `#define RGBLIGHT_LAYER_BLINK` in your `config.h` file you can turn a lighting -layer on for a specified duration. Once the specified number of milliseconds has elapsed -the layer will be turned off. This is useful, e.g., if you want to acknowledge some -action (e.g. toggling some setting): - -```c -const rgblight_segment_t PROGMEM _yes_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_GREEN} ); -const rgblight_segment_t PROGMEM _no_layer[] = RGBLIGHT_LAYER_SEGMENTS( {9, 6, HSV_RED} ); - -const rgblight_segment_t* const PROGMEM _rgb_layers[] = - RGBLIGHT_LAYERS_LIST( _yes_layer, _no_layer ); - -void keyboard_post_init_user(void) { - rgblight_layers = _rgb_layers; -} - -// Note we user post_process_record_user because we want the state -// after the flag has been flipped... -void post_process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case QK_DEBUG_TOGGLE: - rgblight_blink_layer(debug_enable ? 0 : 1, 500); - break; - - case NK_TOGG: - case NK_ON: - case NK_OFF: - rgblight_blink_layer(keymap_config.nkro ? 0 : 1, 500); - break; - } -} -``` - -You can also use `rgblight_blink_layer_repeat` to specify the amount of times the layer is supposed to blink. Using the layers from above, -```c -void post_process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case QK_DEBUG_TOGGLE: - rgblight_blink_layer_repeat(debug_enable ? 0 : 1, 200, 3); - break; - } -} -``` -would turn the layer 0 (or 1) on and off again three times when `DB_TOGG` is pressed. - -Blinking accumulates layers so if multiple layers are set blinking at the same time they will all blink for the duration and repeat times of the last layer to be blinked. -To stop these other layers from blinking use `rgblight_unblink_layer` or `rgblight_unblink_all_but_layer`: - -```c -rgblight_blink_layer(1, 500); -rgblight_unblink_all_but_layer(1); -``` - -```c -rgblight_unblink_layer(3); -rgblight_blink_layer(2, 500); -``` - -!> Lighting layers on split keyboards will require layer state synced to the slave half (e.g. `#define SPLIT_LAYER_STATE_ENABLE`). See [data sync options](feature_split_keyboard.md#data-sync-options) for more details. - -### Overriding RGB Lighting on/off status - -Normally lighting layers are not shown when RGB Lighting is disabled (e.g. with `RGB_TOG` keycode). If you would like lighting layers to work even when the RGB Lighting is otherwise off, add `#define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF` to your `config.h`. - -### Retain brightness - -Usually lighting layers apply their configured brightness once activated. If you would like lighting layers to retain the currently used brightness (as returned by `rgblight_get_val()`), add `#define RGBLIGHT_LAYERS_RETAIN_VAL` to your `config.h`. - -## Functions - -If you need to change your RGB lighting in code, for example in a macro to change the color whenever you switch layers, QMK provides a set of functions to assist you. See [`rgblight.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/rgblight/rgblight.h) for the full list, but the most commonly used functions include: - -### Low level Functions -|Function |Description | -|--------------------------------------------|-------------------------------------------| -|`rgblight_set()` |Flush out led buffers to LEDs | -|`rgblight_set_clipping_range(pos, num)` |Set clipping Range. see [Clipping Range](#clipping-range) | - -### Effects and Animations Functions -#### effect range setting -|Function |Description | -|--------------------------------------------|------------------| -|`rgblight_set_effect_range(pos, num)` |Set Effects Range | - -#### direct operation -|Function |Description | -|--------------------------------------------|-------------| -|`rgblight_setrgb_at(r, g, b, index)` |Set a single LED to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `index` is between 0 and `RGBLIGHT_LED_COUNT` (not written to EEPROM) | -|`rgblight_sethsv_at(h, s, v, index)` |Set a single LED to the given HSV value, where `h`/`s`/`v` are between 0 and 255, and `index` is between 0 and `RGBLIGHT_LED_COUNT` (not written to EEPROM) | -|`rgblight_setrgb_range(r, g, b, start, end)`|Set a continuous range of LEDs to the given RGB value, where `r`/`g`/`b` are between 0 and 255 and `start`(included) and `stop`(excluded) are between 0 and `RGBLIGHT_LED_COUNT` (not written to EEPROM)| -|`rgblight_sethsv_range(h, s, v, start, end)`|Set a continuous range of LEDs to the given HSV value, where `h`/`s`/`v` are between 0 and 255, and `start`(included) and `stop`(excluded) are between 0 and `RGBLIGHT_LED_COUNT` (not written to EEPROM)| -|`rgblight_setrgb(r, g, b)` |Set effect range LEDs to the given RGB value where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | -|`rgblight_setrgb_master(r, g, b)` |Set the LEDs on the master side to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | -|`rgblight_setrgb_slave(r, g, b)` |Set the LEDs on the slave side to the given RGB value, where `r`/`g`/`b` are between 0 and 255 (not written to EEPROM) | -|`rgblight_sethsv_master(h, s, v)` |Set the LEDs on the master side to the given HSV value, where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | -|`rgblight_sethsv_slave(h, s, v)` |Set the LEDs on the slave side to the given HSV value, where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | - -Example: -```c -rgblight_sethsv_at(HSV_WHITE, 0); // led 0 -rgblight_sethsv_at(HSV_RED, 1); // led 1 -rgblight_sethsv_at(HSV_GREEN, 2); // led 2 -// The above functions automatically calls rgblight_set(), so there is no need to call it explicitly. -// Note that it is inefficient to call repeatedly. -``` - -#### effect mode change -|Function |Description | -|--------------------------------------------|-------------| -|`rgblight_mode(x)` |Set the mode, if RGB animations are enabled | -|`rgblight_mode_noeeprom(x)` |Set the mode, if RGB animations are enabled (not written to EEPROM) | -|`rgblight_step()` |Change the mode to the next RGB animation in the list of enabled RGB animations | -|`rgblight_step_noeeprom()` |Change the mode to the next RGB animation in the list of enabled RGB animations (not written to EEPROM) | -|`rgblight_step_reverse()` |Change the mode to the previous RGB animation in the list of enabled RGB animations | -|`rgblight_step_reverse_noeeprom()` |Change the mode to the previous RGB animation in the list of enabled RGB animations (not written to EEPROM) | -|`rgblight_reload_from_eeprom()` |Reload the effect configuration (enabled, mode and color) from EEPROM | - -#### effects mode disable/enable -|Function |Description | -|--------------------------------------------|-------------| -|`rgblight_toggle()` |Toggle effect range LEDs between on and off | -|`rgblight_toggle_noeeprom()` |Toggle effect range LEDs between on and off (not written to EEPROM) | -|`rgblight_enable()` |Turn effect range LEDs on, based on their previous state | -|`rgblight_enable_noeeprom()` |Turn effect range LEDs on, based on their previous state (not written to EEPROM) | -|`rgblight_disable()` |Turn effect range LEDs off | -|`rgblight_disable_noeeprom()` |Turn effect range LEDs off (not written to EEPROM) | - -#### hue, sat, val change -|Function |Description | -|--------------------------------------------|-------------| -|`rgblight_increase_hue()` |Increase the hue for effect range LEDs. This wraps around at maximum hue | -|`rgblight_increase_hue_noeeprom()` |Increase the hue for effect range LEDs. This wraps around at maximum hue (not written to EEPROM) | -|`rgblight_decrease_hue()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue | -|`rgblight_decrease_hue_noeeprom()` |Decrease the hue for effect range LEDs. This wraps around at minimum hue (not written to EEPROM) | -|`rgblight_increase_sat()` |Increase the saturation for effect range LEDs. This stops at maximum saturation | -|`rgblight_increase_sat_noeeprom()` |Increase the saturation for effect range LEDs. This stops at maximum saturation (not written to EEPROM) | -|`rgblight_decrease_sat()` |Decrease the saturation for effect range LEDs. This stops at minimum saturation | -|`rgblight_decrease_sat_noeeprom()` |Decrease the saturation for effect range LEDs. This stops at minimum saturation (not written to EEPROM) | -|`rgblight_increase_val()` |Increase the value for effect range LEDs. This stops at maximum value | -|`rgblight_increase_val_noeeprom()` |Increase the value for effect range LEDs. This stops at maximum value (not written to EEPROM) | -|`rgblight_decrease_val()` |Decrease the value for effect range LEDs. This stops at minimum value | -|`rgblight_decrease_val_noeeprom()` |Decrease the value for effect range LEDs. This stops at minimum value (not written to EEPROM) | -|`rgblight_sethsv(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 | -|`rgblight_sethsv_noeeprom(h, s, v)` |Set effect range LEDs to the given HSV value where `h`/`s`/`v` are between 0 and 255 (not written to EEPROM) | - -#### Speed functions -|Function |Description | -|--------------------------------------------|-------------| -|`rgblight_increase_speed()` |Increases the animation speed | -|`rgblight_increase_speed_noeeprom()` |Increases the animation speed (not written to EEPROM) | -|`rgblight_decrease_speed()` |Decreases the animation speed | -|`rgblight_decrease_speed_noeeprom()` |Decreases the animation speed (not written to EEPROM) | -|`rgblight_set_speed()` |Sets the speed. Value is between 0 and 255 | -|`rgblight_set_speed_noeeprom()` |Sets the speed. Value is between 0 and 255 (not written to EEPROM) | - - -#### layer functions -|Function |Description | -|--------------------------------------------|-------------| -|`rgblight_get_layer_state(i)` |Returns `true` if lighting layer `i` is enabled | -|`rgblight_set_layer_state(i, is_on)` |Enable or disable lighting layer `i` based on value of `bool is_on` | - -#### query -|Function |Description | -|-----------------------|---------------------------| -|`rgblight_is_enabled()`|Gets current on/off status | -|`rgblight_get_mode()` |Gets current mode | -|`rgblight_get_hue()` |Gets current hue | -|`rgblight_get_sat()` |Gets current sat | -|`rgblight_get_val()` |Gets current val | -|`rgblight_get_speed()` |Gets current speed | - -## Colors - -These are shorthands to popular colors. The `RGB` ones can be passed to the `setrgb` functions, while the `HSV` ones to the `sethsv` functions. - -|RGB |HSV | -|---------------------|---------------------| -|`RGB_AZURE` |`HSV_AZURE` | -|`RGB_BLACK`/`RGB_OFF`|`HSV_BLACK`/`HSV_OFF`| -|`RGB_BLUE` |`HSV_BLUE` | -|`RGB_CHARTREUSE` |`HSV_CHARTREUSE` | -|`RGB_CORAL` |`HSV_CORAL` | -|`RGB_CYAN` |`HSV_CYAN` | -|`RGB_GOLD` |`HSV_GOLD` | -|`RGB_GOLDENROD` |`HSV_GOLDENROD` | -|`RGB_GREEN` |`HSV_GREEN` | -|`RGB_MAGENTA` |`HSV_MAGENTA` | -|`RGB_ORANGE` |`HSV_ORANGE` | -|`RGB_PINK` |`HSV_PINK` | -|`RGB_PURPLE` |`HSV_PURPLE` | -|`RGB_RED` |`HSV_RED` | -|`RGB_SPRINGGREEN` |`HSV_SPRINGGREEN` | -|`RGB_TEAL` |`HSV_TEAL` | -|`RGB_TURQUOISE` |`HSV_TURQUOISE` | -|`RGB_WHITE` |`HSV_WHITE` | -|`RGB_YELLOW` |`HSV_YELLOW` | - -```c -rgblight_setrgb(RGB_ORANGE); -rgblight_sethsv_noeeprom(HSV_GREEN); -rgblight_setrgb_at(RGB_GOLD, 3); -rgblight_sethsv_range(HSV_WHITE, 0, 6); -``` - -These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master/quantum/color.h). Feel free to add to this list! - - -## Changing the order of the LEDs - -If you want to make the logical order of LEDs different from the electrical connection order, you can do this by defining the `RGBLIGHT_LED_MAP` macro in your `config.h`. - -Normally, the contents of the LED buffer are output to the LEDs in the same order. -
-
-By defining `RGBLIGHT_LED_MAP` as in the example below, you can specify the LED with addressing in reverse order of the electrical connection order.
-
-```c
-// config.h
-
-#define RGBLIGHT_LED_COUNT 4
-#define RGBLIGHT_LED_MAP { 3, 2, 1, 0 }
-
-```
-
-
-## Clipping Range
-
-Using the `rgblight_set_clipping_range()` function, you can prepare more buffers than the actual number of LEDs, and output some of the buffers to the LEDs. This is useful if you want the split keyboard to treat left and right LEDs as logically contiguous.
-
-You can set the Clipping Range by executing the following code.
-
-```c
-// some source
-rgblight_set_clipping_range(3, 4);
-```
-
-
-In addition to setting the Clipping Range, you can use `RGBLIGHT_LED_MAP` together.
-
-```c
-// config.h
-#define RGBLIGHT_LED_COUNT 8
-#define RGBLIGHT_LED_MAP { 7, 6, 5, 4, 3, 2, 1, 0 }
-
-// some source
-rgblight_set_clipping_range(3, 4);
-```
-
-
-## Hardware Modification
-
-If your keyboard lacks onboard underglow LEDs, you may often be able to solder on an RGB LED strip yourself. You will need to find an unused pin to wire to the data pin of your LED strip. Some keyboards may break out unused pins from the MCU to make soldering easier. The other two pins, VCC and GND, must also be connected to the appropriate power pins.
-
-## Velocikey
-
-Velocikey is a feature that lets you control the speed of lighting effects (like the Rainbow Swirl effect) with the speed of your typing. The faster you type, the faster the lights will go!
-
-### Usage
-For Velocikey to take effect, there are two steps. First, when compiling your keyboard, you'll need to set `VELOCIKEY_ENABLE=yes` in `rules.mk`, e.g.:
-
-```
-MOUSEKEY_ENABLE = no
-STENO_ENABLE = no
-EXTRAKEY_ENABLE = yes
-VELOCIKEY_ENABLE = yes
-```
-
-Then, while using your keyboard, you need to also turn it on with the `VK_TOGG` keycode, which toggles the feature on and off.
-
-The following light effects will all be controlled by Velocikey when it is enabled:
- - RGB Breathing
- - RGB Rainbow Mood
- - RGB Rainbow Swirl
- - RGB Snake
- - RGB Knight
-
-Support for LED breathing effects is planned but not available yet.
-
- As long as Velocikey is enabled, it will control the speed regardless of any other speed setting that your RGB lights are currently on.
-
- ### Configuration
- Velocikey doesn't currently support any configuration via keyboard settings. If you want to adjust something like the speed increase or decay rate, you would need to edit `velocikey.c` and adjust the values there to achieve the kinds of speeds that you like.
diff --git a/docs/feature_secure.md b/docs/feature_secure.md
deleted file mode 100644
index eaa2b601ae..0000000000
--- a/docs/feature_secure.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# Secure
-
-The secure feature aims to prevent unwanted interaction without user intervention.
-
-?> Secure does **not** currently implement encryption/decryption/etc and should not be a replacement where a strong hardware/software based solution is required.
-
-### Unlock sequence
-
-To unlock, the user must perform a set of actions. This can optionally be configured to be multiple keys.
-
-* While unlocking all keyboard input is ignored
-* Incorrect attempts will revert back to the previously locked state
-
-### Automatic Locking
-
-Once unlocked, the keyboard will revert back to a locked state after the configured timeout.
-The timeout can be refreshed by using the `secure_activity_event` function, for example from one of the various [hooks](custom_quantum_functions.md).
-
-## Usage
-
-Add the following to your `rules.mk`:
-
-```make
-SECURE_ENABLE = yes
-```
-
-## Keycodes
-
-| Key |Aliases | Description |
-|---------------------|---------|--------------------------------------------------------------------------------|
-| `QK_SECURE_LOCK` |`SE_LOCK`| Revert back to a locked state |
-| `QK_SECURE_UNLOCK` |`SE_UNLK`| Forces unlock without performing a unlock sequence |
-| `QK_SECURE_TOGGLE` |`SE_TOGG`| Toggle directly between locked and unlock without performing a unlock sequence |
-| `QK_SECURE_REQUEST` |`SE_REQ` | Request that user perform the unlock sequence |
-
-## Configuration
-
-| Define | Default | Description |
-|-------------------------|----------------|---------------------------------------------------------------------------------|
-|`SECURE_UNLOCK_TIMEOUT` | `5000` | Timeout for the user to perform the configured unlock sequence - `0` to disable |
-|`SECURE_IDLE_TIMEOUT` | `60000` | Timeout while unlocked before returning to locked - `0` to disable |
-|`SECURE_UNLOCK_SEQUENCE` | `{ { 0, 0 } }` | Array of matrix locations describing a sequential sequence of keypresses |
-
-## Functions
-
-| Function | Description |
-|---------------------------|----------------------------------------------------------------------------|
-| `secure_is_locked()` | Check if the device is currently locked |
-| `secure_is_unlocking()` | Check if an unlock sequence is currently in progress |
-| `secure_is_unlocked()` | Check if the device is currently unlocked |
-| `secure_lock()` | Lock down the device |
-| `secure_unlock()` | Force unlock the device - bypasses user unlock sequence |
-| `secure_request_unlock()` | Begin listening for an unlock sequence |
-| `secure_activity_event()` | Flag that user activity has happened and the device should remain unlocked |
diff --git a/docs/feature_send_string.md b/docs/feature_send_string.md
deleted file mode 100644
index 7d3f3ba32a..0000000000
--- a/docs/feature_send_string.md
+++ /dev/null
@@ -1,224 +0,0 @@
-# Send String :id=send-string
-
-The Send String API is part of QMK's macro system. It allows for sequences of keystrokes to be sent automatically.
-
-The full ASCII character set is supported, along with all of the keycodes in the Basic Keycode range (as these are the only ones that will actually be sent to the host).
-
-?> Unicode characters are **not** supported with this API -- see the [Unicode](feature_unicode.md) feature instead.
-
-## Usage :id=usage
-
-Send String is enabled by default, so there is usually no need for any special setup. However, if it is disabled, add the following to your `rules.mk`:
-
-```make
-SEND_STRING_ENABLE = yes
-```
-
-## Basic Configuration :id=basic-configuration
-
-Add the following to your `config.h`:
-
-|Define |Default |Description |
-|-----------------|----------------|------------------------------------------------------------------------------------------------------------|
-|`SENDSTRING_BELL`|*Not defined* |If the [Audio](feature_audio.md) feature is enabled, the `\a` character (ASCII `BEL`) will beep the speaker.|
-|`BELL_SOUND` |`TERMINAL_SOUND`|The song to play when the `\a` character is encountered. By default, this is an eighth note of C5. |
-
-## Keycodes :id=keycodes
-
-The Send String functions accept C string literals, but specific keycodes can be injected with the below macros. All of the keycodes in the [Basic Keycode range](keycodes_basic.md) are supported (as these are the only ones that will actually be sent to the host), but with an `X_` prefix instead of `KC_`.
-
-|Macro |Description |
-|--------------|-------------------------------------------------------------------|
-|`SS_TAP(x)` |Send a keydown, then keyup, event for the given Send String keycode|
-|`SS_DOWN(x)` |Send a keydown event for the given Send String keycode |
-|`SS_UP(x)` |Send a keyup event for the given Send String keycode |
-|`SS_DELAY(ms)`|Wait for `ms` milliseconds |
-
-The following characters are also mapped to their respective keycodes for convenience:
-
-|Character|Hex |ASCII|Keycode |
-|---------|------|-----|--------------|
-|`\b` |`\x08`|`BS` |`KC_BACKSPACE`|
-|`\e` |`\x09`|`ESC`|`KC_ESCAPE` |
-|`\n` |`\x0A`|`LF` |`KC_ENTER` |
-|`\t` |`\x1B`|`TAB`|`KC_TAB` |
-| |`\x7F`|`DEL`|`KC_DELETE` |
-
-### Language Support :id=language-support
-
-By default, Send String assumes your OS keyboard layout is set to US ANSI. If you are using a different keyboard layout, you can [override the lookup tables used to convert ASCII characters to keystrokes](reference_keymap_extras.md#sendstring-support).
-
-## Examples :id=examples
-
-### Hello World :id=example-hello-world
-
-A simple custom keycode which types out "Hello, world!" and the Enter key when pressed.
-
-Add the following to your `keymap.c`:
-
-```c
-bool process_record_user(uint16_t keycode, keyrecord_t *record) {
- switch (keycode) {
- case SS_HELLO:
- if (record->event.pressed) {
- SEND_STRING("Hello, world!\n");
- }
- return false;
- }
-
- return true;
-}
-```
-
-### Keycode Injection :id=example-keycode-injection
-
-This example types out opening and closing curly braces, then taps the left arrow key to move the cursor between the two.
-
-```c
-SEND_STRING("{}" SS_TAP(X_LEFT));
-```
-
-This example types Ctrl+A, then Ctrl+C, without releasing Ctrl.
-
-```c
-SEND_STRING(SS_LCTL("ac"));
-```
-
-## API :id=api
-
-### `void send_string(const char *string)` :id=api-send-string
-
-Type out a string of ASCII characters.
-
-This function simply calls `send_string_with_delay(string, 0)`.
-
-#### Arguments :id=api-send-string-arguments
-
- - `const char *string`
- The string to type out.
-
----
-
-### `void send_string_with_delay(const char *string, uint8_t interval)` :id=api-send-string-with-delay
-
-Type out a string of ASCII characters, with a delay between each character.
-
-#### Arguments :id=api-send-string-with-delay-arguments
-
- - `const char *string`
- The string to type out.
- - `uint8_t interval`
- The amount of time, in milliseconds, to wait before typing the next character.
-
----
-
-### `void send_string_P(const char *string)` :id=api-send-string-p
-
-Type out a PROGMEM string of ASCII characters.
-
-On ARM devices, this function is simply an alias for `send_string_with_delay(string, 0)`.
-
-#### Arguments :id=api-send-string-p-arguments
-
- - `const char *string`
- The string to type out.
-
----
-
-### `void send_string_with_delay_P(const char *string, uint8_t interval)` :id=api-send-string-with-delay-p
-
-Type out a PROGMEM string of ASCII characters, with a delay between each character.
-
-On ARM devices, this function is simply an alias for `send_string_with_delay(string, interval)`.
-
-#### Arguments :id=api-send-string-with-delay-p-arguments
-
- - `const char *string`
- The string to type out.
- - `uint8_t interval`
- The amount of time, in milliseconds, to wait before typing the next character.
-
----
-
-### `void send_char(char ascii_code)` :id=api-send-char
-
-Type out an ASCII character.
-
-#### Arguments :id=api-send-char-arguments
-
- - `char ascii_code`
- The character to type.
-
----
-
-### `void send_dword(uint32_t number)` :id=api-send-dword
-
-Type out an eight digit (unsigned 32-bit) hexadecimal value.
-
-The format is `[0-9a-f]{8}`, eg. `00000000` through `ffffffff`.
-
-#### Arguments :id=api-send-dword-arguments
-
- - `uint32_t number`
- The value to type, from 0 to 4,294,967,295.
-
----
-
-### `void send_word(uint16_t number)` :id=api-send-word
-
-Type out a four digit (unsigned 16-bit) hexadecimal value.
-
-The format is `[0-9a-f]{4}`, eg. `0000` through `ffff`.
-
-#### Arguments :id=api-send-word-arguments
-
- - `uint16_t number`
- The value to type, from 0 to 65,535.
-
----
-
-### `void send_byte(uint8_t number)` :id=api-send-bytes
-
-Type out a two digit (8-bit) hexadecimal value.
-
-The format is `[0-9a-f]{2}`, eg. `00` through `ff`.
-
-#### Arguments :id=api-send-byte-arguments
-
- - `uint8_t number`
- The value to type, from 0 to 255.
-
----
-
-### `void send_nibble(uint8_t number)` :id=api-send-nibble
-
-Type out a single hexadecimal digit.
-
-The format is `[0-9a-f]{1}`, eg. `0` through `f`.
-
-#### Arguments :id=api-send-nibble-arguments
-
- - `uint8_t number`
- The value to type, from 0 to 15.
-
----
-
-### `void tap_random_base64(void)` :id=api-tap-random-base64
-
-Type a pseudorandom character from the set `A-Z`, `a-z`, `0-9`, `+` and `/`.
-
----
-
-### `SEND_STRING(string)` :id=api-send-string-macro
-
-Shortcut macro for `send_string_with_delay_P(PSTR(string), 0)`.
-
-On ARM devices, this define evaluates to `send_string_with_delay(string, 0)`.
-
----
-
-### `SEND_STRING_DELAY(string, interval)` :id=api-send-string-delay-macro
-
-Shortcut macro for `send_string_with_delay_P(PSTR(string), interval)`.
-
-On ARM devices, this define evaluates to `send_string_with_delay(string, interval)`.
diff --git a/docs/feature_sequencer.md b/docs/feature_sequencer.md
deleted file mode 100644
index 3af55197c5..0000000000
--- a/docs/feature_sequencer.md
+++ /dev/null
@@ -1,87 +0,0 @@
-# Sequencer
-
-Since QMK has experimental support for MIDI, you can now turn your keyboard into a [step sequencer](https://en.wikipedia.org/wiki/Music_sequencer#Step_sequencers)!
-
-!> **IMPORTANT:** This feature is highly experimental, it has only been tested on a Planck EZ so far. Also, the scope will be limited to support the drum machine use-case to start with.
-
-## Enable the step sequencer
-
-Add the following line to your `rules.mk`:
-
-```make
-SEQUENCER_ENABLE = yes
-```
-
-By default the sequencer has 16 steps, but you can override this setting in your `config.h`:
-
-```c
-#define SEQUENCER_STEPS 32
-```
-
-## Tracks
-
-You can program up to 8 independent tracks with the step sequencer. Select the tracks you want to edit, enable or disable some steps, and start the sequence!
-
-## Resolutions
-
-While the tempo defines the absolute speed at which the sequencer goes through the steps, the resolution defines the granularity of these steps (from coarser to finer).
-
-|Resolution |Description |
-|---------- |----------- |
-|`SQ_RES_2` |Every other beat |
-|`SQ_RES_2T` |Every 1.5 beats |
-|`SQ_RES_4` |Every beat |
-|`SQ_RES_4T` |Three times per 2 beats|
-|`SQ_RES_8` |Twice per beat |
-|`SQ_RES_8T` |Three times per beat |
-|`SQ_RES_16` |Four times per beat |
-|`SQ_RES_16T` |Six times per beat |
-|`SQ_RES_32` |Eight times per beat |
-
-## Keycodes
-
-|Key |Aliases |Description |
-|-------------------------------|---------|---------------------------------------------------|
-|`QK_SEQUENCER_ON` |`SQ_ON` |Start the step sequencer |
-|`QK_SEQUENCER_OFF` |`SQ_OFF` |Stop the step sequencer |
-|`QK_SEQUENCER_TOGGLE` |`SQ_TOGG`|Toggle the step sequencer playback |
-|`QK_SEQUENCER_STEPS_ALL` |`SQ_SALL`|Enable all the steps |
-|`QK_SEQUENCER_STEPS_CLEAR` |`SQ_SCLR`|Disable all the steps |
-|`QK_SEQUENCER_TEMPO_DOWN` |`SQ_TMPD`|Decrease the tempo |
-|`QK_SEQUENCER_TEMPO_UP` |`SQ_TMPU`|Increase the tempo |
-|`QK_SEQUENCER_RESOLUTION_DOWN` |`SQ_RESD`|Change to the slower resolution |
-|`QK_SEQUENCER_RESOLUTION_UP` |`SQ_RESU`|Change to the faster resolution |
-|`SQ_S(n)` | |Toggle the step `n` |
-|`SQ_R(n)` | |Set the resolution to n |
-|`SQ_T(n)` | |Set `n` as the only active track or deactivate all |
-
-## Functions
-
-|Function |Description |
-|-------- |----------- |
-|`bool is_sequencer_on(void);` |Return whether the sequencer is playing |
-|`void sequencer_toggle(void);` |Toggle the step sequencer playback |
-|`void sequencer_on(void);` |Start the step sequencer |
-|`void sequencer_off(void);` |Stop the step sequencer |
-|`bool is_sequencer_step_on(uint8_t step);` |Return whether the step is currently enabled |
-|`void sequencer_set_step(uint8_t step, bool value);` |Enable or disable the step |
-|`void sequencer_set_step_on();` |Enable the step |
-|`void sequencer_set_step_off();` |Disable the step |
-|`void sequencer_toggle_step(uint8_t step);` |Toggle the step |
-|`void sequencer_set_all_steps(bool value);` |Enable or disable all the steps |
-|`void sequencer_set_all_steps_on();` |Enable all the steps |
-|`void sequencer_set_all_steps_off();` |Disable all the steps |
-|`uint8_t sequencer_get_tempo(void);` |Return the current tempo |
-|`void sequencer_set_tempo(uint8_t tempo);` |Set the tempo to `tempo` (between 1 and 255) |
-|`void sequencer_increase_tempo(void);` |Increase the tempo |
-|`void sequencer_decrease_tempo(void);` |Decrease the tempo |
-|`sequencer_resolution_t sequencer_get_resolution(void);` |Return the current resolution |
-|`void sequencer_set_resolution(sequencer_resolution_t resolution);` |Set the resolution to `resolution` |
-|`void sequencer_increase_resolution(void);` |Change to the faster resolution |
-|`void sequencer_decrease_resolution(void);` |Change to the slower resolution |
-|`bool is_sequencer_track_active(uint8_t track);` |Return whether the track is active |
-|`void sequencer_set_track_activation(uint8_t track, bool value);` |Activate or deactivate the `track` |
-|`void sequencer_toggle_track_activation(uint8_t track);` |Toggle the `track` |
-|`void sequencer_activate_track(uint8_t track);` |Activate the `track` |
-|`void sequencer_deactivate_track(uint8_t track);` |Deactivate the `track` |
-|`void sequencer_toggle_single_active_track(uint8_t track);` |Set `track` as the only active track or deactivate all |
diff --git a/docs/feature_space_cadet.md b/docs/feature_space_cadet.md
deleted file mode 100644
index 223a5b3ccf..0000000000
--- a/docs/feature_space_cadet.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# Space Cadet: The Future, Built In
-
-Steve Losh described the [Space Cadet Shift](https://web.archive.org/web/20230330090938/https://stevelosh.com/blog/2012/10/a-modern-space-cadet/) quite well. Essentially, when you tap Left Shift on its own, you get an opening parenthesis; tap Right Shift on its own and you get the closing one. When held, the Shift keys function as normal. Yes, it's as cool as it sounds, and now even cooler supporting Control and Alt as well!
-
-## Usage
-
-Firstly, in your keymap, do one of the following:
-- Replace the Left Shift key with `SC_LSPO` (Left Shift, Parenthesis Open), and Right Shift with `SC_RSPC` (Right Shift, Parenthesis Close).
-- Replace the Left Control key with `SC_LCPO` (Left Control, Parenthesis Open), and Right Control with `SC_RCPC` (Right Control, Parenthesis Close).
-- Replace the Left Alt key with `SC_LAPO` (Left Alt, Parenthesis Open), and Right Alt with `SC_RAPC` (Right Alt, Parenthesis Close).
-- Replace any Shift key in your keymap with `SC_SENT` (Right Shift, Enter).
-
-## Keycodes
-
-|Keycode |Aliases |Description |
-|----------------------------------------------|---------|----------------------------------------|
-|`QK_SPACE_CADET_LEFT_CTRL_PARENTHESIS_OPEN` |`SC_LCPO`|Left Control when held, `(` when tapped |
-|`QK_SPACE_CADET_RIGHT_CTRL_PARENTHESIS_CLOSE` |`SC_RCPC`|Right Control when held, `)` when tapped|
-|`QK_SPACE_CADET_LEFT_SHIFT_PARENTHESIS_OPEN` |`SC_LSPO`|Left Shift when held, `(` when tapped |
-|`QK_SPACE_CADET_RIGHT_SHIFT_PARENTHESIS_CLOSE`|`SC_RSPC`|Right Shift when held, `)` when tapped |
-|`QK_SPACE_CADET_LEFT_ALT_PARENTHESIS_OPEN` |`SC_LAPO`|Left Alt when held, `(` when tapped |
-|`QK_SPACE_CADET_RIGHT_ALT_PARENTHESIS_CLOSE` |`SC_RAPC`|Right Alt when held, `)` when tapped |
-|`QK_SPACE_CADET_RIGHT_SHIFT_ENTER` |`SC_SENT`|Right Shift when held, Enter when tapped|
-
-## Caveats
-
-Space Cadet's functionality can conflict with the default Command functionality when both Shift keys are held at the same time. See the [Command feature](feature_command.md) for info on how to change it, or make sure that Command is disabled in your `rules.mk` with:
-
-```make
-COMMAND_ENABLE = no
-```
-
-## Configuration
-
-By default Space Cadet assumes a US ANSI layout, but if your layout uses different keys for parentheses, you can redefine them in your `config.h`. In addition, you can redefine the modifier to send on tap, or even send no modifier at all. The new configuration defines bundle all options up into a single define of 3 key codes in this order: the `Modifier` when held or when used with other keys, the `Tap Modifer` sent when tapped (no modifier if `KC_TRNS`), finally the `Keycode` sent when tapped. Now keep in mind, mods from other keys will still apply to the `Keycode` if say `KC_RSFT` is held while tapping `SC_LSPO` key with `KC_TRNS` as the `Tap Modifer`.
-
-|Define |Default |Description |
-|----------------|-------------------------------|---------------------------------------------------------------------------------|
-|`LSPO_KEYS` |`KC_LSFT, LSPO_MOD, LSPO_KEY` |Send `KC_LSFT` when held, the mod and key defined by `LSPO_MOD` and `LSPO_KEY`. |
-|`RSPC_KEYS` |`KC_RSFT, RSPC_MOD, RSPC_KEY` |Send `KC_RSFT` when held, the mod and key defined by `RSPC_MOD` and `RSPC_KEY`. |
-|`LCPO_KEYS` |`KC_LCTL, KC_LSFT, KC_9` |Send `KC_LCTL` when held, the mod `KC_LSFT` with the key `KC_9` when tapped. |
-|`RCPC_KEYS` |`KC_RCTL, KC_RSFT, KC_0` |Send `KC_RCTL` when held, the mod `KC_RSFT` with the key `KC_0` when tapped. |
-|`LAPO_KEYS` |`KC_LALT, KC_LSFT, KC_9` |Send `KC_LALT` when held, the mod `KC_LSFT` with the key `KC_9` when tapped. |
-|`RAPC_KEYS` |`KC_RALT, KC_RSFT, KC_0` |Send `KC_RALT` when held, the mod `KC_RSFT` with the key `KC_0` when tapped. |
-|`SFTENT_KEYS` |`KC_RSFT, KC_TRNS, SFTENT_KEY` |Send `KC_RSFT` when held, no mod with the key `SFTENT_KEY` when tapped. |
-|`SPACE_CADET_MODIFIER_CARRYOVER` |*Not defined* |Store current modifiers before the hold mod is pressed and use them with the tap mod and keycode. Useful for when you frequently release a modifier before triggering Space Cadet. |
-
-
-## Obsolete Configuration
-
-These defines are used in the above defines internally to support backwards compatibility, so you may continue to use them, however the above defines open up a larger range of flexibility than before. As an example, say you want to not send any modifier when you tap just `SC_LSPO`, with the old defines you had an all or nothing choice of using the `DISABLE_SPACE_CADET_MODIFIER` define. Now you can define that key as: `#define LSPO_KEYS KC_LSFT, KC_TRNS, KC_9`. This tells the system to set Left Shift if held or used with other keys, then on tap send no modifier (transparent) with the `KC_9`.
-
-|Define |Default |Description |
-|------------------------------|-------------|------------------------------------------------------------------|
-|`LSPO_KEY` |`KC_9` |The keycode to send when Left Shift is tapped |
-|`RSPC_KEY` |`KC_0` |The keycode to send when Right Shift is tapped |
-|`LSPO_MOD` |`KC_LSFT` |The modifier to apply to `LSPO_KEY` |
-|`RSPC_MOD` |`KC_RSFT` |The modifier to apply to `RSPC_KEY` |
-|`SFTENT_KEY` |`KC_ENT` |The keycode to send when the Shift key is tapped |
-|`DISABLE_SPACE_CADET_MODIFIER`|*Not defined*|If defined, prevent the Space Cadet from applying a modifier |
diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md
deleted file mode 100644
index 99c252d03e..0000000000
--- a/docs/feature_split_keyboard.md
+++ /dev/null
@@ -1,486 +0,0 @@
-# Split Keyboard
-
-Many keyboards in the QMK Firmware repo are "split" keyboards. They use two controllers—one plugging into USB, and the second connected by a serial or an I2C connection over a TRRS or similar cable.
-
-Split keyboards can have a lot of benefits, but there is some additional work needed to get them enabled.
-
-QMK Firmware has a generic implementation that is usable by any board, as well as numerous board specific implementations.
-
-For this, we will mostly be talking about the generic implementation used by the Let's Split and other keyboards.
-
-!> ARM split supports most QMK subsystems when using the 'serial' and 'serial_usart' drivers. I2C slave is currently unsupported.
-
-!> Both sides must use the same MCU family, for eg two Pro Micro-compatible controllers or two Blackpills. Currently, mixing AVR and ARM is not possible as ARM vs AVR uses different method for serial communication, and are not compatible. Moreover Blackpill's uses 3.3v logic, and atmega32u4 uses 5v logic.
-
-## Compatibility Overview
-
-| Transport | AVR | ARM |
-|------------------------------|--------------------|--------------------|
-| ['serial'](serial_driver.md) | :heavy_check_mark: | :white_check_mark: 1 |
-| I2C | :heavy_check_mark: | |
-
-Notes:
-
-1. Both hardware and software limitations are detailed within the [driver documentation](serial_driver.md).
-
-## Hardware Configuration
-
-This assumes that you're using two Pro Micro-compatible controllers, and are using TRRS jacks to connect to two halves.
-
-### Required Hardware
-
-Apart from diodes and key switches for the keyboard matrix in each half, you will need 2x TRRS sockets and 1x TRRS cable.
-
-Alternatively, you can use any sort of cable and socket that has at least 3 wires.
-
-If you want to use I2C to communicate between halves, you will need a cable with at least 4 wires and 2x 4.7kΩ pull-up resistors.
-
-#### Considerations
-
-The most commonly used connection is a TRRS cable and jacks. These provide 4 wires, making them very useful for split keyboards, and are easy to find.
-
-However, since one of the wires carries VCC, this means that the boards are not hot pluggable. You should always disconnect the board from USB before unplugging and plugging in TRRS cables, or you can short the controller, or worse.
-
-Another option is to use phone cables (as in, old school RJ-11/RJ-14 cables). Make sure that you use one that actually supports 4 wires/lanes.
-
-However, USB cables, SATA cables, and even just 4 wires have been known to be used for communication between the controllers.
-
-!> Using USB cables for communication between the controllers works just fine, but the connector could be mistaken for a normal USB connection and potentially short out the keyboard, depending on how it's wired. For this reason, they are not recommended for connecting split keyboards.
-
-### Serial Wiring
-
-The 3 wires of the TRS/TRRS cable need to connect GND, VCC, and D0/D1/D2/D3 (aka PD0/PD1/PD2/PD3) between the two Pro Micros.
-
-?> Note that the pin used here is actually set by `SOFT_SERIAL_PIN` below.
-
-
-
-
-### I2C Wiring
-
-The 4 wires of the TRRS cable need to connect GND, VCC, and SCL and SDA (aka PD0/pin 3 and PD1/pin 2, respectively) between the two Pro Micros.
-
-The pull-up resistors may be placed on either half. If you wish to use the halves independently, it is also possible to use 4 resistors and have the pull-ups in both halves.
-Note that the total resistance for the connected system should be within spec at 2.2k-10kOhm, with an 'ideal' at 4.7kOhm, regardless of the placement and number.
-
-
-
-## Firmware Configuration
-
-To enable the split keyboard feature, add the following to your `rules.mk`:
-
-```make
-SPLIT_KEYBOARD = yes
-```
-
-If you're using a custom transport (communication method), then you will also need to add:
-
-```make
-SPLIT_TRANSPORT = custom
-```
-
-### Layout Macro
-
-Configuring your layout in a split keyboard works slightly differently to a non-split keyboard. Take for example the following layout. The top left numbers refer to the matrix row and column, and the bottom right are the order of the keys in the layout:
-
-
-
-Since the matrix scanning procedure operates on entire rows, it first populates the left half's rows, then the right half's. Thus, the matrix as QMK views it has double the rows instead of double the columns:
-
-
-
-### Setting Handedness
-
-By default, the firmware does not know which side is which; it needs some help to determine that. There are several ways to do this, listed in order of precedence.
-
-#### Handedness by Pin
-
-You can configure the firmware to read a pin on the controller to determine handedness. To do this, add the following to your `config.h` file:
-
-```c
-#define SPLIT_HAND_PIN B7
-```
-
-This will read the specified pin. By default, if it's high, then the controller assumes it is the left hand, and if it's low, it's assumed to be the right side.
-
-This behaviour can be flipped by adding this to you `config.h` file:
-
-```c
-#define SPLIT_HAND_PIN_LOW_IS_LEFT
-```
-
-#### Handedness by Matrix Pin
-
-You can configure the firmware to read key matrix pins on the controller to determine handedness. To do this, add the following to your `config.h` file:
-
-```c
-#define SPLIT_HAND_MATRIX_GRID D0, F1
-```
-
-The first pin is the output pin and the second is the input pin.
-
-Some keyboards have unused intersections in the key matrix. This setting uses one of these unused intersections to determine the handedness.
-
-Normally, when a diode is connected to an intersection, it is judged to be right. If you add the following definition, it will be judged to be left.
-
-```c
-#define SPLIT_HAND_MATRIX_GRID_LOW_IS_LEFT
-```
-
-Note that adding a diode at a previously unused intersection will effectively tell the firmware that there is a key held down at that point. You can instruct qmk to ignore that intersection by defining `MATRIX_MASKED` and then defining a `matrix_row_t matrix_mask[MATRIX_ROWS]` array in your keyboard config. Each bit of a single value (starting form the least-significant bit) is used to tell qmk whether or not to pay attention to key presses at that intersection.
-
-While `MATRIX_MASKED` isn't necessary to use `SPLIT_HAND_MATRIX_GRID` successfully, without it you may experience issues trying to suspend your computer with your keyboard attached as the matrix will always report at least one key-press.
-
-#### Handedness by EEPROM
-
-This method sets the keyboard's handedness by setting a flag in the persistent storage (`EEPROM`). This is checked when the controller first starts up, and determines what half the keyboard is, and how to orient the keyboard layout.
-
-
-To enable this method, add the following to your `config.h` file:
-
-```c
-#define EE_HANDS
-```
-
-Next, you will have to flash the correct handedness option to the controller on each halve. You can do this manually with the following bootloader targets using `qmk flash -kb (e.g. Pro Micro)|`avrdude-split-left`
`avrdude-split-right`| -|AVR controllers with the stock Amtel DFU or DFU compatible bootloader
(e.g. Elite-C)|`dfu-split-left`
`dfu-split-right`| -|ARM controllers with a DFU compatible bootloader
(e.g. Proton-C)|`dfu-util-split-left`
`dfu-util-split-right`| -|ARM controllers with a UF2 compatible bootloader
(e.g. RP2040)|`uf2-split-left`
`uf2-split-right`| - -Example for `crkbd/rev1` keyboard with normal AVR Pro Micro MCUs, reset the left controller and run: -``` -qmk flash -kb crkbd/rev1 -km default -bl avrdude-split-left -``` -Reset the right controller and run: -``` -qmk flash -kb crkbd/rev1 -km default -bl avrdude-split-right -``` - -?> Some controllers (e.g. Blackpill with DFU compatible bootloader) will need to be flashed with handedness bootloader parameter every time because it is not retained between flashes. - -?> [QMK Toolbox]() can also be used to flash EEPROM handedness files. Place the controller in bootloader mode and select menu option Tools -> EEPROM -> Set Left/Right Hand - -This setting is not changed when re-initializing the EEPROM using the `EE_CLR` key, or using the `eeconfig_init()` function. However, if you reset the EEPROM outside of the firmware's built in options (such as flashing a file that overwrites the `EEPROM`, like how the [QMK Toolbox]()'s "Reset EEPROM" button works), you'll need to re-flash the controller with the `EEPROM` files. - -You can find the `EEPROM` files in the QMK firmware repo, [here](https://github.com/qmk/qmk_firmware/tree/master/quantum/split_common). - - -#### Handedness by `#define` - -You can use this option when USB cable is always connected to just one side of the split keyboard. - -If the USB cable is always connected to the right side, add the following to your `config.h` file and flash both sides with this option: -```c -#define MASTER_RIGHT -``` - -If the USB cable is always connected to the left side, add the following to your `config.h` file and flash both sides with this option: -```c -#define MASTER_LEFT -``` - -?> If neither options are defined, the handedness defaults to `MASTER_LEFT`. - - -### Communication Options - -Because not every split keyboard is identical, there are a number of additional options that can be configured in your `config.h` file. - -```c -#define USE_I2C -``` - -This configures the use of I2C support for split keyboard transport (AVR only). - -```c -#define SOFT_SERIAL_PIN D0 -``` - -This sets the pin to be used for serial communication. If you're not using serial, you shouldn't need to define this. - -However, if you are using serial and I2C on the board, you will need to set this, and to something other than D0 and D1 (as these are used for I2C communication). - -```c -#define SELECT_SOFT_SERIAL_SPEED {#} -``` - -If you're having issues with serial communication, you can change this value, as it controls the communication speed for serial. The default is 1, and the possible values are: - -* **`0`**: about 189kbps (Experimental only) -* **`1`**: about 137kbps (default) -* **`2`**: about 75kbps -* **`3`**: about 39kbps -* **`4`**: about 26kbps -* **`5`**: about 20kbps - -```c -#define FORCED_SYNC_THROTTLE_MS 100 -``` - -This sets the maximum number of milliseconds before forcing a synchronization of data from master to slave. Under normal circumstances this sync occurs whenever the data _changes_, for safety a data transfer occurs after this number of milliseconds if no change has been detected since the last sync. - -```c -#define SPLIT_MAX_CONNECTION_ERRORS 10 -``` -This sets the maximum number of failed communication attempts (one per scan cycle) from the master part before it assumes that no slave part is connected. This makes it possible to use a master part without the slave part connected. - -Set to 0 to disable the disconnection check altogether. - -```c -#define SPLIT_CONNECTION_CHECK_TIMEOUT 500 -``` -How long (in milliseconds) the master part should block all connection attempts to the slave after the communication has been flagged as disconnected (see `SPLIT_MAX_CONNECTION_ERRORS` above). - -One communication attempt will be allowed everytime this amount of time has passed since the last attempt. If that attempt succeeds, the communication is seen as working again. - -Set to 0 to disable this throttling of communications while disconnected. This can save you a couple of bytes of firmware size. - - -### Data Sync Options - -The following sync options add overhead to the split communication protocol and may negatively impact the matrix scan speed when enabled. These can be enabled by adding the chosen option(s) to your `config.h` file. - -```c -#define SPLIT_TRANSPORT_MIRROR -``` - -This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to keypresses). - -```c -#define SPLIT_LAYER_STATE_ENABLE -``` - -This enables syncing of the layer state between both halves of the split keyboard. The main purpose of this feature is to enable support for use of things like OLED display of the currently active layer. - -```c -#define SPLIT_LED_STATE_ENABLE -``` - -This enables syncing of the Host LED status (caps lock, num lock, etc) between both halves of the split keyboard. The main purpose of this feature is to enable support for use of things like OLED display of the Host LED status. - -```c -#define SPLIT_MODS_ENABLE -``` - -This enables transmitting modifier state (normal, weak, oneshot and oneshot locked) to the non primary side of the split keyboard. The purpose of this feature is to support cosmetic use of modifer state (e.g. displaying status on an OLED screen). - -```c -#define SPLIT_WPM_ENABLE -``` - -This enables transmitting the current WPM to the slave side of the split keyboard. The purpose of this feature is to support cosmetic use of WPM (e.g. displaying the current value on an OLED screen). - -```c -#define SPLIT_OLED_ENABLE -``` - -This enables transmitting the current OLED on/off status to the slave side of the split keyboard. The purpose of this feature is to support state (on/off state only) syncing. - -```c -#define SPLIT_ST7565_ENABLE -``` - -This enables transmitting the current ST7565 on/off status to the slave side of the split keyboard. The purpose of this feature is to support state (on/off state only) syncing. - -```c -#define SPLIT_POINTING_ENABLE -``` - -This enables transmitting the pointing device status to the master side of the split keyboard. The purpose of this feature is to enable use pointing devices on the slave side. - -!> There is additional required configuration for `SPLIT_POINTING_ENABLE` outlined in the [pointing device documentation](feature_pointing_device.md?id=split-keyboard-configuration). - -```c -#define SPLIT_HAPTIC_ENABLE -``` - -This enables the triggering of haptic feedback on the slave side of the split keyboard. This will send information to the slave side such as the mode, dwell, and whether buzz is enabled. - -```c -#define SPLIT_ACTIVITY_ENABLE -``` - -This synchronizes the activity timestamps between sides of the split keyboard, allowing for activity timeouts to occur. - -### Custom data sync between sides :id=custom-data-sync - -QMK's split transport allows for arbitrary data transactions at both the keyboard and user levels. This is modelled on a remote procedure call, with the master invoking a function on the slave side, with the ability to send data from master to slave, process it slave side, and send data back from slave to master. - -To leverage this, a keyboard or user/keymap can define a comma-separated list of _transaction IDs_: - -```c -// for keyboard-level data sync: -#define SPLIT_TRANSACTION_IDS_KB KEYBOARD_SYNC_A, KEYBOARD_SYNC_B -// or, for user: -#define SPLIT_TRANSACTION_IDS_USER USER_SYNC_A, USER_SYNC_B, USER_SYNC_C -``` - -These _transaction IDs_ then need a slave-side handler function to be registered with the split transport, for example: - -```c -typedef struct _master_to_slave_t { - int m2s_data; -} master_to_slave_t; - -typedef struct _slave_to_master_t { - int s2m_data; -} slave_to_master_t; - -void user_sync_a_slave_handler(uint8_t in_buflen, const void* in_data, uint8_t out_buflen, void* out_data) { - const master_to_slave_t *m2s = (const master_to_slave_t*)in_data; - slave_to_master_t *s2m = (slave_to_master_t*)out_data; - s2m->s2m_data = m2s->m2s_data + 5; // whatever comes in, add 5 so it can be sent back -} - -void keyboard_post_init_user(void) { - transaction_register_rpc(USER_SYNC_A, user_sync_a_slave_handler); -} -``` - -The master side can then invoke the slave-side handler - for normal keyboard functionality to be minimally affected, any keyboard- or user-level code attempting to sync data should be throttled: - -```c -void housekeeping_task_user(void) { - if (is_keyboard_master()) { - // Interact with slave every 500ms - static uint32_t last_sync = 0; - if (timer_elapsed32(last_sync) > 500) { - master_to_slave_t m2s = {6}; - slave_to_master_t s2m = {0}; - if(transaction_rpc_exec(USER_SYNC_A, sizeof(m2s), &m2s, sizeof(s2m), &s2m)) { - last_sync = timer_read32(); - dprintf("Slave value: %d\n", s2m.s2m_data); // this will now be 11, as the slave adds 5 - } else { - dprint("Slave sync failed!\n"); - } - } - } -} -``` - -!> It is recommended that any data sync between halves happens during the master side's _housekeeping task_. This ensures timely retries should failures occur. - -If only one-way data transfer is needed, helper methods are provided: - -```c -bool transaction_rpc_exec(int8_t transaction_id, uint8_t initiator2target_buffer_size, const void *initiator2target_buffer, uint8_t target2initiator_buffer_size, void *target2initiator_buffer); -bool transaction_rpc_send(int8_t transaction_id, uint8_t initiator2target_buffer_size, const void *initiator2target_buffer); -bool transaction_rpc_recv(int8_t transaction_id, uint8_t target2initiator_buffer_size, void *target2initiator_buffer); -``` - -By default, the inbound and outbound data is limited to a maximum of 32 bytes each. The sizes can be altered if required: - -```c -// Master to slave: -#define RPC_M2S_BUFFER_SIZE 48 -// Slave to master: -#define RPC_S2M_BUFFER_SIZE 48 -``` - -### Hardware Configuration Options - -There are some settings that you may need to configure, based on how the hardware is set up. - -```c -#define MATRIX_ROW_PINS_RIGHT {
`(ST7565_DISPLAY_HEIGHT / 8 * ST7565_DISPLAY_WIDTH)`. | -|`ST7565_BLOCK_TYPE` |`uint16_t`|The unsigned integer type to use for dirty rendering. | -|`ST7565_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.
`(sizeof(ST7565_BLOCK_TYPE) * 8)`.| -|`ST7565_BLOCK_SIZE` |`32` |The size of each block for dirty rendering
`(ST7565_MATRIX_SIZE / ST7565_BLOCK_COUNT)`. | - -## API - -```c -// Rotation enum values are flags -typedef enum { - DISPLAY_ROTATION_0, - DISPLAY_ROTATION_180 -} display_rotation_t; - -// Initialize the display, rotating the rendered output based on the define passed in. -// Returns true if the was initialized successfully -bool st7565_init(display_rotation_t rotation); - -// Called at the start of st7565_init, weak function overridable by the user -// rotation - the value passed into st7565_init -// Return new display_rotation_t if you want to override default rotation -display_rotation_t st7565_init_user(display_rotation_t rotation); - -// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering -void st7565_clear(void); - -// Renders the dirty chunks of the buffer to display -void st7565_render(void); - -// Moves cursor to character position indicated by column and line, wraps if out of bounds -// Max column denoted by 'st7565_max_chars()' and max lines by 'st7565_max_lines()' functions -void st7565_set_cursor(uint8_t col, uint8_t line); - -// Advances the cursor to the next page, writing ' ' if true -// Wraps to the begining when out of bounds -void st7565_advance_page(bool clearPageRemainder); - -// Moves the cursor forward 1 character length -// Advance page if there is not enough room for the next character -// Wraps to the begining when out of bounds -void st7565_advance_char(void); - -// Writes a single character to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -// Main handler that writes character data to the display buffer -void st7565_write_char(const char data, bool invert); - -// Writes a string to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -void st7565_write(const char *data, bool invert); - -// Writes a string to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -// Advances the cursor to the next page, wiring ' ' to the remainder of the current page -void st7565_write_ln(const char *data, bool invert); - -// Pans the buffer to the right (or left by passing true) by moving contents of the buffer -// Useful for moving the screen in preparation for new drawing -void st7565_pan(bool left); - -// Returns a pointer to the requested start index in the buffer plus remaining -// buffer length as struct -display_buffer_reader_t st7565_read_raw(uint16_t start_index); - -// Writes a string to the buffer at current cursor position -void st7565_write_raw(const char *data, uint16_t size); - -// Writes a single byte into the buffer at the specified index -void st7565_write_raw_byte(const char data, uint16_t index); - -// Sets a specific pixel on or off -// Coordinates start at top-left and go right and down for positive x and y -void st7565_write_pixel(uint8_t x, uint8_t y, bool on); - -// Writes a PROGMEM string to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -// Remapped to call 'void st7565_write(const char *data, bool invert);' on ARM -void st7565_write_P(const char *data, bool invert); - -// Writes a PROGMEM string to the buffer at current cursor position -// Advances the cursor while writing, inverts the pixels if true -// Advances the cursor to the next page, wiring ' ' to the remainder of the current page -// Remapped to call 'void st7565_write_ln(const char *data, bool invert);' on ARM -void st7565_write_ln_P(const char *data, bool invert); - -// Writes a PROGMEM string to the buffer at current cursor position -void st7565_write_raw_P(const char *data, uint16_t size); - -// Can be used to manually turn on the screen if it is off -// Returns true if the screen was on or turns on -bool st7565_on(void); - -// Called when st7565_on() turns on the screen, weak function overridable by the user -// Not called if the screen is already on -void st7565_on_user(void); - -// Can be used to manually turn off the screen if it is on -// Returns true if the screen was off or turns off -bool st7565_off(void); - -// Called when st7565_off() turns off the screen, weak function overridable by the user -// Not called if the screen is already off -void st7565_off_user(void); - -// Returns true if the screen is currently on, false if it is -// not -bool st7565_is_on(void); - -// Basically it's st7565_render, but with timeout management and st7565_task_user calling! -void st7565_task(void); - -// Called at the start of st7565_task, weak function overridable by the user -void st7565_task_user(void); - -// Inverts the display -// Returns true if the screen was or is inverted -bool st7565_invert(bool invert); - -// Returns the maximum number of characters that will fit on a line -uint8_t st7565_max_chars(void); - -// Returns the maximum number of lines that will fit on the display -uint8_t st7565_max_lines(void); -``` diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md deleted file mode 100644 index 5ca3ea945f..0000000000 --- a/docs/feature_stenography.md +++ /dev/null @@ -1,213 +0,0 @@ -# Stenography in QMK :id=stenography-in-qmk - -[Stenography](https://en.wikipedia.org/wiki/Stenotype) is a method of writing most often used by court reports, closed-captioning, and real-time transcription for the deaf. In stenography words are chorded syllable by syllable with a mixture of spelling, phonetic, and shortcut (briefs) strokes. Professional stenographers can reach 200-300 WPM without any of the strain usually found in standard typing and with far fewer errors (>99.9% accuracy). - -The [Open Steno Project](https://www.openstenoproject.org/) has built an open-source program called Plover that provides real-time translation of steno strokes into words and commands. It has an established dictionary and supports - -## Plover with QWERTY Keyboard :id=plover-with-qwerty-keyboard - -Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar. - -To enable NKRO, add `NKRO_ENABLE = yes` in your `rules.mk` and make sure to press `NK_ON` to turn it on because `NKRO_ENABLE = yes` merely adds the possibility of switching to NKRO mode but it doesn't automatically switch to it. If you want to automatically switch, add `#define FORCE_NKRO` in your `config.h`. - -You may also need to adjust your layout, either in QMK or in Plover, if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys. - -## Plover with Steno Protocol :id=plover-with-steno-protocol - -Plover also understands the language of several steno machines. QMK can speak a couple of these languages: TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`. - -When QMK speaks to Plover over a steno protocol, Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover. - -In this mode, Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard. - -> Note: Due to hardware limitations, you might not be able to run both a virtual serial port and mouse emulation at the same time. - -!> Serial stenography protocols are not supported on [V-USB keyboards](compatible_microcontrollers#atmel-avr). - -To enable stenography protocols, add the following lines to your `rules.mk`: -```mk -STENO_ENABLE = yes -``` - -### TX Bolt :id=tx-bolt - -TX Bolt communicates the status of 24 keys over a simple protocol in variable-sized (1–4 bytes) packets. - -To select TX Bolt, add the following lines to your `rules.mk`: -```mk -STENO_ENABLE = yes -STENO_PROTOCOL = txbolt -``` - -Each byte of the packet represents a different group of steno keys. Determining the group of a certain byte of the packet is done by checking the first two bits, the remaining bits are set if the corresponding steno key was pressed for the stroke. The last set of keys (as indicated by leading `11`) needs to keep track of less keys than there are bits so one of the bits is constantly 0. - -The start of a new packet can be detected by comparing the group “ID” (the two MSBs) of the current byte to that of the previously received byte. If the group “ID” of the current byte is smaller or equal to that of the previous byte, it means that the current byte is the beginning of a new packet. - -The format of TX Bolt packets is shown below. -``` -00HWPKTS 01UE*OAR 10GLBPRF 110#ZDST -``` - -Examples of steno strokes and the associated packet: -- `EUBG` = `01110000 10101000` -- `WAZ` = `00010000 01000010 11001000` -- `PHAPBGS` = `00101000 01000010 10101100 11000010` - -### GeminiPR :id=geminipr - -GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including differentiating between top and bottom `S-`, and supporting non-English theories. - -To select GeminiPR, add the following lines to your `rules.mk`: -```mk -STENO_ENABLE = yes -STENO_PROTOCOL = geminipr -``` - -All packets in the GeminiPR protocol consist of exactly six bytes, used as bit-arrays for different groups of keys. The beginning of a packet is indicated by setting the most significant bit (MSB) to 1 while setting the MSB of the remaining five bytes to 0. - -The format of GeminiPR packets is shown below. -``` -1 Fn #1 #2 #3 #4 #5 #6 -0 S1- S2- T- K- P- W- H- -0 R- A- O- *1 *2 res1 res2 -0 pwr *3 *4 -E -U -F -R -0 -P -B -L -G -T -S -D -0 #7 #8 #9 #A #B #C -Z -``` - -Examples of steno strokes and the associated packet: -- `EUBG` = `10000000 00000000 00000000 00001100 00101000 00000000` -- `WAZ` = `10000000 00000010 00100000 00000000 00000000 00000001` -- `PHAPBGS` = `10000000 00000101 00100000 00000000 01101010 00000000` - -### Switching protocols on the fly :id=switching-protocols-on-the-fly - -If you wish to switch the serial protocol used to transfer the steno chords without having to recompile your keyboard firmware every time, you can press the `QK_STENO_BOLT` and `QK_STENO_GEMINI` keycodes in order to switch protocols on the fly. - -To enable these special keycodes, add the following lines to your `rules.mk`: -```mk -STENO_ENABLE = yes -STENO_PROTOCOL = all -``` - -If you want to switch protocols programatically, as part of a custom macro for example, don't use `tap_code(QK_STENO_*)`, as `tap_code` only supports [basic keycodes](keycodes_basic). Instead, you should use `steno_set_mode(STENO_MODE_*)`, whose valid arguments are `STENO_MODE_BOLT` and `STENO_MODE_GEMINI`. - -The default protocol is Gemini PR but the last protocol used is stored in non-volatile memory so QMK will remember your choice between reboots of your keyboard — assuming that your keyboard features (emulated) EEPROM. - -Naturally, this option takes the most amount of firmware space as it needs to compile the code for all the available stenography protocols. In most cases, compiling a single stenography protocol is sufficient. - -The default value for `STENO_PROTOCOL` is `all`. - -## Configuring QMK for Steno :id=configuring-qmk-for-steno - -After enabling stenography and optionally selecting a protocol, you may also need disable mouse keys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them. - -!> If you had *explicitly* set `VIRSTER_ENABLE = no`, none of the serial stenography protocols (GeminiPR, TX Bolt) will work properly. You are expected to either set it to `yes`, remove the line from your `rules.mk` or send the steno chords yourself in an alternative way using the [provided interceptable hooks](#interfacing-with-the-code). - -In your keymap, create a new layer for Plover, that you can fill in with the [steno keycodes](#keycode-reference). Remember to create a key to switch to the layer as well as a key for exiting the layer. - -Once you have your keyboard flashed, launch Plover. Click the 'Configure...' button. In the 'Machine' tab, select the Stenotype Machine that corresponds to your desired protocol. Click the 'Configure...' button on this tab and enter the serial port or click 'Scan'. Baud rate is fine at 9600 (although you should be able to set as high as 115200 with no issues). Use the default settings for everything else (Data Bits: 8, Stop Bits: 1, Parity: N, no flow control). - -To test your keymap, you can chord keys on your keyboard and either look at the output of the 'paper tape' (Tools > Paper Tape) or that of the 'layout display' (Tools > Layout Display). If your strokes correctly show up, you are now ready to steno! - -## Learning Stenography :id=learning-stenography - -* [Learn Plover!](https://sites.google.com/site/learnplover/) -* [Steno Jig](https://joshuagrams.github.io/steno-jig/) -* More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki - -## Interfacing with the code :id=interfacing-with-the-code - -The steno code has three interceptable hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things. - -```c -bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[MAX_STROKE_SIZE]); -``` - -This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen. - -```c -bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; } -``` - -This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values. - -```c -bool post_process_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[MAX_STROKE_SIZE], int8_t n_pressed_keys); -``` - -This function is called after a key has been processed, but before any decision about whether or not to send a chord. This is where to put hooks for things like, say, live displays of steno chords or keys. - -If `record->event.pressed` is false, and `n_pressed_keys` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This relieves you of the need of keeping track of where a packet ends and another begins. - -The `chord` argument contains the packet of the current chord as specified by the protocol in use. This is *NOT* simply a list of chorded steno keys of the form `[STN_E, STN_U, STN_BR, STN_GR]`. Refer to the appropriate protocol section of this document to learn more about the format of the packets in your steno protocol/mode of choice. - -The `n_pressed_keys` argument is the number of physical keys actually being held down. -This is not always equal to the number of bits set to 1 (aka the [Hamming weight](https://en.wikipedia.org/wiki/Hamming_weight)) in `chord` because it is possible to simultaneously press down four keys, then release three of those four keys and then press yet another key while the fourth finger is still holding down its key. -At the end of this scenario given as an example, `chord` would have five bits set to 1 but -`n_pressed_keys` would be set to 2 because there are only two keys currently being pressed down. - -## Keycode Reference :id=keycode-reference - -> Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both. - -|GeminiPR|TX Bolt|Steno Key| -|--------|-------|-----------| -|`STN_N1`|`STN_NUM`|Number bar #1| -|`STN_N2`|`STN_NUM`|Number bar #2| -|`STN_N3`|`STN_NUM`|Number bar #3| -|`STN_N4`|`STN_NUM`|Number bar #4| -|`STN_N5`|`STN_NUM`|Number bar #5| -|`STN_N6`|`STN_NUM`|Number bar #6| -|`STN_N7`|`STN_NUM`|Number bar #7| -|`STN_N8`|`STN_NUM`|Number bar #8| -|`STN_N9`|`STN_NUM`|Number bar #9| -|`STN_NA`|`STN_NUM`|Number bar #A| -|`STN_NB`|`STN_NUM`|Number bar #B| -|`STN_NC`|`STN_NUM`|Number bar #C| -|`STN_S1`|`STN_SL`| `S-` upper| -|`STN_S2`|`STN_SL`| `S-` lower| -|`STN_TL`|`STN_TL`| `T-`| -|`STN_KL`|`STN_KL`| `K-`| -|`STN_PL`|`STN_PL`| `P-`| -|`STN_WL`|`STN_WL`| `W-`| -|`STN_HL`|`STN_HL`| `H-`| -|`STN_RL`|`STN_RL`| `R-`| -|`STN_A`|`STN_A`| `A` vowel| -|`STN_O`|`STN_O`| `O` vowel| -|`STN_ST1`|`STN_STR`| `*` upper-left | -|`STN_ST2`|`STN_STR`| `*` lower-left| -|`STN_ST3`|`STN_STR`| `*` upper-right| -|`STN_ST4`|`STN_STR`| `*` lower-right| -|`STN_E`|`STN_E`| `E` vowel| -|`STN_U`|`STN_U`| `U` vowel| -|`STN_FR`|`STN_FR`| `-F`| -|`STN_RR`|`STN_RR`| `-R`| -|`STN_PR`|`STN_PR`| `-P`| -|`STN_BR`|`STN_BR`| `-B`| -|`STN_LR`|`STN_LR`| `-L`| -|`STN_GR`|`STN_GR`| `-G`| -|`STN_TR`|`STN_TR`| `-T`| -|`STN_SR`|`STN_SR`| `-S`| -|`STN_DR`|`STN_DR`| `-D`| -|`STN_ZR`|`STN_ZR`| `-Z`| -|`STN_FN`|| (Function)| -|`STN_RES1`||(Reset 1)| -|`STN_RES2`||(Reset 2)| -|`STN_PWR`||(Power)| - -If you do not want to hit two keys with one finger combined keycodes can be used. These cause both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file. - -|Combined key | Key1 | Key 2 | -|---------------|--------|----------| -|STN_S3 | STN_S1 | STN_S2 | -|STN_TKL | STN_TL | STN_KL | -|STN_PWL | STN_PL | STN_WL | -|STN_HRL | STN_HL | STN_RL | -|STN_FRR | STN_FR | STN_RR | -|STN_PBR | STN_PR | STN_BR | -|STN_LGR | STN_LR | STN_GR | -|STN_TSR | STN_TR | STN_SR | -|STN_DZR | STN_DR | STN_ZR | -|STN_AO | STN_A | STN_O | -|STN_EU | STN_E | STN_U | diff --git a/docs/feature_swap_hands.md b/docs/feature_swap_hands.md deleted file mode 100644 index e9c1d4b7ba..0000000000 --- a/docs/feature_swap_hands.md +++ /dev/null @@ -1,57 +0,0 @@ -# Swap-Hands Action - -The swap-hands action allows support for one-handed typing without requiring a separate layer. Set `SWAP_HANDS_ENABLE` in the Makefile and define a `hand_swap_config` entry in your keymap. Now whenever the `ACTION_SWAP_HANDS` command key is pressed the keyboard is mirrored. For instance, to type "Hello, World" on QWERTY you would type `^Ge^s^s^w^c W^wr^sd` - -## Configuration - -The configuration table is a simple 2-dimensional array to map from column/row to new column/row. Example `hand_swap_config` for Planck: - -```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}}, -}; -``` - -Note that the array indices are reversed same as the matrix and the values are of type `keypos_t` which is `{col, row}` and all values are zero-based. In the example above, `hand_swap_config[2][4]` (third row, fifth column) would return `{7, 2}` (third row, eighth column). Yes, this is confusing. - -## Swap Keycodes - -|Key |Aliases |Description | -|-----------------------------|---------|----------------------------------------------------| -|`SH_T(kc)` | |Momentary swap when held, `kc` when tapped | -|`QK_SWAP_HANDS_ON` |`SH_ON` |Turn on hand swap | -|`QK_SWAP_HANDS_OFF` |`SH_OFF` |Turn off hand swap | -|`QK_SWAP_HANDS_MOMENTARY_ON` |`SH_MON` |Turn on hand swap while held | -|`QK_SWAP_HANDS_MOMENTARY_OFF`|`SH_MOFF`|Turn off hand swap while held | -|`QK_SWAP_HANDS_TOGGLE` |`SH_TOGG`|Toggle hand swap | -|`QK_SWAP_HANDS_TAP_TOGGLE` |`SH_TT` |Momentary swap when held, toggle when tapped | -|`QK_SWAP_HANDS_ONE_SHOT` |`SH_OS` |Turn on hand swap while held or until next key press| - -`SH_TT` swap-hands tap-toggle key is similar to [layer tap-toggle](feature_layers.md?id=switching-and-toggling-layers). Tapping repeatedly (5 taps by default) will toggle swap-hands on or off, like `SH_TOGG`. Tap-toggle count can be changed by defining a value for `TAPPING_TOGGLE`. - -## Encoder Mapping - -When using an encoder mapping, it's also able to handle swapping encoders between sides, too. - -Encoder indexes are defined as left-to-right, and the extent of the array needs to match the number of encoders on the keyboard. - -As an example, if a split keyboard has a single encoder per side, you can swap the order by using the following code in your keymap: -```c -#if defined(SWAP_HANDS_ENABLE) && defined(ENCODER_MAP_ENABLE) -const uint8_t PROGMEM encoder_hand_swap_config[NUM_ENCODERS] = { 1, 0 }; -#endif -``` - -### Functions :id=functions - -User callback functions to manipulate Swap-Hands: - -| Function | Description | -|-----------------------|---------------------------------------------| -| `swap_hands_on()` | Turns Swap-Hands on. | -| `swap_hands_off()` | Turns Swap-Hands off. | -| `swap_hands_toggle()` | Toggles Swap-Hands. | -| `is_swap_hands_on()` | Returns true if Swap-Hands is currently on. | diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md deleted file mode 100644 index bb1c2c8034..0000000000 --- a/docs/feature_tap_dance.md +++ /dev/null @@ -1,563 +0,0 @@ -# Tap Dance: A Single Key Can Do 3, 5, or 100 Different Things - -## Introduction :id=introduction - -Hit the semicolon key once, send a semicolon. Hit it twice, rapidly -- send a colon. Hit it three times, and your keyboard's LEDs do a wild dance. That's just one example of what Tap Dance can do. It's one of the nicest community-contributed features in the firmware, conceived and created by [algernon](https://github.com/algernon) in [#451](https://github.com/qmk/qmk_firmware/pull/451). Here's how algernon describes the feature: - -With this feature one can specify keys that behave differently, based on the amount of times they have been tapped, and when interrupted, they get handled before the interrupter. - -## How to Use Tap Dance :id=how-to-use - -First, you will need `TAP_DANCE_ENABLE = yes` in your `rules.mk`, because the feature is disabled by default. This adds a little less than 1k to the firmware size. - -Optionally, you might want to set a custom `TAPPING_TERM` time by adding something like this in your `config.h` file: - -```c -#define TAPPING_TERM 175 -#define TAPPING_TERM_PER_KEY -``` - -The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. The `TAPPING_TERM_PER_KEY` definition is only needed if you control the tapping term through a [custom `get_tapping_term` function](tap_hold.md#tapping_term), which may be needed because `TAPPING_TERM` affects not just tap-dance keys. - -Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro. That macro takes a number which will later be used as an index into the `tap_dance_actions` array and turns it into a tap-dance keycode. - -After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options: - -* `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held. -* `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode). -* `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: Sends the `kc` keycode when tapped once, or toggles the state of `layer`. (this functions like the `TG` layer keycode). -* `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action. -* `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets. -* `ACTION_TAP_DANCE_FN_ADVANCED_WITH_RELEASE(on_each_tap_fn, on_each_release_fn, on_dance_finished_fn, on_dance_reset_fn)`: This macro is identical to `ACTION_TAP_DANCE_FN_ADVANCED` with the addition of `on_each_release_fn` which is invoked every time the key for the tap dance is released. It is worth noting that `on_each_release_fn` will still be called even when the key is released after the dance finishes (e.g. if the key is released after being pressed and held for longer than the `TAPPING_TERM`). - -The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. - -!> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported. - -Similar to the first option, the second and third option are good for simple layer-switching cases. - -For more complicated cases, like blink the LEDs, fiddle with the backlighting, and so on, use the fourth or fifth option. Examples of each are listed below. - -## Implementation Details :id=implementation - -Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works! - -Let's go over the three functions mentioned in `ACTION_TAP_DANCE_FN_ADVANCED` in a little more detail. They all receive the same two arguments: a pointer to a structure that holds all dance related state information, and a pointer to a use case specific state variable. The three functions differ in when they are called. The first, `on_each_tap_fn()`, is called every time the tap dance key is *pressed*. Before it is called, the counter is incremented and the timer is reset. The second function, `on_dance_finished_fn()`, is called when the tap dance is interrupted or ends because `TAPPING_TERM` milliseconds have passed since the last tap. When the `finished` field of the dance state structure is set to `true`, the `on_dance_finished_fn()` is skipped. After `on_dance_finished_fn()` was called or would have been called, but no sooner than when the tap dance key is *released*, `on_dance_reset_fn()` is called. It is possible to end a tap dance immediately, skipping `on_dance_finished_fn()`, but not `on_dance_reset_fn`, by calling `reset_tap_dance(state)`. - -To accomplish this logic, the tap dance mechanics use three entry points. The main entry point is `process_tap_dance()`, called from `process_record_quantum()` *after* `process_record_kb()` and `process_record_user()`. This function is responsible for calling `on_each_tap_fn()` and `on_dance_reset_fn()`. In order to handle interruptions of a tap dance, another entry point, `preprocess_tap_dance()` is run right at the beginning of `process_record_quantum()`. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. Finally, `tap_dance_task()` periodically checks whether `TAPPING_TERM` has passed since the last key press and finishes a tap dance if that is the case. - -This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness. - -## Examples :id=examples - -### Simple Example: Send `ESC` on Single Tap, `CAPS_LOCK` on Double Tap :id=simple-example - -Here's a simple example for a single definition: - -1. In your `rules.mk`, add `TAP_DANCE_ENABLE = yes` -2. In your `keymap.c` file, define the variables and definitions, then add to your keymap: - -```c -// Tap Dance declarations -enum { - TD_ESC_CAPS, -}; - -// Tap Dance definitions -tap_dance_action_t tap_dance_actions[] = { - // Tap once for Escape, twice for Caps Lock - [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS), -}; - -// Add tap dance item to your keymap in place of a keycode -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - // ... - TD(TD_ESC_CAPS) - // ... -}; -``` - -### Complex Examples :id=complex-examples - -This section details several complex tap dance examples. -All the enums used in the examples are declared like this: - -```c -// Enums defined for all examples: -enum { - TD_ESC_CAPS, - CT_EGG, - CT_FLSH, - CT_CLN, - X_CTL, -}; -``` - -#### Example 1: Send "Safety Dance!" After 100 Taps :id=example-1 - -```c -void dance_egg(tap_dance_state_t *state, void *user_data) { - if (state->count >= 100) { - SEND_STRING("Safety dance!"); - reset_tap_dance(state); - } -} - -tap_dance_action_t tap_dance_actions[] = { - [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg), -}; -``` - -#### Example 2: Turn LED Lights On Then Off, One at a Time :id=example-2 - -```c -// On each tap, light up one LED, from right to left -// On the fourth tap, turn them off from right to left -void dance_flsh_each(tap_dance_state_t *state, void *user_data) { - switch (state->count) { - case 1: - ergodox_right_led_3_on(); - break; - case 2: - ergodox_right_led_2_on(); - break; - case 3: - ergodox_right_led_1_on(); - break; - case 4: - ergodox_right_led_3_off(); - wait_ms(50); - ergodox_right_led_2_off(); - wait_ms(50); - ergodox_right_led_1_off(); - } -} - -// On the fourth tap, set the keyboard on flash state -void dance_flsh_finished(tap_dance_state_t *state, void *user_data) { - if (state->count >= 4) { - reset_keyboard(); - } -} - -// If the flash state didn't happen, then turn off LEDs, left to right -void dance_flsh_reset(tap_dance_state_t *state, void *user_data) { - ergodox_right_led_1_off(); - wait_ms(50); - ergodox_right_led_2_off(); - wait_ms(50); - ergodox_right_led_3_off(); -} - -// All tap dances now put together. Example 2 is "CT_FLSH" -tap_dance_action_t tap_dance_actions[] = { - [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS), - [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg), - [CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset) -}; -``` - -#### Example 3: Send `:` on Tap, `;` on Hold :id=example-3 - -With a little effort, powerful tap-hold configurations can be implemented as tap dances. To emit taps as early as possible, we need to act on releases of the tap dance key. There is no callback for this in the tap dance framework, so we use `process_record_user()`. - -```c -typedef struct { - uint16_t tap; - uint16_t hold; - uint16_t held; -} tap_dance_tap_hold_t; - -bool process_record_user(uint16_t keycode, keyrecord_t *record) { - tap_dance_action_t *action; - - switch (keycode) { - case TD(CT_CLN): // list all tap dance keycodes with tap-hold configurations - action = &tap_dance_actions[QK_TAP_DANCE_GET_INDEX(keycode)]; - if (!record->event.pressed && action->state.count && !action->state.finished) { - tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)action->user_data; - tap_code16(tap_hold->tap); - } - } - return true; -} - -void tap_dance_tap_hold_finished(tap_dance_state_t *state, void *user_data) { - tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)user_data; - - if (state->pressed) { - if (state->count == 1 -#ifndef PERMISSIVE_HOLD - && !state->interrupted -#endif - ) { - register_code16(tap_hold->hold); - tap_hold->held = tap_hold->hold; - } else { - register_code16(tap_hold->tap); - tap_hold->held = tap_hold->tap; - } - } -} - -void tap_dance_tap_hold_reset(tap_dance_state_t *state, void *user_data) { - tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)user_data; - - if (tap_hold->held) { - unregister_code16(tap_hold->held); - tap_hold->held = 0; - } -} - -#define ACTION_TAP_DANCE_TAP_HOLD(tap, hold) \ - { .fn = {NULL, tap_dance_tap_hold_finished, tap_dance_tap_hold_reset}, .user_data = (void *)&((tap_dance_tap_hold_t){tap, hold, 0}), } - -tap_dance_action_t tap_dance_actions[] = { - [CT_CLN] = ACTION_TAP_DANCE_TAP_HOLD(KC_COLN, KC_SCLN), -}; -``` - -#### Example 4: 'Quad Function Tap-Dance' :id=example-4 - -By [DanielGGordon](https://github.com/danielggordon) - -Allow one key to have 4 (or more) functions, depending on number of presses, and if the key is held or tapped. -Below is a specific example: -* Tap = Send `x` -* Hold = Send `Control` -* Double Tap = Send `Escape` -* Double Tap and Hold = Send `Alt` - -You will need a few things that can be used for 'Quad Function Tap-Dance'. - -You'll need to add these to the top of your `keymap.c` file, before your keymap. - -```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); - -// For the x tap dance. Put it here so it can be used in any keymap -void x_finished(tap_dance_state_t *state, void *user_data); -void x_reset(tap_dance_state_t *state, void *user_data); -``` - -Now, at the bottom of your `keymap.c` file, you'll need to add the following: - -```c -/* Return an integer that corresponds to what kind of tap dance should be executed. - * - * How to figure out tap dance state: interrupted and pressed. - * - * Interrupted: If the state of a dance is "interrupted", that means that another key has been hit - * under the tapping term. This is typically indicitive that you are trying to "tap" the key. - * - * Pressed: Whether or not the key is still being pressed. If this value is true, that means the tapping term - * has ended, but the key is still being pressed down. This generally means the key is being "held". - * - * One thing that is currenlty not possible with qmk software in regards to tap dance is to mimic the "permissive hold" - * feature. In general, advanced tap dances do not work well if they are used with commonly typed letters. - * For example "A". Tap dances are best used on non-letter keys that are not hit while typing letters. - * - * Good places to put an advanced tap dance: - * z,q,x,j,k,v,b, any function key, home/end, comma, semi-colon - * - * Criteria for "good placement" of a tap dance key: - * Not a key that is hit frequently in a sentence - * Not a key that is used frequently to double tap, for example 'tab' is often double tapped in a terminal, or - * in a web form. So 'tab' would be a poor choice for a tap dance. - * Letters used in common words as a double. For example 'p' in 'pepper'. If a tap dance function existed on the - * letter 'p', the word 'pepper' would be quite frustating to type. - * - * For the third point, there does exist the 'TD_DOUBLE_SINGLE_TAP', however this is not fully tested - * - */ -td_state_t cur_dance(tap_dance_state_t *state) { - if (state->count == 1) { - if (state->interrupted || !state->pressed) return TD_SINGLE_TAP; - // Key has not been interrupted, but the key is still held. Means you want to send a 'HOLD'. - else return TD_SINGLE_HOLD; - } else if (state->count == 2) { - // TD_DOUBLE_SINGLE_TAP is to distinguish between typing "pepper", and actually wanting a double tap - // action when hitting 'pp'. Suggested use case for this return value is when you want to send two - // keystrokes of the key, and not the 'double tap' action/macro. - if (state->interrupted) return TD_DOUBLE_SINGLE_TAP; - else if (state->pressed) return TD_DOUBLE_HOLD; - else return TD_DOUBLE_TAP; - } - - // Assumes no one is trying to type the same letter three times (at least not quickly). - // If your tap dance key is 'KC_W', and you want to type "www." quickly - then you will need to add - // an exception here to return a 'TD_TRIPLE_SINGLE_TAP', and define that enum just like 'TD_DOUBLE_SINGLE_TAP' - if (state->count == 3) { - if (state->interrupted || !state->pressed) return TD_TRIPLE_TAP; - else return TD_TRIPLE_HOLD; - } else return TD_UNKNOWN; -} - -// Create an instance of 'td_tap_t' for the 'x' tap dance. -static td_tap_t xtap_state = { - .is_press_action = true, - .state = TD_NONE -}; - -void x_finished(tap_dance_state_t *state, void *user_data) { - xtap_state.state = cur_dance(state); - switch (xtap_state.state) { - case TD_SINGLE_TAP: register_code(KC_X); break; - case TD_SINGLE_HOLD: register_code(KC_LCTL); break; - case TD_DOUBLE_TAP: register_code(KC_ESC); break; - case TD_DOUBLE_HOLD: register_code(KC_LALT); break; - // Last case is for fast typing. Assuming your key is `f`: - // For example, when typing the word `buffer`, and you want to make sure that you send `ff` and not `Esc`. - // In order to type `ff` when typing fast, the next character will have to be hit within the `TAPPING_TERM`, which by default is 200ms. - case TD_DOUBLE_SINGLE_TAP: tap_code(KC_X); register_code(KC_X); break; - default: break; - } -} - -void x_reset(tap_dance_state_t *state, void *user_data) { - switch (xtap_state.state) { - case TD_SINGLE_TAP: unregister_code(KC_X); break; - case TD_SINGLE_HOLD: unregister_code(KC_LCTL); break; - case TD_DOUBLE_TAP: unregister_code(KC_ESC); break; - case TD_DOUBLE_HOLD: unregister_code(KC_LALT); break; - case TD_DOUBLE_SINGLE_TAP: unregister_code(KC_X); break; - default: break; - } - xtap_state.state = TD_NONE; -} - -tap_dance_action_t tap_dance_actions[] = { - [X_CTL] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, x_finished, x_reset) -}; -``` - -And then simply use `TD(X_CTL)` anywhere in your keymap. - -> In this configuration "hold" takes place **after** tap dance timeout. To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`). - -#### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5 - -Tap dance can be used to emulate `MT()` and `LT()` behavior when the tapped code is not a basic keycode. This is useful to send tapped keycodes that normally require `Shift`, such as parentheses or curly braces—or other modified keycodes, such as `Control + X`. - -Below your layers and custom keycodes, add the following: - -```c -// Tap Dance keycodes -enum td_keycodes { - ALT_LP // Our example key: `LALT` when held, `(` when tapped. Add additional keycodes for each tapdance. -}; - -// Define a type containing as many tapdance states as you need -typedef enum { - TD_NONE, - TD_UNKNOWN, - TD_SINGLE_TAP, - TD_SINGLE_HOLD, - TD_DOUBLE_SINGLE_TAP -} td_state_t; - -// Create a global instance of the tapdance state type -static td_state_t td_state; - -// Declare your tapdance functions: - -// Function to determine the current tapdance state -td_state_t cur_dance(tap_dance_state_t *state); - -// `finished` and `reset` functions for each tapdance keycode -void altlp_finished(tap_dance_state_t *state, void *user_data); -void altlp_reset(tap_dance_state_t *state, void *user_data); -``` - -Below your `LAYOUT`, define each of the tapdance functions: - -```c -// Determine the tapdance state to return -td_state_t cur_dance(tap_dance_state_t *state) { - if (state->count == 1) { - if (state->interrupted || !state->pressed) return TD_SINGLE_TAP; - else return TD_SINGLE_HOLD; - } - - if (state->count == 2) return TD_DOUBLE_SINGLE_TAP; - else return TD_UNKNOWN; // Any number higher than the maximum state value you return above -} - -// Handle the possible states for each tapdance keycode you define: - -void altlp_finished(tap_dance_state_t *state, void *user_data) { - td_state = cur_dance(state); - switch (td_state) { - case TD_SINGLE_TAP: - register_code16(KC_LPRN); - break; - case TD_SINGLE_HOLD: - register_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_on(_MY_LAYER)` here - break; - case TD_DOUBLE_SINGLE_TAP: // Allow nesting of 2 parens `((` within tapping term - tap_code16(KC_LPRN); - register_code16(KC_LPRN); - break; - default: - break; - } -} - -void altlp_reset(tap_dance_state_t *state, void *user_data) { - switch (td_state) { - case TD_SINGLE_TAP: - unregister_code16(KC_LPRN); - break; - case TD_SINGLE_HOLD: - unregister_mods(MOD_BIT(KC_LALT)); // For a layer-tap key, use `layer_off(_MY_LAYER)` here - break; - case TD_DOUBLE_SINGLE_TAP: - unregister_code16(KC_LPRN); - break; - default: - break; - } -} - -// Define `ACTION_TAP_DANCE_FN_ADVANCED()` for each tapdance keycode, passing in `finished` and `reset` functions -tap_dance_action_t tap_dance_actions[] = { - [ALT_LP] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, altlp_finished, altlp_reset) -}; -``` - -Wrap each tapdance keycode in `TD()` when including it in your keymap, e.g. `TD(ALT_LP)`. - -#### Example 6: Using tap dance for momentary-layer-switch and layer-toggle keys :id=example-6 - -Tap Dance can be used to mimic MO(layer) and TG(layer) functionality. For this example, we will set up a key to function as `KC_QUOT` on single-tap, as `MO(_MY_LAYER)` on single-hold, and `TG(_MY_LAYER)` on double-tap. - -The first step is to include the following code towards the beginning of your `keymap.c`: - -```c -// Define a type for as many tap dance states as you need -typedef enum { - TD_NONE, - TD_UNKNOWN, - TD_SINGLE_TAP, - TD_SINGLE_HOLD, - TD_DOUBLE_TAP -} td_state_t; - -typedef struct { - bool is_press_action; - td_state_t state; -} td_tap_t; - -enum { - QUOT_LAYR, // Our custom tap dance key; add any other tap dance keys to this enum -}; - -// Declare the functions to be used with your tap dance key(s) - -// Function associated with all tap dances -td_state_t cur_dance(tap_dance_state_t *state); - -// Functions associated with individual tap dances -void ql_finished(tap_dance_state_t *state, void *user_data); -void ql_reset(tap_dance_state_t *state, void *user_data); -``` - -Towards the bottom of your `keymap.c`, include the following code: - -```c -// Determine the current tap dance state -td_state_t cur_dance(tap_dance_state_t *state) { - if (state->count == 1) { - if (!state->pressed) return TD_SINGLE_TAP; - else return TD_SINGLE_HOLD; - } else if (state->count == 2) return TD_DOUBLE_TAP; - else return TD_UNKNOWN; -} - -// Initialize tap structure associated with example tap dance key -static td_tap_t ql_tap_state = { - .is_press_action = true, - .state = TD_NONE -}; - -// Functions that control what our tap dance key does -void ql_finished(tap_dance_state_t *state, void *user_data) { - ql_tap_state.state = cur_dance(state); - switch (ql_tap_state.state) { - case TD_SINGLE_TAP: - tap_code(KC_QUOT); - break; - case TD_SINGLE_HOLD: - layer_on(_MY_LAYER); - break; - case TD_DOUBLE_TAP: - // Check to see if the layer is already set - if (layer_state_is(_MY_LAYER)) { - // If already set, then switch it off - layer_off(_MY_LAYER); - } else { - // If not already set, then switch the layer on - layer_on(_MY_LAYER); - } - break; - default: - break; - } -} - -void ql_reset(tap_dance_state_t *state, void *user_data) { - // If the key was held down and now is released then switch off the layer - if (ql_tap_state.state == TD_SINGLE_HOLD) { - layer_off(_MY_LAYER); - } - ql_tap_state.state = TD_NONE; -} - -// Associate our tap dance key with its functionality -tap_dance_action_t tap_dance_actions[] = { - [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, ql_finished, ql_reset) -}; - -// Set a long-ish tapping term for tap-dance keys -uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { - case QK_TAP_DANCE ... QK_TAP_DANCE_MAX: - return 275; - default: - return TAPPING_TERM; - } -} -``` - -The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is(layer)` function which returns `true` if the given `layer` is active. - -The use of `cur_dance()` and `ql_tap_state` mirrors the above examples. - -The `case: TD_SINGLE_TAP` in `ql_finished` is similar to the above examples. The `TD_SINGLE_HOLD` case works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `TD_DOUBLE_TAP` case works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`. - -`tap_dance_actions[]` works similar to the above examples. Note that, additionally, I set a longer tapping term for the tap dance keys. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here. In order for the per-key tapping terms to take effect, `TAPPING_TERM_PER_KEY` must be defined in your `config.h`. - -Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`. diff --git a/docs/feature_tri_layer.md b/docs/feature_tri_layer.md deleted file mode 100644 index 3087fb5a55..0000000000 --- a/docs/feature_tri_layer.md +++ /dev/null @@ -1,48 +0,0 @@ -# Tri Layers :id=tri-layers - -This enables support for the OLKB style "Tri Layer" keycodes. These function similar to the `MO` (momentary) function key, but if both the "Lower" and "Upper" keys are pressed, it activates a third "Adjust" layer. To enable this functionality, add this line to your `rules.mk`: - -```make -TRI_LAYER_ENABLE = yes -``` - -Note that the "upper", "lower" and "adjust" names don't have a particular significance, they are just used to identify and clarify the behavior. Layers are processed from highest numeric value to lowest, however the values are not required to be consecutive. - -For a detailed explanation of how the layer stack works, check out [Keymap Overview](keymap.md#keymap-and-layers). - -## Keycodes :id=keycodes - -| Keycode | Alias | Description | -|----------------------|-----------|---------------------------------------------------------------------------------------------------------| -| `QK_TRI_LAYER_LOWER` | `TL_LOWR` | Momentarily enables the "lower" layer. Enables the "adjust" layer if the "upper" layer is also enabled" | -| `QK_TRI_LAYER_UPPER` | `TL_UPPR` | Momentarily enables the "upper" layer. Enables the "adjust" layer if the "lower" layer is also enabled" | - -## Configuration - -To change the default values for the layers, you can change these defines, in your `config.h` - -| Config name | Default | Description | -|--------------------------|---------|------------------------------------------| -| `TRI_LAYER_LOWER_LAYER` | `1` | Sets the default for the "lower" layer. | -| `TRI_LAYER_UPPER_LAYER` | `2` | Sets the default for the "upper" layer. | -| `TRI_LAYER_ADJUST_LAYER` | `3` | Sets the default for the "adjust" layer. | - -Eg, if you wanted to set the "Adjust" layer to be layer 5, you'd add this to your `config.h`: - -```c -#define TRI_LAYER_ADJUST_LAYER 5 -``` - -## Functions - -| Function name | Description | -|----------------------------------------------|-------------------------------------------------| -| `set_tri_layer_lower_layer(layer)` | Changes the "lower" layer*. | -| `set_tri_layer_upper_layer(layer)` | Changes the "upper" layer*. | -| `set_tri_layer_adjust_layer(layer)` | Changes the "adjust" layer*. | -| `set_tri_layer_layers(lower, upper, adjust)` | Sets the "lower", "upper" and "adjust" layers*. | -| `get_tri_layer_lower_layer()` | Gets the current "lower" layer. | -| `get_tri_layer_upper_layer()` | Gets the current "upper" layer. | -| `get_tri_layer_adjust_layer()` | Gets the current "adjust" layer. | - -!> Note: these settings are not persistent, and will be reset to the default on power loss or power cycling of the controller. diff --git a/docs/feature_unicode.md b/docs/feature_unicode.md deleted file mode 100644 index 2c6d2ef002..0000000000 --- a/docs/feature_unicode.md +++ /dev/null @@ -1,452 +0,0 @@ -# Unicode :id=unicode - -With a little help from your OS, practically any Unicode character can be input using your keyboard. - -## Caveats :id=caveats - -There are some limitations to this feature. Because there is no "standard" method of Unicode input across all operating systems, each of them require their own setup process on both the host *and* in the firmware, which may involve installation of additional software. This also means Unicode input will not "just work" when the keyboard is plugged into another device. - -## Usage :id=usage - -The core Unicode API can be used purely programmatically. However, there are also additional subsystems which build on top of it and come with keycodes to make things easier. See below for more details. - -Add the following to your keymap's `rules.mk`: - -```make -UNICODE_COMMON = yes -``` - -## Basic Configuration :id=basic-configuration - -Add the following to your `config.h`: - -|Define |Default |Description | -|------------------------|------------------|--------------------------------------------------------------------------------| -|`UNICODE_KEY_MAC` |`KC_LEFT_ALT` |The key to hold when beginning a Unicode sequence with the macOS input mode | -|`UNICODE_KEY_LNX` |`LCTL(LSFT(KC_U))`|The key to tap when beginning a Unicode sequence with the Linux input mode | -|`UNICODE_KEY_WINC` |`KC_RIGHT_ALT` |The key to hold when beginning a Unicode sequence with the WinCompose input mode| -|`UNICODE_SELECTED_MODES`|`-1` |A comma separated list of input modes for cycling through | -|`UNICODE_CYCLE_PERSIST` |`true` |Whether to persist the current Unicode input mode to EEPROM | -|`UNICODE_TYPE_DELAY` |`10` |The amount of time to wait, in milliseconds, between Unicode sequence keystrokes| - -### Audio Feedback :id=audio-feedback - -If you have the [Audio](feature_audio.md) feature enabled on your board, you can configure it to play sounds when the input mode is changed. - -Add the following to your `config.h`: - -|Define |Default|Description | -|-------------------|-------|-----------------------------------------------------------| -|`UNICODE_SONG_MAC` |*n/a* |The song to play when the macOS input mode is selected | -|`UNICODE_SONG_LNX` |*n/a* |The song to play when the Linux input mode is selected | -|`UNICODE_SONG_BSD` |*n/a* |The song to play when the BSD input mode is selected | -|`UNICODE_SONG_WIN` |*n/a* |The song to play when the Windows input mode is selected | -|`UNICODE_SONG_WINC`|*n/a* |The song to play when the WinCompose input mode is selected| - -## Input Subsystems :id=input-subsystems - -Each of these subsystems have their own pros and cons in terms of flexibility and ease of use. Choose the one that best fits your needs. - - - -### ** Basic ** - -This is the easiest to use, albeit somewhat limited. It supports code points up to `U+7FFF`, which covers characters for most modern languages (including East Asian), as well as many symbols, but does not include emoji. - -To enable Basic Unicode, add the following to your `rules.mk`: - -```make -UNICODE_ENABLE = yes -``` - -You can then add `UC(c)` keycodes to your keymap, where *c* is the code point of the desired character (in hexadecimal - the `U+` prefix will not work). For example, `UC(0x40B)` will output [Ћ](https://unicode-table.com/en/040B/), and `UC(0x30C4)` will output [ツ](https://unicode-table.com/en/30C4). - -### ** Unicode Map ** - -Unicode Map supports all possible code points (up to `U+10FFFF`). Here, the code points are stored in a separate mapping table (which may contain at most 16,384 entries), instead of directly in the keymap. - -To enable Unicode Map, add the following to your `rules.mk`: - -```make -UNICODEMAP_ENABLE = yes -``` - -Then, you will need to create a mapping table in your `keymap.c`, and (optionally) an enum for naming the array indices, like so: - -```c -enum unicode_names { - BANG, - IRONY, - SNEK -}; - -const uint32_t PROGMEM unicode_map[] = { - [BANG] = 0x203D, // ‽ - [IRONY] = 0x2E2E, // ⸮ - [SNEK] = 0x1F40D, // 🐍 -}; -``` - -Finally, add `UM(i)` keycodes to your keymap, where *i* is an index into the `unicode_map[]` array. If you defined the enum above, you can use those names instead, for example `UM(BANG)` or `UM(SNEK)`. - -#### Lower and Upper Case Pairs :id=unicodemap-pairs - -Some writing systems have lowercase and uppercase variants of each character, such as å and Å. To make inputting these characters easier, you can use the `UP(i, j)` keycode in your keymap, where *i* and *j* are the mapping table indices of the lowercase and uppercase characters, respectively. If you're holding down Shift or have Caps Lock turned on when you press the key, the uppercase character will be inserted; otherwise, the lowercase character will be inserted. - -```c -const uint32_t PROGMEM unicode_map[] = { - [AE_LOWER] = 0x00E6, // æ - [AE_UPPER] = 0x00C6, // Æ -}; -``` - -This is most useful when creating a keymap for an international layout with special characters. Instead of having to put the lower and upper case versions of a character on separate keys, you can have them both on the same key. This helps blend Unicode keys in with regular keycodes. - -Due to keycode size constraints, *i* and *j* can each only refer to one of the first 128 characters in your `unicode_map`. In other words, 0 ≤ *i* ≤ 127 and 0 ≤ *j* ≤ 127. - -### ** UCIS ** - -As with Unicode Map, the UCIS method also supports all possible code points, and requires the use of a mapping table. However, it works much differently - Unicode characters are input by replacing a typed mnemonic. - -To enable UCIS, add the following to your keymap's `rules.mk`: - -```make -UCIS_ENABLE = yes -``` - -Then, create a mapping table in your `keymap.c`: - -```c -const ucis_symbol_t ucis_symbol_table[] = UCIS_TABLE( - UCIS_SYM("poop", 0x1F4A9), // 💩 - UCIS_SYM("rofl", 0x1F923), // 🤣 - UCIS_SYM("ukr", 0x1F1FA, 0x1F1E6), // 🇺🇦 - UCIS_SYM("look", 0x0CA0, 0x005F, 0x0CA0) // ಠ_ಠ -); -``` - -By default, each table entry may be up to three code points long. This can be changed by adding `#define UCIS_MAX_CODE_POINTS n` to your keymap's `config.h`. - -To invoke UCIS input, the `ucis_start()` function must first be called (for example, in a custom "Unicode" keycode). Then, type the mnemonic for the mapping table entry (such as "rofl"), and hit Space or Enter. The "rofl" text will be backspaced and the emoji inserted. - - - -## Input Modes :id=input-modes - -Unicode input works by typing a sequence of characters, similar to a macro. However, since this sequence depends on your OS, you will need to prepare both your host machine and QMK to recognise and send the correct Unicode input sequences respectively. - -To set the list of enabled input modes, add the `UNICODE_SELECTED_MODES` define to your keymap's `config.h`, for example: - -```c -#define UNICODE_SELECTED_MODES UNICODE_MODE_LINUX -// or -#define UNICODE_SELECTED_MODES UNICODE_MODE_MACOS, UNICODE_MODE_WINCOMPOSE -``` - -These modes can then be cycled through using the `UC_NEXT` and `UC_PREV` keycodes. You can also switch to any input mode, even if it is not specified in `UNICODE_SELECTED_MODES`, using their respective keycodes. - -If your keyboard has working EEPROM, it will remember the last used input mode and continue using it on the next power up. This can be disabled by defining `UNICODE_CYCLE_PERSIST` to `false`. - - - -### ** macOS ** - -**Mode Name:** `UNICODE_MODE_MACOS` - -macOS has built-in support for Unicode input as its own input source. It supports all possible code points by way of surrogate pairs for code points above `U+FFFF`. - -To enable, go to **System Preferences → Keyboard → Input Sources**, then add Unicode Hex Input to the list (under Other), and activate it from the input dropdown in the menu bar. Note that this may disable some Option-based shortcuts such as Option+Left and Option+Right. - -### ** Linux (IBus) ** - -**Mode Name:** `UNICODE_MODE_LINUX` - -For Linux distros with IBus, Unicode input is enabled by default, supports all possible code points, and works almost anywhere. Without IBus, it works under GTK apps, but rarely anywhere else. - -Users who would like support in non-GTK apps without IBus may need to resort to a more indirect method, such as creating a custom keyboard layout. - -### ** Windows (WinCompose) ** - -**Mode Name:** `UNICODE_MODE_WINCOMPOSE` - -This mode requires a third-party tool called [WinCompose](https://github.com/samhocevar/wincompose). It supports all possible code points, and is the recommended input mode for Windows. - -To enable, install the [latest release from GitHub](https://github.com/samhocevar/wincompose/releases/latest). Once installed, it will automatically run on startup. This works reliably under all versions of Windows supported by WinCompose. - -### ** Windows (HexNumpad) ** - -**Mode Name:** `UNICODE_MODE_WINDOWS` - -!> This input mode is *not* the "Alt code" system. Alt codes are not Unicode; they instead follow [the Windows-1252 character set](https://en.wikipedia.org/wiki/Alt_code). - -This is Windows' built-in hex numpad Unicode input mode. It only supports code points up to `U+FFFF`, and is not recommended due to reliability and compatibility issues. - -To enable, run the following as an administrator, then reboot: - -``` -reg add "HKCU\Control Panel\Input Method" -v EnableHexNumpad -t REG_SZ -d 1 -``` - -### ** Emacs ** - -**Mode Name:** `UNICODE_MODE_EMACS` - -Emacs supports code point input with the `insert-char` command. - -### ** BSD ** - -**Mode Name:** `UNICODE_MODE_BSD` - -Not currently implemented. If you're a BSD user and want to contribute support for this input mode, please [feel free](contributing.md)! - - - -## Keycodes :id=keycodes - -|Key |Aliases |Description | -|----------------------------|---------|----------------------------------------------------------------| -|`UC(c)` | |Send Unicode code point `c`, up to `0x7FFF` | -|`UM(i)` | |Send Unicode code point at index `i` in `unicode_map` | -|`UP(i, j)` | |Send Unicode code point at index `i`, or `j` if Shift/Caps is on| -|`QK_UNICODE_MODE_NEXT` |`UC_NEXT`|Cycle through selected input modes | -|`QK_UNICODE_MODE_PREVIOUS` |`UC_PREV`|Cycle through selected input modes in reverse | -|`QK_UNICODE_MODE_MACOS` |`UC_MAC` |Switch to macOS input | -|`QK_UNICODE_MODE_LINUX` |`UC_LINX`|Switch to Linux input | -|`QK_UNICODE_MODE_WINDOWS` |`UC_WIN` |Switch to Windows input | -|`QK_UNICODE_MODE_BSD` |`UC_BSD` |Switch to BSD input (not implemented) | -|`QK_UNICODE_MODE_WINCOMPOSE`|`UC_WINC`|Switch to Windows input using WinCompose | -|`QK_UNICODE_MODE_EMACS` |`UC_EMAC`|Switch to emacs (`C-x-8 RET`) | - -## API :id=api - -### `uint8_t get_unicode_input_mode(void)` :id=api-get-unicode-input-mode - -Get the current Unicode input mode. - -#### Return Value :id=api-get-unicode-input-mode-return-value - -The currently active Unicode input mode. - ---- - -### `void set_unicode_input_mode(uint8_t mode)` :id=api-set-unicode-input-mode - -Set the Unicode input mode. - -#### Arguments :id=api-set-unicode-input-mode-arguments - - - `uint8_t mode` - The input mode to set. - ---- - -### `void unicode_input_mode_step(void)` : id=api-unicode-input-mode-step - -Change to the next Unicode input mode. - ---- - -### `void unicode_input_mode_step_reverse(void)` : id=api-unicode-input-mode-step-reverse - -Change to the previous Unicode input mode. - ---- - -### `void unicode_input_mode_set_user(uint8_t input_mode)` :id=api-unicode-input-mode-set-user - -User-level callback, invoked when the input mode is changed. - -#### Arguments :id=api-unicode-input-mode-set-user-arguments - - - `uint8_t input_mode` - The new input mode. - ---- - -### `void unicode_input_mode_set_kb(uint8_t input_mode)` :id=api-unicode-input-mode-set-kb - -Keyboard-level callback, invoked when the input mode is changed. - -#### Arguments :id=api-unicode-input-mode-set-kb-arguments - - - `uint8_t input_mode` - The new input mode. - ---- - -### `void unicode_input_start(void)` :id=api-unicode-input-start - -Begin the Unicode input sequence. The exact behavior depends on the currently selected input mode: - - - **macOS**: Hold `UNICODE_KEY_MAC` - - **Linux**: Tap `UNICODE_KEY_LNX` - - **WinCompose**: Tap `UNICODE_KEY_WINC`, then U - - **HexNumpad**: Hold Left Alt, then tap Numpad + - - **Emacs**: Tap Ctrl+X, then 8, then Enter - -This function is weakly defined, and can be overridden in user code. - ---- - -### `void unicode_input_finish(void)` :id=api-unicode-input-finish - -Complete the Unicode input sequence. The exact behavior depends on the currently selected input mode: - - - **macOS**: Release `UNICODE_KEY_MAC` - - **Linux**: Tap Space - - **WinCompose**: Tap Enter - - **HexNumpad**: Release Left Alt - - **Emacs**: Tap Enter - -This function is weakly defined, and can be overridden in user code. - ---- - -### `void unicode_input_cancel(void)` :id=api-unicode-input-cancel - -Cancel the Unicode input sequence. The exact behavior depends on the currently selected input mode: - - - **macOS**: Release `UNICODE_KEY_MAC` - - **Linux**: Tap Escape - - **WinCompose**: Tap Escape - - **HexNumpad**: Release Left Alt - - **Emacs**: Tap Ctrl+G - -This function is weakly defined, and can be overridden in user code. - ---- - -### `void register_unicode(uint32_t code_point)` :id=api-register-unicode - -Input a single Unicode character. A surrogate pair will be sent if required by the input mode. - -#### Arguments :id=api-register-unicode-arguments - - - `uint32_t code_point` - The code point of the character to send. - ---- - -### `void send_unicode_string(const char *str)` :id=api-send-unicode-string - -Send a string containing Unicode characters. - -#### Arguments :id=api-send-unicode-string-arguments - - - `const char *str` - The string to send. - ---- - -### `uint8_t unicodemap_index(uint16_t keycode)` :id=api-unicodemap-index - -Get the index into the `unicode_map` array for the given keycode, respecting shift state for pair keycodes. - -#### Arguments :id=api-unicodemap-index-arguments - - - `uint16_t keycode` - The Unicode Map keycode to get the index of. - -#### Return Value :id=api-unicodemap-index-return-value - -An index into the `unicode_map` array. - ---- - -### `uint32_t unicodemap_get_code_point(uint8_t index)` :id=api-unicodemap-get-code-point - -Get the code point for the given index in the `unicode_map` array. - -#### Arguments :id=unicodemap-get-code-point-arguments - - - `uint8_t index` - The index into the `unicode_map` array. - -#### Return Value :id=unicodemap-get-code-point-return-value - -A Unicode code point value. - ---- - -### `void register_unicodemap(uint8_t index)` :id=api-register-unicodemap - -Send the code point for the given index in the `unicode_map` array. - -#### Arguments :id=api-register-unicodemap-arguments - - - `uint8_t index` - The index into the `unicode_map` array. - ---- - -### `void ucis_start(void)` :id=api-ucis-start - -Begin the input sequence. - ---- - -### `bool ucis_active(void)` :id=api-ucis-active - -Whether UCIS is currently active. - -#### Return Value :id=api-ucis-active-return-value - -`true` if UCIS is active. - ---- - -### `uint8_t ucis_count(void)` :id=api-ucis-count - -Get the number of characters in the input sequence buffer. - -#### Return Value :id=api-ucis-count-return-value - -The current input sequence buffer length. - ---- - -### `bool ucis_add(uint16_t keycode)` :id=api-ucis-add - -Add the given keycode to the input sequence buffer. - -#### Arguments :id=api-ucis-add-arguments - - - `uint16_t keycode` - The keycode to add. Must be between `KC_A` and `KC_Z`, or `KC_1` and `KC_0`. - -#### Return Value :id=api-ucis-add-return-value - -`true` if the keycode was added. - ---- - -### `bool ucis_remove_last(void)` :id=api-ucis-remove-last - -Remove the last character from the input sequence buffer. - -#### Return Value :id=api-ucis-remove-last - -`true` if the sequence was not empty. - ---- - -### `void ucis_finish(void)` :id=api-ucis-finish - -Mark the input sequence as complete, and attempt to match. - ---- - -### `void ucis_cancel(void)` :id=api-ucis-cancel - -Cancel the input sequence. - ---- - -### `void register_ucis(void)` :id=api-register-ucis - -Send the code point(s) for the given UCIS index. - -#### Arguments :id=api-register-ucis-arguments - - - `uint8_t index` - The index into the UCIS symbol table. diff --git a/docs/feature_userspace.md b/docs/feature_userspace.md index aabf18e393..2c8c08b38e 100644 --- a/docs/feature_userspace.md +++ b/docs/feature_userspace.md @@ -1,6 +1,8 @@ # Userspace: Sharing Code Between Keymaps -!> Please note, userspace submissions to the upstream `qmk/qmk_firmware` repository are no longer being accepted. The userspace feature itself remains functional and can be configured locally. +::: warning +Please note, userspace submissions to the upstream `qmk/qmk_firmware` repository are no longer being accepted. The userspace feature itself remains functional and can be configured locally. +::: If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in `users/` named the same as your keymap (ideally your GitHub username, `