Servo¶

class ingenialink.ethercat.servo.EthercatServo(cffi_servo, cffi_net, target, dictionary_path=None, servo_status_listener=False)[source]¶

Servo object for all the EtherCAT slave functionalities.

Parameters

cffi_servo (CData) – CData instance of the servo.
cffi_net (CData) – CData instance of the network.
target (int) – Target ID for the slave.
dictionary_path (str) – Path to the dictionary.
servo_status_listener (bool) – Toggle the listener of the servo for its status, errors, faults, etc.

destroy()[source]¶

Destroy servo instance.

Returns: Result code.
Return type: int

disable(subnode=1, timeout=1000)[source]¶

Disable PDS.

Parameters

subnode (int) – Subnode of the drive.
timeout (int) – Timeout in milliseconds.

Raises

ILTimeoutError – The servo could not be disabled due to timeout.
ILError – Failed to disable PDS.

disturbance_channel_data(channel, dtype, data_arr)[source]¶

Send disturbance data.

Parameters

channel (int) – Identity channel number.
dtype (REG_DTYPE) – Data type of the register mapped.
data_arr (array) – Data that will be sent to the drive.

Returns

Return code.

Return type

int

disturbance_disable()[source]¶

Disable disturbance process.

Raises

ILError – If the drive is unable to disable
the disturbance process. –

disturbance_enable()[source]¶

Enable disturbance process.

Raises

ILError – If the drive is unable to enable
the disturbance process. –

disturbance_remove_all_mapped_registers()[source]¶

Remove all disturbance mapped registers.

Raises

ILError – If the drive is unable to remove
the disturbance mapped registers. –

disturbance_remove_data()[source]¶

Remove disturbance data.

Raises

ILError – If the drive is unable to remove
the disturbance data. –

disturbance_set_mapped_register(channel, address, subnode, dtype, size)[source]¶

Set disturbance mapped register.

Parameters

channel (int) – Identity channel number.
address (int) – Register address to map.
dtype (REG_DTYPE) – Data type of the register to map.

Raises

ILError – If the drive is unable to map
the disturbance register. –

disturbance_write_data(channels, dtypes, data_arr)[source]¶

Write disturbance data.

Parameters

channels (int or list of int) – Channel identifier.
dtypes (int or list of int) – Data type.
data_arr (list or list of list) – Data array.

emcy_subscribe(cb)[source]¶

Subscribe to emergency messages.

Parameters: cb – Callback
Returns: Assigned slot.
Return type: int

emcy_unsubscribe(slot)[source]¶

Unsubscribe from emergency messages.

Parameters: slot (int) – Assigned slot when subscribed.

enable(subnode=1, timeout=1000)[source]¶

Enable PDS.

Parameters

subnode (int, optional) – Subnode.
timeout (int) – Timeout in milliseconds.

Raises

ILTimeoutError – The servo could not be enabled due to timeout.
ILError – The servo could not be enabled.

fault_reset(subnode=1, timeout=1000)[source]¶

Fault reset.

Parameters

subnode (int, optional) – Subnode.
timeout (int) – Timeout in milliseconds.

Raises

ILTimeoutError – The servo could not be reset due to timeout.
ILError – Failed to fault reset.

get_state(subnode=1)[source]¶

Obtain state of the servo.

Parameters: subnode (int, optional) – Subnode.
Returns: Servo state and state flags.
Return type: tuple

homing_start()[source]¶: Start the homing procedure.

homing_wait(timeout)[source]¶

Wait until homing completes.

Notes

The homing itself has a configurable timeout. The timeout given here is purely a ‘communications’ timeout, e.g. it could happen that the statusword change is never received. This timeout should be >= than the programmed homing timeout.

Parameters: timeout (int, float) – Timeout (s).

is_alive()[source]¶

Checks if the servo responds to a reading a register.

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

load_configuration(config_file, subnode=None)[source]¶

Load configuration from dictionary file to the servo drive.

Parameters

config_file (str) – Dictionary.
subnode (int) – Target subnode.

monitoring_channel_data(channel, dtype)[source]¶

Obtain processed monitoring data of a channel.

Parameters

channel (int) – Identity channel number.
dtype (REG_DTYPE) – Data type of the register to map.

Returns

Monitoring data.

Return type

array

monitoring_disable()[source]¶

Disable monitoring process.

Raises

ILError – If the drive is unable to disable
the monitoring process. –

monitoring_enable()[source]¶

Enable monitoring process.

Raises

ILError – If the drive is unable to enable
the monitoring process. –

monitoring_get_bytes_per_block()[source]¶

Obtain Bytes x Block configured.

Returns: Actual number of Bytes x Block configured.
Return type: int

monitoring_get_num_mapped_registers()[source]¶

Obtain the number of monitoring mapped registers.

Returns: Actual number of mapped registers.
Return type: int

monitoring_read_data()[source]¶

Obtain processed monitoring data.

Raises

ILError – If the drive is unable to read
the monitoring data. –

monitoring_remove_all_mapped_registers()[source]¶

Remove all monitoring mapped registers.

Raises

ILError – If the drive is unable to remove
the mapped monitoring registers. –

monitoring_remove_data()[source]¶

Remove monitoring data.

Raises

ILError – If the drive is unable to remove
the monitoring data. –

monitoring_set_mapped_register(channel, address, subnode, dtype, size)[source]¶

Set monitoring mapped register.

Parameters

channel (int) – Identity channel number.
address (int) – Register address to map.
subnode (int) – Subnode to be targeted.
dtype (int) – Register data type.
size (int) – Size of data in bytes.

Raises

ILError – If the drive is unable to map
the monitoring register. –

raw_read(reg, subnode=1)[source]¶

Raw read from servo.

Parameters

reg (IPBRegister) – Register.
subnode (int) – Subnode for the register.

Returns

Otained value

Return type

int

Raises

TypeError – If the register type is not valid.

raw_write(reg, data, confirm=True, extended=0, subnode=1)[source]¶

Raw write to servo.

Parameters

reg (IPBRegister) – Register.
data (int) – Data.
confirm (bool, optional) – Confirm write.
extended (int, optional) – Extended frame.
subnode (int) – Subnode for the register.

Raises

TypeError – If any of the arguments type is not valid or unsupported.

read(reg, subnode=1)[source]¶

Read from servo.

Parameters

reg (str, Register) – Register.
subnode (int) – Subnode for the register.

Returns

Obtained value

Return type

float

Raises

TypeError – If the register type is not valid.

read_array_sdo(idx, subidx, length, dtype, slave=1)[source]¶

Read array SDO from network.

Parameters

idx (int) – Register index.
subidx (int) – Register subindex.
length (int) – Array length.
dtype (REG_DTYPE) – Register data type.
slave (int, Optional) – Identifier of an slave in the network.

Returns

Obtained value

Return type

list

Raises

ValueError – If the register type is not valid.

read_sdo(idx, subidx, dtype, slave=1)[source]¶

Read SDO from network.

Parameters

idx (int) – Register index.
subidx (int) – Register subindex.
dtype (REG_DTYPE) – Register data type.
slave (int, Optional) – Identifier of an slave in the network.

Returns

Obtained value

Return type

float

Raises

TypeError – If the register type is not valid.

read_sdo_complete_access(idx, size, slave=1)[source]¶

Read SDO complete access from network.

Parameters

idx (int) – Register index.
size (int) – Size in bytes to read.
slave (int, Optional) – Identifier of an slave in the network.

Returns

Obtained value

Return type

bytes

read_string_sdo(idx, subidx, size, slave=1)[source]¶

Read string SDO from network.

Parameters

idx (int) – Register index.
subidx (int) – Register subindex.
size (int) – Size in bytes to read.
slave (int, Optional) – Identifier of an slave in the network.

Returns

Obtained value

Return type

str

Raises

TypeError – If the register type is not valid.

reload_errors(dictionary)[source]¶

Force to reload all dictionary errors.

Parameters: dictionary (str) – Dictionary.

replace_dictionary(dictionary)[source]¶

Deletes and creates a new instance of the dictionary.

Parameters: dictionary (str) – Dictionary.

reset()[source]¶

Reset servo.

Notes

You may need to reconnect the network after reset.

restore_parameters(subnode=None)[source]¶

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 (int) – Subnode of the axis. None by default which restores
the parameters. (all) –

Raises

ILError – Invalid subnode.
ILObjectNotExist – Failed to write to the registers.

save_configuration(config_file, subnode=None)[source]¶

Read all dictionary registers content and save it to a new dictionary.

Parameters

config_file (str) – Dictionary.
subnode (int) – Target subnode.

start_status_listener()[source]¶: Start listening for servo status events (SERVO_STATE).

stop_status_listener()[source]¶: Stop listening for servo status events (SERVO_STATE).

store_parameters(subnode=None)[source]¶

Store all the current parameters of the target subnode.

Parameters

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

Raises

ILError – Invalid subnode.
ILObjectNotExist – Failed to write to the registers.

subscribe_to_status(callback)[source]¶

Subscribe to state changes.

Parameters: callback – Callback

switch_on(timeout=2.0)[source]¶

Switch on PDS.

This function switches on the PDS but it does not enable the motor. For most application cases, you should only use the enable function.

Parameters

subnode (int) – Subnode of the drive.
timeout (int) – Timeout in milliseconds.

Raises

ILTimeoutError – The servo could not be disabled due to timeout.
ILError – Failed to disable PDS.

units_factor(reg)[source]¶

Obtain units scale factor for the given register.

Parameters: reg (IPBRegister) – Register.
Returns: Scale factor for the given register.
Return type: float

units_update()[source]¶

Update units scaling factors.

Notes

This must be called if any encoder parameter, rated torque or pole pitch are changed, otherwise, the readings conversions will not be correct.

unsubscribe_from_status(callback)[source]¶

Unsubscribe from state changes.

Parameters: callback (function) – Callback function.

wait_reached(timeout)[source]¶

Wait until the servo does a target reach.

Parameters: timeout (int, float) – Timeout (s).

write(reg, data, confirm=True, extended=0, subnode=1)[source]¶

Write to servo.

Parameters

reg (IPBRegister, str) – Register or UID to be written.
data (int) – Data to be written.
confirm (bool, optional) – Confirm write.
extended (int, optional) – Extended frame.
subnode (int) – Subnode for the register.

Raises

TypeError – If any of the arguments type is not valid or unsupported.

write_sdo(idx, subidx, dtype, value, slave=1)[source]¶

Write SDO from network.

Parameters

idx (int) – Register index.
subidx (int) – Register subindex.
dtype (REG_DTYPE) – Register data type.
value (float) – Value to write.
slave (int, Optional) – Identifier of an slave in the network.

Returns

Obtained value

Return type

float

Raises

TypeError – If the register type is not valid.

property dictionary¶: Obtain dictionary of the servo.

property disturbance_data¶

Obtain disturbance data.

Returns: Current disturbance data.
Return type: array

property disturbance_data_size¶

Obtain disturbance data size.

Returns: Current disturbance data size.
Return type: int

property errors¶

Obtain drive errors.

Returns: Current errors.
Return type: dict

property extended_buffer¶

Obtain extended buffer data.

Returns: Current extended buffer data.
Return type: str

property info¶

Servo information.

Type: dict

property mode¶

Obtains Operation mode.

Returns: Current operation mode.
Return type: SERVO_MODE

property monitoring_data¶

Obtain monitoring data.

Warning

This function is deprecated. Please use “monitoring_channel_data” instead.

Returns: Current monitoring data.
Return type: array

property monitoring_data_size¶

Obtain monitoring data size.

Returns: Current monitoring data size.
Return type: int

property ol_frequency¶

Get open loop frequency.

Returns: Open loop frequency (mHz).
Return type: float

property ol_voltage¶

Get open loop voltage.

Returns: Open loop voltage (% relative to DC-bus, -1…1).
Return type: float

property position¶

Get actual position.

Returns: Actual position.
Return type: float

property position_res¶

Get position resolution.

Returns: Position resolution (c/rev/s, c/ppitch/s).
Return type: int

property subnodes¶

Obtain number of subnodes.

Returns: Current number of subnodes.
Return type: int

property torque¶

Get actual torque.

Returns: Actual torque.
Return type: float

property units_acc¶

Acceleration units.

Type: SERVO_UNITS_ACC

property units_pos¶

Position units.

Type: SERVO_UNITS_POS

property units_torque¶

Torque units.

Type: SERVO_UNITS_TORQUE

property units_vel¶

Velocity units.

Type: SERVO_UNITS_VEL

property velocity¶

Get actual velocity.

Returns: Actual velocity.
Return type: float

property velocity_res¶

Get velocity resolution.

Returns: Velocity resolution (c/rev, c/ppitch).
Return type: int