ROS SUGAR 🍬 is a meta-framework that provides a whole lot of syntactic sugar for creating event-driven multinode systems in ROS2, using an intuitive Python API.

• Learn more about the design concepts in ROS Sugar 📚
• Learn how to create your own ROS2 package using ROS Sugar 🚀

Packages created using ROS Sugar

• Kompass: a framework for building robust and comprehensive event-driven navigation stacks using an easy-to-use and intuitive Python API
• ROS Agents: a fully-loaded framework for creating interactive embodied agents that can understand, remember, and act upon contextual information from their environment.

Overview

ROS Sugar is built for ROS2 developers who want to create event-driven systems with multiple nodes that are easy to use, have builtin fallbacks and fault tolerance, and can be configured started with an intuitive Python API. It provides primitives for writing ROS nodes, and events/actions which can start/stop/modify the nodes, in the spirit of event driven software. ROS Sugar is also a replacement for the ROS Launch API.

A Component is the main execution unit in ROS Sugar, each component is configured with Inputs/Outputs and Fallback behaviors. Additionally, each component updates its own Health Status. Components can be handled and reconfigured dynamically at runtime using Events and Actions. Events, Actions and Components are passed to the Launcher which runs the set of components as using multi-threaded or multi-process execution. The Launcher also uses an internal Monitor to keep track of the components and monitor events.

Base Component

Multi-Process Execution

Installation

Install python dependencies using pip as follows:

pip install 'attrs>=23.2.0' msgpack-numpy numpy-quaternion setproctitle

Grab your favorite deb package from the release page and install it as follows:

sudo dpkg -i ros-$ROS_DISTRO-sugar_$version$DISTRO_$ARCHITECTURE.deb

Building from source

mkdir -p ros-sugar-ws/src
cd ros-sugar-ws/src
git clone https://github.com/automatika-robotics/ros-sugar && cd ..
pip install numpy opencv-python-headless 'attrs>=23.2.0' jinja2 msgpack msgpack-numpy numpy-quaternion setproctitle
colcon build
source install/setup.bash

Copyright

The code in this distribution is Copyright (c) 2024 Automatika Robotics unless explicitly indicated otherwise.

ROS Sugar is made available under the MIT license. Details can be found in the LICENSE file.

Contributions

ROS Agents has been developed in collaboration between Automatika Robotics and Inria. Contributions from the community are most welcome.

Changelog for package automatika_ros_sugar

0.2.5 (2025-01-07)

• (fix) Gets imports and default values based on installed distro
• (fix) Fix launch and launch_ros imports based on ros distro
• Contributors: ahr, mkabtoul

0.2.4 (2024-12-27)

• (fix) Adds algorithm auto re-configuration from YAML file
• (fix) Fixes callback got_msg property
• (feature) Adds topics callbacks/conversions reparsing to component Supports running components from different packages in one script and each component uses its own package callbacks/conversions
• (fix) Updates AllowedTopics config and its validator
• (refactor) Removes PIL as a dependancy
• (fix) Fixes component state transition logging
• (fix) Fixes order to custom method execution in component lifecycle transition methods
• (refactor) Removes BaseNode class
• (fix) Fixes packaging workflow formatting
• (fix) Removes redundant methods from components
• (chore) Increments release action version
• (chore) Adds new action in debs creation workflow
• (refactor) Formats utils
• (refactor) Minor refactoring in utils
• (fix) Removes fix for color correction as the transformation is now applied at the time of visualization
• (fix) Adds color transformation when reading images of yuv encoding
• (chore) Changes name of release action
• (feature) Adds component algorithm config management to the api
• (fix) fixes datatypes update method for using multiple packages
• (chore) Cleans up cmake and packaging
• (refactor) Improves error message when a topic of unsupported type is created
• (refactor) Handles additional datatypes provided by user packages
• (fix) Pins release mirror workflow to run only on release publishing
• (fix) Adds branch name to release workflow
• (fix) Fixes name of action
• (feature) Adds release mirror action
• (docs) Removes autogenerated docs
• (docs) Adds minor modification to readme
• (docs) Changes package description
• (feature) Adds ExecuteMethod service to BaseComponent
• (fix) Minor fix in conversion method
• (refactor) Makes compressed image a realization of image
• (fix) Fixes ros compressed image conversion util
• (feature) Adds support for CompressedImage msg
• (feature) Adds ros_log_level option to each added package
• (feature) Adds additional supported types argument to BaseComponent and Topic validators
• (fix) Adds algorithm auto re-configuration from YAML file
• (fix) Fixes callback got_msg property
• (feature) Adds topics callbacks/conversions reparsing to component Supports running components from different packages in one script and each component uses its own package callbacks/conversions
• (fix) Updates AllowedTopics config and its validator
• (refactor) Removes PIL as a dependancy
• (fix) Fixes component state transition logging
• (fix) Fixes order to custom method execution in component lifecycle transition methods
• (refactor) Removes BaseNode class
• (fix) Fixes packaging workflow formatting
• (fix) Removes redundant methods from components
• (chore) Increments release action version
• (chore) Adds new action in debs creation workflow
• (refactor) Formats utils
• (refactor) Minor refactoring in utils
• (fix) Removes fix for color correction as the transformation is now applied at the time of visualization
• (fix) Adds color transformation when reading images of yuv encoding
• (chore) Changes name of release action
• (feature) Adds component algorithm config management to the api
• (fix) fixes datatypes update method for using multiple packages
• (chore) Cleans up cmake and packaging
• (refactor) Improves error message when a topic of unsupported type is created
• (refactor) Handles additional datatypes provided by user packages
• (fix) Pins release mirror workflow to run only on release publishing
• (fix) Adds branch name to release workflow
• (fix) Fixes name of action
• (feature) Adds release mirror action
• (docs) Removes autogenerated docs
• (docs) Adds minor modification to readme
• (docs) Changes package description
• (feature) Adds ExecuteMethod service to BaseComponent
• (fix) Fixes OccupnacyGrid data publishing from numpy
• (fix) Minor fix in conversion method
• (refactor) Makes compressed image a realization of image
• (fix) Fixes ros compressed image conversion util
• (feature) Adds support for CompressedImage msg
• (feature) Adds ros_log_level option to each added package
• (feature) Adds additional supported types argument to BaseComponent and Topic validators
• (fix) Merge pull request #14
• (chore) Updates package name to automatika_ros_sugar
• (fix) Checks numpy array shape in OccupancyGrid converter
• (feature) Adds stamped header and frame_id to ros publishers/callbacks
• (docs) Updates install instructions
• Contributors: ahr, mkabtoul

0.2.3 (2024-11-13)

• (chore) bump version 0.2.2 -> 0.2.3
• (chore) Adds deb packaging scripts and actions (#13)
• (docs) Removes notice
• Contributors: ahr

0.2.2 (2024-11-04)

• (chore) bump version 0.2.1 -> 0.2.2
• (feature) Adds activation timeout to monitor and launcher
• (fix) Fixes publishing numpy data to ROS OcuupancyGrid
• (refactor) Updates OccupancyGrid get_output using numpy operations
• Contributors: mkabtoul

0.2.1 (2024-10-29)

• (chore) bump version 0.2.0 -> 0.2.1
• (feature) Adds support for external tool calling in multiprocessing
• Contributors: ahr

0.2.0 (2024-10-25)

• (chore) Bump version 0.1.1 -> 0.2.0
• Merge pull request #12 from automatika-robotics/feature/external_processors Adds external processor support when running components in multiprocessing
• (refactor) Makes msgpack a global dependancy
• (fix) Fixes deserialization of external processors and handling of processor result in launcher
• (fix) Corrects the serialization of numpy arrays within lists
• (feature) Changes defaults for launcher parameters when using multiprocessing
• (fix) Fixes handling composite type check for deserialization and input/output deserialization in components
• (fix) Adds node name as parameter to callbacks for init
• (fix) Adds alias to attrs private attribute in BaseComponentConfig
• (fix) Restores executable to old version
• Merge branch 'feature/external_processors' of github.com:automatika-robotics/ros-sugar into feature/external_processors
• (fix) Fixes new method name in launcher
• (fix) Moves callbackgroup to BaseComponentConfig and changes initialization of inputs/outputs in component
• (fix) Fixes serialization of callbackgroup in config
• (fix) Fixes type hints for compatibility
• (docs) Fixes ubuntu version for dependancy problems
• (refactor) Makes msgpack a functional dependency
• (refactor) Adds handling of callback group and input/output initialization to facilitate multiprocessing
• (feature) Adds handling of callback group for multiprocess launch
• (fix) Adds serialization of np arrays and tuples
• (fix) Adds converter for QoS profile for serialization
• (refactor) Changes inputs/outputs handling in executable
• (refactor) Changes name of enum convert utility function
• (fix) Fixes use of multi processors for same topic in launcher
• (fix) Fix package installation for documentation workflow
• (feature) Adds support for multiple external processors on the same topic
• (fix) Fixes visibility of external_processors to protected
• (fix) Fixes typo in attaching external preprocessors
• (feature) Adds unix socket based listener threads for using external processors with components being run in multiprocessing
  • Modifies executable to add an argument for external processors
  • Adds setting and getting for external processor json in component
  • Adds setting up of external processors on component activation and destruction on component stop
  • Adds setup of external processor sockets and thread pool in launcher
• (fix) Moves callbackgroup to BaseComponentConfig and changes initialization of inputs/outputs in component
• (fix) Fixes serialization of callbackgroup in config
• (fix) Fixes type hints for compatibility
• (docs) Fixes ubuntu version for dependancy problems
• (refactor) Makes msgpack a functional dependency
• (refactor) Adds handling of callback group and input/output initialization to facilitate multiprocessing
• (feature) Adds handling of callback group for multiprocess launch
• (fix) Adds serialization of np arrays and tuples
• (fix) Adds converter for QoS profile for serialization
• (refactor) Changes inputs/outputs handling in executable
• (refactor) Changes name of enum convert utility function
• (feature) Adds event processing options and supports lists in event values Adds options to handle an event once or handle with a time delay
• (fix) Uses List from typing in type hints
• (feature) Adds handle_once and event_delay options to Event
• (feature) Adds list to supported event trigger values
• (fix) Handles keep_alive in component parameter update service requests
• (fix) Passes monitor executor to service client send_req
• (fix) Fixes use of multi processors for same topic in launcher
• (fix) Fix package installation for documentation workflow
• (feature) Adds support for multiple external processors on the same topic
• (fix) Fixes visibility of external_processors to protected
• (fix) Fixes typo in attaching external preprocessors
• (feature) Adds unix socket based listener threads for using external processors with components being run in multiprocessing
  • Modifies executable to add an argument for external processors
  • Adds setting and getting for external processor json in component
  • Adds setting up of external processors on component activation and destruction on component stop
  • Adds setup of external processor sockets and thread pool in launcher
• (fix) Fixes minor bugs in base component and launcher (#10)
• (fix) Fixes the handling of yuv422_yuy2 encoding in image reading util function
• (fix) Adds process id to monitor node name
• (fix) Fixes type check for callables in attaching post and pre processors
• (fix) Updates component launch arguments after parsing events_actions
• (docs) Updates docs url links in readme
• (docs) Adds github workflow for docs (#9)
• (fix) Adds handling image encodings with alpha channel
• Create LICENSE
• Initial release version 0.1.1 (#8)
• init commit
• Contributors: ahr, aleph-ra, mkabtoul