Detailed Description

The bones of every Mozzi sketch.

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 setup() routine.

This function intializes the timer(s) needed to move audio samples to the output according to the configured MOZZI_AUDIO_MODE .

Parameters

control_rate_hz Sets how often updateControl() is called. It must be a power of 2. If no parameter is provided, control_rate_hz is set to MOZZI_CONTROL_RATE, which has a default value of 64 (you can re-#define it in your sketch). The practical upper limit for control rate depends on how busy the processor is, and you might need to do some tests to find the best setting.

Note: startMozzi calls setupMozziADC(), which calls setupFastAnalogRead() and adcDisconnectAllDigitalIns(), which disables digital inputs on all analog input pins. All in mozzi_analog.h and easy to change if you need to (hack). They are all called automatically and hidden away because it keeps things simple for a STANDARD_PLUS set up, but if it turns out to be confusing, they might need to become visible again.

Files
file	Mozzi.h
	This is the main include file in Mozzi.

file	MozziHeadersOnly.h
	This file provides declarations of the Mozzi Core Functions Mozzi functions, but no implementation.

Macros
#define	CONSTTABLE_STORAGE(X)
	Declare a variable such that it will be stored in flash memory, instead of RAM, on platforms where this is reasonably possible (i.e. More...

Functions
template<typename T >
T	mozzi_pgm_read_wrapper (const T *address)
	Helper function to FLASH_OR_RAM_READ(). More...

template<typename T >
T	FLASH_OR_RAM_READ (T *address)
	Read a value from flash or RAM. More...

void	stopMozzi ()
	Stops audio and control interrupts and restores the timers to the values they had before Mozzi was started. More...

AudioOutput	updateAudio ()
	This is where you put your audio code. More...

void	updateControl ()
	This is where you put your control code. More...

void	audioHook ()
	This is required in Arduino's loop(). More...

unsigned long	audioTicks ()
	An alternative for Arduino time functions like micros() and millis(). More...

unsigned long	mozziMicros ()
	An alternative for Arduino time functions like micros() and millis(). More...

Macro Definition Documentation

◆ CONSTTABLE_STORAGE

#define CONSTTABLE_STORAGE ( X )

Declare a variable such that it will be stored in flash memory, instead of RAM, on platforms where this is reasonably possible (i.e.

not on ESP8266, where random location flash memory access is too slow). To read the variable in a cross-platform compatible way, use FLASH_OR_RAM_READ().

Definition at line 67 of file mozzi_pgmspace.h.

Function Documentation

◆ audioHook()

void audioHook ( )

This is required in Arduino's loop().

If there is room in Mozzi's output buffer, audioHook() calls updateAudio() once and puts the result into the output buffer. Also, if @ref MOZZI_AUDIO_INPUT is enabled in the config, audioHook() takes care of moving audio input from the input buffer so it can be accessed with getAudioInput() in your updateAudio() routine. If other functions are called in loop() along with audioHook(), see if they can be called less often by moving them into updateControl(), to save processing power. Otherwise it may be most efficient to calculate a block of samples at a time by putting audioHook() in a loop of its own, rather than calculating only 1 sample for each time your other functions are called.

Definition at line 313 of file MozziGuts.hpp.

◆ audioTicks()

unsigned long audioTicks ( )

An alternative for Arduino time functions like micros() and millis().

This is slightly faster than micros(), and also it is synchronized with the currently processed audio sample (which, due to the audio output buffer, could diverge up to 256/MOZZI_AUDIO_RATE seconds from the current time). audioTicks() is updated each time an audio sample is output, so the resolution is 1/MOZZI_AUDIO_RATE microseconds (61 microseconds when MOZZI_AUDIO_RATE is 16384 Hz).

Returns: the number of audio ticks since the program began.

Definition at line 301 of file MozziGuts.hpp.

◆ FLASH_OR_RAM_READ()

template<typename T >

T FLASH_OR_RAM_READ ( T * address )

inline

Read a value from flash or RAM.

The specified address is read from flash, if T is const, and const tables are stored in flash on this platform (i.e. not on ESP8266). It is read from RAM, if T is not-const or tables are always stored in RAM on this platform.

See also: CONSTTABLE_STORAGE .

Definition at line 57 of file mozzi_pgmspace.h.

◆ mozzi_pgm_read_wrapper()

template<typename T >

T mozzi_pgm_read_wrapper ( const T * address )

inline

Helper function to FLASH_OR_RAM_READ().

You do not want to call this, directly.

Definition at line 32 of file mozzi_pgmspace.h.

◆ mozziMicros()

unsigned long mozziMicros ( )

An alternative for Arduino time functions like micros() and millis().

This is slightly faster than micros(), and also it is synchronized with the currently processed audio sample (which, due to the audio output buffer, could diverge up to 256/MOZZI_AUDIO_RATE seconds from the current time). audioTicks() is updated each time an audio sample is output, so the resolution is 1/MOZZI_AUDIO_RATE microseconds (61 microseconds when MOZZI_AUDIO_RATE is 16384 Hz).

Returns: the approximate number of microseconds since the program began.

Definition at line 300 of file MozziGuts.hpp.

◆ stopMozzi()

void stopMozzi ( )

Stops audio and control interrupts and restores the timers to the values they had before Mozzi was started.

This could be useful when using sensor libraries which depend on the same timers as Mozzi.

A potentially better option for resolving timer conflicts involves using non-blocking methods, such as demonstrated by the twowire_nonblock code in the 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.hpp could involve individually saving and restoring particular Timer registers depending on which one(s) are required for other tasks.

Note: This function is not actually implemented on all platforms.

Definition at line 303 of file MozziGuts.hpp.

◆ updateAudio()

AudioOutput updateAudio ( )

This is where you put your audio code.

updateAudio() has to keep up with the MOZZI_AUDIO_RATE of 16384 or 32768 Hz, so to keep things running smoothly, avoid doing any calculations here which could be done in setup() or updateControl().

Returns: an audio sample.

While is possible (in mono sketches) to return a plain unscaled int, it is generally best to return auto-scaled samples using MonoOutput::from8Bit(), MonoOutput::from16Bit(), MonoOutput::fromNbit(), or their StereoOutput equivalents.

Definition at line 5 of file Skeleton_Multi_Unit2.cpp.

◆ updateControl()

void updateControl ( )

This is where you put your control code.

You need updateControl() somewhere in your sketch, even if it's empty. updateControl() is called at the control rate you set in startMozzi(). To save processor load, avoid any calculations here which could be done in setup().