README.md

Dynamixel Library for MATLAB and Simulink

This repository contains a ROBOTIS Dynamixel library for MATLAB and Simulink. The purpose of the library is to provide higher level functions for easier control of multiple Dynamixel smart actuators from within MATLAB and Simulink environments.

The Dynamixel library for MATLAB and Simulink is based on the dynamic library using C language included in the Dynamixel SDK (see Requirements), and was inspired by the MATLAB library included in the same SDK, as well as the Dynamixel Simulink Library developed by Jeihun Lee.

This library expands on the capabilities of the aforementioned references, by providing high-level functions for easier communication handling and control of multiple Dynamixel motors supporting both ROBOTIS protocols (1.0 and 2.0). The Simulink implementation makes it easier to execute near real-time Dynamixel motor control using its integrated Simulation Pacing functionality, while enabling the design and testing of higher-level robot controllers using Simulink's and MATLAB's toolboxes. Finally, the library comes with a number of examples written for MATLAB and Simulink providing help on how to use its functionalities.

You can also access the latest release of this library in MATLAB's file exchange.

Author: Georgios Andrikopoulos ([email protected]). Written in MATLAB 2022b.

Current Support

• Protocols 1 and 2
• Dynamixel Motors:
  • X Series
    • XL320
    • XL330-M288
    • XL330-M077
    • XC330-M288
    • XC330-M181
    • XC330-T181
    • XC330-T288
    • XC430-W240
    • XC430-W150
    • XL430-W250
    • XM430-W350
    • XM430-W210
    • XM540-W150
    • XM540-W270
  • AX Series
    • AX-12A
    • AX-12W
    • AX-18A
• Controllers:
  • U2D2
  • OpenRB-150
• MATLAB 2022b on Windows

This library has been successfully tested on various combinations of the above entries, while more tests are currently being performed to identify bugs and incompatibilities. The addition of support for Ubuntu and macOS systems, additional Dynamixel motor series, motor models, other high-level features (e.g. bulk read) and more examples is part of current work.

Requirements

• Dynamixel C Library as included in the Dynamixel SDK
• MATLAB 2022b with Simulink

  While the MATLAB functions will run normally in versions prior to 2022b, the included Simulink files will require Simulink 2022b to run. Simulink files compatible with previous versions will be made available soon.

Getting Started

To get started with the Dynamixel library for MATLAB and Simulink, follow these steps:

1. Download the C library folder from the Dynamixel SDK.

2. Open MATLAB, navigate to the downloaded c folder and select Add to Path with Selected Folders and Subfolders.

Make sure that you do not also add the C# folder from the Dynamixel SDK, as it has been reported to cause conflicts when initDXL.m (see MATLAB functions below) tries to load the .dll file of the C library.

3. Clone or download the Dynamixel Library for MATLAB and Simulink.

If you choose to download the library, make sure that you unzip the included folders.

4. From MATLAB, add the Dynamixel library for MATLAB and Simulink folders (and subfolders) to the MATLAB path.

5. Connect your Dynamixel smart motor(s) to your computer via a compatible controller (OpenRB-150) or interface (U2D2). See the ROBOTIS page for more information on how to use these boards.

Make sure that your motor(s) are connected to an external power supply that matches the permissible input voltage. Do not connect motors with different input voltage ranges, see the ROBOTIS page of your respective motor(s) for more information.

Do not connect or disconnect DYNAMIXEL motors when power is being supplied.

When using the U2D2 interface, it is recommended to use the U2D2 Power Hub.

When using the OpenRB-150 controller, make sure that you first upload the usb_to_dynamixel.ino sketch. Please note that the OpenRB-150 with that sketch currently supports baud rates up to 1,000,000. If the Dynamixel motor(s) baud rate is set to a value higher than 1,000,000, the motor(s) will not be recognized by the controller.

6. Identify the COM port of the connected controller.

On Windows: You can identify the COM port via the device manager, the Dynamixel Wizard 2.0, or the Arduino IDE.

7. Set all motors' baudrate to the same value.

Changing the baudrate for each motor can be done via the Dynamixel Wizard 2.0.

8. Use the provided MATLAB functions and Simulink blocks to control your Dynamixel smart actuator(s).

It is highly recommended that you first open and try the examples included with this MATLAB/Simulink library, as they will provide you with knowledge on how to setup and initiate motor communication, who to control the motors, troubleshoot errors, properly close the communication etc.

Make sure that you do not try to use the MATLAB/Simulink library while the motors are connected to the Dynamixel Wizard 2.0, or any other related software that establishes connection to the motors.

Usage

The Dynamixel library for MATLAB and Simulink provides several functions for controlling Dynamixel smart motors from within MATLAB and Simulink. The library folders include:

MATLAB functions

MATLAB functions that call the ROBOTIS dynamic library using C language, while providing high-level functionalities for easier control of multiple Dynamixel motors. The included MATLAB functions are:

• bulkReadAddParamDxl: Adds parameters for bulk read function of Dynamixel motors
• bulkReadDxl: Returns the acquired data from bulk read function for the connected Dynamixel motors
• bulkReadTxRxPacket: Executes bulk read for Dynamixel motors
• bulkWriteAddParamDxl: Adds parameters for bulk write function of Dynamixel motors
• bulkWriteDxl: Executes bulk write for Dynamixel motors
• checkErrorDxl: Checks for communication errors and returns the communication status of connected Dynamixel motors
• closePortDxl: Closes communication port with connected Dynamixel motors
• driveModeDxl: Changes the drive mode of connected Dynamixel motors
• fastSyncReadDxl: Executes fast sync read for Dynamixel motors and returns the selected read parameter
• fastSyncReadDxlSim: Executes fast sync read for Dynamixel Motors in Simulink
• fastSyncWriteDxl: Executes fast sync write for Dynamixel motors
• fastSyncWriteDxlSim: Executes fast sync write for Dynamixel Motors in Simulink
• findDxl: Finds connected dynamixels, returns their IDs and models
• findserial: Finds and returns connected serial (COM) ports
• initBulkReadDxl: Initializes the bulk read function for Dynamixel motors and returns the group numbers
• initBulkWriteDxl: Initializes the bulk write function for Dynamixel motors and returns the group write number
• initDxl: Loads C library and initializes Dynamixel communication
• initSyncReadDxl: Initializes the sync read function for Dynamixel motors and returns the group numbers
• initSyncReadIndirectDxl: Initializes the sync read function using indirect addresses of Dynamixel motors and returns the group numbers
• initSyncWriteDxl: Initializes the sync write function using indirect addresses of Dynamixel motors and returns the group numbers
• initSyncWriteIndirectDxl: Initializes the sync write function using indirect addresses of Dynamixel motors and returns the group numbers
• lookupDxl: Searches the control table RAM data of Dynamixel motors
• openPortDxl: Opens port for communication with Dynamixel motors
• operatingModeDxl: Changes the operating mode of Dynamixel motors
• readDxl: Executes read for Dynamixel motors and returns the acquired data
• readDxlSim: Executes read for Dynamixel motors and returns the acquired data
• setBaudDxl: Sets the baudrate of Dynamixel motor communication
• setIndirectReadDxl: Sets indirect addresses for enabling fast sync read for multiple Dynamixel motors
• setIndirectWriteDxl: Sets indirect addresses for enabling fast sync write for multiple Dynamixel motors
• syncReadAddParamDxl: Add parameter for bulk read function of Dynamixel motors
• syncReadClearParamDxl: Clears parameters for bulk read function of Dynamixel motors
• syncReadDxl: Executes sync read for Dynamixel motors and returns the acquired data
• syncReadDxlSim: Executes sync read for Dynamixel Motors in Simulink
• syncWriteDxl: Executes sync write for Dynamixel motors and returns the acquired data
• syncWriteDxlSim: Executes sync write for Dynamixel motors in Simulink
• torqueDxl: Enables or disables the torque to Dynamixel motors
• writeDxl: Executes write for Dynamixel motors
• writeDxlSim: Executes write for Dynamixel motors in Simulink

For detailed information on these functions, please refer to the comments in the corresponding MATLAB files.

For examples on how to use these functions in MATLAB, please refer to the respective example files included in this library.

For a deeper dive into the communication protocols, check the ROBOTIS pages for protocols (1.0 and 2.0).

Simulink Library

The Simulink library provides high-level functions for easier communication handling and control of multiple Dynamixel motors. The provided implementation is based on level-2 MATLAB S-Functions, which allow the creation of custom blocks that call the ROBOTIS dynamic library using C language in a Simulink model. Simulink's Simulation Pacing functionality allows for near real-time Dynamixel motor control, thus enabling the design and testing of higher-level robot controllers incorporating all other available Simulink's and MATLAB's toolboxes.

The included Simulink blocks are:

• Read: Library block executing the read instruction to one or more Dynamixel motors. The block's output is a vector whose length is equal to the number of connected Dynamixels, which contains the read results. In the current version of the library the acquired data from this block needs to be converted to integer values of bit-size equal to the size of the read instruction (see the Simulink examples for more information on how to do this, as well as the RAM Area control table provided in the ROBOTIS emanual page for each respective motor).

• Write: Library block executing the write instruction to one or more Dynamixel motors. The block's input is a vector whose length is equal to the number of connected Dynamixels, which contains the data to write. The data sent to this block first needs to be converted to unsigned integer values of bit-size equal to the size of the read instruction (see the Simulink examples for more information on how to do this, as well as the RAM Area control table provided in the ROBOTIS emanual page for each respective motor).

• Sync Read: Library block executing the sync read instruction to one or more Dynamixel motors, from the same Address and with the same length at once. The block's output is a vector whose length is equal to the number of connected Dynamixels, which contains the sync read results. The acquired data from this block needs to be converted to integer values of bit-size equal to the size of the read instruction (see the Simulink examples for more information on how to do this, as well as the RAM Area control table provided in the ROBOTIS emanual page for each respective motor).

• Sync Write: Library block executing the sync write instruction to one or more Dynamixel motors, on the same Address and with the same length at once. The block's input is a vector whose length is equal to the number of connected Dynamixels, which contains the data to sync write. The data sent to this block first needs to be converted to unsigned integer values of bit-size equal to the size of the read instruction (see the Simulink examples for more information on how to do this, as well as the RAM Area control table provided in the ROBOTIS emanual page for each respective motor).

• Fast Sync Read (via indirect addresses): Library block executing the sync read instruction to one or more Dynamixel motors, from the same multiple addresses and with the same lengths at once using indirect addresses. As ROBOTIS states "The indirect address links between direct and indirect data storages. This makes the Syncread and the Syncwrite function accessible to the items which are far from each other’s address". The block's output is a vector whose length is equal to the number of connected Dynamixels, which contains the sync read results. The acquired data from this block needs to be converted to integer values of bit-size equal to the size of the read instruction (see the Simulink examples for more information on how to do this, as well as the RAM Area control table provided in the ROBOTIS emanual page for each respective motor).

• Fast Sync Write (via indirect addresses): Library block executing the sync write instruction to one or more Dynamixel motors, on the same multiple addresses and with the same lengths at once using indirect addresses. The block's input is a vector whose length is equal to the number of connected Dynamixels, which contains the data to sync write. The data sent to this block first needs to be converted to unsigned integer values of bit-size equal to the size of the read instruction (see the Simulink examples for more information on how to do this, as well as the RAM Area control table provided in the ROBOTIS emanual page for each respective motor).

• Motor Models: Numerical models extracted from the motors' performance graphs provided by ROBOTIS.

The performance graphs are only provided for selected motor series. These graphs include the experimentally acquired motor performance under gradually increasing loads, and describe the relationships between

• Motor current to motor torque
• Motor speed to motor torque
• Motor efficiency to motor torque

(Motor images and performance graphs taken from ROBOTIS e-Manual)

As ROBOTIS states "The actual motor operation environment is closer to the performance graph, not stall torque method. For this reason, the performance graph is broadly used in the industrial field. Generally, Max Torque of the Performance Graph is less than the Stall Torque". Currently, the library includes the extracted models of:

• XC430-W150
• XM430-W350
• XM540-W150
• XM540-W270

While most X series motors provide the Present Current as feedback, which can be converted to motor torque via the respective model, motors like the XC430-W150 return the Present Load. ROBOTIS states that "Present load is an inferred value based on the internal output value; not a measured value using torque sensor, etc. Therefore, it may be inaccurate for measuring weight or torque. It is recommended to use it for predicting the direction and size of the force being applied to the joint.". For this reason, a simplified model for converting motor load to motor torque is provided, which maps the min/max torque values extracted from the performance graphs to the 0-100% load range.

For detailed documentation of the Simulink library blocks, please refer to the comments in the corresponding Simulink files.

For examples on how to use these functions in Simulink, please refer to the respective example files included in this library.

For a deeper dive into the communication protocols, check the ROBOTIS pages for protocols (1.0 and 2.0).

Examples

The Examples folder contains several examples of how to use the library to control Dynamixel smart actuators from within MATLAB and Simulink. These examples include:

MATLAB examples

The MATLAB examples included in this library are listed below:

• Protocol 1.0
  • ReadWrite.m: Example file executing read and write functions for one or more Dynamixel motors under Protocol 1.0 communication.
  • ReadSyncWrite.m: Example file executing read and sync write functions for one or more Dynamixel motors under Protocol 1.0 communication.
• Protocol 2.0
  • ReadWrite.m: Example file executing read and write functions for one or more Dynamixel motors under Protocol 2.0 communication.
  • SyncReadSyncWrite.m: Example file executing sync read and sync write functions for one or more Dynamixel motors under Protocol 2.0 communication.
  • FastSyncReadFastSyncWrite.m: Example file executing fast sync read and fast sync write functions for two Dynamixel motors under Protocol 2.0 communication and using indirect addresses. The examples included in this library are listed below. For detailed documentation of these examples, please refer to the comments in the corresponding MATLAB files.

After you have performed all steps noted in the Getting Started section, you will need to execute the first section in the respective .m file of the example you want to run. This section opens the port, identifies the connected motors and initializes all required parameters.

If everything was done correctly, execution of that section should give you a similar result to the following image:

SyncReadSyncWrite.m example of controlling two different motor models of the X series under the "Extended Position Control" operating mode and the "Velocity-based Profile" drive mode.

FastSyncReadFastSyncWrite.m example of controlling two motors via Fast Sync Read/Write by using indirect addresses. Note that the motor torques are disabled before setting the indirect data addresses.

In the case of errors, most library functions return prompts to help you identify the issues. For example, if the COM port is not set properly, the initDXL() function returns the communication error along with COM ports that are currently used. For example:

If the COM port assigned to your controller is not found and is not listed in that message, this usually means that the port was not closed properly during the last test. To solve this issue you will have to reset your controller.

To properly finish your tests, make sure that you execute the last section found in all example .m files (named as End Session) to disable motor torques and close the port.

Failing to close the port will require resetting power to your controller.

Make sure that you disconnect from Dynamixel Wizard before using this MATLAB/Simulink library. Also, make sure that you properly end your Dynamixel connection with MATLAB/Simulink before connecting to Dynamixel Wizard or any similar software that establishes a connection to the motors.

Simulink examples

All Simulink examples (.slx files) are accompanied by a MATLAB (.m) file with the same name. After you have performed all steps noted in the Getting Started section, you will need to execute the first section in the respective .m file of the example you want to run. As in the MATLAB examples, this section opens the port, sets the sampling time that will be used for near real-time simulation pacing, identifies the connected motors, sets their operating and drive modes, initializes all required parameters, and opens the selected simulink file. Execution of that section should give you a similar result to the following image:

At the end of that section, make sure you uncomment the .slx file you want to open, for example:

This step is not necessary if that file has already been opened manually

Please check the notes on the MATLAB examples subsection for expected outputs when executing that section, as well as notes on error handling and properly ending the session.

%% Simulink file run and comment on real-time execution (pacing)

As in the MATLAB examples, make sure that you finally execute the last section found in the respective .m files (named as End Session) to disable motor torques and close the port.

Failing to close the port will require resetting power to your controller.

Make sure that you disconnect from Dynamixel Wizard before using this MATLAB/Simulink library. Also, make sure that you properly end your Dynamixel connection with MATLAB/Simulink before connecting to Dynamixel Wizard.

To maximize performance of the Simulink programs, functions that do not usually require on-line changes during testing (setting the baudrate, changing the profile configuration between time-based and velocity profile etc.) are suggested to be set via MATLAB functions during the initialization phase, or via Dynamixel Wizard 2.0 prior to the Simulink tests.

To ensure that near real-time simulation pacing is achieved, please adjust the sampling time according to the number of connected motors and the amount of data that you will be writing and/or reading. If the pacing is active, this will be noted in the left bottom edge of the Simulink window during execution, as shown below. If that message notes that pacing cannot be achieved, the sampling time will have to be increased until the warning stops.

The examples included in this library are listed below for the two communication protocols. For detailed documentation of these examples, please refer to the comments in the corresponding MATLAB and Simulink files.

• Protocol 1.0
  • Read and Write for one or two Dynamixel motors:

Examples executing the Read and Write functions for one and two motors under Protocol 1.0 communication. The motor(s) goal position is controlled via dashboard knob(s) and is sent to the motors to execute, while the present position, velocity, current/load and temperature are read and displayed.

ReadWrite_1Motor.slx

ReadWrite_2Motors.slx

• Read and Sync Write for one or two Dynamixel motors:

Examples executing the Read and Write functions for one and two motors under Protocol 1.0 communication. The motor(s) goal position is controlled via dashboard knob(s) and is sent to the motors to execute, while the present position, velocity, current/load and temperature are read and displayed. The sync write implementation is faster than the simple write, as it handles communication on the same address and with the same length at once for all connected motors.

ReadSyncWrite_1Motor.slx

ReadSyncWrite_2Motors.slx

In the case of multiple motors, the written and read data are all handled as vectors, with length equal to the number of connected motors.

As mentioned in the above Simulink Blocks description, the data fed into the Write blocks and the data acquired via the Read blocks must be converted to unsigned and signed integer values, respectively, of size equal to the size of the performed instructions (as stated in the motor's RAM area control table).

• Protocol 2.0

  • Read and Write for one or two Dynamixel motors:

Examples executing the Read and Write functions for one and two motors under Protocol 2.0 communication. The motors' goal position is controlled via dashboard knob(s) and is sent to the motors to execute, while the present position, velocity, current/load and temperature are read and displayed.

ReadWrite_1Motor.slx

ReadWrite_2Motors.slx

• Sync Read and Sync Write for one or two Dynamixel motors:

Examples executing the Sync Read and Sync Rrite functions for one and two motors under Protocol 2.0 communication. The motors' goal position is controlled via dashboard knob(s) and is sent to the motors to execute, while the present position, velocity, current/load and temperature are read and displayed. This implementation is faster than the simple read and write functions, as it handles communication on the same address and with the same length at once for all connected motors.

SyncReadSyncWrite_1Motor.slx

SyncReadSyncWrite_2Motors.slx

• Fast Sync Read and Fast Sync Write for two Dynamixel motors:

Example executing the Fast Sync Read and Fast Sync Write functions for two motors under Protocol 2.0 communication. The motors' goal position and LED status are controlled via dashboard blocks and written to the motors, while the present position, velocity, current/load and temperature are read and displayed. This implementation is faster than all previous functions, as it handles communication on the same address and with the same length at once for all connected motors using indirect addresses. In this case, the indirect addresses link the goal position and LED parameters, which are not next to each other in the RAM control table, to be written at once to all motors.

FastSyncReadFastSyncWrite_2Motors.slx

In the case of multiple motors, the written and read data are all handled as vectors, with length equal to the number of connected motors.

As mentioned in the above Simulink Blocks description, the data fed into the Write blocks and the data acquired via the Read blocks must be converted to unsigned and signed integer values, respectively, of size equal to the size of the performed instructions (as stated in the motor's RAM area control table).

Since Present Current and Present Load are assigned to the same address in the motors' RAM control table, it is handled via the unified prompt Present Current/Load in the Dynamixel Read, Dynamixel Sync Read, and Dynamixel Fast Sync Read blocks to avoid confusion. Using the prompts Present Current and Present Load will still return the same results.

Contributing

If you find a bug or have a feature request, please open an issue in the repository. If you would like to contribute to the library, please fork the repository and submit a pull request with your changes.

License

This library is released under the GPL-3.0 License. See the License file for more information.

Cite as

Georgios Andrikopoulos (2022). Dynamixel Library for MATLAB and Simulink (https://github.com/geoand-robotdesign/Dynamixel_Library_MATLAB_Simulink), GitHub. Retrieved February 20, 2023.