--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/FC-aftermarket-intro	Sun Jun 11 06:18:53 2023 +0000
@@ -0,0 +1,140 @@
+Running FreeCalypso in aftermarket configurations - introduction
+================================================================
+
+In the context of FreeCalypso family of projects, the term "aftermarket
+configurations" means running FC firmware on alien hardware, primarily Motorola
+C1xx and Pirelli DP-L10, as opposed to proper FreeCalypso development boards.
+Running our firmware on alien hw in aftermarket configs is NOT the primary
+direction in FreeCalypso, has never been and never will be - however, such
+aftermarket configs are supported to a limited extent, and have been so for a
+long time.  The reasons for our continued support of aftermarket configs are as
+follows:
+
+1] Even when you do have proper FreeCalypso hardware such as FCDEV3B, physical
+   portability is a concern.  Development boards such as FCDEV3B and
+   Caramel/Luna are made to be used on a lab bench, complete with an ESD mat,
+   a multi-board arrangement with ribbon cables and a dedicated power supply.
+   OTOH, a simple old phone of either Mot C1xx or Pirelli DP-L10 kind is an item
+   which you can easily take with you anywhere.  Pirelli DP-L10 is ideal for
+   this purpose, thanks to its use of USB for both charging and host computer
+   connection, but even when you have to use Mot C1xx instead (because you don't
+   have a Pirelli phone, or because you need to do some work in the GSM850 band
+   that isn't supported on the Pirelli), it is still far more portable than a
+   "fully proper" development board setup.
+
+2] Those GSM enthusiasts and tinkerers who come from Osmocom background are
+   typically very familiar with Motorola C1xx phones, and typically already have
+   such hardware.  Making it possible to run FreeCalypso firmware on that hw,
+   and making it as easy as possible, opens the door into our FreeCalypso
+   sorority for that target audience.
+
+However, it is important to point out that the combination of running
+FreeCalypso fw on alien hw has significant limitations, compared to both
+standard end user phones and traditional modem development boards, and these
+limitations need to be covered from both directions.
+
+Lack of end user phone functionality
+====================================
+
+In its current state as of this writing (mid-2023), our FreeCalypso firmware is
+NOT capable of functioning as an end user phone!  You *cannot* take a Motorola
+or Pirelli phone, reflash it to FC and expect to continue using it as an end
+user phone in that state - our firmware just isn't there.  We do have a
+minimally-passing functional configuration that runs as an untethered phone,
+with a UI layer that draws on the LCD and accepts control via the keypad, but:
+
+* The smallbw configuration of this handset UI (which is the only config we can
+  run on aftermarket phones) is badly bitrotten and functionally broken compared
+  to the bigcolor config - and the latter requires custom FreeCalypso hw that
+  currently exists only as a very messy multi-board arrangement for lab bench
+  use.
+
+* Even the better bigcolor config, exercised on our Luna development platform,
+  is still very unpolished, far from an end user product, and smallbw is even
+  worse.
+
+Of all aftermarket phone targets, the only hw model for which we have any
+UI-enabled firmware build at all is C139: for that one model we have a
+buildable, flashable and runable smallbw firmware configuration.  (The physical
+LCD on C139 is color, but because it is only 96x64 pixels, compared to 176x220
+needed for bigcolor UI config, we run smallbw instead - a UI config derived by
+slightly extending TI's C-Sample UI design, which was 84x48 pix B&W.)
+
+Our prebuilt C1xx firmware packages include this smallbw firmware for C139, and
+you can flash it into your phone using the present fc-am-toolkit.  However, that
+firmware should be treated as a preview of what may some day become possible,
+NOT as a practically usable solution - you've been warned!
+
+Aside from the just-described preview of maybe-some-day UI-enabled aftermarket
+fw for C139, the much more actively supported FreeCalypso aftermarket firmware
+configuration is voice pseudo-modem, or VPM for short.  FreeCalypso VPM firmware
+configs are available for all 4 aftermarket hw targets: all 3 subfamilies of
+Motorola C1xx, plus Pirelli DP-L10.
+
+When you run FC VPM firmware on a phone (on Mot C1xx it needs to be flashed, on
+Pirelli DP-L10 it runs in RAM without flashing), the phone's display stays dark
+and its buttons do nothing - there is no hw-model-specific LCD driver code
+included in the fw, hence we have no ability to display anything, and there is
+no handset UI layer included in the functional config, hence even though we do
+have a driver for the keypad, there is no action to be taken on button presses
+other than to emit debug traces indicating such.  Instead the phone turns into
+a modem-like device that needs to be controlled via AT commands from the
+connected host computer - hence the name VPM.
+
+VPM compared to proper TI/FreeCalypso modems
+============================================
+
+On traditional modem development boards going back to near the beginning of TI's
+GSM chipset program, and on Calypso-based finished modem products such as the
+embedded GSM modem in Openmoko GTA01/02 smartphones, or Huawei GTM900 or iWOW
+TR-800, there are two Calypso UARTs brought out, not just one.  With traditional
+TI-family modem firmware, Calypso MODEM UART presents a classic ASCII AT command
+interface, complete with CSD, GPRS and GSM 07.10 MUX, while the other Calypso
+UART (called IrDA UART in hw terms, even when no actual IrDA is used) presents
+TI's debug, development and factory production tools interface called RVTMUX.
+
+FreeCalypso VPM is different in that on all of our aftermarket Calypso hw
+targets (Mot C1xx and Pirelli DP-L10), there is only one UART practically
+accessible.  In FreeCalypso we've adopted TI's RVTMUX interface, we make very
+heavy use of it, so we are not giving it up.  Instead our VPM firmware
+sacrifices the traditional all-ASCII AT command channel.  The AT command
+interface to control the GSM MS is still there, but it is encapsulated inside
+RVTMUX binary packets, and unless you are going to develop your own custom
+software speaking this protocol, you need to use FreeCalypso tools rvinterf and
+fc-shell to talk AT commands to FC VPM firmware.
+
+Two major areas of GSM MS functionality that are sacrificed in this arrangement
+are CSD and GPRS.  In our TI-inherited firmware architecture these two
+functional components are optional, i.e., they can be included or excluded in a
+given firmware build, and we set both of them to disabled in our VPM config.
+
+If one were to enable CSD and/or GPRS in a VPM fw build (once upon a time we had
+both enabled, when we were using a binary-only version of the protocol stack,
+with blobs preventing us from changing config options), the resulting firmware
+components will be dead weight, with no ability to make use of them.  In TI's
+architecture both CSD and GPRS (outside of high-end feature phone configs with
+built-in TCP/IP, WAP and MMS) are meant to hook up to the AT command interface
+on the dedicated MODEM UART, complete with data modes, and that part is lost in
+our VPM arrangement.  Therefore, as soon as we deblobbed our protocol stack and
+regained the ability to change its configuration, we adopted our current
+approach of building VPM firmware configs with CSD and GPRS excluded.
+
+Still useful despite the limitations
+====================================
+
+Despite all of its limitations, FreeCalypso VPM firmware running in aftermarket
+configurations on Mot C1xx and Pirelli DP-L10 is still useful enough to justify
+keeping it around, and doing efforts like the present fc-am-toolkit package that
+aim to make it more accessible to GSM hobbyists, enthusiasts and tinkerers.
+With FreeCalypso VPM, you can connect to a GSM network as a subscriber using a
+GSM MS implementation for which you have full source code, as opposed to the
+usual black box, and you can see everything it does.  By watching the debug
+trace in the rvinterf terminal window or log file, you can observe the MS
+searching for the network, all of its registration attempts, and then idle mode
+- you can see how the MS wakes up to listen on PCH, as well as neighbour cell
+measurements and cell reselection.  You can then make test calls and see
+everything that happens: RACH process, entry into dedicated mode with IMM ASS,
+subsequent channel assignments or handovers, speech codec selection made by the
+network etc.  Whichever area you are interested in, you can study that part of
+the source, enable additional traces or make better understanding of the
+existing ones, and even new functionality can be implemented as needed.