Mozzi  version v2.0
sound synthesis library for Arduino
MozziGuts_impl_template.hpp
Go to the documentation of this file.
1 /*
2  * MozziGuts_impl_template.hpp
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 /** @file MozziGuts_impl_template.hpp Template for implementation of new ports
13  *
14  * README!
15  * This file is meant to be used as a template when adding support for a new platform. Please read these instructions, first.
16  *
17  * Files involved:
18  * 1. Modify hardware_defines.h, adding a macro to detect your target platform
19  * 2. Modify MozziGuts.cpp to include MozziGuts_impl_YOURPLATFORM.hpp
20  * 3. Modify internal/config_checks_generic.h to include internal/config_checks_YOURPLATFORM.h
21  * 4. Copy this file to MozziGuts_impl_YOURPLATFORM.hpp and adjust as necessary, same for internal/config_checks_template.h
22  * (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,
23  * instead of steps 2-3.).
24  * Some platforms may need small modifications to other files as well, e.g. mozzi_pgmspace.h
25  *
26  * How to implement MozziGuts_impl_YOURPLATFORM.hpp:
27  * - Follow the NOTEs provided in this file
28  * - Read the doc at the top of AudioOutput.h for a better understanding of the basic audio output framework
29  * - Take a peek at existing implementations for other hardware (e.g. TEENSY3/4 is rather complete while also simple at the time of this writing)
30  * - Wait for more documentation to arrive
31  * - Ask when in doubt
32  * - Don't forget to provide a PR when done (it does not have to be perfect; e.g. many ports skip analog input, initially)
33  */
34 
35 // The main point of this check is to document, what platform & variants this implementation file is for.
36 #if !(IS_MYPLATFORM())
37 # error "Wrong implementation included for this platform"
38 #endif
39 // Add platform specific includes and declarations, here
40 
41 //#include <my_hardware_header.h>
42 
43 // In order to allow simple yet efficient user configuration, the entire contents of this file are compiled in the same translation unit
44 // as (the main file of) the user sketch. To avoid name clashes, we encapsulate everyghing in a namespace.
45 // For the most part, this namescape can just extend from the start of the file to the end (as shown, here), and you will not have to
46 // worry about it. However, there may be a few situations, where you have to "leave" the MozziPrivate namespace. This includes:
47 // - When you include a further (hardware-dependent library). Consider gathering all includes at the top of this file, instead.
48 // - When you provide definitions for special names, importantly for ISR-functions. If these would be placed in the namespace, the linker would not
49 // recognize them as the definition of the intended ISR-vector. See MozziGuts_impl_AVR.hpp for examples.
50 
51 namespace MozziPrivate {
52 
53 ////// BEGIN analog input code ////////
54 
55 #if MOZZI_IS(MOZZI_ANALOG_READ, MOZZI_ANALOG_READ_STANDARD)
56 /** NOTE: This section deals with implementing (fast) asynchronous analog reads, which form the backbone of mozziAnalogRead(), but also of MOZZI_AUDIO_INPUT (if enabled).
57  *
58  * It is possible, and even recommended, to skip over this section, initially, when starting a new port. Once you have an implementation, be sure to include something like this
59  * in your platform configuration checks:
60  *
61  * // analog reads shall be enabled by default on platforms that support it
62  * #if not defined(MOZZI_ANALOG_READ)
63  * #define MOZZI_ANALOG_READ MOZZI_ANALOG_READ_STANDARD
64  * #endif
65  *
66  * Also, of course, remove the #error line, below
67  */
68 #error not yet implemented
69 
70 // Insert here code to read the result of the latest asynchronous conversion, when it is finished.
71 // You can also provide this as a function returning unsigned int, should it be more complex on your platform
72 #define getADCReading() GET_MY_PLATFORM_ADC_REGISTER
73 
74 /** NOTE: On "pins" vs. "channels" vs. "indices"
75  * "Pin" is the pin number as would usually be specified by the user in mozziAnalogRead().
76  * "Channel" is an internal ADC channel number corresponding to that pin. On many platforms this is simply the same as the pin number, on others it differs.
77  * In other words, this is an internal representation of "pin".
78  * "Index" is the index of the reading for a certain pin/channel in the array of analog_readings, ranging from 0 to NUM_ANALOG_PINS. This, again may be the
79  * same as "channel" (e.g. on AVR), however, on platforms where ADC-capable "channels" are not numbered sequentially starting from 0, the channel needs
80  * to be converted to a suitable index.
81  *
82  * In summary, the semantics are roughly
83  * mozziAnalogRead(pin) -> _ADCimplementation_(channel) -> analog_readings[index]
84  * Implement adcPinToChannelNum() and channelNumToIndex() to perform the appropriate mapping.
85  */
86 // NOTE: Theoretically, adcPinToChannelNum is public API for historical reasons, thus cannot be replaced by a define
87 #define channelNumToIndex(channel) channel
89  return pin;
90 }
91 
92 /** NOTE: Code needed to trigger a conversion on a new channel */
94 }
95 
96 /** NOTE: Code needed to trigger a subsequent conversion on the latest channel. If your platform has no special code for it, you should store the channel from
97  * adcStartConversion(), and simply call adcStartConversion(previous_channel), here. */
99 }
100 
101 /** NOTE: Code needed to initialize the ADC for asynchronous reads. Typically involves setting up an interrupt handler for when conversion is done, and
102  * possibly calibration. */
103 void setupMozziADC(int8_t speed) {
105  // insert further custom code
106 }
107 
108 /* NOTE: Most platforms call a specific function/ISR when conversion is complete. Provide this function, here.
109  * From inside its body, simply call advanceADCStep(). E.g.:
110 void stm32_adc_eoc_handler() {
111  advanceADCStep();
112 }
113 */
114 
115 /** 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.
116  * This particular function is not super important, so may be ok to leave empty, at least, if the ADC is fast enough by default. */
118 }
119 
120 #endif
121 
122 ////// END analog input code ////////
123 
124 ////// BEGIN audio output code //////
125 /* NOTE: Some platforms rely on control returning from loop() every so often. However, updateAudio() may take too long (it tries to completely fill the output buffer,
126  * which of course is being drained at the same time, theoretically it may not return at all). If you set this define, it will be called once per audio frame to keep things
127  * running smoothly. */
128 //#define LOOP_YIELD yield();
129 
130 /* NOTE: On some platforms, what can be called in the ISR used to output the sound is limited.
131  * This define can be used, for instance, to output the sound in audioHook() instead to overcome
132  * this limitation (see MozziGuts_impl_MBED.hpp). It can also be used if something needs to be called in audioHook() regarding
133  * analog reads for instance. */
134 //#define AUDIO_HOOK_HOOK
135 
136 /* 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
137  * two modes MOZZI_OUTPUT_PWM, and MOZZI_OUTPUT_INTERNAL_DAC (should your port happen to support these two).
138  *
139  * Keep in mind that you probably want to support MOZZI_OUTPUT_EXTERNAL_TIMED, and MOZZI_OUTPUT_EXTERNAL_CUSTOM, too, which is usually very
140  * 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
141  * timer is set up to call defaultAudioOutput() at MOZZI_AUDIO_RATE. For MOZZI_OUTPUT_EXTERNAL_CUSTOM, nothing else will be needed. */
142 
143 #if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM, MOZZI_OUTPUT_INTERNAL_DAC) // just an example!
144 /** 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. */
145 inline void audioOutput(const AudioOutput f) {
146  // e.g. analogWrite(MOZZI_AUDIO_CHANNEL_1_PIN, f.l()+MOZZI_AUDIO_BIAS);
147 # if (MOZZI_AUDIO_CHANNELS > 1)
148  // e.g. analogWrite(MOZZI_AUDIO_CHANNEL_2_PIN, f.r()+MOZZI_AUDIO_BIAS);
149 # endif
150 }
151 #endif
152 
153 static void startAudio() {
154  // Add here code to get audio output going. This usually involves:
155  // 1) setting up some DAC mechanism (e.g. setting up a PWM pin with appropriate resolution
156  // 2a) setting up a timer to call defaultAudioOutput() at MOZZI_AUDIO_RATE
157  // OR 2b) setting up a buffered output queue such as I2S (see ESP32 / ESP8266 for examples for this setup)
158 #if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM)
159  // [...]
160 #elif MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_INTERNAL_DAC)
161  // [...]
162 #elif MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_EXTERNAL_TIMED)
163  // remember that the user may configure MOZZI_OUTPUT_EXTERNAL_TIMED, in which case, you'll want to provide step 2a), and only that.
164 #endif
165 }
166 
167 void stopMozzi() {
168  // Add here code to pause whatever mechanism moves audio samples to the output
169 }
170 ////// END audio output code //////
171 
172 //// BEGIN Random seeding ////////
173 void MozziRandPrivate::autoSeed() {
174  // Add here code to initialize the values of MozziRandPrivate::x, MozziRandPrivate::y, and MozziRandPrivate::z to some random values
175  // This doesn't need to be crypographically safe. If nothing better is available, e.g. try reading an internal temperature sensor
176  // in order to get some noise. It also doesn't have to be fast.
177  // It *should* however ensure that rand() sequences will differ across reboots, after randSeed() has been called.
178  // x, y, and z are already initialized to non-zero, when this function is called.
179  // It's ok to leave this unimplemented, initially.
180 #warning Automatic random seeding is not implemented on this platform
181 }
182 //// END Random seeding ////////
183 
184 } // namespace MozziPrivate