RsInstrument Python

https://rsinstrument.readthedocs.io/en/latest
Admin
RsInstrument is a Python package designed for instrument control, offering features for session...
Tokens:59,527
Snippets:301
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Python RsInstrument Shared Logging Example

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

This Python script demonstrates setting up a global logging target and relative timestamp for multiple RsInstrument instances. It shows how to initialize instruments, log custom messages, query device information, and retrieve execution times, with the log output directed to a shared file and console. The example includes the expected console output and explains the setup for shared logging.

```Python
"""
Example of logging to a file shared by multiple sessions.
The log file and the reference timestamp is set to the RsInstrument class variable,
which makes it available to all the instances immediately.
Each instance must set the LogToGlobalTarget=True in the constructor,
or later io.logger.set_logging_target_global().
"""

from RsInstrument import *
import os
from pathlib import Path
from datetime import datetime

RsInstrument.assert_minimum_version('1.102.0')

# Log file common for all the RsInstrument instances, saved in the same folder as this script,
# with the same name as this script, just with the suffix .ptc
# The previous file content is discarded.
log_file = open(Path(os.path.realpath(__file__)).stem + ".ptc", 'w')
RsInstrument.set_global_logging_target(log_file)

# If you do now care about the absolute times,
# here you can set relative timestamp of the first incoming entry.
RsInstrument.set_global_logging_relative_time_of_first_entry()

# Setting of the SMW: log to the global target and to the console
smw = RsInstrument(
    resource_name='TCPIP::10.102.12.13::hislip0',
    options=f'LoggingMode=On, LoggingToConsole=True, LoggingName=SMW, LogToGlobalTarget=On')

# Setting of the SMCV: log to the global target and to the console
smcv = RsInstrument(
    resource_name='TCPIP::10.102.12.14::hislip0',
    options='LoggingMode=On, LoggingToConsole=True, LoggingName=SMCV, LogToGlobalTarget=On')

smw.logger.info_raw("> Custom log entry from SMW session")
smw.reset()
smcv.logger.info_raw("> Custom log entry from SMCV session")
idn = smcv.query('*IDN?')
# Close the sessions
smw.close()
smcv.close()
# Show how much time each instrument needed for its operations.
smw.logger.info_raw("> SMW execution time: " + str(smw.get_total_execution_time()))
smcv.logger.info_raw("> SMCV execution time: " + str(smcv.get_total_execution_time()))

# Close the log file
log_file.close()

```

--------------------------------

### RsInstrument Relative Time Logging Example

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates setting up relative time logging using constructor options and methods, and shows how to retrieve execution and program times. Includes resetting time statistics.

```python
1"""
2Logging example with:
3 - Logging to the console.
4 - Initialization in the constructor.
5 - Time will be relative to the first log entry.
6 - Time statistics at the end.
7"""
8import time
9
10from RsInstrument import *
11
12RsInstrument.assert_minimum_version('1.102.0')
13instr = RsInstrument(
14    'TCPIP::192.168.1.101::hislip0',
15    options='LoggingToConsole=True, LoggingMode=On, LoggingRelativeTimeOfFirstEntry=True')
16
17print('\nEntries above come from the constructor.\n')
18idn = instr.query('*IDN?')
19# Pause for 1 second, to amplify the difference between
20# simple time delta get_total_time() and the get_total_execution_time().
21time.sleep(1.0)
22instr.reset()
23
24print('\nCommunication time spent: ' + str(instr.get_total_execution_time()))
25print('Program time spent:       ' + str(instr.get_total_time()))
26
27instr.reset_time_statistics()
28print('\nWe can reset the time stats to start from 0 again:\n')
29
30# Also, the next log entry will have the start time set to 00:00:00.000
31instr.logger.set_time_offset_zero_on_first_entry()
32
33# Again, pause for 500 milliseconds to see
34# the difference between the get_total_time() and the get_total_execution_time().
35time.sleep(0.5)
36instr.check_status()
37
38# Close the session
39instr.close()
40
41print('\nCommunication time spent: ' + str(instr.get_total_execution_time()))
42print('Program time spent:       ' + str(instr.get_total_time()))

```

--------------------------------

### Initialize RsInstrument Session and Query Instrument IDN

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

This example demonstrates how to establish a connection to a VISA instrument using the RsInstrument Python module. It shows various resource string formats for different physical interfaces (LAN, GPIB, USB, R&S Powersensor) and queries basic instrument identification information such as IDN, driver version, VISA manufacturer, and installed options. It also includes a check for the minimum required RsInstrument driver version.

```Python
from RsInstrument import *

# A good practice is to assure that you have a certain minimum version installed
RsInstrument.assert_minimum_version('1.102.0')
resource_string_1 = 'TCPIP::192.168.2.101::INSTR'  # Standard LAN connection (also called VXI-11)
resource_string_2 = 'TCPIP::192.168.2.101::hislip0'  # Hi-Speed LAN connection - see 1MA208
resource_string_3 = 'GPIB::20::INSTR'  # GPIB Connection
resource_string_4 = 'USB::0x0AAD::0x0119::022019943::INSTR'  # USB-TMC (Test and Measurement Class)
resource_string_5 = 'RSNRP::0x0095::104015::INSTR'  # R&S Powersensor NRP-Z86

# Initializing the session
instr = RsInstrument(resource_string_1)

idn = instr.query_str('*IDN?')
print(f"\nHello, I am: '{idn}'")
print(f'RsInstrument driver version: {instr.driver_version}')
print(f'Visa manufacturer: {instr.visa_manufacturer}')
print(f'Instrument full name: {instr.full_instrument_model_name}')
print(f'Instrument installed options: {",".join(instr.instrument_options)}')

# Close the session
instr.close()
```

--------------------------------

### OPC-synchronized I/O Communication Example

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates using OPC-synchronized methods like `write_str_with_opc` and `query_str_with_opc` for robust instrument communication. It shows how to set `visa_timeout` and `opc_timeout`, send commands, wait for completion, and retrieve results. The example covers resetting the instrument, initiating measurements, fetching data, and closing the session.

```python
from RsInstrument import *

instr = RsInstrument('TCPIP::192.168.56.101::INSTR', True, True)
instr.visa_timeout = 3000
# opc_timeout default value is 10000 ms
instr.opc_timeout = 20000

# Send Reset command and wait for it to finish
instr.write_str_with_opc('*RST')

# Initiate the measurement and wait for it to finish, define the timeout 50 secs
# Notice no changing of the VISA timeout
instr.write_str_with_opc('INIT', 50000)
# The results are ready, simple fetch returns the results
# Waiting here is not necessary
result1 = instr.query_str('FETCH:MEASUREMENT?')

# READ command starts the measurement, we use query_with_opc to wait for the measurement to finish
result2 = instr.query_str_with_opc('READ:MEASUREMENT?', 50000)

# Close the session
instr.close()
```

--------------------------------

### Transferring Files from PC to Instrument

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates how to send a file (e.g., a setup file or configuration) from the PC to the instrument's storage using `send_file_from_pc_to_instrument`. This allows for easy deployment of test programs or settings to the instrument.

```Python
instr.send_file_from_pc_to_instrument(
    'c:\MyCoolTestProgram\instr_setup.sav',
    r'/var/appdata/instr_setup.sav')
```

--------------------------------

### Select Specific VISA Implementation for RsInstrument

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

This example shows how to explicitly select a specific VISA implementation (e.g., R&S VISA or NI VISA) when initializing an RsInstrument session. By passing `SelectVisa='rs'` or `SelectVisa='ni'` as a constructor argument, users can control which underlying VISA library is used for communication, which is useful in environments with multiple VISA installations.

```Python
from RsInstrument import *

# Force use of the Rs Visa. For e.g.: NI Visa, use the "SelectVisa='ni'"
instr = RsInstrument('TCPIP::192.168.56.101::INSTR', True, True, "SelectVisa='rs'")

idn = instr.query_str('*IDN?')
print(f"\nHello, I am: '{idn}'")
print(f"\nI am using the VISA from: {instr.visa_manufacturer}")

# Close the session
instr.close()
```

--------------------------------

### Configure RsInstrument Logging via Constructor Options

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Shows how to initialize RsInstrument with logging enabled and a custom format string directly within the constructor's options. This method sets up logging from the start of the session.

```python
from RsInstrument import *

RsInstrument.assert_minimum_version('1.102.0')
instr = RsInstrument('TCPIP::10.102.52.53::hislip0',
            options='LoggingMode=On, 
                    LoggingToConsole=True, 
                    LoggingFormat = "PAD_LEFT12(%START_TIME%) PAD_LEFT12(%DURATION%) %SCPI_COMMAND%"')
instr.reset()

# Close the session
instr.close()
```

--------------------------------

### Query Binary Data to Bytes

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Provides an example of retrieving raw binary data directly as a byte stream using the query_bin_block method. This is useful for saving waveform data to files or processing it as raw bytes.

```Python
data = rto.query_bin_block('FORM REAL,32;:CHAN1:DATA?')
```

--------------------------------

### Find Instruments Specifying VISA Implementation

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Shows how to list instruments while explicitly selecting a VISA implementation, such as 'rs' for Rohde & Schwarz VISA. This method is useful for ensuring the correct VISA library is used, especially when multiple VISA versions are installed.

```python
"""
Find the instruments in your environment with the defined VISA implementation.
"""

from RsInstrument import *

# In the optional parameter visa_select you can use e.g.: 'rs' or 'ni'
# Rs Visa also finds any NRP-Zxx USB sensors
instr_list = RsInstrument.list_resources('?*', 'rs')
print(instr_list)
```

--------------------------------

### Check Instrument Options (Literal Search)

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates checking for specific instrument options using literal string matching. It covers checking individual options, multiple options using logical OR, and the special 'K0' option. The `instr.instrument_options` attribute provides a sorted list of all installed options.

```python
"""
Checking the installed options with literal search.
"""

from RsInstrument import *

instr = RsInstrument('TCPIP::192.168.56.101::hislip0')

# Get all the options as list, and check for the specific one.
if 'K1' in instr.instrument_options:
	print('Option K1 installed')

# Check for one option.
# Keep in mind, that if the 'K0' is present, all the K-options are reported as installed.
if instr.has_instr_option('K1'):
	print('Option K1 installed')

# Check whether the K0 is installed:
if instr.has_instr_option_k0():
	print('You are a lucky customer, your instrument has all the K-options available.')

# Check with a dedicated function for at least one option (logical OR).
if instr.has_instr_option('K1 / K1a / K1b'):
	print('At least one of the K1,K1a,K1b installed')

# Same as previous, but entered as a list of strings.
if instr.has_instr_option(['K1', 'K1a', 'K1b']):
	print('At least one of the K1,K1a,K1b installed')

instr.close()
```

--------------------------------

### Log RsInstrument to Console

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

This snippet demonstrates how to enable and start logging instrument communication directly to the console. It's useful for real-time troubleshooting and observing SCPI command execution. The output includes timestamps, device information, operation duration, and the logged message.

```python
"""
Basic logging example to the console.
"""

from RsInstrument import *

RsInstrument.assert_minimum_version('1.102.0')
instr = RsInstrument('TCPIP::192.168.1.101::INSTR')

# Switch ON logging to the console.
instr.logger.log_to_console = True
instr.logger.start()
instr.reset()

# Close the session
instr.close()
```

--------------------------------

### RsInstrument Constructor and Options

Source: https://rsinstrument.readthedocs.io/en/latest/RsInstrument

Details the initialization parameters and extensive configuration options for the RsInstrument class, enabling connection and setup for SCPI-based instrument control.

```APIDOC
RsInstrument:
  __init__(resource_name: str, id_query: bool = True, reset: bool = False, options: str = None, direct_session: object = None)
    Root class for remote-controlling instrument with SCPI commands. Initializes new RsInstrument session.
    Parameters:
      resource_name: VISA resource name, e.g. ‘TCPIP::192.168.2.1::INSTR’
      id_query: if True, the instrument’s model name is verified against the models supported by the driver and eventually throws an exception. Default: True
      reset: Resets the instrument (sends *RST) command and clears its status syb-system. Default: False
      direct_session: Another driver object or pyVisa object to reuse the session instead of opening a new session. Default: None
      options: string tokens alternating the driver settings. Examples:
        Simulate=True - starts the session in simulation mode. Default: False
        SelectVisa=socketio - uses no VISA implementation for socket connections. Default: None
        SelectVisa=rs - forces usage of RohdeSchwarz Visa. Default: None
        SelectVisa=ni - forces usage of National Instruments Visa. Default: None
        Profile = HM8123 - setting profile fitting the specific non-standard instruments. Available values: HM8123, CMQ, ATS, Minimal. Default: none
        OpenTimeout=5000 - sets timeout used at the session opening. Default: 2000ms
        ExclusiveLock=True - opens the session with exclusive lock on the VISA level. Default: False
        QueryInstrumentStatus = False - same as driver.utilities.instrument_status_checking = False. Default: True
        WriteDelay = 20, ReadDelay = 5 - introduces delay of 20ms before each write and 5ms before each read. Default: 0ms for both
        TerminationCharacter = "\r" - sets the termination character for reading. Default: \n (LineFeed or LF)
        AssureWriteWithTermChar = True - makes sure each command/query is terminated with termination character. Default: Interface dependent
        AddTermCharToWriteBinBlock = True - adds one additional LF to the end of the binary data. Default: False
        DataChunkSize = 10E3 - maximum size of one write/read segment. Default: 1E7 bytes
        OpcTimeout = 10000 - same as driver.utilities.opc_timeout = 10000. Default: 30000ms
        VisaTimeout = 5000 - same as driver.utilities.visa_timeout = 5000. Default: 10000ms
        ViClearExeMode = Disabled - viClear() execution mode. Default: execute_on_all
        OpcQueryAfterWrite = True - same as driver.utilities.opc_query_after_write = True. Default: False
        OpcWaitMode = OpcQuery - mode for all the opc-synchronised write/reads. Other modes: StbPolling, StbPollingSlow, StbPollingSuperSlow. Default: StbPolling
        StbInErrorCheck = False - if true, the driver checks errors with *STB? If false, it uses SYST:ERR?. Default: True
        SkipStatusSystemSettings = False - set to True for instruments that do not support full status system commands. Default: False
        SkipClearStatus = True - set to True for instruments that do not support *CLS command. Default: False
        DisableOpcQuery = True - set to True for instruments that do not support *OPC? query. Default: False
        EachCmdAsQuery = True - set to True, for instruments that always return answer. Default: false
        CmdIdn = ID? - defines which SCPI command to use for identification query. Use ‘<none>’ string to skip identification query at the init. Default: *IDN?
        CmdReset = RT - defines which SCPI command to use for reset. Default: *RST
        VxiCapable = false - you can force a session to a VXI-incapable. Default: <interface-dependent>
        Encoding = utf-8 - setting of encoding for strings into bytes and vice versa. Default: charmap
        OpcSyncQueryMechanism = AlsoCheckMav - setting of mechanism for OPC-synchronised queries. Default: OnlyCheckMavErrQueue
        FirstCmds = *CLS - first command(s) to sent after init. Separated more commands/queries with ‘;;’. Default: []
        EachCmdPrefix = lf - this prefix is added to the beginning of each command sent to the instrument. Default: ""

```

--------------------------------

### Initialize RsInstrument with ID Query and Reset Options

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

This example demonstrates how to initialize an RsInstrument session using optional boolean arguments in the constructor: `id_query` and `reset`. Setting `id_query` to True (default) verifies instrument compatibility, while setting `reset` to True (default is False) performs a reset operation on the instrument upon connection, equivalent to calling the `reset()` method.

```Python
instr = RsInstrument('TCPIP::192.168.56.101::hislip0', id_query=True, reset=True)
```

--------------------------------

### RsInstrument Multithreaded Access with Locks

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates how to safely access a single RsInstrument session from multiple threads concurrently. It shows the setup of threads, each executing a query command, and how RsInstrument's internal locking mechanism ensures that only one thread communicates with the instrument at a time.

```Python
import threading
from RsInstrument import *

def execute(session: RsInstrument) -> None:
    """Executed in a separate thread."""
    session.query_str('*IDN?')


RsInstrument.assert_minimum_version('1.102.0')
instr = RsInstrument('TCPIP::192.168.56.101::INSTR')
threads = []
for i in range(10):
    t = threading.Thread(target=execute, args=(instr, ))
    t.start()
    threads.append(t)
print('All threads started')

# Wait for all threads to join this main thread
for t in threads:
    t.join()
print('All threads ended')

instr.close()
```

--------------------------------

### RsInstrument Key Features Overview

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

This section outlines the primary advantages and functionalities of the RsInstrument Python module, emphasizing its robust design and ease of use for instrument control.

```APIDOC
RsInstrument Module Features:

- Type-safe API using the typing module.
- Flexible VISA selection: Choose a specific VISA or omit it entirely.
- Straightforward session initialization without complex property settings.
- Built-in features: reset, self-test, OPC synchronization, error checking, option checking.
- Bidirectional binary data block transfer.
- Array transfer in binary or ASCII format.
- Bidirectional file transfers.
- Event generation for errors, sent data, received data, and chunk data.
- Multithreading session locking for concurrent instrument access.
- Specialized logging feature tailored for SCPI communication.
```

--------------------------------

### Log RsInstrument to File

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

This example shows how to log instrument communication to a file. It configures logging to both the console and a specified file, sets a custom device name for log entries, and logs a custom informational message. The file is opened in write mode and closed after the instrument session.

```python
"""
Example of logging to a file.
"""

from RsInstrument import *

RsInstrument.assert_minimum_version('1.102.0')
instr = RsInstrument('TCPIP::192.168.1.101::INSTR')

# We also want to log to the console.
instr.logger.log_to_console = True

# Logging target is our file
file = open(r'c:\temp\my_file.txt', 'w')
instr.logger.set_logging_target(file)
instr.logger.start()

# Instead of the 'TCPIP::192.168.1.101::INSTR', show 'MyDevice'
instr.logger.device_name = 'MyDevice'

# Custom user entry
instr.logger.info_raw('----- This is my custom log entry. ---- ')

instr.reset()

# Close the session
instr.close()

# Close the log file
file.close()
```

--------------------------------

### Find Instruments Using RsInstrument

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates how to list available instruments in the environment using the RsInstrument.list_resources method. This basic usage queries for all available resources without specifying a particular VISA implementation.

```python
"""
Find the instruments in your environment.
"""

from RsInstrument import *

# Use the instr_list string items as resource names in the RsInstrument constructor
instr_list = RsInstrument.list_resources("?*")
print(instr_list)
```

--------------------------------

### Basic write_str and query_str

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates the fundamental `write_str` and `query_str` methods for sending commands without expecting a response and for sending commands that require a response, respectively. It includes instrument initialization and session closing.

```Python
"""
Basic string write_str / query_str.
"""

from RsInstrument import *

instr = RsInstrument('TCPIP::192.168.56.101::INSTR', True, True)
instr.write_str('*RST')
response = instr.query_str('*IDN?')
print(response)

# Close the session
instr.close()
```

--------------------------------

### Check Instrument Options (Regex Search)

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates checking for instrument options using regular expressions. The regex must fully match the option string. Examples show checking for options matching a pattern like 'K1.' (e.g., K10, K11) and checking for multiple patterns using logical OR.

```python
"""
Checking the installed options with regular expressions search.
"""

from RsInstrument import *

instr = RsInstrument('TCPIP::192.168.56.101::hislip0')

# Check for one option.
# Keep in mind, that if the 'K0' is present, all the K-options are reported as installed.
if instr.has_instr_option_regex('K1.'):
    print('Option K10 or K11 or K12 up to K19 installed')

# Check with a dedicated function for at least one option (logical OR).
if instr.has_instr_option_regex('K1. / K2..'):
    print('At least one of the K10..K19, K200..K299 installed')

# Same as previous, but entered as a list of strings.
if instr.has_instr_option_regex(['K1.', 'K2..']):
    print('At least one of the K10..K19, K200..K299 installed')

instr.close()
```

--------------------------------

### RsInstrument Identification Properties

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

This section documents the key identification properties available on an RsInstrument object after a successful session initialization. These properties provide details about the connected instrument and the RsInstrument driver itself, such as the instrument's IDN string, serial number, firmware version, and installed options, as well as the driver and VISA manufacturer versions.

```APIDOC
RsInstrument Properties:
  idn_string: str
    The identification string of the instrument (result of *IDN? query).
  driver_version: str
    The version of the RsInstrument driver being used.
  visa_manufacturer: str
    The manufacturer of the VISA library currently in use.
  full_instrument_model_name: str
    The full model name of the connected instrument.
  instrument_serial_number: str
    The serial number of the connected instrument.
  instrument_firmware_version: str
    The firmware version of the connected instrument.
  instrument_options: List[str]
    A list of installed options on the instrument.
```

--------------------------------

### Checking File Existence and Size on Instrument

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Provides examples of using `file_exist` to check if a file is present on the instrument and `get_file_size` to retrieve its size. These methods help prevent errors related to non-existent files or overwriting existing files during file operations.

```Python
# Do you exist?
i_exist = instr.file_exist(r'/var/appdata/instr_setup.sav')

# Give me your size or give me nothing...
your_size = instr.get_file_size(r'/var/appdata/instr_setup.sav')
```

--------------------------------

### Handle RsInstrument Exceptions

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates how to catch and handle various RsInstrument exceptions like ResourceError, StatusException, and TimeoutException during instrument initialization and command execution. It also shows how to use the `instr_err_suppressor` context manager.

```Python
"""
How to deal with RsInstrument exceptions.
"""

from RsInstrument import *

RsInstrument.assert_minimum_version('1.102.0')
instr = None
# Try-catch for initialization. If an error occurs, the ResourceError is raised
try:
    instr = RsInstrument('TCPIP::192.168.1.110::hislip0', True, True)
except ResourceError as e:
    print(e.args[0])
    print('Your instrument is probably OFF...')
    # Exit now, no point of continuing
    exit(1)
try:
    # Dealing with commands that potentially generate instrument errors:
    # Switching the status checking OFF temporarily.
    # We use the InstrumentErrorSuppression context-manager that does it for us:
    with instr.instr_err_suppressor() as supp:
        instr.write('MY:MISSpelled:COMMand')
    if supp.get_errors_occurred():
        print("Errors occurred: ")
        for err in supp.get_all_errors():
            print(err)

    # Here for this query we use the reduced VISA timeout to prevent long waiting
    with instr.instr_err_suppressor(visa_tout_ms=500) as supp:
        idn = instr.query('*IDaN')
    if supp.get_errors_occurred():
        print("Errors occurred: ")
        for err in supp.get_all_errors():
            print(err)

except StatusException as e:
    # Instrument status error
    print(e.args[0])
    print('Nothing to see here, moving on...')

except TimeoutException as e:
    # Timeout error
    print(e.args[0])
    print('That took a long time...')

except RsInstrException as e:
    # RsInstrException is a base class for all the RsInstrument exceptions
    print(e.args[0])
    print('Some other RsInstrument error...')

finally:
    instr.close()
```

--------------------------------

### Configure RsInstrument Logging Format Programmatically

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates how to enable console logging and set a custom format string for RsInstrument after the instrument object is created. It shows how to switch logging on, set the format, and then execute commands.

```python
from RsInstrument import *

RsInstrument.assert_minimum_version('1.102.0')
instr = RsInstrument('TCPIP::10.102.52.53::hislip0')

# Switch ON logging to the console.
instr.logger.log_to_console = True
instr.logger.set_format_string('PAD_LEFT12(%START_TIME%) PAD_LEFT12(%DURATION%) %SCPI_COMMAND%')
instr.logger.start()
instr.reset()

# Close the session
instr.close()
```

--------------------------------

### Synchronization with query_opc

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Explains the `query_opc()` method, which sends the '*OPC?' command to synchronize program execution with instrument operations. The instrument waits until its queue is clear before responding, ensuring tasks are completed.

```Python
instr.visa_timeout = 3000
instr.write("INIT")
instr.query_opc()

# The results are ready now to fetch
results = instr.query('FETCH:MEASUREMENT?')
```

--------------------------------

### RsInstrument Context Manager Usage

Source: https://rsinstrument.readthedocs.io/en/latest/Readme

Demonstrates how to use the RsInstrument class as a context manager for automatic resource management, ensuring proper setup and teardown.

```Python
with RsInstrument("TCPIP::192.168.1.101::hislip0") as io:
    io.reset()

```

--------------------------------

### Start Logging (Python)

Source: https://rsinstrument.readthedocs.io/en/latest/_modules/RsInstrument/Internal/ScpiLogger

Initiates logging using the last defined logging mode. If no mode was previously set, it defaults to LoggingMode.On.

```Python
def start(self) -> None:
    """Starts the logging with the last defined LoggingMode. Default is LoggingMode.On"""
    self.mode = self._last_logging_mode
```

--------------------------------

### RsInstrument Python Logging Integration

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Shows how to integrate RsInstrument logging with Python's standard logging module by creating a custom stream handler and configuring the RsInstrument logger.

```python
1"""
2Example of logging to a python standard logger object.
3"""
4
5import logging
6
7from RsInstrument import *
8
9RsInstrument.assert_minimum_version('1.102.0')
10
11
12class LoggerStream:
13    """Class to wrap the python's logging into a stream interface."""
14
15    @staticmethod
16    def write(log_entry: str) -> None:
17        """Method called by the RsInstrument to add the log_entry.
18        Use it to do your custom operation, in our case calling python's logging function."""
19        logging.info('RsInstrument: ' + log_entry.rstrip())
20
21    def flush(self) -> None:
22        """Do the operations at the end. In our case, we do nothing."""
23        pass
24
25
26# Setting of the SMW
27smw = RsInstrument('TCPIP::10.99.2.10::hislip0', options='LoggingMode=On, LoggingName=SMW')
28
29# Create a logger stream object
30target = LoggerStream()
31logging.getLogger().setLevel(logging.INFO)
32
33# Adjust the log string to not show the start time
34smw.logger.set_format_string('PAD_LEFT25(%DEVICE_NAME%) PAD_LEFT12(%DURATION%)  %LOG_STRING_INFO%: %LOG_STRING%')
35smw.logger.set_logging_target(target)  # Log to my target
36
37smw.logger.info_raw("> Custom log from SMW session")
38smw.reset()
39
40# Close the sessions
41smw.close()

```

--------------------------------

### Check Instrument Status and Raise Exception

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Checks the instrument's status for errors and raises a StatusException if any errors are found in the queue.

```python
# Check for errors and raise exception in case of one or more errors
instr.check_status()
```

--------------------------------

### RsInstrument Documentation Expansion

Source: https://rsinstrument.readthedocs.io/en/latest/Readme

Enhances the library's documentation by adding more details and including an offline installer option, improving user onboarding and accessibility.

```APIDOC
Extended documentation, added offline installer.
```

--------------------------------

### Optimized Error Checking Pattern

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates an optimized approach to instrument error checking by selectively disabling and re-enabling status checking around groups of commands.

```python
1"""
2How to optimize instrument status (error) checking.
3Example contains commands for a spectrum analyzer.
4"""
5
6from RsInstrument import *
7
8RsInstrument.assert_minimum_version('1.102.0')
9instr = None
10# Try-catch for initialization. If an error occurs, the ResourceError is raised
11try:
12	instr = RsInstrument('TCPIP::192.168.1.110::hislip0', True, True)
13except ResourceError as e:
14	print(e.args[0])
15	print('Your instrument is probably OFF...')
16	# Exit now, no point of continuing
17	exit(1)
18
19# Single commands, keep the instrument stats checking ON
20instr.write('SYSTem:DISPlay:UPDate ON')
21instr.write('INITiate:CONTinuous OFF')
22
23# Switch the error checking off for a group of commands logically belonging together
24instr.instrument_status_checking = False
25
26# Configuration
27instr.write('SENSe1:FREQuency:SPAN 10E6')
28instr.write('SENSe1:BANDwidth:RESolution 1000')
29instr.write('SENSe1:BANDwidth:VIDeo 100')
30# Check status after this group of configuration commands
31instr.check_status()
32
33# Measure spectrum peaks in a loop
34for freq in [10E6, 20E6, 100E6, 200E6, 500E6, 1E9]:
35	instr.write_float('SENS:FREQ:CENT ', freq)
36	instr.write_with_opc("INITiate:IMMediate")
37	instr.write('CALC1:MARK1:STAT ON')
38	instr.write('CALC1:MARK1:MAX:PEAK')
39	marker_x = instr.query_float('CALCulate:MARKer1:X?')
40	si_freq = value_to_si_string(freq)  # Nice way to create SI-formatted numbers
41	si_marker_x = value_to_si_string(marker_x)
42	marker_y = instr.query_float('CALCulate:MARKer1:Y?')
43	print(f'Center Frequency {si_freq}Hz, peak: [{si_marker_x}Hz, {marker_y} dBm]')
44	# Check status after one cycle of a marker measurement
45	instr.check_status()
46
47instr.close()
```

--------------------------------

### RsInstrument Logger Methods

Source: https://rsinstrument.readthedocs.io/en/latest/Readme

Introduces convenient start() and stop() methods for the RsInstrument logger, allowing for easier control over logging operations.

```Python
# Assuming 'io' is an instance of RsInstrument
io.logger.start()
# ... perform operations ...
io.logger.stop()

```

--------------------------------

### RsInstrument SocketIO Plugin

Source: https://rsinstrument.readthedocs.io/en/latest/Readme

Introduces a SocketIO plugin, enabling remote control of instruments without requiring a VISA installation. This expands connectivity options for users.

```APIDOC
Implemented SocketIO plugin for remote-control without VISA installation.
```

--------------------------------

### Basic reset and idn_string query

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Provides an alternative approach to basic communication by using the `reset()` method to send the '*RST' command and accessing the `idn_string` property to retrieve the instrument's identification.

```Python
"""
Basic string write_str / query_str.
"""

from RsInstrument import *

instr = RsInstrument('TCPIP::192.168.56.101::INSTR', True, True)
instr.reset()
print(instr.idn_string)

# Close the session
instr.close()
```

--------------------------------

### Transferring Files from Instrument to PC

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Explains how to retrieve a file (e.g., a screenshot or measurement result) from the instrument's storage and save it to a specified path on the PC using `read_file_from_instrument_to_pc`. This is useful for archiving or further processing instrument-generated files.

```Python
instr.read_file_from_instrument_to_pc(
    r'/var/user/instr_screenshot.png',
    r'c:\temp\pc_screenshot.png')
```

--------------------------------

### Automatic OPC Query after write

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Details the `opc_query_after_write` property, which, when set to `True`, automatically triggers an OPC query after every `write_xxx()` command. This ensures synchronization after each write operation.

```Python
# Default value after init is False
instr.opc_query_after_write = True
```

--------------------------------

### RsInstrument Global Logging and Time API

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Provides documentation for global logging functions and session-specific time/statistic methods within the RsInstrument library. These functions allow control over logging targets, relative timestamps, and performance metrics for instrument sessions.

```APIDOC
RsInstrument.set_global_logging_relative_timestamp(timestamp: datetime)
  Sets the reference timestamp for all global log entries.
  Parameters:
    timestamp: The datetime object to set as the reference.

RsInstrument.get_global_logging_relative_timestamp() -> datetime
  Retrieves the currently set reference timestamp for global log entries.
  Returns:
    The reference datetime object.

RsInstrument.set_global_logging_relative_timestamp_now()
  Sets the reference timestamp for all global log entries to the current time.

RsInstrument.clear_global_logging_relative_timestamp()
  Clears the reference timestamp for global log entries.

---

session.logger.set_relative_timestamp(timestamp: datetime)
  Sets the reference timestamp for session-specific log entries.
  Parameters:
    timestamp: The datetime object to set as the reference.

session.logger.set_relative_timestamp_now()
  Sets the reference timestamp for session-specific log entries to the current time.

session.logger.get_relative_timestamp() -> datetime
  Retrieves the currently set reference timestamp for session-specific log entries.
  Returns:
    The reference datetime object.

session.logger.clear_relative_timestamp()
  Clears the reference timestamp for session-specific log entries.

---

session.get_total_execution_time() -> timedelta
  Returns the total time spent executing commands on the instrument session.
  Returns:
    A timedelta object representing the total execution time.

session.get_total_time() -> timedelta
  Returns the total time elapsed since the session was initialized or the last reset.
  Returns:
    A timedelta object representing the total session time.

session.get_total_time_startpoint() -> datetime
  Returns the datetime object marking the start point for total time calculations.
  Returns:
    The start point datetime object.

session.reset_time_statistics()
  Resets all time statistics for the current instrument session.
```

--------------------------------

### Enable UDP Logging in RsInstrument (Python)

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Enables logging to a UDP port in addition to other configured log targets. Users can choose to log exclusively to UDP or concurrently to UDP and the console by setting the appropriate logger attributes.

```Python
smw.logger.log_to_udp = True
```

```Python
smw.logger.log_to_console_and_udp = True
```

--------------------------------

### Query ASCII and Binary Integer Arrays

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Illustrates querying integer arrays in both ASCII and binary formats using the query_bin_or_ascii_int_list method. It also explains how to configure the bin_int_numbers_format attribute for binary integer data, including endianness considerations.

```Python
"""
Querying ASCII and binary integer arrays.
"""

from RsInstrument import *
from time import time

rto = RsInstrument('TCPIP::192.168.56.101::INSTR', True, True)
# Initiate a single acquisition and wait for it to finish
rto.write_str_with_opc("SINGle", 20000)

# Query array of integers in ASCII format
t = time()
waveform = rto.query_bin_or_ascii_int_list('FORM ASC;:CHAN1:DATA?')
print(f'Instrument returned {len(waveform)} points in ASCII format, query duration {time() - t:.3f} secs')


# Query array of integers in Binary format
t = time()
# This tells the RsInstrument in which format to expect the binary integer data
rto.bin_int_numbers_format = BinIntFormat.Integer32_4bytes
# If your instrument sends the data with the swapped endianness, use the following format:
# rto.bin_int_numbers_format = BinIntFormat.Integer32_4bytes_swapped
waveform = rto.query_bin_or_ascii_int_list('FORM INT,32;:CHAN1:DATA?')
print(f'Instrument returned {len(waveform)} points in binary format, query duration {time() - t:.3f} secs')

# Close the rto session
rto.close()
```

--------------------------------

### Get Instrument Options

Source: https://rsinstrument.readthedocs.io/en/latest/_modules/RsInstrument/RsInstrument

Retrieves all instrument options, sorted in ascending order starting with K-options and continuing with B-options.

```python
@property
def instrument_options(self) -> List[str]:
    """Returns all the instrument options.
    The options are sorted in the ascending order starting with K-options and continuing with B-options"""
    return self._core.io.instr_options.get_all()
```

--------------------------------

### Type-safe write/query methods

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates the use of type-specific methods such as `write_int`, `query_int`, `write_bool`, `query_bool`, `write_float`, and `query_float` for sending and receiving data in integer, boolean, and float formats, respectively. This enhances type safety and convenience.

```Python
"""
Basic string write_xxx / query_xxx.
"""

from RsInstrument import *

instr = RsInstrument('TCPIP::192.168.56.101::INSTR', True, True)
instr.visa_timeout = 5000
instr.instrument_status_checking = True
instr.write_int('SWEEP:COUNT ', 10)  # sending 'SWEEP:COUNT 10'
instr.write_bool('SOURCE:RF:OUTPUT:STATE ', True)  # sending 'SOURCE:RF:OUTPUT:STATE ON'
instr.write_float('SOURCE:RF:FREQUENCY ', 1E9)  # sending 'SOURCE:RF:FREQUENCY 1000000000'

sc = instr.query_int('SWEEP:COUNT?')  # returning integer number sc=10
out = instr.query_bool('SOURCE:RF:OUTPUT:STATE?')  # returning boolean out=True
freq = instr.query_float('SOURCE:RF:FREQUENCY?')  # returning float number freq=1E9

# Close the session
instr.close()
```

--------------------------------

### Basic RsInstrument Hello-World Example (Python)

Source: https://rsinstrument.readthedocs.io/en/latest/Readme

This snippet demonstrates a basic 'Hello-World' interaction with an R&S instrument using the RsInstrument library. It initializes a connection, queries the instrument's identification string, and prints it. Requires the RsInstrument library and a connected R&S instrument.

```python
from RsInstrument import *

instr = RsInstrument('TCPIP::192.168.56.101::hislip0', id_query=True, reset=True)
idn = instr.query_str('*IDN?')
print('Hello, I am: ' + idn)
```

--------------------------------

### Modify Reported Instrument Options

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Demonstrates how to add or remove options from the list of reported instrument options using `add_instr_option()` and `remove_instr_option()`. This manipulation affects the results of checks like `has_instr_option_k0()` but does not alter the actual options installed on the instrument.

```python
"""
Changing how the installed options are reported.
This code does not actually install any option on the instrument :-)
"""

from RsInstrument import *

instr = RsInstrument('TCPIP::192.168.56.101::hislip0')

# I want to remove the 'K0' and see if the individual K-options are reported as present.
instr.remove_instr_option('K0')
if not instr.has_instr_option_k0():
    print('We have lost the K0, let us hope the individual options are still reported.')

instr.add_instr_option('K0')
if not instr.has_instr_option_k0():
    print('Now we have the K0 again :-)')
```

--------------------------------

### Python RsInstrument Manual Lock Assignment Example

Source: https://rsinstrument.readthedocs.io/en/latest/StepByStepGuide

Illustrates synchronizing multiple independent RsInstrument sessions to the same instrument by manually assigning locks. This is crucial when instruments handle sessions with shared buffers, preventing data corruption or command interleaving.

```Python
"""
Multiple threads are accessing two RsInstrument objects with two separate sessions.
"""

import threading
from RsInstrument import *


def execute(session: RsInstrument, session_ix, index) -> None:
    """Executed in a separate thread."""
    print(f'{index} session {session_ix} query start...')
    session.query_str('*IDN?')
    print(f'{index} session {session_ix} query end')


RsInstrument.assert_minimum_version('1.102.0')
instr1 = RsInstrument('TCPIP::192.168.56.101::INSTR')
instr2 = RsInstrument('TCPIP::192.168.56.101::INSTR')
instr1.visa_timeout = 200
instr2.visa_timeout = 200

# Synchronise the sessions by sharing the same lock
instr2.assign_lock(instr1.get_lock())  # To see the effect of crosstalk, comment this line

threads = []
for i in range(10):
    t = threading.Thread(target=execute, args=(instr1, 1, i,))
    t.start()
    threads.append(t)
    t = threading.Thread(target=execute, args=(instr2, 2, i,))
    t.start()
    threads.append(t)
print('All threads started')

# Wait for all threads to join this main thread
for t in threads:
    t.join()
print('All threads ended')

instr2.close()
instr1.close()
```
Tokens:
Raw