Han´s Robot Joints - ROS2 API

ROS 2 servo interface overview

Each Han´s Robot Joints makes use of HRIM in order to operate the actuator and monitor its status. This is a description of the available topics, services and actions :

Topic models:

• GoalRotaryServo model allows to control the position, velocity or/and effort.
• StateRotaryServo.msg publishes the status of the motor.

Services:

• SpecsRotaryServo.srv is a custom message which reports the main features of the device.
• EnableDisable.srv disables or enables the servo motor.
• ClearFault.srv sends a request to clear any fault in the servo motor.
• Stop.srv request to stops any ongoing movement.
• OpenCloseBrake.srv opens or closes the servo motor brake.

Actions:

• GoalJointTrajectory action that allows to move the joint using a trajectory msg.

Remember that the naming convention in H-ROS is the following:

• nodes /hrim_<device_kind>_<device_name>
• topic /hrim_<device_kind>_<device_name>/<topic_name>.
• service /hrim_<device_kind>_<device_name>/<service_name>.

Note the Han´s Robot Joints are two axis modules. This means that each device has topics specific for each axis. Therefore, in the case of goal topic we will have two different topics, goal_axis1 and goal_axis2. However, other topics work at a device level, for example enable.

Topic Name Rate Pub/Sub
goal /hrim_actuator_rotaryservo_XXXXXXXXXXXX/goal_axis1 200 Hz Sub
goal /hrim_actuator_rotaryservo_XXXXXXXXXXXX/goal_axis2 200 Hz Sub
state /hrim_actuator_rotaryservo_XXXXXXXXXXXX/state_axis1 200 Hz Pub
state /hrim_actuator_rotaryservo_XXXXXXXXXXXX/state_axis2 200 Hz Pub

Service Name
specs /hrim_actuator_rotaryservo_XXXXXXXXXXXX/specs
enable servo /hrim_actuator_rotaryservo_XXXXXXXXXXXX/enable
disable servo /hrim_actuator_rotaryservo_XXXXXXXXXXXX/disable
clear fault /hrim_actuator_rotaryservo_XXXXXXXXXXXX/clear_fault
stop /hrim_actuator_rotaryservo_XXXXXXXXXXXX/stop_axis1
stop /hrim_actuator_rotaryservo_XXXXXXXXXXXX/stop_axis2
close brake /hrim_actuator_rotaryservo_XXXXXXXXXXXX/close_brake_axis1
close brake /hrim_actuator_rotaryservo_XXXXXXXXXXXX/close_brake_axis2
open brake /hrim_actuator_rotaryservo_XXXXXXXXXXXX/open_brake_axis1
open brake /hrim_actuator_rotaryservo_XXXXXXXXXXXX/open_brake_axis2

Action Name
goal joint trajectory /hrim_actuator_rotaryservo_XXXXXXXXXXXX/trajectory_axis1
goal joint trajectory /hrim_actuator_rotaryservo_XXXXXXXXXXXX/trajectory_axis2

Generic interface

There are also generic topics/services common to all type of components.

• ID.srv which publishes the general identity of the component.
• Power.msg that publishes the power consumption.
• Status.msg which inform about the resources that are consumed, SpecsCommunication.msg and StateCommunication.msg that are created to inform about communication aspects.
• Simulation3D.srv and SimulationURDF.srv.msg that sends the device 3D model and related information.
• StateCommunication.msg is a custom message which reports the state of the device network.
• SpecsCommunication.srv is a custom message which reports the specs of the device network.

Topic Name Rate Pub/Sub
status /hrim_actuator_rotaryservo_XXXXXXXXXXXX/status 1 Hz Pub
power /hrim_actuator_rotaryservo_XXXXXXXXXXXX/power 1 Hz Pub
state comm /hrim_actuator_rotaryservo_XXXXXXXXXXXX/state_comm 1 Hz Pub

Service Name
id /hrim_actuator_rotaryservo_XXXXXXXXXXXX/id
module_3d /hrim_actuator_rotaryservo_XXXXXXXXXXXX/module_3d
module_urdf /hrim_actuator_rotaryservo_XXXXXXXXXXXX/module_urdf
specs comm /hrim_actuator_rotaryservo_XXXXXXXXXXXX/specs_comm

Listing topics and services using the command line

Listing the nodes

To visualize the nodes that are running in the ROS 2.0 network in the terminal, you should run ros2 node list:

$ros2 node list /hrim_actuator_rotaryservo_XXXXXXXXXXXX /hrim_actuator_rotaryservo_XXXXXXXXXXXX_generic Listing the topics To visualize the topics that are been exposed by MARA, you should run ros2 topic list. Then, you will see the following topics: $ ros2 topic list

/hrim_actuator_rotaryservo_XXXXXXXXXXXX/goal_axis1
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/goal_axis2
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/state_axis1
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/state_axis2
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/power
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/state_comm
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/status

Listing the services

To visualize the services that are been exposed by MARA, you should run ros2 service list. Then, you will see the following services:

$ros2 service list /hrim_actuator_rotaryservo_XXXXXXXXXXXX/id /hrim_actuator_rotaryservo_XXXXXXXXXXXX/module_3d /hrim_actuator_rotaryservo_XXXXXXXXXXXX/module_urdf /hrim_actuator_rotaryservo_XXXXXXXXXXXX/specs /hrim_actuator_rotaryservo_XXXXXXXXXXXX/specs_comm Listing topics and services from actions Actions are compossed by topics and services. However, these topics are not meant to be used directly but using action interfaces. Action topics and services are hidden but it is possible to visualize them from the command line using the --include-hidden-topics and --include-hidden-services parameters. $ ros2 topic --include-hidden-topics list

/hrim_actuator_rotaryservo_XXXXXXXXXXXX/trajectory_axis1/_action/feedback
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/trajectory_axis1/_action/status
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/trajectory_axis2/_action/feedback
/hrim_actuator_rotaryservo_XXXXXXXXXXXX/trajectory_axis2/_action/status
$ros2 service --include-hidden-services list /hrim_actuator_rotaryservo_XXXXXXXXXXXX/trajectory_axis1/_action/cancel_goal /hrim_actuator_rotaryservo_XXXXXXXXXXXX/trajectory_axis2/_action/cancel_goal Topics Goal This topic controls the position, velocity or/and effort by using the message GoalRotaryServo.msg. This message allows to control the joint in different ways depending the control type specified in the message. Here we have a list of the available different types of control: • CONTROL_TYPE_NONE: • CONTROL_TYPE_POSITION: • CONTROL_TYPE_EFFORT: • CONTROL_TYPE_VELOCITY: • CONTROL_TYPE_POSITION_VELOCITY: • CONTROL_TYPE_POSITION_EFFORT: • CONTROL_TYPE_VELOCITY_EFFORT: • CONTROL_TYPE_POSITION_VELOCITY_EFFORT: For example, in order to move an axis we will send the positon using a goal msg with a position-velocity control type. We could send for example a command to move the axis 1 to 0.5 rad position with a 0.1 rad/s velocity: $ ros2 topic pub -1 /hrim_actuator_rotaryservo_XXXXXXXXXXXX/goal_axis1 hrim_actuator_rotaryservo_msgs/GoalRotaryServo "{control_type: 4, position: 0.5, velocity: 0.1}"

To visualize the topic in the terminal, just type: ros2 topic echo /hrim_actuator_rotaryservo_XXXXXXXXXXXX/goal. We should observe the goals we are sending.

$ros2 topic echo /hrim_actuator_rotaryservo_XXXXXXXXXXXX/goal header: stamp: sec: 0 nanosec: 0 frame_id: '' control_type: 4 position: 0.5 velocity: 0.10000000149011612 effort: 0.0 State The state topic gives us information about the motor conditions and the causes in case of error by using the message StateRotaryServo. To visualize the information about this topic in the terminal, you need to type ros2 topic echo /hrim_actuator_rotaryservo_XXXXXXXXXXXX/state: $ ros2 topic echo /hrim_actuator_rotaryservo_XXXXXXXXXXXX/state

stamp:
sec: 2198
nanosec: 553000000
frame_id: ''
goal: 0.0
position: -1.2887455911325674e-06
error: 1.2887455911325674e-06
velocity: -2.501547525126175e-07
effort: 0.0
moving: false
fault: 0
control_type: 0

Services

Specs

This service shows the device features. To visualize the information in the terminal type: ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/specs hrim_actuator_rotaryservo_srvs/SpecsRotaryServo {}

$ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/specs hrim_actuator_rotaryservo_srvs/SpecsRotaryServo {} response: hrim_actuator_rotaryservo_srvs.srv.SpecsRotaryServo_Response(control_type=4, range_min=-6.27, range_max=6.27, precision=8.722222e-05, rated_speed=1.46607657, reachable_speed=1.46607657, rated_torque=9.0, reachable_torque=13.0, temperature_range_min=-10.0, temperature_range_max=50.0) Enable This service request the HAN's module to enable the servo. Once the servo is enabled the module will accept commands for both axis. In order to enable the servo using the command line you need to type: ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/enable hrim_actuator_rotaryservo_srvs/EnableDisable {} $ ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/enable hrim_actuator_rotaryservo_srvs/EnableDisable {enable: true}

response:
hrim_actuator_rotaryservo_srvs.srv.EnableDisable_Response(success=True, message="module is enabled")

Disable

This service request the HAN's module to enable the servo. Once the servo is enabled the module will accept commands for both axis. In order to enable the servo using the command line you need to type: ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/disable hrim_actuator_rotaryservo_srvs/EnableDisable {}

$ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/disable hrim_actuator_rotaryservo_srvs/EnableDisable {enable: false} response: hrim_actuator_rotaryservo_srvs.srv.EnableDisable_Response(success=True, message="module is disabled") Stop This service sends a request to stop a movement of a specific axis. For example if we want to stop the movement of the axis 1 we would write in the terminal type: ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/stop_axis1 hrim_actuator_rotaryservo_srvs/Stop {} $ ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/stop_axis1 hrim_actuator_rotaryservo_srvs/Stop {}

response:
hrim_actuator_rotaryservo_srvs.srv.EnableRotaryServo_Response(success=True, message="motor is stopped")

Clear fault

This service sends a request to clear any fault in the servo motor.

Open brake

When the module is not enabled, you can open the brake of the corresponding module using this service. For example:

$ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/open_brake1 hrim_actuator_rotaryservo_srvs/OpenCloseBrake {open: true} response: hrim_actuator_rotaryservo_srvs.srv.OpenCloseBrake_Response(success=True, message="brake is openned") Close brake When the module is not enabled, you can close the brake of the corresponding module using this service. For example: $ ros2 service call /hrim_actuator_rotaryservo_XXXXXXXXXXXX/close_brake1 hrim_actuator_rotaryservo_srvs/OpenCloseBrake {open: true}

response:
hrim_actuator_rotaryservo_srvs.srv.OpenCloseBrake_Response(success=True, message="brake is closed")

Actions

GoalJointTrajectory

The joint trajectory action provides an action interface for tracking trajectory execution. It passes trajectory goals to the modular joint controller, and reports success when they have finished executing. The joint trajectory action can also enforce constraints on the trajectory, and abort trajectory execution when the constraints are violated.

The joint trajectory action interface receives goals each of which describes the trajectory that the controller will attempt to execute. This message contains:

• The joint name of the axis.
• a set of waypoints, each of them containing the desired position, velocity and acceleration at each joint. It is assumed that the values in the waypoints are ordered.

The JointTrajectory message has two fields for managing time:

• the stamp field in the header of the message.
• a time_from_start value for each waypoint.

The stamp in the header determines when the execution of the trajectory starts. Once the time in the stamp field passes, the controller will begin to move towards the first waypoint in the trajectory. The controller attempts to achieve each waypoint at the time obtained by adding that waypoint's time_from_start value to the time in stamp. The time_from_start values must be monotonically non-decreasing or else the trajectory will be considered invalid.

The joint trajectory action interface sends feedback about the state of the joint during the execution of the trajectory. This message contains:

• actual returns the current position of the motor.
• desired returns the desired position of the motor.
• error returns the error between the current position and the desired position.

The joint trajectory action interface returns a message when the trajectory finished (because it reaches the goal or it's cancel). This message contains:

• error shows the number code of the error.
• error_string if an error has happened the field returns a string with more details about the error.