Welcome to QUISK (February 2014)

This is Quisk, a Software Defined Radio (SDR). You supply an antenna, a complex (I/Q) mixer to convert radio spectrum to a low IF, and send that IF to the left and right inputs of the sound card in your computer. The Quisk software will read the sound card data, tune it, filter it, demodulate it, and send the audio to headphones or speakers. Quisk has a microphone input and a key input so it can operate as a complete transceiver. Quisk works with this hardware:

Quisk is small and simple, and has been designed so that it is easy to change Quisk to suit your own hardware. Quisk rhymes with "brisk", and is QSK plus a few letters to make it easier to pronounce. QSK is a Q signal meaning full breakin CW operation, and Quisk has been designed for low latency. Quisk includes an input keying signal that can mute the audio and substitute a sidetone.

Please read the file CHANGELOG.txt for changes.

When running Quisk for the first time, please press the "Help" button on the lower right.

Credits

Quisk was originally written by James Ahlstrom, N2ADR.

Thanks to Leigh L. Klotz, Jr. WA5ZNU for configuration improvements, factoring out my eccentric hardware control, and adding panadapter and other hardware support.

Thanks to Franco Spinelli for a fix for the H101 hardware.

Thanks to Andrew Nilsson VK6JBL for adding support for SoftRock Rx and Tx.

Thanks to Terry Fox, WB4JFI, for code to support the Charleston hardware.

Thanks to Maitland Bottoms, AA4HS, for the sub-module linkage patches.

Thanks to Philip G. Lee for adding native support for PulseAudio.

Many others contributed to Quisk, and are mentioned in comments in the source code.

Installation


Quisk is registered on http://pypi.python.org; just search for "quisk" to see the latest version and the download URL. The download page is http://james.ahlstrom.name/quisk/index.html. There will be a source distribution (a tar.gz file) and a binary Windows version (msi installer). The Linux version is for 32-bit Linux. If you get the message "wrong ELF class", you have 64-bit Linux, and you must recompile (use "make"). You do not need to compile the Windows binary, but you need Python to run it.

You must have Python installed on your computer, preferably version 2.7. Linux almost certainly has Python installed. For Windows, visit http://www.python.org and download the Windows installer for Python 2.7 to install it. You must also install the latest wxPython package for your version of Python from http://www.wxpython.org.

Linux

I recommend that you just uncompress and un-tar the tar.gz file somewhere under your home directory:

gunzip quisk-3.4.4.tar.gz
tar xf quisk-3.4.4.tar
# Check directory quisk-3.4.4 before removing the tar file
rm quisk-3.4.4.tar
# Perhaps change to a shorter name unless you want multiple versions
mv quisk-3.4.4 quisk

That way all the source for Quisk is available so you can change or add to Quisk. If you need to recompile the source, use the "make" command in the quisk directory. If there are compile errors or missing *.h files, you must install some "dev" packages. See below for needed "dev" packages.

Run Quisk using a terminal with the command "python quisk.py". If there is any error output, it will appear on the terminal. After testing, you can create a panel launcher with the same command but a full path, for example "python /home/jim/quisk-3.4.4/quisk.py" or "python /home/jim/quisk/quisk.py" if you used the shorter name . Then just click the button to run Quisk.

Another way to install Quisk is to change to the superuser (root) and run "easy_install quisk" or "python setup.py install". If you don't have easy_install, install the python-setuptools package (for Debian/Ubuntu). This method installs Quisk as a package. But you need to be root, and the source is not in a convenient place; it is in /usr/lib/python2.7/site-packages. And there is no uninstall feature.

Quisk needs a few additional packages to run. All should be available as packages or RPM's so you don't have to compile the source. Generally you would get the most recent versions rather than the versions I show below. Needed packages are:


If you want to attach a key status line to your computer, you need to change is_key_down.c and run "make". I currently use Ethernet to send key up/down status. I previously sent a 5 volt CMOS signal to my parallel port, but new computers often lack a parallel port, and Ethernet is much easier.

If you decide to use the parallel port, you need the ppdev Linux driver. To load it on boot, add it to /etc/modules (on Debian). The permissions on the port (on Debian) are 660, group "lp". So add yourself to the "lp" group. Otherwise you will have to run "modprobe ppdev", and run "chmod 666 /dev/parport0" as root to access the parallel port.

Quisk does not use the serial port, but some of the special hardware files do. If you need Python serial port support, install pyserial from package python-serial. Note that many programs use USB, but are based on a USB to serial converter, and pyserial works with these too.

Windows Installer

To install Quisk, first install Python and wxPython (see above). Next download the quisk.msi installer, right click it, and select "install". This is best for those who plan to run Quisk, but not work with the source code. To uninstall Quisk, use the Control Panel item Add/Remove Programs. Quisk is installed in the site-packages folder under the Python 2.7 libraries. This enables Quisk to be imported as a package by other software.

Windows Source

If you want to see and change the source code, or recompile the Windows version from source, download the source tarball (the tar.gz file), uncompress it and extract it into a directory somewhere. This is the same as the Linux install proceedure. I use the directory C:/pub/quisk because I synchronize this directory using SpiderOak on multiple computers. You should probably choose a directory under C:/Users/my_name with Windows 7, or perhaps a directory under the Documents folder. You can then run Quisk with the command "C:\python27\pythonw.exe quisk.py" from the Quisk directory, the directory where quisk.py is located. You can create a shortcut on the desktop with this command. There is no need to recompile unless you change the C language source, as the needed DLLs are included. You can change any of the Python *.py files, and there is no need to recompile.

To recompile the DLL, install the MinGw compiler and the same dependencies as the Linux version, and enter "make win". If you get errors, look for missing *.h files from missing dependencies.

Quisk Files


These are the Quisk files in the distribution:

Configuration

Quisk does not have a menu to control its operating parameters. Instead, you must create and edit your own configuration file. For Linux, the default configuration file name is ".quisk_conf.py" in your home directory; that is, "~/.quisk_conf.py". For Windows, the default configuration file name is quisk_conf.py in your My Documents folder.
To help you get started, there are several configuration files included, such as quisk_conf_model.py for sound card, quisk_conf_sdriq.py for SDR-IQ, and quisk_conf_fixed.py for fixed VFO such as SoftRock. Do not change any of the quisk_conf_*.py files. Instead copy one of these files (but NOT quisk_conf_defaults.py) to your own config file. Newer versions of Quisk will not overwrite your personal config file.

The file quisk_conf_defaults.py contains all Quisk's parameters. It is read in first; then your config file is read in and overwrites some parameters. Do not copy quisk_conf_defaults.py to your config file. It is too long and is subject to change with each new version. Instead, read it to see what you can change, and then just put the lines that need changing into your config file.

If you are controlling custom hardware, you will need to specify a hardware file in quisk_conf.py. The default is quisk_hardware_model.py. Look at the other quisk_hardware_*.py files. For example, quisk_hardware_fixed.py is for crystal controlled SoftRock. To use that hardware file, change your quisk_conf.py to include:

import quisk_hardware_fixed as quisk_hardware

There are comments in quisk_conf_model.py showing this change. If none of the hardware files do exactly what you want, copy one of them to your own quisk_hardware.py, edit that file, and include this line in quisk_conf.py:

import quisk_hardware

Newer versions of Quisk will not overwrite your quisk_hardware.py. Your hardware file enables you to customize Quisk without changing the Quisk program files.

Alternatively, you can define a class named "Hardware" in your config file, and that class will be used instead of a hardware file. This is recommended only for simple hardware needs. The class should start like this: 

from quisk_hardware_model import Hardware as BaseHardware
class Hardware(BaseHardware):
    def __init__(self, app, conf):
        BaseHardware.__init__(self, app, conf)
        # Start your hardware control here.
        # For ideas, see one of the other hardware modules.

Both the config file and your hardware file are written in the Python language. Python is an easy to learn but powerful computer language. Quisk can be adapted to different hardware because of the power of Python.

Sound Cards

If you use a sound card for input, the quality of your sound card is critical; but you can start with the sound card you have. Check the Graph screen with no input to see the noise floor. It should be as flat and as low as possible, with no bump near zero Hertz. The 0dB line at the top of the Graph screen is the maximum level, so if your noise floor is at -90 dB, you have that much dynamic range. The IF (sound) input to the sound card should raise the noise floor only slightly to avoid losing dynamic range.

The sample rate determines how much of the band you can see on the screen. My 96 kHz card shows a little over 80 kHz of bandwidth, from -40 kHz to + 40 kHz centered at the VFO frequency. Generally you would choose the highest rate available to get the most visible bandwidth. Be aware that a card claiming to work at (say) 192 kHz may in fact play at that rate, but only capture (record) audio at a lower rate. It is the capture rate that matters. Enter only the sample rate you know your raw hardware supports for capture.

If you use the SDR-IQ or other hardware for input, you still need a sound card for sound output. The quality of this card is not so important, so try the one you have. Be aware that most sound cards require the capture and playback rate to be the same when used for both. Here are some sample configurations:
If you buy a new sound card, make sure you know the capture (recording) sample rates and the noise level. Sound cards are usually specified over the audio range up to 24 kHz or so. But we need low noise and distortion over the whole range.

Linux Names

Quisk can use PulseAudio, PortAudio or ALSA to access your sound card. Names can be a fragment of text from the device description. It is better to use this text search rather than an index number, because the index number can change if you plug and unplug USB sound cards.

The ALSA drivers use different names for the same sound card to provide different access. The names "hw:0" and "hw:1" refer to the raw hardware devices of the first and second sound card. You should use the raw hardware if possible. If the raw devices don't work, use the "plughw" name. The ALSA name can also be a string name. Here are some ALSA names: 
"hw:0"		# First sound card
"hw:1"		# Second sound card, etc.
"plughw"	# plug device
"default"	# alsa default device
"alsa:NVidia"	# Search for the name in the alsa device description
Alsa names starting with "alsa:" are an extension to the normal alsa names. They search for the text after the colon in the alsa device name. The alsa device names are shown on the config screen. Or you can start a terminal window and enter "aplay -l" for a list of play devices, or "arecord -l" for a list of capture devices. See alsa_names for more information.

The PortAudio interface is newer, may be easier to get working, and may be used to connect Quisk to other programs (I have not tried this). But for CW, ALSA has lower latency. Run "python portaudio.py" in a terminal window to see a list of available names, or use a different PortAudio tool. Here are some PortAudio names: 
"portaudio:(hw:0,0)"    First sound card.
"portaudio:(hw:1,0)"    Second sound card, etc.
"portaudio:NVidia"      Search for the name in the portaudio device description.
"portaudio#1"           Directly specified index.
"portaudiodefault"      May give poor performance on capture.

Linux Sound Servers

Newer Linux systems are now shipping with PulseAudio enabled. PulseAudio is a sound server, a program that takes control of your sound cards, and controls usage by applications. The idea is that your applications talk to PulseAudio, and PulseAudio talks to the sound cards. Another example of a sound server is JACK. You can control the sound routing with the pavucontrol program. Remarkably, this is not included with PulseAudio, and you will need to install the pavucontrol package first.

Thanks to Philip G. Lee, Quisk now has native support for PulseAudio. Just use the name "pulse".

Linux Problems

If Quisk appears to run but you get no sound input or output, you may be having trouble with your settings. Start Quisk and look at the graph. You should get a moving line display. Look at the Config screen. Interrupts should be increasing and latencies should fluctuate. If all this looks normal, but you get no sound output, or you get only white noise output, then you may need to change your settings with a mixer program.

If you capture data with the sound card (no SDR-IQ) then you need to set the "capture device" to the line-in jack, and set the volume of the line-in to 100%. To play sound, you need to increase the volume of the playback device. Since a typical sound card has ten or twenty controls for all its analog and digital inputs and outputs, it is a guessing game to figure out which control to adjust.

Basically you start the alsamixer program (use "man alsamixer" first) and adjust the volume controls and capture device until Quisk works. It is wise to reduce or mute unwanted inputs to avoid adding extra noise. Quisk does not do this for you. But once you have the controls set, they will stay the same and Quisk should keep working until you run another audio program that changes them.

To make Quisk adjust the mixer controls when it starts, you need to know the control id number. Run the command "amixer -c 0 contents" (for card zero) and look at the control ids, names and values of all your controls. Figure out the control you need to adjust. For a setable option (on/off) the control value is one or zero. For a volume it is a number from 0.0 to 1.0. Make a list of (device_name, numid, value) and add it to mixer_settings in your .quisk_conf.py file (see quisk_conf_defaults.py). I don't need to do this on my computer except for the microphone input on my second sound card.

If you really get stuck, try one of these commands (see the "man" page):
And try to play an audio CD or run some other Linux audio program just to see that you have a working sound system. If you can't get ALSA to work, you could try the PortAudio or PulseAudio interface by just changing the sound card names.

For more information try these articles:
http://linuxplanet.com/linuxplanet/tutorials/6465/1/
http://linuxplanet.com/linuxplanet/tutorials/6466/1/

Windows Names

To see what sound cards you have, use the Control Panel item Sound Devices. There is a separate list for capture (recording) and playback devices, and a specified default device for each. The name of the default device is "Primary". To specify your sound card name, use either "Primary" or a substring of the device name. The search is case sensitive.

SDR-IQ as Input


Quisk can use an SDR-IQ from RfSpace instead of a sound card for input. Edit your config file to select the SDR-IQ. Read quisk_conf_defaults.py to see what changes you need to make. For Linux, try the USB driver that came with your system first. If you need a faster driver, install the ft245 Linux USB driver. See http://james.ahlstrom.name/ft245 for installation instructions. You still need a sound card for output. The output is 48 kHz stereo and a high quality card is not required. Files that support the SDR-IQ are now in subdirectory sdriqpkg.

Timing


There are several configuration parameters devoted to tuning; read the file quisk_conf_defaults.py for documentation. For most users, Quisk should run fine with the default settings. But if you use Quisk as part of a QSK CW transmitter, you should reduce latency_millisecs to as low a value as possible. This will reduce latency, but increase the likelihood of clicks and pops due to sound buffer underruns.

USB Control

Many radio devices are now controlled through a USB interface. In many cases, the interface is actually a serial port, and an external or internal USB to serial converter is used. In other cases, the USB is native, but requires a custom device driver. In still other cases, the USB device announces itself as a standard device such as a sound device or human interface device, and uses a standard operating system built-in driver.

Linux

Default USB permissions do not allow a non-root user to write to the bus. You may find that Quisk will complain about lack of permission to access the USB. You could test this by running Quisk as root and seeing if that works; but this is not acceptable except for testing. To change USB permissions, add a rule to /etc/udev/rules.d/local.rules (for SoftRock on Debian and Ubuntu) like this:

SUBSYSTEM=="usb", ATTR{idVendor}=="16c0" , ATTR{idProduct}=="05dc", MODE="0666", GROUP="dialout"

This changes the USB device permissions to read/write for all users, and changes the group to the "dialout" group. Default group permissions are read/write, so if you are in the "dialout" group, you don't need "MODE"; modify as appropriate. To load the new rule, you can either reboot or on Ubuntu use

sudo udevadm control --reload-rules

Custom Hardware

Quisk receives RF using your sound card or your SDR-IQ out of the box. But if you have custom hardware such as a VFO or a transmitter, you need to describe your hardware to Quisk.

First, Quisk h