FreeCalypso > hg > freecalypso-tools
annotate doc/Buzzer-melodies @ 955:803e926e0699
doc/Pirelli-loadtools-entry: new article
author | Mychaela Falconia <falcon@freecalypso.org> |
---|---|
date | Wed, 07 Jun 2023 23:52:09 +0000 |
parents | cb0f61535166 |
children |
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. |