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.