diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 2 | ||||
| -rw-r--r-- | docs/apa102_driver.md | 49 | ||||
| -rw-r--r-- | docs/eeprom_driver.md | 20 | ||||
| -rw-r--r-- | docs/feature_auto_shift.md | 18 | ||||
| -rw-r--r-- | docs/feature_backlight.md | 4 | ||||
| -rw-r--r-- | docs/feature_led_matrix.md | 55 | ||||
| -rw-r--r-- | docs/feature_oled_driver.md | 56 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 286 | ||||
| -rw-r--r-- | docs/feature_rgblight.md | 37 | ||||
| -rw-r--r-- | docs/feature_split_keyboard.md | 2 | ||||
| -rw-r--r-- | docs/feature_velocikey.md | 29 | ||||
| -rw-r--r-- | docs/i2c_driver.md | 12 | ||||
| -rw-r--r-- | docs/ja/_summary.md | 1 | ||||
| -rw-r--r-- | docs/ja/feature_velocikey.md | 34 | ||||
| -rw-r--r-- | docs/quantum_painter.md | 209 | ||||
| -rw-r--r-- | docs/quantum_painter_lvgl.md | 8 | ||||
| -rw-r--r-- | docs/reference_info_json.md | 170 | ||||
| -rw-r--r-- | docs/spi_driver.md | 17 | ||||
| -rw-r--r-- | docs/squeezing_avr.md | 1 | ||||
| -rw-r--r-- | docs/uart_driver.md | 12 | ||||
| -rw-r--r-- | docs/unit_testing.md | 4 | ||||
| -rw-r--r-- | docs/ws2812_driver.md | 278 | ||||
| -rw-r--r-- | docs/zh-cn/_summary.md | 1 |
23 files changed, 861 insertions, 444 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 26a543aee4..722c5f9c5d 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -126,7 +126,6 @@ * [PS/2 Mouse](feature_ps2_mouse.md) * [Split Keyboard](feature_split_keyboard.md) * [Stenography](feature_stenography.md) - * [Velocikey](feature_velocikey.md) * Keyboard Building * [Easy Maker for One Offs](easy_maker.md) @@ -148,6 +147,7 @@ * [Compatible Microcontrollers](compatible_microcontrollers.md) * [Drivers](hardware_drivers.md) * [ADC Driver](adc_driver.md) + * [APA102 Driver](apa102_driver.md) * [Audio Driver](audio_driver.md) * [I2C Driver](i2c_driver.md) * [SPI Driver](spi_driver.md) diff --git a/docs/apa102_driver.md b/docs/apa102_driver.md new file mode 100644 index 0000000000..1da2de6ca3 --- /dev/null +++ b/docs/apa102_driver.md @@ -0,0 +1,49 @@ +# APA102 Driver :id=apa102-driver + +This driver provides support for APA102 addressable RGB LEDs. They are similar to the [WS2812](ws2812_driver.md) LEDs, but have increased data and refresh rates. + +## Usage :id=usage + +In most cases, the APA102 driver code is automatically included if you are using either the [RGBLight](feature_rgblight.md) or [RGB Matrix](feature_rgb_matrix.md) feature with the `apa102` driver set, and you would use those APIs instead. + +However, if you need to use the driver standalone, add the following to your `rules.mk`: + +```make +APA102_DRIVER_REQUIRED = yes +``` + +You can then call the APA102 API by including `apa102.h` in your code. + +## Basic Configuration :id=basic-configuration + +Add the following to your `config.h`: + +|Define |Default |Description | +|---------------------------|-------------|------------------------------------------------------------------| +|`APA102_DI_PIN` |*Not defined*|The GPIO pin connected to the DI pin of the first LED in the chain| +|`APA102_CI_PIN` |*Not defined*|The GPIO pin connected to the CI pin of the first LED in the chain| +|`APA102_DEFAULT_BRIGHTNESS`|`31` |The default global brightness level of the LEDs, from 0 to 31 | + +## API :id=api + +### `void apa102_setleds(rgb_led_t *start_led, uint16_t num_leds)` + +Send RGB data to the APA102 LED chain. + +#### Arguments :id=api-apa102-setleds-arguments + + - `rgb_led_t *start_led` + A pointer to the LED array. + - `uint16_t num_leds` + The length of the LED array. + +--- + +### `void apa102_set_brightness(uint8_t brightness)` + +Set the global brightness. + +#### Arguments :id=api-apa102-set-brightness-arguments + + - `uint8_t brightness` + The brightness level to set, from 0 to 31. diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md index 50d8bcb7b3..c77d18c68d 100644 --- a/docs/eeprom_driver.md +++ b/docs/eeprom_driver.md @@ -66,6 +66,14 @@ Currently QMK supports 25xx-series chips over SPI. As such, requires a working s `#define EXTERNAL_EEPROM_PAGE_SIZE` | `32` | Page size of the EEPROM in bytes, as specified in the datasheet `#define EXTERNAL_EEPROM_ADDRESS_SIZE` | `2` | The number of bytes to transmit for the memory location within the EEPROM +Default values and extended descriptions can be found in `drivers/eeprom/eeprom_spi.h`. + +Alternatively, there are pre-defined hardware configurations for available chips/modules: + +Module | Equivalent `#define` | Source +-----------------|---------------------------------|------------------------------------------ +MB85RS64V FRAM | `define EEPROM_SPI_MB85RS64V` | <https://www.adafruit.com/product/1897> + !> There's no way to determine if there is an SPI EEPROM actually responding. Generally, this will result in reads of nothing but zero. ## Transient Driver configuration :id=transient-eeprom-driver-configuration @@ -105,11 +113,11 @@ Configurable options in your keyboard's `config.h`: `config.h` override | Default | Description -----------------------------------------|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_ | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration. -`#define WEAR_LEVELING_EFL_FLASH_SIZE` | _unset_ | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting. -`#define WEAR_LEVELING_LOGICAL_SIZE` | `1024` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. -`#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size. -`#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly. +`#define WEAR_LEVELING_EFL_FIRST_SECTOR` | _unset_ | The first sector on the MCU to use. By default this is not defined and calculated at runtime based on the MCU. However, different flash sizes on MCUs may require custom configuration. +`#define WEAR_LEVELING_EFL_FLASH_SIZE` | _unset_ | Allows overriding the flash size available for use for wear-leveling. Under normal circumstances this is automatically calculated and should not need to be overridden. Specifying a size larger than the amount actually available in flash will usually prevent the MCU from booting. +`#define WEAR_LEVELING_LOGICAL_SIZE` | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. +`#define WEAR_LEVELING_BACKING_SIZE` | `2048` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size. +`#define BACKING_STORE_WRITE_SIZE` | _automatic_ | The byte width of the underlying write used on the MCU, and is usually automatically determined from the selected MCU family. If an error occurs in the auto-detection, you'll need to consult the MCU's datasheet and determine this value, specifying it directly. !> If your MCU does not boot after swapping to the EFL wear-leveling driver, it's likely that the flash size is incorrectly detected, usually as an MCU with larger flash and may require overriding. @@ -139,7 +147,7 @@ Configurable options in your keyboard's `config.h`: ------------------------------------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------- `#define WEAR_LEVELING_RP2040_FLASH_SIZE` | `PICO_FLASH_SIZE_BYTES` | Number of bytes of flash on the board. `#define WEAR_LEVELING_RP2040_FLASH_BASE` | `(flash_size-sector_size)` | The byte-wise location that the backing storage should be located. -`#define WEAR_LEVELING_LOGICAL_SIZE` | `4096` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. +`#define WEAR_LEVELING_LOGICAL_SIZE` | `(backing_size/2)` | Number of bytes "exposed" to the rest of QMK and denotes the size of the usable EEPROM. `#define WEAR_LEVELING_BACKING_SIZE` | `8192` | Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size as well as the sector size. `#define BACKING_STORE_WRITE_SIZE` | `2` | The write width used whenever a write is performed on the external flash peripheral. diff --git a/docs/feature_auto_shift.md b/docs/feature_auto_shift.md index 6241cbaeb1..74be33cdd4 100644 --- a/docs/feature_auto_shift.md +++ b/docs/feature_auto_shift.md @@ -180,18 +180,18 @@ For more granular control, there is `get_auto_shifted_key`. The default function bool get_auto_shifted_key(uint16_t keycode, keyrecord_t *record) { switch (keycode) { # ifndef NO_AUTO_SHIFT_ALPHA - case KC_A ... KC_Z: + case AUTO_SHIFT_ALPHA: # endif # ifndef NO_AUTO_SHIFT_NUMERIC - case KC_1 ... KC_0: + case AUTO_SHIFT_NUMERIC: # endif # ifndef NO_AUTO_SHIFT_SPECIAL -# ifndef NO_AUTO_SHIFT_TAB +# ifndef NO_AUTO_SHIFT_TAB case KC_TAB: -# endif -# ifndef NO_AUTO_SHIFT_SYMBOLS +# endif +# ifndef NO_AUTO_SHIFT_SYMBOLS case AUTO_SHIFT_SYMBOLS: -# endif +# endif # endif # ifdef AUTO_SHIFT_ENTER case KC_ENT: @@ -310,10 +310,16 @@ generating taps on release. For example: #define RETRO_SHIFT 500 ``` +Without a value set, holds of any length without an interrupting key will produce the shifted value. + This value (if set) must be greater than one's `TAPPING_TERM`, as the key press must be designated as a 'hold' by `process_tapping` before we send the modifier. +[Per-key tapping terms](tap_hold.md#tapping-term) can be used as a workaround. There is no such limitation in regards to `AUTO_SHIFT_TIMEOUT` for normal keys. +**Note:** Tap Holds must be added to Auto Shift, see [here.](feature_auto_shift.md#auto-shift-per-key) +`IS_RETRO` may be helpful if one wants all Tap Holds retro shifted. + ### Retro Shift and Tap Hold Configurations Tap Hold Configurations work a little differently when using Retro Shift. diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index d032c33f18..89916aa813 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -37,8 +37,10 @@ Add the following to your `config.h`: |`BREATHING_PERIOD` |`6` |The length of one backlight "breath" in seconds | |`BACKLIGHT_ON_STATE` |`1` |The state of the backlight pin when the backlight is "on" - `1` for high, `0` for low | |`BACKLIGHT_LIMIT_VAL` |`255` |The maximum duty cycle of the backlight -- `255` allows for full brightness, any lower will decrease the maximum.| +|`BACKLIGHT_DEFAULT_ON` |`true` |Enable backlight upon clearing the EEPROM | +|`BACKLIGHT_DEFAULT_BREATHING`|`false` |Whether to enable backlight breathing upon clearing the EEPROM | |`BACKLIGHT_DEFAULT_LEVEL` |`BACKLIGHT_LEVELS`|The default backlight level to use upon clearing the EEPROM | -|`BACKLIGHT_DEFAULT_BREATHING`|*Not defined* |Whether to enable backlight breathing upon clearing the EEPROM | +|`BACKLIGHT_PWM_PERIOD` |2048Hz |Defaults to `BACKLIGHT_PWM_COUNTER_FREQUENCY / 2048`, which results in a PWM frequency of 2048Hz. | Unless you are designing your own keyboard, you generally should not need to change the `BACKLIGHT_PIN` or `BACKLIGHT_ON_STATE`. diff --git a/docs/feature_led_matrix.md b/docs/feature_led_matrix.md index fd56a45725..7dd2e71d61 100644 --- a/docs/feature_led_matrix.md +++ b/docs/feature_led_matrix.md @@ -19,14 +19,14 @@ You can use between 1 and 4 IS31FL3731 IC's. Do not specify `LED_DRIVER_ADDR_<N> | Variable | Description | Default | |----------|-------------|---------| -| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `LED_DRIVER_COUNT` | (Required) How many LED driver IC's are present | | +| `IS31FL3731_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `IS31FL3731_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `IS31FL3731_DRIVER_COUNT` | (Required) How many LED driver IC's are present | | | `LED_MATRIX_LED_COUNT` | (Required) How many LED lights are present across all drivers | | -| `LED_DRIVER_ADDR_1` | (Required) Address for the first LED driver | | -| `LED_DRIVER_ADDR_2` | (Optional) Address for the second LED driver | | -| `LED_DRIVER_ADDR_3` | (Optional) Address for the third LED driver | | -| `LED_DRIVER_ADDR_4` | (Optional) Address for the fourth LED driver | | +| `IS31FL3731_I2C_ADDRESS_1` | (Required) Address for the first LED driver | | +| `IS31FL3731_I2C_ADDRESS_2` | (Optional) Address for the second LED driver | | +| `IS31FL3731_I2C_ADDRESS_3` | (Optional) Address for the third LED driver | | +| `IS31FL3731_I2C_ADDRESS_4` | (Optional) Address for the fourth LED driver | | Here is an example using 2 drivers. @@ -34,14 +34,16 @@ Here is an example using 2 drivers. // This is a 7-bit address, that gets left-shifted and bit 0 // set to 0 for write, 1 for read (as per I2C protocol) // The address will vary depending on your wiring: -// 0b1110100 AD <-> GND -// 0b1110111 AD <-> VCC -// 0b1110101 AD <-> SCL -// 0b1110110 AD <-> SDA -#define LED_DRIVER_ADDR_1 0b1110100 -#define LED_DRIVER_ADDR_2 0b1110110 - -#define LED_DRIVER_COUNT 2 +// 00 AD <-> GND +// 01 AD <-> SCL +// 10 AD <-> SDA +// 11 AD <-> VCC +// ADDR represents A1:A0 of the 7-bit address. +// The result is: 0b11101(ADDR) +#define IS31FL3731_I2C_ADDRESS_1 IS31FL3731_I2C_ADDRESS_GND +#define IS31FL3731_I2C_ADDRESS_2 IS31FL3731_I2C_ADDRESS_SDA + +#define IS31FL3731_DRIVER_COUNT 2 #define LED_DRIVER_1_LED_TOTAL 25 #define LED_DRIVER_2_LED_TOTAL 24 #define LED_MATRIX_LED_COUNT (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL) @@ -49,12 +51,12 @@ Here is an example using 2 drivers. !> Note the parentheses, this is so when `LED_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL)` will give very different results than `rand() % LED_DRIVER_1_LED_TOTAL + LED_DRIVER_2_LED_TOTAL`. -For split keyboards using `LED_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `DRIVER_ADDR_1` for one and `DRIVER_ADDR_2` for the other one. Then, in `g_is31_leds`, fill out the correct driver index (0 or 1). If using one address, use `DRIVER_ADDR_1` for both, and use index 0 for `g_is31_leds`. +For split keyboards using `LED_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `IS31FL3731_I2C_ADDRESS_1` for one and `IS31FL3731_I2C_ADDRESS_2` for the other one. Then, in `g_is31fl3731_leds`, fill out the correct driver index (0 or 1). If using one address, use `IS31FL3731_I2C_ADDRESS_1` for both, and use index 0 for `g_is31fl3731_leds`. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led PROGMEM g_is31_leds[LED_MATRIX_LED_COUNT] = { +const is31fl3731_led_t PROGMEM g_is31fl3731_leds[LED_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | LED address @@ -159,7 +161,7 @@ Then Define the array listing all the LEDs you want to override in your `<keyboa ```c const is31_led PROGMEM g_is31_scaling[ISSI_MANUAL_SCALING] = { - * LED Index +/* LED Index * | Scaling * | | */ {5, 120}, @@ -248,16 +250,16 @@ enum led_matrix_effects { LED_MATRIX_CYCLE_OUT_IN, // Full gradient scrolling out to in LED_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard LED_MATRIX_SOLID_REACTIVE_SIMPLE, // Pulses keys hit then fades out - LED_MATRIX_SOLID_REACTIVE_WIDE // Value pulses near a single key hit then fades out - LED_MATRIX_SOLID_REACTIVE_MULTIWIDE // Value pulses near multiple key hits then fades out - LED_MATRIX_SOLID_REACTIVE_CROSS // Value pulses the same column and row of a single key hit then fades out - LED_MATRIX_SOLID_REACTIVE_MULTICROSS // Value pulses the same column and row of multiple key hits then fades out - LED_MATRIX_SOLID_REACTIVE_NEXUS // Value pulses away on the same column and row of a single key hit then fades out - LED_MATRIX_SOLID_REACTIVE_MULTINEXUS // Value pulses away on the same column and row of multiple key hits then fades out + LED_MATRIX_SOLID_REACTIVE_WIDE, // Value pulses near a single key hit then fades out + LED_MATRIX_SOLID_REACTIVE_MULTIWIDE, // Value pulses near multiple key hits then fades out + LED_MATRIX_SOLID_REACTIVE_CROSS, // Value pulses the same column and row of a single key hit then fades out + LED_MATRIX_SOLID_REACTIVE_MULTICROSS, // Value pulses the same column and row of multiple key hits then fades out + LED_MATRIX_SOLID_REACTIVE_NEXUS, // Value pulses away on the same column and row of a single key hit then fades out + LED_MATRIX_SOLID_REACTIVE_MULTINEXUS, // Value pulses away on the same column and row of multiple key hits then fades out LED_MATRIX_SOLID_SPLASH, // Value pulses away from a single key hit then fades out LED_MATRIX_SOLID_MULTISPLASH, // Value pulses away from multiple key hits then fades out - LED_MATRIX_WAVE_LEFT_RIGHT // Sine wave scrolling from left to right - LED_MATRIX_WAVE_UP_DOWN // Sine wave scrolling from up to down + LED_MATRIX_WAVE_LEFT_RIGHT, // Sine wave scrolling from left to right + LED_MATRIX_WAVE_UP_DOWN, // Sine wave scrolling from up to down LED_MATRIX_EFFECT_MAX }; ``` @@ -363,6 +365,7 @@ For inspiration and examples, check out the built-in effects under `quantum/led_ #define LED_MATRIX_LED_PROCESS_LIMIT (LED_MATRIX_LED_COUNT + 4) / 5 // limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness) #define LED_MATRIX_LED_FLUSH_LIMIT 16 // limits in milliseconds how frequently an animation will update the LEDs. 16 (16ms) is equivalent to limiting to 60fps (increases keyboard responsiveness) #define LED_MATRIX_MAXIMUM_BRIGHTNESS 255 // limits maximum brightness of LEDs +#define LED_MATRIX_DEFAULT_ON true // Sets the default enabled state, if none has been set #define LED_MATRIX_DEFAULT_MODE LED_MATRIX_SOLID // Sets the default mode, if none has been set #define LED_MATRIX_DEFAULT_VAL LED_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set #define LED_MATRIX_DEFAULT_SPD 127 // Sets the default animation speed, if none has been set diff --git a/docs/feature_oled_driver.md b/docs/feature_oled_driver.md index e67f80c879..452f729e14 100644 --- a/docs/feature_oled_driver.md +++ b/docs/feature_oled_driver.md @@ -167,6 +167,42 @@ bool oled_task_user(void) { #endif ``` +Render a message before booting into bootloader mode. +```c +void oled_render_boot(bool bootloader) { + oled_clear(); + for (int i = 0; i < 16; i++) { + oled_set_cursor(0, i); + if (bootloader) { + oled_write_P(PSTR("Awaiting New Firmware "), false); + } else { + oled_write_P(PSTR("Rebooting "), false); + } + } + + oled_render_dirty(true); +} + +bool reboot = false; + +bool uint16_t keycode, keyrecord_t *record) { + if (record->event.pressed) { + + // Display a special message prior to rebooting... + if (keycode == QK_BOOT) { + reboot = true; + } + } + + return true; +} + +void shutdown_user(void) { + oled_render_boot(reboot); +} + +``` + ## Basic Configuration These configuration options should be placed in `config.h`. Example: @@ -276,7 +312,7 @@ Rotation on SH1106 and SH1107 is noticeably less efficient than on SSD1306, beca ## OLED API ```c -// OLED rotation enum values are flags +// OLED Rotation enum values are flags typedef enum { OLED_ROTATION_0 = 0, OLED_ROTATION_90 = 1, @@ -284,7 +320,7 @@ typedef enum { 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. +// 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); @@ -302,8 +338,12 @@ 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); -// Renders the dirty chunks of the buffer to OLED display -void oled_render(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 @@ -334,8 +374,6 @@ 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 -// oled_scroll_left or oled_scroll_right should be preferred for all cases of moving a static -// image such as a logo or to avoid burn-in as it's much, much less cpu intensive void oled_pan(bool left); // Returns a pointer to the requested start index in the buffer plus remaining @@ -352,6 +390,7 @@ void oled_write_raw_byte(const char data, uint16_t index); // 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 @@ -365,6 +404,11 @@ 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 diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 44899d70d9..f068058093 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -19,15 +19,15 @@ You can use between 1 and 4 IS31FL3731 IC's. Do not specify `DRIVER_ADDR_<N>` de | Variable | Description | Default | |----------|-------------|---------| -| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `ISSI_3731_DEGHOST` | (Optional) Set this define to enable de-ghosting by halving Vcc during blanking time | | -| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `IS31FL3731_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `IS31FL3731_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `IS31FL3731_DEGHOST` | (Optional) Set this define to enable de-ghosting by halving Vcc during blanking time | | +| `IS31FL3731_DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | | `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | -| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | -| `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | -| `DRIVER_ADDR_4` | (Optional) Address for the fourth RGB driver | | +| `IS31FL3731_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | +| `IS31FL3731_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | +| `IS31FL3731_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | +| `IS31FL3731_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | Here is an example using 2 drivers. @@ -35,14 +35,16 @@ Here is an example using 2 drivers. // This is a 7-bit address, that gets left-shifted and bit 0 // set to 0 for write, 1 for read (as per I2C protocol) // The address will vary depending on your wiring: -// 0b1110100 AD <-> GND -// 0b1110111 AD <-> VCC -// 0b1110101 AD <-> SCL -// 0b1110110 AD <-> SDA -#define DRIVER_ADDR_1 0b1110100 -#define DRIVER_ADDR_2 0b1110110 - -#define DRIVER_COUNT 2 +// 00 AD <-> GND +// 01 AD <-> SCL +// 10 AD <-> SDA +// 11 AD <-> VCC +// ADDR represents A1:A0 of the 7-bit address. +// The result is: 0b11101(ADDR) +#define IS31FL3731_I2C_ADDRESS_1 IS31FL3731_I2C_ADDRESS_GND +#define IS31FL3731_I2C_ADDRESS_2 IS31FL3731_I2C_ADDRESS_SDA + +#define IS31FL3731_DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 25 #define DRIVER_2_LED_TOTAL 24 #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) @@ -50,12 +52,12 @@ Here is an example using 2 drivers. !> Note the parentheses, this is so when `RGB_MATRIX_LED_COUNT` is used in code and expanded, the values are added together before any additional math is applied to them. As an example, `rand() % (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL)` will give very different results than `rand() % DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL`. -For split keyboards using `RGB_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `DRIVER_ADDR_1` for one and `DRIVER_ADDR_2` for the other one. Then, in `g_is31_leds`, fill out the correct driver index (0 or 1). If using one address, use `DRIVER_ADDR_1` for both, and use index 0 for `g_is31_leds`. +For split keyboards using `RGB_MATRIX_SPLIT` with an LED driver, you can either have the same driver address or different driver addresses. If using different addresses, use `IS31FL3731_I2C_ADDRESS_1` for one and `IS31FL3731_I2C_ADDRESS_2` for the other one. Then, in `g_is31fl3731_leds`, fill out the correct driver index (0 or 1). If using one address, use `IS31FL3731_I2C_ADDRESS_1` for both, and use index 0 for `g_is31fl3731_leds`. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { +const is31fl3731_led_t PROGMEM g_is31fl3731_leds[RGB_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -83,34 +85,34 @@ You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_<N>` de | Variable | Description | Default | |----------|-------------|---------| -| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3733B only | 0 | -| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `IS31FL3733_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `IS31FL3733_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `IS31FL3733_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3733B only | 0 | +| `IS31FL3733_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | +| `IS31FL3733_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | +| `IS31FL3733_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | +| `IS31FL3733_DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | | `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | -| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | -| `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | -| `DRIVER_ADDR_4` | (Optional) Address for the fourth RGB driver | | -| `DRIVER_SYNC_1` | (Optional) Sync configuration for the first RGB driver | 0 | -| `DRIVER_SYNC_2` | (Optional) Sync configuration for the second RGB driver | 0 | -| `DRIVER_SYNC_3` | (Optional) Sync configuration for the third RGB driver | 0 | -| `DRIVER_SYNC_4` | (Optional) Sync configuration for the fourth RGB driver | 0 | - -The IS31FL3733 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`ISSI_SWPULLUP`/`ISSI_CSPULLUP` are given the value of`PUR_0R`), the values that can be set to enable de-ghosting are as follows: - -| `ISSI_SWPULLUP/ISSI_CSPULLUP` | Description | +| `IS31FL3733_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | +| `IS31FL3733_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | +| `IS31FL3733_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | +| `IS31FL3733_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | +| `IS31FL3733_SYNC_1` | (Optional) Sync configuration for the first RGB driver | 0 | +| `IS31FL3733_SYNC_2` | (Optional) Sync configuration for the second RGB driver | 0 | +| `IS31FL3733_SYNC_3` | (Optional) Sync configuration for the third RGB driver | 0 | +| `IS31FL3733_SYNC_4` | (Optional) Sync configuration for the fourth RGB driver | 0 | + +The IS31FL3733 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`IS31FL3733_SWPULLUP`/`IS31FL3733_CSPULLUP` are given the value of `IS31FL3733_PUR_0R`), the values that can be set to enable de-ghosting are as follows: + +| `IS31FL3733_SWPULLUP/IS31FL3733_CSPULLUP` | Description | |----------------------|-------------| -| `PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `PUR_3KR` | The 3k Ohm resistor used at all times | -| `PUR_4KR` | The 4k Ohm resistor used at all times | -| `PUR_8KR` | The 8k Ohm resistor used at all times | -| `PUR_16KR` | The 16k Ohm resistor used at all times | -| `PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3733_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | +| `IS31FL3733_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3733_PUR_3KR` | The 3k Ohm resistor used at all times | +| `IS31FL3733_PUR_4KR` | The 4k Ohm resistor used at all times | +| `IS31FL3733_PUR_8KR` | The 8k Ohm resistor used at all times | +| `IS31FL3733_PUR_16KR` | The 16k Ohm resistor used at all times | +| `IS31FL3733_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | Here is an example using 2 drivers. @@ -118,17 +120,17 @@ Here is an example using 2 drivers. // This is a 7-bit address, that gets left-shifted and bit 0 // set to 0 for write, 1 for read (as per I2C protocol) // The address will vary depending on your wiring: -// 00 <-> GND -// 01 <-> SCL -// 10 <-> SDA -// 11 <-> VCC +// 00 ADDRn <-> GND +// 01 ADDRn <-> SCL +// 10 ADDRn <-> SDA +// 11 ADDRn <-> VCC // ADDR1 represents A1:A0 of the 7-bit address. // ADDR2 represents A3:A2 of the 7-bit address. // The result is: 0b101(ADDR2)(ADDR1) -#define DRIVER_ADDR_1 0b1010000 -#define DRIVER_ADDR_2 0b1010011 +#define IS31FL3733_I2C_ADDRESS_1 IS31FL3733_I2C_ADDRESS_GND_GND +#define IS31FL3733_I2C_ADDRESS_2 IS31FL3733_I2C_ADDRESS_GND_VCC -#define DRIVER_COUNT 2 +#define IS31FL3733_DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 58 #define DRIVER_2_LED_TOTAL 10 #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) @@ -141,7 +143,7 @@ Currently only 4 drivers are supported, but it would be trivial to support all 8 Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { +const is31fl3733_led_t PROGMEM g_is31fl3733_leds[RGB_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -170,31 +172,31 @@ Configure the hardware via your `config.h`: | Variable | Description | Default | |----------|-------------|---------| -| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3736B only | 0 | -| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `IS31FL3736_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `IS31FL3736_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `IS31FL3736_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3736B only | 0 | +| `IS31FL3736_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | +| `IS31FL3736_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | +| `IS31FL3736_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | +| `IS31FL3736_DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | | `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | -| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | -| `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | -| `DRIVER_ADDR_4` | (Optional) Address for the fourth RGB driver | | +| `IS31FL3736_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | +| `IS31FL3736_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | +| `IS31FL3736_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | +| `IS31FL3736_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | -The IS31FL3736 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`ISSI_SWPULLUP`/`ISSI_CSPULLUP` are given the value of`PUR_0R`), the values that can be set to enable de-ghosting are as follows: +The IS31FL3736 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`IS31FL3736_SWPULLUP`/`IS31FL3736_CSPULLUP` are given the value of `IS31FL3736_PUR_0R`), the values that can be set to enable de-ghosting are as follows: -| `ISSI_SWPULLUP/ISSI_CSPULLUP` | Description | +| `IS31FL3736_SWPULLUP/IS31FL3736_CSPULLUP` | Description | |----------------------|-------------| -| `PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | -| `PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | -| `PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | -| `PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | -| `PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | -| `PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3736_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | +| `IS31FL3736_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3736_PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3736_PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3736_PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3736_PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | +| `IS31FL3736_PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | +| `IS31FL3736_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | Here is an example using 2 drivers. @@ -202,16 +204,17 @@ Here is an example using 2 drivers. // This is a 7-bit address, that gets left-shifted and bit 0 // set to 0 for write, 1 for read (as per I2C protocol) // The address will vary depending on your wiring: -// 0000 <-> GND -// 0101 <-> SCL -// 1010 <-> SDA -// 1111 <-> VCC -// ADDR represents A3:A0 of the 7-bit address. -// The result is: 0b101(ADDR) -#define DRIVER_ADDR_1 0b1010000 -#define DRIVER_ADDR_2 0b1010001 +// 00 ADDRn <-> GND +// 01 ADDRn <-> SCL +// 10 ADDRn <-> SDA +// 11 ADDRn <-> VCC +// ADDR1 represents A1:A0 of the 7-bit address. +// ADDR2 represents A3:A2 of the 7-bit address. +// The result is: 0b101(ADDR2)(ADDR1) +#define IS31FL3736_I2C_ADDRESS_1 IS31FL3736_I2C_ADDRESS_GND_GND +#define IS31FL3736_I2C_ADDRESS_2 IS31FL3736_I2C_ADDRESS_GND_SCL -#define DRIVER_COUNT 2 +#define IS31FL3736_DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 30 #define DRIVER_2_LED_TOTAL 32 #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) @@ -221,7 +224,7 @@ Here is an example using 2 drivers. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { +const is31fl3736_led_t PROGMEM g_is31fl3736_leds[RGB_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -246,31 +249,31 @@ Configure the hardware via your `config.h`: | Variable | Description | Default | |----------|-------------|---------| -| `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | -| `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | -| `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3737B only | 0 | -| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | -| `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | -| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `IS31FL3737_I2C_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | +| `IS31FL3737_I2C_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | +| `IS31FL3737_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3737B only | 0 | +| `IS31FL3737_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | +| `IS31FL3737_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | +| `IS31FL3737_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | +| `IS31FL3737_DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | | `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `DRIVER_ADDR_1` | (Required) Address for the first RGB driver | | -| `DRIVER_ADDR_2` | (Optional) Address for the second RGB driver | | -| `DRIVER_ADDR_3` | (Optional) Address for the third RGB driver | | -| `DRIVER_ADDR_4` | (Optional) Address for the fourth RGB driver | | +| `IS31FL3737_I2C_ADDRESS_1` | (Required) Address for the first RGB driver | | +| `IS31FL3737_I2C_ADDRESS_2` | (Optional) Address for the second RGB driver | | +| `IS31FL3737_I2C_ADDRESS_3` | (Optional) Address for the third RGB driver | | +| `IS31FL3737_I2C_ADDRESS_4` | (Optional) Address for the fourth RGB driver | | -The IS31FL3737 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`ISSI_SWPULLUP`/`ISSI_CSPULLUP` are given the value of`PUR_0R`), the values that can be set to enable de-ghosting are as follows: +The IS31FL3737 IC's have on-chip resistors that can be enabled to allow for de-ghosting of the RGB matrix. By default these resistors are not enabled (`IS31FL3737_SWPULLUP`/`IS31FL3737_CSPULLUP` are given the value of `IS31FL3737_PUR_0R`), the values that can be set to enable de-ghosting are as follows: -| `ISSI_SWPULLUP/ISSI_CSPULLUP` | Description | +| `IS31FL3737_SWPULLUP/IS31FL3737_CSPULLUP` | Description | |----------------------|-------------| -| `PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | -| `PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | -| `PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | -| `PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | -| `PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | -| `PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | -| `PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | -| `PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3737_PUR_0R` | (default) Do not use the on-chip resistors/enable de-ghosting | +| `IS31FL3737_PUR_05KR` | The 0.5k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3737_PUR_1KR` | The 1k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3737_PUR_2KR` | The 2k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3737_PUR_4KR` | The 4k Ohm resistor used during blanking period (t_NOL) | +| `IS31FL3737_PUR_8KR` | The 8k Ohm resistor during blanking period (t_NOL) | +| `IS31FL3737_PUR_16KR` | The 16k Ohm resistor during blanking period (t_NOL) | +| `IS31FL3737_PUR_32KR` | The 32k Ohm resistor used during blanking period (t_NOL) | Here is an example using 2 drivers. @@ -278,16 +281,16 @@ Here is an example using 2 drivers. // This is a 7-bit address, that gets left-shifted and bit 0 // set to 0 for write, 1 for read (as per I2C protocol) // The address will vary depending on your wiring: -// 0000 <-> GND -// 0101 <-> SCL -// 1010 <-> SDA -// 1111 <-> VCC +// 0000 ADDR <-> GND +// 0101 ADDR <-> SCL +// 1010 ADDR <-> SDA +// 1111 ADDR <-> VCC // ADDR represents A3:A0 of the 7-bit address. // The result is: 0b101(ADDR) -#define DRIVER_ADDR_1 0b1010000 -#define DRIVER_ADDR_2 0b1010001 +#define IS31FL3737_I2C_ADDRESS_1 IS31FL3737_I2C_ADDRESS_GND +#define IS31FL3737_I2C_ADDRESS_2 IS31FL3737_I2C_ADDRESS_SCL -#define DRIVER_COUNT 2 +#define IS31FL3737_DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 30 #define DRIVER_2_LED_TOTAL 36 #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) @@ -297,7 +300,7 @@ Here is an example using 2 drivers. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const is31_led PROGMEM g_is31_leds[RGB_MATRIX_LED_COUNT] = { +const is31fl3737_led_t PROGMEM g_is31fl3737_leds[RGB_MATRIX_LED_COUNT] = { /* Refer to IS31 manual for these locations * driver * | R location @@ -407,7 +410,7 @@ Then Define the array listing all the LEDs you want to override in your `<keyboa ```c const is31_led PROGMEM g_is31_scaling[ISSI_MANUAL_SCALING] = { - * LED Index +/* LED Index * | R scaling * | | G scaling * | | | B scaling @@ -465,41 +468,41 @@ Configure the hardware via your `config.h`: ``` --- -### AW20216 :id=aw20216 -There is basic support for addressable RGB matrix lighting with the SPI AW20216 RGB controller. To enable it, add this to your `rules.mk`: +### AW20216S :id=aw20216s +There is basic support for addressable RGB matrix lighting with the SPI AW20216S RGB controller. To enable it, add this to your `rules.mk`: ```make RGB_MATRIX_ENABLE = yes -RGB_MATRIX_DRIVER = aw20216 +RGB_MATRIX_DRIVER = aw20216s ``` -You can use up to 2 AW20216 IC's. Do not specify `DRIVER_<N>_xxx` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: +You can use up to 2 AW20216S IC's. Do not specify `DRIVER_<N>_xxx` defines for IC's that are not present on your keyboard. You can define the following items in `config.h`: | Variable | Description | Default | |----------|-------------|---------| -| `DRIVER_1_CS` | (Required) MCU pin connected to first RGB driver chip select line | B13 | -| `DRIVER_2_CS` | (Optional) MCU pin connected to second RGB driver chip select line | | -| `DRIVER_1_EN` | (Required) MCU pin connected to first RGB driver hardware enable line | C13 | -| `DRIVER_2_EN` | (Optional) MCU pin connected to second RGB driver hardware enable line | | +| `AW20216S_CS_PIN_1` | (Required) MCU pin connected to first RGB driver chip select line | B13 | +| `AW20216S_CS_PIN_2` | (Optional) MCU pin connected to second RGB driver chip select line | | +| `AW20216S_EN_PIN_1` | (Required) MCU pin connected to first RGB driver hardware enable line | C13 | +| `AW20216S_EN_PIN_2` | (Optional) MCU pin connected to second RGB driver hardware enable line | | | `DRIVER_1_LED_TOTAL` | (Required) How many RGB lights are connected to first RGB driver | | | `DRIVER_2_LED_TOTAL` | (Optional) How many RGB lights are connected to second RGB driver | | -| `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | +| `AW20216S_DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | | `RGB_MATRIX_LED_COUNT` | (Required) How many RGB lights are present across all drivers | | -| `AW_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 | -| `AW_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 | -| `AW_SPI_MODE` | (Optional) Mode for SPI communication (0-3, defines polarity and phase of the clock) | 3 | -| `AW_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 | +| `AW20216S_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 | +| `AW20216S_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 | +| `AW20216S_SPI_MODE` | (Optional) Mode for SPI communication (0-3, defines polarity and phase of the clock) | 3 | +| `AW20216S_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 | Here is an example using 2 drivers. ```c -#define DRIVER_1_CS B13 -#define DRIVER_2_CS B14 +#define AW20216S_CS_PIN_1 B13 +#define AW20216S_CS_PIN_2 B14 // Hardware enable lines may be connected to the same pin -#define DRIVER_1_EN C13 -#define DRIVER_2_EN C13 +#define AW20216S_EN_PIN_1 C13 +#define AW20216S_EN_PIN_2 C13 -#define DRIVER_COUNT 2 +#define AW20216S_DRIVER_COUNT 2 #define DRIVER_1_LED_TOTAL 66 #define DRIVER_2_LED_TOTAL 32 #define RGB_MATRIX_LED_COUNT (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) @@ -510,10 +513,10 @@ Here is an example using 2 drivers. Define these arrays listing all the LEDs in your `<keyboard>.c`: ```c -const aw_led PROGMEM g_aw_leds[RGB_MATRIX_LED_COUNT] = { -/* Each AW20216 channel is controlled by a register at some offset between 0x00 +const aw20216s_led_t PROGMEM g_aw20216s_leds[RGB_MATRIX_LED_COUNT] = { +/* Each AW20216S channel is controlled by a register at some offset between 0x00 * and 0xD7 inclusive. - * See drivers/awinic/aw20216.h for the mapping between register offsets and + * See drivers/led/aw20216s.h for the mapping between register offsets and * driver pin locations. * driver * | R location @@ -642,6 +645,7 @@ enum rgb_matrix_effects { RGB_MATRIX_DUAL_BEACON, // Full gradient spinning around center of keyboard RGB_MATRIX_RAINBOW_BEACON, // Full tighter gradient spinning around center of keyboard RGB_MATRIX_RAINBOW_PINWHEELS, // Full dual gradients spinning two halfs of keyboard + RGB_MATRIX_FLOWER_BLOOMING, // Full tighter gradient of first half scrolling left to right and second half scrolling right to left RGB_MATRIX_RAINDROPS, // Randomly changes a single key's hue RGB_MATRIX_JELLYBEAN_RAINDROPS, // Randomly changes a single key's hue and saturation RGB_MATRIX_HUE_BREATHING, // Hue shifts up a slight ammount at the same time, then shifts back @@ -654,12 +658,12 @@ enum rgb_matrix_effects { RGB_MATRIX_DIGITAL_RAIN, // That famous computer simulation RGB_MATRIX_SOLID_REACTIVE_SIMPLE, // Pulses keys hit to hue & value then fades value out RGB_MATRIX_SOLID_REACTIVE, // Static single hue, pulses keys hit to shifted hue then fades to current hue - RGB_MATRIX_SOLID_REACTIVE_WIDE // Hue & value pulse near a single key hit then fades value out - RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE // Hue & value pulse near multiple key hits then fades value out - RGB_MATRIX_SOLID_REACTIVE_CROSS // Hue & value pulse the same column and row of a single key hit then fades value out - RGB_MATRIX_SOLID_REACTIVE_MULTICROSS // Hue & value pulse the same column and row of multiple key hits then fades value out - RGB_MATRIX_SOLID_REACTIVE_NEXUS // Hue & value pulse away on the same column and row of a single key hit then fades value out - RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS // Hue & value pulse away on the same column and row of multiple key hits then fades value out + RGB_MATRIX_SOLID_REACTIVE_WIDE, // Hue & value pulse near a single key hit then fades value out + RGB_MATRIX_SOLID_REACTIVE_MULTIWIDE, // Hue & value pulse near multiple key hits then fades value out + RGB_MATRIX_SOLID_REACTIVE_CROSS, // Hue & value pulse the same column and row of a single key hit then fades value out + RGB_MATRIX_SOLID_REACTIVE_MULTICROSS, // Hue & value pulse the same column and row of multiple key hits then fades value out + RGB_MATRIX_SOLID_REACTIVE_NEXUS, // Hue & value pulse away on the same column and row of a single key hit then fades value out + RGB_MATRIX_SOLID_REACTIVE_MULTINEXUS, // Hue & value pulse away on the same column and row of multiple key hits then fades value out RGB_MATRIX_SPLASH, // Full gradient & value pulse away from a single key hit then fades value out RGB_MATRIX_MULTISPLASH, // Full gradient & value pulse away from multiple key hits then fades value out RGB_MATRIX_SOLID_SPLASH, // Hue & value pulse away from a single key hit then fades value out @@ -694,6 +698,7 @@ You can enable a single effect by defining `ENABLE_[EFFECT_NAME]` in your `confi |`#define ENABLE_RGB_MATRIX_DUAL_BEACON` |Enables `RGB_MATRIX_DUAL_BEACON` | |`#define ENABLE_RGB_MATRIX_RAINBOW_BEACON` |Enables `RGB_MATRIX_RAINBOW_BEACON` | |`#define ENABLE_RGB_MATRIX_RAINBOW_PINWHEELS` |Enables `RGB_MATRIX_RAINBOW_PINWHEELS` | +|`#define ENABLE_RGB_MATRIX_FLOWER_BLOOMING` |Enables `RGB_MATRIX_FLOWER_BLOOMING` | |`#define ENABLE_RGB_MATRIX_RAINDROPS` |Enables `RGB_MATRIX_RAINDROPS` | |`#define ENABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS` |Enables `RGB_MATRIX_JELLYBEAN_RAINDROPS` | |`#define ENABLE_RGB_MATRIX_HUE_BREATHING` |Enables `RGB_MATRIX_HUE_BREATHING` | @@ -875,6 +880,7 @@ These are defined in [`color.h`](https://github.com/qmk/qmk_firmware/blob/master #define RGB_MATRIX_DEFAULT_MODE RGB_MATRIX_CYCLE_LEFT_RIGHT // Sets the default mode, if none has been set #define RGB_MATRIX_DEFAULT_HUE 0 // Sets the default hue value, if none has been set #define RGB_MATRIX_DEFAULT_SAT 255 // Sets the default saturation value, if none has been set +#define RGB_MATRIX_DEFAULT_ON true // Sets the default enabled state, if none has been set #define RGB_MATRIX_DEFAULT_VAL RGB_MATRIX_MAXIMUM_BRIGHTNESS // Sets the default brightness value, if none has been set #define RGB_MATRIX_DEFAULT_SPD 127 // Sets the default animation speed, if none has been set #define RGB_MATRIX_DISABLE_KEYCODES // disables control of rgb matrix by keycodes (must use code functions to control the feature) diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 0288fb04b2..8a64454b0d 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -102,6 +102,7 @@ Your RGB lighting can be configured by placing these `#define`s in your `config. |`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 @@ -370,9 +371,9 @@ If you need to change your RGB lighting in code, for example in a macro to chang Example: ```c -sethsv(HSV_WHITE, (LED_TYPE *)&led[0]); // led 0 -sethsv(HSV_RED, (LED_TYPE *)&led[1]); // led 1 -sethsv(HSV_GREEN, (LED_TYPE *)&led[2]); // led 2 +sethsv(HSV_WHITE, (rgb_led_t *)&led[0]); // led 0 +sethsv(HSV_RED, (rgb_led_t *)&led[1]); // led 1 +sethsv(HSV_GREEN, (rgb_led_t *)&led[2]); // led 2 rgblight_set(); // Utility functions do not call rgblight_set() automatically, so they need to be called explicitly. ``` @@ -551,3 +552,33 @@ 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_split_keyboard.md b/docs/feature_split_keyboard.md index 1705ea9222..c67f04995b 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -298,7 +298,7 @@ This enables transmitting the pointing device status to the master side of the s #define SPLIT_HAPTIC_ENABLE ``` -This enables triggering of haptic feedback on the slave side of the split keyboard. For DRV2605L this will send the mode, but for solenoids it is expected that the desired mode is already set up on the slave. +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 diff --git a/docs/feature_velocikey.md b/docs/feature_velocikey.md deleted file mode 100644 index aeb1865e8a..0000000000 --- a/docs/feature_velocikey.md +++ /dev/null @@ -1,29 +0,0 @@ -# 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/i2c_driver.md b/docs/i2c_driver.md index 92b666b5e3..faff0a1d7b 100644 --- a/docs/i2c_driver.md +++ b/docs/i2c_driver.md @@ -2,6 +2,18 @@ The I2C Master drivers used in QMK have a set of common functions to allow portability between MCUs. +## Usage :id=usage + +In most cases, the I2C Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](feature_oled_driver.md). + +However, if you need to use the driver standalone, add the following to your `rules.mk`: + +```make +I2C_DRIVER_REQUIRED = yes +``` + +You can then call the I2C API by including `i2c_master.h` in your code. + ## I2C Addressing :id=note-on-i2c-addresses All of the addresses expected by this driver should be pushed to the upper 7 bits of the address byte. Setting diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md index 4d6f2348d5..f26665e614 100644 --- a/docs/ja/_summary.md +++ b/docs/ja/_summary.md @@ -112,7 +112,6 @@ * [分割キーボード](ja/feature_split_keyboard.md) * [速記](ja/feature_stenography.md) * [感熱式プリンタ](ja/feature_thermal_printer.md) - * [Velocikey](ja/feature_velocikey.md) * QMK の開発 * [PR チェックリスト](ja/pr_checklist.md) diff --git a/docs/ja/feature_velocikey.md b/docs/ja/feature_velocikey.md deleted file mode 100644 index b13969a195..0000000000 --- a/docs/ja/feature_velocikey.md +++ /dev/null @@ -1,34 +0,0 @@ -# Velocikey - -<!--- - original document: 0.8.147:docs/feature_velocikey.md - git diff 0.8.147 HEAD -- docs/feature_velocikey.md | cat ---> - -Velocikey は入力の速度を使って(レインボー渦巻効果のような)ライト効果の速度を制御できる機能です。速く入力すればするほどライトが速くなります！ - -## 使用法 -Velocikey を使うためには、2つのステップがあります。最初に、キーボードをコンパイルする時に、`rules.mk` に `VELOCIKEY_ENABLE=yes` を設定する必要があります。例えば: - -``` -MOUSEKEY_ENABLE = no -STENO_ENABLE = no -EXTRAKEY_ENABLE = yes -VELOCIKEY_ENABLE = yes -``` - -次に、キーボードの使用中に、VLK_TOG キーコードを使って Velocikey を有効にする必要もあります。これは機能をオンおよびオフにします。 - -以下の全てのライト効果が、Velocikey を有効にすることで制御されます: -- RGB 明滅動作 -- RGB レインボームード -- RGB レインボー渦巻 -- RGB スネーク -- RGB ナイト - -LED 明滅動作の効果のサポートは計画されていますがまだ利用できません。 - -Velocikey が有効になっている限り、現在オンになっている RGB ライトの他の全ての速度設定に関係なく、速度が制御されます。 - -## 設定 -Velocikey は現在のところキーボード設定を介したどのような設定もサポートしません。速度の増加あるいは減少率などを調整したい場合は、`velocikey.c` を編集し、そこで値を調整して、好みの速度を実現する必要があります。 diff --git a/docs/quantum_painter.md b/docs/quantum_painter.md index 5e399183f8..e8fa1bdece 100644 --- a/docs/quantum_painter.md +++ b/docs/quantum_painter.md @@ -13,22 +13,24 @@ QUANTUM_PAINTER_DRIVERS += ...... You will also likely need to select an appropriate driver in `rules.mk`, which is listed below. -!> Quantum Painter is not currently integrated with system-level operations such as disabling displays after a configurable timeout, or when the keyboard goes into suspend. Users will need to handle this manually at the current time. +!> Quantum Painter is not currently integrated with system-level operations such as when the keyboard goes into suspend. Users will need to handle this manually at the current time. The QMK CLI can be used to convert from normal images such as PNG files or animated GIFs, as well as fonts from TTF files. Supported devices: -| Display Panel | Panel Type | Size | Comms Transport | Driver | -|----------------|--------------------|------------------|-----------------|---------------------------------------------| -| GC9A01 | RGB LCD (circular) | 240x240 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += gc9a01_spi` | -| ILI9163 | RGB LCD | 128x128 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9163_spi` | -| ILI9341 | RGB LCD | 240x320 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9341_spi` | -| ILI9488 | RGB LCD | 320x480 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9488_spi` | -| 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` | -| RGB565 Surface | Virtual | User-defined | None | `QUANTUM_PAINTER_DRIVERS += rgb565_surface` | +| Display Panel | Panel Type | Size | Comms Transport | Driver | +|---------------|--------------------|------------------|-----------------|------------------------------------------| +| GC9A01 | RGB LCD (circular) | 240x240 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += gc9a01_spi` | +| ILI9163 | RGB LCD | 128x128 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9163_spi` | +| ILI9341 | RGB LCD | 240x320 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9341_spi` | +| ILI9488 | RGB LCD | 320x480 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += ili9488_spi` | +| 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` | +| SH1106 (SPI) | Monochrome OLED | 128x64 | SPI + D/C + RST | `QUANTUM_PAINTER_DRIVERS += sh1106_spi` | +| SH1106 (I2C) | Monochrome OLED | 128x64 | I2C | `QUANTUM_PAINTER_DRIVERS += sh1106_i2c` | +| Surface | Virtual | User-defined | None | `QUANTUM_PAINTER_DRIVERS += surface` | ## Quantum Painter Configuration :id=quantum-painter-config @@ -188,7 +190,8 @@ Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/noto11.qff.c... <!-- tabs:start --> -### ** Common: Standard TFT (SPI + D/C + RST) ** + +### ** LCD ** Most TFT display panels use a 5-pin interface -- SPI SCK, SPI MOSI, SPI CS, D/C, and RST pins. @@ -302,32 +305,6 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb888 is compatible with ILI9488 -#### ** SSD1351 ** - -Enabling support for the SSD1351 in Quantum Painter is done by adding the following to `rules.mk`: - -```make -QUANTUM_PAINTER_ENABLE = yes -QUANTUM_PAINTER_DRIVERS += ssd1351_spi -``` - -Creating a SSD1351 device in firmware can then be done with the following API: - -```c -painter_device_t qp_ssd1351_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); -``` - -The device handle returned from the `qp_ssd1351_make_spi_device` function can be used to perform all other drawing operations. - -The maximum number of displays can be configured by changing the following in your `config.h` (default is 1): - -```c -// 3 displays: -#define SSD1351_NUM_DEVICES 3 -``` - -Native color format rgb565 is compatible with SSD1351 - #### ** ST7735 ** Enabling support for the ST7735 in Quantum Painter is done by adding the following to `rules.mk`: @@ -386,62 +363,139 @@ Native color format rgb565 is compatible with ST7789 <!-- tabs:end --> -### ** Common: Surfaces ** +### ** OLED ** -Quantum Painter has surface drivers which are able to target a buffer in RAM. In general, surfaces keep track of the "dirty" region -- the area that has been drawn to since the last flush -- so that when transferring to the display they can transfer the minimal amount of data to achieve the end result. +OLED displays tend to use 5-pin SPI when at larger resolutions, or when using color -- SPI SCK, SPI MOSI, SPI CS, D/C, and RST pins. Smaller OLEDs may use I2C instead. -!> These generally require significant amounts of RAM, so at large sizes and/or higher bit depths, they may not be usable on all MCUs. +When using these displays, either `spi_master` or `i2c_master` must already be correctly configured for both the platform and panel you're building for. + +For SPI, the pin assignments for SPI CS, D/C, and RST are specified during device construction -- for I2C the panel's address is specified instead. <!-- tabs:start --> -#### ** RGB565 Surface ** +#### ** SSD1351 ** + +Enabling support for the SSD1351 in Quantum Painter is done by adding the following to `rules.mk`: + +```make +QUANTUM_PAINTER_ENABLE = yes +QUANTUM_PAINTER_DRIVERS += ssd1351_spi +``` + +Creating a SSD1351 device in firmware can then be done with the following API: + +```c +painter_device_t qp_ssd1351_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); +``` + +The device handle returned from the `qp_ssd1351_make_spi_device` function can be used to perform all other drawing operations. + +The maximum number of displays can be configured by changing the following in your `config.h` (default is 1): + +```c +// 3 displays: +#define SSD1351_NUM_DEVICES 3 +``` + +Native color format rgb565 is compatible with SSD1351 + +#### ** SH1106 ** -Enabling support for RGB565 surfaces in Quantum Painter is done by adding the following to `rules.mk`: +Enabling support for the SH1106 in Quantum Painter is done by adding the following to `rules.mk`: ```make QUANTUM_PAINTER_ENABLE = yes -QUANTUM_PAINTER_DRIVERS += rgb565_surface +# For SPI: +QUANTUM_PAINTER_DRIVERS += sh1106_spi +# For I2C: +QUANTUM_PAINTER_DRIVERS += sh1106_i2c ``` -Creating a RGB565 surface in firmware can then be done with the following API: +Creating a SH1106 device in firmware can then be done with the following APIs: ```c -painter_device_t qp_rgb565_make_surface(uint16_t panel_width, uint16_t panel_height, void *buffer); +// SPI-based SH1106: +painter_device_t qp_sh1106_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 SH1106: +painter_device_t qp_sh1106_make_i2c_device(uint16_t panel_width, uint16_t panel_height, uint8_t i2c_address); ``` -The `buffer` is a user-supplied area of memory, and is assumed to be of the size `sizeof(uint16_t) * panel_width * panel_height`. +The device handle returned from the `qp_sh1106_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 SH1106_NUM_SPI_DEVICES 3 +// 3 I2C displays: +#define SH1106_NUM_I2C_DEVICES 3 +``` + +Native color format mono2 is compatible with SH1106 + +<!-- tabs:end --> + +### ** Surface ** -The device handle returned from the `qp_rgb565_make_surface` function can be used to perform all other drawing operations. +Quantum Painter has a surface driver which is able to target a buffer in RAM. In general, surfaces keep track of the "dirty" region -- the area that has been drawn to since the last flush -- so that when transferring to the display they can transfer the minimal amount of data to achieve the end result. + +!> These generally require significant amounts of RAM, so at large sizes and/or higher bit depths, they may not be usable on all MCUs. + +Enabling support for surfaces in Quantum Painter is done by adding the following to `rules.mk`: + +```make +QUANTUM_PAINTER_ENABLE = yes +QUANTUM_PAINTER_DRIVERS += surface +``` + +Creating a surface in firmware can then be done with the following APIs: + +```c +// 16bpp RGB565 surface: +painter_device_t qp_make_rgb565_surface(uint16_t panel_width, uint16_t panel_height, void *buffer); +// 1bpp monochrome surface: +painter_device_t qp_make_mono1bpp_surface(uint16_t panel_width, uint16_t panel_height, void *buffer); +``` + +The `buffer` is a user-supplied area of memory, which can be statically allocated using `SURFACE_REQUIRED_BUFFER_BYTE_SIZE`: + +```c +// Buffer required for a 240x80 16bpp surface: +uint8_t framebuffer[SURFACE_REQUIRED_BUFFER_BYTE_SIZE(240, 80, 16)]; +``` + +The device handle returned from the `qp_make_?????_surface` function can be used to perform all other drawing operations. Example: ```c static painter_device_t my_surface; -static uint16_t my_framebuffer[320 * 240]; // Allocate a buffer for a 320x240 RGB565 display +static uint8_t my_framebuffer[SURFACE_REQUIRED_BUFFER_BYTE_SIZE(240, 80, 16)]; // Allocate a buffer for a 16bpp 240x80 RGB565 display void keyboard_post_init_kb(void) { - my_surface = qp_rgb565_make_surface(320, 240, my_framebuffer); + my_surface = qp_rgb565_make_surface(240, 80, my_framebuffer); qp_init(my_surface, QP_ROTATION_0); + keyboard_post_init_user(); } ``` -The maximum number of RGB565 surfaces can be configured by changing the following in your `config.h` (default is 1): +The maximum number of surfaces can be configured by changing the following in your `config.h` (default is 1): ```c // 3 surfaces: -#define RGB565_SURFACE_NUM_DEVICES 3 +#define SURFACE_NUM_DEVICES 3 ``` -To transfer the contents of the RGB565 surface to another display, the following API can be invoked: +To transfer the contents of the surface to another display of the same pixel format, the following API can be invoked: ```c -bool qp_rgb565_surface_draw(painter_device_t surface, painter_device_t display, uint16_t x, uint16_t y); +bool qp_surface_draw(painter_device_t surface, painter_device_t display, uint16_t x, uint16_t y); ``` The `surface` is the surface to copy out from. The `display` is the target display to draw into. `x` and `y` are the target location to draw the surface pixel data. Under normal circumstances, the location should be consistent, as the dirty region is calculated with respect to the `x` and `y` coordinates -- changing those will result in partial, overlapping draws. -?> Calling `qp_flush()` on the surface resets its dirty region. Copying the surface contents to the display also automatically resets the dirty region. +!> The surface and display panel must have the same native pixel format. -<!-- tabs:end --> +?> Calling `qp_flush()` on the surface resets its dirty region. Copying the surface contents to the display also automatically resets the dirty region. <!-- tabs:end --> @@ -857,13 +911,52 @@ void keyboard_post_init_kb(void) { <!-- tabs:start --> -#### ** Get Geometry ** +#### ** Gettters ** + +These functions allow external code to retrieve the current width, height, rotation, and drawing offsets. + +<!-- tabs:start --> + +#### ** Width ** + +```c +uint16_t qp_get_width(painter_device_t device); +``` + +#### ** Height ** + +```c +uint16_t qp_get_height(painter_device_t device); +``` + +#### ** Rotation ** + +```c +painter_rotation_t qp_get_rotation(painter_device_t device); +``` + +#### ** Offset X ** + +```c +uint16_t qp_get_offset_x(painter_device_t device); +``` + +#### ** Offset Y ** + +```c +uint16_t qp_get_offset_y(painter_device_t device); +``` + +##### ** Everything ** + +Convenience function to call all the previous ones at once. +Note: You can pass `NULL` for the values you are not interested in. ```c void qp_get_geometry(painter_device_t device, uint16_t *width, uint16_t *height, painter_rotation_t *rotation, uint16_t *offset_x, uint16_t *offset_y); ``` -The `qp_get_geometry` function allows external code to retrieve the current width, height, rotation, and drawing offsets. +<!-- tabs:end --> #### ** Set Viewport Offsets ** diff --git a/docs/quantum_painter_lvgl.md b/docs/quantum_painter_lvgl.md index 4d10160baf..b4f31ad4af 100644 --- a/docs/quantum_painter_lvgl.md +++ b/docs/quantum_painter_lvgl.md @@ -53,3 +53,11 @@ The `qp_lvgl_detach` function stops the internal LVGL ticks and releases resourc ## Enabling/Disabling LVGL features :id=lvgl-configuring You can overwrite LVGL specific features in your `lv_conf.h` file. + +## Changing the LVGL task frequency + +When LVGL is running, your keyboard's responsiveness may decrease, causing missing keystrokes or encoder rotations, especially during the animation of dynamically-generated content. This occurs because LVGL operates as a scheduled task with a default task rate of five milliseconds. While a fast task rate is advantageous when LVGL is responsible for detecting and processing inputs, it can lead to excessive recalculations of displayed content, which may slow down QMK's matrix scanning. If you rely on QMK instead of LVGL for processing inputs, it can be beneficial to increase the time between calls to the LVGL task handler to better match your preferred display update rate. To do this, add this to your `config.h`: + +```c +#define QP_LVGL_TASK_PERIOD 40 +``` diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 91581afc73..4a70a4bb6f 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -60,6 +60,13 @@ You can create `info.json` files at every level under `qmk_firmware/keyboards/<k } ``` * `qmk` + * `locking` + * `enabled` + * Enable locking switch support. + * Default: `false` + * `resync` + * Keep switch state consistent with keyboard LED state. + * Default: `false` * `tap_capslock_delay` * The delay between keydown and keyup for Caps Lock tap events in milliseconds. * Default: `80` (80 ms) @@ -88,7 +95,7 @@ You can create `info.json` files at every level under `qmk_firmware/keyboards/<k ## APA102 :id=apa102 -Configures the APA102 driver. +Configures the [APA102](apa102_driver.md) driver. * `apa102` * `clock_pin` (Required) @@ -127,6 +134,16 @@ Configures the [Backlight](feature_backlight.md) feature. * `breathing_period` * The length of one backlight breathing cycle in seconds. * Default: `6` (6 seconds) + * `default` + * `on` + * The default backlight enabled state. + * Default: `true` + * `breathing` + * The default backlight breathing state. + * Default: `false` + * `brightness` + * The default brightness level. + * Default: `max_brightness` * `driver` * The driver to use. Must be one of `custom`, `pwm`, `software`, `timer`. * Default: `"pwm"` @@ -194,6 +211,20 @@ Configures the [Combo](feature_combo.md) feature. * The amount of time to recognize a combo in milliseconds. * Default: `50` (50 ms) +## DIP Switches :id=dip-switch + +Configures the [DIP Switches](feature_dip_switch.md) feature. + +* `dip_switch` + * `enabled` + * Enable the DIP Switches feature. + * Default: `false` + * `pins` + * A list of GPIO pins connected to the MCU. + * `matrix_grid` + * A list of matrix locations in the key matrix. + * Example: `[ [0,6], [1,6], [2,6] ]` + ## EEPROM :id=eeprom Configures the [EEPROM](eeprom_driver.md) driver. @@ -202,6 +233,13 @@ Configures the [EEPROM](eeprom_driver.md) driver. * `driver` * The EEPROM backend to use. Must be one of `custom`, `i2c`, `legacy_stm32_flash`, `spi`, `transient`, `vendor`, `wear_leveling`. * Default: `"vendor"` + * `wear_leveling` + * `driver` + * The driver to use. Must be one of `embedded_flash`, `legacy`, `rp2040_flash`, `spi_flash`, `custom`. + * `backing_size` + * Number of bytes used by the wear-leveling algorithm for its underlying storage, and needs to be a multiple of the logical size. + * `logical_size` + * Number of bytes “exposed” to the rest of QMK and denotes the size of the usable EEPROM. ## Encoder :id=encoder @@ -313,7 +351,7 @@ Configures the [LED Matrix](feature_led_matrix.md) feature. * Example: ```json { - "alpha_mods": true, + "alphas_mods": true, "breathing": true, "cycle_left_right": false } @@ -321,8 +359,21 @@ Configures the [LED Matrix](feature_led_matrix.md) feature. * `center_point` * The centroid (geometric center) of the LEDs. Used for certain effects. * Default: `[112, 32]` + * `default` + * `animation` + * The default effect. Must be one of `led_matrix.animations` + * Default: `"solid"` + * `on` + * The default enabled state. + * Default: `true` + * `val` + * The default brightness level. + * Default: `max_brightness` + * `speed` + * The default animation speed. + * Default: `128` * `driver` (Required) - * The driver to use. Must be one of `ckled2001`, `custom`, `is31fl3731`, `is31fl3742a`, `is31fl3743a`, `is31fl3745`, `is31fl3746a`. + * The driver to use. Must be one of `custom`, `is31fl3218`, `is31fl3731`, `is31fl3733`, `is31fl3736`, `is31fl3737`, `is31fl3741`, `is31fl3742a`, `is31fl3743a`, `is31fl3745`, `is31fl3746a`, `snled27351`. * `layout` (Required) * List of LED configuration dictionaries. Each dictionary contains: * `flags` (Required) @@ -335,9 +386,21 @@ Configures the [LED Matrix](feature_led_matrix.md) feature. * The key matrix position associated with the LED. * Example: `[0, 2]` * Example: `{"matrix": [2, 1], "x": 20, "y": 48, "flags": 2}` + * `led_flush_limit` + * Limits in milliseconds how frequently an animation will update the LEDs. + * Default: `16` + * `led_process_limit` + * Limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness). + * Default: `led_count / 5` * `max_brightness` * The maximum value which brightness is scaled to, from 0 to 255. * Default: `255` + * `react_on_keyup` + * Animations react to keyup instead of keydown. + * Default: `false` + * `sleep` + * Turn off the LEDs when the host goes to sleep. + * Default: `false` * `speed_steps` * The number of speed adjustment steps. * Default: `16` @@ -466,6 +529,25 @@ Configures the [RGB Lighting](feature_rgblight.md) feature. * `brightness_steps` * The number of brightness adjustment steps. * Default: `17` + * `default` + * `animation` + * The default effect. Must be one of `rgblight.animations` + * Default: `"static_light"` + * `on` + * The default enabled state. + * Default: `true` + * `hue` + * The default hue value. + * Default: `0` + * `sat` + * The default saturation value. + * Default: `255` + * `val` + * The default brightness level. + * Default: `max_brightness` + * `speed` + * The default animation speed. + * Default: `0` * `driver` * The driver to use. Must be one of `apa102`, `custom`, `ws2812`. * Default: `"ws2812"` @@ -514,7 +596,7 @@ Configures the [RGB Matrix](feature_rgb_matrix.md) feature. * Example: ```json { - "alpha_mods": true, + "alphas_mods": true, "breathing": true, "cycle_left_right": false } @@ -522,8 +604,27 @@ Configures the [RGB Matrix](feature_rgb_matrix.md) feature. * `center_point` * The centroid (geometric center) of the LEDs. Used for certain effects. * Default: `[112, 32]` + * `default` + * `animation` + * The default effect. Must be one of `rgb_matrix.animations` + * Default: `"solid_color"` + * `on` + * The default enabled state. + * Default: `true` + * `hue` + * The default hue value. + * Default: `0` + * `sat` + * The default saturation value. + * Default: `255` + * `val` + * The default brightness level. + * Default: `max_brightness` + * `speed` + * The default animation speed. + * Default: `128` * `driver` (Required) - * The driver to use. Must be one of `aw20216`, `ckled2001`, `custom`, `is31fl3731`, `is31fl3733`, `is31fl3736`, `is31fl3737`, `is31fl3741`, `is31fl3742a`, `is31fl3743a`, `is31fl3745`, `is31fl3746a`, `ws2812`. + * The driver to use. Must be one of `aw20216s`, `custom`, `is31fl3218`, `is31fl3731`, `is31fl3733`, `is31fl3736`, `is31fl3737`, `is31fl3741`, `is31fl3742a`, `is31fl3743a`, `is31fl3745`, `is31fl3746a`, `snled27351`, `ws2812`. * `hue_steps` * The number of hue adjustment steps. * Default: `8` @@ -539,12 +640,24 @@ Configures the [RGB Matrix](feature_rgb_matrix.md) feature. * The key matrix position associated with the LED. * Example: `[0, 2]` * Example: `{"matrix": [2, 1], "x": 20, "y": 48, "flags": 2}` + * `led_flush_limit` + * Limits in milliseconds how frequently an animation will update the LEDs. + * Default: `16` + * `led_process_limit` + * Limits the number of LEDs to process in an animation per task run (increases keyboard responsiveness). + * Default: `led_count / 5` * `max_brightness` * The maximum value which the HSV "V" component is scaled to, from 0 to 255. * Default: `255` + * `react_on_keyup` + * Animations react to keyup instead of keydown. + * Default: `false` * `sat_steps` * The number of saturation adjustment steps. * Default: `16` + * `sleep` + * Turn off the LEDs when the host goes to sleep. + * Default: `false` * `speed_steps` * The number of speed adjustment steps. * Default: `16` @@ -584,6 +697,10 @@ Configures the [Split Keyboard](feature_split_keyboard.md) feature. * `bootmagic` * `matrix` * See [Bootmagic](#bootmagic) config. + * `dip_switch` + * `right` + * `pins` + * See [DIP Switches](#dip-switch) config. * `enabled` * Enable the Split Keyboard feature. * Default: `false` @@ -591,6 +708,12 @@ Configures the [Split Keyboard](feature_split_keyboard.md) feature. * `right` * `rotary` * See [Encoder](#encoder) config. + * `handedness` + * `pin` + * The GPIO pin connected to determine handedness. + * `matrix_grid` + * The GPIO pins of the matrix position which determines the handedness. + * Example: `["A1", "B5"]` * `matrix_pins` * `right` * See [Matrix](#matrix) config. @@ -602,12 +725,37 @@ Configures the [Split Keyboard](feature_split_keyboard.md) feature. * `transport` * `protocol` * The split transport protocol to use. Must be one of `custom`, `i2c`, `serial`, `serial_usart`. - * `sync_matrix_state` - * Mirror the main/primary half's matrix state to the secondary half. - * Default: `false` - * `sync_modifiers` - * Mirror the modifier state to the secondary half. - * Default: `false` + * `sync` + * `activity` + * Mirror the activity timestamps to the secondary half. + * Default: `false` + * `detected_os` + * Mirror the [detected OS](feature_os_detection.md) to the secondary half. + * Default: `false` + * `haptic` + * Mirror the haptic state and process haptic feedback to the secondary half. + * Default: `false` + * `layer_state` + * Mirror the layer state to the secondary half. + * Default: `false` + * `indicators` + * Mirror the indicator state to the secondary half. + * Default: `false` + * `matrix_state` + * Mirror the main/primary half's matrix state to the secondary half. + * Default: `false` + * `modifiers` + * Mirror the modifier state to the secondary half. + * Default: `false` + * `oled` + * Mirror the OLED on/off status to the secondary half. + * Default: `false` + * `st7565` + * Mirror the ST7565 on/off status to the secondary half. + * Default: `false` + * `wpm` + * Mirror the current WPM value to the secondary half. + * Default: `false` * `watchdog` * Reboot the secondary half if it loses connection. * Default: `false` diff --git a/docs/spi_driver.md b/docs/spi_driver.md index c1c6831e73..569a19f1db 100644 --- a/docs/spi_driver.md +++ b/docs/spi_driver.md @@ -2,6 +2,18 @@ The SPI Master drivers used in QMK have a set of common functions to allow portability between MCUs. +## Usage :id=usage + +In most cases, the SPI Master driver code is automatically included if you are using a feature or driver which requires it, such as [OLED](feature_oled_driver.md). + +However, if you need to use the driver standalone, add the following to your `rules.mk`: + +```make +SPI_DRIVER_REQUIRED = yes +``` + +You can then call the SPI API by including `spi_master.h` in your code. + ## AVR Configuration :id=avr-configuration No special setup is required - just connect the `SS`, `SCK`, `MOSI` and `MISO` pins of your SPI devices to the matching pins on the MCU: @@ -49,6 +61,11 @@ Configuration-wise, you'll need to set up the peripheral as per your MCU's datas As per the AVR configuration, you may choose any other standard GPIO as a slave select pin, which should be supplied to `spi_start()`. +If a complete SPI interface is not required, then the following can be done to disable certain SPI pins, so they don't occupy a GPIO unnecessarily: + - in `config.h`: `#define SPI_MISO_PIN NO_PIN` + - in `config.h`: `#define SPI_MOSI_PIN NO_PIN` + - in `mcuconf.h`: `#define SPI_SELECT_MODE SPI_SELECT_MODE_NONE`, in this case the `slavePin` argument passed to `spi_start()` may be `NO_PIN` if the slave select pin is not used. + ## API :id=api ### `void spi_init(void)` :id=api-spi-init diff --git a/docs/squeezing_avr.md b/docs/squeezing_avr.md index b437901bdb..af015b4b18 100644 --- a/docs/squeezing_avr.md +++ b/docs/squeezing_avr.md @@ -168,6 +168,7 @@ For RGB Matrix, these need to be explicitly enabled as well. To disable any that #undef ENABLE_RGB_MATRIX_DUAL_BEACON #undef ENABLE_RGB_MATRIX_RAINBOW_BEACON #undef ENABLE_RGB_MATRIX_RAINBOW_PINWHEELS +#undef ENABLE_RGB_MATRIX_FLOWER_BLOOMING #undef ENABLE_RGB_MATRIX_RAINDROPS #undef ENABLE_RGB_MATRIX_JELLYBEAN_RAINDROPS #undef ENABLE_RGB_MATRIX_HUE_BREATHING diff --git a/docs/uart_driver.md b/docs/uart_driver.md index a44f2c28d9..a88278d543 100644 --- a/docs/uart_driver.md +++ b/docs/uart_driver.md @@ -4,6 +4,18 @@ The UART drivers used in QMK have a set of common functions to allow portability Currently, this driver does not support enabling hardware flow control (the `RTS` and `CTS` pins) if available, but may do so in future. +## Usage :id=usage + +In most cases, the UART driver code is automatically included if you are using a feature or driver which requires it. + +However, if you need to use the driver standalone, add the following to your `rules.mk`: + +```make +UART_DRIVER_REQUIRED = yes +``` + +You can then call the UART API by including `uart.h` in your code. + ## AVR Configuration :id=avr-configuration No special setup is required - just connect the `RX` and `TX` pins of your UART device to the opposite pins on the MCU: diff --git a/docs/unit_testing.md b/docs/unit_testing.md index 47a1055796..60787fdffc 100644 --- a/docs/unit_testing.md +++ b/docs/unit_testing.md @@ -36,7 +36,9 @@ Note how there's several different tests, each mocking out a separate part. Also ## Running the Tests -To run all the tests in the codebase, type `make test:all`. You can also run test matching a substring by typing `make test:matchingsubstring` Note that the tests are always compiled with the native compiler of your platform, so they are also run like any other program on your computer. +To run all the tests in the codebase, type `make test:all`. You can also run test matching a substring by typing `make test:matchingsubstring`. `matchingsubstring` can contain colons to be more specific; `make test:tap_hold_configurations` will run the `tap_hold_configurations` tests for all features while `make test:retro_shift:tap_hold_configurations` will run the `tap_hold_configurations` tests for only the Retro Shift feature. + +Note that the tests are always compiled with the native compiler of your platform, so they are also run like any other program on your computer. ## Debugging the Tests diff --git a/docs/ws2812_driver.md b/docs/ws2812_driver.md index 9b79cfa905..244d39dbe0 100644 --- a/docs/ws2812_driver.md +++ b/docs/ws2812_driver.md @@ -1,189 +1,229 @@ -# WS2812 Driver -This driver powers the [RGB Lighting](feature_rgblight.md) and [RGB Matrix](feature_rgb_matrix.md) features. +# WS2812 Driver :id=ws2812-driver -Currently QMK supports the following addressable LEDs (however, the white LED in RGBW variants is not supported): +This driver provides support for WorldSemi addressable RGB(W) LEDs, and compatible equivalents: - WS2811, WS2812, WS2812B, WS2812C, etc. - SK6812, SK6812MINI, SK6805 + * WS2811, WS2812, WS2812B, WS2812C, etc. + * SK6812, SK6812MINI, SK6805 -These LEDs are called "addressable" because instead of using a wire per color, each LED contains a small microchip that understands a special protocol sent over a single wire. The chip passes on the remaining data to the next LED, allowing them to be chained together. In this way, you can easily control the color of the individual LEDs. +These LEDs are often called "addressable" because instead of using a wire per color (and per LED), each LED contains a small microchip that understands a special protocol sent over a single wire. +The LEDs can be chained together, and the remaining data is passed on to the next. In this way, you can easily control the color of many LEDs using a single GPIO. -## Supported Driver Types +## Usage :id=usage -| | AVR | ARM | -| -------- | ------------------ | ------------------ | -| bit bang | :heavy_check_mark: | :heavy_check_mark: | -| I2C | :heavy_check_mark: | | -| SPI | | :heavy_check_mark: | -| PWM | | :heavy_check_mark: | -| PIO | | :heavy_check_mark: | +In most cases, the WS2812 driver code is automatically included if you are using either the [RGBLight](feature_rgblight.md) or [RGB Matrix](feature_rgb_matrix.md) feature with the `ws2812` driver set, and you would use those APIs instead. -## Driver configuration +However, if you need to use the driver standalone, add the following to your `rules.mk`: -### All drivers +```make +WS2812_DRIVER_REQUIRED = yes +``` + +You can then call the WS2812 API by including `ws2812.h` in your code. + +## Basic Configuration :id=basic-configuration + +Add the following to your `config.h`: + +|Define |Default |Description | +|-------------------|-----------------------|------------------------------------------------------------------------------------------------| +|`WS2812_DI_PIN` |*Not defined* |The GPIO pin connected to the DI pin of the first LED in the chain | +|`WS2812_LED_COUNT` |*Not defined* |Number of LEDs in the WS2812 chain - automatically set when RGBLight or RGB Matrix is configured| +|`WS2812_TIMING` |`1250` |The total length of a bit (TH+TL) in nanoseconds | +|`WS2812_T1H` |`900` |The length of a "1" bit's high phase in nanoseconds | +|`WS2812_T0H` |`350` |The length of a "0" bit's high phase in nanoseconds | +|`WS2812_TRST_US` |`280` |The length of the reset phase in microseconds | +|`WS2812_BYTE_ORDER`|`WS2812_BYTE_ORDER_GRB`|The byte order of the RGB data | + +### Timing Adjustment :id=timing-adjustment -Different versions of the addressable LEDs have differing requirements for the T<sub>RST</sub> period between frames. -The default setting is 280 µs, which should work for most cases, but this can be overridden in your config.h. e.g.: +The WS2812 LED communication protocol works by encoding a "1" bit with a long high pulse (T<sub>1</sub>H), and a "0" bit with a shorter pulse (T<sub>0</sub>H). The total cycle length of a bit is the same. +The "reset" pulse (T<sub>RST</sub>) latches the sent RGB data to all of the LEDs and denotes a completed "frame". + +Some WS2812 variants have slightly different timing parameter requirements, which can be accounted for if necessary using the above `#define`s in your `config.h`. + +### Byte Order :id=byte-order + +Some WS2812 variants may have their color components in a different physical or logical order. For example, the WS2812B-2020 has physically swapped red and green LEDs, which causes the wrong color to be displayed, because the default order of the bytes sent over the wire is defined as GRB. +If you find your LED colors are consistently swapped, you may need to change the byte order by adding the following to your `config.h`: ```c -#define WS2812_TRST_US 80 +#define WS2812_BYTE_ORDER WS2812_BYTE_ORDER_GRB ``` -#### Byte Order +Where the byte order may be one of: + +|Byte Order|Known Devices | +|----------|----------------------------| +|`GRB` |Most WS2812s, SK6812, SK6805| +|`RGB` |WS2812B-2020 | +|`BGR` |TM1812 | -Some variants of the WS2812 may have their color components in a different physical or logical order. For example, the WS2812B-2020 has physically swapped red and green LEDs, which causes the wrong color to be displayed, because the default order of the bytes sent over the wire is defined as GRB. -In this case, you can change the byte order by defining `WS2812_BYTE_ORDER` as one of the following values: +## Driver Configuration :id=driver-configuration -| Byte order | Known devices | -| --------------------------------- | ----------------------------- | -| `WS2812_BYTE_ORDER_GRB` (default) | Most WS2812's, SK6812, SK6805 | -| `WS2812_BYTE_ORDER_RGB` | WS2812B-2020 | -| `WS2812_BYTE_ORDER_BGR` | TM1812 | +Driver selection can be configured in `rules.mk` as `WS2812_DRIVER`, or in `info.json` as `ws2812.driver`. Valid values are `bitbang` (default), `i2c`, `spi`, `pwm`, `vendor`, or `custom`. See below for information on individual drivers. +### Bitbang Driver :id=bitbang-driver -### Bitbang -Default driver, the absence of configuration assumes this driver. To configure it, add this to your rules.mk: +This is the default WS2812 driver. It operates by "bit-banging" ie. directly toggling the GPIO. + +Please note that on AVR devices, due to the tight timing requirements longer chains and/or heavy CPU loads may cause visible lag. Unfortunately this driver is usually the only option for AVR. ```make WS2812_DRIVER = bitbang ``` -!> This driver is not hardware accelerated and may not be performant on heavily loaded systems. +### I2C Driver :id=i2c-driver + +A specialized driver mainly used for PS2AVRGB (Bootmapper Client) boards, which possess an ATtiny85 that handles the WS2812 LEDs. + +```make +WS2812_DRIVER = i2c +``` + +The following `#define`s apply only to the `i2c` driver: -#### Adjusting bit timings +|Define |Default|Description | +|--------------------|-------|---------------------------------| +|`WS2812_I2C_ADDRESS`|`0xB0` |The I2C address of the ATtiny85. | +|`WS2812_I2C_TIMEOUT`|`100` |The I2C timeout, in milliseconds.| -The WS2812 LED communication topology depends on a serialized timed window. Different versions of the addressable LEDs have differing requirements for the timing parameters, for instance, of the SK6812. -You can tune these parameters through the definition of the following macros: +### PIO Driver :id=pio-driver -| Macro | Default | AVR | ARM | -| --------------- | ---------------------------- | ------------------ | ------------------ | -| `WS2812_TIMING` | `1250` | :heavy_check_mark: | :heavy_check_mark: | -| `WS2812_T0H` | `350` | :heavy_check_mark: | :heavy_check_mark: | -| `WS2812_T0L` | `WS2812_TIMING - WS2812_T0H` | | :heavy_check_mark: | -| `WS2812_T1H` | `900` | :heavy_check_mark: | :heavy_check_mark: | -| `WS2812_T1L` | `WS2812_TIMING - WS2812_T1H` | | :heavy_check_mark: | +This driver is RP2040-only, and leverages the onboard PIO (programmable I/O) system and DMA to offload processing from the CPU. -### I2C -Targeting boards where WS2812 support is offloaded to a 2nd MCU. Currently the driver is limited to AVR given the known consumers are ps2avrGB/BMC. To configure it, add this to your rules.mk: +The WS2812 PIO program uses one state machine, six instructions and one DMA interrupt handler callback. Due to the implementation the time resolution for this driver is 50 ns - any value not specified in this interval will be rounded to the next matching interval. ```make -WS2812_DRIVER = i2c +WS2812_DRIVER = vendor ``` -Configure the hardware via your config.h: -```c -#define WS2812_I2C_ADDRESS 0xB0 // default: 0xB0 -#define WS2812_I2C_TIMEOUT 100 // default: 100 +### PWM Driver :id=pwm-driver + +This driver is ARM-only, and leverages the onboard PWM peripheral and DMA to offload processing from the CPU. + +```make +WS2812_DRIVER = pwm ``` -### SPI -Targeting STM32 boards where WS2812 support is offloaded to an SPI hardware device. The advantage is that the use of DMA offloads processing of the WS2812 protocol from the MCU. `WS2812_DI_PIN` for this driver is the configured SPI MOSI pin. Due to the nature of repurposing SPI to drive the LEDs, the other SPI pins, MISO and SCK, **must** remain unused. To configure it, add this to your rules.mk: +### SPI Driver :id=spi-driver + +This driver is ARM-only, and leverages the onboard SPI peripheral and DMA to offload processing from the CPU. The DI pin **must** be connected to the MOSI pin on the MCU, and all other SPI pins **must** be left unused. This is also very dependent on your MCU's SPI peripheral clock speed, and may or may not be possible depending on the MCU selected. ```make WS2812_DRIVER = spi ``` -Configure the hardware via your config.h: -```c -#define WS2812_SPI SPID1 // default: SPID1 -#define WS2812_SPI_MOSI_PAL_MODE 5 // MOSI pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 5 -#define WS2812_SPI_SCK_PIN B3 // Required for F072, may be for others -- SCK pin, see the respective datasheet for the appropriate values for your MCU. default: unspecified -#define WS2812_SPI_SCK_PAL_MODE 5 // SCK pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 5 -``` +## ChibiOS/ARM Configuration :id=arm-configuration -You must also turn on the SPI feature in your halconf.h and mcuconf.h +The following defines apply only to ARM devices: -#### Circular Buffer Mode -Some boards may flicker while in the normal buffer mode. To fix this issue, circular buffer mode may be used to rectify the issue. +|Define |Default |Description | +|------------|------------------------------|---------------------------------------------------------------------------------| +|`WS2812_T1L`|`(WS2812_TIMING - WS2812_T1H)`|The length of a "1" bit's low phase in nanoseconds (bitbang and PIO drivers only)| +|`WS2812_T0L`|`(WS2812_TIMING - WS2812_T0H)`|The length of a "0" bit's low phase in nanoseconds (bitbang and PIO drivers only)| -By default, the circular buffer mode is disabled. +### Push-Pull and Open Drain :id=push-pull-open-drain -To enable this alternative buffer mode, place this into your `config.h` file: -```c -#define WS2812_SPI_USE_CIRCULAR_BUFFER -``` +By default, the GPIO used for data transmission is configured as a *push-pull* output, meaning the pin is effectively always driven either to VCC or to ground. -#### Setting baudrate with divisor -To adjust the baudrate at which the SPI peripheral is configured, users will need to derive the target baudrate from the clock tree provided by STM32CubeMX. +For situations where the logic level voltage is lower than the power supply voltage, however, this can pose an issue. The solution is to configure the pin for *open drain* mode instead, and use a pullup resistor between the DI pin and VCC. In this mode, the MCU can only pull the GPIO *low*, or leave it floating. The pullup resistor is then responsible for pulling the line high, when the MCU is not driving the GPIO. -Only divisors of 2, 4, 8, 16, 32, 64, 128 and 256 are supported by hardware. +To configure the DI pin for open drain configuration, add the following to your `config.h`: -| Define | Default | Description | -| -------------------- | ------- | ----------------------------------- | -| `WS2812_SPI_DIVISOR` | `16` | SPI source clock peripheral divisor | +```c +#define WS2812_EXTERNAL_PULLUP +``` -#### Testing Notes +### SPI Driver :id=arm-spi-driver -While not an exhaustive list, the following table provides the scenarios that have been partially validated: +Depending on the ChibiOS board configuration, you may need to enable SPI at the keyboard level. For STM32, this would look like: -| | SPI1 | SPI2 | SPI3 | -| ---- | ------------------------------------------- | --------------------------------------- | --------------------- | -| f072 | ? | B15 :heavy_check_mark: (needs SCK: B13) | N/A | -| f103 | A7 :heavy_check_mark: | B15 :heavy_check_mark: | N/A | -| f303 | A7 :heavy_check_mark: B5 :heavy_check_mark: | B15 :heavy_check_mark: | B5 :heavy_check_mark: | +`halconf.h`: +```c +#define HAL_USE_SPI TRUE +``` +`mcuconf.h`: +```c +#undef STM32_SPI_USE_SPI1 +#define STM32_SPI_USE_SPI1 TRUE +``` -*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.* +The following `define`s apply only to the `spi` driver: -### PWM +|Define |Default |Description | +|--------------------------------|-------------|-------------------------------------------------------------------------------| +|`WS2812_SPI_DRIVER` |`SPID1` |The SPI driver to use | +|`WS2812_SPI_MOSI_PAL_MODE` |`5` |The MOSI pin alternative function to use | +|`WS2812_SPI_SCK_PIN` |*Not defined*|The SCK pin - required for F072 and possibly others | +|`WS2812_SPI_SCK_PAL_MODE` |`5` |The SCK pin alternative function to use - required for F072 and possibly others| +|`WS2812_SPI_DIVISOR` |`16` |The divisor used to adjust the baudrate | +|`WS2812_SPI_USE_CIRCULAR_BUFFER`|*Not defined*|Enable a circular buffer for improved rendering | -Targeting STM32 boards where WS2812 support is offloaded to an PWM timer and DMA stream. The advantage is that the use of DMA offloads processing of the WS2812 protocol from the MCU. To configure it, add this to your rules.mk: +#### Setting the Baudrate :id=arm-spi-baudrate -```make -WS2812_DRIVER = pwm -``` +To adjust the SPI baudrate, you will need to derive the target baudrate from the clock tree provided by STM32CubeMX, and add the following to your `config.h`: -Configure the hardware via your config.h: ```c -#define WS2812_PWM_DRIVER PWMD2 // default: PWMD2 -#define WS2812_PWM_CHANNEL 2 // default: 2 -#define WS2812_PWM_PAL_MODE 2 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 2 -//#define WS2812_PWM_COMPLEMENTARY_OUTPUT // Define for a complementary timer output (TIMx_CHyN); omit for a normal timer output (TIMx_CHy). -#define WS2812_DMA_STREAM STM32_DMA1_STREAM2 // DMA Stream for TIMx_UP, see the respective reference manual for the appropriate values for your MCU. -#define WS2812_DMA_CHANNEL 2 // DMA Channel for TIMx_UP, see the respective reference manual for the appropriate values for your MCU. -#define WS2812_DMAMUX_ID STM32_DMAMUX1_TIM2_UP // DMAMUX configuration for TIMx_UP -- only required if your MCU has a DMAMUX peripheral, see the respective reference manual for the appropriate values for your MCU. +#define WS2812_SPI_DIVISOR 16 ``` -Note that using a complementary timer output (TIMx_CHyN) is possible only for advanced-control timers (TIM1, TIM8, TIM20 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. +Only divisors of 2, 4, 8, 16, 32, 64, 128 and 256 are supported on STM32 devices. Other MCUs may have similar constraints -- check the reference manual for your respective MCU for specifics. + +#### Circular Buffer :id=arm-spi-circular-buffer -You must also turn on the PWM feature in your halconf.h and mcuconf.h +A circular buffer can be enabled if you experience flickering. -#### Testing Notes +To enable the circular buffer, add the following to your `config.h`: -While not an exhaustive list, the following table provides the scenarios that have been partially validated: +```c +#define WS2812_SPI_USE_CIRCULAR_BUFFER +``` -| | Status | -| --------- | ------------------ | -| f072 | ? | -| f103 | :heavy_check_mark: | -| f303 | :heavy_check_mark: | -| f401/f411 | :heavy_check_mark: | +### PIO Driver :id=arm-pio-driver -*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.* +The following `#define`s apply only to the PIO driver: -### PIO +|Define |Default |Description | +|---------------------|-------------|---------------------------------------| +|`WS2812_PIO_USE_PIO1`|*Not defined*|Use the PIO1 peripheral instead of PIO0| -Targeting Raspberry Pi RP2040 boards only where WS2812 support is offloaded to an dedicated PIO implementation. This offloads processing of the WS2812 protocol from the MCU to a dedicated PIO program using DMA transfers. +### PWM Driver :id=arm-pwm-driver -To configure it, add this to your rules.mk: +Depending on the ChibiOS board configuration, you may need to enable PWM at the keyboard level. For STM32, this would look like: -```make -WS2812_DRIVER = vendor +`halconf.h`: +```c +#define HAL_USE_PWM TRUE ``` - -You may optionally switch the PIO peripheral used with the following define in config.h: +`mcuconf.h`: ```c -#define WS2812_PIO_USE_PIO1 // Force the usage of PIO1 peripheral, by default the WS2812 implementation uses the PIO0 peripheral +#undef STM32_PWM_USE_TIM2 +#define STM32_PWM_USE_TIM2 TRUE ``` -The WS2812 PIO programm uses 1 state machine, 6 instructions and one DMA interrupt handler callback. Due to the implementation the time resolution for this drivers is 50ns, any value not specified in this interval will be rounded to the next matching interval. +The following `#define`s apply only to the `pwm` driver: -### Push Pull and Open Drain Configuration -The default configuration is a push pull on the defined pin. -This can be configured for bitbang, PWM and SPI. +|Define |Default |Description | +|---------------------------------|--------------------|------------------------------------------------------------------------------------------| +|`WS2812_PWM_DRIVER` |`PWMD2` |The PWM driver to use | +|`WS2812_PWM_CHANNEL` |`2` |The PWM channel to use | +|`WS2812_PWM_PAL_MODE` |`2` |The pin alternative function to use | +|`WS2812_DMA_STREAM` |`STM32_DMA1_STREAM2`|The DMA Stream for `TIMx_UP` | +|`WS2812_DMA_CHANNEL` |`2` |The DMA Channel for `TIMx_UP` | +|`WS2812_DMAMUX_ID` |*Not defined* |The DMAMUX configuration for `TIMx_UP` - only required if your MCU has a DMAMUX peripheral| +|`WS2812_PWM_COMPLEMENTARY_OUTPUT`|*Not defined* |Whether the PWM output is complementary (`TIMx_CHyN`) | -Note: This only applies to STM32 boards. +?> 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. - To configure the `WS2812_DI_PIN` to open drain configuration add this to your config.h file: -```c -#define WS2812_EXTERNAL_PULLUP -``` +## API :id=api + +### `void ws2812_setleds(rgb_led_t *ledarray, uint16_t number_of_leds)` :id=api-ws2812-setleds + +Send RGB data to the WS2812 LED chain. + +#### Arguments :id=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. diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md index 0fc92e33d3..a076f1a8c6 100644 --- a/docs/zh-cn/_summary.md +++ b/docs/zh-cn/_summary.md @@ -121,7 +121,6 @@ * [分体式键盘](zh-cn/feature_split_keyboard.md) * [速记](zh-cn/feature_stenography.md) * [热敏打印机](zh-cn/feature_thermal_printer.md) - * [Velocikey](zh-cn/feature_velocikey.md) * QMK开发 * [PR Checklist](zh-cn/pr_checklist.md) |