Errors¶

When an operation fails, the imperix Python library raises an exception. Unless the script handles it, the script stops immediately and Python prints the type of the error along with a message explaining what went wrong.

All errors raised by the library derive from CockpitError. In the API reference, the Raises section of each method lists the main errors that the method can raise.

Overview¶

Errors related to the connection with Cockpit:

Error	Raised when
`CockpitConnectionError`	The library cannot start, connect to, or communicate with Cockpit. This includes a connection that closes during an operation, and a method called while not connected.
`VersionMismatchError`	The Python library and the ACG/CPP SDK have different major versions and cannot work together. The error message indicates which one to update. This is a kind of `CockpitConnectionError`.
`BusyError`	Cockpit is already connected to another script.

Errors raised by operations on targets, projects, variables, modules, and data loggers:

Error	Raised when
`NotFoundError`	A target, project, user variable, module, or data logger used by the script does not exist in Cockpit. Check the name or MAC address.
`InvalidStateError`	The operation is not allowed in the current state. For example, the project has no linked target, or the user code is not running.
`InvalidParamsError`	An argument is not valid. For example, a number is outside the allowed range, or a file format is not supported.
`UnsupportedOperationError`	Cockpit cannot perform the operation. For example, the action is not available for this type of module, or it requires a newer version of the ACG/CPP SDK.
`TimeoutError`	The operation did not finish within the allowed time. For example, Cockpit took too long to answer, or the condition passed to `wait_until()` did not become true in time.

Handling errors¶

In most scripts, errors do not need to be handled: letting the script stop and reading the error message is the right behavior. It is however highly recommended to make sure the converter is safely powered down, as explained in Disabling PWM when an error occurs.

Handling an error is useful when the script can do something about it. This is done with try and except: if an operation inside the try block raises the error named after except, Python runs the except block instead of stopping the script.

In the example below, if the target is not found, the script refreshes the target list and tries again:

from imperix import Cockpit, NotFoundError

TARGET_MAC = "AA:BB:CC:DD:EE:FF"

with Cockpit() as cockpit:
    try:
        target = cockpit.targets[TARGET_MAC]
    except NotFoundError:
        cockpit.targets.refresh()
        # If the target is still not found, the error is raised again and the script stops.
        target = cockpit.targets[TARGET_MAC]

Only the error named after except is handled. Any other error still stops the script.

Tip

When a missing item is an expected situation, get() is simpler than try/except: it returns None instead of raising NotFoundError.

project = cockpit.projects.get("My project")
if project is None:
    # Create or open the project
    ...

Disabling PWM when an error occurs¶

An error stops the script, but not the controller: the user code keeps running and the PWM outputs remain enabled. If an error occurs in the middle of an experiment, the line that was meant to disable the PWM outputs is never reached.

To avoid this, place the experiment in a try block and disable the PWM outputs in a finally block. Python runs the finally block whether the experiment finishes normally or is interrupted by an error:

try:
    project.enable_pwm()
    # Run the experiment
finally:
    project.disable_pwm()

Unlike except, finally does not handle the error: once the PWM outputs are disabled, the script still stops and reports it.

See the Projects page for a more complete power-down sequence and for the limits of this approach.

API Reference¶

Base class¶

class imperix.CockpitError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Base class for all imperix library exceptions.

Parameters:

message – Human-readable error message.
code – JSON-RPC error code, when available.
data_code – Cockpit-specific error code, when available.
data_details – Additional error details returned by Cockpit.

code¶: JSON-RPC error code, or None.

data_code¶: Cockpit-specific error code, or None.

data_details¶: Additional structured details, or None.

Connection errors¶

class imperix.CockpitConnectionError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when the library cannot start, connect to, or communicate with Cockpit.

This also covers a connection that closes during an operation and a connection that cannot be closed cleanly.

class imperix.VersionMismatchError(*, python_library_version: str, sdk_version: str)¶: Raised when the Python library and Cockpit have different major API versions.

class imperix.VersionMismatchWarning(*, python_library_version: str, sdk_version: str)¶

Warns once per connection when minor API versions differ.

The connection stays open, but some features may be unavailable.

class imperix.BusyError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶: Raised when Cockpit is already connected to another script.

Operation errors¶

class imperix.NotFoundError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶: Raised when a target, project, user variable, module, or data logger used by the script is not available in Cockpit.

class imperix.InvalidStateError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when the requested operation is not allowed in the current state.

For example, a project may not have a target linked, user code may not be running, or a module may not be ready for the requested action.

class imperix.InvalidParamsError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when one or more inputs are not valid for the requested operation.

For example, the selected file format may not be supported or a number may be outside the allowed range.

class imperix.UnsupportedOperationError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when Cockpit cannot perform the requested operation.

For example, the script may ask Cockpit to create a module type that it does not recognize, or use an action that is not available for that type of module. Some operations also require a newer version of the ACG or CPP SDK. If the installed SDK is too old, update it before trying again.

class imperix.TimeoutError(message: str, *, code: int | None = None, data_code: str | None = None, data_details: Any | None = None)¶

Raised when an operation does not finish within the allowed time.

For example, Cockpit may take too long to answer, or a condition passed to wait_until() may not become true before the timeout.