"""Provides methods to fetch and read the Pvt measurement results."""
import functools
import nirfmxgsm.attributes as attributes
import nirfmxgsm.enums as enums
import nirfmxgsm.errors as errors
import nirfmxgsm.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 Gsm signal configuration")
return f(*xs, **kws)
return aux
[docs]
class PvtResults(object):
"""Provides methods to fetch and read the Pvt measurement results."""
def __init__(self, signal_obj):
"""Provides methods to fetch and read the Pvt 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_measurement_status(self, selector_string):
r"""Indicates the overall measurement status based on standard-defined limits.
You do not need to use a `Selector String
<https://www.ni.com/docs/en-US/bundle/rfmx/page/selector-strings-net.html>`_ to read this result for the default signal
and result instances. Refer to the Selector String topic for information about the string syntax for named signals and
named results.
+--------------+---------------------------------------------------------------------------------------------------------------+
| Name (Value) | Description |
+==============+===============================================================================================================+
| Fail (0) | The measurement failed because the average power of at least one slot is outside the standard-defined limits. |
+--------------+---------------------------------------------------------------------------------------------------------------+
| Pass (1) | The measurement passed because the average power of all slots is within the standard-defined limits. |
+--------------+---------------------------------------------------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (enums.PvtMeasurementStatus):
Indicates the overall measurement status based on standard-defined limits.
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_i32(
updated_selector_string, attributes.AttributeID.PVT_RESULTS_MEASUREMENT_STATUS.value
)
attr_val = enums.PvtMeasurementStatus(attr_val)
except (KeyError, ValueError):
raise errors.DriverTooNewError() # type: ignore
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_slot_average_power(self, selector_string):
r"""Gets the mean power of the signal, averaged over the corresponding slots of each acquisition. This value is
expressed in dBm.
Use "slot<*n*>" as the selector string to read this attribute.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the mean power of the signal, averaged over the corresponding slots of each acquisition. 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.PVT_RESULTS_SLOT_AVERAGE_POWER.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_slot_burst_width(self, selector_string):
r"""Gets the burst width for the slot where the -3 dB transition points occur. This value is expressed in seconds.
Use "slot<*n*>" as the selector string to read this attribute.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the burst width for the slot where the -3 dB transition points occur. This value is expressed in seconds.
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.PVT_RESULTS_SLOT_BURST_WIDTH.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_slot_maximum_power(self, selector_string):
r"""Gets the maximum power of the signal, averaged over the corresponding slots of each acquisition. This value is
expressed in dBm.
Use "slot<*n*>" as the selector string to read this attribute.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the maximum power of the signal, averaged over the corresponding slots of each acquisition. 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.PVT_RESULTS_SLOT_MAXIMUM_POWER.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_slot_minimum_power(self, selector_string):
r"""Gets the minimum power of the signal, averaged over the corresponding slots of each acquisition. This value is
expressed in dBm.
Use "slot<*n*>" as the selector string to read this attribute.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the minimum power of the signal, averaged over the corresponding slots of each acquisition. 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.PVT_RESULTS_SLOT_MINIMUM_POWER.value
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_slot_burst_threshold(self, selector_string):
r"""Gets the threshold that the power versus time (PVT) measurement uses to determine the burst validity. This value is
expressed in dBm.
Use "slot<*n*>" as the selector string to read this attribute.
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (float):
Returns the threshold that the power versus time (PVT) measurement uses to determine the burst validity. 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.PVT_RESULTS_SLOT_BURST_THRESHOLD.value,
)
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def get_slot_measurement_status(self, selector_string):
r"""Indicates the power versus time (PVT) measurement status for a particular slot.
Use "slot<*n*>" as the selector string to read this attribute.
+--------------+---------------------------------------------------------------------------------+
| Name (Value) | Description |
+==============+=================================================================================+
| Fail (0) | The average power for at least one slot is outside the standard-defined limits. |
+--------------+---------------------------------------------------------------------------------+
| Pass (1) | The average power for each slot is within the standard-defined limits. |
+--------------+---------------------------------------------------------------------------------+
Args:
selector_string (string):
Pass an empty string.
Returns:
Tuple (attr_val, error_code):
attr_val (enums.PvtSlotMeasurementStatus):
Indicates the power versus time (PVT) measurement status for a particular slot.
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_i32(
updated_selector_string,
attributes.AttributeID.PVT_RESULTS_SLOT_MEASUREMENT_STATUS.value,
)
attr_val = enums.PvtSlotMeasurementStatus(attr_val)
except (KeyError, ValueError):
raise errors.DriverTooNewError() # type: ignore
finally:
self._session_function_lock.exit_read_lock()
return attr_val, error_code
[docs]
@_raise_if_disposed
def fetch_measurement_status(self, selector_string, timeout):
r"""Fetches the overall PVT measurement status based on the standard defined measurement limits.
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. The default is "" (empty string).
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.
Returns:
Tuple (measurement_status, error_code):
measurement_status (enums.PvtMeasurementStatus):
This parameter indicates the overall measurement status based on standard-defined limits.
+--------------+---------------------------------------------------------------------------------------------------------------+
| Name (Value) | Description |
+==============+===============================================================================================================+
| Fail (0) | The measurement failed because the average power of at least one slot is outside the standard-defined limits. |
+--------------+---------------------------------------------------------------------------------------------------------------+
| Pass (1) | The measurement passed because the average power of all slots is within the standard-defined limits. |
+--------------+---------------------------------------------------------------------------------------------------------------+
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
)
measurement_status, error_code = self._interpreter.pvt_fetch_measurement_status(
updated_selector_string, timeout
)
finally:
self._session_function_lock.exit_read_lock()
return measurement_status, error_code
[docs]
@_raise_if_disposed
def fetch_slot_measurement(self, selector_string, timeout):
r"""Fetches the measurement results for a single-slot PVT measurement.
Use "slot<*n*>" as the selector string to read results from this method.
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 slot number. The default is "" (empty string).
Example:
"slot0"
"result::r1/slot0"
You can use the :py:meth:`build_slot_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 (slot_average_power, slot_burst_width, slot_measurement_status, slot_maximum_power, slot_minimum_power, slot_burst_threshold, error_code):
slot_average_power (float):
This parameter returns the mean power of the signal, averaged over corresponding slots of each acquisition. This value
is expressed in dBm.
slot_burst_width (float):
This parameter returns the burst width of the slot where the -3 dB transition points occur. This value is expressed in
seconds.
slot_measurement_status (enums.PvtSlotMeasurementStatus):
This parameter indicates the PVT measurement status for a particular slot.
+--------------+-----------------------------------------------------------------------+
| Name (Value) | Description |
+==============+=======================================================================+
| Fail (0) | The signal power is outside the standard-defined upper or lower mask |
+--------------+-----------------------------------------------------------------------+
| Pass (1) | The signal power is within the standard-defined upper and lower mask. |
+--------------+-----------------------------------------------------------------------+
slot_maximum_power (float):
This parameter returns the maximum power of the signal, averaged over corresponding slots of each acquisition. This
value is expressed in dBm.
slot_minimum_power (float):
This parameter returns the minimum power of the signal, averaged over corresponding slots of each acquisition. This
value is expressed in dBm.
slot_burst_threshold (float):
This parameter returns the threshold that the PVT measurement uses to determine the burst validity. 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()
_helper.validate_not_none(selector_string, "selector_string")
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
(
slot_average_power,
slot_burst_width,
slot_measurement_status,
slot_maximum_power,
slot_minimum_power,
slot_burst_threshold,
error_code,
) = self._interpreter.pvt_fetch_slot_measurement(updated_selector_string, timeout)
finally:
self._session_function_lock.exit_read_lock()
return (
slot_average_power,
slot_burst_width,
slot_measurement_status,
slot_maximum_power,
slot_minimum_power,
slot_burst_threshold,
error_code,
)
[docs]
@_raise_if_disposed
def fetch_slot_measurement_array(self, selector_string, timeout):
r"""Fetches the PVT measurement results for each slot.
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. The default is "" (empty string).
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.
Returns:
Tuple (slot_average_power, slot_burst_width, slot_measurement_status, slot_maximum_power, slot_minimum_power, slot_burst_threshold, error_code):
slot_average_power (float):
This parameter returns an array of mean powers of the signal, averaged over corresponding slots of each acquisition.
This value is expressed in dBm.
slot_burst_width (float):
This parameter returns an array of burst widths for the slots where the -3 dB transition points occur. This value is
expressed in seconds.
slot_measurement_status (enums.PvtSlotMeasurementStatus):
This parameter indicates an array of PVT measurement statuses for multiple slots.
+--------------+-----------------------------------------------------------------------+
| Name (Value) | Description |
+==============+=======================================================================+
| Fail (0) | The signal power is outside the standard-defined upper or lower mask |
+--------------+-----------------------------------------------------------------------+
| Pass (1) | The signal power is within the standard-defined upper and lower mask. |
+--------------+-----------------------------------------------------------------------+
slot_maximum_power (float):
This parameter returns an array of maximum powers of the signal, averaged over corresponding slots of each acquisition.
This value is expressed in dBm.
slot_minimum_power (float):
This parameter returns an array of minimum powers of the signal, averaged over corresponding slots of each acquisition.
This value is expressed in dBm.
slot_burst_threshold (float):
This parameter returns an array of thresholds that the PVT measurement uses to determine the burst validity. 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()
_helper.validate_not_none(selector_string, "selector_string")
updated_selector_string = _helper.validate_and_update_selector_string(
selector_string, self._signal_obj
)
(
slot_average_power,
slot_burst_width,
slot_measurement_status,
slot_maximum_power,
slot_minimum_power,
slot_burst_threshold,
error_code,
) = self._interpreter.pvt_fetch_slot_measurement_array(updated_selector_string, timeout)
finally:
self._session_function_lock.exit_read_lock()
return (
slot_average_power,
slot_burst_width,
slot_measurement_status,
slot_maximum_power,
slot_minimum_power,
slot_burst_threshold,
error_code,
)
[docs]
@_raise_if_disposed
def fetch_power_trace(self, selector_string, timeout, upper_mask, signal_power, lower_mask):
r"""Fetches the upper mask, signal power, and lower mask trace.
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. The default is "" (empty string).
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.
upper_mask (numpy.float32):
This parameter returns an array of upper mask values measured at each time instance.
signal_power (numpy.float32):
This parameter returns an array of upper mask values measured at each time instance.
lower_mask (numpy.float32):
This parameter returns an array of upper mask values measured at each time instance.
Returns:
Tuple (x0, dx, error_code):
x0 (float):
This parameter returns the start time, in seconds.
dx (float):
This parameter returns the sample duration, in seconds.
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.pvt_fetch_power_trace(
updated_selector_string, timeout, upper_mask, signal_power, lower_mask
)
finally:
self._session_function_lock.exit_read_lock()
return x0, dx, error_code
[docs]
@_raise_if_disposed
def fetch_maximum_power_trace(self, selector_string, timeout, maximum_signal_power):
r"""Fetches the maximum signal power trace.
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. The default is "" (empty string).
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.
maximum_signal_power (numpy.float32):
This parameter returns an array of signal power values measured at each time instance.
Returns:
Tuple (x0, dx, error_code):
x0 (float):
This parameter returns the start time, in seconds.
dx (float):
This parameter returns the sample duration, in seconds.
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.pvt_fetch_maximum_power_trace(
updated_selector_string, timeout, maximum_signal_power
)
finally:
self._session_function_lock.exit_read_lock()
return x0, dx, error_code
[docs]
@_raise_if_disposed
def fetch_minimum_power_trace(self, selector_string, timeout, minimum_signal_power):
r"""Fetches the minimum signal power trace.
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. The default is "" (empty string).
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.
minimum_signal_power (numpy.float32):
This parameter returns an array of signal power values measured at each time instance.
Returns:
Tuple (x0, dx, error_code):
x0 (float):
This parameter returns the start time, in seconds.
dx (float):
This parameter returns the sample duration, in seconds.
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.pvt_fetch_minimum_power_trace(
updated_selector_string, timeout, minimum_signal_power
)
finally:
self._session_function_lock.exit_read_lock()
return x0, dx, error_code