--- a/doc/C139-Howto	Sat Oct 15 23:02:23 2016 +0000
+++ b/doc/C139-Howto	Sun Oct 16 00:01:13 2016 +0000
@@ -16,9 +16,19 @@
 
 ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/compal-flash-boot-for-fc.bin
 
-Because neither FC Citrine nor FC Magnetite implements any phone UI or puts
-anything at all on the LCD, when a C139 phone is flashed with one of our
-firmwares, it will behave very oddly:
+We are currently able to produce two kinds of firmware builds for the C139:
+pseudo-modem or UI demo.  The pseudo-modem configuration is intended for those
+who would really like to play with AT-command-controlled modem firmware on some
+proper Calypso modem hardware like our desired FCDEV3B, but who are using a
+C139 instead out of poverty - a poor man's substitute for proper modem hardware.
+In this configuration the C139 phone's LCD stays dark, the buttons do nothing,
+but the firmware presents TI's RVTMUX interface with FreeCalypso extensions on
+the headset jack serial port.  You connect to this serial interface with
+FreeCalypso host utility rvinterf, and use another FC host utility fc-shell to
+talk AT commands to the pseudo-modem.
+
+If you flash a C139 phone with one of our pseudo-modem firmware builds, it will
+behave in some odd ways which you might not expect:
 
 * Whenever the phone is off but the battery is inserted, even a momentary
   accidental press of the power button will launch a full power-on and firmware
@@ -30,6 +40,14 @@
   So it will just keep running until the battery runs down, once again with the
   LCD dark and no visible indication of any kind that it's on.
 
+In the UI demo configuration (see Handset-configs) the FC-reflashed C139 acts
+*almost* like an end user phone: it can be operated from the keypad without
+being connected to a PC with a serial cable, there is a very rudimentary UI
+presented on the LCD, the phone can be turned on and off with the power button.
+However, battery charging doesn't work, there is not even a working battery
+gauge, and the UI is full of serious bugs.  Thus this fw configuration is
+intended as a DEMO, not something to be inflicted on an actual end user!
+
 Additional considerations are:
 
 * Flashing a given phone back and forth between FreeCalypso and Mot/Compal's
@@ -37,9 +55,9 @@
   FreeCalypso on a C139, it would be the easiest to dedicate a phone
   specifically for FC experiments;
 
-* We haven't got firmware-controlled battery charging working yet, so you will
-  need another phone running one of the official fw versions to charge
-  batteries.
+* We haven't got firmware-controlled battery charging working yet in any of our
+  fw configurations, so you will need another phone running one of the official
+  fw versions to charge batteries.
 
 Converting a phone to FreeCalypso
 =================================
@@ -65,21 +83,26 @@
 * Once you are in with fc-loadtool, i.e., at the loadtool> prompt, reflash the
   boot sector with the FreeCalypso version:
 
-loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
+  loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin
 
 * Flash whichever FreeCalypso firmware image you would like to play with, e.g.:
 
-loadtool> flash erase 0x10000 0x230000
-loadtool> flash program-bin 0x10000 fwimage.bin
+  loadtool> flash erase 0x10000 0x230000
+  loadtool> flash program-bin 0x10000 fwimage.bin
+
+  Please note that the image size will be different depending on which
+  configuration of which FC fw project you would like to play with, so adjust
+  the second number in the flash erase command accordingly - it needs to be
+  the fw image size rounded up to a 64 KiB sector boundary.
 
 * Erase the flash sectors to be used for the FFS (flash file system) by
   FreeCalypso firmwares:
 
-loadtool> flash erase 0x3C0000 0x30000
+  loadtool> flash erase 0x3C0000 0x30000
 
 * Exiting fc-loadtool cleanly will cause it to power off the phone:
 
-loadtool> exit
+  loadtool> exit
 
 Reflashing between different FreeCalypso firmwares
 ==================================================
@@ -117,9 +140,19 @@
 fc-loadtool entry.  Because there is no fc-loadtool running on the host end of
 the serial cable, the boot path will *not* be diverted in the bootloader, and
 the main fw image will run - and this time it will be the FreeCalypso firmware
-you have compiled and flashed.  The phone's LCD will remain dark as there is no
-LCD driver code in this firmware, but you will see trace output in the rvinterf
-window, telling you that the fw is running.
+you have compiled and flashed.  If the fw you have flashed is the UI demo
+configuration, the phone must have *NO* SIM in it the first time you boot it.
+UI-enabled fw configuration automatically bring up the GSM radio and try to
+connect to the default network on boot if there is a SIM present, and you don't
+want your firmware trying to connect to a real live GSM network when you haven't
+initialized your FFS yet.  If the fw you have flashed is one of the AT-command-
+controlled pseudo-modem configurations, then you don't need to worry if the SIM
+is there or not on your first boot - just don't command it to connect to a
+network until you have initialized the FFS.
+
+If you have flashed a non-UI firmware version, the phone's LCD will remain dark
+as there is no LCD driver code in this firmware, but you will see trace output
+in the rvinterf window, telling you that the fw is running.
 
 Before you do anything else, you will need to run fc-fsio and initialize the
 aftermarket FFS for our firmware:
@@ -131,8 +164,9 @@
 or
 fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)
 
-After you've initialized your FFS as above, you can exit fc-fsio, run fc-shell
-and try some AT commands:
+After you've initialized your FFS as above, you should exit fc-fsio, and your
+next steps will depend on which fw configuration you are playing with.  If it's
+the sans-UI pseudo-modem configuration, run fc-shell and try some AT commands:
 
 AT+CMEE=2	-- enable verbose error responses
 AT+CFUN=1	-- enable radio and SIM interfaces
@@ -145,29 +179,6 @@
 momentary accidental press of the power button will cause it to power on and
 boot, but there will be absolutely no visual indication, as the LCD stays dark.
 
-Magnetite-specific notes
-========================
-
-Just like FC Citrine, FC Magnetite currently supports only AT command operation
-via fc-shell; the C-Sample UI hack we have built earlier in tcs211-c139 has NOT
-been incorporated into Magnetite - at least not yet.
-
-When compiling our Magnetite firmware for the C139 target, you will need to
-select the l1reconst configuration - it is the only currently available
-configuration that works on this target.  Therefore, you configure.sh command
-should be:
-
-./configure.sh c139 l1reconst
-
-See the Compiling write-up for more details.
-
-Because we have not deblobbed the G23M firmware component yet (the l1reconst
-configuration uses G23M binary blobs from TCS211/Sotovik), your Magnetite fw
-build will include FAX_AND_DATA and GPRS functionality.  In the FreeCalypso
-environment where we are not doing WAP or MMS this functionality can only be
-exercised on targets that bring out a classic modem UART with the classic AT
-command interface to the external host, but Mot C139 is not one of those
-targets - hence on the C139 all FAX_AND_DATA and GPRS code is nothing but dead
-weight.  We will only be able to remove this dead weight when and if we fully
-deblob all of L1 and G23M, so it will be a while before we get there, and we'll
-have to carry the dead weight until then.
+If you are playing with the UI demo firmware, after you have initialized your
+FFS, you can power the phone off with the power button, insert a SIM, power it
+back on and play with the primitive UI.