Mozzi  version v2.0
sound synthesis library for Arduino
config_checks_stm32duino.h
1 /*
2  * config_checks_stm32duino.h
3  *
4  * This file is part of Mozzi.
5  *
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 #ifndef CONFIG_CHECKS_STM32DUINO_H
13 #define CONFIG_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.
48  * - twi_nonblock is not ported
49  *
50  * @section stm32duino_output_modes Output modes
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:
67  *
68  * @code
69  * #define MOZZI_AUDIO_PIN_1 ... // Left / mono output pin. Default: PA8
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
74  * @endcode
75  *
76  * @section stm32duino_pwm MOZZI_OUTPUT_2PIN_PWM
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).
92 */
93 
94 #if not IS_STM32DUINO()
95 #error This header should be included for STM32 (stm32duino.com core), only
96 #endif
97 
98 #if !defined(MOZZI_AUDIO_MODE)
99 # define MOZZI_AUDIO_MODE MOZZI_OUTPUT_PWM
100 #endif
101 MOZZI_CHECK_SUPPORTED(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_EXTERNAL_TIMED, MOZZI_OUTPUT_EXTERNAL_CUSTOM, MOZZI_OUTPUT_PWM, MOZZI_OUTPUT_2PIN_PWM)
102 
103 #if !defined(MOZZI_AUDIO_RATE)
104 # define MOZZI_AUDIO_RATE 32768
105 #endif
106 
107 #if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM, MOZZI_OUTPUT_2PIN_PWM, MOZZI_OUTPUT_EXTERNAL_TIMED)
108 # if !defined(MOZZI_AUDIO_UPDATE_TIMER)
109 # define MOZZI_AUDIO_UPDATE_TIMER TIM2
110 # endif
111 #endif
112 
113 #if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM)
114 # if !defined(MOZZI_AUDIO_PIN_1)
115 # define MOZZI_AUDIO_PIN_1 PA8
116 # endif
117 # if (MOZZI_AUDIO_CHANNELS > 1) && !defined(MOZZI_AUDIO_PIN_1)
118 # define MOZZI_AUDIO_PIN_2 PA9
119 # endif
120 # if !defined(MOZZI_AUDIO_BITS)
121 # define MOZZI_AUDIO_BITS 10
122 # endif
123 # define MOZZI_AUDIO_BITS_PER_CHANNEL MOZZI_AUDIO_BITS
124 #elif MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_2PIN_PWM)
125 # if !defined(MOZZI_AUDIO_PIN_1)
126 # define MOZZI_AUDIO_PIN_1 PA8
127 # endif
128 # if !defined(MOZZI_AUDIO_PIN_1_LOW)
129 # define MOZZI_AUDIO_PIN_1_LOW PA9
130 # endif
131 # include "disable_stereo_on_github_workflow.h"
132 MOZZI_CHECK_SUPPORTED(MOZZI_AUDIO_CHANNELS, 1)
133 # if !defined(MOZZI_AUDIO_PER_CHANNEL)
134 # define MOZZI_AUDIO_BITS_PER_CHANNEL 7
135 # endif
136 # define MOZZI_AUDIO_BITS (MOZZI_AUDIO_BITS_PER_CHANNEL * 2)
137 #endif
138 
139 #if !defined(MOZZI_ANALOG_READ)
140 #define MOZZI_ANALOG_READ MOZZI_ANALOG_READ_STANDARD
141 #endif
142 
143 #define MOZZI__INTERNAL_ANALOG_READ_RESOLUTION ADC_RESOLUTION
144 
145 #endif // #ifndef CONFIG_CHECKS_STM32DUINO_H