@spec capture(EtherCAT.Session.t(), atom(), keyword()) ::
  {:ok, capture()} | {:error, term()}

Capture a live slave into a structural snapshot.

Supported options:

• :sdos — list of {index, subindex} tuples to upload and include

@spec definition_options(capture()) :: keyword()

Convert a capture map into simulator definition options.

The generated options normalize PDO data onto the simulator's simpler process-data model: one output window and one input window with canonical physical offsets.

@spec gen_driver(EtherCAT.Session.t(), atom(), keyword()) ::
  {:ok, %{driver_path: String.t()}} | {:error, term()}

Generate a self-contained best-effort driver scaffold for slave_name or a previously loaded capture map.

Supported options:

• :module (required) — driver module name
• :driver_path — output path for the generated driver file
• :force — overwrite existing files when true
• :sdos — list of {index, subindex} tuples to upload and include

Use write_capture/3 separately if you also want to persist the captured snapshot file alongside the generated driver.

@spec gen_simulator(EtherCAT.Session.t(), atom(), keyword()) ::
  {:ok, %{capture_path: String.t(), module_path: String.t()}} | {:error, term()}

Generate a simulator companion scaffold for slave_name.

Supported options:

• :module (required) — simulator companion module name
• :module_path — output path for the generated module
• :capture_path — output path for the generated capture file
• :force — overwrite existing files when true
• :sdos — list of {index, subindex} tuples to upload and include

@spec help() :: :ok

Print a short interactive command summary.

@spec list_slaves(EtherCAT.Session.t()) :: {:ok, [map()]} | {:error, term()}

Return a compact snapshot of the currently discovered slaves.

@spec load_capture(Path.t()) :: {:ok, capture()} | {:error, term()}

Load a data-only capture file written by write_capture/3.

@spec load_capture!(Path.t()) :: capture()

Load a data-only capture file and raise on failure.

@spec render_driver(EtherCAT.Session.t(), atom(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Render the best-effort driver scaffold for slave_name or a previously loaded capture map.

This returns the final module source directly instead of writing files.

Supported options:

• :module (required) — driver module name
• :simulator_module — simulator companion module name; defaults to Module.concat(module, Simulator)
• :signal_names — map or keyword list of {{direction, pdo_index}, name} overrides used for the rendered signal names
• :sdos — list of {index, subindex} tuples to upload and include when slave_name is a live slave

@spec render_simulator(EtherCAT.Session.t(), atom(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Render a capture-backed simulator scaffold for slave_name or a previously loaded capture map.

This returns the final module source directly instead of writing files.

Supported options:

• :module (required) — simulator companion module name
• :capture_path — output path for the generated capture file; used to compute the relative load path embedded in the module
• :module_path — output path of the generated module; used to compute the relative load path embedded in the module
• :sdos — list of {index, subindex} tuples to upload and include when slave_name is a live slave

@spec write_capture(EtherCAT.Session.t(), atom(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Write a data-only capture file for slave_name.

Supported options:

• :path — output path; defaults to priv/ethercat/captures/...
• :force — overwrite an existing file when true
• :sdos — list of {index, subindex} tuples to upload and include