Device Connection - PIPython
Author: Physik Instrumente (PI) GmbH & Co. KG

# Device connection

Here you will find sample code for how to connect one ore more PI devices. For further reading see the python scripts in the `samples` subdirectory.

## Connect a single device via the GCS DLL

### By a dialog

On Windows systems the GCS DLL provides a graphical user interface to select the interface and parameters.

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

If you pass an optional `key` as arbitrary string to the `InterfaceSetupDlg` method, the DLL remembers the settings in the Windows registry and will recall them the next time you connect with the same key.

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

### By a dedicated interface

You can connect via these interfaces with the according methods.

- RS-232: `ConnectRS232(comport, baudrate)`
- USB: `ConnectUSB(serialnum)`
- TCP/IP: `ConnectTCPIP(ipaddress, ipport=50000)`
- TCP/IP: `ConnectTCPIPByDescription(description)`
- NI GPIB: `ConnectNIgpib(board, device)`
- PCI board: `ConnectPciBoard(board)`

    from pipython import GCSDevice
    with GCSDevice() as pidevice:
        pidevice.ConnectTCPIP('192.168.178.42')
        print('connected: {}'.format(pidevice.qIDN().strip()))

The parameter `serialnum` can be the serial number of the device as string or the device identification returned by `EnumerateUSB`. For TCP/IP `ConnectTCPIP` connects by given IP address where `ConnectTCPIPByDescription` uses the string from `EnumerateTCPIPDevices`.

### By the device identification

There are functions to scan for available devices.

- USB: `EnumerateUSB(mask='')`
- TCPIP: `EnumerateTCPIPDevices(mask='')`

Use the `mask` to limit the number of found devices. It is a string that must be part of the identification string - see `qIDN` - returned by the devices.

    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()))

## Connect daisy chain devices

You have to open the interface once and than you connect all devices to this interface. Each device must have a unique ID on the daisy chain (see controller manual). There must be one device with ID1 which needs not to be the master device (i.e. connected to the PC). See an example for 3 devices on an RS-232 daisy chain.

- C-863 controller with device ID 3, this is the master device
- E-861 controller with device ID 7
- C-867 controller with device ID 1

There is no need to close the connections. This is done automatically because `GCSDevice` is used as context manager.

    from pipython import GCSDevice
    with GCSDevice() as c863:
        c863.OpenRS232DaisyChain(comport=1, baudrate=115200)
        # c863.OpenUSBDaisyChain(description='1234567890')
        # c863.OpenTCPIPDaisyChain(ipaddress='192.168.178.42')
        daisychainid = c863.dcid
        c863.ConnectDaisyChainDevice(3, daisychainid)
        with GCSDevice() as e861:
            e861.ConnectDaisyChainDevice(7, daisychainid)
            with GCSDevice() as c867:
                c867.ConnectDaisyChainDevice(1, daisychainid)
                print('\n{}:\n{}'.format(c863.GetInterfaceDescription(), c863.qIDN()))
                print('\n{}:\n{}'.format(e861.GetInterfaceDescription(), e861.qIDN()))
                print('\n{}:\n{}'.format(c867.GetInterfaceDescription(), c867.qIDN()))

## Low level interface

Usually you connect with `GCSDevice` via the GCS DLL. But on platforms where the GCS DLL is not available you are still able to connect.

### By PISocket:

    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)
        pidevice = GCSCommands(messages)
        print(pidevice.qIDN())

### By PISerial:

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

### By PIUSB:

This interface requires LibUSB which usually is only available on Linux like operation systems. Hint: Run `pip install pyusb`.

    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)
        pidevice = GCSCommands(messages)
        print(pidevice.qIDN())

## Unknown devices

When you call `GCSDevice` with the controller name the according GCS DLL is chosen automatically. For unknown devices you can specify a dedicated GCS DLL instead.

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

« Previous Next »