Skip to content

usage-rules.md

Latest commit

 

History

History
47 lines (40 loc) · 2.8 KB

usage-rules.md

File metadata and controls

47 lines (40 loc) · 2.8 KB
Raw

Rules for working with EtherCAT

EtherCAT is an experimental pure-Elixir EtherCAT master. Read the module docs for this dependency version before using it; unreleased main and published versions may have different APIs.

Runtime ownership

  • Supervise one EtherCAT.Runtime per BEAM node in the host application.
  • EtherCAT.start/1 returns {:ok, session}. Carry that EtherCAT.Session through runtime, provisioning, diagnostic, subscription, and capture calls.
  • EtherCAT.stop/1 ends the session, not the host supervisor. Do not reuse stopped sessions; they return {:error, :stale_session}.
  • Use an explicit :backend (EtherCAT.Backend). Physical rings use raw Ethernet; UDP is the simulator/integration transport, not a physical ESC transport.

Startup and observations

  • Without a slave list, discovery holds the ring in PREOP. Use EtherCAT.await_ready/2, not await_operational/2, for this workflow.
  • Cyclic I/O requires ordered EtherCAT.Slave.Config entries and EtherCAT.Domain.Config entries. Domain periods are whole milliseconds, expressed in microseconds. Use await_operational/2 after requesting cyclic operation.
  • EtherCAT.Provisioning owns PREOP configuration, activation/deactivation, and SDOs. EtherCAT.Diagnostics owns detailed runtime inspection.
  • EtherCAT.sample/3 returns a coherent per-slave, per-domain observation; there is no cross-domain consistency guarantee. Check Sample.errors for decode failures. A retained sample alone is not proof that the ring is currently healthy.
  • EtherCAT.subscribe/3 returns {:ok, ref, status, samples} and pushes {:ethercat, ref, payload} with no backpressure. Poll samples/2 for latest-only consumers. EtherCAT.Signals is the specialist signal/latch subscription API.
  • EtherCAT.write/4 stages an output; :ok is not proof of physical actuation. Never hide transport, WKC, AL-state, or topology faults with optimistic state.

Drivers and tests

  • Implement EtherCAT.Driver, not a slave-runtime behaviour. signal_model/2 maps named signals onto discovered PDOs; describe/1 is static/offline metadata.
  • Codecs return {:ok, value} / {:error, reason}. Encoding must match the declared width and zero unused high bits. Only registered directions require codecs.
  • Use EtherCAT.Driver.Provisioning for optional mailbox/sync configuration and EtherCAT.Simulator.Adapter for separate simulator definitions. Device identity metadata is not automatic hardware compatibility enforcement.
  • Start with deterministic EtherCAT.Simulator tests. Raw-socket and hardware tests need explicit interface setup and privileges; never run them on a production ring.
  • Distributed Clocks synchronize device clocks; they do not make BEAM scheduling hard real-time or guarantee that PDO frames arrive before a device deadline.