Projects¶

The Project class represents a Cockpit project and provides project-level operations, such as:

Linking the project to an imperix controller and connecting to it
Enabling or disabling the PWM outputs of the linked controller
Accessing the user variables
Adding or removing modules (Scope, Rolling Plot, XY Plot, Sys. Id.)

Projects are created, opened, and retrieved through the ProjectCollection, available as cockpit.projects.

Creating a project¶

Recreating the project from scratch ensures that the execution starts from a clean, known state. It takes three steps:

Create the project from a compiled user code (.elf file) with create().
Link it to an imperix controller with link_target().
Connect to the controller with connect().

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)

The options used above are:

overwrite=True: Deletes any existing project with the same name before creating the new one.
auto_start_code=True: Starts the user code as soon as the connection is established.
bypass_warnings=True: Suppresses Cockpit’s warning popups (e.g., “A code is already running on this target”), so that the script runs without user intervention.

Opening an existing project¶

There are two ways to get hold of a project that already exists:

get() retrieves a project that is already open in Cockpit, by name. It returns None if no open project has that name.
open() opens a saved project (.ixproj file), including its modules and settings. It accepts the same auto_start_code and bypass_warnings options as connect().

The example below uses the project if it is already open, and opens it from disk otherwise:

from imperix import Cockpit

with Cockpit() as cockpit:

    project = cockpit.projects.get("My project")

    if project is None:
        project = cockpit.projects.open(
            "C:/imperix/my_project/My project.ixproj",
            auto_start_code=True,
            bypass_warnings=True,
        )

Enabling the PWM outputs safely¶

An unhandled error terminates a Python script immediately. If any call fails after enable_pwm() (a misspelled variable name, a timeout, a failed export, …), the remaining lines are skipped, including the one that was meant to disable the PWM outputs. The converter is then left switching and delivering power at whatever operating point the script last set, with no script supervising it anymore.

To avoid this, place everything that happens while the PWM outputs are enabled in a try block, and power down the converter in the matching finally block. Python executes the finally block whether the try block completed, raised an error, or was interrupted with Ctrl+C.

# Create or open a project...

try:
    # Enable the PWM outputs (the user code must be running)
    project.enable_pwm()

    # Run the experiment...

finally:
    # Always executed, even if an error occurred above
    project.disable_pwm()

Warning

A finally block is a safeguard against script errors, not a protection for the hardware. It is not executed if the Python process is killed or the PC shuts down, and disable_pwm() cannot succeed if the connection to Cockpit or to the controller is lost. A script running on a PC is far too slow to react to an over-current or over-voltage.

Always configure the hardware protections of the controller before running a script (see PN257). When a safety limit is exceeded, the controller blocks all PWM outputs instantly and enters the FAULT state, independently of the script.

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,
)

open(path: str | PathLike[str], *, auto_start_code: bool = False, bypass_warnings: bool | None = None, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → Project¶

Opens a saved Cockpit project.

Parameters:

path – Path to the .ixproj file, as a string or Path.
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.

Returns:

The opened Project.

Raises:

InvalidParamsError – If the path does not name an existing .ixproj file.
InvalidStateError – If the project cannot be opened, or if a connection is requested but the project is not linked to a target or the connection cannot be completed.

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.

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

Closes the project while preserving its project file.

Warning

Closing 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.
Raises:: NotFoundError – If the project is no longer open.

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()