ClockTamerControlProtocol: Difference between revisions

Democratising Wireless Innovation
Jump to navigation Jump to search
(Created page with "== Introduction == You can control ClockTamer via USB or SPI. When USB connected ClockTamer emulates a serial port, so you can control it easily with your preferred terminal...")
 
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Introduction ==
== Introduction ==


You can control ClockTamer via USB or SPI. When USB connected ClockTamer emulates a serial port, so you can control it easily with your preferred terminal emulator, from scripts and from programs. 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.
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 [[ClockTamerProtocolSPI#Control_protocol_SPI-specific_operation|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:
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 [[ClockTamerProtocolSPI#Control_protocol_SPI-specific_operation|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:
Line 18: Line 18:


If you just want to start using your !ClockTamer without getting into all fine details, here is the way to go:
If you just want to start using your !ClockTamer without getting into all fine details, here is the way to go:
<nowiki>
 
<nowiki>
SET,,OSC,<osc_freq>
SET,,OSC,<osc_freq>
SET,,OUT,<out_freq></nowiki>
SET,,OUT,<out_freq></nowiki>
Line 30: Line 31:
If you're satisfied with your settings, you can store them in EEPROM to be used after reboot:
If you're satisfied with your settings, you can store them in EEPROM to be used after reboot:


<nowiki>
<nowiki>
STE</nowiki>
STE</nowiki>


== Commands and answers structure ==
== Command and response structure ==


Every command has a format:
Every command has a format:


<nowiki>
<nowiki>
CMD[,TYP[,DET[,value]]]<CR><LF></nowiki>
CMD[,TYP[,DET[,value]]]<CR><LF></nowiki>


Line 46: Line 47:
* ''DET'' — three letter command target details. May be empty string, even if ''value'' is present (e.g. ''PIN,LED,,0'').
* ''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'').
* ''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.:
Depending on the command class, later fields may be omitted completely, e.g.:


<nowiki>
* ''LDE'' — only CMD is present
* ''LDE'' — only CMD is present
* ''INF,,OSC'' — CMD, TYP and DET are present with TYP as empty string</nowiki>
* ''INF,,OSC'' — CMD, TYP and DET are present with TYP as empty string




The response format is as follows:
The response format is as follows:


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


<nowiki>
<nowiki>
OK<CR><LF></nowiki>
OK<CR><LF></nowiki>


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


<nowiki>
<nowiki>
CMD[,TYP[,DET[,value]]]<CR><LF></nowiki>
CMD[,TYP[,DET[,value]]]<CR><LF></nowiki>


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


<nowiki>
<nowiki>
SYNTAX ERROR<CR><LF></nowiki>
SYNTAX ERROR<CR><LF></nowiki>


== Command classes ==
== Command classes ==


=== Register (''REG'') ===
=== Register (REG) ===


Writes ''value'' data to the appropriate registers of chips via [http://en.wikipedia.org/wiki/Microwire MicroWire bus]. Using this commands you can control every aspect of clock generation in manual mode. Permitted target type and detail combinations:
Writes ''value'' data to the appropriate registers of chips via [http://en.wikipedia.org/wiki/Microwire MicroWire bus]. Using this commands you can control every aspect of clock generation in manual mode. Permitted target type and detail combinations:


ABTOHERE
{| class="wikitable"
|-
|TYP
|DET
|Value
|Description
|-
|LMK
|<empty>
|32 bit value
|Write to LMK (clock distributor) chip registers
|-
|LMX
|<empty>
|24 bit value
|Write to LMX (PLL+VCO) chip registers (if LMX is present)
|-
|DAC
|<empty>
|16-24 bit value
|Write to DAC (Digital-to-Analog Converter) chip registers (if DAC is present)
|}
 
=== Pin (PIN) ===


|| *`TYP`* || *`DET`* || *`value`* || *Description* ||
Controls pins of chips. Allowed target type and detail combinations:
|| `LMK` || `<empty>` || 32bit value || Write to LMK (clock distributor) chip registers ||
|| `LMX` || `<empty>` || 24bit value || Write to LMX (PLL+VCO) chip registers (if LMX is present) ||
|| `DAC` || `<empty>` || 16-24bit value || Write to DAC (Digital-to-Analog Converter) chip registers (if DAC is present)||


== Pin ("PIN") ==
{| class="wikitable"
|-
|TYP
|DET
|Value
|Description
|-
|LMK
|ENB
|0/1
|ENABLE pin of LMK (clock distributor) chip
|-
|LMK
|GOE
|0/1
|GOE pin of LMK (clock distributor) chip
|-
|LMX
|SYN
|0/1
|SYN pin of LMX (PLL+VCO) chip
|-
|LED
| <empty>
|0/1
|Turn LED on/off
|}


Controls pins of chips. Allowed target type and detail combinations:
=== Set (SET) ===
|| *`TYP`* || *`DET`* || *`value`* || *Description* ||
|| `LMK` || `ENB` || 0/1 || `ENABLE` pin of LMK (clock distributor) chip. ||
|| `LMK` || `GOE` || 0/1 || `GOE` pin of LMK (clock distributor) chip. ||
|| `LMX` || `SYN` || 0/1 || `SYN` pin of LMX (PLL+VCO) chip. ||
|| `LED` || `<empty>` || 0/1 || Turn LED on/off. ||


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


Easy to use setting of output frequency, setting oscillator calibration value, changing algorithms internal variables. The most useful target type and detail combinations:
{| class="wikitable"
|| *`TYP`* || *`DET`* || *`value`* || *Description* ||
|-
|| `<empty>` || `<empty>` || `<empty>` || Write all control registers from MCU RAM to LMX and LMK chips. ||
|TYP
|| `<empty>` || `OSC` || integer || Set oscillator frequency. Used when oscillator is changed, when external frequency source changed its frequency or to calibrate oscillator. Control registers of LMK and LMX are recalculated and written to the chips with this command. ||
|DET
|| `<empty>` || `OUT` || integer || Set !ClockTamer output frequency. Control registers of LMK and LMX are recalculated and written to the chips with this command. ||
|Value
|| `<empty>` || `AUT` || 0/1 || If set to 1 !ClockTamer will load all variables from EEPROM and start generator on boot. ||
|Description
|| `LMK` || `<empty>` || `<empty>` || Write all control registers of LMK to the chip. ||
|-
|| `LMK` || `PRT` || integer || Change value of LMK output mask. See description of `LMK_OutMask` EEPROM register for details. Control registers of LMK are written to the chip with this command. ||
|<empty>
|| `GPS` || `SYN` || `<empty>` || One-time synchronization to GPS. ||
|<empty>
|| `GPS` || `AUT` || 0/1 || If set to 1 !ClockTamer will keep clock synchronized to GPS. ||
|<empty>
|Write all control registers from MCU RAM to LMX and LMK chips
|-
|<empty>
|OSC
|<integer>
|Set oscillator frequency. Used when oscillator is changed, when external frequency source changed its frequency or to calibrate oscillator. Control registers of LMK and LMX are recalculated and written to the chips with this command
|-
|<empty>
|OUT
|<integer>
|Set ClockTamer output frequency. Control registers of LMK and LMX are recalculated and written to the devices with this command.
|-
|<empty>
|AUT
|0/1
|If set to 1 ClockTamer will load all variables from EEPROM and start generator on boot
|-
|LMK
|<empty>
|<empty>
|Write all control registers of LMK to the chip
|-
|LMK
|PRT
|<integer>
|Change value of LMK output mask. See description of LMK_OutMask EEPROM register for details. Control registers of LMK are written to the chip with this command
|-
|GPS
|SYN
|<empty>
|One-time synchronization to GPS
|-
|GPS
|AUT
|0/1
|If set to 1 ClockTamer will keep clock synchronized to GPS
|}


== Save ("SAV") ==
=== Save (SAV) ===


_NOT IMPLEMENTED YET_
''NOT IMPLEMENTED YET''.


== Defaults ("DEF") ==
=== Defaults (DEF) ===


_NOT IMPLEMENTED YET_
''NOT IMPLEMENTED YET''.


== Info ("INF") ==
=== Info (INF) ===


Get value of the selected variable. Every variable (specified in `DET`), usable with `SET` has its `INF` counterpart. There is no `NFO` command with empty `DET`, though.
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:
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:
|| *`TYP`* || *`DET`* || *`value`* || *Description* ||
|| `GPS` || `DIV` || `<empty>` || Debug output. Value of divider of LMK output, routed to MCU input. ||
|| `GPS` || `KBT` || `<empty>` || Debug output. ||
|| `GPS` || `R00` || `<empty>` || Debug output. ||
|| `GPS` || `R01` || `<empty>` || Debug output. In !ClockTamer-1.2 it gives you a number of received 1pps ticks. If this value is increasing, then GPS lock is acquired. ||
|| `GPS` || `R02` || `<empty>` || Debug output. ||
|| `GPS` || `R03` || `<empty>` || Debug output. In !ClockTamer-1.2 it gives you calculated output frequency, multiplied by 32, i.e. `Fout = R02/32`. ||
|| `GPS` || `MAX` || `<empty>` || Debug output. ||
|| `GPS` || `MIN` || `<empty>` || Debug output. ||


{| class="wikitable"
|-
|TYP
|DET
|Value
|Description
|-
|GPS
|DIV
|<empty>
|Debug output. Value of divider of LMK output, routed to MCU input
|-
|GPS
|KBT
|<empty>
|Debug output
|-
|GPS
|R00
|<empty>
|Debug output
|-
|GPS
|R01
|<empty>
|Debug output. In ClockTamer-1.2 it gives you a number of received 1pps ticks. If this value is increasing, then GPS lock is acquired
|-
|GPS
|R02
|<empty>
|Debug output
|-
|GPS
|R03
|<empty>
|Debug output. In ClockTamer-1.2 it gives you calculated output frequency, multiplied by 32, i.e. `Fout = R02/32`
|-
|GPS
|MAX
|<empty>
|Debug output
|-
|GPS
|MIN
|<empty>
|Debug output
|-
|}


== Version ("VER") ==
=== Version (VER) ===


Get firmware and protocol versions.
Get firmware and protocol versions.


Example:
Example:
{{{
ClockTamer SW=1.23 API=1
}}}


== Hardware information ("HWI") ==
<nowiki>
ClockTamer SW=1.23 API=1</nowiki>


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 can not change EEPROM data.
=== 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:
Values shown in HWI string incude:
|| `LMX=` || Type of LMX2531 VCO+PLL. Can be "2080" for LMX2531LQ2080E or "1515" for LMX2531LQ1515E. Most !ClockTamers have LMX2531LQ2080E. ||
|| `LMK=` || Type of LMK01000 Clock Buffer, Divider, and Distributor. Can be "1000" for LMK01000, "1010" for LMK01010 or "1020" for LMK01020, but is usually LMK01010. ||
|| `OSC=`<br/>`FOSC=` || Frequency of the reference TCXO or VCTCXO in MHz. Possible values are 10, 20 or 26. ||
|| `GPS` || !ClockTamer has GPS module installed if `GPS` is present in `HWI`. ||
|| `VCTCXO` || !ClockTamer use VCTCXO with DAC instead of TCXO with VCO+PLL is `VCTCXO` is present in `HWI`. ||


{| class="wikitable"
|-
|LMX=
|Type of LMX2531 VCO+PLL. Can be "2080" for LMX2531LQ2080E or "1515" for LMX2531LQ1515E. Most ClockTamers have LMX2531LQ2080E
|-
|LMK=
|Type of LMK01000 Clock Buffer, Divider, and Distributor. Can be "1000" for LMK01000, "1010" for LMK01010 or "1020" for LMK01020, but is usually LMK01010
|-
|OSC=<br/>FOSC=
|Frequency of the reference TCXO or VCTCXO in MHz. Possible values are 10, 20 or 26.
|-
|GPS
|ClockTamer has GPS module installed if GPS is present in HWI
|-
|VCTCXO
|ClockTamer use VCTCXO with DAC instead of TCXO with VCO+PLL is `VCTCXO` is present in `HWI`
|-
|}


Example of `HWI` for a !ClockTamer with LMX2531LQ2080E, LMK1010, 20MHz TCXO and GPS:
Example of `HWI` for a !ClockTamer with LMX2531LQ2080E, LMK1010, 20MHz TCXO and GPS:
{{{
LMX=2080 LMK=1010 OSC=20 GPS
}}}


== Reset ("RST") ==
<nowiki>
LMX=2080 LMK=1010 OSC=20 GPS</nowiki>
 
=== 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:


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,<val>`", "`SET,,OUT,<val>`" or "`LDE`"+"`SET`".
<nowiki>
`SET,,OSC,<val>`", "`SET,,OUT,<val>`" or "`LDE`"+"`SET`"</nowiki>


== Load EEPROM ("LDE") ==
=== 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.
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.
TYP, DET and value should be empty.


== Store EEPROM ("STE") ==
=== Store EEPROM (STE) ===


Stores all values to EEPROM. This values will be used by default after !ClockTamer reboot. They can also be loaded to RAM at any time with `LDE` command.
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.
TYP, DET and value should be empty.


== Enter GPS mode ("%%%") ==
=== 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 a usual NMEA device and does not accept any !ClockTamer control commands expect "Leave GPS mode" command ("%").
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 (%).


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


== Leave GPS mode ("%") ==
=== 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.  
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.  


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


= EEPROM variables list =
== EEPROM variables ==


|| Variable || Description ||
{| class="wikitable"
|| `Fosc` || Oscillator frequency ||
|-
|| `Fout` || Output frequency ||
|Variable
|| `VCO_MIN` || Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit. ||
|Description
|| `VCO_MAX` || Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit. ||
|-
|| `VCO_Kbit` || Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit. ||
|Fosc
|| `LMK_OutMask` || Enable/disable output generation on specific LMK outputs. Set bit in the mask to 1 to enable corresponding output and to 0 to disable it. E.g. `x60` value will enable 5 and 6 outputs and disable all others. See [#Outputs_numbering outputs numbering] below. ||
|Oscillator frequency
|| `AutoFreq` || Autostart generating output on boot. ||
|-
|| `DacValue` || DAC value if VCTCXO is used. ||
|Fout
|| `AutoGPSSync` || Continuously synchronize clock to GPS. ||
|Output frequency
|-
|VCO_MIN
|Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit
|-
|VCO_MAX
|Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit
|-
|VCO_Kbit
|Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit
|-
|LMK_OutMask
|Enable/disable output generation on specific LMK outputs. Set bit in the mask to 1 to enable corresponding output and to 0 to disable it. E.g. x60 value will enable 5 and 6 outputs and disable all others. See [[#Outputs_numbering|outputs numbering]] below
|-
|AutoFreq
|Autostart generating output on boot
|-
|DacValue
|DAC value if VCTCXO is used
|-
|AutoGPSSync
|Continuously synchronize clock to GPS
|-
|}


= Outputs numbering =
== Outputs numbering ==


== !ClockTamer-1.0 ==
=== ClockTamer-1.0 ===


If you look at !ClockTamer so that "!ClockTamer v1.0" label reads normally, then outputs are numbered in the following way:
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:
{{{
 
<nowiki>
2        0
2        0
   .---.
   .---.
Line 210: Line 370:
   .---.
   .---.
         6
         6
4  5    6*
4  5    6*</nowiki>
}}}
 
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.
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.


== !ClockTamer-1.1 and !ClockTamer-1.2 ==
[[File:Tamer-gui-pic.png]]


Outputs numbering is as shown on the picture:
Outputs 1 and 6 are CMOS, while outputs 0, 3, 4, 5 and 7 are LVDS or half-LVDS. Refer to [[ClockTamerFeaturesAndTechnicalSpecification#Output_types|Features and technical specification]] for further information about half-LVDS outputs.
http://wiki.clock-tamer.googlecode.com/hg/images/misc/tamer-gui-pic.png


Outputs 1 and 6 and CMOS, while outputs 0, 3, 4, 5 and 7 are LVDS or half-LVDS. Refer to [FeaturesAndTechnicalSpecification#Output_types Features and technical specification] page for more information about half-LVDS outputs.
{{Community}}

Latest revision as of 14:55, 15 September 2015

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,<osc_freq>
SET,,OUT,<out_freq>

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]]]<CR><LF>

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<CR><LF>

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

CMD[,TYP[,DET[,value]]]<CR><LF>

Where CMD, TYP and DET repeats the respective fields in the command.

If a command cannot be parsed an error is returned:

SYNTAX ERROR<CR><LF>

Command classes

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:

TYP DET Value Description
LMK <empty> 32 bit value Write to LMK (clock distributor) chip registers
LMX <empty> 24 bit value Write to LMX (PLL+VCO) chip registers (if LMX is present)
DAC <empty> 16-24 bit value Write to DAC (Digital-to-Analog Converter) chip registers (if DAC is present)

Pin (PIN)

Controls pins of chips. Allowed target type and detail combinations:

TYP DET Value Description
LMK ENB 0/1 ENABLE pin of LMK (clock distributor) chip
LMK GOE 0/1 GOE pin of LMK (clock distributor) chip
LMX SYN 0/1 SYN pin of LMX (PLL+VCO) chip
LED <empty> 0/1 Turn LED on/off

Set (SET)

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

TYP DET Value Description
<empty> <empty> <empty> Write all control registers from MCU RAM to LMX and LMK chips
<empty> OSC <integer> Set oscillator frequency. Used when oscillator is changed, when external frequency source changed its frequency or to calibrate oscillator. Control registers of LMK and LMX are recalculated and written to the chips with this command
<empty> OUT <integer> Set ClockTamer output frequency. Control registers of LMK and LMX are recalculated and written to the devices with this command.
<empty> AUT 0/1 If set to 1 ClockTamer will load all variables from EEPROM and start generator on boot
LMK <empty> <empty> Write all control registers of LMK to the chip
LMK PRT <integer> Change value of LMK output mask. See description of LMK_OutMask EEPROM register for details. Control registers of LMK are written to the chip with this command
GPS SYN <empty> One-time synchronization to GPS
GPS AUT 0/1 If set to 1 ClockTamer will keep clock synchronized to GPS

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:

TYP DET Value Description
GPS DIV <empty> Debug output. Value of divider of LMK output, routed to MCU input
GPS KBT <empty> Debug output
GPS R00 <empty> Debug output
GPS R01 <empty> Debug output. In ClockTamer-1.2 it gives you a number of received 1pps ticks. If this value is increasing, then GPS lock is acquired
GPS R02 <empty> Debug output
GPS R03 <empty> Debug output. In ClockTamer-1.2 it gives you calculated output frequency, multiplied by 32, i.e. `Fout = R02/32`
GPS MAX <empty> Debug output
GPS MIN <empty> Debug output

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:

LMX= Type of LMX2531 VCO+PLL. Can be "2080" for LMX2531LQ2080E or "1515" for LMX2531LQ1515E. Most ClockTamers have LMX2531LQ2080E
LMK= Type of LMK01000 Clock Buffer, Divider, and Distributor. Can be "1000" for LMK01000, "1010" for LMK01010 or "1020" for LMK01020, but is usually LMK01010
OSC=
FOSC=
Frequency of the reference TCXO or VCTCXO in MHz. Possible values are 10, 20 or 26.
GPS ClockTamer has GPS module installed if GPS is present in HWI
VCTCXO ClockTamer use VCTCXO with DAC instead of TCXO with VCO+PLL is `VCTCXO` is present in `HWI`

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,<val>`", "`SET,,OUT,<val>`" 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.

EEPROM variables

Variable Description
Fosc Oscillator frequency
Fout Output frequency
VCO_MIN Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit
VCO_MAX Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit
VCO_Kbit Parameter for calculation of VCO registers for LMX. Shouldn't be changed unless you change LMX on your unit
LMK_OutMask Enable/disable output generation on specific LMK outputs. Set bit in the mask to 1 to enable corresponding output and to 0 to disable it. E.g. x60 value will enable 5 and 6 outputs and disable all others. See outputs numbering below
AutoFreq Autostart generating output on boot
DacValue DAC value if VCTCXO is used
AutoGPSSync Continuously synchronize clock to GPS

Outputs numbering

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.