Understanding ROS Message Payloads

To take full advantage of AMBF, it should be installed on Linux (Ubuntu 16, 17, 18) with a working installation of ROS. All the simulated/visual objects in the AMBF simulator (kinematic bodies, dynamic bodies, connected bodies, lights and cameras) are controllable using ROS messages. Each simulated/visual object (conveniently called afObject) communicates bidirectionally using ambf_msgs/ObjectState and ambf_msgs/ObjectCmd message types. The ObjectState is an outgoing message from the simulator that describes the state of the object. The ObjectCmd is the incoming message to the simulator and can be used to change the state of the corresponding afObject.

afObject Messages

The following table describes the payload of the State message for any afObject.

ObjectState Payload	Description
header	The ROS message header includes seq_number, time_stamp and frame_id. frame_id not used for now
name	The name of this afOjbect, set the AMBF Config file that loads this Object
wall_time	System time or Wall Clock in seconds
sim_time	Simulation clock which is incremented at each time-step. For RT sim_time == wall_time
mass	The mass of the afObject, for kinematic bodies this is 0
pInertia	The principal inertial of the afObject. Ignore for kinematic bodies
pose	The position and orientation as quaternion in the Parent frame
wrench	The accumulated external forces on this body in the Parent Frame. Not yet implemented
userdata	Array of floats for defining user data
userdata_description	String to define any user data
children_names	An array for children names that are connected to this afObject
joint_names	An array of joint names that this object is a parent of
joint_positions	Positions of joints that this object is a parent of

Similarly, the table below outlines the afObject Command Payload.

ObjectCmd Payload	Description
header	The ROS message header includes seq_number, time_stamp and frame_id. frame_id not used for now
pose	The pose command (position and orientation) in Parent frame
wrench	The wrench command (force and torque) for this body in World Frame
enable_position_controller	Boolean to inform which command to consider 1 for pose Command & 0 for wrench Command
joint_cmds	An array of joint commands for children joints
position_controller_mask	A mask to inform if the joint command is a Position Control Target or Effort Command

afWorld Messages

There exists a single instance of simulation World called afWorld. Similar to afObjects, afWorld is controllable using ambf_msgs/afWorldCmd message and relays its state using the ambf_msgs/afWorldState message.

WorldState Payload	Description
header	The ROS message header includes seq_number, time_stamp and frame_id. frame_id not used for now
dynamic_loop_freq	The frequency of underlying pyhsics solver loop
n_devices	The number of haptics/input devices currently connected AMBF Simulator
sim_step	The number of simulation steps of the physics solver. This keeps incrementing
wall_time	The System Clock (Wall Clock) in seconds
sim_time	The time of the physics simulation. For RT sim_time == wall_time

The afWorldCmd message payload is as follows:

WorldCmd Payload	Description
enable_step_throttling	Boolean to enable/disable phyics simulation throttling
step_clock	If the enable_step_throttling is set true, the toggle of field steps the simulation
n_skip_steps	The number of physics sub-steps to take in between each step_clock toggle

Controlling dynamic bodies vs kinematic bodies:

Kinematic and dynamic bodies are controlled using the same afCommand message type. If an object is kinematic (which could be a camera or a light or a plain kinematic body), the boolean flag enable_position_controller has to be set to 1 in the afObjectCmd message. This is necessary as by default the enable_position_controller is set to 0 and the AMBF simulator takes the wrench command. For kinematic bodies, wrench commands are meaningless.

If the corresponding body is Dynamic (has non-zero mass and inertia), the enable_position_controller can be set to 1 or 0 to inform the AMBF Simulator to consider Pose or Wrench commands respectively. For Position Commands, the AMBF Simulator runs an internal PID Loop. The gains for this controller are directly set in the AMBF Description of the body.

Parenting of bodies and joints:

It is important to point out the way parenting works in the AMBF Simulator. This table sheds some light on this where the nodes (circles) can be considered as bodies and the arrows as joints. The resulting parenting is shown in the same table.

Based on this image, children bodies are in fact all the bodies lower in the hierarchy to a specific body. This is reflected in the afObjectState and afObjectCommand messages.

Note:

A robot can have a large number of children bodies and joints and thus transmitting their names and positions using the children_name, joint_names and joint_positions payload fields can eat up the socket communication. Towards this end, the AMBF Description of the Robot / Multi-Body comes in handy. By default, the bodies are set to NOT publish children_names and joint_positions and ONLY publish joint_names. This can, of course, be overridden using the AMBF Description of Robot by specifying the following three optional fields for any afObject.

• publish children names: True or False
• publish joint names: True or False
• publish joint positions: True or False

Lastly, visual objects such as Cameras and Lights do not have joints.

Example

// TODO