KinoEtherCAT

Livebook and Kino tools for EtherCAT.

kino_ethercat is built around three use cases:

• discover and configure an EtherCAT bus from Livebook
• inspect and control a running master with focused runtime renders
• teach EtherCAT with a simulator-first workflow and low setup friction

Quick Start

If you want the shortest path to a first useful result, start with the example notebook:

• EtherCAT Introduction

That notebook uses the built-in simulator, walks through Setup and Master, and ends with a simple outputs.ch1 -> inputs.ch1 interaction.

The broader teaching direction lives in examples/README.md.

Installation

Add kino_ethercat to a Livebook notebook:

Mix.install([
  {:kino_ethercat, "~> 0.5.0"}
])

KinoEtherCAT 0.5 uses ethercat ~> 0.5.0 and its session-based API.

KinoEtherCAT supervises EtherCAT.Runtime by default. If your application already supervises it, set config :kino_ethercat, supervise_runtime: false before startup.

For local development against this repo:

Mix.install([
  {:kino_ethercat, path: "~/path/to/kino_ethercat"}
])

When developing this repo itself against a sibling ../ethercat checkout, set:

export KINO_ETHERCAT_USE_LOCAL_ETHERCAT=1

Main Surfaces

Smart Cells

KinoEtherCAT registers Smart Cells in Livebook under + Smart.

EtherCAT Setup

Discovers the current bus or simulator and generates a static EtherCAT.start/1 cell.

• auto-scans when added
• supports raw socket or UDP transport
• lets you name slaves, choose drivers, assign domains, and tune DC
• generates a notebook cell that ends with Master and diagnostics tabs

EtherCAT Simulator

Builds a small virtual ring for teaching and testing.

• starts with coupler -> inputs -> outputs
• defaults to one loopback path: outputs.ch1 -> inputs.ch1
• simple mode keeps the workflow minimal
• Expert mode exposes device ordering and connection editing
• simple mode generates Introduction, Simulator, and Faults tabs
• expert mode keeps the simulator workspace focused on Simulator and Faults

EtherCAT Visualizer

Builds a compact signal dashboard from the running bus.

• pick signals with checkboxes grouped by slave
• keep the selected signal path short and reorder it directly
• widget type is chosen automatically from the signal direction and bit size
• generate focused signal widgets like led/3, switch/3, and value/3

EtherCAT Slave Explorer

Combines low-level workflows for a selected slave:

• ESC registers
• CoE SDO
• SII EEPROM

Runtime Renders

The main runtime API returns renderable EtherCAT resources:

KinoEtherCAT.master()
KinoEtherCAT.slave(:io_1)
KinoEtherCAT.domain(:main)
KinoEtherCAT.bus()
KinoEtherCAT.dc()

In Livebook, these render as interactive views through Kino.Render.

Use them when you want a resource-oriented runtime surface instead of a generated Smart Cell workflow.

Diagnostics And Simulator Panels

KinoEtherCAT.diagnostics()
KinoEtherCAT.introduction()
KinoEtherCAT.simulator()
KinoEtherCAT.simulator_faults()

• diagnostics/0 is the broad Task Manager style overview
• introduction/0 is the reduced teaching surface
• simulator/0 is the simulator topology and status view
• simulator_faults/0 is the fault injection console

Widgets

Signal-level and slave-panel widgets live under KinoEtherCAT.Widgets.

Signal Widgets

KinoEtherCAT.Widgets.led(:inputs, :ch1, label: "Input 1")
KinoEtherCAT.Widgets.switch(:outputs, :ch1, label: "Output 1")
KinoEtherCAT.Widgets.value(:analog, :temperature, label: "Temperature")

• led/3 is a read-only 1-bit input indicator
• switch/3 writes a 1-bit output
• value/3 displays multi-bit values

Slave Panels

KinoEtherCAT.Widgets.panel(:inputs)
KinoEtherCAT.Widgets.dashboard([:left_io, :right_io], columns: 2)

Use these when you want a compact operator-facing view without the full runtime panels.

Signal widgets and slave panels bind to the session active when they are created. Re-evaluate their cells after restarting the master; old widgets will not write to a replacement session.

Built-in Drivers

KinoEtherCAT ships built-in drivers for a small Beckhoff-focused teaching and bring-up set:

Driver lookup:

KinoEtherCAT.Driver.all()
KinoEtherCAT.Driver.lookup(%{vendor_id: 2, product_code: 0x07113052})

Drivers that should work with the simulator also need a companion MyDriver.Simulator module implementing EtherCAT.Simulator.Adapter.

Custom Drivers

Custom drivers implement EtherCAT.Driver. Provide a signal model and only the codecs needed by the signal directions. Identity enables driver lookup, and describe/1 supplies static endpoint metadata for the UI. For example, a one-bit input driver:

defmodule MyApp.MyDriver do
  @behaviour EtherCAT.Driver

  @impl true
  def identity do
    %{vendor_id: 0x0000_0002, product_code: 0x1234_5678}
  end

  @impl true
  def signal_model(_config, _pdos) do
    [ch1: %EtherCAT.Driver.Signal{pdo_index: 0x1A00}]
  end

  @impl true
  def describe(_config) do
    %{endpoints: [%EtherCAT.Endpoint{signal: :ch1, direction: :input, type: :boolean}]}
  end

  @impl true
  def decode_signal(:ch1, _config, <<0::7, bit::1>>), do: {:ok, bit}
  def decode_signal(_signal, _config, _raw), do: {:error, :invalid_data}
end

License

Apache 2.0. See LICENSE.