# pymeasure.adapters

The adapter classes allow the instruments to be independent of the communication method used. The instrument implementation takes care of any potential quirks in its communication protocol (see Advanced communication protocols), and the adapter takes care of the details of the over-the-wire communication with the hardware device. In the vast majority of cases, it will be sufficient to pass a connection string or integer to the instrument (see Connecting to an instrument), which uses the `pymeasure.adapters.VISAAdapter` in the background.

## Adapter base class

class pymeasure.adapters.Adapter(preprocess_reply=None, log=None, **kwargs)

  Base class for Adapter child classes, which adapt between the Instrument object and the connection, to allow flexible use of different connection techniques.

  This class should only be inherited from.

  Parameters:

    - preprocess_reply –

      An optional callable used to preprocess strings received from the instrument. The callable returns the processed string.

      Deprecated since version 0.11: Implement it in the instrument’s read method instead.

    - log – Parent logger of the ‘Adapter’ logger.

    - **kwargs – Keyword arguments just to be cooperative.

  ask(command)

    Write the command to the instrument and returns the resulting ASCII response.

    Deprecated since version 0.11: Call Instrument.ask instead.

    Parameters:

      command – SCPI command string to be sent to the instrument

    Returns:

      String ASCII response of the instrument

  binary_values(command, header_bytes=0, dtype=<class 'numpy.float32'>)

    Returns a numpy array from a query for binary data

    Deprecated since version 0.11: Call Instrument.binary_values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - header_bytes – Integer number of bytes to ignore in header

      - dtype – The NumPy data type to format the values with

    Returns:

      NumPy array of values

  close()

    Close the connection.

  flush_read_buffer()

    Flush and discard the input buffer. Implement in subclass.

  read(**kwargs)

    Read up to (excluding) read_termination or the whole read buffer.

    Do not override in a subclass!

    Parameters:

      **kwargs – Keyword arguments for the connection itself.

    Returns str:

      ASCII response of the instrument (excluding read_termination).

  read_binary_values(header_bytes=0, termination_bytes=None, dtype=<class 'numpy.float32'>, **kwargs)

    Returns a numpy array from a query for binary data

    Parameters:

      - header_bytes (int) – Number of bytes to ignore in header.

      - termination_bytes (int) – Number of bytes to strip at end of message or None.

      - dtype – The NumPy data type to format the values with.

      - **kwargs – Further arguments for the NumPy fromstring method.

    Returns:

      NumPy array of values

  read_bytes(count=-1, break_on_termchar=False, **kwargs)

    Read a certain number of bytes from the instrument.

    Do not override in a subclass!

    Parameters:

      - count (int) – Number of bytes to read. A value of -1 indicates to read from the whole read buffer.

      - break_on_termchar (bool) – Stop reading at a termination character.

      - **kwargs – Keyword arguments for the connection itself.

    Returns bytes:

      Bytes response of the instrument (including termination).

  values(command, separator=', ', cast=<class 'float'>, preprocess_reply=None)

    Write a command to the instrument and returns a list of formatted values from the result.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - separator – A separator character to split the string into a list

      - cast – A type to cast the result

      - preprocess_reply – optional callable used to preprocess values received from the instrument. The callable returns the processed string. If not specified, the Adapter default is used if available, otherwise no preprocessing is done.

    Returns:

      A list of the desired type, or strings where the casting fails

  write(command, **kwargs)

    Write a string command to the instrument appending write_termination.

    Do not override in a subclass!

    Parameters:

      - command (str) – Command string to be sent to the instrument (without termination).

      - **kwargs – Keyword arguments for the connection itself.

  write_binary_values(command, values, termination='', **kwargs)

    Write binary data to the instrument, e.g. waveform for signal generators

    Parameters:

      - command – command string to be sent to the instrument

      - values – iterable representing the binary values

      - termination – String added afterwards to terminate the message.

      - **kwargs – Key-word arguments to pass onto `Adapter._format_binary_values()`

    Returns:

      number of bytes written

  write_bytes(content, **kwargs)

    Write the bytes content to the instrument.

    Do not override in a subclass!

    Parameters:

      - content (bytes) – The bytes to write to the instrument.

      - **kwargs – Keyword arguments for the connection itself.

## VISA adapter

class pymeasure.adapters.VISAAdapter(resource_name, visa_library='', preprocess_reply=None, query_delay=0, log=None, **kwargs)

  Bases: `Adapter`

  Adapter class for the VISA library, using PyVISA to communicate with instruments.

  The workhorse of our library, used by most instruments.

  Parameters:

    - resource_name – A VISA resource string or GPIB address integer that identifies the target of the connection

    - visa_library – PyVISA VisaLibrary Instance, path of the VISA library or VisaLibrary spec string (`@py` or `@ivi`). If not given, the default for the platform will be used.

    - preprocess_reply –

      An optional callable used to preprocess strings received from the instrument. The callable returns the processed string.

      Deprecated since version 0.11: Implement it in the instrument’s read method instead.

    - query_delay (float) –

      Time in s to wait after writing and before reading.

      Deprecated since version 0.11: Implement it in the instrument’s wait_for method instead.

    - log – Parent logger of the ‘Adapter’ logger.

    - **kwargs – Keyword arguments for configuring the PyVISA connection.

  Kwargs:

    Keyword arguments are used to configure the connection created by PyVISA. This is complicated by the fact that which arguments are valid depends on the interface (e.g. serial, GPIB, TCPI/IP, USB) determined by the current `resource_name`.

    A flexible process is used to easily define reasonable default values for different instrument interfaces, but also enable the instrument user to override any setting if their situation demands it.

    A kwarg that names a pyVISA interface type (most commonly `asrl`, `gpib`, `tcpip`, or `usb`) is a dictionary with keyword arguments defining defaults specific to that interface. Example: `asrl={'baud_rate': 4200}`.

    All other kwargs are either generally valid (e.g. `timeout=500`) or override any default settings from the interface-specific entries above. For example, passing `baud_rate=115200` when connecting via a resource name `ASRL1` would override a default of 4200 defined as above.

    See Modifying connection settings for how to tweak settings when connecting to an instrument. See Defining default connection settings for how to best define default settings when implementing an instrument.

  ask(command)

    Writes the command to the instrument and returns the resulting ASCII response

    Deprecated since version 0.11: Call Instrument.ask instead.

    Parameters:

      command – SCPI command string to be sent to the instrument

    Returns:

      String ASCII response of the instrument

  ask_values(command, **kwargs)

    Writes a command to the instrument and returns a list of formatted values from the result. This leverages the query_ascii_values method in PyVISA.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - **kwargs – Key-word arguments to pass onto query_ascii_values

    Returns:

      Formatted response of the instrument.

  binary_values(command, header_bytes=0, dtype=<class 'numpy.float32'>)

    Returns a numpy array from a query for binary data

    Deprecated since version 0.11: Call Instrument.binary_values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - header_bytes – Integer number of bytes to ignore in header

      - dtype – The NumPy data type to format the values with

    Returns:

      NumPy array of values

  close()

    Close the connection.

    Note

    This closes the connection to the resource for all adapters using it currently (e.g. different adapters using the same GPIB line).

  flush_read_buffer()

    Flush and discard the input buffer

    As detailed by pyvisa, discard the read and receivee buffer contents and if data was present in the read buffer and no END-indicator was present, read from the device until encountering an END indicator (which causes loss of data).

  read(**kwargs)

    Read up to (excluding) read_termination or the whole read buffer.

    Do not override in a subclass!

    Parameters:

      **kwargs – Keyword arguments for the connection itself.

    Returns str:

      ASCII response of the instrument (excluding read_termination).

  read_binary_values(header_bytes=0, termination_bytes=None, dtype=<class 'numpy.float32'>, **kwargs)

    Returns a numpy array from a query for binary data

    Parameters:

      - header_bytes (int) – Number of bytes to ignore in header.

      - termination_bytes (int) – Number of bytes to strip at end of message or None.

      - dtype – The NumPy data type to format the values with.

      - **kwargs – Further arguments for the NumPy fromstring method.

    Returns:

      NumPy array of values

  read_bytes(count=-1, break_on_termchar=False, **kwargs)

    Read a certain number of bytes from the instrument.

    Do not override in a subclass!

    Parameters:

      - count (int) – Number of bytes to read. A value of -1 indicates to read from the whole read buffer.

      - break_on_termchar (bool) – Stop reading at a termination character.

      - **kwargs – Keyword arguments for the connection itself.

    Returns bytes:

      Bytes response of the instrument (including termination).

  values(command, separator=', ', cast=<class 'float'>, preprocess_reply=None)

    Write a command to the instrument and returns a list of formatted values from the result.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - separator – A separator character to split the string into a list

      - cast – A type to cast the result

      - preprocess_reply – optional callable used to preprocess values received from the instrument. The callable returns the processed string. If not specified, the Adapter default is used if available, otherwise no preprocessing is done.

    Returns:

      A list of the desired type, or strings where the casting fails

  wait_for_srq(timeout=25, delay=0.1)

    Block until a SRQ, and leave the bit high

    Parameters:

      - timeout – Timeout duration in seconds

      - delay – Time delay between checking SRQ in seconds

  write(command, **kwargs)

    Write a string command to the instrument appending write_termination.

    Do not override in a subclass!

    Parameters:

      - command (str) – Command string to be sent to the instrument (without termination).

      - **kwargs – Keyword arguments for the connection itself.

  write_binary_values(command, values, termination='', **kwargs)

    Write binary data to the instrument, e.g. waveform for signal generators

    Parameters:

      - command – command string to be sent to the instrument

      - values – iterable representing the binary values

      - termination – String added afterwards to terminate the message.

      - **kwargs – Key-word arguments to pass onto `Adapter._format_binary_values()`

    Returns:

      number of bytes written

  write_bytes(content, **kwargs)

    Write the bytes content to the instrument.

    Do not override in a subclass!

    Parameters:

      - content (bytes) – The bytes to write to the instrument.

      - **kwargs – Keyword arguments for the connection itself.

## Serial adapter

class pymeasure.adapters.SerialAdapter(port, preprocess_reply=None, write_termination='', read_termination='', **kwargs)

  Bases: `Adapter`

  Adapter class for using the Python Serial package to allow serial communication to instrument

  Parameters:

    - port – Serial port

    - preprocess_reply –

      An optional callable used to preprocess strings received from the instrument. The callable returns the processed string.

      Deprecated since version 0.11: Implement it in the instrument’s read method instead.

    - write_termination – String appended to messages before writing them.

    - read_termination – String expected at end of read message and removed.

    - **kwargs – Any valid key-word argument for serial.Serial

  _format_binary_values(values, datatype='f', is_big_endian=False, header_fmt='ieee')

    Format values in binary format, used internally in `Adapter.write_binary_values()`.

    Parameters:

      - values – data to be written to the device.

      - datatype – the format string for a single element. See struct module.

      - is_big_endian – boolean indicating endianess.

      - header_fmt – Format of the header prefixing the data (“ieee”, “hp”, “empty”).

    Returns:

      binary string.

    Return type:

      bytes

  ask(command)

    Write the command to the instrument and returns the resulting ASCII response.

    Deprecated since version 0.11: Call Instrument.ask instead.

    Parameters:

      command – SCPI command string to be sent to the instrument

    Returns:

      String ASCII response of the instrument

  binary_values(command, header_bytes=0, dtype=<class 'numpy.float32'>)

    Returns a numpy array from a query for binary data

    Deprecated since version 0.11: Call Instrument.binary_values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - header_bytes – Integer number of bytes to ignore in header

      - dtype – The NumPy data type to format the values with

    Returns:

      NumPy array of values

  close()

    Close the connection.

  flush_read_buffer()

    Flush and discard the input buffer.

  read(**kwargs)

    Read up to (excluding) read_termination or the whole read buffer.

    Do not override in a subclass!

    Parameters:

      **kwargs – Keyword arguments for the connection itself.

    Returns str:

      ASCII response of the instrument (excluding read_termination).

  read_binary_values(header_bytes=0, termination_bytes=None, dtype=<class 'numpy.float32'>, **kwargs)

    Returns a numpy array from a query for binary data

    Parameters:

      - header_bytes (int) – Number of bytes to ignore in header.

      - termination_bytes (int) – Number of bytes to strip at end of message or None.

      - dtype – The NumPy data type to format the values with.

      - **kwargs – Further arguments for the NumPy fromstring method.

    Returns:

      NumPy array of values

  read_bytes(count=-1, break_on_termchar=False, **kwargs)

    Read a certain number of bytes from the instrument.

    Do not override in a subclass!

    Parameters:

      - count (int) – Number of bytes to read. A value of -1 indicates to read from the whole read buffer.

      - break_on_termchar (bool) – Stop reading at a termination character.

      - **kwargs – Keyword arguments for the connection itself.

    Returns bytes:

      Bytes response of the instrument (including termination).

  values(command, separator=', ', cast=<class 'float'>, preprocess_reply=None)

    Write a command to the instrument and returns a list of formatted values from the result.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - separator – A separator character to split the string into a list

      - cast – A type to cast the result

      - preprocess_reply – optional callable used to preprocess values received from the instrument. The callable returns the processed string. If not specified, the Adapter default is used if available, otherwise no preprocessing is done.

    Returns:

      A list of the desired type, or strings where the casting fails

  write(command, **kwargs)

    Write a string command to the instrument appending write_termination.

    Do not override in a subclass!

    Parameters:

      - command (str) – Command string to be sent to the instrument (without termination).

      - **kwargs – Keyword arguments for the connection itself.

  write_binary_values(command, values, termination='', **kwargs)

    Write binary data to the instrument, e.g. waveform for signal generators

    Parameters:

      - command – command string to be sent to the instrument

      - values – iterable representing the binary values

      - termination – String added afterwards to terminate the message.

      - **kwargs – Key-word arguments to pass onto `Adapter._format_binary_values()`

    Returns:

      number of bytes written

  write_bytes(content, **kwargs)

    Write the bytes content to the instrument.

    Do not override in a subclass!

    Parameters:

      - content (bytes) – The bytes to write to the instrument.

      - **kwargs – Keyword arguments for the connection itself.

## Prologix adapter

class pymeasure.adapters.PrologixAdapter(resource_name, address=None, rw_delay=0, serial_timeout=None, preprocess_reply=None, auto=False, eoi=True, eos='\n', gpib_read_timeout=None, **kwargs)

  Bases: `VISAAdapter`

  Encapsulates the additional commands necessary to communicate over a Prologix GPIB-USB Adapter, using the `VISAAdapter`.

  Each PrologixAdapter is constructed based on a connection to the Prologix device itself and the GPIB address of the instrument to be communicated to. Connection sharing is achieved by using the `gpib()` method to spawn new PrologixAdapters for different GPIB addresses.

  Parameters:

    - resource_name – A VISA resource string that identifies the connection to the Prologix device itself, for example “ASRL5” for the 5th COM port.

    - address – Integer GPIB address of the desired instrument.

    - rw_delay –

      An optional delay to set between a write and read call for slow to respond instruments.

      Deprecated since version 0.11: Implement it in the instrument’s wait_for method instead.

    - preprocess_reply –

      optional callable used to preprocess strings received from the instrument. The callable returns the processed string.

      Deprecated since version 0.11: Implement it in the instrument’s read method instead.

    - auto – Enable or disable read-after-write and address instrument to listen.

    - eoi – Enable or disable EOI assertion.

    - eos – Set command termination string (CR+LF, CR, LF, or “”)

    - gpib_read_timeout – Set read timeout for GPIB communication in milliseconds from 1..3000

    - kwargs – Key-word arguments if constructing a new serial object

  Variables:

    address – Integer GPIB address of the desired instrument.

  Usage example:

      adapter = PrologixAdapter("ASRL5::INSTR", 7)
      sourcemeter = Keithley2400(adapter)  # at GPIB address 7
      # generate another instance with a different GPIB address:
      adapter2 = adapter.gpib(9)
      multimeter = Keithley2000(adapter2)  # at GPIB address 9

  To allow user access to the Prologix adapter in Linux, create the file: `/etc/udev/rules.d/51-prologix.rules`, with contents:

      SUBSYSTEMS=="usb",ATTRS{idVendor}=="0403",ATTRS{idProduct}=="6001",MODE="0666"

  Then reload the udev rules with:

      sudo udevadm control --reload-rules
      sudo udevadm trigger

  _format_binary_values(values, datatype='f', is_big_endian=False, header_fmt='ieee')

    Format values in binary format, used internally in `write_binary_values()`.

    Parameters:

      - values – data to be written to the device.

      - datatype – the format string for a single element. See struct module.

      - is_big_endian – boolean indicating endianess.

      - header_fmt – Format of the header prefixing the data (“ieee”, “hp”, “empty”).

    Returns:

      binary string.

    Return type:

      bytes

  ask(command)

    Ask the Prologix controller.

    Deprecated since version 0.11: Call Instrument.ask instead.

    Parameters:

      command – SCPI command string to be sent to instrument

  ask_values(command, **kwargs)

    Writes a command to the instrument and returns a list of formatted values from the result. This leverages the query_ascii_values method in PyVISA.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - **kwargs – Key-word arguments to pass onto query_ascii_values

    Returns:

      Formatted response of the instrument.

  property auto

    Control whether to address instruments to talk after sending them a command (bool).

    Configure Prologix GPIB controller to automatically address instruments to talk after sending them a command in order to read their response. The feature called, Read-After-Write, saves the user from having to issue read commands repeatedly. This property enables (True) or disables (False) this feature.

  binary_values(command, header_bytes=0, dtype=<class 'numpy.float32'>)

    Returns a numpy array from a query for binary data

    Deprecated since version 0.11: Call Instrument.binary_values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - header_bytes – Integer number of bytes to ignore in header

      - dtype – The NumPy data type to format the values with

    Returns:

      NumPy array of values

  close()

    Close the connection.

    Note

    This closes the connection to the resource for all adapters using it currently (e.g. different adapters using the same GPIB line).

  property eoi

    Control whether to assert the EOI signal with the last character of any command sent over GPIB port (bool).

    Some instruments require EOI signal to be asserted in order to properly detect the end of a command.

  property eos

    Control GPIB termination characters (str).

    possible values:

      - CR+LF

      - CR

      - LF

      - empty string

    When data from host is received, all non-escaped LF, CR and ESC characters are removed and GPIB terminators, as specified by this command, are appended before sending the data to instruments. This command does not affect data from instruments received over GPIB port.

  flush_read_buffer()

    Flush and discard the input buffer

    As detailed by pyvisa, discard the read and receivee buffer contents and if data was present in the read buffer and no END-indicator was present, read from the device until encountering an END indicator (which causes loss of data).

  gpib(address, **kwargs)

    Return a PrologixAdapter object that references the GPIB address specified, while sharing the Serial connection with other calls of this function

    Parameters:

      - address – Integer GPIB address of the desired instrument

      - kwargs – Arguments for the initialization

    Returns:

      PrologixAdapter for specific GPIB address

  property gpib_read_timeout

    Control the timeout value for the GPIB communication in milliseconds

    possible values: 1 - 3000

  read(**kwargs)

    Read up to (excluding) read_termination or the whole read buffer.

    Do not override in a subclass!

    Parameters:

      **kwargs – Keyword arguments for the connection itself.

    Returns str:

      ASCII response of the instrument (excluding read_termination).

  read_binary_values(header_bytes=0, termination_bytes=None, dtype=<class 'numpy.float32'>, **kwargs)

    Returns a numpy array from a query for binary data

    Parameters:

      - header_bytes (int) – Number of bytes to ignore in header.

      - termination_bytes (int) – Number of bytes to strip at end of message or None.

      - dtype – The NumPy data type to format the values with.

      - **kwargs – Further arguments for the NumPy fromstring method.

    Returns:

      NumPy array of values

  read_bytes(count=-1, break_on_termchar=False, **kwargs)

    Read a certain number of bytes from the instrument.

    Do not override in a subclass!

    Parameters:

      - count (int) – Number of bytes to read. A value of -1 indicates to read from the whole read buffer.

      - break_on_termchar (bool) – Stop reading at a termination character.

      - **kwargs – Keyword arguments for the connection itself.

    Returns bytes:

      Bytes response of the instrument (including termination).

  reset()

    Perform a power-on reset of the controller.

    The process takes about 5 seconds. All input received during this time is ignored and the connection is closed.

  values(command, separator=', ', cast=<class 'float'>, preprocess_reply=None)

    Write a command to the instrument and returns a list of formatted values from the result.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - separator – A separator character to split the string into a list

      - cast – A type to cast the result

      - preprocess_reply – optional callable used to preprocess values received from the instrument. The callable returns the processed string. If not specified, the Adapter default is used if available, otherwise no preprocessing is done.

    Returns:

      A list of the desired type, or strings where the casting fails

  property version

    Get the version string of the Prologix controller.

  wait_for_srq(timeout=25, delay=0.1)

    Blocks until a SRQ, and leaves the bit high

    Parameters:

      - timeout – Timeout duration in seconds.

      - delay – Time delay between checking SRQ in seconds.

    Raises:

      TimeoutError – “Waiting for SRQ timed out.”

  write(command, **kwargs)

    Write a string command to the instrument appending write_termination.

    If the GPIB address in `address` is defined, it is sent first.

    Parameters:

      - command (str) – Command string to be sent to the instrument (without termination).

      - kwargs – Keyword arguments for the connection itself.

  write_binary_values(command, values, **kwargs)

    Write binary data to the instrument, e.g. waveform for signal generators.

    values are encoded in a binary format according to IEEE 488.2 Definite Length Arbitrary Block Response Data block.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - values – iterable representing the binary values

      - kwargs – Key-word arguments to pass onto `_format_binary_values()`

    Returns:

      number of bytes written

  write_bytes(content, **kwargs)

    Write the bytes content to the instrument.

    Do not override in a subclass!

    Parameters:

      - content (bytes) – The bytes to write to the instrument.

      - **kwargs – Keyword arguments for the connection itself.

## VXI-11 adapter

class pymeasure.adapters.VXI11Adapter(host, preprocess_reply=None, **kwargs)

  Bases: `Adapter`

  VXI11 Adapter class. Provides a adapter object that

    wraps around the read, write and ask functionality of the vxi11 library.

  Deprecated since version 0.11: Use VISAAdapter instead.

  Parameters:

    - host – string containing the visa connection information.

    - preprocess_reply – (deprecated) optional callable used to preprocess strings received from the instrument. The callable returns the processed string.

  ask(command)

    Wrapper function for the ask command using the vx11 interface.

    Deprecated since version 0.11: Call Instrument.ask instead.

    Parameters:

      command – string with the command that will be transmitted to the instrument.

    :returns string containing a response from the device.

  ask_raw(command)

    Wrapper function for the ask_raw command using the vx11 interface.

    Deprecated since version 0.11: Use Instrument.write_bytes and Instrument.read_bytes instead.

    Parameters:

      command – binary string with the command that will be transmitted to the instrument

    :returns binary string containing the response from the device.

  binary_values(command, header_bytes=0, dtype=<class 'numpy.float32'>)

    Returns a numpy array from a query for binary data

    Deprecated since version 0.11: Call Instrument.binary_values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - header_bytes – Integer number of bytes to ignore in header

      - dtype – The NumPy data type to format the values with

    Returns:

      NumPy array of values

  close()

    Close the connection.

  flush_read_buffer()

    Flush and discard the input buffer. Implement in subclass.

  read(**kwargs)

    Read up to (excluding) read_termination or the whole read buffer.

    Do not override in a subclass!

    Parameters:

      **kwargs – Keyword arguments for the connection itself.

    Returns str:

      ASCII response of the instrument (excluding read_termination).

  read_binary_values(header_bytes=0, termination_bytes=None, dtype=<class 'numpy.float32'>, **kwargs)

    Returns a numpy array from a query for binary data

    Parameters:

      - header_bytes (int) – Number of bytes to ignore in header.

      - termination_bytes (int) – Number of bytes to strip at end of message or None.

      - dtype – The NumPy data type to format the values with.

      - **kwargs – Further arguments for the NumPy fromstring method.

    Returns:

      NumPy array of values

  read_bytes(count=-1, break_on_termchar=False, **kwargs)

    Read a certain number of bytes from the instrument.

    Do not override in a subclass!

    Parameters:

      - count (int) – Number of bytes to read. A value of -1 indicates to read from the whole read buffer.

      - break_on_termchar (bool) – Stop reading at a termination character.

      - **kwargs – Keyword arguments for the connection itself.

    Returns bytes:

      Bytes response of the instrument (including termination).

  read_raw()

    Read bytes from the device.

    Deprecated since version 0.11: Use read_bytes instead.

  values(command, separator=', ', cast=<class 'float'>, preprocess_reply=None)

    Write a command to the instrument and returns a list of formatted values from the result.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - separator – A separator character to split the string into a list

      - cast – A type to cast the result

      - preprocess_reply – optional callable used to preprocess values received from the instrument. The callable returns the processed string. If not specified, the Adapter default is used if available, otherwise no preprocessing is done.

    Returns:

      A list of the desired type, or strings where the casting fails

  write(command, **kwargs)

    Write a string command to the instrument appending write_termination.

    Do not override in a subclass!

    Parameters:

      - command (str) – Command string to be sent to the instrument (without termination).

      - **kwargs – Keyword arguments for the connection itself.

  write_binary_values(command, values, termination='', **kwargs)

    Write binary data to the instrument, e.g. waveform for signal generators

    Parameters:

      - command – command string to be sent to the instrument

      - values – iterable representing the binary values

      - termination – String added afterwards to terminate the message.

      - **kwargs – Key-word arguments to pass onto `Adapter._format_binary_values()`

    Returns:

      number of bytes written

  write_bytes(content, **kwargs)

    Write the bytes content to the instrument.

    Do not override in a subclass!

    Parameters:

      - content (bytes) – The bytes to write to the instrument.

      - **kwargs – Keyword arguments for the connection itself.

  write_raw(command)

    Write bytes to the device.

    Deprecated since version 0.11: Use write_bytes instead.

## Telnet adapter

class pymeasure.adapters.TelnetAdapter(host, port=0, query_delay=0, preprocess_reply=None, **kwargs)

  Bases: `Adapter`

  Adapter class for using the Python telnetlib package to allow communication to instruments

  This Adapter has been removed from service as the underlying library is missing!

  Deprecated since version 0.11.2: The Python telnetlib module is deprecated since Python 3.11 and will be removed in Python 3.13 release. As a result, TelnetAdapter is deprecated, use VISAAdapter instead. The VISAAdapter supports TCPIP socket connections. When using the VISAAdapter, the resource_name argument should be TCPIP[board]::<host>::<port>::SOCKET. see here, <https://pyvisa.readthedocs.io/en/latest/introduction/names.html>

  ask(command)

    Write the command to the instrument and returns the resulting ASCII response.

    Deprecated since version 0.11: Call Instrument.ask instead.

    Parameters:

      command – SCPI command string to be sent to the instrument

    Returns:

      String ASCII response of the instrument

  binary_values(command, header_bytes=0, dtype=<class 'numpy.float32'>)

    Returns a numpy array from a query for binary data

    Deprecated since version 0.11: Call Instrument.binary_values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - header_bytes – Integer number of bytes to ignore in header

      - dtype – The NumPy data type to format the values with

    Returns:

      NumPy array of values

  close()

    Close the connection.

  flush_read_buffer()

    Flush and discard the input buffer. Implement in subclass.

  read(**kwargs)

    Read up to (excluding) read_termination or the whole read buffer.

    Do not override in a subclass!

    Parameters:

      **kwargs – Keyword arguments for the connection itself.

    Returns str:

      ASCII response of the instrument (excluding read_termination).

  read_binary_values(header_bytes=0, termination_bytes=None, dtype=<class 'numpy.float32'>, **kwargs)

    Returns a numpy array from a query for binary data

    Parameters:

      - header_bytes (int) – Number of bytes to ignore in header.

      - termination_bytes (int) – Number of bytes to strip at end of message or None.

      - dtype – The NumPy data type to format the values with.

      - **kwargs – Further arguments for the NumPy fromstring method.

    Returns:

      NumPy array of values

  read_bytes(count=-1, break_on_termchar=False, **kwargs)

    Read a certain number of bytes from the instrument.

    Do not override in a subclass!

    Parameters:

      - count (int) – Number of bytes to read. A value of -1 indicates to read from the whole read buffer.

      - break_on_termchar (bool) – Stop reading at a termination character.

      - **kwargs – Keyword arguments for the connection itself.

    Returns bytes:

      Bytes response of the instrument (including termination).

  values(command, separator=', ', cast=<class 'float'>, preprocess_reply=None)

    Write a command to the instrument and returns a list of formatted values from the result.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - separator – A separator character to split the string into a list

      - cast – A type to cast the result

      - preprocess_reply – optional callable used to preprocess values received from the instrument. The callable returns the processed string. If not specified, the Adapter default is used if available, otherwise no preprocessing is done.

    Returns:

      A list of the desired type, or strings where the casting fails

  write(command, **kwargs)

    Write a string command to the instrument appending write_termination.

    Do not override in a subclass!

    Parameters:

      - command (str) – Command string to be sent to the instrument (without termination).

      - **kwargs – Keyword arguments for the connection itself.

  write_binary_values(command, values, termination='', **kwargs)

    Write binary data to the instrument, e.g. waveform for signal generators

    Parameters:

      - command – command string to be sent to the instrument

      - values – iterable representing the binary values

      - termination – String added afterwards to terminate the message.

      - **kwargs – Key-word arguments to pass onto `Adapter._format_binary_values()`

    Returns:

      number of bytes written

  write_bytes(content, **kwargs)

    Write the bytes content to the instrument.

    Do not override in a subclass!

    Parameters:

      - content (bytes) – The bytes to write to the instrument.

      - **kwargs – Keyword arguments for the connection itself.

## Test adapters

These pieces are useful when writing tests.

pymeasure.test.expected_protocol(instrument_cls, comm_pairs, connection_attributes=None, connection_methods=None, **kwargs)

  Context manager that checks sent/received instrument commands without a device connected.

  Given an instrument class and a list of command-response pairs, this context manager confirms that the code in the context manager block produces the expected messages.

  Terminators are excluded from the protocol definition, as those are typically a detail of the communication method (i.e. Adapter), and not the protocol itself.

  Parameters:

    - instrument_cls (pymeasure.Instrument) – `Instrument` subclass to instantiate.

    - comm_pairs (list[2-tuples[str]]) – List of command-response pairs, i.e. 2-tuples like (‘VOLT?’, ‘3.14’). ‘None’ indicates that a pair member (command or response) does not exist, e.g. (None, ‘RESP1’). Commands and responses are without termination characters.

    - connection_attributes – Dictionary of connection attributes and their values.

    - connection_methods – Dictionary of method names of the connection and their return values.

    - **kwargs – Keyword arguments for the instantiation of the instrument.

class pymeasure.adapters.ProtocolAdapter(comm_pairs=None, preprocess_reply=None, connection_attributes=None, connection_methods=None, **kwargs)

  Bases: `Adapter`

  Adapter class for testing the command exchange protocol without instrument hardware.

  This adapter is primarily meant for use within `pymeasure.test.expected_protocol()`.

  The `connection` attribute is a `unittest.mock.MagicMock` such that every call returns. If you want to set a return value, you can use `adapter.connection.some_method.return_value = 7`, such that a call to `adapter.connection.some_method()` will return 7. Similarly, you can verify that this call to the connection method happened with `assert adapter.connection.some_method.called is True`. You can specify dictionaries with return values of attributes and methods.

  Parameters:

    - comm_pairs (list) – List of “reference” message pair tuples. The first element is what is sent to the instrument, the second one is the returned message. ‘None’ indicates that a pair member (write or read) does not exist. The messages do not include the termination characters.

    - connection_attributes – Dictionary of connection attributes and their values.

    - connection_methods – Dictionary of method names of the connection and their return values.

  flush_read_buffer()

    Flush and discard the input buffer

    As detailed by pyvisa, discard the read buffer contents and if data was present in the read buffer and no END-indicator was present, read from the device until encountering an END indicator (which causes loss of data).

class pymeasure.adapters.FakeAdapter(preprocess_reply=None, log=None, **kwargs)

  Bases: `Adapter`

  Provides a fake adapter for debugging purposes, which bounces back the command so that arbitrary values testing is possible.

      a = FakeAdapter()
      assert a.read() == ""
      a.write("5")
      assert a.read() == "5"
      assert a.read() == ""
      assert a.ask("10") == "10"
      assert a.values("10") == [10]

  ask(command)

    Write the command to the instrument and returns the resulting ASCII response.

    Deprecated since version 0.11: Call Instrument.ask instead.

    Parameters:

      command – SCPI command string to be sent to the instrument

    Returns:

      String ASCII response of the instrument

  binary_values(command, header_bytes=0, dtype=<class 'numpy.float32'>)

    Returns a numpy array from a query for binary data

    Deprecated since version 0.11: Call Instrument.binary_values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - header_bytes – Integer number of bytes to ignore in header

      - dtype – The NumPy data type to format the values with

    Returns:

      NumPy array of values

  close()

    Close the connection.

  flush_read_buffer()

    Flush and discard the input buffer. Implement in subclass.

  read(**kwargs)

    Read up to (excluding) read_termination or the whole read buffer.

    Do not override in a subclass!

    Parameters:

      **kwargs – Keyword arguments for the connection itself.

    Returns str:

      ASCII response of the instrument (excluding read_termination).

  read_binary_values(header_bytes=0, termination_bytes=None, dtype=<class 'numpy.float32'>, **kwargs)

    Returns a numpy array from a query for binary data

    Parameters:

      - header_bytes (int) – Number of bytes to ignore in header.

      - termination_bytes (int) – Number of bytes to strip at end of message or None.

      - dtype – The NumPy data type to format the values with.

      - **kwargs – Further arguments for the NumPy fromstring method.

    Returns:

      NumPy array of values

  read_bytes(count=-1, break_on_termchar=False, **kwargs)

    Read a certain number of bytes from the instrument.

    Do not override in a subclass!

    Parameters:

      - count (int) – Number of bytes to read. A value of -1 indicates to read from the whole read buffer.

      - break_on_termchar (bool) – Stop reading at a termination character.

      - **kwargs – Keyword arguments for the connection itself.

    Returns bytes:

      Bytes response of the instrument (including termination).

  values(command, separator=', ', cast=<class 'float'>, preprocess_reply=None)

    Write a command to the instrument and returns a list of formatted values from the result.

    Deprecated since version 0.11: Call Instrument.values instead.

    Parameters:

      - command – SCPI command to be sent to the instrument

      - separator – A separator character to split the string into a list

      - cast – A type to cast the result

      - preprocess_reply – optional callable used to preprocess values received from the instrument. The callable returns the processed string. If not specified, the Adapter default is used if available, otherwise no preprocessing is done.

    Returns:

      A list of the desired type, or strings where the casting fails

  write(command, **kwargs)

    Write a string command to the instrument appending write_termination.

    Do not override in a subclass!

    Parameters:

      - command (str) – Command string to be sent to the instrument (without termination).

      - **kwargs – Keyword arguments for the connection itself.

  write_binary_values(command, values, termination='', **kwargs)

    Write binary data to the instrument, e.g. waveform for signal generators

    Parameters:

      - command – command string to be sent to the instrument

      - values – iterable representing the binary values

      - termination – String added afterwards to terminate the message.

      - **kwargs – Key-word arguments to pass onto `Adapter._format_binary_values()`

    Returns:

      number of bytes written

  write_bytes(content, **kwargs)

    Write the bytes content to the instrument.

    Do not override in a subclass!

    Parameters:

      - content (bytes) – The bytes to write to the instrument.

      - **kwargs – Keyword arguments for the connection itself.

class pymeasure.generator.Generator

  Generates tests from the communication with an instrument.

  Example usage:

      g = Generator()
      inst = g.instantiate(TC038, "COM5", 'hcp', adapter_kwargs={'baud_rate': 9600})
      inst.information  # returns the 'information' property and adds it to the tests
      inst.setpoint = 20
      inst.setpoint == 20  # should be True
      g.write_file("test_tc038.py")  # write the tests to a file

  instantiate(instrument_class, adapter, manufacturer, adapter_kwargs=None, **kwargs)

    Instantiate the instrument and store the instantiation communication.

    ..note:

        You have to give all keyword arguments necessary for adapter instantiation in
        `adapter_kwargs`, even those, which are defined somewhere in the instrument's
        ``__init__`` method, be it as a default value, be it directly in the
        ``Instrument.__init__()`` call.

    Parameters:

      - instrument_class – Class of the instrument to test.

      - adapter – Adapter (instance or str) for the instrument instantiation.

      - manufacturer – Module from which to import the instrument, e.g. ‘hcp’ if instrument_class is ‘pymeasure.hcp.tc038’.

      - adapter_kwargs – Keyword arguments for the adapter instantiation (see note above).

      - **kwargs – Keyword arguments for the instrument instantiation.

    Returns:

      A man-in-the-middle instrument, which can be used like a normal instrument.

  parse_stream()

    Parse the stream not yet read.

  test_method(method_name, *args, **kwargs)

    Test calling the method_name of the instruments with args and kwargs.

  test_property_getter(property)

    Test getting the property of the instrument, adding it to the list.

  test_property_setter(property, value)

    Test setting the property of the instrument to value, adding it to the list.

  test_property_setter_batch(property, values)

    Test setting property to each element in values.

  write_file(filename='tests.py')

    Write the tests into the file.

    Parameters:

      filename – Name to save the tests to, may contain the path, e.g. “/tests/test_abc.py”.

  write_getter_test(file, property, parameters)

    Write a getter test.

  write_init_test(file)

    Write the header and init test.

  write_method_test(file, method, parameters)

    Write a test for a method.

  write_method_tests(file)

    Write all parametrized method tests in alphabetic order.

  write_property_tests(file)

    Write tests for properties in alphabetic order.

    If getter and setter exist, the setter is the first test.

  write_setter_test(file, property, parameters)

    Write a setter test.