Dynamixel Motors API

Dynamixel Motors API is a simple and easy-to-use API for controling the Dynamixel motors from Compliance Robotics.

Installation

To install the Dynamixel Motors API, you can use pip:

python -m pip install git+https://github.com/SofaComplianceRobotics/DynamixelMotorsAPI.git@release-main

Usage

The Dynamixel Motors API provides the DynamixelMotors class, which can be used to control the Motors. The API provides methods for controlling the robot's motors. You can look at the motors_example.py file for a simple example of how to use the API to control the motors of the motors.

You have several ways to create a DynamixelMotors object:

• by using the from_dicts method, which takes a list of dictionaries or one dictionnary describing the motors like above
• by using a json file containing the same list of dictionaries, and use the from_json method
• by inheriting from DynamixelMotors class. This is the recommended way if you need to extend the capabilities of your Dynamixel motors set (e.g. you want to add specific methods or attributes)

⚠️ You cannot specify different baud rates into the same DynamixelMotors object, they all have to be the same, otherwise, an exception will be raised at init.

Simple example thaht sets the angles of 4 XM430-W210 motors to 0 radians, waits for 1 second, and then prints the status of the robot:

# Standard creation example

import time
from dynamixelmotorsapi import DynamixelMotors

motors_description = [
                        {
                            "id": [0, 1, 2, 3],
                            "model": "XM430-W210",
                            "pulley_radius": 20, # radius of the pulley in mm
                            "pulse_center": 2048,
                            "max_vel": 1000,
                            "baud_rate": 57600  
                        }
                    ]

robot_motors = DynamixelMotors.from_dicts(motors_description)
        
if robot_motors.open(): 
    
    robot_motors.printStatus()
    initial_pos_pulse = [0] * len(DXL_IDs)
    robot_motors.angles = initial_pos_pulse
    time.sleep(1)
    robot_motors.printStatus()
    robot_motors.close()

This is an example of creation using inheritance. Note that you keep the list of dictionnaries notation you use in the previous example.

# Inheritance creation example

import time
from dynamixelmotorsapi import DynamixelMotors

class MyRobot(DynamixelMotors):
    def __init__(self):
        super().__init__([{
            "id": [0, 1, 2, 3],
            "model": "XM430-W210",
            "pulley_radius": 20,
            "pulse_center": 2048,
            "max_vel": 1000,
            "baud_rate": 1000000
        }])

        self.foo_bar = "foo"

    def toggleAttribute(self):
        self.foo_bar = "foo"if self.foo_bar=="bar" else "foo"

myrobot = MyRobot()
        
if robot_motors.open(): 
    print("Foo Bar attribute: ", myrobot.foo_bar)
    robot_motors.printStatus()
    initial_pos_pulse = [0] * len(DXL_IDs)
    robot_motors.angles = initial_pos_pulse
    time.sleep(1)
    robot_motors.printStatus()
    print("Foo Bar attribute: ", myrobot.foo_bar)
    robot_motors.close()

The catalog of Dynamixel motors has been compiled into the file dynamixel_configs.json. They've been extracted from the Dynamixel website.

Except for the id parameter, which must be a list of unique IDs for each motor, the other parameters can be shared among motors of the same model or can also be lists of values for each motor, as long as they are consistent with the number of motors described in the id parameter.

Several syntaxes are possible for the motor description dictionaries, as long as they contain the required information: id, model, pulley_radius (mm), pulse_center, max_vel (rev/min).

# Example of a motor description dictionary for 4 XM430-W210 motors, note that the IDs must be unique for each motor, but the other parameters can be shared among motors of the same model.
{
    "id": [0, 1, 2, 3],
    "model": "XM430-W210",
    "pulley_radius": 20,
    "pulse_center": 2048,
    "max_vel": 1000,
    "baud_rate": 57600
}

# Equivalent to the above, but with the parameters as lists of values for each motor, which can be useful if you have motors of different models or with different configurations.
[
    {
        "id": [0, 1, 2, 3],
        "model": ["XM430-W210"]*4,
        "pulley_radius": [20]*4,
        "pulse_center": [2048, 2048, 2048, 2048],
        "max_vel": [1000]*4,
        "baud_rate": [57600]*4
    }
]

# Equivalent to the above, but with each motor described as a separate dictionary in the list, which can be useful if you want to have more flexibility in the configuration of each motor.
[
    {
        "id": 0,
        "model": "XM430-W210",
        "pulley_radius": 20,
        "pulse_center": 2048,
        "max_vel": 1000,
        "baud_rate": 57600
    },
    {
        "id": 1,
        "model": "XM430-W210",
        "pulley_radius": 20,
        "pulse_center": 2048,
        "max_vel": 1000,
        "baud_rate": 57600
    },
    {
        "id": 2,
        "model": "XM430-W210",
        "pulley_radius": 20,
        "pulse_center": 2048,
        "max_vel": 1000,
        "baud_rate": 57600
    },
    {
        "id": 3,
        "model": "XM430-W210",
        "pulley_radius": 20,
        "pulse_center": 2048,
        "max_vel": 1000,
        "baud_rate": 57600
    }
]

You can also create a DynamixelMotors object by directly passing a list of MotorConfig objects to the constructor.

For Developers

The documentation is generated using pydoc-markdown. To generate the documentation, you need to install pydoc-markdown:

pipx install pydoc-markdown

Then, you can generate the documentation in a dynamixelmotors-api.md file, by using the following command at the root of the project:

pydoc-markdown