Menu
▾
▴
Tree [5af118] master / History
Read Me
This is README file for unixcw project version 3.6.1.
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
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
program that uses the library looks like this (compile it with
"gcc -lcw example.c"):
#include <libcw.h>
int main(void)
{
/* Library initialization */
cw_generator_new(CW_AUDIO_SOUNDCARD, NULL);
cw_generator_start();
/* Start the string sending in the background. */
cw_send_string("Hello, world");
/* Wait for the string send to complete. */
cw_wait_for_tone_queue();
/* Library cleanup */
cw_generator_stop();
cw_generator_delete();
return 0;
}
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.
As well as the handful of applications included in unixcw, the
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 sound 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.
In addition to libcw, the package comes with four basic applications:
- 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:
cwgen | cw
- 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.
- 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:
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
3.4.2 6.4.1 2015-06-17
3.5.0 6.5.1 2015-10-06
3.5.1 6.6.1 2017-02-12
3.6.0 7.0.0 2021-01-17
3.6.1 8:0:0 2023-11-18
Primary development platform for unixcw is Debian GNU/Linux. An effort has
been made to compile and test this version of unixcw package (or at least
parts of this package) on following platforms:
Debian GNU/Linux 12, x86_64, gcc (Debian 12.2.0-14) 12.2.0
Alpine Linux Alpine 3.18.4, x86_64, gcc (Alpine 12.2.1_git20220924-r10) 12.2.1 20220924
FreeBSD 13.2-RELEASE-p4, x86_64, gcc (FreeBSD Ports Collection) 12.2.0
unixcw is distributed under the terms of GNU GPL license, version 2 or
later. See COPYING for details.
unixcw was developed by Simon Baldwin, G0FRD <simon_baldwin@yahoo.com>.
unixcw is developed by Kamil Ignacak <acerion@wp.pl>.
Website: unixcw.sf.net
Comments, questions, bug reports:
- create ticket: http://sourceforge.net/p/unixcw/tickets/, or
- write directly to acerion@wp.pl
I reserve a right to a month of delay to reply.
unixcw is written in C and C++.
unixcw can be built and installed with standard set of commands:
./configure && make && make install
Depending on platform and software/files installed on build machine,
build system will configure and compile following features:
- support for console buzzer in libcw;
- support for OSS sound system in libcw;
- support for ALSA sound system in libcw;
- support for PulseAudio sound system in libcw;
If a support for a feature from this list is available in libcw, it
will be available in rest of applications from unixcw package.
Moreover, depending on platform and software/files installed on build
machine, the build system will configure and compile following
features:
- cwcp, if ncurses development files are available;
- xcwcp, if QT5 development files are available (xcwcp is an
application written in C++);
libcw library, and cw and cwgen applications are built
unconditionally.
You can explicitly disable some libcw and unixcw features by passing
flags to configure script. See output of "./configure --help" for
details.
Check your platform-dependent documentation on what packages/files are
needed for each of these features.
Build-time requirements for unixcw:
- standard build environment to build software from source package
with "./configure && make && make install";
- GNU make may be necessary on some platforms (I've had a problem
with FreeBSD's make on FreeBSD 9.3; make on FreeBSD 10.0 worked
fine). If, when running "make", you see an error message like
this:
*** Parse error in unixcw-3.4.0/src: Need an operator in '../Makefile.inc' (Makefile:640)
*** Error 1 in unixcw-3.4.0 (Makefile:416 'all-recursive')
then install gmake package, and try running "gmake & gmake install"
instead of "make & make install".
- pkg-config to get configuration flags for QT5 application (xcwcp);
you can override pkg-config settings for QT5 using environment
variables, see output of "./configure --help" for details.
- sound system library development files for including support for
OSS, ALSA and PulseAudio sound sinks in libcw;
- header file providing KIOCSOUND symbol for including support for
console buzzer in libcw.
- ncurses development files for building cwcp;
- QT5 development files for building xcwcp;
- gawk for generating man page for libcw;
Some run-time requirements for unixcw:
- XDG_RUNTIME_DIR env variable must be set when PulseAudio sound system is
used. When using execve() to start a program that uses libcw, be sure to
set this env variable in program's env. Otherwise the program may be unable
to use PulseAudio sound system.
Quality Assurance
-----------------
- Compile-time flags
- -std=c11
- -Wall -Wextra -pedantic
- a long list of additional warning flags for compiler, enabled during
development cycles (see configure.ac)
- -D_FORTIFY_SOURCE=2
Only a handful of enabled compiler warnings aren't fixed yet.
- Static analysis of code
- clang-tidy is being run on entire C/C++ code in the package. Scope of
checks is specified by .clang-tidy config file found in repo's root
dir.
- Unit tests
- Functional tests
