# HG changeset patch # User Mychaela Falconia # Date 1622435062 0 # Node ID 2f401860e9ad156ae434d9ee83c0609bcb1244bc # Parent 07105f2444242a7facf907e6b655e47ab4ac9e59 documentation update for buzzer melodies diff -r 07105f244424 -r 2f401860e9ad CHANGES --- 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: diff -r 07105f244424 -r 2f401860e9ad doc/Buzzer-melodies --- /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 is the +frequency to be played (BU or PWT), is the relative volume for this +note (PWM volume control), and is how long this note should sound. + +The definitions for and 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. diff -r 07105f244424 -r 2f401860e9ad doc/Host-tools-overview --- 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