annotate doc/Buzzer-melodies @ 1014:961efadd530a default tip

fc-shell TCH DL handler: add support for CSD modes TCH DL capture mechanism in FC Tourmaline firmware has been extended to support CSD modes in addition to speech - add the necessary support on the host tools side. It needs to be noted that this mechanism in its present state does NOT provide the debug utility value that was sought: as we learned only after the code was implemented, TI's DSP has a misfeature in that the buffer we are reading (a_dd_0[]) is zeroed out when the IDS block is enabled, i.e., we are reading all zeros and not the real DL bits we were after. But since the code has already been written, we are keeping it - perhaps we can do some tests with IDS disabled.
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 26 Nov 2024 06:27:43 +0000
parents cb0f61535166
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
831
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 The Calypso chip includes a built-in hardware provision for driving
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 old-fashioned cellphone ringing buzzers. Not all Calypso phones use a buzzer
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 as their ringing noise generator - many of the higher-end Calypso phones like
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4 Mot C155/156 and Pirelli DP-L10 use a loudspeaker driven by a MIDI player chip
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 instead, and it appears that the legendary TSM30 phone may have used TI's
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6 Melody E1 mechanism as its ringer. However, Motorola C11x/12x and C139/140
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 phones do use an old-fashioned buzzer, and in FreeCalypso we also work with some
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 development boards that include one. Having thus established the relevance of
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9 the buzzer feature for FreeCalypso, we have done a bit of work toward exercising
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 the buzzer and playing melodies through it. This article describes the
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11 available support for buzzer melodies in FC host tools.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13 Buzzer hardware capabilities
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 ============================
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 The actual noise-making element in phones like Mot C1xx appears to be a magnetic
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 buzzer - I previously assumed that it was a piezoelectic buzzer, but this
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 assumption now appears to be incorrect. However, the relevant capabilities of
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 this old-fashioned cellphone ringing buzzer are determined not so much by the
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 physics of the actual noise-making element, but by the circuit with which it is
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 driven. The buzzer is controlled by a single-bit digital output from the
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 Calypso chip, different tone frequencies are generated by Calypso as digital
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 square wave outputs, and different power control levels (for louder or softer
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 ringing sound volume) are produced by applying PWM to the "on" phase of the tone
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 square wave.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 The Calypso chip allows its buzzer output to be driven with one of two different
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 internal logic blocks: either BU or PWT. We don't have any authoritative
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 documentation for TI's earlier DBB chips prior to Calypso, but it appears that
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 LT and BU functions for light and buzzer control came first, built into the
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 ARMIO block which appears to precede the GSM Skunkworks business altogether, and
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 then at some later point the alternative PWL and PWT implementations were added.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 When driven as BU, Calypso buzzer output can produce 255 different frequencies
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 ranging from 99 Hz to 12.7 kHz, produced by taking the 13 MHz master clock,
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 dividing it by 512, and then dividing it again by a programmable integer factor
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 in the range [2,256]. This mode of driving the buzzer works ideally when
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 non-musical output frequencies are needed, i.e., frequencies that are expressed
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 in absolute Hz rather than musical notes.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 PWT appears to have been added specifically to facilitate playing of ringtones
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 that are composed of musical notes. Compared to the range of 255 possible
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 frequencies that can be produced by BU, PWT can only produce 48 different tone
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 frequencies, but these 48 possible PWT frequencies are special in that they
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 closely approximate the 48 musical notes ranging from F4 to E8 in the scientific
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 pitch notation. These 48 musical notes of PWT range cannot be reproduced as
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 distinct frequencies in BU mode: at the upper range beginning with A6, two or
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 three different notes collapse to the same BU tone frequency, as the possible
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 frequencies that can be produced from 13 MHz by the simple division implemented
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 in BU get farther apart than successive notes of the chromatic scale. Thus if
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51 you are seeking to play ringtones that are composed of musical notes, use of PWT
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 should be considered mandatory rather than optional. OTOH, if you are playing
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 non-musical tones like SIT that are defined in absolute Hz, then BU will often
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 work better.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55
889
834b5645a123 doc/Buzzer-melodies: note the fact that Mot C1xx official fw uses PWT
Mychaela Falconia <falcon@freecalypso.org>
parents: 875
diff changeset
56 Motorola C1xx official firmware uses PWT mode to play its ringtones, both
834b5645a123 doc/Buzzer-melodies: note the fact that Mot C1xx official fw uses PWT
Mychaela Falconia <falcon@freecalypso.org>
parents: 875
diff changeset
57 built-in and user-composed, and we have successfully extracted some of those
834b5645a123 doc/Buzzer-melodies: note the fact that Mot C1xx official fw uses PWT
Mychaela Falconia <falcon@freecalypso.org>
parents: 875
diff changeset
58 professional-quality PWT melodies from at least one C1xx firmware version.
834b5645a123 doc/Buzzer-melodies: note the fact that Mot C1xx official fw uses PWT
Mychaela Falconia <falcon@freecalypso.org>
parents: 875
diff changeset
59
831
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 Concept of buzzer melodies
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61 ==========================
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
62
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 The Calypso buzzer (either BU or PWT) is monophonic, meaning that it can only
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64 play one note at a time. Given this constraint, a playable buzzer melody can be
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 defined as a list of {tone, volume, duration} tuples, where <tone> is the
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66 frequency to be played (BU or PWT), <volume> is the relative volume for this
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 note (PWM volume control), and <duration> is how long this note should sound.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 The definitions for <tone> and <volume> are straightforward - they are numbers
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 going directly into hardware registers - but in what units should the duration
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 of notes be reckoned? In FreeCalypso we have adopted TDMA frames of 4.615 ms
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 (or more precisely 60/13 ms) as our unit of duration for buzzer melodies, based
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 on this reasoning: if playing of buzzer melodies is to be incorporated into
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 operational phone handset firmware, then TDMA frames will be the only time unit
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 that is available natively and directly, whereas any other measurement such as
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 milliseconds would have to be converted to TDMA frames by the firmware code.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 Therefore, it makes the best sense to reckon all note durations in our buzzer
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 melodies in TDMA frames to begin with.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79
873
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
80 2022 addition: BUZM melody player engine in FC Tourmaline
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
81 =========================================================
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
82
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
83 As of 2022 our FC Tourmaline firmware includes a new buzzer melody player
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
84 engine, implemented as a RiViera-based service named BUZM. The new BUZM service
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
85 sits on top of the low-level PWT buzzer driver in the same way how RiViera
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
86 Audio service sits on top of the low-level DSP+L1 combo, and the API (directed
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
87 toward UI firmware layers) of the new BUZM service is modeled after that of RV
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
88 Audio service. The primary objective of this BUZM venture is to get rid of the
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
89 Condat audio driver layer mess which we inherited from TI (it has buzzer ringing
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
90 and audio tone generation entangled together in a gnarly way which we need to
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
91 move away from), but this migration also provides a secondary benefit: instead
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
92 of being hard-coded, buzzer melodies will now be read from files in FFS, just
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
93 like E1 melodies for loudspeaker-based ringing, allowing our UI firmware design
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
94 to be harmonized between the two ringer configurations.
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
95
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
96 The following design decisions underlie our new FC Tourmaline buzzer melody
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
97 facility:
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
98
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
99 * Regarding the choice between BU or PWT driving, PWT has been chosen. All
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
100 melodies created for playing via BUZM need to consist of musical notes F4
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
101 through E8 (scientific pitch notation, 349 to 5274 Hz), as supported by
889
834b5645a123 doc/Buzzer-melodies: note the fact that Mot C1xx official fw uses PWT
Mychaela Falconia <falcon@freecalypso.org>
parents: 875
diff changeset
102 Calypso PWT block. This design decision matches Mot C1xx official firmware.
873
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
103
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
104 * Each melody is a sequence of sounded tones (PWT), either directly abutted or
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
105 separated by pauses. In actual implementation, each melody is a sequence of
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
106 directly abutted entries, where each entry can be either a sounded tone or a
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
107 pause. Each entry (tone or silence) has a duration, reckoned in TDMA frames
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
108 as explained above.
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
109
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
110 * For every sounded tone in a melody, a note volume in the range [1,64] is
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
111 given. If the melody is played at maximum volume, the per-note volumes will
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
112 be written directly into the hardware register (PWM control in 1/64 units).
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
113 If the user-specified play volume is less than 64, the actual sounding volume
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
114 of each note is determined as (play_volume * note_volume / 64), with the
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
115 division step rounding up - when both play_volume and note_volume are
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
116 constrained in the [1,64] range, the result of the rounding-up division is
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
117 also constrained in the same range.
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
118
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
119 In terms of tool support, each FreeCalypso PWT buzzer melody begins life as an
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
120 ASCII text source in the format defined by us. It is then compiled into binary
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
121 form with our fc-pwt-comp utility, and the resulting binary melody file is
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
122 uploaded into FreeCalypso device FFS. For manual testing, each uploaded buzzer
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
123 melody can be played with AT@BUZ command. For finished phone operation, there
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
124 will be two ringtone list files (one for play-until-answer ringing tones and
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
125 one for non-repeating message alert tones) that will drive ringtone selection
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
126 in the phone UI.
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
127
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
128 The format of ASCII source files for PWT melodies is best documented by
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
129 examples: see several in the ringtools/examples directory.
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
130
875
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
131 Organization of melodies in FC device FFS
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
132 =========================================
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
133
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
134 We shall have two types of ringtone melodies in FreeCalypso: PWT melodies to be
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
135 played via the buzzer, and E1 melodies to be played via the voice path
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
136 loudspeaker. Naturally, buzzer melodies can only be played on hardware
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
137 platforms that have a buzzer, and voice path loudspeaker melodies can only be
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
138 played on hw platforms that have such a speaker. The only platforms that can
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
139 be expected to have both hw provisions are development boards like D-Sample and
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
140 FC Venus - but even on those development boards, each given UI firmware build
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
141 will support one or the other ringing type, but not both at the same time.
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
142
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
143 We shall have two separate FFS subtrees for these two melody types: PWT melodies
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
144 for the buzzer will be stored under /buz, whereas E1 melodies for the voice path
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
145 will be stored under /mel. Both trees will be constructed on the host system
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
146 under /opt/freecalypso/buz and /opt/freecalypso/mel, and they will be uploaded
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
147 into FC device FFS with fc-fsio:
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
148
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
149 upload-subtree /opt/freecalypso/buz /buz
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
150 upload-subtree /opt/freecalypso/mel /mel
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
151
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
152 Individual melody files (compiled binary formats produced by fc-pwt-comp and
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
153 fc-e1gen) will be stored as /buz/melodyname.bz and /mel/melodyname.e1 for the
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
154 two types. There will also be melody list or index files:
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
155
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
156 /buz/ringtones.mls
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
157 /buz/msgtones.mls
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
158 /mel/ringtones.mls
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
159 /mel/msgtones.mls
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
160
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
161 Each ringtones.mls file (for the buzzer or for Melody E1) will list the
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
162 available melodies for the continuous play-until-answer ringing tone, and each
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
163 msgtones.mls file will list the available melodies for the non-repeating message
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
164 alert tone. The melody list (.mls) file format is defined by us: it is a binary
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
165 format consisting of fixed-length records, one 80-byte record for each listed
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
166 melody. Each record consists of two fields: the FFS pathname (always absolute
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
167 as required by the RTOS environment without current directories) of the melody
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
168 file and the name of the melody for the selection menu in the phone UI. Melody
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
169 lists are compiled from line-based ASCII source into this binary format by our
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
170 fc-ringlist-comp utility.
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
171
890
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
172 Support for iMelody ringtones
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
173 =============================
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
174
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
175 Back in the olden days when dumbphones with monophonic buzzer-type ringers were
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
176 the norm in society, there was a community of phone users who composed and
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
177 exchanged their own ringtone melodies; the community standard format for those
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
178 interchanges was EMS iMelody. Searching around the Internet in 2022, I (Mother
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
179 Mychaela) couldn't find any iMelody ringtones that sound any good - the only
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
180 ones I could find sound like crap, nowhere near professional-quality melodies
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
181 which we've lifted out of Motorola's firmware. However, as a matter of due
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
182 diligence, I felt that it would improper for FreeCalypso not to support iMelody
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
183 ringtones, hence I wrote a program that groks iMelody files and converts those
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
184 melodies to our native PWT format - this program is fc-imy2pwt.
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
185
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
186 Right now fc-imy2pwt implements a subset of the iMelody spec; the missing
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
187 features are:
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
188
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
189 * All volume change commands in the melody are ignored: fc-imy2pwt does not
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
190 support per-note volume changes within the melody, and all PWT notes are
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
191 emitted at the maximum per-note volume of 64/64.
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
192
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
193 * The STYLE setting in IMY files is ignored, and all melodies are converted as
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
194 if the style was S1, i.e., continuous, without automatically inserted rest
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
195 between notes.
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
196
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
197 * All vibrator/LED/backlight control commands are ignored: in FreeCalypso
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
198 architecture there is no synchronization between ringtone melodies and
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
199 vibration cadence, instead the user selects between silent mode, ring only,
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
200 vibrate only or ring+vibrate alerting as needed, without interference from
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
201 overly-creative vanity melody composers. Likewise, we do not support
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
202 melody-driven manipulation of any lights.
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
203
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
204 The policies of keeping the ringer and the vibrator separate and of leaving our
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
205 LCD and keypad backlights alone are absolute, whereas support for volume changes
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
206 within the melody and for non-S1 styles (automatically inserted rest periods)
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
207 can be implemented *if* someone in our community has a real use case for such
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
208 functionality.
76cc910c508e document fc-imy2pwt
Mychaela Falconia <falcon@freecalypso.org>
parents: 889
diff changeset
209
873
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
210 Standalone buzzer exercising (outside of FC firmware)
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
211 =====================================================
831
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
212
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
213 We have a target utility (running on Calypso devices out of RAM) called
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
214 buzplayer, and a front end host program called fc-buzplay. If you load and run
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
215 buzplayer manually via fc-iram, you can use it to exercise the buzzer manually,
873
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
216 playing any tone at any volume, in either BU or PWT mode.
831
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
217
873
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
218 fc-buzplay is a higher-level tool: it establishes out-of-firmware operation on
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
219 a target Calypso device similarly to fc-loadtool (based on the same framework),
897
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
220 but running buzplayer instead of loadagent. Once you land at the buzplay>
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
221 prompt, the main command of interest is 'play': it takes one required argument,
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
222 the name of the melody file to play (ASCII BU or PWT format), and a second
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
223 optional argument, the play volume in the [1,64] range. The current version of
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
224 this 'play' command intuits the melody format (BU or PWT) from the filename,
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
225 which must end in .buz or .pwt, respectively. You can also issue explicit
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
226 play-bu and play-pwt commands, in which case the filename can be anything. All
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
227 of these play command variants read the melody file in the respective format
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
228 (ASCII in both cases, line-based), feed the melody to the target, and then
cb0f61535166 doc/Buzzer-melodies: update for new fc-buzplay
Mychaela Falconia <falcon@freecalypso.org>
parents: 890
diff changeset
229 command buzplayer to actually play it on the physical buzzer.