Targets¶

The Target class provides an interface for interacting with imperix controllers, similar to using the Target configuration tab in Cockpit.

Note

To interact with running user code (e.g., to read and write variables, or acquire Scope data) a project must be used.

Listing available imperix controllers¶

The following example instructs Cockpit to refresh its target list (which triggers an Ethernet network scan) and iterates through all detected controllers. This code snippet serves as the “Hello World” example in the getting started guide.

from imperix import Cockpit

with Cockpit() as cockpit:

   # Instructs Cockpit to run an Ethernet network scan and refresh its target list
   print("Refreshing target list...")
   cockpit.targets.refresh()

   # Retrieve the list of detected targets
   targets = cockpit.targets.list()
   print(f"{len(targets)} target(s) found:")

   # Display the hostname and IP address of each target
   for target in targets:
      print(f"  {target.hostname} ({target.ip})")

Retrieving a specific imperix controller¶

A controller is uniquely identified by its MAC address, and Cockpit automatically tracks its IP address.

The code below demonstrates how to verify that a specific controller is properly detected. To save time during multiple script executions, a network scan is performed only if the target is absent from the initial list.

from imperix import Cockpit

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

with Cockpit() as cockpit:

   # Retrieve the target using its MAC address
   target = cockpit.targets.get(TARGET_MAC)

   if target is None:
      # The target was not found; run a network scan
      cockpit.targets.refresh()
      target = cockpit.targets.get(TARGET_MAC)

   if target is None:
      # The target is still not found; exit the script
      raise SystemExit(f"Target {TARGET_MAC} not found")

   # The rest of the script...

Waiting for a controller after a reboot¶

Rebooting an imperix controller takes approximately one minute, or longer if multiple controllers are networked together (e.g., in a master-slave or multi-master setup).

The following example illustrates how combining is_ready() with wait_until() blocks script execution until the controller is fully ready to accept code following a reboot.

from imperix import Cockpit

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

with Cockpit() as cockpit:

   # Retrieve the target using its MAC address
   target = cockpit.targets.get(TARGET_MAC)

   # Upload a custom FPGA bitstream and reboot the target
   target.upload_bitstream(r"C:\imperix\custom_bitstream.bit")
   target.reboot()

   # Wait for the target to go offline
   cockpit.wait_until(
      lambda: not cockpit.targets.is_online(target),
      timeout=10.0,
      interval=3.0
   )

   # Wait for the target to reboot and become fully ready
   cockpit.wait_until(
      lambda: cockpit.targets.is_ready(target),
      timeout=120.0,
      interval=3.0,
   )

API Reference¶

class imperix.TargetCollection(cockpit: Cockpit)¶

Imperix controllers detected by Cockpit. Accessed via imperix.Cockpit.targets.

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

Returns a list of the targets currently detected by Cockpit.

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

Example:

for target in cockpit.targets.list():
    print(target.mac, target.ip)

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

Runs an Ethernet network scan and returns a list of the targets currently detected by Cockpit.

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

Example:

targets = cockpit.targets.refresh()
for target in targets:
    print(target.mac, target.ip)

get_realsync_network(mac: str, *, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → list[Target]¶

Returns a list of all targets in the specified target’s RealSync network.

The targets are ordered by ascending RealSync ID.

Parameters:

mac – MAC address of a target currently known by Cockpit.
timeout – Maximum time to wait for a response in seconds.

Returns:

A list of Target instances.

Raises:

NotFoundError – If Cockpit does not know the target.

Example:

network = cockpit.targets.get_realsync_network("AA:BB:CC:DD:EE:FF")
for realsync_id, target in enumerate(network):
    print(realsync_id, target.mac)

Checks whether targets are currently online.

This method runs refresh() behind the scenes to ensure up-to-date results.

Parameters:

targets – MAC address(es) or Target instance(s).
timeout – Maximum time to wait for a response in seconds.

Returns:

True if all requested targets are online, False otherwise.

Example:

cockpit.targets.is_online(["AA:BB:CC:DD:EE:01", "AA:BB:CC:DD:EE:02"])

Checks whether targets finished booting and are ready to receive a new user code.

This method runs refresh() behind the scenes to ensure up-to-date results.

Parameters:

targets – MAC address(es) or Target instance(s).
timeout – Maximum time to wait for a response in seconds.

Returns:

True if all requested targets are online, False otherwise.

Example:

cockpit.targets.is_ready(["AA:BB:CC:DD:EE:01", "AA:BB:CC:DD:EE:02"])

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

Represents an imperix controllers.

property mac: str¶: The MAC address of the target (primary identifier).

property hostname: str¶: The hostname of the target, if available.

property ip: str¶: The IP address of the target, if available.

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

Enables the PWM outputs.

Parameters:: timeout – Override the default timeout (seconds).
Raises:: InvalidStateError – If user code is not running or the outputs cannot be enabled.

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

Disables the PWM outputs.

Parameters:: timeout – Maximum time to wait for a response in seconds.
Raises:: InvalidStateError – If user code is not running or the outputs cannot be disabled.

reboot(*, delay_ms: int | None = None, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Reboots the target.

This operation is not supported on B-Box 3 targets.

Parameters:

delay_ms – Delay in milliseconds before rebooting. None reboots immediately.
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If the target cannot be rebooted.

upload_bitstream(path: str | PathLike[str], *, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Uploads a customized FPGA bitstream (.bit) to this target.

Parameters:

path – Absolute path to the bitstream file, as a string or Path.
timeout – Override the default timeout (seconds).

Raises:

InvalidStateError – If the file cannot be sent to the target.

Example:

target.upload_bitstream(r"C:\\imperix\\tests\\custom_bitstream.bit")
target.reboot()

# Wait for the target to go offline
cockpit.wait_until(
    lambda: not cockpit.targets.is_online(target),
    timeout=10.0,
    interval=3.0
)

# Wait for the target to reboot and be ready
cockpit.wait_until(
    lambda: cockpit.targets.is_ready(target),
    timeout=120.0,
    interval=3.0,
)

upload_user_code(path: str | PathLike[str], *, timeout: float | None | UseDefaultTimeout = UseDefaultTimeout.TOKEN) → None¶

Upload a user code (.elf) file to this target.

Parameters:

path – Absolute path to the user code .elf file, as a string or Path.
timeout – Maximum time to wait for a response in seconds.

Raises:

InvalidStateError – If the file cannot be sent to the target.

Example::: target = cockpit.targets[“AA:BB:CC:DD:EE:FF”] target.stop_code() target.upload_user_code(r”C:\imperix\tests\motor_control.elf”) target.start_code()

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

Starts the user code execution on this 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 user code cannot be started.

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

Stops the user code execution on this target.

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