.. ......................................
.. UHDAS/CODAS restructured text document
.. ......................................


UHDAS serial port access (gui)
==============================

Description of tk_terminal.py
-----------------------------

The UHDAS computer has a terminal emulation program 
for access to serial ports.  The program allows
the user "adcp" to 

- choose a serial port
- change baud rate
- change parity, stop bit, [etc]
- send commands
- view data on the specified serial port
- capture a dialog or incoming messages

This program is written in python and tk and is accessed on the command line as:

::

 tk_terminal.py
 /home/currents/programs/uhdas/serial/tk_terminal.py


This program can be run to assess ascii serial data streams or to 
communicate with an Ocean Surveyor, Workhorse, or Broadband RDI ADCP.
To communicate with an NB150, use **rditerm.py**

.. NOTE::

   Do not run this program to access an serial port which is
   in use by UHDAS.  To see a list of configured ports, type:

   grep tty /home/adcp/config/sensor_cfg.py

It is safest to use this program when the UHDAS gui is not running
but if you are *sure* a given port is not in use, you can interact 
with that port using this program even if UHDAS is running.  

UHDAS locks the serial ports so it will not be confused. Do not
use tk_terminal.py to access any ports listed here:

::

 ls /var/lock/tty*


``tk_terminal.py`` should not allow you to choose a serial port that
is locked, but it is always safest to check.  Error messages are 
written to the terminal window which called the program.


How to use
----------

(1) Type on the command line

::

 tk_terminal.py

(2) **Choose the port**

Use the Port menu to choose the Device.  For example the
first on-board serial port is called /dev/ttyS0.  You will
probably not need to use View/Set, but if you need to change
parity for instance, that is where to do it.

(3)  **Choose the Baud rate**

Use the Baud menu to choose baud rate.  

(4) **Connect to the port**

Under the File menu, choose **Connect to Port**.  This opens the port
for communication.

(5) **Saving input**

If the serial port is connected to a device with serial messages
spewing forth, you should see those in the tk_terminal window.  To
stop the flow, choose **Disconnect** from the File menu.

The rest of the menu options under the File menu are related to saving 
input.  You can 

- clear the screen ("clear")
- save what exists there ("save previous")
- start a log file ("start saving")
- stop a log file ("stop saving")
- close the connection ("Disconnect")

(6) **Sending Commands**

There are two kinds of commands that can be sent to an instrument

- **BREAK** 

  This is a long pulse sent (to instrument such as an ADCP)
  to wake it up.  After the serial port is set up, you can send 
  a break to an instrument under the Command menu

- **ascii commands** 

  Use: for instance, running diagnostic tests on an ADCP
  or (in desparation) sending commands to an Ashtech.  To send an ascii
  command to an instrument, type the command in the bottom panel
  where it says "Transmit line:", then send it by hitting the
  <return> key.

(7) **ADCP troubleshooting**

Most RDI ADCPs allow you to start figuring out the commands they know
by typing a **?** (question mark).  If you type a **?** you will see what
kinds of commands they know. 

For example, the diagnostic tests on the ocean surveyor are usually
commands that start with "P".  You can send **P?** to see what they are.

.. WARNING::

  **DO NOT PING OCEAN SURVEYOR IN AIR**

A similar approach works with a BB or Workhorse ADCP.  

  * Type type **?**, 
  * look for a menu item for tests
  * and type that letter followed by **?**.
  * NB150 is much more cryptic and you have to read the manual

.. NOTE::

  It is OK to ping **fixed** transducers in air, (BB300, NB150 or Workhorse)