Projects¶

The Project class provides an interface for performing project-level operations, such as:

Creating a project and linking it to an imperix controller
Enabling or disabling the PWM outputs of the linked controller
Retrieving the list of user variables.
Adding or removing modules (Scope, Rolling Plot, XY Plot, Sys. Id.)

Creating a project¶

When using Python scripting, recreating the project from scratch is recommended to ensure execution starts from a clean, known state. Setting overwrite=True when creating a project automatically deletes any existing project with the same name.

Setting bypass_warnings=True instructs Cockpit to suppress warning popups (e.g., “A code is already running on this target”).

from imperix import Cockpit

with Cockpit() as cockpit:

   # Create a new project, overwriting any existing one with the same name
   project = cockpit.projects.create(
      "C:/imperix/my_script/user_code.elf",
      name="My project",
      overwrite=True,
   )

   # Link the project to an imperix controller, using its MAC address
   project.link_target("AA:BB:CC:DD:EE:FF")

   # Connect to the controller and start the user code
   project.connect(auto_start_code=True, bypass_warnings=True)

Retrieving an existing project¶

Instead of creating a project from scratch, an existing project open in Cockpit can be retrieved by name using the get() method. If the specified project does not exist, get() returns None.

from imperix import Cockpit

with Cockpit() as cockpit:

    # Look up the project by name
    project = cockpit.projects.get("Central PV inverter")

    if project is None:
        raise SystemExit("Project not found.")

Interacting with a project¶

The following example demonstrates common interactions with a project, such as enabling and disabling PWM outputs, creating a Scope module, and reading and writing variables.

# Enable the PWM outputs
project.enable_pwm()

# Add a Scope module to the project view
scope = project.modules.create(ModuleType.SCOPE)

# Read and write user variables
value = project.variables["speed_ref"].read()
project.variables["speed_ref"].write(value + 25.0)

# Disable the PWM outputs
project.disable_pwm()

API Reference¶

class imperix.ProjectCollection(cockpit: Cockpit)¶

Projects currently open in Cockpit. Accessed via projects.

Example:

# List all projects currently open in Cockpit.
for p in cockpit.projects:
    print(p.name, p.path)

# Look up by name
project = cockpit.projects["My project"]

# Look up by user code
project = cockpit.projects["C:/imperix/my_script/user_code.elf"]

list(*, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → list[Project]¶

Returns a list of the projects currently open in Cockpit.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Returns:: A list of Project instances.

Example:

for project in cockpit.projects.list():
    print(project.name, project.path)

create(path: str | PathLike[str], *, name: str | None = None, overwrite: bool = False, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → Project¶

Creates a new project from a user code file.

Parameters:

path – Absolute path to the user code .elf file, as a string or Path.
name – Project name displayed in Cockpit
overwrite – Whether to delete an existing project with the same name before creating the new one.
timeout – Maximum time to wait for a response in seconds.

Returns:

The newly created Project.

Raises:

InvalidStateError – If Cockpit cannot create the project or replace an existing project with the same name.

Example:

# Create a new project, overwriting any existing one with the same name
project = cockpit.projects.create(
    "C:/imperix/my_script/user_code.elf",
    name="My project",
    overwrite=True,
)

class imperix.Project(cockpit: Cockpit, data: dict[str, Any])¶

Represents a project open in Cockpit.

variables¶: User variables of the user code.

modules¶: Modules instantiated in the project view (e.g. Scope, Rolling Plot, XY Plot).

property id: int¶: Numeric project ID assigned by Cockpit.

property name: str¶: Display name of the project.

property path: str¶: Absolute path to the user code file.

property linked_target_mac: str | None¶: MAC address of the linked target, or None if unlinked.

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

Deletes the project.

Warning

Deleting a project does not stop the user code or disable the PWM outputs on the linked target.

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

link_target(mac: str, *, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → Project¶

Links a target to this project.

Parameters:

mac – MAC address of the target.
timeout – Maximum time to wait for a response in seconds.

Returns:

This Project instance, updated in place.

Raises:

InvalidStateError – If Cockpit cannot link the target to the project.

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

Unlinks the currently linked target from this project.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Raises:: InvalidStateError – If Cockpit cannot unlink the target.

take_snapshot(*, name: str | None = None, comment: str | None = None, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → str¶

Takes a snapshot of acquired data.

The call completes after Cockpit has finished recording the snapshot data.

Parameters:

name – Snapshot name. If omitted, Cockpit uses its default naming.
comment – Comment stored with the snapshot.
timeout – Maximum time to wait for a response in seconds.

Returns:

Absolute path to the created snapshot.

Raises:

InvalidStateError – If Cockpit cannot create the snapshot.

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

Removes all snapshots.

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

connect(*, auto_start_code: bool = False, bypass_warnings: bool | None = None, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Connects to the linked target.

Parameters:

auto_start_code – Start the user code right after connecting. Defaults to False.
bypass_warnings – Whether to bypass Cockpit warning popups (e.g. “A code is already running on this target”).
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If no target is linked or the connection cannot be completed.

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

Disconnect from the linked target.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Raises:: InvalidStateError – If no target is linked or the target cannot be disconnected.

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

Enable PWM outputs on the linked target.

Parameters:

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

Raises:

NotFoundError – If the linked target is no longer available.
InvalidStateError – If no target is linked, user code is not running, or the outputs cannot be enabled.

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

Disable PWM outputs on the linked target.

Parameters:

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

Raises:

NotFoundError – If the linked target is no longer available.
InvalidStateError – If no target is linked, user code is not running, or the outputs cannot be disabled.

start_code(*, bypass_warnings: bool | None = None, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Start user code execution on the linked target.

Parameters:

bypass_warnings – Whether to bypass Cockpit warning popups (e.g. “A code is already running on this target”).
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If no target is linked or user code cannot be started.

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

Stop user code execution on the linked target.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Raises:: InvalidStateError – If no target is linked or user code cannot be stopped.

add_data_logger(variables: str | Sequence[str], path: str | PathLike[str], sampling_frequency_hz: float, *, overwrite: bool = False, max_file_duration_s: float | None = None, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → DataLogger¶

Configures a data logger for this project.

A data logger continuously saves acquired data from selected variables to a file on the host PC in CSV, MAT, HDF5, or MDF4 format.

Warning

CSV stores each value as readable text, which uses more disk space and takes more CPU to write. MAT, HDF5, or MDF4 file formats are therefore recommended when logging at high frequency or for long periods.

See the Data loggers page for more details.

Parameters:

variables – Variable name or variable names to record.
path – Output file path. The extension selects the file format (.csv, .mat, .h5, .hdf5, or .mf4).
sampling_frequency_hz – Sampling frequency in hertz. Must be greater than 0. This value saturates at the CPU task frequency.
overwrite – Replace an existing output file when True. Defaults to False.
max_file_duration_s – Maximum recorded-data duration of each physical file in seconds. Must be at least 1 second when set. None disables automatic splitting. Defaults to None.
timeout – Maximum time to wait for a response in seconds.

Returns:

The newly created DataLogger.

Raises:

NotFoundError – If one of the requested variables is not available.
InvalidStateError – If the project is not linked to a ready target, or another data logger already uses the output path.

Example:

# Configure the data logger.
data_logger = project.add_data_logger(
    ["speed_ref", "phase_current"],
    "C:/imperix/recordings/my_recording.csv",
    sampling_frequency_hz=1_000.0,
    overwrite=True,
    max_file_duration_s=60.0,
)

data_logger.start()
# Run the experiment.
data_logger.split()  # Optional manual file boundary.
data_logger.stop()
data_logger.remove()