Servo

class ingenialink.ethercat.servo.EthercatEmergencyMessage(servo: Servo, emergency_msg: pysoem.Emergency)[source]

Ethercat emergency message class.

Parameters:

servo – The servo that generated the emergency error.
emergency_msg – The emergency message instance from PySOEM.

get_desc() → str | None

Get the error description from the servo’s dictionary.

Returns:: Error description.

class ingenialink.ethercat.servo.EthercatServo(slave: CdefSlave, slave_id: int, dictionary_path: str, servo_status_listener: bool = False, sdo_read_write_release_gil: bool | None = None, disconnect_callback: Callable[[Servo], None] | None = None)[source]

Ethercat Servo instance.

Parameters:

slave – Slave to be connected.
slave_id – Slave ID.
dictionary_path – Path to the dictionary.
connection_timeout – Time in seconds of the connection timeout.
servo_status_listener – Toggle the listener of the servo for its status, errors, faults, etc.
sdo_read_write_release_gil – True to release the GIL in SDO read/write operations, False otherwise. If not specified, default pysoem configuration will be used.
disconnect_callback – Callback function to be called when the servo is disconnected. If not specified, no callback will be called.

Raises:

ImportError – WinPcap is not installed

check_configuration(config_file: str, subnode: int | None = None) → None

Check if the drive is configured in the same way as the given configuration file.

Compares the value of each register in the given file with the corresponding value in the drive.

Parameters:

config_file – the configuration to check
subnode – Subnode of the axis. Defaults to None.

Raises:

ValueError – If a configuration file from a subnode different from 0 is attempted to be loaded to subnode 0.
ValueError – If an invalid subnode is provided.
ILConfigurationError – If the configuration file differs from the drive state.

check_servo_is_in_preoperational_state() → None[source]

Checks if the servo is in preoperational state.

Raises:: ILEcatStateError – if servo is not in preoperational state.

disable(subnode: int = 1, timeout: int = 1000) → None

Disable PDS.

Parameters:

subnode – Subnode of the drive.
timeout – Timeout in milliseconds.

disturbance_disable() → None: Disable disturbance process.

disturbance_enable() → None: Enable disturbance process.

disturbance_get_num_mapped_registers() → int

Obtain the number of disturbance mapped registers.

Returns:: Actual number of mapped registers.

disturbance_remove_all_mapped_registers() → None: Remove all disturbance mapped registers.

disturbance_remove_data() → None: Remove disturbance data.

disturbance_set_mapped_register(channel: int, uid: str, size: int, axis: int | None = None) → None

Set monitoring mapped register.

Parameters:

channel – Identity channel number.
uid – Register uid.
size – Size of data in bytes.
axis – axis. Should be specified if multiaxis, None otherwise.

Raises:

RuntimeError – if the register is not monitoreable.

Write disturbance data.

Parameters:

channels – Channel identifier.
dtypes – Data type.
data_arr – Data array.

Raises:

ILValueError – if the disturbance data cannot be written.

emcy_subscribe(callback: Callable[[EmergencyMessage], None]) → None[source]

Subscribe to emergency messages.

Parameters:: callback – Callable that takes a EmergencyMessage instance as argument.

emcy_unsubscribe(callback: Callable[[EmergencyMessage], None]) → None[source]

Unsubscribe from emergency messages.

Parameters:: callback – Subscribed callback.

enable(subnode: int = 1, timeout: int = 1000) → None

Enable PDS.

Parameters:

subnode – Subnode of the drive.
timeout – Timeout in milliseconds.

Raises:

ILStateError – If a subnode cannot be enabled within the timeout.

fault_reset(subnode: int = 1, timeout: int = 1000) → None

Executes a fault reset on the drive.

Parameters:

subnode – Subnode of the drive.
timeout – Timeout in milliseconds.

generate_pdo_outputs() → None[source]

Process the PDO outputs.

It should call _process_tpdo method using the received bytes as argument.

get_state(subnode: int = 1) → ServoState

Get the current drive state.

Returns:: current drive state.

is_alive() → bool

Checks if the servo responds to a reading a register.

Returns:: Return code with the result of the read.

is_listener_started() → bool

Check if servo listener is started.

Returns:: True if listener is started, else False

load_configuration(config_file: str, subnode: int | None = None, strict: bool = False) → None

Write current dictionary storage to the servo drive.

Parameters:

config_file – Path to the dictionary.
subnode – Subnode of the axis.
strict – Whether to raise an exception if any error occurs during the loading
false (configuration process. If)
ignored. (all errors will only be)
default. (False by)

Raises:

ValueError – If a configuration file from a subnode different from 0 is attempted to be loaded to subnode 0.
ValueError – If an invalid subnode is provided.
ILError – If strict is set to True and any error occurs during the loading
configuration process. –

map_pdos(slave_index: int) → None

Map RPDO and TPDO register into the slave.

WARNING: This operation can not be done if the servo is not in pre-operational state.

Parameters:: slave_index – salve index.

map_rpdos() → None

Map the RPDO registers into the servo slave.

It writes the RPDO maps into the slave, saves the RPDO maps in the _rpdo_maps attribute and adds them to the PDO Assign object.

WARNING: This operation can not be done if the servo is not in pre-operational state.

Raises:: ILError – If there are no available PDOs.

map_tpdos() → None

Map the TPDO registers into the servo slave.

It writes the TPDO maps into the slave, saves the TPDO maps in the _tpdo_maps attribute and adds them to the PDO Assign object

WARNING: This operation can not be done if the servo is not in pre-operational state.

Raises:: ILError – If there are no available PDOs.

monitoring_actual_number_bytes() → int

Get the number of monitoring bytes left to be read.

Returns:: number of monitoring bytes left to be read.

monitoring_channel_data(channel: int) → list[float]

Obtain processed monitoring data of a channel.

Parameters:: channel – Identity channel number.
Returns:: Monitoring data.

monitoring_disable() → None: Disable monitoring process.

monitoring_enable() → None: Enable monitoring process.

monitoring_get_bytes_per_block() → int

Obtain Bytes x Block configured.

Returns:: Actual number of Bytes x Block configured.

monitoring_get_num_mapped_registers() → int

Obtain the number of monitoring mapped registers.

Returns:: Actual number of mapped registers.

monitoring_read_data() → None: Obtain processed monitoring data.

monitoring_remove_all_mapped_registers() → None: Remove all monitoring mapped registers.

monitoring_remove_data() → None: Remove monitoring data.

monitoring_set_mapped_register(channel: int, uid: str, size: int, axis: int | None = None) → None

Set monitoring mapped register.

Parameters:

channel – Identity channel number.
uid – Register uid.
size – Size of data in bytes.
axis – axis. Should be specified if multiaxis, None otherwise.

Raises:

RuntimeError – if the register is not monitoreable.

process_pdo_inputs() → None[source]

Process the PDO inputs.

It should call _process_rpdo method to obtain the bytes to be sent to the slave.

read(reg: str | Register, subnode: int = 1) → int | float | str | bytes

Read a register value from servo.

Parameters:

reg – Register.
subnode – Target axis of the drive.

Returns:

int, float or Value stored in the register.

Raises:

ILAccessError – Wrong access to the register.

read_bitfields(reg: str | Register, subnode: int = 1, bitfields: dict[str, BitField] | None = None) → dict[str, int]

Read bitfields of a register.

Parameters:

reg – Register.
subnode – Target subnode of the drive.
bitfields – Optional bitfield specification. If not it will be used from the register definition (if Any).

Raises:

ValueError – if the register does not have bitfields.
TypeError – if the register is not of integer type.

Returns:

Dictionary with values of the bitfields. Key is the name of the bitfield. Value is the value parsed.

read_complete_access(reg: str | CanopenRegister | EthercatRegister | CanOpenObject, subnode: int = 1, buffer_size: int | None = None) → bytes

Read a complete access register.

Parameters:

reg – Register to be read.
subnode – Target subnode of the drive.
buffer_size – Size of the buffer to read.

Raises:

ValueError – if buffer size is not specified or cannot be detected
TypeError – if the register is not a CanopenRegister or EthercatRegister.

Returns:

Data read from the register.

read_rpdo_map_from_slave(map_obj: str | CanOpenObject, subnode: int = 0, buffer_size: int | None = 0) → RPDOMap[source]

Read the RPDO map from the slave.

Parameters:

map_obj – UID or object of the RPDO map.
subnode – Subnode of the rpdo map.
buffer_size – Size of the buffer to read the pdo map.

Returns:

The RPDO map read from the slave.

Return type:

RPDOMap

read_tpdo_map_from_slave(map_obj: str | CanOpenObject, subnode: int = 0, buffer_size: int | None = None) → TPDOMap[source]

Read the TPDO map from the slave.

Parameters:

map_obj – UID or object of the RPDO map.
subnode – Subnode of the rpdo map.
buffer_size – Size of the buffer to read the pdo map.

Returns:

The TPDO map read from the slave.

Return type:

TPDOMap

register_update_complete_access_subscribe(callback: Callable[[Servo, CanopenRegister | EthercatRegister, int | float | str | bytes, RegisterAccessOperation], None]) → None

Subscribe to complete access register updates.

The callback will be called when a complete access read/write operation occurs.

Parameters:: callback – Callable that takes a Servo and a Register instance as arguments.

register_update_complete_access_unsubscribe(callback: Callable[[Servo, CanopenRegister | EthercatRegister, int | float | str | bytes, RegisterAccessOperation], None]) → None

Unsubscribe to complete access register updates.

Parameters:: callback – Subscribed callback.

register_update_subscribe(callback: Callable[[Servo, Register, int | float | str | bytes], None]) → None

Subscribe to register updates.

The callback will be called when a read/write operation occurs.

Parameters:: callback – Callable that takes a Servo and a Register instance as arguments.

register_update_unsubscribe(callback: Callable[[Servo, Register, int | float | str | bytes], None]) → None

Unsubscribe to register updates.

Parameters:: callback – Subscribed callback.

reload_errors(dictionary: str) → None

Force to reload all dictionary errors.

Parameters:: dictionary – The dictionary path.

remove_rpdo_map(rpdo_map: RPDOMap | None = None, rpdo_map_index: int | None = None) → None

Remove a RPDOMap from the RPDOMap list.

WARNING: This operation can not be done if the servo is not in pre-operational state.

Parameters:

rpdo_map – The RPDOMap instance to be removed.
rpdo_map_index – The map index of the RPDOMap list to be removed.

Raises:

ValueError – If the RPDOMap instance is not in the RPDOMap list.

remove_tpdo_map(tpdo_map: TPDOMap | None = None, tpdo_map_index: int | None = None) → None

Remove a TPDOMap from the TPDOMap list.

Parameters:

tpdo_map – The TPDOMap instance to be removed.
tpdo_map_index – The map index of the TPDOMap list to be removed.

Raises:

ValueError – If the TPDOMap instance is not in the TPDOMap list.

replace_dictionary(dictionary: str) → None

Deletes and creates a new instance of the dictionary.

Parameters:: dictionary – Path to the dictionary.

reset_pdo_mapping() → None

Reset the RPDO and TPDO mapping in the slave.

WARNING: This operation can not be done if the servo is not in pre-operational state.

reset_rpdo_mapping() → None

Delete the RPDO mapping stored in the servo slave.

WARNING: This operation can not be done if the servo is not in pre-operational state.

reset_tpdo_mapping() → None

Delete the TPDO mapping stored in the servo slave.

WARNING: This operation can not be done if the servo is not in pre-operational state.

restore_parameters(subnode: int | None = None) → None

Restore all the current parameters of all the slave to default.

Note

The drive needs a power cycle after this in order for the changes to be properly applied.

Parameters:: subnode – Subnode of the axis. None by default which restores all the parameters.
Raises:: ILError – Invalid subnode.

save_configuration(config_file: str, subnode: int | None = None) → None

Save a drive configuration.

Read all dictionary registers content and put it to the dictionary storage.

Parameters:

config_file – Destination path for the configuration file.
subnode – Subnode of the axis.

Raises:

ILError – if the subnode is invalid.

save_configuration_csv(config_file: str, subnode: int | None = None) → None[source]

Save a drive configuration in CSV format.

Parameters:

config_file – Destination path for the configuration file.
subnode – Subnode of the axis.

Raises:

NotImplementedError – CSV configuration files are only supported for EtherCAT drives.
ILError – if the subnode is invalid.

set_pdo_map_to_slave(rpdo_maps: list[RPDOMap], tpdo_maps: list[TPDOMap]) → None[source]

Callback called by the slave to configure the map.

Parameters:

rpdo_maps – List of RPDO maps.
tpdo_maps – List of TPDO maps.

set_pdo_watchdog_time(timeout: float) → None[source]

Set the process data watchdog time.

Parameters:: timeout – Time in seconds.

start_status_listener() → None: Start listening for servo status events (ServoState).

state_wait_change(state: ServoState, timeout: int, subnode: int = 1) → ServoState

Waits for a state change.

Parameters:

state – Servo state before calling this function.
timeout – Maximum value to wait for the change.
subnode – Subnode of the drive.

Returns:

The last read state.

Raises:

ILTimeoutError – If state does not change in the given time.

status_word_decode(status_word: dict[str, int]) → ServoState

Decodes the status word to a known value.

Parameters:: status_word – Read value for the status word.
Returns:: Status word value.

status_word_wait_change(status_word: int, timeout: int, subnode: int = 1) → None

Waits for a status word change.

Parameters:

status_word – Status word to wait for.
timeout – Maximum value to wait for the change.
subnode – Subnode of the drive.

Raises:

ILTimeoutError – If status word does not change in the given time.

stop_status_listener() → None: Stop listening for servo status events (ServoState).

store_parameters(subnode: int | None = None) → None

Store all the current parameters of the target subnode.

Parameters:

subnode – Subnode of the axis. None by default which stores
parameters. (all the)

Raises:

ILError – Invalid subnode.

subscribe_to_status(callback: Callable[[ServoState, int], Any]) → None

Subscribe to state changes.

Parameters:: callback – Callback function.

teardown() → None[source]: Perform the necessary actions for teardown.

unsubscribe_from_status(callback: Callable[[ServoState, int], Any]) → None

Unsubscribe from state changes.

Parameters:: callback – Callback function.

update_slave_reference(slave: CdefSlave) → None[source]

Update the slave reference.

Parameters:: slave – The new slave reference.

write(reg: str | Register, data: int | float | str | bytes, subnode: int = 1) → None

Writes a data to a target register.

Parameters:

reg – Target register to be written.
data – Data to be written.
subnode – Target axis of the drive.

Raises:

ILAccessError – Wrong access to the register.

write_bitfields(reg: str | Register, values: dict[str, int], subnode: int = 1, bitfields: dict[str, BitField] | None = None) → None

Write bitfields of a register.

Only the values specified will be updated. The register will be read first to prevent overwriting other bits.

Parameters:

reg – Register
values – Dictionary with values of the bitfields. Key is the name of the bitfield. Value is the value to set.
subnode – Target subnode of the drive.
bitfields – Optional bitfield specification. If not it will be used from the register definition (if Any)

Raises:

ValueError – if the register does not have bitfields.
TypeError – if the register is not of integer type.

write_complete_access(reg: str | CanopenRegister | EthercatRegister | CanOpenObject, data: bytes, subnode: int = 1) → None

Write a complete access register.

Parameters:

reg – Register to be written.
data – Data to be written.
subnode – Target subnode of the drive.

Raises:

TypeError – if the register is not a CanopenRegister or EthercatRegister.

property dictionary: EthercatDictionary: Ethercat dictionary.

property disturbance_data: bytes

Obtain disturbance data.

Returns:: Current disturbance data.

property disturbance_data_size: int

Obtain disturbance data size.

Returns:: Current disturbance data size.

property disturbance_number_mapped_registers: int: Get the number of mapped disturbance registers.

property errors: dict[int, DictionaryError]: Errors.

property full_name: str: Drive full name.

property info: dict[str, None | str | int]: Servo information.

property monitoring_data_size: int

Obtain monitoring data size.

Returns:: Current monitoring data size in bytes.

property monitoring_number_mapped_registers: int: Get the number of mapped monitoring registers.

property slave: CdefSlave: Ethercat slave.

property status: dict[int, ServoState]: Servo status.

property subnodes: dict[int, SubnodeType]: Dictionary of subnode ids and their type.

units_acc

Acceleration units.

Type:: ServoUnitsAcc

units_pos

Position units.

Type:: ServoUnitsPos

units_torque

Torque units.

Type:: ServoUnitsTorque

units_vel

Velocity units.

Type:: ServoUnitsVel

class ingenialink.ethercat.servo.SdoOperationMsg(value)[source]: Message for exceptions depending on the operation type.