FreeCalypso end user libre phone goals
======================================

The Mother's primary goal in FreeCalypso is to create (design and build) our
own FreeCalypso libre phone handset (a Libre Dumbphone) that can replace the
proprietary Pirelli DP-L10, retaining the following essential qualities of the
latter:

* a "dumbphone" in the most classic "candybar" form factor with traditional
  dial buttons, NOT a smartphone;
* a color LCD of a decent size (Pirelli's is 128x128 pixels, ours will be
  176x220 pixels);
* a loudspeaker that works for both hands-free calls and polyphonic ringtone
  melodies;
* a USB port that combines charging with a built-in serial interface for
  computer interfacing.

A secondary goal is to put together a firmware version that can be flashed into
a surplus Motorola C139 or C140 phone (obscenely cheap hardware) and turn those
originally-proprietary phones into a sort of Libre Dumbphone Lite - functionally
inferior to our own FreeCalypso Libre Dumbphone because Mot C139/140 hardware
is significantly inferior to what I seek to build (no loudspeaker, no USB, much
smaller LCD), but may be attractive to those cheap souls who are unwilling to
pay for higher-quality hardware.  (Doing a similar feat with Pirelli DP-L10
hardware - turning it into a Libre Dumbphone by way of aftermarket firmware -
is not practically feasible: the effort to reverse-eng Pirelli's undocumented
hardware to the extent necessary for such a feat would cost at least as much
time and money as designing and building our own Libre Dumbphone hardware,
hence the latter is clearly preferable.)

The primary goal of entirely new FreeCalypso Libre Phone hardware and the
secondary goal of FC on the C139 are not mutually exclusive: because we are a
FLOSS project rather than proprietary sw, we do not artificially restrict what
hardware our fw can run on and what functionality it can provide: while the
primary target for our Libre Dumbphone firmware will always be our own hw,
whatever functionality can work on the more limited Mot C139 hw will work there,
subject to the limitations of the crippled hw platform.

However, in terms of timeline sequentiality, the critical point is that I,
Mychaela Falconia, the Mother of FreeCalypso, am not willing to do any more
work on the UI firmware (for any target) ahead of designing and building the
first prototype of the just-outlined FC Libre Dumbphone hardware: when it comes
to the work that *I* am doing, it has to be hardware first, then UI firmware.

But the FreeCalypso codebase is free for everyone, it is free software which
anyone in the world is free to fork in whatever ways they like, hence for those
who feel (contrary to my own personal stance) that aftermarket Libre Dumbphone
firmware for pre-existing hw platforms like Mot C139 is more important than new
FreeCalypso Libre Dumbphone hardware, the correct solution for those people is
to get over their fear of programming, roll up their sleeves and do some
firmware coding of their own.

What we got from TI in terms of firmware
========================================

Phone handset firmware, i.e., fw that makes a phone device work as an untethered
phone and not just a serial-cable-controlled pseudo-modem, requires a few
additional layers of functionality beyond AT-command-controlled modem fw:

* The hardware-specific LCD driver, called R2D in TI's TCS211 program;
* The actual phone UI implementation, which the cellular industry calls by the
  sexist term "MMI" - TI's implementation consists of two components called BMI
  and MFW;
* Battery management (monitoring and charging);
* Fairly complex on/off logic to handle all possible combinations of turn-on,
  turn-off, charging while "on", charging while "off", charging completed or
  failed but charging power source not unplugged yet.

The bulk of the UI code resides in the BMI and MFW layers, which sit on top of
ACI (Application Control Interface), which is the topmost layer of the
underlying GSM modem firmware stack.  We got two different versions of this
MFW+BMI code from TI:

* The version under src/aci2, used together with the original TCS211 versions
  of G23M PS and ACI components in the legacy 2092 config, has a very unclear
  origin: it came from the internal SVN of an obscure company that made
  AT-command-controlled Calypso modems (*not* complete phones with Calypso UI),
  those people did not use this code themselves at all (their environment was
  not even set up to be able to compile it), and it is totally unclear how they
  came to have that code which they did not use.  It *might* correspond to the
  rest of TCS211 fw which we got from the same source, or it might not.

* The version under src/ui3, used in our hybrid configs going forward, has a
  much clearer origin: we took it from TCS3.2_N5.24_M18_V1.11_M23BTH_PSL1_src
  reference firmware for TI's later LoCosto chipset, which was published free
  to the world by Peek Inc. as that company was closing shop.

We are now able to build UI-enabled firmware configs using both versions of TI's
MFW+BMI code, and there are no significant differences in the quality of the
phone UI implementation: in both cases it is only a proof of concept, and is
absolutely not ready for driving a real end user phone: the UI code contains
crashing and other killer bugs, the battery management driver officially
endorsed by TI for TCS211 and later programs (LCC for "low cost" unregulated
chargers) is not appropriate for phones that use simple charging circuits and
regulated +5 VDC charging power sources (USB or Motorola's C1xx charging
adapters), and TI's older PWR battery management driver (TI totally removed it
from TCS211, but we pulled it from the older MV100 source fragments) is
bitrotten and just generally broken.

In FreeCalypso we have developed our own battery charging and discharge
monitoring driver (FCHG) that works on Mot C1xx and Pirelli DP-L10 phones in
the "voice pseudo-modem" configuration (see the Voice-pseudo-modem article),
but we still have the problem of the UI, namely, the lack of one that is
practically usable.  Because TI were in the business of making and selling
chipsets rather than complete phones, proper phone UI development was something
they left to their customers, and they provided only a very rough proof of
concept implementation.

What we have currently
======================

If you wish to play with our current work in progress based on TI's PoC UI code,
you have 3 configurations (in the ./configure.sh sense) to choose from:

2092		This is our first UI-enabled configuration; it got its name
		because it is a mostly unchanged replica of TI's pdt_2092
		configuration in the original TCS211 program.  This config uses
		the original TCS211 versions of G23M PS (blobs), ACI (source)
		and MFW+BMI (source) components.  Data services (FAX_AND_DATA
		and GPRS) are enabled and cannot be disabled because of G23M PS
		blobs.

hybrid-ui	This config is the TCS2/TCS3 hybrid counterpart to the above,
		using the new full source versions of G23M PS, ACI and MFW+BMI
		from the TCS3.2/LoCosto source.  FAX_AND_DATA and GPRS are
		still enabled.

hybrid-ui-vo	Same as hybrid-ui, but with FAX_AND_DATA and GPRS disabled,
		resulting in a lighter build.

All 3 of the above configs can be usefully built for 3 hardware targets:
dsample, fcdev3b and c139.  The resulting firmware will work as follows:

* If you have a real TI-made D-Sample board with the attached test handset (the
  platform that TI's own software engineers used when working on this UI code,
  at least before LoCosto), TI's 176x220 pixel color UI will be displayed on
  the LCD in the handset part of the kit, just the way TI meant it.  However,
  because we are missing a piece of code for Clara RF, GSM radio won't work,
  and the UI can only be exercised as it would work in the absence of coverage:
  one can step through the menus and read SIM phonebook entries and saved
  messages, but no calls.  See the D-Sample article for the details.

* You can run a UI-enabled firmware build on our FCDEV3B modem board that has
  no physical LCD or keypad hardware, and display TI's 176x220 pixel color UI
  on a connected external host, sending simulated keypresses from the same -
  look in the freecalypso-ui-dev repository for the necessary tools.

* When a UI-enabled firmware config is built for the C139 target, the UI config
  (Bourne shell variable UI_CONFIG in our configuration and Makefile generation
  system) is switched from TI's D-Sample UI (176x220 pix color,
  UI_CONFIG=bigcolor) to their older C-Sample UI: 84x48 pix black & white,
  UI_CONFIG=84x48.  This 84x48 pix B&W C-Sample UI is then displayed on the
  96x64 pixel physical LCD on the C139 phone.

If you are interested in the Mot C139 hardware target and you are interested in
turning our current state of affairs into something that would allow you to use
your C139 as a practically usable libre phone with FreeCalypso, the Mother
strongly recommends that you use the hybrid-ui-vo configuration as your starting
point; working on the old src/aci2 UI code that is slated for retirement because
it is coupled to a G23M PS version that exists only as binary blobs would be a
total waste.  If you try to use our current hybrid-ui-vo firmware on the C139
as a practical phone, the following problems will be the ones that hit you most
immediately, and therefore would need to be fixed first:

* The FCHG driver included in the fw build does monitor the battery state of
  charge as it discharges, and you can query it with the standard AT+CBC command
  using the AT-over-RVTMUX channel on the headset jack serial port, but it is
  not connected to the UI, hence the battery icon on the screen shows no useful
  info.  Thus with an end user hat on, you would have no way of knowing if your
  battery is full or almost empty and about to die any second or anywhere in
  between.

* The firmware similarly supports battery charging, but once again there is
  absolutely no indication in the UI as to the state of the charging process as
  in progress, completion or errors.  Instead you can only observe this
  charging process by watching the debug trace output emitted on the headset
  jack serial port.

* Every standard commercial end user phone implements a special mode of
  operation that is activated if the user plugs in the charging power source
  while the phone is off: the phone firmware boots just enough to manage the
  battery charging process (the LCD shows nothing but this charging process),
  but does not boot all the way to "full on" operation (SIM bring-up and
  network search) until and unless some designated button is pressed to request
  such full boot.  The proof-of-concept code we got from TI does not implement
  this special "charging boot" mode; instead if you connect the charging power
  source to a fully-off phone, the result will be a full boot just as if you
  pressed the red power-on button.  This lack of the expected "charging boot"
  mode is bad, as one really needs a "charge while off" mode in order to
  properly recover from a fully discharged battery.

* Every standard commercial end user phone implements some timer logic for the
  power-on button, such that if the phone is fully off, the power button needs
  to be pressed not just momentarily, but held down for some time in order to
  make the phone turn on and boot.  This logic provides necessary protection
  from accidental turn-ons: if you are in some place where your phone needs to
  be off and you have turned it off, you don't want it booting back up on its
  own because the button got pressed momentarily from the phone being in your
  pocket or purse.  This logic is currently missing.

* The LCD on Mot C139 phones is already small, only 96x64 pixels, but with the
  current firmware using the UI which TI originally created for their C-Sample
  and earlier development boards, the usable area is reduced even further to
  only 84x48 pixels.  Likewise the physical LCD is color, but the UI is only
  black&white because the UI code "thinks" it's running on a C-Sample board
  which only had a black&white LCD.  Massively reworking the UI code to make
  use of the full 96x64 pixel LCD real estate, along with some colors, ought to
  be essential before this UI can really become fit for end user operation.

Some of these just-listed killer bugs are specific to the C139 target, while
others will still be there when we have our own HSMBP with a 176x220 pix color
LCD like on the D-Sample.  Those bugs which are not C139-specific will be fixed
in the process of making our own FreeCalypso Libre Dumbphone based on our own
hardware, and by virtue of the common code the fixes will benefit the C139
target as well.  In the case of C139-specific bugs, i.e., those specific to the
tiny screen size or to the weird (not TI-canonical) way in which the power
button is wired on C1xx phones, it is not currently known whether or not I
(Mychaela aka The Mother) will ever be willing to invest significant work into
these C139-specific issues.  Thus the message is loud and clear: those who
desire FreeCalypso as aftermarket libre phone fw for Mot C139 or other non-FC
hardware need to roll up their sleeves and start learning the code.