# HG changeset patch # User Mychaela Falconia # Date 1648540145 0 # Node ID 2b5f4736079cce5909861614856f3eb9edc22ba3 # Parent b026f11568523fcd81040d132f127d85675aed6f doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM diff -r b026f1156852 -r 2b5f4736079c doc/Buzzer-melodies --- a/doc/Buzzer-melodies Mon Mar 28 06:30:09 2022 +0000 +++ b/doc/Buzzer-melodies Tue Mar 29 07:49:05 2022 +0000 @@ -73,19 +73,73 @@ 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 -========================================= +2022 addition: BUZM melody player engine in FC Tourmaline +========================================================= + +As of 2022 our FC Tourmaline firmware includes a new buzzer melody player +engine, implemented as a RiViera-based service named BUZM. The new BUZM service +sits on top of the low-level PWT buzzer driver in the same way how RiViera +Audio service sits on top of the low-level DSP+L1 combo, and the API (directed +toward UI firmware layers) of the new BUZM service is modeled after that of RV +Audio service. The primary objective of this BUZM venture is to get rid of the +Condat audio driver layer mess which we inherited from TI (it has buzzer ringing +and audio tone generation entangled together in a gnarly way which we need to +move away from), but this migration also provides a secondary benefit: instead +of being hard-coded, buzzer melodies will now be read from files in FFS, just +like E1 melodies for loudspeaker-based ringing, allowing our UI firmware design +to be harmonized between the two ringer configurations. + +The following design decisions underlie our new FC Tourmaline buzzer melody +facility: + +* Regarding the choice between BU or PWT driving, PWT has been chosen. All + melodies created for playing via BUZM need to consist of musical notes F4 + through E8 (scientific pitch notation, 349 to 5274 Hz), as supported by + Calypso PWT block. + +* Each melody is a sequence of sounded tones (PWT), either directly abutted or + separated by pauses. In actual implementation, each melody is a sequence of + directly abutted entries, where each entry can be either a sounded tone or a + pause. Each entry (tone or silence) has a duration, reckoned in TDMA frames + as explained above. + +* For every sounded tone in a melody, a note volume in the range [1,64] is + given. If the melody is played at maximum volume, the per-note volumes will + be written directly into the hardware register (PWM control in 1/64 units). + If the user-specified play volume is less than 64, the actual sounding volume + of each note is determined as (play_volume * note_volume / 64), with the + division step rounding up - when both play_volume and note_volume are + constrained in the [1,64] range, the result of the rounding-up division is + also constrained in the same range. + +In terms of tool support, each FreeCalypso PWT buzzer melody begins life as an +ASCII text source in the format defined by us. It is then compiled into binary +form with our fc-pwt-comp utility, and the resulting binary melody file is +uploaded into FreeCalypso device FFS. For manual testing, each uploaded buzzer +melody can be played with AT@BUZ command. For finished phone operation, there +will be two ringtone list files (one for play-until-answer ringing tones and +one for non-repeating message alert tones) that will drive ringtone selection +in the phone UI. + +The format of ASCII source files for PWT melodies is best documented by +examples: see several in the ringtools/examples directory. + +Standalone buzzer exercising (outside of FC firmware) +===================================================== 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. +playing any tone at any volume, in either BU or PWT mode. -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. +fc-buzplay is a higher-level tool: it establishes out-of-firmware operation on +a target Calypso device similarly to fc-loadtool (based on the same framework), +but running buzplayer instead of loadagent. The original command of meaty +action was/is 'play' - it reads a BU (not PWT) melody from an ASCII source file +in a format that was the predecessor of our current PWT format, feeds it to +buzplayer on the target, and commands buzplayer to actually play it on the +physical buzzer. Later buzplayer (the target utility) was extended to support +PWT in addition to BU, and fc-buzplay got a new 'playt' command - this new +command plays PWT melodies, reading melody files in the same ASCII source format +as fc-pwt-comp. (In actual history this ASCII source format was invented for +fc-buzplay first, and then later we turned it into fc-pwt-comp.)