1CWLIB(3) Library Functions Manual CWLIB(3)
2
6 cwlib - general purpose Morse code functions library
7
9 #include <cwlib.h>
10 int cw_version (void)
12 void cw_license (void)
14 void cw_set_debug_flags (unsigned int new_value)
16 unsigned int cw_get_debug_flags (void)
18 int cw_get_character_count (void)
20 void cw_list_characters (char *list)
22 int cw_get_maximum_representation_length (void)
24 int cw_lookup_character (char c, char *representation)
26 int cw_check_representation (const char *representation)
28 int cw_lookup_representation (const char *representation, char *c)
30 int cw_get_procedural_character_count (void)
32 void cw_list_procedural_characters (char *list)
34 int cw_get_maximum_procedural_expansion_length (void)
36 int cw_lookup_procedural_character (char c, char *representation,
38 int *is_usually_expanded)
39 int cw_get_maximum_phonetic_length (void)
41 int cw_lookup_phonetic (char c, char *phonetic)
43 void cw_get_speed_limits (int *min_speed, int *max_speed)
45 void cw_get_frequency_limits (int *min_frequency, int *max_frequency)
47 void cw_get_volume_limits (int *min_volume, int *max_volume)
49 void cw_get_gap_limits (int *min_gap, int *max_gap)
51 void cw_get_tolerance_limits (int *min_tolerance, int *max_tolerance)
53 void cw_get_weighting_limits (int *min_weighting, int *max_weighting)
55 void cw_reset_send_receive_parameters (void)
57 int cw_set_send_speed (int new_value)
59 int cw_set_receive_speed (int new_value)
61 int cw_set_frequency (int new_value)
63 int cw_set_volume (int new_value)
65 int cw_set_gap (int new_value)
67 int cw_set_tolerance (int new_value)
69 int cw_set_weighting (int new_value)
71 int cw_get_send_speed (void)
73 int cw_get_receive_speed (void)
75 int cw_get_frequency (void)
77 int cw_get_volume (void)
79 int cw_get_gap (void)
81 int cw_get_tolerance (void)
83 int cw_get_weighting (void)
85 void cw_get_send_parameters (int *dot_usecs, int *dash_usecs,
87 int *end_of_element_usecs,
88 int *end_of_character_usecs, int *end_of_word_usecs,
89 int *additional_usecs, int *adjustment_usecs)
90 void cw_get_receive_parameters (int *dot_usecs, int *dash_usecs,
92 int *dot_min_usecs, int *dot_max_usecs,
93 int *dash_min_usecs, int *dash_max_usecs,
94 int *end_of_element_min_usecs,
95 int *end_of_element_max_usecs,
96 int *end_of_element_ideal_usecs,
97 int *end_of_character_min_usecs,
98 int *end_of_character_max_usecs,
99 int *end_of_character_ideal_usecs,
100 int *adaptive_threshold)
101 int cw_set_noise_spike_threshold (int threshold)
103 int cw_get_noise_spike_threshold (void)
105 void cw_block_callback (int is_block)
107 void cw_set_console_file (const char *new_value)
109 const char * cw_get_console_file (void)
111 void cw_set_soundcard_file (const char *new_value)
113 const char * cw_get_soundcard_file (void)
115 void cw_set_soundmixer_file (const char *new_value)
117 const char * cw_get_soundmixer_file (void)
119 int cw_is_soundcard_possible (void)
121 int cw_is_console_possible (void)
123 void cw_set_console_sound (int sound_state)
125 int cw_get_console_sound (void)
127 void cw_set_soundcard_sound (int sound_state)
129 int cw_get_soundcard_sound (void)
131 void cw_complete_reset (void)
133 int cw_register_signal_handler (int signal_number,
135 void (*callback_func) (int))
136 int cw_unregister_signal_handler (int signal_number)
138 void cw_register_keying_callback (void (*callback_func) (void*, int),
140 void *callback_arg)
141 int cw_register_tone_queue_low_callback (void (*callback_func) (void*),
143 void *callback_arg, int level)
144 int cw_is_tone_busy (void)
146 int cw_wait_for_tone (void)
148 int cw_wait_for_tone_queue (void)
150 int cw_wait_for_tone_queue_critical (int level)
152 int cw_is_tone_queue_full (void)
154 int cw_get_tone_queue_capacity (void)
156 int cw_get_tone_queue_length (void)
158 void cw_flush_tone_queue (void)
160 int cw_queue_tone (int usecs, int frequency)
162 void cw_reset_tone_queue (void)
164 int cw_send_dot (void)
166 int cw_send_dash (void)
168 int cw_send_character_space (void)
170 int cw_send_word_space (void)
172 int cw_send_representation (const char *representation)
174 int cw_send_representation_partial (const char *representation)
176 int cw_check_character (char c)
178 int cw_send_character (char c)
180 int cw_send_character_partial (char c)
182 int cw_check_string (const char *string)
184 int cw_send_string (const char *string)
186 void cw_get_receive_statistics (double *dot_sd, double *dash_sd,
188 double *element_end_sd, double *character_end_sd)
189 void cw_reset_receive_statistics (void)
191 void cw_enable_adaptive_receive (void)
193 void cw_disable_adaptive_receive (void)
195 int cw_get_adaptive_receive_state (void)
197 int cw_start_receive_tone (const struct timeval *timestamp)
199 int cw_end_receive_tone (const struct timeval *timestamp)
201 int cw_receive_buffer_dot (const struct timeval *timestamp)
203 int cw_receive_buffer_dash (const struct timeval *timestamp)
205 int cw_receive_representation (const struct timeval *timestamp,
207 char *representation, int *is_end_of_word,
208 int *is_error)
209 int cw_receive_character (const struct timeval *timestamp,
211 char *c, int *is_end_of_word, int *is_error)
212 void cw_clear_receive_buffer (void)
214 int cw_get_receive_buffer_capacity (void)
216 int cw_get_receive_buffer_length (void)
218 void cw_reset_receive (void)
220 void cw_enable_iambic_curtis_mode_b (void)
222 void cw_disable_iambic_curtis_mode_b (void)
224 int cw_get_iambic_curtis_mode_b_state (void)
226 int cw_notify_keyer_paddle_event (int dot_paddle_state,
228 int dash_paddle_state)
229 int cw_notify_keyer_dot_paddle_event (int dot_paddle_state)
231 int cw_notify_keyer_dash_paddle_event (int dash_paddle_state)
233 void cw_get_keyer_paddles (int *dot_paddle_state, int *dash_paddle_state)
235 void cw_get_keyer_paddle_latches (int *dot_paddle_latch_state,
237 int *dash_paddle_latch_state)
238 int cw_is_keyer_busy (void)
240 int cw_wait_for_keyer_element (void)
242 int cw_wait_for_keyer (void)
244 void cw_reset_keyer (void)
246 int cw_notify_straight_key_event (int key_state)
248 int cw_get_straight_key_state (void)
250 int cw_is_straight_key_busy (void)
252 void cw_reset_straight_key (void)
254 DESCRIPTION
257 cwlib is a general purpose CW (Morse code) functions library. It con‐
258 tains routines for converting characters into Morse code representa‐
259 tions and back again, for sending Morse code characters, and for
260 receiving characters. It also contains routines to emulate an Iambic
261 Morse keyer, and a straight key.
262 The library can be included in any program that wishes to make use of
264 these features. It forms the heart of three Morse code tutor applica‐
265 tions that accompany the package in which it is distributed.
266 See the cw(7) man page for information on Morse code timings, and the
268 dot and dash representations for the various Morse characters.
269 TONE QUEUE
271 cwlib contains an inbuilt tone queue. The queue is emptied by back‐
272 ground processing, using SIGALRM calls and itimers, so a caller program
273 can continue with other tasks while the library sends tones and keys
274 any external device.
275 As well as being used by the library functions that sound Morse code
277 characters and provide a keyer sidetone, the primitive tone queue func‐
278 tions are publicly available to caller programs.
279 CONTROLLING AN EXTERNAL DEVICE
281 cwlib may be passed the address of a function that controls external
282 keying. This function is called each time the library changes the key‐
283 ing state, either as a result of sending a Morse character or represen‐
284 tation, or as a result of an iambic keyer or straight key state change.
285 The argument passed is a single integer, TRUE for key-down, and FALSE
286 for key-up.
287 cwlib calls the external keying function only when the keying state
289 changes. A call is likely each time a tone is taken off the tone
290 queue.
291 SENDING CW CHARACTERS AND STRINGS
293 cwlib offers several functions that send individual characters and
294 character strings as Morse code. It also offers functions that allow
295 specialized 'representations' to be sent. A 'representation' is an
296 ASCII string that consists of only the characters '.' and '-'.
297 Characters and strings are converted into representations, and then the
299 correct tones for the dots and dashes in these representations are
300 queued on the tone queue, for action by the background queue emptying
301 process.
302 RECEIVING CW CHARACTERS AND REPRESENTATIONS
304 cwlib contains functions to allow it to receive Morse code. To
305 receive, the library must be told when a tone start is detected, and
306 when a tone end is detected. It then determines whether the tone was a
307 dot or a dash depending on the timing difference between the two.
308 After the required silence gap has passed, the library may be queried
309 to see what the received representation or character was.
310 Errors in receiving may be detected by means of the flags passed back
312 on receive character functions.
313 IAMBIC KEYER
315 cwlib offers functions to simulate an Iambic Morse keyer. The caller
316 program needs to tell the library of paddle state changes. Iambic
317 keyer functions are mutually exclusive with character send and straight
318 key functions.
319 STRAIGHT KEY
321 cwlib offers simple functions to allow effective pass-through of
322 straight key information. The caller program needs to tell the library
323 of key state changes. Straight key functions are mutually exclusive
324 with character send and iambic keyer functions.
325 FUNCTIONS
327 The following list describes the functions available to a cwlib caller:
328 int cw_version (void)
331 Returns the version number of the library. Version numbers are
333 returned as an int, composed of major_version << 16 | minor_version.
334 void cw_license (void)
337 Prints a short library licensing message to stdout.
339 void cw_set_debug_flags (unsigned int new_value)
342 Sets a value for the library debug flags. Debug output is generally
344 strings printed on stderr. There is no validation of flags.
345 unsigned int cw_get_debug_flags (void)
348 Retrieves library debug flags. If no flags are set, then on first
350 call, it will check the environment variable CWLIB_DEBUG, and if it is
351 available, will set debug flags to its value. The provides a way for a
352 program to set the debug flags without needing to make any source code
353 changes.
354 int cw_get_character_count (void)
357 Returns the number of characters represented in the character lookup
359 table.
360 void cw_list_characters (char *list)
363 Returns into list a string containing all of the Morse characters rep‐
365 resented in the table. The length of list must be at least one greater
366 than the number of characters represented in the character lookup ta‐
367 ble, returned by cw_get_character_count.
368 int cw_get_maximum_representation_length (void)
371 Returns the string length of the longest representation in the charac‐
373 ter lookup table.
374 int cw_lookup_character (char c, char *representation)
377 Returns the string 'shape' of a given Morse code character. The rou‐
379 tine returns TRUE on success, and fills in the string pointer passed
380 in. On error, it returns FALSE and sets errno to ENOENT, indicating
381 that the character could not be found. The length of representation
382 must be at least one greater than the longest representation held in
383 the character lookup table, returned by cw_get_maximum_representa‐
384 tion_length.
385 int cw_check_representation (const char *representation)
388 Checks that the given string is a valid Morse representation. A valid
390 string is one composed of only '.' and '-' characters. On success, the
391 routine returns TRUE. On error, it returns FALSE, with errno set to
392 EINVAL.
393 int cw_lookup_representation (const char *representation, char *c)
396 Returns the character for a given Morse representation. On success,
398 the routine returns TRUE, and fills in char *c. On error, it returns
399 FALSE, and sets errno to EINVAL if any character of the representation
400 is invalid, or ENOENT to indicate that the representation could not be
401 found.
402 int cw_get_procedural_character_count (void)
405 Returns the number of characters represented in the procedural signal
407 expansion lookup table.
408 void cw_list_procedural_characters (char *list)
411 Returns into list a string containing all of the Morse characters for
413 which procedural expansion are available. The length of list must be
414 at least one greater than the number of characters represented in the
415 procedural signal expansion lookup table, returned by cw_get_procedur‐
416 al_character_count.
417 int cw_get_maximum_procedural_expansion_length (void)
420 Returns the string length of the longest expansion in the procedural
422 signal expansion table.
423 int cw_lookup_procedural_character (char c, char *representation,
426 int *is_usually_expanded)
427 Returns the string expansion of a given Morse code procedural signal
429 character. The routine returns TRUE on success, filling in the string
430 pointer passed in and setting is_usuall_expanded to TRUE as a display
431 hint for the caller. On error, it returns FALSE and sets errno to
432 ENOENT, indicating that the procedural signal character could not be
433 found. The length of representation must be at least one greater than
434 the longest representation held in the procedural signal character
435 lookup table, returned by cw_get_maximum_procedural_expansion_length.
436 int cw_get_maximum_phonetic_length (void)
439 Returns the string length of the longest phonetic in the phonetics
441 lookup table.
442 int cw_lookup_phonetic (char c, char *phonetic)
445 Returns the phonetic of a given character. The routine returns TRUE on
447 success, and fills in the string pointer passed in. On error, it
448 returns FALSE and sets errno to ENOENT, indicating that the character
449 could not be found. The length of phonetic must be at least one
450 greater than the longest phonetic held in the phonetic lookup table,
451 returned by cw_get_maximum_phonetic_length.
452 void cw_get_speed_limits (int *min_speed, int *max_speed)
455 void cw_get_frequency_limits (int *min_frequency, int *max_frequency)
458 void cw_get_volume_limits (int *min_volume, int *max_volume)
461 void cw_get_gap_limits (int *min_gap, int *max_gap)
464 void cw_get_tolerance_limits (int *min_tolerance, int *max_tolerance)
467 void cw_get_weighting_limits (int *min_weighting, int *max_weighting)
470 Return the limits on the speed, frequency, volume, gap, tolerance, and
472 weighting parameters. Normal values are speed 4-60 WPM, frequency
473 0-10,000 Hz, volume 0-70 %, gap 0-20 dots, tolerance 0-90 %, and
474 weighting 20-80 %.
475 void cw_reset_send_receive_parameters (void)
478 Reset the library speed, frequency, volume, gap, tolerance, weighting,
480 adaptive receive, and noise spike threshold to their initial default
481 values: send/receive speed 12 WPM, volume 70 %, frequency 800 Hz, gap 0
482 dots, tolerance 50 %, and weighting 50 %.
483 int cw_set_send_speed (int new_value)
486 int cw_set_receive_speed (int new_value)
489 int cw_set_frequency (int new_value)
492 int cw_set_volume (int new_value)
495 int cw_set_gap (int new_value)
498 int cw_set_tolerance (int new_value)
501 int cw_set_weighting (int new_value)
504 int cw_get_send_speed (void)
507 int cw_get_receive_speed (void)
510 int cw_get_frequency (void)
513 int cw_get_volume (void)
516 int cw_get_gap (void)
519 int cw_get_tolerance (void)
522 int cw_get_weighting (void)
525 Get and set routines for all the Morse code parameters available to
527 control the library. Set routines return TRUE on success, or FALSE on
528 failure, with errno set to indicate the problem, usually EINVAL, except
529 for cw_set_receive_speed, which returns EINVAL if the new value is
530 invalid, or EPERM if the receive mode is currently set for adaptive
531 receive speed tracking. Get routines simply return the current value.
532 The default values of the parameters where none are explicitly set are
534 send/receive speed 12 WPM, volume 70 %, frequency 800 Hz, gap 0 dots,
535 tolerance 50 %, and weighting 50 %. Note that volume settings are not
536 fully possible for the console speaker; in this case, volume settings
537 greater than zero indicate console speaker sound is on, and setting
538 volume to zero will turn off console speaker sound.
539 void cw_get_send_parameters (int *dot_usecs, int *dash_usecs,
542 int *end_of_element_usecs,
543 int *end_of_character_usecs, int *end_of_word_usecs,
544 int *additional_usecs, int *adjustment_usecs)
545 void cw_get_receive_parameters (int *dot_usecs, int *dash_usecs,
548 int *dot_min_usecs, int *dot_max_usecs,
549 int *dash_min_usecs, int *dash_max_usecs,
550 int *end_of_element_min_usecs,
551 int *end_of_element_max_usecs,
552 int *end_of_element_ideal_usecs,
553 int *end_of_character_min_usecs,
554 int *end_of_character_max_usecs,
555 int *end_of_character_ideal_usecs,
556 int *adaptive_threshold)
557 Return the low-level timing parameters calculated from the speed, gap,
559 tolerance, and weighting set. Parameter values are returned in
560 microseconds. Use NULL for the pointer argument to any parameter value
561 not required.
562 int cw_set_noise_spike_threshold (int threshold)
565 int cw_get_noise_spike_threshold (void)
568 Set and get the period shorter than which, on receive, received tones
570 are ignored. This allows the receive tone functions to apply noise
571 canceling for very short apparent tones. For useful results the value
572 should never exceed the dot length of a dot at maximum speed; 20,000
573 microseconds (the dot length at 60WPM). Setting a noise threshold of
574 zero turns off receive tone noise canceling. The default noise spike
575 threshold is 10,000 microseconds.
576 void cw_block_callback (int is_block)
579 Blocks the callback from being called for a critical section of caller
581 code if is_block is TRUE, and unblocks the callback if block is FALSE.
582 Works by blocking SIGALRM; a block should always be matched by an
583 unblock, otherwise the tone queue will suspend forever.
584 void cw_set_console_file (const char *new_value)
587 const char * cw_get_console_file (void)
590 Get and set routines for the path to the console device through which
592 the library generates PC speaker sound. The set routine does not
593 return any indication of whether the device is a valid console; for
594 that, use cw_is_console_possible() to test to see if the value passed
595 in might be an acceptable console device.
596 The default console file is /dev/console. The call is ingored on plat‐
598 forms that do no support the KIOCSOUND ioctl.
599 void cw_set_soundcard_file (const char *new_value)
602 const char * cw_get_soundcard_file (void)
605 Get and set routines for the path to the sound device through which the
607 library generates soundcard sound. The set routine does not return any
608 indication of whether the device is a valid soundcard; use cw_is_sound‐
609 card_possible() to test to see if the value passed in might be an
610 acceptable soundcard device.
611 The default soundcard file is /dev/audio.
613 void cw_set_soundmixer_file (const char *new_value)
616 const char * cw_get_soundmixer_file (void)
619 Get and set routines for the path to the mixer device that the library
621 may use to gate soundcard sound. The library uses the mixer device
622 where the main sound device does not support the PCM volume control
623 ioctl call; this tends to occur on newer OSS drivers, but not on older
624 ones, or on ALSA in OSS emulation mode. The set routine does not
625 return any indication of whether the device is a valid mixer.
626 The default sound mixer file is /dev/mixer.
628 int cw_is_soundcard_possible (void)
631 Return success status if it appears that the library will be able to
633 generate tones through a sound card. If it appears that a sound card
634 may not work, the routine returns FALSE to indicate failure.
635 The function tests only that the given sound card file exists and is
637 writable.
638 int cw_is_console_possible (void)
641 Return success status if it appears that the library will be able to
643 generate tones through the console speaker. If it appears that console
644 sound may not work, the routine returns FALSE to indicate failure.
645 The function tests that the given console file exists, and that it will
647 accept the KIOCSOUND ioctl. It unconditionally returns FALSE on plat‐
648 forms that do no support the KIOCSOUND ioctl.
649 void cw_set_console_sound (int sound_state)
652 int cw_get_console_sound (void)
655 Enable and disable console sound output, and return the current console
657 sound output setting. By default, console sound output is disabled.
658 On platforms that do not support the KIOCSOUND ioctl, enabling console
659 sound output has no effect.
660 void cw_set_soundcard_sound (int sound_state)
663 int cw_get_soundcard_sound (void)
666 Enable and disable soundcard sound output, and return the current
668 soundcard sound output setting. By default, soundcard sound output is
669 enabled.
670 void cw_complete_reset (void)
673 Reset all library features to their default states. Clears the tone
675 queue, receive buffers and retained state information, any current
676 keyer activity, and any straight key activity, returns to silence, and
677 closes soundcard and console devices. This function is suitable for
678 calling from an application exit handler.
679 int cw_register_signal_handler (int signal_number,
682 void (*callback_func) (int))
683 Register a signal handler and optional callback function for signals.
685 On receipt of that signal, all library features will be reset to their
686 default states. Following the reset, if callback_func is a function
687 pointer, the function is called; if it is SIG_DFL, the library calls
688 exit(); and if it is SIG_IGN, the library returns from the signal han‐
689 dler. This is a convenience function for clients that need to clean up
690 library on signals, with either exit, continue, or an additional func‐
691 tion call; in effect, a wrapper round a restricted form of sigaction.
692 The signal_number argument indicates which signal to catch. Returns
693 TRUE if the signal handler installs correctly, FALSE otherwise, with
694 errno set to EINVAL if signal_number is invalid or if a handler is
695 already installed for that signal, or to the sigaction error code.
696 int cw_unregister_signal_handler (int signal_number)
699 Removes a signal handler interception previously registered with
701 cw_register_signal_handler. Returns TRUE if the signal handler unin‐
702 stalls correctly, FALSE otherwise, with errno set to EINVAL or to the
703 sigaction error code.
704 void cw_register_keying_callback (void (*callback_func) (void*, int),
707 void *callback_arg)
708 Register a function that should be called when a tone state changes
710 from key-up to key-down, or vice-versa. The first argument passed out
711 to the registered function is the supplied callback_arg, if any. The
712 second argument passed out is the key state: TRUE for down, FALSE for
713 up. Calling this routine with an NULL function address disables keying
714 callbacks. Any callback supplied will be called in signal handler con‐
715 text.
716 int cw_register_tone_queue_low_callback (void (*callback_func) (void*),
719 void *callback_arg, int level)
720 Registers a function to be called automatically by the dequeue routine
722 whenever the tone queue falls to a given level; callback_arg may be
723 used to give a value passed back on callback calls. A NULL function
724 pointer suppresses callbacks. On success, the routine returns TRUE.
725 If level is invalid, the routine returns FALSE with errno set to EIN‐
726 VAL. Any callback supplied will be called in signal handler context.
727 int cw_is_tone_busy (void)
730 Indicates if the tone sender is busy; returns TRUE if there are still
732 entries in the tone queue, FALSE if the queue is empty.
733 int cw_wait_for_tone (void)
736 Wait for the current tone to complete. The routine returns TRUE on
738 success. If called with SIGALRM blocked, the routine returns FALSE,
739 with errno set to EDEADLK, to avoid indefinite waits.
740 int cw_wait_for_tone_queue (void)
743 Wait for the tone queue to drain. The routine returns TRUE on success.
745 If called with SIGALRM blocked, the routine returns FALSE, with errno
746 set to EDEADLK, to avoid indefinite waits.
747 int cw_wait_for_tone_queue_critical (int level)
750 Wait for the tone queue to drain until only as many tones as given in
752 level remain queued. This routine is for use by programs that want to
753 optimize themselves to avoid the cleanup that happens when the tone
754 queue drains completely; such programs have a short time in which to
755 add more tones to the queue. The routine returns TRUE on success. If
756 called with SIGALRM blocked, the routine returns FALSE, with errno set
757 to EDEADLK, to avoid indefinite waits.
758 int cw_is_tone_queue_full (void)
761 Indicates if the tone queue is full, returning TRUE if full, FALSE if
763 not.
764 int cw_get_tone_queue_capacity (void)
767 Returns the number of entries the tone queue can accommodate.
769 int cw_get_tone_queue_length (void)
772 Returns the number of entries currently pending in the tone queue.
774 void cw_flush_tone_queue (void)
777 Cancel all pending queued tones, and return to silence. If there is a
779 tone in progress, the function will wait until this last one has com‐
780 pleted, then silence the tones.
781 This function may be called with SIGALRM blocked, in which case it will
783 empty the queue as best it can, then return without waiting for the
784 final tone to complete. In this case, it may not be possible to guar‐
785 antee silence after the call.
786 int cw_queue_tone (int usecs, int frequency)
789 Provides primitive access to simple tone generation. This routine
791 queues a tone of given duration and frequency. The routine returns
792 TRUE on success. If usec or frequency are invalid, it returns FALSE
793 with errno set to EINVAL. If the sound card, console speaker, or key‐
794 ing function are busy, it returns FALSE with errno set to EBUSY. If
795 the tone queue is full, it returns FALSE with errno set to EAGAIN.
796 void cw_reset_tone_queue (void)
799 Cancel all pending queued tones, reset any queue low callback regis‐
801 tered, and return to silence. This function is suitable for calling
802 from an application exit handler.
803 int cw_send_dot (void)
806 int cw_send_dash (void)
809 int cw_send_character_space (void)
812 int cw_send_word_space (void)
815 Low level primitives, available to send single dots, dashes, character
817 spaces, and word spaces. The dot and dash routines always append the
818 normal inter-element gap after the tone sent. The cw_send_charac‐
819 ter_space routine sends space timed to exclude the expected prior
820 dot/dash inter-element gap. The cw_send_word_space routine sends space
821 timed to exclude both the expected prior dot/dash inter-element gap and
822 the prior end of character space. These functions return TRUE on suc‐
823 cess, or FALSE with errno set to EBUSY or EAGAIN on error.
824 int cw_send_representation (const char *representation)
827 Checks, then sends the given string as dots and dashes. The represen‐
829 tation passed in is assumed to be a complete Morse character; that is,
830 all post- character delays will be added when the character is sent.
831 On success, the routine returns TRUE. On error, it returns FALSE, with
832 errno set to EINVAL if any character of the representation is invalid,
833 EBUSY if the sound card, console speaker, or keying system is busy, or
834 EAGAIN if the tone queue is full, or if there is insufficient space to
835 queue the tones for the representation.
836 int cw_send_representation_partial (const char *representation)
839 Check, then send the given string as dots and dashes. The representa‐
841 tion passed in is assumed to be only part of a larger Morse representa‐
842 tion; that is, no post-character delays will be added when the charac‐
843 ter is sent. On success, the routine returns TRUE. On error, it
844 returns FALSE, with errno set to EINVAL if any character of the repre‐
845 sentation is invalid, EBUSY if the sound card, console speaker, or key‐
846 ing system is busy, or EAGAIN if the tone queue is full, or if there is
847 insufficient space to queue the tones for the representation.
848 int cw_check_character (char c)
851 Checks that the given character is validly sendable in Morse. If it
853 is, the routine returns TRUE. If not, the routine returns FALSE, with
854 errno set to ENOENT.
855 int cw_send_character (char c)
858 Lookup, and send a given ASCII character as Morse. The end of charac‐
860 ter delay is appended to the Morse sent. On success, the routine
861 returns TRUE. On error, it returns FALSE, with errno set to ENOENT if
862 the given character is not a valid Morse character, EBUSY if the sound
863 card, console speaker, or keying system is busy, or EAGAIN if the tone
864 queue is full, or if there is insufficient space to queue the tones for
865 the representation.
866 This routine returns as soon as the character has been successfully
868 queued for send; that is, almost immediately. The actual sending hap‐
869 pens in background processing. See cw_wait_for_tone and
870 cw_wait_for_tone_queue for ways to check the progress of sending.
871 int cw_send_character_partial (char c)
874 Lookup, and send a given ASCII character as Morse. The end of charac‐
876 ter delay is not appended to the Morse sent by the function, to support
877 the formation of combination characters. On success, the routine
878 returns TRUE. On error, it returns FALSE, with errno set to ENOENT if
879 the given character is not a valid Morse character, EBUSY if the sound
880 card, console speaker, or keying system is busy, or EAGAIN if the tone
881 queue is full, or if there is insufficient space to queue the tones for
882 the representation.
883 This routine queues its arguments for background processing. See
885 cw_send_character for details of how to check the queue status.
886 int cw_check_string (const char *string)
889 Checks that each character in the given string is validly sendable in
891 Morse. On success, the routine returns TRUE. On error, it returns
892 FALSE, with errno set to EINVAL.
893 int cw_send_string (const char *string)
896 Send a given ASCII string as cw. On success, the routine returns TRUE.
898 On error, it returns FALSE, with errno set to ENOENT if any character
899 in the string is not a valid Morse character, EBUSY if the sound card,
900 console speaker, or keying system is in use by the iambic keyer or the
901 straight key, or EAGAIN if the tone queue is full. If the tone queue
902 runs out of space part way through queueing the string, the function
903 returns EAGAIN. However, an indeterminate number of the characters
904 from the string will have already been queued. For safety, clients can
905 ensure the tone queue is empty before queueing a string, or use
906 cw_send_character() if they need finer control.
907 This routine queues its arguments for background processing. See
909 cw_send_character for details of how to check the queue status.
910 void cw_get_receive_statistics (double *dot_sd, double *dash_sd,
913 double *element_end_sd, double *character_end_sd)
914 Calculate and return receive timing statistics. These statistics may
916 be used to obtain a measure of the accuracy of received CW. The values
917 dot_sd and dash_sd contain the standard deviation of dot and dash
918 lengths from the ideal values, and element_end_sd and character_end_sd
919 the deviations for inter element and inter character spacing. Statis‐
920 tics are held for all timings in a 256 element circular buffer. If any
921 statistic cannot be calculated, because no records for it exist, the
922 returned value is 0.0. Use NULL for the pointer argument to any
923 statistic not required.
924 void cw_reset_receive_statistics (void)
927 Clear the receive statistics buffer, removing all records from it and
929 returning it to its initial default state.
930 void cw_enable_adaptive_receive (void)
933 void cw_disable_adaptive_receive (void)
936 int cw_get_adaptive_receive_state (void)
939 Enable and disable adaptive receive speeds. If adaptive speed tracking
941 is enabled, the receive functions will attempt to automatically adjust
942 the receive speed setting to match the speed of the incoming Morse
943 code. If it is disabled, the receive functions will use fixed speed
944 settings, and reject incoming Morse which is not at the expected speed.
945 The cw_get_adaptive_receive_state function returns TRUE if adaptive
946 speed tracking is enabled, FALSE otherwise. Adaptive speed tracking
947 uses a moving average of the past four elements as its baseline for
948 tracking speeds. The default state is adaptive tracking disabled.
949 int cw_start_receive_tone (const struct timeval *timestamp)
952 Called on the start of a receive tone. If the timestamp is NULL, the
954 current time is used. On success, the routine returns TRUE. On
955 error, it returns FALSE, with errno set to ERANGE if the call is
956 directly after another cw_start_receive_tone call or if an existing
957 received character has not been cleared from the buffer, or EINVAL if
958 the timestamp passed in is invalid.
959 int cw_end_receive_tone (const struct timeval *timestamp)
962 Called on the end of a receive tone. If the timestamp is NULL, the
964 current time is used. On success, the routine adds a dot or dash to
965 the receive representation buffer, and returns TRUE. On error, it
966 returns FALSE, with errno set to ERANGE if the call was not preceded by
967 a cw_start_receive_tone call, EINVAL if the timestamp passed in is not
968 valid, ENOENT if the tone length was out of bounds for the permissible
969 dot and dash lengths and fixed speed receiving is selected, ENOMEM if
970 the representation buffer is full, or EAGAIN if the tone was shorter
971 than the threshold for noise and was therefore ignored.
972 int cw_receive_buffer_dot (const struct timeval *timestamp)
975 int cw_receive_buffer_dash (const struct timeval *timestamp)
978 Adds either a dot or a dash to the receive representation buffer. If
980 the timestamp is NULL, the current timestamp is used. These routines
981 are for callers that have already determined whether a dot or dash was
982 received by a method other than calling the routines
983 cw_start_receive_tone and cw_end_receive_tone. On success, the rele‐
984 vant element is added to the receive representation buffer. On error,
985 the routines return FALSE, with errno set to ERANGE if preceded by a
986 cw_start_receive_tone call with no matching cw_end_receive_tone or if
987 an error condition currently exists within the receive buffer, or
988 ENOMEM if the receive representation buffer is full.
989 int cw_receive_representation (const struct timeval *timestamp,
992 char *representation, int *is_end_of_word,
993 int *is_error)
994 Returns the current buffered representation from the receive buffer.
996 On success, the function returns TRUE, and fills in representation with
997 the contents of the current representation buffer. On error, it
998 returns FALSE, with errno set to ERANGE if not preceded by a
999 cw_end_receive_tone call, a prior successful cw_receive_representation
1000 call, or a prior cw_receive_buffer_dot or cw_receive_buffer_dash, EIN‐
1001 VAL if the timestamp passed in is invalid, or EAGAIN if the call is
1002 made too early to determine whether a complete representation has yet
1003 been placed in the buffer (that is, less than the inter-character gap
1004 period elapsed since the last cw_end_receive_tone or cw_receive_buf‐
1005 fer_dot/dash call). is_end_of_word indicates that the delay after the
1006 last tone received is longer that the inter-word gap, and is_error
1007 indicates that the representation was terminated by an error condition.
1008 int cw_receive_character (const struct timeval *timestamp,
1011 char *c, int *is_end_of_word, int *is_error)
1012 Returns the current buffered character from the representation buffer.
1014 On success, the function returns TRUE, and fills char *c with the con‐
1015 tents of the current representation buffer, translated into a charac‐
1016 ter. On error, it returns FALSE, with errno set to ERANGE if not pre‐
1017 ceded by a cw_end_receive_tone call, a prior successful
1018 cw_receive_character call, or a cw_receive_buffer_dot or
1019 cw_receive_buffer dash call, EINVAL if the timestamp passed in is
1020 invalid, or EAGAIN if the call is made too early to determine whether a
1021 complete character has yet been placed in the buffer (that is, less
1022 than the inter-character gap period elapsed since the last
1023 cw_end_receive_tone or cw_receive_buffer_dot/dash call).
1024 is_end_of_word indicates that the delay after the last tone received is
1025 longer that the inter-word gap, and is_error indicates that the charac‐
1026 ter was terminated by an error condition.
1027 void cw_clear_receive_buffer (void)
1030 Clears the receive representation buffer to receive tones again. This
1032 routine must be called after successful, or terminating,
1033 cw_receive_representation or cw_receive_character calls, to clear the
1034 states and prepare the buffer to receive more tones.
1035 int cw_get_receive_buffer_capacity (void)
1038 Returns the number of entries the receive buffer can accommodate. The
1040 maximum number of character written out by cw_receive_representation is
1041 the capacity + 1, the extra character being used for the terminating
1042 NUL.
1043 int cw_get_receive_buffer_length (void)
1046 Returns the number of elements currently pending in the receive buffer.
1048 void cw_reset_receive (void)
1051 Clear the receive representation buffer, statistics, and any retained
1053 receive state. This function is suitable for calling from an applica‐
1054 tion exit handler.
1055 void cw_enable_iambic_curtis_mode_b (void)
1058 void cw_disable_iambic_curtis_mode_b (void)
1061 int cw_get_iambic_curtis_mode_b_state (void)
1064 Normally, the iambic keying functions will emulate Curtis 8044 Keyer
1066 mode A. In this mode, when both paddles are pressed together, the last
1067 dot or dash being sent on release is completed, and nothing else is
1068 sent. In mode B, when both paddles are pressed together, the last dot
1069 or dash being sent on release is completed, then an opposite element is
1070 also sent. Some operators prefer mode B, but timing is more critical
1071 in this mode. The default mode is Curtis mode A.
1072 int cw_notify_keyer_paddle_event (int dot_paddle_state,
1075 int dash_paddle_state)
1076 Informs the internal keyer states that the keyer paddles have changed
1078 state. The new paddle states are recorded, and if either transition
1079 from FALSE to TRUE, paddle latches, for iambic functions, are also set.
1080 On success, the routine returns TRUE. On error, it returns FALSE, with
1081 errno set to EBUSY if the tone queue or straight key are using the
1082 sound card, console speaker, or keying system.
1083 If appropriate, this routine starts the keyer functions sending the
1085 relevant element. Element send and timing occurs in the background, so
1086 this routine returns almost immediately. See cw_keyer_element_wait and
1087 cw_keyer_wait for details about how to check the current status of
1088 iambic keyer background processing.
1089 int cw_notify_keyer_dot_paddle_event (int dot_paddle_state)
1092 int cw_notify_keyer_dash_paddle_event (int dash_paddle_state)
1095 Convenience functions to alter the state of just one of the two iambic
1097 keyer paddles. The other paddle state of the paddle pair remains
1098 unchanged.
1099 See cw_keyer_paddle_event for details of iambic keyer background pro‐
1101 cessing, and how to check its status.
1102 void cw_get_keyer_paddles (int *dot_paddle_state, int *dash_paddle_state)
1105 Returns the current saved states of the two paddles.
1107 void cw_get_keyer_paddle_latches (int *dot_paddle_latch_state,
1110 int *dash_paddle_latch_state)
1111 Returns the current saved states of the two paddle latches. A paddle
1113 latches is set to TRUE when the paddle state becomes true, and is
1114 cleared if the paddle state is FALSE when the element finishes sending.
1115 int cw_is_keyer_busy (void)
1118 Indicates if the keyer is busy; returns TRUE if the keyer is going
1120 through a dot or dash cycle, FALSE if the keyer is idle.
1121 int cw_wait_for_keyer_element (void)
1124 Waits until the end of the current element, dot or dash, from the
1126 keyer. This routine returns TRUE on success. On error, it returns
1127 FALSE, with errno set to EDEADLK if SIGALRM is blocked.
1128 int cw_wait_for_keyer (void)
1131 Waits for the current keyer cycle to complete. The routine returns
1133 TRUE on success. On error, it returns FALSE, with errno set to EDEADLK
1134 if SIGALRM is blocked or if either paddle state is TRUE.
1135 void cw_reset_keyer (void)
1138 Clear all keyer latches and paddle states, return to Curtis 8044 Keyer
1140 mode A, and return to silence. This function is suitable for calling
1141 from an application exit handler.
1142 int cw_notify_straight_key_event (int key_state)
1145 Informs the library that the straight key has changed state. This rou‐
1147 tine returns TRUE on success. On error, it returns FALSE, with errno
1148 set to EBUSY if the tone queue or iambic keyer are using the sound
1149 card, console speaker, or keying control system. If key_state indi‐
1150 cates no change of state, the call is ignored.
1151 int cw_get_straight_key_state (void)
1154 Returns the current saved state of the straight key; TRUE if the key is
1156 down, FALSE if up.
1157 int cw_is_straight_key_busy (void)
1160 Returns TRUE if the straight key is busy, FALSE if not. This routine
1162 is just a pseudonym for cw_get_straight_key_state, and exists to fill a
1163 hole in the API naming conventions.
1164 void cw_reset_straight_key (void)
1167 Clears the straight key state, and returns to silence. This function
1169 is suitable for calling from an application exit handler.
1170
1172 Despite the fact that this manual page constantly and consistently
1173 refers to Morse code elements as dots and dashes, DO NOT think in these
1174 terms when trying to learn Morse code. Always think of them as 'dit's
1175 and 'dah's.
1176 cwlib uses system itimers for its internal timing. On most UNIX
1178 flavours, itimers are not guaranteed to signal a program exactly at the
1179 specified time, and they generally offer a resolution only as good as
1180 the normal system 'clock tick' resolution. An itimer SIGALRM usually
1181 falls on a system clock tick, making it accurate to no better than 10mS
1182 on a typical 100Hz kernel.
1183 The effect of this is that an itimer period is generally either exactly
1185 as specified, or, more likely, slightly longer. At higher WPM set‐
1186 tings, the cumulative effect of this affects timing accuracy, because
1187 at higher speeds, there are fewer 10mS clock ticks in a dot period.
1188 For example, at 12 WPM, the dot length is 100mS, enough to contain five
1189 kernel clock ticks; at 60 WPM, the dot length is 20mS, or just two ker‐
1190 nel clock ticks. So at higher speeds, the effect of itimer resolutions
1191 becomes more pronounced.
1192
1194 Man pages for cw(7,LOCAL), cw(1,LOCAL), cwgen(1,LOCAL), cwcp(1,LOCAL),
1195 and xcwcp(1,LOCAL).
1196G0FRD CW Tutor Package CWLIB(3)