***********************************************
Device management with guitastro Python classes
***********************************************

This section explains how to use guitastro to drive a device.

1. Context
**********

A device is a system constituted by:

	* **communication**: Communication means that messages to drive the device are exchanged between guitastro and the device. Messages can be transported by Serial or TCP protocols.
	* **components**: A component is a part of the device identified to realize an astronomical action. For example a focuser is a component. Some devices are constituted by many compenents. For example a camera équiped by a shutter and a filter wheel is a device constituted by 3 components.
	
In Guitastro we define the following **categories** of components:

	* **MountPointing**: It is a mechanical motorized mount able to point a direction in the sky using two axes.
	* **DetectorFocuser**: It is a mechanical motorized motor placed close the detector to able changing the focus. 
	* **SensorDetector**: It is a sensor that deliver data (often an image). 
	* **DetectorShutter**: It is a mechanical shutter placer just front of the sensor. 
	* **DetectorTimer**: It is an electronic device that deliver a date of an exposure (GPS, Glonass, etc.). 

The complete list of supported categories can be listed:

.. code-block:: python

	import guitastro
	print(Component().categories)
		
The communication chanel is the same for all the components included in the same device.
The commands are messages to pilot the components. There are two types of commands:

	* **uniform**: From the side of a Guitastro user, the commands are the same for a given component category. For example to slew a mount the command is always "DO RADEC_GOTO".	
	* **native**: From the side of device controler, the commands are translated by guitastro into the device manufactured grammar. 

A uniform command is constituted by an **action**, an **operation** and optional parameters:

	* **action**: Main actions are GET, SET, DO. GET and SET manage variables and DO manage messages towards the device.
	* **operation**: It is a word that depends on the action.

2. Commands of a component
**************************

A command can be generalized as component/action/operation/parameters

When the component/action = MountPointing/SET, the operation is a variable symbol and parameters is the variable value:

.. code-block:: python

	import guitastro
	comp = ComponentMountPointing()
	comp.command("SET", "target", "RADEC 12h56m -08d45m")
	
When the component/action = MountPointing/GET, the operation is a variable symbol. The result is the variable value:

.. code-block:: python

	import guitastro
	comp = ComponentMountPointing()
	comp.command("GET", "target")

When the component/action/operation = MountPointing/DO/RADEC_GOTO, the operation start a slewing to the target defined in the target variable previously defined:

.. code-block:: python

	import guitastro
	comp = ComponentMountPointing()
	comp.command("SET", "target", "RADEC 12h56m -08d45m")
	comp.command("DO", "GOTO")


A given category of component have a list of operations. For example for a MountPointing:

	* **COORD RADEC**: Returns the current coordinates in the RA,Dec system
	* **COORD HADEC**: Returns the current coordinates in the HA,Dec system
	* **GOTO**: Slew the mount until a target previously defined by a command 

3. Integration of components into devices for Guitastro
*******************************************************

The device codes are written outside the guitastro module.
For a given device, the code is a module. For example, guitastro_device_meade_mount.
The device modules are downloaded in the site of Guitastro.
To drive a device it is necessary to install guitastro and the device module.

4. Simulation and real devices
******************************

Take a example with the device module guitastro_device_meade_mount.
This module has a class Device_MeadeMount. This class is composed by two components: 

	* The file component_mount_pointing_meade_mount provides the class ComponentMountPointingMeadeMount. This class inherits from ComponentMountPointing and adds the method _my_do that send native commands to the real device.
	* The file component_detector_focuser_meade_mount provides the class ComponentDetectorFocuserMeadeMount. This class inherits from ComponentDetectorFocuser and adds the method _my_do that send native commands to the real device.

Consider the component of category MountPointing.
The class ComponentMountPointing inherits from the class Component.
ComponentMountPointing concretes the method _do which provides a
simulator of a mount. kwargs of the class ComponentMountPointing
can be used to give optional parameters.

To summarize:

	* The class **Component** provides basic methods: command, parameters, prop, init and attributes categories, channel, category, log, verbose, actions
	* The class **ComponentMountPointing** override mainly the method prop to define the list of actions/operations and _do for a simulator.
	* The class **ComponentMountPointingMeadeMount** override mainly the method _my_do for real driving of the mount. _my_do is called after _do.
	* The class **Device** provides communication methods: open, close, commandstring, command and provides information method components.
	* The class **Device_MeadeMount** override device class methods to adapt them to the specificities of the real device.

The following example shows how to instanciate and send commands:

.. code-block:: python

	import guitastro
    import guitastro_device_meademount
	dev = Device_MeadeMount()
	print("Components are:")
	for key, val in dev.components().items():
		print(f" * {key} of type {val[0]}")
	dev.open(True)
	dev.commandstring("mount SET target 'RADEC 12h56m -10d23m'")
	dev.commandstring("mount DO GOTO")
	res = dev.commandstring("mount DO COORD")
	print(f"Coordinates of the mount: {res}")
	res = dev.commandstring("focuser DO COORD")
	print(f"Position of the focuser: {res}")

5. Example of a telescope device
*********************************

Deltatau is a controller that is used to drive two TAROT telescopes.
This controller can also drive the focuser.

.. figure:: doc_images/device_telescope.png
	:align: center

6. Example of a camera device
******************************

FLI is a camera manufacturer. FLIPro is a driver for Kepler series cameras.
These camera are equiped by a sensor and a shutter. In this case a third part
provived by the manufacturer must be compiled to create a wrapper extension
of the Python language.

.. figure:: doc_images/device_camera.png
	:align: center

7. Programming a new device
******************************

Be inspired by the over codes. When the module folder is ready, record it
in the Git of Guitastrolib. For example Quickaudine:

.. code-block:: bash

    cd Documents
    cd guitastro_device_quickaudine
    git config --global user.name "A... K..."
    git config --global user.email "a...k...@irap..."
    git init
    git add *
    git commit -m "first commit"    
    git remote add origin https://gitlab.irap.omp.eu/guitastrolib/guitastro_device_quickaudine.git
    git push -u origin master