Metadata-Version: 2.4
Name: nirfmxpulse
Version: 26.5.0
Summary: Python APIs for interacting with RFmx Pulse Product
License: MIT
License-File: LICENSE
Keywords: rfmx,pulse,pulse measurement,python,python api,documentation,national instruments,ni,rf measurement,nirfmxpulse
Author: NI
Author-email: opensource@ni.com
Maintainer: Thangam V
Maintainer-email: thangam.v@emerson.com
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering :: Instrument Drivers
Provides-Extra: dev
Provides-Extra: grpc
Requires-Dist: fasteners (>=0.19)
Requires-Dist: grpcio (>=1.49.0,<1.81.0) ; extra == "grpc"
Requires-Dist: hightime (>=0.2.2)
Requires-Dist: ni.grpcdevice.v1.proto (>=1.0.0) ; extra == "grpc"
Requires-Dist: nirfmxinstr (==26.5.0)
Requires-Dist: numpy (>=1.22) ; python_version >= "3.9" and python_version < "3.12" and implementation_name != "pypy"
Requires-Dist: numpy (>=1.26) ; implementation_name != "pypy" and python_version == "3.12"
Requires-Dist: numpy (>=2.1) ; implementation_name == "pypy" and python_version == "3.10"
Requires-Dist: numpy (>=2.1) ; python_version >= "3.13" and python_version < "4.0" and implementation_name != "pypy"
Requires-Dist: numpy (>=2.3) ; python_version >= "3.11" and python_version < "4.0" and implementation_name == "pypy"
Requires-Dist: protobuf (>=4.21) ; extra == "grpc"
Project-URL: Documentation, https://nirfmx-python-nirfmxpulse.readthedocs-hosted.com/
Project-URL: Repository, https://github.com/ni/nirfmx-python
Description-Content-Type: text/markdown

| **Info**      | Contains Python APIs for interacting with NI RFmx Pulse Product. |
| :------------ | :-------------------------------------------------------------- |
| **Author**    | National Instruments                                            |

# Table of Contents

- [Table of Contents](#table-of-contents)
- [About](#about)
  - [Documentation](#documentation)
  - [Operating System Support](#operating-system-support)
- [Installation](#installation)
- [Upgrade](#upgrade)
- [License](#license)
- [Support and Feedback](#support-and-feedback)
- [Example](#example)


# About

The **nirfmx-python** repository generates Python bindings (Application Programming Interface)
for interacting with the NI RFmx Products.

**nirfmx-python** follows [Python Software Foundation](https://devguide.python.org/#status-of-python-branches)
support policy for different versions.


## RFmx Instr Python API Status

| Item                         | Details                      |
|------------------------------|-------------------------------|
| **Driver Version Tested**    | [2026 Q3](http://www.ni.com/downloads/)                      |
| **Supported Python Versions**| Python 3.9+ (64-bit)    |
| **Documentation**            | [RFmx Instr Docs](https://nirfmx-python-nirfmxinstr.readthedocs-hosted.com/en/latest/) |


## RFmx Pulse Python API Status

| Item                         | Details                      |
|------------------------------|-------------------------------|
| **Driver Version Tested**    | [2026 Q3](http://www.ni.com/downloads/)                      |
| **Supported Python Versions**| Python 3.9+ (64-bit)    |
| **Documentation**            | [RFmx Pulse Docs](https://nirfmx-python-nirfmxpulse.readthedocs-hosted.com/en/latest/) |


## Documentation

You can find the latest API documentation for the **nirfmx-python** package
on [Read the Docs](https://nirfmx-python-nirfmxinstr.readthedocs-hosted.com/en/latest/)

Refer to the [RFmx User Manual](https://www.ni.com/docs/en-US/bundle/rfmx/page/user-manual-welcome.html)
for an overview of RFmx, system requirements, troubleshooting, key concepts, etc.


## Operating System Support

**nirfmx-python** supports Windows systems where the supported drivers are 
installed. Refer to [NI Hardware and Operating System Compatibility](https://www.ni.com/r/hw-support) for 
which versions of the driver support your hardware on a given operating system.


## Installation

You can use [pip](http://pypi.python.org/pypi/pip) to download [nirfmxpulse](https://pypi.org/project/nirfmxpulse/) and install it.
    
    $ python -m pip install nirfmxpulse

To also install gRPC support for remote NI gRPC Device Server communication:

    $ python -m pip install "nirfmxpulse[grpc]"

## Upgrade

You can use [pip](http://pypi.python.org/pypi/pip) to upgrade [nirfmxpulse](https://pypi.org/project/nirfmxpulse/) package using following command:

    $ python -m pip install nirfmxpulse --upgrade


## License

This project is licensed under the MIT License. While the source code is not publicly released,
the license permits binary distribution with attribution.

**Note:** This Python driver depends on several third-party components that are subject to separate
commercial licenses. Users are responsible for ensuring they have the appropriate rights and licenses
to use those dependencies in their environments.


# gRPC Features

For driver APIs that support it, passing a GrpcSessionOptions instance as a parameter to nirfmxinstr.Session.__init__() is subject to the NI General Purpose EULA.


# SSL/TLS Support

The server supports both server-side TLS and mutual TLS. Security configuration is accomplished by setting the `server_cert`, `server_key` and `root_cert` values in the server's configuration file. The server expects the certificate files specified in the configuration file to exist in a `certs` folder that is located in the same directory as the configuration file being used by the server. For more detailed information on SSL/TLS support refer to the [Server Security Support wiki page](https://github.com/ni/grpc-device/wiki/Server-Security-Support).


## Support and Feedback

For support with Python API, hardware, the driver runtime or any other questions,
please visit [NI Community Forums](https://forums.ni.com/).


## RFmxPulse Example

```python

import nirfmxinstr
import nirfmxpulse
import numpy

instr_session = None
pulse = None

try:
    # Create a new RFmx Session
    instr_session = nirfmxinstr.Session(resource_name, option_string)

    # Get Pulse signal configuration
    pulse = instr_session.get_pulse_signal_configuration()

    # Configure measurement
    instr_session.configure_frequency_reference(
        selector_string="",
        frequency_reference_source="OnboardClock", 
        frequency_reference_frequency=10.0e6
    )
    pulse.configure_rf(
        selector_string="", 
        center_frequency=1.0e9, 
        reference_level=-10.0,
        external_attenuation=0.0
    )
    pulse.configure_iq_power_edge_trigger(
        selector_string="",
        iq_power_edge_source="0",
        iq_power_edge_slope=nirfmxpulse.IQPowerEdgeTriggerSlope.RISING,
        iq_power_edge_level=-20.0,
        trigger_delay=0.0,
        trigger_min_quiet_time_mode=nirfmxpulse.TriggerMinimumQuietTimeMode.AUTO,
        trigger_min_quiet_time_duration=5.0e-6,
        iq_power_edge_level_type=nirfmxpulse.IQPowerEdgeTriggerLevelType.RELATIVE,
        enable_trigger=True,
    )
    pulse.set_measurement_bandwidth(selector_string="", value=80.0e6)
    pulse.set_measurement_filter_type(
        selector_string="",
        value=nirfmxpulse.MeasurementFilterType.GAUSSIAN
    )
    pulse.set_acquisition_length(selector_string="", value=1.0e-3)
    pulse.select_measurements(
        selector_string="",
        measurements=nirfmxpulse.MeasurementTypes.PULSE, 
        enable_all_traces=True
    )

    # Configure Pulse Detection Settings
    pulse.pulse_measurement.configuration.set_detection_reference(
        selector_string="", value=nirfmxpulse.PulseDetectionReference.REFERENCE_LEVEL
    )
    pulse.pulse_measurement.configuration.set_detection_threshold(
        selector_string="", value=-20.0
    )
    pulse.pulse_measurement.configuration.set_detection_hysteresis(
        selector_string="", value=1.0
    )
    pulse.pulse_measurement.configuration.set_detection_minimum_off_duration(
        selector_string="", value=50.0e-9
    )
    pulse.pulse_measurement.configuration.set_level_computation_method(
        selector_string="", value=nirfmxpulse.PulseLevelComputationMethod.MEDIAN
    )
    pulse.pulse_measurement.configuration.set_metrics_enabled(
        selector_string="", value=nirfmxpulse.PulseMetricsEnabled.TRUE
    )
    pulse.initiate(selector_string="", result_name="")
    pulse.wait_for_measurement_complete(selector_string="", timeout=10.0)

    # Retrieve results
    pulse_count, _ = pulse.pulse_measurement.results.get_pulse_count(selector_string="")
    rise_time, _ = pulse.pulse_measurement.results.get_rise_time(selector_string="")
    fall_time, _ = pulse.pulse_measurement.results.get_fall_time(selector_string="")
    pulse_width, _ = pulse.pulse_measurement.results.get_pulse_width(selector_string="")
    top_level, _ = pulse.pulse_measurement.results.get_top_level(selector_string="")
    base_level, _ = pulse.pulse_measurement.results.get_base_level(selector_string="")
    average_on_level, _ = pulse.pulse_measurement.results.get_average_on_level(
        selector_string=""
    )
    # The numpy arrays are passed in pre-allocated. If the pre allocated array size does not match the
    # actual array size returned by the measurement, the array is automatically resized to fit the data,
    # which may invalidate the previously created view. Passing an empty array (size 0) is fine;
    # it will be resized as needed.
    amplitude = numpy.empty(0, dtype=numpy.float32)
    pulse.pulse_measurement.results.fetch_amplitude_trace(
        selector_string="", timeout=10.0, amplitude=amplitude
    )

    # Print results
    print(f"Pulse Count                            : {pulse_count}")
    for i in range(len(rise_time)):
        print(f"Rise Time (s)                          : {rise_time[i]:.11f}")
        print(f"Fall Time (s)                          : {fall_time[i]:.11f}")
        print(f"Pulse Width (s)                        : {pulse_width[i]:.9f}")
        print(f"Top Level (dBm)                        : {top_level[i]}")
        print(f"Base Level (dBm)                       : {base_level[i]}")
        print(f"Average On Level (dBm)                 : {average_on_level[i]}")

except Exception as e:
    print("ERROR: " + str(e))

finally:
    # Close Session
    if pulse is not None:
        pulse.dispose()
        pulse = None
    if instr_session is not None:
        instr_session.close()
        instr_session = None

```


## Numpy array size handling in RFmx APIs

The numpy arrays are passed in pre-allocated. If the pre allocated array size does not match the actual array size returned by the measurement, the array is automatically resized to fit the data, which may invalidate the previously created view. Passing an empty array (size 0) is fine; it will be resized as needed.

