--- a/doc/Handset-goal	Mon Mar 19 19:59:35 2018 +0000
+++ b/doc/Handset-goal	Tue Mar 20 01:29:44 2018 +0000
@@ -1,5 +1,57 @@
-Work toward end user libre phone firmware
-=========================================
+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
@@ -14,181 +66,156 @@
   turn-off, charging while "on", charging while "off", charging completed or
   failed but charging power source not unplugged yet.
 
-The code we got from TI with the TCS211 delivery by Sotovik includes only a
-very rudimentary implementation of the above functions that basically amounts
-to nothing more than 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 the TCS211 program (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.
+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.
+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.
 
-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.
-One difficulty which we face most immediately in our effort to turn this PoC UI
-implementation into a practically usable one is the lack of support for our
-desired target display sizes.  Because TI apparently did not want to become
-significantly involved in phone UI development, they did not provide a selection
-of UI layouts for different LCD sizes; instead at each given point in TI's
-history they only supported one display size - whatever their current
-development platform at each moment had on it.
+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:
 
-At the time of TCS211, TI's primary development platform was called D-Sample;
-it consisted of a development board with the Calypso+Iota chipset on it (as
-well as a GSM RF section based on their older Clara RF transceiver chip) plus
-an attached test handset.  Here are some pictures:
-
-https://www.freecalypso.org/members/falcon/pictures/D-Sample/
+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.
 
-The handset part of the D-Sample kit contains a 176x220 pixel color LCD, a
-21-button main keypad just like on Mot C1xx and Pirelli DP-L10 phones, and 3
-side buttons that almost match Pirelli's.  This D-Sample was the main
-development platform for the entire TCS211 program (basically everything except
-the small parts specific to Rita RF for which they had their other Leonardo
-development boards), including the UI - the latter was made to target the
-176x220 pix LCD size on the D-Sample.
+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.
 
-I (Mychaela) have managed to obtain one of these historical D-Sample kits (the
-one pictured) back in 2015, and I have a strong desire to get the TCS211 PoC UI
-up and running in its native 176x220 pixel size.  However, the big difficulty
-with getting our FC Magnetite firmware running on the original D-Sample board
-(which, remember, is the original and most native hw target for TCS211!) is
-that the D-Sample has Clara RF, not Rita, and we only got a stripped semi-src
-version of TCS211 in which the *.c files for L1 were censored out and only
-*.obj blobs were supplied instead.  The latter blobs target Rita RF and not
-Clara.  We have now successfully reconstructed the lost C sources for the RF-
-independent and Rita-specific L1 modules, and we have l1_rf10.c for Clara RF
-from the MV100 source fragments, but we are still missing the tpudrv10.c module
-which is also required for Clara RF.
+hybrid-ui-vo	Same as hybrid-ui, but with FAX_AND_DATA and GPRS disabled,
+		resulting in a lighter build.
 
-Back in 2015 (when I first got this D-Sample kit) running our own firmware on
-this historical board with an older version of the Calypso chip and with Clara
-RF was absolutely out of the question, but since then we have made enormous
-progress with our complete deblobbing of L1 and the init module and with our
-FC Magnetite build system, and now that tpudrv10 module is literally the only
-missing piece.  Given these new circumstances, I plan on making some serious
-effort to locate the TPU driver code in the ancient 20020917 fw image that came
-with our DS board, and attempt to reconstruct the needed tpudrv10 code from
-that.
+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:
 
-We also have a fallback plan: if we are not able to get our FC Magnetite
-firmware running on the historical TI-made D-Sample board, there is another way
-to get TI's TCS211 UI code running in its original 176x220 pixel size, albeit
-one that will require a lot of time, effort and expense: design and build our
-own UI development board to take the place of TI's D-Sample, combining the good
-version of the Calypso+Iota+Rita chipset for which we have good fw support with
-a 176x220 pix color LCD of our own - it is one of the industry standard sizes,
-so it should only be a matter of getting a semi-custom one with the right
-interface (16-bit parallel) and the right polarizer orientation (6 o'clock
-viewing direction).  The proposed board would be a derivative of our current
-FCDEV3B, keeping the core Calypso+RF block (originally from Openmoko) completely
-unchanged, but adding the LCD, the keypad buttons and other handset peripherals,
-resulting in a Handset Motherboard Prototype - HSMBP.
+* 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.
 
-Once we get TI's TCS211 UI running in its original 176x220 pixel size like it
-once ran in TI's own software development labs back in The Day, whether we do
-it by way of TI's original DS board or our own HSMBP, the next step will be to
-migrate it to the TCS2/TCS3 hybrid config, using the new versions of G23M PS
-and ACI components.  It will also be worthwhile to see if the new version of
-this BMI+MFW code in the LoCosto version is any better than the one we got from
-Sotovik.  After these preliminary steps, the UI work can bifurcate:
+* 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.
 
-* On the one hand, it will be worthwhile to produce a size-reduced version of
-  the UI that targets a 96x64 pixel LCD instead of 176x220 pix, but still full
-  color - thus fitting the LCD on Mot C139/140 phones on which we already run
-  our fw very successfully in the "voice pseudo-modem" config.  We would then
-  be able to see if a Mot C139 phone running FreeCalypso fw can be a practically
-  usable end user phone, albeit a super-low-end one.
+* 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.
 
-* On the other hand, it is my (Mychaela's) strong desire to have our own
-  FreeCalypso Libre Dumbphone hardware product; running FC fw on Mot C139 just
-  isn't enough to satisfy my ambition.  My choice of LCD size for our own FC
-  Libre Dumbphone is 176x220 pix, matching TI's D-Sample, so that the rich UI
-  targeting this large LCD size can see the light of day as a real end user
-  product, and my planned HSMBP board is envisioned as not only an alternative
-  to the D-Sample, but also as the prototype motherboard for our FC Libre
-  Dumbphone.
-
-Current state of the firmware
-=============================
+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:
 
-If we desire a libre phone for our pockets and purses (I do desire one for my
-purse), we will have to bite the bullet and do the necessary work to transform
-the UI and associated handset code from its current sorry state into something
-usable, and I have started laying a little bit of the necessary foundation for
-doing this work in FC Magnetite.
+* 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.
 
-There is currently one Magnetite configuration (in the ./configure.sh sense)
-that includes the UI layers, called 2092.  2092 is TI's bizarre "product"
-number for the configuration that is just like the one we got from Sotovik
-(called pdt_2091), but with BMI enabled.  We previously had another config
-called 2092-pwr that had TI's old PWR battery charging driver included, which
-never worked because of severe bitrot - that config has now been dropped as the
-regular 2092 config now includes our new and working FCHG battery charging
-driver.
+* 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.
 
-If you request the 2092 configuration for a target other than c139, i.e., for
-fcdev3b, gtamodem or pirelli, you will get a successful build (to be pedantic,
-if you pick gtamodem, you'll get a link failure unless you tweak the linker
-script, but it's a minor nit), but if you then run that fw image on the
-hardware, it won't do anything good: it will try to display TI's D-Sample UI
-(176x220 pixels, color) on the D-Sample LCD attached to Calypso chip select
-nCS3, but of course neither Openmoko's modem nor the Pirelli has a D-Sample LCD
-on that chip select, thus the LCD output would fall into the aether.  (It would
-be even worse in the case of the Pirelli which has the 2nd flash bank on nCS3,
-thus the D-Sample LCD writes could clash with the FFS code operating on that
-flash - so don't do it.)  However, because BMI is enabled, the fw will still
-automatically bring up the GSM radio and register to the default network
-immediately upon boot like a typical UI-enabled phone does, even though the
-associated LCD output will be invisible.  Needless to say, this configuration
-is not something I would ever advise actually running - but it is there in
-anticipation of my idea of running our fw on the original D-Sample board as
-described above.
+* 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.
 
-However, if you build the 2092 config for the c139 target, the Magnetite build
-system will enable the same hack which was originally implemented in the
-tcs211-c139 side project in late 2015.  Prior to the D-Sample with its fancy
-176x220 pix color LCD, TI's previous development platforms (C-Sample and
-earlier) had 84x48 pix black&white (1 bit per pixel) LCDs, and this old C-Sample
-LCD support is still there in TCS211, albeit in a bitrotten form that wouldn't
-even compile without a lot of fixing.  In our late-2015 tcs211-c139 side project
-we had resurrected this C-Sample UI configuration, and this work has now been
-integrated into Magnetite.  When you build Magnetite in the 2092 configuration
-for the c139, you will get our C139 LCD driver that pretends to be C-Sample to
-the upper layers, and you will get TI's old 84x48 pix B&W UI displayed on the
-phone's 96x64 pixel color LCD.  IOW, only 84x48 out of the available 96x64
-pixels are used, and only 2 out of the available 65536 colors.  Yes, pretty
-pathetic, I know.
+* 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.
 
-Going forward, the plan is as outlined above - I wish to see this UI code run
-in the proper 176x220 pix color display config that once existed in TI's own
-development environment before I do anything else to it.  I am not happy at all
-about having had to disable TI's D-Sample UI (the 176x220 pix color one) and
-resurrect the ancient pathetic C-Sample one instead, and given the long list of
-show-stopping bugs this UI code currently exhibits, I can never be sure which
-of these bugs were already there in the D-Sample config this code was made for,
-vs. which of these bugs could be a result of re-enabling the very bitrotten
-C-Sample UI config - remember, it wouldn't even compile at first.
-
-Deblobbing status
-=================
-
-The current 2092 config is based on the l1reconst modem config (see the
-Modem-configs write-up), i.e., the entire chipsetsw division of the fw
-including all of L1 and the init code in main.lib is fully rebuilt from source,
-but the versions of G23M PS and ACI are the original TCS211 ones, thus the G23M
-PS component is all blobs.  In order to build a G23M-deblobbed UI-enabled
-config, we would need to build the UI layers (MFW and BMI) on top of the new
-TCS3.2 version of ACI used in the deblobbed hybrid config, and no such feat has
-been attempted yet.  My current plan is to work in this direction after we
-either get our fw running on the historical D-Sample board or build our own
-HSMBP.
+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.