audio.md (13286B)
1 # Audio Driver {#audio-driver} 2 3 The [Audio feature](../features/audio) 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. 4 5 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. 6 7 8 ## AVR {#avr} 9 10 Boards built around an Atmega32U4 can use two sets of PWM capable pins, each driving a separate speaker. 11 The possible configurations are: 12 13 | | Timer3 | Timer1 | 14 |--------------|-------------|--------------| 15 | one speaker | C4,C5 or C6 | | 16 | one speaker | | B4, B5 or B7 | 17 | two speakers | C4,C5 or C6 | B4, B5 or B7 | 18 19 Currently there is only one/default driver for AVR based boards, which is automatically configured to: 20 21 ```make 22 AUDIO_DRIVER = pwm_hardware 23 ``` 24 25 26 ## ARM {#arm} 27 28 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. 29 30 Supported wiring configurations, with their ChibiOS/MCU peripheral requirement are listed below; 31 piezo speakers are marked with :one: for the first/primary and :two: for the secondary. 32 33 | driver | GPTD6<br>Tim6 | GPTD7<br>Tim7 | GPTD8<br>Tim8 | PWMD1<sup>1</sup><br>Tim1_Ch1 | 34 |--------------|------------------------------------------|------------------------|---------------|-------------------------------| 35 | dac_basic | A4+DACD1 = :one: | A5+DACD2 = :one: | state | | 36 | | A4+DACD1 = :one: + Gnd | A5+DACD2 = :two: + Gnd | state | | 37 | | A4+DACD1 = :two: + Gnd | A5+DACD2 = :one: + Gnd | state | | 38 | | A4+DACD1 = :one: + Gnd | | state | | 39 | | | A5+DACD2 = :one: + Gnd | state | | 40 | dac_additive | A4+DACD1 = :one: + Gnd | | | | 41 | | A5+DACD2 = :one: + Gnd | | | | 42 | | A4+DACD1 + A5+DACD2 = :one: <sup>2</sup> | | | | 43 | pwm_software | state-update | | | any = :one: | 44 | pwm hardware | state-update | | | A8 = :one: <sup>3</sup> | 45 46 47 <sup>1</sup>: the routing and alternate functions for PWM differ sometimes between STM32 MCUs, if in doubt consult the data-sheet 48 <sup>2</sup>: one piezo connected to A4 and A5, with AUDIO_PIN_ALT_AS_NEGATIVE set 49 <sup>3</sup>: TIM1_CH1 = A8 on STM32F103C8, other combinations are possible, see Data-sheet. configured with: AUDIO_PWM_DRIVER and AUDIO_PWM_CHANNEL 50 51 52 53 ### DAC basic {#dac-basic} 54 55 The default driver for ARM boards, in absence of an overriding configuration. 56 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. 57 58 Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8: 59 60 ::: code-group 61 ```c [halconf.h] 62 #pragma once 63 64 #define HAL_USE_DAC TRUE // [!code focus] 65 #define HAL_USE_GPT TRUE // [!code focus] 66 67 #include_next <halconf.h> 68 ``` 69 ```c [mcuconf.h] 70 #pragma once 71 72 #include_next <mcuconf.h> 73 74 #undef STM32_DAC_USE_DAC1_CH1 // [!code focus] 75 #define STM32_DAC_USE_DAC1_CH1 TRUE // [!code focus] 76 #undef STM32_DAC_USE_DAC1_CH2 // [!code focus] 77 #define STM32_DAC_USE_DAC1_CH2 TRUE // [!code focus] 78 #undef STM32_GPT_USE_TIM6 // [!code focus] 79 #define STM32_GPT_USE_TIM6 TRUE // [!code focus] 80 #undef STM32_GPT_USE_TIM7 // [!code focus] 81 #define STM32_GPT_USE_TIM7 TRUE // [!code focus] 82 #undef STM32_GPT_USE_TIM8 // [!code focus] 83 #define STM32_GPT_USE_TIM8 TRUE // [!code focus] 84 ``` 85 ::: 86 87 ::: tip 88 Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable). 89 ::: 90 91 You can also change the timer used for the overall audio state by defining the driver. For instance: 92 93 ```c 94 #define AUDIO_STATE_TIMER GPTD9 95 ``` 96 97 ### DAC additive {#dac-additive} 98 99 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. 100 101 Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6: 102 103 ::: code-group 104 ```c [halconf.h] 105 #pragma once 106 107 #define HAL_USE_DAC TRUE // [!code focus] 108 #define HAL_USE_GPT TRUE // [!code focus] 109 110 #include_next <halconf.h> 111 ``` 112 ```c [mcuconf.h] 113 #pragma once 114 115 #include_next <mcuconf.h> 116 117 #undef STM32_DAC_USE_DAC1_CH1 // [!code focus] 118 #define STM32_DAC_USE_DAC1_CH1 TRUE // [!code focus] 119 #undef STM32_DAC_USE_DAC1_CH2 // [!code focus] 120 #define STM32_DAC_USE_DAC1_CH2 TRUE // [!code focus] 121 #undef STM32_GPT_USE_TIM6 // [!code focus] 122 #define STM32_GPT_USE_TIM6 TRUE // [!code focus] 123 ``` 124 ::: 125 126 ### DAC Config 127 128 | Define | Defaults | Description | 129 | -------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 130 | `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. | 131 | `AUDIO_DAC_OFF_VALUE` | `AUDIO_DAC_SAMPLE_MAX / 2` | The value of the DAC when not playing anything. Some setups may require a high (`AUDIO_DAC_SAMPLE_MAX`) or low (`0`) value here. | 132 | `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. | 133 | `AUDIO_DAC_SAMPLE_RATE` | __see next table__ | Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality. | 134 | `AUDIO_DAC_BUFFER_SIZE` | __see next table__ | Number of samples generated every refill. Too few may cause excessive CPU load; too many may cause freezes, RAM or flash exhaustion or lags during matrix scanning. | 135 136 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, number of simultaneous tones and buffer size, instead of using one of the listed presets. 137 138 | Define | Sample Rate | Simultaneous tones | Buffer size | 139 | --------------------------------- | ----------- | ------------------- | ----------- | 140 | `AUDIO_DAC_QUALITY_VERY_LOW` | `11025U` | `8` | `64U` | 141 | `AUDIO_DAC_QUALITY_LOW` | `22050U` | `4` | `128U` | 142 | `AUDIO_DAC_QUALITY_HIGH` | `44100U` | `2` | `256U` | 143 | `AUDIO_DAC_QUALITY_VERY_HIGH` | `88200U` | `1` | `256U` | 144 | `AUDIO_DAC_QUALITY_SANE_MINIMUM` | `16384U` | `8` | `64U` | 145 146 #### Notes on buffer size {#buffer-size} 147 148 By default, the buffer size attempts to keep to these constraints: 149 150 * The interval between buffer refills can't be too short, since the microcontroller would then only be servicing buffer refills and would freeze up. 151 * On the additive driver, the interval between buffer refills can't be too long, since matrix scanning would suffer lengthy pauses every so often, which would delay key presses or releases or lose some short taps altogether. 152 * The interval between buffer refills is kept to a minimum, which allows notes to stop as soon as possible after they should. 153 * For greater compatibility, the buffer size should be a power of 2. 154 * The buffer size being too large causes resource exhaustion leading to build failures or freezing at runtime: RAM usage (on the additive driver) or flash usage (on the basic driver). 155 156 You can lower the buffer size if you need a bit more space in your firmware, or raise it if your keyboard freezes up. 157 158 159 ```c 160 /* zero crossing (or approach, whereas zero == DAC_OFF_VALUE, which can be configured to anything from 0 to DAC_SAMPLE_MAX) 161 * ============================*=*========================== AUDIO_DAC_SAMPLE_MAX 162 * * * 163 * * * 164 * --------------------------------------------------------- 165 * * * } AUDIO_DAC_SAMPLE_MAX/100 166 * --------------------------------------------------------- AUDIO_DAC_OFF_VALUE 167 * * * } AUDIO_DAC_SAMPLE_MAX/100 168 * --------------------------------------------------------- 169 * * 170 * * * 171 * * * 172 * =====*=*================================================= 0x0 173 */ 174 ``` 175 176 177 ### PWM hardware {#pwm-hardware} 178 179 This driver uses the ChibiOS-PWM system to produce a square-wave on specific output pins that are connected to the PWM hardware. 180 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. 181 182 A configuration example for the STM32F103C8 would be: 183 184 ::: code-group 185 ```c [halconf.h] 186 #pragma once 187 188 #define HAL_USE_PWM TRUE // [!code focus] 189 #define HAL_USE_PAL TRUE // [!code focus] 190 191 #include_next <halconf.h> 192 ``` 193 ```c [mcuconf.h] 194 #pragma once 195 196 #include_next <mcuconf.h> 197 198 #undef STM32_PWM_USE_TIM1 // [!code focus] 199 #define STM32_PWM_USE_TIM1 TRUE // [!code focus] 200 ``` 201 ::: 202 203 If we now target pin A8, looking through the data-sheet of the STM32F103C8, for the timers and alternate functions 204 - TIM1_CH1 = PA8 <- alternate0 205 - TIM1_CH2 = PA9 206 - TIM1_CH3 = PA10 207 - TIM1_CH4 = PA11 208 209 with all this information, the configuration would contain these lines: 210 ```c 211 //config.h: 212 #define AUDIO_PIN A8 213 #define AUDIO_PWM_DRIVER PWMD1 214 #define AUDIO_PWM_CHANNEL 1 215 ``` 216 217 ChibiOS uses GPIOv1 for the F103, which only knows of one alternate function. 218 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. 219 220 You can also use the Complementary output (`TIMx_CHyN`) for PWM on supported controllers. To enable this functionality, you will need to make the following changes: 221 ```c 222 // config.h: 223 #define AUDIO_PWM_COMPLEMENTARY_OUTPUT 224 ``` 225 226 ### PWM software {#pwm-software} 227 228 This driver uses the PWM callbacks from PWMD1 with TIM1_CH1 to toggle the selected AUDIO_PIN in software. 229 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). 230 231 You can also change the timer used for software PWM by defining the driver. For instance: 232 233 ```c 234 #define AUDIO_STATE_TIMER GPTD8 235 ``` 236 237 238 ### Testing Notes {#testing-notes} 239 240 While not an exhaustive list, the following table provides the scenarios that have been partially validated: 241 242 | | DAC basic | DAC additive | PWM hardware | PWM software | 243 | ------------------------ | ------------------ | ------------------ | ------------------ | ------------------ | 244 | Atmega32U4 | :o: | :o: | :heavy_check_mark: | :o: | 245 | RP2040 | :x: | :x: | :heavy_check_mark: | ? | 246 | STM32F103C8 (bluepill) | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: | 247 | STM32F303CCT6 (proton-c) | :heavy_check_mark: | :heavy_check_mark: | ? | :heavy_check_mark: | 248 | STM32F405VG | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | 249 | L0xx | :x: (no Tim8) | ? | ? | ? | 250 251 :heavy_check_mark: : works and was tested 252 :o: : does not apply 253 :x: : not supported by MCU 254 255 *Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.*