.. currentmodule:: sardana.pool.controller .. _sardana-controller-overview: =========== Controllers =========== Each different hardware object is directly controlled by a software object called *controller*. This object is responsible for mapping the communication between a set of hardware objects (example: motors) and the underlying hardware (example: a motor controller crate). The *controller* object is also exposed as a Tango_ device. Controllers exist to keep Sardana hardware independent: the :ref:`elements ` offer stable, generic interfaces (move, count, read, ...) on which scans, macros and GUIs are built, while the controller :term:`plug-in` translates those generic operations into the dialect of a particular piece of hardware. To support new hardware only a new controller class has to be written; nothing else in the system needs to change. Usually a controller is capable of handling several hardware objects. For example, a motor controller crate is capable of controlling several motors (generally called *axis* [#]_). The controller objects can be created/deleted/renamed dynamically in a running pool. A specific type of controller needs to be created to handle each specific type of hardware. Therefore, to each type of hardware controller there must be associated a specific controller software component. You can write a specific controller software component (:term:`plug-in`) that is able to communicate with the specific hardware. You can this way extend the initial pool capabilities to talk to all kinds of different hardware. .. figure:: /_static/sardana_server_np200.png :width: 500 :align: center A diagram representing a sardana server with a controller class *NSC200Controller*, an instance of that controller *np200ctrl_1* "connected" to a real hardware and a single motor *npm_1*. Controller-element relation =========================== A sardana controller is responsible for its sardana element(s). Example: an IcePAP hardware motor controller can *control* up to 128 individual motor axes. In the same way, the corresponding software motor controller *IcepapController* will *own* the individual motor axes. .. figure:: /_static/sardana_server_icepap.png :width: 500 :align: center A diagram representing a sardana server with a controller class *IcepapController*, an instance of that controller *icectrl_1* "connected" to a real hardware and motors *icem_[1..5]*. Controller types ================ These are the different types of controllers recognized by sardana: :class:`MotorController` You should use/write a :class:`MotorController` sardana :term:`plug-in` if the device you want to control has a *moveable* interface. The :class:`MotorController` actually fulfills a *changeable* interface. This means that, for example, a power supply that has a current which you want to *ramp* could also be implemented as a :class:`MotorController`. Example: the Newport NSC200 motor controller :class:`CounterTimerController` This controller type is designed to control a device capable of counting scalar values (and, optionally, have a timer). Example: The National Instruments 6602 8-Channel Counter/Timer :class:`ZeroDController` This controller type is designed to control a device capable of supplying scalar values. The :term:`API` provides a way to obtain a value over a certain acquisition time through different algorithms (sum, average, integral). Example: an electrometer :class:`OneDController` This controller type is designed to control a device capable of supplying 1D values. It has a very similar :term:`API` to :class:`CounterTimerController`. Example: an :term:`MCA` :class:`TwoDController` This controller type is designed to control a device capable of supplying 2D values. It has a very similar :term:`API` to :class:`CounterTimerController`. Example: a :term:`CCD` :class:`TriggerGateController` A controller designed to control synchronization devices (digital trigger and/or gate generators) used to synchronize the acquisition of experimental channels (see :ref:`sardana-explanation-synchronization`). :class:`PseudoMotorController` A controller designed to export *virtual motors* that represent a new view over the actual physical motors. Example: A slit pseudo motor controller provides *gap* and *offset* virtual motors over the physical blades :class:`PseudoCounterController` A controller designed to export *virtual counters* that represent a new view over the actual physical counters/0Ds. :class:`IORegisterController` A controller designed to control hardware registers. Controllers as plug-ins ======================= Controller plug-ins can be written in Python_. Each controller code is basically a Python_ class that needs to obey a specific :term:`API`: it declares its properties, attributes and custom commands as class members (from which the configuration interface is generated automatically) and implements the methods of its controller type (e.g. for a motor controller: ``StateOne``, ``ReadOne``, ``StartOne``, ``AbortOne``, ...). Here is an extract of a Python_ motor controller able to talk to a Newport NSC200 motor controller:: from sardana.pool.controller import MotorController, \ Type, Description, DefaultValue class NSC200Controller(MotorController): """This class is the Tango Sardana motor controller for the Newport NewStep handheld motion controller NSC200.""" ctrl_properties = \ { 'SerialCh' : { Type : str, Description : 'Communication channel name for the serial line' }, 'SwitchBox': { Type : bool, Description : 'Using SwitchBox', DefaultValue : False}, 'ControllerNumber' : { Type : int, Description : 'Controller number', DefaultValue : 1 } } def StateOne(self, axis): status = int(self._queryCommand("TS")) status = self._STATE_MAP.get(status, State.Unknown) ... return status, "OK", switchstate def ReadOne(self, axis): return float(self._queryCommand("TP")) def StartOne(self, axis, pos): self._setCommand("PA", pos) def AbortOne(self, axis): self._setCommand("ST", "") Besides values, a controller may also expose *actions* — calibrating an axis, resetting a counter — as :ref:`custom commands `. These become Tango_ commands on the element and controller devices, next to the standard ones. Plug-in discovery ================= Controller classes are not registered anywhere by hand. The Pool discovers them by scanning the directories listed in its ``PoolPath`` Tango_ device property: every Python_ module found there is inspected and the controller classes it defines become available for instantiation. Creating a controller instance then only requires giving the class name, an instance name and values for the declared controller properties. This makes the set of supported hardware a deployment time decision rather than a build time one. .. seealso:: :ref:`sardana-controller-howto` How to write controller :term:`plug-in`\s in sardana :ref:`sardana-controller-api` the controller :term:`API` :class:`~sardana.tango.pool.Controller.Controller` the controller tango device :term:`API` .. rubric:: Footnotes .. [#] The term *axis* will be used from here on to refer to the ID of a specific hardware object (like a motor) with respect to its *controller*. .. _Tango: http://www.tango-controls.org/ .. _Python: http://www.python.org/