v.1.0
Copyright © 2002 Ernest Stracener, KG9NI
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
Abstract
KPSK is a PSK31 digital radio communications application for use by licensed amateur radio operators and designed specifically for the KDE 3.x desktop environment.
Table of Contents
Table of Contents
This document addresses:
Installation and troubleshooting for KPSK v.1.0 and later versions. Most of the information in this document also applies to earlier versions, but no effort has been made to verify applicability of this information to earlier versions.
Basic configuration and operation of KPSK
This document does not address:
Soundcard installation or configuration (See Sound-How-To)
Configuration or cabling of PSK31 interfaces
Linux Distributions Tested with this release of KPSK:
SuSE 8.0, 8.1 (by Luc)
RedHat 7.3, 8.0 (by David, Ernest)
Mandrake 8.2, 9.0 (by Ernest, John)
Debian 3.0r0 (by Ernest)
KPSK is a PSK31 digital radio communications application for use by licensed amateur radio operators. KPSK is designed for the KDE 3.x desktop environment and provides:
A deceivingly simple, yet very robust and customizable user interface
Basic QSO logging capabilities
Twelve user-defined ?fixedtext?, or macro, dialogs to simplify basic elements of QSOs.
Simultaneous monitoring of four different PSK31 signals in separate receive windows
QPSK or BPSK operation
Please report any problems or feature requests to the <kpsk-users@lists.sourceforge.net>mail list.
Table of Contents
Before using KPSK, you should familiarize yourself with the menus and features detailed in the command reference section of this document. The program operation is intended to be intuitive, but some features may not be immediately obvious without first skimming through the command reference.
The executable file is in the KPSK directory and will also be installed to the kde3/bin during the make install portion of installation. To run the program from the command line, be sure that the path to your kde3/bin is in your PATH environment variable. To run the program, issue the command kpsk. You may also start the program by changing to the directory where the KPSK executable is located and issuing the command ./kpsk. An XWindows menu item may also be available within your KDE desktop application menu.
Read this section completely before trying to tune.
For a clean signal, it is critically important that your soundcard input/output levels be properly adjusted.
To "tune" your soundcard, connect your transmitter to a good dummy load and set the output power to its lowest level -- five watts or less (even dummy loads radiate). Place a signal marker on the waterfall with a single left-mouse-click in an area that shows no received signal (with the use of a dummy load, your waterfall should be blank, showing no signals).
If you do not use a dummy load, please be sure to set your power levels to a very low level <5 watts and place your signal marker at least 100Hz or more from any adjacent signal.
Open KMix or your favorite audio mixer application and set your soundcard volume level to its lowest setting. Also set your soundcard "Synth" setting to approximately 25% of its maximum (that is, a quarter of the way up from its lowest setting). Mute your soundcard microphone or set it to its lowest setting. Begin the tuning process with single left-mouse-click on "Tune" in the menu bar (or use Ctrl+T) to put KPSK and your radio into TX and send a carrier signal. Slowly increase the soundcard volume setting while watching your radio POWER/SWR/ALC meter. You may also need to slightly adjust the Synth setting to achieve the proper adjustment. A properly adjusted signal will provide maximum output with no indication of ALC on the radio meter. While you have your audio mixer window open, now is a good time to save your audio mixer settings as the default settings so you will not need to retune your audio signal every time you start KPSK.
More thorough treatment of tuning issues can be found within many PSK31 References; several are provided near the end of this document.
Please help clean up the PSK31 signals on the air by providing signal quality reports to your contacts--praise the excellent signals, help the operators with bad signals improve their signal quality. Most stations don't know they are sending a poor signal.
Place the mouse pointer over a received signal in the waterfall and use a single left-mouse-click to place an RX marker over that signal; a TX/RX marker will be placed on the waterfall and the received information will print in the RX text window at the top of the screen.
KPSK can decode up to four PSK31 signals simultaneously in separate RX windows (main window plus three auxiliary windows). An auxiliary window is created by moving the mouse pointer over a new signal and pressing and releasing the right-mouse-button. This action creates a new RX window for text from that signal and places a waterfall signal marker on the window.
Waterfall RX markers can be dragged into the exact desired position by using your mouse to click-and-drag the marker to the left or right. A new feature allows keyboard control of marker positioning. To move the active marker using keyboard controls, hold down the Ctrl key while pressing the left or right arrow keys.
When an RX marker is ?activated?, or selected, its color will be displayed as bright red. If multiple RX windows are open, non-selected markers will be a darker red color. A single mouse-click anywhere in the waterfall will cause the activated RX marker to be moved to the position beneath the mouse pointer.
A single mouse-click near a waterfall marker will bring that marker's associated RX window to the ?top?, or window focus. To begin a QSO with the originator of a signal being transcribed in an auxiliary RX window, mouse-click on the frequency display area of the auxiliary window's status bar (lower right of window). This action will cause the signal transcription to be switched with the main window RX (that is, the signal being transcribed in the main window will trade places with the signal being transcribed in the auxiliary window). Transmissions take place from within the main window; to hold a QSO with another operator, their signal must be received and transcribed within the main RX text window.
Please Remember: Use only the minimum amount of output power that is necessary for a contact. High power operation for PSK31 contacts is usually not necessary and can be very detrimental to your equipment and to others using the bands. Also note that use of ALL CAPS in transmit increases the time required to transmit your message and is considered by many to be ?rude?, as if unnecessarily yelling at someone standing next to you.
Type your text in the TX text window and toggle TX/RX with Ctrl+T or a single left-mouse-click on the Receive/Transmit area of the status bar. Alternately, you can toggle TX/RX to put the application/radio into TX and type your text. The text that you type in the TX text window will be transmitted over the air--and hopefully received by a new contact in a new country/state/provice/island or by your good friend across town! If properly configured, fixedtext macros can be sent automatically with a single left-mouse-click or press of a function key, <F1>-<F12>. To end your transmission toggle TX/RX again to place the application and radio into receive mode.
When selecting a frequency to call CQ or initiate a contact, please be sure to maintain at least 100Hz separation from other signals to avoid interference with other stations.
If it is necessary to quickly stop transmitting, press the <Esc> key. Transmissions may also be aborted with Ctrl+T or a mouse-click on 'Receive/Transmit' in the status bar.
KPSK uses Berkeley DB as the foundation for the logbook functions. The log file is located in ~/.kde/share/apps/kpsk/log.db and is not human-readable in its native format. There is no easy way at this time to export the data in the logfile to other formats or to print the log. It is highly recommended that users backup the directory and its contained files on a regular basis. If you delete, overwrite, or move your ~/.kde directory KPSK will create a new, blank log.db file in the appropriate location.
Logging a QSO is very simple: complete the QSO fields at the top of the screen and save the log data with Ctrl+S, or through the Save QSO choice in the Logging menu. Additional operational features of the logbook are addressed in detail within the command reference section of this document.
The call check function can be a handy feature for catching a callsign and automatically entering it into the CALL field of the logbook. When used in combination with properly configured Fixedtexts, it will automatically insert the captured callsign into the transmission of the Fixedtext.
Call Check works by examining the RX text for ?de? and picks up the first character string that follows. When activated, it is active in both TX and RX, so if the function is not disabled before TX, it will pick up your own callsign and replace the callsign in the QSO log field with your own! For this reason, a checkbox is located in the upper right of the main window to enable you to turn the callcheck function on or off at as you wish, while retaining your configuration preference for this function. Fixtexted functions are also available to turn this function on and off.
The automatic operation of callcheck can be disabled or enabled as a configuration setting. See the command reference section of this document for more detail. Note that if enabled in Settings->Auto Call Check, Call Check will be re-activated whenever the any of the functions Send CQ, Auto CQ or Save QSO are executed.
KPSK can be customized for semi-automatic operation with the use of up to twelve fixedtexts (text macros). Fixedtexts can be quite useful for routine exchanges or portions of exchanges if carefully constructed and cautiously used. The following markup can be used within fixedtext construction:
Fixedtext construction markup is case sensitive. All markup must be in uppercase.
Table 2.1. Fixedtext Macro Construction Reference
| Markup | Function |
|---|---|
| <TX> | Switch to Transmit |
| <RX> | Switch to Receive |
| <MYNAME> | Sends the your name (from Settings:Personals) |
| <MYCALL> | Sends the your callsign (from Settings:Personals) |
| <MYQTH> | Sends the your location (from Settings:Personals) |
| <BAND> | Sends the current operating frequency |
| <CALL> | Sends the current distant callsign as shown in Call window |
| <NAME> | Sends the current distant name as shown in Name window |
| <NAME> | Sends the current distant name as shown in Name window |
| <QTH> | Sends the current distant QTH as shown in QTH window |
| <RSTR> | Sends the report you received as shown in RST received window |
| <RSTS> | Sends the report you gave as shown in RST sent window |
| <CALLCHECKON> | Enables the Call check |
| <CALLCHECKOFF> | Disables the Call check |
In all cases, if text is missing from the referenced text fields nothing is transmitted. In the second example below, if the Call window in the QSO logging field is empty and the Settings:Personals has been configured to contain N0CAL, the transmitted text would be: DE N0CAL N0CAL
An example of text that might be used in a fixedtext labeled '?QRL?': <TX> QRL QRL N0CAL <RX>
Another example of text that might be used in a fixedtext labeled "BEGIN": <TX><CALL> <CALL> DE <MYCALL> <MYCALL>
One more example of text that might be used in a fixedtext labeled "END": 73 <NAME>, TU FER CHAT! <CALL> DE <MYCALL> SK SK <RX>
After constructing a fixedtext and assigning a label within the fixedtext dialog, the label of that macro will be displayed on one of the 12 buttons displayed just above the RX text window. The fixedtexts can also be activated with the function key corresponding to the fixedtext button, <F1>-<F12>.
Table of Contents
Provides a popup menu to select a text file for transmission via PSK31. Text files can be used for creating "brag" files explaining your station setup or announcing a special event station. It may also be useful for traffic handling where a text message has been received and must be forwarded. This file MUST only contain normal ASCII characters.
Switches the application/radio into TX and sends the following message:
CQ CQ CQ de <MYCALL> <MYCALL> <MYCALL>
CQ CQ CQ de <MYCALL> <MYCALL> <MYCALL>
CQ CQ CQ de <MYCALL> <MYCALL> <MYCALL>
pse K
This CQ string is currently hard-coded. If you wish to change the length or content, you can do so by editing and recompiling kpsk.cpp. The CQ string is located near line 646. Remember to recompile the file after modification!
Repeatedly sends the CQ string as above, with a 12 second RX interval between each TX. To cancel the Auto CQ use the button on the countdown dialog. If you wish to change the interval period between each Auto CQ transmission, the interval is hard coded on line 33 of autocqdlg.cpp. Remember to recompile the file after modification!
Saves current configuration settings and terminates the program
Saves the information in the QSO information fields. Use this command often if you wish to use the integral logbook functions of KPSK.
Clears all information fields for the current QSO; does not affect database entries that have been saved.
Performs a search of the database, using the currently selected QSO information field for the search term. Any results will be displayed in a separate dialog that will enable editing or deletion of matching entries.
If information is present within the current QSO fields, and if other database entries for the same callsign are present, this function will present a summary of past QSO information and a variety of other details relative to that call.
Enters the fixedtext editing dialog. Use and configuration of fixedtext information is covered in detail in Chapter 2.
Displays information fields for Name, Call, QTH, and Maidenhead Locator. This information is used by the menu functions 'Send CQ and 'Auto CQ'. This information is also used in fixedtext construction and for determining station distance, bearing and other details supplied within the Display QSO Information dialog as described earlier in this document.
Displays information fields to specify audio/PTT devices (i.e. /dev/audio, /dev/ttyS0) Any changes will require a restart of the application.
The Appearance submenu provides font and color dialogs for customizing the displayed font, the color of the RX and TX fonts and text windows, and the colors used within the waterfall. An option is available for a grayscale waterfall. Grayscale waterfall is particularly good for weak-signal operations. The default configuration for KPSK is to use the grayscale waterfall. To enable the color waterfall, simply select the radio button labeled Color Waterfall.
The scheme used to provide color within the waterfall assigns each pixel a value based on its representative signal intensity, from 0 to 99. The waterfall color labels assigned to pixels of intensity 'x' are: 'background' (0 > x < 1) , 'very low amplitude' (1 > x < 17) , 'low amplitude' (17 > x < 34), 'mid amplitude' (34 > x < 51), 'mid-high amplitude' (51 > x < 68), 'high amplitude' (68 > x < 97 ), and 'very high amplitude' (97 > x < 100). This scheme offers you the opportunity to customize the color scheme of your waterfall at any time of operation.
You can change the color assignment ranges by editing and recompiling waterfall.cpp. The lines of code that affect the color assignments are around lines 466 to 484. If you develop a better color division scheme, please let the development team know by sending a note to <kpsk-develop@lists.sourceforge.net>.
A dialog for entering the actual frequencies (in KHz) used for the various bands of operation. The result of setting an actual frequency for a given band in this dialog is a change in the displayed divisions on the waterfall lineal scale and the frequency display area of the status bar. An example of the configuration of this item, would be to enter 14070.15 in the 20m field. This would change the waterfall lineal scale from the default audio tone scale (0 Hz to 2800 Hz)to an RF scale. If the LSB checkbox is checked for any of the bands, the displayed lineal scale is changed to show LSB frequencies. This setting is linked with the Band dialog of KPSK's logbook area; when bands are changed in the logbook area, the waterfall lineal scale and frequency display are updated to match the entered Band/Frequency information for the band of operation.
A simple slide button to adjust the waterfall display. A good way to adjust the slider is to experiment; start at the maximum setting (slider at maximum travel to the right) and reduce the sensitivity by moving the slider to the left until weak signals are displayed to your satisfaction.
This configuration dialog enables you to either enable or disable the automatic operation the Call Check function. If enabled in Settings-->Auto Call Check, the state of the Call Check Active checkbox will revert to the enabled state after every instance of Auto CQ, Send CQ, or Save QSO. If enabled, Call Check will cause the first character string after any instance of 'de' to be transcribed into the CALL field of the current QSO logbook fields. The function can be momentarily disabled by manually unchecking the Call Check Active checkbox, presented near the top right corner of the main window. Call Check functions in both TX and RX modes, so it is important to uncheck the Call Check Active box after the desired callsign is first captured. If Call Check is not momentarily disabled, it will overwrite the originally captured callsign with your own callsign when you transmit your call to the distant station!
Automatic operation of the Call Check function can be disabled (leave the configuration dialog box unchecked). If disabled in Settings-->Auto Call Check, the state of the Call Check Active checkbox will revert to the disabled state after every instance of Auto CQ,Send CQ, or Save QSO. The function can be momentarily enabled by manually checking the Call Check Active checkbox presented near the top right corner of the main window.
Selecting this item will delete all text from Main RX window.
Selecting this item will delete all text from Channel 1 Auxiliary RX window.
Selecting this item will delete all text from Channel 2 Auxiliary RX window.
Selecting this item will delete all text from Channel 3 Auxiliary RX window.
The main RX text window is displayed in the upper portion of the main program window, below the logbook information fields. The TX text window displayed below the main RX text window and above the waterfall display. The vertical size of the TX, RX, and waterfall windows can be resized by clicking-and-dragging the upper or lower window frame divider and moving the divider up or down as desired. Text that is typed into the TX window will be sent during the next transmission cycle.
Auxiliary windows are displayed in separate windows. Closing an auxiliary window halts transcription of the corresponding received signal and removes the associated signal marker from the waterfall.
The TX window can be cleared with a left-mouse-click on the Clear TX button on the menu bar. Alt+T from the keyboard will also clear the window.
The RX windows can be cleared with a left-mouse-click on the Clear RX menu. This action will display menu choices for clearing either the main RX window or any of 3 Auxiliary windows that may be open (Channel 1, 2, 3).
The Status Bar is located along the bottom of the KPSK window. In addition to providing critical information about the program's status and state, it serves several command/control functions.
Data Carrier Detect (DCD) S-meter display. The yellow bar in this area indicates DCD level. The vertical red bar in this box indicates the DCD decoding threshold (similar to a squelch setting). A left-mouse-click in this area brings up a DCD sensitivity slider. Setting this sensitivity can minimize the amount of noise text displayed when no valid signal is detected. When set to it's minimum (all the way left on the DCD slider bar) DCD is set to off, which results in all noise decoded into text. Setting the slider to higher settings establishes the minimum signal DCD level required to decode a signal and display text. The DCD S-meter display is updated instantaneously once per second and does not represent an average value. This display can be helpful when determining signal quality.
When a valid signal is being decoded and when signal 'idle' is detected, an IMD will be displayed in this area. IMD is generally used as an indication of signal quality. A high IMD (< -10 db) indicates either a very strong signal (overloading the sound card) or very poorly adjusted (overdriven) transmitter. A low IMD (approaching -30db) can be a good indicator of a properly adjusted transmitter.
IMD can only accurately be measured on strong signals and during times of carrier (i.e. tune or no text transmitting). In normal text transmissions or low signals, other signal components or noise contribute to corrupt the measure.
Please help clean up the PSK31 signals on the air by providing signal quality reports to your contacts--praise the excellent signals, help the operators with bad signals improve their signal quality. Most stations don't know they are sending a poor signal.
This box indicates the application's current status. Receive means the application is in the receive mode. Transmit means the application is in the transmit mode. You can toggle between Receive and Transmit with a single left-mouse-click in this box. This feature is only shown in the main KPSK window; it is not present within the auxiliary windows.
This box indicates current tune status. You can toggle between on and off with a single left-mouse-click in this box. The receive/transmit status will toggle showing when the transmitter is keyed in tune mode. This feature is only shown in the main KPSK window; it is not present within the auxiliary windows.
This box indicates the PSK31 operation mode. You can toggle between BPSK and QPSK with a single left-mouse-click in this box. The most common operation is BPSK. Default is BPSK. This feature is only shown in the main KPSK window; it is not present within the auxiliary windows.
If ON at the end of each transmission a CW ID is sent using the callsign entered in the personals menu. Default mode is OFF. Toggle between ON/OFF with a single left-mouse-click. This feature is only shown in the main KPSK window; it is not present within the auxiliary windows.
Automatic Frequency Control. If on, markers will automatically track the decoded signal; this is helpful/critical for signals that drift. Default mode is On. Toggle between ON/OFF with a single left-mouse-click.
If on, sets TX to last RX frequency for the signal. Default mode is On. Toggle between ON/OFF with a single left-mouse-click.
Shows frequency of the received signal; if toggled from an auxiliary window, it switches the auxiliary signal and transcript to the main application window. Toggle with a single left-mouse-click.
Displays the current date and time of your system.
| 4.1. | ./configure is unable to run to completion, complains of missing "foo"; exits with errors |
Read the end of config.log to determine what was not found. Locate the file or library on your system to ensure that it is installed. Re-make your 'configure' file by issuing make -f admin/Makefile.common and re-run ./configure Read the help provided by the results of issuing ./configure --help If ./configure cannot find Qt or KDE3, you will need to specify the location when running ./configure. For example, the following is required on the author's machine (Mandrake): ./configure --enable-debug=full --with-qt-dir=/usr/lib/qt3 --prefix=/opt/kde3 | |
| 4.2. | make exits with errors |
The most common cause of errors during make is due to incorrect specification of libraries during execution of ./configure. Examine the error message to attempt to determine what is wrong. Run ./configure again with the appropriate options (see above). Before attempting make again, run make clean. | |
| 4.3. | make install exits with errors |
You must be root (or have permissions to write to kde/bin); login as root and try it again. | |
| 4.4. | Error Message: Unable to access audio device. |
Common sources of this error message are:
| |
| 4.5. | Error Message: Cannot Open PTT Device |
Common sources of this error message are: You do not have the computer interface connected. You do not have the correct access permission for /dev/ttySx (where x = 1,2,3... depending on which port you are using). To find out which group owns /dev/ttyS0, simply enter ls -al /dev/ttyS0. Serial port permissions are often alloted to the uucp group. If this is the case on your machine, simply add your username to the appropriate group. Another application is using /dev/ttySx. | |
| 4.6. | Error Message: 'inexact sampling rate: request for 8000 resulted in XXXXXX' |
KPSK operates at a sampling rate (conversion of analog sound input to digital values) of 8000 samples/sec. Not all sound cards or on-board chips can change their sampling rate. For example the VIA VT82C686 "Southbridge" chip with on-board sound has a fixed 48000 sampling rate. This chip and typical Red Hat native drivers will not support KPSK. Simple Sound Blaster cards are capable of changing their sampling rate. The ALSA sound drivers (http://www.alsa.org) compensates for the VT82C686 fixed sampling rates by software downsampling in the driver. This may be an effective solution for fixed rate hardware depending on processor speeds. The CPU must be able to keep up with all tasks and the realtime input of KPSK data. If you get this error code, give the ALSA drivers a try. With the relative low cost of add-on sound cards, another alternative is to disable the on-board sound (in BIOS) and replace the fixed rate card with a low cost Sound Blaster type card. | |
| 4.7. | Blank/Black Waterfall, Audio Signal Present |
Check and adjust waterfall sensitivity setting Check and adjust sound mixer settings using the KDE application KMix (or your favorite audio mixer application). You may be ?listening? on the wrong line or your mixer input levels may be too low; adjust mixer levels. | |
| 4.8. | Blank/Black Waterfall, Audio Signal Not Present |
Check and double-check physical connections between antenna/radio/interface/soundcard -- if you've gotten this far, it is likely that the program is working fine but a signal is not being properly fed to the computer. | |
| 4.9. | Error message: ?Unable to find dxcc database. Continue without it?? |
This error occurs when the file dxcc.db is deleted, overwritten, or moved from its default installation path of KDEDIR/share/apps/kpsk/dxcc.db . This file contains the information that is used to display distance, bearing, and other information shown by Logbook Display QSO Information. Previously, KPSK could not continue without this file. KPSK is now able to continue without this file with reduced functionality in the logbook. The warning is to alert you to the missing file so you can find it or replace it on your system. | |
| 4.10. | Blank logbook -- Where did my contact logs go??? |
This will occur if you delete, overwrite or move your ~/.kde directory. The QSO logfile itself is stored in ~/.kde/share/apps/kpsk/log.db . If something happens to the original file and KPSK cannot locate log.db in the path described previously, it will create a new, blank log.db file in the correct location. In its current format the QSO logfile is not human readable. It is highly recommended for users to backup this directory and the files contained on a regular basis, just to be safe. | |
| 4.11. | Configuration settings have returned to application defaults -- what happened??? |
The file ~/.kde/share/config/kpskrc stores all of the application's configuration settings. This file has either been moved, deleted, or damaged. A new file will be generated when KPSK is executed and you will need to re-establish your settings and preferences. The logbook and fixedtext contents are stored separately, as detailed previously in this section. | |
| 4.12. | Other Error Message, Not Listed |
Please report the error to <kspk-users@lists.sourceforge.net> after attempting to determine and solve the problem--this will enable you to get assistance and by doing so, it will help others who may have the same problem (now or in the future). Be sure to include information about your distribution, any error messages received and anything else that you feel is important. If you have the application gdb installed on your machine, you can obtain backtrace debugging information for program crashes by starting the program from within gdb. To start the program within gdb, issue the command gdb kpsk and then run (you should do this from within the directory that the KPSK executable is located). After the program crashes (exits abnormally), issue the command bt. Copy and paste the backtrace information into an email and send it to <kpsk-users@lists.sourceforge.net>. |
KPSK
Program copyright 2000, 2001, 2002 Luc Langehegermann, LX2GT <luc@1409.org>
Code Contributors:
| Luc Langehegermann, LX2GT <luc@1409.org> |
| David Kjellquist, WB5NHL <david@kjellquist.com> |
| Ernest Stracener, KG9NI <kg9ni@arrl.net> |
| Klaus, DL2WP |
Luc is the original author and current project manager for KPSK. Luc developed and released the original KPSK v.0.7 code in September 2000 for KDE 2.2, adding to it and improving the code through three subsequent KDE 2 releases, v.0.9.0, v.0.9.2 and v.0.9.3. His efforts established an excellent foundation for PSK31 operations and additional development in Linux.
In 2001, David joined Luc in the KPSK development project and spearheaded an effort to port the code to KDE 3. David has tirelessly added mountains of code and consideration to the project. As a result KPSK has rapidly evolved, gaining a number of excellent new features and functions.
John joined the group in September of 2002. His first contact with the KPSK team was accompanied by a perfectly packaged RPM for Mandrake 8.2. A source of many good ideas, John is working towards his amateur radio license in his ?spare? time.
I (Ernest) joined the project in June 2002 and took on the task of doc writer, since my code skills are quite minimal. Beyond documentation, my only code contributions (so far) have been limited to the task of providing user-selectable colors within the waterfall and the user-configurable call check function (a simple addition to Luc's original call check function). Since joining the project, I have learned quite a bit about the development process, how to write documentation in DocBook XML with Emacs (psgml mode), and a little bit of C++ and Qt3 code as well--it has been a fun learning experience!
Documentation copyright 2002 Ernest Stracener, KG9NI <kg9ni@arrl.net>
Documentation Contributors:
| Ernest Stracener, KG9NI <kg9ni@arrl.net> |
| Luc Langehegermann, LX2GT <luc@1409.org> |
| David Kjellquist, WB5NHL <david@kjellquist.com> |
| John R. Marshall <hotrodder@users.sf.net> |
Packagers:
| Sebastian Muszynski, DO2KSM, for debian packages for KPSK <0.9.4 |
| David Kjellquist, WB5NHL and Ernest Stracener, KG9NI for Red Hat 7.3, 8.0 packages for KPSK v.1.0 |
| John R. Marshall and Ernest Stracener for Mandrake 8.2 and 9.0 packages, respectively, for KPSK v.1.0 |
This documentation is licensed under the terms of the GNU Free Documentation License.
This program is licensed under the terms of the GNU General Public License.
Table of Contents
KPSK source and binary packages are available at the Sourceforge KPSK Project page. The packages may also be available elsewhere, but the Sourceforge KPSK Project page is the "official" repository of code.
Serial port available for keying transmitter.
Sound card with capability for changing sampling rate. See trouble shooting, inexact sampling rate. Also see Sound-How-To. Soundblaster soundcards are recommended.
KDE v.3.0.1 or later -- this version will not work with KDE2. KPSK v.0.9.3 and earlier versions were designed for KDE2.x
Qt v.3.0.3 or later
BerkeleyDB v.3.1 or later (http://www.sleepycat.com). This application is packaged with most distributions, but may not be installed on your machine. The purpose of this application is to provide QSO logging capabilities.
Compilation of KPSK will require that your machine have a number of development packages installed. Each linux distribution usually has a relatively simple way of selecting and installing these packages. With Debian, use tasksel at the root prompt and install the development environment packages; use aptitude or dselect for others. With Mandrake, use Software Manager (rpmdrake) to select the Development RPMS. With Redhat, kpackage to select the RPMS.
In particular, you will need to ensure that you have: qt and qt-devel for Qt v.3.0.3 or later, kdelibs and kdelibs-devel for KDE 3.0.1 or later, zlib-devel, libjpeg, libjpeg-devel,libpng2 and libpng2-devel. NOTE: Before installing libpng2 packages, PLEASE check your system to determine if libpng2 or libpng3 is present; problems have been reported (with other applications) when libpng2 and libpng3 are present on the same machine. If you have or install these, your distro package handler will probably pick-up any other required dependencies.
Depending on how KDE 3 was installed on your machine, you may also require the libfam and libMesaGL packages.
When you run ./configure you should specify the path to your root KDE3 and Qt3 directories. At the command prompt, type ./configure --prefix=<path to kde3> --with-qt-dir=<path to Qt3.x> --enable-debug=full. The ./configure script will examine your system and attempt to locate needed libraries and files. If it returns an error, it will exit; if the error message on the screen is not descriptive enough, take a look at the end of the config.log file. If the prerequisite software mentioned in the Software Requirements section of this document has been installed, the script should run to completion.
If the ./configure routine fails to find db4/db.h or db3/db.h on your machine, you may need to modify the file logcore.h to point to the correct file on your machine and recompile the file. When Berkeley DB is installed from packages provided by Sleepycat Software, the common installation location is often /usr/local/BerkeleyDB.4.0. The db.h file is located within the include directory of BerekelyDB. Locate the Berkeley DB file db4/db.h (i.e. run slocate db.h); copy the correct path to into the logcore.h file. The lines in logcore.h to modify look like this:
| #ifdef HAVE_LIBDB_4_0 |
| #include <db4/db.h> |
| #else |
| #include <db3/db.h> |
| #endif |
As an example, that section in the author's logcore.h file has been altered to look like this:
| #include </usr/local/BerkeleyDB.4.0/include/db.h> |
As in the example above, you will likely need to remove the other lines (starting with 'ifdef' and ending with 'endif'), keeping only the line that has your correct BerkeleyDB path. Please note that you must recompile the file to run the program.
If configure still will not run to completion, consult the Troubleshooting section of this document.
Make and install the application with make; make install
Ensure that your regular user(s) have read/write permissions for your serial (ttySx) port that interfaces with your radio. One way to permit users to access the serial port is to issue the command: chmod ug+rw /dev/ttyS0 (*modify this to match your machine, usually COM1->/dev/ttyS0, COM2->/dev/ttyS1*) and then ensuring that your users are included in the group that owns serial port access. To find out which group owns /dev/ttySx, simply enter ls -al /dev/ttyS0. Serial port permissions are often alloted to the uucp group. If this is the case on your machine, simply add your username to the appropriate group.
Users will also need read access on /dev/audio, /dev/dsp, or your machine's sound device. For soundcard and sound troubleshooting, please refer to the Sound-How-To.
Exit the 'root' identity and login as a regular user (with correct permissions for tty and audio).
Start KDE3 (if you are not currently running KDE3)
The executable file is in the KPSK directory and will also be installed to the kde3/bin during the make install portion of installation. To run the program from the command line, be sure that the path to your kde3/bin is in your PATH environment variable. To run the program, issue the command kpsk. You may also start the program by changing to the directory where the KPSK executable is located and issuing the command ./kpsk.
If you have performed the installation correctly, the program will start up and you will see the waterfall begin to scroll down the screen. If the startup crashed or otherwise bombed out, see the Troubleshooting section of this document.
Table of Contents
If you need additional assistance with installation or operation of KPSK, send an email to <kpsk-users@lists.sourceforge.net> . If you are trying to troubleshoot an installation, be sure to include information about your distribution, any error messages received and anything else that you feel is important.
If you have the application gdb installed on your machine, you can obtain backtrace debugging information for program crashes by starting the program from within gdb. To start the program within gdb, issue the command gdb kpsk and then run (you should do this from within the directory that the KPSK executable is located). After the program crashes (exits abnormally), issue the command bt. Copy and paste the backtrace information into an email and send it to <kpsk-users@lists.sourceforge.net>.
These references were valid URLs at the time of writing and each contains links to additional resources:
Official PSK31 Site: http://aintel.bi.ehu.es/psk31.html
Mirrored at: http://www.kender.es/~edu/psk31.html
W2MU's PSK31 Page: http://www.qsl.net/wm2u/psk31.html
Frequencies for PSK31 operations: http://www.kender.es/~edu/frecuencies.html
If you think other resources should be included in this list, please email <kpsk-users@lists.sourceforge.net> with details.
Just like any viable population, we need new genes to continually enter the pool to continue the evolution of KPSK. If you have something to offer to the development of KPSK, please join us! Send an email to <kpsk-develop@lists.sourceforge.net>.
This section is intended to provide a few tips for resolving specific problems that influence KPSK's operation, but are not directly attributable to KPSK. If you have something that should be included here, please let us know.
Setiathome and KPSK: Sluggish performance observed in KPSK when running concurrently with setiathome. The apparent interference between the two applications can be resolved by running setiathome with a different scheduling priority. Run setiathome with a ?nice? value of -19: nice -19 setiathome. Reported by WB5NHL