rminstr.instruments.communications

Exceptions

InstrumentError	InstrumentErrors are raised when an instrument is in an error state.
SettingError	InstrumentErrors are raised when a bad seeting is passed.

Classes

Instrument	Wrapper for pyvisa Resource objects. This class exists to standardize the interface of derived instruments.
TSPRunner	Protocols for interacting with TSP enabled instruments.
GPIBInterface	Calorimeter-python GPIB Interface for group triggering.

Functions

get_bit(x, bit)	Return a specific bit in x. Intended to make the status byte easier to read.
do_after_group_trigger(*instruments)	Call to have instruments perform post triggering commands.
ext_trigger(self, *instruments)	Call when an external trigger occurs so that the state model and other things can be updated.

Package Contents

class rminstr.instruments.communications.Instrument(visa_resource)

Bases: abc.ABC

Wrapper for pyvisa Resource objects. This class exists to standardize the interface of derived instruments.

Attributes

visa_resourcevisa.Resource

Pyvisa resource object of the connected instrument.

time_zerofloat

Absolute time for relative timestamps.

Initiate the instrument.

Parameters:

visa_resourcevisa.Resources

The pyvisa resource.

Returns:

None.

visa_resource

time_zero = None

write(txt)

Shortened version of self.visa_resource.write(txt).

Parameters:

txtstr

Text to write.

Returns:

None.

read_stb(num_attempts=3)

Shortened version of self.visa_resource.read_stb().

Parameters:

num_attemptsint, optional

Number of attempts for reading the status bit if there is an error. The default is 3.

Returns:

str

The status_byte.

read()

Shortened version of self.visa_resource.read().

Returns:

str

Result of self.visa_resource.read().

query(txt)

Shortened version of self.visa_resource.query().

Parameters:

txtstr

The text to query.

Returns:

str

Result of self.visa_resource.query().

read_bytes(n)

Shortened version of self.visa_resource.read_bytes(n).

Parameters:

nint

Number of bytes to read

Returns:

str

Result of self.visa_resource.read_bytes(n)

set_time_zero(time_zero=None)

Set time zero for relative timestamps.

Parameters:

time_zerofloat, optional

Time zero for relative timestamps if None, use the result of time.time(). The default is None.

Returns:

None.

clear_output()

Clear the output buffer on the instrument connection.

Returns:

None.

get_relative_time()

Get the relataive time since instantiation.

Use for making timestamps. Returns the result of time.time() - time_zero.

Returns:

float

Time relative to self.time_zero

get_info()

Get instrument metadata you may want to keep track of.

Returns:

dict

Keys: ex. “GPIB address” Values: ex. 11

abstract raise_errors()

Query the instrument status.

Query the status of the instrument. If there are errors, raise them as Python errors. Abstract method.

Returns:

None.

abstract get_errors()

Query the instrument errors.

Query the status of the instrument. Returns errors as a string. Abstract method.

Returns:

None.

rminstr.instruments.communications.get_bit(x, bit)

Return a specific bit in x. Intended to make the status byte easier to read.

Parameters:

xint

Value to get bit from

bitint

A power of 2: 1, 2, 4, 8, 16, 32, 64, 128 I.E. the 5th bit would be 2^5 = 32

Returns:

True if the bit is 1, False otherwise

exception rminstr.instruments.communications.InstrumentError(message)

Bases: Exception

InstrumentErrors are raised when an instrument is in an error state.

Initialize self. See help(type(self)) for accurate signature.

exception rminstr.instruments.communications.SettingError(message)

Bases: Exception

InstrumentErrors are raised when a bad seeting is passed.

Initialize self. See help(type(self)) for accurate signature.

class rminstr.instruments.communications.TSPRunner(visa_resource)

Bases: rminstr.instruments.communications.Instrument

Protocols for interacting with TSP enabled instruments.

The TSPRunner is a communication class that inherits from instrument, the more fundemental communication object. It is design to handle communication over pyvisa with instruments that are tsp enabled, and expect tsp langauage commands (Lua).

Attributes

timeoutfloat

Seconds for timeout when trying to read off data.

stb_regdict

Dictionary of status byte bit places.

termination_strstr

Termination string that is sent at the end of run scripts to signal its end.

busybool

If True, it means that the instrument is running a tsp script, trying to command it at that moment will raise an error.

busy_countint

Counter for busy checks, used in some methods for debugging.

logsbool

When True, the class will print logs of commands, states, and other debugging information to the console.

last_scrstr

String of the last tsp script that was commmanded to run through run_script.

Initialize a tsp instrument.

Parameters:

visa_resourcevisa.Resource

Pyvisa resource that is the tsp enabled instrument.

Returns:

None.

info_dict

timeout = 2

stb_reg

termination_str = 'script_complete'

busy = False

busy_count = 0

logs = False

last_scr = ''

get_info()

Get machine info.

Returns:

dict

instrument information.

raise_errors()

Raise an error if error bit is high on instrument.

Needs to be reworked to actually get the error message, TSP scripts block sending commands for error information, need to work out a protocl that accounts for this. Currently, this will just raise an error, telling you to check the instrument.

Returns:

None

Raises:

InstrumentError

Error if the error bit is high.

get_output_bit(bit: int)

Check a bit in the status byte register.

Parameters:

bitint

Bit placement you want to check.

Returns:

bool

Returns True if bit is high. False otherwise.

tsp_trace()

Print the status of the TSPRunner instance.

Returns:

None.

check_busy(showGarbage: bool = False)

Check if the instrument is busy running a TSP script.

Checks if the instrument is busy by checking for termination strings, and applying a zero order hold where the termination string sets the status False, not busy, and sending a run script command sets the status True, busy.

Parameters:

showGarbagebool, optional

If true, logs information about the method. The default is False.

Returns:

bool

True if busy, False if not.

check_error_bit()

Generate a status byte error if the error bit is high.

Returns:

None.

Raises:

StatusByteError

Error if the error bit in the status byte is high.

wait(timeout: float)

Wait until not busy, raise error if takes longer than timeout seconds.

Parameters:

timeoutfloat

Time to wait before raising an error.

Returns:

None.

Raises:

SMUTimeoutError

Error if the SMU is busy for longer than the timeout amount.

flush_readout()

Flushes the output buffer of the tsp enabled instrument.

Returns:

None.

get_errors()

Either prints outs instrument events or raises and error if the event is an error.

Returns:

None.

Raises:

Exception

Error if the SMU shows an error in its events.

assign(varname: str, val: int | float)

Assign a variable to the TSP instruments global variable space.

Assigns a variable to the global namespace of the instrument. val is cast as str(variable). If the tsp namespace variable is being assign a string, enclose in quationtion marks. eg. val = “‘string’”. This is not the best and could be reworked to account for more data types.

Parameters:

varnamestr

Name of the variable that will be used in the tsp instruments namespace.

valfloat or int

The value to assign.

Returns:

None.

print_number(varname: str)

Command the TSP instument to print a number from its namespace.

Parameters:

varnamestr

String of tsp namespace variable.

Returns:

None.

query_print(msg)

Query the instrument.

Parameters:

msgstr

String of message type to have it print.

Returns:

str

Message query.

run_script(scriptVar: str, force: bool = False)

Run a TSP script stored on the instruments memory.

Parameters:

scriptVarstr

String of script name on instruments non-volatile memory.

forcebool, optional

If true, will by-pass the busy checks. The default is False.

Returns:

None.

Raises:

BusyError

If force is False and instrument is busy while trying to be commanded, this will be raised.

read_buffer(deleteBuffer: bool = True)

Read data from a data buffer of the TSP instrument.

This is the general purpose function for reading data off the instruments memory buffer. This could be better generalized to usable for buffers with different names, and for getting different types of data from the buffer.

Parameters:

deleteBufferbool, optional

If true, read buffer will deallocate the buffer from the instruments memory after the data has been read. The default is True.

Returns:

dict

Dictionary of values from instrument. They are ‘time’, ‘measure’, ‘source.’

Raises:

BusyError

If instrument is busy when asking for data.

SMUTimeoutError

If instrument isn’t busy, but a timeout occured while trying to download the data.

load_script(project_name: str, script_name: str, file_names: list[str])

Load a tsp project saved in the package’s TSP directory.

Parameters:

project_namestr

The name of the project, directory name in instruments//TSP.

script_namestr

The name to save the script as on the tsp instrument memory.

file_nameslist [str]

List of files in the project, in order to be loaded onto the tsp instrument.

Returns:

None.

rminstr.instruments.communications.do_after_group_trigger(*instruments)

Call to have instruments perform post triggering commands.

Will call each instruments do_after_group_trigger() method, as well as reset measurement start time, if applicable.

Parameters:

*instrumentsinstruments.communications.instrument

List of instruments to perform the post triggering commands on.

Returns:

float

Trigger time, from time.time() at the beginning of this method.

rminstr.instruments.communications.ext_trigger(self, *instruments)

Call when an external trigger occurs so that the state model and other things can be updated.

Parameters:

*instruments

List of instruments to perform the external trigger on.

Returns:

None.

class rminstr.instruments.communications.GPIBInterface(interface_address: str, resource_manager: pyvisa.ResourceManager = None)

Calorimeter-python GPIB Interface for group triggering.

This is a wrapper for the pyvisa interface, and handles state model management within calorimeter-python objects.

Attributes

interfacevisa.Resource

GPIB pyvisa resource

Initialize the interface.

Parameters:

interface_addressstr

GPIB interface of form “GPIBX::INTFC”.

resource_manager_visa.ResourceManager, optional

Resource manager to instantiate interface with. If none provided, a manager will be instantiated. The default is None

Returns:

None.

interface

group_trigger(*instruments: rminstr.instruments.communications.Instrument)

Send a group-execute-trigger (GET) signal to all instruments.

Instruments being triggered should all be positional arguments. Non GPIB instruments will have their visa_resource.assert_trigger() method called immediately following the GET command, and a warning will be raised to the user.

Instrument classes that require additional commands/logic to manage their state models following a group_trigger command are expected to have a “do_after_group_trigger()” class instance method that takes no arguments. Any instrument class with this method will have it called immediately following the GET.

Parameters:

*instrumentsinstruments.communications.instrument

Positional arguments all calorimeter-python instrument objects.

Returns:

float

Clock time at do_after_group_trigger() time. Should be very close to GET signal.

close()

Close the instrument.