Running FreeCalypso firmware on the Motorola C139
=================================================

Mot C139 phones are brickable - because the Calypso boot ROM is disabled by PCB
wiring, the ability to reflash a phone with new firmware critically depends on
there being a particular kind of boot code in flash sector 0 at all times - a
particular kind of boot code that allows the boot process to be interrupted and
diverted to external code loaded via the headset jack serial port.

The FreeCalypso project has adopted one specific version of the flash sector 0
boot code (produced by applying a binary patch to one of Compal/Motorola's
original versions) for use with all of our firmwares for this target.  No matter
which FreeCalypso firmware you are running - Citrine, Magnetite or tcs211-c139 -
you flash your FC fw image at offset 0x10000 while keeping this boilerplate boot
code at the beginning of the flash:

ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/compal-flash-boot-for-fc.bin

We are currently able to produce two kinds of firmware builds for the C139:
pseudo-modem or UI demo.  The pseudo-modem configuration is intended for those
who would really like to play with AT-command-controlled modem firmware on some
proper Calypso modem hardware like our desired FCDEV3B, but who are using a
C139 instead out of poverty - a poor man's substitute for proper modem hardware.
In this configuration the C139 phone's LCD stays dark, the buttons do nothing,
but the firmware presents TI's RVTMUX interface with FreeCalypso extensions on
the headset jack serial port.  You connect to this serial interface with
FreeCalypso host utility rvinterf, and use another FC host utility fc-shell to
talk AT commands to the pseudo-modem.

If you flash a C139 phone with one of our pseudo-modem firmware builds, it will
behave in some odd ways which you might not expect:

* Whenever the phone is off but the battery is inserted, even a momentary
  accidental press of the power button will launch a full power-on and firmware
  boot - without any visible indication whatsoever as the LCD stays dark!

* Once the firmware has booted from a press of the power button - even a
  momentary accidental press - there is no way to make it shut down and power
  off except by sending a power-off command via the headset jack serial port.
  So it will just keep running until the battery runs down, once again with the
  LCD dark and no visible indication of any kind that it's on.

In the UI demo configuration (see Handset-configs) the FC-reflashed C139 acts
*almost* like an end user phone: it can be operated from the keypad without
being connected to a PC with a serial cable, there is a very rudimentary UI
presented on the LCD, the phone can be turned on and off with the power button.
However, battery charging doesn't work, there is not even a working battery
gauge, and the UI is full of serious bugs.  Thus this fw configuration is
intended as a DEMO, not something to be inflicted on an actual end user!

Additional considerations are:

* Flashing a given phone back and forth between FreeCalypso and Mot/Compal's
  official firmware is a royal pita, so if you are going to play with
  FreeCalypso on a C139, it would be the easiest to dedicate a phone
  specifically for FC experiments;

* We haven't got firmware-controlled battery charging working yet in any of our
  fw configurations, so you will need another phone running one of the official
  fw versions to charge batteries.

Converting a phone to FreeCalypso
=================================

Start by installing FreeCalypso host tools on your PC/laptop or whatever host
you will use to talk to C139 phones, if you haven't already.  If you are
starting with an unhacked C139 phone running one of the official firmware
versions, the procedure for flashing and bringing up FreeCalypso for the first
time is as follows:

* Note down your phone's factory IMEI.  After you get FreeCalypso firmware
  flashed and running, you will need to set your own IMEISV, as our fw doesn't
  know how to grok Mot/Compal's flash data structures where they store theirs.
  You can set whatever IMEISV you like, but if you would like to keep the
  factory one, it would be the easiest to have it noted down on a piece of
  paper.  If you have a labelmaker, you can print a sticky label with the IMEI
  and stick it on the side of the phone where you can easily see it later while
  playing with FreeCalypso.

* Get in with fc-loadtool, preceded with tfc139 if necessary - see FC host tools
  documentation.

* Once you are in with fc-loadtool, i.e., at the loadtool> prompt, reflash the
  boot sector with the FreeCalypso version:

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

* Flash whichever FreeCalypso firmware image you would like to play with, e.g.:

  loadtool> flash erase 0x10000 0x230000
  loadtool> flash program-bin 0x10000 fwimage.bin

  Please note that the image size will be different depending on which
  configuration of which FC fw project you would like to play with, so adjust
  the second number in the flash erase command accordingly - it needs to be
  the fw image size rounded up to a 64 KiB sector boundary.

* Erase the flash sectors to be used for the FFS (flash file system) by
  FreeCalypso firmwares:

  loadtool> flash erase 0x3C0000 0x30000

* Exiting fc-loadtool cleanly will cause it to power off the phone:

  loadtool> exit

Reflashing between different FreeCalypso firmwares
==================================================

By the conventions established in the FreeCalypso project, all of our firmwares
for the C139 target have the following in common:

* They all stay out of the boot sector and expect to receive control from the
  boot code in the same manner (boot entry point at 0x10058, exception vectors
  at 0x10000), thus there is no need to reflash the dangerous boot sector when
  going from one FC firmware to another.

* They all use the same aftermarket FFS configuration of 3 sectors of 64 KiB
  each (64x3) at 0x3C0000.  This FFS location is deliberately different from
  the one used by Mot/Compal's firmwares, eliminating the possibility of one fw
  trying to use the FFS created by the other, and by putting our FFS toward the
  end of the flash we maximize the amount of flash space available for our
  firmware code images.  But even though we don't share our FFS with
  Mot/Compal's official firmwares, we do share the same FFS between all of
  FreeCalypso firmware projects - thus once you have initialized your FFS (see
  below) with one FC firmware version, it will work with the others as well.

If you need to reflash your C139 from one FC firmware version to another,
simply get in with fc-loadtool -h compal (no more need for the inefficient
-c 1003 or -c 1004 options or for tfc139) and reflash just the fw image part:

loadtool> flash erase 0x10000 0x230000
loadtool> flash program-bin 0x10000 fwimage.bin

First boot of the firmware
==========================

Connect the serial cable, but instead of running fc-loadtool, run rvinterf.
Press the red power button on the phone briefly just like you would for
fc-loadtool entry.  Because there is no fc-loadtool running on the host end of
the serial cable, the boot path will *not* be diverted in the bootloader, and
the main fw image will run - and this time it will be the FreeCalypso firmware
you have compiled and flashed.  If the fw you have flashed is the UI demo
configuration, the phone must have *NO* SIM in it the first time you boot it.
UI-enabled fw configuration automatically bring up the GSM radio and try to
connect to the default network on boot if there is a SIM present, and you don't
want your firmware trying to connect to a real live GSM network when you haven't
initialized your FFS yet.  If the fw you have flashed is one of the AT-command-
controlled pseudo-modem configurations, then you don't need to worry if the SIM
is there or not on your first boot - just don't command it to connect to a
network until you have initialized the FFS.

If you have flashed a non-UI firmware version, the phone's LCD will remain dark
as there is no LCD driver code in this firmware, but you will see trace output
in the rvinterf window, telling you that the fw is running.

Before you do anything else, you will need to run fc-fsio and initialize the
aftermarket FFS for our firmware:

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 you've initialized your FFS as above, you should exit fc-fsio, and your
next steps will depend on which fw configuration you are playing with.  If it's
the sans-UI pseudo-modem configuration, run fc-shell and try some AT commands:

AT+CMEE=2	-- enable verbose error responses
AT+CFUN=1	-- enable radio and SIM interfaces
AT+COPS=0	-- register to the default GSM network

When you are done, you can power the phone off by sending a 'poweroff' command
through fc-shell.  The only other way is to yank the battery, and doing the
latter is recommended anyway: when a phone with the present hack-firmware
flashed into it is powered off but still has the battery inserted, even a
momentary accidental press of the power button will cause it to power on and
boot, but there will be absolutely no visual indication, as the LCD stays dark.

If you are playing with the UI demo firmware, after you have initialized your
FFS, you can power the phone off with the power button, insert a SIM, power it
back on and play with the primitive UI.