\ This is the term program, which was found in the extensions folder when
\ downloading PropForth v5.5, rewritten with my explanations to make it easier
\ to understand.

\ ********************************************************************************************

fl

: term                            \ ( cog flag -- ) 
   over                           \ ( cog flag cog -- )
   cognchan                       \ number of channels in the target cog ( cog flag #channels -- )
   min                            \ minimum of flag and #channels ( cog chan -- )

   ." Hit CTL-P to exit term"     \ tells how to get out of the loop ( cog chan -- )
   >r >r                          \ save the stack over to the return stack ( -- )
   cogid                          \ get the cog id of the current cog, usually 6 ( cog -- )
   0				  \ desired chan of current cog to link to the target cog ( cog chan -- )
   r> r>                          \ return the items from the return stack ( cog chan cog chan -- )
   (iolink)                       \ link the two cogs together
                                  \ for example 6-out to 4-in and 4-out to 6-in
                                  \ at this point the stack is empty ( -- )
   begin                          \ start the loop in the current cog, i.e. cog 6
      key                         \ get a key from the keyboard ( key -- )
      dup                         \ make a copy of the key on the stack ( key key -- )
      h10 =                       \ check key for hex 10 (CTL-P) ( key flag -- )
      if                          \ yes, it is CTL-P ( key -- )
        drop -1                   \ drop the key, and go to the until statement ( True -- )
      else                        \ it wasn't CTL-P  (key -- )
        dup                       \ copy of the key again ( key key -- )
        h11                       \ hex 11 to the stack ( key key 11 -- )
        h19                       \ hex 19 to the stack ( key key 11 19 -- )
        between	                  \ tests to see if the key is between h11 and h19 ( key flag)
        if                        \ yes, it is between these two values ( key -- )
          1-                      \ subtract one from key ( key-1 -- )
        then                      \ ends that if statement
        emit                      \ actually send the char out the serial connection ( -- )
        0                         \ put a false flag on the stack to keep the loop going ( flag -- )
      then                        \ ends the first if statement ( flag -- )
    until                         \ Tests the flag for true or false, if false do it again ( -- )
    cogid                         \ gets the cogid of the current cog
    iounlink                      \ and breaks the linkage between the two cogs
;                                     
   
\ ******************************************************************************************
\ Usage
\ Let's say I wanted to hook up to a laser rangefinder and have it be communicating with cog 4
\ I would want to set up cog 4 for serial communications with the rangefinder
\ i.e. c" txpin rxpin baud 4 / serial" 4 cogx

\ I have rangefinder transmit connected to the propeller on P0 (receive)
\ I have rangefinder receive connected to the propeller on P1 (transmit), so I would enter  the following:
\ c" 1 0 9600 4 / serial" 4 cogx

\ Then it is necessary to enable the serial port with the following by
\ setting the active flag.

\ 1 1 sersetflags

\ this makes the serial port active

\ The last remaining thing to do is to start the term, as defined above:
\ 4 0 term

\ Now, whatever you type on the keyboard will be sent out of cog 4 and whatever cog 4 receives
\ will be received in cog 6 and displayed on your computer screen terminal program.