Utilities#
- class Utilities
Common utility class. Utility functions common for all types of drivers.
Access snippet:
utils = RsFsw.utilities- property logger: ScpiLogger
Scpi Logger interface, see here
Access snippet:
logger = RsFsw.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: BinFloatFormat
Sets / returns format of float numbers when transferred as binary data.
- property bin_int_numbers_format: 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] | None
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()
Note: If status-error suppression rules are configured (see status_error_suppression_add_rule()), errors matching those rules are filtered out and will not appear in the returned list.
- query_all_errors_with_codes ( ) List[Tuple[int, str]] | None
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.
Note: If status-error suppression rules are configured (see status_error_suppression_add_rule()), errors matching those rules are filtered out and will not appear in the returned list.
- reset ( ) None
SCPI command:
*RSTSends*RSTcommand + calls the clear_status().
- default_instrument_setup ( ) None
Custom steps performed at the init and at the reset().
- self_test ( timeout: int | None = 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: str
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: str
Returns the manufacturer of the current VISA session.
- process_all_commands ( ) None
SCPI command:
*WAIStops further commands processing until all commands sent before*WAIhave 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
- write_int_with_opc ( cmd: str, param: int, timeout: int | None = None ) None
Writes the command to the instrument followed by the integer parameter: e.g.: cmd = ‘SELECT:INPUT’ param = ‘2’, result command = ‘SELECT:INPUT 2’
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
- write_float_with_opc ( cmd: str, param: float, timeout: int | None = None ) None
Writes the command to the instrument followed by the boolean parameter: e.g.: cmd = ‘CENTER:FREQ’ param = ‘10E6’, result command = ‘CENTER:FREQ 10E6’
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
- write_bool_with_opc ( cmd: str, param: bool, timeout: int | None = None ) None
Writes the command to the instrument followed by the boolean parameter: e.g.: cmd = ‘OUTPUT’ param = ‘True’, result command = ‘OUTPUT ON’
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: int | None = 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: int | None = 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: int | None = 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: int | None = 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: int | None = 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: int | None = 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: int | None = 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
- query_bin_block_with_opc ( query: str, timeout: int | None = None ) bytes
Queries binary data block to bytes. Throws an exception if the returned data was not a binary data. Returns data: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]
- query_str_list_with_opc ( query: str, timeout: int | None = None, 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 [].
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]
- query_bool_list_with_opc ( query: str, timeout: int | None = None ) 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.
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]
- query_bin_or_ascii_float_list_with_opc ( query: str, timeout: int | None = None ) 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).
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]
- query_bin_or_ascii_int_list_with_opc ( query: str, timeout: int | None = None ) 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).
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
- query_bin_block_to_file_with_opc ( query: str, file_path: str, append: bool = False, timeout: int | None = None ) 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()
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_fileto 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 ( mixed_mode: bool = True ) None
Puts the instrument into local state. By default, the method uses a mechanism to keep the instrument in a mixed mode: remote and local. That means, you can remote-control your instrument, and at the same time it still allows manual control. Set the mixed_mode to False, if you want your instrument to go to remote mode as soon as it receives the first remote command.
- go_to_remote ( ) None
Puts the instrument into remote state.
- get_lock ( ) RLock
Returns the thread lock for the current session.
By default,
If you create standard new RsFsw instance with new VISA session, the session gets a new thread lock. You can assign it to other RsFsw sessions in order to share one physical instrument with a multi-thread access.
If you create new RsFsw 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: 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: int | List[int] | None = None ) 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 ) 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: Utilities ) None
Synchronizes these Utils with the source.
- 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.
- has_instr_option ( options: str | List[str] ) bool
Returns true, if the entered options (case-insensitive) matches at least one of the installed options (or-logic). You can enter either a string with one option, or more options ‘/’-separated, or more options as a list of strings. If K0 is present, all the K-options are reported as present. B-options are not affected by K0. Example 1: options=’k23’ returns true, if the instrument has the option ‘K23’. Example 2: options=’k23 / K23e’ returns true, if the instrument has either the option ‘K23’ or the option ‘K23E’. Example 3: options=[‘k11’,’K22’] returns true, if the instrument has either the option ‘K11’ or the option ‘K22’.
- has_instr_option_regex ( re_options: str | List[str] ) bool
Returns true, if the entered regex string (case-insensitive) matches at least one of the installed options. The match must be complete, not just partial (search). You can enter either a string with one option, or more options ‘/’-separated, or more options as a list of strings. Example 1: re_options=’k10.’ returns true, if the instrument contains any option ‘K100’ … up to ‘K109’ . Example 2: re_options=’k10. / k20.*’ returns true, if the instrument contains any of the options ‘K10x’ or ‘K20xxx’. Example 3: re_options=[‘k10.’, ‘k20.*’] returns true, if the instrument contains any options ‘K10x’ or ‘K20xxx’.
- has_instr_option_k0 ( ) bool
Returns true, if the instrument has K0 installed.
- add_instr_option ( option: str ) None
Adds new option if not already existing.
- remove_instr_option ( option: str ) None
Removes the option if exists.
- check_status ( ) None
Throws InstrumentStatusException in case of an error in the instrument’s error queue. The status checking is performed always, independent of the property ‘instrument_status_checking’. Also, the property ScpiLogger.log_status_check_ok is ignored, and the Status check is always logged.