As quoted on RoboComp GSoD website,
RoboComp is an open-source Robotics framework providing the tools to create and modify software components that communicate through public interfaces. The Components may require, subscribe, implement, or publish interfaces in a seamless way.
The robocomp repo includes a wide range of components (maintained in smaller repo named robocomp-robolab) for different robotic applications such as motor control, localization and mapping, navigation, recognition, etc.
However, most of the components in robocomp-robolab repo currently lack detailed instructions on how to compile and how to use in different parameter configurations. This creates a huge obstacle for new developers who want to use components in their projects or contribute to the framework. The reason is that many components (i.e hokuyoComp) are a wrapper of external driver or libraries having many dependencies, which makes compiling and installing task difficult and requires device-specific knowledge to tune the parameters.
This project solves this problem by:
- Documenting crucial components of RoboComp
- Dividing components into categories for ease of management and sense of unity.
- Writing a tutorial on how to use and combine RoboComp components to achieve robotics tasks.
To write a concrete and detail component documentation using a top-down approach, one must at least be able to experience the content written in that document, because the final purpose of documentation is to transfer working knowledge to inherited developers. The proposed structure for each component doc is presented as follow:
- Description
- Compilation and Installation
- Configuration parameters
- Starting the component (usages)
- Known issues
An example of hokuyoComp component document is found in the link:
https://github.com/anindex/robocomp-robolab/tree/master-doc/components/hardware/laser/hokuyo
In the example, one firstly gathers information about the Hokuyo sensor specification, reads through the component code to understand the picture of component functionalities to write component descriptions. Next, understanding of RoboComp environment and knowledge of device-specific parameters as well as library dependencies would help to document the compilation, installation, and configuration process of the component. For instance, compiling hokuyoComp needs an old liburg0-dev deb package from Ubuntu 14.04, but the deb package is removed from Ubuntu PPA in later versions, thus we must do the workaround for compilation as stated in the doc. In this process, we can also record known issues to speed up debugging for new developers. Finally, component usages for different use scenarios are documented for easy integrating the component to RoboComp landscape for different robotics tasks.
This section describes completed documentation processes as well as unfinished future works in this project.
During the GSoD period, we have divided the components into hierarchy levels as follow:
- component: currently in use components
- deprecated/other: deprecated or unsupported components, only in the category for backward compatibility
- detection: components for cognitive tasks such as detection, recognition, and tracking the various target of interest, e.g faces, and emotions, human joint states, objects, or specialized tags.
- hardware: various driver components for robotics hardware, e.g robot base, camera, control equipment, Inertial Measurement Unit (IMU), laser sensors, and motors.
- interaction: human-computer interaction methods such as speech component.
- localization: components for state or pose estimation tasks for mobile entities.
- experimental: experimental components, which could be unstable.
The following list states the corresponding pull requests for documenting each of the categories:
- detection components: [link]
- hardware components:
- interaction components: [link]
- other components: [link]
- other PRs: typo fixing[link] and component category descriptions [link], RoboComp Innermodel Simulator (RCIS) [link]
Uncompleted documentations will be mentioned in Future work section.
The project has achieved the following aspects:
- Help new developers familiar with RoboComp faster, including dependencies, configuration, and usage.
- Create coherent between components as a whole.
- Demonstrate precisely the architecture design of each component, hence assist understanding of the developers in implementing solutions for the robotics tasks. Overall, the project increases RoboComp's repository comprehension. It will assist and guide RoboComp organization's students and developers in conceptual and implementation planning better.
Although most of the important RoboComp components were documented, the mentioned tutorial was not completed in time. Hence, the next crucial task for RoboComp documentation would be writing tutorials on using various components to solve a practical robotics task. These tutorials would speed up the comprehension of new developers to get a big picture of RoboComp and guide the users with instant interesting examples.