--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/C139-Howto	Mon Oct 03 04:26:16 2016 +0000
@@ -0,0 +1,146 @@
+Running FreeCalypso Magnetite 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
+
+Because neither FC Citrine nor FC Magnetite implements any phone UI or puts
+anything at all on the LCD, when a C139 phone is flashed with one of our
+firmwares, it will behave very oddly:
+
+* 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.
+
+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, 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 the FC Magnetite firmware image you have compiled:
+
+loadtool> flash erase 0x10000 0x230000
+loadtool> flash program-bin 0x10000 fwimage.bin
+
+* 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.  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 can exit fc-fsio, 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.