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, also to be used for ringing
* 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
* MP3 or any other music player
* stereo headphone output or any other beyond-voice audio
* 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 transflective: primarily reflective, but can also operate in
   transmissive mode when the optional backlight is turned on.  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.

1.10. Battery

The battery in our FC Libre Dumbphone handset will be single-cell Li-ion.  It
goes without saying that this battery will be freely removable and replaceable
by end users.  The specific size, form factor and mAh capacity of this battery
won't be addressed until later in the project, when we get closer to building
the actual handset.

Our Calypso+Iota chipset dates from the era when the cellular handset industry
was transitioning from NiMH to Li-ion batteries, and the Battery Charger
Interface (BCI) block in the Iota chip supports both battery types, or at least
TI's documentation claims so.  Given that we are going against the mainstream
society's ideas in so many other ways, I have given thought to the possibility
of using a NiMH battery instead of Li-ion.  However, the problem with using a
NiMH battery is that we would be going into completely uncharted territory
without any guidance.  In the case of Li-ion batteries the charging process is
well-understood in both theory and practice, and our FCHG logic based on reverse
engineering of Pirelli's firmware works well both on the same Pirelli and on
Motorola C1xx family.  In contrast, if we went with NiMH, we would have
absolutely no guidance in implementing the necessary charging control logic
(TI's LCC code is useless), causing a huge risk to the project.  Furthermore,
determining the state of charge from Vbat for the purpose of the bars icon is
already somewhat challenging even with Li-ion, given the relatively flat middle
part of the discharge curve - and with NiMH we can only expect the problem to be
even worse, as their discharge curve is said to be even flatter.  For these
reasons, we are going to play it safe and stick with Li-ion.

1.11. Charging circuit

Our FC Libre Dumbphone will feature a USB port (mini-B, device role only, no
OTG) that combines two logically separate functions: battery charging and
computer interface.  The basic idea of this dual-function USB port comes from
Pirelli DP-L10, but we are applying significant refinements of our own to this
general idea, as the following description will make clear.  This section
describes the charging function; the computer interface function is described
in section 1.12.

One highly non-standard innovation that will appear on our FC handset will be a
user-visible mechanical slide switch that will turn the charging circuit on or
off.  The purpose of this charging on/off switch is to make it possible to
connect USB and have the two ttyUSB devices appear (see section 1.12) without
presenting a 'charger plug' boot condition to the Calypso+Iota core chipset.
From an end user perspective, if you only use the USB port for charging and
don't care about the computer interface function, then leave the charging switch
always on - USB plug/unplug will mean charger plug/unplug like on any
conventional phone.  Similarly, if you do use the computer interface function to
connect your phone to a host computer in regular operation, with the firmware
up and running normally, but you don't mind having the phone also charge from
your computer every time you connect USB, then likewise leave the charging
switch always on.  However, if you are going to reflash phone firmware or do
other advanced manipulations using the computer interface, then you will need
to turn the charging switch off.  With the switch off, the USB port becomes a
computer interface only, without charging.

Past the switch, the battery charging circuit using USB +5V as the charging
power source will be the most classic one depicted in Figure 4-10 in the Iota
chip datasheet (TWL3025_SWRS021.pdf), same as in Pirelli DP-L10 and Motorola
C1xx phones.  Presentation of USB +5V to Iota VCHG terminal past the charging
on/off switch is what will cause the chipset to boot in the 'charger plug' mode,
or to activate charging functions in the firmware if the phone is already on.

1.12. Computer interface

Our Calypso chip has no native USB, instead the host computer interface of all
Calypso-based systems consists of two UARTs.  On our development boards starting
with FCDEV3B, we got used to interfacing to both of these UARTs by way of
FT2232x adapters, a USB to serial adapter that goes from one USB device to two
UARTs, presenting two ttyUSB devices to a Linux host.  For low-level operations
like flash programming, having just one Calypso UART is sufficient (either of
the two), but once our regular firmware is up and running, then having both
Calypso UARTs gives maximum user empowerment: Modem UART carries a classic AT
command interface complete with CSD, GPRS and GSM 07.10 MUX capabilities, while
the other UART (IrDA) carries TI's RVTMUX debug and development interface.

Before arriving at our current radical approach with the charging on/off switch,
for many years previously I was considering a more conservative approach.  My
original idea was to bring out the two Calypso UARTs in very different ways: my
thought was to bring only the Modem UART to the built-in USB port (by way of a
built-in single-channel USB-serial chip), and have plugged-in USB always present
VCHG to the chipset, but route the debug UART (the one most useful in low-level
development and bring-up) to a special FPC connector that would interface to a
special debug board, just like Openmoko did on their Neo.  Serious development
work would then require having that debug board attached, while more casual
users would be able to talk AT commands to the phone via the built-in USB port,
charging the battery at the same time.

What made me change my mind about this design was the realization that I, as the
most principal user and developer, would end up wanting to have the debug board
attached all the time, and the need to have it hanging externally, or perhaps
glued or taped to the back of the phone, would be a huge blemish and
inconvenience.  Back in the days of Openmoko, someone must have had a similar
experience, as I remember reading about a hack where someone built a debug board
functional equivalent that fits inside the Neo, in some otherwise unused space.

Hence the new design for our planned FC Libre Dumbphone handset: the USB port
will have a built-in FT2232D (or perhaps FT2232H) subsystem (USB to two UARTs)
connected to it, interfacing to both Calypso UARTs, while the charging on/off
switch will make it possible to use this interface for low-level development
and bring-up without presenting VCHG to the chipset.  In this architecture this
FT2232x subsystem should be considered the primary "owner" of the handset's USB
port, while the charging function is secondary and optional, enabled or disabled
with a switch.  To put it another way, if our USB port is connected to a regular
USB host (as opposed to a Dedicated Charging Port power-only source), that USB
host will always enumerate the FT2232x and see two ttyUSB devices, whereas
charging may or may not take place depending on the switch setting.

1.12.1. Set of UART signals

The set of signals to be connected between Calypso and FT2232x for the Modem
UART is almost complete:

USB UART
DTE signal	Calypso signal
------------------------------
TxD		RX_MODEM
RxD		TX_MODEM
RTS		CTS_MODEM
CTS		RTS_MODEM
DTR		GPIO3
DCD		GPIO2
RI		GPIO8

Only DSR is omitted for the Modem UART channel, all others are included.  The
second debug UART channel is only two wires:

USB UART
DTE signal	Calypso signal
------------------------------
TxD2		RX_IRDA
RxD2		TX_IRDA

However, as shown in the next section, these signals cannot be simply connected
between Calypso and FT2232x, instead a more complicated scheme needs to be
implemented.

1.12.2. USB and mobile power domains

Our FC Libre Dumbphone handset will have two principal power domains in it: the
main battery-powered mobile domain, and the USB domain.  This power domain
situation presents some very significant challenges, a problem generally
referred to as "partial power-down".  There are two PPD scenarios to be
concerned about:

1) In normal operation the phone is mobile and not connected to USB.  In this
   state the mobile power domain is on, whereas USB-powered circuits in the
   FT2232x subsystem have no power.  The two challenges in this state are:

1a) We need to ensure that no currents flow from the powered-on mobile domain
    into powered-down USB domain circuits, as any such currents would be an
    unacceptable drain on the battery.

1b) Calypso UART inputs that come from the USB domain when the latter is active
    need to have defined logic levels on them when the USB domain has no power:
    no floating, no mid-way levels that would cause higher currents in CMOS
    input structures, and furthermore, some Calypso inputs need to be high in
    this state, while others need to be low.

2) A reverse PPD scenario occurs when the USB domain has power, but the
   Calypso+Iota chipset is in its switched-off state per Iota VRPC.  This
   scenario can occur when the charging switch is set to off, or when the
   battery is critically low and undergoing precharge.  The main concern in
   this state is to avoid feeding power from the USB domain into the Calypso
   chipset's V-IO rail - our experience on Caramel2 boards conclusively
   demonstrates that Calypso does not like this condition and can behave oddly,
   erratically feeding current into its outputs that are supposed to be low or
   Hi-Z, and thereby erratically turning on various peripherals.

If we were to naively connect our UART signals between Calypso and FT2232x, the
result would be bad: all of the above concerns would be violated.  Instead we
need to insert carefully designed isolating buffer circuits in both directions.

1.12.2.1. Calypso to FT2232x signal direction

If these signals were connected directly, significant current (in the mA range)
would flow from Calypso outputs into powered-down FT2232x inputs, which is not
acceptable.  Our solution is to insert an LVC buffer (probably 74LVC541A, for
the 5 signals that are needed) between Calypso outputs and FT2232x inputs, with
the buffer powered from USB domain 3.3V supply.  With mobile on and USB power
absent, the LVC buffer's Ioff spec will apply, which is listed in Nexperia's
74LVC541A datasheet as 0.1 uA typical, 10 uA maximum.

An unfortunate consequence of this design is that in the opposite PPD scenario
(USB connected to a host, charging switch off, mobile chipset in its off state)
the inputs to the LVC buffer will float, with FT2232x inputs receiving garbage
as a result.  Adding pull-up resistors to a USB-domain supply would cause other
problems, hence the Mother's position is that we'll just live with a few
floating inputs in this particular condition - and it is a condition that
should not persist for extended lengths of time.  There is also a software
consideration stemming from this floating input situation: when you are doing
low-level programming and development operations in this state, don't open the
Modem UART ttyUSB device, and only operate via the other debug UART.  The latter
is a 2-wire UART without any flow control or modem control signals, hence there
will be less bogosity for the Linux host to see in this state.

1.12.2.2. FT2232x to Calypso signal direction

This direction is even more difficult, and we will need to insert two chained
LVC buffers: the signals will first pass through an LVC buffer powered from the
USB domain, and then through another LVC buffer powered from the Calypso+Iota
chipset's V-IO rail.  There will be pull resistors inserted between the two
buffers: either pull-up to VBAT (raw battery positive rail) or pull-down to GND,
depending on the needed signal sense.

The LVC buffer powered from Calypso V-IO is needed in order to prevent current
feeding into Calypso when the mobile is switched off - the buffer's Ioff spec
will apply.  Pull-up and pull-down resistors in front of this buffer are needed
so that Calypso inputs will receive the desired states when no USB host is
connected.  Pull-ups are being made to VBAT instead of V-IO to eliminate the
possibility of current feeding into V-IO through these resistors.  (Feeding
from 3.3V logic signals into the battery can't happen when the battery is above
3.3 V, and if the battery is below 3.3 V, then we are only adding a little to
the precharge current.)

The other LVC buffer (the one powered from USB-domain 3.3V) is needed because
in the absence of this buffer, current will flow through pull-up resistors and
into powered-down FT2232x output pins, the resulting pull-down resistance will
be lower than the pull-up, and the next buffer won't receive the desired logic
level, not to mention unwanted current flowing.  With the other LVC buffer
added, that buffer's Ioff spec will apply.

The value of pull-up resistors to VBAT will be 22 kOhm.  With maximum 15 uA
current flowing through each resistor (worst-case Ioff of one buffer plus
worst-case Ii of the other buffer), the maximum voltage drop on the 22 kOhm
resistor will be 330 mV.  In order for the LVC buffer's input structure to not
draw extra current, the input voltage needs to be 2.8 V or higher - thus with
22 kOhm resistors we'll keep satisfying this condition until the battery falls
to about 3.1 V, which is below the operational range for switched-on mobile.

One downside of having pull-ups to VBAT (which can be as high as 4.2 V) on
signals that are output from a 3.3V-powered buffer is that when the buffer
output is high, there may be current flowing into that high output (not sourcing
out of it as normally expected), which is a bad condition for CMOS outputs.
However, this current will be limited to a maximum of about 40 uA
((4.2-3.3 V) / 22 kOhm), and my feeling is that such small current won't hurt
Nexperia LVC buffers.

1.12.2.2.1. Signal pull-up/down directions

Of the 4 UART signals going from FT2232x to Calypso (see section 1.12.1), TxD
and TxD2 MUST be sensed high by Calypso when no USB host is connected, hence
they will need the two chained LVC buffers with pull-ups to VBAT in between, as
described above.  RTS and DTR are less critical in that either high or low level
would be acceptable, as long as it is stable and not floating.  However, it is
slightly preferable to have DTR pulled up like TxD (to be sensed as logically
negated), and to have RTS (flow control signal going to CTS_MODEM) pulled down,
to be sensed as logically asserted.

The approach chosen by the Mother is to have TxD, TxD2 and DTR pulled up to VBAT
as described above, and to have RTS pulled down to GND.  The value of the pull-
down resistor to GND will be 47 kOhm, and the USB-side-powered LVC buffer can be
skipped for this signal - that buffer is only needed in order to work correctly
with the pull-up to VBAT.

With only 3 FT2232x-to-Calypso signals needing to go through a USB-side-powered
LVC buffer, and with 3 slots remaining available in the 74LVC541A buffer from
section 1.12.2.1, that one 74LVC541A IC can serve both signal directions (5
signals from Calypso to FT2232x and 3 signals going the other way), reducing the
component count.

1.12.3. Boot control by USB host

Our DUART28C adapter (DUART28 hardware, EEPROM in the 'C' configuration) has a
nifty feature in the form of CTL1 and CTL2 open drain outputs, intended for
triggering Iota VRPC boot control signals on Calypso devices, i.e., boot control
signals from the {PWON, RPWON, nTESTRESET} set.  So far none of our FreeCalypso
development boards bring out RPWON, but both FCDEV3B and Caramel2 feature PWON
and nTESTRESET controls, and we have an established convention for driving them
with CTL1 and CTL2 from a DUART28C.  The end effect for the developer-operator
is that one can run operations based on Calypso boot ROM loading path (fc-iram,
fc-loadtool etc) purely from the host command line, without needing to press any
buttons on the development board: adding -Prts to the command line is equivalent
to pressing PWON, or adding -Pdtr is equivalent to pressing RESET.  rvinterf can
also be run with the same options, allowing flashed firmware to be booted in a
similar no-buttons-needed manner.

It is the Mother's intent to replicate this boot control feature on our FC Libre
Dumbphone handset as well, i.e., make FT2232x Channel B RTS and DTR outputs
(otherwise unused) act as host-driven boot control triggers.  In hardware terms,
this addition consists of just one tiny IC (74LVC2G07) and two pull-up resistors
on the BDBUS[24] lines from FT2232x to this OD buffer.  FT2232x EEPROM will be
programmed with the same custom USB ID as DUART28C, and the Linux kernel
ftdi_sio driver will need to have our DUART28C support patch added to it.

There will be one change from our previous convention, however: the OD buffer
output controlled with Channel B RTS will be wired to RPWON rather than PWON;
the other OD buffer output controlled with Channel B DTR will still be wired to
nTESTRESET like before.  The reason for this change is that our handset firmware
has more complex logic that treats different boot causes differently (as
required for standard expected handset functionality), and Iota PWON is now
reserved solely for the end user power-on button.  Host-commanded boot needs to
be different from this end user power-on button (no long press is required, and
the firmware should enter its misc boot state that behaves like an ACI build),
hence we are changing the wiring so that -Prts will trigger RPWON rather than
PWON.  The same boot effect can still be achieved with -Pdtr triggering
nTESTRESET, but it is a bigger hammer (reset of RTC can be unwanted), hence
-Prts will be recommended as the gentler option, leaving -Pdtr for times when
recovery from runaway code is needed.

2. FC handset firmware functional scope specification

FreeCalypso handset firmware will always run (perhaps with subset functionality)
on more hardware targets than just our main-goal FC Libre Dumbphone handset.  It
already does: our firmware currently runs on our Luna development platform, and
prior to FC it ran on TI's original D-Sample platform.  A very restricted
functional subset also runs on Motorola C139 hardware.

If we consider only the main goal of FC Libre Dumbphone handset, then our
firmware evolution can be seen as strictly linear: we start with what we got
from TI, and we morph it toward what will be needed to operate our handset,
adding functionality and peripheral support which we need for our FC handset,
but which is not present in the starting point code from TI.  However, we also
have side-branch functionality: at times when the code from TI supports
something which we don't need for our own FC handset, but which may be useful
for alien hardware targets, a moral imperative can be made for keeping and at
least minimally maintaining that functionality as a kind of side-branch feature,
a permitted configuration that is not needed for our own FC handset but needed
for others.  Similarly, when we add support for entirely new peripherals that
are planned for our FC handset (such as the loudspeaker), we should make the
firmware change in such a way that targets without the extra feature can still
be supported.  Finally, when we are changing the firmware in ways that
significantly depart from TI's original, it may sometimes be prudent to preserve
TI's original way as a lorekeeping option.

The following sections will spell out what we support and what we don't support
in FreeCalypso handset firmware, and how these scoping decisions relate to our
starting point from TI, to our main goal of FC Libre Dumbphone handset, and to
secondary objectives of alien target support and lorekeeping.

2.1. Display support

2.1.1. Support for different display sizes

By the very nature of the problem, any phone handset UI design will always be
quite specific to a particular display size in pixels, and also to the display
type as in color or black&white.  The starting point code we got from TI
supports 3 different UI configurations in terms of size and coloration:

* 176x220 pixel, 16-bit color;
* 176x220 pixel B&W;
* 84x48 pixel B&W.

In FreeCalypso we have made two changes to this set of possible UI
configurations:

1) The large (176x220 pixel) B&W option has been removed.  In TI's delivery this
   option was nothing more than a quick&dirty hack to extend their small (84x48
   pixel) B&W UI to the large D-Sample screen, and this configuration offers
   nothing useful - any real display of such large size will always be color.

2) The small B&W configuration has been extended from 84x48 to 96x64 pixels.
   Why 96x64?  Because it is the size in pixels of Motorola C139 LCD, and it is
   the smallest LCD size found among those alien Calypso phones whose existence
   is known to us and for which we have at least minimal support.  Extending
   this UI configuration from 84x48 to 96x64 pixels was an easy change because
   it is an increase in screen real estate (not a decrease), and it is a fairly
   small increment, such that UI design choices which were sensible for an 84x48
   pixel display are still sensible for 96x64.

The main principal difference between our approach in FreeCalypso and what a
conventional commercial phone manufacturer would have done is that we are
retaining TI's smallbw configuration and keeping it supported, as opposed to
disregarding it and working only on the bigcolor UI config for our own planned
hardware product.  We keep this smallbw UI configuration around, in the extended
96x64 pixel size, for two reasons:

1) Lorekeeping: unlike TI's 176x220 pixel B&W config that was totally
   uninteresting, TI's old smallbw UI (from the days of C-Sample) is
   sufficiently interesting and unique (and naturally quite different from the
   bigcolor version) to be worth preserving.

2) By keeping this configuration around (not discarding it and not allowing it
   to bitrot beyond repair), we keep the door open for the possibility of a
   minimally usable FreeCalypso Lite aftermarket firmware for Motorola C139.

Both UI configurations can be built for our current Luna platform, and both of
them display on our Luna LCD.  The virtual framebuffer of 96x64 pix B&W in the
smallbw config is displayed in the center of our physical 176x220 pixel color
LCD, surrounded by a pale magenta border.  The same ability to run both configs
will continue on our next development board (Venus).

2.1.2. Backlight readability paradigm

(See theoretical background in section 1.4.3.)

Our actively maintained FC handset firmware has been paradigmatically redesigned
to assume a display which is NOT readable without the backlight.  Our logical
primitives with respect to display control are display on/off, rather than
backlight on/off, and we swallow the initial keypress that turns on the display.

This change is a significant departure from TI's original.  The LCD on TI's
D-Sample is transflective, and when the backlight is off, the display remains
readable in ambient light.  It is certainly better in this regard than Motorola
C139 LCD.  And if we go back further in TI's history to C-Sample and earlier,
those 84x48 pixel B&W LCDs were the traditional mostly-reflective type,
perfectly readable without the backlight.

This area is one where we are NOT retaining TI's original way as an option in
our actively maintained firmware.  The difference between the two principal
paradigms is too great, and we don't have any active-demand prospective targets
with B&W displays of the old traditional kind.

2.2. Keypad assumptions

The keypad arrangement on our FC handset (see sections 1.5 and 1.6) will be
exactly the same as on TI's D-Sample, thus no principal changes to the firmware
are needed in this regard.  Furthermore, the same 21-button keypad exists on
Motorola C1xx phones, thus no firmware design variations are needed in this
regard for secondary target support.

The only issue of concern is that the 3 side buttons which exist on D-Sample and
Pirelli DP-L10 and will also exist on our FC handset don't exist on Mot C1xx.
Our starting point code from TI does not do anything with these buttons (even
though it was developed on the D-Sample platform where they exist), but when we
do get around to adding support for these side buttons, we will need to take
some extra care in preserving flexibility:

* The original code from TI uses navigation up/down buttons for volume control,
  for both ringer and earpiece volume.  We are going to change the code to drive
  these volume controls with side buttons instead (dedicated volume up/down
  buttons), but when we make this change, we'll need to provide an option of
  restoring the old way for less button-equipped phones like Mot C1xx.

* Whatever functions we assign to the right side button, all of them will be
  our own inventions, as none exist in TI's original code.  However, this right
  side button does not exist on Mot C1xx.  The Mother's idea is to assign the
  right side button to loudspeaker on/off control - this arrangement will work
  well as the same C1xx phones that lack this button also lack the hands-free
  loudspeaker.

2.2.1. No support for 18-button main keypads

Prior to D-Sample, TI's C-Sample and earlier boards had keypads with fewer
buttons, 18 instead of 21, and no side buttons.  The difference between the
C-Sample 18-button main keypad and the 21-button one found on D-Sample, Pirelli
DP-L10 and Motorola C1xx is that the older 18-button keypad has only up and down
navigation buttons in the place where the 21-button version has a 5-way
navigation button group.  In other words, navigation left, right and center keys
don't exist on the 18-button version.

TI's demo/prototype/PoC UI code was originally developed on C-Sample or perhaps
even earlier, thus it was originally designed for the 18-button keypad
arrangement.  For this reason, the code currently makes very little use of
navigation left, right and center keys.  However, some limited use is already
being made of these extra keys (primarily on text and number entry screens, aka
the editor), and our use of all available keys in the UI will keep growing.  As
a matter of project scope, we are NOT supporting backward compatibility with
18-button keypads, given that the lowest-end Mot C1xx family already has
21-button keypads.

2.3. Audio routing

TI's demo/prototype/PoC UI code from TCS211 does not use the audio mode facility
of the RiViera Audio Service: ABB configuration remains the default set in L1
initialization, volume control is done by calling audio_SetAmplf() in the Condat
abstraction layer, which in turn calls ABB_DlVolume().  This design will need to
change in FreeCalypso: we will start using the RiViera Audio Service audio mode
facility, and the use of this facility (including correct audio mode
configuration files under /aud in FFS) will become mandatory on all targets.

The following 3 audio modes are defined for call audio routing and idle
operation (keyclicks etc), as opposed to Melody E1 ringing covered in section
2.4.2:

Mode name	Used for
------------------------
handheld	Default handheld operation and idle state
handfree	Calls in hands-free loudspeaker mode
headset		When a wired analog headset is plugged in

At the minimum, valid /aud/handheld.{cfg,vol} files will need to be created in
FFS on every supported target; other modes can be omitted if they can't be
entered.  /aud/*.vol files maintained by RiViera Audio Service will serve as the
non-volatile volume setting store for each mode.

2.3.1. Loudspeaker inclusion or omission

The Mother's plan is to use a long press of the right side button as the command
for entering or exiting hands-free loudspeaker mode; by this design, if this
right side button does not exist on a given target, then loudspeaker mode cannot
be entered.  Furthermore, our code supporting hands-free loudspeaker mode can be
limited to just bigcolor configuration (conditionalize on LSCREEN preprocessor
symbol), further excluding this mode from ports to alien targets like Mot C1xx
and Pirelli DP-L10.

2.3.2. Headset inclusion or omission

The code supporting wired headset mode will always be included in the firmware,
however, there will be a hardware driver function call to inquire if a headset
is inserted or not.  If the wired headset jack does not exist on a given target,
or more practically if it exists but we don't support it, this headset status
function will always return "no headset" indication, and the headset mode will
never be entered.

2.4. Ringtone generation

See section 1.8 for an overview of possible ways in which ringtone generation
may be accomplished.  The only ring sound generation method supported by TI's
TCS211 version of their demo/prototype/PoC phone UI (the version for Calypso,
as opposed to other chipsets) is the original Calypso buzzer, i.e., Calypso
digital waveform output intended for switching a magnetic buzzer.  The code that
rings this buzzer will execute successfully on every Calypso target, regardless
of whether it actually has a magnetic buzzer or not: if there is no buzzer and
Calypso BU/PWT output is left unconnected, like it is on our Luna platform, the
code will still run and emit the intended tone waveform on BU, but this output
will go nowhere and no audible sound will be made.

As a matter of project scope, in our FreeCalypso handset firmware we shall
support two configurations with regard to ringing:

1) TI's original buzzer configuration will be retained for lorekeeping and to
   keep the door open for the possibility of a minimally usable FreeCalypso Lite
   aftermarket firmware for Motorola C139.

2) For our own FC Libre Dumbphone handset, we will need to implement ringing by
   way of the same loudspeaker that will be used for hands-free calls, using the
   Melody E1 feature of Calypso DSP for ringtone melody generation.

2.4.1. Scope limitation on buzzer melodies

Because the option of ringing via Calypso buzzer output is retained only for
lorekeeping and for minimal-support alien targets, no effort will be expended
toward playing more musical melodies via the buzzer.  Our current code (bugfixed
from TI's original) implements just one buzzer ringing sound, consisting of
alternating 800 Hz and 900 Hz tones, using BU mode rather than PWT, and the
Mother currently has no plans to implement anything more for the buzzer
configuration.

2.4.2. Melody E1 ringer

Our Melody E1 ringer implementation will require melody files in FFS, and we
will also have a separate audio mode (in the RiViera Audio Service sense) that
will be loaded during ringing.  Even though the same physical loudspeaker will
be used for both hands-free calls and ringing, logically the two are separate
modes, and they will be treated as separate for the Audio Service.  Separate
logical modes will provide separate volume files, which is the correct approach:
loudspeaker volume and ringing volume should be separate, just like how ringing
volume is entirely separate when a buzzer is used.

2.5. Vibrating alert

Our FC handset firmware will support both ringing and vibrating alert modes (as
well as a ring+vibrate mode) on all targets.  The vibrator will be modeled as a
simple on/off control (no "analog" control of different vibration intensity
levels, at least initially), and the vibrating alert code path will ultimately
boil down to a driver function call for vibrator on/off.  Therefore, if the
vibrator does not exist on a given target, or if it exists but we don't know how
to operate it, the on/off control function can be empty on that target, and the
firmware will "vibrate" virtually.

On development boards such as FC Venus, the vibrator on/off function can turn a
LED on and off to provide an indication of the UI layers making a vibrating
alert.

3. Venus development board

As of the summer of 2021, FreeCalypso handset development has reached a point
where a new development board is desired, to take the place of our current Luna
development platform.  The newly planned FreeCalypso development board is
codenamed Venus, and it is envisioned as serving two goals:

1) Many of the hardware features intended for the ultimate FC handset product
   as described in Chapter 1 can be prototyped on this Venus board;

2) The board will serve as the ideal firmware development platform, covering all
   features and options that are listed in the previous chapter and defined as
   being in scope for FC handset firmware.

The following sections spell out the design specification for this Venus
development board.

3.1. Build principle

The board will be built in the "hard" way, with the Calypso+Iota+RF chipset
implemented directly on the Venus board itself, as opposed to using a Tango
(iWOW TR-800) module.  This approach is necessary because we need some Calypso
and Iota signals that are not brought out on TR-800:

1) We need Iota HSMICBIAS, HSMICP and HSO signals (the 3rd audio channel) in
   addition to the primary and secondary audio channels, in order to prototype
   section 1.7 hardware for the real handset, and in order to provide a proper
   firmware development platform for section 2.3.

2) We need Calypso BU/PWT output so we can implement an old-fashioned buzzer,
   which we need in order to develop and maintain firmware per section 2.4,
   supporting both buzzer and Melody E1 ringing.

Once we have accepted that we have to bite the bullet and build our Venus board
in the "hard" way, we can also implement some other nice-to-have functions that
would have been deemed non-essential otherwise:

* We can bring out Calypso JTAG (which is not brought out on TR-800) like we did
  on FCDEV3B.  In the Mother's experience there is very little actual need for
  Calypso JTAG, but it would be improper to omit this interface on a development
  board when bringing it out is possible.

* With access to the internal ON_nOFF signal, we can implement a reliable
  chipset-ON LED indicator, also like we did on FCDEV3B.

* We can implement both LPG and PWL LEDs like on the original D-Sample.  Neither
  LED is strictly needed for the handset firmware functional scope or for
  prototyping toward the final handset; at least one LED is desired for the
  purpose of indicating virtual vibrator on/off state, but similarly to other
  considerations, it would be improper to pass up the opportunity to implement
  both LEDs.

* Mostly unrelated to the handset project, falling instead into the realm of
  general Calypso chipset knowledge recovery, I have wanted for a long time to
  sniff the internal chip-to-chip VSP interface between Calypso and Iota - but
  such feat cannot be accomplished on any currently existing hardware, as it's
  an internal interface going from one BGA to another on PCB inner layers.  If
  we are building a new Calypso development board for other purposes, it would
  be nifty to throw in a VSP tap header as well.

3.2. Purpose and scope

Aside from the logically unrelated VSP tap feature, our Venus board will be
intended for handset firmware development and handset hardware prototyping only.
It is not intended for non-handset directions of interest - for other interests
and purposes, use Caramel2 or FCDEV3B.

Calypso MCSI will not be available on FC Venus - in handset applications MCSI
pins are switched into GPIO mode, and we'll be using these GPIOs for LCD
backlight control on both Venus and the final handset.  (Our current Luna
platform is likewise.)  If you need MCSI, then you are doing modem work, not
handset, so use Caramel2 or FCDEV3B.

3.3. RF bands and PCB layout

The Mother's intent for the Venus board is to stop copying Openmoko's triband
PCB layout and instead switch to TI's original Leonardo+ quadband layout, which
has been recovered from iWOW TR-800 via professional PCB reverse engineering.
We will need quadband RF for the final FC Libre Dumbphone handset, thus it would
be best to switch to it now, starting with Venus.

3.4. Power supply arrangement

FC Venus will have the same orange Weidmuller power input connector as previous
TI and FreeCalypso development boards C-Sample, D-Sample, Leonardo, FCDEV3B and
Caramel2.  Ready-made VBAT needs to be provided via this connector, fed directly
to the core chipset and to VBAT-powered peripherals, no on-board power
conversion.  During development, operation with an AC-mains-powered fixed 3.6 V
DC supply is generally much more convenient than a real battery.

For development and testing of handset battery management in the firmware, and
for exercising the charging boot path in particular, Iota VCHG needs to be
brought out like it is on iWOW DSK and FC Caramel2 boards, to be connected with
a jumper wire to +5V pin on the DUART28 USB adapter whenever a "charger plugged"
condition needs to be presented to the chipset.  FC Venus will feature a 2x4 pin
header with Iota BCI signals like on Caramel2:

ICTL	VCCS
PCHG	VCHG
ADIN2	ADIN1
GND	GND

The Mother's approach to development and testing of higher-level UI functions
dealing with battery management is to use the BSIM feature of our FCHG driver,
in which case the board remains powered from a fixed DC supply (no actual
battery) and only VCHG needs to be connected.  However, if a need arises to
connect an actual battery and an actual Iota-controlled charging circuit, it
will be possible: the battery will need to be connected to the orange power
input connector, and the control signals for the charging circuit will need to
be connected to the 2x4 header.

3.5. LCD module and backlight

It is the Mother's desire to finalize the selection of LCD module for the actual
handset before embarking on the detailed design (as in schematics, BOM and
layout) of FC Venus, and to implement the final LCD and the final backlight
circuit on the Venus board.

3.6. Keypad buttons

The complex mechanical arrangement of keypad buttons that will be needed for the
real handset will NOT be done on the Venus board.  Instead there will be a
simple 5x5 matrix of buttons in rows and columns, with silk screen labels
indicating the function of each button, matching D-Sample - the same arrangement
as on our current Luna platform.  There will also be 3 out-of-matrix buttons for
PWON, RPWON and RESET.

There will be no keypad backlight on the Venus board.  This secondary backlight
is not needed for firmware development, as it is not managed separately in our
fw architecture - instead its control will be absorbed into our R2D BLRR control
mechanism on the final handset where this backlight will be added.

3.7. Audio interfaces

Corresponding to the 3 audio channels of section 1.7, there will be 3 analog
audio interfaces on FC Venus: two TRRS jacks and one 2-pin header.  These audio
interfaces will be as follows:

* The main audio channel (the one that will go to the built-in earpiece speaker
  and mic in the real handset) will be wired to a TRRS jack exactly like on
  Caramel2.

* The "official" headset channel (the one that will be a jack in the final
  handset) will be wired to another identical TRRS jack.  This other jack will
  need plug insertion detection, signaled to a Calypso GPIO input.

* The output of the loudspeaker amplifier (see section 1,7.2) will be wired to
  a 2-pin header exactly like on FCDEV3B, allowing the same 8 ohm lab bench
  loudspeaker to be connected.

3.8. Magnetic buzzer

There will be a magnetic buzzer implemented directly on the Venus board itself
(not an externally attached component), exactly like on TI's D-Sample board.
This buzzer will be controlled by Calypso BU/PWT output in the canonical manner,
allowing the expected sounds to actually emanate when firmware operates the
old-fashioned Calypso buzzer output.  See section 2.4 for the purpose of this
hardware provision.

3.9. LEDs instead of vibrator

There will be no vibrator on FC Venus - it is a mechanical function which cannot
be sensibly implemented on a development board meant for use on a lab bench.
Instead our Venus board will feature both LPG and PWL LEDs (i.e., LEDs
controlled by the respective Calypso outputs) exactly like D-Sample, and either
of these LEDs can be used to simulate vibrator on/off state.

3.10. Host computer interface

The host interface model on FC Venus will need to follow that of section 1.12.
More specifically, our Venus board will implement the mobile side of the "wall"
between USB and mobile power domains, complete with all provisions of section
1.12.2 for the mobile side, whereas the USB domain is already implemented on our
DUART28 adapter board.  The two domains will be interconnected with a ribbon
cable in the FC Venus lab bench setup.  The 10-pin DUART header will have our
standardized FreeCalypso DUART pinout.

Also following the principal design of section 1.12.3, there will be a 3-pin
header on the Venus board bringing out RPWON, nTESTRESET and GND, to be
connected to the boot control header on DUART28C.