EtherCAT.Provisioning (ethercat v0.5.0)

Copy Markdown View Source

Session-bound provisioning and low-level configuration API.

Use this module for PREOP-first workflows, direct SDO traffic, and runtime activation control. Every operation requires the %EtherCAT.Session{} that owns the target runtime.

PREOP-first workflow

  1. Supervise EtherCAT.Runtime and start a session with a :backend and the domains you will need, but no :slaves list.
  2. Call EtherCAT.await_ready/2. Discovery holds devices in PREOP under positional names (:coupler, :slave_1, …); inspect EtherCAT.Diagnostics.slaves/1 before choosing a driver.
  3. Use configure_slave/3 to supply a driver, driver config, process-data assignments, and target_state: :op for each device that should activate. Refer only to domain IDs declared at session startup.
  4. Call activate/1, then EtherCAT.await_operational/2. Slaves intentionally left with target_state: :preop are not promoted to OP.
  5. Inspect status and samples. If activation fails, inspect EtherCAT.Diagnostics.master_status/1 and EtherCAT.Diagnostics.last_failure/1 rather than assuming the ring is operational.

To change configuration after activation, first use deactivate(session, :preop). The default deactivate(session) holds at SAFEOP, which is not the configuration state. Neither operation ends the session; EtherCAT.stop/1 does.

Mailbox traffic

SDO uploads return raw binaries. Downloads accept raw binaries; choose the object width, signedness, and byte order from the device's object dictionary. For example, given a live session and a mailbox-capable slave named :drive:

{:ok, device_name} = EtherCAT.Provisioning.upload_sdo(session, :drive, 0x1008, 0x00)

Mailbox support and allowed AL states are device-specific. An SDO failure is returned explicitly, including protocol and device abort errors. A failed or timed-out write may already have reached the device; do not blindly retry non-idempotent operations. Provisioning and output writes are not a safety stop.

Summary

Functions

activate(session)

Attempt cyclic activation for slaves configured with target_state: :op.

await_dc_locked(session, timeout_ms \\ 5000)

Wait for the session's active DC monitor to report lock; does not enable DC.

configure_slave(session, slave_name, opts)

Update one slave while the session and the slave are in PREOP.

deactivate(session, target \\ :safeop)

Stop cyclic runtime and retreat activatable slaves to SAFEOP (default) or PREOP.

download_sdo(session, slave_name, index, subindex, data)

Download one non-empty raw binary to a CoE object on a named slave.

update_domain_cycle_time(session, domain_id, cycle_time_us)

Update a domain period in microseconds, using a whole-millisecond value.

upload_sdo(session, slave_name, index, subindex)

Upload one CoE object from a named slave as a raw binary.

Functions

activate(session)

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

Attempt cyclic activation for slaves configured with target_state: :op.

await_dc_locked(session, timeout_ms \\ 5000)

@spec await_dc_locked(EtherCAT.Session.t(), pos_integer()) :: :ok | {:error, term()}

Wait for the session's active DC monitor to report lock; does not enable DC.

configure_slave(session, slave_name, opts)

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

Update one slave while the session and the slave are in PREOP.

Keyword options update the existing configuration; a EtherCAT.Slave.Config struct supplies a replacement. The name cannot change. Supported fields are :driver, :config, :process_data, :target_state, :sync, and :health_poll_ms. Domains must already exist. Layout changes remain subject to PREOP and domain registration checks; an error is not a request to silently discard mappings.

deactivate(session, target \\ :safeop)

@spec deactivate(EtherCAT.Session.t(), :safeop | :preop) :: :ok | {:error, term()}

Stop cyclic runtime and retreat activatable slaves to SAFEOP (default) or PREOP.

The session remains live. Check the result and runtime status for incomplete transitions; this API does not replace hardware safety mechanisms.

download_sdo(session, slave_name, index, subindex, data)

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

Download one non-empty raw binary to a CoE object on a named slave.

update_domain_cycle_time(session, domain_id, cycle_time_us)

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

Update a domain period in microseconds, using a whole-millisecond value.

The runtime validates the affected slave synchronization configuration too; callers must handle rejection rather than assuming the new period was applied.

upload_sdo(session, slave_name, index, subindex)

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

Upload one CoE object from a named slave as a raw binary.