Skip to content

Commit

Permalink
Start reorganizing port documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@tfry-git
tfry-git committed Nov 18, 2023
1 parent 5a47d80 commit 219980e
Show file tree
Hide file tree
Showing 14 changed files with 354 additions and 313 deletions.
217 changes: 0 additions & 217 deletions MozziConfigExample.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,6 @@
*
* For simplicity, mozziAnalogRead() is always defined, but when MOZZI_ANALOG_READ s are disabled or unsupported, it simply relays
* to Arduino's regular analogRead(). It is thus quite recommended _not_ to depend on mozziAnalogRead() when disabling this.
* Also setupFastAnalogReads() continues to be defined, for your convenience, but is not called automatically. TODO: rethink that!
*
* As a rough estimate (your numbers may differ a bit, depending on compiler version, etc.), on an ATMEGA328P (aka Arduino Uno),
* disabling analog reads saves 33 bytes of RAM and 340 bytes of FLASH. The performance savings are theorized to be neglegible, however.
Expand Down Expand Up @@ -660,219 +659,3 @@
*/




/***************************************** ADVANCED SETTTINGS -- STM32(duino) ***********************************************************
*
* The settings in the following section applies to the STM32(duino) architecture.
*
* It is generally not recommended to change anything, here, unless you really know, what you are doing and/or
* are willing to rough it out by yourself.
*
********************************************************************************************************************************/

/** @ingroup hardware
* @page hardware_stm32_disambiguation Mozzi on STM32-based boards - disambiguation
*
* * The situation on STM32-based boards is rather confusing, as there are several competing Arduino cores. Importantly:
* - Some boards use dedicated cores (e.g. Arduino Giga / Portenta @ref hardware_mbed) etc. For those, see the relevant sections (if we support them).
* - 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,
* 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
* via the Arduino Board Manager, and they do not currently seem actively maintained.
* For using these with Mozzi, see @ref hardware_stm32_maple
* - A generic Arduino core for STM32 is the [STM32duino core](https://github.com/stm32duino/Arduino_Core_STM32). It supports a huge step of boards, and seems to have offical
* 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
* the libmaple cores above were known by (don't blame Mozzi for this mess!).
* For using this with Mozzi, see @ref hardware_stm32duino
*
* */

/** @ingroup hardware
* @page hardware_stm32duino Mozzi on STM32duino-based boards.
*
* @note
* Be sure to understand the info given at @ref hardwware_stm32_disambiguation . This page is about using Mozzi with the STM32duino core.
*
* The following audio modes (see @ref MOZZI_AUDIO_MODE) are currently supported on this hardware:
* - MOZZI_OUTPUT_EXTERNAL_TIMED
* - MOZZI_OUTPUT_EXTERNAL_CUSTOM
* - MOZZI_OUTPUT_PWM
* - MOZZI_OUTPUT_PWM_2PIN
*
* The default mode is @ref stm32duino_pwm .
*
* @note
* This port may look similar to, but uses a different default GPIO pinout than @hardware_stm32_maple !
*
* @section stm32duino_pwm MOZZI_OUTPUT_PWM
* 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).
* 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.
* 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.
* The following settings may be costumized, if desired:
*
* @code
* #define MOZZI_AUDIO_PIN_1 ... // Left / mono output pin. Default: PA8
* #define MOZZI_AUDIO_UPDATE_TIMER ... // Second hardware timer to claim, must not be the same of the timer for the above pin. Default TIM2
* #define MOZZI_AUDIO_BITS ... // Output resolution in bits. Default is 10
* // For stereo, only:
* #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
* @endcode
*
* @section stm32duino_pwm MOZZI_OUTPUT_2PIN_PWM
* 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
* hardware setup, and configuration tradeoffs, see @ref avr_2pin_pwm . Stereo output is not available in this mode.
*
* Customizable configuration options:
* @code
* #define MOZZI_AUDIO_PIN_1 ... // High byte of the output. Default: PA8
* #define MOZZI_AUDIO_PIN_1_LOW ... // Low byte of the output. Default: PA9
* #define MOZZI_AUDIO_UPDATE_TIMER ... // Second hardware timer to claim. Default TIM2
* #define MOZZI_AUDIO_BITS_PER_CHANNEL ... // Bits per pin. Default is 7
* @endcode
*
* @section stm32duino_external MOZZI_OUTPUT_EXTERNAL_TIMED and MOZZI_OUTPUT_EXTERNAL_CUSTOM
* See @ref external_audio .
* The (single) hardware timer claimed for MOZZI_OUTPUT_EXTERNAL_TIMED may be configured using "MOZZI_AUDIO_UPDATE_TIMER" (default: TIM2).
*/



/***************************************** ADVANCED SETTTINGS -- STM32 (libmaple-based core) ***********************************************************
*
* The settings in the following section applies to the STM32 (libmaple-based core) architecture.
*
* It is generally not recommended to change anything, here, unless you really know, what you are doing and/or
* are willing to rough it out by yourself.
*
********************************************************************************************************************************/

/** @ingroup hardware
* @page hardware_stm32_maple Mozzi on STM32duino-based boards.
*
* @note
* Be sure to understand the info given at @ref hardwware_stm32_disambiguation . This page is about using Mozzi with the STM32 "libmaple based" core.
*
* @note
* This port may look similar to, but uses a different default GPIO pinout than @hardware_stm32duino !
*
* The following audio modes (see @ref MOZZI_AUDIO_MODE) are currently supported on this hardware:
* - MOZZI_OUTPUT_EXTERNAL_TIMED
* - MOZZI_OUTPUT_EXTERNAL_CUSTOM
* - MOZZI_OUTPUT_PWM
* - MOZZI_OUTPUT_PWM_2PIN
*
* The default mode is @ref stm32_maple_pwm .
*
* @section stm32_maple_pwm MOZZI_OUTPUT_PWM
* 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).
* 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.
* 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.
* The following settings may be costumized, if desired:
*
* @code
* #define MOZZI_AUDIO_PIN_1 ... // Left / mono output pin. Default: PB8
* #define MOZZI_AUDIO_PWM_TIMER ... // Must be set ot the hardware timer connected to the above pin. Default: 4
* #define MOZZI_AUDIO_UPDATE_TIMER ... // Second hardware timer to claim. Default 2
* #define MOZZI_AUDIO_BITS ... // Output resolution in bits. Default is 10
* // For stereo, only:
* #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
* @endcode
*
* @section stm32_maple_pwm MOZZI_OUTPUT_2PIN_PWM
* 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
* hardware setup, and configuration tradeoffs, see @ref avr_2pin_pwm . Stereo output is not available in this mode.
*
* Customizable configuration options:
* @code
* #define MOZZI_AUDIO_PIN_1 ... // High byte of the output. Default: PB8
* #define MOZZI_AUDIO_PIN_2 ... // Low byte of the output. Default: PB9
* #define MOZZI_AUDIO_PWM_TIMER ... // Must be set to the number of the hardware timer connect to the above pins. Default: 4
* #define MOZZI_AUDIO_UPDATE_TIMER ... // Second hardware timer to claim. Default TIM2
* #define MOZZI_AUDIO_BITS_PER_CHANNEL ... // Bits per pin. Default is 7
* @endcode
*
* @section stm32_maple_external MOZZI_OUTPUT_EXTERNAL_TIMED and MOZZI_OUTPUT_EXTERNAL_CUSTOM
* See @ref external_audio
* The (single) hardware timer claimed for MOZZI_OUTPUT_EXTERNAL_TIMED may be configured using "MOZZI_AUDIO_UPDATE_TIMER" (default: TIM2).
*/


/***************************************** ADVANCED SETTTINGS -- Teensy 3.x ***********************************************************
*
* The settings in the following section applies to Teensy 3.x boards
*
* It is generally not recommended to change anything, here, unless you really know, what you are doing and/or
* are willing to rough it out by yourself.
*
********************************************************************************************************************************/

/** @ingroup hardware
* @page hardware_teensy3 Mozzi on Teensy 3.0/3.1/3.2/3.4/3.5/LC boards.
*
* @note
* For Teensy 4.x see @ref hardware_teensy4
*
* @note
* This port requires the following two libraries (which should be part of a default installtion, however):
* - [Timer library](https://github.com/loglow/IntervalTimer) for Teensy 3.* by Daniel Gilbert
* - [ADC library](http://github.com/pedvide/ADC) by Pedro Villanueva
*
* The following audio modes (see @ref MOZZI_AUDIO_MODE) are currently supported on this hardware:
* - MOZZI_OUTPUT_EXTERNAL_TIMED
* - MOZZI_OUTPUT_EXTERNAL_CUSTOM
* - MOZZI_OUTPUT_INTERNAL_DAC
*
* The default mode is @ref teensy3_internal_dac .
*
* @section teensy3_internal_dac MOZZI_OUTPUT_INTERNAL_DAC
* Output is to the inbuilt DAC. Output resolution is 12 bits. Mono, only. The DAC output pin differs from board to boards.
* In most cases the appropriate pin will be set outmatically. If needed, you can specify the DAC pin, explicitly:
*
* @code
* #define MOZZI_AUDIO_PIN_1 ... // Default: A14, A12, or A21, depending on board
* @endcode
*
* @section teensy3_external MOZZI_OUTPUT_EXTERNAL_TIMED and MOZZI_OUTPUT_EXTERNAL_CUSTOM
* See @ref external_audio
*/

/***************************************** ADVANCED SETTTINGS -- Teensy 4.x ***********************************************************
*
* The settings in the following section applies to Teensy 4.x boards
*
* It is generally not recommended to change anything, here, unless you really know, what you are doing and/or
* are willing to rough it out by yourself.
*
********************************************************************************************************************************/

/** @ingroup hardware
* @page hardware_teensy4 Mozzi on Teensy 3.0/3.1/3.2/3.4/3.5/LC boards.
*
* @note
* For Teensy 3.x see @ref hardware_teensy3
*
* @note
* This port requires the following two libraries (which should be part of a default installtion, however):
* - [Timer library](https://github.com/loglow/IntervalTimer) for Teensy 4.* by Daniel Gilbert
* - [ADC library](http://github.com/pedvide/ADC) by Pedro Villanueva
*
* The following audio modes (see @ref MOZZI_AUDIO_MODE) are currently supported on this hardware:
* - MOZZI_OUTPUT_EXTERNAL_TIMED
* - MOZZI_OUTPUT_EXTERNAL_CUSTOM
* - MOZZI_OUTPUT_PWM
*
* The default mode is @ref teensy4_pwm .
*
* @section teensy4_pwm MOZZI_OUTPUT_PWM
* Output is to a GPIO pin (or two in stereo). The output resolution is fixed at 10 bits, and a 146484 kHz carrier frequency.
* The output pins can be configured as:
*
* @code
* #define MOZZI_AUDIO_PIN_1 ... // Left / mono output pin. Default: A8
* // For stereo, only:
* #define MOZZI_AUDIO_PIN_2 ... // Right channel output pin. Default: A9
* @endcode
*
* @section teensy4_external MOZZI_OUTPUT_EXTERNAL_TIMED and MOZZI_OUTPUT_EXTERNAL_CUSTOM
* See @ref external_audio
*/
2 changes: 1 addition & 1 deletion MozziGuts.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@
#include "mozzi_analog.h"


#include "internal/config_check_generic.h"
#include "internal/config_checks_generic.h"

#if (STEREO_HACK == true)
extern int audio_out_1, audio_out_2;
Expand Down
4 changes: 2 additions & 2 deletions MozziGuts_impl_AVR.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,8 +85,6 @@ void setupMozziADC(int8_t speed) {
setupFastAnalogRead(speed);
}

#endif

void setupFastAnalogRead(int8_t speed) {
if (speed == FAST_ADC){ // divide by 16
ADCSRA |= (1 << ADPS2);
Expand All @@ -103,6 +101,8 @@ void setupFastAnalogRead(int8_t speed) {
}
}

#endif

////// END analog input code ////////


Expand Down
5 changes: 2 additions & 3 deletions MozziGuts_impl_ESP32.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,10 @@ void startSecondADCReadOnCurrentChannel() {
}
void setupMozziADC(int8_t speed) {
}
#endif

void setupFastAnalogRead(int8_t speed) {
#warning Fast analog read not implemented on this platform
}

#endif
////// END analog input code ////////


Expand Down
3 changes: 1 addition & 2 deletions MozziGuts_impl_ESP8266.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,9 @@ void startSecondADCReadOnCurrentChannel() {
}
void setupMozziADC(int8_t speed) {
}
#endif
void setupFastAnalogRead(int8_t speed) {
#warning Fast analog read not implemented on this platform
}
#endif
////// END analog input code ////////


Expand Down
2 changes: 1 addition & 1 deletion MozziGuts_impl_MBED.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ static void startAudioInput() {}; // dummy to ease coding
#endif

#if MOZZI_IS(MOZZI_ANALOG_READ, MOZZI_ANALOG_READ_STANDARD)
#error not yet implemented
/** NOTE: This section deals with implementing (fast) asynchronous analog reads, which form the backbone of mozziAnalogRead(), but also of USE_AUDIO_INPUT (if enabled).
* This template provides empty/dummy implementations to allow you to skip over this section, initially. Once you have an implementation, be sure to enable the
* #define, above */
Expand Down Expand Up @@ -91,7 +92,6 @@ void startSecondADCReadOnCurrentChannel() {
/** NOTE: Code needed to set up faster than usual analog reads, e.g. specifying the number of CPU cycles that the ADC waits for the result to stabilize.
* This particular function is not super important, so may be ok to leave empty, at least, if the ADC is fast enough by default. */
void setupFastAnalogRead(int8_t speed) {
#warning Fast analog read not implemented on this platform
}

/** NOTE: Code needed to initialize the ADC for asynchronous reads. Typically involves setting up an interrupt handler for when conversion is done, and
Expand Down
1 change: 1 addition & 0 deletions MozziGuts_impl_SAMD.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

////// BEGIN analog input code ////////
#if MOZZI_IS(MOZZI_ANALOG_READ, NOZZI_ANALOG_READ_STANDARD)
#error not yet implemented
#define getADCReading() 0
#define channelNumToIndex(channel) channel
uint8_t adcPinToChannelNum(uint8_t pin) {
Expand Down
43 changes: 27 additions & 16 deletions MozziGuts_impl_template.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@
* Files involved:
* 1. Modify hardware_defines.h, adding a macro to detect your target platform
* 2. Modify MozziGuts.cpp to include MozziGuts_impl_YOURPLATFORM.hpp
* 3. Modify MozziGuts.h to include AudioConfigYOURPLATFORM.h
* 4. Copy this file to MozziGuts_impl_YOURPLATFORM.hpp and adjust as necessary
* (If your platform is very similar to an existing port, it may instead be better to modify the existing MozziGuts_impl_XYZ.hpp/AudioConfigYOURPLATFORM.h,
* 3. Modify internal/config_checks_generic.h to include internal/config_checks_YOURPLATFORM.h
* 4. Copy this file to MozziGuts_impl_YOURPLATFORM.hpp and adjust as necessary, same for internal/config_checks_template.h
* (If your platform is very similar to an existing port, it may instead be better to modify the existing MozziGuts_impl_XYZ.hpp/config_checks_XYZ.h,
* instead of steps 2-3.).
* Some platforms may need small modifications to other files as well, e.g. mozzi_pgmspace.h
*
Expand Down Expand Up @@ -51,8 +51,9 @@
* #define MOZZI_ANALOG_READ MOZZI_ANALOG_READ_STANDARD
* #endif
*
* The only function in this section that is always defined is setupFastAnalogRead() (but this, too, may be left empty, initially).
* Also, of course, remove the #error line, below
*/
#error not yet implemented

// Insert here code to read the result of the latest asynchronous conversion, when it is finished.
// You can also provide this as a function returning unsigned int, should it be more complex on your platform
Expand Down Expand Up @@ -99,14 +100,13 @@ void stm32_adc_eoc_handler() {
}
*/

#endif

/** NOTE: Code needed to set up faster than usual analog reads, e.g. specifying the number of CPU cycles that the ADC waits for the result to stabilize.
* This particular function is not super important, so may be ok to leave empty, at least, if the ADC is fast enough by default. */
void setupFastAnalogRead(int8_t speed) {
#warning Fast analog read not implemented on this platform
}

#endif

////// END analog input code ////////

////// BEGIN audio output code //////
Expand All @@ -121,23 +121,34 @@ void setupFastAnalogRead(int8_t speed) {
* analog reads for instance. */
//#define AUDIO_HOOK_HOOK

#if (EXTERNAL_AUDIO_OUTPUT != true) // otherwise, the last stage - audioOutput() - will be provided by the user
/** NOTE: This is the function that actually write a sample to the output. In case of EXTERNAL_AUDIO_OUTPUT == true, it is provided by the library user, instead. */
/* NOTE: Code sections that are needed for a certain audio mode, only, should be guarded as follows (in this example, code will compile for the
* two modes MOZZI_OUTPUT_PWM, and MOZZI_OUTPUT_INTERNAL_DAC (should your port happen to support these two).
*
* Keep in mind that you probably want to support MOZZI_OUTPUT_EXTERNAL_TIMED, and MOZZI_OUTPUT_EXTERNAL_CUSTOM, too, which is usually very
* easy: For both, do *not* provide an audioOutput() function, as this will be provided by the user. For MOZZI_OUTPUT_EXTERNAL_TIMED make sure some
* timer is set up to call defaultAudioOutput() at MOZZI_AUDIO_RATE. For MOZZI_OUTPUT_EXTERNAL_CUSTOM, nothing else will be needed. */

#if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM, MOZZI_OUTPUT_INTERNAL_DAC) // just an example!
/** NOTE: This is the function that actually write a sample to the output. In case of the two EXTERNAL modes, it is provided by the library user, instead. */
inline void audioOutput(const AudioOutput f) {
// e.g. analogWrite(AUDIO_CHANNEL_1_PIN, f.l()+AUDIO_BIAS);
#if (AUDIO_CHANNELS > 1)
// e.g. analogWrite(AUDIO_CHANNEL_2_PIN, f.r()+AUDIO_BIAS);
#endif
// e.g. analogWrite(MOZZI_AUDIO_CHANNEL_1_PIN, f.l()+MOZZI_AUDIO_BIAS);
# if (MOZZI_AUDIO_CHANNELS > 1)
// e.g. analogWrite(MOZZI_AUDIO_CHANNEL_2_PIN, f.r()+MOZZI_AUDIO_BIAS);
# endif
}
#endif

static void startAudio() {
// Add here code to get audio output going. This usually involves:
// 1) setting up some DAC mechanism (e.g. setting up a PWM pin with appropriate resolution
// 2a) setting up a timer to call defaultAudioOutput() at AUDIO_RATE
// 2a) setting up a timer to call defaultAudioOutput() at MOZZI_AUDIO_RATE
// OR 2b) setting up a buffered output queue such as I2S (see ESP32 / ESP8266 for examples for this setup)
#if (EXTERNAL_AUDIO_OUTPUT != true)
// remember that the user may configure EXTERNAL_AUDIO_OUTPUT, in which case, you'll want to provide step 2a), and only that.
#if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM)
// [...]
#elif MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_INTERNAL_DAC)
// [...]
#elif MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_EXTERNAL_TIMED)
// remember that the user may configure MOZZI_OUTPUT_EXTERNAL_TIMED, in which case, you'll want to provide step 2a), and only that.
#endif
}

Expand Down
Loading

0 comments on commit 219980e

Please sign in to comment.