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

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

.. code-block:: shell

    $ python -m pip install nirfmxspecan

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

  acp
  acp_configuration
  acp_results
  ampm
  ampm_configuration
  ampm_results
  attributes
  ccdf
  ccdf_configuration
  ccdf_results
  chp
  chp_configuration
  chp_results
  dpd
  dpd_apply_dpd
  dpd_configuration
  dpd_pre_dpd
  dpd_results
  enums
  errors
  fcnt
  fcnt_configuration
  fcnt_results
  grpc_session_options
  harm
  harm_configuration
  harm_results
  idpd
  idpd_configuration
  idpd_results
  im
  im_configuration
  im_results
  iq
  iq_configuration
  iq_results
  marker
  marker_configuration
  marker_results
  nf
  nf_configuration
  nf_results
  obw
  obw_configuration
  obw_results
  pavt
  pavt_configuration
  pavt_results
  phase_noise
  phase_noise_configuration
  phase_noise_results
  power_list
  power_list_configuration
  power_list_results
  sem
  sem_configuration
  sem_results
  specan
  spectrum
  spectrum_configuration
  spectrum_results
  spur
  spur_configuration
  spur_results
  txp
  txp_configuration
  txp_results

Example:
========

.. code-block:: python

  import nirfmxinstr
  import nirfmxspecan
  import numpy

  instr_session = None
  specan = None

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

    # Configure RFmx Session
    instr_session.configure_frequency_reference(selector_string="",
      frequency_reference_source="OnboardClock", frequency_reference_frequency=10.0e+6)

    # Create SpecAn Signal
    specan = instr_session.get_specan_signal_configuration()

    # Configure SpecAn Signal
    specan.set_selected_ports(selector_string="", value="")
    specan.configure_frequency(selector_string="", center_frequency=1e+9)
    specan.configure_reference_level(selector_string="", reference_level=0.0)
    specan.configure_external_attenuation(selector_string="", external_attenuation=0.0)

    # Select Spectrum Measurement
    specan.select_measurements(selector_string="",
      measurement=nirfmxspecan.MeasurementTypes.SPECTRUM, enable_all_traces=True)

    # Configure Spectrum Measurement
    specan.spectrum.configuration.configure_span(selector_string="", span=1.0e+6)
    specan.spectrum.configuration.configure_measurement_method(selector_string="",
      measurement_method=nirfmxspecan.SpectrumMeasurementMethod.NORMAL)

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

    # Retrieve Results
    spectrum = numpy.empty(0, dtype=numpy.float32)
    x0, dx, _ = specan.spectrum.results.fetch_spectrum(selector_string="", timeout=10.0,
      spectrum=spectrum)
    peak_amplitude, peak_frequency, frequency_resolution, error_code = (
      specan.spectrum.results.fetch_measurement(selector_string="", timeout=10.0))

    # Print Results
    print(f"Peak Amplitude (dBm)             {peak_amplitude}")
    print(f"Peak Frequency (Hz)              {peak_frequency}")

  except nirfmxinstr.RFmxError as e:
    print("ERROR: " + str(e.description))

  finally:
    # Dispose Signal & Session
    if specan is not None:
        specan.dispose()
        specan = 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.

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

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