xritty User Manual

  1. Introduction
  2. Features
  3. Compilation
  4. Command line options
  5. Operation
  6. Bugs and annoyances
  7. Version history
  8. Copying
W

1. Introduction
xritty is an X/GTK+-3 Linux application for Amateur Radio communications in the RTTY digital mode. xritty detects the Mark/Space signals that make an RTTY-encoded character by reading audio samples from the DSP in the computer's sound card, connected to the output of a receiver. The audio signal is processed by software Goertzel detectors, which detect the level of the Mark and Space frequencies and forward these to a Sync Train detector and RTTY character decoder. The decoded ASCII characters are printed to the Receive window of xritty after some processing to deal with non-printable characters etc. An DFT-based "Waterfall" display is available to help tune in RTTY signals and a "Scope" display is available to show the input Mark/Space signals.

Transmission of RTTY-encoded characters is realized by writing pre-computed audio samples to the sound card's DSP and feeding the resultant audio signal to the transmitter's input. The transmitter must be in the SSB mode during transmission but for reception a narrow-bandwidth mode like CW-Narrow is preferable since RTTY theoretically only occupies about 300 Hz of bandwidth at 170 Hz shift. xritty has built-in CAT control capability for the Yaesu FT-847 or FT857 and Elecraft K2 or K3 Transceiver which, when enabled, can change the operating mode automatically. xritty now also has serial port RTS or DTR control to allow transceiver PTT-On/PTT-Off control.

Usage: xritty [-hv]

-h: Print usage information and exit.

-v: Print version number and exit.

2. Features

Sound-card set-up
xritty automatically prepares the sound card and sets the mixer Capture level to the value specified in the ~/xritty/xrittyrc configuration file. For proper operation, the level of the input signal must be adjusted from the receiver, if volume control is available, or by changing the value of the Capture level in the ~/xritty/xrittyrc configuration file, if audio is taken from a fixed-volume source, such as the "data" i/o port. The output audio level is also set to the Playback level specified in ~/xritty/xrittyrc, although again this will need to be set-up properly for low-distortion transmission. Please see the Operation section for details on how to set-up the sound card.

Software Mark/Space signal detector
xritty was designed from the beginning to be simple and efficient, decoding RTTY signals using mostly integer arithmetic and simple processing methods. It uses the computer's sound card to read the '1' and '0' elements that make the RTTY-coded characters by implementing a software detector of the received audio signal's amplitude. These Goertzel detectors are centered on the Mark and Space frequencies, which are either side of the BFO tone frequency specified in the xrittyrc configuration file. To provide for a finer search for the Start bit position, four samples of signal levels are taken for each bit of the RTTY code. A measure of compensation for the effects of Selective Fading is provided, by compensating partially for the imbalance of amplitudes of the Mark and Space signals.

Mark-Space Signal Scope
xritty has a simple oscilloscope type display of the Mark and Space signals as produced by the Goertzel detectors. This can be used to monitor the RTTY signal received by the Transceiver and to maximize by tuning the receiver manually. An idea of the signal quality and magnitude can also be realized.

"Waterfall" display with CAT
xritty has a "Waterfall" (audio spectrum) display derived from an DFT of the receiver's audio output. The Waterfall display has two vertical white lines either side of its center, which indicate the position of the Mark and Space frequencies. The position of these lines depends on the specified BFO center tone frequency and the AFSK frequency shift: the two lines are positioned at one half the AFSK shift either side of the center of the Waterfall, which represents the BFO center tone frequency. An RTTY signal is tuned correctly when the two traces, produced by the DFT function, are positioned under the two white guide lines. If a Yaesu FT-847 or FT-857, or an Elecraft K2 or K3 transceiver is being used, xritty can automatically tune the Rx if the left button is clicked near the left trace, or the right button near the right trace. During Transmit or Receive, xritty Can also set up the right mode of operation for the transceiver. Also, xritty now has serial port RTS or DTR control to allow transceiver PTT-On/PTT-Off control.

Macros in Transmit mode
xritty allows 9 prepared Macros to be sent by clicking on one of the nine buttons in the 'Prepared Macros' frame for easy transmission of repeated messages like call-sign exchanges, station info, BTU, sign-off etc. Theses Macros are stored in the 'xrittyrc' run time configuration file (in ~/xritty/) and are invoked by clicking on the relevant Macro button. Short labels for these Macros are also stored in xrittyrc and are displayed in the button labels. For even more operating convenience xritty allows the use of 'tags' embedded in the Macros for automatic insertion of certain basic strings in the transmitted message: call-sign, RST, name, QTH and QTH locator for both the operator and the remote station, the current UTC date and time and the operating frequency. The program's version string is also available as a tag so that it can be included in a macro, e.g. there are 13 tags altogether in this version. More on this in the Operation section.

QSO Recording and Logging
xritty can save details of activity during its operation in three separate files on the disk:
1. In ~/xritty/record.txt all characters printed in the Transmit or Receive window including Macros are recorded 'raw' e.g. in real time and unedited. This makes it possible to check everything transmitted or received during operation if something goes wrong.
2. In ~/xritty/log.txt all details of a QSO entered in the QSO Record form (under the Receive window) are saved in text form with the addition of date and time to form a standard station log.
3. In ~/xritty/log.adif an ADIF-formatted version of the QSO Record is saved for direct uploading to eQSL.cc or other sites that can accept ADIF formatted logs.

Recognized characters The alphabetic characters, punctuation marks and numerics that xritty can currently recognize are the ones specified in the ITA2 character code. These can be seen in the ita2.gif file in the doc/ folder.

3. Compilation
Before compiling xritty, it is possible to customize some entries in the header file codec.h. Different characters can be entered in the ITA2 table in the codec.h header file before compilation, following the instructions in that file. Non-printable characters (LTRS/FIGS shift, Carriage Return/Line Feed etc) must not be changed.

Please note that I use Void Linux which is a "bleeding edge" type distribution, so there may be compilation and/or run time difficulties if you are using a relatively old distro. This is mostly true of the basic dependencies like GTK+-3, and there can also be sound card incompatibility problems at run time.

To compile the package, it may be preferable to first run the included "autogen.sh" script in the package's top directory, to produce a fresh build environment. Then the "configure" script can be run with optional parameters to override the default settings and compiler flags, e.g: ./configure --prefix=/usr CFLAGS="-g -O2" will override the default /usr/local installation prefix and the "-Wall -O2" compiler flags.

Running "make" in the package's top directory should produce the executable binary in src/. Running "make install" will install the binary into /usr/local/bin by default or under the specified prefix. It will also install the xritty working directory and default configuration file into the user's home directory. This will have to be edited by the user as required. There is also this hypertext documentation file which you can copy to a location of your choice.

xritty requires a directory named xritty in the user's Home directory, where the xritty/xrittyrc run time configuration file is placed after suitable editing. Additionally, xritty places three files in this directory, created during operation:
1. record.txt is a complete character-by-character record of everything that has been received or sent during a session.
2. log.adif is an 'ADIF' formatted record of the main QSO data e.g. call-sign, signal report, mode, frequency and date-time.
3. log.txt is a more detailed record of conducted QSO's in text format.

4. Command line options
xritty can be invoked with the following options:

-h: Print this usage information and exit.

-v: Print version number and exit.

5. Operation

xritty User Interface
xritty is an X/GTK+-3 application for Linux. The main application window has the following widgets:

1. The Transmit window: Any text typed during transmission appears in this window. When it is filled, it scrolls automatically so that the last line is always visible. It can be cleared by right-clicking in the window and activating the 'Clear Window' item in the pop-up menu. Clicking the middle button toggles xritty between the Transmit and Receive modes. Next to the Transmit button there is a spinbutton which can be used to change the Playback volume, thereby adjusting the Transmitter's power output.

2. The Receive window: Displays characters decoded from an RTTY signal. When it is filled, it scrolls automatically so that the last line is always visible. It can be cleared by right-clicking in the window and activating the 'Clear Window' item in the pop-up menu. Clicking the middle button toggles xritty between the Receive mode and Standby. If xritty is in Transmit mode it is changed over to Receive, but if a Macro is being transmitted, then it is interrupted and xritty remains in Transmit mode until another middle-click on either window. Next to the Receive button there is a spinbutton which can be used to change the Capture volume, thereby adjusting the audio input level to the DSP. To the right of this is the Squelch slider, which can be used to set a Squelch level for the incoming signal level, to stop decoding of stray characters from incoming background noise. Again, to the right of this is a button that indicates the state of the LTRS/FIGS shift flag and can also be used to toggle this state.

3. Waterfall and Tuning Aid: The Waterfall widget is an aid to tuning the receiver accurately to an incoming RTTY signal. The Waterfall display has two vertical white lines either side of its center, which indicate the position of the Mark and Space frequencies. The position of these lines depends on the specified BFO center tone frequency and the AFSK frequency shift: the two lines are positioned at one half the AFSK shift either side of the center of the Waterfall, which represents the BFO center tone frequency. An RTTY signal is tuned correctly when the two traces, produced by the DFT function, are positioned under the two white guide lines. If a Yaesu FT-847 or FT-857, or an Elecraft K2 or K3 transceiver is being used, xritty can automatically tune the Rx if the left button is clicked near the left trace, or the right button near the right trace. During Transmit or Receive, xritty can also set up the right mode of operation for the transceiver. Also, xritty now has serial port RTS or DTR control to allow transceiver PTT-On/PTT-Off control.

Below the Waterfall display there is a Sync Train (Start bit) Position display, in the form of a circle which represents the circular buffer used to save average signal values. The Sync detection function searches the circular buffer (which stores four signal samples per bit for three RTTY characters) and the detected position of the Start bit is marked by a radial line from the center. Since three RTTY characters are saved in the buffer, the indicator line rotates clockwise to three points on the circle, at 120 degrees spacing. If sync detection is done correctly, the indicator line will either move to stable positions or creep around very slowly (indicating a difference in the clocks between the two stations).

4. The QSO Record frame: In this frame there are seven entry fields in which basic QSO data are entered for saving in the text-format station log file and the ADIF-format log file in the ~/xritty/ directory. The minimum requirement for a valid record is the DX station's call-sign, signal report and operating frequency. The mode and date are entered automatically by xritty each time a new record is opened. If the transceiver in use is an FT847 and CAT is enabled, xritty will read the Transceiver status and enter the signal report and operating frequency automatically each time a new record is opened.

The buttons below the QSO Record fields have the following functions:
Open New Record: This button clears all but the 'Band' field and enters the mode and the date and time to the QSO record buffer in memory. If there is a previous valid record then this is saved to the log files in ~/xritty/ before a new record is opened. Key F10 also opens a new Record.
Save Record: Opens a pop-up save dialog box. If the QSO Record is valid (call-sign, RST-out and Band have been entered) then a confirmation request for saving is shown, otherwise if not, a warning is given to that effect. Key F11 also has the same function.
Clear All Fields: This button clears all entry fields. NOTE: This will clear the QSO Record buffer in memory, resulting in lost data if the record has not been saved first!.
Clear Windows: Clears the Transmit and Receive windows of all text.

5. The Macro buttons frame: In this frame there are nine buttons that initiate the transmission of prepared macros, e.g. standard messages saved in the run time config file xritty (in the ~/xritty/ directory). Clicking on a button puts xritty in Transmit mode and starts transmission of the macro, clicking again on any of these buttons interrupts the macro but leaves xritty in transmit mode.

6. The pop-up menu: This opens on a right-click on the Receive or Transmit window. It has the following items:
Baud Rate: Select the RTTY baud rate: 45.5, 50, 75, 100 bd.
AFSK Shift: Select the RTTY AFSK shift: 170, 200, 450, 850 Hz.
Stop Bits: Select the stop bit size: 1, 1.5 or 2 bits.
Enable Pseudo Diversity: Enable/Disable compensation for selective fading of the mark or space frequency. This to some extend works like the space diversity system used by some stations.
Unshift on Space: Enable/Disable automatic unshifting from FIGS to LTRS shift, when a Space character is received.
Enable CAT: Select the transceiver type for CAT, or serial port RTS/DTR control of the transceiver.
Record QSO's: Keep a record of all transmitted and received characters in the record.txt file in ~/xritty.
Clear Window: Clears the window of all characters.
Identify in CW: Sends the station call-sign in CW/Morse code.
Quit: Quits xritty.

Configuration and set-up
After compilation and installation, the ~/xritty/xrittyrc run time configuration file MUST be edited for proper operation! To do this, load ~/xritty/xrittyrc into your favorite editor and make sure that you review ALL the configuration fields in the file and that you properly edit all the ones that must be edited. There are four sections, Sound card, xritty Run time, Operator/QTH info and Macros fields. Please review ALL and EDIT as needed!! There are more detailed instructions in the file itself so please follow them for a proper set-up. In particular, station details like Call-sign, operator's name and QTH etc must be edited for Macros to be usable.

Next, the sound card must be set up. For this to be done, the receiver's audio output should be connected to the computer's sound card (usually to the 'line' input) and the receiver tuned to some stable carrier signal with no am modulation. Modern HF transceivers have general coverage receivers with DSP audio filters down to 25 or 50 Hz bandwidth and this makes it possible to use a local broadcast station as a signal source.

With the narrowest bandwidth selected, start xritty and fine tune the receiver for the specified BFO tone frequency + 1/2 the AFSK shift. This can be done by placing the Waterfall trace under the right guide line. For the correct level of audio input, the signal level line in the Scope display should be no higher than about 80% the height of the scope display. If the audio level is to high, then traces of RTTY signals (well tuned) will appear clipped at the top. If this happens then reduce the receiver's volume level or if the audio output is taken from a fixed-level outlet (like the 'data' port), set the correct input level by editing the Capture level value in the ~/xritty/xrittyrc file. This can be done by using the spinbutton next to the Receive button to adjust Capture level as above and then setting this value as the Capture level in xrittyrc.

For RTTY transmission, the DSP output level needs to be set up for minimum distortion in the transmitter. The Playback volume setting in ~/xritty/xrittyrc can be edited to set the right audio output level by using the spinbutton next to the Transmit button. Adjust the Playback volume till the Transmitter's output is about 50% or less. The spinbutton setting can then be used in xrittyrc as the Playback volume level. If the setting needs to be below approximately 10% then a simple resistive attenuator will be needed ahead of the transmitter's audio input. In each case the best way to set the sound card output level would be to have the transmitter's settings (Mic gain, ALC or other appropriate control) at an average or 'normal' level and adjust the sound-card audio level so that the RF output power is about 50% or less of the rated maximum power. This will ensure that distortion is kept to a minimum and the dissipation of the final stage within its ratings.

Receiving RTTY signals

RTTY is a narrow-band mode and it requires accurate tuning, to within less than +-20-40 Hz for reliable operation. For manual tuning this requires the receiver to have a tuning step of 10 Hz resolution at least. If the transceiver in use is one of the supported types by CAT, then the Waterfall display can be used to tune in a signal by clicking near its trace, with the left button on the left trace or the right button on the right trace. xritty will adjust the main dial frequency so that that the signal is tuned in closely, but if the tuning resolution under CAT is 10 Hz then an error of at least +-5 Hz is possible.

Conducting a QSO
As usual to make a QSO with another station using RTTY you may call CQ or reply to a CQ. Calling CQ would normally be done using a prepared Macro by clicking on the relevant Macro button and during the course of a QSO, other Macros can be started as needed to send some of the standard messages that are usually exchanged. When the Macro is finished, xritty will revert to Receive mode unless a tilde '~' is the last character in the Macro, in which case it remains in Transmit so that a manually typed message can follow the Macro. Reversion to Receive would then be done by middle-clicking on the Receive or Transmit window. Please note that Macro transmission can be interrupted by middle-clicking on the Receive or Transmit window or left-clicking on any of the Macro buttons.

When a station replies to a CQ it would normally be netted closely and characters transmitted will appear in the Receive window. If there is a significant frequency offset, it will cause errors in decoding but correcting this from the main dial may cause the remote station to miss reception. Using the RIT control may be advisable as this will help to avoid 'crawling' along the band as stations tune in to each other during the QSO.

Once two-way contact is established, at least the station's call-sign, RST, and the QSO frequency must be entered in the QSO Record's fields before it can be saved to ~/xritty/log.adif and ~/xritty/log.txt. BUT PLEASE NOTE: Always remember to 'Open New Record' before entering any data otherwise the mode and date/time will not be entered to the record buffer by xritty.

Any information entered in the fields is available to any relevant 'tag' in the Macros but please note that if any fields are not filled, xritty enters blanks in place of tags! Please note that during transmission no entries should be made to the QSO Record fields since these will reflect in whatever tags are embedded in Macros.

To reply to a CQ, tune in the station accurately and type its call-sign, signal report and frequency in the QSO Record fields. Then prepared Macros can be used to reply to the call and conduct a QSO. Have a look in ~/xritty/xrittyrc for some typical prepared Macros. NOTE: You will need to edit at least some of these!!

It is now also possible to type in text into the Transmit window while xritty is in Receive mode. This, in addition to the prepared macros, can help save some time in replying to the station in contact with.

6. Bugs and annoyances
I have fixed whatever bugs I came across testing xritty, but there may be some hiding, waiting for the right conditions to appear.

7. Version history

Version 0.1 First beta release of the basic xritty application.

Version 0.2 Fixed the omission of initializing the Viterbi decoder when switching to QPSK.

Version 0.3 Modified the QSO record so that the RST-out is before the RST-in field. Also changed the format of the 'log.txt' file that is used for logging QSO's to make it more printable.

Version 0.4 Added +- 5.0 Hz fine tuning to the receive audio frequency, e.g. it can now be tuned from 495 to 505 Hz to help with rigs that only have 10 Hz tuning steps.

Version 0.5 Fixed a bug that caused xritty to not send the time of a QSO in the final closing transmission. Also fixed a bug that on a particular combination of user actions could cause xritty to crash by trying to write to the sound card DSP while the DSP write handle was closed.

Version 0.6 I made some changes to the DFT code used to produce the Waterfall display, e.g. to decimate the sampling rate by simple "box" averaging instead of skipping samples.

Version 0.7: I updated the GUI code to the latest GTK+-3.22. This made it necessary to make minor changes to the User Interface but functionality remains the same. An advantage of this version is that the GUI specification is in a Glade-3 XML file in the ~/xritty/ folder (xritty.glade), and this can be edited in Glade-3 if some cosmetic changes are desired. I migrated the internationalization system from "intltoolize" to GNU GetText, as the former is now considered obsolete. Also replaced the autogen.sh script with a newer version.

Version 0.7.1: I edited Makefile.am so that make install will now place relevant application files (documentation, pixmaps, desktop file, glade UI file etc) into the right places.

Version 0.8: I replaced the integer DFT functions with an open-source integer FFT function I found on the internet. This I had to modify to fit the needs of this application and this change resulted in a worthwhile reduction of processor workload.

Version 0.9: I have separated the pseudo-colorization code for the waterfall into a separate function and edited it to improve the colorization algorithm.

Version 0.9.1: Changed the installation commands in Makefile.am so that all the relevant files (desktop file, application pixmap, configuration file, executable binary etc) are installed under any location specified to the configure script by the --prefix= option. Also modified the program so that on first start up after installation, the application will create its working directory by copying files from the relevant directories under the installation prefix.

8. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.