i2c_gui2 package

Module contents

class i2c_gui2.AD5593R_Chip(i2c_address, i2c_connection: I2C_Connection_Helper, logger: Logger)

Bases: Base_Chip

property i2c_address: int

read_adc_results(adc_sequence: int, num_measurements: int)

class i2c_gui2.ETROC2_Chip(etroc2_i2c_address, waveform_sampler_i2c_address, i2c_connection: I2C_Connection_Helper, logger: Logger)

Bases: Base_Chip

property broadcast: bool

property col: int

property etroc2_i2c_address: int

read_all_efficient()

This read function will only read the named register addresses in the ETROC2 manual. There are many addresses which are not named and as a result are not read. In principle, these addresses are not used for anything and may not even be implemented in the chip, but by using this function we are essentially blind to what is happening on these unnamed addresses

property row: int

property waveform_sampler_i2c_address: int

write_all_address_space(address_space_name: str, readback_check: bool = True, no_message: bool = True)

write_all_block(address_space_name: str, block_name: str, full_array: bool = False, readback_check: bool = True, no_message: bool = True)

write_all_efficient(readback_check: bool = True)

This write function will only write the named register addresses in the ETROC2 manual. There are many addresses which are not named and as a result are not written. In principle, these addresses are not used for anything and may not even be implemented in the chip, but by using this function we are essentially not setting these unnamed addresses

write_decoded_value(address_space_name: str, block_name: str, decoded_value_name: str, write_check: bool = True, no_message: bool = False)

write_register(address_space_name: str, block_name: str, register: str, readback_check: bool = True, no_message: bool = True)

class i2c_gui2.I2CMessages(*values)

Bases: Enum

Class to wrap the I2C Messages unique identifiers

This is a temporary description

Examples

>>> from i2c_gui2.i2c_messages import I2CMessages
>>> single_command = I2CMessages.READ7
>>> command_sequence = [I2CMessages.START, I2CMessages.NACK, I2CMessages.READ2, I2CMessages.STOP]

NACK = 4

READ1 = 32

READ10 = 41

READ11 = 42

READ12 = 43

READ13 = 44

READ14 = 45

READ15 = 46

READ16 = 47

READ2 = 33

READ3 = 34

READ4 = 35

READ5 = 36

READ6 = 37

READ7 = 38

READ8 = 39

READ9 = 40

RESTART = 2

START = 1

STOP = 3

WRITE1 = 48

WRITE10 = 57

WRITE11 = 58

WRITE12 = 59

WRITE13 = 60

WRITE14 = 61

WRITE15 = 62

WRITE16 = 63

WRITE2 = 49

WRITE3 = 50

WRITE4 = 51

WRITE5 = 52

WRITE6 = 53

WRITE7 = 54

WRITE8 = 55

WRITE9 = 56

class i2c_gui2.USB_ISS_Helper(port: str, clock: int, use_serial: bool = False, baud_rate: int | None = None, verbose: bool = False, max_seq_byte: int = 8, dummy_connect: bool = False)

Bases: I2C_Connection_Helper

Class to handle the USB-ISS connection

This class is a wrapper around the usb_iss library, providing a simplified interface for the usage in the ETROC DAQ assuming only I2C is used, with optional GPIO for the extra pins

Parameters:

• port – The port where the USB-ISS device can be found

• clock – The clock frequency to use for I2C communication. It must be a valid clock from the list: 20, 50, 100, 400, 1000. For clock frequencies where there is both software and hardware support, the hardware version will be given precedence.

• use_serial – Whether to use the extra pins on the USB-ISS as a serial interface, if not they will be GPIO (by default set to analog in). The serial port is only enabled if the baud rate is also set.

• baud_rate – The baud rate to use for the serial communication

• verbose – Whether to output detailed information to the terminal

• max_seq_byte – The maximum number of sequential bytes supported in a single I2C message. The limit is not necessarily from the USB-ISS and may be from the device it is communicating with. TODO: Add an option to set this limit per operation so different limits can be set for different devices.

• dummy_connect – If set, the connection to the USB-ISS will be emulated and a dummy device will be configured

Raises:

• SerialException – If the serial object can not be found

• ValueError – If a wrong value is passed to the clock configuration

• RuntimeError – For other issues communicating with the USB-ISS device

Examples

>>> import i2c_gui2
>>> usbiss = i2c_gui2.USB_ISS_Helper("/dev/ttyACM0")
>>> usbiss.version()

property baud_rate: int | None

The baud_rate property getter method

This method returns the baud rate the extra pins on the USB-ISS used as a serial communication are set to

Returns:

• int – If the extra pins on the USB-ISS are being used as a serial communication

• None – If the USB-ISS is not configured to use the serial port for communication

property clock: int

The clock property getter method

This method returns the clock frequency the USB-ISS I2C is configured to

Returns:

int – The clock frequency.

property fw_version: int

The fw_version property getter method

This method returns the firmware version of the USB-ISS firmware

Returns:

int – The firmware version number.

property port: str

The port property getter method

This method returns the port the USB-ISS is connected to

Returns:

str – The port.

property serial: str

The serial_number property getter method

This method returns the serial number of the USB-ISS firmware

Returns:

str – The serial number.

property use_serial: bool

The use_serial property getter method

This method returns if the extra pins on the USB-ISS are being used as a serial communication

Returns:

bool – If the extra pins on the USB-ISS are being used as a serial communication

Submodules

i2c_gui2.functions module

i2c_gui2.functions.addLoggingLevel(levelName, levelNum, methodName=None)

Comprehensively adds a new logging level to the logging module and the currently configured logging class.

levelName becomes an attribute of the logging module with the value levelNum. methodName becomes a convenience method for both logging itself and the class returned by logging.getLoggerClass() (usually just logging.Logger). If methodName is not specified, levelName.lower() is used.

To avoid accidental clobberings of existing attributes, this method will raise an AttributeError if the level name is already an attribute of the logging module or if the method name is already present

Example

>>> addLoggingLevel('TRACE', logging.DEBUG - 5)
>>> logging.getLogger(__name__).setLevel("TRACE")
>>> logging.getLogger(__name__).trace('that worked')
>>> logging.trace('so did this')
>>> logging.TRACE
5

i2c_gui2.functions.address_to_phys(address: int, bitlength: int = 8, endianness: str = 'big')

i2c_gui2.functions.bytes_to_word_list(byte_list: list[int], bytelength: int = 1, endianness: str = 'big')

i2c_gui2.functions.is_valid_hostname(hostname: str)

i2c_gui2.functions.is_valid_ip(hostname: str)

i2c_gui2.functions.swap_endian_16bit(value: int)

i2c_gui2.functions.swap_endian_32bit(value: int)

i2c_gui2.functions.valid_i2c_address(value: int)

i2c_gui2.functions.validate_hostname(hostname: str)

i2c_gui2.functions.word_list_to_bytes(word_list: list[int], bytelength: int = 1, endianness: str = 'big')

i2c_gui2.i2c_connection_helper module

The i2c_connection_helper module

Contains the I2C_Connection_Helper class, which is only a base class from which derived classes which implement I2C communication should inherit from.

class i2c_gui2.i2c_connection_helper.I2C_Connection_Helper(max_seq_byte: int, successive_i2c_delay_us: int = 10000, no_connect: bool = False)

Bases: object

Base Class to handle an I2C Connection

This is a base class from which derived classes should inherit and implement the necessary methods.

This base class sets up many of the internal features of an I2C connection, such as an internal log for logging I2C activity.

Parameters:

• max_seq_byte – The maximum number of bytes which can be transmitted in a single I2C command

• successive_i2c_delay_us – The minimum delay in microseconds (us) between successive I2C commands

• no_connect – Mostly used for debugging, if set to True, no physical cconnection will actually be attempted, but default values will be returned as I2C responses

check_i2c_device(device_address: int) → bool

The user method to check if a device with the device_address is connected to the I2C bus.

This method makes use of the internal method _check_i2c_device

Parameters:

device_address – The I2C address of the device to write to. It must be a 7-bit address as per the I2C standard.

Raises:

RuntimeError – If there is any problem during runtime

Returns:

bool – The presence or absence of the device with the device_address

property connected

The connected property getter method

This method returns the connection status of the I2C connection

Returns:

bool – The state of the connection

property logger

The logger property getter method

This method returns the internal logger of the I2C Connection object

Returns:

logging.Logger – The logger

read_device_memory(device_address: int, word_address: int, word_count: int = 1, address_bitlength: int = 8, address_endianness: str = 'big', word_bitlength: int = 8, word_endianness: str = 'big', read_type: str = 'Normal') → list[int]

The user method to read register data from a device on the I2C bus with the given device_address.

This method makes use of the internal method _read_i2c_device_memory

Parameters:

• device_address – The I2C address of the device to write to. It must be a 7-bit address as per the I2C standard.

• word_address – The address of the first byte to be read from.

• word_count – The number of register words to be read from the I2C device.

• address_bitlength – The bit length of the address, typical values are 8 and 16.

• address_endianness – The endianness of the address as presented on the I2C bus. This parameter does not make any difference for 8-bit addresses.

• word_bitlength – The bit length of the register words, typical values are 8 and 16.

• word_endianness – The endianness of the register words as presented on the I2C bus. This parameter does not make any difference for 8-bit register words.

• read_type – The type of protocol used for the actual reading procedure from the device. Supported protocols are “Normal” and “Repeated Start”. The Repeated Start protocol is implemented by the AD5593R chip.

Raises:

RuntimeError – If there is an issue identified during runtime

Returns:

list[int] – The list of word in order. The words have been put together according to the endianness options set.

write_device_memory(device_address: int, word_address: int, data: list[int], address_bitlength: int = 8, address_endianness: str = 'big', word_bitlength: int = 8, word_endianness: str = 'big', write_type: str = 'Normal')

The user method to write register data to a device on the I2C bus with the given device_address.

This method makes use of the internal method _write_i2c_device_memory

Parameters:

• device_address – The I2C address of the device to write to. It must be a 7-bit address as per the I2C standard.

• word_address – The address of the first byte to be written to.

• data – The register word data to be written to the I2C device.

• address_bitlength – The bit length of the address, typical values are 8 and 16.

• address_endianness – The endianness of the address as presented on the I2C bus. This parameter does not make any difference for 8-bit addresses.

• word_bitlength – The bit length of the register words, typical values are 8 and 16.

• word_endianness – The endianness of the register words as presented on the I2C bus. This parameter does not make any difference for 8-bit register words.

• write_type – The type of protocol used for the actual writing procedure to the device.

Raises:

RuntimeError – If there is an issue identified during runtime

i2c_gui2.i2c_usb_iss_helper module

class i2c_gui2.i2c_usb_iss_helper.USB_ISS_Helper(port: str, clock: int, use_serial: bool = False, baud_rate: int | None = None, verbose: bool = False, max_seq_byte: int = 8, dummy_connect: bool = False)

Bases: I2C_Connection_Helper

Class to handle the USB-ISS connection

This class is a wrapper around the usb_iss library, providing a simplified interface for the usage in the ETROC DAQ assuming only I2C is used, with optional GPIO for the extra pins

Parameters:

• port – The port where the USB-ISS device can be found

• clock – The clock frequency to use for I2C communication. It must be a valid clock from the list: 20, 50, 100, 400, 1000. For clock frequencies where there is both software and hardware support, the hardware version will be given precedence.

• use_serial – Whether to use the extra pins on the USB-ISS as a serial interface, if not they will be GPIO (by default set to analog in). The serial port is only enabled if the baud rate is also set.

• baud_rate – The baud rate to use for the serial communication

• verbose – Whether to output detailed information to the terminal

• max_seq_byte – The maximum number of sequential bytes supported in a single I2C message. The limit is not necessarily from the USB-ISS and may be from the device it is communicating with. TODO: Add an option to set this limit per operation so different limits can be set for different devices.

• dummy_connect – If set, the connection to the USB-ISS will be emulated and a dummy device will be configured

Raises:

• SerialException – If the serial object can not be found

• ValueError – If a wrong value is passed to the clock configuration

• RuntimeError – For other issues communicating with the USB-ISS device

Examples

>>> import i2c_gui2
>>> usbiss = i2c_gui2.USB_ISS_Helper("/dev/ttyACM0")
>>> usbiss.version()

property baud_rate: int | None

The baud_rate property getter method

This method returns the baud rate the extra pins on the USB-ISS used as a serial communication are set to

Returns:

• int – If the extra pins on the USB-ISS are being used as a serial communication

• None – If the USB-ISS is not configured to use the serial port for communication

property clock: int

The clock property getter method

This method returns the clock frequency the USB-ISS I2C is configured to

Returns:

int – The clock frequency.

property fw_version: int

The fw_version property getter method

This method returns the firmware version of the USB-ISS firmware

Returns:

int – The firmware version number.

property port: str

The port property getter method

This method returns the port the USB-ISS is connected to

Returns:

str – The port.

property serial: str

The serial_number property getter method

This method returns the serial number of the USB-ISS firmware

Returns:

str – The serial number.

property use_serial: bool

The use_serial property getter method

This method returns if the extra pins on the USB-ISS are being used as a serial communication

Returns:

bool – If the extra pins on the USB-ISS are being used as a serial communication

i2c_gui2.etroc1_gui module

The ETROC1 GUI module

This is a utility module which serves as a wrapper for the ETROC1 GUI module so it can be called from the command line

i2c_gui2.etroc1_gui.main(args=None)

This is the main entry function for the command line interface

i2c_gui2.etroc2_gui module

i2c_gui2.chips submodule

i2c_gui2.chips.address_space_controller module

class i2c_gui2.chips.address_space_controller.Address_Space_Controller(name: str, i2c_address: int, address_space_size: int, logger: Logger, i2c_connection: I2C_Connection_Helper, address_bitlength: int = 8, address_endianness: str = 'big', word_bitlength: int = 8, word_endianness: str = 'big', read_type: str = 'Normal', write_type: str = 'Normal', address_space_map: dict = {})

Bases: object

get_register(block_name, register_name)

get_register_address(block_name, register_name)

read_all()

read_block(block_name)

read_memory_block(base_address, word_count)

read_memory_word(address)

read_register(block_name, register_name)

reset_to_defaults()

set_register(block_name, register_name, value)

update_i2c_address(address: int)

write_all(readback_check: bool = True)

write_block(block_name, readback_check: bool = True)

write_memory_block(base_address, word_count, readback_check: bool = True, readback_base_address=None)

write_memory_block_with_split_for_read_only(base_address, word_count, readback_check: bool = True, readback_base_address=None)

write_memory_word(address, readback_check: bool = True, readback_address=None)

write_register(block_name, register_name, readback_check: bool = True)

i2c_gui2.chips.base_chip module

class i2c_gui2.chips.base_chip.Base_Chip(chip_name: str, i2c_connection: I2C_Connection_Helper, logger: Logger, software_version: str = '', register_model=None, register_decoding=None, indexer_info=None)

Bases: object

property enable_readback

get_decoded_value(address_space_name: str, block_name: str, decoded_value_name: str)

get_indexer_array(indexer_info)

get_indexer_info(name)

property id

load_config(config_file: str)

load_pickle_file(config_file: str)

newid = count(0)

read_all()

read_all_address_space(address_space_name: str, no_message: bool = True)

read_all_block(address_space_name: str, block_name: str, full_array: bool = False, no_message: bool = True)

read_decoded_value(address_space_name: str, block_name: str, decoded_value_name: str, no_message: bool = False)

read_register(address_space_name: str, block_name: str, register: str, no_message: bool = True)

reset_config_to_default()

save_config(config_file: str)

save_pickle_file(config_file: str, object)

set_decoded_value(address_space_name: str, block_name: str, decoded_value_name: str, value: int)

set_indexer(name, value)

write_all(readback_check: bool = True)

write_all_address_space(address_space_name: str, readback_check: bool = True, no_message: bool = True)

write_all_block(address_space_name: str, block_name: str, full_array: bool = False, readback_check: bool = True, no_message: bool = True)

write_decoded_value(address_space_name: str, block_name: str, decoded_value_name: str, write_check: bool = True, no_message: bool = False)

write_register(address_space_name: str, block_name: str, register: str, readback_check: bool = True, no_message: bool = True)

i2c_gui2.chips.etroc2_chip module

class i2c_gui2.chips.etroc2_chip.ETROC2_Chip(etroc2_i2c_address, waveform_sampler_i2c_address, i2c_connection: I2C_Connection_Helper, logger: Logger)

Bases: Base_Chip

property broadcast: bool

property col: int

property etroc2_i2c_address: int

read_all_efficient()

This read function will only read the named register addresses in the ETROC2 manual. There are many addresses which are not named and as a result are not read. In principle, these addresses are not used for anything and may not even be implemented in the chip, but by using this function we are essentially blind to what is happening on these unnamed addresses

property row: int

property waveform_sampler_i2c_address: int

write_all_address_space(address_space_name: str, readback_check: bool = True, no_message: bool = True)

write_all_block(address_space_name: str, block_name: str, full_array: bool = False, readback_check: bool = True, no_message: bool = True)

write_all_efficient(readback_check: bool = True)

This write function will only write the named register addresses in the ETROC2 manual. There are many addresses which are not named and as a result are not written. In principle, these addresses are not used for anything and may not even be implemented in the chip, but by using this function we are essentially not setting these unnamed addresses

write_decoded_value(address_space_name: str, block_name: str, decoded_value_name: str, write_check: bool = True, no_message: bool = False)

write_register(address_space_name: str, block_name: str, register: str, readback_check: bool = True, no_message: bool = True)

i2c_gui2.chips.etroc2_chip.etroc2_column_row_to_base_address(block: str, column: int, row: int, broadcast: bool = False)

i2c_gui2.chips.etroc1_chip module

class i2c_gui2.chips.etroc1_chip.ETROC1_Chip(i2c_address_a, i2c_address_b, i2c_address_full_pixel, i2c_address_tdc_test_block, i2c_connection: I2C_Connection_Helper, logger: Logger)

Bases: Base_Chip

property i2c_address_a: int

property i2c_address_b: int

property i2c_address_full_pixel: int

property i2c_address_tdc_test_block: int

i2c_gui2.chips.ad5593r_chip module

class i2c_gui2.chips.ad5593r_chip.AD5593R_Chip(i2c_address, i2c_connection: I2C_Connection_Helper, logger: Logger)

Bases: Base_Chip

property i2c_address: int

read_adc_results(adc_sequence: int, num_measurements: int)