Initialization, Shutdown, and Spinning

A collection of functions for writing a ROS program.

A typical ROS program consists of the following operations:

  1. Initialization
  2. Create one or more ROS nodes
  3. Process node callbacks
  4. Shutdown

Inititalization is done by calling init() for a particular Context. This must be done before any ROS nodes can be created.

Creating a ROS node is done by calling create_node() or by instantiating a Node. A node can be used to create common ROS entities like publishers, subscriptions, services, and actions.

After a node is created, items of work can be done (e.g. subscription callbacks) by spinning on the node. The following functions can be used to process work that is waiting to be executed: spin(), spin_once(), and spin_until_future_complete().

When finished with a previously initialized Context (ie. done using all ROS nodes associated with the context), the shutdown() function should be called. This will invalidate all entities derived from the context.

rclpy.create_node(node_name, *, context=None, cli_args=None, namespace=None, use_global_arguments=True, start_parameter_services=True, parameter_overrides=None, allow_undeclared_parameters=False, automatically_declare_parameters_from_overrides=False)

Create an instance of Node.

Parameters:
  • node_name (str) – A name to give to the node.
  • context (Context) – The context to associated with the node, or None for the default global context.
  • cli_args (List[str]) – Command line arguments to be used by the node.
  • namespace (str) – The namespace prefix to apply to entities associated with the node (node name, topics, etc).
  • use_global_arguments (bool) – False if the node should ignore process-wide command line arguments.
  • start_parameter_services (bool) – False if the node should not create parameter services.
  • parameter_overrides (List[Parameter]) –
    A list of Parameter which are used to override the
    initial values of parameters declared on this node.
    param allow_undeclared_parameters:
     if True undeclared parameters are allowed, default False. This option doesn’t affect parameter_overrides.
  • automatically_declare_parameters_from_overrides (bool) – If True, the “parameter overrides” will be used to implicitly declare parameters on the node during creation, default False.
Return type:

Node

Returns:

An instance of the newly created node.

rclpy.get_global_executor()
Return type:Executor
rclpy.init(*, args=None, context=None)

Initialize ROS communications for a given context.

Parameters:
  • args (Optional[List[str]]) – List of command line arguments.
  • context (Optional[Context]) – The context to initialize. If None, then the default context is used (see get_default_context()).
Return type:

None

rclpy.shutdown(*, context=None)

Shutdown a previously initialized context.

This will also shutdown the global executor.

Parameters:context (Optional[Context]) – The context to invalidate. If None, then the default context is used (see get_default_context()).
Return type:None
rclpy.spin(node, executor=None)

Execute work and block until the context associated with the executor is shutdown.

Callbacks will be executed by the provided executor.

This function blocks.

Parameters:
  • node (Node) – A node to add to the executor to check for work.
  • executor (Executor) – The executor to use, or the global executor if None.
Return type:

None

rclpy.spin_once(node, *, executor=None, timeout_sec=None)

Execute one item of work or wait until a timeout expires.

One callback will be executed by the provided executor as long as that callback is ready before the timeout expires.

If no executor is provided (ie. None), then the global executor is used. It is possible the work done is for a node other than the one provided if the global executor has a partially completed coroutine.

Parameters:
  • node (Node) – A node to add to the executor to check for work.
  • executor (Executor) – The executor to use, or the global executor if None.
  • timeout_sec (float) – Seconds to wait. Block forever if None or negative. Don’t wait if 0.
Return type:

None

rclpy.spin_until_future_complete(node, future, executor=None, timeout_sec=None)

Execute work until the future is complete.

Callbacks and other work will be executed by the provided executor until future.done() returns True or the context associated with the executor is shutdown.

Parameters:
  • node (Node) – A node to add to the executor to check for work.
  • future (Future) – The future object to wait on.
  • executor (Executor) – The executor to use, or the global executor if None.
  • timeout_sec (float) – Seconds to wait. Block until the future is complete if None or negative. Don’t wait if 0.
Return type:

None