# Asynchronous multi-body framework

Asynchronous multi-body framework (AMBF) is an open-source 3D versatile simulator for robots developed in April 2019. This multi-body framework provides a real-time dynamic simulation of multi-bodies such as robots, free bodies, and multi-link puzzles, paired with real-time haptic interaction with various input devices. The framework integrates a real surgeon master console, haptic or not, to control simulated robots in real-time. This feature results in the simulator being used in real-time training applications for surgical and non-surgical tasks. It offers the possibility to interact with soft bodies to simulate surgical tasks where tissues are subject to deformations. It also provides a Python Client to interact easily with the simulated bodies and train neural networks on real-time data with in-loop simulation. It includes a wide range of robots, grippers, sensors, puzzles, and soft bodies. Each simulated object is represented as an afObject; likewise, the simulation world is represented as an afWorld. Both utilize two communication interfaces: state and command. Through the State command, the object can send data outside the simulation environment, while the Command allows to apply commands to the underlying afObject.
The AMBF simulator uses several external packages including CHAI-3D for the integration of input devices, Bullet Physics for simulating rigid and soft bodies, Open-GL, GLFW.
It is compatible with Ubuntu 16.04 and Ubuntu 18.04 but it has been also tested on macOs Maverick and macOS Mojave.
The simulator finds applications in many fields such as multi-bodies simulation, manipulation of robotic manipulators, real-time training for surgical and non-surgical tasks, and reinforcement learning.

## AMBF file format

The asynchronous multi-body framework introduces a new robot description file format: the AMBF description format or ADF. The description format is based on YAML which allows to modify, create or test multi-bodies in an easy way thanks to its human readability. The idea is that a robot is a spatial tree of bodies where joints are parts of links. The AMBF description file can be seen as composed by blocks. Each of these blocks contains the data for a single independent body such that it can be modified or removed without influencing the other blocks. The header list is located at the beginning of the file and it contains global parameters and all the elements that define the specific description file such as bodies, visual elements and constraints.
This file format allows also to define different multi-bodies or multi-robots in the same description file.

## Features
### ROS communication

The simulator is integrated with ROS (Robot Operating System), a middle-ware that handles the communication with robots. ROS allows to control the simulated robot through external codes, and it also offers useful plotting (RQT Plot) and logging (ROS Bag) tools. The Asynchronous Framework remains isolated from ROS-based run-time mechanics while being able to leverage its tools. High-speed asynchronous communication is implemented via ROS-topic in the AMBF framework library. Both C++ and Python can be used to interact with simulated robots, multi bodies, kinematic and visual objects in the simulator.

### Python client

The Python Client provides the possibility to control different afObject while keeping a high communication speed. This allows managing the ROS communication making the process of controlling simulated bodies much easier compared to any other simulator. The communication between the Client and the AMBF simulator is managed through ROS as middle-ware. The Client uses bidirectional communication such that it is possible to set commands to the bodies and at the same time to read their states using a library of Python functions. These functions are used, for example, to set or get the position and orientation of bodies as well as control the wrench acting on a body or get the number of joints connected to it. When used, an instance of the client is created, and it is connected to the simulation. This creates callable objects from ROS topics and initiates a shared pool of threads for bidirectional communication. Each callable object has a WatchDog timer that resets commands if the timing condition fails.
Moreover, the Python Client is used for the training of reinforcement learning agents on real-time data.

### Input interface device

The framework allows integrating the real master console to manipulate simulated bodies in real-time. These interfaces are also referred to as Input Interface Device or IIDs and can be haptic or not. Several input interface are already included in the simulator such as the Geomagic Phantom, Falcon Novint, Razer Hydra, and dVRK MTM. Others can be easily included in the simulator by defining them in the input_device.yaml file. Each input interface is simulated as a dynamic end-effector (SDE) that can be bound or not to any simulated body. The simulated end-effector is controlled using a dynamic control law based on the motion of the input devices. The root link is the base of the simulated end-effector to which the input device is connected. Usually, the state of the input interface is in the reference frame of the device itself while the end-effector is with respect to the world frame therefore a transform mapping is needed in order to have the states converted to a common frame. For each element some properties can be specified including the following:
* Workspace scaling: it scales the motion of the input device in simulation.
* Simulated multibody: it specifies the multi-body that emulates the external device within the simulated AMBF scene. Different descriptions files such as grippers can be chosen to be implemented in the simulation.
* Haptic gain: it is a set of gains for controlling the force feedback applied on the input interface device.
* Controller gain: it is used for scaling the wrench for the simulated end-effector.
* Pair cameras filed: it is used to set one or more cameras to be paired with the IID-SDE pair.

### Soft bodies

In addition to rigid bodies, AMBF provides support for soft bodies. Soft bodies are defined as rigid bodies with additional parameters that can be tuned to define the behavior of the soft body. The interaction between bodies is provided by the Bullet's solver, which handles the dynamics of both rigid and soft bodies.
Soft bodies are represented as a collection of interconnected inertial nodes that can collide with other objects in the scene. The interconnection is generalized as a three-dimensional spring that accounts for the tension, torsion, and flexion. The position of each node is computed using the symplectit Euler method at each time-step. A high-quality mesh for visualization and a lower resolution mesh to represent the soft-body can be specified for each soft body.

### Blender add-on

AMBF includes an add-on with Blender that allows the user to create new models or modify existing models according to their purpose. Blender has large community support for graphic designers and represents an immediate and intuitive interface for the user to create or modify bodies. The Blender-to-AMBF add-on is bidirectional meaning that the user can both import objects defined through the AMBF file format and create both high and low-resolution files and subsequently AMBF YAML configuration files of complex robots and multi-bodies. This tool facilitates the creation process of new elements by allowing the user to tune rigid and soft bodies with real-time visual feedback.