RFmx WLAN Generation 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
========================

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

.. code-block:: shell

    $ python -m pip install nirfmxwlangen

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
  wlangen

Example:
========

.. code-block:: python

  import nirfmxwlangen
  import nirfsg

  num_tx = 4
  resource_names = ["RFSG0", "RFSG1", "RFSG2", "RFSG3"]
  waveform_name = "Wlan"
  script = (
    "script GenerateWlan\n"
    "    repeat forever\n"
    "        generate Wlan\n"
    "    end repeat\n"
    "end script"
  )

  wlangen_session = None
  rfsg_sessions = [None] * num_tx

  try:
    # Create RFSG Sessions
    active_rfsg_sessions = []
    for i in range(num_tx):
      rfsg_sessions[i] = nirfsg.Session(resource_names[i])
      rfsg_sessions[i].power_level_type = nirfsg.PowerLevelType.PEAK
      rfsg_sessions[i].external_gain = 0.0
      active_rfsg_sessions.append(rfsg_sessions[i])

    # Create WLAN Generation Session
    wlangen_session = nirfmxwlangen.Session(
      nirfmxwlangen.CompatibilityVersion.Version060000, "WlanGenSession"
    )

    # Configure WLAN MIMO OFDM standard and parameters
    wlangen_session.set_standard("", nirfmxwlangen.Standard.STANDARD_80211AX_MIMO_OFDM)
    wlangen_session.set_channel_bandwidth("", 80e6)
    wlangen_session.set_number_of_transmit_channels("", num_tx)
    wlangen_session.set_mcs_index("", 0)
    wlangen_session.set_mapping_matrix_type("", nirfmxwlangen.MappingMatrixType.DIRECT)
    wlangen_session.set_number_of_space_time_streams("", num_tx)
    wlangen_session.set_lo_frequency_offset_mode("", nirfmxwlangen.LOFrequencyOffsetMode.AUTO)
    wlangen_session.set_rf_blanking_enabled("", nirfmxwlangen.RFBlankingEnabled.TRUE)

    # Configure Multiple Device Synchronization
    wlangen_session.rfsg_configure_multiple_device_synchronization(
      active_rfsg_sessions, "PXI_Clk", [0, 1]
    )

    # Configure Frequency using Single LO
    wlangen_session.rfsg_configure_frequency_single_lo(
      active_rfsg_sessions,
      nirfmxwlangen.LOSource.ONBOARD,
      rfsg_sessions[0],
      5.18e9,
      False,
      False,
    )

    # Create and Download MIMO Waveforms
    wlangen_session.rfsg_create_and_download_mimo_waveforms(
      active_rfsg_sessions, None, waveform_name
    )

    # Configure Script for each RFSG device and Initiate Generation
    for i in range(num_tx):
      wlangen_session.rfsg_configure_script(rfsg_sessions[i], "", script, -10.0)
    wlangen_session.rfsg_multiple_device_initiate(active_rfsg_sessions)

    # Print Results
    iq_rate, _ = wlangen_session.get_iq_rate("")
    iq_waveform_size, _ = wlangen_session.get_iq_waveform_size("")
    print(f"Waveform Duration {{s}}{iq_waveform_size / iq_rate}")
    print("Actual Headroom (dB)")
    for i in range(num_tx):
      actual_headroom, _ = wlangen_session.get_actual_headroom(f"channel{i}")
      print(f"\t{actual_headroom}")

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

  finally:
    # Stop Generation and Close Sessions
    for i in range(num_tx):
      if rfsg_sessions[i] is not None:
        rfsg_sessions[i].abort()
        rfsg_sessions[i].output_enabled = False
        rfsg_sessions[i].commit()
    if wlangen_session is not None:
      for i in range(num_tx):
        wlangen_session.rfsg_clear_database(rfsg_sessions[i], "", waveform_name)
      wlangen_session.close()
      wlangen_session = None
    for i in range(num_tx):
      if rfsg_sessions[i] is not None:
        rfsg_sessions[i].close()
        rfsg_sessions[i] = 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`