Behaviour for slave-specific drivers.

A driver is a pure module — no process state, no Application.get_env. All configuration is passed as a config map from EtherCAT.start/1.

If a slave config omits :driver, EtherCAT.Slave.Driver.Default is used. That default driver exposes no PDO profile and is intended for couplers or dynamically configured devices.

Generic SYNC0/SYNC1/latch intent does not live in the driver. It belongs on %EtherCAT.Slave.Config{sync: %EtherCAT.Slave.Sync.Config{...}}. Drivers only own device-specific translation through the optional sync_mode/2 callback when a slave application needs additional mailbox objects beyond the generic ESC DC registers.

Optional identity and simulator support

Drivers may optionally declare static device identity through identity/0. That metadata is useful for future driver discovery against scanned bus identity and for tooling. Keep it high-level: vendor, product, and revision.

Exact simulator authoring does not live in the real driver behaviour. Use an optional MyDriver.Simulator companion module that implements EtherCAT.Simulator.DriverAdapter when EtherCAT.Simulator.Slave.from_driver/2 needs profile-specific simulator configuration.

Signal model

signal_model/1 returns a keyword list of {signal_name, declaration} pairs. Each value declares where that signal lives in the slave's PDO layout:

• an integer means "this signal spans the whole PDO at that index"
• %EtherCAT.Slave.ProcessData.Signal{} may select a bit-range inside a PDO

The master reads SII EEPROM categories 0x0032 (TxPDO) and 0x0033 (RxPDO) to derive SyncManager assignment, direction, total SM size, and each PDO's bit offset within its SyncManager. The driver's signal model sits on top of that hardware description and names the application-facing signals.

Use a keyword list (not a map) so signal order is explicit and deterministic.

[channels: 0x1A00]

Each signal is encoded and decoded independently. Sub-byte signals (e.g. 1-bit digital channels) receive/return 1 padded byte with the value in bit 0 (LSB). Larger signals receive exactly enough bytes to carry the declared bit_size.

Example — EL1809 / EL2809 digital cards

Full compiled example drivers live in the test integration support tree:

• test/integration/support/drivers/el1809.ex
• test/integration/support/drivers/el2809.ex

They show the minimal signal_model/1 and bit-oriented encode_signal/3 / decode_signal/3 callbacks for Beckhoff-style 16-channel digital I/O terminals.

Example — EL3202 (2-ch PT100 input, 2 × 32-bit TxPDOs)

defmodule MyApp.EL3202 do
  @behaviour EtherCAT.Slave.Driver

  @impl true
  def signal_model(_config) do
    # 0x1A00 = channel 1 (SM3, bytes 0–3), 0x1A01 = channel 2 (SM3, bytes 4–7)
    [channel1: 0x1A00, channel2: 0x1A01]
  end

  @impl true
  def mailbox_config(_config) do
    [
      {:sdo_download, 0x8000, 0x19, <<8::16-little>>},
      {:sdo_download, 0x8010, 0x19, <<8::16-little>>}
    ]
  end

  @impl true
  def encode_signal(_signal, _config, _value), do: <<>>

  @impl true
  def decode_signal(:channel1, _config, <<
        _::1, error::1, _::2, _::2, overrange::1, underrange::1,
        toggle::1, state::1, _::6, value::16-little>>) do
    %{ohms: value / 16.0, overrange: overrange == 1, underrange: underrange == 1,
      error: error == 1, invalid: state == 1, toggle: toggle}
  end
  def decode_signal(:channel2, _config, <<
        _::1, error::1, _::2, _::2, overrange::1, underrange::1,
        toggle::1, state::1, _::6, value::16-little>>) do
    %{ohms: value / 16.0, overrange: overrange == 1, underrange: underrange == 1,
      error: error == 1, invalid: state == 1, toggle: toggle}
  end
  def decode_signal(_signal, _config, _), do: nil
end