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

The purpose of this document is multifold:

* Chapter 1 gives the principal design specification for the FreeCalypso Libre
  Dumbphone handset hardware which I, Mother Mychaela, seek to build as a
  distant long-term goal.

* Chapter 2 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.

* Chapter 3 gives the principal design specification for FreeCalypso Venus
  development board, which is a more near-term piece of hardware I seek to
  build, nearer than the long-term goal of Chapter 1.

* Chapter 4 explains the side project of FreeCalypso Lite aftermarket firmware
  on Motorola C139 hardware.

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

Over the summer of 2021 we have selected Formike KWH020ST23-F01 as our LCD
module for FreeCalypso; in prior years we had evaluated two other LCD modules
from HaoRan and Startek.  All relevant datasheets (our finally chosen LCD
module, our previous candidate LCD modules and the controller ICs inside these
modules) are collected here:

ftp://ftp.freecalypso.org/pub/embedded/LCDs/

Our LCD module selection criteria were as follows:

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

Formike KWH020ST23-F01 is an LCD module that was discovered by Mother Mychaela
in May-June of 2021, and it satisfies all of our requirements.  In June of 2021
we received sample pieces, then we designed a test board for the purpose of
evaluating this new LCD, connecting it to our Luna interface from 2020.  Our
lunalcd2 test board was finally assembled in August, all tests passed, and in
September of 2021 we have bought 100 pcs of this finally chosen LCD module.
This stash of 100 LCD modules is expected to be sufficient as a lifetime buy.

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.

In terms of absolute requirements, 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 strict need
to provide different configurable backlight levels - but it so happens that our
implementation will allow a total of 4 different backlight intensity levels -
see section 1.4.4.1.

1.4.4. Backlight circuit implementation

In all candidate TFT LCD modules that have been 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
both Formike and HaoRan LCD modules) 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_min, where
Vds_min 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_min, 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 74LVC2G126 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.  There will also be a third
resistor connected between MAX1916 SET pin and the V-IO rail.

The values of the 3 just-described resistors will be selected so that the path
through each SET resistor will add a different contribution to the total LED
current.  The always-on SET resistor will provide the smallest current
corresponding to the long-call dimmed mode, whereas the sum of all 3
contribution currents will equal the 15 mA limit - the current is reckoned per
LED.  The difference between the 15 mA maximum and the small dimmed mode current
will be split unequally between the two switched SET resistors, allowing a total
of 4 different backlight intensity levels to be selected via the two Calypso
GPIO outputs going to the 74LVC2G126 buffer's output enable inputs.  The actual
currents will be determined after some further experimentation with our lunalcd2
test setup: this setup features our KWH020ST23-F01 LCD, a MAX1916-based
backlight circuit, and a DIP switch pack selecting the LED current in 1 mA
increments.

74LVC2G126 has been chosen as the dual tristate buffer part instead of more
common 74LVC2G125 because the '126 has active-high output enable inputs, making
the software interface (bits in the GPIO output register) more intuitive: with
a '126 buffer, writing 1 into GPIO11 or GPIO12 will turn on the corresponding
current contribution, whereas a '125 buffer would produce an inverted sense.
74LVC2G126GT parts were less readily available than the '125 counterpart, but
we have now made a lifetime buy of the preferred part.

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 4
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 not-so-current and not-
so-mainstream Pirelli DP-L10 also features the same arrangement.  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, and so does the Pirelli phone that serves as
my personal reference - 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.  It is a
"dumb" loudspeaker amplifier, as opposed to a much more complex chip that
combines the loudspeaker amplifier function with a MIDI ringtone player - see
section 1.8.  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.

We already have an official FreeCalypso headset with a TRRS plug and BTL-wired
earpiece speaker as described above: it is called FC-HDS4, it was custom-made
for us by a professional headset manufacturer company, and we have made 100 pcs
at the time of our initial order in the fall of 2021 - this quantity is expected
to be a lifetime supply for us.

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
    special 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.  (2021-09 update: we are now looking at using Panasonic
NCR18650B as our canonical battery on the Venus board, but we are not yet
committing to anything for 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.  Here are some of the difficulties that would arise with
a NiMH battery:

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

2) When TI designed their canonical battery charging circuit to be controlled
   via Iota BCI, they assumed a charging power source that puts out somewhere
   between 6 and 7 V, not 5.0 V - those were the days before USB charging.  For
   Li-ion batteries charging at around 500 mA, a USB +5V charging power source
   is good enough, as proven by Pirelli DP-L10.  However, this lower charging
   voltage may not be enough for NiMH - consider the note in the Iota chip
   datasheet (TWL3025_SWRS021.pdf) that reads "Ni-MH/Ni-Cd 3-cell battery
   voltage can reach 5.5 V at the end of a charge cycle."

3) 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.10.1. Battery ID resistors or thermistors

In all classic dumbphones from the era which we seek to revive (the ones with
user-removable batteries), the battery pack (flat pouch) has 3 or 4 contacts
rather than just 2: in addition to battery +ve and -ve terminals, there are some
ID resistors or thermistors included.  Both Motorola C1xx and Pirelli DP-L10
batteries have 3 contacts, and so does Nokia BL-6C battery form factor that was
copied by FIC/Openmoko.  In contrast, cylindrical Li-ion battery cells like
18650 have no such third terminal.

As of this writing (2021-09), we do not anticipate using any kind of battery ID
resistors or thermistors, neither on our Venus board nor on our final handset.
FC Venus will have a provision for bringing out Iota ADIN2 like on Leonardo
(see section 3.3.1.1), but we do not anticipate actually using it.  The battery
on FC Venus will most likely be an 18650; on the final handset we will most
likely either keep the same or use a custom-made flat pouch battery pack, and
if we go with the latter, it will still most likely only have two terminals.

Our current FCHG battery charging driver does not touch ADIN1 or ADIN2 at all.
Looking at TI's old PWR reference code and the disassembly of Pirelli's
firmware, it appears that when mainstream proprietary firmwares do check those
ID resistors or thermistors on ADIN1 or ADIN2, they only act as artificial
blockers: the firmware refuses to charge the battery if it sees something it
doesn't like, as opposed to using data from these sensors to tune or adjust the
charging process in some positive constructive manner.  In FreeCalypso we stand
against all such artificial blocking, instead we uphold the principles of user
empowerment and personal responsibility - thus we do not currently anticipate
ever implementing any kind of ADIN1 or ADIN2 logic.

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.11.1. Charging indicator LED

We are going to implement a TI-classic charging indicator LED controlled by
Iota LEDC; the circuit is nothing more than a LED in series with a resistor,
connected between the VCHG rail and Iota LEDC terminal.  The LED will probably
be red (TBD), such indicator LEDs have low Vf, and because the positive source
is USB +5V rather than VBAT, there should be no issues with LED brightness
variation.

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 41 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 conditionalize loudspeaker support on the firmware build
configuration.  Once we implement initial support for audio modes using RiViera
Audio Service, our basic bigcolor-{gprs,vo} and smallbw configurations will
support only handheld and headset modes, but not handfree.  We will then later
add new bigcolor-spk-* configurations whose purpose will be to support
loudspeaker-equipped phone handset targets; these configurations will enable
support for the hands-free loudspeaker mode (and will expect the loudspeaker
and handfree audio mode to be available), and will also switch the ringtone
generation mechanism from the buzzer to Melody E1 - see section 2.4.

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. Approach to buzzer melodies

My (Mother Mychaela's) original intention was to limit buzzer ringing support
to the extremely crude implementation contained in the Condat audio "driver"
abstraction layer - this demo/prototype/PoC code uses BU mode rather than PWT,
and it only has one extremely basic ringing sound: alternating 800 Hz and 900 Hz
tones, no melodies.  However, I have subsequently changed my mind on this point:
upon further reflection, I realized that the audio "driver" in the Condat
abstraction layer is a horrendous mess that needs to be cleaned up, and one
very helpful step in cleaning it up will be to remove buzzer functionality from
it.  Toward this end, I came up with a new architecture:

* What little remains of the Condat audio "driver" layer (it will be thinned
  significantly) will be only for simple audio tones (call waiting, busy,
  ringing code for the calling party when the GSM network provides no IBT), and
  it won't be involved in ringing, neither in the buzzer config nor in the
  Melody E1 loudspeaker config.

* For platforms that feature a magnetic buzzer, there is a new BUZM (buzzer
  melody) service implemented in RiViera land (the part of fw architecture
  where such application services properly belong), and this BUZM service plays
  PWT buzzer melodies, rather than BU mode.  The bit-level format for these PWT
  melodies is an original FreeCalypso invention, the necessary tool support for
  it has been added to the FC host tools package as of fc-host-tools-r17, and
  the necessary documentation is maintained in the same place.

For the end user of a FreeCalypso phone that features an old-fashioned buzzer
(e.g., FreeCalypso Lite aftermarket fw on Mot C139), the visible effect of this
architecture change is that a decent selection of varied ringtone melodies can
be implemented.  A basic ring that sounds just like TI's original BU version is
still available in PWT mode (it is now composed of alternating G5 and A5 musical
notes, rather than alternating 800 Hz and 900 Hz tones, but it sounds just the
same at least to my ear), but we are now also able to play ringtone melodies of
the same rich kind as those offered by Motorola in their official firmwares for
buzzer-equipped phones.

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) Our Venus board will be a close-to-final prototype for the actual FC handset,
   as close as can be achieved in the physical form factor of a development
   board meant to be used "bare" on a lab bench;

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. Handset vs. development board

The Mother's vision is that our Venus development board will be fairly close to
a final handset motherboard in terms of included hardware and general layout:
on the top side it will feature our LCD, underneath this LCD it will feature our
keypad button set, whereas the bottom side will feature the same two core
component clusters (each possibly covered by a shieldcan) as are envisioned for
the final handset: one for the mobile domain (Calypso+RF core) and one for the
USB domain (FT2232x subsystem of section 1.12).  However, in terms of physical
form factor, FC Venus will still be a development board meant to be used "bare"
on a lab bench, and will exhibit the following key differences from the final
handset motherboard:

* The general form factor will be simple rectangular and unconstrained, without
  highly complex mechanical design effort that will later be needed for a
  handset motherboard that goes into a plastic case.

* Two handset peripheral features will be omitted: the vibrator and the keypad
  backlight.

* There will be one additional peripheral just for the fw development platform
  role of this board, as opposed to the handset prototype role: the magnetic
  buzzer described in section 3.8.  JTAG and VSP tap header connectors can also
  be regarded as special development-board-only extra peripherals.

* The physical realization of audio interfaces will be a little different from
  the final handset and more appropriate for a development board, as detailed
  in section 3.7.

* The SIM socket and all developer-user controls and indicators will be located
  on the top side of the board.

3.3.1. Power supply or battery connection

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.

However, in a departure from our previous development boards, it will also be
possible to connect a real Li-ion battery (instead of a fixed supply) to the
same connector - the Mother's intent is to use a common off-the-shelf 18650
battery holder and wire it up to the necessary Weidmuller plug.  When a real
battery is used, it will also be possible to charge it via Calypso+Iota BCI and
FreeCalypso FCHG just like in a real handset - see the following section.

Because of the need for battery-specific tuning in FCHG, it will be difficult
to use "any" 18650 battery for the real-battery mode of operation on FC Venus -
instead we will be on much more solid footing if we select some specific battery
model and stick to it.  The Mother's current plan is to use Panasonic NCR18650B
as our canonical battery.

3.3.1.1. Iota ADIN2 connection

Our previous development boards FCDEV3B and Caramel2 use only pins 1 and 3 on
the 3-pin Weidmuller battery power input connector - however, TI's Leonardo
schematics also connect ADIN2 to the otherwise unused middle pin.  Just for the
sake of flexibility, we are going to replicate this Leonardo-style ADIN2
connection on our Venus board, allowing the possibility of experimenting with
battery packs that include some kind of ID resistor or thermistor and provide a
third terminal for it.  However, as of this writing (2021-09), we do not
anticipate actually using this functionality - the Mother's current plan is to
use an 18650 battery that does not provide any kind of third terminal.

3.3.2. USB subsystem

Our Venus development board will include the same USB subsystem as intended for
the final FC Libre Dumbphone handset, as described in sections 1.11 and 1.12,
consisting of a USB mini-B interface connector, a charging on/off switch with
the charging circuit behind it, and the FT2232D subsystem of section 1.12.

This design is a radical departure from our previous development boards which
bring out the two Calypso UARTs in their raw LVCMOS form, leaving the USB
interface to an external adapter, most recently our own DUART28.  In fact, the
Mother's original idea for the Venus board was to keep essentially the same
interfaces as on Caramel2, retaining the use of the external DUART28 adapter
and calling for a potential separate battery+charger board - but then this
design was changed after further reflection.

On our previous modem-centric (as opposed to handset-centric) Calypso
development boards, the USB interface was kept separate for the sake of
modularity, allowing the two Calypso UARTs to be connected to other entities
besides just USB.  That design made good sense and continues to make good sense
for non-handset Calypso modem boards.  However, on a handset development board
like FC Venus it becomes much more difficult to think of a realistic use case
where the two Calypso UARTs (or either one of them) would need to be connected
to something other than USB, thus this particular modularity becomes much less
of a value - while the opposite approach of integrating USB provides numerous
benefits:

* One of the primary benefits of the new Venus board over existing Luna is
  significant reduction in clutter: instead of 3 separate boards (Caramel2 MB,
  LCD and keypad) connected with ribbon cables, there will be just one
  integrated board.  If we also integrate the functionality of our DUART28C
  adapter, then we reduce clutter even further.

* In the integrated USB arrangement, the Modem UART channel's RI output (coming
  from Calypso GPIO8) will be connected just like in the final handset - see
  section 1.12.1.  OTOH, this signal would have to be omitted if we were to use
  our legacy 10-pin DUART interface and a DUART28 adapter - RI does not fit well
  into that arrangement.

* When development is done using an AC-mains-powered fixed DC supply and the
  BSIM mode in FCHG, there still needs to be a way to present and remove VCHG.
  Turning on the charging switch will be more convenient than connecting a
  jumper wire between a VCHG header pin and the USB +5V pin on DUART28.

* If our Venus board includes complete charging circuits just like the real
  handset, operation with an actual battery will become a much more practical
  option.  Such operation can be very useful for the purpose of giving field
  demos away from FreeCalypso HQ: in such field scenarios, having to connect an
  AC-mains-powered fixed DC supply may be difficult (limited space, no access
  to AC power outlets, limited attention span of the audience), and furthermore,
  if the demo is presented to a less technical audience, it will likely feel
  more "real" if the phone prototype being demonstrated is powered by a battery
  rather than an AC mains adapter.  In some cases, the charging process itself
  (with standard USB as the charging power source) can be made a part of the
  demo.

3.3.2.1. Linux kernel patch requirement

The FT2232D USB subsystem implemented on FC Venus will include the boot control
feature originating from DUART28C, as described in section 1.12.3.  This
hardware feature has an implication for developer-users of this board: anyone
wishing to play with a Venus board beyond already-flashed fw (i.e., anyone
wishing to connect the board to a host computer) will need to apply our DUART28C
support patch to the ftdi_sio driver in their Linux kernel; as for other host
OSes beyond Linux, absolutely no support exists currently, thus you would need
to do all of the necessary support-creating work yourself.

The problem with the needed ftdi_sio driver patch is that it has been rejected
by mainline Linux maintainers.  The patch is purely additive and non-impacting:
it simply adds support for an entirely new USB device (a new USB VID:PID) that
did not exist before, and has exactly zero impact on anything pre-existing, on
anything outside of this brand-spankin'-new USB device.  But the power-wielding
maintainers rejected the patch because it isn't general enough to them, because
it serves only one specific hardware device which they don't wish to support.

The Mother's answer to those Linux maintainers' game of hardball is to play back
a game of my own: our Venus boards will NOT be sold for money, not for any
price, instead they will be given out free of cost to loyal FreeCalypso
supporters.  Anyone wishing to receive a Venus board will be required to apply
the non-mainlined ftdi_sio driver patch locally to their own Linux kernel, and
to show proof that they have applied this maintainer-rejected patch as a
condition of receiving their board.

3.3.2.2. Board bring-up order

The on-board FT2232D subsystem will be the preferred way to interface to the
two Calypso UARTs on FC Venus, and also the preferred way of driving RPWON and
nTESTRESET boot controls - if everything goes according to plan.  However, to
guard against inoperable boards in the unfortunate event that the built-in USB
subsystem doesn't work as designed, there will also be a "rescue" 10-pin DUART
header on the board.  If all USB subsystem components are populated on the
board as we currently intend, the "rescue" DUART header MUST NOT have anything
connected to it, other than oscilloscope probes - however, if a need arises to
operate a Venus board via an external DUART28 or other adapter, then some
components will need to be removed from the USB section of the board to prevent
the scenario of two fighting drivers.

There will also be a 3-pin boot control header, bringing out RPWON and
nTESTRESET, but this provision does not present the same stringent single driver
requirements as the "rescue" DUART header, as all drivers for these boot control
signals are open drain.

The charging switch will need to be off during board bring-up, and it is
expected to remain off during most development activities on FC Venus, to be
turned on only rarely when exercising the charging function.

3.3.3. Stepping stone toward the final handset

When the time comes to embark on the design of the actual FC Libre Dumbphone
handset, after all necessary fw development work gets done on the Venus
development board, one of the biggest challenges will be the need for close
coordination between electronico-mechanical design of the motherboard PCBA and
ergonomico-mechanical design of the handset case.  It is the Mother's hope that
by being as close as possible to the final handset motherboard while subject to
the constraints of a development board, our Venus board will serve as a useful
stepping stone toward the actual handset.  When the time comes to hire a
cellphone mechanical design expert to create the mechanical design for our FC
handset, we will present a working Venus board (battery-powered and running
well-polished fw, for proper psychological impact) to our hired mechanical
designer, and hopefully this Venus board reference will work for the purpose of
communicating to that mechanical designer our requirements from the electronics
side, as in how much space is required for all of our functional components,
which will be quite different from the more recent mainstream proprietary
phones.

In terms of electronic circuit details, our final FC Libre Dumbphone handset is
expected to be somewhat different from FC Venus, different enough to call for a
different fw build target, as a matter of fact.  However, we expect that in
terms of PCB layout, these electronic circuit differences won't be heavily
disruptive, and we hope that once our hired mechanical designer gives us a
design for the handset, we will then able to transform the PCB layout of FC
Venus into the real handset motherboard.

3.4. 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.5. LCD module and backlight

The LCD module on FC Venus will be Formike KWH020ST23-F01, the same LCD module
which we have settled on for the actual FC handset.  In 2021-09 we made a
lifetime buy of 100 pcs of this LCD module, thus we are now past the point of
considering different candidate LCD modules.  Our chosen Formike LCD module is
almost perfect for development boards such as FC Venus; the only blemish is
that in the absence of additional mechanical restraints, an elastic force that
originates somewhere in the area of the folded-under FPC tail pushes the bottom
of the module upward, away from the PCB, acting against both gravity and
adhesive forces.  However, we have a planned workaround: we are working with a
local-to-us mechanical engineering company to produce a custom retaining
bracket; with the addition of this bracket, the mounting of our LCD module is
expected to become secure enough for development board purposes.

The backlight circuit design of section 1.4.4.1, which is hoped to be final, is
being included in the Venus board design.  Specific LED currents don't need to
be finalized for Venus PCB layout or PCB fabrication; resistor values that set
these currents will only need to be finalized when the time comes to populate
the first fabricated Venus PCBs with components.

3.6. Keypad buttons

The Mother's original intent for FC Venus was to punt on the more complex keypad
arrangement that approximates the real handset, instead continuing what we
currently have on FC Luna: a "raw" 5x5 matrix of buttons in rows and columns,
with silk screen labels indicating the function of each button, matching TI's
D-Sample.  However, this plan has been changed upon further reflection - the
Mother's new thinking is that FC Venus will be a prototype toward the final
handset, a prototype as close as possible to "the real thing" while staying
within the constraints of a development board, thus the keypad arrangement needs
to be made closer to "real" as well.

The main 21-button keypad described in section 1.5 will need to be implemented
on our Venus board, with the buttons in approximately correct relative
positions, all below the LCD.  The buttons will be generic off-the-shelf tactile
switches with finger-accessible actuators, similar to those used on Caramel2 and
on our current Luna keypad add-on, except that SMT parts will need to be used,
in order to not put extra constraints on component placement on the opposite
side of the board.  Because we won't have any overlay with button legends, we
will need to put silk screen labels on our PCB next to each button, denoting
logical functions.

Out of the 21 buttons of the main keypad, 20 will fall onto KBC/KBR cross-
points, i.e., they will be "regular" keypad buttons.  However, the button in the
END position (the one which is traditionally red, for power on/off and call
hang-up) will be special: in hardware terms it will be the PWON button, both on
FC Venus and on the final handset.  This special arrangement exactly follows
TI's canon (D-Sample and predecessors), and has also been followed by the makers
of Pirelli DP-L10.

The 3 side buttons of section 1.6 will also need to be implemented on FC Venus.
The two left side buttons (volume up/down) will be placed on the left side of
our LCD, and the single right side button will be placed on the right side of
our LCD.

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.6.1. Limited boot control buttons

The Mother's original idea for FC Venus was to implement pushbutton switches for
all 3 boot controls as in PWON, RPWON and nTESTRESET.  However, now that we are
integrating the FT2232D USB subsystem of section 1.12 and the boot control
mechanism of section 1.12.3 as a non-removable part of the Venus board itself,
the pushbutton switch for RPWON is being eliminated, leaving only PWON in the
"END" position in the main keypad and a rare-use RESET button.  For additional
context, when I first decided to integrate the FT2232D subsystem with boot
control, I was going to drop the RESET button as well - but then I decided that
it would be more proper to include at least a footprint for one.  My current
intent is to populate an actual button for RESET, but to use a different switch
part with a shorter actuator and a greater operating force, reducing the
probability of accidental resets.

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 intent is that an FC-HDS4 headset will be plugged into this
  main audio jack.

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

4. Motorola C139 port

4.1. Background information

In FreeCalypso we have low-level support for the following alien targets:

* Motorola C11x/12x
* Motorola C139/140
* Motorola C155/156
* Pirelli DP-L10
* Sony Ericsson J100

Low-level support means that for all of these targets, we are able to build and
load a FreeCalypso firmware image that boots and runs without crashing, operates
the phone's GSM radio hardware in proper spec-compliant manner (transmissions
verified with a CMU200 RF tester), and allows control via AT commands and
FreeCalypso debug & development tools fc-shell, fc-tmsh and fc-fsio.  However,
in this so-called "voice pseudo-modem" (VPM) operation, the phone's LCD stays
dark, the buttons do nothing, and there are no high-level functions of any kind,
only low-level control from the attached host computer.

It also just happens that in year 2015 I (Mother Mychaela) produced a firmware
version for Mot C139 that runs untethered, without host computer connection.
However, that untethered FC-on-C139 firmware was produced as a poor man's hack,
not as an end user offering!  Here is the situation we were in: we did not
discover the existence of iWOW TR-800 (an extremely obscure Calypso module)
until December of 2019, thus for the 4 years between 2015 and 2019 we had no way
of running TI's TCS211 MFW+BMI (handset configuration) firmware in its proper
D-Sample config, which is 176x220 pixel color.  But we knew that TI also had an
older C-Sample UI configuration (84x48 pixel B&W), thus out of poverty, for the
lack of proper development hardware, we resurrected that old C-Sample UI config
(at first it wouldn't even compile) and got it running on Mot C139 hardware -
possible because that 84x48 pixel UI was small enough to fit into Motorola's
96x64 pixel LCD.

To be clear, I *never* considered this hacky FC-on-C139 port to be an acceptable
substitute or replacement for my real goals of first getting TI's TCS211 UI up
and running in its proper 176x220 pixel color configuration, and then producing
a FreeCalypso handset that can replace the proprietary Pirelli DP-L10.  However,
a peculiar situation has arisen: we now know that it is possible to transform
Motorola C139 into a sort of Libre Dumbphone Lite with aftermarket FreeCalypso
firmware, and it is clear that some users will prefer this "liberated C139"
option over the Mother's desired FC Libre Dumbphone handset - probably for
reasons of cost more than anything, as our FC phone will likely end up costing
thousands of dollars.  The rest of this chapter will explore the possibility of
practically usable FreeCalypso handset firmware on Mot C139 hardware.

4.2. Why C139?

As a matter of general principle, we could probably get our FreeCalypso Lite
firmware running on all or most of the 5 alien targets listed in section 4.1.
However, the level of usability and the set of user-available features on the
other 4 would only be worse than what we would get on C139, thus if someone is
looking for a pre-existing phone hw unit to convert to FreeCalypso Lite, then
C139 is the best choice in terms of outcome quality.

It is particularly worthy of note that if we were to get FreeCalypso Lite
firmware running on Pirelli DP-L10 (it hasn't been tried as of this writing,
but it is likely possible), the result would be not only much much worse in
functionality than Pirelli's official firmware or the Mother's desired full FC
handset, but actually even worse than the same FreeCalypso Lite firmware running
on Motorola C139!  Therefore, even though the Pirelli phone serves as the
Mother's inspiration for our own FC handset hardware, the existing Pirelli
hardware is mostly useless for the purpose of turning it into a libre phone -
all because of the vast amount of completely undocumented hardware in this
model.

4.3. How to make it happen

The main reason why a practically usable FC firmware version for Mot C139 has
not been produced yet is because I, Mother Mychaela, am not willing to do it in
such a way that would jeopardize my primary goal of true FC handset hardware.
I am willing to support FreeCalypso Lite on C139 as a *side addition* to the
main FC handset hardware goal, but never as a replacement.

Right now my next project goal is to build my desired Venus development board.
Once that board is built, we will be in a better position to whip our TI-based
FC handset firmware into shape.  No, my priorities won't change, and my initial
work on the Venus platform will be on the bigcolor firmware configuration.
However, once FC Tourmaline bigcolor firmware runs on FC Venus in a satisfactory
manner, with audio mode conversion implemented but still using the Calypso
buzzer for ringing, then it may be a good time to bring the smallbw
configuration up to par.  And once FC Tourmaline smallbw runs in an end-user-
acceptable manner on FC Venus, then it will be a slam dunk to move it to actual
C139 hardware.

4.4. Functional scope limitations

Because FC Lite on Mot C139 can only ever be a side project and can never be my
main goal, I have to put some strict limits on the amount of work I am going to
do in that direction:

* The color capability of C139 physical LCD will not be used by FC Lite
  firmware, instead the screen of FC-on-C139 will always be black&white.  The
  reason for this limitation is that displaying color on C139 would involve
  actual work (a non-trivial amount of it) to create an entirely new "small
  color" UI configuration (as opposed to the existing bigcolor and smallbw),
  whereas the existing smallbw config is a freebie gift from TI.

* No dynamic mode switching support on the headset jack: this jack on all C1xx
  phones serves a dual function, it is both an analog headset interface and a
  digital interface for computer connection (UART at 2.8V logic levels), and I
  currently have no plans to implement dynamic switching between these two
  modes.  There will be one firmware build configuration in which the jack
  accepts Motorola headsets - serial cables won't work unless you shut down the
  fw and operate on the phone with tools like fc-loadtool, fc-simint or our FC
  FFS editor - and another fw build configuration in which the headset jack
  accepts serial cables, but not actual headsets.

In summary, FreeCalypso Lite on Motorola C139 will be an *extremely* basic and
"bare bones" phone - but the hope is that it would still be useful to some.