--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/Cable-config-howto	Mon Jul 17 18:26:30 2017 +0000
@@ -0,0 +1,47 @@
+One of the critical requirements for proper calibration of Tx power levels (and
+of the Rx "magic gain" to a lesser degree) is that the insertion loss of the
+cabling setup between your CMU200 and your DUTs (Calypso GSM devices to be
+calibrated) needs to be precisely known and accounted for.  Actually measuring
+the insertion loss of your cables at the center frequency of each GSM uplink and
+downlink frequency band with 0.1 dB accuracy is your responsibility; the rest
+of this article will merely tell you how to feed these cable loss numbers to
+FreeCalypso RF calibration tools.
+
+In our architecture the software component that takes care of adjusting the
+power levels for the cable loss is fc-cmu200d; our fc-cmu200d reads the cable
+loss numbers from a configuration file and instructs the CMU200 itself to
+perform the actual adjustments.  Furthermore, our architecture allows for
+multiple cable configurations.  Some Calypso GSM devices have SMA RF connectors
+for attaching the antenna, in which case the calibration coax needs to terminate
+in an SMA, others have MS-147 or Murata SWD/SWF RF test ports, in which case the
+calibration coax needs to terminate in an MS-147 or Murata probe connector.  If
+you are working with different types of Calypso GSM devices, you will need to
+switch between the corresponding cable setups, as the cable loss numbers will be
+different for each setup: even if you keep the same "main" coax going from your
+CMU200 to an SMA and add/remove Murata's SMA-to-SWD/SWF adapter at the end, the
+addition or removal of that extra adapter will change the total insertion loss
+along the full path, and this change needs to be accounted for.
+
+Cable configuration files are kept in the /opt/freecalypso/rfcal/cableconf
+directory; it is up to you how you name your cable configs, but the following
+convention is suggested:
+
+* If you have a cable setup that terminates in an SMA connector for calibrating
+  Calypso GSM devices with SMA antenna interfaces, the corresponding cable
+  config file should be named "sma".
+
+* If you have a cable setup that terminates in an MS-147 probe connector for
+  recalibrating Mot C1xx phones or similar, the corresponding cable config file
+  should be named "ms147".
+
+* If you have a cable setup that terminates in a Murata SWD/SWF probe for
+  working with devices like Openmoko GTA0x, the corresponding cable config file
+  should be named "murata".
+
+See cableconf-example for an example of the syntax, but please remember that
+you are still responsible for putting in YOUR OWN numbers for the actual
+insertion loss of your cable setups.
+
+When you actually run fc-cmu200d to begin a calibration session (see the
+General-flow article), you will select the cable configuration to be used
+by name with the -c option to fc-cmu200d.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/General-flow	Mon Jul 17 18:26:30 2017 +0000
@@ -0,0 +1,54 @@
+The general flow of using fc-rfcal-tools to calibrate Calypso GSM devices is as
+follows:
+
+* At the beginning of your calibration work session, you need to power on your
+  CMU200, wait for it to finish booting, and then run fc-cmu200d; the fc-cmu200d
+  command line takes the following form:
+
+  fc-cmu200d -c cable_name /dev/ttyXXX 19200
+
+  Change /dev/ttyXXX to the serial port that is connected to the CMU200, give
+  fc-cmu200d the same baud rate that is configured on the CMU (19200 is the
+  default), and select the appropriate cable configuration with the -c option:
+  see the Cable-config-howto article.
+
+  By default the RF2 port on the CMU200 will be used; you can give a -1 option
+  to use the RF1 port instead, or you can include an 'rf-port 1' or 'rf-port 2'
+  line in your cable config files to have the port selection go with the -c
+  selection.
+
+* In typical usage the fc-cmu200d process you started in the previous step can
+  persist through any number of individual device calibrations, as on a factory
+  production line.  However, if you need to switch to a different cable setup
+  with different loss numbers, you will need to kill the fc-cmu200d process and
+  restart it with the appropriate new -c option.
+
+* To calibrate an individual Calypso GSM device, you will need to have an
+  rvinterf process running, talking to the RVTMUX UART channel on that device.
+  Booting your Calypso GSM device in the correct manner and running rvinterf
+  with the right arguments is your responsibility: fc-rfcal-* tools will expect
+  rvinterf to be running already, and will not launch it themselves.
+
+* With both fc-cmu200d and rvinterf running, talking to your CMU200 and your
+  DUT, respectively, and with the correct RF coax (matching your fc-cmu200d -c
+  selection) connected between the two, you can now run the actual calibration
+  automation programs.  For a 900/1800/1900 MHz triband Calypso GSM device, the
+  standard sequence is as follows:
+
+fc-rfcal-vcxo
+fc-rfcal-rxband 900
+fc-rfcal-rxband 1800
+fc-rfcal-rxband 1900
+fc-rfcal-txband 900 <profile>
+fc-rfcal-txband 1800 <profile>
+fc-rfcal-txband 1900 <profile>
+
+The <profile> argument to fc-rfcal-txband commands needs to be changed to the
+name of the appropriate Tx levels calibration profile; see the Tx-cal-theory
+article for more information.
+
+Each of the fc-rfcal-* steps finishes by writing the values it has calibrated
+into the Calypso device's non-volatile flash file system (FFS); once all of the
+steps have been completed, the Calypso device is fully calibrated.  After the
+calibration procedure the Calypso device should be rebooted before normal AT
+command operation is attempted.