FreeCalypso > hg > freecalypso-tools
diff doc/Buzzer-melodies @ 831:2f401860e9ad
documentation update for buzzer melodies
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Mon, 31 May 2021 04:24:22 +0000 |
parents | |
children | 2b5f4736079c |
line wrap: on
line diff
--- /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.