--- a/Handset-UI-fw	Sun Sep 13 21:36:17 2020 +0000
+++ b/Handset-UI-fw	Wed Sep 23 23:06:58 2020 +0000
@@ -180,70 +180,100 @@
 original form - using our own FCHG or no battery management driver at all is
 just as fine.
 
+FreeCalypso Luna handset UI development platform
+================================================
+
+As of 2020 we have a new hardware platform for running UI-enabled firmware
+configurations; this development platform is codenamed FC Luna.  Our FC Luna
+platform consists of a 176x220 pixel LCD (TFT color) and a 5x5 keypad connected
+to a Calypso core; the key feature is that the LCD size (176x220 pix), color
+depth (16 bits) and interface to Calypso (16-bit parallel with memory-mapped
+registers) are exactly the same as on TI's D-Sample.  This FC Luna platform is
+supported in FC Magnetite, and it finally allows us to run TI's handset UI code
+in its native form.  We can run all of the same configurations which existed in
+TI's original TCS211 fw on TI's original D-Sample platform:
+
+* The default configuration is 176x220 pixel UI with full color - this is the
+  config which TI actually supported in TCS211 days.
+
+* Setting UI_CONFIG=bigbw (switching UI code config) and optionally
+  DSAMPLE_FULL_COLOR=0 (switching R2D driver config) produces TI's 176x220 pixel
+  black&white configuration.  This config is not particularly interesting: any
+  practical phone LCD of this large size is also going to be color, thus it is
+  better to use the full color config for this large size instead.  For this
+  reason whatever bugs are specific to this 176x220 pix B&W config (and there
+  definitely are some) will be ignored, as there is no point in investigating
+  and fixing them.
+
+* Setting UI_CONFIG=84x48 and DSAMPLE_FULL_COLOR=0 produces the same C-Sample
+  UI config which we've been running on Mot C139 phones, but without the
+  ugliness of emulating C-Sample LCD hw at the driver level - instead in this
+  config the small 84x48 pixel UI code runs on top of TI's D-Sample B&W R2D
+  driver, with the small UI displayed in the upper left corner of the large
+  physical Luna LCD.
+
+Running the UI_CONFIG=84x48 DSAMPLE_FULL_COLOR=0 config on Luna has already
+helped shed light on one UI issue that was more elusive when running on C139 hw:
+the disappearing time display.  When running this config on Luna, we can see
+that the UI code displays a text line with date and time outside of the 84x48
+pixel area, i.e., it is a bug in the !LSCREEN configuration - but when we run
+with driver-level C-Sample emulation on C139, this misplaced text line is
+invisible.
+
 The proper way to get proper support for Mot C139
 =================================================
 
-I (Mother Mychaela) feel very strongly that the best way to produce practically
-usable end user FreeCalypso firmware for the C139 target would be to do it
-together with our own FreeCalypso Libre Dumbphone development, as opposed to
-trying to support the C139 to the exclusion of our own FreeCalypso hardware.
-Specifically, I propose the following order of steps:
-
-1) First build our own FreeCalypso UI development board, a derivative of the
-   FCDEV3B adding a 176x220 pixel color LCD and other miscellany to serve as a
-   replacement for TI's D-Sample.
-
-2) Retire the C-Sample UI configuration and our currently implemented C-Sample
-   emulation hack on the C139, and start running TI's UI code the way TI's own
-   developers ran it on the D-Sample.
+For many years the handset firmware project direction in FreeCalypso had been
+blocked by the lack of a D-Sample-like development platform with a 176x220 pixel
+LCD.  This blockage has finally been lifted in 2020 with the arrival of our Luna
+UI development platform, and now the only lacking factor is developer time and
+motivation.  As of this writing (2020-09) I (Mother Mychaela) am not able to
+devote any significant time to handset firmware work because I need to focus on
+bringing FC Tango and Caramel2 hardware products to market, but once I get past
+this current work, I may be able to refocus on handset fw.
 
-3) Change the "small screen" UI layout from 84x48 to 96x64 pixels (from 6 rows
-   of 14 characters to 8 rows of 16 characters with TI's existing font), and
-   fix the bugs related to displaying this "small screen" (!LSCREEN) UI on a
-   physically larger LCD - we would like to display it on our 176x220 pixel UI
-   development board.
+When and if I start working again in the handset fw direction, my plan of action
+is as follows:
 
-4) Extend the UI code to allow the possibility of COLOURDISPLAY && !LSCREEN,
-   i.e., a small (96x64 pixels) color display like on the C139.  Have this
-   96x64 pixel color UI displayed on our 176x220 pixel UI development board.
+1) Fix the most obvious bugs like the misplaced text line in the small UI config
+   while staying in the Magnetite source tree, but working only in the hybrid UI
+   code base - the old TCS2 version of BMI+MFW that sits on top of a blobs-only
+   old version of G23M PS will not be carried forward.
 
-5) Work on getting the actual UI into shape, keeping the two configurations of
-   176x220 pixel color (future FreeCalypso Libre Dumbphone) and 96x64 pixel
-   color (Mot C139) as actively supported ones.  Do all development on our
-   176x220 pixel UI development board.
+2) Create a new firmware source tree based on Magnetite that keeps only the
+   hybrid config with old clutter removed, allowing bolder changes going
+   forward.
 
-6) Once the UI-enabled firmware works decently on our development board in both
-   176x220 and 96x64 configurations, add native C139 LCD support (not C-Sample
-   emulation) to R2D, adapt Condat's display driver as necessary if we are still
-   using it (if we don't find a way to get rid of it by this point), and run
-   our 96x64 pixel color UI config on real C139 hardware.  At this point we
-   should have practically usable end user FreeCalypso fw on the C139.
+3) Drop the driver-level C-Sample LCD emulation approach, and instead implement
+   a 96x64 pixel B&W logical framebuffer config in R2D.  Display this logical
+   96x64 pix B&W framebuffer on both Luna and C139 physical LCDs.  In both cases
+   the physical LCD color capability will remain unutilized, with all display
+   images being black&white, but so be it.
 
-7) While the less demanding and more casual phone users will be happy with the
-   feeble C139 if it runs our FreeCalypso fw, those of us who desire the
-   Ultimate Awesome Libre Dumbphone will be able to take our 176x220 pixel UI
-   development board and start turning it into an actual FreeCalypso Libre
-   Dumbphone handset.  This will be the point when we can move the ringtone
-   output from the piezo buzzer to the loudspeaker (Melody E1) and start making
-   other changes for better-than-C139 hardware.
+4) Immediately after the previous step the 84x48 pixel UI will appear in the
+   upper left corner of the 96x64 pixel B&W display, with the rightmost 12 and
+   bottommost 16 pixels remaining unused.
+
+5) Drop the 176x220 pixel B&W UI config, leaving only large (176x220 pix) color
+   and "small B&W".  Remove code stanzas specific to the
+   (LSCREEN && !COLOURDISPLAY) combination, and outside of that eliminated
+   combination, make all conditionals based on LSCREEN and not COLOURDISPLAY.
 
-Of course the biggest difficulty with the above plan is that it requires
-designing and building a new piece of hardware as its very first critical step.
-My personal plan is to kill two birds with one stone: design the board in such
-a way that it can be used both as a development board for the above plan and as
-a close-to-final prototype for my desired FC Libre Dumbphone handset - although
-not completely final, as this board would absolutely need to be usable in its
-bare form on a lab bench without plastics, which calls for a somewhat different
-design than a final handset product.
+6) Extend the "small B&W" UI config from 84x48 to 96x64 pixels, i.e., from 6
+   rows of 14 characters to 8 rows of 16 characters with TI's existing font.
+
+7) With the above gymnastics out of the way, work on whipping the actual phone
+   UI into shape, supporting two configurations: large color and small B&W,
+   with Luna hw platform supporting both configs, whereas the small B&W config
+   will also run on C139 hw.
 
-Anyone who disagrees with my approach, anyone who is against designing and
-building new custom hardware at high cost and who is instead interested first
-and foremost in pre-existing hardware targets like Mot C139 is more than welcome
-to delve into the code themselves and try their own hand at fixing the code to
-make it practically usable on the C139.  However, I have to warn you: if you
-spend a significant amount of time working with TI's code and develop an
-affection for it, it is quite possible that you will start to feel the way I do
-in terms of desiring a D-Sample-like platform for development.
+It should be noted that this approach does NOT include any implementation of
+color UI for the small LCD size on Mot C139 and similar low-end platforms.  As
+the plan stands currently, this omission is intentional and is part of effort
+minimization: I need to put some limits on the amount of time and effort I
+invest into project directions that are specific to low-end phones, i.e.,
+project directions that are intrinsically less worthy than my desired
+FreeCalypso Libre Dumbphone as in FreeCalypso handset hardware.
 
 Why Mot C139?
 =============