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

.. _tk_terminal:

UHDAS serial port access gui: 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 (often /dev/ttyUSB*)
- 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


This program can be run to look at 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 a serial port which is
   in use by UHDAS or at least not while UHDAS is running.
   To see a list of configured ports, type:

   ``cat /home/adcp/config/sensor_cfg.py``


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.



Serial Settings (Baud rate, COM Port, etc)
---------------------------------------------

(1) **Starting tk_terminal.py**
(2) **Choose the port**
(3) **Choose the Baud rate**
(4) **Connect to the port**

Under the File menu, choose **Connect to port**.  This opens the port
for communication.  Be sure to **Disconnect** when you are finished,
or if you are going to change settings (or it will get confused).



.. image:: /images/tk_terminal/tk_terminal_start.png
     :alt: setting up tk_terminal.py

**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")

..

Waking up the ADCP
-------------------------

(6) **Establishing Communication**

After setting up the Port and Baud rate, and connecting to
the port (to allow 2-way communication), you must wake up the
instrument.  By sending a BREAK to the instrument, and seeing
the "Wakeup" message, you have established that the above
settings are correct, the cable works, the instrument has power
and can communicate.

RDI documentation will tell you to do these things with BBTALK
but that is unnecessary.  You have tk_terminal.py


Use the **Commands** menu item and choose **Wakeup**


.. image:: /images/tk_terminal/tk_terminal_wakeup.png
     :alt: waking up the ADCP


Sending commands to the ADCP
--------------------------------------------

When troubleshoooting ADCP problems, you may be asked to
send some commands to the instrument.  These can be run with
``tk_terminal.py``; you do not need BBTALK.


With the ``tk_terminal.py`` interface, you can send commands to the
instrument by simply typing in the text box at the bottom of the
window (the one that says **Run** next to it)


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)



.. image:: /images/tk_terminal/tk_terminal_diagnostics.png
     :alt: sending ascii commands to ADCP