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 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.