Scope

The ScopeModule class serves to interact with Scope modules, providing the ability to:

  • Configure a scope module (set window size, create plots, and add variables)

  • Set up a trigger-based data acquisition

  • Apply a predefined sequence of values to a variable using the transient generator

  • Export acquired data in .mat or .csv format

Note

To retrieve an existing Scope module from an active project rather than creating a new one, refer to the code examples on the Module base class page.

Trigger-based acquisition and data export

The following example demonstrates how to configure the Scope to capture data based on a defined trigger condition. It arms the acquisition, applies a reference step which activates the trigger, and exports the resulting data to a file.

from imperix import ModuleType, TriggerEdge

# Create and configure a Scope module
scope = project.modules.create(ModuleType.SCOPE)
scope.add_variables(["Iout_ref", "Iout_meas"])
scope.set_window(window_ms=100.0)

# Configure the trigger
scope.set_trigger(
    signal="Iout_ref",
    edge=TriggerEdge.RISING,
    level=3.0,
    position_ms=50.0,
)

project.enable_pwm()

project.variables["Iout_ref"] = 1.0

# Arm the Scope module
scope.play()

# Wait for the pre-trigger buffer to fill up
cockpit.wait(delay_ms=100)

# Apply a current reference step
project.variables["Iout_ref"] = 5.0

# Wait for the acquisition to finish
cockpit.wait_until(scope.is_capture_done)

project.variables["Iout_ref"] = 0.0
project.disable_pwm()

# Export the data in MAT format
scope.export("C:/imperix/captures/scope_data.mat")

Using the transient generator

This example shows how to use the transient generator to apply a predefined sequence of values to a variable and acquire the resulting acquisition.

from imperix import ModuleType

# Create and configure a Scope module
scope = project.modules.create(ModuleType.SCOPE)
scope.add_variables(["Iout_ref", "Iout_meas"])
scope.set_window(window_ms=100.0)

# Configure the transient generator
scope.set_transient(
    variable="Iout_ref",
    positions_ms=[30.0, 70.0],
    values=[5.0, 2.0],
)

project.enable_pwm()

project.variables["Iout_ref"] = 1.0

scope.fire_transient()

# Wait for the acquisition to finish
cockpit.wait_until(scope.is_capture_done)

project.variables["Iout_ref"] = 0.0
project.disable_pwm()

# Export the data in MAT format
scope.export("C:/imperix/captures/scope_data.mat")

API Reference

class imperix.ScopeModule(cockpit: Cockpit, data: dict[str, Any])
export(path: str | PathLike[str], *, plot: int = 0, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Export acquired data from one plot to a CSV or MAT file.

Parameters:

  • path – Absolute path where the file will be written, as a string or Path. The file extension selects the export format. The supported extensions are .csv and .mat.

  • plot – Index of the plot to export. Defaults to 0 (the first plot).

  • timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot export the acquired data.

Example:

scope.export("C:/imperix/captures/scope_data.csv")
stop(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Stops the acquisition.

Parameters:

timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If the acquisition cannot be stopped.

add_plot(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → int

Creates a new plot.

Parameters:

timeout – Maximum time to wait for a response in seconds.

Returns:

The index of the newly created plot.

Raises:

InvalidStateError – If Cockpit cannot create the plot.

Example:

# Add variables to the first plot
scope.add_variables(["Va", "Vb", "Vc])

# Create and add variables to a second plot
current_plot = scope.add_plot()
scope.add_variables(["Ia", "Ib", "Ic"], plot=current_plot)
remove_plot(plot: int, *, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Deletes a plot.

Parameters:

  • plot – index of the plot to remove.

  • timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If this is the only remaining plot or Cockpit cannot remove it.

plot_count(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → int

Returns the current number of plots.

Parameters:

timeout – Maximum time to wait for a response in seconds.

Returns:

Number of plots in the scope.

list_variables(*, plot: int = 0, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → Any

Returns the list of variables in a plot.

Parameters:

  • plot – plot index. Defaults to 0.

  • timeout – Maximum time to wait for a response in seconds.

Returns:

A list of variable names on the given plot.

Example::

print(scope.list_variables(plot=0))

add_variables(names: Sequence[str], *, plot: int = 0, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Adds variables by name.

Parameters:

  • names – Name(s) of the variables to add.

  • plot – plot index to add them to. Defaults to 0 (the first plot).

  • timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot add the variables.

Example::

scope.add_variables([“Va”, “Vb”, “Vc”])

remove_variables(names: Sequence[str], *, plot: int = 0, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Removes variables from this scope by name.

Parameters:

  • names – Name(s) of the variables to remove.

  • plot – plot index to add them to. Defaults to 0 (the first plot).

  • timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot remove the variables.

set_window(*, window_ms: float, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Sets the scope capture window duration.

Parameters:

  • window_ms – Capture window duration in milliseconds.

  • timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot update the capture window.

set_trigger(*, edge: TriggerEdge | None = None, level: float | None = None, position_ms: float | None = None, signal: str | None = None, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Configures the scope trigger.

Only the passed arguments are updated, the others retain their current values.

Parameters:

  • edge – The trigger edge condition: RISING, FALLING, or ANY.

  • level – Threshold value the signal must cross.

  • position_ms – Pre-trigger time in milliseconds.

  • signal – Name of the variable used as the trigger source.

  • timeout – Override the default timeout (seconds).

Raises:

InvalidStateError – If Cockpit cannot update the trigger.

Example:

from imperix import TriggerEdge

scope.set_trigger(
    signal="speed_ref",
    edge=TriggerEdge.RISING,
    level=1500.0,
    position_ms=50.0,
)
set_oversampling(*, variables: Sequence[str] | None = None, enabled: bool, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Enables or disables oversampling on scoped variables.

Parameters:

  • enabled – Whether to enable oversampling.

  • variables – Name(s) of the variables to update. When this parameter is omitted, applies to all variables.

  • timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot update oversampling.

Example:

# Disable oversampling on all the variables
scope.set_oversampling(enabled=False)

# Reenables oversampling on specific variables
scope.set_oversampling(variables=["Ia", "Ib", "Ic"], enabled=True)
play(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Arms the scope and wait for a trigger event.

Parameters:

timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If the scope cannot be armed.

force_trigger(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Forces a trigger event.

Parameters:

timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If the trigger cannot be forced.

is_capture_done(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → bool

Checks whether the current capture has completed.

Parameters:

timeout – Maximum time to wait for a response in seconds.

Returns:

True if the capture has completed, False otherwise.

Example:

# Wait until a capture is ready before exporting the waveform.
cockpit.wait_until(scope.is_capture_done)
set_transient(*, variable: str, positions_ms: Sequence[float], values: Sequence[float], interpolation: Interpolation = Interpolation.STEPS, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Sets a Transient Generator sequence for a variable.

Parameters:

  • variable – Name of the variable to apply the sequence to.

  • positions_ms – Vector of positions at which the transient signal values will be applied

  • values – Vector of values that will be applied on the transient variable.

  • interpolation – STEPS (hold previous value) or LINEAR. Defaults to STEPS.

  • timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot configure the transient sequence.

Example:

scope.set_transient(
    variable="Iref",
    positions_ms=[10.0, 20.0, 30.0],
    values=[2.0, 5.0, 3.0],
)
scope.fire_transient()
remove_transient(variable: str, *, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Remove the Transient Generator sequence for a variable.

Parameters:

  • variable – Name of the variable whose sequence to remove.

  • timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If Cockpit cannot remove the transient sequence.

fire_transient(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None

Fires the Transient Generator sequence.

Parameters:

timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If the transient sequence cannot be started.

class imperix.TriggerEdge(*values)

Trigger edge direction for a Scope module.

Values:

  • ANY: Trigger on any crossing of the trigger level.

  • RISING: Trigger on a rising crossing of the trigger level.

  • FALLING: Trigger on a falling crossing of the trigger level.

ANY = 'any'
RISING = 'rising'
FALLING = 'falling'
class imperix.Interpolation(*values)

Interpolation mode for Transient Generator sequences.

Values:

  • STEPS: Hold each value until the next position.

  • LINEAR: Linearly interpolate between adjacent values.

STEPS = 'steps'
LINEAR = 'linear'