This semi-source tree contains a hacked version of TI's TCS211 firmware that
has been made to run on the Motorola C139.  The UI part of TI's reference fw
has not been ported over yet, hence the version presented here currently builds
and works only in the modem-like ACI configuration, i.e., control via AT
commands only.

TI's original fw was/is designed to make use of two UARTs, one for the classic
AT command interface and the other for their RVTMUX debug/calibration/etc
interface.  Unfortunately though, our present target hw has only one UART
practically accessible (Calypso's MODEM UART brought out on the headset jack),
thus the classic AT command interface had to be sacrificed.  Instead the AT
command interface (which is currently the only way to control the GSM
functionality in the absence of a UI ported to the present target) needs to be
accessed through the RVTMUX binary packet interface using FreeCalypso host
tools rvinterf and fc-shell.

The present fw has been built from a semi-src (half source, half binary objects)
TI firmware release which was made for some manufacturer that made GSM/GPRS
modems, rather than voice handsets, hence the present configuration is
unfortunately highly suboptimal for our use case.  The entire mass of code
supporting CSD, fax and GPRS data services is included and cannot be removed
because that part of the fw is in binary blobs, but all this code is pure dead
weight in the present configuration: the phone UI layer (when we get around to
porting it) won't make any use of data functionality (nowhere near enough
resources on this hw to implement a WAP browser or MMS), and because we had to
give up the standard AT command channel, the option of having the phone dual-
function as a laptop-tethered modem is not available either.

Building the present firmware from semi-source requires using a Wine environment
to run TI's proprietary compiler toolchain and other build tools which exist
only as M$ Windows binaries.  The necessary environment can be downloaded here:

ftp://ftp.freecalypso.org/pub/GSM/TI_src/wine/

You will also need the mokosrec2bin utility, which is needed for one of the
finishing steps in generating an image that can be usefully flashed into a C139:

ftp://ftp.freecalypso.org/pub/GSM/GTA02/gsm-fw/mokosrec2bin.c

Once you have the necessary build tools installed, you should be able to
compile the present fw by running first winebuild.sh, then copyout.sh in the
g23m subdirectory.  Then you can flash this firmware you just built into an
actual C139 phone with FreeCalypso host tool fc-loadtool.  Flash sector 0 (the
brickable boot sector) needs to contain our patched bootloader version
compal-flash-boot-for-fc.bin (this brickable sector only needs to be rewritten
once when first installing some FreeCalypso fw on the phone; no need to touch
this dangerous sector on subsequent updates from one FC fw version to another),
and the main fw image needs to be flashed starting at 0x10000.  The image to
flash is aci-build.progbin - it has TI's bootloader code stripped off, as we
are using compal-flash-boot-for-fc instead.

The phones in question have a data structure in flash at 0x3FC000 (in an 8 KiB
short sector) that must contain factory programming, including each phone's
unique IMEI and RF calibration values.  However, we don't understand how to
grok this data structure.  Therefore, our firmware features the following
points of inconvenience:

* You have to set your own IMEI.  It's entirely up to you whether you set the
  same IMEI as the phone had originally or a different one, but our fw has no
  way of reading the original from Mot/Compal's factory flash programming.
  You probably won't be able to connect to a live commercial GSM network until
  you set some IMEISV which the network will accept as valid.

* Because Mot/Compal stored their RF calibration values in some format
  (different from TI's) which we can't grok, a phone running our aftermarket fw
  will run UNCALIBRATED.  It may have difficulty connecting to networks if it
  can't acquire the frequency burst lacking VCXO calibration, and the Tx power
  levels are almost certainly wrong (out of spec) - BEWARE!

* Our fw does not even know whether your C139 is the 900+1800 MHz version or
  850+1900 MHz.  You will need to set the correct rfcap configuration at the
  same time when you set your IMEISV.

Flashing and usage instructions
===============================

If you are not scared off by all of the above and you still wish to try this
experimental fw on your C139, you can install it as follows:

1. Connect to the phone with fc-loadtool, preceded by tfc139 if necessary -
   see loadtools documentation.

2. If the C139 in question does not already have some other FreeCalypso fw
   version in its flash, replace the bootloader:

loadtool> flash erase-program-boot compal-flash-boot-for-fc.bin

3. Flash the main fw image:

loadtool> flash erase 10000 220000
loadtool> flash program-bin 10000 aci-build.progbin

(If your serial cable setup supports the special GSM high baud rates,
 you can speed the process up by issuing a baud 406250 or baud 812500
 command first.)

4. Erase the sectors where our firmware's non-volatile flash file system
   (aftermarket FFS configuration) will reside:

loadtool> flash erase 3C0000 30000

5. Cleanly end your fc-loadtool session, which will power the phone off:

loadtool> exit

Now your phone has FreeCalypso firmware in its flash, but it no longer works
as a "normal" phone.  Gotchas to be aware of:

* Mot/Compal's original firmwares (like all other production phone fws)
  implement on a guard on the power-on button: you have to hold it down for a
  little while to confirm that you really mean to power the phone on; a
  momentary press of the power-on button is interpreted as spurious by standard
  fws, and they power the phone back off.  However, the present hack-fw has no
  such guard, hence even a momentary press of the power-on button will launch
  the firmware into full boot.

* Because our present fw has no UI, the LCD will remain dark and the buttons
  won't do anything.  A momentary press of the power button will turn the phone
  on, but you won't know that it's on - it will just silently and invisibly eat
  the battery.  Furthermore, the only way to power it off (aside from yanking
  the battery) is to connect a serial cable and send a poweroff command via
  fc-shell - there is no way to command a power-off from the keypad.  (Pressing
  and holding the power button produces some kind of hang or crash - to be
  investigated - instead of a proper power-off.)

* The present fw includes TI's LCC (low-cost charger) code that came with
  TCS211, but it is not clear whether or not this code drives the charging
  circuitry correctly for Mot/Compal's hardware.  Therefore, plan on having
  the phone with FC firmware draining batteries only, and have another phone
  running official fw (or a standalone charger) to charge them back up.

What all of these gotchas practically mean is that the phone with FC fw in it
should not have a battery inserted on a regular basis; instead you should use
it as follows:

1. Begin each FC hacking session by inserting the SIM you wish to use, then
   inserting the battery - but don't touch the power button yet.

2. Connect the serial cable and run rvinterf on your host.

3. Press the power button, and see the firmware boot output in the rvinterf
   window.

4. Run fc-shell, fc-fsio, fc-tmsh etc as desired during your hacking session.

5. End the session by yanking the battery, killing rvinterf and stowing away
   your serial cable.

First session
=============

Remember the notes above regarding this fw not being able to read the factory
IMEI record?  That's right, you'll need to set your own IMEISV.  Furthermore,
because we are using our own "aftermarket" FFS configuration for non-volatile
data storage (you erased the flash sectors to be used for this FFS when you
flashed the fw with fc-loadtool, or at least you should have), this FFS needs
to be initialized before the fw can function correctly.

Initialize your FFS as follows:

1. Connect the serial cable, run rvinterf and boot the fw as above.

2. Before you try issuing any AT commands via fc-shell, run fc-fsio first.

3. Initialize the FFS via fc-fsio as follows:

fsio> format /
fsio> mk-std-dirs
fsio> set-imeisv fc XXXXXXXX-YYYYYY-ZZ (punctuation optional, place anywhere)
fsio> set-rfcap dual-eu (if you have 900+1800 MHz hardware)
or
fsio> set-rfcap dual-us (if you have 850+1900 MHz hardware)

After the above steps, you can exit fc-fsio (or leave it running), run fc-shell
and exercise the GSM MS via AT commands - try connecting to a network!  With my
US band C139 (former Tracfone, now a Crackfone) on Operator 310260's network,
both voice calls and SMS work like a charm.  YMMV.