ClockTamerControlProtocol

Introduction
You can control ClockTamer via USB or SPI. With USB connected the ClockTamer emulates a serial port, so you can control it easily with your preferred terminal emulator, via scripts and from programs. An SPI connection is used when ClockTamer is connected to a USRP and is useful if you don't want to have two USB cables running from the USRP to your computer.

ClockTamer uses a text based protocol and this is essentially the same for USB and SPI interfaces. USB and SPI versions of the protocol differ only in the way responses from ClockTamer are transfered. When using SPI connection you need to poll the ClockTamer, as described at the SPI interface page. When using a USB connection, you don't need to do anything specific to receive a reply, but on Linux before doing any exchange you should turn off echo for the ClockTamer serial device. You can achieve this from the command line with: stty -F /dev/ttyACM0 -echo

Where /dev/ttyACM0 is your ClockTamer's serial device file.

In short, the protocol has the following features:


 * 1) It is strictly master/slave, with ClockTamer being slave. This means, that a ClockTamer can only reply to commands sent by a host and cannot issue any commands or queries to the host.
 * 2) All commands and answers are ASCII strings, terminated by CR/LF. This makes it easy to command ClockTamer in interactive mode with your favorite terminal emulator program.
 * 3) Every command from the host is followed by answer from ClockTamer, i.e. protocol is synchronous. It's similar to SD/MMC — if you've sent a command you should wait until an answer is received before issuing the next command. If you haven't received an answer after a long period of time, something went wrong and it's a bug. It's then recommended to reset ClockTamer and try again. And don't forget to report bugs!

For the impatient...
If you just want to start using your !ClockTamer without getting into all fine details, here is the way to go:

SET,,OSC, SET,,OUT,

Where you should replace:


 * osc_freq with the frequency (in Hz) of (VC)TCXO installed on your ClockTamer, e.g. something like 20000000. Note that you can calibrate your ClockTamer by slightly adjusting `osc_freq`. See the calibration page for detailed instructions.
 * out_freq with desired output frequency (in Hz).

If you're satisfied with your settings, you can store them in EEPROM to be used after reboot:

STE

Command and response structure
Every command has a format:

CMD[,TYP[,DET[,value]]]

Where:


 * CMD — three letter command class. Must be non empty string.
 * TYP — three letter command target type. May be empty string, even if DET or value is present (e.g. SET,,OSC,10000200).
 * DET — three letter command target details. May be empty string, even if value is present (e.g. PIN,LED,,0).
 * value — decimal or hexadecimal value. Decimal values start with a digit (e.g. 54781), hexadecimal values start with x letter (e.g. x01af3d).

Depending on the command class, later fields may be omitted completely, e.g.:


 * LDE — only CMD is present
 * INF,,OSC — CMD, TYP and DET are present with TYP as empty string

The response format is as follows:

If command does not require a value to be returned, then the response is

OK

If a command returns a value, the response has the same structure same as the command:

CMD[,TYP[,DET[,value]]]

Where CMD, TYP and DET repeats the respective fields in the command. If a command cannot be parsed an error is returned:

SYNTAX ERROR

Register (REG)
Writes value data to the appropriate registers of chips via MicroWire bus. Using this commands you can control every aspect of clock generation in manual mode. Permitted target type and detail combinations:

Pin (PIN)
Controls pins of chips. Allowed target type and detail combinations:

Set (SET)
Setting of output frequency, setting oscillator calibration value, changing algorithms internal variables. The most useful target type and detail combinations:

Save (SAV)
NOT IMPLEMENTED YET.

Defaults (DEF)
NOT IMPLEMENTED YET.

Info (INF)
Get the value of the selected variable. Every variable (specified in DET), usable with SET has its INF counterpart. Note that there is no INF command with empty DET, though.

There are also a set of variables for debugging purposes only. You don't need to touch them if you don't change the firmware. Also their meaning may change from one firmware version to another, without API version change. Currently available target type and detail combinations:

Version (VER)
Get firmware and protocol versions.

Example:

ClockTamer SW=1.23 API=1

Hardware information (HWI)
Get detailed information about installed hardware options. This information is stored in EEPROM and may be altered only if ClockTamer is flashed over SPI. Flashing over USB cannot change EEPROM data.

Values shown in HWI string incude:

Example of `HWI` for a !ClockTamer with LMX2531LQ2080E, LMK1010, 20MHz TCXO and GPS:

LMX=2080 LMK=1010 OSC=20 GPS

Reset (RST)
Sends reset command to LMK and LMX, and clears variables in MCU RAM, but does not affect EEPROM.

To start output generation after RST you can execute:

`SET,,OSC, `", "`SET,,OUT, `" or "`LDE`"+"`SET`"

Load EEPROM (LDE)
Loads previously stored values from EEPROM to RAM. This command does not push them to LMK and LMX chips, so you should execute `SET` command manually.

TYP, DET and value should be empty.

Store EEPROM (STE)
Stores all values to EEPROM. These values will be used by default after ClockTamer reboots. They can also be loaded to RAM at any time with the LDE command.

TYP, DET and value should be empty.

Enter GPS mode (%%%)
Run this command to switch from the control mode to the GPS positioning mode. In the GPS positioning mode ClockTamer acts as an NMEA device and does not accept any ClockTamer control commands expect Leave GPS mode command (%).

The command does not return any status. You should start reading NMEA status right after this command.

Leave GPS mode (%)
Run this command to leave GPS positioning mode and switch back to the normal ClockTamer control mode. In the control mode this command does nothing, so it's safe to use it before you issue a command to make sure a ClockTamer is in the control mode.

The command does not return any status. You could issue the next command right after this command.

ClockTamer-1.0
If you look at ClockTamer so that the "ClockTamer v1.0" label reads the correct way around, the outputs are numbered in the following way:

2       0  .---.  |LMK|  7 .---.        6 4   5    6*

Where 0,2,4,5,6 - places for U.FL connectors, 6`*` - a place for SMA connector. Outputs number 1 and 3 are not present on PCB. In default configuration outputs number 0 and 2 are LVDS, while 4,5,6 are LVPECL/CMOS.

ClockTamer-1.1 and ClockTamer-1.2
Output numbering is as shown.



Outputs 1 and 6 are CMOS, while outputs 0, 3, 4, 5 and 7 are LVDS or half-LVDS. Refer to Features and technical specification for further information about half-LVDS outputs.