Welcome to Maxon EPOS CANopen Library’s documentation!

Date:Apr 09, 2019 Version:0.1 Author:Bruno Tibério Contact:bruno.tiberio@tecnico.ulisboa.pt

This documentation describes the class Epos developed in Python using CANopen to control the Maxon Motors EPOS 70/10 device.

Epos Class description

class epos.Epos(_network=None, debug=False)

begin(nodeID, _channel='can0', _bustype='socketcan', object_dictionary=None)

Initialize Epos device

Configure and setup Epos device.

Parameters:

• nodeID – Node ID of the device.
• _channel (optional) – Port used for communication. Default can0
• _bustype (optional) – Port type used. Default socketcan.
• object_dictionary (optional) – Name of EDS file, if any available.

Returns:

A boolean if all went ok.

Return type:

bool

change_state(new_state)

Change EPOS state

Change Epos state using controlWord object

To change Epos state, a write to controlWord object is made. The bit change in controlWord is made as shown in the following table:

State	LowByte of Controlword [binary]
shutdown	0xxx x110
switch on	0xxx x111
disable voltage	0xxx xx0x
quick stop	0xxx x01x
disable operation	0xxx 0111
enable operation	0xxx 1111
fault reset	1xxx xxxx

see section 8.1.3 of firmware for more information

Parameters:new_state – string with state witch user want to switch. Returns:boolean if all went ok and no error was received. Return type:bool

check_state()

Check current state of Epos

Ask the StatusWord of EPOS and parse it to return the current state of EPOS.

State	ID	Statusword [binary]
Start	0	x0xx xxx0 x000 0000
Not Ready to Switch On	1	x0xx xxx1 x000 0000
Switch on disabled	2	x0xx xxx1 x100 0000
ready to switch on	3	x0xx xxx1 x010 0001
switched on	4	x0xx xxx1 x010 0011
refresh	5	x1xx xxx1 x010 0011
measure init	6	x1xx xxx1 x011 0011
operation enable	7	x0xx xxx1 x011 0111
quick stop active	8	x0xx xxx1 x001 0111
fault reaction active (disabled)	9	x0xx xxx1 x000 1111
fault reaction active (enabled)	10	x0xx xxx1 x001 1111
Fault	11	x0xx xxx1 x000 1000

see section 8.1.1 of firmware manual for more details.

Returns:numeric identification of the state or -1 in case of fail. Return type:int

emcy_error_print(emcy_error)

Print any EMCY Error Received on CAN BUS

load_config()

Load all configurations

log_debug(message=None)

Log a message with debug level

A wrap around logging. The log message will have the following structure: [class name : function name ] message

the function name will be the caller function retrieved automatically by using sys._getframe(1).f_code.co_name

Parameters:message – a string with the message.

log_info(message=None)

Log a message

A wrap around logging. The log message will have the following structure: [class name : function name ] message

Parameters:message – a string with the message.

print_controlword(controlword=None)

Print the meaning of controlword

Check the meaning of current controlword of device or check the meaning of your own controlword. Useful to check your own controlword before actually sending it to device.

Parameters:controlword (optional) – If None, request the controlword of device.

print_current_control_parameters()

Print the current mode control PI gains

Request current mode control parameter gains from device and print.

print_motor_config()

Print current motor config

Request current motor config and print it

print_op_mode()

Print current operation mode

print_position_control_parameters()

Print position control mode parameters

Request device for the position control mode parameters and prints it.

print_sensor_config()

Print current sensor configuration

print_software_pos_limit()

Print current software position limits

read_controlword()

Read ControlWord

Request current controlword from device.

Returns:A tuple containing:

controlword:the current controlword or None if any error. ok:A boolean if all went ok.

Return type:tuple

read_current_control_parameters()

Read the PI gains used in current control mode

Returns:A tuple containing:

gains:A dictionary with the current pGain and iGain ok:A boolean if all went as expected or not.

Return type:tuple

read_current_mode_setting()

Read current value set

Asks EPOS for the current value set in current control mode.

Returns:A tuple containing:

current:value set. ok:a boolean if successful or not.

Return type:tuple

read_current_value()

Read current value

Returns:a tuple containing:

current:current in mA. ok:A boolean if all requests went ok or not.

Return type:tuple

read_current_value_averaged()

Read current averaged value

Returns:a tuple containing:

current:current averaged in mA. ok:A boolean if all requests went ok or not.

Return type:tuple

read_following_error()

Returns the current following error

Read the current following error value which is the difference between actual value and desired value.

Returns:a tuple containing:

following_error:  value of actual following error. ok:A boolean if all requests went ok or not.

Return type:tuple

read_max_following_error()

Read the Max following error

Read the max following error value which is the maximum allowed difference between actual value and desired value in modulus.

Returns:a tuple containing:

max_following_error:  value of max following error. ok:A boolean if all requests went ok or not.

Return type:tuple

read_motor_config()

Read motor configuration

Read the current motor configuration

Requests from EPOS the current motor type and motor data. The motor_config is a dictionary containing the following information:

• motor_type describes the type of motor.
• current_limit - describes the maximum continuous current limit.
• max_current_limit - describes the maximum allowed current limit. Usually is set as two times the continuous current limit.
• pole_pair_number - describes the pole pair number of the rotor of the brushless DC motor.
• max_speed - describes the maximum allowed speed in current mode.
• thermal_time_constant - describes the thermal time constant of motor winding is used to calculate the time how long the maximal output current is allowed for the connected motor [100 ms].

If unable to request the configuration or unsuccessfully, None and false is returned .

Returns:A tuple with:

motor_config:A structure with the current configuration of motor ok:A boolean if all went as expected or not.

Return type:tuple

read_object(index, subindex)

Reads an object

Request a read from dictionary object referenced by index and subindex.

Parameters:

• index – reference of dictionary object index
• subindex – reference of dictionary object subindex

Returns:

message returned by EPOS or empty if unsuccessful

Return type:

bytes

read_op_mode()

Read current operation mode

Returns:A tuple containing:

op_mode:current op_mode or None if request fails ok:A boolean if successful or not

Return type:tuple

read_position_control_parameters()

Read position mode control parameters

Read position mode control PID gains and and feedfoward and acceleration values

Returns:A tuple containing:

pos_mode_parameters:  a dictionary containing pGain, iGain, dGain, vFeed and aFeed. ok:A boolean if all went as expected or not.

Return type:tuple

read_position_mode_setting()

Reads the set desired Position

Ask Epos device for demand position object. If a correct request is made, the position is placed in answer. If not, an answer will be empty

Returns:A tuple containing:

position:the demanded position value. ok:A boolean if all requests went ok or not.

Return type:tuple

read_position_value()

Read current position value

Returns:a tuple containing:

position:current position in quadrature counts. ok:A boolean if all requests went ok or not.

Return type:tuple

read_position_window()

Read current position Window value.

Position window is the modulus threshold value in which the output is considered to be achieved.

Returns:a tuple containing:

position_window:  current position window in quadrature counts. ok:A boolean if all requests went ok or not.

Return type:tuple

read_position_window_time()

Read current position Window time value.

Position window time is the minimum time in milliseconds in which the output must be inside the position window for the target is considered to have been reached.

Returns:a tuple containing:

position_window_time:  current position window time in milliseconds. ok:A boolean if all requests went ok or not.

Return type:tuple

read_quickstop_deceleration()

Read the quick stop deceleration.

Read deceleration used in fault reaction state.

Returns:A tuple containing:

quickstop_deceleration:  The value of deceleration in rpm/s. ok:A boolean if all went as expected or not.

Return type:tuple

read_sensor_config()

Read sensor configuration

Requests from EPOS the current sensor configuration. The sensor_config is an structure containing the following information:

• sensorType - describes the type of sensor.
• pulseNumber - describes the number of pulses per revolution in one channel.
• sensorPolarity - describes the of each sensor.

If unable to request the configuration or unsucessfull, an empty structure is returned. Any error inside any field requests are marked with ‘error’.

Returns:A tuple containing:

sensor_config:A dictionary with the current configuration of the sensor ok:A boolean if all went as expected or not.

Return type:tuple

read_software_pos_limit()

Read the software position limit

Returns:A tuple containing:

limits:a dictionary containing minPos and maxPos ok:A boolean if all went as expected or not.

Return type:tuple

read_statusword()

Read StatusWord

Request current statusword from device.

Returns:A tuple containing:

statusword:the current statusword or None if any error. ok:A boolean if all went ok.

Return type:tuple

read_velocity_mode_setting()

Reads the set desired velocity

Asks EPOS for the desired velocity value in velocity control mode

Returns:A tuple containing:

velocity:Value set or None if any error. ok:A boolean if successful or not.

Return type:tuple

read_velocity_value()

Read current velocity value

Returns:a tuple containing:

velocity:current velocity in rpm. ok:A boolean if all requests went ok or not.

Return type:tuple

read_velocity_value_averaged()

Read current velocity averaged value

Returns:a tuple containing:

velocity:current velocity in rpm. ok:A boolean if all requests went ok or not.

Return type:tuple

save_config()

Save all configurations

set_current_control_parameters(pGain, iGain)

Set the PI gains used in current control mode

Parameters:

• pGain – Proportional gain.
• iGain – Integral gain.

Returns:

A boolean if all went as expected or not.

Return type:

bool

set_current_mode_setting(current)

Set desired current

Set the value for desired current in current control mode

Parameters:current – the value to be set [mA] Returns:a boolean if successful or not Return type:bool

set_max_following_error(max_following_error)

Set the Max following error

The Max Following Error is the maximum permissible difference between demanded and actual position at any time of evaluation. It serves as a safety and motion-supervising feature. If the following error becomes too high, this is a sign of something going wrong. Either the drive cannot reach the required speed or it is even blocked.

Parameters:max_following_error – The value of maximum following error. Returns:A boolean if all requests went ok or not. Return type:bool

set_motor_config(motor_type, current_limit, max_speed, pole_pair_number)

Set motor configuration

Sets the configuration of the motor parameters. The valid motor type is:

motorType	value	Description
DC motor	1	brushed DC motor
Sinusoidal PM BL motor	10	EC motor sinus commutated
Trapezoidal PM BL motor	11	EC motor block commutated

The current limit is the current limit is the maximal permissible continuous current of the motor in mA. Minimum value is 0 and max is hardware dependent.

The output current limit is recommended to be 2 times the continuous current limit.

The pole pair number refers to the number of magnetic pole pairs (number of poles / 2) from rotor of a brushless DC motor.

The maximum speed is used to prevent mechanical destroys in current mode. It is possible to limit the velocity [rpm]

Thermal winding not changed, using default 40ms.

Parameters:

• motor_type – value of motor type. see table behind.
• current_limit – max continuous current limit [mA].
• max_speed – max allowed speed in current mode [rpm].
• pole_pair_number – number of pole pairs for brushless DC motors.

Returns:

A boolean if all requests went ok or not.

Return type:

bool

set_op_mode(op_mode)

Set Operation mode

Sets the operation mode of Epos. OpMode is described as:

OpMode	Description
6	Homing Mode
3	Profile Velocity Mode
1	Profile Position Mode
-1	Position Mode
-2	Velocity Mode
-3	Current Mode
-4	Diagnostic Mode
-5	MasterEncoder Mode
-6	Step/Direction Mode

Parameters:op_mode – the desired opMode. Returns:A boolean if all requests went ok or not. Return type:bool

set_position_control_parameters(pGain, iGain, dGain, vFeed=0, aFeed=0)

Set position mode control parameters

Set position control PID gains and feedfoward velocity and acceleration values.

Feedback and Feed Forward

PID feedback amplification

PID stands for Proportional, Integral and Derivative control parameters. They describe how the error signal e is amplified in order to produce an appropriate correction. The goal is to reduce this error, i.e. the deviation between the set (or demand) value and the measured (or actual) value. Low values of control parameters will usually result in a sluggish control behavior. High values will lead to a stiffer control with the risk of overshoot and at too high an amplification, the system may start oscillating.

Feed-forward

With the PID algorithms, corrective action only occurs if there is a deviation between the set and actual values. For positioning systems, this means that there always is – in fact, there has to be a position error while in motion. This is called following error. The objective of the feedforward control is to minimize this following error by taking into account the set value changes in advance. Energy is provided in an open-loop controller set-up to compensate friction and for the purpose of mass inertia acceleration. Generally, there are two parameters available in feed-forward. They have to be determined for the specific application and motion task:

• Speed feed-forward gain: This component is multiplied by the demanded speed and compensates for speed-proportional friction.
• Acceleration feed-forward correction: This component is related to the mass inertia of the system and provides sufficient current to accelerate this inertia.

Incorporating the feed forward features reduces the average following error when accelerating and decelerating. By combining a feed-forward control and PID, the PID controller only has to correct the residual error remaining after feed-forward, thereby improving the system response and allowing very stiff control behavior.

According to Position Regulation with Feed Forward the acceleration and velocity feed forward take effect in Profile Position Mode and Homing Mode. There is no influence to all the other operation modes like Position Mode, Profile Velocity Mode, Velocity Mode and Current Mode

Parameters:

• pGain – Proportional gain value
• iGain – Integral gain value
• dGain – Derivative gain value
• vFeed – velocity feed forward gain value. Default to 0
• aFeed – acceleration feed forward gain value. Default to 0

Returns:

A boolean if all requests went ok or not

Return type:

OK

set_position_mode_setting(position)

Sets the desired Position

Ask Epos device to define position mode setting object.

Returns:A boolean if all requests went ok or not. Return type:bool

set_position_window(position_window)

Set position Window value

Position window is the modulus threshold value in which the output is considered to be achieved.

Parameters:position_window – position window in quadrature counts Returns:A boolean if all requests went ok or not. Return type:bool

set_position_window_time(position_window_time)

Set position Window Time value

Position window time is the minimum time in milliseconds in which the output must be inside the position window for the target is considered to have been reached.

Parameters:position_window_time – position window time in milliseconds. Returns:A boolean if all requests went ok or not. Return type:bool

set_quick_stop_deceleration(quickstop_deceleration)

Set the quick stop deceleration.

The quick stop deceleration defines the deceleration during a fault reaction.

Parameters:quickstop_deceleration – the value of deceleration in rpm/s Returns:A boolean if all went as expected or not. Return type:bool

set_sensor_config(pulse_number, sensor_type, sensor_polarity)

Change sensor configuration

Change the sensor configuration of motor. Only possible if in disable state The encoder pulse number should be set to number of counts per revolution of the connected incremental encoder. range : [16 - 7500]

sensor type is described as:

value	description
1	Incremental Encoder with index (3-channel)
2	Incremental Encoder without index (2-channel)
3	Hall Sensors (Remark: consider worse resolution)

sensor polarity is set by setting the corresponding bit from the word:

Bit	description
15-2	Reserved (0)
1	Hall sensors polarity 0: normal / 1: inverted
0	Encoder polarity 0: normal 1: inverted (or encoder mounted on motor shaft side)

Parameters:

• pulse_number – Number of pulses per revolution.
• sensor_type – 1,2 or 3 according to the previous table.
• sensor_polarity – a value between 0 and 3 describing the polarity of sensors as stated before.

Returns:

A boolean if all went as expected or not.

Return type:

bool

set_software_pos_limit(min_pos, max_pos)

Set the software position limits

Use encoder readings as limit position for extremes range = [-2147483648 | 2147483647]

Parameters:

• min_pos – minimum position limit
• max_pos – maximum position limit

Returns:

A boolean if all went as expected or not.

Return type:

bool

set_velocity_mode_setting(velocity)

Set desired velocity

Set the value for desired velocity in velocity control mode.

Parameters:velocity – value to be set. Returns:a boolean if successful or not. Return type:bool

write_controlword(controlword)

Send controlword to device

Parameters:controlword – word to be sent. Returns:a boolean if all went ok. Return type:bool

write_object(index, subindex, data)

Write an object

Request a write to dictionary object referenced by index and subindex.

Parameters:

• index – reference of dictionary object index
• subindex – reference of dictionary object subindex
• data – data to be stored

Returns:

boolean if all went ok or not

Return type:

bool

Indices and tables

• Index
• Search Page