1 CWirc X-Chat morse plugin
2 -------------------------
3 2.0.0
4 -----
5
6 F8EJF
7 Pierre-Philippe Coupard <pcoupard@skynet.be>
8 20/05/2006
9
10
11
12 CWirc is a plugin for the X-Chat IRC client to transmit raw morse code over
13the internet using IRC servers as reflectors. The transmitted morse code can be
14received in near real-time by other X-Chat clients with the CWirc plugin. CWirc
15tries to emulate a standard amateur radio rig : it sends and receives morse
16over virtual channels, and it can listen to multiple senders transmitting on
17the same channel. Morse code is keyed locally using a straight or iambic key
18connected to a serial port, or using the mouse buttons, and the sound is played
19through the soundcard, or through an external sounder.
20
21 Note that CWirc doesn't do any morse decoding : it simply transmits and
22receives morse code timing events. A standard IRC user on the same IRC channel
23you're transmitting morse on will only see coded lines when morse code is
24transmitted. Only other CWirc users can receive what you send.
25
26
27
281 - Installing CWirc
29
30 - Edit the Makefile to set the target OS (LINUX, FREEBSD or NETBSD) and the
31 installation paths for the CWirc binaries.
32
33 - Build the program by typing "make"
34
35 - Install the plugin and its frontend program by typing "make install" as root
36
37
38
392 - Using CWirc
40
41 CWirc is composed of two parts : a X-Chat plugin stub that intercept and
42 sends morse frames as IRC text, and a frontend application that interacts
43 with the user through a graphical interface. The frontend application is
44 meant to be loaded by the plugin only, and cannot be used as a standalone
45 program.
46
47 To use CWirc, it is necessary that X-Chat loads the plugin part first.
48 Normally, the CWirc plugin is installed in the X-Chat plugins directory as
49 "cwirc.so" and is automatically loaded by X-Chat at startup. You can verify
50 it's loaded properly by going in the "Windows" --> "Plugins and Scripts" menu
51 in X-Chat and checking that CWirc appears in the list.
52
53 When the "cwirc.so" file is loaded, it adds a new command to X-Chat, called
54 "/CW" (you can do "/HELP CW" to verify this), and it also adds a "CWirc"
55 button in the userlist buttons (if you don't see it, try enabling "Userlist
56 button enabled" in the "Preferences -> User list" menu. The "/CW" command or
57 the "CWirc" button enable and disable the plugin. Note that CWirc should
58 have no incidence whatsoever on your normal IRC chatting on any channel, but
59 it will always silently filter out incoming morse frames, whether it is
60 enabled or not, so you can chat normally on a morse-dedicated IRC channel
61 even with the plugin disabled.
62
63 When enabling the plugin, the frontend application is called and the CWirc
64 control panel appears outside of X-Chat. In the control panel, there are six
65 tabs: the main tab for regular use, as well as the keyer settings,
66 simulation, personal information, I/O configuration and "about" tabs.
67
68
69 2.1 - The main tab
70
71 2.1.1 - The S-meter / sidetone mode toggle
72
73 This is an emulated classic needle signal meter. When signal strength
74 simulation (see below) is used, it shows the strength of the incoming
75 signal. When no simulation is used, it is simply decorative and move
76 from S0 to S9+30 no matter what signal is sent or received.
77
78 When the S-meter is clicked, CWirc switches to sidetone mode. When it's
79 clicked again, CWirc goes back to normal mode. In sidetone mode, you can
80 key without actually sending anything. This is useful when adjusting a
81 key, or to train keying morse code, without bothering anybody on the
82 channel.
83
84
85 2.1.2 - The Channel setting
86
87 CWirc has a concept of "CW channel", as opposed to IRC channel. They are
88 not the same. Think of it as the frequency you'd dial on your radio rig.
89 You can only send or receive morse on one CW channel. CWirc ignores morse
90 sent to other CW channels. There are 4000 CW channels available (0->3999),
91 therefore on any given IRC channel, there can be up to 4000 distinct QSOs
92 going on.
93
94 The top "PR x" selector selects one of 5 preset channels. The bottom
95 channel setting sets the CW channel for that preset channel. You can
96 therefore program up to 5 favorite CW channels : for example, you could
97 set channel 1 at 1000 for the CQ channel, channel 2 at 1100 for the
98 channel you usually QSY to, channel 3 at 912 to listen to the news
99 channel ...
100
101
102 2.1.3 - The RX pitch setting
103
104 This setting changes the sound pitch of received morse beeps, allowing
105 you to play your correspondant's signal at a frequency you're confortable
106 with, or helping you discriminate between different operators
107 transmitting on the same channel, if you "have an ear" for a particular
108 audio frequency.
109
110 NOTE: this setting does nothing if CWirc plays sounder clicks instead of
111 beeps, or if the CW output is an external sounder only (see below).
112
113
114 2.1.4 - The TX pitch setting
115
116 This setting changes the sound pitch of your own signal played back to
117 you locally. You can adjust it in sidetone mode (see above) to avoid
118 sending garbage on the channel.
119
120 NOTE: this setting does nothing if CWirc plays sounder clicks instead of
121 beeps, or if the CW output is an external sounder only (see below).
122
123
124 2.1.5 - The Squelch setting
125
126 If you use QRN simulation (see below), fake radio static is played
127 continuously and it quickly gets very tiring. Like on a real radio, to
128 cut off the background noise when it's not useful (when you're not
129 actually transmitting or receiving anything), set the squelch high enough
130 to stop the background noise, and low enough to re-enable the sound when
131 a signal comes.
132
133 Note that if you use signal strength and/or sporadic-E simulation (see
134 below), using the squelch can make you miss weak signals.
135
136
137 2.1.6 - The AF gain setting
138
139 This changes the volume of beeps or sounder clicks played throught the
140 sound card. Note that your computer's actual mixer device isn't used to
141 set the volume : CWirc simply generates lower amplitude sound signals
142 internally.
143
144
145 2.1.7 - The Key setting
146
147 This setting tells CWirc to read mouse clicks on the mouse keying zone,
148 or a real morse key connected to a serial port (see below), as a straight
149 key, or as paddles using the internal automatic keyer. The icon displayed
150 in the mouse keying zone changes to a straight key or an iambic key
151 accordingly.
152
153
154 2.1.8 - The Iambic keyer speed setting
155
156 If you set "Key" to "iambic", you can set the automatic keyer's speed
157 in words per minutes. The keyer will function in that speed according to
158 the settings in the "Keyer settings" tab (see below).
159
160
161 2.1.9 - The mouse keying zone
162
163 If you enabled the mouse as CW input (see below), you can key morse code
164 with the mouse by leaving the pointer in the morse key icon and using the
165 buttons as key or paddles. If you set "Key" to "iambic", the left and
166 right mouse buttons act as paddles. If you set "Key" to "straight", either
167 mouse button emulates the key.
168
169
170 2.1.10 - The automatic morse decoder
171
172 At the bottom of the control panel, there is a line with morse
173 characters decoded from the morse signal currently received.
174
175 The morse decoder that generates those characters simulates a real
176 automatic decoder connected to the audio output of a real radio rig.
177 Therefore, it will work only if only one person is transmitting at a
178 time. If several people send morse together on the same CW channel, like
179 in a pile-up, or if you transmit over someone else's signal, the decoder
180 will get confused and generate garbage. If you really need to decode a
181 particular sender in a pile-up with the decoder, you could use the IRC
182 command "/IGNORE" to silence all the other senders.
183
184 If you use signal strength and/or sporadic-E simulation, the decoder
185 will not work if the incoming signal is too weak or fluctuating, or will
186 not decode properly. Similarly, if a strong signal and a weak signal are
187 received at the same time, only the strong signal will be decoded. If
188 more than one strong signal arrive at the same time, the decoder will get
189 confused.
190
191 Also, the decoder needs to "hear" a little signal before synchronizing
192 correctly with a sender, or with you. Therefore, the first character(s)
193 will be garbled as the decoder guesses the timing of the morse code.
194 It will resync similarly if the sender suddenly changes his/her keying
195 speed dramatically, or if you yourself don't send at a speed close to
196 that of your correspondant. Finally, although the decoder makes
197 allowances for slightly incorrect morse timings and drifting keying
198 speed, it still needs to receive somewhat clean morse code to work well.
199 You're better off using your ears to copy a bad sender, or a sender using
200 a very atypical dit weighing.
201
202 The decoder is also useful in sidetone mode (see above) to train keying
203 clean morse with proper timing.
204
205 NOTE: If you conduct a QSO in a code that's not modern morse code or DOT
206 code, like in genuine American morse code, the decoder will
207 produce garbage.
208
209
210 2.1.11 - The automatic morse decoder's speed indicator / reset button
211
212 The received morse speed indicator at the right of the decoded text, in
213 words per minute, is an measure of your correspondant's keying speed.
214 It is measured from the raw received or sent signal, therefore it can be
215 quite approximative. If the decoder gets confused with two superimposed
216 signals, or a signal with fluctuating strength, the speed indicator
217 becomes wild and means nothing. If the morse code doesn't use a dit
218 weighing of 50%, the speed indicator will also be skewed.
219
220 This indicator also doubles as a morse decoder reset button. Pressing
221 it will erase the current decoded characters buffer and will reset the
222 automatic decoder.
223
224
225 2.1.12 - The automatic morse decoder's language selector
226
227 At the right of the morse decoder speed indicator, you can select which
228 language or code set you would like the decoder to use to decode incoming
229 signals. At the moment, English (international), French, Russian,
230 Japanese (katakana) morse code, and historic DOT code (which isn't morse)
231 are supported.
232
233 In order to view decoded characters in a language other than English,
234 (english morse or DOT) you need to have a real Unicode/ISO-10646 font set
235 installed on your system. If you are interested in using a non-English
236 morse code set, chances are your machine is already setup correctly.
237 Otherwise, a good start if you want to configure your fonts correctly
238 under X is to read the "XFree86 Font De-uglification HOWTO" document
239 available at :
240
241 http://www.tldp.org/HOWTO/FDU/index.html
242
243 If you find the decoder distracting, or if you can't resist looking at
244 it when training to copy, simply select "No decoder" to disable it
245 entirely.
246
247
248 2.2 - The Keyer settings tab
249
250 This tab lets you adjust the iambic keyer to your liking. Keyer features
251 and settings are a very personal issue : iambic keyers from different
252 manufacturers (or home-made keyers), and sometimes different models from
253 the same manufacturer, have slightly different responses to an operator's
254 input, and most people tend to prefer the features displayed by whichever
255 keyer they first learned iambic keying with. The CWirc keyer can be
256 adjusted to match almost any existing iambic keyer.
257
258
259 2.2.1 - The iambic mode selector
260
261 Set the iambic mode you would like the CWirc keyer to use. The iambic
262 mode (A or B) only changes the behaviour of the keyer when both paddles
263 are released after having been squeezed together (i.e. iambic keying) :
264 in mode-A, when both paddles are released in the middle of an element
265 being sent (dit or dah), the element is completed, then the keyer stops.
266 In mode-B, the element is completed, then the keyer automatically sends
267 an extra opposing element, then stops.
268
269 If your Cs consistently come out as Ks, you're probably using mode-A
270 when you really want mode-B. Conversely, if your Ks consistently come out
271 as Cs, you probably want to use mode-A.
272
273
274 2.2.2 - The dit memory and dah memory
275
276 If you enable the dit memory, when the keyer sees the dit paddle being
277 hit, however briefly, during the sending of a dah, it "remembers" it and
278 sends the dit at the next possible occasion. Similarly, the dah memory
279 enables the automatic insertion of a dah by touching the dah paddle while
280 a dit is being sent out.
281
282 Typically, dit/dah memory is used to make Ns and As by tapping the
283 two paddles quickly one after the other (but not squeezing, that would
284 make the keyer go into iambic mode). It's also very useful to make
285 letters such as Y, Q, L or F by sending a stream of dahs or dits, and
286 inserting a dit or a dah by tapping the opposing paddle at the right
287 moment.
288
289
290 2.2.3 - The mid-element mode-B mode
291
292 Most mode-B keyers automatically insert an opposing element when
293 releasing both paddles anytime during the element currently being sent,
294 in iambic mode. Some mode-B keyers however seem to make a distinction
295 between the case where both paddles are released before the middle of the
296 element currently being sent, and the case where they're released after.
297 In the former case, those keyers don't send an opposing element, while
298 they do in the latter. Those keyers seem to be a minority though.
299
300 If your As consistently come out as Rs and your Us as Fs, but your
301 keying is otherwise fine in mode-B, you might want to try this option.
302
303
304 2.2.4 - The auto character spacing
305
306 When this option is enabled, the keyer forces you to wait the correct
307 time between letters. Try using this if you consistently run letters
308 together.
309
310
311 2.2.5 - The auto word spacing
312
313 In addition to the auto character spacing, you can use this option to
314 force the keyer to make you wait the correct time between words and help
315 you format your transmission perfectly. Try using this if you consistently
316 fail to leave enough time between words. Be aware however that this option
317 requires an otherwise good keying to be used efficiently, as it will force
318 you to wait a full inter-word pause each time you hesistate on a letter.
319
320
321 2.2.6 - The "invert paddles" option
322
323 If you're left handed, or if you're used to key using the left paddle
324 as dah paddle and the right paddle as dit paddle, enable this option.
325
326
327 2.2.7 - The dit weight setting
328
329 Back when radios often showed a certain lag between the moment a key
330 was depressed and the moment it would start transmitting, it was often
331 useful to artificially increase the length of the elements sent by the
332 keyer, so that they would end up being sent on the air with the proper
333 timing by the radio. Today, most transceivers don't need this trick to
334 send properly formatted CW, but some operators have kept their
335 non-standard dit weight because it sounds better, or to "personalize"
336 their signal. The CWirc keyer allows you to change the dit weight as
337 well, although it's completely useless to do CW over the net.
338
339 The value corresponding to the standard morse code timing is 50%.
340
341 NOTE: don't overdo it : if you set the dit weight too far off 50%, most
342 people won't be comfortable copying you, and some might even not
343 copy you at all.
344
345
346 2.3 - The Simulation tab
347
348 This tab lets you set CWirc to experience an approximation of what a real
349 radio sounds like, to train copying signals that are less than perfect and
350 a little less "artificial" and computer-generated than with the basic
351 settings.
352
353
354 2.3.1 - the QRN simulation box
355
356 Check "simulate QRN" to add noise and static to incoming signals. Use
357 the "QRN level" slider to set the level of noise you want. The level
358 of QRN you've chosen registers on the S-meter in the main tab.
359
360
361 2.3.2 - The Propagation simulation box
362
363 Check "simulate signal strength for signals with grid squares" to make
364 CWirc generate a fake signal strength for incoming signals that have been
365 sent with a grid square location as part of the signal.
366
367 For this to work, you have to have your own grid square set in the
368 Personal info tab (see below) : the way CWirc knows what signal strength
369 to give to an incoming signal is by calculating the distance between you
370 and the person who emits the signal, hence it must know your location as
371 well as the sender's. It's up to the sender to disclose his/her own grid
372 square : if he/she doesn't want to disclose it, his/her signal will be
373 given a default signal strength that you can set with the bottom slider
374 marked "default signal strength for signals without grid squares".
375
376 In addition to the basic signal strength simulation, you can add
377 sporadic-E simulation by checking "simulate sporadic-E for weak signals".
378 Real sporadic-E is a type of ionospheric E-layer reflection caused by
379 small patches of unusually dense ionization in the atmosphere that makes
380 many long distance contacts possible on VHF. Such reflected signals tends
381 to come and go quickly as the patches of ionization move up in the
382 atmosphere, making those long contacts challenging to establish and
383 maintain. With sporadic-E simulation enabled, CWirc makes the strength of
384 all weak signals it receives (approximately under S3) fluctuate as if
385 they came from a sporadic-E reflection.
386
387
388 2.4 - The Personal info tab
389
390 2.4.1 - The Callsign setting
391
392 If you are a ham, you can set your callsign for other users to see in
393 your morse messages, or when they query your information with the
394 /CTCP CWIRC command (see below).
395
396
397 2.4.2 - The Grid square setting
398
399 Set the grid square corresponding to your present physical location here
400 if you want to be able to use signal strength and sporadic-E simulation.
401 If you don't know your grid square location, you can find it on the
402 following webpage, with the grid map, or if you know your latitude and
403 longitude :
404
405 http://www4.plala.or.jp/nomrax/GL/index.html
406
407 CWirc accepts grid squares in the basic 4-character format ("AB12"), or
408 the more accurate 6-character ("AB12CD") format.
409
410
411 2.4.3 - The "send callsign with CW" button
412
413 If you select this, CWirc will send your callsign along with your CW
414 signal, and other CWirc users will be able to see it when they receive
415 your signal. If you choose to broadcast your callsign, it will be sent
416 in scrambled form in the IRC message, so only other CWirc users will be
417 able to see it.
418
419 This is useful if you want to keep your normal anonymous IRC nick for
420 casual IRC chatting, but you want to go by your ham callsign with other
421 CWirc users at the same time.
422
423
424 2.4.4 - The "send grid square with CW" button
425
426 If you select this, your grid square location will be sent along with
427 your CW signal, allowing remote CWirc users to use signal strength
428 simulation options with your signal. If you choose to broadcast your
429 grid square, it will be sent in scrambled form in the IRC message. If you
430 you want to stay vague about where you are, enter your grid square in
431 4-character format (they define an area that measures approximately
432 70 miles x 100 miles in the continental US).
433
434
435 2.4.5 - The CTCP settings
436
437 CWirc can reply to a custom CTCP query (CTCP CWIRC) to report what
438 version you are using, what channel you are currently on, what your
439 callsign is or what your grid square location is.
440
441 If you don't want to disclose any of these details, un-check the "reply
442 to CTCP CWIRC queries" setting. If you check it, it'll give anybody who
443 types "/CTCP <your nick> CWIRC" the version of your CWirc client.
444
445 Additionally, you can also check "send callsign in CTCP reply", "send
446 grid square in CTCP reply, or "send current channel in CTCP reply" to
447 give those details along with the CWirc version.
448
449
450 2.5 - The I/O configuration tab
451
452 This tab allows you to set the parameters for the CW input and output
453 devices, and the buffering policy. The settings in the I/O configuration
454 tab are only effective after your click on the "Change/Save" button. If a
455 parameter is erroneous, an error popup window will inform you of the reason.
456
457
458 2.5.1 - The CW input setting
459
460 To key morse code, you can use the mouse by clicking on the mouse keying
461 zone (see above), a real morse key connected to a serial port (see below)
462 or both. If you choose "real key" or "both", the "Serial device" setting
463 needs to be set.
464
465
466 2.5.2 - The CW output setting
467
468 To play morse code, CWirc can use a soundcard, an external sounder or CW
469 oscillator connected to a serial port (see below), or both. If you choose
470 "soundcard" or "both", the "Sound device" setting needs to be set. If you
471 choose "sounder", the "Serial device" setting needs to be set.
472
473 NOTE: if you use both a real morse key and a sounder, they will share the
474 same serial port.
475
476 NOTE: if you use a sounder, you shouldn't use signal strength simulation
477 as well. The reason is that weak signals, below a certain threshold,
478 will simply not be played on the sounder.
479
480 NOTE: the "sounder" option (external sounder as sole CW output) isn't
481 available under FreeBSD or NetBSD, as these OSes don't provide a
482 proper /dev/rtc implementation, therefore CWirc always needs the
483 soundcard to pace itself.
484
485
486 2.5.3 - The CW sound setting
487
488 If "CW output" is set to "soundcard" or "both", you can choose to play
489 incoming and outgoing morse code as regular beeps, or as sounder clicks.
490 Most "modern" hams should choose beeps here. Sounder clicks are really
491 a feature for those who are interested in historical landline telegraphy,
492 who want to experience the sound of yesteryear's telegraphy as heard in
493 railway telegraph stations, or want to try out the original American
494 morse code (which is different from the international morse code
495 everybody knows today).
496
497 Note that the sounder clicks played by CWirc come from an actual Vail
498 sounder, and the timings of the sounder's arm going up and down are
499 accurately reproduced.
500
501
502 2.5.4 - The Key debounce setting
503
504 When using a real morse key connected to a serial port, its contact(s)
505 will read at regular interval to determine its/their states. If you get
506 spurrious dits or dahs while keying, it's possible that your key
507 contact(s) "bounce" when they make or break the electrical contact.
508 Contact "bouncing" is a common electrical phenomenon that occurs with
509 nearly all electrical switches. To alleviate the problem, increase the
510 value of "Key debounce" until the problem disappears.
511
512 NOTE: the lower the "Key debounce" value, the better, especially if you're
513 a fast keyer. If you feel your key is sluggish and/or misses
514 elements when you key fast, try lowering the value.
515
516
517 2.5.5 - The Recv buffering setting
518
519 This tells CWirc how long (in milliseconds) it should pre-buffer
520 incoming morse from the IRC server. On IRC servers that are reasonably
521 responsive, 1000 ms (1 s) is usually enough. If you're connected to an
522 IRC server with a lot of lag, try increasing the buffering value. If
523 you're connected to a local IRC server, of if you receive morse from an
524 operator in a DCC CHAT connection (see below), you can lower the value.
525
526 The more you increase the buffering value, the less your CWirc client
527 will be subject to buffer underruns, but the more the receive latency will
528 increase.
529
530
531 2.5.6 - Sound device
532
533 If "CW output" is set to "soundcard" or "both", this tells CWirc which
534 sound device to use to access the soundcard. Usually it's "/dev/dsp" under
535 Linux, "/dev/dsp0.0" under FreeBSD, or "/dev/audio0" under NetBSD, if you
536 only have one soundcard.
537
538 NOTE: if you want to use the aRts daemon with CWirc, you can with
539 the artsdsp wrapper and some tinkering, at the expense of sound
540 latency:
541
542 - In the KDE sound system preferences, enable the sound system if
543 not already enabled of course, enable "Run with the highest
544 possible priority (realtime priority)" and set the sound buffer
545 slider to the lowest possible level.
546
547 - As root, rename the "cwirc_frontend" binary (usually installed in
548 /usr/bin or /usr/local/bin) to "cwirc_frontend.REAL"
549
550 - As root, edit a new shell script called "cwirc_frontend" where
551 the real frontend binary was, with the following lines in it:
552
553 #!/bin/sh
554 artsdsp cwirc_frontend.REAL $*
555
556 and make it executable by invoking
557
558 chmod +x cwirc_frontend
559
560 - Restart CWirc and ensure the sound device is set to "/dev/dsp".
561 The sound should then be redirected to the aRts sound daemon.
562
563
564 2.5.7 - Serial device
565
566 If "CW input" is set to "real key" or "both", or "CW output" is set to
567 "sounder" or "both", this tells CWirc which serial device the real morse
568 key and/or the sounder are connected to. Use /dev/ttyS0 for COM1,
569 /dev/ttyS1 for COM2 ... under Linux, or /dev/cuaa0 for COM1, /dev/cuaa1
570 for COM2 ... under FreeBSD, or /dev/tty00 for COM1, /dev/tty01 for
571 COM2 ... under NetBSD.
572
573
574 2.6 - Conducting QSOs in an IRC channel
575
576 When CWirc is configured to your liking, try connecting to an IRC server
577 and joining a channel bearing morse traffic. Don't forget to set the channel
578 to the same as used by other parties in the channel (typically 1000 is the
579 general CQ channel).
580
581 The morse you send will be emitted on the IRC channel as encoded lines
582 every 2 seconds. Similarly, your CWirc client will receive incoming morse
583 sent in encoded lines. Note that morse received on channels other than the
584 one you are currently ignored will be silently ignored.
585
586 IMPORTANT: CWirc uses a protocol that looks very much like high-speed
587 garbage to non-CWirc users. Please be considerate and do NOT use
588 CWirc on general IRC channels (i.e. not dedicated to morse
589 traffic) unless you know the chatters and you ask them first.
590
591
592 2.7 - Conducting QSOs outside of the IRC channel
593
594 It is possible that you want to discuss things outside of the IRC channel,
595 so not everybody who happens to be tuned to your CW channel can hear what
596 you say. It's possible to /QUERY the other person and send him/her morse in
597 private, as you would to send normal IRC private messages. You still need
598 to be on the same CW channel though.
599
600 You can also DCC CHAT with the other party : in that case, the connection
601 between the other party and you is direct, bypassing the IRC server, which
602 has the big advantage of reducing the lag between the 2 CWirc clients, and
603 ensuring you won't get kicked out of the IRC channel for flooding.
604
605
606 2.8 - IRC channel locking
607
608 Normally, CWirc receives and sends morse from whatever channel you have
609 currently in focus. If you just do morse, that's usually good enough.
610 However, it's possible that you might want to send/receive morse to/from one
611 IRC channel while doing something else in another. Typically, the situation
612 is when you're sitting on a channel waiting for a CQ and you want to chat
613 with friends on another IRC channel in the meantime.
614
615 You can instruct CWirc to not follow the channel currently in focus. To
616 that, put the IRC channel you want to use in morse in focus and issue the
617 "/CWLOCK" command : CWirc then tells you that it's locked on that IRC
618 channel. You're then free to do whatever you want on other channels and
619 CWirc will stay on the channel you locked it on. If you want to lock CWirc
620 onto another channel, simply put the new channel in focus and use the
621 "/CWLOCK" command again. If you want to revert to the default mode of
622 following the channel in focus, issue the "/CWUNLOCK" command.
623
624 Note that you can lock and unlock CWirc on private chat and DCC CHAT
625 windows as well.
626
627
628 2.9 - Notes on using simulation
629
630 If you use signal strength simulation, and especially if you add
631 sporadic-E simulation on top of it, it is entirely possible to not hear an
632 incoming signal despite the fact that CWirc reports receiving it, if it is
633 too weak (typically the remote sender is too far away physically) or if it
634 is too attenuated by the sporadic-E simulation.
635
636 Also, while it is possible, it's a bad idea to use signal strength or
637 sporadic-E simulation with a sounder : if the signal is too weak, the sound
638 of the sounder will simply be cut-off, because it's a device that is either
639 on or off.
640
641 Finally, while possible too, note that using sounder clicks with QRN,
642 signal strength or sporadic-E simulation makes no sense : sounders were
643 used for land-line telegraphy, and therefore never generated QRN or weak
644 signal.
645
646
647
6483 - Connecting a real morse key
649
650 Keying morse with a mouse is okay when nothing else is available, but it's
651 not ideal. If you have a real morse key, you can use it to key morse in CWirc
652 by connecting it to your computer with a simple serial cable :
653
654
655 3.1 - Using a straight key
656
657 Assuming your serial port uses a DB9 connector, the wiring is :
658
659 DB9 pin number Key
660
661 =====
662 6 (DSR line) --------------------+-------------|
663
664 4 (DTR line) --------------------+-------------O
665
666
667 Once the key is connected, configure CWirc by setting "CW input" to "real
668 key" or "both" and "Key" to "straight".
669
670
671 3.2 - Using an iambic key
672
673 Assuming your serial port uses a DB9 connector, the wiring is :
674
675 DB9 pin number Key
676
677 8 (CTS line) --------------------+--------O--===== Right paddle
678
679 4 (DTR line) --------------------+--------| Common
680
681 6 (DSR line) --------------------+--------O--===== Left paddle
682
683
684 Once the key is connected, configure CWirc by setting "CW input" to "real
685 key" or "both" and "Key" to "iambic", then configure "Iambic keyer" to your
686 liking.
687
688
689
6904 - Connecting an external sounder
691
692 A sounder, a CW oscillator, a lamp, or even the PTT of your radio rig can
693 be controlled by CWirc through the RTS line on a serial port. That line can
694 be made to change state following the received and sent morse code, in
695 conjunction with, or in lieu of the soundcard. This is useful for various
696 kinds of users :
697
698 - People whose soundcard can't be opened by more than one process at a time,
699 and who want to listen to something while doing CW at the same time
700
701 - People who want to experience the original land telegraphy sound (i.e. the
702 sounder), that wasn't beeps but clicking noises
703
704 - Hams who want to retransmit an internet CW QSO on the air
705
706 - Users with hearing problems who need a visual indication of dits and dahs
707
708 Of course, ready-made devices that can be driven by a RS232 RTS line aren't
709 usually available in retail stores, so you'll probably have to dust off your
710 soldering iron. The easiest is probably to make a simple RTS-controlled relay
711 box, with an optocoupler to protect your serial port, then use the relay to
712 inject power in a commercially available training CW oscillator, a buzzer, a
713 light bulb or a sounder coil.
714
715 Assuming your serial port uses a DB9 connector, the wiring to connect your
716 custom-made sounder (or whatever other device) is :
717
718 DB9 pin number
719
720 7 (RTS line) --------------------+-------- Sounder output
721
722 5 (GND line) --------------------+-------- Sounder ground
723
724
725 Once the key is connected, configure CWirc by setting "CW output" to
726 "sounder" or "both".
727
728 With a sounder device, if several operators send morse on the same CW
729 channel, it's not possible to discriminate between them by the received
730 tones, since the only information available with a single data line is the
731 presence or absence of signal.
732
733 NOTE: if you set "CW output" to "sounder" (available under Linux only), CWirc
734 will not be able to use the soundcard to pace itself. As a result, it
735 will try to use your computer's real-time clock instead, through the
736 /dev/rtc interface. There are however several things you need to do to
737 allow a user program like CWirc to use /dev/rtc :
738
739 - Enable "Enhanced Real Time Clock Support" in the Linux kernel, either
740 as a module or compiled in
741
742 - Set permissions to open the /dev/rtc device file read-only as a normal
743 user
744
745 - Allow CWirc to ask /dev/rtc to generate 1024 interrupts per second by
746 typing the following command in a console, as root :
747
748 echo 1024 > /proc/sys/dev/rtc/max-user-freq
749
750 (The easiest it to put that line in a bootup script, so it's always
751 set up correctly each time you restart the machine.)
752
753 If you use the soundcard output as well as the sounder, there is no
754 need to do any of the above, as CWirc will automatically use the
755 soundcard to synchronize itself whenever possible.
756
757
758
7595 - CWirc extensions
760
761 As of version 1.7.0, CWirc supports external extension programs. A simple
762 interface allows a program specially designed or modified to work with CWirc
763 to receive audio synchronously as you hear it, and key as you'd key.
764
765 If you have extension programs installed, an extra tab will appear in CWirc
766 so that you can start it. Note that only one extension can be running at
767 any given time.
768
769
770
7716 - Note on CWirc and CWCom interfacings
772
773 The interfacing of external devices to a serial port used by CWirc is
774 strictly identical to the one used by CWCom for Windows, by MRX Software
775 (http://www.mrx.com.au/d_cwcom.htm). Consequently, if you already use CWCom
776 in Windows with a key and/or a sounder connected to a serial port, you won't
777 need to modify anything to your hardware setup to use CWirc in Unix.
778
779
780
7817 - Solving the scratchy sound problem
782
783 On some machines with low-end or integrated sound devices (typically SiS,
784 i8x0 or VIA sound devices), CWirc may start to sound very nasty when the
785 system gets loaded, even only a little. If you experience sound cuts and
786 "scratchy" noises, try to set the CWirc frontend executable (usually
787 /usr/bin/cwirc_frontend or /usr/local/bin/cwirc_frontend) suid root, by
788 issuing the following commands as root:
789
790 chown root <CWirc frontend install path>/cwirc_frontend
791 chmod u+s <CWirc frontend install path>/cwirc_frontend
792
793 then restarting CWirc. This should clear, or at least improve the bad sound
794 problem.
795
796 When CWirc is run suid root, it asks the system to give its I/O routine a
797 better execution priority than most processes in the system, thereby reducing
798 or suppressing sound buffer underruns that are the cause of "scratchy"
799 noises. CWirc can only instruct the system to give it this better treatment
800 if it has root permissions, hence the need to set the CWirc frontend
801 executable file suid root.
802
803 CWirc is normally installed as a regular, non-suid binary by default,
804 because although the program drops its root privileges as soon as it has
805 changed its own system priority, almost immediately at the beginning of the
806 program, and therefore should be quite safe, suid programs are usually viewed
807 as a security risk, and most users will be able to run CWirc fine without the
808 better priority anyway. This is the reason why it is left to you to set the
809 suid attribute on the CWirc frontend executable manually if you need it.
810
811 If the problem seems to persist, you may want to check that CWirc
812 effectively did manage to reprioritize its I/O routine with the root
813 privilege. To do this, invoke:
814
815 ps x | grep cwirc_frontend
816
817 while CWirc is running, and check that one of the two "cwirc_frontend"
818 processes has "<" marked next to it, meaning that it's a high-priority
819 task.
820
821
822
8238 - FAQ
824
825 Q: When setting "CW output" to "sounder", when I try to enable the plugin, it
826 says "Error : cannot open /dev/rtc." but I'm sure my kernel has real-time
827 clock support, rtc support is setup properly and I have proper permissions
828 to access /dev/rtc.
829
830 A: Programs that use /dev/rtc, like VMware or mplayer, have exclusive control
831 over the real-time clock and need to be stopped first before using CWirc.
832 Try to do "lsof /dev/rtc" to check what process is currently using
833 /dev/rtc.
834
835 Q: When setting "CW output" to "sounder", when I try to enable the plugin, it
836 says "cannot set /dev/rtc to generate 1024 interrupts per second."
837
838 A: By default, the Linux kernel won't let non-root programs instruct the
839 real-time clock to generate more than 64 interrupts per second. CWirc
840 needs 1024, so it's necessary that you tell the kernel to lift that safety
841 restriction. For details, see the section above on using a sounder. If you
842 can't change the kernel setting, because you don't have root access to the
843 box for example, you'll have to use the soundcard as well.
844
845 Q: When I try to enable CWirc, X-Chat tells me "CWirc : error : cannot
846 execute "cwirc_frontend" ".
847
848 A: cwirc_frontend is the executable for the CWirc frontend. It needs to be
849 in your search PATH for the plugin to be able to start it.
850
851 Q: When I key, after a short while, the IRC server kicks me out
852
853 A: A lot of data is transmitted to the IRC server as fast as possible when you
854 key. Most IRC servers let you get away with one line sent every 2 seconds,
855 but some servers may interpret that as flooding and kick you out. Also, if
856 you're a fast keyer, the lines transmitted to the IRC server can get quite
857 long and trip the server's flood detection too. Try using a more
858 permissive server, keying less fast, or doing private QSOs in DCC CHAT.
859
860 Q: The plugin starts fine but nothing happens when I key with my real key
861
862 A: Make sure the serial device file you've set is the one you connected your
863 key to. The plugin can't detect your morse key.
864
865 Q: When someone transmits, the CW flow is chopped every now and then
866
867 A: This is most likely due to lag between the person's machine and the IRC
868 server, or between your machine and the IRC server. Try to increase the
869 receive buffering, or try to connect to a more responsive, less busy
870 server, or initiate a DCC CHAT with the other party to communicate
871 directly without the IRC server.
872
873 Q: I've increased the buffering and the sounds still cuts, or the sound cuts
874 when I run many things on my system
875
876 A: See the "Solving the scratchy sound problem" section above
877
878 Q: A friend has CWirc installed, I can see some coded frames coming from him
879 and he can see some of mine, and none of us can hear anything, or only
880 partially.
881
882 A: The frame format changed at version 0.3.0, at version 0.8.0 and again at
883 version 1.7.0. Frames generated by previous versions of CWirc will be
884 dismissed as normal text. Please upgrade to the latest version.
885
886 Q: I've joined my favorite channel on my favorite IRC server, I've sent
887 CQ to see if I could get a contact with other CWirc users, and I've been
888 kicked off the channel / banned / insulted as a result. What's going on ?
889
890 A: When the CWirc plugin is loaded, it filters out incoming and outgoing CW
891 frames and simply displays "sending" or "receiving" (or nothing at all) to
892 spare you of having to watch encoded garbage. However, non-CWirc users
893 will see the garbage and will quickly interpret it as a very unfunny trick
894 from you, and classify you as a nuisance. Please ask if there are any
895 CWirc users on the channel in plain text first, then either /QUERY other
896 users in private, DCC CHAT to them, or create another IRC channel, so
897 regular IRC users aren't bothered.
898
899 Q: Why isn't the "sounder" option available under FreeBSD or NetBSD, in the
900 "CW output" setting ?
901
902 A: Normally, CWirc uses the soundcard to pace itself, i.e. it takes advantage
903 of the fact that it takes a very precise amount of time to play a chunk of
904 audio. With the "sounder" option, the soundcard isn't used at all.
905 Therefore, CWirc has to use another precise timing source. Under Linux,
906 it's possible to use the /dev/rtc interface for this. Under FreeBSD or
907 NetBSD, there is no such interface natively, and the rtc kernel module
908 available as Linux emulation isn't complete and lacks some of the
909 functions used by CWirc. As a result, the "sounder" option is simply
910 disabled under these OSes.
911
912 Q: What is this DOT thing in the decoder language selection ?
913
914 A: DOT code isn't a language but an old telegraph code directly derived from
915 a flag code. Most notably, it was used by the U.S. military during the
916 American Civil War. DOT code is not morse code, and isn't in use anymore
917 apart during living history events and reenactments. If you're interested
918 in historical landline telegraphy and would like to setup a station to
919 simulate a telegraph station of that period, you can use the sounder clicks
920 simulator and switch the decoder to DOT code to help you copy this old
921 code.
922
923 Q: I key morse, but apparently nobody hears me
924
925 A: Check that you're not in sidetone mode. In sidetone mode, CWirc works
926 exactly like in normal mode, only it never transmits anything
927
928
929
9309 - Contributions
931
932 If you feel like improving the plugin, please send me your changes, I'll
933 glady incorporate them. Also, if you run have an IRC server and would like to
934 dedicate a channel to morse users, please let me know so I can post the
935 address of your server for others to use. I personally use irc.freenode.net,
936 which is a nice permissive IRC server.
937
938
939
94010 - Credits
941
942 Many thanks to the following people :
943
944 - Patrick Maille <patrick@arcturusnetworks.com> for doing a lot of testing on
945 different Linux flavors, and for his suggestions.
946
947 - Juha Nygard <juha.nygard1@netikka.fi> for providing FreeBSD specific help
948 and a shell account on his FreeBSD box.
949
950 - Bill Meahan <wmeahan@wa8tzg.org> for providing NetBSD patches, testing and
951 debugging help.
952
953 - Ted Wagner <trwagner1@yahoo.com> & David T. Bock <bock@marketcommander.com>
954 for their help to add DOT code in the automatic decoder.
955
956 - Mac WA4CAW, for his time, help, and documentation, to figure out the iambic
957 keyer timings.
958
959 - Ted WA0EIR, for his help and obscure-bug-finding abilities.
960
961 - Joop Stakenborg PG4I <pa3aba@debian.org> for maintaining the Debian package
962 and for the bugfixes.
963
964
965
96611 - Legalese
967
968 This software is released under the terms of the General Public License. See
969 the "COPYING" file for details.
970
971 Oh, and yes, I forgot :
972
973 DISCLAIMER :
974
975 I am not responsible for any damage caused by this software, whether it's on
976 your computer, your morse key, or if it wipes out your hard-drive, or if it
977 sets off a nuclear bomb, etc ...
978