NoDL
Un file di interfaccia revisionabile per ogni nodo ROS 2, che ne genera codice, documentazione e verifiche di deriva
Licenza
Apache-2.0
Panoramica
NoDL, il Node Definition Language, permette a un nodo ROS 2 di dichiarare la propria interfaccia (publisher, subscription, servizi, azioni, QoS e parametri) in un unico documento che può essere revisionato come qualsiasi altro contratto. Da quel documento genera il cablaggio del nodo come classe base astratta C++ o classe base rclpy, lasciando il comportamento scritto a mano; produce un riferimento esatto dell'interfaccia tramite un'estensione Sphinx per rosdoc2; e verifica che un sistema in esecuzione non se ne discosti. Funziona anche la direzione inversa: ros2 nodl describe osserva un nodo attivo e ne redige il NoDL, così una codebase esistente può adottarlo senza riscritture. È sviluppato dal ROS 2 ROSGraph Working Group sotto ros-tooling e rilasciato per ogni distribuzione ROS 2 attuale.
L'interfaccia di un nodo ROS 2 non risiede in nessun posto preciso. Topic e servizi vengono creati nel codice del costruttore, i parametri vengono dichiarati ovunque qualcuno si sia ricordato di farlo, la QoS è un dettaglio del punto di chiamata, e l'unica descrizione completa di ciò che un nodo espone è il grafo in esecuzione. NoDL mette quell'interfaccia in un unico file e rende il file autorevole. Gli autori sono attenti all'ambito: verifica i contratti del grafo (endpoint, tipi, QoS, parametri) e dice chiaramente che non dimostra il comportamento, la semantica dei sistemi di coordinate (frame) TF, la schedulazione né le garanzie di tempo reale.
Lo stesso documento serve tre usi che si possono adottare separatamente. La generazione scrive la parte idraulica: il generatore C++ produce una classe base astratta con ogni endpoint già collegato e delega i parametri a generate_parameter_library, e il generatore Python fa lo stesso per rclpy, inclusi i nodi lifecycle. La documentazione produce un riferimento dell'interfaccia a partire dal file anziché da commenti che si disallineano. La conformità confronta il contratto dichiarato con ciò che un nodo in esecuzione espone davvero, e ros2 nodl diff confronta due documenti offline. ament_nodl registra i documenti nell'indice ament ed esegue la verifica sui nodi attivi con colcon test.
Il progetto è nato nel 2020 e la versione 2 è arrivata a settembre 2026 dopo un periodo di lavoro intenso: parametri annidati, generazione Python di servizi, azioni e lifecycle, e un tutorial eseguibile con un robot fittizio sono stati tutti integrati nelle due settimane precedenti il rilascio. I suoi progressi sono riportati nei verbali del ROS PMC stesso, e la versione 2.1 è prevista per la prossima distribuzione ROS 2 ad aprile 2027.
Perché è importante
Il cablaggio delle interfacce è il punto in cui si perde molto tempo con ROS 2 e in cui vivono molti bug di integrazione: un nome di topic cambiato in un nodo e non nel suo consumatore, un parametro che nessuno ha documentato, una mancata corrispondenza di QoS che emerge solo a runtime. NoDL è il tentativo del progetto ROS stesso di rendere l'interfaccia del nodo un contratto esplicito anziché una proprietà emergente del codice, da parte del working group responsabile degli strumenti per il grafo ROS. Questa provenienza è il motivo per cui vale la pena seguirlo anche in una fase così precoce: se prende piede, è il genere di cosa che finisce in ogni template.
Il problema che risolve
L'interfaccia di un nodo ROS 2 è sparsa nel codice del costruttore ed è pienamente visibile solo nel grafo in esecuzione, quindi resta non documentata e si disallinea tra i nodi. NoDL la trasforma in un unico file revisionato che genera il cablaggio, genera la documentazione e individua un sistema in esecuzione che non vi corrisponde più.
Punti chiave
- Un documento NoDL dichiara publisher, subscription, servizi, azioni, QoS e parametri di un nodo
- Genera il cablaggio dell'interfaccia come classe base astratta C++ o classe base rclpy, lasciando il comportamento scritto a mano
- Produce un riferimento esatto dell'interfaccia nella documentazione ROS tramite un'estensione Sphinx per rosdoc2
- Verifica un nodo in esecuzione rispetto al suo contratto dichiarato, e ros2 nodl diff confronta i documenti offline
- ros2 nodl describe redige un NoDL da un nodo attivo, così il codice esistente può adottarlo senza riscritture
- Sviluppato dal ROS 2 ROSGraph Working Group e rilasciato per Humble, Jazzy, Kilted, Lyrical e Rolling
- La versione 2 è uscita a settembre 2026; la 2.1 è prevista per la distribuzione ROS 2 di aprile 2027
A chi si rivolge
- Team ROS 2 i cui bug di integrazione derivano da nodi in disaccordo su topic, tipi, QoS o parametri
- Manutentori di pacchetti che vogliono una documentazione delle interfacce generata anziché mantenuta a mano
- Chiunque inizi un nuovo nodo e preferisca dichiararne l'interfaccia una volta sola anziché scrivere a mano la parte idraulica
- Responsabili della CI che vogliono un colcon test che fallisca quando un nodo in esecuzione si discosta dal suo contratto
Limiti
- Fase di adozione iniziale per sua stessa descrizione: la v2 è uscita e lo schema è definito ragionevolmente stabile, non definitivo
- Verifica solo il contratto del grafo; non dimostra il comportamento, la semantica dei sistemi di coordinate (frame) TF, la schedulazione né le proprietà di tempo reale
- La generazione del codice copre C++ e Python; non c'è un generatore per altre librerie client
- Alcune dipendenze dei test completi sono disponibili solo tramite pip, quindi le build della buildfarm eseguono una suite di test ridotta
- Adottare la generazione significa che il nodo eredita da una classe base generata, un cambiamento strutturale per il codice esistente
- Gruppo di manutentori ristretto: la maggior parte del lavoro recente viene da una manciata di contributori