Creating a Python Node from scratch (for ament_python)

TL;DR Making an ament_python Node

Modify package.xml with any additional dependencies.
Create the Node.
Modify the setup.py file.

Let us add an additional Node to our ament_python package that actually uses ROS2 functionality. These are the steps that must be taken, in general, to add a new Node.

Handling dependencies (`package.xml`)

The package.xml was automatically generated by ros2 pkg create and holds basic information about the package.

One important role of package.xml is to declare dependencies with other ROS2 packages. It is common for new Nodes to have additional dependencies, so we will cover that here. For any ROS2 package, we must modify the package.xml to add new dependencies.

In this toy example, let us add rclpy as a dependency because it is the Python implementation of the RCL. All Nodes that use anything related to ROS2 will directly or indirectly depend on that library.

By no coincidence, the package.xml has the .xml extension, meaning that it is written in XML.

Let us add the dependency between the <license> and <test_depend> tags. This is not a strict requirement but is where it commonly is for standard packages.

~/ros2_tutorial_workspace/src/python_package_with_a_node/package.xml

<?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>python_package_with_a_node</name>
  <version>0.0.0</version>
  <description>TODO: Package description</description>
  <maintainer email="murilomarinho@ieee.org">murilo</maintainer>
  <license>TODO: License declaration</license>

  <depend>rclpy</depend>

  <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>

After you modify the workspace, build it once

After you add a new dependency to package.xml, nothing really changes in the workspace unless a new build is performed.

In addition, when programming with new dependencies, unless you rebuild the workspace, PyCharm will not recognize the libraries, and autocomplete will not work.

So,

close PyCharm.
Run (in the terminal you used to run PyCharm before)
cd ~/ros2_tutorial_workspace colcon build source install/setup.bash
Note

If you don’t remember why we’re building with these commands, see Always source after you build.
Re-open pycharm
pycharm_ros2

Creating the Node

In the directory src/python_package_with_a_node/python_package_with_a_node, create a new file called print_forever_node.py. Copy and paste the following contents into the file.

~/ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py

import rclpy
from rclpy.node import Node


class PrintForever(Node):
    """A ROS2 Node that prints to the console periodically."""

    def __init__(self):
        super().__init__('print_forever')
        timer_period: float = 0.5
        self.timer = self.create_timer(timer_period, self.timer_callback)
        self.print_count: int = 0

    def timer_callback(self):
        """Method that is periodically called by the timer."""
        self.get_logger().info(f'Printed {self.print_count} times.')
        self.print_count = self.print_count + 1


def main(args=None):
    """
    The main function.
    :param args: Not used directly by the user, but used by ROS2 to configure
    certain aspects of the Node.
    """
    try:
        rclpy.init(args=args)

        print_forever_node = PrintForever()

        rclpy.spin(print_forever_node)
    except KeyboardInterrupt:
        pass
    except Exception as e:
        print(e)


if __name__ == '__main__':
    main()

By now, this should be enough for you to be able to run the node in PyCharm. You can right-click it and choose Debug print_forever_node. This will output

[INFO] [1683009340.877110693] [print_forever]: Printed 0 times.
[INFO] [1683009341.336559942] [print_forever]: Printed 1 times.
[INFO] [1683009341.836334639] [print_forever]: Printed 2 times.
[INFO] [1683009342.336555088] [print_forever]: Printed 3 times.

To finish, press the Stop button or press CTRL+F2 on PyCharm. The node will exit gracefully with

Process finished with exit code 0

Making ros2 run work

Even though you can run the new node in PyCharm, we need an additional step to make it deployable in a place where ros2 run can find it.

To do so, we modify the console_scripts key in the entry_points dictionary defined in setup.py, to have our new node, as follows

Hint

console_scripts expects a list of str in a specific format. Hence, follow the format properly and don’t forget the commas to separate elements in the list.

~/ros2_tutorial_workspace/src/python_package_with_a_node/setup.py

from setuptools import setup

package_name = 'python_package_with_a_node'

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='murilo',
    maintainer_email='murilomarinho@ieee.org',
    description='TODO: Package description',
    license='TODO: License declaration',
    tests_require=['pytest'],
    entry_points={
        'console_scripts': [
            'sample_python_node = python_package_with_a_node.sample_python_node:main',
            'print_forever_node = python_package_with_a_node.print_forever_node:main'
        ],
    },
)

The format is straightforward, as follows

`print_forever_node`	The name of the node when calling it through ros2 run.
`python_package_with_a_node`	The name of the package.
`print_forever_node`	The name of the script, without the `.py` extension.
`main`	The function, within the script, that will be called. In general, `main`.

Once again, we have to refresh the workspace so we run

cd ~/ros2_tutorial_workspace
colcon build
source install/setup.bash

Note

If you don’t remember why we’re building with these commands, see Always source after you build.

And, with that, we can run

ros2 run python_package_with_a_node print_forever_node

which will output, as expected

[INFO] [1683010987.130432622] [print_forever]: Printed 0 times.
[INFO] [1683010987.622780292] [print_forever]: Printed 1 times.
[INFO] [1683010988.122731296] [print_forever]: Printed 2 times.
[INFO] [1683010988.622735422] [print_forever]: Printed 3 times.

To stop, press CTRL+C on the terminal and the Node will return gracefully.