--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Voice-pseudo-modem	Sat Jan 13 00:40:14 2018 +0000
@@ -0,0 +1,127 @@
+Back when TI's TCS211 fw existed in the traditional world of phone handset and
+cellular modem manufacturers, there were only two principal classes of target
+devices for it: handsets and modems.  The former have local UI hardware (LCDs
+and keypads) and run firmware that works with this UI hw, the latter have no
+such hw and run firmware that expects to be controlled by an external host via
+AT commands.
+
+But the peculiar circumstances under which our FreeCalypso family of projects
+operates give rise to a third possibility: what happens if one were to run
+non-UI-capable firmware that expects control via AT commands on a hardware
+target device that was originally designed to be an end user phone handset, in
+our case either Motorola C1xx or Pirelli DP-L10?  The result is what I call a
+voice pseudo-modem (VPM): the phone's LCD stays dark, the buttons do nothing
+and the device expects to be controlled via AT commands as if it were a modem
+like the one in GTA01/02 smartphones, but there is no practically usable way to
+make use of any data services, only voice and SMS, hence my VPM term.
+
+It needs to be noted clearly that the VPM hack described in this article is NOT
+a substitute for proper modem hardware - if your area of interest is Standard
+Modem functionality (the full set of GSM and GPRS services accessed via AT
+commands), then you need a proper hardware platform for it, such as our FCDEV3B
+hardware product.  However, support for VPM operation in FreeCalypso exists for
+the following purposes:
+
+* On some hw targets the VPM configuration can be an intermediate stepping stone
+  toward potential future UI (see the Handset-goal article) - this situation
+  holds on the C139.
+
+* Being able to run FreeCalypso fw in the VPM configuration on Mot C1xx hw that
+  many people already have and that may still be readily and cheaply available
+  makes our firmware accessible to those who are not able to afford our
+  expensive FCDEV3B hardware.
+
+* If you have a Pirelli DP-L10 phone (now very rare and hard to get, but were
+  readily available in early 2013 when I started FreeCalypso): while there is
+  unfortunately very little chance of being able to turn it into a practically
+  usable Libre Dumbphone with FreeCalypso (the unwanted extra chips sans docs
+  which we don't know how to power down are a killer), running FreeCalypso fw
+  on the Pirelli in the VPM configuration is so easy and convenient that I do
+  it all the time during development and testing.
+
+Building firmware for VPM operation
+===================================
+
+The following two firmware build configurations (in the ./configure.sh sense)
+are appropriate for VPM usage:
+
+hybrid-vpm	This is the TCS2/TCS3 hybrid config (see the Modem-configs
+		article) that has all data services (CSD, fax and GPRS)
+		disabled and FCHG (new FreeCalypso battery charging driver)
+		enabled.  The removal of data services code makes the firmware
+		image size and its RAM usage significantly smaller than all
+		other configurations, making hybrid-vpm the smallest of all
+		FC Magnetite firmware configs.
+
+l1reconst-chg	This is a variant of the stable l1reconst config (again, see
+		the Modem-configs article) that has our FCHG battery charging
+		driver enabled.  Because this config uses the TCS211 blob
+		version of the G23M PS, data services cannot be disabled, and
+		the associated code sits in the firmware image as dead weight.
+		Thus this l1reconst-chg config produces much heavier fw images
+		than hybrid-vpm, and should only be used when you suspect a bug
+		in the new TCS3 G23M or ACI code and would like to run the old
+		TCS2 version for comparison.
+
+Mot C139/140 phones have enough flash and RAM to run the l1reconst-chg config
+(with data services code as non-exercisable dead weight), but the more basic
+C11x/12x models (the ones with black&white LCDs) have smaller memories, and the
+only FC Magnetite config that is small enough to fit into their tiny flash and
+XRAM capacity is hybrid-vpm.  As of this writing there is no official support
+for the C11x target yet, but it is currently under investigation, now that we
+have a functional firmware config that is small enough to fit.
+
+Playing with FreeCalypso VPM on C1xx phones
+===========================================
+
+If a Mot C11x phone is flashed with a FreeCalypso firmware image in the VPM
+configuration (see C139-Howto for the messy details of how to do it), it will
+behave as follows:
+
+* The LCD will remain dark and the buttons will do nothing no matter what.
+
+* If you plug in Motorola's charging adapter (it's a regulated 5 VDC power
+  source, but with a non-USB connector) and you had properly installed the
+  charging config file when creating the aftermarket FFS for FreeCalypso, the
+  battery will charge.  When you unplug the charging adapter, if there is no
+  host computer running FC host program rvinterf connected to the phone
+  serially, the phone will power off some 60 to 80 s after the charger unplug.
+
+* If you press the power button while the phone is off, even momentarily, the
+  phone will power on and boot (with nothing on the LCD as usual), but if the
+  headset jack serial port is not connected to a computer running rvinterf, the
+  firmware will execute a power-off after at most 80 s.
+
+* In order to make the phone-turned-VPM do anything useful, you will need to
+  connect the headset jack serial port to a host computer running FC host tools,
+  run rvinterf to keep the phone alive (keep it from automatically powering
+  off), and use FC host utility fc-shell to issue AT commands to it over the
+  RVTMUX channel managed by rvinterf.
+
+* The phone will remain on (i.e., the fw won't execute an automatic power-off)
+  for as long as there is either a charging power adapter plugged in or a
+  connected host computer running rvinterf - if there is no charging power,
+  the fw will send periodic keepalive queries to check for the presence of a
+  connected rvinterf process.
+
+Playing with FreeCalypso VPM on a Pirelli DP-L10
+================================================
+
+There are two ways in which one can play with FC VPM firmware on a Pirelli:
+
+* FC VPM fw can be flashed into the phone just like on Mot C1xx.  To make this
+  approach sensible, you will also need to craft and install a charging config
+  file that will cause our FCHG driver to initiate the charging process
+  automatically when the battery voltage falls below some sensible threshold,
+  without requiring manual charging start via AT@CHG=1.  In this case the
+  reflashed phone will behave like C1xx in the previous section, except that
+  the charging power source and the host computer connection are one and the
+  same in the case of Pirelli's USB.
+
+* The other approach is to keep Pirelli's original fw in the flash, let the
+  phone function normally when not in the middle of a FreeCalypso VPM session,
+  and load our FC VPM fw into RAM via fc-xram, making use of this phone's huge
+  RAM that can hold an entire functional fw image without flashing.  This is
+  the Mother's preferred method.
+
+See the Pirelli-Howto article for the details.