@spec activate() :: :ok | {:error, term()}

Start cyclic operation after dynamic PREOP configuration.

This starts the DC runtime, starts all domains cycling, and advances all slaves whose target_state is :op.

@spec await_dc_locked(timeout_ms :: pos_integer()) :: :ok | {:error, term()}

Wait for DC lock.

Returns :ok once the active DC runtime reports :locked.

@spec await_operational(timeout_ms :: pos_integer()) :: :ok | {:error, term()}

Block until the master reaches operational cyclic runtime, then return :ok.

This is stricter than await_running/1: :preop_ready and :deactivated are not enough.

@spec await_running(timeout_ms :: pos_integer()) :: :ok | {:error, term()}

Block until the master reaches a usable session state, then return :ok.

Returns {:error, :timeout} if startup does not complete within timeout_ms ms. Returns {:error, :not_started} if start/1 has not been called. Returns startup degradation or runtime recovery errors if the session is not currently usable.

@spec bus() :: master_query_result(EtherCAT.Bus.server() | nil)

Return the stable bus server reference for direct frame transactions.

Returns {:ok, bus} while the session owns a running bus process. Returns {:ok, nil} if the master process exists but the bus subsystem is not currently running, such as after the session has settled back to :idle.

Returns {:error, :not_started} if the master does not exist, {:error, :timeout} if the local master call itself times out, and {:error, {:server_exit, reason}} if the local master dies mid-call.

@spec configure_slave(atom(), keyword() | EtherCAT.Slave.Config.t()) ::
  :ok | {:error, term()}

Configure a discovered slave while the session is still in PREOP.

This is the dynamic counterpart to providing %EtherCAT.Slave.Config{} entries up front in start/1.

@spec dc_status() :: master_query_result(EtherCAT.DC.Status.t())

Return a Distributed Clocks status snapshot for the current session.

Returns {:ok, status} on success.

Returns {:error, :not_started} if the master process does not exist. Returns {:error, :timeout} if the local master call itself times out.

@spec deactivate(:safeop | :preop) :: :ok | {:error, term()}

Leave OP while keeping the session alive.

deactivate/0 settles the runtime in SAFEOP by default. Use deactivate(:preop) when you need to re-enter PREOP for reconfiguration.

@spec domain_info(atom()) ::
  {:ok, domain_info()}
  | {:error, :not_found | :timeout | {:server_exit, term()}}

Return a diagnostic snapshot for a domain.

Keys:

• :id — domain atom identifier
• :cycle_time_us — current cycle period in microseconds

• :state — :open | :cycling | :stopped

• :cycle_count — successful LRW cycles since last start
• :miss_count — consecutive missed cycles (resets on success)
• :total_miss_count — cumulative missed cycles since last start
• :logical_base — current LRW logical start address for this domain image
• :image_size — PDO image size in bytes
• :expected_wkc — expected working counter for a healthy bus
• :freshness — cached-input freshness window derived from the domain cycle time

Example

iex> EtherCAT.domain_info(:main)
{:ok, %{
  id: :main,
  cycle_time_us: 1_000,
  state: :cycling,
  cycle_count: 12345,
  miss_count: 0,
  total_miss_count: 2,
  logical_base: 0,
  image_size: 4,
  expected_wkc: 3,
  freshness: %{state: :fresh, refreshed_at_us: 1_234_000, age_us: 250, stale_after_us: 3_000}
}}

@spec domains() :: master_query_result([domain_summary()])

Return {:ok, [{id, cycle_time_us, pid}]} for all running domains.

Returns {:error, :not_started} if the master does not exist and {:error, :timeout} if the local master call itself times out.

@spec download_sdo(atom(), non_neg_integer(), non_neg_integer(), binary()) ::
  :ok | {:error, term()}

Download a CoE SDO value to a slave mailbox object entry.

This is a blocking acyclic mailbox transfer and is only valid once the slave mailbox is configured, typically from PREOP onward.

@spec last_failure() :: master_query_result(map() | nil)

Return the last terminal startup/runtime failure retained after the master returned to :idle.

Returns {:ok, failure} on success, where failure may be nil.

Returns {:error, :not_started} if the master does not exist and {:error, :timeout} if the local master call itself times out.

@spec read_input(atom(), atom()) :: {:ok, {term(), integer()}} | {:error, term()}

Read the latest decoded input sample for a slave input signal.

Returns {value, refreshed_at_us} where refreshed_at_us is the last valid domain refresh time for the cached process-image sample, not a hardware-edge timestamp.

Returns {:error, :not_ready} until the first domain cycle completes and {:error, {:stale, details}} once the cached sample is older than the domain freshness window.

@spec reference_clock() ::
  {:ok, %{name: atom() | nil, station: non_neg_integer()}} | {:error, term()}

Return the current DC reference clock as %{name, station}.

@spec slave_info(atom()) ::
  {:ok, slave_info()} | {:error, :not_found | :timeout | {:server_exit, term()}}

Return a diagnostic snapshot for a slave.

Keys:

• :name — slave atom name
• :station — assigned bus station address

• :al_state — current ESM state: :init | :preop | :safeop | :op

• :identity — %{vendor_id, product_code, revision, serial_number} from SII, or nil
• :esc — %{fmmu_count, sm_count} from ESC base registers, or nil
• :driver — driver module in use
• :coe — true if the slave has a mailbox (CoE-capable)
• :available_fmmus — FMMUs supported by the ESC, or nil
• :used_fmmus — count of active {domain, SyncManager} attachments
• :attachments — list of %{domain, sm_index, direction, logical_address, sm_size, signal_count, signals}
• :signals — list of %{name, domain, direction, bit_offset, bit_size} for registered signals
• :configuration_error — last configuration failure term, or nil Common values are structured tuples such as {:mailbox_config_failed, index, subindex, reason}.

Example

iex> EtherCAT.slave_info(:sensor)
{:ok, %{
  name: :sensor,
  station: 0x1001,
  al_state: :op,
  identity: %{vendor_id: 0x2, product_code: 0x07111389, revision: 0x00190000, serial_number: 0},
  esc: %{fmmu_count: 3, sm_count: 4},
  driver: MyApp.EL1809,
  coe: false,
  available_fmmus: 3,
  used_fmmus: 1,
  attachments: [
    %{domain: :main, sm_index: 3, direction: :input, logical_address: 0x0000, sm_size: 2, signal_count: 2, signals: [:ch1, :ch2]}
  ],
  pdo_health: %{state: :fresh, domains: [%{id: :main, state: :fresh, refreshed_at_us: 1_234_000, age_us: 250, stale_after_us: 3_000}]},
  signals: [
    %{name: :ch1, domain: :main, direction: :input, bit_offset: 0, bit_size: 1},
    ...
  ],
  configuration_error: nil
}}

@spec slaves() :: master_query_result([slave_summary()])

Return {:ok, [%{name:, station:, server:, pid:, fault:}]} for all running slaves.

Returns {:error, :not_started} if the master does not exist and {:error, :timeout} if the local master call itself times out.

@spec start(keyword()) :: :ok | {:error, term()}

Start the master: open the interface, discover slaves, and begin self-driving configuration.

Returns :ok once discovery has started. Call await_running/1 to block until startup finishes. If the master falls back to :idle, inspect last_failure/0 for the retained reason. For dynamic PREOP workflows, call activate/0 afterwards to enter cyclic operation.

Options:

• :interface (required) — network interface, e.g. "eth0"
• :domains — list of %EtherCAT.Domain.Config{} structs describing domain intent. High-level domain configs do not take :logical_base; the master allocates logical windows automatically.
• :slaves — list of %EtherCAT.Slave.Config{} structs (position matters — station address = base_station + index). nil entries are rejected; use %EtherCAT.Slave.Config{name: :coupler} for unnamed couplers. If omitted or empty, one default slave process is started per discovered station and held in :preop for dynamic configuration.
• :base_station — first station address, default 0x1000
• :dc — %EtherCAT.DC.Config{} for master-wide Distributed Clocks, or nil to disable DC. await_lock? gates startup activation; lock_policy controls the runtime reaction to DC lock loss.
• :frame_timeout_ms — optional fixed bus frame response timeout in ms (otherwise auto-tuned from slave count and cycle time)
• :scan_poll_ms — optional discovery poll interval in ms
• :scan_stable_ms — optional identical-count stability window in ms before startup begins

@spec state() :: master_query_result(session_state())

Return the current public session state.

Values:

• :idle
• :discovering
• :awaiting_preop
• :preop_ready
• :deactivated — session is live but intentionally settled below OP, typically SAFEOP
• :operational — cyclic OP path is healthy; inspect slaves/0 for non-critical per-slave faults
• :activation_blocked — the transition to the desired runtime target is blocked
• :recovering — runtime fault recovery in progress

Returns {:ok, state} on success.

{:ok, :idle} means the master process exists and the session is idle. {:error, :not_started} means there is no local master process at all.

Returns {:error, :not_started} if the master does not exist and {:error, :timeout} if the local master call itself times out.

@spec stop() :: :ok | {:error, :already_stopped | :timeout | {:server_exit, term()}}

Stop the master: tear the session down completely.

Returns {:error, :already_stopped} if not running.

@spec subscribe(atom(), atom(), pid()) ::
  :ok
  | {:error,
     {:not_registered, atom()} | :not_found | :timeout | {:server_exit, term()}}

Subscribe to named slave events.

name may refer to:

• a registered process-data signal, delivered as {:ethercat, :signal, slave_name, name, value}
• a named latch configured through sync.latches, delivered as {:ethercat, :latch, slave_name, name, timestamp_ns}

Unknown names are rejected with {:error, {:not_registered, name}}.

@spec update_domain_cycle_time(atom(), pos_integer()) :: :ok | {:error, term()}

Update the live cycle period of a running domain.

This changes the Domain runtime directly. The master keeps its initial domain plan; domains/0 and domain_info/1 reflect the live period owned by the Domain process.

@spec upload_sdo(atom(), non_neg_integer(), non_neg_integer()) ::
  {:ok, binary()} | {:error, term()}

Upload a CoE SDO value from a slave mailbox object entry.

This is a blocking acyclic mailbox transfer and is only valid once the slave mailbox is configured, typically from PREOP onward.

@spec write_output(atom(), atom(), term()) :: :ok | {:error, term()}

Stage value into a slave output PDO for the next domain cycle.

This confirms the value was staged into the master's domain output buffer for the next cycle. It does not prove the slave has already applied the value on hardware.