### 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+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: + +```c +//halconf.h: +#define HAL_USE_DAC TRUE +#define HAL_USE_GPT TRUE +#include_next
+ +## Bitbang + +This is the Default driver, absence of configuration assumes this driver. It works by [bit banging](https://en.wikipedia.org/wiki/Bit_banging) a GPIO pin using the CPU. It is therefore not as efficient as a dedicated hardware peripheral, which the Half-duplex and Full-duplex drivers use. + +::: warning +On ARM platforms the bitbang driver causes connection issues when using it together with the bitbang WS2812 driver. Choosing alternate drivers for both serial and WS2812 (instead of bitbang) is strongly recommended. +::: + +### Pin configuration + +``` + LEFT RIGHT ++-------+ SERIAL +-------+ +| SSP |-----------------| SSP | +| | VDD | | +| |-----------------| | +| | GND | | +| |-----------------| | ++-------+ +-------+ +``` + +One GPIO pin is needed for the bitbang driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SOFT_SERIAL_PIN` (SSP) in the configuration. A TRS or USB cable provides enough conductors for this driver to function. + +### Setup + +To use the bitbang driver follow these steps to activate it. + +1. Change the `SERIAL_DRIVER` to `bitbang` in your keyboards `rules.mk` file: + +```make +SERIAL_DRIVER = bitbang +``` + +2. Configure the GPIO pin of your keyboard via the `config.h` file: + +```c +#define SOFT_SERIAL_PIN D0 // or D1, D2, D3, E6 +``` + +3. On ARM platforms you must turn on ChibiOS `PAL_USE_CALLBACKS` feature: + +* In `halconf.h` add the line `#define PAL_USE_CALLBACKS TRUE`. + +
+ +## USART Half-duplex + +Targeting ARM boards based on ChibiOS, where communication is offloaded to a USART hardware device that supports Half-duplex operation. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose Half-duplex over Bitbang if MCU is capable of utilising Half-duplex, and Full-duplex can't be used instead (e.g. lack of available GPIO pins, or imcompatible PCB design). + +### Pin configuration + +``` + LEFT RIGHT ++-------+ | | +-------+ +| | R R | | +| | | SERIAL | | | +| TX |-----------------| TX | +| | VDD | | +| |-----------------| | +| | GND | | +| |-----------------| | ++-------+ +-------+ +``` + +Only one GPIO pin is needed for the Half-duplex driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SERIAL_USART_TX_PIN` in the configuration. Ensure that the pin chosen for split communication can operate as the TX pin of the contoller's USART peripheral. A TRS or USB cable provides enough conductors for this driver to function. As the split connection is configured to operate in open-drain mode, an **external pull-up resistor is needed to keep the line high**. Resistor values of 1.5kΩ to 8.2kΩ are known to work. + +::: warning +***Note:*** A pull-up resistor isn't required for RP2040 controllers configured with PIO subsystem. +::: + +### Setup + +To use the Half-duplex driver follow these steps to activate it. If you target the Raspberry Pi RP2040 PIO implementation, start at step 2. + +1. Change the `SERIAL_DRIVER` to `usart` in your keyboards `rules.mk` file: + +```make +SERIAL_DRIVER = usart +``` + +Skip to step 3. + +2. (RP2040 + PIO only!) Change the `SERIAL_DRIVER` to `vendor` in your keyboards `rules.mk` file: + +```make +SERIAL_DRIVER = vendor +``` + +3. Configure the hardware of your keyboard via the `config.h` file: + +```c +#define SERIAL_USART_TX_PIN B6 // The GPIO pin that is used split communication. +``` + +For STM32 MCUs several GPIO configuration options can be changed as well. See the section ["Alternate Functions for selected STM32 MCUs"](#alternate-functions-for-selected-stm32-mcus). + +```c +#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. +#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 +``` + +4. Decide either for `SERIAL`, `SIO`, or `PIO` subsystem. See section ["Choosing a driver subsystem"](#choosing-a-driver-subsystem). + +
+ +## USART Full-duplex + +Targeting ARM boards based on ChibiOS where communication is offloaded to an USART hardware device. The advantages over bitbanging are fast, accurate timings and reduced CPU usage; therefore it is advised to choose this driver over all others where possible. Due to its internal design Full-duplex is slightly more efficient than the Half-duplex driver, but Full-duplex should be primarily chosen if Half-duplex operation is not supported by the controller's USART peripheral. + +### Pin configuration + +``` + LEFT RIGHT ++-------+ +-------+ +| | SERIAL | | +| TX |-----------------| RX | +| | SERIAL | | +| RX |-----------------| TX | +| | VDD | | +| |-----------------| | +| | GND | | +| |-----------------| | ++-------+ +-------+ +``` + +Two GPIO pins are needed for the Full-duplex driver, as two distinct wires are used for receiving and transmitting data. The pin transmitting data is the `TX` pin and refereed to as the `SERIAL_USART_TX_PIN`, the pin receiving data is the `RX` pin and refereed to as the `SERIAL_USART_RX_PIN` in this configuration. Please note that `TX` pin of the master half has to be connected with the `RX` pin of the slave half and the `RX` pin of the master half has to be connected with the `TX` pin of the slave half! Usually this pin swap has to be done outside of the MCU e.g. with cables or on the PCB. Some MCUs like the STM32F303 used on the Proton-C allow this pin swap directly inside the MCU. A TRRS or USB cable provides enough conductors for this driver to function. + +To use this driver the USART peripherals `TX` and `RX` pins must be configured with the correct Alternate-functions. If you are using a Proton-C development board everything is already setup, same is true for STM32F103 MCUs. For MCUs which are using a modern flexible GPIO configuration you have to specify these by setting `SERIAL_USART_TX_PAL_MODE` and `SERIAL_USART_RX_PAL_MODE`. Refer to the corresponding datasheets of your MCU or find those settings in the section ["Alternate Functions for selected STM32 MCUs"](#alternate-functions-for-selected-stm32-mcus). + +### Setup + +To use the Full-duplex driver follow these steps to activate it. If you target the Raspberry Pi RP2040 PIO implementation, start at step 2 + +1. Change the `SERIAL_DRIVER` to `usart` in your keyboards `rules.mk` file: + +```make +SERIAL_DRIVER = usart +``` + +Skip to step 3 + +2. (RP2040 + PIO only!) Change the `SERIAL_DRIVER` to `vendor` in your keyboards `rules.mk` file: + +```make +SERIAL_DRIVER = vendor +``` + +3. Configure the hardware of your keyboard via the `config.h` file: + +```c +#define SERIAL_USART_FULL_DUPLEX // Enable full duplex operation mode. +#define SERIAL_USART_TX_PIN B6 // USART TX pin +#define SERIAL_USART_RX_PIN B7 // USART RX pin +``` + +For STM32 MCUs several GPIO configuration options, including the ability for `TX` to `RX` pin swapping, can be changed as well. See the section ["Alternate Functions for selected STM32 MCUs"](#alternate-functions-for-selected-stm32-mcus). + +```c +#define SERIAL_USART_PIN_SWAP // Swap TX and RX pins if keyboard is master halve. (Only available on some MCUs) +#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. +#define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 +``` + +4. Decide either for `SERIAL`, `SIO`, or `PIO` subsystem. See section ["Choosing a driver subsystem"](#choosing-a-driver-subsystem). + +
+ +## Choosing a driver subsystem + +### The `SERIAL` driver + +The `SERIAL` Subsystem is supported for the majority of ChibiOS MCUs and should be used whenever supported. Follow these steps in order to activate it: + +1. In your keyboards `halconf.h` add: + +```c +#define HAL_USE_SERIAL TRUE +``` + +2. In your keyboards `mcuconf.h`: activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS. + +Just below `#include_next
+ +## Advanced Configuration + +There are several advanced configuration options that can be defined in your keyboards `config.h` file: + +### Baudrate + +If you're having issues or need a higher baudrate with serial communication, you can change the baudrate which in turn controls the communication speed for serial. You want to lower the baudrate if you experience failed transactions. + +```c +#define SELECT_SOFT_SERIAL_SPEED {#} +``` + +| Speed | Bitbang | Half-duplex and Full-duplex | +| ----- | -------------------------- | --------------------------- | +| `0` | 189000 baud (experimental) | 460800 baud | +| `1` | 137000 baud (default) | 230400 baud (default) | +| `2` | 75000 baud | 115200 baud | +| `3` | 39000 baud | 57600 baud | +| `4` | 26000 baud | 38400 baud | +| `5` | 20000 baud | 19200 baud | + +Alternatively you can specify the baudrate directly by defining `SERIAL_USART_SPEED`. + +### Timeout + +This is the default time window in milliseconds in which a successful communication has to complete. Usually you don't want to change this value. But you can do so anyways by defining an alternate one in your keyboards `config.h` file: + +```c +#define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20 +``` + +
+ +## Troubleshooting + +If you're having issues withe serial communication, you can enable debug messages that will give you insights which part of the communication failed. The enable these messages add to your keyboards `config.h` file: + +```c +#define SERIAL_DEBUG +``` + +::: tip +The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](../faq_debug). +::: + +## Alternate Functions for selected STM32 MCUs + +Pins for USART Peripherals with + +### STM32F303 / Proton-C [Datasheet](https://www.st.com/resource/en/datasheet/stm32f303cc.pdf) + +Pin Swap available: :heavy_check_mark: + +| Pin | Function | Mode | +| ---------- | -------- | ---- | +| **USART1** | | | +| PA9 | TX | AF7 | +| PA10 | RX | AF7 | +| PB6 | TX | AF7 | +| PB7 | RX | AF7 | +| PC4 | TX | AF7 | +| PC5 | RX | AF7 | +| PE0 | TX | AF7 | +| PE1 | RX | AF7 | +| **USART2** | | | +| PA2 | TX | AF7 | +| PA3 | RX | AF7 | +| PA14 | TX | AF7 | +| PA15 | RX | AF7 | +| PB3 | TX | AF7 | +| PB4 | RX | AF7 | +| PD5 | TX | AF7 | +| PD6 | RX | AF7 | +| **USART3** | | | +| PB10 | TX | AF7 | +| PB11 | RX | AF7 | +| PC10 | TX | AF7 | +| PC11 | RX | AF7 | +| PD8 | TX | AF7 | +| PD9 | RX | AF7 | + +### STM32F072 [Datasheet](https://www.st.com/resource/en/datasheet/stm32f072c8.pdf) + +Pin Swap available: :heavy_check_mark: + +| Pin | Function | Mode | +| ------ | -------- | ---- | +| USART1 | | | +| PA9 | TX | AF1 | +| PA10 | RX | AF1 | +| PB6 | TX | AF0 | +| PB7 | RX | AF0 | +| USART2 | | | +| PA2 | TX | AF1 | +| PA3 | RX | AF1 | +| PA14 | TX | AF1 | +| PA15 | RX | AF1 | +| USART3 | | | +| PB10 | TX | AF4 | +| PB11 | RX | AF4 | +| PC4 | TX | AF1 | +| PC5 | RX | AF1 | +| PC10 | TX | AF1 | +| PC11 | RX | AF1 | +| PD8 | TX | AF0 | +| PD9 | RX | AF0 | +| USART4 | | | +| PA0 | TX | AF4 | +| PA1 | RX | AF4 | + +### STM32F103 Medium Density (C8-CB) [Datasheet](https://www.st.com/resource/en/datasheet/stm32f103c8.pdf) + +Pin Swap available: N/A + +TX Pin is always Alternate Function Push-Pull, RX Pin is always regular input pin for any USART peripheral. **For STM32F103 no additional Alternate Function configuration is necessary. QMK is already configured.** + +Pin remapping: + +The pins of USART Peripherals use default Pins that can be remapped to use other pins using the AFIO registers. Default pins are marked **bold**. Add the appropriate defines to your config.h file. + +| Pin | Function | Mode | USART_REMAP | +| ---------- | -------- | ---- | ------------------- | +| **USART1** | | | | +| **PA9** | TX | AFPP | | +| **PA10** | RX | IN | | +| PB6 | TX | AFPP | USART1_REMAP | +| PB7 | RX | IN | USART1_REMAP | +| **USART2** | | | | +| **PA2** | TX | AFPP | | +| **PA3** | RX | IN | | +| PD5 | TX | AFPP | USART2_REMAP | +| PD6 | RX | IN | USART2_REMAP | +| **USART3** | | | | +| **PB10** | TX | AFPP | | +| **PB11** | RX | IN | | +| PC10 | TX | AFPP | USART3_PARTIALREMAP | +| PC11 | RX | IN | USART3_PARTIALREMAP | +| PD8 | TX | AFPP | USART3_FULLREMAP | +| PD9 | RX | IN | USART3_FULLREMAP | diff --git a/docs/drivers/snled27351.md b/docs/drivers/snled27351.md new file mode 100644 index 00000000000..1d91182f7c3 --- /dev/null +++ b/docs/drivers/snled27351.md @@ -0,0 +1,245 @@ +# SNLED27351 Driver {#snled27351-driver} + +I²C 16x12 LED matrix driver by Sonix. Supports a maximum of four drivers, each controlling up to 192 single-color LEDs, or 64 RGB LEDs. + +A slightly modified version of this IC is also known as "CKLED2001". + +[SNLED27351 Datasheet](https://www.sonix.com.tw/files/1/D235860C0C037C28E050007F01001CBE) + +## Usage {#usage} + +The SNLED27351 driver code is automatically included if you are using the [LED Matrix](../features/led_matrix) or [RGB Matrix](../features/rgb_matrix) feature with the `snled27351` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add this to your `rules.mk`: + +```make +COMMON_VPATH += $(DRIVER_PATH)/led +SRC += snled27351-mono.c # For single-color +SRC += snled27351.c # For RGB +I2C_DRIVER_REQUIRED = yes +``` + +## Basic Configuration {#basic-configuration} + +Add the following to your `config.h`: + +|Define |Default |Description | +|----------------------------|-------------|----------------------------------------------------| +|`SNLED27351_SDB_PIN` |*Not defined*|The GPIO pin connected to the drivers' shutdown pins| +|`SNLED27351_I2C_TIMEOUT` |`100` |The I²C timeout in milliseconds | +|`SNLED27351_I2C_PERSISTENCE`|`0` |The number of times to retry I²C transmissions | +|`SNLED27351_I2C_ADDRESS_1` |*Not defined*|The I²C address of driver 0 | +|`SNLED27351_I2C_ADDRESS_2` |*Not defined*|The I²C address of driver 1 | +|`SNLED27351_I2C_ADDRESS_3` |*Not defined*|The I²C address of driver 2 | +|`SNLED27351_I2C_ADDRESS_4` |*Not defined*|The I²C address of driver 3 | + +### I²C Addressing {#i2c-addressing} + +The SNLED27351 has four possible 7-bit I²C addresses, depending on how the `ADDR` pin is connected. + +To configure this, set the `SNLED27351_I2C_ADDRESS_n` defines to one of the following in your `config.h`, where *n* denotes the driver index: + +|Define |Value | +|------------------------------|------| +|`SNLED27351_I2C_ADDRESS_GND` |`0x74`| +|`SNLED27351_I2C_ADDRESS_SCL` |`0x75`| +|`SNLED27351_I2C_ADDRESS_SDA` |`0x76`| +|`SNLED27351_I2C_ADDRESS_VDDIO`|`0x77`| + +## ARM/ChibiOS Configuration {#arm-configuration} + +Depending on the ChibiOS board configuration, you may need to [enable and configure I²C](i2c#arm-configuration) at the keyboard level. + +## LED Mapping {#led-mapping} + +In order to use this driver, each output must be mapped to an LED index, by adding the following to your `
` 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 287ca7711d1..133dbcf6126 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 171243301d3..7f5a10d1c13 100644
--- a/docs/feature_advanced_keycodes.md
+++ b/docs/feature_advanced_keycodes.md
@@ -1,4 +1,4 @@
-# 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.
@@ -26,7 +26,7 @@ These allow you to combine a modifier with a keycode. When pressed, the keydown
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.
-# Checking Modifier State :id=checking-modifier-state
+# 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 +35,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 a50ee7ccc23..00000000000 --- 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 f55b3082861..00000000000 --- 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 eaa2b601aef..00000000000
--- 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 7d3f3ba32a1..00000000000
--- 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 3af55197c54..00000000000
--- 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 223a5b3ccf6..00000000000
--- 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 99c252d03ec..00000000000
--- 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 {
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. | + +::: warning +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); +``` + +::: warning +Scrolling is unsupported on the SH1106 and SH1107. +::: + +::: warning +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/features/os_detection.md b/docs/features/os_detection.md new file mode 100644 index 00000000000..d0556d2549d --- /dev/null +++ b/docs/features/os_detection.md @@ -0,0 +1,132 @@ +# 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; +``` + +::: tip +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 {#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/features/pointing_device.md b/docs/features/pointing_device.md new file mode 100644 index 00000000000..a6bf521a184 --- /dev/null +++ b/docs/features/pointing_device.md @@ -0,0 +1,928 @@ +# Pointing Device {#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. | + +::: tip +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) {} +``` + +::: warning +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_ | + +::: warning +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. + +::: warning +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](split_keyboard#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_ | + +::: warning +If there is a `_RIGHT` configuration option or callback, the [common configuration](pointing_device#common-configuration) option will work for the left. For correct left/right detection you should setup a [handedness option](split_keyboard#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](pointing_device#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 +``` + +::: tip +The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](../faq_debug). +::: + + +--- +# Automatic Mouse Layer {#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.