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!