diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 2 | ||||
| -rw-r--r-- | docs/compatible_microcontrollers.md | 5 | ||||
| -rw-r--r-- | docs/config_options.md | 2 | ||||
| -rw-r--r-- | docs/data_driven_config.md | 91 | ||||
| -rw-r--r-- | docs/feature_backlight.md | 24 | ||||
| -rw-r--r-- | docs/feature_macros.md | 113 | ||||
| -rw-r--r-- | docs/feature_mouse_keys.md | 31 | ||||
| -rw-r--r-- | docs/feature_pointing_device.md | 2 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 22 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 13 | ||||
| -rw-r--r-- | docs/feature_split_keyboard.md | 10 | ||||
| -rw-r--r-- | docs/ja/compatible_microcontrollers.md | 5 | ||||
| -rw-r--r-- | docs/ja/feature_macros.md | 113 | ||||
| -rw-r--r-- | docs/ja/feature_mouse_keys.md | 3 | ||||
| -rw-r--r-- | docs/ja/proton_c_conversion.md | 1 | ||||
| -rw-r--r-- | docs/proton_c_conversion.md | 1 | ||||
| -rw-r--r-- | docs/reference_info_json.md | 158 | ||||
| -rw-r--r-- | docs/reference_keymap_extras.md | 2 | ||||
| -rw-r--r-- | docs/serial_driver.md | 1 | ||||
| -rw-r--r-- | docs/spi_driver.md | 12 | ||||
| -rw-r--r-- | docs/uart_driver.md | 90 |
21 files changed, 444 insertions, 257 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 5af0046ab3..526caf926f 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -138,6 +138,7 @@ * [WS2812 Driver](ws2812_driver.md) * [EEPROM Driver](eeprom_driver.md) * ['serial' Driver](serial_driver.md) + * [UART Driver](uart_driver.md) * [GPIO Controls](internals_gpio_control.md) * [Keyboard Guidelines](hardware_keyboard_guidelines.md) @@ -159,6 +160,7 @@ * [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) diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 1bf7072246..47a4844e7f 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -9,6 +9,7 @@ The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB * [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2) * [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4) * [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286) +* [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162) Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) instead: @@ -25,6 +26,10 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html) * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html) * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) + * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) + * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) + * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) + * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) ### NXP (Kinetis) diff --git a/docs/config_options.md b/docs/config_options.md index a3262b418b..9a64b9b3d2 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -97,6 +97,8 @@ This is a C header file that is one of the first things included, and will persi * sets the maximum power (in mA) over USB for the device (default: 500) * `#define USB_POLLING_INTERVAL_MS 10` * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces +* `#define USB_SUSPEND_WAKEUP_DELAY 200` + * set the number of milliseconde to pause after sending a wakeup packet * `#define F_SCL 100000L` * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`. diff --git a/docs/data_driven_config.md b/docs/data_driven_config.md new file mode 100644 index 0000000000..c2ad4fed8f --- /dev/null +++ b/docs/data_driven_config.md @@ -0,0 +1,91 @@ +# Data Driven Configuration + +This page describes how QMK's data driven JSON configuration system works. It is aimed at developers who want to work on QMK itself. + +## History + +Historically QMK has been configured through a combination of two mechanisms- `rules.mk` and `config.h`. While this worked well when QMK was only a handful of keyboards we've grown to encompass nearly 1500 supported keyboards. That extrapolates out to 6000 configuration files under `keyboards/` alone! The freeform nature of these files and the unique patterns people have used to avoid duplication have made ongoing maintenance a challenge, and a large number of our keyboards follow patterns that are outdated and sometimes harder to understand. + +We have also been working on bringing the power of QMK to people who aren't comformable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `info.json`- into a single source of truth that end-user tools can use. + +Now we have support for generating `rules.mk` and `config.h` values from `info.json`, allowing us to have a single source of truth. This will allow us to use automated tooling to maintain keyboards saving a lot of time and maintenance work. + +## Overview + +On the C side of things nothing changes. When you need to create a new rule or define you follow the same process: + +1. Add it to `docs/config_options.md` +1. Set a default in the appropriate core file +1. Add your ifdef statements as needed + +You will then need to add support for your new configuration to `info.json`. The basic process is: + +1. Add it to the schema in `data/schemas/keyboards.jsonschema` +1. Add a mapping in `data/maps` +1. (optional and discoraged) Add code to extract/generate it to: + * `lib/python/qmk/info.py` + * `lib/python/qmk/cli/generate/config_h.py` + * `lib/python/qmk/cli/generate/rules_mk.py` + +## Adding an option to info.json + +This section describes adding support for a `config.h`/`rules.mk` value to info.json. + +### Add it to the schema + +QMK maintains [jsonschema](https://json-schema.org/) files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here. + +In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options. + +In other cases you should group like options together in an `object`. This is particularly true when adding support for a feature. Some examples to follow for this are `indicators`, `matrix_pins`, and `rgblight`. If you are not sure how to integrate your new option(s) [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there. + +### Add a mapping + +In most cases you can add a simple mapping. These are maintained as JSON files in `data/mappings/info_config.json` and `data/mappings/info_rules.json`, and control mapping for `config.h` and `rules.mk`, respectively. Each mapping is keyed by the `config.h` or `rules.mk` variable, and the value is a hash with the following keys: + +* `info_key`: (required) The location within `info.json` for this value. See below. +* `value_type`: (optional) Default `str`. The format for this variable's value. See below. +* `to_json`: (optional) Default `true`. Set to `false` to exclude this mapping from info.json +* `to_c`: (optional) Default `true`. Set to `false` to exclude this mapping from config.h +* `warn_duplicate`: (optional) Default `true`. Set to `false` to turn off warning when a value exists in both places + +#### Info Key + +We use JSON dot notation to address variables within info.json. For example, to access `info_json["rgblight"]["split_count"]` I would specify `rgblight.split_count`. This allows you to address deeply nested keys with a simple string. + +Under the hood we use [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/), you can refer to that documentation for how these strings are converted to object access. + +#### Value Types + +By default we treat all values as simple strings. If your value is more complex you can use one of these types to intelligently parse the data: + +* `array`: A comma separated array of strings +* `array.int`: A comma separated array of integers +* `int`: An integer +* `hex`: A number formatted as hex +* `list`: A space separate array of strings +* `mapping`: A hash of key/value pairs + +### Add code to extract it + +Most use cases can be solved by the mapping files described above. If yours can't you can instead write code to extract your config values. + +Whenever QMK generates a complete `info.json` it extracts information from `config.h` and `rules.mk`. You will need to add code for your new config value to `lib/python/qmk/info.py`. Typically this means adding a new `_extract_<feature>()` function and then calling your function in either `_extract_config_h()` or `_extract_rules_mk()`. + +If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part. + +### Add code to generate it + +The final piece of the puzzle is providing your new option to the build system. This is done by generating two files: + +* `.build/obj_<keyboard>/src/info_config.h` +* `.build/obj_<keyboard>/src/rules.mk` + +These two files are generated by the code here: + +* `lib/python/qmk/cli/generate/config_h.py` +* `lib/python/qmk/cli/generate/rules_mk.py` + +For `config.h` values you'll need to write a function for your rule(s) and call that function in `generate_config_h()`. + +If you have a new top-level `info.json` key for `rules.mk` you can simply add your keys to `info_to_rules` at the top of `lib/python/qmk/cli/generate/rules_mk.py`. Otherwise you'll need to create a new if block for your feature in `generate_rules_mk()`. diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index a558af64e1..2adb16e4a8 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -93,18 +93,18 @@ BACKLIGHT_DRIVER = pwm On AVR boards, QMK automatically decides which driver to use according to the following table: -|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P| -|-------------|-------------|-------------|-------------|---------|-----------| -|`B1` | | | | |Timer 1 | -|`B2` | | | | |Timer 1 | -|`B5` |Timer 1 |Timer 1 | | | | -|`B6` |Timer 1 |Timer 1 | | | | -|`B7` |Timer 1 |Timer 1 |Timer 1 | | | -|`C4` |Timer 3 | | | | | -|`C5` |Timer 3 | |Timer 1 | | | -|`C6` |Timer 3 |Timer 3 |Timer 1 | | | -|`D4` | | | |Timer 1 | | -|`D5` | | | |Timer 1 | | +|Backlight Pin|AT90USB64/128|AT90USB162|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P| +|-------------|-------------|----------|-------------|-------------|---------|-----------| +|`B1` | | | | | |Timer 1 | +|`B2` | | | | | |Timer 1 | +|`B5` |Timer 1 | |Timer 1 | | | | +|`B6` |Timer 1 | |Timer 1 | | | | +|`B7` |Timer 1 |Timer 1 |Timer 1 |Timer 1 | | | +|`C4` |Timer 3 | | | | | | +|`C5` |Timer 3 |Timer 1 | |Timer 1 | | | +|`C6` |Timer 3 |Timer 1 |Timer 3 |Timer 1 | | | +|`D4` | | | | |Timer 1 | | +|`D5` | | | | |Timer 1 | | All other pins will use timer-assisted software PWM: diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 36fa761d21..aa1ebc337a 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -4,7 +4,7 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has !> **Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets a hold of your keyboard will be able to access that information by opening a text editor. -## The New Way: `SEND_STRING()` & `process_record_user` +## `SEND_STRING()` & `process_record_user` Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`). @@ -262,15 +262,15 @@ This will clear all keys besides the mods currently pressed. This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows. ```c -bool is_alt_tab_active = false; # ADD this near the begining of keymap.c -uint16_t alt_tab_timer = 0; # we will be using them soon. +bool is_alt_tab_active = false; // ADD this near the begining of keymap.c +uint16_t alt_tab_timer = 0; // we will be using them soon. -enum custom_keycodes { # Make sure have the awesome keycode ready +enum custom_keycodes { // Make sure have the awesome keycode ready ALT_TAB = SAFE_RANGE, }; bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { # This will do most of the grunt work with the keycodes. + switch (keycode) { // This will do most of the grunt work with the keycodes. case ALT_TAB: if (record->event.pressed) { if (!is_alt_tab_active) { @@ -287,7 +287,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { return true; } -void matrix_scan_user(void) { # The very important timer. +void matrix_scan_user(void) { // The very important timer. if (is_alt_tab_active) { if (timer_elapsed(alt_tab_timer) > 1000) { unregister_code(KC_LALT); @@ -296,104 +296,3 @@ void matrix_scan_user(void) { # The very important timer. } } ``` - ---- - -## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro` - -!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead. - -By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example: - -```c -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - if (record->event.pressed) { - switch(id) { - case 0: - return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END); - case 1: - return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END); - } - } - return MACRO_NONE; -}; -``` - -This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement: - - if (!record->event.pressed) { - -### Macro Commands - -A macro can include the following commands: - -* I() change interval of stroke in milliseconds. -* D() press key. -* U() release key. -* T() type key(press and release). -* W() wait (milliseconds). -* END end mark. - -### Mapping a Macro to a Key - -Use the `M()` function within your keymap to call a macro. For example, here is the keymap for a 2-key keyboard: - -```c -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = LAYOUT( - M(0), M(1) - ), -}; - -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - if (record->event.pressed) { - switch(id) { - case 0: - return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END); - case 1: - return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END); - } - } - return MACRO_NONE; -}; -``` - -When you press the key on the left it will type "Hi!" and when you press the key on the right it will type "Bye!". - -### Naming Your Macros - -If you have a bunch of macros you want to refer to from your keymap while keeping the keymap easily readable you can name them using `#define` at the top of your file. - -```c -#define M_HI M(0) -#define M_BYE M(1) - -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = LAYOUT( - M_HI, M_BYE - ), -}; -``` - - -## Advanced Example: - -### Single-Key Copy/Paste - -This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released. - -```c -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - switch(id) { - case 0: { - if (record->event.pressed) { - return MACRO( D(LCTL), T(C), U(LCTL), END ); - } else { - return MACRO( D(LCTL), T(V), U(LCTL), END ); - } - break; - } - } - return MACRO_NONE; -}; -``` diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index ffde133892..8e2a3a4cd1 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -29,6 +29,9 @@ In your keymap you can use the following keycodes to map key presses to mouse ac |`KC_MS_BTN3` |`KC_BTN3`|Press button 3 | |`KC_MS_BTN4` |`KC_BTN4`|Press button 4 | |`KC_MS_BTN5` |`KC_BTN5`|Press button 5 | +|`KC_MS_BTN6` |`KC_BTN6`|Press button 6 | +|`KC_MS_BTN7` |`KC_BTN7`|Press button 7 | +|`KC_MS_BTN8` |`KC_BTN8`|Press button 8 | |`KC_MS_WH_UP` |`KC_WH_U`|Move wheel up | |`KC_MS_WH_DOWN` |`KC_WH_D`|Move wheel down | |`KC_MS_WH_LEFT` |`KC_WH_L`|Move wheel left | @@ -42,6 +45,7 @@ In your keymap you can use the following keycodes to map key presses to mouse ac Mouse keys supports three different modes to move the cursor: * **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed. +* **Kinetic:** Holding movement keys accelerates the cursor with its speed following a quadratic curve until it reaches its maximum speed. * **Constant:** Holding movement keys moves the cursor at constant speeds. * **Combined:** Holding movement keys accelerates the cursor until it reaches its maximum speed, but holding acceleration and movement keys simultaneously moves the cursor at constant speeds. @@ -56,7 +60,8 @@ This is the default mode. You can adjust the cursor and scrolling acceleration u |Define |Default|Description | |----------------------------|-------|---------------------------------------------------------| |`MOUSEKEY_DELAY` |300 |Delay between pressing a movement key and cursor movement| -|`MOUSEKEY_INTERVAL` |50 |Time between cursor movements | +|`MOUSEKEY_INTERVAL` |50 |Time between cursor movements in milliseconds | +|`MOUSEKEY_MOVE_DELTA` |5 |Step size | |`MOUSEKEY_MAX_SPEED` |10 |Maximum cursor speed at which acceleration stops | |`MOUSEKEY_TIME_TO_MAX` |20 |Time until maximum cursor speed is reached | |`MOUSEKEY_WHEEL_DELAY` |300 |Delay between pressing a wheel key and wheel movement | @@ -73,6 +78,30 @@ Tips: Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys). +### Kinetic Mode + +This is an extension of the accelerated mode. The kinetic mode uses a quadratic curve on the cursor speed which allows precise movements at the beginning and allows to cover large distances by increasing cursor speed quickly thereafter. You can adjust the cursor and scrolling acceleration using the following settings in your keymap’s `config.h` file: + +|Define |Default |Description | +|--------------------------------------|---------|---------------------------------------------------------------| +|`MK_KINETIC_SPEED` |undefined|Enable kinetic mode | +|`MOUSEKEY_DELAY` |8 |Delay between pressing a movement key and cursor movement | +|`MOUSEKEY_INTERVAL` |8 |Time between cursor movements in milliseconds | +|`MOUSEKEY_MOVE_DELTA` |25 |Step size for accelerating from initial to base speed | +|`MOUSEKEY_INITIAL_SPEED` |100 |Initial speed of the cursor in pixel per second | +|`MOUSEKEY_BASE_SPEED` |1000 |Maximum cursor speed at which acceleration stops | +|`MOUSEKEY_DECELERATED_SPEED` |400 |Decelerated cursor speed | +|`MOUSEKEY_ACCELERATED_SPEED` |3000 |Accelerated cursor speed | +|`MOUSEKEY_WHEEL_INITIAL_MOVEMENTS` |16 |Initial number of movements of the mouse wheel | +|`MOUSEKEY_WHEEL_BASE_MOVEMENTS` |32 |Maximum number of movements at which acceleration stops | +|`MOUSEKEY_WHEEL_ACCELERATED_MOVEMENTS`|48 |Accelerated wheel movements | +|`MOUSEKEY_WHEEL_DECELERATED_MOVEMENTS`|8 |Decelerated wheel movements | + +Tips: + +* The smoothness of the cursor movement depends on the `MOUSEKEY_INTERVAL` setting. The shorter the interval is set the smoother the movement will be. Setting the value too low makes the cursor unresponsive. Lower settings are possible if the micro processor is fast enough. For example: At an interval of `8` milliseconds, `125` movements per second will be initiated. With a base speed of `1000` each movement will move the cursor by `8` pixels. +* Mouse wheel movements are implemented differently from cursor movements. While it's okay for the cursor to move multiple pixels at once for the mouse wheel this would lead to jerky movements. Instead, the mouse wheel operates at step size `1`. Setting mouse wheel speed is done by adjusting the number of wheel movements per second. + ### Constant mode In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `KC_ACL0`, `KC_ACL1` and `KC_ACL2` change the cursor and scroll speed to their respective setting. diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index 37edac5e6b..905c2a8f95 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -19,7 +19,7 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper * `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 the last 5 bits are used. These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1. +* `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. Once you have made the necessary changes to the mouse report, you need to send it: diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index f5abd327c5..fd866bd571 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -129,6 +129,28 @@ Configure the hardware via your `config.h`: --- +### APA102 :id=apa102 + +There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`: + +```makefile +RGB_MATRIX_ENABLE = yes +RGB_MATRIX_DRIVER = APA102 +``` + +Configure the hardware via your `config.h`: + +```c +// The pin connected to the data pin of the LEDs +#define RGB_DI_PIN D7 +// The pin connected to the clock pin of the LEDs +#define RGB_CI_PIN D6 +// The number of LEDs connected +#define DRIVER_LED_TOTAL 70 +``` + +--- + From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: ```c diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 755fd769e6..b5a2b179d6 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -10,6 +10,7 @@ Currently QMK supports the following addressable LEDs (however, the white LED in * WS2811, WS2812, WS2812B, WS2812C, etc. * SK6812, SK6812MINI, SK6805 + * APA102 These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs. @@ -21,11 +22,19 @@ On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is n RGBLIGHT_ENABLE = yes ``` -At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these. +For APA102 LEDs, add the following to your `rules.mk`: + +```make +RGBLIGHT_ENABLE = yes +RGBLIGHT_DRIVER = APA102 +``` + +At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. For APA102 LEDs, you must also define the clock pin. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these. |Define |Description | |---------------|---------------------------------------------------------------------------------------------------------| |`RGB_DI_PIN` |The pin connected to the data pin of the LEDs | +|`RGB_CI_PIN` |The pin connected to the clock pin of the LEDs (APA102 only) | |`RGBLED_NUM` |The number of LEDs connected | |`RGBLED_SPLIT` |(Optional) For split keyboards, the number of LEDs connected on each half directly wired to `RGB_DI_PIN` | @@ -139,7 +148,7 @@ The following options are used to tweak the various animations: |`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` |`75` |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps) | +|`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 diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index b234114200..c285e353d4 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -181,6 +181,16 @@ If you're having issues with serial communication, you can change this value, as * **`4`**: about 26kbps * **`5`**: about 20kbps +```c +#define SPLIT_MODS_ENABLE +``` + +This enables transmitting modifier state (normal, weak and oneshot) to the non +primary side of the split keyboard. This adds a few bytes of data to the split +communication protocol and may impact the matrix scan speed when enabled. +The purpose of this feature is to support cosmetic use of modifer state (e.g. +displaying status on an OLED screen). + ### Hardware Configuration Options There are some settings that you may need to configure, based on how the hardware is set up. diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md index 48b07aaec4..fdd11f14fa 100644 --- a/docs/ja/compatible_microcontrollers.md +++ b/docs/ja/compatible_microcontrollers.md @@ -14,6 +14,7 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま * [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2) * [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4) * [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286) +* [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162) 組み込みの USB インターフェースを持たない、いくつかの MCU は代わりに [V-USB](https://www.obdev.at/products/vusb/index.html) を使います: @@ -30,6 +31,10 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま * [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html) * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html) * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) +* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) +* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) +* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) +* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) ### NXP (Kinetis) diff --git a/docs/ja/feature_macros.md b/docs/ja/feature_macros.md index 14a58ad244..c42a61b5fb 100644 --- a/docs/ja/feature_macros.md +++ b/docs/ja/feature_macros.md @@ -9,7 +9,7 @@ !> **セキュリティの注意**: マクロを使って、パスワード、クレジットカード番号、その他の機密情報のいずれも送信することが可能ですが、それは非常に悪い考えです。あなたのキーボードを手に入れた人は誰でもテキストエディタを開いてその情報にアクセスすることができます。 -## 新しい方法: `SEND_STRING()` と `process_record_user` +## `SEND_STRING()` と `process_record_user` 単語またはフレーズを入力するキーが欲しい時があります。最も一般的な状況のために `SEND_STRING()` を提供しています。これは文字列(つまり、文字のシーケンス)を入力します。簡単にキーコードに変換することができる全ての ASCII 文字がサポートされています (例えば、`qmk 123\n\t`)。 @@ -267,15 +267,15 @@ SEND_STRING(".."SS_TAP(X_END)); このマクロは `KC_LALT` を登録し、`KC_TAB` をタップして、1000ms 待ちます。キーが再度タップされると、別の `KC_TAB` が送信されます; タップが無い場合、`KC_LALT` が登録解除され、ウィンドウを切り替えることができます。 ```c -bool is_alt_tab_active = false; # keymap.c の先頭付近にこれを追加します -uint16_t alt_tab_timer = 0; # すぐにそれらを使います +bool is_alt_tab_active = false; // keymap.c の先頭付近にこれを追加します +uint16_t alt_tab_timer = 0; // すぐにそれらを使います -enum custom_keycodes { # 素晴らしいキーコードを用意してください +enum custom_keycodes { // 素晴らしいキーコードを用意してください ALT_TAB = SAFE_RANGE, }; bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { # これはキーコードを利用したつまらない作業のほとんどを行います。 + switch (keycode) { // これはキーコードを利用したつまらない作業のほとんどを行います。 case ALT_TAB: if (record->event.pressed) { if (!is_alt_tab_active) { @@ -292,7 +292,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { return true; } -void matrix_scan_user(void) { # とても重要なタイマー +void matrix_scan_user(void) { // とても重要なタイマー if (is_alt_tab_active) { if (timer_elapsed(alt_tab_timer) > 1000) { unregister_code(KC_LALT); @@ -301,104 +301,3 @@ void matrix_scan_user(void) { # とても重要なタイマー } } ``` - ---- - -## **(非推奨)** 古い方法: `MACRO()` と `action_get_macro` - -!> これは TMK から継承されており、更新されていません - 代わりに `SEND_STRING` と `process_record_user` を使うことをお勧めします。 - -デフォルトでは、QMK はマクロが無いことを前提としています。マクロを定義するには、`action_get_macro()` 関数を作成します。例えば: - -```c -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - if (record->event.pressed) { - switch(id) { - case 0: - return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END); - case 1: - return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END); - } - } - return MACRO_NONE; -}; -``` - -これは割り当てられているキーが押された時に実行される2つのマクロを定義します。キーが放された時にそれらを実行したい場合は、if 文を変更することができます。 - - if (!record->event.pressed) { - -### マクロコマンド - -マクロは以下のコマンドを含めることができます: - |