forked from jimahlstrom/quisk
-
Notifications
You must be signed in to change notification settings - Fork 0
/
docs.html
1717 lines (1569 loc) · 59.9 KB
/
docs.html
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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en"><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="description" content="Documentation for Quisk">
<meta name="author" content="James C. Ahlstrom">
<meta name="keywords" content="quisk, sdr, software defined radio, ham radio">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Documentation for Quisk</title>
<style type="text/css">
* {
margin: 0px;
}
table, th, td {
border: 1px solid black;
border-collapse: collapse;
padding-left: 10px;
padding-right: 20px;
}
body {
padding: 0px;
}
ul.menu {
padding: 20px;
}
div.menu {
position: fixed;
float left;
background: #F9F9C9;
overflow: scroll;
width: 15%;
height: 100%;
padding: 5px;
font-family: sans-serif;
font-size: 16px;
}
div.contents {
position: relative;
float: right;
overflow: scroll;
width: 80%;
height: 100%;
padding: 10px;
}
p {font-size:1.2rem;}
pre {font-size:1.2rem;}
ul {font-size:1.2rem;}
table {font-size:1.2rem;}
h1 {font-size:2.0rem;}
h2 {font-size:1.8rem;}
h3 {font-size:1.6rem;}
</style>
</head>
<body>
<div class="menu">
<ul class="menu">
<li><a href="#Welcome">Welcome</a></li>
<li><a href="#Credits">Credits</a></li>
<li><a href="#Installation">Installation</a></li>
<li><a href="#Configuration">Configuration</a></li>
<li><a href="#SoundCards">Sound Cards</a></li>
<li><a href="#SoftRock">SoftRock</a></li>
<li><a href="#SDRIQ">SDR-IQ</a></li>
<li><a href="#Perseus">Perseus</a></li>
<li><a href="#Timing">Timing</a></li>
<li><a href="#USBControl">USB Control</a></li>
<li><a href="#CustomHardware">Custom Hardware</a></li>
<li><a href="#ExtensionPackages">Extensions</a></li>
<li><a href="#Digital">Digital Modes</a></li>
<li><a href="#Hamlib">Rig Control and Logging</a></li>
<li><a href="#wsjtx">WSJT-X</a></li>
<li><a href="#VNA">VNA</a></li>
<li><a href="#Remote">Remote Operation</a></li>
</ul>
</div>
<div class="contents">
<h1>
<a id="Welcome"></a>
Welcome to QUISK (December 2023)
</h1>
<p>
This is Quisk, a Software Defined Radio (SDR). You supply an antenna and
a complex (I/Q) mixer to convert the radio spectrum to a low IF. Then send
that IF to your computer using the sound card, Ethernet or USB.
The Quisk software will read the I/Q data, tune it, filter it,
demodulate it, and send the audio to headphones or speakers.
Quisk has a microphone input and a key input so it can operate as a
complete transceiver. Quisk works with this hardware:
</p>
<br>
<ul>
<li>SoftRock connected to the sound card</li>
<li>Many other SDR's connected to the sound card</li>
<li>SDR-IQ connected by USB</li>
<li>Perseus connected by USB</li>
<li>N2ADR hardware connected by Ethernet and IP</li>
<li>HiQSDR hardware connected by Ethernet and IP</li>
<li>The Hermes-Lite project at <a href="http://hermeslite.com">hermeslite.com</a></li>
<li>Quisk can be used as a pan adapter, and can control some radios</li>
</ul>
<br>
<p>
Quisk is small and simple, and has been designed so that it is easy to
change Quisk to suit your own hardware. 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.
<br>
<br>
Please read the file <a href="http://james.ahlstrom.name/quisk/CHANGELOG.txt">CHANGELOG.txt</a>
for changes.
<br>
<br>
When running Quisk for the first time, please press the "Help"
button on the lower right.
<br>
<br>
</p>
<h2>News</h2>
<p>
The newest versions of Linux and Raspberry Pi OS do not allow installing Quisk in the system Python package directory.
Use the Linux Source Installation below instead.
</p>
<br>
<p>
<b>Python 2 is no longer supported.</b>
Python 2 was obsolete as of January 1, 2020. And the new code by Ben, AC2YD, needs Python 3. It is troublesome to write
code that runs on both Python 2 and Python 3. So it is time to stop supporting Python 2 in Quisk. Please upgrade to
Python 3. If you have both versions, use Python 3 for Quisk.
</p>
<br>
<h2 id="Credits">Credits </h2>
<p>
Quisk was originally written by James Ahlstrom, N2ADR.
<br>
<br>
Thanks to Leigh L. Klotz, Jr. WA5ZNU for configuration improvements,
factoring
out my eccentric hardware control, and adding panadapter and other
hardware
support.
<br>
<br>
Thanks to Franco Spinelli for a fix for the H101 hardware.
<br>
<br>
Thanks to Andrew Nilsson VK6JBL for adding support for SoftRock Rx and
Tx.
<br>
<br>
Thanks to Terry Fox, WB4JFI, for code to support the Charleston
hardware.
<br>
<br>
Thanks to Maitland Bottoms, AA4HS, for the sub-module linkage patches.
<br>
<br>
Thanks to Philip G. Lee for adding native support for PulseAudio.
<br>
<br>
Thanks to Eric Thornton, KM4DSJ, for adding async support for PulseAudio.
<br>
<br>
Many others contributed to Quisk, and are mentioned in comments in the source code.
<br>
<br>
</p>
<h2 id="Installation">Installation</h2>
<p>
Quisk is free open source software written in Python and C. It is hosted on the PyPi repository
<a href="https://pypi.org">https://pypi.org</a> and it is available on github.
</p>
<br>
<p>
If you have Python 3 installed on your computer, just continue to use that version.
<b>On Windows Quisk requires Python 3.8 or 3.9 or 3.10 or 3.11 or 3.12.</b>
If you want to install a more recent version of Python, uninstall the old version first.
Running multiple versions of Python is possible but can be confusing and is not necessary.
A Quisk installation is needed for each version of Python you have.
</p>
<br>
<h3 id="g0.2.2">Windows Initial Installation</h3>
<p>
Windows does not include Python, so you must first install a recent version of 64-bit Python 3.
If you already have 64-bit Python 3 installed, just keep using it.
<b>On Windows Quisk requires Python 3.8 or 3.9 or 3.10 or 3.11 or 3.12.</b>
There may be newer versions of Python, but until support is added, use the versions listed above.
Python is available from <a href="http://www.python.org/">http://www.python.org</a>.
There is an option to <b>Add Python to PATH</b>. You MUST select
this option so that you can start python by just typing "python" instead of the whole path
to your install directory. My install directory is:
<br>
C:\users\jim\AppData\Local\Programs\Python\Python39
<br>
And "AppData" is invisible. To avoid problems, check <b>Add Python to PATH</b>.
If you forget, it is worth it to uninstall and reinstall Python.
Quisk is really designed for curious people who want to play with the code, but Windows
tries to shield users from program details.
</p>
<br>
<p>
Next open Windows PowerShell (not PowerShell ISE). This is on the Start button menu on Windows 10; or use the
search bar. Enter "python --version" to make sure that Python is installed
and what version you have. If "python" is not found, it might not be on your Path.
You will need to keep typing <b>your_install_directory</b>\python instead of "python".
</p>
<br>
<p>
Next upgrade some Python modules to the newest version, then install Quisk. Enter these commands:
<br>
python -m pip install --upgrade pip
<br><br>
python -m pip install --upgrade setuptools
<br><br>
python -m pip install --upgrade wxPython
<br><br>
python -m pip install --upgrade pyserial
<br><br>
python -m pip install --upgrade quisk
<br><br>
To create a Quisk shortcut on your desktop, right-click an empty space and select "New" and "Shortcut".
Enter this as the location of the item:
</p>
<br>
<pre>
pythonw -m quisk
</pre>
<br>
<p>
and then name the shortcut, perhaps "Quisk".
If you check the properties you will see that Windows expanded the location and start directory to the full path.
If you are curious, Quisk and its Python source files are installed in "<b>your_install_directory</b>\Lib\site-packages\quisk".
If you change to that directory you can run Quisk with "pythonw quisk.py".
</p>
<br>
<p>
To get started you must tell Quisk what kind of radio hardware you have. Press the Config button and select Radios.
Then set your sound devices for that radio; the device for the radio speakers, the microphone and so forth. All configuration
is (mostly) from the Config button. Ignore old directions and don't bother with a config file.
</p>
<br>
<h3>Windows Quisk Upgrade</h3>
<p>
To upgrade to a newer version of Quisk, use pip. Remember that if Python is not on your Path, you will
need to type out the whole path.
You should check for newer versions of the other modules twice a year.
<br>
<br>
python -m pip install --upgrade quisk
<br>
<br>
You can also install an older version of Quisk. You may need to do that if the most recent version fails for some reason. Use:
<br>
<br>
python -m pip install quisk==4.1.51
<br>
<br>
</p>
<h3>Windows Uninstall Quisk</h3>
<p>
python -m pip uninstall quisk
<br>
<br>
</p>
<h3 id="g0.2.1">Linux Initial Installation</h3>
<p>
Linux runs on a wide variety of computers with different processors and versions of Linux.
Therefore Quisk is compiled for each one. To do this, Python and a number of other packages are required.
Most likely both Python2 and Python3 are already installed on your computer.
On my Ubuntu machine, "python2" starts Python2 and "python3" starts Python3.
Just "python" starts Python2, but this will change as Python2 is phased out.
<b>Python2 is obsolete</b>, so you should only install Quisk to Python3, and use "python3" to start it.
Install these packages by using your package manager, not Python pip.
If newer versions of these packages become available, Linux will notify you.
Use the most recent version of python3-wxgtk available for your Python version.
<br><br>
</p>
<p>
These are part of your operating system. You only install them once unless it changes.
</p>
<br>
<pre>
sudo apt-get install libfftw3-dev
sudo apt-get install libasound2-dev
sudo apt-get install portaudio19-dev
sudo apt-get install libpulse-dev
sudo apt-get install python3-dev
sudo apt-get install libpython3-dev
</pre>
<br>
<p>
These are part of Python. You only install them once unless the Python started by "python3" changes.
</p>
<br>
<pre>
sudo apt-get install python3-wxgtk4.0
sudo apt-get install python3-usb
sudo apt-get install python3-serial
sudo apt-get install python3-setuptools
</pre>
<br>
<p>
If you want to use the SoapySDR module make sure that SoapySDR is installed from its Pothosware site before you build Quisk.
Otherwise Quisk will not have the files it needs. You can install SoapySDR later, but then you
will need to run "make" again. This is also true of any other external packages that have their own C source.
<br>
<br>
</p>
<h3>Linux Pip Installation</h3>
<br>
<p>
<b> Installation of Quisk using Python tools like pip is deprecated</b>.
</p>
<br>
<p>
Installation to the system Python is no longer allowed, and you may get the message "error: externally-managed-environment".
If you used pip to install Quisk you can continue to upgrade with "sudo python3 -m pip install --upgrade quisk"
until you get this error message. But it is best to uninstall the pip Quisk. If you installed with pipx, uninstall that too.
</p>
<br>
<pre>
sudo python3 -m pip uninstall quisk
pipx uninstall quisk
</pre>
<br>
<p>
Then use the Linux Source Installation.
</p>
<br>
<br>
<h3 id="LSI">Linux Source Installation</h3>
<p>
On Linux, Quisk is installed from github, and it is contained in a "quisk" directory. First you need to decide where to put the
quisk directory. Anywhere will do, but it is best to use a directory where you have write permission so
you don't need to use "sudo". The examples below assume you used your home directory indicated by "~". Just replace "~"
by your desired location.
</p>
<br>
<p>
To install a fresh copy of Quisk, change to your desired directory, clone the github site, change to the quisk directory and run "make".
Then run the python program quisk.py.
</p>
<br>
<pre>
cd ~
git clone https://github.com/jimahlstrom/quisk
cd quisk
make
python3 quisk.py
</pre>
<br>
<p>
If "make" fails, you probably have missing packages or missing "-dev" packages. Try to figure out what is missing from the error messages.
You only clone github for the initial installation. To update Quisk, use pull:
</p>
<br>
<pre>
cd ~/quisk
git pull
</pre>
<br>
<p>
You run Quisk by running the file quisk.py with python3. For example, "python3 /home/jim/quisk/quisk.py".
You can create a desktop icon to do that, but the method depends on your version of Linux.
<b>Never run Quisk with root privelege by using sudo. Fix the permission problem instead.</b>
To get started you must tell Quisk what kind of radio hardware you have. Press the Config button and select Radios.
Then set your sound devices for that radio; the device for the radio speakers, the microphone and so forth. All configuration
is (mostly) from the Config button. Ignore old directions and don't bother with a config file.
To uninstall Quisk, just delete the quisk directory.
</p>
<br>
<h3 id="g0.2.4">Quisk Files</h3>
<p>
<br>
These are the Quisk files in the distribution:
<br>
<br>
</p>
<ul>
<li>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. </li>
</ul>
<ul>
<li>help.html is the help file for quisk. Press the "Help" button. </li>
</ul>
<ul>
<li>_quisk.so is the _quisk extension module for Linux, and _quisk.pyd is the extension module DLL used by Windows.
<br>
</li>
</ul>
<ul>
<li>sdriq.so is the extension module needed for the SDR-IQ. It needs
_quisk.so to be available when it starts. </li>
</ul>
<ul>
<li>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. </li>
</ul>
<ul>
<li>setup.py is used by makefile and the Python installers. </li>
</ul>
<ul>
<li>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. </li>
</ul>
<ul>
<li>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.
</li>
</ul>
<ul>
<li>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. </li>
</ul>
<ul>
<li>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 and _quisk.pyd.
<br>
</li>
</ul>
<ul>
<li>sound.c is the general purpose sound code for all sources.</li>
</ul>
<ul>
<li>sound_portaudio.c is the sound card access code for PortAudio. PortAudio is optional.</li>
</ul>
<ul>
<li>sound_pulseaudio.c is the sound card access code for PulseAudio. </li>
</ul>
<ul>
<li>sound_alsa.c is the sound card access code for the ALSA drivers.
<br>
</li>
</ul>
<ul>
<li>sound_directx.c is the sound card access code for DirectX. </li>
</ul>
<ul>
<li>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. </li>
</ul>
<ul>
<li>sdriq.c, sdriq.h are the files that make sdriq.so and support the
SDR-IQ. </li>
</ul>
<ul>
<li>microphone.c reads the microphone audio and sends it to your
hardware
using Ethernet. Change it for other sound access.</li>
</ul>
<ul>
</ul>
<ul>
<li>docs.html is Quisk documentation. Look for other *.html and *.txt too.</li>
</ul>
<ul>
<li>portaudio.py is a utility program. Run it to list your PortAudio
devices. It is not used by the Quisk program. </li>
</ul>
<br>
<h2 id="Configuration">Configuration</h2>
<p>
The Quisk "Config" button brings up a number of status and configuration screens.
Quisk supports multiple types of radio hardware and each type has different parameters.
Each block of parameters is called a "radio". It is a named block of settings Quisk uses
to control a specific kind of hardware.
So a single Quisk can have parameters for a SoftRock and an HL2.
You specfy the radio you want when starting Quisk.
<br>
<br>
When you first install Quisk, you will not have any settings for your radio.
Press the Config button and go to the Radios screen.
Then create a radio by specifying the general hardware type and give it a name of your choosing.
For a Hermes-Lite, specify "Hermes" as the hardware type and call it "HL2" (or some other name).
Press "Add" and a new tab for your radio will appear. Look through the various settings on the HL2 tab.
The parameters for the radios are stored in the file quisk_settings.json.
<br>
<br>
A special radio called "ConfigFileRadio" is always available.
It takes its parameters from a configuration file.
You can set almost everything with the screens, but you can have a configuration file if you want.
Most users will not need a configuration file.
For Linux, the default configuration file name is ".quisk_conf.py" in your home
directory; that is, "~/.quisk_conf.py". For Windows, the default
configuration file name is quisk_conf.py in your My Documents folder.
<br>
<br>
</p>
<h2 id="SoundCards">Sound Cards </h2>
<p>
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 input to see the noise floor. It should be as flat and as low
as
possible,
with no bump near 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 (sound) input to the sound card should raise the
noise
floor only slightly to avoid losing dynamic range.
<br>
<br>
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. 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.
<br>
<br>
If you use the SDR-IQ or other hardware for input, you still need a
sound card for sound output. The quality of this card is not so
important, so try the one you have. Be aware that most sound
cards require the capture and playback rate to be the same when used
for both. Here are some sample configurations:
<br>
</p>
<ul>
<li>SoftRock Rx/Tx: Receive to card 1, Transmit to card 1 at the same
rate, radio sound to card 2 at 48 kHz, microphone input from card 2 or
3 at 48 kHz.</li>
<li>SoftRock Rx: Receive to card 1, radio sound to card1 at the same
rate; OR radio sound to card 2 at 48 kHz.</li>
<li>Other: Receive from SDR-IQ or other hardware, radio sound to card
1 at 48 kHz. Add a microphone to card1 at 48 kHz, or to card2 at
48 kHz.</li>
<li>Panadapter: There is no radio sound. Enter a null name ""
for the play device.
<br>
</li>
</ul>
<p>
If you buy a new sound card, make sure you know the
capture (recording) sample rates and the noise level. 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.
</p>
<br>
<h3 id="g0.4.1">Linux Names</h3>
<p>
Quisk can use PulseAudio, PortAudio or ALSA to access your sound card.
Names can be a fragment of text from the device description. It is
better to use this text search rather than an index number, because the
index number can change if you plug and unplug USB sound cards.
<br>
<br>
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 the raw hardware if possible. If the raw devices don't
work,
use the "plughw" name. The ALSA name can also be a string
name. Here are some ALSA names:
<br>
</p>
<br>
<pre>"hw:0" # First sound card
"hw:1" # Second sound card, etc.
"plughw" # plug device
"default" # alsa default device
"alsa:NVidia" # Search for the name in the alsa device description
</pre>
<br>
<p>
Alsa names starting with "alsa:" are an extension to the normal alsa
names. They search for the text after the colon in the alsa
device
name. The alsa device names are shown on the config screen.
Or you
can start a terminal window and enter "aplay -l" for a list of play
devices, or "arecord -l" for a list of capture devices. See <a href="http://james.ahlstrom.name/alsa_names.html">alsa_names</a> for
more information.
<br>
<br>
The PortAudio interface is now optional. Many users are changing to PulseAudio.
You can run "python portaudio.py" in a terminal window to
see a list of available PortAudio names. Here are some PortAudio names:
<br>
</p>
<pre>"portaudio:(hw:0,0)" First sound card.
"portaudio:(hw:1,0)" Second sound card, etc.
"portaudio:NVidia" Search for the name in the portaudio device description.
"portaudio#1" Directly specified index.
"portaudiodefault" May give poor performance on capture.
</pre>
<br>
<h3 id="g0.4.2">Linux Sound Servers </h3>
<p>
Newer Linux systems are now shipping with PulseAudio enabled.
PulseAudio is a sound server, a program that takes control of your
sound cards, and controls usage by applications. The idea is that
your applications talk to PulseAudio, and PulseAudio talks to the sound
cards. Another example of a sound server is JACK.
You can control the
sound routing with the pavucontrol program. Remarkably, this is
not included with PulseAudio, and you will need to install the
pavucontrol package first.
<br>
<br>
Thanks to Philip G. Lee and Eric Thornton, KM4DSJ, Quisk now has native support for PulseAudio.
For PulseAudio devices, use the name "pulse:name" and connect the streams
to your hardware devices using a PulseAudio control program like pavucontrol. The name "pulse"
alone refers to the "default" device. The PulseAudio names are quite long;
for example "alsa_output.pci-0000_00_1b.0.analog-stereo". Look on the screen
Config/Sound to see the device names. There is a description, a PulseAudio name,
and for ALSA devices, the ALSA name.
Instead of the long PulseAudio name, you can enter a substring of any of these three strings.
An example is:
</p>
<br>
<pre>
# As seen on the Config/Sound screen:
CM106 Like Sound Device Analog Stereo
alsa_output.usb-0d8c_USB_Sound_Device-00-Device.analog-stereo
USB Sound Device USB Audio (hw:1,0)
# Use the default pulse device for radio sound:
"pulse"
# Use a PulseAudio name for radio sound:
"pulse:alsa_output.usb-0d8c_USB_Sound_Device-00-Device.analog-stereo"
# Abbreviate the PulseAudio name:
"pulse:alsa_output.usb"
# Another abbreviation:
"pulse:CM106"
</pre>
<br>
<p>
The PulseAudio code should not cause problems, but I am not sure what happens if PulseAudio is not
installed, or if you replace it with JACK. This config file option will turn off all but directly
entered "pulse:" names:
</p>
<pre>show_pulse_audio_devices = False
</pre>
<br>
<h3 id="g0.4.3">Linux Problems </h3>
<p>
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.
<br>
<br>
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.
<br>
<br>
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.
<br>
<br>
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.
<br>
<br>
If you really get stuck, try one of these commands (see the "man"
page):
<br>
</p>
<ul>
<li>alsamixer An ALSA mixer program with a curses interface. </li>
</ul>
<ul>
<li>amixer A character ALSA mixer. </li>
</ul>
<ul>
<li>aplay Play sound. </li>
</ul>
<ul>
<li>arecord Capture sound. </li>
</ul>
<ul>
<li>speaker-test Play sound to test your speakers. </li>
</ul>
<p>
<br>
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 or PulseAudio interface by
just
changing the sound card names.
<br>
<br>
</p>
<h3 id="g0.4.4">Windows Names</h3>
<p>
To see what sound cards you have, use the Control Panel item Sound
Devices. There is a separate list for capture (recording) and
playback devices, and a specified default device for each. The
name of the default device is "Primary". To specify your sound
card name, use either "Primary" or a substring of the device
name. The search is case sensitive.
<br>
<br>
</p>
<h2 id="SoftRock">SoftRock</h2>
<p>
SoftRock radios use an analog mixer to change the RF signal to stereo audio, and then use a sound card to digitize it.
A high quality sound card is advisable. The analog mixer is not perfect, and it will be necessary to adjust the I and Q
signals to equal amplitude and 90 degrees phase difference. Use the Config/Config screen buttons to
bring up an adjustment screen. Adjustments must be made for each band, and separately for transmit and receive.
The adjustment depends on both the VFO frequency and the tuning offset from the VFO.
Quisk has an option to fix the tuning offset to a constant and to tune with the hardware.
The tuning offset then has a constant correction and it is only necessary to correct for the VFO,
a much less sensitive correction.
See my paper
<a href="http://james.ahlstrom.name/phase_corr.html">http://james.ahlstrom.name/phase_corr.html</a> for more information.
<br>
<br>
A good strategy is to pick a VFO near the band center, and record corrections at an Rx frequency of -15000, -1000, 1000 and 15000 Hertz.
If the corrections are sensitive to VFO, record the corrections for these same Rx frequencies at VFOs equal to
or slightly outside the upper and lower band edges.
To effectively adjust for multiple VFO frequencies, the VFOs must have the same table of Rx frequencies.
You can add as many correction points as desired. The corrections are saved in the file quisk_init.json. This file can be edited
by hand if you are a Python expert. Otherwise you can just read the values.
<br>
<br>
If you fix the tuning offset to a constant, you can create a correction for VFO at the band center, or
the center and both edges.
<br>
<br>
To create a Receive correction point for a given VFO and frequency, attach a signal generator to the SoftRock through an attenuator,
and look at the image on the graph screen. If the signal is 3500 Hertz above the VFO, the image is 3500 Hertz below it.
Choose "Measure" to measure the corrections and then "Add Cell".
If you don't have a signal generator, find a strong station on the band and look at its image. Choose "Manual adjustment".
Minimize the image by adjusting the amplitude and phase sliders on the adjustment screen, and then press "Add cell".
<br>
<br>
To create a Transmit correction point for a given VFO and frequency, attach the SoftRock RF output to a spectrum analyzer through an attenuator,
and look at the image. If you don't have a spectrum analyzer use a second receiver tuned to the image. Minimize the image by adjusting
the amplitude and phase sliders on the adjustment screen, and then press "Add cell".
<br>
<br>
</p>
<h2 id="SDRIQ">SDR-IQ as Input </h2>
<p>
Quisk can use an SDR-IQ from RfSpace instead of a sound card as input.
Set up a radio of type SdrIQ. The SDR-IQ uses a serial port to connect to Quisk. When you plug it in,
it will create a USB serial port and connect to it.
</p>
<br>
<p>
On Linux the serial port has a name like /dev/ttyUSB0. Look in /dev or use "dmesg | tail" to figure out what port it is using.
Then enter that port as the "Serial port" on the Config/radio/Hardware screen. The serial ports are part of the "dialout" group.
Add yourself to the "dialout" group so you have permission to use the serial port. You also need a serial port USB
driver for the ft245 chip in the SDR-IQ, but Linux generally comes with a suitable driver.
</p>
<br>
<p>
On Windows the "Serial port" name is not used, and Quisk will search for the port in use.
On Windows 10, you should see a device "SDR-IQ" in Device Manager in the "View/Devices by Container" tab.
In earlier versions of Windows, port names are COM1, COM2 etc. and use the "USB Serial Converter" driver.
Windows should find this driver by itself.
</p>
<br>
<h2 id="Perseus">Perseus as Input </h2>
<p>
Quisk can use an Perseus HF receiver from Microtelecom instead of a sound card as input.
Set up a radio of type Perseus. The Perseus uses a native USB interface to connect to Quisk.
The Quisk perseuspkg extension relies on <a href="http://github.com/Microtelecom/libpserseus-sdr">libperseus-sdr</a>
open source library to manage Perseus hardware and receive the I/Q samples stream.
</p>
<br>
<p>
Follow the instruction into GitHub repository to compile and install the library.
On Suse distribution the library is available as binary package.
Next compile the perseuspkg using the command:
</p>
<br>
<pre>
make perseus3
</pre>
<br>
<p>
The several sample rates can be selected opening Config panel: in
the Config tab there is the Samples rates dropdown.
The input analog filter can be switched in using the button Wideband.<br>
The input attenuator is operate via the button RF, that allows to select
the four attenuator steps.<br>
The ADC commands for dithering and preamplifier are found on
left bottom corner as ADC Dither and ADC Preamp.<br>
</p>
<br>
<h2 id="Timing">Timing </h2>
<p>
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.
<br>
<br>
</p>
<h2 id="USBControl">USB Control </h2>
<p>
Many radio devices are now controlled through a USB interface. In
many cases, the interface is actually a serial port, and an external or
internal USB to serial converter is used. In other cases, the USB
is native, but requires a custom device driver. In still other
cases, the USB device announces itself as a standard device such as a
sound device or human interface device, and uses a standard operating
system built-in driver.
<br>
<br>
</p>
<h3 id="g0.7.1">Linux</h3>
<p>
Default USB permissions do not allow a non-root user to write to the
bus. You may find that Quisk will complain about lack of
permission to access the USB. You could test this by running
Quisk as root and seeing if that works; but this is not acceptable
except for testing. To change USB permissions, add a rule to
/etc/udev/rules.d/local.rules (for SoftRock on Debian and Ubuntu) like
this:
<br>
<br>
SUBSYSTEM=="usb", ATTR{idVendor}=="16c0" ,
ATTR{idProduct}=="05dc", MODE="0666", GROUP="dialout"
<br>
<br>
This changes the USB device permissions to read/write for all users,
and changes the group to the "dialout" group. Default group
permissions are read/write, so if you are in the "dialout" group, you
don't need "MODE"; modify as appropriate. To load the new rule, you can either reboot or on Ubuntu use
<br>
<br>
sudo udevadm control --reload-rules
<br>
<br>
</p>
<h2 id="CustomHardware">Custom Hardware</h2>
<p>
Quisk comes with hardware files for many types of radio. See the various quisk_hardware_*.py files.
But if you have a radio that Quisk does not support, or if you want to customize an included hardware file, you
can write your own hardware file and enter the name on the Config/radio/Hardware screen.
A model hardware file is included as quisk_hardware_model.py.
It is useful as a starting point and as documentation. Hardware files use Python class inheritance.
That is, all hardware files inherit methods from a parent file and then add their custom methods.
Hardware files can control other hardware too.
At my shack, I control an AT-200PC antenna tuner, my SDR-IQ, my filter
boxes and my SSB transceiver (using Ethernet) all with Quisk.
Take a look at my n2adr subdirectory.
</p>
<br>
<p>
The quisk_hardware_model.py file shows the basics of hardware control.
There is an open() and close() function called once on startup and
shutdown. The ChangeMode() and ChangeBand() functions are called when
the user changes the mode or band with the corresponding buttons.
The HeartBeat() function is called at about 10 Hz by Quisk. You
can put code there to poll a serial port or to perform other
housekeeping functions.
</p>
<br>
<p>
Here is the start of the SDR-IQ hardware file:
</p>
<br>
<pre>
from quisk_hardware_model import Hardware as BaseHardware