Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo del progetto
- Organizzazione open source:
- RoboComp
- Technical Writer:
- Le Thai An
- Nome del progetto:
- Componenti di base di RoboComp
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Motivazione
RoboComp è uno dei framework di robotica più noti per la ricerca e le applicazioni pratiche. Il repository robocomp include una vasta gamma di componenti (gestita in un repository più piccolo denominato robocomp-robolab) per diverse applicazioni robotiche come controllo del motore, localizzazione e mappatura, navigazione, riconoscimento e così via. Tuttavia, il repository dei componenti manca di documentazione dettagliata per la compilazione o l'utilizzo di ciascun componente, da qui l'usabilità limitata per i nuovi sviluppatori. Questa proposta mira a risolvere il problema documentando i componenti cruciali di RoboComp e compilando un documento di esempio sull'utilizzo per combinare diversi componenti al fine di risolvere un'attività robotica specifica. I dettagli della procedura di documentazione verranno discussi nella sezione successiva, seguita dalla sezione relativa ai traguardi per la pianificazione del periodo di tempo necessario per completare il progetto. Infine, vengono menzionate alcune note sul processo di documentazione.
Descrizione
Come accennato, questo progetto ha due obiettivi principali:
- Documenta la descrizione dettagliata, la compilazione e l'installazione, la configurazione, gli utilizzi e i problemi noti relativi a ciascun componente di RoboComp
- Scrivi una guida di esempio che utilizzi diversi componenti nell'ambiente RoboComp per risolvere un'attività robotica specifica, ad esempio la localizzazione.
La maggior parte dei componenti di base nel repository robocomp-robolab attualmente non dispone di istruzioni dettagliate su come compilare e utilizzare i componenti in configurazioni di parametri diverse. Ciò crea un enorme ostacolo per i nuovi sviluppatori che vogliono utilizzare componenti nel loro progetto o contribuire al framework. Il motivo è che molti componenti sono un wrapper di driver o librerie esterne con molte dipendenze, il che rende difficile la compilazione e l'installazione. Inoltre, molti componenti avvolgono il driver del dispositivo complesso (ad es.hokuyoComp generico) per fornire l'interfaccia di messaggistica in RoboComp, che richiede conoscenze specifiche del dispositivo per ottimizzare i parametri.
Di conseguenza, la necessità di una documentazione dettagliata, che comprende descrizioni dei dispositivi, risoluzione delle dipendenze e utilizzi, è essenziale per il contributo open source. Un esempio del mio documento di lavoro sul componente hokuyoComp è disponibile al link:
https://github.com/anindex/robocomp-robolab/tree/master/components/hokuyoComp
Per scrivere una documentazione dettagliata e concreta dei componenti utilizzando l'approccio dall'alto verso il basso, devi almeno essere in grado di utilizzare i contenuti scritti nel documento, perché lo scopo finale della documentazione è trasferire le conoscenze operative agli sviluppatori ereditati. La struttura proposta per ogni documento del componente è la seguente:
- Descrizione
- Compilation e installazione
- Parametri di configurazione
- Avvio del componente (utilizzi)
- Problemi noti
Nell'esempio, innanzitutto vengono raccolte informazioni sulle specifiche del sensore Hokuyo, viene letto il codice del componente per comprendere le funzionalità del componente al fine di scrivere le descrizioni dei componenti. Inoltre, la conoscenza dell'ambiente RoboComp e dei parametri specifici del dispositivo, nonché delle dipendenze delle librerie, è utile per documentare la procedura di compilazione, installazione e configurazione del componente. Ad esempio, la compilazione hokuyoComp richiede un vecchio pacchetto deb liburg0-dev da Ubuntu 14.04, ma il pacchetto deb viene rimosso da Ubuntu PPA nella versione successiva, quindi dobbiamo eseguire la soluzione alternativa per la compilazione come indicato nel documento. In questo processo, possiamo anche registrare problemi noti per velocizzare il debug per i nuovi sviluppatori. Infine, gli utilizzi dei componenti per diversi scenari di utilizzo sono documentati per facilitare l'integrazione del componente nel panorama di RoboComp per diverse attività di robotica.
Traguardi
Questa sezione prevede un periodo di tempo iniziale per il completamento degli obiettivi del progetto menzionati. Selezioniamo le documentazioni dei componenti da scrivere in base alle categorie (ad es.componenti della videocamera, componenti laser). La stima attuale del tempo necessario per completare il documento sui componenti si basa sul tempo per il completamento dei documenti hokuyoComp di esempio. La tabella dei tempi è la seguente:
1° agosto - 1° settembre: creazione di un senso di appartenenza alla community:
- Organizzazione di riunioni settimanali per stabilire gli scopi del progetto, nonché le aspettative dello scrittore e dei mentor.
- Acquisisci una conoscenza approfondita del framework RoboComp.
2 settembre - 2 novembre: stesura della documentazione per ogni componente nel repository robocomp-robolab con perfezionamenti iterativi tra mentor e autore tramite riunioni (è previsto il completamento della maggior parte della documentazione non documentata)
2 novembre - 26 novembre: scrittura di un documento generale come esempio per l'utilizzo di componenti diversi per risolvere un'attività di robotica.
27-29 novembre: report di fine progetto.
Dopo GSoD 2019: vorrei rimanere in contatto con RoboComp per migliorare e mantenere ulteriormente il mio lavoro.
Note finali
È essenziale scrivere un esempio generale di come integrare componenti diversi nell'ambiente RoboComp per consentire agli utenti di comprendere il quadro generale delle funzionalità di RoboComp. Questo documento di esempio verrà discusso ulteriormente con i mentor per decidere quale attività di robotica è adatta a seconda dell'implementazione attuale di RoboComp.