Création d’un paquet

Objectif : Créer un nouveau package à l’aide de CMake ou de Python, et exécuter son exécutable.

Niveau du tutoriel : Débutant

Durée : 15 minutes

Contenu

Arrière-plan
Conditions préalables
Tâches
Résumé
Prochaines étapes

Arrière-plan 

1 Qu’est-ce qu’un package ROS 2 ?

Un paquet peut être considéré comme un conteneur pour votre code ROS 2. Si vous voulez pouvoir installer votre code ou le partager avec d’autres, vous en aurez besoin organisé dans un package. Avec les packages, vous pouvez publier votre travail ROS 2 et permettre à d’autres de le construire et de l’utiliser facilement.

La création de packages dans ROS 2 utilise ament comme système de construction et colcon comme outil de construction. Vous pouvez créer un package à l’aide de CMake ou de Python, qui sont officiellement pris en charge, bien que d’autres types de construction existent.

2 Qu’est-ce qui constitue un package ROS 2 ?

Les packages ROS 2 Python et CMake ont chacun leur propre contenu minimum requis :

package.xml fichier contenant des méta-informations sur le paquet
CMakeLists.txt fichier qui décrit comment construire le code dans le package

package.xml fichier contenant des méta-informations sur le paquet
setup.py contenant des instructions sur la façon d’installer le paquet
setup.cfg est requis lorsqu’un paquet contient des exécutables, donc ros2 run peut les trouver
/<package_name> - un répertoire portant le même nom que votre package, utilisé par les outils ROS 2 pour trouver votre package, contient __init__.py

Le package le plus simple possible peut avoir une structure de fichier qui ressemble à :

my_package/
     CMakeLists.txt
     package.xml

my_package/
      setup.py
      package.xml
      resource/my_package

3 packages dans un espace de travail 

Un seul espace de travail peut contenir autant de packages que vous le souhaitez, chacun dans son propre dossier. Vous pouvez également avoir des packages de différents types de construction dans un espace de travail (CMake, Python, etc.). Vous ne pouvez pas avoir de packages imbriqués.

La meilleure pratique est d’avoir un dossier src dans votre espace de travail et d’y créer vos packages. Cela permet de garder le niveau supérieur de l’espace de travail « propre ».

Un espace de travail trivial pourrait ressembler à :

workspace_folder/
    src/
      package_1/
          CMakeLists.txt
          package.xml

      package_2/
          setup.py
          package.xml
          resource/package_2
      ...
      package_n/
          CMakeLists.txt
          package.xml

Conditions préalables 

Vous devriez avoir un espace de travail ROS 2 après avoir suivi les instructions du tutoriel précédent. Vous allez créer votre package dans cet espace de travail.

Tâches 

1 Créer un package 

Tout d’abord, sourcez votre installation ROS 2.

Utilisons l’espace de travail que vous avez créé dans le tutoriel précédent, ros2_ws, pour votre nouveau package.

Assurez-vous d’être dans le dossier src avant d’exécuter la commande de création de paquet.

cd ~/ros2_ws/src

cd ~/ros2_ws/src

cd \ros2_ws\src

La syntaxe de commande pour créer un nouveau package dans ROS 2 est :

ros2 pkg create --build-type ament_cmake <package_name>

ros2 pkg create --build-type ament_python <package_name>

Pour ce tutoriel, vous utiliserez l’argument optionnel --node-name qui crée un simple exécutable de type Hello World dans le package.

Saisissez la commande suivante dans votre terminal :

ros2 pkg create --build-type ament_cmake --node-name my_node my_package

ros2 pkg create --build-type ament_python --node-name my_node my_package

Vous aurez maintenant un nouveau dossier dans le répertoire src de votre espace de travail appelé my_package.

Après avoir exécuté la commande, votre terminal renverra le message :

going to create a new package
package name: my_package
destination directory: /home/user/ros2_ws/src
package format: 3
version: 0.0.0
description: TODO: Package description
maintainer: ['<name> <email>']
licenses: ['TODO: License declaration']
build type: ament_cmake
dependencies: []
node_name: my_node
creating folder ./my_package
creating ./my_package/package.xml
creating source and include folder
creating folder ./my_package/src
creating folder ./my_package/include/my_package
creating ./my_package/CMakeLists.txt
creating ./my_package/src/my_node.cpp

going to create a new package
package name: my_package
destination directory: /home/user/ros2_ws/src
package format: 3
version: 0.0.0
description: TODO: Package description
maintainer: ['<name> <email>']
licenses: ['TODO: License declaration']
build type: ament_python
dependencies: []
node_name: my_node
creating folder ./my_package
creating ./my_package/package.xml
creating source folder
creating folder ./my_package/my_package
creating ./my_package/setup.py
creating ./my_package/setup.cfg
creating folder ./my_package/resource
creating ./my_package/resource/my_package
creating ./my_package/my_package/__init__.py
creating folder ./my_package/test
creating ./my_package/test/test_copyright.py
creating ./my_package/test/test_flake8.py
creating ./my_package/test/test_pep257.py
creating ./my_package/my_package/my_node.py

Vous pouvez voir les fichiers générés automatiquement pour le nouveau package.

2 Créer un package 

Placer des packages dans un espace de travail est particulièrement utile car vous pouvez créer plusieurs packages à la fois en exécutant colcon build à la racine de l’espace de travail. Sinon, vous devrez créer chaque package individuellement.

Retournez à la racine de votre espace de travail :

cd ~/ros2_ws

cd ~/ros2_ws

cd \ros2_ws

Vous pouvez maintenant créer vos packages :

colcon build

colcon build

colcon build --merge-install

Windows n’autorise pas les longs chemins, donc merge-install combinera tous les chemins dans le répertoire install.

Rappelez-vous du dernier tutoriel que vous avez également les packages ros_tutorials dans votre ros2_ws. Vous avez peut-être remarqué que l’exécution de colcon build a également construit le paquet turtlesim. C’est bien quand vous n’avez que quelques packages dans votre espace de travail, mais quand il y a beaucoup de packages, colcon build peut prendre beaucoup de temps.

Pour compiler uniquement le package my_package la prochaine fois, vous pouvez exécuter :

colcon build --packages-select my_package

3 Source du fichier d’installation 

Pour utiliser votre nouveau package et exécutable, ouvrez d’abord un nouveau terminal et sourcez votre installation principale de ROS 2.

Ensuite, depuis le répertoire ros2_ws, exécutez la commande suivante pour sourcer votre espace de travail :

. install/local_setup.bash

. install/local_setup.bash

call install/local_setup.bat

Maintenant que votre espace de travail a été ajouté à votre chemin, vous pourrez utiliser les exécutables de votre nouveau package.

4 Utilisez le forfait 

Pour exécuter l’exécutable que vous avez créé à l’aide de l’argument --node-name lors de la création du package, entrez la commande :

ros2 run my_package my_node

Ce qui renverra un message à votre terminal :

hello world my_package package

Hi from my_package.

5 Examinez le contenu de l’emballage 

Dans ros2_ws/src/my_package, vous verrez les fichiers et dossiers générés automatiquement par ros2 pkg create :

CMakeLists.txt  include  package.xml  src

my_node.cpp se trouve dans le répertoire src. C’est là que tous vos nœuds C++ personnalisés iront à l’avenir.

my_package  package.xml  resource  setup.cfg  setup.py  test

my_node.py se trouve dans le répertoire my_package. C’est là que tous vos nœuds Python personnalisés iront à l’avenir.

6 Personnaliser package.xml 

Vous avez peut-être remarqué dans le message de retour après la création de votre package que les champs description et license contiennent des notes TODO. En effet, la description du package et la déclaration de licence ne sont pas automatiquement définies, mais sont requises si vous souhaitez publier votre package. Le champ mainteneur peut également devoir être rempli.

Depuis ros2_ws/src/my_package, ouvrez package.xml en utilisant votre éditeur de texte préféré :

<?xml version="1.0"?>
<?xml-model
   href="http://download.ros.org/schema/package_format3.xsd"
   schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
 <name>my_package</name>
 <version>0.0.0</version>
 <description>TODO: Package description</description>
 <maintainer email="user@todo.todo">user</maintainer>
 <license>TODO: License declaration</license>

 <buildtool_depend>ament_cmake</buildtool_depend>

 <test_depend>ament_lint_auto</test_depend>
 <test_depend>ament_lint_common</test_depend>

 <export>
   <build_type>ament_cmake</build_type>
 </export>
</package>

<?xml version="1.0"?>
<?xml-model
   href="http://download.ros.org/schema/package_format3.xsd"
   schematypens="http://www.w3.org/2001/XMLSchema"?>
<package format="3">
 <name>my_package</name>
 <version>0.0.0</version>
 <description>TODO: Package description</description>
 <maintainer email="user@todo.todo">user</maintainer>
 <license>TODO: License declaration</license>

 <test_depend>ament_copyright</test_depend>
 <test_depend>ament_flake8</test_depend>
 <test_depend>ament_pep257</test_depend>
 <test_depend>python3-pytest</test_depend>

 <export>
   <build_type>ament_python</build_type>
 </export>
</package>

Entrez votre nom et votre email sur la ligne maintainer si elle n’a pas été automatiquement remplie pour vous. Ensuite, modifiez la ligne description pour résumer le package :

<description>Beginner client libraries tutorials practice package</description>

Ensuite, mettez à jour la ligne license. Vous pouvez en savoir plus sur les licences open source ici. Étant donné que ce package est uniquement destiné à la pratique, vous pouvez utiliser n’importe quelle licence en toute sécurité. Nous utilisons Apache License 2.0 :

<license>Apache License 2.0</license>

N’oubliez pas de sauvegarder une fois que vous avez terminé l’édition.

Sous la balise de licence, vous verrez des noms de balises se terminant par _depend. C’est là que votre package.xml listerait ses dépendances sur d’autres packages, pour que colcon les recherche. my_package est simple et n’a aucune dépendance, mais vous verrez cet espace utilisé dans les prochains tutoriels.

Vous avez terminé pour l’instant !

Le fichier setup.py contient les mêmes champs de description, de responsable et de licence que package.xml, vous devez donc également les définir. Ils doivent correspondre exactement dans les deux fichiers. La version et le nom (package_name) doivent également correspondre exactement et doivent être automatiquement renseignés dans les deux fichiers.

Ouvrez setup.py avec votre éditeur de texte préféré.

from setuptools import setup

package_name = 'my_py_pkg'

setup(
 name=package_name,
 version='0.0.0',
 packages=[package_name],
 data_files=[
     ('share/ament_index/resource_index/packages',
             ['resource/' + package_name]),
     ('share/' + package_name, ['package.xml']),
   ],
 install_requires=['setuptools'],
 zip_safe=True,
 maintainer='TODO',
 maintainer_email='TODO',
 description='TODO: Package description',
 license='TODO: License declaration',
 tests_require=['pytest'],
 entry_points={
     'console_scripts': [
             'my_node = my_py_pkg.my_node:main'
     ],
   },
)

Modifiez les lignes maintainer, maintainer_email et description pour qu’elles correspondent à package.xml.

N’oubliez pas de sauvegarder le fichier.

Résumé 

Vous avez créé un package pour organiser votre code et le rendre facile à utiliser pour les autres.

Votre package a été automatiquement rempli avec les fichiers nécessaires, puis vous avez utilisé colcon pour le construire afin que vous puissiez utiliser ses exécutables dans votre environnement local.

Prochaines étapes 

Ensuite, ajoutons quelque chose de significatif à un package. Vous commencerez avec un simple système éditeur/abonné, que vous pouvez choisir d’écrire en C++ ou Python.