diff --git a/docs/README.md b/docs/README.md index 127cec4f625..1da3925a49e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,16 +8,16 @@ QMK (*Quantum Mechanical Keyboard*) is an open source community centered around
-:::caution +:::tip Basic -**Basic** [QMK Configurator](newbs_building_firmware_configurator.md)
+[QMK Configurator](newbs_building_firmware_configurator.md)
User friendly graphical interfaces, no programming knowledge required. ::: -:::caution +:::caution Advanced -**Advanced** [Use The Source](newbs.md)
+[Use The Source](newbs.md)
More powerful, but harder to use. ::: diff --git a/docs/newbs_building_firmware_workflow.md b/docs/newbs_building_firmware_workflow.md index 5f9779117cf..0a3f38639db 100644 --- a/docs/newbs_building_firmware_workflow.md +++ b/docs/newbs_building_firmware_workflow.md @@ -1,3 +1,6 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Building QMK with GitHub Userspace This is an intermediate QMK tutorial to setup an out-of-tree build environment with a personal GitHub repository. It avoids using a fork of the QMK firmware to store and build your keymap within its source tree. Keymap files will instead be stored in your own personal GitHub repository, in [Userspace](https://docs.qmk.fm/#/feature_userspace) format, and built with an action workflow. Unlike the [default tutorial](https://docs.qmk.fm/#/newbs), this guide requires some familiarity with using Git. @@ -34,17 +37,19 @@ If you are familiar with using [github.dev](https://docs.github.com/en/codespace A working Git client is required for your local operating system to commit and push changes to GitHub. - + -### ** Windows ** + QMK maintains a bundle of MSYS2, the CLI and all necessary dependencies including Git. Install [QMK MSYS](https://msys.qmk.fm/) with the latest release [here](https://github.com/qmk/qmk_distro_msys/releases/latest). Git will be part of the bundle. -### ** macOS ** + + Install Homebrew following the instructions on https://brew.sh. Git will be part of the bundle. -### ** Linux/WSL ** + + It's very likely that you already have Git installed. If not, use one of the following commands: @@ -56,7 +61,8 @@ It's very likely that you already have Git installed. If not, use one of the fol * Sabayon: `sudo equo install dev-vcs/git` * Gentoo: `sudo emerge dev-vcs/git` - + + ### 2. GitHub authentication diff --git a/docs/newbs_flashing.md b/docs/newbs_flashing.md index 99c2e14d79d..644666d0bb2 100644 --- a/docs/newbs_flashing.md +++ b/docs/newbs_flashing.md @@ -1,3 +1,6 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Flashing Your Keyboard Now that you've built a custom firmware file you'll want to flash your keyboard. @@ -37,21 +40,25 @@ Begin by opening the QMK Toolbox application. You'll want to locate the firmware If you are on Windows or macOS, there are commands you can use to easily open the current folder in Explorer or Finder. - + -#### ** Windows ** + ``` start . ``` -#### ** macOS ** + + + ``` open . ``` - + + + The firmware file always follows this naming format: diff --git a/docs/quantum_painter.md b/docs/quantum_painter.md index f411890a34d..b22535700a7 100644 --- a/docs/quantum_painter.md +++ b/docs/quantum_painter.md @@ -1,3 +1,6 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Quantum Painter {#quantum-painter} Quantum Painter is the standardised API for graphical displays. It currently includes support for basic drawing primitives, as well as custom images, animations, and fonts. @@ -51,9 +54,7 @@ Drivers have their own set of configurable options, and are described in their r ## Quantum Painter CLI Commands {#quantum-painter-cli} - - -### ** `qmk painter-convert-graphics` ** +### `qmk painter-convert-graphics` This command converts images to a format usable by QMK, i.e. the QGF File Format. @@ -104,7 +105,7 @@ Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/my_image.qgf.h... Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/my_image.qgf.c... ``` -### ** `qmk painter-make-font-image` ** +### `qmk painter-make-font-image` This command converts a TTF font to an intermediate format for editing, before converting to the QFF File Format. @@ -137,7 +138,7 @@ The `UNICODE_GLYPHS` argument allows for specifying extra unicode glyphs to gene $ qmk painter-make-font-image --font NotoSans-ExtraCondensedBold.ttf --size 11 -o noto11.png --unicode-glyphs "ĄȽɂɻɣɈʣ" ``` -### ** `qmk painter-convert-font-image` ** +### `qmk painter-convert-font-image` This command converts an intermediate font image to the QFF File Format. @@ -182,13 +183,10 @@ Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/noto11.qff.h... Writing /home/qmk/qmk_firmware/keyboards/my_keeb/generated/noto11.qff.c... ``` - - ## Quantum Painter Display Drivers {#quantum-painter-drivers} - - -### ** Common: Standard TFT (SPI + D/C + RST) ** + + Most TFT display panels use a 5-pin interface -- SPI SCK, SPI MOSI, SPI CS, D/C, and RST pins. @@ -196,9 +194,8 @@ For these displays, QMK's `spi_master` must already be correctly configured for The pin assignments for SPI CS, D/C, and RST are specified during device construction. - - -#### ** GC9A01 ** + + Enabling support for the GC9A01 in Quantum Painter is done by adding the following to `rules.mk`: @@ -224,7 +221,8 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with GC9A01 -#### ** ILI9163 ** + + Enabling support for the ILI9163 in Quantum Painter is done by adding the following to `rules.mk`: @@ -250,7 +248,8 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with ILI9163 -#### ** ILI9341 ** + + Enabling support for the ILI9341 in Quantum Painter is done by adding the following to `rules.mk`: @@ -276,7 +275,8 @@ The maximum number of displays can be configured by changing the following in yo Native color format rgb565 is compatible with ILI9341 -#### ** ILI9488 ** + + Enabling support for the ILI9488 in Quantum Painter is done by adding the following to `rules.mk`: @@ -302,7 +302,8 @@ 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`: @@ -328,7 +329,8 @@ The maximum number of displays can be configured by changing the following in yo 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`: @@ -360,7 +362,8 @@ Some ST7735 devices are known to have different drawing offsets -- despite being ::: -#### ** ST7789 ** + + Enabling support for the ST7789 in Quantum Painter is done by adding the following to `rules.mk`: @@ -392,9 +395,11 @@ Some ST7789 devices are known to have different drawing offsets -- despite being ::: - + + -### ** Common: Surfaces ** + + 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. @@ -404,9 +409,11 @@ These generally require significant amounts of RAM, so at large sizes and/or hig ::: - + + -#### ** RGB565 Surface ** + + Enabling support for RGB565 surfaces in Quantum Painter is done by adding the following to `rules.mk`: @@ -457,9 +464,11 @@ Calling `qp_flush()` on the surface resets its dirty region. Copying the surface ::: - + + - + + ## Quantum Painter Drawing API {#quantum-painter-api} @@ -470,8 +479,6 @@ To use any of the APIs, you need to include `qp.h`: #include ``` - - ### ** General Notes ** The coordinate system used in Quantum Painter generally accepts `left`, `top`, `right`, and `bottom` instead of x/y/width/height, and each coordinate is inclusive of where pixels should be drawn. This is required as some datatypes used by display panels have a maximum value of `255` -- for any value or geometry extent that matches `256`, this would be represented as a `0`, instead. @@ -496,9 +503,8 @@ Colors used in Quantum Painter are not subject to the RGB lighting CIE curve, if ### ** Device Control ** - - -#### ** Display Initialisation ** + + ```c bool qp_init(painter_device_t device, painter_rotation_t rotation); @@ -513,8 +519,8 @@ void keyboard_post_init_kb(void) { qp_init(display, QP_ROTATION_0); // Initialise the display } ``` - -#### ** Display Power ** + + ```c bool qp_power(painter_device_t device, bool power_on); @@ -548,8 +554,8 @@ void suspend_wakeup_init_user(void) { last_backlight = 255; } ``` - -#### ** Display Clear ** + + ```c bool qp_clear(painter_device_t device); @@ -557,7 +563,8 @@ bool qp_clear(painter_device_t device); The `qp_clear` function clears the display's screen. -#### ** Display Flush ** + + ```c bool qp_flush(painter_device_t device); @@ -583,13 +590,13 @@ void housekeeping_task_user(void) { } ``` - + + ### ** Drawing Primitives ** - - -#### ** Set Pixel ** + + ```c bool qp_setpixel(painter_device_t device, uint16_t x, uint16_t y, uint8_t hue, uint8_t sat, uint8_t val); @@ -616,8 +623,8 @@ void housekeeping_task_user(void) { } } ``` - -#### ** Draw Line ** + + ```c bool qp_line(painter_device_t device, uint16_t x0, uint16_t y0, uint16_t x1, uint16_t y1, uint8_t hue, uint8_t sat, uint8_t val); @@ -638,8 +645,8 @@ void housekeeping_task_user(void) { } } ``` - -#### ** Draw Rect ** + + ```c bool qp_rect(painter_device_t device, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom, uint8_t hue, uint8_t sat, uint8_t val, bool filled); @@ -660,8 +667,8 @@ void housekeeping_task_user(void) { } } ``` - -#### ** Draw Circle ** + + ```c bool qp_circle(painter_device_t device, uint16_t x, uint16_t y, uint16_t radius, uint8_t hue, uint8_t sat, uint8_t val, bool filled); @@ -682,8 +689,8 @@ void housekeeping_task_user(void) { } } ``` - -#### ** Draw Ellipse ** + + ```c bool qp_ellipse(painter_device_t device, uint16_t x, uint16_t y, uint16_t sizex, uint16_t sizey, uint8_t hue, uint8_t sat, uint8_t val, bool filled); @@ -705,7 +712,8 @@ void housekeeping_task_user(void) { } ``` - + + ### ** Image Functions ** @@ -720,9 +728,8 @@ SRC += my_image.qgf.c #include "my_image.qgf.h" ``` - - -#### ** Load Image ** + + ```c painter_image_handle_t qp_load_image_mem(const void *buffer); @@ -747,16 +754,16 @@ Image information is available through accessing the handle: | Width | `image->width` | | Height | `image->height` | | Frame Count | `image->frame_count` | - -#### ** Unload Image ** + + ```c bool qp_close_image(painter_image_handle_t image); ``` The `qp_close_image` function releases resources related to the loading of the supplied image. - -#### ** Draw image ** + + ```c bool qp_drawimage(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image); @@ -775,8 +782,8 @@ void keyboard_post_init_kb(void) { } } ``` - -#### ** Animate Image ** + + ```c deferred_token qp_animate(painter_device_t device, uint16_t x, uint16_t y, painter_image_handle_t image); @@ -800,8 +807,8 @@ void keyboard_post_init_kb(void) { } } ``` - -#### ** Stop Animation ** + + ```c void qp_stop_animation(deferred_token anim_token); @@ -816,7 +823,8 @@ void housekeeping_task_user(void) { } ``` - + + ### ** Font Functions ** @@ -831,9 +839,8 @@ SRC += noto11.qff.c #include "noto11.qff.h" ``` - - -#### ** Load Font ** + + ```c painter_font_handle_t qp_load_font_mem(const void *buffer); @@ -856,24 +863,24 @@ Font information is available through accessing the handle: | Property | Accessor | |-------------|----------------------| | Line Height | `image->line_height` | - -#### ** Unload Font ** + + ```c bool qp_close_font(painter_font_handle_t font); ``` The `qp_close_font` function releases resources related to the loading of the supplied font. - -#### ** Measure Text ** + + ```c int16_t qp_textwidth(painter_font_handle_t font, const char *str); ``` The `qp_textwidth` function allows measurement of how many pixels wide the supplied string would result in, for the given font. - -#### ** Draw Text ** + + ```c int16_t qp_drawtext(painter_device_t device, uint16_t x, uint16_t y, painter_font_handle_t font, const char *str); @@ -895,37 +902,37 @@ void keyboard_post_init_kb(void) { } ``` - + + ### ** Advanced Functions ** - - -#### ** Get Geometry ** + + ```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. - -#### ** Set Viewport Offsets ** + + ```c void qp_set_viewport_offsets(painter_device_t device, uint16_t offset_x, uint16_t offset_y); ``` The `qp_set_viewport_offsets` function can be used to offset all subsequent drawing operations. For example, if a display controller is internally 240x320, but the display panel is 240x240 and has a Y offset of 80 pixels, you could invoke `qp_set_viewport_offsets(display, 0, 80);` and the drawing positioning would be corrected. - -#### ** Set Viewport ** + + ```c bool qp_viewport(painter_device_t device, uint16_t left, uint16_t top, uint16_t right, uint16_t bottom); ``` The `qp_viewport` function controls where raw pixel data is written to. - -#### ** Stream Pixel Data ** + + ```c bool qp_pixdata(painter_device_t device, const void *pixel_data, uint32_t native_pixel_count); @@ -939,6 +946,5 @@ Under normal circumstances, users will not need to manually call either `qp_view ::: - - - + + diff --git a/docs/serial_driver.md b/docs/serial_driver.md index 71239957ecf..62e40d4523b 100644 --- a/docs/serial_driver.md +++ b/docs/serial_driver.md @@ -1,4 +1,4 @@ -# 'serial' Driver +# Serial Driver The serial driver powers the [Split Keyboard](feature_split_keyboard.md) feature. Several implementations are available, depending on the platform of your split keyboard. Note that none of the drivers support split keyboards with more than two halves. diff --git a/docs/sidebars.js b/docs/sidebars.js index b1fa01821a5..e95ab1c42b7 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -98,9 +98,7 @@ const sidebars = { ], }, { - type: "category", - label: "Using QMK", - items: [ + "Using QMK": [ { Guides: [ "custom_quantum_functions", @@ -220,6 +218,105 @@ const sidebars = { }, ], }, + { + "Developing QMK": [ + "pr_checklist", + { + type: "category", + label: "Breaking Changes", + link: { + type: "doc", + id: "breaking_changes", + }, + items: [ + "breaking_changes_instructions", + "ChangeLog/20230226", + "breaking_changes_history", + ], + }, + { + "C Development": [ + "arm_debugging", + "coding_conventions_c", + "compatible_microcontrollers", + "hardware_drivers", + "adc_driver", + "audio_driver", + "i2c_driver", + "spi_driver", + "ws2812_driver", + "eeprom_driver", + "flash_driver", + "serial_driver", + "uart_driver", + "gpio_control", + "hardware_keyboard_guidelines", + ], + }, + { + "Python Development": [ + "coding_conventions_python", + "cli_development", + ], + }, + { + "Configurator Development": [ + { + "QMK API": [ + "api_development_environment", + "api_development_overview", + ], + }, + ], + }, + { + "Hardware Platform Development": [ + { + "Arm/ChibiOS": [ + "platformdev_selecting_arm_mcu", + "platformdev_chibios_earlyinit", + "platformdev_rp2040", + "platformdev_proton_c", + "platformdev_blackpill_f4x1", + ], + }, + ], + }, + { + "QMK Reference": [ + "contributing", + "translating", + "config_options", + "data_driven_config", + "getting_started_make_guide", + "documentation_best_practices", + "documentation_templates", + "feature_layouts", + "unit_testing", + "ref_functions", + "reference_info_json", + ], + }, + { + "For a Deeper Understanding": [ + "how_keyboards_work", + "how_a_matrix_works", + "understanding_qmk", + ], + }, + { + "QMK Internals": [ + "internals/defines", + "internals/input_callback_reg", + "internals/midi_device", + "internals/midi_device_setup_process", + "internals/midi_util", + "internals/send_functions", + "internals/sysex_tools", + ], + }, + ], + }, ], };