FreeCalypso > hg > freecalypso-tools

comparison doc/Buzzer-melodies @ 873:2b5f4736079c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 29 Mar 2022 07:49:05 +0000
parents 2f401860e9ad
children 8ff9bce1b56e
comparison
equal deleted inserted replaced
872:b026f1156852 873:2b5f4736079c
71 that is available natively and directly, whereas any other measurement such as 71 that is available natively and directly, whereas any other measurement such as
72 milliseconds would have to be converted to TDMA frames by the firmware code. 72 milliseconds would have to be converted to TDMA frames by the firmware code.
73 Therefore, it makes the best sense to reckon all note durations in our buzzer 73 Therefore, it makes the best sense to reckon all note durations in our buzzer
74 melodies in TDMA frames to begin with. 74 melodies in TDMA frames to begin with.
75 75
76 FC host tools support for buzzer melodies 76 2022 addition: BUZM melody player engine in FC Tourmaline
77 ========================================= 77 =========================================================
78
79 As of 2022 our FC Tourmaline firmware includes a new buzzer melody player
80 engine, implemented as a RiViera-based service named BUZM. The new BUZM service
81 sits on top of the low-level PWT buzzer driver in the same way how RiViera
82 Audio service sits on top of the low-level DSP+L1 combo, and the API (directed
83 toward UI firmware layers) of the new BUZM service is modeled after that of RV
84 Audio service. The primary objective of this BUZM venture is to get rid of the
85 Condat audio driver layer mess which we inherited from TI (it has buzzer ringing
86 and audio tone generation entangled together in a gnarly way which we need to
87 move away from), but this migration also provides a secondary benefit: instead
88 of being hard-coded, buzzer melodies will now be read from files in FFS, just
89 like E1 melodies for loudspeaker-based ringing, allowing our UI firmware design
90 to be harmonized between the two ringer configurations.
91
92 The following design decisions underlie our new FC Tourmaline buzzer melody
93 facility:
94
95 * Regarding the choice between BU or PWT driving, PWT has been chosen. All
96 melodies created for playing via BUZM need to consist of musical notes F4
97 through E8 (scientific pitch notation, 349 to 5274 Hz), as supported by
98 Calypso PWT block.
99
100 * Each melody is a sequence of sounded tones (PWT), either directly abutted or
101 separated by pauses. In actual implementation, each melody is a sequence of
102 directly abutted entries, where each entry can be either a sounded tone or a
103 pause. Each entry (tone or silence) has a duration, reckoned in TDMA frames
104 as explained above.
105
106 * For every sounded tone in a melody, a note volume in the range [1,64] is
107 given. If the melody is played at maximum volume, the per-note volumes will
108 be written directly into the hardware register (PWM control in 1/64 units).
109 If the user-specified play volume is less than 64, the actual sounding volume
110 of each note is determined as (play_volume * note_volume / 64), with the
111 division step rounding up - when both play_volume and note_volume are
112 constrained in the [1,64] range, the result of the rounding-up division is
113 also constrained in the same range.
114
115 In terms of tool support, each FreeCalypso PWT buzzer melody begins life as an
116 ASCII text source in the format defined by us. It is then compiled into binary
117 form with our fc-pwt-comp utility, and the resulting binary melody file is
118 uploaded into FreeCalypso device FFS. For manual testing, each uploaded buzzer
119 melody can be played with AT@BUZ command. For finished phone operation, there
120 will be two ringtone list files (one for play-until-answer ringing tones and
121 one for non-repeating message alert tones) that will drive ringtone selection
122 in the phone UI.
123
124 The format of ASCII source files for PWT melodies is best documented by
125 examples: see several in the ringtools/examples directory.
126
127 Standalone buzzer exercising (outside of FC firmware)
128 =====================================================
78 129
79 We have a target utility (running on Calypso devices out of RAM) called 130 We have a target utility (running on Calypso devices out of RAM) called
80 buzplayer, and a front end host program called fc-buzplay. If you load and run 131 buzplayer, and a front end host program called fc-buzplay. If you load and run
81 buzplayer manually via fc-iram, you can use it to exercise the buzzer manually, 132 buzplayer manually via fc-iram, you can use it to exercise the buzzer manually,
82 playing any tone at any volume, in either BU or PWT mode. fc-buzplay is a 133 playing any tone at any volume, in either BU or PWT mode.
83 higher-level tool that reads buzzer melodies from ASCII text files (our own
84 simple ad hoc format), feeds them to buzplayer on the target, and commands
85 buzplayer to play the uploaded melody.
86 134
87 Further documentation will be written if and when a more actual need arises for 135 fc-buzplay is a higher-level tool: it establishes out-of-firmware operation on
88 this functionality - right now the primary direction within FreeCalypso is 136 a target Calypso device similarly to fc-loadtool (based on the same framework),
89 toward our own handset hardware, and the Mother's intent for our FreeCalypso 137 but running buzplayer instead of loadagent. The original command of meaty
90 Libre Dumbphone handset is to use a loudspeaker and Melody E1 for ringtone 138 action was/is 'play' - it reads a BU (not PWT) melody from an ASCII source file
91 generation, as opposed to the buzzer output. 139 in a format that was the predecessor of our current PWT format, feeds it to
140 buzplayer on the target, and commands buzplayer to actually play it on the
141 physical buzzer. Later buzplayer (the target utility) was extended to support
142 PWT in addition to BU, and fc-buzplay got a new 'playt' command - this new
143 command plays PWT melodies, reading melody files in the same ASCII source format
144 as fc-pwt-comp. (In actual history this ASCII source format was invented for
145 fc-buzplay first, and then later we turned it into fc-pwt-comp.)