Basic Usage
===========

This page assumes a successful `installation <install.html>`__ of
NQontrol and all dependencies.

Hello Servo Example
-------------------

Here is a minimalistic, ``hello world``-like example to show, how to
control a servo using the python terminal or a little script.

.. code:: ipython3

    # Importing a ServoDevice is enough
    from nqontrol import ServoDevice
    
    # Create a new servo device object, connecting to adwin with the device number 0.
    # Number 0 is reserved for a virtual mock device for testing.
    sd = ServoDevice(0)
    
    # Print the timestamp
    print(f'Uptime {sd.timestamp}s')
    
    # Get a servo object to control it.
    s = sd.servo(1)
    
    # enable in and output
    s.inputSw = True
    s.outputSw = True


.. parsed-literal::

    WARNING:root:Running with mock device!


.. parsed-literal::

    Uptime 0s


Using a signal generator for the input you will now get the same signal
on the output. (That is true for signals below about 15 kHz.)

Apply a ServoDesign
-------------------

To use a servo for a real control loop we want to have some filters. The
full documentation is in the `OpenQlab
docs <https://las-nq-serv.physnet.uni-hamburg.de/python/openqlab/servodesign.html>`__.

.. code:: ipython3

    # Add an integrator and a lowpass
    s.servoDesign.clear()
    s.servoDesign.integrator(1e2)
    s.servoDesign.lowpass(5e3)
    
    # Add transfer function of a real system
    from openqlab import io
    s.servoDesign.plant = io.read("transfer_function.csv")
    
    # Plot how it looks analytically
    import matplotlib.pyplot as plt
    s.servoDesign.plot()
    plt.show()



.. image:: usage_files/usage_3_0.png


.. code:: ipython3

    # Apply it to our servo
    s.applyServoDesign()
    
    # Control, what happens with the servo
    s.filters




.. parsed-literal::

    [[1.0015692243574656, -0.9999968584122811, 0.0, -0.9968633318334381, 0.0],
     [0.005519854739225482, -1.7786050226116845, 0.8007755579457131, 2.0, 1.0],
     [1.0, 0, 0, 0, 0],
     [1.0, 0, 0, 0, 0],
     [1.0, 0, 0, 0, 0]]



.. code:: ipython3

    print(s.filterStates)
    print(s.gain)


.. parsed-literal::

    [True, True, False, False, False]
    1.0015692243574656


Control Filters
---------------

.. code:: ipython3

    # Disable all filters
    s.filterStates = [False] * 5
    
    # Enable the second (index = 1) filter
    s.filterState(1, True)
    
    print(s.filterStates)


.. parsed-literal::

    [False, True, False, False, False]


Enable a Ramp
-------------

.. code:: ipython3

    # Choose a slow ramp with a frequency of 1 Hz.
    # Amplitude = 4
    s.enableRamp(frequency=1, amplitude=4)

Take data and Plot
------------------

.. code:: ipython3

    # Take data and store them in a pandas.DataFrame
    data = s.takeData()
    
    # Plot them using Matplotlib
    data.plot(subplots=True)



.. image:: usage_files/usage_11_0.png


Start Realtime Plotting
-----------------------

.. code:: ipython3

    # Start plotting in a background process
    s.realtimePlot(multiprocessing=True)
    
    # disable plotting the output
    s.realtime['ydata'] = ['input', 'aux']
    
    # set constant y limit from -3 to 5 
    s.realtime['ylim'] = (-3, 5)
    
    # stop realtime plotting
    s.stopRealtimePlot()