Mozzi  version v2.0
sound synthesis library for Arduino
config_checks_stm32maple.h
1 /*
2  * config_checks_stm32maple.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_STM32MAPLE_H
13 #define CONFIG_CHECKS_STM32MAPLE_H
14 
15 /**
16  * @page hardware_stm32_maple Mozzi on STM32-boards with libmaple based core.
17  * port by Thomas Friedrichsmeier
18  *
19  * @note
20  * Be sure to understand the info given at @ref hardware_stm32_disambiguation . This page is about using Mozzi with the STM32 "libmaple based" core.
21  *
22  * @note
23  * This port may look similar to, but uses a different default GPIO pinout than @ref @hardware_stm32duino !
24  *
25  * @section stm32_maple_status Status and peculiarities of this port
26  * Compiles for and runs on a STM32F103C8T6 blue pill board, with a bunch of caveats (see below), i.e. on a board _without_ a
27  * real DAC. Should probably run on any other board supported by [Roger Clark's libmaple-based core](https://github.com/rogerclarkmelbourne/Ardu0ino_STM32) (although this theory is untested).
28  *
29  * @note that at the time of this writing, [Stev Strong's slightliy more recent fork of this core](https://github.com/stevstrong/Arduino_STM32/) does *not* work with
30  * Mozzi, apparently due to a bug in pwmWrite().
31  *
32  * - If you want to use MIDI, be sure to replace "MIDI_CREATE_DEFAULT_INSTANCE()" with "MIDI_CREATE_INSTANCE(HardwareSerial, Serial1, MIDI)" (or Serial2)
33  * - @ref MOZZI_AUDIO_INPUT_STANDARD is implemented in theory, but untested (feedback welcome)
34  * - getAudioInput() and mozziAnalogRead() return values in the STM32's full ADC resolution of 0-4095 rather than AVR's 0-1023.
35  *- twi_nonblock is not ported
36  *
37  * @section stm32_output_modes Output modes
38  *
39  * The following audio modes (see @ref MOZZI_AUDIO_MODE) are currently supported on this hardware:
40  * - MOZZI_OUTPUT_EXTERNAL_TIMED
41  * - MOZZI_OUTPUT_EXTERNAL_CUSTOM
42  * - MOZZI_OUTPUT_PWM
43  * - MOZZI_OUTPUT_PWM_2PIN
44  *
45  * The default mode is @ref stm32_maple_pwm .
46  *
47  * @section stm32_maple_pwm MOZZI_OUTPUT_PWM
48  * Standard pulse width modulated output to one (mono) or two (stereo, see @ref MOZZI_AUDIO_CHANNELS) GPIO pins. Default pinout: PB8 (mono/left), PB9 (right channel in stereo).
49  * This mode uses two hardware timers: One for the PWM (Timer 4 when using the default pin configuration), and a second for updating the output at audio rate.
50  * 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.
51  * The following settings may be costumized, if desired:
52  *
53  * @code
54  * #define MOZZI_AUDIO_PIN_1 ... // Left / mono output pin. Default: PB8
55  * #define MOZZI_AUDIO_PWM_TIMER ... // Must be set ot the hardware timer connected to the above pin. Default: 4
56  * #define MOZZI_AUDIO_UPDATE_TIMER ... // Second hardware timer to claim. Default 2
57  * #define MOZZI_AUDIO_BITS ... // Output resolution in bits. Default is 10
58  * // For stereo, only:
59  * #define MOZZI_AUDIO_PIN_2 ... // Right channel output pin. This *must* be connected to the same hardware timer as MOZZI_AUDIO_PIN_1 ! Default: PB9
60  * @endcode
61  *
62  * @section stm32_maple_2pin_pwm MOZZI_OUTPUT_2PIN_PWM
63  * This mode is very similar to @ref stm32_maple_pwm, but splitting output for a single channel across two GPIO pins for better resolution. For details on the required
64  * hardware setup, and configuration tradeoffs, see @ref avr_2pin_pwm . Stereo output is not available in this mode.
65  * Output is at 2*7 bits at up to 560kHz carrier frequency (but limited to 5 times audio rate).
66  *
67  * Customizable configuration options:
68  * @code
69  * #define MOZZI_AUDIO_PIN_1 ... // High byte of the output. Default: PB8
70  * #define MOZZI_AUDIO_PIN_2 ... // Low byte of the output. Default: PB9
71  * #define MOZZI_AUDIO_PWM_TIMER ... // Must be set to the number of the hardware timer connect to the above pins. Default: 4
72  * #define MOZZI_AUDIO_UPDATE_TIMER ... // Second hardware timer to claim. Default TIM2
73  * #define MOZZI_AUDIO_BITS_PER_CHANNEL ... // Bits per pin. Default is 7
74  * @endcode
75  *
76  * @section stm32_maple_external MOZZI_OUTPUT_EXTERNAL_TIMED and MOZZI_OUTPUT_EXTERNAL_CUSTOM
77  * See @ref external_audio
78  * The (single) hardware timer claimed for MOZZI_OUTPUT_EXTERNAL_TIMED may be configured using "MOZZI_AUDIO_UPDATE_TIMER" (default: TIM2).
79 */
80 
81 
82 #if not IS_STM32MAPLE()
83 #error This header should be included for STM32 (libmaple based core), only
84 #endif
85 
86 #if !defined(MOZZI_AUDIO_MODE)
87 # define MOZZI_AUDIO_MODE MOZZI_OUTPUT_PWM
88 #endif
89 MOZZI_CHECK_SUPPORTED(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_EXTERNAL_TIMED, MOZZI_OUTPUT_EXTERNAL_CUSTOM, MOZZI_OUTPUT_PWM, MOZZI_OUTPUT_2PIN_PWM)
90 
91 #if !defined(MOZZI_AUDIO_RATE)
92 # define MOZZI_AUDIO_RATE 32768
93 #endif
94 
95 #if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM, MOZZI_OUTPUT_2PIN_PWM, MOZZI_OUTPUT_EXTERNAL_TIMED)
96 # if !defined(MOZZI_AUDIO_UPDATE_TIMER)
97 # define MOZZI_AUDIO_UPDATE_TIMER 2
98 # endif
99 # if !defined(MOZZI_AUDIO_PWM_TIMER)
100 # define MOZZI_AUDIO_PWM_TIMER 4
101 # endif
102 #endif
103 
104 #if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM)
105 # if !defined(MOZZI_AUDIO_PIN_1)
106 # define MOZZI_AUDIO_PIN_1 PB8
107 # endif
108 # if (MOZZI_AUDIO_CHANNELS > 1) && !defined(MOZZI_AUDIO_PIN_1)
109 # define MOZZI_AUDIO_PIN_2 PB9
110 # endif
111 # if !defined(MOZZI_AUDIO_BITS)
112 # define MOZZI_AUDIO_BITS 10
113 # endif
114 # define MOZZI_AUDIO_BITS_PER_CHANNEL MOZZI_AUDIO_BITS
115 #elif MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_2PIN_PWM)
116 # if !defined(MOZZI_AUDIO_PIN_1)
117 # define MOZZI_AUDIO_PIN_1 PB8
118 # endif
119 # if !defined(MOZZI_AUDIO_PIN_1_LOW)
120 # define MOZZI_AUDIO_PIN_1_LOW PB9
121 # endif
122 # include "disable_stereo_on_github_workflow.h"
123 MOZZI_CHECK_SUPPORTED(MOZZI_AUDIO_CHANNELS, 1)
124 # if !defined(MOZZI_AUDIO_PER_CHANNEL)
125 # define MOZZI_AUDIO_PER_CHANNEL 7
126 # endif
127 # define MOZZI_AUDIO_BITS MOZZI_AUDIO_BITS_PER_CHANNEL * 2
128 #endif
129 
130 #if !defined(MOZZI_ANALOG_READ)
131 #define MOZZI_ANALOG_READ MOZZI_ANALOG_READ_STANDARD
132 #endif
133 
134 // TODO: This probably isn't correct for all boards!
135 #define MOZZI__INTERNAL_ANALOG_READ_RESOLUTION 12
136 
137 #endif // #ifndef CONFIG_CHECKS_STM32MAPLE_H