Welcome to QUISK (July 2010)
============================

NOTE:  Quisk now requires that PortAudio Version 19, API version 2.0
       (or newer) be installed.  Most Linux distributions will have
       PortAudio installed, but you will also need the development
       files.  Look for package portaudio19-dev (or newer).  If you
       can't get this, email me for help.

NOTE:  Please read the file quisk_conf_defaults.py for additional information.

NOTE:  Please read the file CHANGELOG.txt for changes.

Please read Documentation.html too.

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

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 the same sound card for output to
external headphones or speakers.

Quisk can also accept I/Q data from the SDR-IQ from RfSpace.  The selection
of SDR-IQ or sound card is made in the configuration file.

Quisk can be used as a panadapter, and can control some radios.  Many thanks
to Leigh L. Klotz, Jr. WA5ZNU for his many contributions to Quisk.

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.

Currently Quisk runs only on Linux or other Unix systems.

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.

CONFIGURATION
=============
Quisk will run with no configuration file using the first sound card.  There
are several configuration files included, including 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.  The complete list of configuration parameters is in
quisk_conf_defaults.py; read this file to see what you can change.

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 ~/.quisk_conf.py.  If this
file exists, it is used to overwrite the defaults in quisk_conf_defaults.
Newer versions of Quisk will not overwrite your ~/.quisk_conf.py.

Do not copy quisk_conf_defaults.py to your config file.  It is too long, is subject
to change with each new version, and must always be imported.  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.

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.


SOUND CARD AS INPUT
===================
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
IF input to see the noise floor.  It should be as flat and as low as possible,
with no bump at 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 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.

Quisk can use PortAudio or ALSA to access your sound card.  The PortAudio
interface is newer, and may be easier to get working.  But for CW, ALSA has
lower latency.  These are the PortAudio names:
  "portaudio:(hw:0,0)"     First sound card
  "portaudio:(hw:1,0)"     Second sound card, etc.
  "portaudio#1"            Directly specified index
  "portaudiodefault"       May give poor performance on capture
To use another name, you need to know what PortAudio devices you have.
Run "python portaudio.py" in a terminal window to see a list, or use
a different PortAudio tool.  See quisk_conf_defaults.py for more information.

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 "hw" names if possible.  If the "hw" names don't work,
use the "plughw" name.

Look at the available sample rates.  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 buy a new sound card, first make sure there is a Linux driver
available.  See www.alsa-project.org.  And make sure you know the
capture (recording) sample rate.  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.

SDR-IQ AS INPUT
===============
Quisk can use an SDR-IQ from RfSpace instead of a sound card for input.  Edit
.quisk_conf.py to select the SDR-IQ.  Read quisk_conf_defaults.py to see
what changes you need to make.  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.

INSTALLATION
============
As of Quisk version 3.0 Quisk is distributed on http://pypi.python.org;
just search for "quisk" to get the latest version.  There will be a source
distribution (an sdist) but no binary distributions (a bdist_egg).
The distribution conforms to all Python standards, and can be installed
using distutils, easy_install, or just by un-taring the tar.gz file.

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.  Next recompile the source using 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".  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.6/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:

  python2.5, the Python programming language.  See www.python.org.  This
          almost certainly is already installed on your Linux.  Use the
          version you have, or get the most recent version.

  python-wxgtk2.8, the wxPython package used for the GUI.  Get the most
          recent version available for your Python version.

  fftw3, the Fastest Fourier Transform in the West.  See fftw.org.  This is
          a great FFT package and is also used by GNU radio.

  python2.5-dev, fftw3-dev, libasound2-dev, portaudio19-dev
          These are development packages that you need so you can change
          and recompile the Quisk C-language files.  Get the version that
          corresponds to the software you have.  If you get compiler
          errors, check for missing "-dev" packages.

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.

SHARED LIBRARIES
================
The main Python extension module for Quisk is _quisk.so.  It is a shared
library.  To import it, it must be on the Python path.  There are other
Python extension modules (shared libraries) for other hardware, for example,
sdriq.so.  Quisk works fine when all these modules are in package subdirectories.
If you want to put them somewhere else, be aware that sdriq.so
and all other such modules are linked with _quisk.so and must be able to find
_quisk.so at run time.  You need to follow the Linux rules for searching for
shared libraries.  Try using the "ldd sdriq.so" command to see your library
dependencies.  Also try readelf -d sdriq.so.

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.


These are the Quisk files in the distribution:
==============================================
quisk.py
     is the main program and is written in the Python language.  Python is
     a powerful but easy to learn language, and I hope you have fun changing
     Quisk to make it do what you want.  Python is also useful for general
     electronics calculations such as complex arithmetic.  See www.python.org.
     Quisk.py uses the wxPython Python package to make the screen interface.

help.html
     is the help file for quisk.  Press the "Help" button.

_quisk.so
     is the _quisk extension module used by quisk.py.

sdriq.so
     is the extension module needed for the SDR-IQ.  It needs _quisk.so to
     be available when it starts.

makefile
     is the makefile, and you must run "make" to create a new _quisk.so
     unless you use a Python installer that creates _quisk.so itself.

setup.py
     is used by makefile and the Python installers.

quisk_conf_defaults.py
     is the basic configuration file imported into all other configuration
     files.  Read it (but don't change it) to see what you can change in
     your own quisk_conf.py.

quisk_conf_*.py
     are various Quisk configuration files.  Copy one of them to your own
     .quisk_conf.py and edit that file.  I may publish new model files in the
     future, and you don't want your changes to be overwritten.

quisk_hardware_*.py
     are various quisk hardware control programs.  If you have custom hardware,
     import one of these files into your quisk_conf.py.  Or copy one of them to
     your own quisk_hardware.py, edit that file, and import it in .quisk_conf.py.

quisk.c, quisk.h
     are the files for the _quisk extension module used by quisk.py.  The other
     C-language files are linked with these to make _quisk.so.

sound.c
     is sound card access code that supports both PortAudio and ALSA.

sound_portaudio.c
     is the sound card access code for PortAudio.

sound_alsa.c
     is the sound card access code for the ALSA drivers.

is_key_down.c
     is the hardware key checker for the PC.  I use Ethernet to send the key
     status, but there is code for the parallel port and dummy code too.

sdriq.c, sdriq.h
	are the files that make sdriq.so and support the SDR-IQ.

microphone.c
    reads the microphone audio and sends it to your hardware using Ethernet.  Change
    it for other sound access.

portaudio.py
	is a utility program.  Run it to list your PortAudio devices.  It is not
    used by the Quisk program.

BUGS and PROBLEMS
=================
If you get the message
    python: pcm_params.c:2259: snd_pcm_hw_refine: Assertion `pcm && params' failed
please upgrade to Quisk 2.3 or later.  This bug affects the SDR-IQ only.

The makefile and setup.py files used to have the Python version 2.4 hard coded.  But
Python 2.6 is the current version and is appearing in Linux distributions.  As of
Quisk 2.3, these files have been rewritten to automatically use the default installed
version of Python.

I will rewrite quisk to work with Python 3.x, but I don't have 3.x yet.

HELP with SOUND CARDS
=========================
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.
The settings you need are as follows:

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):
  alsamixer             An ALSA mixer program with a curses interface.
  amixer                A character ALSA mixer.
  aplay                 Play sound.
  arecord               Capture sound.
  speaker-test          Play sound to test your speakers.
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 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/