Introduction
************

The Telescope Control System (Tcs) at the Hobby-Eberly Telescope (Het)
consists of a approximately ten control system programs and associated
subsystems. There is a built-in messaging interface to allow
communications between systems.  Control systems act as servers and can
also be clients of the other control systems. About half the control
systems within Tcs manage hardware associated with pointing and
operating the telescope. The Tcs software is written in C++. In order
to allow easy program development and scripting capabilities a set of
python interfaces have been developed.  This documentation describes
the Python interface and the application programming interface (API)
for the Tcs.

The Python interface to the Tcs Control System at Het consists of the
**Tcs Python** modules and the **Hetlib** package.  **Hetlib**
provides wrappers around some of the routines in the **Tcs Python**
modules as well as scripts to assist in the operation of the telescope
system. These packages and modules are available to other software
developers and provide an easy interface to the Tcs Control Systems.

Note that the **Tcs Python** modules will be migated to the **pytcs**
package at some future date which will be soon I hope.



Definition of Terms
===================

.. _Control_System_def-label:

Control System
--------------

A Control System is a standalone program. It may receive :ref:`Handler_def-label`
requests (basically commands) from clients and it may emit events that
other programs can receive. The control systems with in the Tcs are
the tracker_server, tcs_server, pasServer, pfipserver, legacyServer,
tcsGui, apcServer, tcs_monitor, tcs_log_relay, and tcsnamed.


.. _Subsystem_def-label:

Subsystem
---------

A subsystem is the name for a part of a
:ref:`Control_System_def-label`.  For example, the legacyServer
controls the dome and shutter as well as collecting the weather
information.  The dome, shutter, and weather are all subsystems of the
legacy :ref:`Control_System_def-label`.

.. _Route_def-label:

Route
-----

A route is a URL (Uniform Resource Locator) that is used by clients to
talk to the :ref:`Control_System_def-label`. Requests to a
:ref:`Control_System_def-label` are sent to the route URL. The URL is
of the form ``aaa://xxx.xxx.xxx.xxx:nnnnn`` where aaa is the protocol
(e.g. tcp or udp), xxx.xxx.xxx.xxx is an IP address, and nnnnn is a
port number. For example, the route to the tcs_server is
tcp://192.168.66.31:30300. All :ref:`Control_System_def-label` within
Tcs use the TCP protocol.  Routes are available from the tcsnamed
server.

.. _Event_Route_def-label:

Event-route
-----------

An event route is a URL that is used by a
:ref:`Control_System_def-label` to emit :ref:`Events_def-label`.
Clients and other :ref:`Control_System_def-label` may listen to these
:ref:`Events_def-label` to obtain state or activity information about the
:ref:`Control_System_def-label`.  The Event-route's port number is normally
one higher than the :ref:`Control_System_def-label`
:ref:`Route_def-label` port. For example, the tcs_server route is on
port 30300 and its event-route is on port 30301.  Event-routes are
available from the tcsnamed server.

.. _Handler_def-label:

Handler
-------

A handler is a function within a :ref:`Control_System_def-label` that
may be called by a client.  A handler is called through the
:ref:`Route_def-label` to the :ref:`Control_System_def-label`.  When
the handler completes a return value is sent to the client. Some
handlers return immediately even though the action may take longer and
the client will have to look at :ref:`Events_def-label` from the
:ref:`Control_System_def-label` in order to see when the action might
be complete.

.. _Events_def-label:

Events
------

Events are emitting by a :ref:`Control_System_def-label` via a
broadcast on the :ref:`Event_Route_def-label` URL.  Clients may
subscribe to events from some or all :ref:`Control_System_def-label`. Clients
are not able to pick which events from a particular :ref:`Control_System_def-label`
they subscribe to. Client must filter events on their end and provide
any call back required to handle the event.