6 * Copyright 2023-2024 Thomas Friedrichsmeier and the Mozzi Team
7 *
8 * Mozzi is licensed under the GNU Lesser General Public Licence (LGPL) Version 2.1 or later.
9 *
10*/
11
12#ifndefCONFIG_CHECKS_STM32DUINO_H
13#defineCONFIG_CHECKS_STM32DUINO_H
14
15/**
16* @page hardware_stm32_disambiguation Mozzi on STM32-based boards - disambiguation
17*
18* * The situation on STM32-based boards is rather confusing, as there are several competing Arduino cores. Importantly:
19* - Some boards use dedicated cores (e.g. Arduino Giga / Portenta @ref hardware_mbed) etc. For those, see the relevant sections (if we support them).
20* - There is a series of libmaple-based cores, including [Roger Clark's libmaple-based core](https://github.com/rogerclarkmelbourne/Arduino_STM32). These are highly optimized,
21* and provide very complete support, but only for a limited number of boards. Unfortunately, at the time of this writing (2023/04), they are not available for installation
22* via the Arduino Board Manager, and they do not currently seem actively maintained.
23* For using these with Mozzi, see @ref hardware_stm32_maple
24* - A generic Arduino core for STM32 is the [STM32duino core](https://github.com/stm32duino/Arduino_Core_STM32). It supports a huge set of boards, and seems to have offical
25* backing by STM, but some features of the libmaple based cores are still lacking. To complete confusion, this core now uses the label "STM32duino", which used to be what
26* the libmaple cores above were known by (don't blame Mozzi for this mess!).
27* For using this with Mozzi, see @ref hardware_stm32duino
28* */
29
30/**
31 * @page hardware_stm32duino Mozzi on STM32duino-based boards.
32 *
33 * port by Thomas Friedrichsmeier
34 *
35 * @note
36 * Be sure to understand the info given at @ref hardware_stm32_disambiguation . This page is about using Mozzi with the STM32duino core.
37 *
38 * @section stm32duino_status Port status and usage notes
39 * Tested on a STM32F103C8T6 blue pill board as well as an STM32F411CE black pill board, i.e. on sboards _without_ a
40 * real DAC. Compiles and runs, with a bunch of caveats (see below). Should probably run on any other board supported by the
41 * [STM32duino core](https://github.com/stm32duino/Arduino_Core_STM32) (although this theory is untested).
42 * When trying any other board, you probably want to check the platform specific settings (see below), carefully, importantly, whether the desired output resolution is
43 * achievable, and whether the desired output pins are PWM capable.
44 *
45 * - @ref MOZZI_ANALOG_READ input implementation is somewhat experimental, and may not be able to service a whole lot of pins (contributions welcome)
46 * - @ref MOZZI_AUDIO_INPUT is completely untested (but implemented in theory; feedback welcome!)
47 * - getAudioInput() and mozziAnalogRead() return values in the STM32's full ADC resolution (the exact range depending on the board in use) rather than AVR's 0-1023.
51 * The following audio modes (see @ref MOZZI_AUDIO_MODE) are currently supported on this hardware:
52 * - MOZZI_OUTPUT_EXTERNAL_TIMED
53 * - MOZZI_OUTPUT_EXTERNAL_CUSTOM
54 * - MOZZI_OUTPUT_PWM
55 * - MOZZI_OUTPUT_PWM_2PIN
56 *
57 * The default mode is @ref stm32duino_pwm .
58 *
59 * @note
60 * This port may look similar to, but uses a different default GPIO pinout than @hardware_stm32_maple !
61 *
62 * @section stm32duino_pwm MOZZI_OUTPUT_PWM
63 * Standard pulse width modulated output to one (mono) or two (stereo, see @ref MOZZI_AUDIO_CHANNELS) GPIO pins. Default pinout: PA8 (mono/left), PA9 (right channel in stereo).
64 * This mode uses two hardware timers: One for the PWM (Timer 3 when using the default pin configuration), and a second for updating the output at audio rate.
65 * The default audio resolution is 10 bits, which results in a carrier frequency of ~70kHz on a 72MHz CPU. On slower boards you will have to descrease this.
66 * The following settings may be costumized, if desired:
70 * #define MOZZI_AUDIO_UPDATE_TIMER ... // Second hardware timer to claim, must not be the same of the timer for the above pin. Default TIM2
71 * #define MOZZI_AUDIO_BITS ... // Output resolution in bits. Default is 10
72 * // For stereo, only:
73 * #define MOZZI_AUDIO_PIN_2 ... // Right channel output pin. This *must* be connected to the same hardware timer as MOZZI_AUDIO_PIN_1 ! Default: PA9
77 * This mode is very similar to @ref stm32duino_pwm, but splitting output for a single channel across two GPIO pins for better resolution. For details on the required
78 * hardware setup, and configuration tradeoffs, see @ref avr_2pin_pwm . Stereo output is not available in this mode.
79 * Output is at 2*7 bits at up to 560kHz carrier frequency (but limited to 5 times audio rate).
80 *
81 * Customizable configuration options:
82 * @code
83 * #define MOZZI_AUDIO_PIN_1 ... // High byte of the output. Default: PA8
84 * #define MOZZI_AUDIO_PIN_1_LOW ... // Low byte of the output. Default: PA9
85 * #define MOZZI_AUDIO_UPDATE_TIMER ... // Second hardware timer to claim. Default TIM2
86 * #define MOZZI_AUDIO_BITS_PER_CHANNEL ... // Bits per pin. Default is 7
87 * @endcode
88 *
89 * @section stm32duino_external MOZZI_OUTPUT_EXTERNAL_TIMED and MOZZI_OUTPUT_EXTERNAL_CUSTOM
90 * See @ref external_audio .
91 * The (single) hardware timer claimed for MOZZI_OUTPUT_EXTERNAL_TIMED may be configured using "MOZZI_AUDIO_UPDATE_TIMER" (default: TIM2).
Generated automatically using Doxygen. If info on this page is outdated, incomplete, or wrong, please open an issue at https://github.com/sensorium/Mozzi/issues
