Device Connection

Connecting to a single device with the GCS DLL

Via dialog

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

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

If you pass a string as the optional key argument to the InterfaceSetupDlg method, the DLL stores the settings in the Windows registry and retrieves 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()))

Via device identification

There are functions to scan for available devices:

Interface	Function
USB	`EnumerateUSB(mask='')`
TCP/IP	`EnumerateTCPIPDevices(mask='')`

Use mask (= string) to limit the number of devices to be found. If it is contained in the device identification, the device is found (see qIDN).

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

Via dedicated interface

You can connect to a device via the following interfaces using the corresponding methods:

Interface	Method
RS-232	`ConnectRS232(comport, baudrate)`
USB	`ConnectUSB(serialnum)` `serialnum` = the serial number of the device as a string or the device identification returned by the `EnumerateUSB` method
USB via virtual COM port	`ConnectRS232(comport, baudrate)`
TCP/IP	`ConnectTCPIP(ipaddress, ipport=50000)`
TCP/IP	`ConnectTCPIPByDescription(description)` `description` = string returned by the `EnumerateTCPIPDevices` method
NI GPIB	`ConnectNIgpib(board, device)`
PCI board	`ConnectPciBoard(board)`

USB connection on Windows

All PI USB controllers support a native USB connection using the ConnectUSB() function.
Some PI USB controllers support also a connection via a virtual COM port using the ConnectRS232() function.

USB connection on Linux

Some PI USB controllers only support a native USB connection using the ConnectUSB() function.
For information about which controllers only support a native USB connection, call the EnumerateUSB() function. Some PI USB controllers only support a connection via a virtual COM port using the ConnectRS232() function (for example, with /dev/ttyUSB0 as comport). The EnumerateUSB() function does not return these controllers.

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

Connecting to devices in a daisy chain network

Open the interface to the daisy chain master device (i.e., the device connected to the PC), then connect all devices of the daisy chain network to this interface.

Info

In a daisy chain network, each device must have a unique address (= device ID). There must be one device with the address 1, though this device does not have to be the master device (see controller manual on how to change the address of a device).

Use the following methods to connect to the master device in a daisy chain network:

Interface	Method
RS-232	`OpenRS232DaisyChain(comport, baudrate)`
USB	`OpenUSBDaisyChain(serialnum)`
TCP/IP	`OpenTCPIPDaisyChain(ipaddress, ipport=50000)`

In the following example, three controllers are connected:

C-863 controller as the master device, address 3
E-861 controller, address 7

C-867 controller, address 1

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

Connecting via low-level interface

The preferred method to connect to devices is GCSDevice using the GCS DLL. On platforms where the GCS DLL is not available, low-level functions of the PIPython package can be used instead.

Interface	Method
RS-232	`PISerial(comport, baudrate)`
USB	`PIUSB(serialnum)`
USB via virtual COM port	`PISerial(virtual_comport, baudrate)`
TCP/IP	`PISocket(ipaddress, ipport=50000)`

USB connection on Windows

A USB connection using PIUSB() is not supported on Windows.
Some PI USB controllers support a connection via a virtual COM port using the PISerial() function. Only these controllers are supported on Windows.

USB connection on Linux

Some PI USB controllers only support a native USB connection using PIUSB() and some PI USB controllers only support a connection via a virtual COM port using PISerial() (e.g., with /dev/ttyUSB0 as comport).
If one method does not work, please try the other method.

PISerial

Windows

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

Linux

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

PIUSB

Windows: PIUSB() is not supported on Windows.

Linux:

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

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

Connecting to unknown devices

If GCSDevice is called with the controller name, the corresponding GCS DLL is chosen automatically. For unknown devices, a dedicated GCS DLL can be used instead.

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