Cheat Sheet

Gazebo support 

To run your Gazebo-based simulated robot on xbot2, you must add

a world plugin providing simulated clock information (only used when running xbot2-core --simtime)

a model plugin to expose the joint device

optionally, model plugins to expose force-torque sensors and IMUs

Follow this link for details and commented examples.

Synchronize with simulation time 

Run xbot2-core --simtime

Make sure that you are loading the provided ros_control and ros_io plugins on a non-realtime thread (see this example yaml file) Then, the following topics and services will be available (as well as others)

Joint state monitoring 

Reading rostopic echo /xbotcore/joint_states will output the robot joint state.

Sending joint references 

Publishing to rostopic pub /xbotcore/command will move the robot to the provided joint reference (only if the ros_control plugin is running!). Notice that torque and velocity references are subject to a timeout, and must therefore be published at a sufficiently high rate.

Interacting with plugins 

Calling rosservice call /xbotcore/get_plugin_list will provide the loaded plugin list.

For each plugin, rosservice call /xbotcore/<plugin_name>/switch <flag> will enable (flag = true) or disable (flag = false) the plugin. Besides the switch service, state will return the current plugin state according to its lifecycle state machine, and abort will immediately stop the plugin execution.

The /xbotcore/lifecycle_events topic will echo a message whenever a plugin changes its state.

Managing joint reference filtering 

Because the real-time loop which actually manages the robot joints typically runs way faster than a ROS controller loop, it is usually a good idea to enable the joint filter, and tune its cutoff frequency to a proper value.

To this purpose, rosservice call /xbotcore/enable_joint_filter <flag> will enable (flag = true) or disable (flag = false) the filtering of joint references (excluding torque); the filter bandwidth can be tuned with the services /xbotcore/set_filter_profile_[safe|medium|fast].

Cutoff frequencies corresponding to the three profiles can be customized through the /xbot/hal/joint_safety/filter_[safe|medium|fast]_cutoff_hz parameters.

A default filter cutoff can be set inside the configuration file through the parameter /xbot/hal/joint_safety/filter_cutoff_hz; the filter can be set to auto-start through the /xbot/hal/joint_safety/filter_autostart boolean parameter, as seen in this example

Joint safety 

The framework will automatically detect unsafe joint references, inside the joint_master component. Safety is evaluated after filtering (if enabled). Whenever an unsafe reference is detected, the joint devide is disabled, and must be re-enabled manually.

Reading the safety state 

The topic /xbotcore/joint_device_info will report

joint filter activation state

joint filter cutoff

joint device mask value (mask = 0 means joint is inactive)

The xbot2 console will report details about the reason of the joint device deactivation.

Restoring joint device 

Set a non-zero mask with the service /xbotcore/joint_master/set_control_mask.

Disabling safety (simulation only)

Add the following parameter to the configuration file

/xbot/hal/joint_safety/enable_safety: {value: true, type: bool}