diff options
Diffstat (limited to 'docs')
31 files changed, 1020 insertions, 319 deletions
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 <keyboard>`. 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 5af0046ab3..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) @@ -133,11 +129,13 @@ * [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) * [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) @@ -159,6 +157,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/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<br>Tim6 | GPTD7<br>Tim7 | GPTD8<br>Tim8 | PWMD1<sup>1</sup><br>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: <sup>2</sup> | | | | + | pwm_software | state-update | | | any = :one: | + | pwm hardware | state-update | | | A8 = :one: <sup>3</sup> | + + +<sup>1</sup>: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet +<sup>2</sup>: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set +<sup>3</sup>: 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 <halconf.h> +``` + +``` c +// mcuconf.h: +#include_next <mcuconf.h> +#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 <halconf.h> +``` + +``` c +// mcuconf.h: +#include_next <mcuconf.h> +#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 <halconf.h> +``` + +``` c +// mcuconf.h: +#include_next <mcuconf.h> +#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/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 diff --git a/docs/compatible_microcontrollers.md b/docs/compatible_microcontrollers.md index 1bf7072246..47a4844e7f 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: @@ -25,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/config_options.md b/docs/config_options.md index a3262b418b..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` @@ -97,6 +103,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`. diff --git a/docs/data_driven_config.md b/docs/data_driven_config.md new file mode 100644 index 0000000000..c2ad4fed8f --- /dev/null +++ b/docs/data_driven_config.md @@ -0,0 +1,91 @@ +# Data Driven Configuration + +This page describes how QMK |