diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/compatible_microcontrollers.md | 4 | ||||
-rw-r--r-- | docs/config_options.md | 2 | ||||
-rw-r--r-- | docs/drivers/gpio.md | 2 | ||||
-rw-r--r-- | docs/drivers/ws2812.md | 47 | ||||
-rw-r--r-- | docs/feature_layers.md | 1 | ||||
-rw-r--r-- | docs/features/bluetooth.md | 10 | ||||
-rw-r--r-- | docs/features/combo.md | 44 | ||||
-rw-r--r-- | docs/features/os_detection.md | 30 | ||||
-rw-r--r-- | docs/features/pointing_device.md | 1 | ||||
-rw-r--r-- | docs/keycodes.md | 10 | ||||
-rw-r--r-- | docs/other_vscode.md | 5 | ||||
-rw-r--r-- | docs/quantum_painter.md | 36 | ||||
-rw-r--r-- | docs/ref_functions.md | 4 |
13 files changed, 161 insertions, 35 deletions
diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 785aee30d5..e2d27e06f2 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -75,10 +75,6 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s For a detailed overview about the RP2040 support by QMK see the [dedicated RP2040 page](platformdev_rp2040). -## Atmel ATSAM - -There is limited support for one of Atmel's ATSAM microcontrollers, that being the [ATSAMD51J18A](https://www.microchip.com/wwwproducts/en/ATSAMD51J18A) used by the [Massdrop keyboards](https://github.com/qmk/qmk_firmware/tree/master/keyboards/massdrop). However, it is not recommended to design a board with this microcontroller as the support is quite specialized to Massdrop hardware. - ## RISC-V ### GigaDevice diff --git a/docs/config_options.md b/docs/config_options.md index fec6b22b13..90a708dd99 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -426,8 +426,6 @@ Use these to enable or disable building certain features. The more you have enab * Key combo feature * `NKRO_ENABLE` * USB N-Key Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work -* `RING_BUFFERED_6KRO_REPORT_ENABLE` - * USB 6-Key Rollover - Instead of stopping any new input once 6 keys are pressed, the oldest key is released and the new key is pressed. * `AUDIO_ENABLE` * Enable the audio subsystem. * `KEY_OVERRIDE_ENABLE` diff --git a/docs/drivers/gpio.md b/docs/drivers/gpio.md index 9ce4f2aa20..b21a17bc39 100644 --- a/docs/drivers/gpio.md +++ b/docs/drivers/gpio.md @@ -13,7 +13,7 @@ The following macros provide basic control of GPIOs and are found in `platforms/ |`gpio_set_pin_input_low(pin)` |Set pin as input with builtin pull-down resistor (unavailable on AVR)| |`gpio_set_pin_output(pin)` |Set pin as output (alias of `gpio_set_pin_output_push_pull`) | |`gpio_set_pin_output_push_pull(pin)` |Set pin as output, push/pull mode | -|`gpio_set_pin_output_open_drain(pin)`|Set pin as output, open-drain mode (unavailable on AVR and ATSAM) | +|`gpio_set_pin_output_open_drain(pin)`|Set pin as output, open-drain mode (unavailable on AVR) | |`gpio_write_pin_high(pin)` |Set pin level as high, assuming it is an output | |`gpio_write_pin_low(pin)` |Set pin level as low, assuming it is an output | |`gpio_write_pin(pin, level)` |Set pin level, assuming it is an output | diff --git a/docs/drivers/ws2812.md b/docs/drivers/ws2812.md index 61addf1917..036ea40d1d 100644 --- a/docs/drivers/ws2812.md +++ b/docs/drivers/ws2812.md @@ -236,18 +236,49 @@ The following `#define`s apply only to the `pwm` driver: |`WS2812_PWM_COMPLEMENTARY_OUTPUT`|*Not defined* |Whether the PWM output is complementary (`TIMx_CHyN`) | ::: tip -Using a complementary timer output (`TIMx_CHyN`) is possible only for advanced-control timers (1, 8 and 20 on STM32), and the `STM32_PWM_USE_ADVANCED` option in `mcuconf.h` must be set to `TRUE`. Complementary outputs of general-purpose timers are not supported due to ChibiOS limitations. +Using a complementary timer output (`TIMx_CHyN`) is possible only for advanced-control timers (1, 8 and 20 on STM32). Complementary outputs of general-purpose timers are not supported due to ChibiOS limitations. ::: ## API {#api} -### `void ws2812_setleds(rgb_led_t *ledarray, uint16_t number_of_leds)` {#api-ws2812-setleds} +### `void ws2812_init(void)` {#api-ws2812-init} -Send RGB data to the WS2812 LED chain. +Initialize the LED driver. This function should be called first. -#### Arguments {#api-ws2812-setleds-arguments} +--- - - `rgb_led_t *ledarray` - A pointer to the LED array. - - `uint16_t number_of_leds` - The length of the LED array. +### `void ws2812_set_color(int index, uint8_t red, uint8_t green, uint8_t blue)` {#api-ws2812-set-color} + +Set the color of a single LED. This function does not immediately update the LEDs; call `ws2812_flush()` after you are finished. + +#### Arguments {#api-ws2812-set-color-arguments} + + - `int index` + The LED index in the WS2812 chain. + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void ws812_set_color_all(uint8_t red, uint8_t green, uint8_t blue)` {#api-ws2812-set-color-all} + +Set the color of all LEDs. + +#### Arguments {#api-ws2812-set-color-all-arguments} + + - `uint8_t red` + The red value to set. + - `uint8_t green` + The green value to set. + - `uint8_t blue` + The blue value to set. + +--- + +### `void ws2812_flush(void)` {#api-ws2812-flush} + +Flush the PWM values to the LED chain. diff --git a/docs/feature_layers.md b/docs/feature_layers.md index fe9932fadb..30ab713222 100644 --- a/docs/feature_layers.md +++ b/docs/feature_layers.md @@ -74,6 +74,7 @@ There are a number of functions (and variables) related to how you can use or ma | `default_layer_and(layer_mask)` | Turns on layers based on matching enabled bits between specifed layer and existing default layer state. | | `default_layer_xor(layer_mask)` | Turns on layers based on non-matching bits between specifed layer and existing default layer state. | | `default_layer_debug(layer_mask)` | Prints out the current bit mask and highest active default layer to debugger console. | +| [`set_single_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer, but does _not_ write it to persistent memory (EEPROM). | | [`set_single_persistent_default_layer(layer)`](ref_functions.md#setting-the-persistent-default-layer) | Sets the default layer and writes it to persistent memory (EEPROM). | | [`update_tri_layer(x, y, z)`](ref_functions.md#update_tri_layerx-y-z) | Checks if layers `x` and `y` are both on, and sets `z` based on that (on if both on, otherwise off). | | [`update_tri_layer_state(state, x, y, z)`](ref_functions.md#update_tri_layer_statestate-x-y-z) | Does the same as `update_tri_layer(x, y, z)`, but from `layer_state_set_*` functions. | diff --git a/docs/features/bluetooth.md b/docs/features/bluetooth.md index 1dbf15f4e1..d3634498be 100644 --- a/docs/features/bluetooth.md +++ b/docs/features/bluetooth.md @@ -39,8 +39,8 @@ BLUETOOTH_DRIVER = bluefruit_le # or rn42 This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both. -|Key |Aliases |Description | -|---------------------|---------|----------------------------------------------| -|`QK_OUTPUT_AUTO` |`OU_AUTO`|Automatically switch between USB and Bluetooth| -|`QK_OUTPUT_USB` |`OU_USB` |USB only | -|`QK_OUTPUT_BLUETOOTH`|`OU_BT` |Bluetooth only | +| Key | Aliases | Description | +|-----------------------|----------------------|------------------------------------------------| +| `QK_OUTPUT_NEXT` | `OU_NEXT`, `OU_AUTO` | Automatically switch between USB and Bluetooth | +| `QK_OUTPUT_USB` | `OU_USB` | USB only | +| `QK_OUTPUT_BLUETOOTH` | `OU_BT` | Bluetooth only | diff --git a/docs/features/combo.md b/docs/features/combo.md index bdb8c4b15f..10e33b72a6 100644 --- a/docs/features/combo.md +++ b/docs/features/combo.md @@ -307,6 +307,50 @@ bool process_combo_key_release(uint16_t combo_index, combo_t *combo, uint8_t key return false; } ``` + +### Customizable key repress +By defining `COMBO_PROCESS_KEY_REPRESS` and implementing `bool process_combo_key_repress(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode)` you can run your custom code when you repress just released key of a combo. By combining it with custom `process_combo_event` we can for example make special handling for Alt+Tab to switch windows, which, on combo F+G activation, registers Alt and presses Tab - then we can switch windows forward by releasing G and pressing it again, or backwards with F key. Here's the full example: + +```c +enum combos { + CMB_ALTTAB +}; + +const uint16_t PROGMEM combo_alttab[] = {KC_F, KC_G, COMBO_END}; + +combo_t key_combos[COMBO_LENGTH] = { + [CMB_ALTTAB] = COMBO(combo_alttab, KC_NO), // KC_NO to leave processing for process_combo_event +}; + +void process_combo_event(uint16_t combo_index, bool pressed) { + switch (combo_index) { + case CMB_ALTTAB: + if (pressed) { + register_mods(MOD_LALT); + tap_code(KC_TAB); + } else { + unregister_mods(MOD_LALT); + } + break; + } +} + +bool process_combo_key_repress(uint16_t combo_index, combo_t *combo, uint8_t key_index, uint16_t keycode) { + switch (combo_index) { + case CMB_ALTTAB: + switch (keycode) { + case KC_F: + tap_code16(S(KC_TAB)); + return true; + case KC_G: + tap_code(KC_TAB); + return true; + } + } + return false; +} +``` + ### Layer independent combos If you, for example, use multiple base layers for different key layouts, one for QWERTY, and another one for Colemak, you might want your combos to work from the same key positions on all layers. Defining the same combos again for another layout is redundant and takes more memory. The solution is to just check the keycodes from one layer. diff --git a/docs/features/os_detection.md b/docs/features/os_detection.md index d0556d2549..880e88d4b9 100644 --- a/docs/features/os_detection.md +++ b/docs/features/os_detection.md @@ -70,17 +70,33 @@ The process is done in steps, generating a number of intermediate results until 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` +* `#define OS_DETECTION_DEBOUNCE 250` * defined the debounce time for OS detection, in milliseconds + * defaults to 250ms * `#define OS_DETECTION_KEYBOARD_RESET` - * enables the keyboard reset upon a USB device reinitilization, such as switching devices on some KVMs + * enables the keyboard reset upon a USB device reinitilization + * this setting may help with detection issues when switching between devices on some KVMs (see [Troubleshooting](#troubleshooting)) +* `#define OS_DETECTION_SINGLE_REPORT` + * allows the report callbacks to be called only once, when the OS detection result is considered stable + * subsequent changes in the detection results, if any, are ignored + * this setting may help with delayed stability issues when switching devices on some KVMs (see [Troubleshooting](#troubleshooting)) + +## Troubleshooting + +Some KVMs and USB switches may cause issues when the OS detection is turned on. +Here is a list of common issues and how to fix them: + +* **Problem**: _keyboard won't redetect the OS when switching between machines using a KVM_ + * **Explanation**: some KVMs keep the USB controller powered on during the switch and OS + detection happens when the USB device description is being assembled. + * **Solution**: use `OS_DETECTION_KEYBOARD_RESET` to force the keyboard to reset upon switching. +* **Problem**: _keyboard OS detection callback gets invoked even minuted after startup_ + * **Explanation**: some OSes, notably macOS on ARM-based Macs, may cause this behavior. + The actual cause is not known at this time.' + * **Solution**: use `OS_DETECTION_SINGLE_REPORT` to suppress repeated callback invocations. + ## Debug diff --git a/docs/features/pointing_device.md b/docs/features/pointing_device.md index a6bf521a18..0ecf82c8df 100644 --- a/docs/features/pointing_device.md +++ b/docs/features/pointing_device.md @@ -394,6 +394,7 @@ Ideally, new sensor hardware should be added to `drivers/sensors/` and `quantum/ | Setting | Description | Default | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `MOUSE_EXTENDED_REPORT` | (Optional) Enables support for extended mouse reports. (-32767 to 32767, instead of just -127 to 127). | _not defined_ | +| `WHEEL_EXTENDED_REPORT` | (Optional) Enables support for extended wheel 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_ | diff --git a/docs/keycodes.md b/docs/keycodes.md index 9038c2b6d7..9107ca5eb8 100644 --- a/docs/keycodes.md +++ b/docs/keycodes.md @@ -294,11 +294,11 @@ See also: [Backlighting](features/backlight) See also: [Bluetooth](features/bluetooth) -|Key |Aliases |Description | -|---------------------|---------|----------------------------------------------| -|`QK_OUTPUT_AUTO` |`OU_AUTO`|Automatically switch between USB and Bluetooth| -|`QK_OUTPUT_USB` |`OU_USB` |USB only | -|`QK_OUTPUT_BLUETOOTH`|`OU_BT` |Bluetooth only | +| Key | Aliases | Description | +|-----------------------|----------------------|------------------------------------------------| +| `QK_OUTPUT_NEXT` | `OU_NEXT`, `OU_AUTO` | Automatically switch between USB and Bluetooth | +| `QK_OUTPUT_USB` | `OU_USB` | USB only | +| `QK_OUTPUT_BLUETOOTH` | `OU_BT` | Bluetooth only | ## Caps Word {#caps-word} diff --git a/docs/other_vscode.md b/docs/other_vscode.md index 31208d8f3b..ab2b23e96b 100644 --- a/docs/other_vscode.md +++ b/docs/other_vscode.md @@ -177,12 +177,13 @@ You'll need to perform some modifications to the file above in order to target y Windows builds of QMK Firmware are generally compiled using QMK MSYS, and the path to gdb's location (`C:\\QMK_MSYS\\mingw64\\bin`) needs to be specified under `armToolchainPath` for it to be detected. You may also need to change the GDB path to point at `C:\\QMK_MSYS\\mingw64\\bin\\gdb-multiarch.exe` in the VSCode Cortex-Debug user settings:  ::: -Optionally, the following modifications should also be made to the keyboard's `rules.mk` file to disable optimisations -- not strictly required but will ensure breakpoints and variable viewing works correctly: +The following modifications must be made to the keyboard's `rules.mk` file to enable debug information and disable optimisations -- this will ensure breakpoints and variable viewing works correctly: ```makefile +# Enable debug information in the final binaries +DEBUG_ENABLE = yes # Disable optimisations for debugging purposes LTO_ENABLE = no OPT = g -DEBUG = 3 ``` At this point, you should build and flash your firmware through normal methods (`qmk compile ...` and `qmk flash ...`). diff --git a/docs/quantum_painter.md b/docs/quantum_painter.md index 1d844d0f94..782d496ff7 100644 --- a/docs/quantum_painter.md +++ b/docs/quantum_painter.md @@ -28,6 +28,8 @@ Supported devices: | ILI9341 | RGB LCD | 240x320 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9341_spi` | | ILI9486 | RGB LCD | 320x480 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9486_spi` | | ILI9488 | RGB LCD | 320x480 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9488_spi` | +| LD7032 (SPI) | Monochrome OLED | 128x40 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ld7032_spi` | +| LD7032 (I2C) | Monochrome OLED | 128x40 | I2C | `QUANTUM_PAINTER_DRIVERS += ld7032_i2c` | | SSD1351 | RGB OLED | 128x128 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ssd1351_spi` | | ST7735 | RGB LCD | 132x162, 80x160 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += st7735_spi` | | ST7789 | RGB LCD | 240x320, 240x240 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += st7789_spi` | @@ -478,6 +480,40 @@ Native color format mono2 is compatible with SH1106 SSD1306 and SH1106 are almost entirely identical, to the point of being indisinguishable by Quantum Painter. Enable SH1106 support in Quantum Painter and create SH1106 devices in firmware to perform drawing operations on SSD1306 displays. +==== LD7032 + +Enabling support for the LD7032 in Quantum Painter is done by adding the following to `rules.mk`: + +```make +QUANTUM_PAINTER_ENABLE = yes +# For SPI: +QUANTUM_PAINTER_DRIVERS += ld7032_spi +# For I2C: +QUANTUM_PAINTER_DRIVERS += ld7032_i2c +``` + +Creating a SH1106 device in firmware can then be done with the following APIs: + +```c +// SPI-based LD7032: +painter_device_t qp_ld7032_make_spi_device(uint16_t panel_width, uint16_t panel_height, pin_t chip_select_pin, pin_t dc_pin, pin_t reset_pin, uint16_t spi_divisor, int spi_mode); +// I2C-based LD7032: +painter_device_t qp_ld7032_make_i2c_device(uint16_t panel_width, uint16_t panel_height, uint8_t i2c_address); +``` + +The device handle returned from the `qp_ld7032_make_???_device` function can be used to perform all other drawing operations. + +The maximum number of displays of each type can be configured by changing the following in your `config.h` (default is 1): + +```c +// 3 SPI displays: +#define LD7032_NUM_SPI_DEVICES 3 +// 3 I2C displays: +#define LD7032_NUM_I2C_DEVICES 3 +``` + +Native color format mono2 is compatible with LD7032. + ::::: ===== Surface diff --git a/docs/ref_functions.md b/docs/ref_functions.md index 3304981ef5..599515ebc1 100644 --- a/docs/ref_functions.md +++ b/docs/ref_functions.md @@ -69,7 +69,7 @@ layer_state_t layer_state_set_user(layer_state_t state) { Do you want to set the default layer, so that it's retained even after you unplug the board? If so, this is the function for you. -To use this, you would use `set_single_persistent_default_layer(layer)`. If you have a name defined for your layer, you can use that instead (such as _QWERTY, _DVORAK or _COLEMAK). +To do this, you would use `set_single_persistent_default_layer(layer)`. If you have a name defined for your layer, you can use that instead (such as _QWERTY, _DVORAK or _COLEMAK). This will set the default layer, update the persistent settings, and play a tune if you have [Audio](features/audio) enabled on your board, and the default layer sounds set. @@ -82,6 +82,8 @@ To configure the default layer sounds, you would want to define this in your `co } ``` +If you do not require it to be retained after you unplug the board, use `set_single_default_layer(layer)` instead. + ::: tip There are a large number of predefined songs in [quantum/audio/song_list.h](https://github.com/qmk/qmk_firmware/blob/master/quantum/audio/song_list.h) that you can use. |