Session-bound inspection and diagnostic API.
Normal protocol-level runtime usage should stay on EtherCAT. This module is
for topology inspection, DC status, slave/domain details, and lower-level
runtime visibility. Every query requires its owning %EtherCAT.Session{}.
Master status, domain lists, and DC queries collect live observations in the
caller under a shared one-second timeout budget. An unavailable worker returns
{:error, {:diagnostic_unavailable, source, reason}}, where source is :bus,
:dc, or {:domain, id}. The session is revalidated after collection; results
from a stopped or replaced generation return {:error, :stale_session}.
Choose the narrowest query you need:
| Query | Use |
|---|---|
master_status/1 | Session target, activation/recovery faults, and subsystem observations |
slaves/1 | Discovered/configured slave summary |
slave_info/2 | One slave's AL state, identity, registrations, and runtime details |
domain_info/2 | One domain's cycle health, counters, and invalid reason |
dc_status/1 | DC lock state and synchronization diagnostics |
last_failure/1 | Retained master failure information, when present |
Diagnostic collection is not an atomic snapshot of the entire ring. An
operational master can still track non-critical slave-local faults; inspect
the returned fault fields rather than using its state as machine readiness.
For static/offline metadata use EtherCAT.describe/2 or EtherCAT.inventory/1.
Summary
Functions
@spec bus(EtherCAT.Session.t()) :: EtherCAT.session_query_result(EtherCAT.Bus.server() | nil)
@spec dc_status(EtherCAT.Session.t()) :: EtherCAT.session_query_result(EtherCAT.DC.Status.t())
@spec domain_info(EtherCAT.Session.t(), atom()) :: {:ok, map()} | {:error, term()}
@spec domains(EtherCAT.Session.t()) :: EtherCAT.session_query_result([tuple()])
@spec last_failure(EtherCAT.Session.t()) :: EtherCAT.session_query_result(map() | nil)
@spec master_status(EtherCAT.Session.t()) :: {:ok, EtherCAT.Master.Status.t()} | {:error, term()}
@spec reference_clock(EtherCAT.Session.t()) :: {:ok, %{name: atom() | nil, station: non_neg_integer()}} | {:error, term()}
@spec slave_info(EtherCAT.Session.t(), atom()) :: {:ok, map()} | {:error, term()}
@spec slaves(EtherCAT.Session.t()) :: EtherCAT.session_query_result([map()])