"""Provides methods to fetch and read the Obw measurement results."""
import functools
import nirfmxlte.attributes as attributes
import nirfmxlte.errors as errors
import nirfmxlte.internal._helper as _helper
def _raise_if_disposed(f):
"""From https://stackoverflow.com/questions/5929107/decorators-with-parameters."""
@functools.wraps(f)
def aux(*xs, **kws):
meas_obj = xs[0] # parameter 0 is 'self' which is the measurement object
if meas_obj._signal_obj.is_disposed:
raise Exception("Cannot access a disposed Lte signal configuration")
return f(*xs, **kws)
return aux
[docs]
class ObwResults(object):
"""Provides methods to fetch and read the Obw measurement results."""
def __init__(self, signal_obj):
"""Provides methods to fetch and read the Obw measurement results."""
self._signal_obj = signal_obj
self._session_function_lock = signal_obj._session_function_lock
self._interpreter = signal_obj._interpreter
[docs]
@_raise_if_disposed
def get_occupied_bandwidth(self, selector_string):
r"""Gets the bandwidth that occupies 99 percentage of the total power of the signal within a carrier/subblock. This
value is expressed in Hz.
Refer to the `LTE Occupied Bandwidth
<https://www.ni.com/docs/en-US/bundle/rfmx-lte/page/lte-occupied-bandwidth.html>`_ topic for more information.
Use "subblock<*n*>" as the selector string to read this result.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the bandwidth that occupies 99 percentage of the total power of the signal within a carrier/subblock. This
value is expressed in Hz.
error_code (int):
Returns the status code of this method. The status code either indicates success or describes a warning condition.
"""
try:
self._session_function_lock.enter_read_lock()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
attr_val, error_code = self._interpreter.get_attribute_f64(
updated_selector_string, attributes.AttributeID.OBW_RESULTS_OCCUPIED_BANDWIDTH.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_absolute_power(self, selector_string):
r"""Gets the total power measured in the carrier/subblock. This value is expressed in dBm.
Use "subblock<*n*>" as the selector string to read this result.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the total power measured in the carrier/subblock. This value is expressed in dBm.
error_code (int):
Returns the status code of this method. The status code either indicates success or describes a warning condition.
"""
try:
self._session_function_lock.enter_read_lock()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
attr_val, error_code = self._interpreter.get_attribute_f64(
updated_selector_string, attributes.AttributeID.OBW_RESULTS_ABSOLUTE_POWER.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_start_frequency(self, selector_string):
r"""Gets the start frequency of the carrier/subblock. This value is expressed in Hz. The occupied bandwidth is
calculated using the following equation:
*Stop frequency* - *Start frequency* = *Occupied bandwidth*
Use "subblock<*n*>" as the selector string to read this result.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the start frequency of the carrier/subblock. This value is expressed in Hz. The occupied bandwidth is
calculated using the following equation:
error_code (int):
Returns the status code of this method. The status code either indicates success or describes a warning condition.
"""
try:
self._session_function_lock.enter_read_lock()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
attr_val, error_code = self._interpreter.get_attribute_f64(
updated_selector_string, attributes.AttributeID.OBW_RESULTS_START_FREQUENCY.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_stop_frequency(self, selector_string):
r"""Gets the stop frequency of the carrier/subblock. This value is expressed in Hz. Occupied bandwidth is calculated
using the following equation:
*Occupied bandwidth* = *Stop frequency* - *Start frequency*
Use "subblock<*n*>" as the selector string to read this result.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the stop frequency of the carrier/subblock. This value is expressed in Hz. Occupied bandwidth is calculated
using the following equation:
error_code (int):
Returns the status code of this method. The status code either indicates success or describes a warning condition.
"""
try:
self._session_function_lock.enter_read_lock()
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
attr_val, error_code = self._interpreter.get_attribute_f64(
updated_selector_string, attributes.AttributeID.OBW_RESULTS_STOP_FREQUENCY.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def fetch_measurement(self, selector_string, timeout):
r"""Returns the occupied bandwidth, absolute power, start frequency, and stop frequency of a component carrier or subblock.
Use "subblock<*n*>" as the selector string to read results from this method.
Refer to the `LTE Occupied Bandwidth
<https://www.ni.com/docs/en-US/bundle/rfmx-lte/page/lte-occupied-bandwidth.html>`_ topic for more information about OBW
measurements.
Args:
selector_string (string):
This parameter specifies a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ comprising of result
name, and subblock number.
Example:
"subblock0"
"result::r1/subblock0"
You can use the :py:meth:`build_subblock_string` method to build the selector string.
timeout (float):
This parameter specifies the timeout for fetching the specified measurement. This value is expressed in seconds. Set
this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the
method waits until the measurement is complete. The default value is 10.
Returns:
Tuple (occupied_bandwidth, absolute_power, start_frequency, stop_frequency, error_code):
occupied_bandwidth (float):
This parameter returns the bandwidth that occupies 99 percentage of the total power of the signal within a
carrier/subblock.
absolute_power (float):
This parameter returns the power measured over the integration bandwidth of the carrier. The carrier power is reported
in dBm when you set the :py:attr:`~nirfmxlte.attributes.AttributeID.ACP_POWER_UNITS` attribute to **dBm**, and in
dBm/Hz when you set the ACP Pwr Units attribute to **dBm/Hz**.
start_frequency (float):
This parameter returns the start frequency of the subblock. The occupied bandwidth of a carrier/subblock is calculated
using the following equation:
*Stop frequency* - *Start frequency* = *Occupied bandwidth*.
stop_frequency (float):
This parameter returns the stop frequency of the subblock. The occupied bandwidth of a carrier/subblock is calculated
using the following equation:
*Stop frequency* - *Start frequency* = *Occupied bandwidth*.
error_code (int):
Returns the status code of this method. The status code either indicates success or describes a warning condition.
"""
try:
self._session_function_lock.enter_read_lock()
_helper.validate_not_none(selector_string, "selector_string")
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
occupied_bandwidth, absolute_power, start_frequency, stop_frequency, error_code = (
self._interpreter.obw_fetch_measurement(updated_selector_string, timeout)
)
finally:
self._session_function_lock.exit_read_lock()
return occupied_bandwidth, absolute_power, start_frequency, stop_frequency, error_code
[docs]
@_raise_if_disposed
def fetch_spectrum(self, selector_string, timeout, spectrum):
r"""Fetches the spectrum used for OBW measurements.
Args:
selector_string (string):
This parameter specifies a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ comprising of the
result name.
Example:
"result::r1"
You can use the :py:meth:`build_result_string` method to build the selector string.
timeout (float):
This parameter specifies the timeout for fetching the specified measurement. This value is expressed in seconds. Set
this value to an appropriate time, longer than expected for fetching the measurement. A value of -1 specifies that the
method waits until the measurement is complete. The default value is 10.
spectrum (numpy.float32):
This parameter returns the array of averaged power measured at each frequency bin. This value is expressed in dBm.
Returns:
Tuple (x0, dx, error_code):
x0 (float):
This parameter returns the start frequency of the channel. This value is expressed in Hz.
dx (float):
This parameter returns the frequency bin spacing. This value is expressed in Hz.
error_code (int):
Returns the status code of this method. The status code either indicates success or describes a warning condition.
"""
try:
self._session_function_lock.enter_read_lock()
_helper.validate_not_none(selector_string, "selector_string")
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
x0, dx, error_code = self._interpreter.obw_fetch_spectrum(
updated_selector_string, timeout, spectrum
)
finally:
self._session_function_lock.exit_read_lock()
return x0, dx, error_code