NoDL
Um arquivo de interface revisável por nó do ROS 2, que gera código, documentação e checagens de desvio
Licença
Apache-2.0
Visão geral
O NoDL, a Node Definition Language, permite que um nó do ROS 2 declare sua interface — publishers, assinaturas, serviços, ações, QoS e parâmetros — num único documento que pode ser revisado como qualquer outro contrato. A partir dele, gera a fiação do nó como uma classe base abstrata em C++ ou uma classe base em rclpy, deixando o comportamento escrito à mão; produz uma referência exata da interface por meio de uma extensão Sphinx para o rosdoc2; e verifica se um sistema em execução se desviou dele. O sentido inverso também funciona: ros2 nodl describe observa um nó em execução e rascunha o NoDL dele, de modo que um código existente pode adotá-lo sem reescrita. É desenvolvido pelo grupo de trabalho ROSGraph do ROS 2 dentro do ros-tooling e publicado para todas as distribuições atuais do ROS 2.
A interface de um nó do ROS 2 não mora em lugar nenhum em especial. Tópicos e serviços são criados no código do construtor, parâmetros são declarados onde alguém lembrou de declarar, a QoS é um detalhe de um ponto de chamada, e a única descrição completa do que um nó expõe é o grafo em execução. O NoDL põe essa interface num arquivo e torna esse arquivo a referência oficial. Os autores são cuidadosos com o escopo: ele verifica contratos do grafo — pontos de conexão, tipos, QoS, parâmetros — e diz com clareza que não prova comportamento, semântica de referenciais TF, escalonamento nem garantias de tempo real.
O mesmo documento serve a três usos que podem ser adotados separadamente. A geração escreve o encanamento: o gerador C++ produz uma classe base abstrata com todos os pontos de conexão ligados e delega os parâmetros ao generate_parameter_library, e o gerador Python faz o mesmo para o rclpy, incluindo nós de ciclo de vida. A documentação gera uma referência de interface a partir do arquivo em vez de comentários que envelhecem. A conformidade compara o contrato declarado com o que um nó em execução realmente expõe, e ros2 nodl diff compara dois documentos offline. O ament_nodl registra os documentos no índice do ament e roda a verificação do nó ao vivo dentro do colcon test.
O projeto começou em 2020 e a versão 2 chegou em setembro de 2026, depois de um mutirão de trabalho: parâmetros aninhados, geração em Python de serviços, ações e ciclo de vida, e um tutorial executável com o robô de exemplo foram todos mesclados nas duas semanas antes do lançamento. O progresso aparece nas próprias atas do PMC do ROS, e a versão 2.1 está prevista para a próxima distribuição do ROS 2, em abril de 2027.
Por que importa
A fiação de interfaces consome muito tempo no ROS 2 e esconde muitos bugs de integração: um nome de tópico que mudou num nó e não no consumidor, um parâmetro que ninguém documentou, uma incompatibilidade de QoS que só aparece em execução. O NoDL é a tentativa do próprio projeto ROS de transformar a interface do nó num contrato explícito em vez de uma propriedade que emerge do código, vinda do grupo de trabalho responsável pelas ferramentas do grafo do ROS. Essa origem é o que faz valer a pena acompanhá-lo mesmo tão cedo: se pegar, é o tipo de coisa que acaba em todo modelo de projeto.
Problema que resolve
A interface de um nó do ROS 2 fica espalhada pelo código do construtor e só aparece por inteiro no grafo em execução, então fica sem documentação e se desalinha entre nós. O NoDL a transforma num único arquivo revisado que gera a fiação, gera a documentação e flagra um sistema em execução que não bate mais com ele.
Pontos principais
- Um documento NoDL declara os publishers, assinaturas, serviços, ações, QoS e parâmetros de um nó
- Gera a fiação da interface como classe base abstrata em C++ ou em rclpy, deixando o comportamento escrito à mão
- Produz uma referência exata da interface na documentação do ROS por meio de uma extensão Sphinx para o rosdoc2
- Verifica um nó em execução contra o contrato declarado, e ros2 nodl diff compara documentos offline
- ros2 nodl describe rascunha um NoDL a partir de um nó em execução, então o código existente pode adotá-lo sem reescrita
- Desenvolvido pelo grupo de trabalho ROSGraph do ROS 2 e publicado para Humble, Jazzy, Kilted, Lyrical e Rolling
- A versão 2 saiu em setembro de 2026; a 2.1 está prevista para a distribuição do ROS 2 de abril de 2027
Para quem é
- Equipes de ROS 2 cujos bugs de integração vêm de nós que discordam sobre tópicos, tipos, QoS ou parâmetros
- Mantenedores de pacotes que querem documentação de interface gerada em vez de mantida à mão
- Quem está começando um nó novo e prefere declarar a interface uma vez a escrever o encanamento à mão
- Responsáveis por CI que querem um colcon test que falhe quando um nó em execução se afasta do contrato
Limitações
- Em fase de adoção inicial pela própria descrição — a v2 saiu e o esquema é tido como razoavelmente estável, não fechado
- Só verifica o contrato do grafo; não prova comportamento, semântica de referenciais TF, escalonamento nem propriedades de tempo real
- A geração de código cobre C++ e Python; não há gerador para outras bibliotecas cliente
- Algumas dependências dos testes completos só existem no pip, então os builds da fazenda de compilação rodam uma suíte reduzida
- Adotar a geração significa que seu nó herda de uma classe base gerada, uma mudança estrutural para código existente
- Grupo pequeno de mantenedores — a maior parte do trabalho recente vem de um punhado de contribuidores