ClockTamerGUI

Democratising Wireless Innovation
Jump to navigation Jump to search

Introduction

The GUI is a very simple application to control ClockTamer without having to type all those boring commands in a terminal. It's written with Python and Qt4.

Current limitations:

  • Works only under Linux.
  • Assumes that your ClockTamer is connected with miniUSB and appears on your system as /dev/ttyACM0.


Improvements are welcomed!

Prerequisites

To build and run !ClockTamer GUI you need:

  • Git version control system
  • PyQt4 development packages
  • pyserial python module

To get those packages on Ubuntu, run:

sudo aptitude install mercurial python-qt4-dev pyqt4-dev-tools python-numeric.

Building and running on Linux

After you have installed all the prerequisites, you're ready to build the ClockTamer GUI. Download the sources from our GitHub repository:

git clone https://github.com/myriadrf/clock-tamer.git

Compile the GUI:

cd clock-tamer/host/tamer-gui
./mk.sh

If everything goes OK, compilation will run silently and produce a bunch of additional `.py` files. Now run the GUI:

./tb.py

Running on Windows

You need to install:


Then clone https://github.com/myriadrf/clock-tamer.git and run *tbwin.cmd*. (You may need to update tbwin.cmd to actual path of your python installation)

Description

Console output

If you run the GUI from a console, you will see all the commands the GUI sends to a connected ClockTamer, along with its responses. This output can be useful for learning the ClockTamer control protocol usage.

Outputs numbering

The image at the top of the GUI window shows a ClockTamer and the outputs numbering scheme. LVDS differential outputs are numbered as `N+` and `N-` for positive and negative wires correspondingly, where `N` is the output number. CMOS outputs have only one connector and have a number without `+` or `-` near it.

Note, that later ClockTamers have so-called half-LVDS outputs, where only positive wire (`N+`) is accessible to the user and the negative wire (`N-`) is properly terminated on the ClockTamer PCB. Refer to the Features and technical specification for more details on half-LVDS usage.

Hardware and software versions

This section of the GUI displays the version of the ClockTamer hardware (`HWI`) and version of the ClockTamer firmware (`VER`). Refer to Control Protocol documentation for details. This section is read-only.

Enabled outputs

This section of the GUI displays the currently enabled outputs and allows you to enable/disable them. Set the checkbox to enable the corresponding output, and clear the checkbox to disable it. Checkboxes with LVDS/P+ label correspond to half-LVDS outputs.

Note that the power consumption of the ClockTamer increases considerably with increased number of outputs enabled. Make sure you provide enough power to the ClockTamer if you enable more then 1 output. E.g. you have to remove the current-limiting resistor on USRP1 if you power the ClockTamer from its fan connector. Alternatively, you can use a mini USB cable connected to USB port with 500mA power supply.

All changes are applied only when you press "Set" button (see below).

Frequency generation options

This section of the GUI shows current values of `Fosc` and `Fout` parameters.

Fosc parameter should be equal to the real frequency of the reference TCXO/VCTCXO in Hz. Change this value to calibrate your ClockTamer before use. For 20MHz TCXO 1Hz change to `Fosc` equals to 50ppb (1/20e6). Refer to Calibration page for details of calculations.

Fout parameter equals to ClockTamer output frequency in Hz. Actual output frequency may differ from this value up to calibration precision. The closer the `Fosc` value is to the real frequency of the reference TCXO/VCTCXO, the closer the actual output frequency is to the `Fout` value.

Disable internal oscillator checkbox let you disable internal !ClockTamer oscillator in case you want to connect an external reference clock source. Most users don't need to do this.

If Start on power up checkbox is set, ClockTamer will start generating the output frequency as soon as power is applied. Otherwise you have to manually start frequency generation. The default is to start frequency generation on power up.

All changes are applied only when you press "Set" button (see below).

GPS information

This section is read-only and shows you the state of GPS synchronization. The section is not visible if your ClockTamer is not fitted with a GPS module.

Keep in sync with GPS checkbox lets you enable/disable automatic synchronization with GPS. Note that automatic synchronization will not actually occur until GPS module locks to satellites. Satellite lock usually takes less then 60s, so if you don't get lock within this time consider checking GPS antenna connection and sky view. One frequent problem with GPS lock indoors is window glass with metallic coating - in this case you have to place the antenna outside. Changes are applied only when you press "Set" button (see below).

In sync (green) and Out of sync (red) labels show the current status of GPS lock.

1PPS count shows the number of 1pps pulses received from the GPS module. This value should increase once a second if GPS is locked to satellites.

Calculated Fout shows an estimated output frequency. This value becomes meaningful a few seconds after GPS lock acquisition. ClockTamer uses the difference between this value and desired Fout value for calibration when Keep in sync with GPS option is enabled.

Control buttons

Set button applies changes you made in the GUI to the ClockTamer. No changes are applied until you press this button. Changes are NOT saved permanently with this button and will be lost if you power down your ClockTamer.

Get button reads values from the ClockTamer. Use this button if you want to reset changes you've made in the GUI, but haven't applied to the ClockTamer.

'Store to EEPROM button stores current ClockTamer settings to the permanent storage, which will allow them to survive power down. Store to EEPROM if you don't want to lose your settings! Note, that Store to EEPROM button stores to EEPROM the current ClockTamer settings, so if you have made any changes in the GUI you have to apply them with Set button first.

Load from EEPROM button loads ClockTamer settings from EEPROM, undoing all changes which were made since last Store to EEPROM. If you haven't done Store to EEPROM yet, this will reset to factory settings.