freecalypso-tools: doc/Buzzer-melodies annotate

annotate doc/Buzzer-melodies @ 926:6a0aa8d36d06

rvinterf backslash escape: introduce libprint The new helper function library named libprint is meant to replace the badly misnamed libg23, and will soon contain functions for printing all of the same kinds of GPF TST packets that are now handled in libg23. However, we are also moving safe_print_trace() from libasync to this new library, and changing it to emit our new backslash escape format.

author	Mychaela Falconia <falcon@freecalypso.org>
date	Tue, 23 May 2023 03:47:46 +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 @ 926:6a0aa8d36d06