
                              TWCW HELP FILE


DESCRIPTION

   Twcw is a X/Motif application that sends Morse code.  It uses the
   openMotif toolkit.  Previous versions used lessTif.

   The application consists of two programs, twcw and sendCW.  Start the 
   application by running twcw.  This creates the Motif interface and forks a
   child process that runs sendCW.  The child process, sendCW, does two things.
   It toggles the serial port's Request to Send (RTS) line, and generates the
   sidetone.  The two processes talk to each other using a message queue.  For
   more information on message queues and troubleshooting, see IPC COMMANDS
   below. 
 

HARDWARE INTERFACE

        WARNING   THIS INTERFACE CAN DAMAGE YOUR EQUIPMENT.  I AM NOT
                  RESPONSIBLE FOR ANY DAMAGE TO ANY OF YOUR EQUIPMENT.
 
   The transmitter is keyed by the RTS signal on the serial port.  A line in 
   the resource file, Twcw, allows you to specify which serial port will be
   keyed.  The default value is /dev/ttyS1.  See the comments in Twcw for more
   info.
   
   View the file interface.gif with xv or xpaint to see one way to interface 
   the rig with the serial port.  This interface consists of one chip and a 
   resistor.  These two parts easily fit into the RS232 connector cover.  No 
   power supply is needed since all power is pulled from the voltage across the
   key contacts and the serial card of your computer.  See the README file for
   more information!


FEATURES
 
   This section gives a brief description of the features of twcw.  For a more
   complete description see the sections mentioned below.

      Interface to Log Programs
         Twcw will try to get the call of the station you are working from
         log programs.  Currently this works with twlog and xlog.

      Send Macros
         Short text strings can be sent with a keystroke you define.  See
         the resource file, Twcw, for instructions on defining new macros.
         Two are automatically defined.  Shift Alt m (Me) can be modified in
         Twcw to send your call.  Shift Alt h (Him) will send the call of the
         station found in a log program.  Shift Alt o (Over) will send
         "his call de your call", or just "de your call" if it can't find
          his call in a log program.

      Twcw Resource File
         Like other X applications, the resource file, Twcw, is used to set
         interface properties.  In addition to the basic properties like the
         x-y location and colors, Twcw initializes the state of other resources,
         like the names of the text files.  See RESOURCE FILE section below for
         more information.

      Timing
         Two methods are used for timing.  Which one, is determined by the
         program at start up.  The RDTSC method uses code hacked from Tom
         Sailer's sound modem program.  The gettimeofday method is used if your
         computer does not have the RDTSC command.  Both methods give good 
         results, but the gettimeofday method has some disadvantages.  See the
         TIMING section below for more.

      Word Completion
         Only whole words are sent.  In other words, you must hit the Space
         or Enter key before a word can be sent.  Once started, the word will
         be sent completely.  See WORD COMPLETION below for more.

      Send Files
         You can create and send your own text files.  These can be used for
         CQ's, QSO's and contests.  When sending a file, the program looks for
         words that start with the * character.  When one of these *WORDS is
         found, a dialog window allows you to enter the words you want to send
         at that point in the file.  See the SENDING FILES section below for
         more.

      Pro Signs
         The pro signs, like sk and kn, are sent by typing Shift-1 through
         Shift-6.  See PRO SIGNS below for more information.
     
      WPM range
         The WPM range is from 8 to 50 WPM.  


GRAPHICAL INTERFACE

   The graphical interface consists of a Call label, a Menu Bar, the Text
   window, the Sending text field, a tone scale, the XMIT and SIDETONE toggle
   buttons, and the WPM text field.
   
   Call Label
      Your call will be displayed here by setting a property in the resource
      file, Twcw.  See RESOURCE FILES below, the README and Twcw for more
      information.

   Menu Bar
      The menu bar has the following buttons, which display drop down menus.

      File
         The menu displayed by this button allows you to terminate the program
         (QRT), and send files.  See SENDING FILES for more information on how
         to set these files,

      Edit
         The menu for this button gives you the following options.  All of the
         buttons in this pull down menu and the QRT (exit) button are also
         on a pop up menu via the right mouse button.  See ACCELERATOR KEYS
         below.

         Clear Text
            Clears the main text field.

         Clear Sent
            Clears the Sending text field.

         Reset 
            Clears both the Text and Sent fields AND delete all the text that
            is waiting to be sent.  

      Help
         About
            This pops up a window that tells you about who did this.

         Help
            Displays this file.

   Text
      This is the window where you type the text you want to send.  If you send 
      a text file, its contents is displayed here too.

   Sending Text Field 
      As a character is sent, this window displays the text.  As this window 
      fills with text, the old text scrolls off the left side of the window.

   Tone
      Use this scale to select a sidetone frequency. The SIDETONE button (see 
      below) must be ON before a sidetone will be heard.  You will not hear the
      new tone when the next word is sent.

   XMIT
      This toggle button starts and stops sending.  If you turn it off while
      a word is being sent, that word will finish, and then sending will stop. 

   SIDETONE 
      When this button is on, the computer's speaker will play the CW being 
      sent.
  
   WPM
      Set this field to the speed you want to send.  This will cause the speed
      to change when the next word is sent, even is you are typing ahead of
      the sending.


RESOURCE FILE

   The resource file is named Twcw.  It has two columns per line.  The left 
   had column is a property name followed by a : character. The right hand
   column has the value you want to assign the property. 

   Any line starting with the ! character is a comment.  There are lots of 
   comments describing the first nine properties in the file.  These are the
   ones you will most likely want to change.

   A resource file is read when the program starts.  So when you change 
   something, you must stop and restart the program for the change to take
   effect.


TIMING
   
   One of two methods is used to generate the timebase, RDTSC or gettimeofday.
   The program determines which one when it starts and prints out a message
   telling you which it is using.

   RDTSC METHOD

      If RDTSC is used, then you need to set the proper value for the property
      twcw.cpuSpeed in the resource file, Twcw.  You will or have done this as
      part of the installation.  The process is in the CALIBRATION section of
      the README file and repeated here.

      1. Look in the Twcw resource file you copied in Step 6 and find the
         line with "twcw.cpuSpeed".  Remember its value. 

      2. Set the WPM to 20 WPM.  Turn XMIT off and SIDETONE on.
   
      3. Click on File in the menubar and then PARIS in the drop down menu.
         This will load the file into the text widget.
   
      4. When the second hand of your clock is at a convenient place, turn
         XMIT on to start sending the file.  You should hear the E at the end,
         exactly 60 seconds later.  If not, grab a calculator (xcalc works
         good) and do this calculation.

            60/time * cpuSpeed

         where
            time = the time it took to send the file
            cpuSpeed = the current value of twcw.cpuSpeed in Twcw

      5. Edit the Twcw you copied and change the value of cpuSpeed to the
         result of your calculation.  Exit and restart twcw and test it again.
         You can repeat this if needed, always using the current value of
         cpuSpeed, but I've never had to do it more than once or twice.


   GETTIMEOFDAY METHOD

      If the program picked the gettimeofday method, then there is nothing for
      you to do.  However, there is one thing you should know.  This method
      calibrates by pretending to send the word PARIS.  It times itself and
      calculates a "fudge factor" to adjust the timing.  This happens every
      time you change the WPM and can take a few seconds.  Everything stops
      while this is going on and the pointer will change to a clock until it
      is done.

   
WORD COMPLETION

   Word completions means that when sendCW starts to send a word, there is no
   way to stop it.  A word is defined when you hit the Space or Enter key.  
   This means that you can not Backspace or Delete past a Space or Enter.  In
   fact, the GUI won't let you.  You can only enter text at the very end.  Just
   hit ! to send an error and retype the word.  If you want to know the messy
   details as to why, then read the next three paragraphs.
   
   Two process, twcw and sendCW are running and they talk to each other with
   a message queue.  twcw sends a word to sendCW every time you hit the SPACE
   or Enter key.  A copy of that word is now in the message queue and sendCW
   will transmit it when it gets around to it.  There are other words ahead of
   it in the queue if you are type fast.   

   GOOD NEWS

      Besides word messages, twcw sends control messages to sendCW, like start,
      stop, and change WPM.  The messages are process according to their type.
      When sendCW reads the queue, it first looks for any control messages in
      the queue and processes them.  If there are none, then it looks for the
      next word message and transmits it completely before checking the queue
      again, first for control messages and then words.  This is what prevents
      the WPM from changing in the middle of a word, yet allows the WPM to
      change even though there are words that were placed in the queue before
      the the WPM message.  Those words will be sent later at the new WPM.

   BAD NEWS

      The bad news is there is no way to change the word once it is on the
      queue.  You still see the word in the interface, but the queue has a copy
      that that you can't change.  This means you can backspace and edit all
      you want, but NOT after the Space or Enter key has been hit.  In fact,
      the GUI won't let you.  It will only let you enter text at the very end,
      and you can only Backspace or Delete to the last Space or Enter.  Trying
      to just makes it mad and beep at you.  Not really bad news.


PRO SIGNS

   The - key sends bt.  The error, ar, sk, kn, as, and bk characters are sent
   with the !, @, #, $, % and ^ keys.  In other words, they are sent by holding
   down the Shift key and hitting 1 through 6.  The program catches these keys
   and actually displays ar, sk, etc. in lower case.  

   I used a word processor to create a line with "err ar sk kn as bt".  By
   playing with the font size and spacing, I got a printout that lined up with
   the 1 through 6 keys.  Some clear plastic and you're ready. 



SENDING FILES

   When sending a file, the program looks for words that start with the *
   character.  When one of these *WORDS is found, a dialog window allows you to
   enter the words you want to send at that point in the file.
   
   For example, if *RST is found in a text file, a dialog box with the label
   RST will pop up and you can enter as much text as you want.  When you have
   finished, hit the Enter key.  The dialog box will go away and the text will
   be put into the interface.   The rest of the file will then be sent or,
   until another *WORD is found.  There is a limit of 9 text files, but it is
   easy to reconfigure the program with different text files.  See LIMITS below.

   To send a file you must create it where twcw can find it, and tell twcw its
   name in the TWCW resource file.  First we will create the file.

   To create a file, it must first be in the directory pointed to by the
   resource file property twcw.dirPath.  If you followed the suggestions during
   the installation, it is under your home directory and is called twcwQSO.
   While you're there, view the QSO1 file that came the program.  It will show
   you a format you could use.  

   Assume that the XMIT toggle button is ON.  When you send QSO1, the first
   thing found is *CALL, so a dialog box pops up with the label CALL.  You can
   enter your contacts call sign a few times, even as he is signing.  Nothing
   will be sent until you hit the Enter key.  When your contact signs, you hit
   the Enter key and, BAM,  the dialogs text is in the interface, followed by
   "de yourcall" and its being sent.  About the time you got your finger off
   the Enter key another dialog pops up with the TOD (time of day) label.  You
   type "ge ge" and hit Enter, and so on for NAME, RST, and another CALL.
   You're done.  Listen to what is being sent!  Its probably sending "ge ge".

   Case does not matter in these files, so I like to do all the text in lower
   case and the *WORDS in upper case.  *WORDS stand out better and since the
   program user WORDS for the dialog title, the dialog box looks better.
   
   Now that you have created file, you have to tell the program about it.  This
   is done in the resource file.  Twcw has a line like this:

        twcw.buttonNames:             ShortCQ,LongCQ,QSO1,QSO2,PARIS


   The right hand side is a comma separated list of you files.  They will
   appear in the File pull down menu in the order they appear here.  Make sure
   there are no spaces on the end of this line.  Restart twcw and check the
   FILE menu.  You should see your file name on a button.  I like to put them
   in some logical order - the first two for CQ's, then QSO files in the order
   they will be used, etc.

   
LIMITS

   There are a few "limits" you should know about.  First, you can only have 9
   files listed in the twcw.buttonNames property.  This is because Control 1
   through Control 9 are used as accelerator keys to send these files.  See
   ACCELERATOR KEYS  below.  This is not a big limit since you can change the
   resource twcw.dirPath in Twcw and make it point to a different directory
   with another set of files.  If you name the files the same, you don't have
   to change twcw.buttonNames.  Using this method, you could have a directory
   for every contest you work.  You may want to copy the helpfile to these
   directories as well, but if you are using this trick, I don't think you will
   need the helpfile very much!

   Another "limit" is the number of bytes that can be in the queue.  On my 
   system, the max size of the queue is 16384 bytes, so this should not be a 
   problem even when sending files.  To determine your system limits, see IPC
   COMMANDS below. 


ACCELERATOR KEYS

   As you start using this program, you will probably use the menus.  But, as
   you do, look for text on the right side of a button.  It will be something
   like Ctrl-T.  This means that pressing Control T does the same thing as 
   pushing the button.  Mice are nice, but the key stroke can be much faster.
   As mentioned above, the File pulldown menu, which lists the files you can
   send also has accelerator keys.  They are assigned Control 1 through
   Control 9.   
   
   There is also one more menu, a popup menu.  It is displayed by pressing the
   right mouse button.  Options on this menu are the same as the Edit menu plus
   the QRT button from the File menu.  These buttons also have the accelerator
   buttons mentioned above.


IPC COMMANDS
   
   Since this program uses IPC message queues, there are a few Unix commands
   that you may need to know.  First is the command "ipcs -lq".  This displays 
   information about Message Limits.  The "default max size of queue (bytes)"
   line of the output shows the "default max size of queue in bytes".  For men,
   it is over 16KB, which should be more than enough to send a file.
   
   The "ipcs -q" command displays detailed information about the message queues.
   If twcw is running, you should see something like this:

    ------ Message Queues --------
    msqid     owner     perms     used-bytes  messages    
    256       you       666       0           0
   
    FIX IT   
    
   
    
    
CREDITS AND THANKS 

   Some thank you's are needed.  First, thanks to Tom Sailor for his timing
   routine.  This was taken from his sound card modem for Packet.  Without it,
   changing the WPM was very time consuming.  His routine provides excellent
   timing across the entire range of the program.

   A second thank you goes to Vibroplex.  They allowed me to use a gif file
   from there Web page for the program's icon.  You should visit the Vibroplex 
   Web page at www.vibroplex.com and say Hello to Mitch, W4OA.

   Thank you, guys!


   Ted - WA0EIR

