The Calypso chip includes a built-in hardware provision for driving
old-fashioned cellphone ringing buzzers.  Not all Calypso phones use a buzzer
as their ringing noise generator - many of the higher-end Calypso phones like
Mot C155/156 and Pirelli DP-L10 use a loudspeaker driven by a MIDI player chip
instead, and it appears that the legendary TSM30 phone may have used TI's
Melody E1 mechanism as its ringer.  However, Motorola C11x/12x and C139/140
phones do use an old-fashioned buzzer, and in FreeCalypso we also work with some
development boards that include one.  Having thus established the relevance of
the buzzer feature for FreeCalypso, we have done a bit of work toward exercising
the buzzer and playing melodies through it.  This article describes the
available support for buzzer melodies in FC host tools.

Buzzer hardware capabilities
============================

The actual noise-making element in phones like Mot C1xx appears to be a magnetic
buzzer - I previously assumed that it was a piezoelectic buzzer, but this
assumption now appears to be incorrect.  However, the relevant capabilities of
this old-fashioned cellphone ringing buzzer are determined not so much by the
physics of the actual noise-making element, but by the circuit with which it is
driven.  The buzzer is controlled by a single-bit digital output from the
Calypso chip, different tone frequencies are generated by Calypso as digital
square wave outputs, and different power control levels (for louder or softer
ringing sound volume) are produced by applying PWM to the "on" phase of the tone
square wave.

The Calypso chip allows its buzzer output to be driven with one of two different
internal logic blocks: either BU or PWT.  We don't have any authoritative
documentation for TI's earlier DBB chips prior to Calypso, but it appears that
LT and BU functions for light and buzzer control came first, built into the
ARMIO block which appears to precede the GSM Skunkworks business altogether, and
then at some later point the alternative PWL and PWT implementations were added.

When driven as BU, Calypso buzzer output can produce 255 different frequencies
ranging from 99 Hz to 12.7 kHz, produced by taking the 13 MHz master clock,
dividing it by 512, and then dividing it again by a programmable integer factor
in the range [2,256].  This mode of driving the buzzer works ideally when
non-musical output frequencies are needed, i.e., frequencies that are expressed
in absolute Hz rather than musical notes.

PWT appears to have been added specifically to facilitate playing of ringtones
that are composed of musical notes.  Compared to the range of 255 possible
frequencies that can be produced by BU, PWT can only produce 48 different tone
frequencies, but these 48 possible PWT frequencies are special in that they
closely approximate the 48 musical notes ranging from F4 to E8 in the scientific
pitch notation.  These 48 musical notes of PWT range cannot be reproduced as
distinct frequencies in BU mode: at the upper range beginning with A6, two or
three different notes collapse to the same BU tone frequency, as the possible
frequencies that can be produced from 13 MHz by the simple division implemented
in BU get farther apart than successive notes of the chromatic scale.  Thus if
you are seeking to play ringtones that are composed of musical notes, use of PWT
should be considered mandatory rather than optional.  OTOH, if you are playing
non-musical tones like SIT that are defined in absolute Hz, then BU will often
work better.

Concept of buzzer melodies
==========================

The Calypso buzzer (either BU or PWT) is monophonic, meaning that it can only
play one note at a time.  Given this constraint, a playable buzzer melody can be
defined as a list of {tone, volume, duration} tuples, where <tone> is the
frequency to be played (BU or PWT), <volume> is the relative volume for this
note (PWM volume control), and <duration> is how long this note should sound.

The definitions for <tone> and <volume> are straightforward - they are numbers
going directly into hardware registers - but in what units should the duration
of notes be reckoned?  In FreeCalypso we have adopted TDMA frames of 4.615 ms
(or more precisely 60/13 ms) as our unit of duration for buzzer melodies, based
on this reasoning: if playing of buzzer melodies is to be incorporated into
operational phone handset firmware, then TDMA frames will be the only time unit
that is available natively and directly, whereas any other measurement such as
milliseconds would have to be converted to TDMA frames by the firmware code.
Therefore, it makes the best sense to reckon all note durations in our buzzer
melodies in TDMA frames to begin with.

FC host tools support for buzzer melodies
=========================================

We have a target utility (running on Calypso devices out of RAM) called
buzplayer, and a front end host program called fc-buzplay.  If you load and run
buzplayer manually via fc-iram, you can use it to exercise the buzzer manually,
playing any tone at any volume, in either BU or PWT mode.  fc-buzplay is a
higher-level tool that reads buzzer melodies from ASCII text files (our own
simple ad hoc format), feeds them to buzplayer on the target, and commands
buzplayer to play the uploaded melody.

Further documentation will be written if and when a more actual need arises for
this functionality - right now the primary direction within FreeCalypso is
toward our own handset hardware, and the Mother's intent for our FreeCalypso
Libre Dumbphone handset is to use a loudspeaker and Melody E1 for ringtone
generation, as opposed to the buzzer output.