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

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

.. code-block:: shell

    $ python -m pip install nirfmxlte

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_component_carrier_results
  acp_configuration
  acp_results
  attributes
  chp
  chp_component_carrier_results
  chp_configuration
  chp_results
  component_carrier
  enums
  errors
  grpc_session_options
  lte
  modacc
  modacc_configuration
  modacc_results
  obw
  obw_configuration
  obw_results
  pvt
  pvt_configuration
  pvt_results
  sem
  sem_component_carrier_configuration
  sem_component_carrier_results
  sem_configuration
  sem_results
  slotphase
  slotphase_configuration
  slotphase_results
  slotpower
  slotpower_configuration
  slotpower_results
  txp
  txp_configuration
  txp_results

Example:
========

.. code-block:: python

  import nirfmxinstr
  import nirfmxlte
  import numpy

  instr_session = None
  lte_signal = None

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

    # Get LTE signal configuration
    lte_signal = instr_session.get_lte_signal_configuration()

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

    lte_signal.configure_rf(
      selector_string="",
      center_frequency=2.115e9,
      reference_level=0.0,
      external_attenuation=0.0
    )

    lte_signal.configure_digital_edge_trigger(
      selector_string="",
      digital_edge_source="PXI_Trig0",
      digital_edge=nirfmxlte.DigitalEdgeTriggerEdge.RISING_EDGE,
      trigger_delay=0.0,
      enable_trigger=True
    )

    lte_signal.component_carrier.configure(
      selector_string="",
      component_carrier_bandwidth=10e6,
      component_carrier_frequency=0.0,
      cell_id=0
    )

    lte_signal.select_measurements(
      selector_string="",
      measurements=nirfmxlte.MeasurementTypes.CHP,
      enable_all_traces=True
    )

    lte_signal.chp.configuration.configure_sweep_time(
      selector_string="",
      sweep_time_auto=nirfmxlte.ChpSweepTimeAuto.TRUE,
      sweep_time_interval=1.0e-3
    )
    lte_signal.chp.configuration.configure_averaging(
      selector_string="",
      averaging_enabled=nirfmxlte.ChpAveragingEnabled.FALSE,
      averaging_count=10,
      averaging_type=nirfmxlte.ChpAveragingType.RMS
    )

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

    absolute_power, relative_power, error_code = (
      lte_signal.chp.results.component_carrier.fetch_measurement(
        selector_string="",
        timeout=10.0
      )
    )

    spectrum = numpy.empty(0, dtype=numpy.float32)
    x0, dx, error_code = lte_signal.chp.results.fetch_spectrum(
      selector_string="",
      timeout=10.0,
      spectrum=spectrum
    )

    # Print results
    print(f"Carrier Absolute Power (dBm)         :{absolute_power}")

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

  finally:
    # Close Session
    if lte_signal is not None:
      lte_signal.dispose()
      lte_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`