3. voraus_ecat package
The Python client API for the voraus auxiliary EtherCAT master.
- class voraus_ecat.EtherCAT(inputs, outputs, instant_communication=False, virtual=False)
Bases:
EtherCAT[InputsT,OutputsT],Generic[InputsT,OutputsT]Initializes the EtherCAT bus client.
- Parameters:
inputs (
TypeVar(InputsT, bound=ProcessData)) – The process image inputs.outputs (
TypeVar(OutputsT, bound=ProcessData)) – The process image outputs.instant_communication (
bool) – Enables the instant communication mode. Defaults to False.virtual (
bool) – Enables PDO input writing if the master is in virtual mode. Defaults to False.
- connection(url, skip_virtual_pdo_init=False)
Creates an OPC UA connection to the EtherCAT master.
- Parameters:
url (
str) – The URL of the EtherCAT master.skip_virtual_pdo_init (
bool) – Skip the PDO initialization during virtual mode.
- Yields:
None.
- Raises:
EtherCATError – If master is in ‘FAILED SETUP’ state
TimeoutError – If master is stuck in SETUP state
- Return type:
Generator[None,None,None]
- continue_with_error()
Forces the master application to continue operation if it is in state ERROR_TRANSITION or ERROR.
- Return type:
None
- get_state()
Gets the EtherCAT state of the master.
- Return type:
- Returns:
The EtherCAT state of the master.
- get_system_info()
Fetches current state and error information from the EtherCAT master application.
- Return type:
- Returns:
State and error information from the EtherCAT master application.
- read_pdo_inputs(*pdos)
Reads the PDO inputs from the OPC UA server if instant communication mode is disabled.
- read_pdo_outputs(*pdos)
Reads the PDO outputs from the OPC UA server if instant communication mode is disabled.
- read_pdos(*pdos)
Reads the PDO values from the OPC UA server if instant communication mode is disabled.
This method reads all PDO input and output values from the EtherCAT master, or only the specified PDOs if provided.
- property sdo: SDO
Get the SDO interface for reading and writing SDO objects.
- Returns:
The SDO interface.
- set_op_state(timeout=10.0)
Sets the state of the EtherCAT master to OP (operational).
- Parameters:
timeout (
float) – The timeout in seconds. Defaults to 10.0.- Return type:
None
- set_state(state, timeout=10)
Sets the state of the EtherCAT master.
- Parameters:
state (
int|State) – The requested state.timeout (
float) – The timeout in seconds. Defaults to 10.
- Raises:
TimeoutError – If the state is not reached within timeout.
- Return type:
None
- wait_for_state(state, timeout=-1.0)
Waits until the master application is in the specified state.
- Parameters:
state (
SystemState) – The state to wait for.timeout (
float) – The timeout in seconds. Defaults to -1.0 (infinite)
- Raises:
TimeoutError – If the state is not reached within timeout.
- Return type:
None
- class voraus_ecat.PDO(name)
Bases:
PDO[PDOT],Generic[PDOT]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- get()
Reads and decodes the value of the descriptor.
Note
This value represents the last value received by the EtherCAT master using
voraus_ecat.EtherCAT.read_pdos()or if instant communication mode is enabled, the value will be requested from the OPC UA server.If you need to access the last pending value (which has not been sent yet) use
voraus_ecat.PDO.get_pending().- Raises:
RuntimeError – If you try to read the output value in cyclic mode without calling the read method before.
PDOError – If reading the value failed (e.g. if the master is not in the required state).
- Return type:
TypeVar(PDOT)- Returns:
The value of the input.
- get_pending()
Reads the last value, which has not been sent to the EtherCAT master yet.
This method should be used if you want to manipulate a value multiple times before it gets written to the EtherCAT master using
voraus_ecat.EtherCAT.write_pdos(). This is helpful when working with bit masks for multiple outputs mapped to one integer PDO.Note
This method is not available in instant communication mode.
This method is available for outputs and, in virtual mode, also for inputs.
If you need to access the last received value to ensure a PDO has been set properly use
voraus_ecat.PDO.get().The methods
voraus_ecat.EtherCAT.read_pdos()andvoraus_ecat.EtherCAT.read_pdo_outputs()will not update the value stored byvoraus_ecat.PDO.set(). After calling the methodvoraus_ecat.EtherCAT.write_pdos(), this method will return the last value read byvoraus_ecat.EtherCAT.read_pdos().- Raises:
RuntimeError – If the EtherCAT client runs in instant communication mode.
- Return type:
TypeVar(PDOT)- Returns:
The pending value of the pdo.
- class voraus_ecat.ProcessData
Bases:
ProcessDataInitializes the EtherCAT process data inputs or outputs.
- class voraus_ecat.SDO(node_coe)
Bases:
SDOInitializes the SDO helper.
- Parameters:
node_coe (
ProtectedOptional[SyncNode]) – OPC UA CoE node accessor.
- poll_read(request_id)
Polls an asynchronous SDO upload operation (upload = read from slave).
- Parameters:
request_id (
int) – Request ID returned bystart_read.- Return type:
- Returns:
The polled read operation state.
- Raises:
SDOError – If polling the SDO read operation failed.
- poll_write(request_id)
Polls an asynchronous SDO download operation (download = write to slave).
- Parameters:
request_id (
int) – Request ID returned bystart_write.- Return type:
- Returns:
The polled write operation state.
- Raises:
SDOError – If polling the SDO write operation failed.
- read_bytes(slave_index, descriptor, size, timeout_ms=500)
Reads SDO data from the slave synchronously on top of start/poll operations (“SDO upload”).
- Parameters:
slave_index (
int) – Slave index.descriptor (
SDODescriptor) – SDO descriptor containing index and subindex.size (
int) – Number of bytes to read.timeout_ms (
int) – Timeout in milliseconds. Defaults to 500 ms.
- Return type:
bytes- Returns:
The read byte payload (little-endian).
- Raises:
SDOError – If the SDO read operation fails.
- start_read(slave_index, descriptor, size, timeout_ms=500)
Starts an asynchronous SDO upload operation (upload = read from slave).
- Parameters:
slave_index (
int) – Slave index.descriptor (
SDODescriptor) – SDO descriptor containing index and subindex.size (
int) – Number of bytes to read.timeout_ms (
int) – Timeout in milliseconds. Defaults to 500 ms.
- Return type:
int- Returns:
The request ID for polling the operation status.
- Raises:
SDOError – If the SDO read start operation failed.
- start_write(slave_index, descriptor, data, timeout_ms=500)
Starts an asynchronous SDO download operation (download = write to slave).
- Parameters:
slave_index (
int) – Slave index.descriptor (
SDODescriptor) – SDO descriptor containing index and subindex.data (
bytes) – Raw payload bytes (little-endian).timeout_ms (
int) – Timeout in milliseconds. Defaults to 500 ms.
- Return type:
int- Returns:
The request ID for polling the operation status.
- Raises:
SDOError – If the SDO write start operation failed.
- write_bytes(slave_index, descriptor, data, timeout_ms=500)
Writes SDO data to the slave synchronously on top of start/poll operations (“SDO download”).
- Parameters:
slave_index (
int) – Slave index.descriptor (
SDODescriptor) – SDO descriptor containing index and subindex.data (
bytes) – Raw payload bytes (little-endian).timeout_ms (
int) – Timeout in milliseconds. Defaults to 500 ms.
- Raises:
SDOError – If the SDO write operation fails.
- Return type:
None
- class voraus_ecat.SDOReadPollResult(done: bool, success: bool, data: bytes, abort_code: int)
Bases:
NamedTupleCreate new instance of SDOReadPollResult(done, success, data, abort_code)
- class voraus_ecat.SDOWritePollResult(done: bool, success: bool, abort_code: int)
Bases:
NamedTupleCreate new instance of SDOWritePollResult(done, success, abort_code)
- class voraus_ecat.State(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
IntEnumRepresents the EtherCAT states.
- class voraus_ecat.SystemInfo(state=SystemState.SETUP, error_number=0, error_message='')
Bases:
objectContains Information about the current state of the EtherCAT master application.
-
state:
SystemState= 0
-
state:
- class voraus_ecat.SystemState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
IntEnumRepresents the EtherCAT Application states.
3.1. Submodules
3.2. voraus_ecat.exceptions module
Contains custom exceptions used by this package.
3.3. voraus_ecat.pdo module
The public-facing interface for PDOs.
- class voraus_ecat.pdo.ArrayOfDInt(name)
Bases:
_ArrayOfDInt,PDO[list[int]]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.ArrayOfInt(name)
Bases:
_ArrayOfInt,PDO[list[int]]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.ArrayOfSInt(name)
Bases:
_ArrayOfSInt,PDO[list[int]]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.ArrayOfUDint(name)
Bases:
_ArrayOfUDint,PDO[list[int]]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit1(name)
Bases:
_Bit1,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit10(name)
Bases:
_Bit10,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit11(name)
Bases:
_Bit11,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit12(name)
Bases:
_Bit12,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit13(name)
Bases:
_Bit13,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit14(name)
Bases:
_Bit14,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit15(name)
Bases:
_Bit15,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit16(name)
Bases:
_Bit16,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit2(name)
Bases:
_Bit2,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit3(name)
Bases:
_Bit3,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit4(name)
Bases:
_Bit4,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit5(name)
Bases:
_Bit5,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit6(name)
Bases:
_Bit6,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit7(name)
Bases:
_Bit7,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit8(name)
Bases:
_Bit8,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Bit9(name)
Bases:
_Bit9,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.BitArr16(name)
Bases:
_BitArr16,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.BitArr32(name)
Bases:
_BitArr32,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.BitArr8(name)
Bases:
_BitArr8,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Boolean(name)
Bases:
_Boolean,PDO[bool]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Byte(name)
Bases:
_Byte,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.DWord(name)
Bases:
_DWord,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Guid(name)
Bases:
_Guid,PDO[UUID]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Integer16(name)
Bases:
_Integer16,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Integer24(name)
Bases:
_Integer24,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Integer32(name)
Bases:
_Integer32,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Integer40(name)
Bases:
_Integer40,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Integer48(name)
Bases:
_Integer48,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Integer56(name)
Bases:
_Integer56,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Integer64(name)
Bases:
_Integer64,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Integer8(name)
Bases:
_Integer8,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.OctetString(name)
Bases:
_OctetString,PDO[list[int]]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Real32(name)
Bases:
_Real32,PDO[float]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Real64(name)
Bases:
_Real64,PDO[float]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.UnicodeString(name)
Bases:
_UnicodeString,PDO[list[int]]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unknown(name)
Bases:
_Unknown,PDO[list[int]]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unsigned16(name)
Bases:
_Unsigned16,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unsigned24(name)
Bases:
_Unsigned24,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unsigned32(name)
Bases:
_Unsigned32,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unsigned40(name)
Bases:
_Unsigned40,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unsigned48(name)
Bases:
_Unsigned48,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unsigned56(name)
Bases:
_Unsigned56,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unsigned64(name)
Bases:
_Unsigned64,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Unsigned8(name)
Bases:
_Unsigned8,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.VisibleString(name)
Bases:
_VisibleString,PDO[str]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.
- class voraus_ecat.pdo.Word(name)
Bases:
_Word,PDO[int]Initializes the PDO.
- Parameters:
name (
str) – The name of the PDO OPC UA node.