Mozzi  alpha 0.01.1t
sound synthesis library for Arduino
 All Classes Functions Typedefs
Defines | Functions
Mozzi core definitions and functions

Defines

#define AUDIO_CHANNEL_1_PIN   TIMER1_A_PIN
 PWM audio output pin.
#define AUDIO_RATE   16384
 AUDIO_RATE is fixed at 16384 Hz for now.
#define AUDIO_PWM_RESOLUTION   488
 This is the maximum sample resolution.

Functions

void startMozzi (unsigned int control_rate_hz)
 Sets up the timers for audio and control rate processes.
void audioHook ()
 This is required in Arduino's loop().
void updateControl ()
 This is where you put your control code.
int updateAudio ()
 This is where you put your audio code.

Define Documentation

#define AUDIO_CHANNEL_1_PIN   TIMER1_A_PIN

PWM audio output pin.

For now there is only one channel in the mainstream version. Below is a list of the Digital Pins used by Mozzi for PWM audio out on different boards. Those which have been tested and reported to work have an x. Feedback about others is welcome.

x 9 Arduino Uno
x 9 Arduino Duemilanove
x 9 Arduino Nano
x 9 Arduino Leonardo
x 9 Ardweeny
x 11 Freetronics EtherMega
..14 Teensy
x B5 Teensy2
x B5(25) Teensy2++
x 11 Arduino Mega
..13 Sanguino
x 9 Boarduino

Definition at line 84 of file MozziGuts.h.

#define AUDIO_PWM_RESOLUTION   488

This is the maximum sample resolution.

8 bit (ie. 256) is usually fine but there might be times where the extra headroom is useful. Use powers of two in audio calculations and use right shifts for divisions where possible. Also, in tests while writing Mozzi, shifts on byte boundaries seem to work fastest. For example, >> 8 is faster than >> 4. Test your timings where possible, using an oscilloscope. To test timing, include utils.h in your sketch, put SET_PIN13_OUT in setup(), then SET_PIN13_HIGH and SET_PIN13_LOW around your test code (see Mozzi utility functions). This is the dynamic range of Mozzi's audio output, equal to Timer1.pwmPeriod calculated for interrupt rate 16384.

Todo:
Can both timer one pwm pins be used together to increase the dynamic range? See toneAC http://code.google.com/p/arduino-tone-ac/

Definition at line 141 of file MozziGuts.h.

#define AUDIO_RATE   16384

AUDIO_RATE is fixed at 16384 Hz for now.

This is a compromise between the sample rate (interrupt rate) and sample bitdepth (pwm width), which are interdependent due to the way pulse wave modulation is used to generate the sound output. With the AUDIO_RATE at 16384, the sample resolution is 488, which provides some headroom above the 8bit table resolution currently used by the oscillators. You can look at the TimerOne library for more info about how interrupt rate and pwm resolution relate.

Todo:
Possible option for output to R/2R DAC circuit, like http://blog.makezine.com/2008/05/29/makeit-protodac-shield-fo/ This would limit dynamic range to 8 bit, but would remove the 16384Hz pwm carrier frequency noise which can be a problem in some applications, requiring filtering to remove (see the Mozzi wiki for filter schematics).

Definition at line 117 of file MozziGuts.h.


Function Documentation

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. If other functions are called in loop() along with audioHook(), see if they can be moved into updateControl(). 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.

Todo:
try pre-decrement positions and swap gap calc around

Definition at line 100 of file MozziGuts.cpp.

void startMozzi ( unsigned int  control_rate_hz)

Sets up the timers for audio and control rate processes.

It goes in your sketch's setup() routine. startMozzi() starts audio interrupts on Timer 1 and control interrupts on Timer 0. The audio rate is currently fixed at 16384 Hz.

Parameters:
control_rate_hzSets how often updateControl() is called. It can be any power of 2 above and including 64. 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. It's good to define CONTROL_RATE in your sketches (eg. "#define CONTROL_RATE 128") because the literal numeric value is necessary for Oscils to work properly, and it also helps to keep the calculations in your sketch clear.

Definition at line 45 of file MozziGuts.cpp.

int updateAudio ( )

This is where you put your audio code.

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

Returns:
an audio sample, between -244 and 243 inclusive.
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().