FreeCalypso Handset Specification
=================================

The purpose of this document is two-fold:

1) This document serves as the principal design specification for the
   FreeCalypso Libre Dumbphone handset hardware which I, Mother Mychaela,
   seek to build.

2) This document also defines the scope of functionality to be supported in
   FreeCalypso handset firmware, including support for additional hardware
   targets beyond the primary FC handset hw target.

1. FC handset hardware specification

1.1. Basic features

The Mother's goal is to produce a replacement for the proprietary Pirelli DP-L10
phone, or more specifically, for the GSM-only subset of this Pirelli phone which
the Mother actually uses, *without* Pirelli's key differentiating feature of
non-GSM WiFi operation, and without Pirelli's camera.  The following hardware
features are to be included:

* 176x220 pixel color display (no touch)
* 21-button main keypad
* 3 side buttons for volume control and an auxiliary function
* hands-free loudspeaker
* vibrator
* USB port that combines charging and computer interface
* wired analog headset jack
* single SIM slot

The following features which are commonly found in mainstream proprietary
phones, particularly more recent ones, will NOT be included:

* camera
* Bluetooth
* FM radio
* TV receiver
* GPS receiver
* dual SIM slot
* torch light beyond LCD and keypad backlights

1.2. RF band capability

Our FC handset needs to be quadband GSM; this quadband capability will be
achieved by copying the RF section and the core PCB layout around it from the
reverse-engineered iWOW TR-800 modem module, which is itself a very direct
(almost verbatim) derivative of TI's Leonardo+ quadband reference design.

1.3. RAM and flash

The Mother's intent is to use Spansion S71PL064JA0 flash+RAM MCP on the final
handset motherboard, providing 8 MiB of flash and 2 MiB of XRAM in a 7x9 mm
footprint.  This flash and RAM capacity is already known to be fully sufficient
for our FreeCalypso handset firmware in maximal feature configuration, hence
any larger capacity would be excessive.  However, on our FC Venus development
board we may use the larger S71PL129NC0 MCP, same as used on FCDEV3B V2.

1.4. Liquid crystal display

1.4.1. Display size

The size of the display for our FC Libre Dumbphone handset design is fixed at
176x220 pixels, 16-bit color, following TI's D-Sample platform and the starting
point UI code that was developed for it.  Thoughts of changing to a different
display size have been considered and rejected:

* If we were to change to a smaller display size, we would have to do extra work
  on the firmware to shrink the UI to the smaller size, and we would reduce the
  amount of information that can be displayed at once.  We would incur extra
  work and a functional loss, but gain absolutely nothing in return.

* If we were to change to a larger display size (240x320 pixels seems to be the
  largest reasonable size for dumbphones, used in high-end Nokia models), we
  would be venturing into uncertain territory - the greatest uncertainty would
  be the extra CPU load on Calypso to draw the larger UI and to refresh the
  larger framebuffer, which is done with PIO on Calypso, without any DMA
  assistance.  The D-Sample LCD size of 176x220 pixels already appears to be a
  strain in some drawing code paths, hence the Mother's decision is to play it
  safe and stick with the known working display size.  Expanding the UI to make
  sensible use of larger screen real estate would also entail additional work.

176x220 is the display size in pixels, and this resolution number by itself says
nothing about the physical display size in inches or mm.  However, most readily
available LCDs that are made for this pixel resolution are made in 2.0" diagonal
physical size, with 31.68x39.60 mm active area and 0.180 mm dot pitch, hence
this physical size is the one we are going to use.

1.4.2. Specific LCD module selection

As of this writing, the specific LCD module to be used has not been firmly
selected yet.  We are actively looking for an LCD module that fits all of the
following requirements:

* TFT color LCD, 2.0" diagonal, 176x220 pixel resolution;

* 16-bit microprocessor bus interface;

* 6:00 viewing direction as appropriate for cellular handsets;

* backlight consisting of 3 white LEDs in parallel, joined at the anode,
  with separately brought-out cathodes;

* mechanical design that supports mounting with the FPC tail folded under the
  module, either by way of direct solder termination (no connector) or by way
  of raised sides that create sufficient vertical space to accommodate the FPC
  connector.

The requirement of 16-bit microprocessor bus interface stems from the desire to
interface this LCD to the Calypso in exactly the same way how TI did it on the
D-Sample, the 6:00 viewing direction and mechanical mounting requirements stem
naturally from the target application (cellular phone handset), and the
backlight LED wiring requirement stems from the constraints of our chosen
MAX1916 backlight LED driver chip - see section 1.4.4.

1.4.3. Backlight and readability considerations

Out of the various pre-existing mobile phones which I (Mychaela) have
experienced, there have been 3 different kinds of LCDs in terms of how display
operation and readability interacts with the backlight:

1) older phones with black&white LCDs: on all phones of this type which I've
   ever used, the display is perfectly readable without the backlight given
   ordinary ambient lighting, be it natural daylight or room lighting.  Such
   LCDs are called reflective.  With these B&W displays, you only need to turn
   on the backlight if you need to operate the phone in darkness, such as
   outdoors at night or inside with all lights off.  The firmware in such phones
   is typically designed to leave the actual display functional and updated at
   all times, with only the backlight subject to on/off control.

2) most newer phones with color displays, of which Pirelli DP-L10 is a
   representative case, have transmissive LCDs that are not designed to be
   readable without the backlight at all - backlight required for readability
   (BLRR) is another way to describe such LCDs.  Because the display is not
   readable at all without the backlight, phone firmware is typically designed
   to turn off the entire display (not just the backlight) when the screen goes
   dark, and operation visible to the user is display on/off, rather than
   backlight on/off.  It is a good firmware design practice to "swallow" the
   initial keypress that turns on the display from dark state, i.e., to block
   the regular action of whatever button was pressed to "wake up" the display.

3) The color display on Motorola C139 phones is an odd intermediate case: this
   display is NOT practically readable with the backlight off, yet the firmware
   is designed as if the display were readable in this condition: the actual
   display (unsure if it is CSTN or TFT) remains on and updated, and when you
   press some button to "wake up" the display, that button still takes its
   regular action, which is really bad for usability.  How do we know that the
   actual CSTN or TFT display remains on and actively updated when it is not
   readable with the backlight off?  Answer: the non-backlit display can be made
   readable by shining a flashlight directly at it - but this trick requires a
   directly pointed flashlight; no amount of ordinary ambient light is enough
   to make the display readable.

Because our FC Libre Dumbphone handset will have a color display (contemporary
TFT) and because we are sane, not copying the monumental design mistake of Mot
C139, our display will fall into class 2 by the above classification: backlight
required for readability, full display on/off rather than just backlight on/off,
firmware operating like Pirelli's in terms of wake-up keypress swallowing.

1.4.3.1. Backlight dimming mode

Because our LCD is of BLRR type and because we seek to fully replicate Pirelli's
logic in terms of when keypresses are swallowed and when they are not, we need
to implement a dimming mode for our LCD backlight.  In Pirelli's design which we
are copying, when you are playing with phone menus or composing SMS etc, but are
not in an active call, the display switches between full brightness and totally
off - it goes fully off on timeout, and when you press a button to wake it up,
it switches on at full brightness, together with the keypad backlight.  But when
you are in a call, when the timer expires (and it's a shorter timer, 10 s
instead of 30 s), the display goes dim instead of fully off, and in this dimmed
(but still readable) state keypresses are NOT swallowed.

We only need to implement two different intensity levels for the LCD backlight:
full brightness and in-call dimmed.  The backlight intensity level in the dimmed
state will need to be chosen on this principle: use the lowest backlight LED
current (to conserve battery power and allow longest talk time on one charge) at
which the display is still readable, similarly to Pirelli's in-call dimmed
state.

In the user-actively-poking state, as opposed to the long-call dimmed state,
there is no need to provide different configurable backlight levels - see
section 1.4.5.

1.4.4. Backlight circuit implementation

In all candidate TFT LCD modules that are being considered (see section 1.4.2),
the backlight consists of 3 white LEDs wired in parallel, joined either at the
anode or at the cathode - although as we shall see momentarily, we require an
LCD module where the 3 LEDs are joined at the anode, with the 3 cathodes brought
out separately.  LCD module datasheets call for 15 mA current through each LED
at maximum intensity, for 45 mA total, and the LED forward drop voltage (Vf) at
this rated current seems to range between 2.9 V (what I actually measured on one
candidate LCD module) to 3.2 V (what the datasheets list as typical) to perhaps
as high as 3.4 V (what one datasheet lists as the maximum).

Given the parallel (as opposed to series) wiring of the 3 LEDs and the
relatively low Vf, there is no need to use any kind of boost converter as part
of the LED driver circuit for this backlight - any boost converter will only add
inefficiency (more current will be drawn from the battery for the same LED
current), hence we need to avoid using such.

Regardless of whether a given phone design uses a boost converter or not (it
seems that older designs do use boost converters, either because older white
LEDs have higher Vf or because 2 or 3 LEDs are wired in series), all traditional
phone designs seem to share the quality where the display backlight brightness
remains the same as the battery discharges and as Vbat goes down - this quality
was directly observed on the Pirelli DP-L10 (unknown circuit design) and
inferred from the available schematics for Mot C139 and C155, with both of the
latter boost-converting to fixed 5.0 V.  In our case, even though we choose to
not use a boost converter for efficiency reasons, we still need to achieve the
quality of the display brightness remaining the same through the discharge range
of our Li-ion battery - having the display dim in half as the battery discharges
from 4.2 V peak to 3.6-3.7 V plateau is simply not acceptable.

The simplest possible LED driving circuit would be one where a current limiting
resistor is inserted in series with each LED, and then the 3 parallel
LED+resistor sets are connected across battery terminals, with a transistor
inserted somewhere to act as the on/off switch.  However, this trivial circuit
is not suitable in our application because it would produce unacceptably large
variation in display brightness as the battery discharges - hence we need a more
intelligent LED driving circuit.  Our Luna LCD carrier board from the spring of
2020 features an LDO bringing Vbat down to fixed 3.5 V, followed by very low-
value resistors in series with each LED - but this approach is not good for
production either, as it makes the LED current extremely sensitive to any slight
variations in Vf.

Fortunately, I was able to find a specialized white LED driver chip that is just
perfect for our application, or more precisely, a specialized chip that acts as
a constant current sink for such LEDs - Maxim MAX1916, design from 2001, just
the right time frame for the kind of phone we are seeking to build.  This
special chip takes the place of "dumb" ballast resistors: connect Vbat (battery
positive terminal) directly to the common anode of the 3 LEDs, but instead of
series resistors, connect each cathode to the corresponding LEDn pin of MAX1916
- *without* any resistors or transistors!  FETs inside the MAX1916 take the
place of resistors as current-limiting elements, and the chip's global on/off
control (which will be driven with a Calypso GPIO) takes the place of a separate
switching transistor.

The special quality of MAX1916 is that it produces constant current through each
LED (based on a set reference current and 230x current multiplication circuit
inside the chip) regardless of variations in both Vbat and Vf!  Of course the
requested current can only be sustained as long as Vbat >= Vf + Vds, where Vds
is the lowest drop voltage of the FETs inside MAX1916, and once Vbat falls below
this point, the LED current will begin to decline.  However, the beauty of this
design is that no arbitrary artificial turnover points (like the 3.5 V point in
our hacky design from the spring of 2020) need to be set: the battery discharge
point at which the LED current begins to decline will be whatever it comes to be
naturally, based on Vf (perhaps depending on temperature) and MAX1916 Vds, and
the decline is expected to be gradual.

1.4.4.1. Backlight current selection and dimming

In the simplest MAX1916-based design, a fixed LED current is set by connecting
a resistor of appropriately computed value between MAX1916 SET pin and whatever
regulated fixed voltage rail happens to be available in the system.  However,
in our application (see section 1.4.3.1) we need at least two different display
brightness levels, and thus at least two switchable LED currents.  At first the
problem seems difficult, but an elegant solution has been found.

LCD backlight LED current will be selected by way of two Calypso GPIO pins
configured as outputs, and a 74LVC2G125 dual tristate buffer.  Each tristate
buffer's A input will be tied high, and the two Calypso GPIO outputs will be
connected to buffer output enable inputs.  There will be two resistors with
different carefully computed values, each connected between one of the two
tristate buffer outputs and MAX1916 SET pin.  One resistor will provide a small
current, the other will provide a large current, and each of these two currents
will be switchable on/off by Calypso GPIO signals switching the buffer outputs
between driving high (2.7-2.8 V) and Hi-Z.  Resistor values will be chosen such
that the sum of both currents will be the 15 mA limit (the current is reckoned
per LED), whereas the small current alone will be whatever we need for the
battery-saving long-call dimmed mode.

1.4.5. Slight regression relative to Pirelli DP-L10

The actual LCD backlight LED driving circuit inside the Pirelli phone is not
known, but reverse engineering of Pirelli's firmware followed by experimentation
reveals that backlight intensity variation is achieved via a form of PWM, using
Calypso PWL output - although PWL is used in an inverted sense, such that the
backlight intensity increases with more 0s being put out on PWL, as opposed to
more 1s.  Thus regardless of the unknown actual circuit implementation, the
backlight intensity appears to be continuously variable from 1/255 to 255/255,
which is certainly a much richer control than our crude selection of just 3
possible LED currents.

In terms of what Pirelli's fw offers to end users, the backlight intensity in
the dimmed in-call state is always set to 1/255, without any way to change it,
whereas the backlight intensity in the active interaction state is selectable
via a menu among 5 levels; the 5 offered levels turn into 1/255, 64/255,
128/255, 192/255 and 255/255 in the resulting PWL programming.

So in terms of both hardware capabilities and end user offering via the
firmware, Pirelli's LCD backlight level control is richer than what we are
proposing for our FC Libre Dumbphone.  However, engineering is all about
trade-offs and compromises, and in the Mother's opinion, this slight reduction
in the richness of functionality is sufficiently offset by the efficiency of
our MAX1916-based approach: aside from the theoretical possibility of a
switching buck converter, which I've never seen used for LED driving
applications, our choice of MAX1916 is the most battery-efficient way to drive
our backlight LEDs.  Furthermore, when dimming is effected by switching the
actual regulated LED current, as in our case, as opposed to applying PWM, our
backlight becomes more resilient to even lower battery voltages.

Consider what happens when Vbat falls below the point at which the design-
intended LED current can be maintained - what happens then?  If no PWM is
applied, or if PWM is set to maximum, then display brightness will be whatever
maximum is possible at this low battery voltage.  But if PWM is applied,
especially very low duty cycles as in the case of Pirelli's dimmed state, then
the display that has already been dimmed by low Vbat will be *further* dimmed
by this aggressive PWM, likely producing an unreadable display at this point.
It may be possible to compensate via extra complexity in the firmware, by
turning PWM up when Vbat (as measured via Iota MADC) falls too low - but then
we would be getting really messy, whereas switching the regulated current is so
much more elegant.  With our approach, low-battery-induced dimming in the "full
brightness" mode will happen at the same discharge point as it would if we had
used PWM (and set PWM to maximum in this "full brightness" mode), but in the
in-call dimmed state, further dimming due to low Vbat will probably happen at a
lower discharge point (if Vf decreases with decreasing current), and when it
does happen, there won't be a combination of both natural and artificially-
induced reductions, just the natural one.

Thus based on all of the above considerations, I feel justified in my design
choice of foregoing PWM control of backlight intensity in favor of fixed current
switching with much more limited selection.

1.5. Main keypad

The main keypad on our FC Libre Dumbphone handset will have the following
21-button arrangement:

left soft key	 ^	right soft key
		<O>
green call	 V	red power/hang-up
button			button

1		2	3
4		5	6
7		8	9
*		0	#

The top section above the traditional numeric dial buttons (12) consists of left
and right soft keys, green and red buttons (classically called SEND/END), and a
5-way navigation button group (left, right, up, down and center), for a total of
9 buttons in this section.  The red hang-up button is also the hardware power-on
button; having the same button effect power-off when held down for some time is
a firmware function.

This 21-button main keypad arrangement is exactly the same as featured on
Motorola C1xx and Pirelli DP-L10 phones, on TI's D-Sample development platform,
and also on many other phones (non-Calypso) from the appropriate era, such as
Samsung E2232.

1.5.1. Keypad backlight

All traditional phones including Mot C1xx and Pirelli DP-L10 feature keypad
backlights, hence we need to include one as well.  The exact structure of this
backlight won't be known until we enter the mechanical design phase for the
actual handset (as opposed to intermediate development boards), which will be
much later in the project, but the Mother's understanding is that keypad
backlights are made up of some number of LEDs (2 on Pirelli DP-L10, unknown
number on Mot C139) and some kind of light diffuser.

Given the discovery of MAX1916 constant-current-sink LED driver chip (see
section 1.4.4), the optimal electrical design of the keypad backlight becomes
clear: use 3 LEDs, and drive them using another MAX1916 chip, separate from the
one used for the LCD backlight.

Backlight intensity: neither Mot C139 nor Pirelli DP-L10 provides any way to
vary keypad backlight intensity, and no such variability is deemed necessary.
In the long-call state when the LCD backlight is dimmed, the keypad backlight
is fully off.  We shall use a fixed LED current setting for our keypad
backlight, set with a single fixed resistor between the keypad MAX1916 chip's
SET pin and the V-IO rail, and the actual current value will be determined in a
much later phase of the project, when we have the actual keypad backlight LEDs
and a better idea of the mechanical design.

Backlight color: Mot C139 uses blue LEDs, Pirelli DP-L10 uses white LEDs.
Because blue and white LEDs have very similar electrical characteristics
(current needed for appropriate brightness, Vf at this current), the choice
between the two can be made in a much later project phase, based on input from
other team members who are better at aesthetics.

1.5.1.1. Comparison with Mot C139 and Pirelli DP-L10

Both of these two pre-existing reference phones feature keypad backlights that
are switched on/off via Iota LEDB; the actual circuit design is unknown.
However, in our design we forego Iota LEDB altogether (it won't be used for
anything), and use two MAX1916 chips for our LCD and keypad backlights, with
each chip's on/off control being a Calypso GPIO.

The actual workings of the LEDB driver or switch inside the Iota chip are a
mystery.  On the one hand it appears to be nothing more than a "dumb" transistor
on/off switch, no different from an external "digital transistor" (BJT with bias
resistors) controlled by a Calypso GPIO: a resistor still seems to be required
for current control, and at least on the Pirelli DP-L10 the keypad backlight
intensity visibly varies with Vbat ranging over the Li-ion discharge range.  But
on the other hand, LEDB requires the 13 MHz clock to be running, and the light
goes out when this clock is stopped.  Why in the world would any kind of clock
be required if the circuit is only a transistor on/off switch controlled by a
static register bit?  Other parts of TI's Iota datasheet describe its LEDA, LEDB
and LEDC as "current drivers" - but in the absence of any way to actually set
the desired current without depending on Vbat or Vf variations, whatever the
Iota chip actually provides can't be anything like MAX1916.

Poorly documented, non-understood mystery hardware is best avoided, hence we are
not going to use Iota LEDB, and shall only use MAX1916 instead.  We also gain a
functional improvement over Pirelli DP-L10 by using MAX1916: our keypad
backlight intensity will remain the same over the battery discharge range.

1.6. Side buttons

In addition to the 21-button main keypad, our FC Libre Dumbphone handset will
include 3 side buttons: two on the left side, intended for volume up/down
control, and one on the right side, serving auxiliary functions.  This side
button arrangement is identical to TI's D-Sample and similar to Pirelli DP-L10:
the only difference between our arrangement (matching D-Sample) and Pirelli's
is that Pirelli moved the 3rd side button to the left and designated it as the
camera button.  However, we (FreeCalypso) have no interest in ever implementing
any kind of camera on our phones, hence we are moving the 3rd side button back
to where it was in TI's original design (on the right), and we will use it for
purposes of our own invention.

The starting point UI code we got from TI does not do anything with the right
side button (even though this button exists and works on the D-Sample platform
on which this code was originally developed), hence we have full freedom to
invent our own uses for it.  The following uses are envisioned:

* Long press of this button may be our way of turning the hands-free loudspeaker
  on and off, a function that does not exist in the starting point UI code from
  TI.

* When the phone is in its normal idle standby operation (not in a call and not
  being poked at by the user, but registered to a GSM network and ready to
  accept incoming calls or SMS), the display will be off.  Users often desire
  to check the time and other status (check coverage, see if they missed any
  calls or SMS), which will require pressing any button to turn on the display.
  At that point a 30 s timer kicks in, which will turn the display back off
  after 30 s of inactivity.  However, an argument can be made that keeping the
  display on for 30 s if the user only wanted to quickly glance at the time is
  a waste of battery.  Here is one proposed solution: we can implement a
  function where a short press of the right side button when the phone is on its
  idle screen will cause the display to turn off immediately and activate the
  keyguard.  The user can then press the right side button once to turn on the
  display and look at it, and then press the same button again to turn it back
  off.

* When we are in a long call, the LCD backlight does not turn off completely,
  instead it will go dim - but still readable.  Any button presses in this state
  are NOT swallowed - they take their regular actions.  However, the keypad
  backlight turns off fully in this state, and under certain conditions (like
  out at night) the user may not be able to see the keypad.  If a short press
  of the right side button invokes no other action besides switching on full
  display brightness and the keypad backlight, this right side button can be
  found by touch, and thus solve this particular problem case.

1.7. Audio routing

3 different audio routing modes will be supported on our FC Libre Dumbphone
handset:

* Default mode: there will be a 32 ohm earpiece speaker physically mounted in
  the usual place, on the front bezel above the display, to match up with the
  user's ear in handheld operation.  There will also be a microphone toward the
  front bottom of the phone, again in the usual place.

* Hands-free mode: there will be an 8 ohm loudspeaker physically separate from
  the 32 ohm earpiece speaker, physical location in the handset TBD.  In the
  hands-free mode, the downlink audio will be switched from the earpiece speaker
  to the loudspeaker, while the microphone input for the uplink will remain the
  same.

* There will be a wired analog headset jack with plug insertion detection; when
  a headset is inserted, both audio input and output will be redirected to this
  headset interface.

1.7.1. Earpiece and loudspeaker separation

Most current mainstream phones (in fact, all that I am familiar with) have
physically separate speaker transducers for the earpiece function (hold up to
ear to talk) and the loudspeaker+ringer function.  The earpiece speaker is a 32
ohm load, and the loudspeaker is an 8 ohm load.  In a Calypso+Iota design, an
external amplifier chip is needed to drive the 8 ohm loudspeaker, whereas the
little 32 ohm earpiece speaker can be driven directly by Iota EAR output.

However, a very different design was implemented by TI on their D-Sample and
Leonardo boards.  They have only one speaker, one of 8 ohm kind, that is
physically mounted in the position where the earpiece speaker would normally go.
In order to not overwhelm the user's ear in handheld operation, they have
peculiar circuit wiring where the analog signal from Iota to the loudspeaker
amplifier goes through different resistor values depending on whether EAR or AUX
output from Iota is used, and when the EAR output is selected, the high resistor
values produce attenuation, such that the sound pressure level produced by the
pressed-to-ear loudspeaker becomes comparable to that produced by a more
traditional 32 ohm earpiece speaker.

Furthermore, TI's single speaker design was not limited to their development
boards.  Some years ago I found schematics for some very old LG phone (called
A316 or B1200, not sure of the correct designation), this phone is from early
TI era (pre-Calypso, using Ulysse/Nausica/Clara chipset), and it has the same
arrangement as D-Sample and Leonardo.

For our own FC Libre Dumbphone, I am going with the separate speakers
architecture, using physically separate earpiece and loudspeaker transducers.
This architecture feels more native to me, and it will allow for independent
tuning of the two audio paths.  In my defense, all current mainstream phones
seem to use the same architecture - the other approach with a single loudspeaker
in the earpiece physical position seems very uncommon.

1.7.2. Loudspeaker implementation

The external amplifier chip for driving the 8 ohm loudspeaker will be TI
TPA6203A1, copied from Leonardo schematics and proven good on FCDEV3B.  On
FCDEV3B this amplifier is fed with signal from Iota EAR output, but on the final
handset and on the Venus development board this amplifier will be fed with
signal from Iota AUX output instead.

The loudspeaker amplifier has an on/off control by way of a Calypso GPIO; in
order to save battery, this amplifier needs to be off normally, and only turn on
when a loudspeaker call is in progress or when a ringtone melody is played.

1.7.3. Wired analog headset jack

The analog headset jack on our FC Libre Dumbphone handset will be of 2.5 mm
TRRS type, using pinout copied from iWOW DSK.  The headset needs to be wired as
follows:

* 32 ohm earpiece speaker connected between Tip and Ring2;
* electret condenser microphone, positive connected to Ring1;
* Sleeve is ground, should be needed only for the microphone.

The advantage of this TRRS headset specification, as opposed to the simpler kind
with a TRS plug and a common ground for the earpiece and the mic, is that our
TRRS headset can be driven with either single-ended or differential earpiece
driver outputs.  On the final handset, the wired headset interface will be
connected to the Iota headset channel (HSMICBIAS, HSMICP, HSO) and thus the
headset earpiece driver will be single-ended (HSO and GND), but the same headset
can also be plugged into other FreeCalypso devices in which the jack is wired
to the main Iota audio channel, with Iota EARP & EARN driving Tip and Ring2 on
the TRRS headset jack.

1.8. Ringtone generation

In terms of the physical sound-emitting element, there are two principal ways
in which cellphone ringing sounds can be produced:

1) The oldest and most classic way is to use a magnetic buzzer controlled by
   Calypso BU/PWT digital output.  The buzzer is driven with raw battery voltage
   being switched with a "digital transistor" (BJT with bias resistors), and the
   control input going to the base of the BJT is Calypso BU/PWT output.  This
   method is standard in older phones that don't have hands-free loudspeakers:
   since there is no loudspeaker for that other purpose, some loud noise-making
   element needs to be implemented just for ringing, and old-style buzzers are
   the traditional choice.  Motorola C1xx lower subfamilies (C11x/12x and
   C139/140) use such buzzers for ringing.

2) In phones that feature a loudspeaker for hands-free operation, the same
   loudspeaker is also used for ringtone sounding, and the buzzer is eliminated.
   Apparently hands-free loudspeakers weren't popular in the Calypso era, thus
   Pirelli DP-L10 is the only known Calypso phone that features one.  There is
   also a more bizarre possibility: some phones have replaced the ringing buzzer
   with a loudspeaker, but that speaker is used *only* for playing ringtone
   melodies - no hands-free call feature is offered.  This situation exists on
   Motorola C155/156 phones.

Furthermore, if the physical sound-emitting element is a loudspeaker and not an
old-fashioned buzzer, and if the chipset is Calypso, as opposed to various newer
chipsets, then a further distinction arises:

2a) Most historical commercial phones that are based on Calypso and use a
    loudspeaker for ringtone sounding, also contain a special ringtone generator
    chip that drives this speaker when a ringtone is played - in other words,
    their loudspeaker ringtones do NOT go through the same voice audio path that
    is used for hands-free calls, if the latter feature is offered at all.  The
    speciai ringtone generator chip is typically a combined MIDI player and
    loudspeaker driver.

2b) The much less popular approach is to not implement any extra hardware at all
    that is specifically for ringtone generation, use only the same loudspeaker
    audio path hardware that is already needed for hands-free calls (a simple
    loudspeaker amplifier), generate ringtone melodies in the Calypso DSP
    (Melody E1 or E2), and play them through the regular voice audio path,
    routed to the loudspeaker.

Approach 2b is the least popular one among historical commercial Calypso phones,
but it is the one which I (Mother Mychaela) have selected for our FC Libre
Dumbphone handset.  But let us nonetheless examine the pros and cons of
different approaches, and see why I have settled on option 2b.

Buzzer melodies (option 1) are monophonic (the signal carrying the melody to
the buzzer is a digital square wave, and there is no way to create multiple
overlapping notes in such a signal), but a decent range of tone frequencies is
available: the magnetic buzzer hardware can easily produce frequencies all the
way up to the limit of human hearing, while Calypso PWT produces musical notes
from F4 through E8 in the scientific pitch notation, or 349 to 5274 Hz.  In
contrast, any tones produced through the 8000 samples/s voice audio path have
to be below the Nyquist frequency of 4 kHz - according to TI's document, Melody
E1 notes go from E4 (330 Hz) up to G#7 or 3322 Hz.

In terms of the richness of possible ringtone melodies that can be played,
option 2a (external MIDI player chip that drives the loudspeaker directly,
without going through Calypso+Iota voice audio path) is the absolute best.
These specialized ringtone generator chips implement full MIDI (128 instruments,
47 drums, up to 64 simultaneous notes, according to one datasheet), and the
available ringtone melodies for these MIDI chips are very rich - just take a
Pirelli DP-L10 phone and listen through various ringtone melodies it offers.
All of Pirelli's melodies are stored as *.mid files in their FFS, thus we could
very easily copy them if we were to adopt a MIDI player chip similar to theirs.

However, the problem for us with adopting option 2a is that this option would
introduce significant extra complexity and adversely affect our already long-
overdue project schedule.  There is only one MIDI ringtone player chip for which
we have enough documentation to attempt such a feat: this chip is Winbond
W56964, a slightly more capable sibling of the W56940 used in the Pirelli phone.
However, just because we have what at first glance appears to be reasonably
complete documentation does not mean that it would be a slam dunk!  We would
have to build a separate test board for this chip, connect it to a Caramel2
motherboard (it needs to connect to Calypso MEMIF), and then spend significant
time climbing the learning curve and getting this chip to actually work: getting
it to play melodies, and just as important, getting it into and out of sleep
modes.  In other words, a lot of extra work and time spent just for this part,
not advancing any other project needs - whereas option 2b eliminates all of this
extra work.

Finally, a philosophical argument can be made that FreeCalypso should be all
about simplicity, producing a phone that does its job: implement just what is
needed for a functional phone, and omit unnecessary baggage.  An extra hardware
circuit (a chip connected to Calypso memory bus, no less) and associated
software complexity that serves absolutely no other purpose except to produce
ringtones that are "richer" than what the Calypso can produce on its own, and
does not assist in any way with hands-free loudspeaker operation for calls (it
is more of a hindrance in that mode), can be seen as an unwelcome burden similar
to other unwelcome burdens which we are already eliminating, like the camera.

In contrast, with our chosen option 2b, we have exactly zero extra hardware
that is just for ringing: our loudspeaker and its associated driver circuit
(simple amplifier) is primarily for hands-free calls, and the ability to use
the same audio path to play ringtone melodies comes literally "for free" with
the Melody E1 feature built into our Calypso DSP.  We already have a selection
of nice-sounding ringtone melodies in E1 format, lifted from the legendary TSM30
source, and software complexity is minimal: the melody playing engine has
already been implemented by TI, we only need to call RiViera Audio Service API
functions.

1.9. Vibrator

All traditional cellphones include a vibrator, and ours needs to include one
too.  Our firmware will need to offer the options of being silent, vibrating
only, ringing only, or ringing and vibrating on an incoming call or SMS - all
of these options are genuinely useful to a heavy-duty phone user in different
situations.

In terms of functionality, the vibrator is envisioned as a simple on/off control
in the hardware, with higher-level "pulse train" functionality implemented in
the firmware.  As far as end user experience goes, the Mother's plan is to copy
the way the vibrator works on the Pirelli DP-L10.  On this to-be-replaced or
to-be-recreated reference phone, the vibrator works as follows: when an incoming
call arrives in vibrating alert mode, the firmware turns the vibrator on for
500 ms, then turns it off for 500 ms, and the cycle endlessly repeats until the
call is either answered or dropped.  This 500 ms on/off cycling is purely a
firmware function, the hardware control is an on/off switch.

Looking at the hardware implementation of the vibrator driving circuit in the
Motorola C1xx family and in the Pirelli DP-L10, both designs support a form of
"analog" control of the vibrator beyond simple on/off.  In the Mot C1xx family
the vibrator is controlled by the output of Iota auxiliary DAC, whereas in the
Pirelli DP-L10 Calypso BU output has been repurposed to control the vibrator,
allowing either full-on or PWM driving.  However, Pirelli's firmware appears to
never operate the vibrator in any way other than fully on, and there is no
evidence of Mot C1xx firmwares applying any analog control to their vibrator
either.

The Mother's tentative plan for our FC Libre Dumbphone handset is to copy
Pirelli's approach in both hardware and firmware: repurpose Calypso BU output
for vibrator control (we won't have a buzzer, see section 1.8), allowing the
possibility of PWM, but have our firmware only use fully-on and fully-off
states, at least initially.  However, because we won't have a vibrator on our
Venus development board, only in the final handset, this decision does not have
to be made right now.

Because our firmware will be designed for a simple on/off vibrator control,
during fw development on the Venus board it will be trivial to use a LED to
simulate the vibrator on/off state.