diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/feature_mouse_keys.md | 28 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 22 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 11 | ||||
| -rw-r--r-- | docs/feature_split_keyboard.md | 10 | ||||
| -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 | 157 | ||||
| -rw-r--r-- | docs/serial_driver.md | 1 |
8 files changed, 208 insertions, 23 deletions
diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index ffde133892..a0d02416f2 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -42,6 +42,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 +57,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 +75,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_rgb_matrix.md b/docs/feature_rgb_matrix.md index a9e711c9f2..bb0acba3bb 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 762056b343..f1178c679d 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` | 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/proton_c_conversion.md b/docs/ja/proton_c_conversion.md index 6e4f7dcb66..e7c07413ce 100644 --- a/docs/ja/proton_c_conversion.md +++ b/docs/ja/proton_c_conversion.md @@ -51,6 +51,7 @@ Proton C には1つのオンボード LED(C13)しかなく、デフォルトで ``` MCU = STM32F303 +BOARD = QMK_PROTON_C ``` 次の変数が存在する場合は削除します。 diff --git a/docs/proton_c_conversion.md b/docs/proton_c_conversion.md index 1b5e496e74..47511e1b1e 100644 --- a/docs/proton_c_conversion.md +++ b/docs/proton_c_conversion.md @@ -44,6 +44,7 @@ To use the Proton C natively, without having to specify `CTPC=yes`, you need to ``` MCU = STM32F303 +BOARD = QMK_PROTON_C ``` Remove these variables if they exist: diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 3ca62c719e..47506bc92d 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -19,8 +19,20 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai * Width of the board in Key Units * `height` * Height of the board in Key Units +* `debounce` + * How many milliseconds (ms) to wait for debounce to happen. (Default: 5) +* `diode_direction` + * The direction diodes face. See [`DIRECT_PINS` in the hardware configuration](https://docs.qmk.fm/#/config_options?id=hardware-options) for more details. +* `layout_aliases` + * A dictionary containing layout aliases. The key is the alias and the value is a layout in `layouts` it maps to. * `layouts` - * Physical Layout representations. See the next section for more detail. + * Physical Layout representations. See the [Layout Format](#layout_format) section for more detail. +* `matrix_pins` + * Configure the pins corresponding to columns and rows, or direct pins. See [Matrix Pins](#matrix_pins) for more detail. +* `rgblight` + * Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb_lighting) section for more detail. +* `usb` + * Configure USB VID, PID, and other parameters. See [USB](#USB) for more detail. ### Layout Format @@ -49,25 +61,128 @@ All key positions and rotations are specified in relation to the top-left corner * The width of the key, in Key Units. Ignored if `ks` is provided. Default: `1` * `h` * The height of the key, in Key Units. Ignored if `ks` is provided. Default: `1` -* `r` - * How many degrees clockwise to rotate the key. -* `rx` - * The absolute position of the point to rotate the key around in the horizontal axis. Default: `x` -* `ry` - * The absolute position of the point to rotate the key around in the vertical axis. Default: `y` -* `ks` - * Key Shape: define a polygon by providing a list of points, in Key Units. - * **Important**: These are relative to the top-left of the key, not absolute. - * Example ISO Enter: `[ [0,0], [1.5,0], [1.5,2], [0.25,2], [0.25,1], [0,1], [0,0] ]` * `label` * What to name this position in the matrix. - * This should usually be the same name as what is silkscreened on the PCB at this location. - -## How is the Metadata Exposed? - -This metadata is primarily used in two ways: - -* To allow web-based configurators to dynamically generate UI -* To support the new `make keyboard:keymap:qmk` target, which bundles this metadata up with the firmware to allow QMK Toolbox to be smarter. - -Configurator authors can see the [QMK Compiler](https://docs.api.qmk.fm/using-the-api) docs for more information on using the JSON API. + * This should usually correspond to the keycode for the first layer of the default keymap. +* `matrix` + * A 2 item list describing the row and column location for this key. + +### Matrix Pins + +Currently QMK supports connecting switches either directly to GPIO pins or via a switch matrix. At this time you can not combine these, they are mutually exclusive. + +#### Switch Matrix + +Most keyboards use a switch matrix to connect keyswitches to the MCU. You can define your pin columns and rows to configure your switch matrix. When defining switch matrices you should also define your `diode_direction`. + +Example: + +```json +{ + "diode_direction": "COL2ROW", + "matrix_pins": { + "cols": ["F4", "E6", "B1", "D2"], + "rows": ["B0", "D3", "D5", "D4", "D6"] + } +} +``` + +#### Direct Pins + +Direct pins are when you connect one side of the switch to GND and the other side to a GPIO pin on your MCU. No diode is required, but there is a 1:1 mapping between switches and pins. + +When specifying direct pins you need to arrange them in nested arrays. The outer array consists of rows, while the inner array is a text string corresponding to a pin. You can use `null` to indicate an empty spot in the matrix. + +Example: + +```json +{ + "matrix_pins": { + "direct": [ + ["A10", "A9"], + ["A0", "B8"], + [null, "B11"], + ["B9", "A8"], + ["A7", "B1"], + [null, "B2"] + ] +} +``` + +### RGB Lighting + +This section controls the legacy WS2812 support in QMK. This should not be confused with the RGB Matrix feature, which can be used to control both WS2812 and ISSI RGB LEDs. + +The following items can be set. Not every value is required. + +* `led_count` + * The number of LEDs in your strip +* `pin` + * The GPIO pin that your LED strip is connected to +* `animations` + * A dictionary that lists enabled and disabled animations. See [RGB Light Animations](#rgb_light_animations) below. +* `sleep` + * Set to `true` to enable lighting during host sleep +* `split` + * Set to `true` to enable synchronization functionality between split halves +* `split_count` + * For split keyboards, the number of LEDs on each side +* `max_brightness` + * (0-255) What the maxmimum brightness (value) level is +* `hue_steps` + * How many steps of adjustment to have for hue +* `saturation_steps` + * How many steps of adjustment to have for saturation +* `brightness_steps` + * How many steps of adjustment to have for brightness (value) + +Example: + +```json +{ + "rgblight": { + "led_count": 4, + "pin": "F6", + "hue_steps": 10, + "saturation_steps": 17, + "brightness_steps": 17, + "animations": { + "all": true + } + } +} +``` + +#### RGB Light Animations + +The following animations can be enabled: + +| Key | Description | +|-----|-------------| +| `all` | Enable all additional animation modes. | +| `alternating` | Enable alternating animation mode. | +| `breathing` | Enable breathing animation mode. | +| `christmas` | Enable christmas animation mode. | +| `knight` | Enable knight animation mode. | +| `rainbow_mood` | Enable rainbow mood animation mode. | +| `rainbow_swirl` | Enable rainbow swirl animation mode. | +| `rgb_test` | Enable RGB test animation mode. | +| `snake` | Enable snake animation mode. | +| `static_gradient` | Enable static gradient mode. | +| `twinkle` | Enable twinkle animation mode. | + +### USB + +Every USB keyboard needs to have its USB parmaters defined. At a minimum you need to set vid, pid, and device version. + +Example: + +```json +{ + "usb": { + "vid": "0xC1ED", + "pid": "0x23B0", + "device_ver": "0x0001" + } +} +``` diff --git a/docs/serial_driver.md b/docs/serial_driver.md index bc376b6ddd..c98f4c1176 100644 --- a/docs/serial_driver.md +++ b/docs/serial_driver.md @@ -60,6 +60,7 @@ Configure the hardware via your config.h: // 5: about 19200 baud #define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1 #define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 +#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100 ``` You must also enable the ChibiOS `SERIAL` feature: |