TekHSI

https://tekhsi.readthedocs.io/
Admin
TekHSI is a Python library that provides a low latency, high-speed data link between Tektronix...
Tokens:14,908
Snippets:153
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies with Poetry and pre-commit

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Install the project dependencies using Poetry and set up pre-commit hooks. This is part of the manual setup process.

```bash
python -m pip install -U pip poetry
poetry install
pre-commit install

```

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

### Run contributor setup script

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Run the provided helper script to set up a virtual environment and install the project with its dependencies. This is the recommended setup method.

```python
python scripts/contributor_setup.py

```

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

### AcqWaitOn.NextAcq usage example

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Shows how to use AcqWaitOn.NextAcq with TekHSIConnect to access data.

```python
>>> from tekhsi import AcqWaitOn, TekHSIConnect
>>> with TekHSIConnect("192.168.0.1:5000") as connection:
...     with connection.access_data(AcqWaitOn.NextAcq):
...         ...
```

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

### Install TekHSI via pip

Source: https://tekhsi.readthedocs.io

Use this command to install the TekHSI library. Note that a 64-bit Python installation is required due to external dependencies.

```bash
pip install tekhsi
```

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

### AcqWaitOn.NewData usage example

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Shows how to use AcqWaitOn.NewData with TekHSIConnect to access data.

```python
>>> from tekhsi import AcqWaitOn, TekHSIConnect
>>> with TekHSIConnect("192.168.0.1:5000") as connection:
...     with connection.access_data(AcqWaitOn.NewData):
...         ...
```

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

### AcqWaitOn.Time usage example

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Shows how to use AcqWaitOn.Time with TekHSIConnect to access data after a delay.

```python
>>> from tekhsi import AcqWaitOn, TekHSIConnect
>>> with TekHSIConnect("192.168.0.1:5000") as connection:
...     with connection.access_data(AcqWaitOn.Time, after=0.5):
...         ...
```

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

### get_data

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Gets the saved data of the previous acquisition with the data item of the requested name. The provided `name` parameter must correspond to the names returned from the `available_symbols` property, however, the names are case-insensitive.

```APIDOC
## get_data

### Description
Gets the saved data of the previous acquisition with the data item of the requested name. The provided `name` parameter must correspond to the names returned from the `available_symbols` property, however, the names are case-insensitive.

### Method
method

### Signature
```
get_data(name: str) -> AnyWaveform | None
```

### Parameters
- **name** (str) - Required - Name of the data item.

### Returns
- **AnyWaveform | None** - The waveform data or None if caching is off or data is not found.
```

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

### force_sequence method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Asks the instrument to provide access to the current acquisition data. Useful when connecting to a stopped instrument to get access to currently available data; otherwise the API waits until the next acquisition.

```python
force_sequence() -> None

```

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

### Mix PyVISA with TekHSI to retrieve waveform data

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Use when controlling the instrument with PyVISA while retrieving waveform data via TekHSI. It opens a VISA session, configures the scope (display off, manual horizontal mode, record length 2500), then connects to TekHSI on port 5000 to capture 10 acquisitions from channel 1. The example prints the source name and record length for each acquisition, then turns the waveform display back on and closes the VISA connection.

```python
"""Command & control using PyVISA, but retrieving waveform data using TekHSI."""

import pyvisa

from tm_data_types import AnalogWaveform

from tekhsi import AcqWaitOn, TekHSIConnect

addr = "192.168.0.1"  # Replace with the IP address of your instrument

rm = pyvisa.ResourceManager("@py")

# write command to instrument sample using pyvisa
visa_scope = rm.open_resource(f"TCPIP0::{addr}::INSTR")

sample_query = visa_scope.query("*IDN?")
print(sample_query)
# Make the waveform display OFF
visa_scope.write("DISplay:WAVEform OFF")
# Set the Horizontal mode to Manual
visa_scope.write("HOR:MODE MAN")
# Set the horizontal Record Length
visa_scope.write("HOR:MODE:RECO 2500")

# time.sleep(2) # Optional delay
# Connect to instrument via TekHSI, select channel 1
with TekHSIConnect(f"{addr}:5000", ["ch1"]) as connect:
    # Save data from 10 acquisitions
    for i in range(10):
        with connect.access_data(AcqWaitOn.NewData):
            waveform: AnalogWaveform = connect.get_data("ch1")
            print(f"{waveform.source_name}_{i}:{waveform.record_length}")

visa_scope.write("DISplay:WAVEform ON")

# close visa connection
visa_scope.close()

```

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

### get_data method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Gets saved data of the previous acquisition by name. The name must correspond to names from the available_symbols property, but is case-insensitive. Returns the waveform data or None if caching is off or data is not found.

```python
get_data(name: str) -> AnyWaveform | None

```

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

### Mix tm_devices with TekHSI to retrieve waveform data

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Use when controlling the instrument with tm_devices while retrieving waveform data via TekHSI. It uses DeviceManager to add an MSO6B scope, queries the IDN, turns off the waveform display, sets horizontal mode to manual with record length 2500, then connects to TekHSI on port 5000 to capture 10 acquisitions from channel 1. The example prints the source name and record length for each acquisition, then turns the waveform display back on.

```python
"""Command & control using tm_devices, but retrieving waveform data using TekHSI."""

from tm_data_types import AnalogWaveform
from tm_devices import DeviceManager
from tm_devices.drivers import MSO6B

from tekhsi import AcqWaitOn, TekHSIConnect

addr = "192.168.0.1"  # Replace with the IP address of your instrument

with DeviceManager(verbose=True) as device_manager:
    scope: MSO6B = device_manager.add_scope(f"{addr}")
    idn_response = scope.commands.idn.query()
    print(idn_response)
    # Make the waveform display OFF
    scope.commands.display.waveform.write("OFF")
    # Set the Horizontal mode to Manual
    scope.commands.horizontal.mode.write("OFF")
    # Set the horizontal Record Length
    scope.commands.horizontal.mode.recordlength.write("2500")

    # time.sleep(2) # Optional delay
    # Connect to instrument via TekHSI, select channel 1
    with TekHSIConnect(f"{scope.ip_address}:5000", ["ch1"]) as connect:
        # Save data from 10 acquisitions
        for i in range(10):
            with connect.access_data(AcqWaitOn.NewData):
                waveform: AnalogWaveform = connect.get_data("ch1")
                print(f"{waveform.source_name}_{i}:{waveform.record_length}")

    # Make the waveform display ON
    scope.commands.display.waveform.write("ON")

```

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

### force_sequence

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

force_sequence asks the instrument to please give us access to the current acquisition data. This is useful when connecting to a stopped instrument to get access to the currently available data. Otherwise, the API will wait until the next acquisition.

```APIDOC
## force_sequence

### Description
force_sequence asks the instrument to please give us access to the current acquisition data. This is useful when connecting to a stopped instrument to get access to the currently available data. Otherwise, the API will wait until the next acquisition.

### Method
method

### Signature
```
force_sequence() -> None
```
```

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

### Build and serve documentation with tox and http.server

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Build the documentation and serve it using Python's HTTP server. This is an alternative to `mkdocs serve` for viewing the documentation locally.

```bash
tox -e docs
python -m http.server -d .results_docs

```

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

### Serve documentation with mkdocs

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Serve the documentation locally with live reload disabled. This is one method to view the built documentation.

```bash
mkdocs serve --clean --no-livereload

```

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

### Build documentation with tox

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Build the documentation. This is required before serving the documentation locally.

```bash
tox -e docs

```

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

### Create virtual environment manually

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Create a virtual environment named `.env` manually. This is an alternative to using the helper script.

```python
python -m venv .env

```

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

### Activate virtual environment (Linux/Windows)

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Activate the virtual environment on Linux or Windows. This is required before running tests or other code.

```bash
# Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate.bat

```

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

### Run basic tox checks

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Run only the tests and static code analysis. This is much quicker than the full `tox -p` command.

```bash
tox -p -m basic

```

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

### Run tests with tox

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Run only the tests. This is a quicker alternative to the full tox run.

```bash
tox -e tests

```

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

### Customize logging with configure_logging() and save waveforms to CSV

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Configures logging levels and file output via `configure_logging()` with `LoggingLevels.NONE` for console and `LoggingLevels.DEBUG` for the log file, saving to a custom directory and filename. Connects to an instrument at the given address and writes 10 CSV files from channel 1. If logging is not configured, defaults from `configure_logging()` apply.

```python
"""A script demonstrating how to customize the logging that happens during runtime."""

from tm_data_types import AnalogWaveform, write_file

from tekhsi import configure_logging, LoggingLevels, TekHSIConnect

addr = "192.168.0.1"  # Replace with the IP address of your instrument

configure_logging(
    log_console_level=LoggingLevels.NONE,  # completely disable console logging
    log_file_level=LoggingLevels.DEBUG,  # log everything to the file
    log_file_directory="./log_files",  # save the log file in the "./log_files" directory
    log_file_name="custom_log_filename.log",  # customize the filename
)

# Connect to instrument, select channel 1
with TekHSIConnect(f"{addr}:5000", ["ch1"]) as connect:
    # Save data from 10 acquisitions as a set of CSV files
    for i in range(10):
        with connect.access_data():
            wfm: AnalogWaveform = connect.get_data("ch1")

        # Save the waveform to a file
        write_file(f"{wfm.source_name}_{i}.csv", wfm)

```

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

### Verify file attestations with GitHub CLI

Source: https://tekhsi.readthedocs.io

Use the GitHub CLI to verify the signatures of files uploaded to PyPI or GitHub releases.

```bash
gh attestation verify --owner tektronix <file>
```

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

### Run full tox checks

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Run full static code analysis, tests, and documentation validation. This is slow but recommended before opening a pull request.

```bash
tox -p

```

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

### any_acq static method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Prebuilt acq acceptance filter that accepts all new acquisitions. Takes previous and current header dictionaries and returns True if the acquisition is accepted.

```python
any_acq(
    previous_header: dict[str, WaveformHeader], current_header: dict[str, WaveformHeader]
) -> bool

```

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

### data_arrival static method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Available to be overridden if the user wants to create a derived class. Called on every accepted acquisition with a list of waveforms.

```python
data_arrival(waveforms: list[AnyWaveform]) -> None

```

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

### Create a git branch

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Create a new branch for your changes. Replace `name-of-your-bugfix-or-feature` with a descriptive branch name.

```bash
git checkout -b name-of-your-bugfix-or-feature

```

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

### Run pre-commit checks

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Run all pre-commit checks on all files. This is part of the code quality checks.

```bash
pre-commit run --all

```

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

### data_arrival

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Available to be overridden if user wants to create a derived class. This method will be called on every accepted acq.

```APIDOC
## data_arrival

### Description
Available to be overridden if user wants to create a derived class. This method will be called on every accepted acq.

### Method
static method

### Signature
```
data_arrival(waveforms: list[AnyWaveform]) -> None
```

### Parameters
- **waveforms** (list[AnyWaveform]) - Required - list of waveforms.
```

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

### Verify TekHSI artifact attestation with gh attestation verify

Source: https://tekhsi.readthedocs.io/stable

Verify the signature of a file uploaded to PyPI or a GitHub Release using the GitHub CLI. Replace <file> with the path to the downloaded file.

```bash
gh attestation verify --owner tektronix <file>

```

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

### Enable parallel reads on Linux/macOS with TEKHSI_USE_PARALLEL_READS

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Enables experimental parallel waveform reads on Linux or macOS by setting the `TEKHSI_USE_PARALLEL_READS` and `TEKHSI_PARALLEL_THRESHOLD` environment variables. The feature is disabled by default and experimental.

```bash
export TEKHSI_USE_PARALLEL_READS=1
export TEKHSI_PARALLEL_THRESHOLD=3

```

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

### configure_logging

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/helpers/logging

Configures the logging for the TekHSI package. This function sets up console and file logging with configurable levels, file location, and colored output. It returns the base logger for the package.

```APIDOC
## configure_logging

### Description
Configures the logging for the TekHSI package. This function sets up console and file logging with configurable levels, file location, and colored output. It returns the base logger for the package.

### Method
Function call

### Signature
configure_logging(*, log_console_level: Union[str, LoggingLevels] = INFO, log_file_level: Union[str, LoggingLevels] = DEBUG, log_file_directory: Union[str, PathLike[str], Path] | None = None, log_file_name: str | None = None, log_colored_output: bool = False) -> Logger

### Parameters
#### Keyword-Only Parameters
- **log_console_level** (Union[str, LoggingLevels]) - Optional, default: INFO - The logging level to set for the console. Set to LoggingLevels.NONE to disable all console logging/printouts except for certain warnings and exceptions.
- **log_file_level** (Union[str, LoggingLevels]) - Optional, default: DEBUG - The logging level to set for the file. Set to LoggingLevels.NONE to disable logging to a file entirely.
- **log_file_directory** (Union[str, PathLike[str], Path] | None) - Optional, default: None - The directory to save log files to. Defaults to "./logs" in the current working directory.
- **log_file_name** (str | None) - Optional, default: None - The name of the log file to save the logs to. Defaults to a timestamped name with the .log extension.
- **log_colored_output** (bool) - Optional, default: False - Whether to use colored output from the colorlog package for the console.

### Returns
- **Logger** - The base logger for the package. This base logger can also be accessed using logging.getLogger(tekhsi.PACKAGE_NAME).

### Notes
After this function is called once, if it is called again, it will not perform any additional configuration. It will simply return the base logger for the package.
```

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

### any_acq

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Prebuilt acq acceptance filter that accepts all new acqs.

```APIDOC
## any_acq

### Description
Prebuilt acq acceptance filter that accepts all new acqs.

### Method
static method

### Signature
```
any_acq(
    previous_header: dict[str, WaveformHeader], current_header: dict[str, WaveformHeader]
) -> bool
```

### Parameters
- **previous_header** (dict[str, WaveformHeader]) - Required - Previous header dictionary.
- **current_header** (dict[str, WaveformHeader]) - Required - Current header dictionary.

### Returns
- **bool** - True if the acquisition is accepted, False otherwise.
```

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

### Enable parallel reads on Windows with TEKHSI_USE_PARALLEL_READS

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Enables experimental parallel waveform reads on Windows (PowerShell) by setting the `TEKHSI_USE_PARALLEL_READS` and `TEKHSI_PARALLEL_THRESHOLD` environment variables. The feature is disabled by default and experimental.

```powershell
setx TEKHSI_USE_PARALLEL_READS 1
setx TEKHSI_PARALLEL_THRESHOLD 3

```

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

### any_vertical_change static method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Prebuilt acq acceptance filter that accepts only acquisitions with changes to vertical settings. Takes previous and current header dictionaries and returns True if the acquisition is accepted.

```python
any_vertical_change(
    previous_header: dict[str, WaveformHeader], current_header: dict[str, WaveformHeader]
) -> bool

```

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

### Connect to a scope and save waveform data with TekHSI

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Connects to a Tektronix oscilloscope via TekHSI, retrieves analog waveforms from channel 1, and saves them as CSV files. Uses AcqWaitOn.NextAcq to wait for new acquisitions and writes each waveform with write_file. Replace the IP address with your instrument's address.

```python
"""A script for connecting to a scope, retrieving waveform data, and saving it to a file."""

from tm_data_types import AnalogWaveform, write_file

from tekhsi import AcqWaitOn, TekHSIConnect

addr = "192.168.0.1"  # Replace with the IP address of your instrument

# Connect to instrument, select channel 1
with TekHSIConnect(f"{addr}:5000", ["ch1"]) as connect:
    # Save data from 10 acquisitions as a set of CSV files
    for i in range(10):
        # Use AcqWaitOn.NextAcq to wait for the next new acquisition
        with connect.access_data(AcqWaitOn.NextAcq):
            wfm: AnalogWaveform = connect.get_data("ch1")

        # Save the waveform to a file
        write_file(f"{wfm.source_name}_{i}.csv", wfm)
```

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

### wait_for_data method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Waits until the specified acquisition criterion is met. The 'on' parameter defaults to NewData, and 'after' is an additional criterion when 'on' is set to AcqWaitOn.Time.

```python
wait_for_data(on: AcqWaitOn = NewData, after: float = -1) -> None

```

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

### Plot an IQ waveform spectrogram with TekHSI

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Retrieves IQ data from channel 'ch1_iq' using TekHSI and displays a spectrogram with matplotlib. Uses waveform.meta_info for FFT length, center frequency, and sample rate. Minimal code required for live IQ data visualization.

```python
"""Use TekHSI to plot an IQ waveform."""

import matplotlib.pyplot as plt

from tm_data_types import IQWaveform

from tekhsi import TekHSIConnect

with TekHSIConnect("192.168.0.1:5000") as connection:
    # Get one data set to setup plot
    with connection.access_data():
        waveform: IQWaveform = connection.get_data("ch1_iq")

    # IQ Data Access (Complex Array)
    iq_data = waveform.normalized_vertical_values

    # Simple Plot Example
    _, ax = plt.subplots()
    ax.specgram(
        iq_data,
        NFFT=int(waveform.meta_info.iq_fft_length),
        Fc=waveform.meta_info.iq_center_frequency,
        Fs=waveform.meta_info.iq_sample_rate,
    )
    ax.set_title("Spectrogram")
    plt.show()

```

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

### done_with_data method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Releases the acquisition after accessing the required data.

```python
done_with_data() -> None

```

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

### any_horizontal_change static method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Acq acceptance filter that accepts only acquisitions with changes to horizontal settings. Takes previous and current header dictionaries and returns True if the acquisition is accepted.

```python
any_horizontal_change(
    previous_header: dict[str, WaveformHeader], current_header: dict[str, WaveformHeader]
) -> bool

```

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

### AcqWaitOn.Time class attribute

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Defines the Time value (2) for waiting a specific time before accepting the next acquisition.

```python
Time = 2
```

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

### set_acq_filter method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Sets rules for acquisitions that are accepted and forwarded. Allows only important data changes to be passed to the callback or saved to backing store.

```python
set_acq_filter(acq_filter: Callable) -> None

```

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

### close

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Close and clean up gRPC connection.

```APIDOC
## close

### Description
Close and clean up gRPC connection.

### Method
method

### Signature
```
close() -> None
```
```

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

### Plot a digital waveform with TekHSI

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Retrieves digital data from channel 'ch4_DAll' using TekHSI and plots a specific bitstream. Uses AcqWaitOn.NewData to wait for new data. The get_nth_bitstream(3) method extracts bit 3 as a float32 array.

```python
"""Use TekHSI to plot a digital waveform."""

import matplotlib.pyplot as plt
import numpy as np

from tm_data_types import DigitalWaveform

from tekhsi import AcqWaitOn, TekHSIConnect

with TekHSIConnect("192.168.0.1:5000") as connection:
    # Get one data set to set up plot
    with connection.access_data(AcqWaitOn.NewData):
        waveform: DigitalWaveform = connection.get_data("ch4_DAll")

    # Digital retrieval of bit 3 in the digital array
    vd = waveform.get_nth_bitstream(3).astype(np.float32)

    # Horizontal Times - returns an array of times
    # that corresponds to the time at each index in
    # vertical array
    hd = waveform.normalized_horizontal_values

    # Simple Plot Example
    _, ax = plt.subplots()
    ax.plot(hd, vd)
    ax.set(xlabel=waveform.x_axis_units, ylabel=waveform.y_axis_units, title="Simple Plot")
    plt.show()

```

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

### close method signature

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Closes and cleans up the gRPC connection.

```python
close() -> None

```

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

### done_with_data

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Releases the acquisition after accessing the required data.

```APIDOC
## done_with_data

### Description
Releases the acquisition after accessing the required data.

### Method
method

### Signature
```
done_with_data() -> None
```
```

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

### any_vertical_change

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Prebuilt acq acceptance filter that accepts only acqs with changes to vertical settings.

```APIDOC
## any_vertical_change

### Description
Prebuilt acq acceptance filter that accepts only acqs with changes to vertical settings.

### Method
static method

### Signature
```
any_vertical_change(
    previous_header: dict[str, WaveformHeader], current_header: dict[str, WaveformHeader]
) -> bool
```

### Parameters
- **previous_header** (dict[str, WaveformHeader]) - Required - Previous header dictionary.
- **current_header** (dict[str, WaveformHeader]) - Required - Current header dictionary.

### Returns
- **bool** - True if the acquisition is accepted, False otherwise.
```

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

### tekhsi package

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi

The tekhsi package provides access to commonly imported items from the TekHSI package, including classes for connection, logging, and data acquisition.

```APIDOC
## tekhsi

### Description
The Tektronix High Speed Interface (TekHSI) package provides access to commonly imported items from the TekHSI package.

### Subpackages
- **helpers** - Helpers used by the TekHSI package.

### Attributes
- **PACKAGE_NAME** - Constant string with the name of this package.

### Classes
- **AcqWaitOn** - This enumeration is used to select how to wait to access data.
- **LoggingLevels** - A class holding the valid logging levels supported.
- **TekHSIConnect** - Support for Tektronix High-Speed Interface data API.

### Functions
- **configure_logging** - Configure the logging for this package.

### Modules
- **tek_hsi_connect** - Module for connecting to Tektronix instruments and retrieving waveform data using gRPC.
```

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

### set_acq_filter

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Sets rules for acquisitions that are accepted and forwarded. This is to allow only import data changes to be passed to the callback or saved to backing store.

```APIDOC
## set_acq_filter

### Description
Sets rules for acquisitions that are accepted and forwarded. This is to allow only import data changes to be passed to the callback or saved to backing store.

### Method
method

### Signature
```
set_acq_filter(acq_filter: Callable) -> None
```

### Parameters
- **acq_filter** (function) - Required - A function that takes two headers and returns True if the data
```

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

### Commit message format

Source: https://tekhsi.readthedocs.io/stable/CONTRIBUTING

Commit messages must follow this structure. The `<type>` can be `fix`, `feat`, `build`, `ci`, `docs`, `style`, `refactor`, or `test`. See the Conventional Commits website for more details.

```text
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

```

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

### wait_for_data

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Waits until specified acquisition criterion is met.

```APIDOC
## wait_for_data

### Description
Waits until specified acquisition criterion is met.

### Method
method

### Signature
```
wait_for_data(on: AcqWaitOn = NewData, after: float = -1) -> None
```

### Parameters
- **on** (AcqWaitOn, default: NewData) - Required - Criterion for acceptance of data.
- **after** (float, default: -1) - Optional - Additional criterion when the `on` input parameter is set to `AcqWaitOn.Time`.
```

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

### AcqWaitOn.NextAcq class attribute

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Defines the NextAcq value (1) for waiting for the next acquisition.

```python
NextAcq = 1
```

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

### Plot an analog waveform with TekHSI

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Retrieves analog data from channel 'ch1' using TekHSI and plots it with matplotlib. The waveform is typed as AnalogWaveform to enable IDE type hinting. Uses normalized_vertical_values and normalized_horizontal_values for plotting.

```python
"""Use TekHSI to plot an analog waveform."""

import matplotlib.pyplot as plt

from tm_data_types import AnalogWaveform

from tekhsi import TekHSIConnect

with TekHSIConnect("192.168.0.1:5000") as connection:
    # Get one data set to setup plot
    with connection.access_data():
        waveform: AnalogWaveform = connection.get_data("ch1")

    # Data converted into vertical units
    # This is the usual way to access the data
    vd = waveform.normalized_vertical_values

    # Horizontal Times - returns an array of times
    # that corresponds to the time at each index in
    # vertical array
    hd = waveform.normalized_horizontal_values

    # Simple Plot Example
    _, ax = plt.subplots()
    ax.plot(hd, vd)
    ax.set(xlabel=waveform.x_axis_units, ylabel=waveform.y_axis_units, title="Simple Plot")
    plt.show()

```

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

### AcqWaitOn.NewData class attribute

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Defines the NewData value (4) for waiting for new data. Using this criterion will continue when current data has not been read by get_data().

```python
NewData = 4
```

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

### any_horizontal_change acquisition filter

Source: https://tekhsi.readthedocs.io/stable/basic_usage

Use this filter to accept acquisitions only when horizontal settings (number of samples, horizontal spacing, or horizontal zero index) change between the previous and current header. It returns True when a change is detected, otherwise False. The function is designed to be used as an acquisition filter in TekHSIConnect, either during instantiation or via set_acq_filter().

```python
    def any_horizontal_change(
        previous_header: dict[str, WaveformHeader],
        current_header: dict[str, WaveformHeader],
    ) -> bool:
        """Acq acceptance filter that accepts only acqs with changes to horizontal settings.

        Args:
            previous_header: Previous header dictionary.
            current_header: Current header dictionary.

        Returns:
            True if the acquisition is accepted, False otherwise.
        """
        for key, cur in current_header.items():
            if key not in previous_header:
                return True
            prev = previous_header[key]
            if prev is None and cur is not None:
                return True
            if prev is not None and (
                prev.noofsamples != cur.noofsamples
                or prev.horizontalspacing != cur.horizontalspacing
                or prev.horizontalzeroindex != cur.horizontalzeroindex
            ):
                return True
        return False
```

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

### AcqWaitOn.AnyAcq class attribute

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Defines the AnyAcq value (3) for waiting for any acquisition.

```python
AnyAcq = 3
```

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

### LoggingLevels Enum

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/helpers/logging

An enumeration of valid logging levels supported by the TekHSI logging helpers. Each member represents a specific logging level.

```APIDOC
## LoggingLevels Enum

### Description
An enumeration of valid logging levels supported by the TekHSI logging helpers. Each member represents a specific logging level.

### Members
- **CRITICAL** - An enum member representing the CRITICAL logging level.
- **DEBUG** - An enum member representing the DEBUG logging level.
- **ERROR** - An enum member representing the ERROR logging level.
- **INFO** - An enum member representing the INFO logging level.
- **NONE** - An enum member indicating no logging messages should be captured.
- **WARNING** - An enum member representing the WARNING logging level.
```

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

### any_horizontal_change

Source: https://tekhsi.readthedocs.io/stable/reference/tekhsi/tek_hsi_connect

Acq acceptance filter that accepts only acqs with changes to horizontal settings.

```APIDOC
## any_horizontal_change

### Description
Acq acceptance filter that accepts only acqs with changes to horizontal settings.

### Method
static method

### Signature
```
any_horizontal_change(
    previous_header: dict[str, WaveformHeader], current_header: dict[str, WaveformHeader]
) -> bool
```

### Parameters
- **previous_header** (dict[str, WaveformHeader]) - Required - Previous header dictionary.
- **current_header** (dict[str, WaveformHeader]) - Required - Current header dictionary.

### Returns
- **bool** - True if the acquisition is accepted, False otherwise.
```
Tokens:
Raw