FreeCalypso > hg > freecalypso-tools

annotate doc/Buzzer-melodies @ 875:8ff9bce1b56e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
document fc-ringlist-comp
author Mychaela Falconia <falcon@freecalypso.org>
date Wed, 30 Mar 2022 06:25:47 +0000
parents 2b5f4736079c
children 834b5645a123
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
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 Concept of buzzer melodies
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 ==========================
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 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
60 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
61 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
62 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
63 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
64
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 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
66 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
67 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
68 (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
69 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
70 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
71 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
72 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
73 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
74 melodies in TDMA frames to begin with.
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
873
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
76 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
77 =========================================================
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
78
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
79 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
80 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
81 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
82 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
83 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
84 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
85 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
86 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
87 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
88 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
89 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
90 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
91
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
92 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
93 facility:
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
94
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
95 * 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
96 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
97 through E8 (scientific pitch notation, 349 to 5274 Hz), as supported by
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
98 Calypso PWT block.
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
99
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
100 * 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
101 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
102 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
103 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
104 as explained above.
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
105
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
106 * 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
107 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
108 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
109 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
110 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
111 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
112 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
113 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
114
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
115 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
116 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
117 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
118 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
119 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
120 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
121 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
122 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
123
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
124 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
125 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
126
875
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
127 Organization of melodies in FC device FFS
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
128 =========================================
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
129
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
130 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
131 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
132 loudspeaker. Naturally, buzzer melodies can only be played on hardware
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
133 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
134 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
135 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
136 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
137 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
138
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
139 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
140 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
141 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
142 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
143 into FC device FFS with fc-fsio:
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
144
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
145 upload-subtree /opt/freecalypso/buz /buz
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
146 upload-subtree /opt/freecalypso/mel /mel
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
147
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
148 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
149 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
150 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
151
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
152 /buz/ringtones.mls
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
153 /buz/msgtones.mls
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
154 /mel/ringtones.mls
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
155 /mel/msgtones.mls
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
156
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
157 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
158 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
159 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
160 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
161 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
162 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
163 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
164 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
165 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
166 fc-ringlist-comp utility.
8ff9bce1b56e document fc-ringlist-comp
Mychaela Falconia <falcon@freecalypso.org>
parents: 873
diff changeset
167
873
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
168 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
169 =====================================================
831
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170
2f401860e9ad documentation update for buzzer melodies
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171 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
172 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
173 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
174 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
175
873
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
176 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
177 a target Calypso device similarly to fc-loadtool (based on the same framework),
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
178 but running buzplayer instead of loadagent. The original command of meaty
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
179 action was/is 'play' - it reads a BU (not PWT) melody from an ASCII source file
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
180 in a format that was the predecessor of our current PWT format, feeds it to
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
181 buzplayer on the target, and commands buzplayer to actually play it on the
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
182 physical buzzer. Later buzplayer (the target utility) was extended to support
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
183 PWT in addition to BU, and fc-buzplay got a new 'playt' command - this new
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
184 command plays PWT melodies, reading melody files in the same ASCII source format
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
185 as fc-pwt-comp. (In actual history this ASCII source format was invented for
2b5f4736079c doc/Buzzer-melodies: update for fc-pwt-comp and Tourmaline BUZM
Mychaela Falconia <falcon@freecalypso.org>
parents: 831
diff changeset
186 fc-buzplay first, and then later we turned it into fc-pwt-comp.)