--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/FC-handset-spec	Thu Jun 10 07:16:17 2021 +0000
@@ -0,0 +1,321 @@
+FreeCalypso Handset Specification
+=================================
+
+The purpose of this document is two-fold:
+
+1) This document serves as the principal design specification for the
+   FreeCalypso Libre Dumbphone handset hardware which I, Mother Mychaela,
+   seek to build.
+
+2) This document also defines the scope of functionality to be supported in
+   FreeCalypso handset firmware, including support for additional hardware
+   targets beyond the primary FC handset hw target.
+
+1. FC handset hardware specification
+
+1.1. Basic features
+
+The Mother's goal is to produce a replacement for the proprietary Pirelli DP-L10
+phone, or more specifically, for the GSM-only subset of this Pirelli phone which
+the Mother actually uses, *without* Pirelli's key differentiating feature of
+non-GSM WiFi operation, and without Pirelli's camera.  The following hardware
+features are to be included:
+
+* 176x220 pixel color display (no touch)
+* 21-button main keypad
+* 3 side buttons for volume control and an auxiliary function
+* USB port that combines charging and computer interface
+* wired headset jack
+* single SIM slot
+
+The following features which are commonly found in mainstream proprietary
+phones, particularly more recent ones, will NOT be included:
+
+* camera
+* Bluetooth
+* FM radio
+* TV receiver
+* GPS receiver
+* dual SIM slot
+* torch light beyond LCD and keypad backlights
+
+1.2. RF band capability
+
+Our FC handset needs to be quadband GSM; this quadband capability will be
+achieved by copying the RF section and the core PCB layout around it from the
+reverse-engineered iWOW TR-800 modem module, which is itself a very direct
+(almost verbatim) derivative of TI's Leonardo+ quadband reference design.
+
+1.3. RAM and flash
+
+The Mother's intent is to use Spansion S71PL064JA0 flash+RAM MCP on the final
+handset motherboard, providing 8 MiB of flash and 2 MiB of XRAM in a 7x9 mm
+footprint.  This flash and RAM capacity is already known to be fully sufficient
+for our FreeCalypso handset firmware in maximal feature configuration, hence
+any larger capacity would be excessive.  However, on our FC Venus development
+board we may use the larger S71PL129NC0 MCP, same as used on FCDEV3B V2.
+
+1.4. Liquid crystal display
+
+1.4.1. Display size
+
+The size of the display for our FC Libre Dumbphone handset design is fixed at
+176x220 pixels, 16-bit color, following TI's D-Sample platform and the starting
+point UI code that was developed for it.  Thoughts of changing to a different
+display size have been considered and rejected:
+
+* If we were to change to a smaller display size, we would have to do extra work
+  on the firmware to shrink the UI to the smaller size, and we would reduce the
+  amount of information that can be displayed at once.  We would incur extra
+  work and a functional loss, but gain absolutely nothing in return.
+
+* If we were to change to a larger display size (240x320 pixels seems to be the
+  largest reasonable size for dumbphones, used in high-end Nokia models), we
+  would be venturing into uncertain territory - the greatest uncertainty would
+  be the extra CPU load on Calypso to draw the larger UI and to refresh the
+  larger framebuffer, which is done with PIO on Calypso, without any DMA
+  assistance.  The D-Sample LCD size of 176x220 pixels already appears to be a
+  strain in some drawing code paths, hence the Mother's decision is to play it
+  safe and stick with the known working display size.  Expanding the UI to make
+  sensible use of larger screen real estate would also entail additional work.
+
+176x220 is the display size in pixels, and this resolution number by itself says
+nothing about the physical display size in inches or mm.  However, most readily
+available LCDs that are made for this pixel resolution are made in 2.0" diagonal
+physical size, with 31.68x39.60 mm active area and 0.180 mm dot pitch, hence
+this physical size is the one we are going to use.
+
+1.4.2. Specific LCD module selection
+
+As of this writing, the specific LCD module to be used has not been firmly
+selected yet.  We are actively looking for an LCD module that fits all of the
+following requirements:
+
+* TFT color LCD, 2.0" diagonal, 176x220 pixel resolution;
+
+* 16-bit microprocessor bus interface;
+
+* 6:00 viewing direction as appropriate for cellular handsets;
+
+* backlight consisting of 3 white LEDs in parallel, joined at the anode,
+  with separately brought-out cathodes;
+
+* mechanical design that supports mounting with the FPC tail folded under the
+  module, either by way of direct solder termination (no connector) or by way
+  of raised sides that create sufficient vertical space to accommodate the FPC
+  connector.
+
+The requirement of 16-bit microprocessor bus interface stems from the desire to
+interface this LCD to the Calypso in exactly the same way how TI did it on the
+D-Sample, the 6:00 viewing direction and mechanical mounting requirements stem
+naturally from the target application (cellular phone handset), and the
+backlight LED wiring requirement stems from the constraints of our chosen
+MAX1916 backlight LED driver chip - see section 1.4.4.
+
+1.4.3. Backlight and readability considerations
+
+Out of the various pre-existing mobile phones which I (Mychaela) have
+experienced, there have been 3 different kinds of LCDs in terms of how display
+operation and readability interacts with the backlight:
+
+1) older phones with black&white LCDs: on all phones of this type which I've
+   ever used, the display is perfectly readable without the backlight given
+   ordinary ambient lighting, be it natural daylight or room lighting.  Such
+   LCDs are called reflective.  With these B&W displays, you only need to turn
+   on the backlight if you need to operate the phone in darkness, such as
+   outdoors at night or inside with all lights off.  The firmware in such phones
+   is typically designed to leave the actual display functional and updated at
+   all times, with only the backlight subject to on/off control.
+
+2) most newer phones with color displays, of which Pirelli DP-L10 is a
+   representative case, have transmissive LCDs that are not designed to be
+   readable without the backlight at all - backlight required for readability
+   (BLRR) is another way to describe such LCDs.  Because the display is not
+   readable at all without the backlight, phone firmware is typically designed
+   to turn off the entire display (not just the backlight) when the screen goes
+   dark, and operation visible to the user is display on/off, rather than
+   backlight on/off.  It is a good firmware design practice to "swallow" the
+   initial keypress that turns on the display from dark state, i.e., to block
+   the regular action of whatever button was pressed to "wake up" the display.
+
+3) The color display on Motorola C139 phones is an odd intermediate case: this
+   display is NOT practically readable with the backlight off, yet the firmware
+   is designed as if the display were readable in this condition: the actual
+   display (unsure if it is CSTN or TFT) remains on and updated, and when you
+   press some button to "wake up" the display, that button still takes its
+   regular action, which is really bad for usability.  How do we know that the
+   actual CSTN or TFT display remains on and actively updated when it is not
+   readable with the backlight off?  Answer: the non-backlit display can be made
+   readable by shining a flashlight directly at it - but this trick requires a
+   directly pointed flashlight; no amount of ordinary ambient light is enough
+   to make the display readable.
+
+Because our FC Libre Dumbphone handset will have a color display (contemporary
+TFT) and because we are sane, not copying the monumental design mistake of Mot
+C139, our display will fall into class 2 by the above classification: backlight
+required for readability, full display on/off rather than just backlight on/off,
+firmware operating like Pirelli's in terms of wake-up keypress swallowing.
+
+1.4.3.1. Backlight dimming mode
+
+Because our LCD is of BLRR type and because we seek to fully replicate Pirelli's
+logic in terms of when keypresses are swallowed and when they are not, we need
+to implement a dimming mode for our LCD backlight.  In Pirelli's design which we
+are copying, when you are playing with phone menus or composing SMS etc, but are
+not in an active call, the display switches between full brightness and totally
+off - it goes fully off on timeout, and when you press a button to wake it up,
+it switches on at full brightness, together with the keypad backlight.  But when
+you are in a call, when the timer expires (and it's a shorter timer, 10 s
+instead of 30 s), the display goes dim instead of fully off, and in this dimmed
+(but still readable) state keypresses are NOT swallowed.
+
+We only need to implement two different intensity levels for the LCD backlight:
+full brightness and in-call dimmed.  The backlight intensity level in the dimmed
+state will need to chosen on this principle: use the lowest backlight LED
+current (to conserve battery power and allow longest talk time on one charge) at
+which the display is still readable, similarly to Pirelli's in-call dimmed
+state.
+
+In the user-actively-poking state, as opposed to the long-call dimmed state,
+there is no need to provide different configurable backlight levels - see
+section 1.4.5.
+
+1.4.4. Backlight circuit implementation
+
+In all candidate TFT LCD modules that are being considered (see section 1.4.2),
+the backlight consists of 3 white LEDs wired in parallel, joined either at the
+anode or at the cathode - although as we shall see momentarily, we require an
+LCD module where the 3 LEDs are joined at the anode, with the 3 cathodes brought
+out separately.  LCD module datasheets call for 15 mA current through each LED
+at maximum intensity, for 45 mA total, and the LED forward drop voltage (Vf) at
+this rated current seems to range between 2.9 V (what I actually measured on one
+candidate LCD module) to 3.2 V (what the datasheets list as typical) to perhaps
+as high as 3.4 V (what one datasheet lists as the maximum).
+
+Given the parallel (as opposed to series) wiring of the 3 LEDs and the
+relatively low Vf, there is no need to use any kind of boost converter as part
+of the LED driver circuit for this backlight - any boost converter will only add
+inefficiency (more current will be drawn from the battery for the same LED
+current), hence we need to avoid using such.
+
+Regardless of whether a given phone design uses a boost converter or not (it
+seems that older designs do use boost converters, either because older white
+LEDs have higher Vf or because 2 or 3 LEDs are wired in series), all traditional
+phone designs seem to share the quality where the display backlight brightness
+remains the same as the battery discharges and as Vbat goes down - this quality
+was directly observed on the Pirelli DP-L10 (unknown circuit design) and
+inferred from the available schematics for Mot C139 and C155, with both of the
+latter boost-converting to fixed 5.0 V.  In our case, even though we choose to
+not use a boost converter for efficiency reasons, we still need to achieve the
+quality of the display brightness remaining the same through the discharge range
+of our Li-ion battery - having the display dim in half as the battery discharges
+from 4.2 V peak to 3.6-3.7 V plateau is simply not acceptable.
+
+The simplest possible LED driving circuit would be one where a current limiting
+resistor is inserted in series with each LED, and then the 3 parallel
+LED+resistor sets are connected across battery terminals, with a transistor
+inserted somewhere to act as the on/off switch.  However, this trivial circuit
+is not suitable in our application because it would produce unacceptably large
+variation in display brightness as the battery discharges - hence we need a more
+intelligent LED driving circuit.  Our Luna LCD carrier board from the spring of
+2020 features an LDO bringing Vbat down to fixed 3.5 V, followed by very low-
+value resistors in series with each LED - but this approach is not good for
+production either, as it makes the LED current extremely sensitive to any slight
+variations in Vf.
+
+Fortunately, I was able to find a specialized white LED driver chip that is just
+perfect for our application, or more precisely, a specialized chip that acts as
+a constant current sink for such LEDs - Maxim MAX1916, design from 2001, just
+the right time frame for the kind of phone we are seeking to build.  This
+special chip takes the place of "dumb" ballast resistors: connect Vbat (battery
+positive terminal) directly to the common anode of the 3 LEDs, but instead of
+series resistors, connect each cathode to the corresponding LEDn pin of MAX1916
+- *without* any resistors or transistors!  FETs inside the MAX1916 take the
+place of resistors as current-limiting elements, and the chip's global on/off
+control takes the place of a separate switching transistor.
+
+The special quality of MAX1916 is that it produces constant current through each
+LED (based on a set reference current and 230x current multiplication circuit
+inside the chip) regardless of variations in both Vbat and Vf!  Of course the
+requested current can only be sustained as long as Vbat >= Vf + Vds, where Vds
+is the lowest drop voltage of the FETs inside MAX1916, and once Vbat falls below
+this point, the LED current will begin to decline.  However, the beauty of this
+design is that no arbitrary artificial turnover points (like the 3.5 V point in
+our hacky design from the spring of 2020) need to be set: the battery discharge
+point at which the LED current begins to decline will be whatever it comes to be
+naturally, based on Vf (perhaps depending on temperature) and MAX1916 Vds, and
+the decline is expected to be gradual.
+
+1.4.4.1. Backlight current selection and dimming
+
+In the simplest MAX1916-based design, a fixed LED current is set by connecting
+a resistor of appropriately computed value between MAX1916 SET pin and whatever
+regulated fixed voltage rail happens to be available in the system.  However,
+in our application (see section 1.4.3.1) we need at least two different display
+brightness levels, and thus at least two switchable LED currents.  At first the
+problem seems difficult, but an elegant solution has been found.
+
+LCD backlight LED current will be selected by way of two Calypso GPIO pins
+configured as outputs, and a 74LVC2G125 dual tristate buffer.  Each tristate
+buffer's A input will be tied high, and the two Calypso GPIO outputs will be
+connected to buffer output enable inputs.  There will be two resistors with
+different carefully computed values, each connected between one of the two
+tristate buffer outputs and MAX1916 SET pin.  One resistor will provide a small
+current, the other will provide a large current, and each of these two currents
+will be switchable on/off by Calypso GPIO signals switching the buffer outputs
+between driving high (2.7-2.8 V) and Hi-Z.  Resistor values will be chosen such
+that the sum of both currents will be the 15 mA limit (the current is reckoned
+per LED), whereas the small current alone will be whatever we need for the
+battery-saving long-call dimmed mode.
+
+1.4.5. Slight regression relative to Pirelli DP-L10
+
+The actual LCD backlight LED driving circuit inside the Pirelli phone is not
+known, but reverse engineering of Pirelli's firmware followed by experimentation
+reveals that backlight intensity variation is achieved via a form of PWM, using
+Calypso PWL output - although PWL is used in an inverted sense, such that the
+backlight intensity increases with more 0s being put out on PWL, as opposed to
+more 1s.  Thus regardless of the unknown actual circuit implementation, the
+backlight intensity appears to be continuously variable from 1/255 to 255/255,
+which is certainly a much richer control than our crude selection of just 3
+possible LED currents.
+
+In terms of what Pirelli's fw offers to end users, the backlight intensity in
+the dimmed in-call state is always set to 1/255, without any way to change it,
+whereas the backlight intensity in the active interaction state is selectable
+via a menu among 5 levels; the 5 offered levels turn into 1/255, 64/255,
+128/255, 192/255 and 255/255 in the resulting PWL programming.
+
+So in terms of both hardware capabilities and end user offering via the
+firmware, Pirelli's LCD backlight level control is richer than what we are
+proposing for our FC Libre Dumbphone.  However, engineering is all about
+trade-offs and compromises, and in the Mother's opinion, this slight reduction
+in the richness of functionality is sufficiently offset by the efficiency of
+our MAX1916-based approach: aside from the theoretical possibility of a
+switching buck converter, which I've never seen used for LED driving
+applications, our choice of MAX1916 is the most battery-efficient way to drive
+our backlight LEDs.  Furthermore, when dimming is effected by switching the
+actual regulated LED current, as in our case, as opposed to applying PWM, our
+backlight becomes more resilient to even lower battery voltages.
+
+Consider what happens when Vbat falls below the point at which the design-
+intended LED current can be maintained - what happens then?  If no PWM is
+applied, or if PWM is set to maximum, then display brightness will be whatever
+maximum is possible at this low battery voltage.  But if PWM is applied,
+especially very low duty cycles as in the case of Pirelli's dimmed state, then
+the display that has already been dimmed by low Vbat will be *further* dimmed
+by this aggressive PWM, likely producing an unreadable display at this point.
+It may be possible to compensate via extra complexity in the firmware, by
+turning PWM up when Vbat (as measured via Iota MADC) falls too low - but then
+we would be getting really messy, whereas switching the regulated current is so
+much more elegant.  With our approach, low-battery-induced dimming in the "full
+brightness" mode will happen at the same discharge point as it would if we had
+used PWM (and set PWM to maximum in this "full brightness" mode), but in the
+in-call dimmed state, further dimming due to low Vbat will probably happen at a
+lower discharge point (if Vf decreases with decreasing current), and when it
+does happen, there won't be a combination of both natural and artificially-
+induced reductions, just the natural one.
+
+Thus based on all of the above considerations, I feel justified in my design
+choice of foregoing PWM control of backlight intensity in favor of fixed current
+switching with much more limited selection.