- Packages in the repository
- Installation
- System startup
- Homing procedure
- Diagnostics
- Published topics
- Motion
- Visualization in RViz
- Dobot Magician Control Panel - RQT plugin
- End effectors
- Additional tools for visualization
- Examples
- Sliding rail
- Multi-robot system (MRS)
- Video - see how the system works
- FAQ
- Citing
- Contributing
dobot_bringup- launch files and parameters configuration (in YAML files)dobot_control_panel- RQT plugin to control Dobot Magician robotic arm (as well as sliding rail)dobot_demos- a collection of sample scripts for beginners (minimal working examples)dobot_description- package containing URDF description of Dobot Magician together with meshesdobot_diagnostics- aggregation and analysis of alarm statesdobot_driver- low-level Python interface to communicate with Dobot via serial portdobot_end_effector- set of service servers allowing to control different kinds of end effectorsdobot_homing- tool for executing homing procedure of Dobot stepper motorsdobot_kinematics- implementation of forward and inverse kinematics to validate trajectory feasibilitydobot_motion- package containing action server to control motion of Dobot Magician (joint interpolated motion / linear motion)dobot_msgs- package defining messages used by control stackdobot_state_updater- package containing a node regularly retrieving information about the state of the robot (e.g. joint angles / TCP position)dobot_visualization_tools- useful tools for visualization (e.g. trajectory / range) in form of RViZ markers
This control system requires a system setup with ROS 2. It is recommended to use Ubuntu 22.04 with ROS 2 Humble, however using Ubuntu 20.04 with ROS 2 Galactic should also work.
Follow the instructions from the link. There are 3 versions of ROS 2 Humble Hawksbill to choose from: Desktop Install, ROS-Base Install and Development tools Install. Be sure to install Desktop Install version (sudo apt install ros-humble-desktop).
All necessary modules are in requirements.txt, install using: pip3 install -r requirements.txt
Packages from apt repository: sudo apt install ros-humble-diagnostic-aggregator ros-humble-rqt-robot-monitor python3-pykdl
rqt --force-discover to make plugins visible in RQT GUI. This issue is further described here.
source /opt/ros/humble/setup.bash
mkdir -p ~/magician_ros2_control_system_ws/src
git clone https://github.com/jkaniuka/magician_ros2.git ~/magician_ros2_control_system_ws/src
cd magician_ros2_control_system_ws
rosdep install -i --from-path src --rosdistro humble -y
colcon build
In order to communicate with the robot, access to serial ports is required. To be able to open serial ports without using sudo, you need to add yourself to the dialout group:
sudo usermod -a -G dialout <username>
# Relogin or reboot required!- Connect Dobot Magician with a USB cable to the computer and then turn it on.
- Set the MAGICIAN_TOOL environment variable describing the robot's configuration
export MAGICIAN_TOOL=<tool_type>(allowed values are: none, pen, suction_cup, gripper, extended_gripper). - From inside of the magician_ros2_control_system_ws directory, run
. install/setup.bashto source your workspace. - Launch entire control stack with
ros2 launch dobot_bringup dobot_magician_control_system.launch.py.
Homing should be performed as the first action after the system is started. It is necessary because an incremental encoder has been placed in the base of the manipulator, and the robot is not aware of its actual position when it is powered up. Stop all other scripts controlling the robot before starting the homing procedure.
Homing is handled by the service server, to start it run the following command:
ros2 service call /dobot_homing_service dobot_msgs/srv/ExecuteHomingProcedure
A homing_position parameter is assigned to the server node of the homing service, which allows you to determine the position reached by the manipulator after the procedure is completed. The following are examples of the commands for reading and setting parameters value.
ros2 param get /dobot_homing_srv homing_position
ros2 param set /dobot_homing_srv homing_position [150.0,0.0,100.0,0.0]
The system takes care of the robot's state diagnostics. Using the Diagnostics Viewer RQT plugin, you can clearly visualize information about active alarm states. To start Diagnostics Viewer run the following command:
rqt -s rqt_robot_monitor
If you already have an open RQT you will find this plugin in section Plugins -> Robot Tools -> Diagnostics Viewer. After opening the plugin, select Alternative view option at the top. After double-clicking on the alarm description, a window will appear with information about its probable cause and how to delete it. Below you will find screenshots of the Diagnostics Viewer plugin.
/joint_states(sensor_msgs/msg/JointState) - angles values in the manipulator's joints/dobot_TCP(geometry_msgs/msg/PoseStamped) - position of the coordinate frame associated with the end of the last robot link (orientation given as a quaternion)/dobot_pose_raw(std_msgs/msg/Float64MultiArray) - position of the coordinate frame associated with the end of the last robot link (raw orientation received from Dobot, expressed in degrees)
The motion of the manipulator is handled using the ROS 2 action. In order for the manipulator to move to the desired position, the motion target must be sent to the action server. The following describes the structure of the message sent to the action server (part of dobot_msgs/action/PointToPoint):
- motion_type:
- 1 -> joint interpolated motion, target expressed in Cartesian coordinates
- 2 -> linear motion, target expressed in Cartesian coordinates
- 4 -> joint interpolated motion, target expressed in joint coordinates
- 5 -> linear motion, target expressed in joint coordinates
- target_pose - desired position expressed in Cartesian coordinates [mm] or in joint coordinates [degrees]
- velocity_ratio (default 1.0)
- acceleration_ratio (default 1.0)
An example of a command that allows you to send a goal to an action server can be found below (adding --feedback flag will cause the terminal to display the current position of the robot while it is moving):
ros2 action send_goal /PTP_action dobot_msgs/action/PointToPoint "{motion_type: 1, target_pose: [200.0, 0.0, 100.0, 0.0], velocity_ratio: 0.5, acceleration_ratio: 0.3}" --feedback
If you want to cancel the goal, run the following command:
ros2 service call /PTP_action/_action/cancel_goal action_msgs/srv/CancelGoal
The parameters associated with the motion action server node allow you to determine the motion velocities and accelerations of the individual joints of the robot (JT1_vel, JT2_vel, JT3_vel, JT4_vel, JT1_acc, JT2_acc, JT3_acc, JT4_acc), as well as the parameters of the linear motion of the manipulator (TCP_vel, end_tool_rot_vel, TCP_acc, end_tool_rot_acc).
The motion target is checked by the trajectory validation service server before execution. The trajectory validation service server checks whether the target point is in the manipulator's workspace and whether there is a solution to the inverse kinematics task.
The parameters of the node implementing the trajectory validation server are: axis_1_range, axis_2_range, axis_3_range, axis_4_range.
- The first four of these allow the manipulator's working space to be limited by setting position restrictions at joints other than those resulting from the mechanical design. If you send a motion order to a point that violates the restrictions you defined, you will receive the following response from the PointToPoint action server:
Response: [PTP_server-1] [WARN] [1668081940.281544573] [dobot_PTP_server]:
Goal rejected: dobot_msgs.srv.EvaluatePTPTrajectory_Response(is_valid=False,
message='Joint limits violated')
In Rviz, you can display one of up to 8 different robot configurations. All allowed configurations are placed in the diagram below:
The command that starts the visualization of the manipulator in the example configuration is as follows:
ros2 launch dobot_description display.launch.py DOF:=4 tool:=extended_gripper use_camera:=true
If the robot is disconnected from the computer, you can start the visualization by adding the gui:=true argument and control the robot using joint_state_publisher_gui node.
Below you will find 3 sample visualizations:
Dobot Magician Control Panel is an RQT plugin that allows you to conveniently position the manipulator, visualize its state, modify motion parameters and control end effectors. In order to launch it, run the following command:
rqt -s dobot_control_panel
Below you will find screenshots of all the plugin screens:
Control of the gripper and pneumatic suction cup was implemented using ROS 2 services.
Command example:
ros2 service call /dobot_gripper_service dobot_msgs/srv/GripperControl "{gripper_state: 'open', keep_compressor_running: true}"
Request fields:
gripper state(type string) : open/closekeep_compressor_running(type bool) : true/false
Command example:
ros2 service call /dobot_suction_cup_service dobot_msgs/srv/SuctionCupControl "{enable_suction: true}"
Request fields:
enable_suction(type bool) : true/false
The dobot_visualization_tools package provides visualization tools in form of RViz markers.
- Camera field of view (FOV) for Intel Realsense D435i (published at
/realsense_FOVtopic)
ros2 run dobot_visualization_tools show_camera_FOV
- Workspace visualization (published at
/reachability_rangetopic) - range without end effector attached.
ros2 run dobot_visualization_tools show_dobot_range
- TCP trajectory (published at
/TCP_trajectorytopic) - trajectory markers are removed after 2 seconds of the manipulator's stationary state, so as not to slow RViz down with too many markers it needs to display.
ros2 run dobot_visualization_tools show_trajectory
- Interactive Markers - you can select the target position of the tool end (x, y, z, r) by moving the interactive marker in RViz. Once the target is selected, right-click on the yellow sphere and select the motion type from the menu. When running a node that allows control using interactive markers, two parameters must be specified (see example below) that define the point at the end of the tool in the coordinate system associated with the last link of the manipulator.
ros2 run dobot_visualization_tools int_marker --ros-args -p TCP_x_offset:=0.059 -p TCP_z_offset:=-0.12
Sample scripts have been included in dobot_demos package. Analysis of sample codes (minimal working examples) from this package will help you understand how to control Dobot Magician robot.
Running sample scripts:
ros2 run dobot_demos test_gripperros2 run dobot_demos test_suction_cupros2 run dobot_demos test_homingros2 run dobot_demos test_point_to_pointros2 run dobot_demos test_pick_and_place
If you have Dobot Magician Sliding Rail and you want to get real time feedback about the position of the carriage you need to export MAGICIAN_RAIL_IN_USE environment variable before launching entire control stack (export MAGICIAN_RAIL_IN_USE=true). The current position of the carriage on the sliding rail will be published on the /dobot_rail_pose topic at a frequency of 20 Hz. After disconnecting the sliding rail, type unset MAGICIAN_RAIL_IN_USE and restart entire control system.
Control of the sliding rail is possible both from Dobot Magician Control Panel RQT plugin and by using /move_sliding_rail action server. To launch /move_sliding_rail action server and load parameters (sliding rail velocity and acceleration) use the command below:
ros2 launch dobot_motion dobot_rail.launch.py
An example of a command that allows you to send a goal to an action server can be found below:
ros2 action send_goal /move_sliding_rail dobot_msgs/action/SlidingRail "{target_pose: 500}"
If you want to connect several Dobot Magician robots to the same computer or to the same network, thus creating a multi-robot system (MRS), check the magician-mrs branch.
| Overview and features | Interactive Markers |
|---|---|
 |
rviz_markers.mp4 |
Why haven't I used MoveIt 2?
MoveIt 2 is a great tool, but I have not used it in my control system for several reasons:
- To begin with, this system was created with the idea of using it when learning ROS 2. First, you need to familiarize yourself with entities such as actions, topics, services, parameters to then understand how this is being utilized in MoveIt 2.
- Secondly, MoveIt is used among other things to generate collision-free trajectories. The mechanical design of Dobot Magician robot and its very short range (32 cm) makes it de facto unsuitable for working in spaces with obstacles.
- Lastly, MoveIt enables grasp generation. Dobot Magician is equipped with a gripper that can be either fully open or fully closed. In addition, it is always pointed horizontally downward. Grip generation in this case does not seem to be necessary.
If you find this work useful, please give credits to the author by citing:
@mastersthesis{jkaniuka-bsc-23-twiki,
author = {Kaniuka, Jan},
school = {WEiTI},
title = {{System sterowania robota manipulacyjnego Dobot Magician na bazie frameworka ROS2}},
engtitle = {{Control system of DobotMagician robotic manipulator based on ROS2 framework}},
year = {2023},
type = {Bachelor's thesis},
lang = {pl},
organization = {IAiIS},
publisher = {IAiIS},
tutor = {Tomasz Winiarski},
twiki = {bsc},
url = {https://gitlab-stud.elka.pw.edu.pl/robotyka/rpmpg_pubs/-/raw/main/student-theses/jkaniuka-bsc-23-twiki.pdf}
}
Please use the issue tracker to report any bugs or feature requests.