AR Manger REST API
The Documentation for the REST-API is provided by Swagger-UI.
Swagger-ui is an open-source project to document REST-APIs. The complete configuration of the Website is provided by a single JSON config at Docker\swagger_config\AR-Manager_swagger_cfg.json
.
We refer the reader to the documentation Swager-ui for further instructions on how to extend this API-Documentation.
cd Docker
sudo docker-compose up
After successfully running the command the AR-Manager is ready to accept REST requests to start and stop containers.
You should see the following output of the server after sending a REST request: ![alt text](images/ServerSummary Get.png.png) As a default, the ros-sharp-com container is launched to establish connectivity between Unity and ROS and allows prototyping via roslibpy. You can send REST-Post requests to start instances of [UR3, UR5, ANYmal, UnityCollision] component.
The rest server can be accessed on port 5000 of the local host network.
By navigating in the Webbrowser of your choice to http://localhost:5001 the Swagger-ui REST-API documentation can be accessed.
TODO Update the cfg file to get clean API TEXT
For example to start a new robot navigate to Instances/POST
and expand the tab.
Hit the Try it out
Button to start an instance of the UR5 component.
Try it out your self to stop the Instance with the Delete Request or start an additional UR3.
Swagger-UI is especially hand for documenting REST APIs but not for quick prototyping. For sending REST request without Swagger-UI for prototyping we recommend using Postman.
To data source of each plot is specified as a tooltip xml tag.
The Unified Robot Description Format (URDF) describes the robot. A robot consists of links and joints. Each link contains information about its visual geometry, collision geometry, material, and inertial. Links are interconnected by different types of joints and most rigid-body robot kinematics can be captured within this format.
Let's have a look at a snippet of the Universal Robot 5 URDF at AR_Manager/src/cfg/UR5.xml
:
<joint name="wrist_1_joint" type="revolute">
<parent link="forearm_link"/>
<child link="wrist_1_link"/>
<origin rpy="0.0 1.57079632679 0.0" xyz="0.0 0.0 0.39225"/>
<axis xyz="0 1 0"/>
<limit effort="28.0" lower="-3.14159265359" upper="3.14159265359" velocity="3.2"/>
<dynamics damping="0.0" friction="0.0"/>
</joint>
<link name="wrist_1_link">
<visual>
<geometry>
<mesh filename="package://ur_description/meshes/ur5/visual/wrist1.dae"/>
</geometry>
<material name="LightGrey">
<color rgba="0.7 0.7 0.7 1.0"/>
</material>
</visual>
<collision>
<geometry>
<mesh filename="package://ur_description/meshes/ur5/collision/wrist1.stl"/>
</geometry>
</collision>
<inertial>
<mass value="1.219"/>
<origin rpy="0 0 0" xyz="0.0 0.093 0.0"/>
<inertia ixx="0.00255989897604" ixy="0.0" ixz="0.0" iyy="0.00255989897604" iyz="0.0" izz="0.0021942"/>
</inertial>
</link>
<joint name="wrist_2_joint" type="revolute">
<parent link="wrist_1_link"/>
<child link="wrist_2_link"/>
<origin rpy="0.0 0.0 0.0" xyz="0.0 0.093 0.0"/>
<axis xyz="0 0 1"/>
<limit effort="28.0" lower="-3.14159265359" upper="3.14159265359" velocity="3.2"/>
<dynamics damping="0.0" friction="0.0"/>
</joint>
The .dae
and .stl
files describe the robot geometry and collision boxes.
A joint name="wrist_1_joint" and joint name="wrist_2_joint" are interconnected by the link name="wrist_1_link"
By adding the following tooltip-tag the user can specify a plot that is physically linked to the wrist_1_link.
<tooltip
name="joint_position"
topic="/img/joint_position">
<parent link="wrist_1_link"/>
</tooltip>"""
The name
specifies the name of the tooltip. The topic
the ROS topic where the data is published and the parent link
defines the link the plot is attached to.
This modified XML including the appended tooltip is sending via a REST-Post request to the AR-Manager for a specified running instance. The send XML-file will be stored in the urdf.dyn attribute of the instance in the AR-Manager. The AR-Manager publishes the state change of the system via its ROS Node.
The Unity ARRobotInteraction.Base constantly monitors the incoming URDF files and can detect the new or updated tooltip tag. According to this ARRobotInteraction.Data creates a new plot that can be activated or deactivated by the operator of the HoloLens.
In the left image the wrist link is highlighted in blue and the plot is active. The plot shows data about the joint angle of the link. In the right image the user has hidden the plot and the link is now orange indicating that data is available to be visualized on demand.