Single compilation unit / In-line configuration

.github/workflows/compile_examples.yml

@@ -62,6 +62,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v3
 
+      - name: Add marker file for github run
+        run: echo "#define IN_GITHUB_RUNNER 1" > detect_github_runner.h
+
       - name: Compile examples
         uses: arduino/compile-sketches@v1
         with:

AudioOutput.h

@@ -44,10 +44,8 @@
  * @see MonoOutput::fromNBit(), StereoOutput::fromNBit()
  */
 
-#ifndef AUDIOOUTPUT
-#define AUDIOOUTPUT
-
-#include "mozzi_config.h"
+#ifndef AUDIOOUTPUT_H
+#define AUDIOOUTPUT_H
 
 /** The type used to store a single channel of a single frame, internally. For compatibility with earlier versions of Mozzi this is defined as int.
  *  If you do not care about keeping old sketches working, you may be able to save some RAM by using int16_t, instead (on boards where int is larger
@@ -79,7 +77,7 @@
  */
 #define AudioOutput_t AudioOutputStorage_t
 /** Representation of an single audio output sample/frame. This #define maps to either MonoOutput or StereoOutput, depending on what is configured
- *  in mozzi_config.h. Since the two are source compatible to a large degree, it often isn't even necessary to test, which it is, in your code. E.g.
+ *  in MOZZI_AUDIO_CHANNELS. Since the two are source compatible to a large degree, it often isn't even necessary to test, which it is, in your code. E.g.
  *  both have functions l() and r(), to return "two" audio channels (which will be the same in case of mono).
  *
  *  You will not usually use or encounter this definition, unless using @ref external_audio output mode.
@@ -98,7 +96,10 @@ struct StereoOutput {
   /** Conversion to int operator: If used in a mono config, returns only the left channel (and gives a compile time warning). 
       This _could_ be turned into an operator for implicit conversion in this case. For now we chose to apply conversion on demand, only, as most of the time
       using StereoOutput in a mono config, is not intended. */
-  inline AudioOutput_t portable() const __attribute__((deprecated("Sketch generates stereo output, but Mozzi is configured for mono. Check mozzi_config.h."))) { return _l; };
+  inline AudioOutput_t portable() const __attribute__((deprecated("Sketch generates stereo output, but Mozzi is configured for mono. Check MOZZI_AUDIO_CHANNELS setting."))) { return _l; };
+#  if GITHUB_RUNNER_ACCEPT_STEREO_IN_MONO
+  inline operator AudioOutput_t() const __attribute__((deprecated("Stereo converted to mono on github runner"))) { return _l; };
+#  endif
 #endif
   AudioOutputStorage_t l() const { return _l; };
   AudioOutputStorage_t r() const { return _r; };
@@ -139,7 +140,7 @@ struct MonoOutput {
   /** Conversion to stereo operator: If used in a stereo config, returns identical channels (and gives a compile time warning).
       This _could_ be turned into an operator for implicit conversion in this case. For now we chose to apply conversion on demand, only, as most of the time
       using StereoOutput in a mono config, is not intended. */
-  inline StereoOutput portable() const __attribute__((deprecated("Sketch generates mono output, but Mozzi is configured for stereo. Check mozzi_config.h."))) { return StereoOutput(_l, _l); };
+  inline StereoOutput portable() const __attribute__((deprecated("Sketch generates mono output, but Mozzi is configured for stereo. Check MOZZI_AUDIO_CHANNELS setting."))) { return StereoOutput(_l, _l); };
 #else
   /** Conversion to int operator. */
   inline operator AudioOutput_t() const { return _l; };
@@ -176,9 +177,11 @@ struct MonoOutput {
 };
 
 
+#if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_EXTERNAL_TIMED, MOZZI_OUTPUT_EXTERNAL_CUSTOM)
 /** When setting using one of the external output modes (@ref MOZZI_OUTPUT_EXTERNAL_TIMED or @ref MOZZI_OUTPUT_EXTERNAL_CUSTOM) implement this function to take care of writing samples to the hardware.
  *  In all otther cases, it will be provided by the platform implementation. You should never call this function, directly, in your sketch. */
 void audioOutput(const AudioOutput f);
+#endif
 #if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_EXTERNAL_CUSTOM)
 /** For @ref MOZZI_OUTPUT_EXTERNAL_CUSTOM implement this function to return true, if and only if your hardware (or custom buffer) is ready to accept the next sample. */
 inline bool canBufferAudioOutput();

AutoMap.h

@@ -21,6 +21,9 @@
 
 #include "AutoRange.h"
 
+/** @defgroup sensortools Automatic range adjustment
+*/
+
 /** @ingroup sensortools
 Automatically map an input value to an output range without knowing the precise range of inputs beforehand.
 */

IntegerType.h

@@ -3,6 +3,9 @@
 
 #include <Arduino.h>
 
+/** @ingroup util
+Provides appropriate integer types that can bit the given number of bytes on this platform (at most 64).
+*/
 template<uint8_t BYTES> struct IntegerType {
     // at an odd value, such as 3 bytes? Add one more byte (up to at most 8 bytes)..
     typedef typename IntegerType<(BYTES < 8) ? (BYTES+1) : 8>::unsigned_type unsigned_type;

Mozzi.h

@@ -0,0 +1,28 @@
+/*
+ * Mozzi.h
+ *
+ * Copyright 2024, Tim Barrass and the Mozzi team
+ *
+ * This file is part of Mozzi.
+ *
+ * Mozzi is licensed under a Creative Commons
+ * Attribution-NonCommercial-ShareAlike 4.0 International License.
+ *
+ */
+
+/** @ingroup core 
+ * @file Mozzi.h
+ *
+ * This is the main include file in Mozzi. Almost all sketches using Mozzi will want to include this file @em exactly once.
+ *
+ * Should your sketch require \ref core Mozzi functions in more than one translation unit (i.e. you have more than one .cpp-file
+ * in your sketch itself), only *one* of these shall include this file, while any others shall include \ref MozziHeadersOnly instead.
+ * (Failing to heed this advice will lead to "duplicate definition" errors.)
+ */
+
+#ifndef MOZZI_H_
+#define MOZZI_H_
+
+#include "MozziGuts.h"
+
+#endif

MozziGuts.h

@@ -12,31 +12,25 @@
 #ifndef MOZZIGUTS_H_
 #define MOZZIGUTS_H_
 
-//#define F_CPU 8000000 // testing
+#include "Arduino.h"
 
-#if ARDUINO >= 100
- #include "Arduino.h"
-#else
- #include "WProgram.h"
+#include "MozziConfigValues.h"
+
+#if !(defined(MOZZI_H_) || defined(MOZZI_HEADERS_ONLY_H_))
+#warning Direct inclusion of MozziGuts.h is deprecated. Use Mozzi.h, instead, and read about porting to Mozzi 2.0
+#define MOZZI_COMPATIBILITY_LEVEL MOZZI_COMPATIBILITY_1_1
 #endif
 
 #include "hardware_defines.h"
-#include "mozzi_config.h"
 
 #if IS_TEENSY3() || IS_TEENSY4()
 // required from http://github.com/pedvide/ADC for Teensy 3.*
 #include <ADC.h>
 #endif
 
-#include "mozzi_analog.h"
-
-
 #include "internal/config_checks_generic.h"
 
-#if (STEREO_HACK == true)
-extern int audio_out_1, audio_out_2;
-#endif
-
+#include "mozzi_analog.h"
 #include "AudioOutput.h"
 
 // TODO Mozzi 2.0: These typedef probably obsolete?
@@ -93,7 +87,7 @@ forked version of Mozzi on github, so sound production can continue while
 reading sensors.
 
 As it is, stopMozzi restores all the Timers used by Mozzi to their previous
-settings. Another scenario which could be easily hacked in MozziGuts.cpp could
+settings. Another scenario which could be easily hacked in MozziGuts.hpp could
 involve individually saving and restoring particular Timer registers depending
 on which one(s) are required for other tasks.
 
@@ -184,4 +178,8 @@ is output, so the resolution is 1/AUDIO_RATE microseconds (61 microseconds when
 */
 unsigned long mozziMicros();
 
+#ifndef _MOZZI_HEADER_ONLY
+#include "internal/MozziGuts.hpp"
+#endif
+
 #endif /* MOZZIGUTS_H_ */

MozziHeadersOnly.h

@@ -0,0 +1,28 @@
+/*
+ * MozziHeadersOnly.h
+ *
+ * Copyright 2024, Tim Barrass and the Mozzi team
+ *
+ * This file is part of Mozzi.
+ *
+ * Mozzi is licensed under a Creative Commons
+ * Attribution-NonCommercial-ShareAlike 4.0 International License.
+ *
+ */
+
+/** @ingroup core 
+ * @file MozziHeadersOnly.h
+ *
+ * This file provides declarations of the \ref core Mozzi functions, but no implementation. Use this only, if you have more than one
+ * translation unit in your project (i.e. you have more than one .cpp-file in your sketch itself). Otherwise include \ref Mozzi.h, instead.
+ *
+ * (Failure to head this advice will lead to "symbol XY undefined" errors.).
+ */
+
+#ifndef MOZZI_HEADERS_ONLY_H_
+#define MOZZI_HEADERS_ONLY_H_
+
+#define _MOZZI_HEADER_ONLY
+#include "MozziGuts.h"
+
+#endif

Oscil.h

@@ -14,12 +14,8 @@
 #ifndef OSCIL_H_
 #define OSCIL_H_
 
-#if ARDUINO >= 100
- #include "Arduino.h"
-#else
- #include "WProgram.h"
-#endif
-#include "MozziGuts.h"
+#include "Arduino.h"
+#include "MozziHeadersOnly.h"
 #include "mozzi_fixmath.h"
 #include "mozzi_pgmspace.h"
 

Readme_Mozzi_2_0.md

@@ -1,6 +1,6 @@
 Porting to Mozzi 2.0
 
-// TODO: properly type up
+// TODO: These are just short notes taken while working. Needs to be typed up properly, in the end.
 
 
 changed config names and semantics TODO (incomplete)
@@ -28,16 +28,17 @@ all new
 general:
  - Added many config sanity checks. Some may be too strict, if so please mention
 
- Other removed stuff:
+Other removed stuff:
  - pauseMozzi() - was still declared but not defined -> not usable, anyway
  - unpauseMozzi() - was still declared but not defined -> not usable, anyway
-
-
-
-Documentation bits that still need to find a new home (many other bits were moved around, many, many duplicates merged into a common place, and seom obsoleted bits discarded):
-
-Contrary to earlier versions of Mozzi, this version does not take over Timer 0, and thus Arduino
-functions delay(), millis(), micros() and delayMicroseconds() remain usable in theory. That said,
-you should avoid these functions, as they are slow (or even blocking). For measuring time, refer
-to mozziMircos(). For delaying events, you can use Mozzi's EventDelay() unit instead
-(not to be confused with AudioDelay()).
+ - Teensy3/4: channel2sc1a -> thought to be unused, removed
+ - Teensy2: adc_mapping -> hidden away; use adcPinToChannelNum(), as on all other platforms, instead
+ - removed several inclusions of "WProgram.h". If using Arduino versions < 1.0, you need to update, seriously ;-)  (TODO many, many, instances of this are still around)
+ - Since Mozzi (AVR-port) no longer uses Timer 0 since a long time, the corresponding library (utility/TimerZero.h) has now been removed, too.
+   The Arduino functions delay(), millis(), micros() and delayMicroseconds() should now be usable in theory. That said,
+   you should avoid these functions, as they are slow (or even blocking). For measuring time, refer
+   to mozziMicros(). For delaying events, you can use Mozzi's EventDelay() unit instead (not to be confused with AudioDelay()).
+
+Moved headers:
+ - Header files not meant for user inclusion have been moved to "internal"
+ - New sketches should include "Mozzi.h", rather than "MozziGuts.h", thereby documenting, they have been written for Mozzi 2.0+

Sample.h

@@ -12,7 +12,7 @@
 #ifndef SAMPLE_H_
 #define SAMPLE_H_
 
-#include "MozziGuts.h"
+#include "MozziHeadersOnly.h"
 #include "mozzi_fixmath.h"
 #include "mozzi_pgmspace.h"
 

WavePacket.h

@@ -13,13 +13,13 @@
 #ifndef WAVEPACKET_H
 #define WAVEPACKET_H
 
-#include <MozziGuts.h>
-#include <Oscil.h>
-#include <tables/cos8192_int8.h>
-#include <mozzi_fixmath.h>
-#include <Phasor.h>
-#include <Line.h>
-#include <meta.h>
+#include "MozziHeadersOnly.h"
+#include "Oscil.h"
+#include "tables/cos8192_int8.h"
+#include "mozzi_fixmath.h"
+#include "Phasor.h"
+#include "Line.h"
+#include "meta.h"
 
 
 enum algorithms {SINGLE,DOUBLE};

config/mozzi_config_documentation.h

@@ -1,8 +1,10 @@
 #ifdef FOR_DOXYGEN_ONLY
 /** @file */
 
-/*! @defgroup config Mozzi Configuration options
- * @brief Mozzi Configuration
+/*! @defgroup config Mozzi Configuration options */
+
+/** @ingroup config
+ * @page config_main Mozzi Configuration
  *
  * @section config_general Configuring Mozzi
  *
@@ -123,7 +125,7 @@
  * @note
  * For compatibility reasons, the option AUDIO_RATE is automatically set to the same value as this option, and you will find some uses of that in old (pre Mozzi 2.0) code examples.
  * It is advised to use only MOZZI_AUDIO_RATE in new code, however.
- * TODO: Only do the above, if MozziGuts.h, rather than Mozzi.h was included?
+ * TODO: Only do the above, for MOZZI_COMPATIBILITY_LEVEL < MOZZI_COMPATIBILITY_2_0?
  */
 #define MOZZI_AUDIO_RATE FOR_DOXYGEN_ONLY
 

examples/01.Basics/Control_Gain/Control_Gain.ino

@@ -17,7 +17,7 @@
     Tim Barrass 2012, CC by-nc-sa.
 */
 
-#include <MozziGuts.h>
+#include <Mozzi.h>
 #include <Oscil.h> // oscillator template
 #include <tables/sin2048_int8.h> // sine table for oscillator
 

examples/01.Basics/Sinewave/Sinewave.ino

@@ -16,7 +16,7 @@
     Tim Barrass 2012, CC by-nc-sa.
 */
 
-#include <MozziGuts.h>
+#include <Mozzi.h>
 #include <Oscil.h> // oscillator template
 #include <tables/sin2048_int8.h> // sine table for oscillator
 

examples/01.Basics/Sinewave_HIFI/Sinewave_HIFI.ino

@@ -3,16 +3,10 @@
 
     Demonstrates the use of Oscil to play a wavetable.
 
-    This sketch using HIFI mode on AVR (i.e. the classic Arduino borads, not Teensy 3.x and friends).
-
-    IMPORTANT: this sketch requires Mozzi/mozzi_config.h to be
-    be changed from STANDARD mode to HIFI.
-    In Mozz/mozzi_config.h, change
-    #define AUDIO_MODE STANDARD
-    //#define AUDIO_MODE HIFI
-    to
-    //#define AUDIO_MODE STANDARD
-    #define AUDIO_MODE HIFI
+    Important:
+    This sketch uses MOZZI_OUTPUT_2PIN_PWM (aka HIFI) output mode, which
+    is not available on all boards (among others, it works on the
+    classic Arduino boards, but not Teensy 3.x and friends).
 
     Circuit: Audio output on digital pin 9 and 10 (on a Uno or similar),
     Check the Mozzi core module documentation for others and more detail
@@ -41,15 +35,18 @@
     Tim Barrass 2012-13, CC by-nc-sa.
 */
 
-#include <MozziGuts.h>
+#include <MozziConfigValues.h>
+#define MOZZI_AUDIO_MODE MOZZI_OUTPUT_2PIN_PWM
+
+#include <Mozzi.h>
 #include <Oscil.h> // oscillator template
 #include <tables/sin2048_int8.h> // sine table for oscillator
 
 // use: Oscil <table_size, update_rate> oscilName (wavetable), look in .h file of table #included above
 Oscil <SIN2048_NUM_CELLS, AUDIO_RATE> aSin(SIN2048_DATA);
 
 void setup(){
-  startMozzi(); // uses the default control rate of 64, defined in mozzi_config.h
+  startMozzi(); // uses the default control rate of 64
   aSin.setFreq(440); // set the frequency
 }
 

examples/01.Basics/Skeleton/Skeleton.ino

@@ -1,4 +1,4 @@
-#include <MozziGuts.h>        // at the top of your sketch
+#include <Mozzi.h>        // at the top of your sketch
 #define CONTROL_RATE 64
 
 void setup() {

examples/01.Basics/Skeleton_Multi/Skeleton_Multi.ino

@@ -4,7 +4,7 @@
  *  Unless you have good reason to do this, it is recommended to base your sketch on the
  *  single-file "Skeleton" example, instead. */
 
-#include <MozziGuts.h>        // at the top of your sketch
+#include <Mozzi.h>        // at the top of your sketch
 
 void setup() {
   startMozzi(64);

examples/01.Basics/Skeleton_Multi/Skeleton_Multi_Unit2.cpp

@@ -1,4 +1,6 @@
-#include <MozziGuts.h>        // This file, too, will have to include the Mozzi headers.
+#include <MozziHeadersOnly.h>        // <Mozzi.h> should be included only once in the whole program. Sketches needing
+                                     // core Mozzi functions in more than one .cpp file, shall include MozziHeadersOnly.h
+                                     // in all but one.
 
 AudioOutput_t updateAudio() {
   return MonoOutput::from8Bit(0);  // just a dummy

examples/01.Basics/Table_Resolution/Table_Resolution.ino

@@ -14,7 +14,7 @@
 	 Tim Barrass 2012, CC by-nc-sa.
 */
 
-#include <MozziGuts.h>
+#include <Mozzi.h>
 #include <Oscil.h>
 #include <tables/sin256_int8.h>
 #include <tables/sin512_int8.h>