Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- RoboComp
- Technischer Redakteur:
- Le Thai An
- Projektname:
- Grundlegende Komponenten von RoboComp
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
Motivation
RoboComp ist eines der bekanntesten Robotik-Frameworks für Forschung und praktische Anwendungen. Das Robocomp-Repository enthält eine breite Palette von Komponenten (in einem kleineren Repository namens robocomp-robolab gepflegt) für verschiedene Roboteranwendungen wie Motorsteuerung, Lokalisierung und Kartierung, Navigation, Erkennung usw. Das Repository der Komponenten enthält jedoch keine detaillierten Dokumentationen zur Kompilierung oder Verwendung der einzelnen Komponenten, was die eingeschränkte Nutzerfreundlichkeit für neue Entwickler erklärt. In diesem Vorschlag soll dieses Problem gelöst werden, indem wichtige Komponenten von RoboComp dokumentiert und ein Beispielnutzungsdokument für die Kombination verschiedener Komponenten zur Lösung einer bestimmten Roboteraufgabe zusammengestellt werden. Die Details des Dokumentationsprozesses werden im nächsten Abschnitt erläutert. Danach folgt der Abschnitt zu Meilensteinen, in dem der Zeitrahmen für die Fertigstellung des Projekts geplant wird. Abschließend werden noch einige Hinweise zum Dokumentationsprozess erwähnt.
Beschreibung
Wie bereits erwähnt, hat dieses Projekt zwei Hauptziele:
- Detaillierte Beschreibung, Kompilierung und Installation, Konfiguration, Verwendung und bekannte Probleme der einzelnen Komponenten in RoboComp
- Erstellen Sie einen Beispielleitfaden, in dem verschiedene Komponenten in der RoboComp-Umgebung verwendet werden, um eine bestimmte Roboteraufgabe zu lösen, z. B. die Lokalisierung.
Für die meisten grundlegenden Komponenten im Robocomp-Robolab-Repository gibt es derzeit keine detaillierten Anweisungen zur Kompilierung und Verwendung in verschiedenen Parameterkonfigurationen. Das ist ein großes Hindernis für neue Entwickler, die Komponenten in ihrem Projekt verwenden oder zum Framework beitragen möchten. Der Grund dafür ist, dass viele Komponenten einen externen Treiber oder Bibliotheken umfassen, die viele Abhängigkeiten haben, was die Kompilierung und Installation erschwert. Darüber hinaus umschließen viele Komponenten komplexe Gerätetreiber (z. B. generisches hokuyoComp), um eine Nachrichtenschnittstelle in RoboComp bereitzustellen, für die gerätespezifisches Wissen zur Feinabstimmung der Parameter erforderlich ist.
Daher ist eine detaillierte Dokumentation, die Gerätebeschreibungen, Abhängigkeitsauflösungen und Verwendungen umfasst, für Open-Source-Beiträge unerlässlich. Ein Beispiel für mein Arbeitsdokument „hokuyoComp“ finden Sie unter folgendem Link:
https://github.com/anindex/robocomp-robolab/tree/master/components/hokuyoComp
Um eine konkrete und detaillierte Komponentendokumentation mit dem Top-Down-Ansatz zu erstellen, muss man zumindest in der Lage sein, die Inhalte dieses Dokuments zu erleben, da der letztendliche Zweck der Dokumentation darin besteht, Arbeitswissen an nachfolgende Entwickler weiterzugeben. Die vorgeschlagene Struktur für jedes Komponentendokument wird wie folgt dargestellt:
- Beschreibung
- Kompilierung und Installation
- Konfigurationsparameter
- Komponente starten (Nutzungen)
- Bekannte Probleme
In diesem Beispiel sammelt man zuerst Informationen über die Hokuyo-Sensorspezifikationen und liest den Komponentencode, um die Funktionen der Komponenten zu verstehen und Komponenten zu beschreiben. Außerdem ist es hilfreich, die RoboComp-Umgebung zu kennen und Kenntnisse über gerätespezifische Parameter sowie Bibliotheksabhängigkeiten zu haben, um die Kompilierung, Installation und Konfiguration der Komponente zu dokumentieren. Für die Kompilierung von hokuyoComp ist beispielsweise das alte deb-Paket „liburg0-dev“ von Ubuntu 14.04 erforderlich. Dieses deb-Paket wird jedoch in einer späteren Version aus dem Ubuntu PPA entfernt. Daher müssen wir die in der Dokumentation beschriebene Umgehung für die Kompilierung verwenden. Bei diesem Vorgang können wir auch bekannte Probleme erfassen, um das Debuggen für neue Entwickler zu beschleunigen. Schließlich werden die Komponentennutzungen für verschiedene Anwendungsfälle dokumentiert, um die Komponente für verschiedene Roboteraufgaben einfach in die RoboComp-Landschaft zu integrieren.
Meilensteine
In diesem Abschnitt wird ein erster Zeitrahmen für die Erreichung der genannten Projektziele geplant. Wir wählen die zu verfassenden Komponentendokumente nach Kategorien aus (z. B. Kamerakomponenten, Laserkomponenten). Die aktuelle Schätzung der Zeit für die Fertigstellung des Dokuments „Komponenten“ basiert auf der Zeit, die für die Fertigstellung der Beispieldokumente für hokuyoComp benötigt wurde. Der Zeitplan sieht so aus:
1. Aug.–1. Sept.: Bindung der Community:
- Wöchentliche Besprechung einrichten, um den Projektumfang und die Erwartungen sowohl von Autoren als auch von beratenden Personen festzulegen
- Ein tiefes Verständnis des RoboComp-Frameworks gewinnen.
2. September bis 2. November: Erstellen von Dokumenten für jede Komponente im robocomp-robolab-Repository mit iterativen Verfeinerungen zwischen Mentoren und Autoren in Besprechungen (voraussichtlich Fertigstellung der meisten nicht dokumentierten Dokumente)
2. bis 26. November: Verfassen eines allgemeinen Dokuments als Beispiel für die Verwendung verschiedener Komponenten zur Lösung einer Roboteraufgabe.
27.–29. November: Berichte zum Ende des Projekts.
Nach GSoD 2019: Ich möchte mit RoboComp in Kontakt bleiben, um meine Arbeiten weiter zu verbessern und zu pflegen.
Abschließende Hinweise
Es ist wichtig, ein allgemeines Beispiel dafür zu schreiben, wie verschiedene Komponenten in die RoboComp-Umgebung eingebunden werden, damit Nutzer einen Überblick über die RoboComp-Funktionen erhalten. Dieses Beispieldokument wird mit Mentoren besprochen, um zu entscheiden, welche Roboteraufgabe je nach aktueller Implementierung von RoboComp geeignet ist.