From 990d5189d19341cb768ea39a5510f381f1522e20 Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Sun, 29 Nov 2020 10:28:03 -0600 Subject: Configurable serial usart timeout (#11057) --- docs/serial_driver.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/serial_driver.md b/docs/serial_driver.md index bc376b6ddd..c98f4c1176 100644 --- a/docs/serial_driver.md +++ b/docs/serial_driver.md @@ -60,6 +60,7 @@ Configure the hardware via your config.h: // 5: about 19200 baud #define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1 #define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 +#define SERIAL_USART_TIMEOUT 100 // USART driver timeout. default 100 ``` You must also enable the ChibiOS `SERIAL` feature: -- cgit v1.2.3 From 87291437bd5afccb44677db3ebcf0c284128e990 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Thu, 3 Dec 2020 13:04:28 +1100 Subject: Add board specific to Proton-C, with usual defaults turned on. (#10976) - Set all other ChibiOS defaults to 'off', when not targeting Proton-C - Modified all existing F303 boards to point at the QMK_PROTON_C to ensure repeatable binary output - Modified version.h generation so that SKIP_VERSION=yes generates the same output --- docs/ja/proton_c_conversion.md | 1 + docs/proton_c_conversion.md | 1 + 2 files changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/ja/proton_c_conversion.md b/docs/ja/proton_c_conversion.md index 6e4f7dcb66..e7c07413ce 100644 --- a/docs/ja/proton_c_conversion.md +++ b/docs/ja/proton_c_conversion.md @@ -51,6 +51,7 @@ Proton C には1つのオンボード LED(C13)しかなく、デフォルトで ``` MCU = STM32F303 +BOARD = QMK_PROTON_C ``` 次の変数が存在する場合は削除します。 diff --git a/docs/proton_c_conversion.md b/docs/proton_c_conversion.md index 1b5e496e74..47511e1b1e 100644 --- a/docs/proton_c_conversion.md +++ b/docs/proton_c_conversion.md @@ -44,6 +44,7 @@ To use the Proton C natively, without having to specify `CTPC=yes`, you need to ``` MCU = STM32F303 +BOARD = QMK_PROTON_C ``` Remove these variables if they exist: -- cgit v1.2.3 From 5e2b53541bef9b380380286724b321cc8a0ac413 Mon Sep 17 00:00:00 2001 From: Casey Webster Date: Wed, 16 Dec 2020 23:21:26 -0600 Subject: Add modifier state to the split keyboard transport (#10400) * Add modifier state to the split transport This adds modifier state to the i2c and serial transport for split keyboards. The purpose of this is to allow e.g. displaying modifier state on the slave side of a split keyboard on an oled. This adds one byte to the data transferred between halves. This also fixes a missing ifdef guard for BLACKLIGHT_ENABLE. Break modifiers into real/weak/oneshot Fix incorrect slave serial mod setting Fix typo in serial weal mod setter Fix build errors for the I2C code that I introduced Code cleanup and formatting per project preferences Correctly get oneshot mods Fix missing braces Remove unneeded ifdef guard Make the added state transport optional Add documentation for the new define to enable this feature Fix stray grave mark * Fix error introduced in conflict resolution --- docs/feature_split_keyboard.md | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index b234114200..c285e353d4 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -181,6 +181,16 @@ If you're having issues with serial communication, you can change this value, as * **`4`**: about 26kbps * **`5`**: about 20kbps +```c +#define SPLIT_MODS_ENABLE +``` + +This enables transmitting modifier state (normal, weak and oneshot) to the non +primary side of the split keyboard. This adds a few bytes of data to the split +communication protocol and may impact the matrix scan speed when enabled. +The purpose of this feature is to support cosmetic use of modifer state (e.g. +displaying status on an OLED screen). + ### Hardware Configuration Options There are some settings that you may need to configure, based on how the hardware is set up. -- cgit v1.2.3 From 010271d6ea08b58415d3ecd3e8acb37aeb4372bb Mon Sep 17 00:00:00 2001 From: Jan Christoph Ebersbach Date: Thu, 24 Dec 2020 23:12:19 +0100 Subject: Implement kinetic mouse movement algorithm (#6739) * Implement kinetic mouse movement algorithm * Adjust mouse wheel speed * Remove unused math.h include * Wrap mouse_timer definition in ifdef * Replace double space by single space * Clarify documentation of kinetic mouse speed Co-Authored-By: lf * Clarify documentation of kinetic mouse speed Co-Authored-By: lf * Remove superfluous definition of speed * fix(variable): remove unused variable Co-authored-by: lf --- docs/feature_mouse_keys.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index ffde133892..a0d02416f2 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -42,6 +42,7 @@ In your keymap you can use the following keycodes to map key presses to mouse ac Mouse keys supports three different modes to move the cursor: * **Accelerated (default):** Holding movement keys accelerates the cursor until it reaches its maximum speed. +* **Kinetic:** Holding movement keys accelerates the cursor with its speed following a quadratic curve until it reaches its maximum speed. * **Constant:** Holding movement keys moves the cursor at constant speeds. * **Combined:** Holding movement keys accelerates the cursor until it reaches its maximum speed, but holding acceleration and movement keys simultaneously moves the cursor at constant speeds. @@ -56,7 +57,8 @@ This is the default mode. You can adjust the cursor and scrolling acceleration u |Define |Default|Description | |----------------------------|-------|---------------------------------------------------------| |`MOUSEKEY_DELAY` |300 |Delay between pressing a movement key and cursor movement| -|`MOUSEKEY_INTERVAL` |50 |Time between cursor movements | +|`MOUSEKEY_INTERVAL` |50 |Time between cursor movements in milliseconds | +|`MOUSEKEY_MOVE_DELTA` |5 |Step size | |`MOUSEKEY_MAX_SPEED` |10 |Maximum cursor speed at which acceleration stops | |`MOUSEKEY_TIME_TO_MAX` |20 |Time until maximum cursor speed is reached | |`MOUSEKEY_WHEEL_DELAY` |300 |Delay between pressing a wheel key and wheel movement | @@ -73,6 +75,30 @@ Tips: Cursor acceleration uses the same algorithm as the X Window System MouseKeysAccel feature. You can read more about it [on Wikipedia](https://en.wikipedia.org/wiki/Mouse_keys). +### Kinetic Mode + +This is an extension of the accelerated mode. The kinetic mode uses a quadratic curve on the cursor speed which allows precise movements at the beginning and allows to cover large distances by increasing cursor speed quickly thereafter. You can adjust the cursor and scrolling acceleration using the following settings in your keymap’s `config.h` file: + +|Define |Default |Description | +|--------------------------------------|---------|---------------------------------------------------------------| +|`MK_KINETIC_SPEED` |undefined|Enable kinetic mode | +|`MOUSEKEY_DELAY` |8 |Delay between pressing a movement key and cursor movement | +|`MOUSEKEY_INTERVAL` |8 |Time between cursor movements in milliseconds | +|`MOUSEKEY_MOVE_DELTA` |25 |Step size for accelerating from initial to base speed | +|`MOUSEKEY_INITIAL_SPEED` |100 |Initial speed of the cursor in pixel per second | +|`MOUSEKEY_BASE_SPEED` |1000 |Maximum cursor speed at which acceleration stops | +|`MOUSEKEY_DECELERATED_SPEED` |400 |Decelerated cursor speed | +|`MOUSEKEY_ACCELERATED_SPEED` |3000 |Accelerated cursor speed | +|`MOUSEKEY_WHEEL_INITIAL_MOVEMENTS` |16 |Initial number of movements of the mouse wheel | +|`MOUSEKEY_WHEEL_BASE_MOVEMENTS` |32 |Maximum number of movements at which acceleration stops | +|`MOUSEKEY_WHEEL_ACCELERATED_MOVEMENTS`|48 |Accelerated wheel movements | +|`MOUSEKEY_WHEEL_DECELERATED_MOVEMENTS`|8 |Decelerated wheel movements | + +Tips: + +* The smoothness of the cursor movement depends on the `MOUSEKEY_INTERVAL` setting. The shorter the interval is set the smoother the movement will be. Setting the value too low makes the cursor unresponsive. Lower settings are possible if the micro processor is fast enough. For example: At an interval of `8` milliseconds, `125` movements per second will be initiated. With a base speed of `1000` each movement will move the cursor by `8` pixels. +* Mouse wheel movements are implemented differently from cursor movements. While it's okay for the cursor to move multiple pixels at once for the mouse wheel this would lead to jerky movements. Instead, the mouse wheel operates at step size `1`. Setting mouse wheel speed is done by adjusting the number of wheel movements per second. + ### Constant mode In this mode you can define multiple different speeds for both the cursor and the mouse wheel. There is no acceleration. `KC_ACL0`, `KC_ACL1` and `KC_ACL2` change the cursor and scroll speed to their respective setting. -- cgit v1.2.3 From 4f2f21dc05c70451593ba83ed7a0956c771850c2 Mon Sep 17 00:00:00 2001 From: Aldehir Rojas Date: Tue, 29 Dec 2020 18:28:49 -0600 Subject: Rewrite APA102 support (#10894) * Rewrite APA102 support The APA102 source was broken by commit 16a15c1cfcbfd0feb2c2cf1383676747e2f97d73 as it did not include the quantum header. This commit addresses that, as well as other issues with transferring bytes over the SPI interface, i.e. it was not setting the clock pin back to low after sending a bit. The deviation when sending the end frame is kept, but updated to the latest from the referenced project. Finally, these changes expose the global LED brightness parameter of the APA102. Brightness values are configurable through `APA102_DEFAULT_BRIGHTNESS` and `APA102_MAX_BRIGHTNESS`. * Fix typo in led brightness extern * Move driver out of AVR directory and add delay for ARM * Experimental APA102 support on AVR and ARM Co-authored-by: Alde Rojas * Refactor apa102_send_byte() calls to a loop * Implement io_wait function for ARM * Move APA102 drivers to own directory, fix copyright notice * Add APA102 keymap to handwired/onekey * Simplify RGBLIGHT_ENABLE/DRIVER option handling Co-authored-by: Mikkel Jeppesen <2756925+Duckle29@users.noreply.github.com> --- docs/feature_rgb_matrix.md | 22 ++++++++++++++++++++++ docs/feature_rgblight.md | 11 ++++++++++- 2 files changed, 32 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index a9e711c9f2..bb0acba3bb 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -129,6 +129,28 @@ Configure the hardware via your `config.h`: --- +### APA102 :id=apa102 + +There is basic support for APA102 based addressable LED strands. To enable it, add this to your `rules.mk`: + +```makefile +RGB_MATRIX_ENABLE = yes +RGB_MATRIX_DRIVER = APA102 +``` + +Configure the hardware via your `config.h`: + +```c +// The pin connected to the data pin of the LEDs +#define RGB_DI_PIN D7 +// The pin connected to the clock pin of the LEDs +#define RGB_CI_PIN D6 +// The number of LEDs connected +#define DRIVER_LED_TOTAL 70 +``` + +--- + 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: ```c diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 762056b343..f1178c679d 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -10,6 +10,7 @@ Currently QMK supports the following addressable LEDs (however, the white LED in * WS2811, WS2812, WS2812B, WS2812C, etc. * SK6812, SK6812MINI, SK6805 + * APA102 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. @@ -21,11 +22,19 @@ On keyboards with onboard RGB LEDs, it is usually enabled by default. If it is n RGBLIGHT_ENABLE = yes ``` -At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these. +For APA102 LEDs, add the following to your `rules.mk`: + +```make +RGBLIGHT_ENABLE = yes +RGBLIGHT_DRIVER = APA102 +``` + +At minimum you must define the data pin your LED strip is connected to, and the number of LEDs in the strip, in your `config.h`. For APA102 LEDs, you must also define the clock pin. If your keyboard has onboard RGB LEDs, and you are simply creating a keymap, you usually won't need to modify these. |Define |Description | |---------------|---------------------------------------------------------------------------------------------------------| |`RGB_DI_PIN` |The pin connected to the data pin of the LEDs | +|`RGB_CI_PIN` |The pin connected to the clock pin of the LEDs (APA102 only) | |`RGBLED_NUM` |The number of LEDs connected | |`RGBLED_SPLIT` |(Optional) For split keyboards, the number of LEDs connected on each half directly wired to `RGB_DI_PIN` | -- cgit v1.2.3 From 47b9b110097a864d6ab76516b2213afd59948527 Mon Sep 17 00:00:00 2001 From: Zach White Date: Wed, 30 Dec 2020 10:27:37 -0800 Subject: Configure keyboard matrix from info.json (#10817) * Make parameters from info.json available to the build system * move all clueboard settings to info.json * code formatting * make flake8 happy * make flake8 happy * make qmk lint happy * Add support for specifying led indicators in json * move led indicators to the clueboard info.json * Apply suggestions from code review Co-authored-by: Erovia * add missing docstring Co-authored-by: Erovia --- docs/reference_info_json.md | 157 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 136 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 3ca62c719e..47506bc92d 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -19,8 +19,20 @@ The `info.json` file is a JSON formatted dictionary with the following keys avai * Width of the board in Key Units * `height` * Height of the board in Key Units +* `debounce` + * How many milliseconds (ms) to wait for debounce to happen. (Default: 5) +* `diode_direction` + * The direction diodes face. See [`DIRECT_PINS` in the hardware configuration](https://docs.qmk.fm/#/config_options?id=hardware-options) for more details. +* `layout_aliases` + * A dictionary containing layout aliases. The key is the alias and the value is a layout in `layouts` it maps to. * `layouts` - * Physical Layout representations. See the next section for more detail. + * Physical Layout representations. See the [Layout Format](#layout_format) section for more detail. +* `matrix_pins` + * Configure the pins corresponding to columns and rows, or direct pins. See [Matrix Pins](#matrix_pins) for more detail. +* `rgblight` + * Configure the [RGB Lighting feature](feature_rgblight.md). See the [RGB Lighting](#rgb_lighting) section for more detail. +* `usb` + * Configure USB VID, PID, and other parameters. See [USB](#USB) for more detail. ### Layout Format @@ -49,25 +61,128 @@ All key positions and rotations are specified in relation to the top-left corner * The width of the key, in Key Units. Ignored if `ks` is provided. Default: `1` * `h` * The height of the key, in Key Units. Ignored if `ks` is provided. Default: `1` -* `r` - * How many degrees clockwise to rotate the key. -* `rx` - * The absolute position of the point to rotate the key around in the horizontal axis. Default: `x` -* `ry` - * The absolute position of the point to rotate the key around in the vertical axis. Default: `y` -* `ks` - * Key Shape: define a polygon by providing a list of points, in Key Units. - * **Important**: These are relative to the top-left of the key, not absolute. - * Example ISO Enter: `[ [0,0], [1.5,0], [1.5,2], [0.25,2], [0.25,1], [0,1], [0,0] ]` * `label` * What to name this position in the matrix. - * This should usually be the same name as what is silkscreened on the PCB at this location. - -## How is the Metadata Exposed? - -This metadata is primarily used in two ways: - -* To allow web-based configurators to dynamically generate UI -* To support the new `make keyboard:keymap:qmk` target, which bundles this metadata up with the firmware to allow QMK Toolbox to be smarter. - -Configurator authors can see the [QMK Compiler](https://docs.api.qmk.fm/using-the-api) docs for more information on using the JSON API. + * This should usually correspond to the keycode for the first layer of the default keymap. +* `matrix` + * A 2 item list describing the row and column location for this key. + +### Matrix Pins + +Currently QMK supports connecting switches either directly to GPIO pins or via a switch matrix. At this time you can not combine these, they are mutually exclusive. + +#### Switch Matrix + +Most keyboards use a switch matrix to connect keyswitches to the MCU. You can define your pin columns and rows to configure your switch matrix. When defining switch matrices you should also define your `diode_direction`. + +Example: + +```json +{ + "diode_direction": "COL2ROW", + "matrix_pins": { + "cols": ["F4", "E6", "B1", "D2"], + "rows": ["B0", "D3", "D5", "D4", "D6"] + } +} +``` + +#### Direct Pins + +Direct pins are when you connect one side of the switch to GND and the other side to a GPIO pin on your MCU. No diode is required, but there is a 1:1 mapping between switches and pins. + +When specifying direct pins you need to arrange them in nested arrays. The outer array consists of rows, while the inner array is a text string corresponding to a pin. You can use `null` to indicate an empty spot in the matrix. + +Example: + +```json +{ + "matrix_pins": { + "direct": [ + ["A10", "A9"], + ["A0", "B8"], + [null, "B11"], + ["B9", "A8"], + ["A7", "B1"], + [null, "B2"] + ] +} +``` + +### RGB Lighting + +This section controls the legacy WS2812 support in QMK. This should not be confused with the RGB Matrix feature, which can be used to control both WS2812 and ISSI RGB LEDs. + +The following items can be set. Not every value is required. + +* `led_count` + * The number of LEDs in your strip +* `pin` + * The GPIO pin that your LED strip is connected to +* `animations` + * A dictionary that lists enabled and disabled animations. See [RGB Light Animations](#rgb_light_animations) below. +* `sleep` + * Set to `true` to enable lighting during host sleep +* `split` + * Set to `true` to enable synchronization functionality between split halves +* `split_count` + * For split keyboards, the number of LEDs on each side +* `max_brightness` + * (0-255) What the maxmimum brightness (value) level is +* `hue_steps` + * How many steps of adjustment to have for hue +* `saturation_steps` + * How many steps of adjustment to have for saturation +* `brightness_steps` + * How many steps of adjustment to have for brightness (value) + +Example: + +```json +{ + "rgblight": { + "led_count": 4, + "pin": "F6", + "hue_steps": 10, + "saturation_steps": 17, + "brightness_steps": 17, + "animations": { + "all": true + } + } +} +``` + +#### RGB Light Animations + +The following animations can be enabled: + +| Key | Description | +|-----|-------------| +| `all` | Enable all additional animation modes. | +| `alternating` | Enable alternating animation mode. | +| `breathing` | Enable breathing animation mode. | +| `christmas` | Enable christmas animation mode. | +| `knight` | Enable knight animation mode. | +| `rainbow_mood` | Enable rainbow mood animation mode. | +| `rainbow_swirl` | Enable rainbow swirl animation mode. | +| `rgb_test` | Enable RGB test animation mode. | +| `snake` | Enable snake animation mode. | +| `static_gradient` | Enable static gradient mode. | +| `twinkle` | Enable twinkle animation mode. | + +### USB + +Every USB keyboard needs to have its USB parmaters defined. At a minimum you need to set vid, pid, and device version. + +Example: + +```json +{ + "usb": { + "vid": "0xC1ED", + "pid": "0x23B0", + "device_ver": "0x0001" + } +} +``` -- cgit v1.2.3 From e190872b822f247794213120e0f7a276c07c95b9 Mon Sep 17 00:00:00 2001 From: Joshua Diamond Date: Fri, 1 Jan 2021 23:54:48 -0500 Subject: Improved Language Specific Keycodes for US International and Extended Layouts (#11307) Co-authored-by: Ryan --- docs/reference_keymap_extras.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/reference_keymap_extras.md b/docs/reference_keymap_extras.md index f2abb4e596..40a1956844 100644 --- a/docs/reference_keymap_extras.md +++ b/docs/reference_keymap_extras.md @@ -18,7 +18,9 @@ To use these, simply `#include` the corresponding [header file](https://github.c |Dutch (Belgium) |`keymap_belgian.h` | |English (Ireland) |`keymap_irish.h` | |English (UK) |`keymap_uk.h` | +|English (US Extended) |`keymap_us_extended.h` | |English (US International) |`keymap_us_international.h` | +|English (US International, Linux)|`keymap_us_international_linux.h`| |Estonian |`keymap_estonian.h` | |Finnish |`keymap_finnish.h` | |French |`keymap_french.h` | -- cgit v1.2.3 From 962bc8d9dd413690dbeadeaac971a5389697210f Mon Sep 17 00:00:00 2001 From: Zach White Date: Sat, 9 Jan 2021 13:34:14 -0800 Subject: Use the schema to eliminate custom code (#11108) * use the schema to eliminate custom code * Update docs/reference_info_json.md Co-authored-by: Ryan * make flake8 happy * bugfix * do not overwrite make vars from json Co-authored-by: Ryan --- docs/reference_info_json.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 47506bc92d..c9864ea2de 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -106,6 +106,7 @@ Example: ["A7", "B1"], [null, "B2"] ] + } } ``` -- cgit v1.2.3 From a15c9057a1f52e28229dd466f51ae4f4f9ecdb81 Mon Sep 17 00:00:00 2001 From: Zach White Date: Sun, 10 Jan 2021 20:47:58 -0800 Subject: Document how to add data driven configurations (#11502) * describe how data driven configuration works * Apply suggestions from code review Co-authored-by: ridingqwerty Co-authored-by: Erovia Co-authored-by: ridingqwerty Co-authored-by: Erovia --- docs/_summary.md | 1 + docs/data_driven_config.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 docs/data_driven_config.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 19498f6a20..8d401bb40c 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -159,6 +159,7 @@ * [Contributing to QMK](contributing.md) * [Translating the QMK Docs](translating.md) * [Config Options](config_options.md) + * [Data Driven Configuration](data_driven_config.md) * [Make Documentation](getting_started_make_guide.md) * [Documentation Best Practices](documentation_best_practices.md) * [Documentation Templates](documentation_templates.md) diff --git a/docs/data_driven_config.md b/docs/data_driven_config.md new file mode 100644 index 0000000000..7e4f232846 --- /dev/null +++ b/docs/data_driven_config.md @@ -0,0 +1,59 @@ +# Data Driven Configuration + +This page describes how QMK's data driven JSON configuration system works. It is aimed at developers who want to work on QMK itself. + +## History + +Historically QMK has been configured through a combination of two mechanisms- `rules.mk` and `config.h`. While this worked well when QMK was only a handful of keyboards we've grown to encompass nearly 1500 supported keyboards. That extrapolates out to 6000 configuration files under `keyboards/` alone! The freeform nature of these files and the unique patterns people have used to avoid duplication have made ongoing maintenance a challenge, and a large number of our keyboards follow patterns that are outdated and sometimes harder to understand. + +We have also been working on bringing the power of QMK to people who aren't comformable with a CLI, and other projects such as VIA are working to make using QMK as easy as installing a program. These tools need information about how a keyboard is laid out or what pins and features are available so that users can take full advantage of QMK. We introduced `info.json` as a first step towards this. The QMK API is an effort to combine these 3 sources of information- `config.h`, `rules.mk`, and `info.json`- into a single source of truth that end-user tools can use. + +Now we have support for generating `rules.mk` and `config.h` values from `info.json`, allowing us to have a single source of truth. This will allow us to use automated tooling to maintain keyboards saving a lot of time and maintenance work. + +## Overview + +On the C side of things nothing really changes. When you need to create a new rule or define you follow the same process: + +1. Add it to `docs/config_options.md` +1. Set a default in the appropriate core file +1. Add your `ifdef` and/or `#ifdef` statements as needed + +You will then need to add support for your new configuration to `info.json`. The basic process is: + +1. Add it to the schema in `data/schemas/keyboards.jsonschema` +1. Add code to extract it from `config.h`/`rules.mk` to `lib/python/qmk/info.py` +1. Add code to generate it to one of: + * `lib/python/qmk/cli/generate/config_h.py` + * `lib/python/qmk/cli/generate/rules_mk.py` + +## Adding an option to info.json + +This section describes adding support for a `config.h`/`rules.mk` value to info.json. + +### Add it to the schema + +QMK maintains schema files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here. + +In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options. In other cases you should group like options together in an `object`. This is particularly true when adding support for a feature. Some examples to follow for this are `indicators`, `matrix_pins`, and `rgblight`. If you are not sure how to integrate your new option(s) [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there. + +### Add code to extract it + +Whenever QMK generates a complete `info.json` it extracts information from `config.h` and `rules.mk`. You will need to add code for your new config value to `lib/python/qmk/info.py`. Typically this means adding a new `_extract_()` function and then calling your function in either `_extract_config_h()` or `_extract_rules_mk()`. + +If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part. + +### Add code to generate it + +The final piece of the puzzle is providing your new option to the build system. This is done by generating two files: + +* `.build/obj_/src/info_config.h` +* `.build/obj_/src/rules.mk` + +These two files are generated by the code here: + +* `lib/python/qmk/cli/generate/config_h.py` +* `lib/python/qmk/cli/generate/rules_mk.py` + +For `config.h` values you'll need to write a function for your rule(s) and call that function in `generate_config_h()`. + +If you have a new top-level `info.json` key for `rules.mk` you can simply add your keys to `info_to_rules` at the top of `lib/python/qmk/cli/generate/rules_mk.py`. Otherwise you'll need to create a new if block for your feature in `generate_rules_mk()`. -- cgit v1.2.3 From 6e8adeeaacd8cdc83422494e3d525caeded6fe9e Mon Sep 17 00:00:00 2001 From: Joshua Diamond Date: Mon, 11 Jan 2021 02:04:42 -0500 Subject: Refine twinkle to be smoother (use breathing curve) (#11350) * Refine twinkle to be smoother (use breathing curve) * tune more for firmware size * fix bug when v=255 ~ drashna approved ~ --- docs/feature_rgblight.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index 08d0e9531e..f24a4f570c 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -148,7 +148,7 @@ The following options are used to tweak the various animations: |`RGBLIGHT_EFFECT_KNIGHT_OFFSET` |`0` |The number of LEDs to start the "Knight" animation from the start of the strip by | |`RGBLIGHT_RAINBOW_SWIRL_RANGE` |`255` |Range adjustment for the rainbow swirl effect to get different swirls | |`RGBLIGHT_EFFECT_SNAKE_LENGTH` |`4` |The number of LEDs to light up for the "Snake" animation | -|`RGBLIGHT_EFFECT_TWINKLE_LIFE` |`75` |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps) | +|`RGBLIGHT_EFFECT_TWINKLE_LIFE` |`200` |Adjusts how quickly each LED brightens and dims when twinkling (in animation steps) | |`RGBLIGHT_EFFECT_TWINKLE_PROBABILITY`|`1/127` |Adjusts how likely each LED is to twinkle (on each animation step) | ### Example Usage to Reduce Memory Footprint -- cgit v1.2.3 From 415d683ea71d516dd2a7d4f2f8e43eb4e3e993cb Mon Sep 17 00:00:00 2001 From: Ryan Date: Mon, 11 Jan 2021 20:25:45 +1100 Subject: Remove unused `action_get_macro()` usages in user files (#11165) --- docs/feature_macros.md | 113 +++------------------------------------------- docs/ja/feature_macros.md | 113 +++------------------------------------------- 2 files changed, 12 insertions(+), 214 deletions(-) (limited to 'docs') diff --git a/docs/feature_macros.md b/docs/feature_macros.md index 36fa761d21..aa1ebc337a 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -4,7 +4,7 @@ Macros allow you to send multiple keystrokes when pressing just one key. QMK has !> **Security Note**: While it is possible to use macros to send passwords, credit card numbers, and other sensitive information it is a supremely bad idea to do so. Anyone who gets a hold of your keyboard will be able to access that information by opening a text editor. -## The New Way: `SEND_STRING()` & `process_record_user` +## `SEND_STRING()` & `process_record_user` Sometimes you want a key to type out words or phrases. For the most common situations, we've provided `SEND_STRING()`, which will type out a string (i.e. a sequence of characters) for you. All ASCII characters that are easily translatable to a keycode are supported (e.g. `qmk 123\n\t`). @@ -262,15 +262,15 @@ This will clear all keys besides the mods currently pressed. This macro will register `KC_LALT` and tap `KC_TAB`, then wait for 1000ms. If the key is tapped again, it will send another `KC_TAB`; if there is no tap, `KC_LALT` will be unregistered, thus allowing you to cycle through windows. ```c -bool is_alt_tab_active = false; # ADD this near the begining of keymap.c -uint16_t alt_tab_timer = 0; # we will be using them soon. +bool is_alt_tab_active = false; // ADD this near the begining of keymap.c +uint16_t alt_tab_timer = 0; // we will be using them soon. -enum custom_keycodes { # Make sure have the awesome keycode ready +enum custom_keycodes { // Make sure have the awesome keycode ready ALT_TAB = SAFE_RANGE, }; bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { # This will do most of the grunt work with the keycodes. + switch (keycode) { // This will do most of the grunt work with the keycodes. case ALT_TAB: if (record->event.pressed) { if (!is_alt_tab_active) { @@ -287,7 +287,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { return true; } -void matrix_scan_user(void) { # The very important timer. +void matrix_scan_user(void) { // The very important timer. if (is_alt_tab_active) { if (timer_elapsed(alt_tab_timer) > 1000) { unregister_code(KC_LALT); @@ -296,104 +296,3 @@ void matrix_scan_user(void) { # The very important timer. } } ``` - ---- - -## **(DEPRECATED)** The Old Way: `MACRO()` & `action_get_macro` - -!> This is inherited from TMK, and hasn't been updated - it's recommended that you use `SEND_STRING` and `process_record_user` instead. - -By default QMK assumes you don't have any macros. To define your macros you create an `action_get_macro()` function. For example: - -```c -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - if (record->event.pressed) { - switch(id) { - case 0: - return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END); - case 1: - return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END); - } - } - return MACRO_NONE; -}; -``` - -This defines two macros which will be run when the key they are assigned to is pressed. If instead you'd like them to run when the key is released you can change the if statement: - - if (!record->event.pressed) { - -### Macro Commands - -A macro can include the following commands: - -* I() change interval of stroke in milliseconds. -* D() press key. -* U() release key. -* T() type key(press and release). -* W() wait (milliseconds). -* END end mark. - -### Mapping a Macro to a Key - -Use the `M()` function within your keymap to call a macro. For example, here is the keymap for a 2-key keyboard: - -```c -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = LAYOUT( - M(0), M(1) - ), -}; - -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - if (record->event.pressed) { - switch(id) { - case 0: - return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END); - case 1: - return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END); - } - } - return MACRO_NONE; -}; -``` - -When you press the key on the left it will type "Hi!" and when you press the key on the right it will type "Bye!". - -### Naming Your Macros - -If you have a bunch of macros you want to refer to from your keymap while keeping the keymap easily readable you can name them using `#define` at the top of your file. - -```c -#define M_HI M(0) -#define M_BYE M(1) - -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = LAYOUT( - M_HI, M_BYE - ), -}; -``` - - -## Advanced Example: - -### Single-Key Copy/Paste - -This example defines a macro which sends `Ctrl-C` when pressed down, and `Ctrl-V` when released. - -```c -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - switch(id) { - case 0: { - if (record->event.pressed) { - return MACRO( D(LCTL), T(C), U(LCTL), END ); - } else { - return MACRO( D(LCTL), T(V), U(LCTL), END ); - } - break; - } - } - return MACRO_NONE; -}; -``` diff --git a/docs/ja/feature_macros.md b/docs/ja/feature_macros.md index 14a58ad244..c42a61b5fb 100644 --- a/docs/ja/feature_macros.md +++ b/docs/ja/feature_macros.md @@ -9,7 +9,7 @@ !> **セキュリティの注意**: マクロを使って、パスワード、クレジットカード番号、その他の機密情報のいずれも送信することが可能ですが、それは非常に悪い考えです。あなたのキーボードを手に入れた人は誰でもテキストエディタを開いてその情報にアクセスすることができます。 -## 新しい方法: `SEND_STRING()` と `process_record_user` +## `SEND_STRING()` と `process_record_user` 単語またはフレーズを入力するキーが欲しい時があります。最も一般的な状況のために `SEND_STRING()` を提供しています。これは文字列(つまり、文字のシーケンス)を入力します。簡単にキーコードに変換することができる全ての ASCII 文字がサポートされています (例えば、`qmk 123\n\t`)。 @@ -267,15 +267,15 @@ SEND_STRING(".."SS_TAP(X_END)); このマクロは `KC_LALT` を登録し、`KC_TAB` をタップして、1000ms 待ちます。キーが再度タップされると、別の `KC_TAB` が送信されます; タップが無い場合、`KC_LALT` が登録解除され、ウィンドウを切り替えることができます。 ```c -bool is_alt_tab_active = false; # keymap.c の先頭付近にこれを追加します -uint16_t alt_tab_timer = 0; # すぐにそれらを使います +bool is_alt_tab_active = false; // keymap.c の先頭付近にこれを追加します +uint16_t alt_tab_timer = 0; // すぐにそれらを使います -enum custom_keycodes { # 素晴らしいキーコードを用意してください +enum custom_keycodes { // 素晴らしいキーコードを用意してください ALT_TAB = SAFE_RANGE, }; bool process_record_user(uint16_t keycode, keyrecord_t *record) { - switch (keycode) { # これはキーコードを利用したつまらない作業のほとんどを行います。 + switch (keycode) { // これはキーコードを利用したつまらない作業のほとんどを行います。 case ALT_TAB: if (record->event.pressed) { if (!is_alt_tab_active) { @@ -292,7 +292,7 @@ bool process_record_user(uint16_t keycode, keyrecord_t *record) { return true; } -void matrix_scan_user(void) { # とても重要なタイマー +void matrix_scan_user(void) { // とても重要なタイマー if (is_alt_tab_active) { if (timer_elapsed(alt_tab_timer) > 1000) { unregister_code(KC_LALT); @@ -301,104 +301,3 @@ void matrix_scan_user(void) { # とても重要なタイマー } } ``` - ---- - -## **(非推奨)** 古い方法: `MACRO()` と `action_get_macro` - -!> これは TMK から継承されており、更新されていません - 代わりに `SEND_STRING` と `process_record_user` を使うことをお勧めします。 - -デフォルトでは、QMK はマクロが無いことを前提としています。マクロを定義するには、`action_get_macro()` 関数を作成します。例えば: - -```c -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - if (record->event.pressed) { - switch(id) { - case 0: - return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END); - case 1: - return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END); - } - } - return MACRO_NONE; -}; -``` - -これは割り当てられているキーが押された時に実行される2つのマクロを定義します。キーが放された時にそれらを実行したい場合は、if 文を変更することができます。 - - if (!record->event.pressed) { - -### マクロコマンド - -マクロは以下のコマンドを含めることができます: - -* I() はストロークの間隔をミリ秒単位で変更します。 -* D() はキーを押します。 -* U() はキーを放します。 -* T() はキーをタイプ(押して放す)します。 -* W() は待ちます (ミリ秒)。 -* END 終了マーク。 - -### マクロをキーにマッピングする - -マクロを呼び出すにはキーマップ内で `M()` 関数を使います。例えば、2キーのキーボードのキーマップは以下の通りです: - -```c -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = LAYOUT( - M(0), M(1) - ), -}; - -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - if (record->event.pressed) { - switch(id) { - case 0: - return MACRO(D(LSFT), T(H), U(LSFT), T(I), D(LSFT), T(1), U(LSFT), END); - case 1: - return MACRO(D(LSFT), T(B), U(LSFT), T(Y), T(E), D(LSFT), T(1), U(LSFT), END); - } - } - return MACRO_NONE; -}; -``` - -左側のキーを押すと、"Hi!" を入力し、右側のキーを押すと "Bye!" を入力します。 - -### マクロに名前を付ける - -キーマップを読みやすくしながらキーマップから参照したいマクロがたくさんある場合は、ファイルの先頭で `#define` を使って名前を付けることができます。 - -```c -#define M_HI M(0) -#define M_BYE M(1) - -const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { - [0] = LAYOUT( - M_HI, M_BYE - ), -}; -``` - - -## 高度な例: - -### 単一キーのコピーと貼り付け - -この例は、押された時に `Ctrl-C` を送信し、放される時に `Ctrl-V` を送信するマクロを定義します。 - -```c -const macro_t *action_get_macro(keyrecord_t *record, uint8_t id, uint8_t opt) { - switch(id) { - case 0: { - if (record->event.pressed) { - return MACRO( D(LCTL), T(C), U(LCTL), END ); - } else { - return MACRO( D(LCTL), T(V), U(LCTL), END ); - } - break; - } - } - return MACRO_NONE; -}; -``` -- cgit v1.2.3 From 30b46fad5764b54ab4d47e9c4024f8030e1bf1a7 Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 27 Jan 2021 17:42:49 +1100 Subject: UART driver refactor (#11637) --- docs/_summary.md | 1 + docs/uart_driver.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+) create mode 100644 docs/uart_driver.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 9bc0b193a7..526caf926f 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -138,6 +138,7 @@ * [WS2812 Driver](ws2812_driver.md) * [EEPROM Driver](eeprom_driver.md) * ['serial' Driver](serial_driver.md) + * [UART Driver](uart_driver.md) * [GPIO Controls](internals_gpio_control.md) * [Keyboard Guidelines](hardware_keyboard_guidelines.md) diff --git a/docs/uart_driver.md b/docs/uart_driver.md new file mode 100644 index 0000000000..4d1716975f --- /dev/null +++ b/docs/uart_driver.md @@ -0,0 +1,90 @@ +# UART Driver + +The UART drivers used in QMK have a set of common functions to allow portability between MCUs. + +Currently, this driver does not support enabling hardware flow control (the `RTS` and `CTS` pins) if available, but may do so in future. + +## 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: + +|MCU |`TX`|`RX`|`CTS`|`RTS`| +|-------------|----|----|-----|-----| +|ATmega16/32U2|`D3`|`D2`|`D7` |`D6` | +|ATmega16/32U4|`D3`|`D2`|`D5` |`B7` | +|AT90USB64/128|`D3`|`D2`|*n/a*|*n/a*| +|ATmega32A |`D1`|`D0`|*n/a*|*n/a*| +|ATmega328/P |`D1`|`D0`|*n/a*|*n/a*| + +## ChibiOS/ARM Configuration + +You'll need to determine which pins can be used for UART -- as an example, STM32 parts generally have multiple UART peripherals, labeled USART1, USART2, USART3 etc. + +To enable UART, modify your board's `halconf.h` to enable the serial driver: + +```c +#define HAL_USE_SERIAL TRUE +``` + +Then, modify your board's `mcuconf.h` to enable the peripheral you've chosen, for example: + +```c +#undef STM32_SERIAL_USE_USART2 +#define STM32_SERIAL_USE_USART2 TRUE +``` + +Configuration-wise, you'll need to set up the peripheral as per your MCU's datasheet -- the defaults match the pins for a Proton-C, i.e. STM32F303. + +|`config.h` override |Description |Default Value| +|--------------------------|---------------------------------------------------------------|-------------| +|`#define SERIAL_DRIVER` |USART peripheral to use - USART1 -> `SD1`, USART2 -> `SD2` etc.|`SD1` | +|`#define SD1_TX_PIN` |The pin to use for TX |`A9` | +|`#define SD1_TX_PAL_MODE` |The alternate function mode for TX |`7` | +|`#define SD1_RX_PIN` |The pin to use for RX |`A10` | +|`#define SD1_RX_PAL_MODE` |The alternate function mode for RX |`7` | +|`#define SD1_CTS_PIN` |The pin to use for CTS |`A11` | +|`#define SD1_CTS_PAL_MODE`|The alternate function mode for CTS |`7` | +|`#define SD1_RTS_PIN` |The pin to use for RTS |`A12` | +|`#define SD1_RTS_PAL_MODE`|The alternate function mode for RTS |`7` | + +## Functions + +### `void uart_init(uint32_t baud)` + +Initialize the UART driver. This function must be called only once, before any of the below functions can be called. + +#### Arguments + + - `uint32_t baud` + The baud rate to transmit and receive at. This may depend on the device you are communicating with. Common values are 1200, 2400, 4800, 9600, 19200, 38400, 57600, and 115200. + +--- + +### `void uart_putchar(uint8_t c)` + +Transmit a single byte. + +#### Arguments + + - `uint8_t c` + The byte (character) to send, from 0 to 255. + +--- + +### `uint8_t uart_getchar(void)` + +Receive a single byte. + +#### Return Value + +The byte read from the receive buffer. + +--- + +### `bool uart_available(void)` + +Return whether the receive buffer contains data. Call this function to determine if `uart_getchar()` will return meaningful data. + +#### Return Value + +`true` if the receive buffer length is non-zero. -- cgit v1.2.3 From 99f3df28939d89b7fc2d2e7c0ee21b0879c7813f Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Wed, 27 Jan 2021 09:38:34 -0800 Subject: Add support for 8 buttons to mouse report (#10807) * Add support for 8 buttons to mouse report This includes support for 8 buttons in mousekeys. However, this does move the keys around due to the fact that the last mousekey keycode is already 0xFF, so any past that would not work with register_code and the like, breaking them for tap hold keys, encoders, and other features. * Update mouse key docs * Add changes based on feedback * Fix VUSB report size comment Because drashna red gud * Fix typo in action.c * Fix IS_MOUSE_BUTTON check * Change start range for mousekeys so that the end is 0xFF properly * condense mousekeys check --- docs/feature_mouse_keys.md | 3 +++ docs/feature_pointing_device.md | 2 +- docs/ja/feature_mouse_keys.md | 3 +++ 3 files changed, 7 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index a0d02416f2..8e2a3a4cd1 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -29,6 +29,9 @@ In your keymap you can use the following keycodes to map key presses to mouse ac |`KC_MS_BTN3` |`KC_BTN3`|Press button 3 | |`KC_MS_BTN4` |`KC_BTN4`|Press button 4 | |`KC_MS_BTN5` |`KC_BTN5`|Press button 5 | +|`KC_MS_BTN6` |`KC_BTN6`|Press button 6 | +|`KC_MS_BTN7` |`KC_BTN7`|Press button 7 | +|`KC_MS_BTN8` |`KC_BTN8`|Press button 8 | |`KC_MS_WH_UP` |`KC_WH_U`|Move wheel up | |`KC_MS_WH_DOWN` |`KC_WH_D`|Move wheel down | |`KC_MS_WH_LEFT` |`KC_WH_L`|Move wheel left | diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index c9309d6975..c6d3560f31 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -19,7 +19,7 @@ Keep in mind that a report_mouse_t (here "mouseReport") has the following proper * `mouseReport.y` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing movement (+ upward, - downward) on the y axis. * `mouseReport.v` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing vertical scrolling (+ upward, - downward). * `mouseReport.h` - this is a signed int from -127 to 127 (not 128, this is defined in USB HID spec) representing horizontal scrolling (+ right, - left). -* `mouseReport.buttons` - this is a uint8_t in which the last 5 bits are used. These bits represent the mouse button state - bit 3 is mouse button 5, and bit 7 is mouse button 1. +* `mouseReport.buttons` - this is a uint8_t in which all 8 bits are used. These bits represent the mouse button state - bit 0 is mouse button 1, and bit 7 is mouse button 8. Once you have made the necessary changes to the mouse report, you need to send it: diff --git a/docs/ja/feature_mouse_keys.md b/docs/ja/feature_mouse_keys.md index 74b09e939b..e4fa9dfb45 100644 --- a/docs/ja/feature_mouse_keys.md +++ b/docs/ja/feature_mouse_keys.md @@ -34,6 +34,9 @@ MOUSEKEY_ENABLE = yes | `KC_MS_BTN3` | `KC_BTN3` | ボタン3を押す | | `KC_MS_BTN4` | `KC_BTN4` | ボタン4を押す | | `KC_MS_BTN5` | `KC_BTN5` | ボタン5を押す | +| `KC_MS_BTN6` | `KC_BTN6` | ボタン6を押す | +| `KC_MS_BTN7` | `KC_BTN7` | ボタン7を押す | +| `KC_MS_BTN8` | `KC_BTN8` | ボタン8を押す | | `KC_MS_WH_UP` | `KC_WH_U` | ホイールを向こう側に回転 | | `KC_MS_WH_DOWN` | `KC_WH_D` | ホイールを手前側に回転 | | `KC_MS_WH_LEFT` | `KC_WH_L` | ホイールを左に倒す | -- cgit v1.2.3 From d92ffd1157e3ecc4ae2dbf8548c45c8b0269f664 Mon Sep 17 00:00:00 2001 From: Dasky <32983009+daskygit@users.noreply.github.com> Date: Sat, 30 Jan 2021 03:53:56 +0000 Subject: Adds AT90USB162 support (#11570) * at90usb162 support * fix missing bracket * Apply suggestions from code review Co-authored-by: Ryan Co-authored-by: Ryan --- docs/compatible_microcontrollers.md | 1 + docs/feature_backlight.md | 24 ++++++++++++------------ docs/ja/compatible_microcontrollers.md | 1 + docs/spi_driver.md | 12 ++++++------ 4 files changed, 20 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index ac90ed7464..8694beb7cb 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -9,6 +9,7 @@ The following use [LUFA](https://www.fourwalledcubicle.com/LUFA.php) as the USB * [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2) * [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4) * [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286) +* [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162) Certain MCUs which do not have native USB will use [V-USB](https://www.obdev.at/products/vusb/index.html) instead: diff --git a/docs/feature_backlight.md b/docs/feature_backlight.md index a558af64e1..2adb16e4a8 100644 --- a/docs/feature_backlight.md +++ b/docs/feature_backlight.md @@ -93,18 +93,18 @@ BACKLIGHT_DRIVER = pwm On AVR boards, QMK automatically decides which driver to use according to the following table: -|Backlight Pin|AT90USB64/128|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P| -|-------------|-------------|-------------|-------------|---------|-----------| -|`B1` | | | | |Timer 1 | -|`B2` | | | | |Timer 1 | -|`B5` |Timer 1 |Timer 1 | | | | -|`B6` |Timer 1 |Timer 1 | | | | -|`B7` |Timer 1 |Timer 1 |Timer 1 | | | -|`C4` |Timer 3 | | | | | -|`C5` |Timer 3 | |Timer 1 | | | -|`C6` |Timer 3 |Timer 3 |Timer 1 | | | -|`D4` | | | |Timer 1 | | -|`D5` | | | |Timer 1 | | +|Backlight Pin|AT90USB64/128|AT90USB162|ATmega16/32U4|ATmega16/32U2|ATmega32A|ATmega328/P| +|-------------|-------------|----------|-------------|-------------|---------|-----------| +|`B1` | | | | | |Timer 1 | +|`B2` | | | | | |Timer 1 | +|`B5` |Timer 1 | |Timer 1 | | | | +|`B6` |Timer 1 | |Timer 1 | | | | +|`B7` |Timer 1 |Timer 1 |Timer 1 |Timer 1 | | | +|`C4` |Timer 3 | | | | | | +|`C5` |Timer 3 |Timer 1 | |Timer 1 | | | +|`C6` |Timer 3 |Timer 1 |Timer 3 |Timer 1 | | | +|`D4` | | | | |Timer 1 | | +|`D5` | | | | |Timer 1 | | All other pins will use timer-assisted software PWM: diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md index 56f4c02977..b89dd54b06 100644 --- a/docs/ja/compatible_microcontrollers.md +++ b/docs/ja/compatible_microcontrollers.md @@ -14,6 +14,7 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま * [ATmega16U2](https://www.microchip.com/wwwproducts/en/ATmega16U2) / [ATmega32U2](https://www.microchip.com/wwwproducts/en/ATmega32U2) * [ATmega16U4](https://www.microchip.com/wwwproducts/en/ATmega16U4) / [ATmega32U4](https://www.microchip.com/wwwproducts/en/ATmega32U4) * [AT90USB64](https://www.microchip.com/wwwproducts/en/AT90USB646) / [AT90USB128](https://www.microchip.com/wwwproducts/en/AT90USB1286) +* [AT90USB162](https://www.microchip.com/wwwproducts/en/AT90USB162) 組み込みの USB インターフェースを持たない、いくつかの MCU は代わりに [V-USB](https://www.obdev.at/products/vusb/index.html) を使います: diff --git a/docs/spi_driver.md b/docs/spi_driver.md index 1d432432ad..03c008da2a 100644 --- a/docs/spi_driver.md +++ b/docs/spi_driver.md @@ -6,12 +6,12 @@ The SPI Master drivers used in QMK have a set of common functions to allow porta 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: -|MCU |`SS`|`SCK`|`MOSI`|`MISO`| -|---------------|----|-----|------|------| -|ATMega16/32U2/4|`B0`|`B1` |`B2` |`B3` | -|AT90USB64/128 |`B0`|`B1` |`B2` |`B3` | -|ATmega32A |`B4`|`B7` |`B5` |`B6` | -|ATmega328/P |`B2`|`B5` |`B3` |`B4` | +|MCU |`SS`|`SCK`|`MOSI`|`MISO`| +|-----------------|----|-----|------|------| +|ATMega16/32U2/4 |`B0`|`B1` |`B2` |`B3` | +|AT90USB64/128/162|`B0`|`B1` |`B2` |`B3` | +|ATmega32A |`B4`|`B7` |`B5` |`B6` | +|ATmega328/P |`B2`|`B5` |`B3` |`B4` | You may use more than one slave select pin, not just the `SS` pin. This is useful when you have multiple devices connected and need to communicate with them individually. `SPI_SS_PIN` can be passed to `spi_start()` to refer to `SS`. -- cgit v1.2.3 From ef6329af7c7be77b537fbfc5a5cc7105acc679f7 Mon Sep 17 00:00:00 2001 From: Zach White Date: Sun, 31 Jan 2021 12:46:00 -0800 Subject: Create a system to map between info.json and config.h/rules.mk (#11548) * generate rules.mk from a json mapping * generate rules.mk from a json mapping * support for config.h from json maps * improve the mapping system * document the mapping system * move data/maps to data/mappings * fix flake8 errors * fixup LED_MATRIX_DRIVER * remove product and description from the vision_division keymap level * reduce the complexity of generate-rules-mk * add tests for the generate commands * fix qmk doctor when submodules are not clean --- docs/data_driven_config.md | 44 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/data_driven_config.md b/docs/data_driven_config.md index 7e4f232846..c2ad4fed8f 100644 --- a/docs/data_driven_config.md +++ b/docs/data_driven_config.md @@ -12,17 +12,18 @@ Now we have support for generating `rules.mk` and `config.h` values from `info.j ## Overview -On the C side of things nothing really changes. When you need to create a new rule or define you follow the same process: +On the C side of things nothing changes. When you need to create a new rule or define you follow the same process: 1. Add it to `docs/config_options.md` 1. Set a default in the appropriate core file -1. Add your `ifdef` and/or `#ifdef` statements as needed +1. Add your ifdef statements as needed You will then need to add support for your new configuration to `info.json`. The basic process is: 1. Add it to the schema in `data/schemas/keyboards.jsonschema` -1. Add code to extract it from `config.h`/`rules.mk` to `lib/python/qmk/info.py` -1. Add code to generate it to one of: +1. Add a mapping in `data/maps` +1. (optional and discoraged) Add code to extract/generate it to: + * `lib/python/qmk/info.py` * `lib/python/qmk/cli/generate/config_h.py` * `lib/python/qmk/cli/generate/rules_mk.py` @@ -32,12 +33,43 @@ This section describes adding support for a `config.h`/`rules.mk` value to info. ### Add it to the schema -QMK maintains schema files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here. +QMK maintains [jsonschema](https://json-schema.org/) files in `data/schemas`. The values that go into keyboard-specific `info.json` files are kept in `keyboard.jsonschema`. Any value you want to make available to end users to edit must go in here. -In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options. In other cases you should group like options together in an `object`. This is particularly true when adding support for a feature. Some examples to follow for this are `indicators`, `matrix_pins`, and `rgblight`. If you are not sure how to integrate your new option(s) [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there. +In some cases you can simply add a new top-level key. Some examples to follow are `keyboard_name`, `maintainer`, `processor`, and `url`. This is appropriate when your option is self-contained and not directly related to other options. + +In other cases you should group like options together in an `object`. This is particularly true when adding support for a feature. Some examples to follow for this are `indicators`, `matrix_pins`, and `rgblight`. If you are not sure how to integrate your new option(s) [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and start a conversation there. + +### Add a mapping + +In most cases you can add a simple mapping. These are maintained as JSON files in `data/mappings/info_config.json` and `data/mappings/info_rules.json`, and control mapping for `config.h` and `rules.mk`, respectively. Each mapping is keyed by the `config.h` or `rules.mk` variable, and the value is a hash with the following keys: + +* `info_key`: (required) The location within `info.json` for this value. See below. +* `value_type`: (optional) Default `str`. The format for this variable's value. See below. +* `to_json`: (optional) Default `true`. Set to `false` to exclude this mapping from info.json +* `to_c`: (optional) Default `true`. Set to `false` to exclude this mapping from config.h +* `warn_duplicate`: (optional) Default `true`. Set to `false` to turn off warning when a value exists in both places + +#### Info Key + +We use JSON dot notation to address variables within info.json. For example, to access `info_json["rgblight"]["split_count"]` I would specify `rgblight.split_count`. This allows you to address deeply nested keys with a simple string. + +Under the hood we use [Dotty Dict](https://dotty-dict.readthedocs.io/en/latest/), you can refer to that documentation for how these strings are converted to object access. + +#### Value Types + +By default we treat all values as simple strings. If your value is more complex you can use one of these types to intelligently parse the data: + +* `array`: A comma separated array of strings +* `array.int`: A comma separated array of integers +* `int`: An integer +* `hex`: A number formatted as hex +* `list`: A space separate array of strings +* `mapping`: A hash of key/value pairs ### Add code to extract it +Most use cases can be solved by the mapping files described above. If yours can't you can instead write code to extract your config values. + Whenever QMK generates a complete `info.json` it extracts information from `config.h` and `rules.mk`. You will need to add code for your new config value to `lib/python/qmk/info.py`. Typically this means adding a new `_extract_()` function and then calling your function in either `_extract_config_h()` or `_extract_rules_mk()`. If you are not sure how to edit this file or are not comfortable with Python [open an issue](https://github.com/qmk/qmk_firmware/issues/new?assignees=&labels=cli%2C+python&template=other_issues.md&title=) or [join #cli on Discord](https://discord.gg/heQPAgy) and someone can help you with this part. -- cgit v1.2.3 From 9a4618b05b9f1093908c2153c719c5eb5d4a79ee Mon Sep 17 00:00:00 2001 From: Joshua Diamond Date: Mon, 1 Feb 2021 19:12:41 -0500 Subject: Address wake from sleep instability (#11450) * resolve race condition between suspend and wake in LUFA * avoid multiple calls to suspend_power_down() / suspend_wakeup_init() * Remove duplicate suspend_power_down_kb() call * pause on wakeup to wait for USB state to settle * need the repeated suspend_power_down() (that's where the sleep is) * more efficient implementation * fine tune the pause after sending wakeup * speculative chibios version of pause-after-wake * make wakeup delay configurable, and adjust value * better location for wakeup delay --- docs/config_options.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/config_options.md b/docs/config_options.md index a3262b418b..9a64b9b3d2 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -97,6 +97,8 @@ This is a C header file that is one of the first things included, and will persi * sets the maximum power (in mA) over USB for the device (default: 500) * `#define USB_POLLING_INTERVAL_MS 10` * sets the USB polling rate in milliseconds for the keyboard, mouse, and shared (NKRO/media keys) interfaces +* `#define USB_SUSPEND_WAKEUP_DELAY 200` + * set the number of milliseconde to pause after sending a wakeup packet * `#define F_SCL 100000L` * sets the I2C clock rate speed for keyboards using I2C. The default is `400000L`, except for keyboards using `split_common`, where the default is `100000L`. -- cgit v1.2.3 From 620a946d01477b64ee2f719141aa35400c0188c6 Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Sat, 6 Feb 2021 11:27:46 +1100 Subject: Add STM32G431 and STM32G474 board definitions. (#11793) * Add STM32G431 and STM32G474 board definitions. * Add docs. --- docs/compatible_microcontrollers.md | 4 ++++ docs/ja/compatible_microcontrollers.md | 4 ++++ 2 files changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index c1287bc33d..47a4844e7f 100644 --- a/docs/compatible_microcontrollers.md +++ b/docs/compatible_microcontrollers.md @@ -26,6 +26,10 @@ You can also use any ARM chip with USB that [ChibiOS](https://www.chibios.org) s * [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html) * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html) * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) + * [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) + * [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) + * [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) + * [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) ### NXP (Kinetis) diff --git a/docs/ja/compatible_microcontrollers.md b/docs/ja/compatible_microcontrollers.md index 31d362d092..fdd11f14fa 100644 --- a/docs/ja/compatible_microcontrollers.md +++ b/docs/ja/compatible_microcontrollers.md @@ -31,6 +31,10 @@ QMK は十分な容量のフラッシュメモリを備えた USB 対応 AVR ま * [STM32F0x2](https://www.st.com/en/microcontrollers-microprocessors/stm32f0x2.html) * [STM32F103](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html) * [STM32F303](https://www.st.com/en/microcontrollers-microprocessors/stm32f303.html) +* [STM32F401](https://www.st.com/en/microcontrollers-microprocessors/stm32f401.html) +* [STM32F411](https://www.st.com/en/microcontrollers-microprocessors/stm32f411.html) +* [STM32G431](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x1.html) +* [STM32G474](https://www.st.com/en/microcontrollers-microprocessors/stm32g4x4.html) ### NXP (Kinetis) -- cgit v1.2.3 From 7161d650705afb86b0874d95d72d15cf134f4148 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Tue, 9 Feb 2021 09:49:05 -0800 Subject: Remove FAUXCLICKY feature (deprecated) (#11829) --- docs/feature_audio.md | 6 ------ docs/getting_started_make_guide.md | 4 ---- docs/ja/feature_audio.md | 6 ------ docs/ja/getting_started_make_guide.md | 4 ---- 4 files changed, 20 deletions(-) (limited to 'docs') diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 5132dfe971..68ba4477a5 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -215,12 +215,6 @@ This is still a WIP, but check out `quantum/process_keycode/process_midi.c` to s AU_OFF, AU_TOG, - #ifdef FAUXCLICKY_ENABLE - FC_ON, - FC_OFF, - FC_TOG, - #endif - // Music mode on/off/toggle MU_ON, MU_OFF, diff --git a/docs/getting_started_make_guide.md b/docs/getting_started_make_guide.md index ad63a1c2ec..7198576e3a 100644 --- a/docs/getting_started_make_guide.md +++ b/docs/getting_started_make_guide.md @@ -121,10 +121,6 @@ For further details, as well as limitations, see the [Unicode page](feature_unic This allows you output audio on the C6 pin (needs abstracting). See the [audio page](feature_audio.md) for more information. -`FAUXCLICKY_ENABLE` - -Uses buzzer to emulate clicky switches. A cheap imitation of the Cherry blue switches. By default, uses the C6 pin, same as `AUDIO_ENABLE`. - `VARIABLE_TRACE` Use this to debug changes to variable values, see the [tracing variables](unit_testing.md#tracing-variables) section of the Unit Testing page for more information. diff --git a/docs/ja/feature_audio.md b/docs/ja/feature_audio.md index 2d13c3f7cc..ca7820e3c4 100644 --- a/docs/ja/feature_audio.md +++ b/docs/ja/feature_audio.md @@ -220,12 +220,6 @@ const uint8_t music_map[MATRIX_ROWS][MATRIX_COLS] = LAYOUT_ortho_4x12( AU_OFF, AU_TOG, - #ifdef FAUXCLICKY_ENABLE - FC_ON, - FC_OFF, - FC_TOG, - #endif - // Music mode on/off/toggle MU_ON, MU_OFF, diff --git a/docs/ja/getting_started_make_guide.md b/docs/ja/getting_started_make_guide.md index 08005877e7..45284a0b9f 100644 --- a/docs/ja/getting_started_make_guide.md +++ b/docs/ja/getting_started_make_guide.md @@ -110,10 +110,6 @@ make コマンド自体にもいくつかの追加オプションがあります C6 ピン(抽象化が必要)でオーディオ出力できます。詳細は[オーディオページ](ja/feature_audio.md)を見てください。 -`FAUXCLICKY_ENABLE` - -クリック音のあるスイッチをエミュレートするためにブザーを使います。Cherry社製の青軸スイッチの安っぽい模倣です。デフォルトでは、`AUDIO_ENABLE` と同じように C6 ピンを使います。 - `VARIABLE_TRACE` これを使って変数の値の変更をデバッグします。詳細についてはユニットテストのページの[変数のトレース](ja/unit_testing.md#tracing-variables)のセクションを見てください。 -- cgit v1.2.3 From c80e5f9f8868ccaa8cb990be6f4da3f1011c2b78 Mon Sep 17 00:00:00 2001 From: Drashna Jaelre Date: Sun, 14 Feb 2021 14:40:38 -0800 Subject: Audio system overhaul (#11820) * Redo Arm DAC implementation for additive, wavetable synthesis, sample playback changes by Jack Humbert on an implementation for DAC audio on arm/chibios platforms this commits bundles the changes from the arm-dac-work branch focused on audio/audio_arm.* into one commit (leaving out the test-keyboard) f52faeb5d (origin/arm-dac-work) add sample and wavetable examples, parsers for both -> only the changes on audio_arm_.*, the keyboard related parts are split off to a separate commit bfe468ef1 start morphing wavetable 474d100b5 refined a bit 208bee10f play_notes working 3e6478b0b start in-place documentation of dac settings 3e1826a33 fixed blip (rounding error), other waves, added key selection (left/right) 73853d651 5 voices at 44.1khz dfb401b95 limit voices to working number 9632b3379 configuration for the ez 6241f3f3b notes working in a new way * Redo Arm DAC implementation for additive, wavetable synthesis, sample playback changes by Jack Humbert on an implementation for DAC audio on arm/chibios platforms this commit splits off the plank example keymap from commit f52faeb5d (origin/arm-dac-work) add sample and wavetable examples, parsers for both * refactoring: rename audio_ to reflect their supported hardware-platform and audio-generation method: avr vs arm, and pwm vs dac * refactoring: deducplicate ISR code to update the pwm duty-cycle and period in the avr-pwm-implementation pulls three copies of the same code into one function which should improve readability and maintainability :-) * refactoring: move common code of arm and avr implementation into a separate/new file * refactoring: audio_avr_pwm, renaming defines to decouple them from actually used timers, registers and ISRs * refactoring: audio_avr_pwm - replacing function defines with plain register defines aligns better with other existing qmk code (and the new audio_arm_pwm) doing similar pwm thing * add audio-arm-pwm since not all STM32 have a DAC onboard (STM32F2xx and STM32F3xx), pwm-audio is an alternative (STM32F1xx) this code works on a "BluePill" clone, with an STM32F103C8B * clang-format changes on quantum/audio/* only * audio_arm_dac: stopping the notes caused screeching when using the DAC audio paths * audio_arm_pwm: use pushpull on the pin; so that a piezzo can be hooked up direclty without additional components (opendrain would require an external pullup) * refactoring: remove unused file from/for atmel-avr chips * refactoring: remove unused (avr) wavetable file * audio_arm_dac: adapt dac_end callback to changed chibios DAC api the previous chibios (17.6.0) passed along a pointer into the buffer plus a sample_count (which are/already where included in the DACDrivre object) - the current chibios (19.1.0) only passes the driver object. this patch ports more or less exactly what the previous chibios ISR code did: either have the user-callback work the first or second half of the buffer (dacsample_t pointer, with half the DAC_BUFFER_SIZE samples) by adjusting the pointer and sample count * audio-arm-dac: show a compile-warning on undefined audio-pins Co-Authored-By: Drashna Jaelre * audio_arm_dac: switch from exemplary wavetable generation to sine only sine+triangle+squrare is exemplary, and not realy fit for "production" use 'stairs' are usefull for debugging (hardware, with an oscilloscope) * audio_arm_dac: enable output buffers in the STM32 to drive external loads without any additional ciruitry - external opamps and such * audio: prevent out-of-bounds array access * audio_arm_dac: add output-frequency correcting factor * audio_arm_pwm: get both the alternate-function and pm-callback variants back into working condition and do some code-cleanup, refine documentation, ... * audio_arm_pwm: increase pwm frequency for "higher fidelity" on the previous .frequency=100000 higher frequency musical notes came out wrong (frequency measured on a Tektronix TDS2014B) note | freq | arm-pwm C2 | 65.4 | 65.491 C5 | 523.25 | 523.93 C6 | 1046.5 | 1053.38 C7 | 2093 | 2129 C8 | 4186 | 4350.91 with .frequency = 500000 C8 | 4186 | 4204.6 * audio refactoring: remove unused variables * audio_arm_dac: calibrate note tempo: with a tempo of 60beats-per-second a whole-note should last for exactly one second * audio: allow feature selection in rules.mk so the user can switch the audio driver between DAC and PWM on STM32 boards which support both (STM32F2 and up) or select the "pin alternate" pwm mode, for example on STM32F103 * audio-refactoring: move codeblocks in audio.[ch] into more coherent groups and add some inline documentation * audio-refactoring: cleanup and streamline common code between audio_arm_[dac|pwm] untangeling the relation between audio.c and the two drivers and adding more documenting comments :-) * audio_avr_pwm: getting it back into working condition, and cleanup+refactor * audio-refactoring: documentation and typo fixes Co-Authored-By: Nick Brassel * audio-refactoring: cleanup defines, inludes and remove debug-prints * audio_chibios_dac: define&use a minimal sampling rate, based on the available tone-range to ease up on the cpu-load, while still rendering the higher notes/tones sufficiently also reenable the lower tones, since with the new implementation there is no evidence of them still beeing 'bugged' * audio-refactoring: one common AUDIO_MAX_VOICES define for all audio-drivers * audio-chibios-pwm: pwm-pin-allternate: make the the timer, timer-channel and alternate function user-#definable * audio_chibios_dac: math.h has fmod for this * Redo Arm DAC implementation for additive, wavetable synthesis, sample playback update Jack Humberts dac-example keymaps for the slight changes in the audio-dac interface * audio-refactoring: use a common AUDIO_PIN configuration switch instead of defines have the user select a pin by configuration in rules.mk instead of a define in config.h has the advantage of beeing in a common form/pattern across all audio-driver implementations * audio-refactoring: switch backlight_avr.c to the new AUDIO_PIN defines * audio-common: have advance_note return a boolean if the note changed, to the next one in the melody beeing played * audio-chibios-pwm: fix issue with ~130ms silence between note/frequency changes while playing a SONG through trial,error and a scope/logic analyzer figured out Chibios-PWMDriver (at least in the current version) misbehaves if the initial period is set to zero (or one; two seems to work); when thats the case subsequent calls to 'pwmChhangePeriod' + pwmEnableChannel took ~135ms of silence, before the PWM continued with the new frequency... * audio-refactoring: get 'play_note' working again with a limited number of available voices (say AUDIO_VOICES_MAX=1) allow new frequencies to be played, by discarding the oldest one in the 'frequencies' queue * audio: set the fallback driver to DAC for chibios and PWM for all others (==avr at the moment) * audio-refactoring: moore documentation and some cleanup * audio-avr-pwm: no fallback on unset AUDIO_PIN this seems to be the expected behaviour by some keyboards (looking at ckeys/handwire_101:default) which otherwise fail to build because the firmware-image ends up beeing too large for the atmega... so we fail silently instead to keep travis happy * audio-refactoring: untangling terminology: voice->tone the code actually was working on tones (combination of pitch/frequency, duration, timbre, intensity/volume) and not voices (characteristic sound of an instrument; think piano vs guitar, which can be played together, each having its own "track" = voice on a music sheet) * audio-pwm: allow freq=0 aka a pause/rest in a SONG continue processing, but do not enable pwm units, since freq=0 wouldn't produce any sound anyway (and lead to division by zero on that occasion) * audio-refactoring: audio_advance_note -> audio_advance_state since it does not only affect 'one note', but the internally kept state as a whole * audio-refactoring: untangling terminology: polyphony the feature om the "inherited" avr code has little to do with polyphony (see wikipedia), but is more a time-multiplexing feature, to work around hardware limitations - like only having one pwm channel, that could on its own only reproduce one voice/instrument at a time * audio-chibios-dac: add zero-crossing feature have tones only change/stop when the waveform approaches zero - to avoid audible clicks note that this also requires the samples to start at zero, since the internally kept index into the samples is reset to zero too * audio-refactoring: feature: time-multiplexing of tones on a single output channel this feature was in the original avr-pwm implementation misnomed as "polyphony" with polyphony_rate and so on; did the same thing though: time-multiplexing multiple active notes so that a single output channel could reproduce more than one note at a time (which is not the same as a polyphony - see wikipedia :-) ) * audio-avr-pwm: get music-mode working (again) on AVRs with both pwm channels, or either one of the two :-) play_notes worked already - but music_mode uses play_note * audio-refactoring: split define MAX_SIMULTANEOUS_TONES -> TONE_STACKSIZE since the two cases are independant from one another, the hardware might impose limitations on the number of simultaneously reproducable tones, but the audio state should be able to track an unrelated number of notes recently started by play_note * audio-arm-dac: per define selectable sample-luts plus generation script in ./util * audio-refactoring: heh, avr has a MIN... * audio-refactoring: add basic dac audio-driver based on the current/master implementation whereas current=d96380e65496912e0f68e6531565f4b45efd1623 which is the state of things before this whole audio-refactoring branch boiled down to interface with the refactored audio system = removing all redundant state-managing and frequency calculation * audio-refactoring: rename audio-drivers to driver_$PLATFORM_$DRIVER * audio-arm-pwm: split the software/hardware implementations into separate files which saves us partially from a 'define hell', with the tradeoff that now two somewhat similar chibios_pwm implementations have to be maintained * audio-refactoring: update documentation * audio-arm-dac: apply AUDIO_PIN defines to driver_chibios_dac_basic * audio-arm-dac: dac_additive: stop the hardware when the last sample completed the audio system calls for a driver_stop, which is delayed until the current sample conversion finishes * audio-refactoring: make function-namespace consistent - all (public) audio functions start with audio_ - also refactoring play*_notes/tones to play*_melody, to visually distance it a bit from play*_tone/_note * audio-refactoring: consistent define namespace: DAC_ -> AUDIO_DAC_ * audio-arm-dac: update (inline) documentation regarding MAX for sample values * audio-chibios-dac: remove zero-crossing feature didn't quite work as intended anyway, and stopping the hardware on close-to-zero seems to be enought anyway * audio-arm-dac: dac_basic: respect the configured sample-rate * audio-arm-pwm: have 'note_timbre' influence the pwm-duty cycle like it already does in the avr implementation * audio-refactoring: get VIBRATO working (again) with all drivers (verified with chibios_[dac|pwm]) * audio-arm-dac: zero-crossing feature (Mk II) wait for the generated waveform to approach 'zero' before either turning off the output+timer or switching to the current set of active_tones * audio-refactoring: re-add note-resting -> introduce short_rest inbetween - introduce a short pause/rest between two notes of the same frequency, to separate them audibly - also updating the refactoring comments * audio-refactoring: cleanup refactoring remnants remove the former avr-isr code block - since all its features are now refactored into the different parts of the current system also updates the TODOS * audio-refactoring: reserve negative numbers as unitialized frequencies to allow the valid tone/frequency f=0Hz == rest/pause * audio-refactoring: FIX: first note of melody was missing the first note was missing because 'goto_next_note'=false overrode a state_change=true of the initial play_tone and some code-indentations/cleanup of related parts * audio-arm-dac: fix hardware init-click due to wron .init= value * audio-refactoring: new conveniance function: audio_play_click which can be used to further refactor/remove fauxclicky (avr only) and/or the 'clicky' features * audio-refactoring: clang-format on quantum/audio/* * audio-avr-pwm: consecutive notes of the same frequency get a pause inserted inbetween by audio.c * audio-refactoring: use milliseconds instead of seconds for 'click' parameters clicks are supposed to be short, seconds make little sense * audio-refactoring: use timer ticks instead of counters local counters were used in the original (avr)ISR to advance an index into the lookup tables (for vibrato), and something similar was used for the tone-multiplexing feature decoupling these from the (possibly irregular) calls to advance_state made sesne, since those counters/lookups need to be in relation to a wall-time anyway * audio-refactoring: voices.c: drop 'envelope_index' counter in favour of timer ticks * audio-refactoring: move vibrato and timbre related parts from audio.c to voices.c also drops the now (globally) unused AUDIO_VIBRATO/AUDIO_ENABLE_VIBRATO defines * audio.c: use system-ticks instead of counters the drivers have to take care of for the internal state posision since there already is a system-tick with ms resolution, keeping count separatly with each driver implementation makes little sense; especially since they had to take special care to call audio_advance_state with the correct step/end parameters for the audio state to advance regularly and with the correct pace * audio.c: stop notes after new ones have been started avoids brief states of with no notes playing that would otherwise stop the hardware and might lead to clicks * audio.c: bugfix: actually play a pause instead of just idling/stopping which lead the pwm drivers to stop entirely... * audio-arm-pwm: pwm-software: add inverted output new define AUDIO_PIN_ALT_AS_NEGATIVE will generate an inverted signal on the alternate pin, which boosts the volume if a piezo is connected to both AUDIO_PIN and AUDIO_PIN_ALT * audio-arm-dac: basic: handle piezo configured&wired to both audio pins * audio-refactoring: docs: update for AUDIO_PIN_ALT_AS_NEGATIVE and piezo wiring * audio.c: bugfix: use timer_elapsed32 instad of keeping timestamps avoids running into issues when the uint32 of the timer overflows * audio-refactoring: add 'pragma once' and remove deprecated NOTE_REST * audio_arm_dac: basic: add missing bracket * audio.c: fix delta calculation was in the wrong place, needs to use the 'last_timestamp' before it was reset * audio-refactoring: buildfix: wrong legacy macro for set_timbre * audio.c: 16bit timerstamps suffice * audio-refactoring: separate includes for AVR and chibios * audio-refactoring: timbre: use uint8 instead of float * audio-refactoring: duration: use uint16 for internal per-tone/note state * audio-refactoring: tonemultiplexing: use uint16 instead of float * audio-arm-dac: additive: set second pin output-low used when a piezo is connected to AUDIO_PIN and AUDIO_PIN_ALT, with PIN_ALT_AS_NEGATIVE * audio-refactoring: move AUDIO_PIN selection from rules.mk to config.h to be consistent with how other features are handled in QMK * audio-refactoring: buildfix: wrong legacy macro for set_tempo * audio-arm-dac: additive: set second pin output-low -- FIXUP * audio.c: do duration<>ms conversion in uint instead of float on AVR, to save a couple of bytes in the firmware size * audio-refactoring: cleanup eeprom defines/usage for ARM, avr is handled automagically through the avr libc and common_features.mk Co-Authored-By: Drashna Jaelre * audio.h: throw an error if OFF is larger than MAX * audio-arm-dac: basic: actually stop the dac-conversion on a audio_driver_stop to put the output pin in a known state == AUDIO_DAC_OFF_VALUE, instead of just leaving them where the last conversion was... with AUDIO_PIN_ALT_AS_NEGATIVE this meant one output was left HIGH while the other was left LOW one CAVEAT: due to this change the opposing squarewave when using both A4 and A5 with AUDIO_PIN_ALT_AS_NEGATIVE show extra pulses at the beginning/end on one of the outputs, the two waveforms are in sync otherwise. the extra pusles probably matter little, since this is no high-fidelity sound generation :P * audio-arm-dac: additive: move zero-crossing code out of dac_value_generate which is/should be user-overridable == simple, and doing one thing: providing sample values state-transitions necessary for the zero crossing are better handled in the surrounding loop in the dac_end callback * audio-arm-dac: dac-additive: zero-crossing: ramping up or down after a start trigger ramp up: generate values until zero=OFF_VALUE is reached, then continue normally same in reverse for strop trigger: output values until zero is reached/crossed, then keep OFF_VALUE on the output * audio-arm-dac: dac-additive: BUGFIX: return OFF_VALUE when a pause is playing fixes a bug during SONG playback, which suddenly stopped when it encoutnered a pause * audio-arm-dac: set a sensible default for AUDIO_DAC_VALUE_OFF 1/2 MAX was probably exemplary, can't think of a setup where that would make sense :-P * audio-arm-dac: update synth_sample/_wavetable for new pin-defines * audio-arm-dac: default for AUDIO_DAC_VALUE_OFF turned out that zero or max are bad default choices: when multiple tones are played (>>5) and released at the same time (!), due to the complex waveform never reaching 'zero' the output can take quite a while to reach zero, and hence the zero-crossing code only "releases" the output waaay to late * audio-arm-dac: additive: use DAC for negative pin instead of PAL, which only allows the pin to be configured as output; LOW or HIGH * audio-arm-dac: more compile-time configuration checks * audio-refactoring: typo fixed * audio-refactoring: clang-format on quantum/audio/* * audio-avr-pwm: add defines for B-pin as primary/only speaker also updates documentation. * audio-refactoring: update documentation with proton-c config.h example * audio-refactoring: move glissando (TODO) to voices.c refactored/saved from the original glissando implementation in then upstream-master:audio_avr.c still needs some work though, as it is now the calculation *should* work, but the start-frequency needs to be tracked somewhere/somehow; not only during a SONG playback but also with user input? * audio-refactoring: cleanup: one round of aspell -c * audio-avr-pwm: back to AUDIO_PIN since config_common.h expands them to plain integers, the AUDIO_PIN define can directly be compared to e.g. B5 so there is no need to deal with separate defines like AUDIO_PIN_B5 * audio-refactoring: add technical documentation audio_driver.md which moves some in-code documentation there * audio-arm-dac: move AUDIO_PIN checks into c-code instead of doing everything with the preprocessor, since A4/A5 do not expand to simple integers, preprocessor int-comparison is not possible. but necessary to get a consistent configuration scheme going throughout the audio-code... solution: let c-code handle the different AUDIO_PIN configurations instead (and leave code/size optimizations to the compiler) * audio-arm-dac: compile-fix: set AUDIO_PIN if unset workaround to get the build going again, and be backwarts compatible to arm-keyboards which not yet set the AUDIO_PIN define. until the define is enforced through an '#error" * audio-refactoring: document tone-multiplexing feature * audio-refactoring: Apply suggestions from documentation review Co-authored-by: James Young <18669334+noroadsleft@users.noreply.github.com> * audio-refactoring: Update docs/audio_driver.md * audio-refactoring: docs: fix markdown newlines Terminating a line in Markdown with -- creates an HTML single-line break (
). Co-authored-by: James Young <18669334+noroadsleft@users.noreply.github.com> * audio-arm-dac: additive: fix AUDIO_PIN_ALT handling * audio-arm-pwm: align define naming with other drivers Co-authored-by: Joel Challis * audio-refactoring: set detault tempo to 120 and add documentation for the override * audio-refactoring: update backlight define checks to new AUDIO_PIN names * audio-refactoring: reworking PWM related defines to be more consistent with other QMK code Co-authored-by: Joel Challis * audio-arm: have the state-update-timer user configurable defaulting to GPTD6 or GPTD8 for stm32f2+ (=proton-c) stm32f1 might need to set this to GPTD4, since 6 and 8 are not available * audio-refactoring: PLAY_NOTE_ARRAY was already removed in master * Add prototype for startup * Update chibiOS dac basic to disable pins on stop * Add defaults for Proton C * avoid hanging audio if note is completely missed * Don't redefine pins if they're already defined * Define A4 and A5 for CTPC support * Add license headers to keymap files * Remove figlet? comments * Add DAC config to audio driver docs * Apply suggestions from code review Co-authored-by: Jack Humbert * Add license header to py files * correct license header * Add JohSchneider's name to modified files AKA credit where credit's due * Set executable permission and change interpeter * Add 'wave' to pip requirements * Improve documentation * Add some settings I missed * Strip AUDIO_DRIVER to parse the name correctly * fix depreciated * Update util/audio_generate_dac_lut.py Co-authored-by: Jack Humbert * Fix type in clueboard config * Apply suggestions from tzarc Co-authored-by: Nick Brassel Co-authored-by: Johannes Co-authored-by: JohSchneider Co-authored-by: Nick Brassel Co-authored-by: James Young <18669334+noroadsleft@users.noreply.github.com> Co-authored-by: Joel Challis Co-authored-by: Joshua Diamond Co-authored-by: Jack Humbert --- docs/_summary.md | 1 + docs/audio_driver.md | 221 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/config_options.md | 12 ++- docs/feature_audio.md | 143 ++++++++++++++++++++++++++++---- 4 files changed, 360 insertions(+), 17 deletions(-) create mode 100644 docs/audio_driver.md (limited to 'docs') diff --git a/docs/_summary.md b/docs/_summary.md index 526caf926f..acbfcfaeda 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -133,6 +133,7 @@ * [Compatible Microcontrollers](compatible_microcontrollers.md) * [Drivers](hardware_drivers.md) * [ADC Driver](adc_driver.md) + * [Audio Driver](audio_driver.md) * [I2C Driver](i2c_driver.md) * [SPI Driver](spi_driver.md) * [WS2812 Driver](ws2812_driver.md) diff --git a/docs/audio_driver.md b/docs/audio_driver.md new file mode 100644 index 0000000000..7cd5a98d9f --- /dev/null +++ b/docs/audio_driver.md @@ -0,0 +1,221 @@ +# Audio Driver :id=audio-driver + +The [Audio feature](feature_audio.md) breaks the hardware specifics out into separate, exchangeable driver units, with a common interface to the audio-"core" - which itself handles playing songs and notes while tracking their progress in an internal state, initializing/starting/stopping the driver as needed. + +Not all MCUs support every available driver, either the platform-support is not there (yet?) or the MCU simply does not have the required hardware peripheral. + + +## AVR :id=avr + +Boards built around an Atmega32U4 can use two sets of PWM capable pins, each driving a separate speaker. +The possible configurations are: + +| | Timer3 | Timer1 | +|--------------|-------------|--------------| +| one speaker | C4,C5 or C6 | | +| one speaker | | B4, B5 or B7 | +| two speakers | C4,C5 or C6 | B4, B5 or B7 | + +Currently there is only one/default driver for AVR based boards, which is automatically configured to: + +```make +AUDIO_DRIVER = pwm_hardware +``` + + +## ARM :id=arm + +For Arm based boards, QMK depends on ChibiOS - hence any MCU supported by the later is likely usable, as long as certain hardware peripherals are available. + +Supported wiring configurations, with their ChibiOS/MCU peripheral requirement are listed below; +piezo speakers are marked with :one: for the first/primary and :two: for the secondary. + + | driver | GPTD6
Tim6 | GPTD7
Tim7 | GPTD8
Tim8 | PWMD11
Tim1_Ch1 | + |--------------|------------------------------------------|------------------------|---------------|-------------------------------| + | dac_basic | A4+DACD1 = :one: | A5+DACD2 = :one: | state | | + | | A4+DACD1 = :one: + Gnd | A5+DACD2 = :two: + Gnd | state | | + | | A4+DACD1 = :two: + Gnd | A5+DACD2 = :one: + Gnd | state | | + | | A4+DACD1 = :one: + Gnd | | state | | + | | | A5+DACD2 = :one: + Gnd | state | | + | dac_additive | A4+DACD1 = :one: + Gnd | | | | + | | A5+DACD2 = :one: + Gnd | | | | + | | A4+DACD1 + A5+DACD2 = :one: 2 | | | | + | pwm_software | state-update | | | any = :one: | + | pwm hardware | state-update | | | A8 = :one: 3 | + + +1: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet +2: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set +3: TIM1_CH1 = A8 on STM32F103C8, other combinations are possible, see Data-sheet. configured with: AUDIO_PWM_DRIVER and AUDIO_PWM_CHANNEL + + + +### DAC basic :id=dac-basic + +The default driver for ARM boards, in absence of an overriding configuration. +This driver needs one Timer per enabled/used DAC channel, to trigger conversion; and a third timer to trigger state updates with the audio-core. + +Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8: + +``` c +//halconf.h: +#define HAL_USE_DAC TRUE +#define HAL_USE_GPT TRUE +#include_next +``` + +``` c +// mcuconf.h: +#include_next +#undef STM32_DAC_USE_DAC1_CH1 +#define STM32_DAC_USE_DAC1_CH1 TRUE +#undef STM32_DAC_USE_DAC1_CH2 +#define STM32_DAC_USE_DAC1_CH2 TRUE +#undef STM32_GPT_USE_TIM6 +#define STM32_GPT_USE_TIM6 TRUE +#undef STM32_GPT_USE_TIM7 +#define STM32_GPT_USE_TIM7 TRUE +#undef STM32_GPT_USE_TIM8 +#define STM32_GPT_USE_TIM8 TRUE +``` + +?> Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable). + +You can also change the timer used for the overall audio state by defining the driver. For instance: + +```c +#define AUDIO_STATE_TIMER GPTD9 +``` + +### DAC additive :id=dac-additive + +only needs one timer (GPTD6, Tim6) to trigger the DAC unit to do a conversion; the audio state updates are in turn triggered during the DAC callback. + +Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6: + +``` c +//halconf.h: +#define HAL_USE_DAC TRUE +#define HAL_USE_GPT TRUE +#include_next +``` + +``` c +// mcuconf.h: +#include_next +#undef STM32_DAC_USE_DAC1_CH1 +#define STM32_DAC_USE_DAC1_CH1 TRUE +#undef STM32_DAC_USE_DAC1_CH2 +#define STM32_DAC_USE_DAC1_CH2 TRUE +#undef STM32_GPT_USE_TIM6 +#define STM32_GPT_USE_TIM6 TRUE +``` + +### DAC Config + +| Define | Defaults | Description --------------------------------------------------------------------------------------------- | +| `AUDIO_DAC_SAMPLE_MAX` | `4095U` | Highest value allowed. Lower value means lower volume. And 4095U is the upper limit, since this is limited to a 12 bit value. Only effects non-pregenerated samples. | +| `AUDIO_DAC_OFF_VALUE` | `AUDIO_DAC_SAMPLE_MAX / 2` | The value of the DAC when notplaying anything. Some setups may require a high (`AUDIO_DAC_SAMPLE_MAX`) or low (`0`) value here. | +| `AUDIO_MAX_SIMULTANEOUS_TONES` | __see next table__ | The number of tones that can be played simultaneously. A value that is too high may freeze the controller or glitch out when too many tones are being played. | +| `AUDIO_DAC_SAMPLE_RATE` | __see next table__ | Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality. | + +There are a number of predefined quality settings that you can use, with "sane minimum" being the default. You can use custom values by simply defining the sample rate and number of simultaneous tones, instead of using one of the listed presets. + +| Define | Sample Rate | Simultaneous tones | +| `AUDIO_DAC_QUALITY_VERY_LOW` | `11025U` | `8` | +| `AUDIO_DAC_QUALITY_LOW` | `22040U` | `4` | +| `AUDIO_DAC_QUALITY_HIGH` | `44100U` | `2` | +| `AUDIO_DAC_QUALITY_VERY_HIGH` | `88200U` | `1` | +| `AUDIO_DAC_QUALITY_SANE_MINIMUM` | `16384U` | `8` | + + +```c + /* zero crossing (or approach, whereas zero == DAC_OFF_VALUE, which can be configured to anything from 0 to DAC_SAMPLE_MAX) + * ============================*=*========================== AUDIO_DAC_SAMPLE_MAX + * * * + * * * + * --------------------------------------------------------- + * * * } AUDIO_DAC_SAMPLE_MAX/100 + * --------------------------------------------------------- AUDIO_DAC_OFF_VALUE + * * * } AUDIO_DAC_SAMPLE_MAX/100 + * --------------------------------------------------------- + * * + * * * + * * * + * =====*=*================================================= 0x0 + */ +``` + + +### PWM hardware :id=pwm-hardware + +This driver uses the ChibiOS-PWM system to produce a square-wave on specific output pins that are connected to the PWM hardware. +The hardware directly toggles the pin via its alternate function. See your MCU's data-sheet for which pin can be driven by what timer - looking for TIMx_CHy and the corresponding alternate function. + +A configuration example for the STM32F103C8 would be: +``` c +//halconf.h: +#define HAL_USE_PWM TRUE +#define HAL_USE_PAL TRUE +#define HAL_USE_GPT TRUE +#include_next +``` + +``` c +// mcuconf.h: +#include_next +#undef STM32_PWM_USE_TIM1 +#define STM32_PWM_USE_TIM1 TRUE +#undef STM32_GPT_USE_TIM4 +#define STM32_GPT_USE_TIM4 TRUE +``` + +If we now target pin A8, looking through the data-sheet of the STM32F103C8, for the timers and alternate functions +- TIM1_CH1 = PA8 <- alternate0 +- TIM1_CH2 = PA9 +- TIM1_CH3 = PA10 +- TIM1_CH4 = PA11 + +with all this information, the configuration would contain these lines: +``` c +//config.h: +#define AUDIO_PIN A8 +#define AUDIO_PWM_DRIVER PWMD1 +#define AUDIO_PWM_CHANNEL 1 +#define AUDIO_STATE_TIMER GPTD4 +``` + +ChibiOS uses GPIOv1 for the F103, which only knows of one alternate function. +On 'larger' STM32s, GPIOv2 or GPIOv3 are used; with them it is also necessary to configure `AUDIO_PWM_PAL_MODE` to the correct alternate function for the selected pin, timer and timer-channel. + + +### PWM software :id=pwm-software + +This driver uses the PWM callbacks from PWMD1 with TIM1_CH1 to toggle the selected AUDIO_PIN in software. +During the same callback, with AUDIO_PIN_ALT_AS_NEGATIVE set, the AUDIO_PIN_ALT is toggled inversely to AUDIO_PIN. This is useful for setups that drive a piezo from two pins (instead of one and Gnd). + +You can also change the timer used for software PWM by defining the driver. For instance: + +```c +#define AUDIO_STATE_TIMER GPTD8 +``` + + +### Testing Notes :id=testing-notes + +While not an exhaustive list, the following table provides the scenarios that have been partially validated: + +| | DAC basic | DAC additive | PWM hardware | PWM software | +|--------------------------|--------------------|--------------------|--------------------|--------------------| +| Atmega32U4 | :o: | :o: | :heavy_check_mark: | :o: | +| STM32F103C8 (bluepill) | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: | +| STM32F303CCT6 (proton-c) | :heavy_check_mark: | :heavy_check_mark: | ? | :heavy_check_mark: | +| STM32F405VG | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | +| L0xx | :x: (no Tim8) | ? | ? | ? | + + +:heavy_check_mark: : works and was tested +:o: : does not apply +:x: : not supported by MCU + +*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.* diff --git a/docs/config_options.md b/docs/config_options.md index 9a64b9b3d2..aeaaf47aaf 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -67,16 +67,22 @@ This is a C header file that is one of the first things included, and will persi * turns on the alternate audio voices (to cycle through) * `#define C4_AUDIO` * enables audio on pin C4 + * Deprecated. Use `#define AUDIO_PIN C4` * `#define C5_AUDIO` * enables audio on pin C5 + * Deprecated. Use `#define AUDIO_PIN C5` * `#define C6_AUDIO` * enables audio on pin C6 + * Deprecated. Use `#define AUDIO_PIN C6` * `#define B5_AUDIO` - * enables audio on pin B5 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO) + * enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins) + * Deprecated. Use `#define AUDIO_PIN B5`, or use `#define AUDIO_PIN_ALT B5` if a `C` pin is enabled with `AUDIO_PIN` * `#define B6_AUDIO` - * enables audio on pin B6 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO) + * enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins) + * Deprecated. Use `#define AUDIO_PIN B6`, or use `#define AUDIO_PIN_ALT B6` if a `C` pin is enabled with `AUDIO_PIN` * `#define B7_AUDIO` - * enables audio on pin B7 (duophony is enables if one of B[5-7]\_AUDIO is enabled along with one of C[4-6]\_AUDIO) + * enables audio on pin B5 (duophony is enabled if one of B pins is enabled along with one of C pins) + * Deprecated. Use `#define AUDIO_PIN B7`, or use `#define AUDIO_PIN_ALT B7` if a `C` pin is enabled with `AUDIO_PIN` * `#define BACKLIGHT_PIN B7` * pin of the backlight * `#define BACKLIGHT_LEVELS 3` diff --git a/docs/feature_audio.md b/docs/feature_audio.md index 68ba4477a5..9e7ba75f52 100644 --- a/docs/feature_audio.md +++ b/docs/feature_audio.md @@ -1,21 +1,117 @@ # Audio -Your keyboard can make sounds! If you've got a Planck, Preonic, or basically any AVR keyboard that allows access to certain PWM-capable pins, you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes. +Your keyboard can make sounds! If you've got a spare pin you can hook up a simple speaker and make it beep. You can use those beeps to indicate layer transitions, modifiers, special keys, or just to play some funky 8bit tunes. -Up to two simultaneous audio voices are supported, one driven by timer 1 and another driven by timer 3. The following pins can be defined as audio outputs in config.h: +To activate this feature, add `AUDIO_ENABLE = yes` to your `rules.mk`. -Timer 1: -`#define B5_AUDIO` -`#define B6_AUDIO` -`#define B7_AUDIO` +## AVR based boards +On Atmega32U4 based boards, up to two simultaneous tones can be rendered. +With one speaker connected to a PWM capable pin on PORTC driven by timer 3 and the other on one of the PWM pins on PORTB driven by timer 1. -Timer 3: -`#define C4_AUDIO` -`#define C5_AUDIO` -`#define C6_AUDIO` +The following pins can be configured as audio outputs in `config.h` - for one speaker set eiter one out of: -If you add `AUDIO_ENABLE = yes` to your `rules.mk`, there's a couple different sounds that will automatically be enabled without any other configuration: +* `#define AUDIO_PIN C4` +* `#define AUDIO_PIN C5` +* `#define AUDIO_PIN C6` +* `#define AUDIO_PIN B5` +* `#define AUDIO_PIN B6` +* `#define AUDIO_PIN B7` +and *optionally*, for a second speaker, one of: +* `#define AUDIO_PIN_ALT B5` +* `#define AUDIO_PIN_ALT B6` +* `#define AUDIO_PIN_ALT B7` + +### Wiring +per speaker is - for example with a piezo buzzer - the black lead to Ground, and the red lead connected to the selected AUDIO_PIN for the primary; and similarly with AUDIO_PIN_ALT for the secondary. + + +## ARM based boards +for more technical details, see the notes on [Audio driver](audio_driver.md). + + +### DAC (basic) +Most STM32 MCUs have DAC peripherals, with a notable exception of the STM32F1xx series. Generally, the DAC peripheral drives pins A4 or A5. To enable DAC-based audio output on STM32 devices, add `AUDIO_DRIVER = dac_basic` to `rules.mk` and set in `config.h` either: + +`#define AUDIO_PIN A4` or `#define AUDIO_PIN A5` + +the other DAC channel can optionally be used with a secondary speaker, just set: + +`#define AUDIO_PIN_ALT A4` or `#define AUDIO_PIN_ALT A5` + +Do note though that the dac_basic driver is only capable of reproducing one tone per speaker/channel at a time, for more tones simultaneously, try the dac_additive driver. + +#### Wiring: +for two piezos, for example configured as `AUDIO_PIN A4` and `AUDIO_PIN_ALT A5` would be: red lead to A4 and black to Ground, and similarly with the second one: A5 = red, and Ground = black + +another alternative is to drive *one* piezo with both DAC pins - for an extra "push". +wiring red to A4 and black to A5 (or the other way round) and add `#define AUDIO_PIN_ALT_AS_NEGATIVE` to `config.h` + +##### Proton-C Example: +The Proton-C comes (optionally) with one 'builtin' piezo, which is wired to A4+A5. +For this board `config.h` would include these defines: + +```c +#define AUDIO_PIN A5 +#define AUDIO_PIN_ALT A4 +#define AUDIO_PIN_ALT_AS_NEGATIVE +``` + +### DAC (additive) +Another option, besides dac_basic (which produces sound through a square-wave), is to use the DAC to do additive wave synthesis. +With a number of predefined wave-forms or by providing your own implementation to generate samples on the fly. +To use this feature set `AUDIO_DRIVER = dac_additive` in your `rules.mk`, and select in `config.h` EITHER `#define AUDIO_PIN A4` or `#define AUDIO_PIN A5`. + +The used waveform *defaults* to sine, but others can be selected by adding one of the following defines to `config.h`: + +* `#define AUDIO_DAC_SAMPLE_WAVEFORM_SINE` +* `#define AUDIO_DAC_SAMPLE_WAVEFORM_TRIANGLE` +* `#define AUDIO_DAC_SAMPLE_WAVEFORM_TRAPEZOID` +* `#define AUDIO_DAC_SAMPLE_WAVEFORM_SQUARE` + +Should you rather choose to generate and use your own sample-table with the DAC unit, implement `uint16_t dac_value_generate(void)` with your keyboard - for an example implementation see keyboards/planck/keymaps/synth_sample or keyboards/planck/keymaps/synth_wavetable + + +### PWM (software) +if the DAC pins are unavailable (or the MCU has no usable DAC at all, like STM32F1xx); PWM can be an alternative. +Note that there is currently only one speaker/pin supported. + +set in `rules.mk`: + +`AUDIO_DRIVER = pwm_software` and in `config.h`: +`#define AUDIO_PIN C13` (can be any pin) to have the selected pin output a pwm signal, generated from a timer callback which toggles the pin in software. + +#### Wiring +the usual piezo wiring: red goes to the selected AUDIO_PIN, black goes to ground. + +OR if you can chose to drive one piezo with two pins, for example `#define AUDIO_PIN B1`, `#define AUDIO_PIN_ALT B2` in `config.h`, with `#define AUDIO_PIN_ALT_AS_NEGATIVE` - then the red lead could go to B1, the black to B2. + +### PWM (hardware) +STM32F1xx have to fall back to using PWM, but can do so in hardware; but again on currently only one speaker/pin. + +`AUDIO_DRIVER = pwm_hardware` in `rules.mk`, and in `config.h`: +`#define AUDIO_PIN A8` +`#define AUDIO_PWM_DRIVER PWMD1` +`#define AUDIO_PWM_CHANNEL 1` +(as well as `#define AUDIO_PWM_PAL_MODE 42` if you are on STM32F2 or larger) +which will use Timer 1 to directly drive pin PA8 through the PWM hardware (TIM1_CH1 = PA8). +Should you want to use the pwm-hardware on another pin and timer - be ready to dig into the STM32 data-sheet to pick the right TIMx_CHy and pin-alternate function. + + +## Tone Multiplexing +Since most drivers can only render one tone per speaker at a time (with the one exception: arm dac-additive) there also exists a "workaround-feature" that does time-slicing/multiplexing - which does what the name implies: cycle through a set of active tones (e.g. when playing chords in Music Mode) at a given rate, and put one tone at a time out through the one/few speakers that are available. + +To enable this feature, and configure a starting-rate, add the following defines to `config.h`: +```c +#define AUDIO_ENABLE_TONE_MULTIPLEXING +#define AUDIO_TONE_MULTIPLEXING_RATE_DEFAULT 10 +``` + +The audio core offers interface functions to get/set/change the tone multiplexing rate from within `keymap.c`. + + +## Songs +There's a couple of different sounds that will automatically be enabled without any other configuration: ``` STARTUP_SONG // plays when the keyboard starts up (audio.c) GOODBYE_SONG // plays when you press the RESET key (quantum.c) @@ -67,15 +163,34 @@ The available keycodes for audio are: * `AU_OFF` - Turn Audio Feature off * `AU_TOG` - Toggle Audio Feature state -!> These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely. +!> These keycodes turn all of the audio functionality on and off. Turning it off means that audio feedback, audio clicky, music mode, etc. are disabled, completely. + +## Tempo +the 'speed' at which SONGs are played is dictated by the set Tempo, which is measured in beats-per-minute. Note lenghts are defined relative to that. +The initial/default tempo is set to 120 bpm, but can be configured by setting `TEMPO_DEFAULT` in `config.c`. +There is also a set of functions to modify the tempo from within the user/keymap code: +```c +void audio_set_tempo(uint8_t tempo); +void audio_increase_tempo(uint8_t tempo_change); +void audio_decrease_tempo(uint8_t tempo_change); +``` ## ARM Audio Volume -For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `DAC_SAMPLE_MAX` in your `config.h`: +For ARM devices, you can adjust the DAC sample values. If your board is too loud for you or your coworkers, you can set the max using `AUDIO_DAC_SAMPLE_MAX` in your `config.h`: ```c -#define DAC_SAMPLE_MAX 65535U +#define AUDIO_DAC_SAMPLE_MAX 4095U ``` +the DAC usually runs in 12Bit mode, hence a volume of 100% = 4095U + +Note: this only adjusts the volume aka 'works' if you stick to WAVEFORM_SQUARE, since its samples are generated on the fly - any other waveform uses a hardcoded/precomputed sample-buffer. + +## Voices +Aka "audio effects", different ones can be enabled by setting in `config.h` these defines: +`#define AUDIO_VOICES` to enable the feature, and `#define AUDIO_VOICE_DEFAULT something` to select a specific effect +for details see quantum/audio/voices.h and .c + ## Music Mode -- cgit v1.2.3 From d1806a26e4ad75fa0e0405283803eba22c1a49ba Mon Sep 17 00:00:00 2001 From: XScorpion2 Date: Mon, 15 Feb 2021 18:30:33 -0600 Subject: Split transport mirror (#11046) * Split transport mirror support * Updated RGB Matrix to respond to electrical events instead of key events * split matrix slave fix --- docs/feature_split_keyboard.md | 6 ++++++ docs/ja/understanding_qmk.md | 1 - docs/understanding_qmk.md | 1 - 3 files changed, 6 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index c285e353d4..90af3930f9 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -191,6 +191,12 @@ communication protocol and may impact the matrix scan speed when enabled. The purpose of this feature is to support cosmetic use of modifer state (e.g. displaying status on an OLED screen). +```c +#define SPLIT_TRANSPORT_MIRROR +``` + +This mirrors the master side matrix to the slave side for features that react or require knowledge of master side key presses on the slave side. This adds a few bytes of data to the split communication protocol and may impact the matrix scan speed when enabled. The purpose of this feature is to support cosmetic use of key events (e.g. RGB reacting to Keypresses). + ### Hardware Configuration Options There are some settings that you may need to configure, based on how the hardware is set up. diff --git a/docs/ja/understanding_qmk.md b/docs/ja/understanding_qmk.md index 74b37398f8..ab860a6096 100644 --- a/docs/ja/understanding_qmk.md +++ b/docs/ja/understanding_qmk.md @@ -147,7 +147,6 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { * [`bool process_haptic(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/2cee371bf125a6ec541dd7c5a809573facc7c456/drivers/haptic/haptic.c#L216) * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/card.c#L20) * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/keymaps/default/keymap.c#L58) - * [`bool process_rgb_matrix(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/rgb_matrix.c#L139) * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_midi.c#L81) * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19) * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160) diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index 9396424258..331b1c893c 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -142,7 +142,6 @@ The `process_record()` function itself is deceptively simple, but hidden within * [`bool process_haptic(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/2cee371bf125a6ec541dd7c5a809573facc7c456/drivers/haptic/haptic.c#L216) * [`bool process_record_kb(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/card.c#L20) * [`bool process_record_user(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/keyboards/clueboard/card/keymaps/default/keymap.c#L58) - * [`bool process_rgb_matrix(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/rgb_matrix.c#L139) * [`bool process_midi(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_midi.c#L81) * [`bool process_audio(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_audio.c#L19) * [`bool process_steno(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_steno.c#L160) -- cgit v1.2.3 From 53b96f685d3399e1281747b11a1194178089706c Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 17 Feb 2021 02:51:28 +1100 Subject: RGBLight: Allow configurable default settings (#11912) * RGBLight: Allow configurable default settings * Docs --- docs/feature_rgblight.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/feature_rgblight.md b/docs/feature_rgblight.md index b5a2b179d6..d2612a6d1b 100644 --- a/docs/feature_rgblight.md +++ b/docs/feature_rgblight.md @@ -82,15 +82,20 @@ Changing the **Value** sets the overall brightness.
Your RGB lighting can be configured by placing these `#define`s in your `config.h`: -|Define |Default |Description | -|---------------------|-------------|-----------------------------------------------------------------------------| -|`RGBLIGHT_HUE_STEP` |`10` |The number of steps to cycle through the hue by | -|`RGBLIGHT_SAT_STEP` |`17` |The number of steps to increment the saturation by | -|`RGBLIGHT_VAL_STEP` |`17` |The number of steps to increment the brightness by | -|`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level | -|`RGBLIGHT_SLEEP` |*Not defined*|If defined, the RGB lighting will be switched off when the host goes to sleep| -|`RGBLIGHT_SPLIT` |*Not defined*|If defined, synchronization functionality for split keyboards is added| -|`RGBLIGHT_DISABLE_KEYCODES`|*not defined*|If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature| +|Define |Default |Description | +|---------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------| +|`RGBLIGHT_HUE_STEP` |`10` |The number of steps to cycle through the hue by | +|`RGBLIGHT_SAT_STEP` |`17` |The number of steps to increment the saturation by | +|`RGBLIGHT_VAL_STEP` |`17` |The number of steps to increment the brightness by | +|`RGBLIGHT_LIMIT_VAL` |`255` |The maximum brightness level | +|`RGBLIGHT_SLEEP` |*Not defined* |If defined, the RGB lighting will be switched off when the host goes to sleep | +|`RGBLIGHT_SPLIT` |*Not defined* |If defined, synchronization functionality for split keyboards is added | +|`RGBLIGHT_DISABLE_KEYCODES`|*Not defined* |If defined, disables the ability to control RGB Light from the keycodes. You must use code functions to control the feature| +|`RGBLIGHT_DEFAULT_MODE` |`RGBLIGHT_MODE_STATIC_LIGHT`|The default mode to use upon clearing the EEPROM | +|`RGBLIGHT_DEFAULT_HUE` |`0` (red) |The default hue to use upon clearing the EEPROM | +|`RGBLIGHT_DEFAULT_SAT` |`UINT8_MAX` (255) |The default saturation to use upon clearing the EEPROM | +|`RGBLIGHT_DEFAULT_VAL` |`RGBLIGHT_LIMIT_VAL` |The default value (brightness) to use upon clearing the EEPROM | +|`RGBLIGHT_DEFAULT_SPD` |`0` |The default speed to use upon clearing the EEPROM | ## Effects and Animations -- cgit v1.2.3 From 3345ce268610edbca8f53bc2909c547485531603 Mon Sep 17 00:00:00 2001 From: Ryan Date: Wed, 17 Feb 2021 07:26:52 +1100 Subject: Add `tap_code_delay(code, delay)` (#11913) Co-authored-by: Drashna Jaelre --- docs/feature_macros.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/feature_macros.md b/docs/feature_macros.md index aa1ebc337a..6e69ad642c 100644 --- a/docs/feature_macros.md +++ b/docs/feature_macros.md @@ -233,9 +233,15 @@ Parallel to `register_code` function, this sends the `` keyup event to the c ### `tap_code();` -This will send `register_code()` and then `unregister_code()`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it). +Sends `register_code()` and then `unregister_code()`. This is useful if you want to send both the press and release events ("tap" the key, rather than hold it). -If you're having issues with taps (un)registering, you can add a delay between the register and unregister events by setting `#define TAP_CODE_DELAY 100` in your `config.h` file. The value is in milliseconds. +If `TAP_CODE_DELAY` is defined (default 0), this function waits that many milliseconds before calling `unregister_code()`. This can be useful when you are having issues with taps (un)registering. + +If the keycode is `KC_CAPS`, it waits `TAP_HOLD_CAPS_DELAY` milliseconds instead (default 80), as macOS prevents accidental Caps Lock activation by waiting for the key to be held for a certain amount of time. + +### `tap_code_delay(, );` + +Like `tap_code()`, but with a `delay` parameter for specifying arbitrary intervals before sending the unregister event. ### `register_code16();`, `unregister_code16();` and `tap_code16();` -- cgit v1.2.3 From 624359b725c9bfe8176cf72cdc2c8bbb7513949f Mon Sep 17 00:00:00 2001 From: James Young <18669334+noroadsleft@users.noreply.github.com> Date: Sat, 27 Feb 2021 12:10:23 -0800 Subject: 2021 February 27 Breaking Changes Changelog (#11975) * restore main readme.md * add ChangeLog entry for 2021-02-27 develop branch - initial version * update Docs; consolidate sidebar entries to new Breaking Changes History doc * Changelog update - concatenate similar changes as one list item - unify change formatting (remove [bracketed] headings and trailing periods) - item sorting improvement * update Changes Requiring User Action section Detail the changes regarding keyboard relocations/additions/deletions. * add entry for fauxpark's user keymap cleanup for config.h/rules.mk * add link to Jacky Studio bugfix PR * add link for "ChibiOS conf migrations... take 15" * add links for "Make LAYOUT parsing more robust" and "Massdrop develop rgb fix" * remove sort sequence numbers * rename Breaking Changes History page Renames the Breaking Changes History page to "Past Breaking Changes". * update schedule in Breaking Changes Overview * suggestions/changes per tzarc * skully's changes * add entry for "Fix develop" (PR 12039) Co-authored-by: Nick Brassel Co-authored-by: Zach White --- docs/ChangeLog/20210227.md | 169 +++++++++++++++++++++++++++++++++++++++ docs/_summary.md | 8 +- docs/breaking_changes.md | 13 +-- docs/breaking_changes_history.md | 10 +++ 4 files changed, 188 insertions(+), 12 deletions(-) create mode 100644 docs/ChangeLog/20210227.md create mode 100644 docs/breaking_changes_history.md (limited to 'docs') diff --git a/docs/ChangeLog/20210227.md b/docs/ChangeLog/20210227.md new file mode 100644 index 0000000000..cb34edfd91 --- /dev/null +++ b/docs/ChangeLog/20210227.md @@ -0,0 +1,169 @@ +# QMK Breaking Changes - 2021 February 27 Changelog + +## Changes Requiring User Action + +The following keyboards have had their source moved within QMK: + +Old Keyboard Name | New Keyboard Name +:---------------- | :---------------- +bear_65 | jacky_studio/bear_65 +s7_elephant/rev1 | jacky_studio/s7_elephant/rev1 +s7_elephant/rev2 | jacky_studio/s7_elephant/rev2 +aplx6 | aplyard/aplx6/rev1 +southpaw75 | fr4/southpaw75 + +The [Aplyard Aplx6 rev2](https://github.com/qmk/qmk_firmware/tree/0.12.0/keyboards/aplyard/aplx6/rev1) and the [FR4Boards Unix60](https://github.com/qmk/qmk_firmware/tree/0.12.0/keyboards/fr4/unix60) have also been added as part of these changes. + +Additionally, the `handwired/bluepill/bluepill70` keyboard has been removed. + +## Core Changes + +### ChibiOS Update and Config Migration + +QMK's ChibiOS and ChibiOS-Contrib submodules have been updated to version 20.3.2. + +Along with this, QMK now provides default configuration files for all commonly-supported ARM microcontrollers running on ChibiOS. As such, keyboards are now only required to define settings which differ from the defaults, thereby reducing the size of pull requests for keyboards running atop ChibiOS. + +### QMK Infrastructure and Internals + +Python is now required to build QMK. The minimum Python version has been increased to 3.7. + +The power of `info.json` has been massively expanded. Most keyboard parameters can now be expressed in `info.json` instead of `config.h`/`rules.mk`. This should make maintaining keyboards easier, and will enable tooling that can allow non-technical users to add and maintain QMK keyboards without writing any code. + +To ease migration a new command has been provided, `qmk generate-info-json -kb `. You can use this command to generate a complete `info.json` file for a keyboard and then remove the duplicate information from `config.h` and `rules.mk`. + +Detailed example showing how to generate a new info.json and identify duplicate keys: + +``` +user@hostname:~/qmk_firmware/keyboards/lets_split:0$ qmk generate-info-json > new-info.json +user@hostname:~/qmk_firmware/keyboards/lets_split:0$ mv new-info.json info.json +user@hostname:~/qmk_firmware/keyboards/lets_split:0$ qmk info +⚠ lets_split/rev2: DEBOUNCE in config.h is overwriting debounce in info.json +⚠ lets_split/rev2: DEVICE_VER in config.h is overwriting usb.device_ver in info.json +⚠ lets_split/rev2: DIODE_DIRECTION in config.h is overwriting diode_direction in info.json +⚠ lets_split/rev2: MANUFACTURER in config.h is overwriting manufacturer in info.json +⚠ lets_split/rev2: RGB_DI_PIN in config.h is overwriting rgblight.pin in info.json +⚠ lets_split/rev2: RGBLED_NUM in config.h is overwriting rgblight.led_count in info.json +⚠ lets_split/rev2: PRODUCT_ID in config.h is overwriting usb.pid in info.json +⚠ lets_split/rev2: VENDOR_ID in config.h is overwriting usb.vid in info.json +⚠ lets_split/rev2: Matrix pins are specified in both info.json and config.h, the config.h values win. +⚠ lets_split/rev2: LAYOUTS in rules.mk is overwriting community_layouts in info.json +⚠ lets_split/rev2: Feature bootmagic is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature mousekey is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature extrakey is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature console is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature command is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature nkro is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature backlight is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature midi is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature audio is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature unicode is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature bluetooth is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature rgblight is specified in both info.json and rules.mk, the rules.mk value wins. +⚠ lets_split/rev2: Feature sleep_led is specified in both info.json and rules.mk, the rules.mk value wins. +Keyboard Name: Let's Split +Manufacturer: Wootpatoot +Website: +Maintainer: QMK Community +Keyboard Folder: lets_split/rev2 +Layouts: LAYOUT, LAYOUT_ortho_4x12 +Size: 13 x 4 +Processor: atmega32u4 +Bootloader: caterina +``` + +## Detailed Change List + +### Changes Requiring User Action + +* Refactor Jacky's boards (Bear65 and S7 Elephant) ([#10528](https://github.com/qmk/qmk_firmware/pull/10528), [#11981](https://github.com/qmk/qmk_firmware/pull/11981)) +* Remove handwired/bluepill ([#11415](https://github.com/qmk/qmk_firmware/pull/11415)) +* Aplyard Aplx6 Added rev2 & move rev1+rev2 to parent folder ([#10973](https://github.com/qmk/qmk_firmware/pull/10973)) +* added `unix60`, moved together with `southpaw75` into `fr4` folder ([#11195](https://github.com/qmk/qmk_firmware/pull/11195)) + +### Fixes + +* GCC 10 can now compile Drop Alt firmware ([#9485](https://github.com/qmk/qmk_firmware/pull/9485)) +* Fix compiling on `develop` branch ([#11409](https://github.com/qmk/qmk_firmware/pull/11409)) +* Fix broken keyboards and keymaps ([#11412](https://github.com/qmk/qmk_firmware/pull/11412), [#11427](https://github.com/qmk/qmk_firmware/pull/11427), [#11448](https://github.com/qmk/qmk_firmware/pull/11448), [#11447](https://github.com/qmk/qmk_firmware/pull/11447), [#11473](https://github.com/qmk/qmk_firmware/pull/11473), [#11584](https://github.com/qmk/qmk_firmware/pull/11584), [#11600](https://github.com/qmk/qmk_firmware/pull/11600)) +* Fixed up build dependencies so that generated files are made available before compiling any object files ([#11435](https://github.com/qmk/qmk_firmware/pull/11435)) +* Formatting fixes ([`378edd9`](https://github.com/qmk/qmk_firmware/commit/378edd9491f2ab0d3d8a970c9a8e64bc03ca15cf), [#11594](https://github.com/qmk/qmk_firmware/pull/11594), [`27749e1`](https://github.com/qmk/qmk_firmware/commit/27749e1c967c02c05e62a89a0ae2776dd7e5158c)) +* Include `stdbool.h` in `uart.h` to fix compiler errors ([#11728](https://github.com/qmk/qmk_firmware/pull/11728)) +* Decouple USB events from the USB interrupt handler in ChibiOS ([#10437](https://github.com/qmk/qmk_firmware/pull/10437)) + * Fixes an issue while using Backlight and External EEPROM at the same time that would cause the MCU to lock up. +* Address wake from sleep instability ([#11450](https://github.com/qmk/qmk_firmware/pull/11450)) +* Fix pressing media key on a momentarily activated layer may lead to missing key up events ([#11162](https://github.com/qmk/qmk_firmware/pull/11162)) +* Fix an RGB initialisation bug on Massdrop keyboards ([#12022](https://github.com/qmk/qmk_firmware/pull/12022)) +* Fix file encoding errors on Windows, and layouts not correctly merging into info.json ([#12039](https://github.com/qmk/qmk_firmware/pull/12039)) + +### Additions and Enhancements + +* Allow configuration of serial USART timeout ([#11057](https://github.com/qmk/qmk_firmware/pull/11057)) +* Added Sync Timer feature for Split Common keyboards ([#10997](https://github.com/qmk/qmk_firmware/pull/10997)) +* Add modifier state to the Split Common transport ([#10400](https://github.com/qmk/qmk_firmware/pull/10400)) +* Add Pix keyboard by sendz (`sendyyeah/pix`) ([#11154](https://github.com/qmk/qmk_firmware/pull/11154)) +* Implement option for kinetic mouse movement algorithm for mouse keys ([#6739](https://github.com/qmk/qmk_firmware/pull/6739)) +* Improved Language Specific Keycodes for US International and Extended Layouts ([#11307](https://github.com/qmk/qmk_firmware/pull/11307)) +* Modified `QWIIC_ENABLE` in `rules.mk` to be yes/no choice, adding `QWIIC_DRIVERS` to allow for inclusion of specific drivers ([#11426](https://github.com/qmk/qmk_firmware/pull/11426)) +* Allow AVR-based keyboards to override the `bootloader_jump` function ([#11418](https://github.com/qmk/qmk_firmware/pull/11418)) +* Refine RGBLight Twinkle effect to be smoother (use breathing curve) ([#11350](https://github.com/qmk/qmk_firmware/pull/11350)) +* Keep track of last matrix activity ([#10730](https://github.com/qmk/qmk_firmware/pull/10730), [`ab375d3`](https://github.com/qmk/qmk_firmware/commit/ab375d3d075c105f09a1ddd0e155f178225518bc), [#11552](https://github.com/qmk/qmk_firmware/pull/11552)) +* fix `matrix_io_delay()` timing in `quantum/matrix.c` ([#9603](https://github.com/qmk/qmk_firmware/pull/9603)) +* Keep track of encoder activity ([#11595](https://github.com/qmk/qmk_firmware/pull/11595)) +* Backport ChibiOS Audio changes from ZSA ([#11687](https://github.com/qmk/qmk_firmware/pull/11687)) +* Add support for 8 buttons to mouse report ([#10807](https://github.com/qmk/qmk_firmware/pull/10807)) +* Allow `post_config.h` to be implemented in userspace ([#11519](https://github.com/qmk/qmk_firmware/pull/11519)) +* Adds AT90USB162 support ([#11570](https://github.com/qmk/qmk_firmware/pull/11570)) +* Stop sounds when suspended ([#11553](https://github.com/qmk/qmk_firmware/pull/11553)) +* Revamp spidey3 userspace and keymaps ([#11768](https://github.com/qmk/qmk_firmware/pull/11768)) +* Add support for analog USBPD on STM32G4xx ([#11824](https://github.com/qmk/qmk_firmware/pull/11824)) +* Master matrix can now be transported to the slave side in Split Common keyboards ([#11046](https://github.com/qmk/qmk_firmware/pull/11046)) +* RGBLight: Allow configurable default settings ([#11912](https://github.com/qmk/qmk_firmware/pull/11912)) +* Add `tap_code_delay(code, delay)` ([#11913](https://github.com/qmk/qmk_firmware/pull/11913), [#11938](https://github.com/qmk/qmk_firmware/pull/11938)) + +### Clean-ups and Optimizations + +* Fix duplicate `I2C_KEYMAP_START` define ([#11237](https://github.com/qmk/qmk_firmware/pull/11237)) +* Rewrite APA102 support for RGBLight ([#10894](https://github.com/qmk/qmk_firmware/pull/10894)) +* Update ADB Protocol implementation in TMK Core ([#11168](https://github.com/qmk/qmk_firmware/pull/11168)) +* Remove unused `action_get_macro()` usages in user files ([#11165](https://github.com/qmk/qmk_firmware/pull/11165)) +* Remove `QMK_KEYBOARD_CONFIG_H` ([#11576](https://github.com/qmk/qmk_firmware/pull/11576)) +* Remove duplicated housekeeping in `arm_atsam` ([#11672](https://github.com/qmk/qmk_firmware/pull/11672)) +* UART driver refactor ([#11637](https://github.com/qmk/qmk_firmware/pull/11637)) +* Move `transport.c` to `QUANTUM_LIB_SRC` ([#11751](https://github.com/qmk/qmk_firmware/pull/11751)) +* Remove `MIDI_ENABLE_STRICT` from user keymaps ([#11750](https://github.com/qmk/qmk_firmware/pull/11750)) +* Remove legacy print backward compatiblitly ([#11805](https://github.com/qmk/qmk_firmware/pull/11805)) +* Migrate mousekey to quantum ([#11804](https://github.com/qmk/qmk_firmware/pull/11804)) +* remove deprecated `qmk json-keymap` ([#11823](https://github.com/qmk/qmk_firmware/pull/11823)) +* Remove FAUXCLICKY feature (deprecated) ([#11829](https://github.com/qmk/qmk_firmware/pull/11829)) +* Refactor platform logic within `print.h` ([#11863](https://github.com/qmk/qmk_firmware/pull/11863)) +* Audio system overhaul ([#11820](https://github.com/qmk/qmk_firmware/pull/11820)) +* Output selection: Remove "USB and BT" option for Bluetooth ([#11940](https://github.com/qmk/qmk_firmware/pull/11940)) +* `tmk_core/common/action.c`: refactor for code size; merge multiple `case`s into one ([#11943](https://github.com/qmk/qmk_firmware/pull/11943)) +* Remove rules and settings from user keymaps that are already defined at keyboard level ([#11966](https://github.com/qmk/qmk_firmware/pull/11966)) + +### QMK Infrastructure and Internals + +* bump to python 3.7 ([#11408](https://github.com/qmk/qmk_firmware/pull/11408)) +* `develop` branch is now formatted as part of CI tasks ([#11893](https://github.com/qmk/qmk_firmware/pull/11893), [#11905](https://github.com/qmk/qmk_firmware/pull/11905), [#11907](https://github.com/qmk/qmk_firmware/pull/11907), [#11928](https://github.com/qmk/qmk_firmware/pull/11928), [#11936](https://github.com/qmk/qmk_firmware/pull/11936)) +* Configure keyboard matrix from info.json ([#10817](https://github.com/qmk/qmk_firmware/pull/10817)) +* Validate our JSON data using json_schema ([#11101](https://github.com/qmk/qmk_firmware/pull/11101)) +* Use the schema to eliminate custom code ([#11108](https://github.com/qmk/qmk_firmware/pull/11108)) +* Add support for specifying BOARD in `info.json` ([#11492](https://github.com/qmk/qmk_firmware/pull/11492)) +* Document how to add data driven configurations ([#11502](https://github.com/qmk/qmk_firmware/pull/11502)) +* Process info.json rules ahead of userspace rules ([#11542](https://github.com/qmk/qmk_firmware/pull/11542)) +* Remove duplicate manufacturer definitions ([#11544](https://github.com/qmk/qmk_firmware/pull/11544)) +* Update list of MCUs in `keyboard.jsonschema` to mirror `qmk.constants.py` ([#11688](https://github.com/qmk/qmk_firmware/pull/11688)) +* Create a system to map between `info.json` and `config.h`/`rules.mk` ([#11548](https://github.com/qmk/qmk_firmware/pull/11548)) +* Make LAYOUT parsing more robust ([#12000](https://github.com/qmk/qmk_firmware/pull/12000)) + + +### ChibiOS Update and Config Migration + +* Add board specific to Proton-C, with usual defaults turned on to match Pro-Micro ([#10976](https://github.com/qmk/qmk_firmware/pull/10976)) +* Disable almost all ChibiOS subsystems in default configs ([#11111](https://github.com/qmk/qmk_firmware/pull/11111)) +* Config Migrations ([#10418](https://github.com/qmk/qmk_firmware/pull/10418), [#11123](https://github.com/qmk/qmk_firmware/pull/11123), [#11261](https://github.com/qmk/qmk_firmware/pull/11261), [#11413](https://github.com/qmk/qmk_firmware/pull/11413), [#11414](https://github.com/qmk/qmk_firmware/pull/11414), [#11495](https://github.com/qmk/qmk_firmware/pull/11495), [#11504](https://github.com/qmk/qmk_firmware/pull/11504), [#11529](https://github.com/qmk/qmk_firmware/pull/11529), [#11588](https://github.com/qmk/qmk_firmware/pull/11588), [#11598](https://github.com/qmk/qmk_firmware/pull/11598), [#11607](https://github.com/qmk/qmk_firmware/pull/11607), [#11617](https://github.com/qmk/qmk_firmware/pull/11617), [#11620](https://github.com/qmk/qmk_firmware/pull/11620), [#11630](https://github.com/qmk/qmk_firmware/pull/11630), [#11646](https://github.com/qmk/qmk_firmware/pull/11646), [#11689](https://github.com/qmk/qmk_firmware/pull/11689), [#11846](https://github.com/qmk/qmk_firmware/pull/11846), [#11927](https://github.com/qmk/qmk_firmware/pull/11927), [#12001](https://github.com/qmk/qmk_firmware/pull/12001)) +* Disable subsystems repo-wide ([#11449](https://github.com/qmk/qmk_firmware/pull/11449)) +* Leftover early initialisation conversions ([#11615](https://github.com/qmk/qmk_firmware/pull/11615)) +* Fix up comments showing how to execute config migration ([#11621](https://github.com/qmk/qmk_firmware/pull/11621)) +* Add STM32G431 and STM32G474 board definitions ([#11793](https://github.com/qmk/qmk_firmware/pull/11793)) diff --git a/docs/_summary.md b/docs/_summary.md index acbfcfaeda..83799acdb8 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -119,12 +119,8 @@ * Breaking Changes * [Overview](breaking_changes.md) * [My Pull Request Was Flagged](breaking_changes_instructions.md) - * History - * [2020 Nov 28](ChangeLog/20201128.md) - * [2020 Aug 29](ChangeLog/20200829.md) - * [2020 May 30](ChangeLog/20200530.md) - * [2020 Feb 29](ChangeLog/20200229.md) - * [2019 Aug 30](ChangeLog/20190830.md) + * [Most Recent ChangeLog](ChangeLog/20210227.md "QMK v0.12.0 - 2021 Feb 27") + * [Past Breaking Changes](breaking_changes_history.md) * C Development * [ARM Debugging Guide](arm_debugging.md) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 3ee14f2bfc..de9148ad62 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -6,6 +6,7 @@ The breaking change period is when we will merge PR's that change QMK in dangero ## What has been included in past Breaking Changes? +* [2021 Feb 27](ChangeLog/20210227.md) * [2020 Nov 28](ChangeLog/20201128.md) * [2020 Aug 29](ChangeLog/20200829.md) * [2020 May 30](ChangeLog/20200530.md) @@ -18,12 +19,12 @@ The next Breaking Change is scheduled for February 27, 2021. ### Important Dates -* [x] 2020 Nov 28 - `develop` is created. Each push to `master` is subsequently merged to `develop` -* [ ] 2021 Jan 30 - `develop` closed to new PR's. -* [ ] 2021 Jan 30 - Call for testers. -* [ ] 2021 Feb 25 - `master` is locked, no PR's merged. -* [ ] 2021 Feb 27 - Merge `develop` to `master`. -* [ ] 2021 Feb 27 - `master` is unlocked. PR's can be merged again. +* [x] 2021 Feb 27 - `develop` is created. Each push to `master` is subsequently merged to `develop` +* [ ] 2021 May 01 - `develop` closed to new PR's. +* [ ] 2021 May 01 - Call for testers. +* [ ] 2021 May 27 - `master` is locked, no PR's merged. +* [ ] 2021 May 29 - Merge `develop` to `master`. +* [ ] 2021 May 29 - `master` is unlocked. PR's can be merged again. ## What changes will be included? diff --git a/docs/breaking_changes_history.md b/docs/breaking_changes_history.md new file mode 100644 index 0000000000..dd474f1bb7 --- /dev/null +++ b/docs/breaking_changes_history.md @@ -0,0 +1,10 @@ +# Past Breaking Changes + +This page links to all previous changelogs from the QMK Breaking Changes process. + +* [2021 Feb 27](ChangeLog/20210227.md) - version 0.12.0 +* [2020 Nov 28](ChangeLog/20201128.md) - version 0.11.0 +* [2020 Aug 29](ChangeLog/20200829.md) - version 0.10.0 +* [2020 May 30](ChangeLog/20200530.md) - version 0.9.0 +* [2020 Feb 29](ChangeLog/20200229.md) - version 0.8.0 +* [2019 Aug 30](ChangeLog/20190830.md) - version 0.7.0 -- cgit v1.2.3