mpylab.device.receiver module¶

This is the mpylab.device.receiver module.

author:

Hans Georg Krauthäuser (main author)

license:

GPLv3 or higher

class mpylab.device.receiver.RECEIVER(SearchPaths=None)

Bases: DRIVER

Child class for all py-drivers for EMC receivers.

The parent class is mpylab.device.driver.DRIVER.

The configuration template for this device class is:

conftmpl={'description':
             {'description': str,
              'type': str,
              'vendor': str,
              'serialnr': str,
              'deviceid': str,
              'driver': str},
            'init_value':
                {'fstart': float,
                 'fstop': float,
                 'fstep': float,
                 'visa': str,
                 'virtual': strbool,
                 'nr_of_channels': int},
            'channel_%d':
                {'name': str,
                 'detector': str,
                 'attenuation': str,
                 'meas_time': str,
                 'min_attenuation': int,
                 'unit': str,
                 'preamplifier': str}}

The meaning is:

Section description
- description: string describing the instrument
- type: string with the instrument type (here: POWERMETER)
- vendor: string ddescribing the vendor/manufactor
- serialnr: string with a unique identification
- deviceid: string with an internal id
- driver: filename of the instrument driver (.py, .pyc, .pyd, .dll)
Section init_value
- fstart: lowest possible frequency in Hz of the device
- fstop: highest possible frequency in Hz of the device
- fstep: smallest frequency step in Hz of the device
- visa: VISA identifier
- virtual: 0, false or 1, true. Virtual device are usefull for testing and debugging.
- nr_of_channels: indicates how many channel sections follow
Section channel_%d (%d may be 1, 2, …)
- name: a string identifying the channel.
- detector: detector used fpr this channel
- unit: a string containing the unit of the returned power/voltage readings. However, scuq will ignore dB-settings, and the returned power/voltage will contain the unit anyway.
- meas_time: the measuring time for that channel, or auto
- attenuation: value of the attenuation, may be auto
- min_attenuation: value of the minimum attenuation
- detector: ‘PEAK’, ‘AVERAGE’, ‘QPEAK’
- preamplifier: ‘on’ or ‘off’

Parameters:: SearchPaths (sequence of path-like, optional) – Directories searched for device INI files and referenced data files.

GetAttenuation()

Read receiver attenuation.

Returns:: (status, attenuation) with the value in decibels.
Return type:: tuple

GetData()

Read one receiver level.

Returns:: (status, level) where level is a scuq.Quantity, or None if communication failed.
Return type:: tuple

GetDataNB(retrigger=False)

Read one level through the non-blocking driver interface.

The base implementation delegates to blocking GetData(). Concrete drivers may return (-1, None) while acquisition is still in progress.

Parameters:: retrigger (bool or str) – Trigger a new acquisition after a successful read when true or equal to "on".
Returns:: (status, level) where level is a scuq.Quantity when available.
Return type:: tuple

GetDetector()

Read the measurement detector.

Returns:: (status, detector) with PEAK, QPEAK, or AVERAGE.
Return type:: tuple
Raises:: UserWarning – If the device reports an unknown detector.

GetFreq()

Read the receiver frequency.

Returns:: (status, frequency) with the frequency in hertz.
Return type:: tuple

GetMeasTime()

Read receiver measurement time.

Returns:: (status, measurement_time) in seconds.
Return type:: tuple

GetMinAttenuation()

Read minimum receiver attenuation.

Returns:: (status, minimum_attenuation) in decibels.
Return type:: tuple

GetPreamplifier()

Read the preamplifier state.

Returns:: (status, preamplifier) with ON or OFF.
Return type:: tuple
Raises:: UserWarning – If the device reports an unknown state.

GetResolutionBandwidth()

Read resolution bandwidth.

Returns:: (status, bandwidth) with the value in hertz.
Return type:: tuple

IterScanFallback(start_freq=None, stop_freq=None, step_freq=None, detectors=None, rbw=None, meas_time=None, attenuation=None, min_attenuation=None, preamplifier=None, spacing='linear', cancel_callback=None, progress_callback=None, frequencies=None, hold_time=None, preselector=None)

Yield receiver scan points using SetFreq and GetData.

This fallback is intentionally synchronous. Non-blocking applications should run it in a worker thread and use cancel_callback to request a stop between frequency points. Each point contains the combined error status as well as separate frequency_error and data_error values. A rejected receiver setting raises ReceiverScanConfigurationError before acquisition starts.

Parameters:

start_freq (float, optional) – Scan bounds in hertz. Required unless frequencies is supplied.
stop_freq (float, optional) – Scan bounds in hertz. Required unless frequencies is supplied.
step_freq (float, optional) – Linear step in hertz or logarithmic ratio, depending on spacing.
detectors (str or sequence of str, optional) – Detector or detectors to scan. The current detector is used by default.
rbw (float or str, optional) – Resolution bandwidth passed to the receiver.
meas_time (float or str, optional) – Measurement or hold time passed to the receiver.
attenuation (float or str, optional) – Receiver attenuation setting.
min_attenuation (float, optional) – Minimum receiver attenuation in decibels.
preamplifier (str or bool, optional) – Receiver preamplifier setting.
spacing ({"linear", "log"}, optional) – Frequency-spacing mode.
cancel_callback (callable, optional) – Zero-argument predicate checked between scan points.
progress_callback (callable, optional) – Callback receiving each point dictionary after acquisition.
frequencies (sequence of float, optional) – Explicit, strictly increasing frequency sequence in hertz. It takes precedence over scan bounds and step.
hold_time (float or str, optional) – Backward-compatible alias for meas_time.
preselector (object, optional) – Optional preselector setting.

Yields:

dict – One point containing frequency, detector, value, status fields, progress indices, and source="fallback".

RunScan(start_freq=None, stop_freq=None, step_freq=None, detectors=None, rbw=None, meas_time=None, attenuation=None, min_attenuation=None, preamplifier=None, spacing='linear', cancel_callback=None, progress_callback=None, frequencies=None, hold_time=None, preselector=None)

Run a receiver scan and return accumulated detector data.

The base implementation uses the slow but widely supported fallback path SetFreq + GetData. Per-point device status errors are retained in the result while acquisition continues. Rejected scan settings raise ReceiverScanConfigurationError. Device drivers may override this method with a hardware-native scan and keep this result shape.

Parameters:

start_freq (float, optional) – Scan bounds in hertz. Required unless frequencies is supplied.
stop_freq (float, optional) – Scan bounds in hertz. Required unless frequencies is supplied.
step_freq (float, optional) – Linear step in hertz or logarithmic ratio, depending on spacing.
detectors (str or sequence of str, optional) – Detector or detectors to scan. The current detector is used by default.
rbw (float or str, optional) – Resolution bandwidth passed to the receiver.
meas_time (float or str, optional) – Measurement or hold time passed to the receiver.
attenuation (float or str, optional) – Receiver attenuation setting.
min_attenuation (float, optional) – Minimum receiver attenuation in decibels.
preamplifier (str or bool, optional) – Receiver preamplifier setting.
spacing ({"linear", "log"}, optional) – Frequency-spacing mode.
cancel_callback (callable, optional) – Zero-argument predicate checked between scan points.
progress_callback (callable, optional) – Callback receiving each point dictionary after acquisition.
frequencies (sequence of float, optional) – Explicit, strictly increasing frequency sequence in hertz. It takes precedence over scan bounds and step.
hold_time (float or str, optional) – Backward-compatible alias for meas_time. If both are given, their numeric values must agree.
preselector (object, optional) – Preselector setting for receivers exposing SetPreselector. Unsupported receivers reject this setting explicitly.

Returns:

(status, result). result contains immutable frequencies, detector-indexed data and errors, settings, completion state, and scan source. Status is -1 if any point failed, otherwise zero.

Return type:

tuple

SetAttenuation(attenuation)

Set and read back receiver attenuation.

The requested value is limited to at least min_attenuation.

Parameters:: attenuation (float) – Requested attenuation in decibels.
Returns:: (status, attenuation) with the read-back value in decibels.
Return type:: tuple

SetCisprRbwScanFrequencies(frequencies=None, terminal_boundary_policy='previous')

Set optional frequency context for software-selected CISPR RBW.

Passing None clears the context. Drivers that select CISPR RBW in software may use this context to keep a final band-boundary frequency in the previous RBW band.

Parameters:

frequencies (sequence of float, optional) – Complete scan-frequency sequence in hertz, or None to clear the context.
terminal_boundary_policy ({"previous", "strict"}, optional) – Keep a final boundary point in the preceding CISPR band or apply the strict band boundary.

Returns:

(0, frequencies) with an immutable frequency tuple, or (0, None) when clearing the context.

Return type:

tuple

SetDetector(detector)

Set and read back the measurement detector.

Parameters:: detector ({"PEAK", "QPEAK", "AVERAGE"}) – Detector name, matched case-insensitively.
Returns:: (status, detector) with the canonical detector name.
Return type:: tuple
Raises:: UserWarning – If the detector is unsupported.

SetFreq(freq)

Set and read back the receiver frequency.

Parameters:: freq (float) – Requested frequency in hertz.
Returns:: (status, frequency) with the read-back frequency in hertz.
Return type:: tuple
Raises:: ValueError – If freq is not finite and positive. Validation happens before any instrument command is sent.

SetMeasTime(meas_time)

Set and read back receiver measurement time.

Negative values are clamped to zero.

Parameters:: meas_time (float) – Requested measurement time in seconds.
Returns:: (status, measurement_time) in seconds.
Return type:: tuple

SetMinAttenuation(min_attenuation)

Set and read back minimum receiver attenuation.

Negative values are clamped to zero.

Parameters:: min_attenuation (float) – Requested minimum attenuation in decibels.
Returns:: (status, minimum_attenuation) in decibels.
Return type:: tuple

SetPreamplifier(preamplifier)

Set and read back the preamplifier state.

Parameters:: preamplifier ({"ON", "OFF"}) – Requested state, matched case-insensitively.
Returns:: (status, preamplifier) with the canonical state.
Return type:: tuple
Raises:: UserWarning – If the requested state is invalid.

SetResolutionBandwidth(rbw)

Set and read back resolution bandwidth.

Parameters:: rbw (float) – Requested resolution bandwidth in hertz.
Returns:: (status, bandwidth) with the read-back value in hertz.
Return type:: tuple

SupportsHardwareScan()

Report support for a device-native scan.

Returns:: (0, False) for the software fallback implementation.
Return type:: tuple

SupportsScan()

Report support for the generic scan API.

Returns:: (0, True) for the base receiver implementation.
Return type:: tuple

Trigger()

Trigger a single measurement.

Returns:: Device status; zero indicates success.
Return type:: int

conftmpl = {'channel_%d': {'attenuation': <class 'str'>, 'detector': <class 'str'>, 'meas_time': <class 'str'>, 'min_attenuation': <class 'int'>, 'name': <class 'str'>, 'preamplifier': <class 'str'>, 'rbw': <class 'str'>, 'unit': <class 'str'>}, 'description': {'description': <class 'str'>, 'deviceid': <class 'str'>, 'driver': <class 'str'>, 'serialnr': <class 'str'>, 'type': <class 'str'>, 'vendor': <class 'str'>}, 'init_value': {'fstart': <class 'float'>, 'fstep': <class 'float'>, 'fstop': <class 'float'>, 'nr_of_channels': <class 'int'>, 'virtual': <function strbool>, 'visa': <class 'str'>}}

update_internal_unit(ch=None, unit='DBUV')

Select the internal unit used to interpret receiver readings.

Parameters:

ch (int, optional) – Channel number for multichannel devices, starting at one. The active channel is used when omitted.
unit (str, optional) – Device-side unit, for example W, DB, DBM, or DBUV.
posibilities:: (The table shows the) – Unit SCPI notation Watt W dB DB dBm DBM dBuV DBUV

exception mpylab.device.receiver.ReceiverScanConfigurationError

Bases: RuntimeError

Raised when a receiver rejects a requested scan setting.

mpylab.device.receiver module¶

Previous topic

Next topic

This Page