RFmx Pulse Python API Documentation
===================================

About
=====

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

**nirfmx-python** follows `Python Software Foundation <https://devguide.python.org/#status-of-python-branches>`_
support policy for different versions.

Operating System Support
========================

**nirfmxpulse** 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.

.. code-block:: shell

    $ python -m pip install nirfmxpulse

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/>`_.

Documentation:
==============

.. toctree::
  :maxdepth: 1

  attributes
  enums
  errors
  grpc_session_options
  pulse
  pulse_measurement
  pulse_measurement_configuration
  pulse_measurement_results

Example:
========

.. code-block:: python

  import nirfmxinstr
  import nirfmxpulse
  import numpy

  instr_session = None
  pulse = None

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

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

    # Configure frequency reference
    instr_session.configure_frequency_reference(
      selector_string="",
      frequency_reference_source="OnboardClock",
      frequency_reference_frequency=10.0e6
    )

    # Configure RF
    pulse.configure_rf(
      selector_string="",
      center_frequency=1.0e9,
      reference_level=-10.0,
      external_attenuation=0.0
    )

    # Select Pulse measurement
    pulse.select_measurements(
      selector_string="",
      measurements=nirfmxpulse.MeasurementTypes.PULSE,
      enable_all_traces=True
    )

    # Configure trigger
    pulse.configure_iq_power_edge_trigger(
      selector_string="",
      iq_power_edge_trigger_source="0",
      iq_power_edge_trigger_slope=nirfmxpulse.IQPowerEdgeTriggerSlope.RISING,
      iq_power_edge_trigger_level=-20.0,
      trigger_delay=0.0,
      trigger_minimum_quiet_time_mode=nirfmxpulse.TriggerMinimumQuietTimeMode.AUTO,
      trigger_minimum_quiet_time_duration=5.0e-6,
      iq_power_edge_trigger_level_type=nirfmxpulse.IQPowerEdgeTriggerLevelType.RELATIVE,
      enable_trigger=True
    )

    # Configure acquisition settings
    pulse.set_measurement_bandwidth(selector_string="", value=80.0e6)
    pulse.set_measurement_filter_type(
      selector_string="",
      value=nirfmxpulse.MeasurementFilterType.RECTANGULAR
    )
    pulse.set_acquisition_length(selector_string="", value=1.0e-3)
    pulse.set_maximum_pulse_count_enabled(
      selector_string="",
      value=nirfmxpulse.MaximumPulseCountEnabled.FALSE
    )
    pulse.set_maximum_pulse_count(selector_string="", value=100)

    # 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
    )

    # Configure state and threshold level settings
    pulse.pulse_measurement.configuration.set_level_computation_method(
      selector_string="",
      value=nirfmxpulse.PulseLevelComputationMethod.MEDIAN
    )
    pulse.pulse_measurement.configuration.set_droop_compensation_enabled(
      selector_string="",
      value=nirfmxpulse.PulseDroopCompensationEnabled.TRUE
    )

    # Configure time sidelobe settings
    pulse.pulse_measurement.configuration.set_time_sidelobe_enabled(
      selector_string="",
      value=nirfmxpulse.PulseTimeSidelobeEnabled.TRUE
    )
    pulse.pulse_measurement.configuration.set_time_sidelobe_reference_window_type(
      selector_string="",
      value=nirfmxpulse.PulseTimeSidelobeReferenceWindowType.NONE
    )
    pulse.pulse_measurement.configuration.set_time_sidelobe_keep_out_time_auto(
      selector_string="",
      value=nirfmxpulse.PulseTimeSidelobeKeepOutTimeAuto.TRUE
    )
    pulse.pulse_measurement.configuration.set_time_sidelobe_minimum_correlation(
      selector_string="", value=0.5
    )

    # Disable pulse metrics and stability
    pulse.pulse_measurement.configuration.set_metrics_enabled(
      selector_string="",
      value=nirfmxpulse.PulseMetricsEnabled.FALSE
    )
    pulse.pulse_measurement.configuration.set_stability_enabled(
      selector_string="",
      value=nirfmxpulse.PulseStabilityEnabled.FALSE
    )

    # Initiate and wait for completion
    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=""
    )

    mainlobe_width, _ = pulse.pulse_measurement.results.get_time_sidelobe_mainlobe_width(
      selector_string=""
    )
    sidelobe_delay, _ = pulse.pulse_measurement.results.get_time_sidelobe_delay(
      selector_string=""
    )
    peak_sidelobe_level, _ = pulse.pulse_measurement.results.get_time_sidelobe_peak_sidelobe_level(
      selector_string=""
    )
    compression_ratio, _ = pulse.pulse_measurement.results.get_time_sidelobe_compression_ratio(
      selector_string=""
    )
    peak_correlation, _ = pulse.pulse_measurement.results.get_time_sidelobe_peak_correlation(
      selector_string=""
    )

    time_sidelobe_trace = numpy.empty(0, dtype=numpy.float32)
    _, _, _ = pulse.pulse_measurement.results.fetch_time_sidelobe_trace(
      selector_string="", timeout=10.0, trace=time_sidelobe_trace
    )

    # Print results
    print(f"\nPulse Count : {pulse_count}\n")
    print("---------------------Time Sidelobe Results---------------------")
    for i in range(pulse_count):
      print(f"Index                        : {i}")
      print(f"Mainlobe Width (s)           : {mainlobe_width[i]:.11f}")
      print(f"Sidelobe Delay (s)           : {sidelobe_delay[i]:.11f}")
      print(f"Peak Sidelobe Level (dB)     : {peak_sidelobe_level[i]:.9f}")
      print(f"Compression Ratio (%)        : {compression_ratio[i]:.9f}")
      print(f"Peak Correlation             : {peak_correlation[i]:.9f}")
      print("---------------------------------------------------------------\n")

  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


Additional Documentation
========================

Refer to the `NI-RFmx User Manual <https://www.ni.com/docs/en-US/bundle/rfmx/page/user-manual-welcome.html>`_
for an overview of NI-RFmx, system requirements, troubleshooting, key concepts, etc.

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 
:py:meth:`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).

Indices and Tables
==================

* :ref:`genindex`
* :ref:`modindex`