initial commit
[amrad.git] / projects / dsp / charleston_build.txt
1 This is a quick description on how to build the Charleston Rx1 support for James Ahlstrom's Quisk, Version 3.4.8.
2                         By Terry Fox, WB4JFI.  Contact: wb4jfi@knology.net
3 Quisk is written by James Ahlstrom, see http://james.ahlstrom.name/
4 This file is based on installing on a system with Ubuntu 10.04LTS
5
6 The first step is to add all the dependencies, libs, etc, for a successful Quisk compile.  You will open Synaptic Package Manager (SPM) (under System/Administration/Synaptic Package Manager in the top-of-screen menu)(password required), then make sure "All" is selected in the left window.  In the "Quick Search" window, type in each of the following searches.  You will then highlight the recommended packages shown below by clicking on the little square box to the left of the package name.  Then, select "mark for installation".  You can either install each section individually by then clicking on "Apply" in the upper SPM menu, or wait until all packages are selected before clicking on Apply.  I usually do each section, that way I get a quicker warning if errors show up.  There will be other packages that have been previously installed either by you or the original Ubuntu installer.  In general, you can leave these other packages alone, with one exception, bluez-alsa, as noted below.  If you are interested, you can also install the "doc" packages for each of these.  Experts can use the "sudo apt-get install 'package'" method...
7
8         A) (Charleston only) get libusb and support.  SDR-IQ uses a separate FTDI driver, see James Ahlstrom web site.
9                 Open Synaptic Package Manager, and search for libusb.  You want to install at least two files:
10                         libusb-0.1-4    (this package may already be installed)
11                         libusb-dev
12                 These files may also be installed (I'm not sure which libusb is a better long-term solution)
13                         libusb-1.0-0
14                         libusb-1.0-0-dev
15
16         B) get fftw3.
17                 In SPM, search for fftw.  You want to install two files:
18                         libfftw3-3
19                         libfftw3-dev
20
21         C) get Python and dev support.  Python may already be installed:
22                 In SPM, search for python.  You want at least these two files:
23                         python (should already be installed, mine shows 2.6.5-0ubuntu)
24                         python2.6-dev
25
26         D)  get sound_alsa support, and remove bluez-alsa, which can cause error messages at runtime.
27                 In SPM, search for alsa.  Note that if you are running a 64-bit machine/Linux, you may want the 64-bit versions.
28                         libasound2 (or 64-bit lib64asound2)     This file should already be installed.
29                         libasound2-dev (or 64-bit lib64asound2)
30
31                 In SPM, still under alsa, find bluez-alsa, and click on it, then select "Mark for Removal"
32
33         E)  get portaudio and support.
34                 In SPM, search for portaudio.  You want to install two files:
35                         libportaudio2 (should already be installed)
36                         portaudio19-dev
37
38         F)  get Python wxgtk support.  There will be additional packages automatically installed during this step.
39                 In SPM, search for wx.  One of these (and its support packages) may already be installed
40                         python-wxgtk2.6
41                         python-wxgtk2.8
42
43 That should complete downloading and installing the dependencies.  Now we need to make sure that the proper wx package is used.  How to fix this has changed in Ubuntu 10.04.1 versus 10.04.  The following paragraph is for the newer 10.04.1, and the paragraph after that is for the older 10.04.  This step is necessary to eliminate an Attribute error.  There are probably other ways to resolve the problem, but this works for me.  The error is: AttributeError: 'module' objuect has no attribute 'BitmapFromBuffer'.
44
45 DO ONLY ONE OF THESE NEXT TWO STEPS:
46 10.04.1 (newer version)fix:
47         Edit the file wx-2.6-gtk2-unicode.pth to point to wx-2.8 instead.  This needs to be done with superuser priveleges.
48         A) cd /usr/lib/python2.6/dist-packages
49         B) sudo vi(or other editor) wx-2.6-gtk2-unicode.pth
50         C) Change FROM: wx-2.6-gtk2-unicode  TO: wx-2.8-gtk2-unicode
51                 (note: you are only changing the character: "6" to: "8")
52         D) save the edited file
53
54 10.04 (older version) fix:
55         Copy a wx2.8 file to be a wx2.6 file.
56         A) cd /usr/lib/python2.6/dist-packages
57         B) sudo cp wx-2.8-gtk2-unicode.pth wx-2.6-gtk2-unicode.pth (you will need to enter your password)
58
59 Next, make sure the charleston folder and its files are within the appropriate Quisk (version) folder.  For example, copy/move the charleston folder into ~/quisk3.4.8.  Users of my combined quisk-3.4.8.tgz file can skip this step.
60
61 copy the (ver)quisk_conf.py file from the charleston directory to your home directory as .quisk_conf.py (cp chas3.4.8quisk_conf.py ~/.quisk_conf.py).  NOTE there is a period before the file name in the final copy.
62
63 The file you just made (~/.quisk_conf.py) holds several configuration parameters that can be tweaked.  For now, leave it as it was, as its default values work for a Charleston board.  You can edit it, but because of the period at the front of the name, it may not show up in normal folder listings.  I use the old "joe" editor (SPM, and search for joe), because it reminds me of the old CP/M and WordStar days.  Plus, I HATE, HATE, HATE vi, emacs, etc.  I edit this file to select between my SDRIQ and Charleston boards.
64
65 Finally, all the preliminary work should be completed.  cd to the quisk directory, and type: make.  If all goes well, you will not see any error messages, just several lines during compile time.  Note that Jim's make also makes the SDRIQ directory, but not the charleston directory.
66
67 Next, compile the charleston support software.  cd into (quiskdir)./charleston, and type: make.  A couple of lines of files will be compiled will go by, hopefully no error messages here either.  You should ALWAYS compile the main quisk directory first, then the charleston directory, to make sure all files are properly synced.
68
69 If you were able to compile without errors, you are ready to test the code.  Plug the Charleston USB connector in, and wait for the amber "DONE" led to light.  cd back to the main quisk folder, and type: "python quisk.py".  After a few seconds, the Quisk window should appear, and the LEDs LD0, LD1, LD5, and LD6 shoudl start flashing quiskly.  The flashing leds indicate that data is being passed between the Digilent FPGA board and the host computer.
70
71 If you get a blank spectrum display and errors such as:
72 Init Chas Rx1: Chas Init failed!
73 Quisk Open Chas Rx1: Failed
74
75 then the Charleston board was not successfully connected to Quisk.  This is probably a hardware problem, double-check cables, Digilent power switch, etc.  Another possibility is that the USB port does not have user-access priveleges, make sure you start Quisk using sudo, or use the Python method mentioned above.
76
77 Another way to start quisk is to type: sudo ./quisk.py.  You will need to type in a password.  I'm working on why you need to run quisk as root (sudo) using this method, as one of my computers does not require this.  This method of starting Quisk allows the last parameters to be saved upon exit, allowing the next Quisk session to start with the same configuration.  For that reason, THIS IS MY PREFERRED WAY TO RUN QUISK.
78
79 Once Quisk is successfully started once, it creates a file in your home (~) directory called "quisk_init.pkl".  This file holds the startup properties, such as band and frequency last used when shut down.  This file may have permissions that limit its alterations, effectively preventing it from being updated.  The can be changed in two ways, one is to change the group from (probably) root, to your group.  The other is to change the permissions to allow read and write by all (666).
80
81 I have included a subdirectory in charleston called filter_display.  I added a shadow to the quisk display that shows the present audio filter bandwidth, based on tuned frequency, mode, filter bandwidth, sample rate, etc.  It is still a little sketchy (but no crashes that I know of), so it is included for your enjoyment.  To use it, copy the file "filter_display_quisk.py to the main quisk directory as quisk.py.  Next, copy the file filter_display_quisk_conf_defaults.py to the main quisk directory as conf_defaults.py.  Note that these overwrite Jim's original version of those files, so make a copy of his versions first.  I usually put them in another folder called "originals".  Now, try it out.  Since these are Python files, no recompiling is necessary.
82
83 I also made notes on the changes necessary to add the filter_display to the above quisk files.  Those notes are in the file "filter_mods3.4.x.txt", where the 3.4.x is the quisk version.  These notes may help down the road as Jim modifies the quisk files.
84
85 That's it for the moment.  Enjoy Quisk on your Charleston SDR Receiver!
86 Terry, WB4JFI
87
88