diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/breaking_changes.md | 4 | ||||
| -rw-r--r-- | docs/chibios_upgrade_instructions.md | 56 | ||||
| -rw-r--r-- | docs/config_options.md | 3 | ||||
| -rw-r--r-- | docs/custom_quantum_functions.md | 8 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 68 | ||||
| -rw-r--r-- | docs/feature_st7565.md | 270 |
7 files changed, 410 insertions, 0 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 9798ef5127..4141e01e77 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -93,6 +93,7 @@ * Hardware Features * Displays * [HD44780 LCD Controller](feature_hd44780.md) + * [ST7565 LCD Driver](feature_st7565.md) * [OLED Driver](feature_oled_driver.md) * Lighting * [Backlight](feature_backlight.md) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 3e85a70761..2ad8b5a14d 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -96,3 +96,7 @@ This happens immediately after the previous `develop` branch is merged. * [ ] Create a PR for `develop` * [ ] Make sure travis comes back clean * [ ] Merge `develop` PR + +## Post-merge operations + +* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions.md)
\ No newline at end of file diff --git a/docs/chibios_upgrade_instructions.md b/docs/chibios_upgrade_instructions.md new file mode 100644 index 0000000000..40c2faafcf --- /dev/null +++ b/docs/chibios_upgrade_instructions.md @@ -0,0 +1,56 @@ +# ChibiOS Upgrade Procedure + +ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a branch tied to the ChibiOS version in use and should not be mixed with different versions. + +## Getting ChibiOS + +* `svn` Initialisation: + * Only needed to be done once + * You might need to separately install `git-svn` package in your OS's package manager + * `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/` + * `git remote add qmk git@github.com:qmk/ChibiOS.git` +* Updating: + * `git svn fetch` + * First time around this will take several hours + * Subsequent updates will be incremental only +* Tagging example (work out which version first!): + * `git tag -a ver20.3.3 -m ver20.3.3 svn/tags/ver20.3.3` + * `git push qmk ver20.3.3` + * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN svn/tags/ver20.3.3` + * `git push qmk breaking_YYYY_qN` + +## Getting ChibiOS-Contrib + +* `git` Initialisation: + * `git clone git@github.com:qmk/ChibiOS-Contrib` + * `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib` + * `git checkout -b chibios-20.3.x upstream/chibios-20.3.x` +* Updating: + * `git fetch --all --tags --prune` + * `git checkout chibios-20.3.x` + * `git pull --ff-only` + * `git push origin chibios-20.3.x` + * `git tag -a breaking_YYYY_qN -m breaking_YYYY_qN chibios-20.3.x` + * `git push origin breaking_YYYY_qN` + +## Updating submodules + +* Update the submodules + * `cd $QMK_FIRMWARE` + * `git checkout develop` + * `git pull --ff-only` + * `git checkout -b chibios-version-bump` + * `cd lib/chibios` + * `git fetch --all --tags --prune` + * `git checkout breaking_YYYY_qN` + * `cd ../chibios-contrib` + * `git fetch --all --tags --prune` + * `git checkout breaking_YYYY_qN` +* Build everything + * `cd $QMK_FIRMWARE` + * `qmk multibuild -j4` + * Make sure there are no errors +* Push to the repo + * `git commit -am 'Update ChibiOS to XXXXXXXXX'` + * `git push --set-upstream origin chibios-version-bump` +* Make a PR to qmk_firmware with the new branch
\ No newline at end of file diff --git a/docs/config_options.md b/docs/config_options.md index d0f0b316e0..26fe8cea55 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -51,8 +51,10 @@ This is a C header file that is one of the first things included, and will persi * the number of columns in your keyboard's matrix * `#define MATRIX_ROW_PINS { D0, D5, B5, B6 }` * pins of the rows, from top to bottom + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }` * pins of the columns, from left to right + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define MATRIX_IO_DELAY 30` * the delay in microseconds when between changing matrix pin state and reading values * `#define UNUSED_PINS { D1, D2, D3, B1, B2, B3 }` @@ -280,6 +282,7 @@ There are a few different ways to set handedness for split keyboards (listed in * `#define MATRIX_ROW_PINS_RIGHT { <row pins> }` * `#define MATRIX_COL_PINS_RIGHT { <col pins> }` * If you want to specify a different pinout for the right half than the left half, you can define `MATRIX_ROW_PINS_RIGHT`/`MATRIX_COL_PINS_RIGHT`. Currently, the size of `MATRIX_ROW_PINS` must be the same as `MATRIX_ROW_PINS_RIGHT` and likewise for the definition of columns. + * may be omitted by the keyboard designer if matrix reads are handled in an alternate manner. See [low-level matrix overrides](custom_quantum_functions.md?id=low-level-matrix-overrides) for more information. * `#define DIRECT_PINS_RIGHT { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }` * If you want to specify a different direct pinout for the right half than the left half, you can define `DIRECT_PINS_RIGHT`. Currently, the size of `DIRECT_PINS` must be the same as `DIRECT_PINS_RIGHT`. diff --git a/docs/custom_quantum_functions.md b/docs/custom_quantum_functions.md index 694b421e79..30c637bb49 100644 --- a/docs/custom_quantum_functions.md +++ b/docs/custom_quantum_functions.md @@ -144,6 +144,14 @@ This is useful for setting up stuff that you may need elsewhere, but isn't hardw * Keyboard/Revision: `void matrix_init_kb(void)` * Keymap: `void matrix_init_user(void)` +### Low-level Matrix Overrides Function Documentation :id=low-level-matrix-overrides + +* GPIO pin initialisation: `void matrix_init_pins(void)` + * This needs to perform the low-level initialisation of all row and column pins. By default this will initialise the input/output state of each of the GPIO pins listed in `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no initialisation of pin state will occur within QMK itself, instead deferring to the keyboard's override. +* `COL2ROW`-based row reads: `void matrix_read_rows_on_col(matrix_row_t current_matrix[], uint8_t current_col)` +* `ROW2COL`-based column reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` +* `DIRECT_PINS`-based reads: `void matrix_read_cols_on_row(matrix_row_t current_matrix[], uint8_t current_row)` + * These three functions need to perform the low-level retrieval of matrix state of relevant input pins, based on the matrix type. Only one of the functions should be implemented, if needed. By default this will iterate through `MATRIX_ROW_PINS` and `MATRIX_COL_PINS`, configuring the inputs and outputs based on whether or not the keyboard is set up for `ROW2COL`, `COL2ROW`, or `DIRECT_PINS`. Should the keyboard designer override this function, no manipulation of matrix GPIO pin state will occur within QMK itself, instead deferring to the keyboard's override. ## Keyboard Post Initialization code diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 169443fb85..afd72fecff 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -228,6 +228,74 @@ 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`: + +```makefile +RGB_MATRIX_ENABLE = yes +RGB_MATRIX_DRIVER = AW20216 +``` + +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`: + +| 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 | | +| `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 | | +| `DRIVER_LED_TOTAL` | (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 | + +Here is an example using 2 drivers. + +```c +#define DRIVER_1_CS B13 +#define DRIVER_2_CS B14 +// Hardware enable lines may be connected to the same pin +#define DRIVER_1_EN C13 +#define DRIVER_2_EN C13 + +#define DRIVER_COUNT 2 +#define DRIVER_1_LED_TOTAL 66 +#define DRIVER_2_LED_TOTAL 32 +#define DRIVER_LED_TOTAL (DRIVER_1_LED_TOTAL + DRIVER_2_LED_TOTAL) +``` + +!> Note the parentheses, this is so when `DRIVER_LED_TOTAL` 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`. + +Define these arrays listing all the LEDs in your `<keyboard>.c`: + +```c +const aw_led g_aw_leds[DRIVER_LED_TOTAL] = { +/* Each AW20216 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 + * driver pin locations. + * driver + * | R location + * | | G location + * | | | B location + * | | | | */ + { 0, CS1_SW1, CS2_SW1, CS3_SW1 }, + { 0, CS4_SW1, CS5_SW1, CS6_SW1 }, + { 0, CS7_SW1, CS8_SW1, CS9_SW1 }, + { 0, CS10_SW1, CS11_SW1, CS12_SW1 }, + { 0, CS13_SW1, CS14_SW1, CS15_SW1 }, + ... + { 1, CS1_SW1, CS2_SW1, CS3_SW1 }, + { 1, CS13_SW1, CS14_SW1, CS15_SW1 }, + { 1, CS16_SW1, CS17_SW1, CS18_SW1 }, + { 1, CS4_SW2, CS5_SW2, CS6_SW2 }, + ... +}; +``` + +--- From this point forward the configuration is the same for all the drivers. The `led_config_t` struct provides a key electrical matrix to led index lookup table, what the physical position of each LED is on the board, and what type of key or usage the LED if the LED represents. Here is a brief example: diff --git a/docs/feature_st7565.md b/docs/feature_st7565.md new file mode 100644 index 0000000000..7db0f9ac4a --- /dev/null +++ b/docs/feature_st7565.md @@ -0,0 +1,270 @@ +# ST7565 LCD Driver + +## Supported Hardware + +LCD modules using ST7565 driver IC, communicating over SPI. + +|Module |IC |Size |Notes | +|------------------------------|-------|------|----------------------------------------------------------| +|Newhaven Display NHD-C12832A1Z|ST7565R|128x32|Used by Ergodox Infinity; primary consumer of this feature| +|Zolentech ZLE12864B |ST7565P|128x64|Requires contrast adjustment | + +## Usage + +To enable the feature, there are three steps. First, when compiling your keyboard, you'll need to add the following to your `rules.mk`: + +```make +ST7565_ENABLE = yes +``` + +Then in your `keymap.c` file, implement the ST7565 task call. This example assumes your keymap has three layers named `_QWERTY`, `_FN` and `_ADJ`: + +```c +#ifdef ST7565_ENABLE +void st7565_task_user(void) { + // Host Keyboard Layer Status + st7565_write_P(PSTR("Layer: "), false); + + switch (get_highest_layer(layer_state)) { + case _QWERTY: + st7565_write_P(PSTR("Default\n"), false); + break; + case _FN: + st7565_write_P(PSTR("FN\n"), false); + break; + case _ADJ: + st7565_write_P(PSTR("ADJ\n"), false); + break; + default: + // Or use the write_ln shortcut over adding '\n' to the end of your string + st7565_write_ln_P(PSTR("Undefined"), false); + } + + // Host Keyboard LED Status + led_t led_state = host_keyboard_led_state(); + st7565_write_P(led_state.num_lock ? PSTR("NUM ") : PSTR(" "), false); + st7565_write_P(led_state.caps_lock ? PSTR("CAP ") : PSTR(" "), false); + st7565_write_P(led_state.scroll_lock ? PSTR("SCR ") : PSTR(" "), false); +} +#endif +``` + +## Logo Example + +In the default font, certain ranges of characters are reserved for a QMK logo. To render this logo to the screen, use the following code example: + +```c +static void render_logo(void) { + static const char PROGMEM qmk_logo[] = { + 0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x8B, 0x8C, 0x8D, 0x8E, 0x8F, 0x90, 0x91, 0x92, 0x93, 0x94, + 0xA0, 0xA1, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xAB, 0xAC, 0xAD, 0xAE, 0xAF, 0xB0, 0xB1, 0xB2, 0xB3, 0xB4, + 0xC0, 0xC1, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xCB, 0xCC, 0xCD, 0xCE, 0xCF, 0xD0, 0xD1, 0xD2, 0xD3, 0xD4, 0x00 + }; + + st7565_write_P(qmk_logo, false); +} +``` + +## Buffer Read Example +For some purposes, you may need to read the current state of the display buffer. The `st7565_read_raw` function can be used to safely read bytes from the buffer. + +In this example, calling `fade_display` in the `st7565_task_user` function will slowly fade away whatever is on the screen by turning random pixels off over time. +```c +//Setup some mask which can be or'd with bytes to turn off pixels +const uint8_t single_bit_masks[8] = {127, 191, 223, 239, 247, 251, 253, 254}; + +static void fade_display(void) { + //Define the reader structure + display_buffer_reader_t reader; + uint8_t buff_char; + if (random() % 30 == 0) { + srand(timer_read()); + // Fetch a pointer for the buffer byte at index 0. The return structure + // will have the pointer and the number of bytes remaining from this + // index position if we want to perform a sequential read by + // incrementing the buffer pointer + reader = st7565_read_raw(0); + //Loop over the remaining buffer and erase pixels as we go + for (uint16_t i = 0; i < reader.remaining_element_count; i++) { + //Get the actual byte in the buffer by dereferencing the pointer + buff_char = *reader.current_element; + if (buff_char != 0) { + st7565_write_raw_byte(buff_char & single_bit_masks[rand() % 8], i); + } + //increment the pointer to fetch a new byte during the next loop + reader.current_element++; + } + } +} +``` + +## Other Examples + +In split keyboards, it is very common to have two displays that each render different content and are oriented or flipped differently. You can do this by switching which content to render by using the return value from `is_keyboard_master()` or `is_keyboard_left()` found in `split_util.h`, e.g: + +```c +#ifdef ST7565_ENABLE +display_rotation_t st7565_init_user(display_rotation_t rotation) { + if (!is_keyboard_master()) { + return DISPLAY_ROTATION_180; // flips the display 180 degrees if offhand + } + + return rotation; +} + +void st7565_task_user(void) { + if (is_keyboard_master()) { + render_status(); // Renders the current keyboard state (layer, lock, caps, scroll, etc) + } else { + render_logo(); // Renders a static logo + } +} +#endif +``` + +## Basic Configuration + +|Define |Default |Description | +|------------------------|--------------|-----------------------------------------------------------------------------------------------------| +|`ST7565_A0_PIN` |*Not defined* |(Required) The GPIO connected to the display's A0 (data/command) pin | +|`ST7565_RST_PIN` |*Not defined* |(Required) The GPIO connected to the display's reset pin | +|`ST7565_SS_PIN` |*Not defined* |(Required) The GPIO connected to the display's slave select pin | +|`ST7565_SPI_CLK_DIVISOR`|`4` |The SPI clock divisor to use | +|`ST7565_FONT_H` |`"glcdfont.c"`|The font code file to use for custom fonts | +|`ST7565_FONT_START` |`0` |The starting character index for custom fonts | +|`ST7565_FONT_END` |`223` |The ending character index for custom fonts | +|`ST7565_FONT_WIDTH` |`6` |The font width | +|`ST7565_FONT_HEIGHT` |`8` |The font height (untested) | +|`ST7565_TIMEOUT` |`60000` |Turns off the screen after 60000ms of keyboard inactivity. Helps reduce burn-in. Set to 0 to disable.| +|`ST7565_COLUMN_OFFSET` |`0` |Shift output to the right this many pixels. | +|`ST7565_CONTRAST` |`32` |The default contrast level of the display, from 0 to 255. | +|`ST7565_UPDATE_INTERVAL`|`0` |Set the time interval for updating the display in ms. This will improve the matrix scan rate. | + +## Custom sized displays + +The default display size for this feature is 128x32 and all necessary defines are precalculated with that in mind. + +|Define |Default |Description | +|-----------------------|----------|-----------------------------------------------------------------------------------------------------------| +|`ST7565_DISPLAY_WIDTH` |`128` |The width of the display. | +|`ST7565_DISPLAY_HEIGHT`|`32` |The height of the display. | +|`ST7565_MATRIX_SIZE` |`512` |The local buffer size to allocate.<br>`(ST7565_DISPLAY_HEIGHT / 8 * ST7565_DISPLAY_WIDTH)`. | +|`ST7565_BLOCK_TYPE` |`uint16_t`|The unsigned integer type to use for dirty rendering. | +|`ST7565_BLOCK_COUNT` |`16` |The number of blocks the display is divided into for dirty rendering.<br>`(sizeof(ST7565_BLOCK_TYPE) * 8)`.| +|`ST7565_BLOCK_SIZE` |`32` |The size of each block for dirty rendering<br>`(ST7565_MATRIX_SIZE / ST7565_BLOCK_COUNT)`. | + +## API + +```c +// Rotation enum values are flags +typedef enum { + DISPLAY_ROTATION_0, + DISPLAY_ROTATION_180 +} display_rotation_t; + +// Initialize the display, rotating the rendered output based on the define passed in. +// Returns true if the was initialized successfully +bool st7565_init(display_rotation_t rotation); + +// Called at the start of st7565_init, weak function overridable by the user +// rotation - the value passed into st7565_init +// Return new display_rotation_t if you want to override default rotation +display_rotation_t st7565_init_user(display_rotation_t rotation); + +// Clears the display buffer, resets cursor position to 0, and sets the buffer to dirty for rendering +void st7565_clear(void); + +// Renders the dirty chunks of the buffer to display +void st7565_render(void); + +// Moves cursor to character position indicated by column and line, wraps if out of bounds +// Max column denoted by 'st7565_max_chars()' and max lines by 'st7565_max_lines()' functions +void st7565_set_cursor(uint8_t col, uint8_t line); + +// Advances the cursor to the next page, writing ' ' if true +// Wraps to the begining when out of bounds +void st7565_advance_page(bool clearPageRemainder); + +// Moves the cursor forward 1 character length +// Advance page if there is not enough room for the next character +// Wraps to the begining when out of bounds +void st7565_advance_char(void); + +// Writes a single character to the buffer at current cursor position +// Advances the cursor while writing, inverts the pixels if true +// Main handler that writes character data to the display buffer +void st7565_write_char(const char data, bool invert); + +// Writes a string to the buffer at current cursor position +// Advances the cursor while writing, inverts the pixels if true +void st7565_write(const char *data, bool invert); + +// Writes a string to the buffer at current cursor position +// Advances the cursor while writing, inverts the pixels if true +// Advances the cursor to the next page, wiring ' ' to the remainder of the current page +void st7565_write_ln(const char *data, bool invert); + +// Pans the buffer to the right (or left by passing true) by moving contents of the buffer +// Useful for moving the screen in preparation for new drawing +void st7565_pan(bool left); + +// Returns a pointer to the requested start index in the buffer plus remaining +// buffer length as struct +display_buffer_reader_t st7565_read_raw(uint16_t start_index); + +// Writes a string to the buffer at current cursor position +void st7565_write_raw(const char *data, uint16_t size); + +// Writes a single byte into the buffer at the specified index +void st7565_write_raw_byte(const char data, uint16_t index); + +// Sets a specific pixel on or off +// Coordinates start at top-left and go right and down for positive x and y +void st7565_write_pixel(uint8_t x, uint8_t y, bool on); + +// 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 st7565_write(const char *data, bool invert);' on ARM +void st7565_write_P(const char *data, bool invert); + +// Writes a PROGMEM string to the buffer at current cursor position +// Advances the cursor while writing, inverts the pixels if true +// Advances the cursor to the next page, wiring ' ' to the remainder of the current page +// Remapped to call 'void st7565_write_ln(const char *data, bool invert);' on ARM +void st7565_write_ln_P(const char *data, bool invert); + +// Writes a PROGMEM string to the buffer at current cursor position +void st7565_write_raw_P(const char *data, uint16_t size); + +// Can be used to manually turn on the screen if it is off +// Returns true if the screen was on or turns on +bool st7565_on(void); + +// Called when st7565_on() turns on the screen, weak function overridable by the user +// Not called if the screen is already on +void st7565_on_user(void); + +// Can be used to manually turn off the screen if it is on +// Returns true if the screen was off or turns off +bool st7565_off(void); + +// Called when st7565_off() turns off the screen, weak function overridable by the user +// Not called if the screen is already off +void st7565_off_user(void); + +// Returns true if the screen is currently on, false if it is +// not +bool st7565_is_on(void); + +// Basically it's st7565_render, but with timeout management and st7565_task_user calling! +void st7565_task(void); + +// Called at the start of st7565_task, weak function overridable by the user +void st7565_task_user(void); + +// Returns the maximum number of characters that will fit on a line +uint8_t st7565_max_chars(void); + +// Returns the maximum number of lines that will fit on the display +uint8_t st7565_max_lines(void); +``` |