This repository contains source code and configuration files to support the Jaco, Jaco2 and Mico arms in ROS.
This repository doesn't support the Gen3 arm in ROS. Have a look at the ros_kortex repository for Gen3 ROS support!
The master branch has been tested with ROS Noetic.
For older ROS version, checkout on corresponding branch :
The kinova-ros stack provides a ROS interface for the Kinova Robotics JACO, JACO2 and MICO robotic manipulator arms. Besides wide support of Kinova products, there are many bug fixes, improvements and new features as well. The stack is developed above the Kinova C++ API functions, which communicate with the DSP inside robot base.
To make kinova-ros part of your workspace, follow these steps (assuming your workspace is setup following the standard conventions):
cd ~/catkin_ws/src
git clone -b <branch-name> git@github.com:Kinovarobotics/kinova-ros.git kinova-ros
cd ~/catkin_ws
catkin_makeAnother way to build your workspace would be to use the newer catkin build, which is part of the catkin_tools package:
# using apt-get
sudo apt-get install python-catkin-tools
# using pip
sudo pip install -U catkin_toolsThen, you add kinova-ros to your workspace and build it
cd ~/catkin_ws/src
git clone -b <branch-name> git@github.com:Kinovarobotics/kinova-ros.git kinova-ros
cd ~/catkin_ws
catkin buildMore about the catkin_tools package in the official documentation
Note : To access the arm via usb copy the udev rule file 10-kinova-arm.rules from ~/catkin_ws/src/kinova-ros/kinova_driver/udev to /etc/udev/rules.d/:
sudo cp kinova_driver/udev/10-kinova-arm.rules /etc/udev/rules.d/kinova_bringup: launch file to start kinova_driver and apply some configurations.kinova_control: files used by Gazebo.kinova_demo: python scripts for actionlibs in joint space and cartesian space.kinova_description: robot urdf models and meshes are stored here.kinova_docs: kinova_comm reference html files generated by doxygen. The comments are based on the reference of Kinova C++ API, and some additional information is provided. The documents of Kinova C++ API are automatically installed while installing Kinova SDK from the Kinova websitekinova_driver: most essential files to run kinova-ros stack. Under the include folder, Kinova C++ API headers are defined in ../indlude/kinova, and ROS package header files are in kinova_driver folder. kinova_api source file is a wrap of Kinova C++ API, and kinova_comm builds up the fundamental functions. Some advanced accesses regarding to force/torque control are only provided in kinova_api. Most parameters and topics are created in kinova_arm. A general architecture from low level up could be:
DSP --> communicate --> Kinova C++ API --> wrapped --> kinova_api --> kinova_comm --> {kinova_arm; kinova_fingers_action; kinova_joint_angles_action; ...} --> kinova_arm_driver. It is not recommended to modify kinova_comm and any level below it. kinova_gazebo: ros package to launch a Gazebo simulation.kinova_moveit: Everything related to Moveit! is stored here.kinova_msgs: all the messages, servers and actionlib format are defined here.kinova_robot.launch in kinova_bringup folder launches the essential drivers and configurations for kinova robots. kinova_robot.launch has multiple arguments:
kinova_robotType specifies which robot type is used. For better supporting wider range of robot configurations, robot type is defined by a char[8], in the format of: [{j|m|r|c}{1|2}{s|n}{4|6|7}{s|a}{2|3}{0}{0}].
{j|m|r|c} refers to jaco, mico, roco and customized{1|2} for now{s|n} can be spherical or non-spherical{4|6|7}{s|a} can be in service or assistive{2|3} may equipped with 2 fingers or 3 fingers gripper. eg: j2n6s300 (default value) refers to jaco v2 6DOF service 3 fingers. Please be aware that not all options are valided for different robot types.
To avoid redundancy urdf for assistive models has been deleted. Please use the service 's' option instead. For Mico 1 and 2 use the tag 'm1' for both. For Jaco 1 and 2 use the tag 'j2' for both.
kinova_robotName and kinova_robotSerial were added to allow multiple robots under a ros master. For applications like moveIt! set kinova_robotName to your prefix for the robot in the URDF. For example you can launch two jaco robots by using the following -
roslaunch kinova_bringup kinova_robot.launch kinova_robotType:=j2n6s300 kinova_robotName:=left kinova_robotSerial:=PJ00000001030703130
roslaunch kinova_bringup kinova_robot.launch kinova_robotType:=j2n6s300 kinova_robotName:=right kinova_robotSerial:=PJ00000001030703133These parameters are optional and can be dropped off when only one robot is connected.
use_urdf specifies whether the kinematic solution is provided by the URDF model. This is recommended and is the default option.
When use_urdf:=true (default value), the kinematic solution is automatically solved by the URDF model.
The robot can be virtually presented in Rviz and the frames in Rviz are located at each of the joints.
To visulize the robot in Rviz, run $ rosrun rviz rviz, and select root as the world frame.
The robot model will synchronize the motion with the real robot.
If use_urdf:=false, the kinematic solution is the same as the DSP code inside the robot.
Node kinova_tf_updater will be activated to publish frames, and the frames are defined
according the classic D-H convention(frame may not located at joints). Even you are not able to visualize
the robot properly in Rviz, you would be able to observe the D-H frames in Rviz.
eg: roslaunch kinova_bringup kinova_robot.launch kinova_robotType:=j2n6s300 use_urdf:=true
If the robot is not able to move after boot, please try to home the arm by either pressing home button on the joystick or calling rosservice in the ROS service commands below.
rosservice call /'${kinova_robotType}'_driver/in/home_armJoint position control can be realized by calling KinovaComm::setJointAngles() in customized node, or you may simply call the node joints_action_client.py in the kinova_demo package. This function takes three parameters : kinova_robotType (eg. j2n6s300), unit {degree | radian} and value (angles for each joint). The function takes the option -r that will tell the robot if the angle values are relative or absolute. It also has the options -v for more verbose output and -h for help. The following code will drive the 6th joint of a 6DOF Jaco2 robot to rotate +10 degree (not to 10 degree), and print additional information about the joint position.
eg: rosrun kinova_demo joints_action_client.py -v -r j2n6s300 degree -- 0 0 0 0 0 10
Joint position can be observed by echoing two topics:
/'${kinova_robotType}_driver'/out/joint_angles (in degree) and
/'${kinova_robotType}_driver'/out/joint_state (in radians including finger information)
eg: rostopic echo -c /j2n6s300_driver/out/joint_state will print out joint names (rad), position, velocity (rad/s) and effort (Nm) information.
Another way to control joint position is to use interactive markers in Rviz. Please follow the steps below to active interactive control:
roslaunch kinova_bringup kinova_robot.launch kinova_robotType:=j2n6s300rosrun kinova_driver kinova_interactive_control j2n6s300rosrun rviz rvizworldchange InteractiveMarkers -> Updated Topic to /j2n6s300_interactive_control_Cart/update
Cartesian position control can be realized by calling KinovaComm::setCartesianPosition() in customized node. Alternatively, you may simply call the node pose_action_client.py in the kinova_demo package. This function takes three parameters : kinova_robotType (eg. j2n6s300), unit {mq | mdeg | mrad} (which refers to meter&Quaternion, meter°ree and meter&radian) and pose_value. The last argument, pose_value, is the position (in coordonates x,y,z) followed by the orientation (either 3 or 4 values based on unit). The unit of position is always meter, and the unit of orientation is different. Degree and radian are in relation to Euler Angles in XYZ order. Please be aware that the length of parameters are different when using Quaternion and Euler Angles. The function takes the option -r that will tell the robot if the angle values are relative or absolute. It also has the options -v for more verbose output and -h for help. The following code will drive a Jaco2 robot to move along +x axis for 1cm and rotate the hand for +10 degree along hand axis.
eg: rosrun kinova_demo pose_action_client.py -v -r j2n6s300 mdeg -- 0.01 0 0 0 0 10
The Cartesian coordinate of robot root frame is defined by the following rules:
The kinova_tool_pose_action (action server called by pose_action_client.py) will send Cartesian position commands to the robot and the inverse kinematics will be handled within the robot. Important The inverse kinematics algorithm that is implemented within Kinova robots is programmed to automatically avoid singularities and self-collisions. To perform those avoidance, the algorithm will restrict access to some parts of the robot's workspace. It may happen that the Cartesian pose goal you send cannot be reached by the robot, although it belongs to the robot's workspace. For more details on why this can happen, and what can you do to avoid this situation, please see the Q & A in issue #149. As a rule of thumb, if you are not able to reach the pose you are commanding in pose_action_client.py by moving your Kinova robot with the Kinova joystick, the robot will not be able to reach this same pose with the action server either. If you do not want to use the robot's IK solver, you can always use MoveIt instead.
The current Cartesian position is published via topic: /'${kinova_robotType}_driver'/out/tool_pose
In addition, the wrench of end-effector is published via topic: /'${kinova_robotType}_driver'/out/tool_wrench
Again, you can also use interactive markers in Rviz for Cartesian position :
roslaunch kinova_bringup kinova_robot.launch kinova_robotType:=j2n6s300rosrun kinova_driver kinova_interactive_control j2n6s300rosrun rviz rvizworldchange InteractiveMarkers -> Updated Topic to /j2n6s300_interactive_control_Cart/update
Executing multiple Cartesian waypoints without stopping
The action client executes one goal at a time. In case the user wants to give multiple waypoints to the robot without stopping at every waypoint, the service AddPoseToCartesianTrajectories can be used.
This service adds the commanded poses to a buffer that that maintained by the robot. The robot executes the poses in this buffer in the order that they are added, without stopping between poses.
The service ClearTrajectories can be used to clear the trajectory buffer in the base.
Cartesian position control can be realized by calling KinovaComm::setFingerPositions() in customized node. Alternatively, you may simply call the node fingers_action_client.py in the kinova_demo package. This function takes three parameters : kinova_robotType (eg. j2n6s300), unit {turn | mm | percent} and finger_value. The finger is essentially controlled by turn, and the rest units are propotional to turn for convenience. The value 0 indicates fully open, while finger_maxTurn represents fully closed. The value of finger_maxTurn may vary due to many factors. A proper reference value for a finger turn will be 0 (fully-open) to 6800 (fully-close). If necessary, please modify this variable in the code. The function also takes the option -r that will tell the robot if the angle values are relative or absolute. It also has the options -v for more verbose output and -h for help. The following code fully closes the fingers.
eg: rosrun kinova_demo fingers_action_client.py j2n6s300 percent -- 100 100 100
The finger position is published via topic: /'${kinova_robotType}_driver'/out/finger_position
The user has access to both joint velocity and Cartesian velocity (angular velocity and linear velocity). The joint velocity control can be realized by publishing to topic /'${kinova_robotType}_driver'/in/joint_velocity. The following command can move the 6th joint of a Jaco robot at a rate of approximate 10 degree/second. Please be aware that the publishing rate does affect the speed of motion.
eg: rostopic pub -r 100 /j2n6s300_driver/in/joint_velocity kinova_msgs/JointVelocity "{joint1: 0.0, joint2: 0.0, joint3: 0.0, joint4: 0.0, joint5: 0.0, joint6: 10.0}"
For Cartesian linear velocity, the unit is meter/second. Definition of angular velocity "Omega" is based on the skew-symmetric matrices "S = R*R^(-1)", where "R" is the rotation matrix. angular velocity vector "Omega = [S(3,2); S(1,3); S(2,1)]". The unit is radian/second. An example is given below:
eg: rostopic pub -r 100 /j2n6s300_driver/in/cartesian_velocity kinova_msgs/PoseVelocity "{twist_linear_x: 0.0, twist_linear_y: 0.0, twist_linear_z: 0.0, twist_angular_x: 0.0, twist_angular_y: 0.0, twist_angular_z: 10.0}"
The motion will stop once the publish on the topic is finished. Please be cautious when using velocity control as it is a continuous motion unless you stop it.
Note on publish frequency : The joint velocity is set to publish at a frequency of 100Hz, due to the DSP inside the robot which loops each 10ms. Higher frequency will not have any influence on the speed. However, it will fill up a buffer (size of 2000) and the robot may continue to move a bit even after it stops receiving velocity topics. For a frequency lower than 100Hz, the robot will not able to achieve the requested velocity.
Therefore, the publishing rate at 100Hz is not an optional argument, but a requirement.
Users can home the robot with the command below. It takes no argument and brings the robot to pre-defined home position. The command supports customized home position that users can define by using the SDK or JacoSoft as well.
rosservice call /'${kinova_robotType}_driver'/in/home_arm
Users can also enable and disable the ROS motion commands with these rosservices :
rosservice call /'${kinova_robotType}_driver'/in/start
/'${kinova_robotType}_driver'/in/stop
When stop is called, robot commands from ROS will not drive the robot until start is called. However, the joystick still has the control during this phase.
This lets the user control the robot by manually (by hand). The admittance force control can be actived and deactivated with these commands :
rosservice call /'${kinova_robotType}_driver'/in/start_force_control
rosservice call /'${kinova_robotType}_driver'/in/stop_force_controlThe user can move the robot by applying force/torque to the end-effector/joints. When there is a Cartesian/joint position command, the result motion will be a combination of both force and position commands.
Over time it is possible that the torque sensors develop offsets in reporting absolute torque. For this they need to be re-calibrated. The calibration process is very simple -
rosservice call /'${kinova_robotType}_driver'/in/set_zero_torquesSupport for the 7 dof robot has been added in this new release. All of the previous control methods can be used on a 7 dof Kinova robot.
The inverse kinematics of the 7 dof robot results in infinite possible solutions for a give pose command. The choice of the best solution (redundancy resolution) is done in the base of the robot considering criteria such as joint limits, closeness to singularities.
To see the full set of solutions, a new fuction is introduced in KinovaAPI - StartRedundantJointNullSpaceMotion(). When in this mode the Kinova joystick can be used to move the robot in null space while keeping the end-effector maintaining its pose.
The mode can be activated by calling the service SetNullSpaceModeState - ${kinova_robotType}_driver /in/set_null_space_mode_state
Pass 1 to service to enable and 0 to disable.
Torque control has been made more accessible. Now you can publish torque/force commands just like joint/cartesian velocity. To do this you need to :
Optional - Set torque parameters
Usually default parameters should work for most applications. But if you need to change some torque parameters, you can set parameters (listed at the end of page) and then call the service -
SetTorqueControlParameters ${kinova_robotType}_driver/in/set_torque_control_parameters
Switch to torque control from position control
You can do this using the service - SetTorqueControlMode ${kinova_robotType}_driver'/in/set_torque_control_mode
Publish torque commands rostopic pub -r 100 /j2n6s300_driver/in/joint_torque kinova_msgs/JointTorque "{joint1: 0.0, joint2: 0.0, joint3: 0.0, joint4: 0.0, joint5: 0.0, joint6: 1.0}"
Gravity compensation is done by default in the robot's base. This means that if the robot is commanded zero torques the robot does not fall under gravity. This case (zero commanded torque)
can be refered to as gravity compensated mode. The robot can be moved around freely by manually pushing its joints. You can try out this mode by using the command (for a j2n6s300)
rosrun kinova_demo gravity_compensated_mode.py j2n6s300 This command moves the robot to a candle-like pose, sets torques to zero, and then starts torque control mode. It publishes torque commands as [0,0,0,0,0,0], so the robot can be moved by pushing on individual joints.
It is posible to publish torque with or without gravity compensation by setting the parameter -
publish_torque_with_gravity_compensation: falseIf not torque command is sent after a given time (250ms by default), the controller will take an action: (0): The robot will return in position mode (1): The torque commands will be set to zero. By default, option (1) is set for Kinova classic robots (Jaco2 and Mico) while option (0) is set for generic mode.
Note - Although this release supports Ethernet connection, this feature is limited. Kinova will notify all users when Ethernet support is released for all customers.
Support for Ethernet connection has been added. All functionalities available in USB are available in Ethernet. To use ethernet follow these steps
To connect to robot via ethernet in ROS just set these parameters in robot_parameters.yaml -
connection_type: Ethernet
local_machine_IP: [your PC network IP]
subnet_mask: [your network subnet mask] serial_number: PJ00000001030703130 Leave commented out if you want to control the first robot found connected. jointSpeedLimitParameter1: 10 Joint speed limit for joints 1, 2, 3 in deg/sjointSpeedLimitParameter2: 20 Joint speed limit for joints 4, 5, 6 in deg/spayload: [0, 0, 0, 0] payload: [COM COMx COMy COMz] in [kg m m m] connection_type: USB Ethernet or USB
ethernet: {
local_machine_IP: 192.168.100.100,
subnet_mask: 255.255.255.0,
local_cmd_port: 25000,
local_broadcast_port: 25025
}Comment these out to use default values.
torque_parameters:
publish_torque_with_gravity_compensation: falsetorque_min: [1, 0, 0, 0, 0, 0, 0]torque_max: [50, 0, 0, 0, 0, 0, 0]safety_factor: 1com_parameters: [0,0,0,0,0,0,0, 0,0,0,0,0,0,0, 0,0,0,0,0,0,0, 0,0,0,0,0,0,0]
COM parameters, order [m1,m2,...,m7,x1,x2,...,x7,y1,y2,...y7,z1,z2,...z7]ROS provides a flexible GUI tool to interact with nodes/robots - rqt. You can use this tool to see topics published by the node - robot position, velocity, torque, etc. You can also launch services like AddPoseToCartesianTrajectory.
Monitoring topics
rqtOther plugins in rqt can similarly be used for quick interation with the robot.
More informations about Gazebo available here
More informations about MoveIt! available here
A few bug fixes:
Specific to 7 dof robot:
Specific to MICO robot:
For all robots:
Force/torque control is only for advanced users. Please use caution when using force/torque control api functions.
The joint_state topic currently reports the joint Names, Position,Velocity and Effort. Depending on your firmware version velocity values can be wrong.
When updating the firmware on the arm (e.g., using Development Center) the serial number will be set to "Not set" which will cause multiple arms to be unusable. The solution is to make sure that the serial number is reset after updating the arm firmware.
Some virtualization software products are known to work well with this package, while others do not. The issue appears to be related to proper handover of access to the USB port to the API. Parallels and VMWare are able to do this properly, while VirtualBox causes the API to fail with a "1015" error.
Previously, files under kinova-ros/kinova_driver/lib/i386-linux-gnu had a bug which required users on 32-bit systems to manually copy them into devel or install to work. This package has not been tested with 32-bit systems and this workaround may still be required. 64-bit versions seem to be unaffected.
Any bugs, issues or suggestions may be sent to support@kinova.ca