Initialization, Shutdown, and Spinning¶
A collection of functions for writing a ROS program.
A typical ROS program consists of the following operations:
- Initialization
- Create one or more ROS nodes
- Process node callbacks
- 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, orNone
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. - A list of
- 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: Returns: An instance of the newly created node.
- node_name (
-
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. IfNone
, then the default context is used (seeget_default_context()
).
Return type: None
- args (
-
rclpy.
shutdown
(*, context=None)¶ Shutdown a previously initialized context.
This will also shutdown the global executor.
Parameters: context ( Optional
[Context
]) – The context to invalidate. IfNone
, then the default context is used (seeget_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: 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: 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()
returnsTrue
or the context associated with the executor is shutdown.Parameters: Return type: None