Connection module

This module contain the Connection class communicate with Dynamixel units.

class pyax12.connection.Connection(port='/dev/ttyUSB0', baudrate=57600, timeout=0.1, waiting_time=0.02)[source]

Create a serial connection with dynamixel actuators.

Parameters:
  • port (str) – the serial device to connect with (e.g. ‘/dev/ttyUSB0’ for Unix users or ‘COM1’ for windows users).
  • baudrate (int) – the baudrate speed (e.g. 57600).
  • timeout (float) – the timeout value for the connection.
  • waiting_time (float) – the waiting time (in seconds) between sending the instruction packet and the receiving the status packet.
close()[source]

Close the serial connection.

dump_control_table(dynamixel_id)[source]

Dump the control table of the specified Dynamixel unit.

This function can be used to backup the current configuration of the given Dynamixel unit.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
Returns:the sequence of all bytes in currently the control table.
flush()[source]

Flush the connection buffers.

get_baud_rate(dynamixel_id)[source]

Return the communication speed (baud rate) of the specified Dynamixel unit.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_ccw_angle_limit(dynamixel_id)[source]

Return the counter clockwise angle limit of the specified Dynamixel unit.

The goal position should be lower or equal than this value, otherwise the Angle Limit Error Bit (the second error bit of Status Packets) will be set to 1.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_ccw_compliance_margin(dynamixel_id)[source]

Return the counter clockwise compliance margin of the specified Dynamixel unit.

The compliance feature can be utilized for absorbing shocks at the output shaft.

     CW
      ▲
      │━━━━━━━━━━     goal position
      │         :╲          :
      │         : ╲         :
      │         :  ╲        :
      │         :   ╲       :
      │         :    ╲      :
      │         :     ┃     :
      │         :     ┃     ▽
CCW ──┼───────────────┺━━━━━━━━━━━┱─────────────▶ CW
      │         :     :     :     ┃
      │         :     :     :     ┃
      │         :     :     :     :╲
      │         :     :     :     : ╲
      │         :     :     :     :  ╲
      │         :     :     :     :   ╲
      │         :     :     :     :    ╲▂▂▂▂▂▂▂▂
      │         :     :     :     :     :
     CCW         ◀───▶ ◀───▶ ◀───▶ ◀───▶
                   A     B     C     D

x axis: position error
y axis: output torque

A: CCW Compliance Slope
B: CCW Compliance Margin
C: CW Compliance Slope
D: CW Compliance Margin
Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_ccw_compliance_slope(dynamixel_id)[source]

Return the counter clockwise compliance scope of the specified Dynamixel unit.

The compliance feature can be utilized for absorbing shocks at the output shaft.

     CW
      ▲
      │━━━━━━━━━━     goal position
      │         :╲          :
      │         : ╲         :
      │         :  ╲        :
      │         :   ╲       :
      │         :    ╲      :
      │         :     ┃     :
      │         :     ┃     ▽
CCW ──┼───────────────┺━━━━━━━━━━━┱─────────────▶ CW
      │         :     :     :     ┃
      │         :     :     :     ┃
      │         :     :     :     :╲
      │         :     :     :     : ╲
      │         :     :     :     :  ╲
      │         :     :     :     :   ╲
      │         :     :     :     :    ╲▂▂▂▂▂▂▂▂
      │         :     :     :     :     :
     CCW         ◀───▶ ◀───▶ ◀───▶ ◀───▶
                   A     B     C     D

x axis: position error
y axis: output torque

A: CCW Compliance Slope
B: CCW Compliance Margin
C: CW Compliance Slope
D: CW Compliance Margin
Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_control_table_tuple(dynamixel_id)[source]

Return the control table of the specified Dynamixel unit in an easily human readable tuple.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_cw_angle_limit(dynamixel_id)[source]

Return the clockwise angle limit of the specified Dynamixel unit.

The goal position should be higher or equal than this value, otherwise the Angle Limit Error Bit (the second error bit of Status Packets) will be set to 1.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_cw_compliance_margin(dynamixel_id)[source]

Return the clockwise compliance margin of the specified Dynamixel unit.

The compliance feature can be utilized for absorbing shocks at the output shaft.

     CW
      ▲
      │━━━━━━━━━━     goal position
      │         :╲          :
      │         : ╲         :
      │         :  ╲        :
      │         :   ╲       :
      │         :    ╲      :
      │         :     ┃     :
      │         :     ┃     ▽
CCW ──┼───────────────┺━━━━━━━━━━━┱─────────────▶ CW
      │         :     :     :     ┃
      │         :     :     :     ┃
      │         :     :     :     :╲
      │         :     :     :     : ╲
      │         :     :     :     :  ╲
      │         :     :     :     :   ╲
      │         :     :     :     :    ╲▂▂▂▂▂▂▂▂
      │         :     :     :     :     :
     CCW         ◀───▶ ◀───▶ ◀───▶ ◀───▶
                   A     B     C     D

x axis: position error
y axis: output torque

A: CCW Compliance Slope
B: CCW Compliance Margin
C: CW Compliance Slope
D: CW Compliance Margin
Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_cw_compliance_slope(dynamixel_id)[source]

Return the clockwise compliance scope of the specified Dynamixel unit.

The compliance feature can be utilized for absorbing shocks at the output shaft.

     CW
      ▲
      │━━━━━━━━━━     goal position
      │         :╲          :
      │         : ╲         :
      │         :  ╲        :
      │         :   ╲       :
      │         :    ╲      :
      │         :     ┃     :
      │         :     ┃     ▽
CCW ──┼───────────────┺━━━━━━━━━━━┱─────────────▶ CW
      │         :     :     :     ┃
      │         :     :     :     ┃
      │         :     :     :     :╲
      │         :     :     :     : ╲
      │         :     :     :     :  ╲
      │         :     :     :     :   ╲
      │         :     :     :     :    ╲▂▂▂▂▂▂▂▂
      │         :     :     :     :     :
     CCW         ◀───▶ ◀───▶ ◀───▶ ◀───▶
                   A     B     C     D

x axis: position error
y axis: output torque

A: CCW Compliance Slope
B: CCW Compliance Margin
C: CW Compliance Slope
D: CW Compliance Margin
Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_down_calibration(dynamixel_id)[source]

Return the “down calibration” value of the specified Dynamixel unit.

The calibration value is used to compensate the differences between the potentiometers used in the Dynamixel units.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_firmware_version(dynamixel_id)[source]

Return the firmware version of the specified Dynamixel unit.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_goal_position(dynamixel_id)[source]

Return the requested goal angular position of the specified Dynamixel unit.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_max_temperature(dynamixel_id)[source]

Return the maximum tolerated internal temperature for the specified Dynamixel unit.

If the internal temperature of the Dynamixel actuator gets higher than this value, the Over Heating Error Bit (the third error bit of Status Packets) will be set to 1. The values are in degrees Celsius.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_max_torque(dynamixel_id)[source]

Return the initial maximum torque output of the specified Dynamixel unit.

This value, written in EEPROM, is copied to the torque limit bytes (in RAM) when the power is turned ON. Thus, max torque is just an initialization value for the actual torque limit.

If this value is equal to 0, the Dynamixel unit is configured in free run mode.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_max_voltage(dynamixel_id)[source]

Return the maximum tolerated operating voltage for the specified Dynamixel unit.

If the present voltage of the Dynamixel actuator gets higher than this value, the Voltage Range Error Bit (the first error bit of Status Packets) will be set to 1. The values are in Volts.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_min_voltage(dynamixel_id)[source]

Return the minimum tolerated operating voltage for the specified Dynamixel unit.

If the present voltage of the Dynamixel actuator gets lower than this value, the Voltage Range Error Bit (the first error bit of Status Packets) will be set to 1. The values are in Volts.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_model_number(dynamixel_id)[source]

Return the model number of the specified Dynamixel unit.

For AX-12, this value should be 12 (0x000C).

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_moving_speed(dynamixel_id)[source]

Return the angular velocity of the specified Dynamixel unit.

This angular velocity is defined in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation. The maximum value (1023 or 0x3FF) corresponds to 114 RPM (provided that there is enough power supplide).

Zero is a special value meaning that the largest possible velocity is supplied for the configured voltage, e.g. no velocity control is applied.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_present_load(dynamixel_id)[source]

Return the magnitude of the load applied to the specified Dynamixel unit.

If the returned value is negative, the load is applied to the clockwise direction.

If the returned value is positive, the load is applied to the counter clockwise direction.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_present_position(dynamixel_id, degrees=False)[source]

Return the current angular position of the specified Dynamixel unit.

Parameters:
  • dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
  • degrees (bool) – defines the returned position unit. If degrees is True, position corresponds to the goal rotation angle in degrees with respect to the original position and is defined in range (-150, 150). Otherwise, position is a unit free angular position to the origin, defined in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation.
get_present_speed(dynamixel_id)[source]

Return the current angular velocity of the specified Dynamixel unit.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_present_temperature(dynamixel_id)[source]

Return the internal temperature of the specified Dynamixel unit (in Degrees Celsius).

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_present_voltage(dynamixel_id)[source]

Return the voltage currently applied to the specified Dynamixel unit (in Volts).

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_punch(dynamixel_id)[source]

Return the minimum current supplied to the motor of the specified Dynamixel unit during operation.

The initial value is set to 0x20 and its maximum value is 0x3FF.

     CW
      ▲
      │━━━━━━━━━━     goal position
      │         :╲          :
      │         : ╲         :
      │         :  ╲        :
      │         :   ╲       :
      │         :    ╲      :
      │         :     ┃     :        ▲
      │         :     ┃     :        │ E
      │         :     ┃     ▽        ▼
CCW ──┼───────────────┺━━━━━━━━━━━┱─────────────▶ CW
      │         :     :     :     ┃  ▲
      │         :     :     :     ┃  │ E
      │         :     :     :     ┃  ▼
      │         :     :     :     :╲
      │         :     :     :     : ╲
      │         :     :     :     :  ╲
      │         :     :     :     :   ╲
      │         :     :     :     :    ╲▂▂▂▂▂▂▂▂
      │         :     :     :     :     :
     CCW         ◀───▶ ◀───▶ ◀───▶ ◀───▶
                   A     B     C     D

x axis: position error
y axis: output torque

A: CCW Compliance Slope
B: CCW Compliance Margin
C: CW Compliance Slope
D: CW Compliance Margin
E: Punch
Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_return_delay_time(dynamixel_id)[source]

Return the return delay time of the specified Dynamixel unit.

The return delay time is the time it takes (in uSec) for the status packet to return after the instruction packet is sent.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_status_return_level(dynamixel_id)[source]

Say whether the specified Dynamixel unit is configured to return a Status Packet after receiving an Instruction Packet.

Returned value Meaning
0 Do not respond to any instructions
1 Respond only to READ_DATA instructions
2 Respond to all instructions
Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_torque_limit(dynamixel_id)[source]

Return the maximum torque output of the specified Dynamixel unit.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
get_up_calibration(dynamixel_id)[source]

Return the “up calibration” value of the specified Dynamixel unit.

The calibration value is used to compensate the differences between the potentiometers used in the Dynamixel units.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
goto(dynamixel_id, position, speed=None, degrees=False)[source]

Set the goal position and moving speed for the specified Dynamixel unit.

Parameters:
  • dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFE).
  • position (int) – the new goal position. If degrees is True, position corresponds to the goal rotation angle in degrees with respect to the original position and must be in range (-150, 150). Otherwise, position is a unit free rotation angle to the origin, defined in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation.
  • speed (int) – the new moving speed. It must be in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation. This parameter is optional; if speed is not specified, the moving speed present in the Dynamixel control table is kept and used to reach the goal position.
  • degrees (bool) – defines the position unit. If degrees is True, position corresponds to the goal rotation angle in degrees with respect to the original position and must be in range (-150, 150). Otherwise, position is a unit free angular position, defined in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation.
has_angle_limit_alarm_led(dynamixel_id)[source]

Return True if the LED of the specified Dynamixel unit is configured to blink when an Angle Limit Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_angle_limit_alarm_shutdown(dynamixel_id)[source]

Return True if the specified Dynamixel unit is configured to turn off its torque when an Angle Limit Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_checksum_alarm_led(dynamixel_id)[source]

Return True if the LED of the specified Dynamixel unit is configured to blink when an Checksum Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_checksum_alarm_shutdown(dynamixel_id)[source]

Return True if the specified Dynamixel unit is configured to turn off its torque when an Checksum Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_input_voltage_alarm_led(dynamixel_id)[source]

Return True if the LED of the specified Dynamixel unit is configured to blink when an Input Voltage Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_input_voltage_alarm_shutdown(dynamixel_id)[source]

Return True if the specified Dynamixel unit is configured to turn off its torque when an Input Voltage Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_instruction_alarm_led(dynamixel_id)[source]

Return True if the LED of the specified Dynamixel unit is configured to blink when an Instruction Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_instruction_alarm_shutdown(dynamixel_id)[source]

Return True if the specified Dynamixel unit is configured to turn off its torque when an Instruction Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_overheating_alarm_led(dynamixel_id)[source]

Return True if the LED of the specified Dynamixel unit is configured to blink when an Overheating Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_overheating_alarm_shutdown(dynamixel_id)[source]

Return True if the specified Dynamixel unit is configured to turn off its torque when an Overheating Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_overload_alarm_led(dynamixel_id)[source]

Return True if the LED of the specified Dynamixel unit is configured to blink when an Overload Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_overload_alarm_shutdown(dynamixel_id)[source]

Return True if the specified Dynamixel unit is configured to turn off its torque when an Overload Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_range_alarm_led(dynamixel_id)[source]

Return True if the LED of the specified Dynamixel unit is configured to blink when an Range Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_range_alarm_shutdown(dynamixel_id)[source]

Return True if the specified Dynamixel unit is configured to turn off its torque when an Range Error occurs.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
has_registred_instruction(dynamixel_id)[source]

Return True if the specified Dynamixel unit is currently processing a REG_WRITE command; otherwise, return False.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
is_led_enabled(dynamixel_id)[source]

Return True if the LED of the specified Dynamixel unit is ON; otherwise return False.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
is_locked(dynamixel_id)[source]

Return True if the specified Dynamixel unit is locked; return False otherwise.

When a Dynamixel unit is locked, only addresses 0x18 to 0x23 can be written. Once locked, it can only be unlocked by turning the power off.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
is_moving(dynamixel_id)[source]

Return True if the specified Dynamixel unit is moving by its own power; return False otherwise.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
is_torque_enable(dynamixel_id)[source]

Return True if the torque of the specified Dynamixel unit is enabled; otherwise return False.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
ping(dynamixel_id)[source]

Ping the specified Dynamixel unit.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
Returns:True if the specified unit is available, False otherwise.
pretty_print_control_table(dynamixel_id)[source]

Print the control table of the specified Dynamixel unit in an easily human readable format.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
print_control_table(dynamixel_id)[source]

Print the control table of the specified Dynamixel unit in an “raw” format.

To get the same output in a more easily human readable format, use the pretty_print_control_table function.

Parameters:dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
read_data(dynamixel_id, address, length)[source]

Read bytes form the control table of the specified Dynamixel unit.

Parameters:
  • dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
  • address (int) – the starting address of the location where the data is to be read.
  • length (int) – the length of the data to be read.
scan(dynamixel_id_bytes=None)[source]

Return the ID sequence of available Dynamixel units.

Parameters:dynamixel_id_bytes (bytes) – a sequence of unique ID of the Dynamixel units to be pinged.
send(instruction_packet)[source]

Send an instruction packet.

Parameters:instruction_packet – can be either a Packet instance or a “bytes” string containing the full instruction packet to be sent to Dynamixel units.
set_ccw_angle_limit(dynamixel_id, angle_limit, degrees=False)[source]

Set the counter clockwise angle limit of the specified Dynamixel unit to the specified angle_limit.

The goal position should be lower or equal than this value, otherwise the Angle Limit Error Bit (the second error bit of Status Packets) will be set to 1.

Parameters:
  • dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
  • angle_limit (int) – the counter clockwise angle limit to be set for the specified Dynamixel unit. If degrees is True, this value is defined in degrees and must be in range (-150, 150); otherwise, it is an unit free angle and must be in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation.
  • degrees (bool) – defines the angle_limit unit. If degrees is True, angle_limit is defined in degrees and must be in range (-150, 150). Otherwise, angle_limit is a unit free angular limit, defined in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation.
set_cw_angle_limit(dynamixel_id, angle_limit, degrees=False)[source]

Set the clockwise angle limit of the specified Dynamixel unit to the specified angle_limit.

The goal position should be higher or equal than this value, otherwise the Angle Limit Error Bit (the second error bit of Status Packets) will be set to 1.

Parameters:
  • dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFD).
  • angle_limit (int) – the clockwise angle limit to be set for the specified Dynamixel unit. If degrees is True, this value is defined in degrees and must be in range (-150, 150); otherwise, it is an unit free angle and must be in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation.
  • degrees (bool) – defines the angle_limit unit. If degrees is True, angle_limit is defined in degrees and must be in range (-150, 150). Otherwise, angle_limit is a unit free angular limit, defined in range (0, 1023) i.e. (0, 0x3FF) in hexadecimal notation.
write_data(dynamixel_id, address, data)[source]

Write bytes to the control table of the specified Dynamixel unit.

Parameters:
  • dynamixel_id (int) – the unique ID of a Dynamixel unit. It must be in range (0, 0xFE).
  • address (int) – the starting address of the location where the data is to be written.
  • data (bytes) – the bytes of the data to be written (it can be an integer, a sequence of integer, a bytes or a bytearray).