Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- RoboComp
- Redactor técnico:
- Le Thai An
- Nombre del proyecto:
- Componentes básicos de RoboComp
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Motivación
RoboComp es uno de los frameworks de robótica más conocidos para aplicaciones prácticas y de investigación. El repositorio Robocomp incluye una amplia variedad de componentes (mantenidos en un repositorio más pequeño llamado robocomp-robolab) para diferentes aplicaciones robóticas, como control de motores, localización y asignación, navegación, reconocimiento, etc. Sin embargo, el repositorio de componentes carece de documentación detallada para la compilación o el uso de cada componente, por lo que la usabilidad para los desarrolladores nuevos es limitada. El objetivo de esta propuesta es resolver este problema mediante la documentación de componentes cruciales de RoboComp, así como la compilación de un documento de uso de ejemplo para combinar diferentes componentes y resolver una tarea de robótica específica. Los detalles del proceso de documentación se analizarán en la siguiente sección y, luego, se seguirá con la sección de eventos importantes para planificar el período para completar el proyecto. Por último, se mencionan algunas notas sobre el proceso de documentación.
Descripción
Como se mencionó, este proyecto tiene dos objetivos principales:
- Documenta la descripción detallada, la compilación y la instalación, la configuración, los usos y los problemas conocidos de cada componente de RoboComp
- Escribe una guía de ejemplo en la que se usen diferentes componentes del entorno de RoboComp para resolver una tarea específica de robótica, es decir, la localización.
Actualmente, la mayoría de los componentes básicos del repositorio robocomp-robolab carecen de instrucciones detalladas para compilarlos y usarlos en diferentes configuraciones de parámetros. Esto crea un gran obstáculo para los desarrolladores nuevos que desean usar componentes en su proyecto o contribuir al framework. El motivo es que muchos componentes son un wrapper de controladores o bibliotecas externos que tienen muchas dependencias, lo que dificulta la tarea de compilación e instalación. Además, muchos componentes unen controladores de dispositivos complejos (es decir, hokuyoComp genérico) para proporcionar una interfaz de mensajes en RoboComp, que requiere conocimientos específicos del dispositivo para ajustar los parámetros.
Por lo tanto, la necesidad de documentación detallada, que comprende las descripciones de los dispositivos, la resolución de dependencias y los usos, es esencial para la contribución de código abierto. En el siguiente vínculo, encontrarás un ejemplo de mi documento de componentes hokuyoComp:
https://github.com/anindex/robocomp-robolab/tree/master/components/hokuyoComp
Para escribir una documentación específica y detallada sobre componentes con un enfoque descendente, es necesario al menos poder experimentar el contenido escrito en ese documento, ya que el objetivo final de la documentación es transferir el conocimiento práctico a los desarrolladores heredados. La estructura propuesta para cada documento de componentes se presenta de la siguiente manera:
- Descripción
- Compilación e instalación
- Parámetros de configuración
- Inicio del componente (usos)
- Problemas conocidos
En el ejemplo, primero se recopila información sobre la especificación del sensor Hokuyo, se lee el código del componente para comprender el panorama de las funciones del componente y, luego, se escriben las descripciones de los componentes. Luego, comprender el entorno de RoboComp y conocer los parámetros específicos del dispositivo, así como las dependencias de la biblioteca, ayudaría a documentar el proceso de compilación, instalación y configuración del componente. Por ejemplo, la compilación de hokuyoComp necesita el paquete deb de liburg0-dev anterior de Ubuntu 14.04, pero el paquete deb se quita del PPA de Ubuntu en versiones posteriores, por lo que debemos usar la solución alternativa para la compilación, como se indica en el documento. En este proceso, también podemos registrar problemas conocidos para acelerar la depuración de los desarrolladores nuevos. Por último, se documentan los usos de los componentes para diferentes situaciones de uso para integrar fácilmente el componente en el panorama de RoboComp para diferentes tareas de robótica.
Logros
En esta sección, se planifica un marco de tiempo inicial para completar los objetivos mencionados del proyecto. Seleccionaremos los documentos de componentes para escribir en función de las categorías (p. ej., componentes de la cámara, componentes láser). La estimación actual del tiempo para completar el documento de componentes se basa en el tiempo que tarda en completar los documentos de ejemplo de hokuyoComp. El horario es el siguiente:
Del 1 de agosto al 1 de septiembre: Vinculación con la comunidad:
- Establecer reuniones semanales para establecer los alcances del proyecto, así como las expectativas del escritor y los mentores
- Comprender en profundidad el framework de RoboComp
Del 2 de septiembre al 2 de noviembre: Escritura de documentos para cada componente en el repositorio de robocomp-robolab con iteraciones de perfeccionamiento entre los mentores y el escritor a través de reuniones (se espera completar la mayoría de los documentos sin documentar)
Del 2 al 26 de noviembre: Escribir un documento general como ejemplo para usar diferentes componentes para resolver una tarea de robótica.
Del 27 al 29 de noviembre: Informes de fin de proyecto.
Después de GSoD 2019: Me gustaría mantenerme conectado con RoboComp para mejorar y mantener mis trabajos.
Notas finales
Es fundamental escribir un ejemplo general de cómo integrar diferentes componentes en el entorno de RoboComp para que los usuarios comprendan el panorama general de las funciones de RoboComp. Este documento de ejemplo se analizará en más detalle con los mentores para decidir qué tarea de robótica es adecuada según la implementación actual de RoboComp.