Merge branch 'sensorium:master' into devel/Mozzi2

.github/workflows/compile_examples.yml

@@ -113,6 +113,7 @@ jobs:
       - name: Compile examples
         uses: arduino/compile-sketches@v1
         with:
+          cli-version: 0.35.3 # See https://github.com/arduino/arduino-cli/issues/2658. Current version (1.0.2) breaks with Teensy.
           github-token: ${{ secrets.GITHUB_TOKEN }}
           fqbn: ${{ matrix.board.fqbn }}
           platforms: ${{ matrix.board.platforms }}

Mozzi.h

@@ -10,6 +10,13 @@
  */
 
 
+/** @page basic_info Getting Started
+ *
+ * You are currently looking at the Mozzi API documentation. It is the most comprehensive source of all functions and
+ * classes available in Mozzi, but not necesarrily the best starting point for learning about Mozzi. For getting
+ * started, it is recommended to browse through the tutorials at https://sensorium.github.io/Mozzi/learn/ .
+ */
+
 /** @ingroup core 
  * @file Mozzi.h
  *

MozziGuts.h

@@ -53,6 +53,8 @@ typedef signed long int32_t;
 
 /*! @defgroup core Mozzi Core Functions
 
+The bones of every Mozzi sketch. 
+
 @ingroup core
 Sets up the timers for audio and control rate processes, storing the timer
 registers so they can be restored when Mozzi stops. startMozzi() goes in your sketch's

README.md

@@ -1,9 +1,6 @@
 # Mozzi  
 
-### sound synthesis library for Arduino  
-
-
-Tim Barrass   
+### sound synthesis library for Arduino     
 
 Currently your Arduino can only beep like a microwave oven. Mozzi brings
 your Arduino to life by allowing it to produce much more complex and interesting
@@ -18,78 +15,76 @@ passing or external synths.
 
 ***
 
-## Features  
--    16384 Hz sample rate, or experimental 32768 Hz rate.
--    8 bit or 14 bit audio output modes on a bare Arduino, up to 16 bit using an external DAC.
+## Features
+-    Available for a wide and growing range of MCUs, with and without inbuilt DACs: Arduino Uno R3 and R4, STM32, Teensy, ESP8266, ESP32, Raspberry Pi Pico, and more.
+-    Configurable sample rate, usually in powers of two (16384 Hz, or 32768 Hz).
 -    Variable control rate from 64 Hz upwards.
+-    Various inbuilt output modes, including 16 bit output to an external DAC.
+-    Allows interfacing to custom output routines, with examples for playing audio on external DAC modules, and even bluetooth.
 -    Useful basic audio toolkit: oscillators, samples, lines, envelopes, scheduling, filtering.
 -    Fast ADC and other cpu-efficient code utilities to help keep audio running smoothly.
 -    Example sketches for easy modification.
 -    Readymade wavetables and a script to convert your own soundfiles for Mozzi.
--    Usable on several platforms: Arduino, STM32, ESP, Teensy.
 -    Mozzi is designed to be easy to use, open source and extendable.
 
 ***
 
-## Installation  
-Use the "code" button on Mozzi's Github page to download a ZIP file of the latest developing code.  Import this into Arduino, following the instructions from the [Arduino libraries guide](http://arduino.cc/en/Guide/Libraries).
-
-*In the Arduino IDE, navigate to Sketch > Include Library > Add .ZIP Library. At the top of the drop down list, select the option to "Add .ZIP Library".*
-
-(Note: the files in the "releases" section on Github are now legacy.  The development code is recommended.)
+## Installation
+The easiest installation option nowadays is to install Mozzi via the Library Manager in your Arduino application:
+_Arduino➞Sketch➞Include Library➞Library Manager_ type "Mozzi" into the search field, then click "install".
+
+For other installation methods (e.g. the development version), see the [Download page](https://sensorium.github.io/Mozzi/download).
+
+## Quick Start
+To hear Mozzi, wire a 3.5mm audio jack with the centre to the audio out pin for your Arduino as shown in the table below, and the shield to GND on the Arduino.
+Plug into your computer and listen with a sound program like [Audacity](https://audacity.sourceforge.net/). (Or connect any other high-impedance input, like an active speaker)
+Try some examples from the __File > Examples > Mozzi__ menu.
+
+For more about audio output, including high quality output modes [Mozzi Output tutorial](https://sensorium.github.io/Mozzi/learn/output/).  
+
+### A note for users coming from Mozzi 1.x
+Mozzi 2.0 brings a lot of changes under the hood, and is not 100% source compatible with earlier versions of Mozzi. Most sketches should continue to compile, but with
+a lot of warnings. A few others will no longer work. See [Porting to Mozzi 2.0](https://sensorium.github.io/Mozzi/learn/porting/) for what to change.
+If desparate, there is still a "Mozzi_1" branch in the git repository, but this will not get any new development.
+
+## Supported boards, output modes and default pins
+> Table is not necessarily complete. Abbreviations explained below the table. The default output mode is in bold for each row. If stereo is supported, in a mode, the cell PWM-1 has two numbers with the second pin number is given in parentheses (+X).
+> Check the [hardware section of the API-documentation](https://sensorium.github.io/Mozzi/doc/html/hardware.html) for platform specific notes and (pin) configuration options.
+
+| **Board or family / Output mode** | PWM-1 | PWM-2 | PDM | inbuilt DAC | I2S DAC (native) |
+| ---------------------------------------------------- | ---------- | ---------- | ------- | ---------------- | ------------------------ |
+| *ATmega328/168*: Uno (R3), Nano, Pro Mini, Duemilanove, Leonardo, etc.  | **9 (+10)** | 9, 10 | | | |
+| *ATmega32U4*: Teensy, Teensy2, 2++ *B5/B6 correspond to pins 14/15 in Arduino* | **B5 (+B6)** | B5, B6 | | | |
+| *ATmega2560*: Arduino Mega, Freetronics EtherMega, etc.  | **11 (+12)** | 11, 12 |  |  |  |
+| *ATmega1284*: Sanguino  | **13 (+12)** | 13, 12 |  |  |  |
+| Teensy3.x - *note: DAC Pin number depends on model: A14, A12, or A21* |  |  |  | **DAC** |  |
+| Teensy4.x | **A8 (+A9)** |  |  |  |  |
+| *LGT8F328P*: "Register clone" of the ATmega328, uses the same code in Mozzi  | **9 (+10)** | 9, 10 |  |  |  |
+| *SAMD*: Arduino Nano 33 Iot, Adafruit Playground Express, Gemma M0 etc.  |  |  |  | **A0/Speaker** |  |
+| *Renesas Arduino Core*: Arduino Uno R4  |  |  |  | **A0** |  |
+| *Arduino MBED Core*: Arduino Giga (only model tested so far in this family)  |  |  | SERIAL2TX | **A13 (+A12)** |  |
+| *STM32 maple core*: Various STM32F1 and STM32F4 boards, "Blue/Black Pill"  | **PB8 (+PB9)** | PB8, PB9 |  |  |  |
+| *STM32duino (STM official) core*: Huge range of STM32Fx boards  | **PA8 (+PA9)** | PA8, PA9 |  |  |  |
+| *ESP8266*: ESP-01, Wemos D1 mini, etc. note: Beware of erratic pin labels |  |  | **GPIO2** |  | yes |
+| *ESP32: note: Beware of vastly different pin labels across board variants* |  |  | yes | **GPIO25 (+GPIO26)** | yes |
+| *RP2040*: Raspberry Pi Pico and friends  | **0 (+1)** | 0, 1 |  |  | yes |
+
+> - PWM-1: 1-pin PWM mode (`MOZZI_OUTPUT_PWM`)
+> - PWM-2: 2-pin PWM mode (`MOZZI_OUTPUT_2PIN_PWM`)
+> - PDM: Pulse density modulation, may be either `MOZZI_OUTPUT_PDM_VIA_SERIAL` or `MOZZI_OUTPUT_PDM_VIA_I2S`
+> - inbuilt DAC: `MOZZI_OUTPUT_INTERNAL_DAC`
+> - I2S DAC (native): native support for externally connected I2S DACs (`MOZZI_OUTPUT_I2S_DAC`). Since this requires several, often
+    configurable pins, and is never the default option, no pin numbers are shown in this table.
+> - **All** platforms also support "external" output modes (`MOZZI_OUTPUT_EXTERNAL_TIMED` or `MOZZI_OUTPUT_EXTERNAL_CUSTOM`), which allow
+    for connecting DACs or other external circuitry.
 
 ***
 
-## Quick Start  
-To hear Mozzi, connect a 3.5mm audio jack with the centre wire to the PWM output
-on Digital Pin 9 on the Arduino, and the ground to the Ground on the Arduino.
-Use this as a line out which you can plug into your computer and listen to with
-a sound program like [Audacity](http://audacity.sourceforge.net/).
-Try some examples from the __File > Examples > Mozzi__ menu.  
-
-Below is a list of the Digital Pins used by Mozzi for STANDARD_PLUS mode PWM audio out on different boards.
-Feedback about others is welcome.
-
-Model | Pin | Tested
------ | --- | ------
-Arduino Uno | 9	| yes
-Arduino Uno R4 | A0 | yes
-Arduino Duemilanove | 9	| yes
-Arduino Nano | 9 | yes
-Arduino Nano 33 Iot | A0 | yes
-Arduino Pro Mini | 9 | yes
-Arduino Leonardo | 9 | yes
-Arduino Mega | 11 | yes
-Arduino MBED (only the Giga has been tested, see "Hardware specific notes", below) | A13 | no
-Arduino Giga | A13 (jack) | yes
-Freetronics EtherMega | 11 | yes
-Ardweeny | 9 | yes     
-Boarduino | 9 | yes
-Teensy | 14 | -
-Teensy2 | B5 | yes  
-Teensy2++ | B5(25) | yes
-Teensy 3.0 3.1 LC 3.2 | DAC/D | yes
-Teensy 3.4, 3.5 | DAC/D | -
-Teensy 4.0 4.1 | A8 | yes
-Gemma M0 | A0 | yes
-Adafruit Playground Express | Built in Speaker | yes    
-Sanguino | 13	| -  
-STM32F1 maple core | PB8 | yes
-STM32F1 STM core | PA8 | yes
-STM32F4 STM core | PA8 | yes
-ESP8266 *see details* | GPIO2 | yes
-RP2040 | 0 | yes
-
-For details about HIFI mode, read the [Mozzi core module documentation](http://sensorium.github.io/Mozzi/doc/html/group__core.html#gae99eb43cb29bb03d862ae829999916c4/).  
-
-***
-
-## Using Mozzi  
-Here's a template for an empty Mozzi sketch:  
-
+## Using Mozzi
+Here's a template for an empty Mozzi sketch:
 
 ```
-#include <MozziGuts.h>   // at the top of your sketch
+#include <Mozzi.h>   // at the top of your sketch
 
 void setup() {
 	startMozzi();
@@ -99,68 +94,51 @@ void updateControl(){
 	// your control code
 }
 
-AudioOutput_t updateAudio() {
-	// your audio code which returns a 0-centered integer, typically in the 8bit or 16-bit range
-	return MonoOutput::from16Bit( [myvalue] );
+AudioOutput_t updateAudio(){
+	MonoOutput::from16Bit( [my_cool_sample] );
 }
 
 void loop() {
 	audioHook();
 }
 ```
 
-There's a detailed example explaining the different parts [here](http://sensorium.github.io/Mozzi/learn/a-simple-sketch/).
+There's a detailed example explaining the different parts [here](https://sensorium.github.io/Mozzi/learn/a-simple-sketch/).
 
-***
 
 ## Documentation
 
-There's documentation in the doc folder in the Mozzi download and [online](http://sensorium.github.io/Mozzi/doc/html/index.html).  
-There is practical help on the [learn](http://sensorium.github.io/Mozzi/learn/) page on the Mozzi site.  
+For getting started, browse the practical help on the [learn](https://sensorium.github.io/Mozzi/learn/) page on the Mozzi site.  
+API reference documentation is available in the doc folder in the Mozzi download and [online](http://sensorium.github.io/Mozzi/doc/html/index.html).  
 Start or look up a topic on the [users forum](https://groups.google.com/forum/#!forum/mozzi-users/).  
 Also, feel free to submit any issues on the [GitHub Mozzi site](https://github.com/sensorium/Mozzi/issues/).  
 Look for code and usage changes [here](extras/NEWS.txt).  
+For hardware specific details, including supported features, caveats, and hardware-dependent configuration options,
+refer to the [Hardware Section of the API-Documentation](https://sensorium.github.io/Mozzi/doc/html/hardware.html).
 
-***
-
-## General caveats and Workarounds
+## Compatibiliy issues
 
-* While Mozzi is running, calling `delay()`, `delayMicroseconds()`, or other functions which wait or cycle through loops can cause audio glitches.
-Mozzi provides `EventDelay()` for scheduling instead of `delay`. In general, make sure to write non-blocking code!
+* In most setups, Mozzi claims one or two hardware timers. This may result in incompatibilities with certain libraries, and / or the ability to use timer-based functions such as `analogWrite()`. As the details on this
+  differ a lot between the supported boards, read up on the details - and available workarounds - in the [ardware Section of the API-Documentation](https://sensorium.github.io/Mozzi/doc/html/hardware.html).
 
-* `analogRead()` is a time-consuming operation especially on the classic AVR boards. Mozzi provides `mozziAnalogRead()` as a drop-in replacement, which works in the
-background instead of blocking the processor.
+* There is also an example on emulating `analogWrite()` on any digitial pin in *Mozzi>examples>11.Communication>Sinewave_PWM_pins_HIFI*.
 
-* Depending on the hardware and configured audio output mode, Mozzi will usually claim one or more hardware timers. This may affect, among other things, the ability to
-use `analogWrite()`. Check the [Hardware Section of the Documentation](https://sensorium.github.io/Mozzi/doc/html/group__hardware.html) to options to configure ressource
-usage.
-  - If you need `analogWrite()`, you can do PWM output on any digital pins using the technique in *Mozzi>examples>11.Communication>Sinewave_PWM_pins_HIFI*.  
+* The timers can be made available with `stopMozzi()`, which stops audio interrupts, until you call `startMozzi()`.
 
-* As last resort, the timers can be made available with `stopMozzi()`, which stops audio interrupts, until you call `startMozzi()`.
+* Note that it is of utmost importance to write non-blocking code, such that the
+  audio buffer never runs low. Hints on how to do this, including why, and how you
+  should avoid using `delay()`, `analogRead()`, and how to make your code run faster,
+  can be found at [on the learn pages](https://sensorium.github.io/Mozzi/learn/hints/).
 
-***
-
-## Tweaking Arduino for Faster Audio Code
-
-If you need your synth to run faster on AVR architectures, Arduino versions above 1.5 can be tweaked to optimise compiled code for speed instead of small size.  
 
-Find Arduino’s platform.txt (on OSX you can find it by searching in Users/your_name/Library/Arduino15). Search and replace -Os with -O2. Save.
+## Extending Mozzi
 
-It’s explained more thoroughly (for Windows) [here](http://www.instructables.com/id/Arduino-IDE-16x-compiler-optimisations-faster-code/?ALLSTEPS).
-
-If you still need more speed, Arduino 1.0.5 produces slightly faster code.
-
-Mozzi itself offers many helpers for producing faster code, such as Fixed-Point integer maths, fast replacements for `map()`, `random()`, `millis()`, and other functions.
-Be sure to use these!
-
-***
-
-## Using external chips to produce the sound
+### Using external chips to produce the sound
 
 External chips (DAC) can also be used on any platform which does not support natively the I2S protocol  using an user defined `audioOutput` function. This can allow a greater audio quality over the native ways to output the sound (PWM for AVR Arduinos and STM32 and 12 bit DAC for Teensy 3.*).
 Examples are provided for the MCP492X DAC (12 bit on SPI) and for the (PT8211) 16 bit stereo DAC using SPI port to emulate the I2S protocol. The latter should be compatible with any DAC using I2S.
 
-***
+### Extendig the library itself
 
 If you enjoy using Mozzi for a project, or have extended it, we would be
 pleased to hear about it and provide support wherever possible. Contribute
@@ -189,27 +167,6 @@ and fixed point version of the filter on [dave's blog of art and programming](ht
 State Variable filter pseudocode at [musicdsp.org](http://www.musicdsp.org/showone.php?id=23) and [here](http://www.musicdsp.org/showone.php?id=142)  
 Various examples from [Pure Data](http://puredata.info/) by Miller Puckette  
 [Practical synthesis tutorials](http://www.obiwannabe.co.uk/) by Andy Farnell  
-
-
-## Hardware compatibility and hardware specific notes
-
-While originating on the 8 bit AVR based "classic Arduino" boards, Mozzi supports a wide variety of different MCUs, these days, including:
-  - Classic AVR boards: Arduino Uno, Duemilanove, Nano, Nano 33, Pro Mini, Leonardo, Mega, many others, and countless clones, Teensy 1 and 2.x, ...
-  - Various Teensy 3.x boards: Teensy 3.0/3.1/3.2/3.4/3.5/LC
-  - Teensy 4.x boards: Teensy 4.0 and 4.1 are known to work, future boards stand good chances of working with Mozzi out of the box
-  - STM32-based boards: Confusingly, several popular Arduino cores exist for these MCUs - and Mozzi supports several. Refer to the documentation
-    linked below. Mozzi has been tested on the popule STM32F1 "blue pill" and STM32F4 "black pill" boards, but should support a very wide range
-    of further boards out of the box.
-  - SAMD21-based boards: Tested on the Arduino Circuitplayground M0, expect to work on others, too.
-  - ESP8266: Should run on the whole range of boards, including the minimal ESP-01
-  - ESP32: Should run on the wohle range of boards
-  - Arduiono Giga/MBED: The Arduino Giga, and - in untested theory - the Arduion Portenta
-  - RP2040: The Raspberry Pi Pico and other boards using RP2040
-  - Arduino Uno R4: The new Uno, based on a 32-bit Renesas MCU
-
-Since the hardware capatibilies of these boards are vastly different, the ports, too, differ in their internals and their capabilities. Importantly,
-of course, they also differ in what pin(s) are used for audio output by default. Refer to the [Hardware Section of the Documentation](https://sensorium.github.io/Mozzi/doc/html/group__hardware.html) for the details
-applicable to your hardware.
 
 
 ***

config/known_16bit_timers.h

@@ -68,7 +68,7 @@ TB2012 added Leonardo section.
 
 // Arduino Uno, Duemilanove, LilyPad, etc
 //
-#elif defined (__AVR_ATmega168__) || defined (__AVR_ATmega328P__)
+#elif defined (__AVR_ATmega168__) || defined (__AVR_ATmega328P__) || defined (__AVR_ATmega328PB__)
   #define TIMER1_A_PIN   9
   #define TIMER1_B_PIN   10
   #define TIMER1_ICP_PIN 8

extras/NEWS.txt

@@ -4,9 +4,15 @@ NEWS
 get the latest version from https://sensorium.github.io/Mozzi/
 
 NOT YET RELEASED (github version): Mozzi 2.0
-- explicitly specify bit depth for "int" or "long" in several places, for better cross-platform consistency
-- restructured configuration options for more consistency across platforms, and easier customization
-- changed licence to LGPL version 2.1 or later
+- This release is *not* 100% source compatible to earlier versions of Mozzi. Most sketches will continue to compile,
+  but with warnings. Some will need adjustments to keep working. See https://sensorium.github.io/Mozzi/learn/porting/ .
+  If porting is not an option, install an earlier (1.x) version of Mozzi, or use the "Mozzi_1" branch in git.
+- Now depends on FixMath library for enhanced fixed point arithmetic (which is actually spin-off originating in the Mozzi project)
+- Explicitly specify bit depth for "int" or "long" in several places, for better cross-platform consistency
+- Restructured configuration options for more consistency across platforms, and easier customization.
+  There is no longer a central mozzi_config.h file, but rather config options can be customized using
+  #defines at the top of a sketch.
+- Changed licence to LGPL version 2.1 or later
 
 release v1.1.2
 - new partial port of the Arduino Uno R4