### Motion Synchronization and Helper Utilities

Source: https://pipython.physikinstrumente.com/quickstart.html

Demonstrates how to wait for motion completion using manual loops or the built-in pitools helper functions.

```python
from time import sleep
# Manual wait
pidevice.MOV(axes, targets)
while not all(list(pidevice.qONT(axes).values())):
    sleep(0.1)

# Using pitools helper
from pipython import pitools
pidevice.MOV(axes, targets)
pitools.waitontarget(pidevice, axes)
```

--------------------------------

### Establish Device Connection

Source: https://pipython.physikinstrumente.com/quickstart.html

Demonstrates how to connect to a PI controller using the GCSDevice class. It shows both standard instantiation and the recommended context manager approach to ensure connections are closed properly.

```python
from pipython import GCSDevice
pidevice = GCSDevice('C-884')
pidevice.InterfaceSetupDlg()
print(pidevice.qIDN())
pidevice.CloseConnection()
```

```python
from pipython import GCSDevice
with GCSDevice('C-884') as pidevice:
    pidevice.InterfaceSetupDlg()
    print(pidevice.qIDN())
pidevice.CloseConnection()
```

--------------------------------

### GCS Getter Function Usage

Source: https://pipython.physikinstrumente.com/quickstart.html

Shows how to retrieve data from controllers using getter functions like qPOS. Demonstrates handling of return values as dictionaries and accessing data by keys.

```python
# GCS 2.0
pidevice.qPOS(['X', 'Y'])
pidevice.qPOS('X')
pidevice.qPOS(1)
pidevice.qPOS()

# GCS 3.0
pidevice.qPOS('AXIS_1')
pidevice.qPOS()

# Accessing returned dictionary data
pos = pidevice.qPOS([1, 2, 3])
print(pos[1])
```

--------------------------------

### Read Big Data with GCS 2.0 (qDRR)

Source: https://pipython.physikinstrumente.com/quickstart.html

Illustrates how to read a large amount of data using the `qDRR()` command in GCS 2.0. It initiates a background read and monitors the `bufstate` property for completion.

```python
header = pidevice.qDRR(1, 1, 8192)
while pidevice.bufstate is not True:
    print('read data {:.1f}%...'.format(pidevice.bufstate * 100))
    sleep(0.1)
data = pidevice.bufdata

```

--------------------------------

### Configure Debug Logging

Source: https://pipython.physikinstrumente.com/quickstart.html

Configures the internal logger to output debug information to the console.

```python
from pipython import PILogger, DEBUG, INFO, WARNING, ERROR, CRITICAL
PILogger.setLevel(DEBUG)
```

--------------------------------

### Send Textual GCS Commands

Source: https://pipython.physikinstrumente.com/quickstart.html

Shows how to send GCS commands as raw strings to the controller using `read()`, `read_gcsdata()`, and `send()`. This bypasses the library's predefined functions but requires manual error checking if enabled.

```python
print(pidevice.read('POS?'))
print(pidevice.read_gcsdata('DRR? 1 100 1'))
pidevice.send('MOV X 1.23')

```

--------------------------------

### GCS Setter Function Arguments

Source: https://pipython.physikinstrumente.com/quickstart.html

Illustrates the various ways to pass arguments to setter functions like MOV, supporting dictionaries, lists, or single values for both GCS 2.0 and GCS 3.0 protocols.

```python
# GCS 2.0
pidevice.MOV({'X': 1.23, 'Y': 2.34})
pidevice.MOV(['X', 'Y'], [1.23, 2.34])
pidevice.MOV('X', 1.23)

# Numeric identifiers
pidevice.MOV({1: 1.23, 2: 2.34})
pidevice.MOV([1, 2], [1.23, 2.34])
pidevice.MOV(1, 1.23)

# GCS 3.0
pidevice.MOV({'AXIS_1': 1.23, 'AXIS_2': 2.34})
pidevice.MOV(['AXIS_1', 'AXIS_2'], [1.23, 2.34])
pidevice.MOV('AXIS_1', 1.23)
```

--------------------------------

### Read Big Data with GCS 3.0 (qREC_DAT)

Source: https://pipython.physikinstrumente.com/quickstart.html

Demonstrates reading large datasets using `qREC_DAT()` in GCS 3.0. Similar to GCS 2.0, it uses a background task and `bufstate` to track read progress.

```python
header = pidevice.qREC_DAT('REC_1', 'ASCII', 1, 1, 8192)
while pidevice.bufstate is not True:
    print('read data {:.1f}%...'.format(pidevice.bufstate * 100))
    sleep(0.1)
data = pidevice.bufdata

```

--------------------------------

### Raise GCSError with Readable Message

Source: https://pipython.physikinstrumente.com/quickstart.html

Shows how to manually raise a `GCSError` exception, translating a numeric error code into a human-readable message. This is useful for debugging or providing user feedback.

```python
from pipython import GCSError, gcserror
raise GCSError(gcserror.E_1024_PI_MOTION_ERROR)
>>> GCSError: Motion error: position error too large, servo is switched off automatically (-1024)

```

--------------------------------

### Configure Record Sources and Options

Source: https://pipython.physikinstrumente.com/datarecorder20.html

Provides examples for mapping record options (measurements) to specific sources (axes or channels) using the Datarecorder class.

```python
# Set recording of two values for one axis
drec.options = [datarectools.RecordOptions.ACTUAL_POSITION_2,
                datarectools.RecordOptions.COMMANDED_POSITION_1]
drec.sources = pidevice.axes[0]

# Set recording of one value for two axes
drec.options = datarectools.RecordOptions.ACTUAL_POSITION_2
drec.sources = ['X', 'Y']

# Configure four recordings for specific inputs and axes
drec.sources = [1, 2, 'X', 'Y']
drec.options = [datarectools.RecordOptions.ANALOG_INPUT_81,
                datarectools.RecordOptions.ANALOG_INPUT_81,
                datarectools.RecordOptions.MOTOR_OUTPUT_73,
                datarectools.RecordOptions.COMMANDED_POSITION_1]
```

--------------------------------

### Handle GCSError Exceptions with gcserror Defines

Source: https://pipython.physikinstrumente.com/quickstart.html

Demonstrates how to catch and handle `GCSError` exceptions using predefined error codes from the `gcserror` module. This allows for specific error messages based on the error type.

```python
from pipython import GCSDevice, GCSError, gcserror
with GCSDevice('C-884') as pidevice:
    try:
        pidevice.MOV('X', 1.23)
    except GCSError as exc:
        if exc == gcserror.E_1024_PI_MOTION_ERROR:
            print('There was a motion error, please check the mechanics.')
        else:
            raise

```

--------------------------------

### Send Textual GCS Commands (No Error Check)

Source: https://pipython.physikinstrumente.com/quickstart.html

Utilizes `ReadGCSCommand()` and `GcsCommandset()` to send GCS commands as strings without querying the device for errors, similar to the C++ GCS DLL.

```python
print(pidevice.ReadGCSCommand('POS?'))
pidevice.GcsCommandset('MOV X 1.23')

```

--------------------------------

### Configure Data Recorder with NOW Trigger

Source: https://pipython.physikinstrumente.com/datarecorder30.html

Configures the data recorder with multiple traces for analog inputs and axes, and sets an immediate 'NOW' trigger. This setup arms the recorder, which then triggers automatically after the 'REC_START' command is issued within the arm() method. Finally, it reads the recorded data and header.

```python
from pipython import GCSDevice
from pipython import datarectools, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
drec = datarectools.Datarecorder(pidevice)
drec.record_rate = 1
drec.traces = { 1: [ 'CON_1', 'SENS_1', '0x1021 ], 2: [ 'CON_2', 'SENS_1', '0x101' ]
                3: [ 'AXIS_1', '-', '0x102' ], 4: [ 'AXIS_2', '-', '0x103' ]}
drec.trigger = [ 'NOW', '0', '0' ]
drec.arm()

# No specific trigger is required, because the data recorder triggers itself
# automatically after `REC_START`, which ist called within the `arm()` method.

# Read the recorded values and the header
data = drec.data
header = drec.header
```

--------------------------------

### Arm Datarecorder for Recording in Python

Source: https://pipython.physikinstrumente.com/datarecorder30.html

Arms the data recorder, enabling it to start recording based on the configured settings. This method checks the state, applies configurations (rate, traces, trigger), and sets the recorder to the waiting state.

```python
from pipython import GCSDevice
from pipython import datarectools, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
drec = datarectools.Datarecorder(pidevice)
...
drec.arm()
```

--------------------------------

### Connect to Unknown Devices with GCS DLL

Source: https://pipython.physikinstrumente.com/connect.html

Connects to PI devices with unknown controllers by specifying a dedicated GCS DLL. This allows the library to automatically select the correct DLL for communication. It also provides access to the interface setup dialog.

```python
from pipython import GCSDevice
with GCSDevice(gcsdll='PI_GCS2_DLL.dll') as pidevice:
    pidevice.InterfaceSetupDlg()
```

--------------------------------

### Asynchronous Data Reading with qDRR

Source: https://pipython.physikinstrumente.com/datarecorder20.html

Initiates an asynchronous data read using the qDRR GCS command. This command returns immediately with a header and starts a background task to buffer data. The bufstate property indicates transmission progress (0 to 1) and becomes True when complete. It's crucial to check bufstate to avoid deadlocks during communication.

```python
header = pidevice.qDRR(rectables, offset, numvalues)
while pidevice.bufstate is not True:
    print('Reading data {:.1f}%...'.format(pidevice.bufstate * 100))
    sleep(0.1)
```

--------------------------------

### Get Servo State with pipython

Source: https://pipython.physikinstrumente.com/pitools.html

The pitools.getservo function retrieves the current servo state for specified axes. It returns a dictionary of servo states, or 'False' if the qSVO command is not supported by the controller.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
# Get servo state of axis 'Axis_1'.
servostates = pitools.getservo(pidevice, 'Axis_1')
print(servostates)
```

--------------------------------

### Display Recorded Data with Matplotlib

Source: https://pipython.physikinstrumente.com/datarecorder20.html

Visualizes recorded data using matplotlib. This example assumes data is stored in two record tables and uses the header information (SAMPLE_TIME, NAME0, NAME1) to plot the data over time.

```python
timescale = [header['SAMPLE_TIME'] * i for i in range(len(data[0]))]
pyplot.plot(timescale, data[0], color='red')
pyplot.plot(timescale, data[1], color='blue')
pyplot.xlabel('time (s)')
pyplot.ylabel(', '.join((header['NAME0'], header['NAME1'])))
pyplot.title('Recorded data over time')
pyplot.grid(True)
pyplot.show()
```

--------------------------------

### Get Axis List with pipython

Source: https://pipython.physikinstrumente.com/pitools.html

Retrieves a list of axes from a GCS device using the pipython library. This function can accept a single axis name, a list or tuple of axis names, a dictionary of axes, or 'None' to get all axes. It returns a list of axis names.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Convert the axis string to an axis list.
axes = pitools.getaxeslist(pidevice, 'Axis_1')
print(axes)

['AXIS_1']

# Convert the specified axes to an axis list.
axes = pitools.getaxeslist(pidevice, ('Axis_1', 'Axis_2))
print(axes)

['Axis_1', 'Axis_2']

# Convert the axes dictionary to an axis list.
axes = pitools.getaxeslist(pidevice, {'Axis_1': 1.1, 'Axis_2': 2.5})
print(axes)

['Axis_1', 'Axis_2']

# Get a list of all axes of the controller (here: a controller with three axes).
axes = pitools.getaxeslist(pidevice, None)
print(axes)

['AXIS_1', 'AXIS_2', 'AXIS_3']
```

--------------------------------

### Startup Routine with pipython.pitools

Source: https://pipython.physikinstrumente.com/pitools.html

Initializes a stage into a specific working condition by enabling axes and performing optional actions like writing parameters, referencing, setting servo state, or changing control modes. Axes are always enabled after a successful call.

```python
import pipython
from pipython import pitools

help(pipython.pitools.startup)

startup(pidevice, stages=None, refmodes=None, servostates=True, controlmodes=None, **kwargs)
    Define 'stages', stop all, enable servo on all connected axes and reference the axes with 'refmodes'.
    Defining stages and homing them is done only if necessary.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param stages: Name of stage(s) to initialize as string or list (not tuple!) or 'None' to skip.
    @param refmodes: Referencing command(s) as string (for all stages) or list (not tuple!) or 'None' to skip.
                     Please see the manual of the controller for the valid reference procedure.
                     'refmodes' can be:
                         'FRF': References the stage using the reference position.
                         'FNL': References the stage using the negative limit switch.
                         'FPL': References the stage using the positive limit switch.
                         'POS': Sets the current position of the stage to 0.0.
                         'ATZ': Runs an auto zero procedure.
    @param servostates: Desired servo state(s) as Boolean (for all stages) or dict {axis : state} or 'None' to skip.
                        For controllers with GCS 3.0 syntax:
                            If True the axis is switched to control mode 0x2.
                            If False the axis is switched to control mode 0x1.
    @param controlmodes: Only valid for controllers with GCS 3.0 syntax!
                         Switch the axis to the given control mode:
                             int (for all axes) or dict {axis : controlmode} or 'None' to skip.
                         To skip any control mode switch make sure the servostate is also 'None'!
                         If 'controlmodes' is set (not 'None') the parameter 'servostates' is ignored.
    @param kwargs: Optional arguments with keywords that are passed to sub-functions.


```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Get the stage parameters fom the stage 'M-111.1DG' out of the PIStages3 database and write
# them to the first two axes of the controller. Don't write any parameters to the third axis.
# Make a reference move for the first axis using the 'FNL' command, dont reference the second axis,
# and make a reference move for the third axis unsing the 'FPL' command.

```

--------------------------------

### Disable Error Checking in pipython

Source: https://pipython.physikinstrumente.com/quickstart.html

Disables the automatic 'ERR?' command sent after each command to check for device errors. This can improve communication speed when error checking is not critical.

```python
pidevice.errcheck = False

```

--------------------------------

### Initialize Datarecorder with PIPython

Source: https://pipython.physikinstrumente.com/datarecorder20.html

Demonstrates the initialization of a GCSDevice and the subsequent creation of a Datarecorder instance for data acquisition tasks.

```python
from pipython import GCSDevice
from pipython import datarectools, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
drec = datarectools.Datarecorder(pidevice)
```

--------------------------------

### Startup Servo Control with pipython

Source: https://pipython.physikinstrumente.com/pitools.html

The pitools.startup function is used to control the servo state of axes during device initialization. It can accept lists of axes, their initial states, and optional parameters for different GCS versions.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
# Doing this switches on the servo for the first two axes and turns it off for the third axis.
pitools.startup(pidevice, ['M-111.1DG', 'M-111.1DG', None], ['FNL', None, 'FPL'], [True, True, False])
```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
# Turn on the servo for the first axis, don't change the servo state of the second axis,
# and turn off the servo for the third axis. Don't change the servo state of any other axis
# (if the controller has more than three axes).
pitools.startup(pidevice, None, 'FRF', [True, None, False, ])
```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
# Switch the control mode for the first two axes to 0x2 (Closed Loop Position), and for the
# third axis to 0x4 (Closed Loop Velocity). Don't change the control mode for any other axis
# (if the controller has more than three axes).
pitools.startup(pidevice, None, 'FRF', None, [0x2, 0x2, 0x4, ])
```

--------------------------------

### Connect via PISerial (Windows)

Source: https://pipython.physikinstrumente.com/connect.html

Establishes a serial connection to a PI device on Windows using the PISerial interface. This method is often used for devices connected via a virtual COM port. It requires specifying the COM port and baud rate.

```python
from pipython.pidevice.gcscommands import GCSCommands
from pipython.pidevice.gcsmessages import GCSMessages
from pipython.pidevice.interfaces.piserial import PISerial
with PISerial(port='COM1', baudrate=115200) as gateway:
    messages = GCSMessages(gateway)
    with GCSCommands(messages) as pidevice:
        print(pidevice.qIDN())
```

--------------------------------

### Reset Axis Errors in GCS 3.0

Source: https://pipython.physikinstrumente.com/quickstart.html

Provides a method to reset error states for one or more axes in GCS 3.0. It checks for fault reaction and then calls the `RES()` command for each affected axis.

```python
for axis in device.axes:
    if axis_has_error(device):
        while check_axis_status_bit(device, axis, AXIS_STATUS_FAULT_REACTION_ACTIVE):
            pass
        print('reset axis error: ', axis)
        device.RES(axis)

```

--------------------------------

### Initialize Datarecorder with GCSDevice in Python

Source: https://pipython.physikinstrumente.com/datarecorder30.html

Initializes a GCSDevice and a Datarecorder instance for configuring data recording. This sets up the basic objects needed for subsequent recording configurations.

```python
from pipython import GCSDevice
from pipython import datarectools, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
drec = datarectools.Datarecorder(pidevice)
...
```

--------------------------------

### Wait for Controller Ready with pipython

Source: https://pipython.physikinstrumente.com/pitools.html

Waits until the GCS controller is in a 'ready' state using the pipython library. This is useful for controllers that may not respond immediately after executing long commands. It allows specifying a timeout, predelay, and poll delay for the waiting process.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Wait until the controller is ready.
pitools.waitonready(pidevice)
```

--------------------------------

### POST writewavepoints

Source: https://pipython.physikinstrumente.com/pitools.html

Sends wave points to a wave table on the controller, automatically handling chunking based on device-specific bunch sizes.

```APIDOC
## POST writewavepoints

### Description
Writes wave points to a specified wave table. This function is not supported for GCS 3.0 syntax controllers. It automatically splits large datasets into bunches defined by the controller's capacity.

### Method
POST

### Parameters
#### Request Body
- **pidevice** (object) - Required - Instance of GCS2Commands object.
- **wavetable** (int) - Required - Wave table ID.
- **wavepoints** (list/float) - Required - Wave points to write.
- **bunchsize** (int) - Optional - Number of points per bunch.

### Response
#### Success Response (200)
- **status** (string) - Confirmation of successful write operation.
```

--------------------------------

### Arm and Execute Data Recording

Source: https://pipython.physikinstrumente.com/datarecorder20.html

Shows the workflow for preparing the data recorder by setting sources and options, arming the device, and waiting for the recording process to complete.

```python
drec.options = datarectools.RecordOptions.ACTUAL_POSITION_2
drec.sources = ['X', 'Y']
drec.trigsources = datarectools.TriggerSources.POSITION_CHANGING_COMMAND_1
drec.arm()

# Wait for recording to finish
drec.wait()
```

--------------------------------

### Connect via PISerial (Linux)

Source: https://pipython.physikinstrumente.com/connect.html

Establishes a serial connection to a PI device on Linux using the PISerial interface. This method is used for devices connected via RS-232 or virtual COM ports. It requires specifying the serial port (e.g., '/dev/ttyS0') and baud rate.

```python
from pipython.pidevice.gcscommands import GCSCommands
from pipython.pidevice.gcsmessages import GCSMessages
from pipython.pidevice.interfaces.piserial import PISerial
with PISerial(port='/dev/ttyS0', baudrate=115200) as gateway:
    messages = GCSMessages(gateway)
    with GCSCommands(messages) as pidevice:
        print(pidevice.qIDN())
```

--------------------------------

### GET getmintravelrange

Source: https://pipython.physikinstrumente.com/pitools.html

Retrieves the maximum travel ranges in the negative direction for specified axes on a connected PI controller.

```APIDOC
## GET getmintravelrange

### Description
Retrieves the minimum travel range for specified axes. Returns a dictionary mapping axis names to their respective minimum travel range values.

### Method
GET

### Parameters
#### Request Body
- **pidevice** (object) - Required - Instance of GCS2Commands or GCS30Commands.
- **axes** (string/list) - Required - Axis name, list of axes, or None for all axes.

### Response
#### Success Response (200)
- **result** (dict) - Dictionary of {axis: minimum_travelrange}

### Response Example
{
  "Axis_1": -5.0,
  "Axis_2": -5.0
}
```

--------------------------------

### POST waitonfastalign

Source: https://pipython.physikinstrumente.com/pitools.html

Blocks execution until the specified fast alignment processes have completed on the controller.

```APIDOC
## POST waitonfastalign

### Description
Waits for fast alignment processes to finish. Not supported for GCS 3.0 syntax. Includes configurable timeouts and polling delays.

### Method
POST

### Parameters
#### Request Body
- **pidevice** (object) - Required - Instance of GCS2Commands object.
- **name** (string/list) - Optional - Name of process(es) to wait for.
- **timeout** (float) - Optional - Timeout in seconds (default 300).
- **polldelay** (float) - Optional - Delay between polls in seconds (default 0.1).

### Response
#### Success Response (200)
- **status** (string) - Confirmation that processes have finished.
```

--------------------------------

### Connect via PISocket (TCP/IP)

Source: https://pipython.physikinstrumente.com/connect.html

Establishes a TCP/IP connection to a PI device using the PISocket interface. This method is suitable for devices accessible over a network. It requires the device's IP address and port number.

```python
from pipython.pidevice.gcscommands import GCSCommands
from pipython.pidevice.gcsmessages import GCSMessages
from pipython.pidevice.interfaces.pisocket import PISocket
with PISocket(host='192.168.178.42', port=50000) as gateway:
    messages = GCSMessages(gateway)
    with GCSCommands(messages) as pidevice:
        print(pidevice.qIDN())
```

--------------------------------

### Wait for Piezo Walk Completion (Python)

Source: https://pipython.physikinstrumente.com/pitools.html

The waitonwalk function waits until the remaining number of steps for specified piezo walk channels in an open-loop step move is zero. It requires a GCS2Commands object and channel identifiers. This function is not supported for controllers with GCS 3.0 syntax.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Wait until the remaining number of steps for piezo walk channel 1 is zero.
pitools.waitonwalk(pidevice, 1)

# Wait until the remaining number of steps for piezo walk channels 1 and 2 is zero.
pitools.waitonwalk(pidevice, [1, 2])
```

--------------------------------

### Write wave points to controller using Python

Source: https://pipython.physikinstrumente.com/pitools.html

Sends wave points to a specified wave table on the controller. The function automatically handles splitting large datasets into manageable bunches based on the device-specific bunch size.

```python
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Write wave points in bunches of 10 values to wave table 1
pitools.writewavepoints(pidevice, 1, WAVEPOINTS_AS_ARRAY, 10)
```

--------------------------------

### Enumerate and Connect to TCP/IP Devices

Source: https://pipython.physikinstrumente.com/connect.html

Scans for available TCP/IP devices using `EnumerateTCPIPDevices` and allows the user to select and connect to a specific device. A mask can be used to filter the search results.

```python
from pipython import GCSDevice
with GCSDevice() as pidevice:
    devices = pidevice.EnumerateTCPIPDevices(mask='C-884.4DB')
    for i, device in enumerate(devices):
        print('{} - {}'.format(i, device))
    item = int(input('Select device to connect:'))
    pidevice.ConnectTCPIPByDescription(devices[item])
    print('connected: {}'.format(pidevice.qIDN().strip()))
```

--------------------------------

### Configure and arm the data recorder

Source: https://pipython.physikinstrumente.com/datarecorder30.html

Sets up traces, defines a trigger based on a MOV command, and arms the device for data acquisition.

```python
drec.record_rate = 1
drec.traces = { 1: [ 'AXIS_1', '-', '0x102' ], 2: [ 'AXIS_1', '-', '0x103' ]}
drec.trigger = [ 'MOV', 'AXIS_1', '0' ]
drec.arm()
pidevice.MOV('AXIS_1', 1.0)
pitools.waitontarget(pidevice, 'AXIS_1')
```

--------------------------------

### Retrieve Servo States with PIPython

Source: https://pipython.physikinstrumente.com/pitools.html

Demonstrates how to query the servo status (closed-loop vs open-loop) for specific axes or all axes using the pitools.getservo function.

```python
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Get servo states of axes 'Axis_1' and 'Axis_2'
servostates = pitools.getservo(pidevice, ['Axis_1', 'Axis_2'])
print(servostates)

# Get servo states of all axes
all_servostates = pitools.getservo(pidevice, None)
print(all_servostates)
```

--------------------------------

### Connect via PIUSB (Linux)

Source: https://pipython.physikinstrumente.com/connect.html

Establishes a direct USB connection to a PI device on Linux using the PIUSB interface. This method is for devices that support native USB communication. It requires the device's serial number and PID.

```python
from pipython.pidevice.gcscommands import GCSCommands
from pipython.pidevice.gcsmessages import GCSMessages
from pipython.pidevice.interfaces.piusb import PIUSB
with PIUSB() as gateway:
    gateway.connect(serialnumber='1234567890', pid=0x1234)
    messages = GCSMessages(gateway)
    with GCSCommands(messages) as pidevice:
        print(pidevice.qIDN())
```

--------------------------------

### Connect to Single Device via USB

Source: https://pipython.physikinstrumente.com/connect.html

Establishes a native USB connection to a PI USB controller. This method is supported on both Windows and Linux systems. The `serialnum` can be a string or a device identification from `EnumerateUSB`.

```python
from pipython import GCSDevice
with GCSDevice() as pidevice:
    pidevice.ConnectUSB(serialnum = '123456789')
    print('connected: {}'.format(pidevice.qIDN().strip()))
```

--------------------------------

### Connect to Single Device via Dialog (Windows)

Source: https://pipython.physikinstrumente.com/connect.html

Connects to a single device using the GCS DLL's graphical user interface on Windows. The `InterfaceSetupDlg` method can optionally take a key to store and retrieve connection settings from the Windows registry.

```python
from pipython import GCSDevice
with GCSDevice() as pidevice:
    pidevice.InterfaceSetupDlg()
    print('connected: {}'.format(pidevice.qIDN().strip()))
```

```python
from pipython import GCSDevice
with GCSDevice() as pidevice:
    pidevice.InterfaceSetupDlg('MyTest')
    print('connected: {}'.format(pidevice.qIDN().strip()))
```

--------------------------------

### METHOD waitontarget

Source: https://pipython.physikinstrumente.com/pitools.html

Waits until all specified closed-loop axes have reached their target position.

```APIDOC
## METHOD waitontarget

### Description
Blocks execution until the specified closed-loop axes are on target. Useful for synchronizing motion commands.

### Method
Python Function Call

### Parameters
- **pidevice** (GCS2Commands/GCS30Commands) - Required - The controller device instance.
- **axes** (str/list/tuple/None) - Optional - Axis identifier(s) to monitor. Defaults to None (all axes).
- **timeout** (float) - Optional - Timeout in seconds. Default: 300.
- **predelay** (float) - Optional - Delay before querying state. Default: 0.
- **postdelay** (float) - Optional - Delay after reaching target. Default: 0.
- **polldelay** (float) - Optional - Delay between status polls. Default: 0.1.

### Request Example
```python
pitools.waitontarget(pidevice, ['Axis_1', 'Axis_2'])
```

### Response
#### Success Response
- **None** - Returns nothing upon successful completion.
```

--------------------------------

### Configure Data Recorder Sample Rate

Source: https://pipython.physikinstrumente.com/datarecorder20.html

Shows how to set the recording frequency using the samplefrequ property and retrieve the rate in various units like servo cycles and seconds.

```python
drec.samplefrequ = 1000
print('data recorder rate: {:d} servo cycles'.format(drec.samplerate))
print('data recorder rate: {:.g} seconds'.format(drec.sampletime))
print('data recorder rate: {:.2f} Hertz'.format(drec.samplefrequ))
```

--------------------------------

### Execute Blocking Motion with moveandwait

Source: https://pipython.physikinstrumente.com/pitools.html

Moves specified axes to target positions and blocks execution until all target positions are reached. Supports single axes, lists, or dictionary mappings.

```python
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Move single axis
pitools.moveandwait(pidevice, 'Axis_1', 1.1)

# Move multiple axes using lists
pitools.moveandwait(pidevice, ['Axis_1', 'Axis_2'], [1.1, 2.5])

# Move multiple axes using dictionary
pitools.moveandwait(pidevice, {'Axis_1': 1.1, 'Axis_2': 2.5}, None)
```

--------------------------------

### Configure Data Recorder Trigger Sources

Source: https://pipython.physikinstrumente.com/datarecorder20.html

Demonstrates how to set trigger sources for the data recorder using single values or lists for multiple record tables. It also shows the use of helper functions to resolve descriptive strings into valid trigger source constants.

```python
drec.options = (datarectools.RecordOptions.ACTUAL_POSITION_2,
                datarectools.RecordOptions.COMMANDED_POSITION_1)
drec.sources = pidevice.axes[0]
drec.trigsources = datarectools.TriggerSources.POSITION_CHANGING_COMMAND_1

# Setting multiple trigger sources
drec.trigsources = (datarectools.TriggerSources.POSITION_CHANGING_COMMAND_1,
                    datarectools.TriggerSources.NEXT_COMMAND_WITH_RESET_2)

# Using helper function
desc = 'pos_chg_cmd'
drec.trigsources = datarectools.gettrigsources(desc)
```

--------------------------------

### METHOD waitonreferencing

Source: https://pipython.physikinstrumente.com/pitools.html

Waits until the referencing process for the specified axes has successfully finished.

```APIDOC
## METHOD waitonreferencing

### Description
Blocks execution until the referencing process for the specified axes is complete or the timeout is reached.

### Method
Python Function Call

### Parameters
- **pidevice** (GCS2Commands/GCS30Commands) - Required - The controller device instance.
- **axes** (str/list/tuple/None) - Optional - Axis identifier(s) to monitor.
- **timeout** (float) - Optional - Timeout in seconds. Default: 300.

### Request Example
```python
pitools.waitonreferencing(pidevice, 'Axis_1')
```

### Response
#### Success Response
- **None** - Returns nothing upon successful completion.
```

--------------------------------

### Wait for fast alignment processes using Python

Source: https://pipython.physikinstrumente.com/pitools.html

Blocks execution until the specified fast alignment processes have completed. Supports timeout, polling delays, and pre/post-process delays.

```python
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Wait until the process 'TestProcess_1' is finished.
pitools.waitonfastalign(pidevice, 'TestProcess_1')

# Wait until multiple processes are finished.
pitools.waitonfastalign(pidevice, ['TestProcess_1', 'TestProcess_2'])
```

--------------------------------

### Wait for axis referencing using PIPython

Source: https://pipython.physikinstrumente.com/pitools.html

The waitonreferencing function monitors the referencing process of PI controllers. It ensures that the specified axes have completed their referencing sequence before proceeding, preventing premature command execution.

```python
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Wait for referencing to complete
pitools.waitonreferencing(pidevice, 'Axis_1')
pitools.waitonreferencing(pidevice, ['Axis_1', 'Axis_2'])
pitools.waitonreferencing(pidevice, None)
```

--------------------------------

### Wait for Auto Zero Procedure Completion (pipython.pitools)

Source: https://pipython.physikinstrumente.com/pitools.html

The waitonautozero function waits until the auto zero procedure has finished on all specified axes. It requires a GCSDevice instance and can take a specific axis, a list of axes, or None for all axes, along with timeout and delay parameters. This function is not supported for controllers with GCS 3.0 syntax.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait while axis 'Axis_1' is running an auto zero procedure.
pitools.waitonautozero(pidevice, 'Axis_1')
...
```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait while axes 'Axis_1' and 'Axis_2' are running an auto zero procedure.
pitools.waitonautozero(pidevice, ['Axis_1', 'Axis_2'])
...
```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until all axes have finished their auto zero procedure.
pitools.waitonautozero(pidevice, None)
...
```

--------------------------------

### Check Axis On-Target Status with pipython

Source: https://pipython.physikinstrumente.com/pitools.html

Retrieves the 'on-target' status for specified axes using the pipython library. It takes a GCSDevice instance and a list of axis names as input. The output is a dictionary mapping axis names to their boolean on-target state. Handles cases for single axes, multiple axes, and all axes.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Get the 'on-target' states of axes 'Axis_1' and 'Axis_2'.
ontargetstate = pitools.ontarget(pidevice, ['Axis_1', 'Axis_2'])
print (ontargetstate)

# The axis 'Axis_1' is on target, 'Axis_2' is not on target.
{'Axis_1': True, 'Axis_2': False}

# Get the 'on-target' state of all axes'.
ontargetstate = pitools.ontarget(pidevice, None)
print(ontargetstate)

# Example for a controller with three axes:
# The axes 'Axis_1' and 'Axis_2' are on target, 'Axis_3' is not on target.
{'Axis_1': True, 'Axis_2': True, 'Axis_3': False}
```

--------------------------------

### Execute Non-blocking Motion with movetomiddle

Source: https://pipython.physikinstrumente.com/pitools.html

Moves specified axes to their middle positions without waiting for the motion to complete. Useful for background positioning tasks.

```python
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Move single axis to middle
pitools.movetomiddle(pidevice, 'Axis_1')

# Move multiple axes to middle
pitools.movetomiddle(pidevice, ['Axis_1', 'Axis_2'])

# Move all axes to middle
pitools.movetomiddle(pidevice, None)
```

--------------------------------

### Wait for Open-Loop Motion Completion (Python)

Source: https://pipython.physikinstrumente.com/pitools.html

The waitonoma function waits until the absolute open-loop motion for specified axes has finished. It takes a GCS2Commands object and can accept a single axis, a list of axes, or None for all axes. This function is not supported for controllers with GCS 3.0 syntax.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()

# Wait until axis 'Axis_1' has finished open-loop motion.
pitools.waitonoma(pidevice, 'Axis_1')

# Wait until axes 'Axis_1' and 'Axis_2' have finished open-loop motion.
pitools.waitonoma(pidevice, ['Axis_1', 'Axis_2'])

# Wait until all axes have finished open-loop motion.
pitools.waitonoma(pidevice, None)
```

--------------------------------

### Read Recorded Data with getdata() and read()

Source: https://pipython.physikinstrumente.com/datarecorder20.html

Retrieves recorded data from a device. getdata() is used for standard recordings, while read() should be used if Datarecorder.wait() was previously called. Both functions call the GCS command qDDR() and return the header and data as a 2D list.

```python
header, data = drec.getdata()
```

```python
drec.arm()
drec.wait()
header, data = drec.read()
```

--------------------------------

### Wait for Wave Generators to Stop (pipython.pitools)

Source: https://pipython.physikinstrumente.com/pitools.html

The waitonwavegen function waits until all specified wave generators have stopped running. It takes a GCSDevice instance and optionally a list of wave generators, timeout, and delay parameters. This function is not supported for controllers with GCS 3.0 syntax.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait while wave generator 1 is running.
pitools.waitonwavegen(pidevice, 1)
...
```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait while wave generators 1 and 2 are running.
pitools.waitonwavegen(pidevice, [1, 2])
...
```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Wait until all wave generators have stopped running.
pitools.waitonwavegen(pidevice, None)
...
```

--------------------------------

### Enable Axes with pipython.pitools

Source: https://pipython.physikinstrumente.com/pitools.html

Enables specified axes on a PI controller. If an axis is already enabled or cannot be enabled, it is skipped. This function handles the underlying commands for axis enablement.

```python
import pipython
from pipython import pitools

help(pipython.pitools.enableaxes)

enableaxes(pidevice, axes, **kwargs)
    Enable all 'axes'.
    @param pidevice: instance of a GCS2Commands or GCS30Commands object
    @param axes: Axis as string or list/tuple of axes to enable.
    @param kwargs: Optional arguments with keywords that are passed to sub-functions.


```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Enable axis 'Axis_1'
pitools.enableaxes(pidevice, 'Axis_1')
...


```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
# Enable the axes 'Axis_1' and 'Axis_2'
pitools.enableaxes(pidevice, ['Axis_1', 'Axis_2'])
...


```

--------------------------------

### Retrieve recorded data using qREC_DAT

Source: https://pipython.physikinstrumente.com/datarecorder30.html

Reads data directly via the qREC_DAT command and monitors the transmission progress using the bufstate property to avoid deadlocks.

```python
header = pidevice.qREC_DAT('REC_1', 'ASCII', [1, 2], 100, 1000)
while pidevice.bufstate is not True:
    print('read data {:.1f}%...'.format(pidevice.bufstate * 100))
    sleep(0.1)
```

--------------------------------

### Configure Traces for Datarecorder in Python

Source: https://pipython.physikinstrumente.com/datarecorder30.html

Specifies which signals are to be recorded and in which trace. The `traces` property accepts a dictionary mapping trace IDs to signal specifications (container unit, function unit, parameter).

```python
from pipython import GCSDevice
from pipython import datarectools, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
...
drec = datarectools.Datarecorder(pidevice)
...
drec.traces = { 1: [ 'AXIS_1', '-', '0x102' ], 2: [ 'AXIS_1', '-', '0x103' ]}
```

--------------------------------

### Set Servo State with pipython

Source: https://pipython.physikinstrumente.com/pitools.html

The pitools.setservo function allows setting the servo state (ON/OFF) for specified axes. It handles preparatory actions like enabling disabled axes or relaxing piezo elements for Nexline axes.

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
# Turn the servo on for 'Axis_1'.
success = pitools.setservo(pidevice, 'Axis_1', True)
print(success)
```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
# Turn the servo on for 'Axis_1' and off for'Axis_2'.
success = pitools.setservo(pidevice, ['Axis_1', 'Axis_2'], [True, False])
print(success)
```

```python
import pipython
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
# Turn the servo on for 'Axis_1' and off for'Axis_2'.
success = pitools.setservo(pidevice, {'Axis_1': True, 'Axis_2': False}, None)
print(success)
```

--------------------------------

### Wait for Macro Completion in Python

Source: https://pipython.physikinstrumente.com/pitools.html

The waitonmacro function pauses execution until all macros on the specified GCS2 device have finished. It includes configurable timeouts and polling delays to monitor controller status.

```python
from pipython import GCSDevice, pitools
pidevice = GCSDevice()
pidevice.InterfaceSetupDlg()
# Wait until macros have finished.
pitools.waitonmacro(pidevice)
```