Mozzi Configuration options

Detailed Description

Macros
#define	MOZZI_COMPATIBILITY_LEVEL
	Mozzi generally tries to keep your old sketches working, but we continue to find new (and hopefully better) approaches to old problems. More...
#define	MOZZI_AUDIO_MODE
	Configure how Mozzi outputs generated sounds. More...
#define	MOZZI_AUDIO_CHANNELS
	This sets allows to change from a single/mono audio output channel to stereo output. More...
#define	MOZZI_AUDIO_RATE
	Defines the audio rate, i.e. More...
#define	MOZZI_CONTROL_RATE
	Control rate setting. More...
#define	MOZZI_ANALOG_READ
	Whether to compile in support for non-blocking analog reads. More...
#define	MOZZI_AUDIO_INPUT
	Whether to enable built in audio input feature. More...
#define	MOZZI_AUDIO_INPUT_PIN
	This sets which analog input channel to use for audio input, if you have enabled MOZZI_AUDIO_INPUT, above. More...
#define	MOZZI_PWM_RATE
	Only for MOZZI_AUDIO_MODE s MOZZI_OUTPUT_PWM and MOZZI_OUTPUT_2PIN_PWM. More...
#define	MOZZI_AUDIO_BITS_PER_CHANNEL
	Only for MOZZI_AUDIO_MODE MOZZI_OUTPUT_2PIN_PWM. More...
#define	MOZZI_AUDIO_PIN_1
	Only for MOZZI_AUDIO_MODE s MOZZI_OUTPUT_PWM and MOZZI_OUTPUT_2PIN_PWM: The IO pin to use as (first) audio output. More...
#define	MOZZI_AUDIO_BITS
	Output resolution of audio samples. More...

Mozzi Configuration

Configuring Mozzi

Mozzi configuration options include details such as audio rate, number of audio channels (mono or stereo), output generation method and many others, where details on the available options differ between the different platforms (see Hardware and configuration), and may include additional options beyond those listed, here.

Note

It is generally safe to leave the Mozzi Configuration unchanged, and that's very much recommended until you have a very specific need to customize something. Contrary to past versions of Mozzi, all configuration options have a (usually sensible) default value, so you do not have to configure anything, unless you actually want to change something.

Configuring Mozzi is mostly done using various preprocessor definitions. This approach is used to move as much of the processing involved to compile time, in order to save Flash, RAM, and CPU use at runtime. This section lists various global options, but in addition, most ports allow additional hardware dependent configuration options. See Hardware and configuration.

Several configuration examples are provided in the "config" folder of the Mozzi sources. You may want to look at these, first. The general approach is as follows:

#include <MozziConfigValues.h>                      // include this first, for named option values
#define MOZZI_AUDIO_CHANNELS MOZZI_STEREO           // set to stereo mode
 
#include <Mozzi.h>                                  // *after* all configuration options, include the main Mozzi headers

Alternatively, if a suitable configuration example exists, use:

#include <config/config_example_avr_stereo.h>       // again, do this, before including the main headers

Note

Should you include Mozzi headers in more than one compilation unit (i.e. more than one .cpp file) inside the same sketch, you must use identical configuration options at the top of each file!

TODO: Fix and complete Doxygen coverage

Macro Definition Documentation

MOZZI_ANALOG_READ

#define MOZZI_ANALOG_READ

Whether to compile in support for non-blocking analog reads.

This is enabled by default on platforms that support it, but may be disabled, explicitly, to save resources, or in order to implement custom read schemes (e.g. with IO multiplexing).

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.

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.

Currently allowed values are:

• MOZZI_ANALOG_READ_NONE Disabled
• MOZZI_ANALOG_READ_STANDARD Analog read implementation enabled (currently there is only the "standard" method, but future versions might allow additional choice, here).

Definition at line 169 of file mozzi_config_documentation.h.

MOZZI_AUDIO_BITS

#define MOZZI_AUDIO_BITS

Output resolution of audio samples.

In most cases you should leave this value untouched (for the defaults that get applied, see Hardware and configuration . However, for MOZZI_AUDIO_MODE s MOZZI_OUTPUT_EXTERNAL_TIMED and MOZZI_OUTPUT_EXTERNAL_CUSTOM you way wish to customize the default value of 16 bits.

Note

At the time of this writng single audio samples are stored as "int", unconditionally. This limits MOZZI_AUDIO_BITS to a maximum of 16 bits on some 8 bit boards!

Definition at line 296 of file mozzi_config_documentation.h.

MOZZI_AUDIO_BITS_PER_CHANNEL

#define MOZZI_AUDIO_BITS_PER_CHANNEL

Only for MOZZI_AUDIO_MODE MOZZI_OUTPUT_2PIN_PWM.

Sample resolution per channel to use in 2 pin output, given in bits (i.e. total resolution is twice as much). Defaults to 7 bits per channel. Note that increasing this requires very, very well matched output resistors.

See Mozzi on classic Arduino, Teensy 2.x, Arduino Mega, and other 8 bit "AVR"/ATMEGA architecture boards for a more detailed description.

Definition at line 223 of file mozzi_config_documentation.h.

MOZZI_AUDIO_CHANNELS

#define MOZZI_AUDIO_CHANNELS

This sets allows to change from a single/mono audio output channel to stereo output.

To actually generate two channels, your updateAudio()-function should return a StereoOutput(). Sketches returning a MonoOutput() in a stereo config, or vice versa will continue to work, but will generate a warning a compile time.

Note

This option superseeds the earlier STEREO_HACK in Mozzi < 1.1

At the time of this writing, only MOZZI_MONO and MOZZI_STEREO are supported. The value of MOZZI_MONO is 1 and the value of MOZZI_STEREO is 2, so future extensions are also expected to set this to the number of available channels, and it's ok to use numerical comparison.

Definition at line 106 of file mozzi_config_documentation.h.

MOZZI_AUDIO_INPUT

#define MOZZI_AUDIO_INPUT

Whether to enable built in audio input feature.

This is not supported on all platforms, and on platforms that do support it may come with a considerable performance overhead. Don't enable, unless you need this.

Currently allowed values are:

• MOZZI_AUDIO_INPUT_NONE No audio input
• MOZZI_AUDIO_INPUT_STANDARD Audio input enabled (currently there is only the "standard" method, but future versions might allow additional choice, here). This mode implies that MOZZI_ANALOG_READ s are enabled and supported. You may have to call setupFastAnalogReads(FASTEST_ADC) after setupMozzi(), when using this.

Further reading and config: getAudioInput() MOZZI_AUDIO_INPUT_PIN

Definition at line 188 of file mozzi_config_documentation.h.

MOZZI_AUDIO_INPUT_PIN

#define MOZZI_AUDIO_INPUT_PIN

This sets which analog input channel to use for audio input, if you have enabled MOZZI_AUDIO_INPUT, above.

Not all pins may be available for this, be sure to check the documentation for your platform.

Definition at line 197 of file mozzi_config_documentation.h.

MOZZI_AUDIO_MODE

#define MOZZI_AUDIO_MODE

Configure how Mozzi outputs generated sounds.

Note

Not all options are available on all platforms, and several options require specific wiring or external components to function on top of this! When customizing this, it is highly recommended to start experimenting with a simple and known-to-work sketch (such as a basic sinewave) to verify that your hardware setup is correct. Similarly, if you observe problems running your "real" sketch, it is often a good idea ot test your sketch with the default audio mode, too (by leaving this option, and preferrably all others, unset).

Refer to the Hardware and configuration specific documentation for which modes are supported on your hardware, and further details!

Supported values:

• MOZZI_OUTPUT_PWM Output using pulse width modulation (PWM) on a GPIO pin. This is the default on most platforms. On the Arduino Uno (more generally ATMEGA328P), this allows for a sample resolution of 488 (almost 9 bits) on pin 9. Usable pins and resolution will be different on other boards.
• MOZZI_OUTPUT_2PIN_PWM Output using pulse width modulation on two GPIO pins, where one pin represents the lower bits, and the other the higer bits of the sample. On the Aduino Uno, this allows for 14 bits of resolution on pins 9 (low) and 10 (high). For further information (wiring etc.) see hardware_avr_2pin.
• MOZZI_OUTPUT_EXTERNAL_TIMED Output is not controlled by Mozzi itself, but left to the user sketch. This setting allows to completely customize the audio output, e.g. for connecting to external DACs. For more detail, see External audio output
• MOZZI_OUTPUT_EXTERNAL_CUSTOM As above, but additionally bypassing Mozzi's sample buffer. For more detail, see External audio output
• MOZZI_OUTPUT_PDM_VIA_I2S Output pulse density modulated (PDM) samples via a (hardware) I2S interface (without a DAC connected to it).
• MOZZI_OUTPUT_PDM_VIA_SERIAL Output pulse density modulated (PDM) samples via a hardware serial interface.
• MOZZI_OUTPUT_I2S_DAC Output samples to a PT8211 (or compatible) DAC connected to a hardware I2S interface.
• MOZZI_OUTPUT_INTERNAL_DAC Output to the interal DAC on boards that support one.

TODO: Adding an R2R-DAC option would be cool, http://blog.makezine.com/2008/05/29/makeit-protodac-shield-fo/ , some discussion on Mozzi-users.

Definition at line 90 of file mozzi_config_documentation.h.

MOZZI_AUDIO_PIN_1

#define MOZZI_AUDIO_PIN_1

Only for MOZZI_AUDIO_MODE s MOZZI_OUTPUT_PWM and MOZZI_OUTPUT_2PIN_PWM: The IO pin to use as (first) audio output.

This must be attached to Timer1. When settings this, you alsso need to specify the output compare register responsible for this pin (either OCR1A or OCR1B).

Example:

#define MOZZI_AUDIO_PIN_1            TIMER1_B_PIN
#define MOZZI_AUDIO_PIN_1_REGISTER   OCR1B          // must also specify this, when customizing MOZZI_AUDIO_PIN_1

Equivalent definitions can be used to control the pin for the right audio channel (in stereo mode), or the low byte channel (in 2 Pin PWM mode):

#define MOZZI_AUDIO_PIN_2            [...]
#define MOZZI_AUDIO_PIN_2_REGISTER   [the matching OCR]
// or
#define MOZZI_AUDIO_PIN_1_LOW            [...]
#define MOZZI_AUDIO_PIN_1_LOW_REGISTER   [the matching OCR]

See also

config/known_16bit_timers.h

Definition at line 250 of file mozzi_config_documentation.h.

MOZZI_AUDIO_RATE

#define MOZZI_AUDIO_RATE

Defines the audio rate, i.e.

rate of samples output per second.

The default rate on the classis Arduino Uno is 16384 Hz, but can be increased to 32768 Hz, subject to the caveats, detailed below. For most other platforms 32678 Hz is the default, but even higher rates may be supported. Increasing the rate allows for better frequency response, but generally all affects achievable sample bitdepth (especially from PWM output). Also, of course, doubling the sample rate also halves the amount of time available to calculate the each sample, so it may only be useful for relatively simple sketches. The increased frequency response can also make unwanted artefacts of low resolution synthesis calculations more apparent, so it's not always a bonus.

It is highly recommended to keep the audio rate a power of two (16384, 32678, 64536, etc.), as some internal calculations can be highly be optimised for speed, this way.

Note

For compatibility reasons, the option MOZZI_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, for MOZZI_COMPATIBILITY_LEVEL < MOZZI_COMPATIBILITY_2_0?

Definition at line 129 of file mozzi_config_documentation.h.

MOZZI_COMPATIBILITY_LEVEL

#define MOZZI_COMPATIBILITY_LEVEL

Mozzi generally tries to keep your old sketches working, but we continue to find new (and hopefully better) approaches to old problems.

Sometimes, keeping API compatibilty with the pre-existing solution may come with a smaller or larger penalty in terms of performance or code size. Therefore - if your sketch supports it - you may be able to get some minor benefit from disabling compatibility code.

Currently supported values are:

• MOZZI_COMPATIBILITY_1_1 - try to support sketches written for Mozzi version 1.1 (or possibly lower); this is the default when including MozziGuts.h
• MOZZI_COMPATIBILITY_2_0 - try to support sketches written for Mozzi version 2.0; this is - currently - the default when including Mozzi.h
• MOZZI_COMPATIBILITY_LATEST - always live on the bleeding edge

Note

MOZZI_COMPATIBILITY_V1_1 does not guarantee, that everything from Mozzi 1.1 will continue to work, just that we're doing a reasonable effort.

Definition at line 59 of file mozzi_config_documentation.h.

MOZZI_CONTROL_RATE

#define MOZZI_CONTROL_RATE

Control rate setting.

Mozzi's MOZZI_CONTROL_RATE sets how many times per second updateControl() is called. MOZZI_CONTROL_RATE has a default of 64 Hz. It is useful to have MOZZI_CONTROL_RATE set at a power of 2 (such as 64,128,256 etc), to have exact timing of audio and control operations. Non-power-of-2 MOZZI_CONTROL_RATE can cause glitches due to audio and control events not lining up precisely. If this happens a power of two MOZZI_CONTROL_RATE might solve it.

Try to keep MOZZI_CONTROL_RATE low, for efficiency, though higher rates up to about 1000 can sometimes give smoother results, avoiding the need to interpolate sensitive variables at audio rate in updateAudio().

TODO: If a definition of MOZZI_CONTROL_RATE is detected, apply that with a warning.

Definition at line 148 of file mozzi_config_documentation.h.

MOZZI_PWM_RATE

#define MOZZI_PWM_RATE

Only for MOZZI_AUDIO_MODE s MOZZI_OUTPUT_PWM and MOZZI_OUTPUT_2PIN_PWM.

On some platforms, the rate at which PWM signals are repeated may be higher than that at with audio signals are produced (i.e. MOZZI_AUDIO_RATE). E.g. for MOZZI_OUTPUT_PWM on the classic Arduino, the pwm defaults to 32768 while the audio rate defaults to 16384. The reasoning behind this is that 16384 Hz audio rate turned out to be te most useful compromise - in most casses - between output quality, and available computing power. However, output at that rate produced high-frequency whine, audible to some people, which could be mitigated by the higher PWM rate.

In other words, increasing this improves the signal quality at less cost than doubling the audio rate itself. However, increasing this too far will limit the dynamic resolution of the samples that can be written to the output pin(s): 2 ^ (output bits) * MOZZI_PWM_RATE cannot be higher than the CPU frequency!

Definition at line 212 of file mozzi_config_documentation.h.