--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Freerunner-Howto	Sun Jun 12 18:28:35 2016 +0000
@@ -0,0 +1,109 @@
+How to play with FreeCalypso GSM firmware on a Neo Freerunner
+=============================================================
+
+We have two entirely different firmware offerings for the Freerunner:
+
+1. Leo2moko fw produced back in 2013-10: this is the only one suitable for
+   end users.  We also have leo2moko-debug which is a slightly hacked-up
+   version of leo2moko with some additional debug features for developers;
+   this version is for developers only; end users should stick with the
+   original leo2moko-r1 aka moko12 from 2013-10.
+
+2. The work-in-progress full-source gcc-built FreeCalypso Citrine fw
+   you are looking at can be built for multiple targets, and the
+   gtamodem target is one of them - the original one, in fact.
+
+The flash+SRAM chip which FIC/Openmoko populated in their modems provides
+plenty enough RAM for the firmware's data space requirements, but not enough
+to run a complete firmware code image entirely from RAM, hence whichever fw
+version you would like to exercise, you need to flash it.  There are two ways
+to flash modem firmware images in these smartphones: from inside the phone
+(from the application processor) or externally through a special serial cable
+inserted into the analog headset jack.  The internal method is intended only
+for end users flashing released production-quality images; developers and
+tinkerers are expected to use the serial cable method.
+
+The serial cable wiring requirements for the GTA02 are the same as for Mot C1xx
+phones, thus the same cable can be used for both.  The FreeCalypso project has
+endorsed UberWaves as our official vendor for serial cables; George at
+UberWaves now makes serial cables that are specifically certified for use with
+FreeCalypso.  If you would like to order one, email uberwaves@gmail.com.
+
+Please see the Current_Status write-up for the current status of the present
+Citrine firmware.  As you can read there, this fw is currently nowhere near
+being able to replace leo2moko.  Therefore, if you are going to flash Citrine
+into your FR's modem, we expect that you are using your FR as a poor man's
+substitute for the not-yet-built FCDEV3B (a board we seek to build specifically
+for developers and not for end users), and are NOT expecting this experimental
+work-in-progress modem fw to work together with user-oriented application
+processor software like QtMoko or SHR.
+
+If you would like to play with our experimental Citrine fw using a GTA02 modem
+as the hw platform, here are the instructions:
+
+1. Build the firmware in the gtamodem-gsm configuration - see the Compiling
+   document for more details;
+
+2. You should get a flashImage.bin image built; now you need to flash it into
+   your FR's modem.  The serial cable method is highly recommended: the only
+   thing you'll be able to do with our current not-fully-functional firmware is
+   play with it and observe the debug output, and the serial cable will be
+   needed for the latter part anyway.
+
+3. Run fc-loadtool the same way you would if you were flashing leo2moko;
+
+4. The actual flash programming commands are a little different because the
+   image is smaller and in a different format:
+
+flash erase 0 0x160000
+flash program-bin 0 finlink/flashImage.bin
+
+The second number in the flash erase command needs to be the size of
+flashImage.bin rounded up to a multiple of 64 KiB (the flash sector size in the
+GTA02 modem); 0x160000 is correct for the fw image size as of this writing, but
+please double-check it yourself before flashing.  The 0 argument in the
+flash program-bin command is the flash offset at which the image should be
+programmed: it will always be 0 for FreeCalypso flashable fw images for gtamodem
+and other targets that have the Calypso boot ROM enabled in the hardware.
+
+Once you have flashed our experimental fw into your modem, you can power-cycle
+the modem and see the new fw boot.  You should have the serial cable connected,
+the serial channel enabled from the Freerunner's AP side and either rvtdump or
+rvinterf running on your PC or other development machine when you first power
+your modem up with the experimental fw in it: this way you will see the debug
+output as the firmware boots up.
+
+Once the firmware has booted, it needs to be controlled via AT commands.  The
+present fw presents its AT command interface on two channels on this target: on
+the MODEM UART going to the Freerunner's application processor and via RVTMUX.
+At the present stage of development, we highly recommend that you avoid running
+any GSM-driving software on the AP and exercise our work-in-progress fw solely
+through the external serial interface on the headset jack, using rvinterf and
+fc-shell.  The standard AT command interface on the dedicated MODEM UART is a
+feature which we plan to address properly only when we build our planned FCDEV3B
+hardware, which will bring both UARTs out to the external host.
+
+Assuming that you already have rvinterf running in a terminal window (you should
+have started it before you gave the modem power-on command from the AP side),
+to exercise our firmware further, you will need to open another terminal window
+on your driving PC/laptop and run fc-shell.  This program will connect to the
+already running rvinterf process via a local socket, and it will enable you to
+send various commands to the running fw on the target, the most important ones
+being standard AT commands.  Send the following sequence of AT commands to
+bring up GSM functionality:
+
+AT+CMEE=2	-- enable verbose error responses
+AT+CFUN=1	-- enable radio and SIM interfaces
+AT+COPS=0	-- register to the default GSM network
+
+To reflash your modem back to stable and working leo2moko aka moko12, execute
+the following fc-loadtool commands:
+
+flash erase 0 0x230000
+flash program-m0 leo2moko.m0
+
+(Whichever firmware image you are flashing, the flash erase command needs to
+ cover the range of flash sectors this image will occupy.  You can erase more
+ sectors up to 0x300000, the "natural" boundary of the flash area where fw
+ images live, but I prefer to erase only the needed number of sectors: it is
+ both faster and imposes less wear on the flash.)