--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/VCXO_calibration	Fri Apr 14 07:45:57 2017 +0000
@@ -0,0 +1,227 @@
+How to calibrate the VCXO on your FreeCalypso development board
+===============================================================
+
+The process of calibrating the VCXO on a Calypso+Iota+Rita GSM MS consists of
+the following fundamental parts:
+
+* The antenna needs to be disconnected and the FreeCalypso device's RF output
+  (SMA on the FCDEV3B) needs to be connected to an RF test station such as an
+  R&S CMU200.
+
+* The DUT is commanded to transmit semi-continuously as if it were transmitting
+  on TCH: Tx in one timeslot out of 8, but with the DUT running its own notion
+  of the TDMA frame not synchronized to anything, and keep transmitting
+  endlessly in 1/8 out of every 4.615 ms.
+
+* The RF test station connected to the DUT is used in the RF analyzer mode to
+  measure the frequency offset of the DUT's signal, relative to the ideal uplink
+  frequency corresponding to the selected ARFCN.
+
+* The above frequency offset measurement is performed with the AFC DAC on the
+  Calypso device set to different values, the results of the initial
+  measurements are used to guide some additional measurements, some computations
+  are made from these results, and the computed values are written into the
+  FreeCalypso device's FFS.
+
+This procedure is meant to be automated by way of a program that talks both to
+the FreeCalypso DUT and to the RF test station and orchestrates all of the
+measurement and computation steps, but until this program gets written (we
+weren't able to get a hold of TI's original, hence we have to develop our own),
+use the following instructions to perform the VCXO calibration procedure
+manually.  You still need a CMU200 or equivalent, though - it is not possible
+to do any kind of calibration on a Calypso device by itself, without connecting
+it to some appropriate RF test equipment.
+
+Reference documentation
+=======================
+
+We have the following two TI documents which describe some of the RF calibration
+procedures including the one for the VCXO:
+
+ftp://ftp.freecalypso.org/pub/GSM/Calypso/rf_calibration.pdf
+
+https://www.freecalypso.org/LoCosto-docs/Production%20test%20and%20calibration/i_sample_rf_test_and_calibration_13_03_04_01991%20-%20v026.pdf
+
+Unfortunately neither of them corresponds to the exact evolutionary time point
+of interest to us: the first one corresponds to some chipset much earlier than
+the one we are working with, and to firmware versions much earlier than ours,
+whereas the second one is for TI's later LoCosto chipset.
+
+Commanding the DUT to transmit semi-continuously
+================================================
+
+There is only one VCXO calibration that is subsequently used for all bands in
+normal MS operation.  Both of the calibration instruction documents above
+instruct the operator to run the Tx in GSM900 mode on ARFCN 40, hence we shall
+do likewise until and unless we find some good reason to do differently.
+
+Issue the following commands through fc-tmsh to start the semi-continuous Tx:
+
+tms 1		# enter RF Test Mode
+rfpw 7 6 0	# select GSM 900+1800 band pair, GSM900 band within the pair
+rfpw 2 40	# set ARFCN to 40
+rfpw 8 0	# disable AFC algorithm, i.e., control the AFC DAC manually
+txpw 1 12	# Tx power level
+rfe 3		# start Rx & Tx without network sync
+
+WARNING: Before issuing the above commands, ensure that the antenna is
+disconnected and that the RF output will be going into your test equipment,
+not on the air!  Do not EVER issue these commands with a real antenna connected,
+unless your intent is to operate a rogue transmitter or jammer.
+
+At this point your CMU200 or equivalent should detect the uplink signal
+generated by the DUT (on the CMU200 one needs to set TSC to 5, dunno about
+other test equipment), and you should see some frequency offset.
+
+The actual calibration procedure
+================================
+
+1. Set the AFC DAC to -2048:
+
+   rfpw 9 -2048
+
+   and measure the frequency offset.  Note it down.
+
+2. Set the AFC DAC to +2048:
+
+   rfpw 9 2048
+
+   and again measure the frequency offset.  Note it down.
+
+Now you need to create an ASCII text file with your frequency offset
+measurements.  Each line represents one measurement and consists of two fields:
+the first field is the DAC value and the second field is the measured frequency
+offset in Hz.  On my FCDEV3B S/N 001 the first two measurements were:
+
+-2048	-30008
++2048	+21394
+
+Next you need to apply a linear model to the VCXO frequency offset as a function
+of the DAC input: if x is the DAC value and F is the resulting frequency offset,
+then the linear model is F = ax + b, where a and b need to be determined from
+two measured points (x1, F1) and (x2, F2).  Then once you have a and b, find the
+x value that should produce F = 0.  The fc-vcxo-linear utility will do this math
+for you: run it with the name of your text file with measurements as its only
+argument.
+
+With my measurements, the DAC_CENTER value computed by fc-vcxo-linear is 343.
+However, the linear model is not perfect, thus when you write this computed
+value into the DAC with the rfpw 9 command, the resulting frequency offset on
+the CMU200 screen may be quite far from 0.
+
+TI's instructions in the LoCosto document direct the calibration operator to do
+two more measurements at DAC_CENTER-100 and DAC_CENTER+100, where DAC_CENTER is
+the value we just computed by applying the linear model to the first two
+measurements.  However, in my case the frequency offset at DAC=343 (DAC_CENTER)
+was so negative that at DAC=443 (DAC_CENTER+100) it was still negative - and I
+assume that TI's intent was to capture a close range around the zero crossing.
+
+Therefore, when I get to writing the automated calibration program, I intend to
+change this part of the algorithm as follows: instead of adding or subtracting
+100 right now, first do an rfpw 9 with the DAC_CENTER value as computed from
+the linear model, make a frequency offset measurement, and see if it is negative
+or positive.  Then step the DAC value in the appropriate direction by some
+reasonable increment (e.g., 100) until the frequency offset changes sign.  Then
+take the two DAC values closest to the output frequency offset sign change.
+
+After doing the above, my measurement notes file became:
+
+-2048	-30008
++2048	+21394
+443	-669
+543	634
+
+This file needs to contain all four measurements, with the first two being at
+the extreme DAC values and with the second two hugging the empirically located
+zero crossing, when you feed it to the next step:
+
+fc-vcxo-param myvcxo.meas
+
+The fc-vcxo-param utility will compute the final math steps to produce the
+actual calibration values which will need to be uploaded to the FreeCalypso
+device and stored in its FFS.  With my measurements above, I got the following
+output:
+
+rf_table afcparams
+
+      3434	# Psi_sta_inv
+        15	# Psi_st
+   1000341	# Psi_st_32
+      4293	# Psi_st_inv
+
+      3954	# DAC_INIT * 8
+     -5860	# DAC_MIN * 8
+     11351	# DAC_MAX * 8
+      2560	# snr_thr
+
+# DAC_INIT: rfpw 10 494
+
+The output from fc-vcxo-param is in the rf_table format which our implementation
+of the rftw command takes as input, and the latter is the fc-tmsh command which
+you will need to issue in order to send this table to the FreeCalypso firmware
+in the DUT.
+
+Explanation of the numbers:
+
+* The Psi constants are computed from the slope of the VCXO, and are
+  subsequently used for the steering: when the DSP reports a particular
+  frequency offset (in the form of an angle in radians), by how much should the
+  DAC value be adjusted?  The slope I use for computing these Psi constants is
+  the one from the first two measurements at the extreme DAC values, as the
+  LoCosto document seems to indicate.
+
+* DAC_INIT is the DAC value at which the resulting frequency offset should be 0;
+  it is computed per the linear model from the second pair of measurements.
+
+* DAC_MIN and DAC_MAX are the DAC values which should produce frequency offsets
+  of -15 and +15 ppm, respectively, according to the LoCosto document.  I
+  compute them per the linear model from the first pair of measurements (the
+  extreme DAC ones), as that is what the LoCosto document says.
+
+* The SNR threshold is a constant that never needs to change.
+
+The 3 dac_* values in the afcparams structure are stored in the times 8 form.
+Examination of the afcparams values read out of several Openmoko-made GTA02
+units shows that the low 3 bits aren't necessarily zeros, indicating that TI's
+calibration program probably multiplied by 8 before converting from floating
+point to integer; I do likewise in fc-vcxo-param.
+
+Examination of the same afcparams values read out of Openmoko-made units also
+shows that the center, min and max DAC values do vary quite a bit from one unit
+to the next, whereas the Psi constants change very little.  The Psi constants
+which my program computed from my manual measurements on FCDEV3B S/N 001 are in
+the same range as those read out of Openmoko-made units, which is definitely a
+reassuring sign.
+
+Writing your VCXO calibration into FFS
+======================================
+
+Save the fc-vcxo-param output in a file, e.g.:
+
+fc-vcxo-param myvcxo.meas myvcxo.param
+
+Upload the generated afcparams table to your FreeCalypso device:
+
+rftw 9 myvcxo.param
+
+There is one more variable in the firmware, outside of the afcparams structure,
+which also holds the DAC_INIT value.  Set it with an rfpw 10 command as
+instructed in the last comment line emitted by fc-vcxo-param; in my case it was:
+
+rfpw 10 494
+
+Now save all of these values in the non-volatile flash file system:
+
+me 102
+me 103
+
+Cleaning up
+===========
+
+To shut off the transmitter you started earlier, issue this command:
+
+rfe 0
+
+Now power off your FreeCalypso device, disconnect the RF test setup, connect the
+antenna back, insert a SIM, do a fresh boot and see if you can connect to a real
+live GSM network with your VCXO calibration!