Py Trees for ROS

Behaviours, trees and utilities that extend py_trees for use with ROS.

Getting Started (ROS2)

Choose your ros distro and install via debs, e.g. for humble

$ sudo apt install \
    ros-humble-py-trees \
    ros-humble-py-trees-ros-interfaces \
    ros-humble-py-trees-ros \
    ros-humble-py-trees-ros-tutorials \
    ros-humble-py-trees-ros-viewer

Dive into the PyTree Docs for a basic primer (non-ROS) on behaviour trees, then move on to the the PyTree ROS Tutorials which incrementally build a scenario for a robot. The PyTree ROS documentation provides api docs for ROS specific trees, idioms and behaviours respectively.

For version specific releases of the documentation, refer to the documentation links in the matrix below.

ROS2	Rolling	Humble	Foxy	Dashing
py_trees				-
py_trees_ros_interfaces				-
py_trees_ros				-
py_trees_ros_tutorials				-
py_trees_js				-
py_trees_ros_viewer				-

Getting Started (ROS1)

Refer to the documentation links in the matrix below (note: you’ll find the tutorials in the py_trees_ros documentation).

ROS1	Noetic	Melodic	Kinetic
py_trees			- -
py_trees_msgs			- -
py_trees_ros			- -
rqt_py_trees			-

Changelog

Forthcoming

• ...

2.2.2 (2023-02-10)

• [pkg] tf2_ros -> tf2_ros_py, #204

2.2.1 (2023-02-08)

• [behaviours] eliminate more arg name defaults, #201

2.2.0 (2023-02-08)

• [actions] pre-merge and push-ci-image actions, #200
• [tests] bugfix explicit args and time float errors in tests, #200
• [watchers] handle explicit args and memory details, #196
• [watchers] bugfix blackboard watcher shutdownon humble, #194
• [code] refactor for explicit arguments, #191
• [trees] optional node and node name args to setup, #188
• [trees] switch deprecating qos policy for shorter versions, #187

2.1.1 (2021-05-09)

• [trees] publish with/without memory information (supports new selector/sequence modes)

2.1.0 (2020-08-02)

• [infra] update for api changes in py_trees 2.1.0 (Chooser no longer supported)
• [infra] update for api changes in ros2 foxy (not breaking changes)

2.0.11 (2020-03-23)

• [blackboards] log a one-shot warning instead of exceptions when pickle fails, #156

2.0.10 (2020-03-06)

• [mock] server bugfixed to accommodate custom result handlers, #154

2.0.9 (2020-03-05)

• [behaviours] default to periodic checks with warnings for action client timeouts, #153

2.0.8 (2020-03-04)

• [behaviours] wait_for_server_timeout_sec in action clients, #152
• [trees] avoid irregular snapshot streams by avoiding timing jitter, #151

2.0.7 (2020-02-10)

• [programs] graph discovery timeouts 1.0->2.0s, #149

2.0.6 (2020-02-06)

• [behaviours] action client goals from blackboard behaviour, #148
• [behaviours] publish from blackboard behaviour, #146

2.0.5 (2020-01-24)

• [serialisation] include parallel policy details

2.0.4 (2019-12-30)

• [blackboard] bugfix protection against activity stream not activitated for views, #140
• [trees] bugfix toggle for activity client on reconfigure, #139

2.0.3 (2019-12-26)

• [infra] add a marker file to assist with ros2cli discovery #138

2.0.2 (2019-12-26)

• [trees] on-demand snapshot stream services, similar to blackboard streams, #135, #136

2.0.1 (2019-12-03)

• [trees] periodically publish snapshots, #131,
• [trees] permit setup visitors, provide a default with timings, #129
• [trees] bugfix non-infinite timeout arg getting ignored, #129
• [trees] snapshot now publishing tree changed flag and key access info, #128
• [utilities] deprecate myargv for rclpy.utilities.remove_ros_args, #130

2.0.0 (2019-11-20)

• [blackboards] updated pretty printing to differentiate namespace vs attribute access, #123
• [blackboards] api updates for namespaced clients, #122,
• [tests] migrated tests from unittest to pytest
• [transforms] behaviours for writing to and broadcasting from the blackboard, #121
• [transforms] add missing mocks and update to latest blackboard api, #125

1.2.1 (2019-10-08)

• [trees] bugfix KeyError on publication of missing keys, #118
• [utilities] a ros myargv stipper, a'la ROS1 style, until something is available upstream

1.2.0 (2019-10-02)

• [blackboards] sweeping changes to accomodate the new blackboards with tracking, #109
• [backend] ensure tree modifications are published with an updated timestamp, #100
• [behaviours] subscriber related behaviours now require qos_profile args, #104
• [trees] ros parameterisation of the setup timeout, #101
• [trees] make use of the new [DisplaySnapshotVisitor]{.title-ref}, #102

1.1.2 (2019-08-10)

• [utilities] permit discovery of multiples with find_topics, #97

1.1.1 (2019-06-22)

• [tests] add missing tests/__init.py, #94
• [infra] add missing ros2topic dependency, #94

1.1.0 (2019-06-19)

• [actions] bugfix action client, don't cancel if not RUNNING
• [conversions] bugfix msg_to_behaviour for decorators
• [watchers] bugfix tree-watchers dot-graph to string functionality
• [watchers] bugfix missing tip in deserialised tree-watcher tree

1.0.0 (2019-04-28)

Stripped down and rebuilt for ROS2:

• [behaviours] the familiar subscriber and action client behaviours
• [blackboard] the exchange, mostly unmodified
• [infra] colcon build environment
• [trees] simpler communications, just one serialised tree snapshot, watchers do the rest
• [watchers] revamped 'blackboard' and new 'tree' watcher

What's missing:

• [logging] the basic mechanisms have moved to py_trees, the rosbag implementation is to come

0.5.13 (2017-05-28)

• [doc] add many missing packages to satiate autodoc

0.5.9 (2017-04-16)

• [doc] add missing rqt-py-trees image
• [infra] bugfix missing install rule for mock sensors script

0.5.5 (2017-03-31)

• [infra] missed the py_trees exec dependency, fixed.

0.5.4 (2017-03-25)

• [docs] faq added
• [tutorials] 9 - bagging
• [infra] various dependency fixes for tests and autodoc
• [tests] fix broken subscrirber test

0.5.3 (2017-03-21)

• [tutorials] 8 - dynamic loading, insertion and execution
• [tutorials] 7 - docking, undocking, cancelling and recovery

0.5.2 (2017-03-19)

• [infra] add missing actionlib dependencies

0.5.1 (2017-03-19)

• [tutorials] 6 - context switching
• [tutorials] re-insert missing images

0.5.0 (2017-02-21)

• [docs] new and shiny index added
• [tutorials] qt dashboard support
• [tutorials] 5 - tree scanning added
• [tutorials] 4 - tree introspection added
• [tutorials] 3 - blackboards added
• [tutorials] 2 - battery low branch added
• [tutorials] 1 - data gathering added
• [mock] a mock robot for tutorials and testing
• [behaviours] action client, battery behaviours added
• [infra] refactoring for kinetic

Indigo -> Kinetic Changelist

Py Trees ROS API

• subscribers
  • py_trees.subscribers.SubscriberHandler -> py_trees_ros.subscribers.Handler
  • py_trees.subscribers.CheckSubscriberVariable -> py_trees_ros.subscribers.CheckData
  • py_trees.subscribers.WaitForSubscriberData -> py_trees_ros.subscribers.WaitForData
• conversions
  • py_trees.converters.convert_type -> py_trees_ros.converters.behaviour_type_to_msg_constant
  • py_trees.converters.convert_status -> py_trees_ros.converters.status_enum_to_msg_constant
  • py_trees.converters.convert_blackbox -> py_trees_ros.converters.blackbox_enum_to_msg_constant
• blackboard
  • py_trees.ros.blackboard -> py_trees_ros.blackboard.Exchange
  • ~list_blackboard_variables -> ~get_blackboard_variables
  • ~spawn_blackboard_watcher -> ~open_blackboard_watcher
  • ~destroy_blackboard_watcher -> ~close_blackboard_watcher
• visitors : classes moved from py_trees.trees -> py_trees_ros.visitors

Py Trees ROS Msgs API

• blackboard services
  • py_trees.msgs.srv.BlackboardVariables -> py_trees_msgs.srv.GetBlackboardVariables
  • py_trees.msgs.srv.SpawnBlackboardWatcher -> py_trees_msgs.srv.OpenBlackboardWatcher
  • py_trees.msgs.srv.DestroyBlackboardWatcher -> py_trees_msgs.srv.CloseBlackboardWatcher

Py Trees

• program : py-trees-render added
• imposter : bugfix to permit visitors to the children of a composite original
• visitors : py_trees.trees -> py_trees.visitors