API access levels

Depending on your application and your proficiency with ROS and HAL, you may want to use the low-level APIs behind the robot application. However, there is not a single low-level API, instead the whole system is built on top of the ROS and Machinekit’s HAL.

High Level API (Python)

First, you may want to consider staying within the possibilities of the robot program. This will give you the advantage of using the robot UI for most tasks, such as for example teaching waypoints and at the same time you can still use Python to write your application software. Moreover, you can simply connect to other ROS nodes, written in the programming language of your choice, using the ROS API.

This is most useful if you are a power user who is familiar with ROS and you want to tweak some parts of the system.

ROS API (Python/C++/…)

If you are familiar with ROS, you can use the underlying ROS API directly. However, please be aware that the TRPL interpreter simplifies a lot of things such as for example move commands and offsets. You won’t be able to use the simplified API through ROS.

Run the following command on the robot computer to open a terminal in the robots Docker container.

Then source the ROS environment:

Now you can use the ROS command line tools to take a look at the published topics and services:

To connect to the ROS master from another Docker container use the following environment variables:

Trajectory Planning

Trajectory planning is provided through MoveIt. See https://ros-planning.github.io/moveit_tutorials/doc/getting_started/getting_started.html for more info.

The name of the move group is /move_group.

Alternatively to the /move_group action, one can generate a trajectory path using the plan_kinematics_path, and the /plan_sequence_path services.

Trajectory Execution

Moreover, MoveIt provides the /execute_trajectory action to execute ROS trajectory messages. If you need a good example on how to use the MoveIt without using the MoveIt libraries, you can take a look at the moveit_python implementation: https://github.com/mikeferguson/moveit_python/blob/ros1/src/moveit_python/move_group_interface.py

Alternatively, you can use the position trajectory controller interface directly /position_trajectory_controller/follow_joint_trajectory for more info take a look at the joint trajectory controller documentation http://wiki.ros.org/joint_trajectory_controller.

Compute FK/IK

You can use the services exposed by MoveIt to compute the forward and inward kinematics solutions.

/compute_fk

/compute_ik

Step or Interactive Jogging

Step based or interactive jogging can be executed as follows:

• Set the target pose or joint position using one of the following services

• Publish true to the /jog/execute topic with a rate of 10Hz

• Publish false to stop jog move

• The /jog/active, /jog/complete, and /jog/failed topics reports the current state of jogging.

Continuous Jogging

Continuous jogging uses the moveit_servo package from MoveIt. See https://ros-planning.github.io/moveit_tutorials/doc/realtime_servo/realtime_servo_tutorial.html for more info.

See the /jog_arm_server/ topics for more info.

Joint States

The robots current joint positions are published to 2 topics:

/joint_states @ 50Hz

/joint_states_throttle @ 16.6Hz

topic type: sensor_msgs/JointState

Pose States

The robots current Cartesian position is published to the following topics:

/pose_states_throttle @ 16.6Hz, current pose including offsets

/world_pose_states_throttle @ 16.6Hz, current pose in world coordinates

topic type: geometry_msgs/PoseStamped

Digital I/O

The following topics can be used to update and subscribe to digital I/O pins.

/hal_io/digital_in_<n>

/hal_ui/digital_out_<n>

topic type: std_msgs/Bool

Power the robot on/off

The robot can be turned on and off by using the following topic:

/hal_io/state_cmd, topic type std_msgs/UInt32, 0 means power off, 1 power on

The current robot status is published to this topic:

/hal_io/state_fb, topic type std_msgs/Int32, 0 means powered off, 1 powered on, -1 error

To reset the robot toggle the following topic:

/hal_io/reset`, topic type std_msgs/Bool, toggle to reset