<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> STM32_GPT_USE_TIM8</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> TRUE</span></span></code></pre></div><divclass="tip custom-block"><pclass="custom-block-title">TIP</p><p>Note: DAC1 (A4) uses TIM6, DAC2 (A5) uses TIM7, and the audio state timer uses TIM8 (configurable).</p></div><p>You can also change the timer used for the overall audio state by defining the driver. For instance:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_STATE_TIMER</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> GPTD9</span></span></code></pre></div><h3id="dac-additive"tabindex="-1">DAC additive <aclass="header-anchor"href="#dac-additive"aria-label="Permalink to "DAC additive {#dac-additive}""></a></h3><p>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.</p><p>Additionally, in the board config, you'll want to make changes to enable the DACs, GPT for Timer 6:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">//halconf.h:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> STM32_GPT_USE_TIM6</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> TRUE</span></span></code></pre></div><h3id="dac-config"tabindex="-1">DAC Config <aclass="header-anchor"href="#dac-config"aria-label="Permalink to "DAC Config""></a></h3><table><thead><tr><th>Define</th><th>Defaults</th><th>Description</th></tr></thead><tbody><tr><td><code>AUDIO_DAC_SAMPLE_MAX</code></td><td><code>4095U</code></td><td>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.</td></tr><tr><td><code>AUDIO_DAC_OFF_VALUE</code></td><td><code>AUDIO_DAC_SAMPLE_MAX / 2</code></td><td>The value of the DAC when not playing anything. Some setups may require a high (<code>AUDIO_DAC_SAMPLE_MAX</code>) or low (<code>0</code>) value here.</td></tr><tr><td><code>AUDIO_MAX_SIMULTANEOUS_TONES</code></td><td><strong>see next table</strong></td><td>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.</td></tr><tr><td><code>AUDIO_DAC_SAMPLE_RATE</code></td><td><strong>see next table</strong></td><td>Effective bit rate of the DAC (in hertz), higher limits simultaneous tones, and lower sacrifices quality.</td></tr><tr><td><code>AUDIO_DAC_BUFFER_SIZE</code></td><td><strong>see next table</strong></td><td>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.</td></tr></tbody></table><p>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.</p><table><thead><tr><th>Define</th><th>Sample Rate</th><th>Simultaneous tones</th><th>Buffer size</th></tr></thead><tbody><tr><td><code>AUDIO_DAC_QUALITY_VERY_LOW</code></td><td><code>11025U</code></td><td><code>8</code></td><td><code>64U</code></td></tr><tr><td><code>AUDIO_DAC_QUALITY_LOW</code></td><td><code>22050U</code></td><td><code>4</code></td><td><code>128U</code></td></tr><tr><td><code>AUDIO_DAC_QUALITY_HIGH</code></td><td><code>44100U</code></td><td><code>2</code></td><td><code>256U</code></td></tr><tr><td><code>AUDIO_DAC_QUALITY_VERY_HIGH</code></td><td><code>88200U</code></td><td><code>1</code></td><td><code>256U</code></td></tr><tr><td><code>AUDIO_DAC_QUALITY_SANE_MINIMUM</code></td><td><code>16384U</code></td><td><code>8</code></td><td><code>64U</code></td></tr></tbody></table><h4id="buffer-size"tabindex="-1">Notes on buffer size <aclass="header-anchor"href="#buffer-size"aria-label="Permalink to "Notes on buffer size {#buffer-size}""></a></h4><p>By default, the buffer size attempts to keep to these constraints:</p><ul><li>The interval between buffer refills can't be too short, since the microcontroller would then only be servicing buffer refills and would freeze up.</li><li>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.</li><li>The interval between buffer refills is kept to a minimum, which allows notes to stop as soon as possible after they should.</li><li>For greater compatibility, the buffer size should be a power of 2.</li><li>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).</li></ul><p>You can lower the buffer size if you need a bit more space in your firmware, or raise it if your keyboard freezes up.</p><divclass="language-c vp-adaptive-theme"><buttont
<spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> */</span></span></code></pre></div><h3id="pwm-hardware"tabindex="-1">PWM hardware <aclass="header-anchor"href="#pwm-hardware"aria-label="Permalink to "PWM hardware {#pwm-hardware}""></a></h3><p>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.</p><p>A configuration example for the STM32F103C8 would be:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">//halconf.h:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> STM32_PWM_USE_TIM1</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> TRUE</span></span></code></pre></div><p>If we now target pin A8, looking through the data-sheet of the STM32F103C8, for the timers and alternate functions</p><ul><li>TIM1_CH1 = PA8 <- alternate0</li><li>TIM1_CH2 = PA9</li><li>TIM1_CH3 = PA10</li><li>TIM1_CH4 = PA11</li></ul><p>with all this information, the configuration would contain these lines:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">//config.h:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_PWM_CHANNEL</span><spanstyle="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span></span></code></pre></div><p>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 <code>AUDIO_PWM_PAL_MODE</code> to the correct alternate function for the selected pin, timer and timer-channel.</p><p>You can also use the Complementary output (<code>TIMx_CHyN</code>) for PWM on supported controllers. To enable this functionality, you will need to make the following changes:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// config.h:</span></span>
<spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_PWM_COMPLEMENTARY_OUTPUT</span></span></code></pre></div><h3id="pwm-software"tabindex="-1">PWM software <aclass="header-anchor"href="#pwm-software"aria-label="Permalink to "PWM software {#pwm-software}""></a></h3><p>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).</p><p>You can also change the timer used for software PWM by defining the driver. For instance:</p><divclass="language-c vp-adaptive-theme"><buttontitle="Copy Code"class="copy"></button><spanclass="lang">c</span><preclass="shiki shiki-themes github-light github-dark vp-code"><code><spanclass="line"><spanstyle="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><spanstyle="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> AUDIO_STATE_TIMER</span><spanstyle="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> GPTD8</span></span></code></pre></div><h3id="testing-notes"tabindex="-1">Testing Notes <aclass="header-anchor"href="#testing-notes"aria-label="Permalink to "Testing Notes {#testing-notes}""></a></h3><p>While not an exhaustive list, the following table provides the scenarios that have been partially validated:</p><table><thead><tr><th></th><th>DAC basic</th><th>DAC additive</th><th>PWM hardware</th><th>PWM software</th></tr></thead><tbody><tr><td>Atmega32U4</td><td>⭕</td><td>⭕</td><td>✔️</td><td>⭕</td></tr><tr><td>RP2040</td><td>❌</td><td>❌</td><td>✔️</td><td>?</td></tr><tr><td>STM32F103C8 (bluepill)</td><td>❌</td><td>❌</td><td>✔️</td><td>✔️</td></tr><tr><td>STM32F303CCT6 (proton-c)</td><td>✔️</td><td>✔️</td><td>?</td><td>✔️</td></tr><tr><td>STM32F405VG</td><td>✔️</td><td>✔️</td><td>✔️</td><td>✔️</td></tr><tr><td>L0xx</td><td>❌ (no Tim8)</td><td>?</td><td>?</td><td>?</td></tr></tbody></table><p>✔️ : works and was tested<br> ⭕ : does not apply<br> ❌ : not supported by MCU</p><p><em>Other supported ChibiOS boards and/or pins may function, it will be highly chip and configuration dependent.</em></p></div></div></main><footerclass="VPDocFooter"data-v-39a288b8data-v-09de1c0f><!--[--><!--]--><!----><navclass="prev-next"data-v-09de1c0f><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link prev"href="/drivers/apa102"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Previous page</span><spanclass="title"data-v-09de1c0f>APA102 Driver</span><!--]--></a></div><divclass="pager"data-v-09de1c0f><aclass="VPLink link pager-link next"href="/drivers/eeprom"data-v-09de1c0f><!--[--><spanclass="desc"data-v-09de1c0f>Next page</span><spanclass="title"data-v-09de1c0f>EEPROM Driver</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
