---------------------------------------------------------
The Liberty Basic Newsletter - Issue #49 - SEP 99
"Knowledge is a gift we receive from others."
		- Michael T. Rankin
---------------------------------------------------------
In this issue:

Serial Communications by Herman


In future issues:

Thunking 32-bit API Calls
---------------------------------------------------------
There has been very little written about using Liberty
BASIC for serial communications, so this article is
especially welcome.  Thank you once again, Herman,
for sharing some of your extensive knowledge (and your
sense of humor) with us!

Contact Herman Oosthuysen:
http://www.AerospaceSoftware.com
mailto:aerosoft@aerospacesoftware.com
---------------------------------------------------------
Serial Communications
=====================


General
-------
There is a lot of mystique surrounding the PC serial port, 
simply because Microsoft never created a proper serial 
port driver.

The BASIC interpreter uses the bad Microsoft driver and 
therefore doesnt work all that well.  Although one can get 
it to work, and it is useable, any serious application 
requires the use of a third party DLL.

That being said, this example shows how to use the LB 
serial port interface for those masochists out there who 
want to know why they should not use it...


Get a Plug
----------
Firstly, we need to discuss a little hardware matter of 
plugs and things.

The PC comes with either a 25 or a 9 pin serial connector.  
You will need to plug into it and loop it back, so that we 
can talk to ourselves.  Talking to oneself is usually not 
recommended, since one cannot learn anything new, but
this is an exception!

Here is a list of the interesting pins on these connectors.  
Ignore the other pins, leave them unconnected.

9-pin Connector           (Male at PC)               25-pin Connector
----------------------------------------------------------------------
1    CD    Carrier Detect (Its life Jim...)          8
2    RX    Receive (...hlab ,hlaB)                   3
3    TX    Transmit (Blah, blah...)                  2
4    DTR   Data Terminal Ready  (Local PC ready)     20
5    GND   Ground - common (Terra firma)             7
6    DSR   Data Set Ready (Remote equipment ready)   6
7    RTS   Request to Send (I beg yours?)            4
8    CTS   Clear to Send (Shoot!)                    5

In order to keep the Windows serial driver happy, we have to 
interconnect some pins.  So, you have to visit your local 
Radio Shack and stock up on connectors, hook-up wire, thin 
rosin flux solder solder and a soldering iron. (and some 
blistex if you are not used to soldering...).

Dont use a soldering gun - those things are for plumbers, 
not budding electrotechnicians. An ElCheapo 15 or 30W 
soldering iron would work fine.

The PC normally uses a male connector, so to interface to it, 
you need a female connector of the correct size.  You PC 
may even have both types of connector on the two 
communications ports.


Connect the following pins together:
------------------------------------
RTS to CTS                   Ensures that CTS is always true
DTR to both of DSR and CD    Ensures that DSR and CD are always true
RX to TX                     Loop back data so we can talk to ourselves

A loop-back connector like this is always very handy, so you 
can just as well make a good job of it and screw on a backshell 
and mark it as a loop-back test connector for future reference.


Which is Which?
---------------
Now, one of those two serial ports is COMM1 and the other is 
COMM2, but which one?  Well, you can go hunt for the PC manual, 
or you can go the easy(?) way out and simply try it and see.

If you select the try and see method, you need a copy of Procomm or
HyperTerminal.  HyperTerminal is a buggy little program shipping 
free with Windoze, so if all else fails, use that one and since 
it was free, don't expect too much.

What you need to do is configure the program for a local 
connection, at whatever speed etc you please.  Essentially, put 
your finger on a key and keep it down, if the port works, you 
will see a stream of characters coming back at you via your 
loop-back connector.  After a while of fiddling and swearing,
you should know which connector is COMM1 and which is COMM2.  
Your modem is probably set up as COMM3, a common convention.


Now for the Super Duper Liberty BASIC Teletypewriter!
-----------------------------------------------------
Once you have proven that the serial port works, you have to 
close the serial comms program and it may even be a good idea 
to reboot your PC at this point. With reboot, I mean full 
power off/on, since thanks to another common oversight
in the design of PCs, the UART can lock up beyond salvage 
from Windoze. To add to your woes, the Windoze driver can 
also get stuck from time to time, and may tell you that the 
port is already in use or some other useless complaints, in 
which case you also have to reboot the PC, to convince Windoze
that the port isnt in use after all and is in fact working 
just fine...

If you get "The device is already open" try closing all DOS 
boxes, then quit  and restart LB.  When all else fails, 
reboot your PC.

Finally, you can run the little program tty.bas.  This program 
shows how to open the serial port and send something interactively.  
The main problem with this program is that it halts at an input 
statement, waiting for a user command which means that one 
cannot see any data coming in from another device, until one 
would press Enter.  If you are talking to yourself with a 
loopback connector then this is not a problem, but see what 
happens when you tie two PCs together!


Connecting 2 PCs Together
-------------------------
Right, now that you got that going and want to go on to more 
adventurous things...

To connect 2 PC together, you need a NULL modem cable.  That 
is literally a cable with no modem in the middle.  I would 
suggest that you start your experiments with a single PC and 
2 comm ports.  In the above example, we used a single comm port.  
If you open both comm ports, then you can send messages from 
COMM1 to COMM2 and vice versa and test out your cable in the
process, without getting two PCs locked up, which saves a lot 
of time on rebooting...


A NULL Modem Cable
------------------
There is an almost infinite number of ways to make such a cable.  
The simplest method is a variation of the loopback plug.

Connect the following pins together on each connector:
RTS to CTS
DTR to both CD and DSR

Then run 3 wires (2 or 3 meters, whatever is convenient to reach 
the other PC) between the two connectors for your data connection:
GND to GND
RX to TX
TX to RX

These data wires can be up to 25 meters in length and still 
allow reliable operation.

Now, with some work, you can send files between the PCs, or 
write your own LAN.


Have fun,


Herman
http://www.AerospaceSoftware.com

'*********************************************************************
'Name:         TTY.bas
'Description:  Serial Terminal Demonstration Program
'Copyright (c) 1999, Aerospace Software Ltd., Calgary, Canada
'You may use this program freely
'*********************************************************************

'declarations
   serial = 0              'serial port file handle
   tty = 0                 'terminal window file handle

   rxdata$ = ""            'receive data
   txdata$ = ""            'transmit data
   length = 0              'receive data length

   wait = 0                'delay counter


'*********************************************************************
'Name:         main
'Description:  Main terminal loop
'inputs:       none
'Outputs:      #tty
'              #serial
'*********************************************************************
[main]
   'center the window if the screen is larger than the default
   WindowWidth = 640
   WindowHeight = 480
   UpperLeftX = (DisplayWidth - WindowWidth) / 2
   UpperLeftY = (DisplayHeight - WindowHeight) / 2
   if UpperLeftX <= 0 then
      UpperLeftX = 0
   end if
   if UpperLeftY <= 0 then
      UpperLeftY = 0
   end if

   'open the comm port
   open "COM1:9600,N,8,1" for random as #serial

   'test the serial comms
   gosub [commtest]

   'forever...
[main_loop]
   'poll the window for keyboard input
   gosub [transmit]

   'poll the serial port for data input
   gosub [receive]

   if (TrapClose = "true") goto [quit]
   goto[main_loop]


'*********************************************************************
'Name:         transmit
'Description:  Get a string from a text window
'              and echo it out the serial port
'Inputs:       #tty
'              #serial
'Outputs:      txdata$
'*********************************************************************
[transmit]
   'Wait for user input.
   'Note that data may be coming in while you are stuck in the input
   'function and you'll only see it when you press Enter.
   input "Transmit>"; txdata$

   'print the string to the main window
   'and the serial port
   if (len(txdata$) > 0) then
      'transmit the data
      print #serial, txdata$

      'wait for the data to be transmitted and received
      for wait = 0 to 1000 step 1
      next wait
   end if

   return


'*********************************************************************
'Name:         receive
'Description:  Get character(s) from the serial port
'              and echo it (if any) to the text window
'Inputs:       #serial
'              #tty
'Outputs:      rxdata$
'              length
'*********************************************************************
[receive]
   length = lof(#serial)

   if (length > 0) then
      trace 2
      rxdata$ = input$(#serial, length)
      print rxdata$
   end if

   return


'*********************************************************************
'Name:         commtest
'Description:  test routine
'Inputs:       #serial
'              #tty
'Outputs:      rxdata$
'              length
'              wait
'*********************************************************************
[commtest]
   'send a data string
   print #serial, "Yahoo!"

   'wait for it - 1ms per character at 9600 bps
   for wait = 0 to 1000 step 1
   next wait

   'read the receive buffer
   length = lof(#serial)

   'print it if anything was received
   if (length > 0) then
      rxdata$ = input$(#serial, length)
      print rxdata$
   end if

   return

'*********************************************************************
'Name:         quit
'Description:  close the window and serial port
'Inputs:       #serial
'              #tty
'Outputs;      none
'*********************************************************************
[quit]
   'close the comm port
   close #serial

   end
'******************************* EOF *********************************


---------------------------------------------------------
 Newsletter compiled and edited by: Brosco and Alyce.
 Comments, requests or corrections: Hit 'REPLY' now!
            mailto:brosco@orac.net.au
                       or
           mailto:awatson@mail.wctc.net
---------------------------------------------------------