--- /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.