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.MasterVersionError if the version of the master is not compatible with this client.

1.2. EtherCAT State Machine

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

  • NONE: No state is known. The master only publishes this state, it cannot be requested.

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

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

  • BOOT: Bootstrap state of a device. It exists only for devices, the master neither reports nor accepts it.

  • 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. Only INIT, PRE_OP, SAFE_OP and OP can be requested.

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. If the master rejects the request, e.g. a request for OP while the master application is in the ERROR state, they raise voraus_ecat.exceptions.StateRequestError.

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.

Besides the EtherCAT state of the bus, the master application has a state of its own, represented by voraus_ecat.SystemState. It is returned together with the current error by voraus_ecat.EtherCAT.get_system_info(), and voraus_ecat.EtherCAT.wait_for_state() blocks until a given state is reached. The states and their transitions are described in the State Machine documentation of the master. For recovering from error states, see Error Handling.