RsSmw Utilities

class Utilities

Common utility class. Utility functions common for all types of drivers.

Access snippet: utils = RsSmw.utilities

property logger: RsSmw.Internal.ScpiLogger.ScpiLogger

Scpi Logger interface, see here

Access snippet: logger = RsSmw.utilities.logger

property driver_version: str

Returns the instrument driver version.

property idn_string: str

Returns instrument’s identification string - the response on the SCPI command *IDN?

property manufacturer: str

Returns manufacturer of the instrument.

property full_instrument_model_name: str

Returns the current instrument’s full name e.g. ‘FSW26’.

property instrument_model_name: str

Returns the current instrument’s family name e.g. ‘FSW’.

property supported_models: List[str]

Returns a list of the instrument models supported by this instrument driver.

property instrument_firmware_version: str

Returns instrument’s firmware version.

property instrument_serial_number: str

Returns instrument’s serial_number.

query_opc(timeout: int = 0) → int

SCPI command: *OPC? Queries the instrument’s OPC bit and hence it waits until the instrument reports operation complete. If you define timeout > 0, the VISA timeout is set to that value just for this method call.

property instrument_status_checking: bool

Sets / returns Instrument Status Checking. When True (default is True), all the driver methods and properties are sending “SYSTem:ERRor?” at the end to immediately react on error that might have occurred. We recommend to keep the state checking ON all the time. Switch it OFF only in rare cases when you require maximum speed. The default state after initializing the session is ON.

property encoding: str

Returns string<=>bytes encoding of the session.

property opc_query_after_write: bool

Sets / returns Instrument *OPC? query sending after each command write. When True, (default is False) the driver sends *OPC? every time a write command is performed. Use this if you want to make sure your sequence is performed command-after-command.

property bin_float_numbers_format: RsSmw.Internal.Conversions.BinFloatFormat

Sets / returns format of float numbers when transferred as binary data.

property bin_int_numbers_format: RsSmw.Internal.Conversions.BinIntFormat

Sets / returns format of integer numbers when transferred as binary data.

clear_status() → None

Clears instrument’s status system, the session’s I/O buffers and the instrument’s error queue.

query_all_errors() → List[str]

Queries and clears all the errors from the instrument’s error queue. The method returns list of strings as error messages. If no error is detected, the return value is None. The process is: querying ‘SYSTem:ERRor?’ in a loop until the error queue is empty. If you want to include the error codes, call the query_all_errors_with_codes()

query_all_errors_with_codes() → List[Tuple[int, str]]

Queries and clears all the errors from the instrument’s error queue. The method returns list of tuples (code: int, message: str). If no error is detected, the return value is None. The process is: querying ‘SYSTem:ERRor?’ in a loop until the error queue is empty.

property instrument_options: List[str]

Returns all the instrument options. The options are sorted in the ascending order starting with K-options and continuing with B-options.

reset() → None

SCPI command: *RST Sends *RST command + calls the clear_status().

default_instrument_setup() → None

Custom steps performed at the init and at the reset().

self_test(timeout: Optional[int] = None) → Tuple[int, str]

SCPI command: *TST? Performs instrument’s self-test. Returns tuple (code:int, message: str). Code 0 means the self-test passed. You can define the custom timeout in milliseconds. If you do not define it, the default selftest timeout is used (usually 60 secs).

is_connection_active() → bool

Returns true, if the VISA connection is active and the communication with the instrument still works.

reconnect(force_close: bool = False) → bool

If the connection is not active, the method tries to reconnect to the device If the connection is active, and force_close is False, the method does nothing. If the connection is active, and force_close is True, the method closes, and opens the session again. Returns True, if the reconnection has been performed.

property resource_name: int

Returns the resource name used in the constructor

property opc_timeout: int

Sets / returns timeout in milliseconds for all the operations that use OPC synchronization.

property visa_timeout: int

Sets / returns visa IO timeout in milliseconds.

property data_chunk_size: int

Sets / returns the maximum size of one block transferred during write/read operations

property visa_manufacturer: int

Returns the manufacturer of the current VISA session.

process_all_commands() → None

SCPI command: *WAI Stops further commands processing until all commands sent before *WAI have been executed.

write_str(cmd: str) → None

Writes the command to the instrument.

write(cmd: str) → None

This method is an alias to the write_str(). Writes the command to the instrument as string.

write_int(cmd: str, param: int) → None

Writes the command to the instrument followed by the integer parameter: e.g.: cmd = ‘SELECT:INPUT’ param = ‘2’, result command = ‘SELECT:INPUT 2’

write_int_with_opc(cmd: str, param: int, timeout: Optional[int] = None) → None

Writes the command with OPC to the instrument followed by the integer parameter: e.g.: cmd = ‘SELECT:INPUT’ param = ‘2’, result command = ‘SELECT:INPUT 2’ If you do not provide timeout, the method uses current opc_timeout.

write_float(cmd: str, param: float) → None

Writes the command to the instrument followed by the boolean parameter: e.g.: cmd = ‘CENTER:FREQ’ param = ‘10E6’, result command = ‘CENTER:FREQ 10E6’

write_float_with_opc(cmd: str, param: float, timeout: Optional[int] = None) → None

Writes the command with OPC to the instrument followed by the boolean parameter: e.g.: cmd = ‘CENTER:FREQ’ param = ‘10E6’, result command = ‘CENTER:FREQ 10E6’ If you do not provide timeout, the method uses current opc_timeout.

write_bool(cmd: str, param: bool) → None

Writes the command to the instrument followed by the boolean parameter: e.g.: cmd = ‘OUTPUT’ param = ‘True’, result command = ‘OUTPUT ON’

write_bool_with_opc(cmd: str, param: bool, timeout: Optional[int] = None) → None

Writes the command with OPC to the instrument followed by the boolean parameter: e.g.: cmd = ‘OUTPUT’ param = ‘True’, result command = ‘OUTPUT ON’ If you do not provide timeout, the method uses current opc_timeout.

query_str(query: str) → str

Sends the query to the instrument and returns the response as string. The response is trimmed of any trailing LF characters and has no length limit.

query(query: str) → str

This method is an alias to the query_str(). Sends the query to the instrument and returns the response as string. The response is trimmed of any trailing LF characters and has no length limit.

query_bool(query: str) → bool

Sends the query to the instrument and returns the response as boolean.

query_int(query: str) → int

Sends the query to the instrument and returns the response as integer.

query_float(query: str) → float

Sends the query to the instrument and returns the response as float.

write_str_with_opc(cmd: str, timeout: Optional[int] = None) → None

Writes the opc-synced command to the instrument. If you do not provide timeout, the method uses current opc_timeout.

write_with_opc(cmd: str, timeout: Optional[int] = None) → None

This method is an alias to the write_str_with_opc(). Writes the opc-synced command to the instrument. If you do not provide timeout, the method uses current opc_timeout.

query_str_with_opc(query: str, timeout: Optional[int] = None) → str

Sends the opc-synced query to the instrument and returns the response as string. The response is trimmed of any trailing LF characters and has no length limit. If you do not provide timeout, the method uses current opc_timeout.

query_with_opc(query: str, timeout: Optional[int] = None) → str

This method is an alias to the query_str_with_opc(). Sends the opc-synced query to the instrument and returns the response as string. The response is trimmed of any trailing LF characters and has no length limit. If you do not provide timeout, the method uses current opc_timeout.

query_bool_with_opc(query: str, timeout: Optional[int] = None) → bool

Sends the opc-synced query to the instrument and returns the response as boolean. If you do not provide timeout, the method uses current opc_timeout.

query_int_with_opc(query: str, timeout: Optional[int] = None) → int

Sends the opc-synced query to the instrument and returns the response as integer. If you do not provide timeout, the method uses current opc_timeout.

query_float_with_opc(query: str, timeout: Optional[int] = None) → float

Sends the opc-synced query to the instrument and returns the response as float. If you do not provide timeout, the method uses current opc_timeout.

write_bin_block(cmd: str, payload: bytes) → None

Writes all the payload as binary data block to the instrument. The binary data header is added at the beginning of the transmission automatically, do not include it in the payload!!!

query_bin_block(query: str) → bytes

Queries binary data block to bytes. Throws an exception if the returned data was not a binary data. Returns data:bytes

query_bin_block_with_opc(query: str, timeout: Optional[int] = None) → bytes

Sends a OPC-synced query and returns binary data block to bytes. If you do not provide timeout, the method uses current opc_timeout.

query_str_list(query: str, remove_blank_response: bool = False) → List[str]

Sends the string query to the instrument and returns the response as List of strings, where the delimiter is comma (‘,’). Each element of the list is trimmed for leading and trailing quotes. Meaning of the ‘remove_blank_response’:

• False(default): whitespaces-only response is returned as a list with one empty element [‘’].

• True: whitespaces-only response is returned as an empty list [].

query_str_list_with_opc(query: str, timeout: Optional[int] = None, remove_blank_response: bool = False) → List[str]

Sends a OPC-synced query and reads response from the instrument as csv-list. If you do not provide timeout, the method uses current opc_timeout. Meaning of the ‘remove_blank_response’:

• False(default): whitespaces-only response is returned as a list with one empty element [‘’].

• True: whitespaces-only response is returned as an empty list [].

query_bool_list(query: str) → List[bool]

Sends the string query to the instrument and returns the response as List of booleans, where the delimiter is comma (‘,’). Blank or empty response is returned as an empty list.

query_bool_list_with_opc(query: str, timeout: Optional[int] = None) → List[bool]

Sends a OPC-synced query and reads response from the instrument as csv-list of booleans. If you do not provide timeout, the method uses current opc_timeout. Blank or empty response is returned as an empty list.

query_bin_or_ascii_float_list(query: str) → List[float]

Queries a list of floating-point numbers that can be returned in ASCII format or in binary format. - For ASCII format, the list numbers are decoded as comma-separated values. - For Binary Format, the numbers are decoded based on the property BinFloatFormat, usually float 32-bit (FORM REAL,32).

query_bin_or_ascii_float_list_with_opc(query: str, timeout: Optional[int] = None) → List[float]

Sends a OPC-synced query and reads a list of floating-point numbers that can be returned in ASCII format or in binary format. - For ASCII format, the list numbers are decoded as comma-separated values. - For Binary Format, the numbers are decoded based on the property BinFloatFormat, usually float 32-bit (FORM REAL,32). If you do not provide timeout, the method uses current opc_timeout.

query_bin_or_ascii_int_list(query: str) → List[int]

Queries a list of floating-point numbers that can be returned in ASCII format or in binary format. - For ASCII format, the list numbers are decoded as comma-separated values. - For Binary Format, the numbers are decoded based on the property BinFloatFormat, usually float 32-bit (FORM REAL,32).

query_bin_or_ascii_int_list_with_opc(query: str, timeout: Optional[int] = None) → List[int]

Sends a OPC-synced query and reads a list of floating-point numbers that can be returned in ASCII format or in binary format. - For ASCII format, the list numbers are decoded as comma-separated values. - For Binary Format, the numbers are decoded based on the property BinFloatFormat, usually float 32-bit (FORM REAL,32). If you do not provide timeout, the method uses current opc_timeout.

query_bin_block_to_file(query: str, file_path: str, append: bool = False) → None

Queries binary data block to the provided file. If append is False, any existing file content is discarded. If append is True, the new content is added to the end of the existing file, or if the file does not exit, it is created. Throws an exception if the returned data was not a binary data. Example for transferring a file from Instrument -> PC: query = f”MMEM:DATA? ‘{INSTR_FILE_PATH}’”. Alternatively, use the dedicated methods for this purpose:

• send_file_from_pc_to_instrument()

• read_file_from_instrument_to_pc()

query_bin_block_to_file_with_opc(query: str, file_path: str, append: bool = False, timeout: Optional[int] = None) → None

Sends a OPC-synced query and writes the returned data to the provided file. If append is False, any existing file content is discarded. If append is True, the new content is added to the end of the existing file, or if the file does not exit, it is created. Throws an exception if the returned data was not a binary data.

write_bin_block_from_file(cmd: str, file_path: str) → None

Writes data from the file as binary data block to the instrument using the provided command. Example for transferring a file from PC -> Instrument: cmd = f”MMEM:DATA ‘{INSTR_FILE_PATH}’,”. Alternatively, use the dedicated methods for this purpose:

• send_file_from_pc_to_instrument()

• read_file_from_instrument_to_pc()

send_file_from_pc_to_instrument(source_pc_file: str, target_instr_file: str) → None

SCPI Command: MMEM:DATA

Sends file from PC to the instrument

read_file_from_instrument_to_pc(source_instr_file: str, target_pc_file: str, append_to_pc_file: bool = False) → None

SCPI Command: MMEM:DATA?

Reads file from instrument to the PC.

Set the append_to_pc_file to True if you want to append the read content to the end of the existing PC file

get_last_sent_cmd() → str

Returns the last commands sent to the instrument. Only works in simulation mode

go_to_local() → None

Puts the instrument into local state.

go_to_remote() → None

Puts the instrument into remote state.

get_lock() → threading.RLock

Returns the thread lock for the current session.

By default:

• If you create standard new RsSmw instance with new VISA session, the session gets a new thread lock. You can assign it to other RsSmw sessions in order to share one physical instrument with a multi-thread access.

• If you create new RsSmw from an existing session, the thread lock is shared automatically making both instances multi-thread safe.

You can always assign new thread lock by calling driver.utilities.assign_lock()

assign_lock(lock: threading.RLock) → None

Assigns the provided thread lock.

clear_lock()

Clears the existing thread lock, making the current session thread-independent from others that might share the current thread lock.

instr_err_suppressor(visa_tout_ms: int = 0, suppress_only_codes: Optional[int] = None) → RsSmw.Internal.ContextManagers.InstrErrorSuppressor

Returns Context Manager that suppresses the instrument errors. Other exceptions types are still raised. On entering the context, this class clears all the instrument status errors. :param visa_tout_ms: VISA Timeout in milliseconds, that is set for this context. Afterward, it is changed back. Default value: do-not-change. :param suppress_only_codes: You can enter a code or list of codes for errors to be suppressed. Other errors will be reported. Example: If you enter -113 here, only the ‘Undefined Header’ error will be suppressed. Default value: suppress-all-errors.

visa_tout_suppressor(visa_tout_ms: int = 0) → RsSmw.Internal.ContextManagers.VisaTimeoutSuppressor

Returns Context Manager that suppresses the VISA timeout error. Careful!!!: Only the very first VISA Timeout exception is suppressed, and afterward the context ends. Therefore, use only one command per context manager, if you do not want to skip the following ones. :param visa_tout_ms: VISA Timeout in milliseconds, that is set for this context. Afterward, it is changed back. Default value: do-not-change.

sync_from(source: RsSmw.CustomFiles.utilities.Utilities) → None

Synchronises these Utils with the source.