aboutsummaryrefslogtreecommitdiff
path: root/docs/audio_driver.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/audio_driver.md')
-rw-r--r--docs/audio_driver.md221
1 files changed, 221 insertions, 0 deletions
diff --git a/docs/audio_driver.md b/docs/audio_driver.md
new file mode 100644
index 000000000..7cd5a98d9
--- /dev/null
+++ b/docs/audio_driver.md
@@ -0,0 +1,221 @@
1# Audio Driver :id=audio-driver
2
3The [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.
4
5Not 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 :id=avr
9
10Boards built around an Atmega32U4 can use two sets of PWM capable pins, each driving a separate speaker.
11The 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
19Currently there is only one/default driver for AVR based boards, which is automatically configured to:
20
21```make
22AUDIO_DRIVER = pwm_hardware
23```
24
25
26## ARM :id=arm
27
28For 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
30Supported wiring configurations, with their ChibiOS/MCU peripheral requirement are listed below;
31piezo 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 :id=dac-basic
54
55The default driver for ARM boards, in absence of an overriding configuration.
56This 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
58Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timers 6, 7 and 8:
59
60``` c
61//halconf.h:
62#define HAL_USE_DAC TRUE
63#define HAL_USE_GPT TRUE
64#include_next <halconf.h>
65```
66
67``` c
68// mcuconf.h:
69#include_next <mcuconf.h>
70#undef STM32_DAC_USE_DAC1_CH1
71#define STM32_DAC_USE_DAC1_CH1 TRUE
72#undef STM32_DAC_USE_DAC1_CH2
73#define STM32_DAC_USE_DAC1_CH2 TRUE
74#undef STM32_GPT_USE_TIM6
75#define STM32_GPT_USE_TIM6 TRUE
76#undef STM32_GPT_USE_TIM7
77#define STM32_GPT_USE_TIM7 TRUE
78#undef STM32_GPT_USE_TIM8
79#define STM32_GPT_USE_TIM8 TRUE
80```
81
82?> Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable).
83
84You can also change the timer used for the overall audio state by defining the driver. For instance:
85
86```c
87#define AUDIO_STATE_TIMER GPTD9
88```
89
90### DAC additive :id=dac-additive
91
92only 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.
93
94Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6:
95
96``` c
97//halconf.h:
98#define HAL_USE_DAC TRUE
99#define HAL_USE_GPT TRUE
100#include_next <halconf.h>
101```
102
103``` c
104// mcuconf.h:
105#include_next <mcuconf.h>
106#undef STM32_DAC_USE_DAC1_CH1
107#define STM32_DAC_USE_DAC1_CH1 TRUE
108#undef STM32_DAC_USE_DAC1_CH2
109#define STM32_DAC_USE_DAC1_CH2 TRUE
110#undef STM32_GPT_USE_TIM6
111#define STM32_GPT_USE_TIM6 TRUE
112```
113
114### DAC Config
115
116| Define | Defaults | Description --------------------------------------------------------------------------------------------- |
117| `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. |
118| `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. |
119| `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. |
120| `AUDIO_DAC_SAMPLE_RATE` | __see next table__ | Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality. |
121
122There 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.
123
124| Define | Sample Rate | Simultaneous tones |
125| `AUDIO_DAC_QUALITY_VERY_LOW` | `11025U` | `8` |
126| `AUDIO_DAC_QUALITY_LOW` | `22040U` | `4` |
127| `AUDIO_DAC_QUALITY_HIGH` | `44100U` | `2` |
128| `AUDIO_DAC_QUALITY_VERY_HIGH` | `88200U` | `1` |
129| `AUDIO_DAC_QUALITY_SANE_MINIMUM` | `16384U` | `8` |
130
131
132```c
133 /* zero crossing (or approach, whereas zero == DAC_OFF_VALUE, which can be configured to anything from 0 to DAC_SAMPLE_MAX)
134 * ============================*=*========================== AUDIO_DAC_SAMPLE_MAX
135 * * *
136 * * *
137 * ---------------------------------------------------------
138 * * * } AUDIO_DAC_SAMPLE_MAX/100
139 * --------------------------------------------------------- AUDIO_DAC_OFF_VALUE
140 * * * } AUDIO_DAC_SAMPLE_MAX/100
141 * ---------------------------------------------------------
142 * *
143 * * *
144 * * *
145 * =====*=*================================================= 0x0
146 */
147```
148
149
150### PWM hardware :id=pwm-hardware
151
152This driver uses the ChibiOS-PWM system to produce a square-wave on specific output pins that are connected to the PWM hardware.
153The 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.
154
155A configuration example for the STM32F103C8 would be:
156``` c
157//halconf.h:
158#define HAL_USE_PWM TRUE
159#define HAL_USE_PAL TRUE
160#define HAL_USE_GPT TRUE
161#include_next <halconf.h>
162```
163
164``` c
165// mcuconf.h:
166#include_next <mcuconf.h>
167#undef STM32_PWM_USE_TIM1
168#define STM32_PWM_USE_TIM1 TRUE
169#undef STM32_GPT_USE_TIM4
170#define STM32_GPT_USE_TIM4 TRUE
171```
172
173If we now target pin A8, looking through the data-sheet of the STM32F103C8, for the timers and alternate functions
174- TIM1_CH1 = PA8 <- alternate0
175- TIM1_CH2 = PA9
176- TIM1_CH3 = PA10
177- TIM1_CH4 = PA11
178
179with all this information, the configuration would contain these lines:
180``` c
181//config.h:
182#define AUDIO_PIN A8
183#define AUDIO_PWM_DRIVER PWMD1
184#define AUDIO_PWM_CHANNEL 1
185#define AUDIO_STATE_TIMER GPTD4
186```
187
188ChibiOS uses GPIOv1 for the F103, which only knows of one alternate function.
189On '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.
190
191
192### PWM software :id=pwm-software
193
194This driver uses the PWM callbacks from PWMD1 with TIM1_CH1 to toggle the selected AUDIO_PIN in software.
195During 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).
196
197You can also change the timer used for software PWM by defining the driver. For instance:
198
199```c
200#define AUDIO_STATE_TIMER GPTD8
201```
202
203
204### Testing Notes :id=testing-notes
205
206While not an exhaustive list, the following table provides the scenarios that have been partially validated:
207
208| | DAC basic | DAC additive | PWM hardware | PWM software |
209|--------------------------|--------------------|--------------------|--------------------|--------------------|
210| Atmega32U4 | :o: | :o: | :heavy_check_mark: | :o: |
211| STM32F103C8 (bluepill) | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: |
212| STM32F303CCT6 (proton-c) | :heavy_check_mark: | :heavy_check_mark: | ? | :heavy_check_mark: |
213| STM32F405VG | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
214| L0xx | :x: (no Tim8) | ? | ? | ? |
215
216
217:heavy_check_mark: : works and was tested
218:o: : does not apply
219:x: : not supported by MCU
220
221*Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.*
generated by cgit v1.2.3 (git 2.25.1) at 2025-07-12 12:03:51 +0000