Driver framework¶

All Python instrument drivers derive directly or indirectly from DRIVER. A concrete driver translates the common device API into protocol commands and declares the unit used by the instrument. Unit conversion is delegated to mpylab.tools.uconv.

Common base class¶

class mpylab.device.driver.DRIVER(SearchPaths=None)¶

Base class for Python device drivers.

Parameters:: SearchPaths (sequence of path-like, optional) – Directories searched for referenced configuration and data files. The current working directory is used by default.

Notes

Beside the common API method for all drivers (see below) this class also implements the following low level methods:

write(cmd)¶

Write a command to the instrument.

Parameters:

cmd (string) – the command

Return type:

status code of the native write operation

read(tmpl)¶

Read an answer from the instrument instrument.

Parameters:

tmpl (valid regular expression string) – a template string

Return type:

the groupdict of the match

Example:

If a device (signal generator in this case) returns :MODULATION:AM:INTERNAL 80 PCT to indicate a AM modulation depth of 80%, a template string of :MODULATION:AM:INTERNAL (?P<depth>\d+) PCT will results in a return dict of {"depth": 80}.

query(cmd, tmpl)¶

Write a command to the instrument and read the answer.

Parameters:

cmd (string) – the command

tmpl (valid regular expression string) – a template string

Return type:

the groupdict of the match

For other low level operation you may use the device stored in self.dev directly.

GetDescription()¶

Return the configured description and instrument identification.

Returns:: Driver status code and a description combining the INI description with IDN obtained during initialization.
Return type:: tuple[int, str]

Init(ini=None, channel=None, ignore_bus=None)¶

Initialize the instrument from an INI configuration.

Parameters:

ini (path-like, file-like, or None, optional) – Initialization data handled by mpylab.tools.configuration.Configuration using the driver’s conftmpl. A false value selects virtual operation.
channel (int or None, optional) – One-based channel number for multichannel devices.
ignore_bus (bool or None, optional) – Load configuration without creating a communication bus. None selects the driver-specific default policy.

Returns:

Driver status code; zero indicates success.

Return type:

int

Quit()¶

Shut down the instrument driver.

Returns:: Driver status code; zero indicates success.
Return type:: int

Instrument-family contracts¶

class mpylab.device.signalgenerator.SIGNALGENERATOR(SearchPaths=None)¶

Base class for signal-generator drivers.

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

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

AMOff()¶

Switch amplitude modulation off.

Returns:: (status, 0).
Return type:: tuple of int

AMOn()¶

Switch amplitude modulation on.

Returns:: (status, 0).
Return type:: tuple of int

ConfAM(source, freq, depth, waveform, LFOut)¶

Configure amplitude modulation.

Parameters:

source (str) – Modulation source, selected from AM_sources.
freq (float) – Modulation frequency in hertz.
depth (float) – Linear modulation depth from zero to one.
waveform (str) – Modulation waveform, selected from AM_waveforms.
LFOut (str) – Low-frequency output state, "ON" or "OFF".

Returns:

Device status; zero indicates success.

Return type:

int

Raises:

ValueError – If frequency or modulation depth is outside its valid range.

ConfPM(source, freq, pol, width, delay)¶

Configure pulse modulation.

Parameters:

source (str) – Modulation source, selected from PM_sources.
freq (float) – Pulse repetition frequency in hertz.
pol (str) – Pulse polarity, selected from PM_pol.
width (float) – Pulse width in the unit expected by the concrete driver.
delay (float) – Pulse delay in the unit expected by the concrete driver.

Returns:

Device status; zero indicates success.

Return type:

int

Raises:

ValueError – If frequency, width, or delay is outside its valid range.

GetFreq()¶

Read the RF output frequency.

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

GetLevel()¶

Read the RF output level.

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

PMOff()¶

Switch pulse modulation off.

Returns:: (status, 0).
Return type:: tuple of int

PMOn()¶

Switch pulse modulation on.

Returns:: (status, 0).
Return type:: tuple of int

RFOff()¶

Switch the RF output off.

Returns:: (status, 0).
Return type:: tuple of int

RFOn()¶

Switch the RF output on.

Returns:: (status, 0).
Return type:: tuple of int

SetAM(state)¶

Set the amplitude-modulation state.

Parameters:: state (str or bool-like) – "on" enables AM; every other value disables it.
Returns:: (status, 0).
Return type:: tuple of int

SetFreq(freq)¶

Set and read back the RF output 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.

SetLevel(lv)¶

Set and read back the RF output level.

Parameters:

lv (scuq.Quantity) – Requested power or voltage level. Conversion between voltage and power assumes 50 ohms when required by the device’s internal unit. For a complex scalar quantity, its magnitude is used.

Returns:

(status, level) where level is a scuq.Quantity, or None if communication failed.

Return type:

tuple

Raises:

TypeError – If lv is not a scuq.Quantity.
ValueError – If the quantity is non-scalar, non-finite, or incompatible with the device’s internal unit. Validation happens before any instrument command is sent.

SetPM(state)¶

Set the pulse-modulation state.

Parameters:: state (str or bool-like) – "on" enables PM; every other value disables it.
Returns:: (status, 0).
Return type:: tuple of int

SetState(state)¶

Set the RF output state.

Parameters:: state (str or bool-like) – "on" enables the output; every other value disables it.
Returns:: (status, 0).
Return type:: tuple of int

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

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

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

class mpylab.device.powermeter.POWERMETER(SearchPaths=None)¶

Child class for all py-drivers for power meters.

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,
                 'gpib': int,
                 'virtual': strbool,
                 'nr_of_channels': int},
            'channel_%d':
                {'name': str,
                 'filter': int,
                 'unit': str,
                 'resolution': int,
                 'rangemode': str,
                 'manrange': float,
                 'swr1': float,
                 'swr2': float,
                 'sensor': str,
                 'interpolation': str,
                 'file': _file_source}}

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
- gpib: GPIB address of the device
- 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.
- filter: device specific integer specifying the filter used
- unit: a string containing the unit of the returned power readings. However, scuq will ignore dB-settings, and the returned power will contain the unit anyway.
- resolution: device specific integer giving the resolutuion of the returned power
- rangemode: ‘auto’, ‘autoonce’, or ‘manual’
- manrange: fload specifiing the range in manual range mode
- swr: VSWR of the measured two port. May be used in uncertainty calculations
- sensor: string specifying the used power sensor. May be used in uncertainty calculations.

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

GetData()¶

Read one power value including mismatch uncertainty.

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

GetDataNB(retrigger=False)¶

Read power through the non-blocking driver interface.

The base implementation delegates to blocking GetData().

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

GetFreq()¶

Read the sensor correction frequency.

Returns:: (status, frequency) with the value in hertz, or None when unavailable.
Return type:: tuple

GetSafetyLimit(what)¶

Return a named safety limit at the current frequency.

Parameters:: what (str) – Limit-channel name, for example MAXIN.
Returns:: (0, limit) with an interpolated scuq.Quantity, or (-1, None) if the limit or current frequency is unavailable.
Return type:: tuple

Init(ini=None, channel=None, ignore_bus=None)¶

Initialize the power meter and its optional safety limits.

Parameters:

ini (path-like or file-like, optional) – Device configuration source.
channel (int or str, optional) – Initial measurement channel.
ignore_bus (bool or None, optional) – Bus policy. None selects normal hardware communication.

Returns:

Device status; zero indicates success.

Return type:

int

SetFreq(freq)¶

Set and read back the sensor correction frequency.

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

Trigger()¶

Trigger a single power measurement.

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

Zero(state='on')¶

Set the power-meter zero-correction state.

Parameters:: state (str or bool-like, optional) – "on" enables zero correction; every other value disables it.
Returns:: (status, 0).
Return type:: tuple of int

get_standard_mismatch_uncertainty()¶

Calculate relative standard uncertainty caused by mismatch.

swr1 and swr2 are read from the active channel configuration. The result is on a linear relative scale. An expanded uncertainty is obtained by applying the desired coverage factor.

Returns:: Relative standard uncertainty for a U-shaped phase distribution.
Return type:: float
Raises:: ValueError – If either configured VSWR is non-finite or smaller than one.

update_internal_unit(ch=None, unit=None)¶

Select the internal unit used to interpret power readings.

Parameters:

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

class mpylab.device.fieldprobe.FIELDPROBE(SearchPaths=None)¶

Base class for field-probe drivers.

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

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

GetBatteryState()¶

Read the probe battery state.

Returns:: (status, battery_state) with a driver-defined numeric relative value, or None when unavailable.
Return type:: tuple

GetData()¶

Read one field-probe data record.

Returns:: (status, data). The concrete driver defines the data record, typically a sequence of three scuq.Quantity components.
Return type:: tuple

GetDataNB(retrigger=False)¶

Read data through the non-blocking-compatible probe interface.

The base implementation is a blocking fallback which calls GetData(). Drivers with asynchronous hardware may override it while preserving the same return structure and retrigger semantics.

Parameters:: retrigger (bool or str, optional) – Request a new trigger after reading when true or equal to "on".
Returns:: (status, data). A concrete driver may indicate that data is not yet available through its status value.
Return type:: tuple

GetFreq()¶

Read the measurement frequency.

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

GetWaveform()¶

Return the base-class marker for unsupported waveform acquisition.

Returns:: (-1, None, None, None, None). Drivers supporting waveforms may override this method with their documented data contract.
Return type:: tuple

SetFreq(freq)¶

Set and read back the measurement frequency.

Parameters:: freq (float) – Requested frequency in hertz.
Returns:: (status, frequency) with the confirmed value in hertz.
Return type:: tuple

Trigger()¶

Trigger one measurement cycle.

Returns:: (status, 0).
Return type:: tuple of int

Zero(state='on')¶

Enable or disable probe zeroing.

Parameters:: state (str or bool-like, optional) – "on" enables zeroing; every other value disables it.
Returns:: (status, state) with canonical "on" or "off".
Return type:: tuple

class mpylab.device.amplifier.AMPLIFIER(SearchPaths=None)¶

Child class for all py-drivers for amplifiers The parent class is NPORT

This class is to be used for all passive amplifiers (no remote control). The class adds the methods ‘Operate’, ‘Standby’, ‘Pon’, ‘POff’ and ‘SetState’ to NPORT to complete the AMPLIFIER API.

The class is base class for all drivers of remote controlled amplifies.

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

GetState()¶

Return the last successfully requested amplifier state.

Returns:: (0, state) with the cached canonical state.
Return type:: tuple

Init(ini=None, channel=None, ignore_bus=None)¶

Initialize NPORT data and optional amplifier communication.

Parameters:

ini (path-like or file-like, optional) – Device configuration source.
channel (int or str, optional) – Initial logical channel.
ignore_bus (bool or None, optional) – Bus policy. None selects the active amplifier default and initializes communication. Passive or virtual amplifier drivers may override that class default.

Returns:

Device status; zero indicates success.

Return type:

int

Operate()¶

Switch to the Operate state.

Returns:: Device status returned by SetState().
Return type:: int

POff()¶

Switch to the POff state.

Returns:: Device status returned by SetState().
Return type:: int

POn()¶

Switch to the POn state.

Returns:: Device status returned by SetState().
Return type:: int

Quit()¶

Power off and close the driver.

Returns:: Bitwise combination of shutdown and base-driver errors.
Return type:: int

SetState(state)¶

Set the remotely controlled amplifier state.

Parameters:: state (str) – State matching Operate, Standby, POn, or POff. Close spellings are normalized by fuzzy matching.
Returns:: Device status; zero indicates success.
Return type:: int

Standby()¶

Switch to the Standby state.

Returns:: Device status returned by SetState().
Return type:: int

class mpylab.device.nport.NPORT(SearchPaths=None)¶

Base class for passive frequency-dependent n-port models.

Channels such as S-parameters, antenna factors, or insertion losses are loaded from DAT data and interpolated at the frequency selected through SetFreq().

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

GetChannels()¶

Return available data-channel names.

Returns:: (0, channels) with an immutable sequence of names.
Return type:: tuple

GetData(what)¶

Return an interpolated channel value at the current frequency.

Parameters:: what (str) – Channel name. Matching ignores case and spaces.
Returns:: (status, value) where value is normally a scuq.Quantity; (-1, None) indicates an unknown channel or an unset frequency.
Return type:: tuple

GetDescription()¶

Return the configured device description.

Returns:: (0, description).
Return type:: tuple

GetFreq()¶

Return the interpolation frequency.

Returns:: (0, frequency) with a value in hertz, or None before the first call to SetFreq().
Return type:: tuple

GetVirtual()¶

Return the runtime virtual-mode flag.

Returns:: (0, virtual).
Return type:: tuple

Init(ini=None, channel=None, ignore_bus=None)¶

Load channel datasets and initialize their interpolators.

Parameters:

ini (path-like or file-like) – NPORT configuration source.
channel (int or str, optional) – Initial logical channel passed to the base driver.
ignore_bus (bool or None, optional) – Skip communication-bus initialization. None selects the passive NPORT default of True.

Returns:

Device status; zero indicates success.

Return type:

int

Quit()¶

Close the passive driver state.

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

SetFreq(freq)¶

Set the interpolation frequency.

Parameters:: freq (float) – Frequency in hertz; it must be finite and non-negative.
Returns:: (0, frequency).
Return type:: tuple

SetVirtual(virtual)¶

Set the runtime virtual-mode flag.

Parameters:: virtual (bool) – Requested virtual-mode state.
Returns:: Device status; zero indicates success.
Return type:: int

class mpylab.device.networkanalyzer.NETWORKANALYZER(SearchPaths=None)¶

Parent class of all py-drivers for networkanalyzer analyzers.

This Driver use the new dirver framework!

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,
             'gpib': int,
             'visa': str,
             'nr_of_channels': int,
             'virtual': strbool},
        'channel_%d':
            {'unit': str,
             'SetRefLevel': float,
             'SetRBW': float,
             'SetSpan': float,
             'CreateWindow': str,
             'CreateTrace': str,
             'SetSweepCount': int,
             'SetSweepPoints': int,
             'SetSweepType': 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
- gpib: GPIB address of the device
- virtual: 0, false or 1, true. Virtual device are usefull for testing and debugging.
Section channel_%d
- unit:
- SetRefLevel: Reference Level (for further information see function description)
- SetRBW: Resolution Bandwidth (for further information see function description)
- SetSpan: Span of Device (for further information see function description)
- CreateWindow: Name of the first Window (for further information see function description)
- CreateTrace: Name of the first Trace (for further information see function description)
- SetSweepCount: Sets the number of sweeps to be measured in single sweep mode. (for further information see function description)
- SetSweepPoints: Sweep Points (for further information see function description)
- SetSweepType: Sweep Type (for further information see function description)

The _commands dictionary:

_commands defines functions that should be available in concrete driver implementations derived from this class.

Convention example:

_commands={"function_name": {'parameter': tuple_of_parameter_names_or_None,
                             'returntype': python_type_or_r_type},
            ...}

Historical note: r_types and Meta_Driver are archived under mpylab.device.legacy and are not used by active drivers. See also mpylab.device.legacy.meta_driver.Meta_Driver.

Possibility lists: Possibilities define valid values for specific parameters. For example, sparam is restricted to values like ('S11', 'S12', 'S21', 'S22'). A fuzzy string compare may map small typos to known valid entries.

Possibility lists can be defined in a concrete driver class or in a base class. Defining them in shared base classes is recommended so valid values remain consistent across drivers.

Methods:

SetCenterFreq(cfreq):

Set the CenterFreq of the Device.

Parameters:: cfreq (float) – CenterFreq for the device
Returns:: CenterFreq which is set on the Device after the set command
Return type:: float

GetCenterFreq():

Get the CenterFreq of the Device

Returns:: CenterFreq which is set on the Device
Return type:: float

SetSpan(span):

Set the Span of the Device.

Defines the width of the measurement and display range for a frequency sweep.

Parameters:: span (float) – Span in Hz
Returns:: Span which is set on the Device after the set command
Return type:: float

GetSpan():

Get the Span of the Device

Returns:: Span which is set on the Device
Return type:: float

SetStartFreq(stfreq):

Set the Start Frequency of the Device

Parameters:: stfreq (float) – Start Frequency of the Device
Returns:: Start Frequency which is set on the Device after the set command
Return type:: float

GetStartFreq():

Get the Start Frequency of the Device

Returns:: Start Frequency which is set on the Device after the set command
Return type:: float

SetStopFreq(spfreq):

Set the Stop Frequency of the Device

Parameters:: spfreq (float) – Stop Frequency of the Device
Returns:: Stop Frequency which is set on the Device after the set command
Return type:: float

GetStopFreq():

Get the Stop Frequency of the Device

Returns:: Stop Frequency which is set on the Device
Return type:: float

SetRBW(rbw):

Set the Resolution Bandwidth of the Device

Parameters:: rbw (float) – Resolution Bandwidth of the Device
Returns:: Resolution Bandwidth which is set on the Device after the set command
Return type:: float

GetRBW():

Get the Resolution Bandwidth of the Device

Returns:: Resolution Bandwidth which is set on the Device
Return type:: float

SetRefLevel(reflevel):

Set the Reference Level of the currently active Trace.

Parameters:: reflevel (float) – Reference Level of the Device
Returns:: Reference Level which is set on the Device after the set command
Return type:: float

GetRefLevel():

Get the Reference Level of the currently active Trace.

Returns:: Reference Level which is set on the Device
Return type:: float

SetDivisionValue(divivalue):

Sets the value between two grid graticules (value per division) for the diagram area.

Parameters:: divivalue (float) – Division Value of the Device
Returns:: Division Value which is set on the Device after the set command
Return type:: float

GetDivisionValue():

Gets the value between two grid graticules (value per division) for the diagram area.

Returns:: Division Value which is set on the Device
Return type:: float

CreateTrace(tracename, sparam):

Creates a Trace and assigns the given name to it.

Parameters:

tracename (String) – Name of the new Trace
sparam (String) – S-parameter as String; (‘S11’, ‘S12’, ‘S21’, ‘S22’)

Returns:

Name of the new Trace

Return type:

String

DelTrace(traceName):

Deletes a trace with a specified trace name.

Parameters:: traceName (String) – Name of the Trace which should deleted
Return type:: None

SetTrace(traceName):

Selects an existing trace as the active trace.

Parameters:: traceName (String) – Name of the trace which should be selected.
Returns:: Name of the currently active Trace after the set command
Return type:: String

GetTrace():

Gets the Name of the currently active Trace

Returns:: Name of the currently active Trace
Return type:: String

SetSparameter(sparam):

Assigns the s-parameter to the currently active Trace.

See also SetTrace()

Parameters:: sparam (String) – S-parameter as String; (‘S11’, ‘S12’, ‘S21’, ‘S22’)
Returns:: S-parameter of the currently active Trace which is set on the Device after the set command
Return type:: String

GetTrace():

Gets s-parameter of the currently active Trace.

See also SetTrace()

Returns:: S-parameter of the currently active Trace which is set on the Device
Return type:: String

SetChannel(chan):

Sets the Channel Number of the Device

Parameters:: chan (Integer) – Number of the Channel
Returns:: Channel Number of the Device after the set command
Return type:: Integer

GetChannel():

Gets the Channel Number of the Device

Returns:: Channel Number of the Device
Return type:: Integer

SetSweepType(sweepType):

Selects the sweep type and the position of the sweep points across the sweep range.

Parameters:: sweepType (String) – sweep type as String (‘LINEAR’,’LOGARITHMIC’)
Returns:: sweep type which is set on the device after the set command
Return type:: String

GetSweepType():

Selects the sweep type and the position of the sweep points across the sweep range.

Returns:: sweep type which is set on the Device
Return type:: String

SetSweepCount(sweepCount):

Sets the number of sweeps to be measured in single sweep mode.

Parameters:: sweepCount (Integer) – Reference Level of the Device
Returns:: Sweep Count which is set on the Device after the set command
Return type:: Integer

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

class mpylab.device.spectrumanalyzer.SPECTRUMANALYZER(SearchPaths=None)¶

Base class for spectrum-analyzer drivers.

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

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

GetAtt()¶

Read the analyzer att setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetAttMode()¶

Read the analyzer attmode setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetCenterFreq()¶

Read the analyzer cfreq setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetDetector()¶

Read the analyzer det setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetPreAmp()¶

Read the analyzer preamp setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetRBW()¶

Read the analyzer rbw setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetRefLevel()¶

Read the analyzer reflevel setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetSpan()¶

Read the analyzer span setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetSpectrum()¶

Acquire one spectrum trace.

Returns:: (status, (frequencies, levels)). Frequencies are numeric values in hertz and levels use the configured analyzer level unit.
Return type:: tuple

GetSpectrumNB()¶

Acquire a spectrum through the non-blocking-compatible API.

The generic fallback is synchronous and delegates to GetSpectrum(). Hardware drivers may override it when they offer genuinely asynchronous acquisition.

GetStartFreq()¶

Read the analyzer stfreq setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetStopFreq()¶

Read the analyzer spfreq setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetSweepCount()¶

Read the analyzer scount setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetSweepPoints()¶

Read the analyzer spoints setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetSweepTime()¶

Read the analyzer stime setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetTrace()¶

Read the analyzer trace setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetTraceMode()¶

Read the analyzer tmode setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetTriggerDelay()¶

Read the analyzer tdelay setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetTriggerMode()¶

Read the analyzer trgmode setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

GetVBW()¶

Read the analyzer vbw setting.

Returns:: (status, value) with the current setting.
Return type:: tuple

SetAtt(value)¶

Set and read back the analyzer att setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetAttAuto()¶

Enable automatic input attenuation.

Returns:: (status, attenuation) with the read-back setting.
Return type:: tuple

SetAttMode(value)¶

Set and read back the analyzer attmode setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetCenterFreq(value)¶

Set and read back the analyzer cfreq setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetDetector(value)¶

Set and read back the analyzer det setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetPreAmp(value)¶

Set and read back the analyzer preamp setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetRBW(value)¶

Set and read back the analyzer rbw setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetRefLevel(value)¶

Set and read back the analyzer reflevel setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetSpan(value)¶

Set and read back the analyzer span setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetStartFreq(value)¶

Set and read back the analyzer stfreq setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetStopFreq(value)¶

Set and read back the analyzer spfreq setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetSweepCount(value)¶

Set and read back the analyzer scount setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetSweepPoints(value)¶

Set and read back the analyzer spoints setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetSweepTime(value)¶

Set and read back the analyzer stime setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetTrace(value)¶

Set and read back the analyzer trace setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetTraceMode(value)¶

Set and read back the analyzer tmode setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetTriggerDelay(value)¶

Set and read back the analyzer tdelay setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetTriggerMode(value)¶

Set and read back the analyzer trgmode setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

SetVBW(value)¶

Set and read back the analyzer vbw setting.

Parameters:: value (object) – Requested setting. Numeric units follow the corresponding analyzer method name and configuration field.
Returns:: (status, value) with the read-back setting.
Return type:: tuple

class mpylab.device.motorcontroller.MOTORCONTROLLER(SearchPaths=None)¶

Base class for motor-controller drivers.

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

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

GetSpeed()¶

Read angular speed.

Returns:: (status, speed) in degrees per second.
Return type:: tuple

GetState()¶

Read position and movement direction.

Returns:: (status, position_deg, direction) where direction is driver-defined, commonly -1, 0, or 1.
Return type:: tuple

Goto(pos)¶

Move to an absolute angular position.

Parameters:: pos (float) – Target position in degrees.
Returns:: (status, position) with the read-back position in degrees.
Return type:: tuple

Move(direction)¶

Start or stop continuous movement.

Parameters:: direction ({-1, 0, 1}) – Negative or positive movement direction; zero stops motion.
Returns:: (status, direction).
Return type:: tuple

SetSpeed(speed)¶

Set and read back angular speed.

Parameters:: speed (float) – Non-negative angular speed in degrees per second.
Returns:: (status, speed) in degrees per second.
Return type:: tuple

class mpylab.device.lisn.LISN(SearchPaths=None)¶

Base class for line impedance stabilization network drivers.

Concrete V- and T-type devices derive from VLISN and TLISN, respectively.

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

GetChannels()¶

Return available correction-data channel names.

Returns:: (0, channels) with an immutable sequence of names.
Return type:: tuple

GetData(what)¶

Return interpolated correction data at the current frequency.

Parameters:: what (str) – Channel name. Matching ignores case and spaces.
Returns:: (status, value); (-1, None) indicates an unknown channel or an unset frequency.
Return type:: tuple

GetDescription()¶

Return the configured device description.

Returns:: (0, description).
Return type:: tuple

GetFilter()¶

Return the internal filter-state flag.

Returns:: (0, filter_enabled).
Return type:: tuple

GetFreq()¶

Return the interpolation frequency.

Returns:: (0, frequency) with a value in hertz, or None before the first call to SetFreq().
Return type:: tuple

GetPath()¶

Return the selected LISN conductor path.

Returns:: (0, path).
Return type:: tuple

GetVirtual()¶

Return the runtime virtual-mode flag.

Returns:: (0, virtual).
Return type:: tuple

Init(ini=None, channel=None, ignore_bus=None)¶

Initialize LISN state and load correction-data channels.

Parameters:

ini (path-like or file-like) – LISN configuration source.
channel (int or str, optional) – Initial logical channel passed to the base driver.
ignore_bus (bool or None, optional) – Skip communication-bus initialization. None selects the passive LISN default of True.

Returns:

Device status; zero indicates success.

Return type:

int

Quit()¶

Close the LISN driver state.

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

SetFilter(state)¶

Set the internal filter-state flag.

Parameters:: state (bool or str) – Value accepted by mpylab.tools.configuration.strbool().
Returns:: (0, filter_enabled).
Return type:: tuple

SetFreq(freq)¶

Set the interpolation frequency.

Parameters:: freq (float) – Frequency in hertz; it must be finite and non-negative.
Returns:: (0, frequency).
Return type:: tuple

SetVirtual(virtual)¶

Set the runtime virtual-mode flag.

Parameters:: virtual (bool or str) – Value accepted by mpylab.tools.configuration.strbool().
Returns:: Device status; zero indicates success.
Return type:: int

These classes define family-specific behavior and defaults. Applications normally select a concrete driver through an INI file instead of importing it directly.

The multichannel driver guide documents shared controllers, channel facades, acquisition modes, and the supported concrete power-meter and field-probe drivers.

Driver framework¶

Common base class¶

Instrument-family contracts¶

Table of Contents

Previous topic

Next topic

This Page