*macro_extensions.motors*
=========================

Module contains helper funcions to access karabo devices with a pre-defined motor interface.
Main usage of the module is to use unified api to control motors.
Currently following Karabo device classes are supported:

- BeckhoffMC2Base
- BeckhoffMC2Beckhoff
- BeckhoffMC2Technosoft
- BeckhoffMC2Elmo
- BeckhoffMC2Hexapod
- BeckhoffSimpleMotor
- DoocsPhaseshifter
- CrystalManipulator
- CrystalManipulatorGroup
- DoocsOpticalDelay
- DoocsPhaseshifter
- DoocsUndulatorEnergy
- JJAttenuator
- MonoChromator
- MonoChromatorGroup
- MonoChromatorEnergyChanger
- PpLaserDelayCopy
- RobotManipulatorStaubli
- SlitSystem
- SoftMono
- X2TimerML

If the requested device class is not within the supported classes then typical
motor attributes (*actualPosition*, *targetPosition*, *state*) and slots (*move*, *stop*)
are used. If one of the attributes or slots is not available in the device class
then an exception is raised.

*getMotor*, *connectMotor*
--------------------------

Methods *getMotor* and *connectMotor* return a *Motor* class instance which inherits 
karabo middlelayer proxy and has additional attributes:

 - *isReady*: identifies if motor is ready for a movement.
 - *isInterlocked*: identifies if motor is interlocked (not possible to move before interlock conditions are released).
 - *position*: current motor position.
 - *targetPosition*: target position.
 - *velocity*: velocity.
 - *isSWLimitLow*: is motor at the soft low limit.
 - *isSWLimitHigh*: is motor at the soft high limit.
 - *isCWLimit*: is motor at the clock wise limit switch.
 - *isCCWLimit*: is motor at the counter-clockwise limit switch
 - *isLimits*: Returns True if at least one of the limits is reached. Otherwise False.

and convenience functions:

 - *moveTo*, *moveToWait*: non-blocking and blocking move to target position.
 - *moveRelative*, *moveRelativeWait*: non-blocking and blocking move by a relative position.

*getMotor* returns motor instance for local and temporal usage and 
*connectMotor* returns motor instance for permanent access. Preferably
use *getMotor* method within the *with* statement.

.. code-block:: Python

    from karabo.middlelayer import Double, Macro, MacroSlot, String

    from macro_extensions.motors import getMotor

    class TestGetMotor(Macro):
        motorName = String(defaultValue="TEST/MOTOR/1")
        target = Double(defaultValue=10)

        @MacroSlot()
        async def move(self):
            with (await getMotor(self.motorName.value)) as motor:

                init_position = motor.position
                # Moves motor to the target position and 
                # waits till motor is in on of the ready states
                await motor.moveToWait(self.target.value)
   
                # Moves motor to the target position. A non blocking call
                await motor.moveTo(init_position)

Example of using *connectMotor*:

.. code-block:: Python

    from karabo.middlelayer import (
        Macro, MacroSlot, VectorDouble, VectorString, waitUntil)

    from asyncio import gather
    from macro_extensions.motors import connectMotor

    class TestConnectMotor(Macro):
        motorNames = VectorString(defaultValue=["TEST/MOTOR/1", "TEST/MOTOR/2"])
        targets = VectorDouble(defaultValue=[10, 100])

        @MacroSlot()
        async def move(self):

            motors = [await connectMotor(motorName) for motorName in self.motorNames]
            init_positions = [motor.position for motor in motors]

            # Moving motors sequentially
            for index, motor in enumerate(motors):
                target = self.targets[index]
                print(f"Moving motor {motor.deviceId} to {target}")
                await motor.moveToWait(target)

            # Moving motors simultaneously and wait till all motors are ready
            fut = [motor.moveToWait(init_positions[index]) for index, motor in enumerate(motors)]
            await gather(*fut)

            # Moving motors simultaneously and do not wait till motors are ready
            fut = [motor.moveTo(self.targets[index]) for index, motor in enumerate(motors)]
            await gather(*fut)

            # Wait till any of the motor is ready
            await waitUntil(lambda: any(motor.isReady for motor in motors))
            print("Done!")


*moveTo*, *moveToWait*, *moveRelative*, *moveRelativeWait*
----------------------------------------------------------

- *moveTo*, *moveToWait*: non-blocking and blocking move to target position.
- *moveRelative*, *moveRelativeWait*: non-blocking and blocking move by a relative position.

Example:

.. code-block:: Python

    from karabo.middlelayer import  Macro, MacroSlot, VectorDouble, VectorString

    from macro_extensions.motors import moveTo, moveToWait, moveRelative, moveRelativeWait

    class TestMoveTor(Macro):
        motorName = String(defaultValue="TEST/MOTOR/1")
        targets = Double(defaultValue=10)

        @MacroSlot()
        async def moveToExample(self):
            # Move motor to target position and wait till it is ready
            await moveToWait(self.motorName, target)

            # Move motor by a relative position and wait till it is ready
            await moveRelativeWait(self.motorName, -10)