FreeCalypso > hg > freecalypso-tools

annotate doc/Buzzer-melodies @ 927:4e243402f453

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
rvinterf/lowlevel: use libprint for backslash-escape output
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 23 May 2023 03:59:42 +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.