--- a/CHANGES	Sun May 30 23:47:16 2021 +0000
+++ b/CHANGES	Mon May 31 04:24:22 2021 +0000
@@ -13,8 +13,10 @@
   + fc-tmsh bsim family of commands send ETM_BSIM command packets to the
     target, driving simulated battery charging and discharging events.
 
-* buzplayer target utility now supports both BU and PWT modes of operating the
-  Calypso buzzer.
+* buzplayer target utility and fc-buzplay front end now support both BU and PWT
+  modes of operating the Calypso buzzer, including support for both BU and PWT
+  melodies in fc-buzplay.  See the new doc/Buzzer-melodies article for more
+  information.
 
 Changes from fc-host-tools-r14 to fc-host-tools-r15:
 

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Buzzer-melodies	Mon May 31 04:24:22 2021 +0000
@@ -0,0 +1,91 @@
+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.

--- a/doc/Host-tools-overview	Sun May 30 23:47:16 2021 +0000
+++ b/doc/Host-tools-overview	Mon May 31 04:24:22 2021 +0000
@@ -97,10 +97,12 @@
 		offset, allowing extraction of tables from alien firmwares and
 		whatnot) and emits it in FreeCalypso ASCII format.
 
-fc-buzplay	This program plays piezoelectic buzzer melodies on an actual
-		Calypso device equipped with such a buzzer (Mot C1xx, TI's
-		D-Sample board, our planned future HSMBP) by loading a buzplayer
-		agent onto the target and feeding melodies to be played to it.
+fc-buzplay	This program plays Calypso buzzer melodies (BU or PWT) on an
+		actual Calypso device equipped with such a buzzer (Mot C1xx,
+		TI's D-Sample board, our next planned development board) by
+		loading a buzplayer agent onto the target and feeding melodies
+		to be played to it.  See the Buzzer-melodies article for more
+		details.
 
 fc-cal2bin	This utility takes an RF table in FreeCalypso ASCII format and
 		converts it to the firmware's native binary format.  See the