RFmx Vna 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
========================

**nirfmxvna** 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
`nirfmxvna <https://pypi.org/project/nirfmxvna/>`_ and install it.

.. code-block:: shell

    $ python -m pip install nirfmxvna

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
  iq
  iq_configuration
  iq_results
  marker
  marker_configuration
  marker_results
  s_params
  s_params_configuration
  s_params_results
  vna
  waves
  waves_configuration
  waves_results

Example:
========

.. code-block:: python

  import nirfmxinstr
  import nirfmxvna
  import numpy

  instr_session = None
  vna_signal = None

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

    # Get VNA signal configuration
    vna_signal = instr_session.get_vna_signal_configuration()

    instr_session.configure_frequency_reference(
      selector_string="",
      frequency_reference_source="OnboardClock",
      frequency_reference_frequency=10e6
    )

    vna_signal.set_sweep_type(selector_string="", value=nirfmxvna.SweepType.LINEAR)
    vna_signal.set_start_frequency(selector_string="", value=1e9)
    vna_signal.set_stop_frequency(selector_string="", value=2e9)
    vna_signal.set_number_of_points(selector_string="", value=101)
    vna_signal.set_if_bandwidth(selector_string="", value=10e3)

    port_selector_string = nirfmxvna.Vna.build_port_string(selector_string="", port_string="port1")
    vna_signal.set_power_level(selector_string=port_selector_string, value=-10.0)
    vna_signal.set_test_receiver_attenuation(
      selector_string=port_selector_string,
      value=0.0
    )

    port_selector_string = nirfmxvna.Vna.build_port_string(selector_string="", port_string="port2")
    vna_signal.set_power_level(selector_string=port_selector_string, value=-10.0)
    vna_signal.set_test_receiver_attenuation(
      selector_string=port_selector_string,
      value=0.0
    )

    vna_signal.set_averaging_enabled(
      selector_string="",
      value=nirfmxvna.AveragingEnabled.FALSE
    )
    vna_signal.set_averaging_count(selector_string="", value=10)

    vna_signal.select_measurements(
      selector_string="",
      measurements=nirfmxvna.MeasurementTypes.WAVES,
      enable_all_traces=True
    )

    vna_signal.waves.configuration.set_number_of_waves(selector_string="", value=2)

    for i in range(2):
      wave_selector_string = nirfmxvna.Vna.build_wave_string(selector_string="", wave_index=i)
      vna_signal.waves.configuration.configure_wave(
        selector_string=wave_selector_string,
        receiver=nirfmxvna.WavesReceiver.TEST,
        source_port="port1",
        measurement_port="port1"
      )
      vna_signal.waves.configuration.set_format(
        selector_string=wave_selector_string,
        value=nirfmxvna.WavesFormat.MAGNITUDE
      )

    vna_signal.waves.configuration.set_magnitude_units(
      selector_string="",
      value=nirfmxvna.WavesMagnitudeUnits.DBM
    )
    vna_signal.waves.configuration.set_phase_trace_type(
      selector_string="",
      value=nirfmxvna.WavesPhaseTraceType.WRAPPED
    )

    vna_signal.initiate(selector_string="", result_name="")

    # Retrieve results
    number_of_waves_result, error_code = vna_signal.waves.configuration.get_number_of_waves(
      selector_string=""
    )

    waves_x_data_result = numpy.empty(0, dtype=numpy.float64)
    waves_x_data_result = vna_signal.waves.results.fetch_x_data(
      selector_string="",
      timeout=10.0
    )

    waves_y1_data_result = []
    waves_y2_data_result = []

    for i in range(number_of_waves_result):
      wave_selector_string = nirfmxvna.Vna.build_wave_string(selector_string="", wave_index=i)

      y1_data, y2_data, error_code = vna_signal.waves.results.fetch_y_data(
        selector_string=wave_selector_string,
        timeout=10.0
      )

      waves_y1_data_result.append(y1_data)
      waves_y2_data_result.append(y2_data)

  except Exception as e:
    print(f"Error occurred: {e}")
    sys.exit(1)

  finally:
    if vna_signal is not None:
      vna_signal.dispose()
      vna_signal = 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`