--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Calypso-buzzer-output	Sat May 29 07:07:05 2021 +0000
@@ -0,0 +1,91 @@
+Our dear Calypso has a dedicated digital output for driving old-fashioned
+cellphone buzzers - I (Mother Mychaela) previously assumed those buzzers to be
+piezoelectric, but now it appears that they are actually magnetic buzzers, not
+piezo.  But irrespective of the physics of the actual transducer that is
+ultimately controlled by Calypso BU/PWT output, the Calypso output itself is
+purely digital, producing digital waveforms, and we (FreeCalypso) need to
+understand exactly what the chip puts out.  The findings presented here have
+been obtained by observing Calypso BU/PWT output with an oscilloscope; the hw
+platform used by the Mother for these experiments was a BenQ M32 module - this
+module has the familiar Calypso+Iota chipset inside, it has BU/PWT brought out,
+and the breakout board supplied with these modules allowed for very quick
+experimentation.
+
+BU mode
+=======
+
+BU functionality of the BU/PWT output is implemented in the ARMIO block,
+together with GPIO and keypad functions.  Here are the new findings which were
+previously unknowable without oscilloscope observation:
+
+* In "normal" buzzer operation when ARMIO_LOAD_TIM is in the [1,255] range
+  (i.e., not 0), the output frequency is 13 MHz / 512 / (ARMIO_LOAD_TIM + 1).
+  This part matches our previous understanding.  The highest frequency that can
+  be produced is 12.6953125 kHz, and the lowest is 99.182129 Hz.
+
+* When ARMIO_LOAD_TIM is set to 0 and the buzzer is enabled, BU output is NOT a
+  25.390625 kHz tone (per the formula above) as we previously thought - instead
+  BU output will be constant high if BUZZER_LEVEL_REG is set to maximum 63, or
+  pure 203.125 kHz PWM exactly like LT otherwise.
+
+* PWM power level control for BU works exactly like the one for LT - see the
+  companion Calypso-PWM-light article.
+
+* The interesting question is exactly how PWM power level control and tone
+  generation combine, and the answer turned out to match the terse description
+  in CAL207: BU is the output of an AND gate; one input to this AND gate is the
+  output of the timer that produces tones between 99 Hz and 12.7 kHz (or
+  constant high if ARMIO_LOAD_TIM is set to 0), and the other input to the AND
+  gate is a PWM block strictly identical to LT.
+
+* For a practical example, consider what happens when a 12.7 kHz (max frequency)
+  tone is emitted in combination with PWM.  The "on" part of the waveform at
+  this tone frequency equals 512 periods of CLK13M, whereas the full cycle of
+  LT-like PWM is 64 periods of CLK13M.  Thus the waveform seen on an o'scope
+  consists of 8 repeated PWM cycles, then a "pause" of 512 CLK13M periods (the
+  "off" part of the tone waveform), then the full cycle repeats.  Furthermore,
+  the tone waveform and the PWM waveform fed to the internal AND gate are not
+  synchronized, and the resulting slight misalignment is easily visible on an
+  o'scope.
+
+Pirelli DP-L10
+==============
+
+In the Pirelli DP-L10 phone Calypso BU output is repurposed to control the
+vibrator.  Pirelli's official fw sets ARMIO_LOAD_TIM to 0 and BUZZER_LEVEL_REG
+to 63; when operated in this manner, BU becomes a mere on/off output under
+software control just like a GPIO.  If someone wishes to run the vibrating motor
+at a lower speed (i.e., exercise a form of "analog" control), the correct way to
+perform such feat would be by dialing down BUZZER_LEVEL_REG (PWM control between
+1/64 and 64/64) - setting ARMIO_LOAD_TIM to a nonzero value does not seem to
+make any sense when the buzzer has been replaced with a vibrator.
+
+PWT mode
+========
+
+The principal difference between BU and PWT modes is that BU mode generates
+"arbitrary" tone frequencies by dividing from CLK13M/512, whereas PWT mode
+generates predefined musical note frequencies, specifically 48 notes of the
+chromatic scale from F4 through E8 in the scientific pitch notation.  The
+frequency range of PWT mode is narrower than BU mode (349 Hz to 5274 Hz, as
+opposed to 99 Hz to 12.7 kHz), and PWT does not support constant high output
+for Pirelli-style vibrator driving - however, BU mode suffers from a major
+problem in that its repertoire of possible tone frequencies does not correspond
+to musical notes.  Given the desire to have ringtone melodies that are composed
+of standard musical notes, TI added the new PWT hardware block that is
+specifically designed to produce musical note frequencies.
+
+Here are some observations about PWT made with o'scope experiments:
+
+* The description of FRC_REG in CAL207 is correct: bits [1:0] select the octave,
+  bits [5:2] select the semitone within the octave.  The definitions in the
+  non-functional (not actually used) mmiBuzzer.h header file in TI's BMI source
+  are wrong - or more precisely, the definitions under #if 0 are the correct
+  ones, whereas the enabled-for-compilation definitions are wrong.
+
+* PWM power control works on the same principle as in BU mode: the output of
+  the musical tone frequency generator and the output of the PWM block are
+  simply ANDed together.  The 64-level PWM block itself is very similar to the
+  ones in LT and BU, but it runs 8 times slower, i.e., one PWM period is 512
+  cycles of CLK13M, as opposed to 64 cycles of CLK13M in BU and LT, and each
+  "quantum" of this slower PWM equals 8 cycles of CLK13M.