forked from ec429/3psk
-
Notifications
You must be signed in to change notification settings - Fork 0
/
readme.htm
153 lines (153 loc) · 10.3 KB
/
readme.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>3psk: README</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8;" />
</head>
<body>
<div id="title">
<h1>3psk: readme</h1>
<h5>3PSK is a datamode for amateur radio, based on PSK</h5>
<p>This is the user manual for the 3psk software. For details of the 3PSK datamode, see the <a href="spec_3psk.htm">spec</a>.</p>
</div><!--#title-->
<div id="contents">
<h2>Contents</h2>
<ul>
<li><a href="#foreword">Foreword</a></li>
<li><a href="#controls">Controls</a></li>
<li><a href="#hotkeys">Hotkeys</a></li>
<li><a href="#config">Configuration</a></li>
<li><a href="#depends">Dependencies</a></li>
</ul>
</div><!--#contents-->
<div id="foreword">
<h2>Foreword</h2>
<p><strong><em><acronym title="3-pole Phase Shift Keying">3PSK</acronym></em></strong> is a conversational datamode for ham radio usage. It is similar to the well-known mode <em><acronym title="Phase Shift Keying">PSK</acronym></em> (created by Peter Martinez G3PLX), but has the advantage that the baud rate does not need to be agreed on in advance, and can even be changed during an 'over'. The corresponding disadvantage is a drop in effective <acronym title="Signal-to-Noise Ratio">SNR</acronym> of about 1.5<acronym title="decibels">dB</acronym>.</p>
<p>The <tt>3psk</tt> software package implements this datamode, and has a (somewhat) user-friendly interface.</p>
</div><!--#foreword-->
<div id="controls">
<h2>Controls</h2>
<p><tt>3psk</tt> is controlled chiefly through a GUI, which looks like this:</p>
<img src="screenshot.png" />
<p>The two graphics to the left indicate the operation of the decoder. On the left is the <em>constellation diagram</em>, which should be familiar to most datamode users. The points plotted on it represent the incoming signal (magnitude and phase), and form into a characteristic shape when a valid signal is received. In the case of 3PSK, the characteristic shape is an equilateral triangle (sometimes with curved edges, if heavy filtering is present).</p>
<p>The constellation diagram also shows something else, which is perhaps less familiar; each time a transition is accepted, a cyan line is drawn to mark it. This is useful because a 3PSK decoder recovers each clock tick individually, and different failure modes have different effects on the recovery. If no cyan lines at all are appearing, probably RXS is too high; if they're appearing in all directions, probably RXS is too low. When correct decoding is taking place, the cyan lines should run to the vertices of the triangle, as can be seen in the above screenshot. <!--XXX-->Actually this has changed somewhat, since 3psk now computes all phases relative to the last received symbol. The result is a dart shape.</p>
<p>To the right of the constellation diagram is the <em>frequency offset graph</em>. This is an aid to tuning in signals; the average y co-ordinate of the marks indicates the amount by which the signal is detuned. Again, the screenshot shows normal operation; in this case, the graph stays close to the x-axis. It will be below this axis if RXF is too low, and above it if RXF is too high.</p>
<p>Continuing to the right, we encounter the <em>codec controls</em>. The top row of buttons are toggles. <tt>TX</tt> controls whether to Transmit or Receive. <tt>MONI</tt> enables the monitor; that is, when transmitting, 3psk will decode its own outgoing audio. <tt>AFC</tt> enables Automatic Frequency Control, which attempts to tune signals in. <tt>SPL</tt> lights up whenever the transmit and receive frequencies are different; clicking it sets the receive frequency equal to the transmit frequency.</p>
<p>Below these toggle buttons is the <em>bandwidth selector</em>. The four buttons each select a filter bandwidth (in Hz). You need a wider bandwidth to decode signals at higher baud rates; the table to the lower right gives an indication of what speeds each bandwidth covers.</p>
<p>Below this are the numeric controls. Note that you can move them in larger increments by right-clicking the +/- buttons, or change them quickly by scrolling the mousewheel while hovering over them. <tt><strong>TXB</strong></tt> is Transmit Baud rate. <tt><strong>TXF</strong></tt> is Transmit Frequency (in Hz). <tt><strong>RXF</strong></tt> is Receive Frequency. <tt><strong>RXS</strong></tt> is Receive Sensitivity, the magic fudge factor you tweak to make the decoder work. <tt><strong>AMP</strong></tt> is amplification, or gain. <tt><strong>RXB</strong></tt> is the Receive Baud rate; that is, the number of transitions per second the decoder is accepting. This should be stable when receiving a valid signal.</p>
<p>At the rightmost edge is the <em>spectrogram</em>. The TXF (red) and RXF (green) are marked, as are 400Hz intervals (grey). Left-clicking sets both TXF and RXF; right-clicking sets RXF only.</p>
<p>The bottom of the screen consists of the output and input text areas and the macros. Decoded text appears in white and scrolls upwards (5 lines of text are displayed). Input text appears in red, then turns green after it has been transmitted. Clicking on a macro line selects it for editing; clicking it again unselects it.</p>
<p><!--XXX-->Missing from this screenshot (it has been added since) is the <em>eye diagram</em>, which plots phase against time. When a signal is decoding correctly, it should look like a series of curly braces, {{{{{. Interpreting this diagram (which is something of an art) can help in adjusting RXS.</p>
</div><!--#controls-->
<div id="hotkeys">
<h2>Hotkeys</h2>
<p>The following hotkeys control <tt>3psk</tt>:</p>
<dl>
<dt>F1-F6</dt>
<dd>Sends macro 1-6.</dd>
<dt>F7</dt>
<dd>Switches to Transmit mode.</dd>
<dt>F8</dt>
<dd>Switches to Receive mode.</dd>
<dt>F9</dt>
<dd>Disables <tt>SPL</tt>it frequencies (sets <tt>RXF</tt> to <tt>TXF</tt>).</dd>
<dt>Esc</dt>
<dd>Switches to Receive mode and discards buffered input.</dd>
<dt>Keypad Enter</dt>
<dd>Inserts a marker into the input stream; when this marker is reached, <tt>3psk</tt> switches to Receive mode.<br />
This can also be done with Ctrl-M.</dd>
</dl>
</div><!--#hotkeys-->
<div id="config">
<h2>Configuration</h2>
<p><tt>3psk</tt> can be configured through the <em>conffile</em> or through command-line options.</p>
<h3><em>Conffile</em></h3>
<p>The conffile is located at <tt>~/.3psk</tt> on Linux, or <tt>3psk.conf</tt> on Windows. It consists of <tt>boolean</tt> items, <tt>name:value</tt> pairs, and comments (lines beginning with '<strong>#</strong>'). A different conffile can be loaded instead by specifying the <tt>--conf=<em>file</em></tt> option on the command-line.</p>
<p>A sample conffile is provided as <tt>sample.conf</tt>.</p>
<p>The <tt>boolean</tt> items are:</p>
<dl>
<dd>MONI</dd>
<dt>Enables the monitor</dt>
<dd>AFC</dd>
<dt>Enables Automatic Frequency Control</dt>
</dl>
<p>Prefixing any <tt>boolean</tt> with an exclamation mark '<strong>!</strong>' disables it.</p>
<p>The <tt>name</tt>s are:</p>
<dl>
<dd>F1 to F6</dd>
<dt>Default text for the macros. The escapes <tt>\n</tt>, <tt>\t</tt> and <tt>\r</tt> are expanded to newline, tab, and the 'stop transmitting' marker. The macros are truncated to 80 characters.</dt>
<dd>TXF</dd>
<dt>Transmit frequency, in Hz.</dt>
<dd>RXF</dd>
<dt>Receive frequency, in Hz. If not set, defaults to TXF.</dt>
<dd>TXB</dd>
<dt>Transmit Baud rate.</dt>
<dd>RXS</dd>
<dt>Receiver Sensitivity parameter.</dt>
<dd>AMP</dd>
<dt>Receive gain.</dt>
<dd>IF</dd>
<dt>Approximate <acronym title="Intermediate Frequency">IF</acronym>, in Hz.</dt>
<dd>SR</dd>
<dt>Sample rate, in Hz. Supported values depend on your sound card.</dt>
<dd>BW</dd>
<dt>Receive filter bandwidth, Hz. Must be one of 10, 50, 150, 750.</dt>
</dl>
<p>There are also configuration options for the AudIO and PTT subsystems:</p>
<dl>
<dd>Au.SDLBUF:int</dd>
<dd>Au.TXBUF:int</dd>
<dd>Au.RXBUF:int</dd>
<dt>Length in samples of the SDL RX buffer, app TX buffer, and app RX buffer. Leave these alone unless you know what you're doing.</dt>
<dd>!Ptt</dd>
<dt>Disable PTT operation.</dt>
<dd>Ptt.DEV:string</dd>
<dt>Set path of PTT device (eg. /dev/ttyS0).</dt>
<dd>Ptt.[!]INV</dd>
<dt>Invert PTT signal.</dt>
<dd>Ptt.LINE:enum</dd>
<dt>Select which line to use for PTT. enum can be RTS, DTR or BOTH.</dt>
</dl>
<h3>Command-line options</h3>
<dl>
<dd><tt>--conf=<em>file</em></tt></dd>
<dt>Uses <em>file</em> instead of the default conffile.</dt>
<dd><tt>--txf=<em>freq</em></tt></dd>
<dt>Transmit frequency is <em>freq</em> Hz.</dt>
<dd><tt>--rxf=<em>freq</em></tt></dd>
<dt>Receive frequency is <em>freq</em> Hz.</dt>
<dd><tt>--txb=<em>bauds</em></tt></dd>
<dt>Transmit baud rate is <em>bauds</em>.</dt>
<dd><tt>--rxs=<em>sens</em></tt></dd>
<dt>Receiver Sensitivity parameter is <em>sens</em>.</dt>
<dd><tt>--amp=<em>gain</em></tt></dd>
<dt>Receive gain is <em>gain</em>.</dt>
<dd><tt>--if=<em>freq</em></tt></dd>
<dt><acronym title="Intermediate Frequency">IF</acronym> is approximately <em>freq</em> Hz.</dt>
<dd><tt>--sr=<em>rate</em></tt></dd>
<dt>Sample rate is <em>rate</em> Hz. Supported values depend on your sound card.</dt>
<dd><tt>--bw=<em>width</em></tt></dd>
<dt>Receive filter bandwidth is <em>width</em> Hz. Must be one of 10, 50, 150, 750.</dt>
<dd><tt>--moni</tt></dd>
<dt>Enables the monitor.</dt>
<dd><tt>--no-moni</tt></dd>
<dt>Disables the monitor.</dt>
<dd><tt>--afc</tt></dd>
<dt>Enables Automatic Frequency Control.</dt>
<dd><tt>--no-afc</tt></dd>
<dt>Disables Automatic Frequency Control.</dt>
</dl>
</div><!--#config-->
<div id="depends">
<h2>Dependencies</h2>
<p>In order to compile and run <tt>3psk</tt>, you will need:</p>
<ul>
<li>libsdl (the Simple DirectMedia Library), <a href="http://www.libsdl.org">http://www.libsdl.org</a>.</li>
<li>SDL_ttf (the SDL TrueType Font library), <a href="http://www.libsdl.org/projects/SDL_ttf">http://www.libsdl.org/projects/SDL_ttf</a>.</li>
<li>FFTW3 (the Fastest Fourier Transform in the West), <a href="http://www.fftw.org">http://www.fftw.org</a>.</li>
<li>libatg (A Tiny Gui library for SDL), on <a href="https://github.com/ec429/libatg">GitHub</a>.</li>
<li>sdl_audioin (an audio input library for SDL), <a href="http://burningsmell.org/sdl_audioin/">http://burningsmell.org/sdl_audioin/</a>.</li>
</ul>
</div><!--#depends-->
</body>
</html>