freecalypso-tools: doc/Buzzer-melodies annotate

annotate doc/Buzzer-melodies @ 973:7c18eac91457

loadtools: round out support for Intel flash families The three Intel flash families encountered so far in Calypso GSM devices are C3, W30 and W18, sizes from 2 to 8 MiB. Let's support all Intel flash chips from these 3 families across this range of sizes.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Tue, 28 Nov 2023 18:56:40 +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.

FreeCalypso > hg > freecalypso-tools

annotate doc/Buzzer-melodies @ 973:7c18eac91457