# HG changeset patch # User Mychaela Falconia # Date 1686464333 0 # Node ID 873d5f33e8f34307cbf840d6e771655b9fbc6ce9 # Parent 9d7d2fdc733b7e1f55cbcb991b1a67b0801c318c doc: beginning with FC-aftermarket-intro diff -r 9d7d2fdc733b -r 873d5f33e8f3 doc/FC-aftermarket-intro --- /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.