Running FreeCalypso firmware on Motorola C1xx phones
====================================================

Before we begin, it needs to be noted that running FreeCalypso fw on a C1xx
phone is very much akin to xenotransplantation: Mot C1xx hardware is an alien
to our FreeCalypso family (our native hw targets are those made by TI, Openmoko
and us, not Motorola or Compal), and our non-Compal-based, non-Mot-based
FreeCalypso fw is equally alien to the C1xx phones.  The xenotransplantation
procedure of converting a C1xx phone to FreeCalypso is highly unnatural, and
involves a large number of cumbersome manual steps - you've been warned.

Preparing the host system
=========================

Firmware flashing on Mot C1xx phones is accomplished through the headset jack
via a special cable.  There is no need to disassemble the phone in any way or
to do any soldering or other hardware surgery, but you will need a host system
to run the multitude of special software tools that are involved in the
procedure.  You will need to begin by installing FreeCalypso host tools; the
current version at any given moment can be found at this URL:

ftp://ftp.freecalypso.org/pub/GSM/FreeCalypso/fc-host-tools-latest.tar.bz2

You will also need our battery charging configuration files:

https://bitbucket.org/falconian/fc-battery-conf

Run 'make install' in the fc-battery-conf tree to add the battery charging
configuration files to your FC host tools installation under /opt/freecalypso.

Flash backup and data gathering
===============================

Before you begin the actual conversion of your C1xx phone to FreeCalypso, you
will need to gather the following pieces of information:

* The phone's IMEI - we don't know how to extract it out of Mot/Compal's non-TI
  flash data structures, so you will have to reset it manually after the
  firmware change.  Of course you can set your "new" FreeCalypso IMEI to
  whatever you feel like, but if you wish to keep the original factory-assigned
  one, you will need to note it down manually, either from the sticker inside
  the battery compartment (*very* hard to read!) or by booting the phone up
  with its original fw prior to the conversion, entering *#06# and reading it
  from the display.

* Your specific phone's factory RF calibration values: you will need to make a
  dump of your phone's flash memory (also serves as a backup, always a good
  thing to have) with fc-loadtool and extract the numbers of interest with our
  c1xx-calextr utility, which is part of the new FC host tools.

* You need to know whether your phone has 900+1800 MHz or 850+1900 MHz bands -
  you will need to communicate this information to the new fw after the
  conversion.  To the best of our knowledge, all C11x/12x and C140 phones have
  900+1800 MHz bands, but C139 phones have been made in both versions.  On the
  phones that have passed through our hands so far, the first two digits of the
  IMEI have been 35 on 900+1800 MHz phones and 01 on 850+1900 MHz ones.

* For the lower C1xx subfamilies only: you need to know whether your phone has
  2 MiB or 4 MiB flash.  To the best of our knowledge, all C139/140 phones have
  4 MiB flash, but C11x have been seen with both 2 MiB and 4 MiB flashes.  The
  flash memory size will be autodetected by fc-loadtool as part of making the
  flash dump.  C155 and C156 phones have 8 MiB flash.

The Mother's method for keeping track of these per-phone bits of information is
to create a separate directory for each phone with the IMEI as the directory
name; the flash dump and the RF calibration bits extracted from it will then
reside in that directory, while the IMEI is in the name of the directory itself.

Once you have created your per-phone directory and cd'ed into it, you are ready
to run fc-loadtool to capture the flash dump.  The phone needs to be off, but
the battery needs to be present and have some charge in it; with the phone off,
connect the serial cable between your host computer and the phone's headset
jack, and run fc-loadtool as follows:

C11x/12x: fc-loadtool -h compal /dev/ttyXXX
C139/140: fc-loadtool -h compal -c 1004 /dev/ttyXXX
C155/156: fc-loadtool -h c155 /dev/ttyXXX

Change /dev/ttyXXX to the serial or USB-serial device corresponding to your
serial cable.  With the serial cable connected, the phone in the powered-off
state and the fc-loadtool process running and waiting for the phone, press the
red power button on the phone - a momentary press is sufficient and recommended.

Once the phone boots the loadagent code fed to it serially by fc-loadtool and
you land at the loadtool> prompt, issue the following command:

flash dump2bin flashdump.bin

Given this command, fc-loadtool will autodetect whether your phone has 2 MiB or
4 MiB flash (for the lower C1xx subfamilies), then make a dump of the complete
content of this flash memory and save it in a file named flashdump.bin in the
current directory.  When this operation completes, exit the loadtool session
with the exit command - it will also cleanly power the phone off.

The next step is to extract the RF calibration values.  Run a command of the
following form:

c1xx-calextr -b rfbin flashdump.bin <offset>

For the lower C1xx subfamilies, change <offset> to 0x1FC000 if your phone has
2 MiB flash (the size of flashdump.bin is 2097152 bytes) or 0x3FC000 if it has
4 MiB flash (the size of flashdump.bin is 4194304 bytes).  For C155/156 the
correct offset is 0x7E0000.  The stdout scribbles from c1xx-calextr will
indicate which per-band calibration records it finds (from which you can tell
if the phone has 900+1800 MHz or 850+1900 MHz bands if you didn't have this
knowledge already), and a directory named rfbin will be created, containing the
correct subtree of directories and files which will need to be uploaded into
the new FreeCalypso flash file system (FFS) under /gsm/rf after the firmware
change.

Selecting and building the desired firmware config
==================================================

There is only one FC Magnetite firmware configuration for C11x/12x phones, but
for the better C139/140 phones (or for C155/156) there are several to choose
from.  The following two configs are the currently recommended ones:

hybrid-vpm	This config is available for all 3 C1xx subfamilies, although
		the actual fw images are different for each.  In this
		configuration the converted phone acts not as an end user phone,
		but as a voice pseudo-modem that needs to be controlled by a
		host computer via a serial cable to do anything interesting.
		See the Voice-pseudo-modem article for more information.

hybrid-ui-vo	This config is available only for the C139/140 target, not for
		the other two.  This configuration includes the UI layers, thus
		when a C139/140 phone runs this firmware, it is able to function
		as an untethered phone without a host computer connection.
		However, please be warned that this proof-of-concept UI is
		nowhere close to being practically usable - see the
		Handset-goal article for more info.

Both of the above are hybrid configurations in that they use the new TCS3
versions of the G23M protocol stack and ACI (Application Control Interface)
firmware components grafted on top of the TCS211 chipsetsw foundation, resulting
in a fully built-from-source configuration without major blob components.  The
UI layers BMI and MFW in the UI-enabled hybrid-ui-vo config also come from the
new TCS3 source, not the old version of unknown origin.  They are "voice only"
configs in that CSD, fax and GPRS functions are disabled - these functions
cannot be made use of on Mot C1xx phones, and disabling them significantly
reduces the weight of the firmware.

For the C139 and C155 targets (but not for C11x/12x), it is also possible to
build some of the older configs that use the old binary blob version of the
G23M PS component and the corresponding old versions of ACI, MFW and BMI on top
of it - however, those configuration are now officially deprecated except for
only two remaining use cases which do not apply to Mot C1xx targets, hence they
are no longer supported officially.

Thus we have a total of 4 possible build configurations, one for the C11x/12x
target, 2 for C139/140 and 1 for C155/156:

./configure.sh c11x hybrid-vpm
./configure.sh c139 hybrid-vpm
./configure.sh c139 hybrid-ui-vo
./configure.sh c155 hybrid-vpm

See the Compiling article for more information on how to compile your own
firmware image in one of the above configurations.

Bootloader change on the lower C1xx subfamilies
===============================================

This section applies ONLY to C11x/12x and C139/140 subfamilies; it does NOT
apply to the C155/156 subfamily.

If this is your first time converting a given lower-C1xx phone from its original
firmware to FreeCalypso (as opposed to updating from an earlier FC firmware
version), you will also need the compal-flash-boot-for-fc.bin bootloader image
in addition to the main fw image you just built:

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

(If you are working with a binary release package that has prebuilt firmware
 images, the compal-flash-boot-for-fc.bin image is also included in the
 package.)

Mot C1xx 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 family of projects 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
these phones.  We use the same FC-C1xx bootloader on both C11x/12x and C139/140
phones: the official bootloader versions are different between the two (and
moreover, each particular official fw version comes with its own bootloader
version), but the simpler bootloader version which we took from one particular
C11x fw version works perfectly well on the C139 as well, hence we've adopted
it for all combinations.

Once you have our compal-flash-boot-for-fc.bin image flashed in sector 0, you
can then flash whichever FC firmware image you like at offset 0x10000 without
having to touch the dangerous boot sector.

On C155/156 phones the situation is a little different: they are also brickable
with the Calypso boot ROM disabled, but Motorola's original bootloader on these
phones is significantly different from the one on the lower C1xx subfamilies,
and they use a different flash layout: the bootloader in the first 8 KiB sector,
unused flash space between 0x2000 and 0x20000, and the main fw image starting
at 0x20000.  Our FC firmwares for the C155/156 target are built to be flashed
at 0x20000 just like Mot's official ones, and they are designed to receive
control from Mot's original bootloader on this target.

Converting the phone to FreeCalypso fw
======================================

If you are starting with an unhacked C1xx phone running one of the official
firmware versions, the procedure for flashing and bringing up FreeCalypso for
the first time is as follows - *after* you have done all of the preparatory
steps described in the preceding sections:

* Have your phone's battery fully charged - although you will regain the
  ability to charge it with FreeCalypso fw when the conversion is fully
  complete (not just the flashing part, but also the subsequent FFS
  initialization), your phone will not have this charging ability while you are
  in the middle of the xenotransplantation procedure.

* Get in with fc-loadtool just like you did when you made the dump of your
  phone's flash memory for backup and RF calibration data extraction.

* If you are operating on a C11x/12x or C139/140 phone, reflash the boot sector
  with our FreeCalypso version:

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

  DO NOT flash compal-flash-boot-for-fc.bin into C155/156 phones, it is ONLY
  for the lower C1xx subfamilies!

* To flash whichever FreeCalypso firmware image you would like to play with,
  execute the flashing script which the fw build system produced along with the
  actual image:

  loadtool> exec flash-script

* Erase the flash sectors to be used for the FFS (flash file system) by
  FreeCalypso firmwares; the specific command depends on whether your phone has
  2 MiB, 4 MiB or 8 MiB flash.  On 2 MiB flash phones:

  loadtool> flash erase 0x1C0000 0x30000

  Or on 4 MiB flash phones:

  loadtool> flash erase 0x3C0000 0x30000

  Or on 8 MiB flash C155/156 phones:

  loadtool> flash erase 0x700000 0xD0000

* 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 family of projects, all of
our firmwares for C11x and C139 targets 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 on 4 MiB flash phones, or at 0x1C0000 on 2 MiB flash
  phones.  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 C1xx phone 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> exec flash-script

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 configurations 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 (run it without the
-p option to have it connect to your already-running rvinterf process) and
initialize the aftermarket FFS for our firmware:

fsio> format /
fsio> mk-std-dirs
fsio> set-imeisv fc XXXXXXXX-YYYYYY-SV (see following section for the details)
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)

then additionally:

fsio> upload-subtree rfbin /gsm/rf
fsio> write-charging-config /opt/freecalypso/charging/c1xx/standard

The last two commands are new with the 2018-01 revision of the FC-to-C1xx
xenotransplantation procedure.  The upload-subtree command uploads the RF
calibration values which you had extracted earlier with c1xx-calextr (the
instructions assume that you are running from the same directory where the
rfbin directory subtree had been created earlier), and this step is necessary
in order for your phone to continue to transmit at the correct power levels
after the conversion.  The write-charging-config command uploads the
configuration settings for the FCHG battery charging driver, without which it
cannot charge the battery; you must have the charging config files from the
fc-battery-conf tree installed under /opt/freecalypso in order for this command
to work as given.

It needs to be noted that the battery charging config settings uploaded with
fc-fsio write-charging-config take effect only on the next boot cycle of the
firmware, i.e., until the next reboot after the write-charging-config operation,
the firmware won't charge the battery even if there is a charging power source
plugged in.

Note regarding the IMEISV
=========================

The argument to the set-imeisv command in fc-fsio is a 16-digit IMEISV, not a
15-digit IMEI.  The IMEI part of IMEISV (the first 14 digits) identifies the
physical hardware and is supposed to be immutable, whereas the two SV digits
are supposed to identify the software version, i.e., they are supposed to change
when the software version changes in a significant way.  Motorola and Compal
did in fact use the SV digits as called for by the specs: their official
firmwares take the IMEI part of IMEISV from the factory-written per-unit vital
data records, and each fw version appends its own SV digits, different from one
version to the next.

When a Mot C1xx phone runs FreeCalypso as opposed to one of Motorola's official
fw versions, we need our own SV to identify our firmware as being distinct from
any of Motorola's original versions.  The convention established by the Mother
of FreeCalypso is that the SV for FreeCalypso on Mot C1xx should be set to 98.

To transform the 15-digit IMEI of your Mot C1xx phone into the 16-digit IMEISV
to be entered in fc-fsio set-imeisv, perform the following two steps:

1) Drop the Luhn check digit - it is not included in the IMEISV form;
2) Add -98 to the remaining 14 content digits of the IMEI from the previous
   step.

Exercising GSM functionality
============================

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

Once you are connected to a network, you can dial and answer voice calls with
ATD and ATA commands, and you can use GSM 07.05 AT commands to send and receive
SMS.  You can also use the quite capable SMS tools included in the FC host tools
package.

When you are done, you can power the phone off by sending a 'poweroff' command
through fc-shell, or you can kill rvinterf or unplug the serial cable and wait
for the firmware to power off by the keepalive timeout after some 15 to 20 s.

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.

Updating from previous versions
===============================

If you had previously initialized your aftermarket FFS using an earlier version
of these instructions, before we added the RF calibration and charging config
upload steps, you need to add these bits to your FFS.  Update to the latest FC
host tools, extract the factory RF calibration values from a dump of your
phone's flash with c1xx-calextr, add the battery charging config files to your
/opt/freecalypso installation, boot the phone with rvinterf, get in with fc-fsio
and run the last two upload-subtree and write-charging-config commands as above.

Recalibration
=============

In the interest of completeness, it needs to be noted that extracting Motorola's
original factory RF calibration values and reusing them for FreeCalypso is not
the only way: the other alternative is to perform a fresh calibration using a
Rohde&Schwarz CMU200 RF test machine and FreeCalypso RF calibration software
(fc-rfcal-tools).  This approach will yield superior results, but the
requirement of having a CMU200 instrument which is itself properly calibrated
and a cabling setup with the right adapters whose insertion loss at particular
GSM frequencies is precisely known makes this approach feasible only for
professional FreeCalypso service shops, not for ordinary individual users.

Restoring Motorola's original firmware
======================================

If you have many phones of the same type, it is best to dedicate a particular
phone to FreeCalypso, as reflashing a phone back and forth is a royal pita.
However, if you have only one phone, then you don't have much choice except to
reflash it back and forth between Motorola's official fw and FreeCalypso, thus
instructions need to be provided.

Restoring original fw on the lower C1xx subfamilies
---------------------------------------------------

Whether you are restoring the original fw version your phone came with or
flashing a different official fw version, you need to ensure that whichever fw
version you are flashing does not have its bootloader locked out.  Examine your
fw image with a hex dump tool and look at the 4 bytes at location 0x2060.  If
these 4 bytes are all FF, then you have an older fw version with no bootloader
locking capability - good.  If these 4 bytes are 'DD DD DD DD' (0xDDDDDDDD
32=bit word), then your fw version does have bootloader locking capability, but
the lock is not activated.  In this case you can still flash it, but you must
make sure that this 32-bit word at 0x2060 always remains equal to 0xDDDDDDDD,
otherwise your phone will be bricked.  And finally if the 4 bytes at 0x2060 are
all zeros, then the bootloader lock is activated - DO NOT flash an image in
this state (you will brick your phone if you do), instead you need to patch
these 4 bytes to 0xDDDDDDDD with a hex editor and then flash the resulting
unlocked version.

Once you have verified that your to-be-flashed fw image is safe, you can flash
it as follows:

1) Get in with fc-loadtool:

fc-loadtool -h compal -c 1004 /dev/ttyXXX

The -c 1004 option is generally unnecessary if your phone runs FreeCalypso fw,
but it doesn't hurt to always include it - it only makes the fc-loadtool entry
process slower by about a second.

2) Once you are at the loadtool> prompt, issue the following commands:

if your phone is C139/140 or C11x/12x with 4 MiB flash:

loadtool> flash erase-program-boot mot-fw-image.bin 0x10000
loadtool> flash erase 0x10000 0x360000
loadtool> flash program-bin 0x10000 mot-fw-image.bin 0x10000 0x360000

or if your phone is C11x/12x with 2 MiB flash:

loadtool> flash erase-program-boot mot-fw-image.bin 0x10000
loadtool> flash erase 0x10000 0x1E0000
loadtool> flash program-bin 0x10000 mot-fw-image.bin 0x10000 0x1E0000

Restoring original fw on Mot C155/156
-------------------------------------

On these phones the bootloader is separate from the main body of the firmware,
thus there is no need to reflash the dangerous boot sector (erase-program-boot)
when changing firmwares, whether changing between Motorola's official fw and
FreeCalypso or between different Mot fw versions.  Simply get in with
fc-loadtool like this:

fc-loadtool -h c155 /dev/ttyXXX

and reflash the firmware like this:

loadtool> flash erase 0x20000 0x7C0000
loadtool> flash program-bin 0x20000 flash-backup.bin 0x20000 0x7C0000