README 4.86 KB
Newer Older
1
This is README file for unixcw project version 3.5.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

unixcw is a project providing libcw library and a set of programs
using the library: cw, cwgen, cwcp and xcwcp. The programs are
intended for people who want to learn receiving and sending Morse
code. unixcw is developed and tested primarily on GNU/Linux system.





For general description of changes see HISTORY file.
For detailed description of changes see NEWS file.
For details on building unixcw from sources see INSTALL file.
For acknowledgements see THANKS file.
For full text of software license see COPYING file.





The heart of the unixcw package is libcw library.  It offers the
following basic CW services to a caller program:

 - Morse code character translation tables, and lookup functions
 - Morse code low-level timing calculations
 - A 'sidetone' generation and queueing system, using either the system sound
   card or the console speaker
 - Optional keying control for an external device, say a transmitter, or an
   oscillator
 - CW character and string send routines, tied in with the character lookup
 - CW receive routines, also tied in to the character lookup
 - Adaptive speed tracking of received CW
 - An iambic keyer, with both Curtis 8044 types A and B timing
 - Straight key emulation


38

39 40 41 42 43


The library uses signals and threads to create a background task in
which it performs the majority of its work, leaving the main program
free to handle other tasks.  For example, the simplest CW sending
44
program that uses the library looks like this (compile it with
45
"gcc -lcw example.c"):
46

47 48 49 50 51 52

#include <libcw.h>

int main ()
{
        /* Library initialization */
53
        cw_generator_new(CW_AUDIO_SOUNDCARD, NULL);
54 55 56
        cw_generator_start();

        /* Start the string sending in the background. */
57
        cw_send_string("Hello, world");
58 59 60 61 62 63 64 65

        /* Wait for the string send to complete. */
        cw_wait_for_tone_queue();

        /* Library cleanup */
        cw_generator_stop();
        cw_generator_delete();

66
        return 0;
67 68
}

69

70 71 72
Instead of the cw_wait_for_tone_queue() call, this program could
instead handle any other work it has to do, asynchronously from the CW
library's sending.
73

74
As well as the handful of applications included in unixcw, the
75 76 77 78 79 80 81 82 83 84 85 86
following types of programs might also use libcw as their core:

 - a fully graphical CW send and receive station
 - a 'CWbiff' that announces incoming email sender in CW
 - an offline CW reader program, capable of decoding CW from MP3 or
   other audio file formats
 - a simple Iambic keyer for an external transmitter, using the mouse
   buttons as the keyer paddles
 - a more comprehensive CW tutor program
 - an automated Morse Code testing application

libcw is written in C for easy portability and use.
87 88 89 90 91





92
In addition to libcw, the package comes with four basic applications:
93

94 95 96 97 98 99
 - cw: a CW sending 'engine' that reads characters from stdin, sounds
   them on either the sound card or the console speaker, and echoes
   them to stdout.

 - cwgen: a simple random character generator that can be used as a
   feed for cw.  For example:
100 101 102

               cwgen | cw

103 104 105
 - cwcp: a curses-based program that generates groups of characters
   from selected sets, words, and CW abbreviations randomly, and
   sounds them using libcw.  It owes much to CP222.EXE, by VU2ZAP.
106

107 108 109 110 111 112 113 114 115 116 117 118
 - xcwcp: a CW tutor program for X Window environment.  It offers the
   same random and keyboard sending as 'cwcp', and in addition can
   read CW that sent to it using the keyboard or mouse as a keyer,
   making it useful for sending as well as receiving practice.





Relationship between version of unixcw package and version of libcw is
following:

119 120 121 122 123 124 125 126 127 128 129
    unixcw      libcw      release date
    3.0         3.0.0      2011.12.13
    3.0.1       3.0.1      2012.01.08
    3.0.2       3.0.1      2012.06.18
    3.1.0       4.0.0      2012.06.30
    3.1.1       4.1.1      2012.07.04
    3.2.0       5.0.0      2013.01.11
    3.3.0       6.0.1      2013.12.10
    3.3.1       6.1.1      2014-04-23
    3.4.0       6.2.1      2014-11-11
    3.4.1       6.3.1      2015-01-02
130
    3.4.2       6.4.1      2015-06-17
131 132
    3.5.0       6.5.1      2015-10-06
    3.5.1       6.6.1      2017-02-12
133

134 135 136 137




138
Primary development platform for unixcw is Debian GNU/Linux. An effort
139 140
has been made to compile and test at least parts of some versions of
unixcw package on following platforms:
141 142 143
 - FreeBSD 9.3
 - FreeBSD 10.0
 - OpenBSD 5.5
144
 - Alpine Linux 3.1
145 146
See INSTALL file for more information about compilation on different
OSes.
147 148 149 150 151





152 153 154 155 156 157
unixcw is distributed under the terms of GNU GPL license, version 2 or
later.  See COPYING for details.




158

159 160
unixcw was developed by Simon Baldwin, G0FRD <simon_baldwin@yahoo.com>.
unixcw is developed by Kamil Ignacak <acerion@wp.pl>.
161

162 163 164



165

166
Website: unixcw.sf.net
167

168 169 170 171




172 173 174
Comments, questions, bug reports:
 - create ticket: http://sourceforge.net/p/unixcw/tickets/, or
 - write directly to acerion@wp.pl
175
I reserve a right to a month of delay to reply.