1. Connection and Lifecycle

Before any process data can be exchanged, a voraus_ecat.EtherCAT client must be created, connected to the voraus EtherCAT Master, and brought into the operational state. This page describes that lifecycle. The individual read and write calls are covered in Communication Modes.

1.1. Opening a Connection

The client is created with the generated input and output process images. The connection itself is managed by the voraus_ecat.EtherCAT.connection() context manager: it opens the OPC UA connection to the master when the block is entered and closes it automatically when the block is left, including in the case of an error.

from voraus_ecat import EtherCAT

from fieldbus import Inputs, Outputs

ethercat = EtherCAT(inputs=Inputs(), outputs=Outputs())

with ethercat.connection("opc.tcp://localhost:4840"):
    ethercat.set_op_state()
    # Exchange process data here.

Opening the connection raises voraus_ecat.exceptions.EtherCATError if the master is in the FAILED SETUP state and TimeoutError if the master does not leave the SETUP state in time.

1.2. EtherCAT State Machine

The EtherCAT master and its devices follow the standard EtherCAT state machine, represented by voraus_ecat.State:

  • INIT: No process data communication; only mailbox configuration.

  • PRE_OP: Mailbox communication is active, but no process data is exchanged.

  • SAFE_OP: PDO inputs are updated, while PDO outputs are not yet applied to the devices.

  • OP: PDO inputs and outputs are exchanged. This is the state required for normal operation.

Use voraus_ecat.EtherCAT.get_state() to read the current state and voraus_ecat.EtherCAT.set_state() to request a specific transition.

1.3. Reaching the Operational State

After the connection has been opened, the master is not yet operational. Call voraus_ecat.EtherCAT.set_op_state() to transition to the OP state before reading or writing PDOs. It is a shorthand for set_state(State.OP). Both calls block until the state is reached or raise TimeoutError if the state is not reached within the given timeout.

1.4. Exchanging Process Data

Once the master is in the OP state, PDO inputs and outputs can be exchanged. Depending on the configured communication mode, this is done either explicitly or instantly. See Communication Modes for details.

The health of the master application can be queried at any time with voraus_ecat.EtherCAT.get_system_info(). For recovering from error states, see Error Handling.