The Orchestration Layer for Event-Driven ROS2 Systems

Sugarcoat is a meta-framework that replaces fragmented ROS2 development with a unified workflow, offering a high-level API to build robust components and orchestrate them into cohesive, self-healing systems.

By replacing verbose boilerplate and static launch files with an Event-Driven API, Sugarcoat allows you to orchestrate complex robotic behaviors with the elegance of modern Python.

Why Sugarcoat? Bridging the Orchestration Gap

In the standard ROS2 ecosystem, developers are given powerful tools to create individual “bricks” (Nodes), but very few tools to create the “building” (the System). As robotic systems scale, they inevitably face the Orchestration Gap: a void between low-level drivers and high-level mission planning.

• Standard ROS2: Leads to a “Manager Node” problem. To coordinate nodes, developers write a manager node that quickly becomes a “spaghetti” of callbacks, timers, and hardcoded logic that is difficult to test and prone to failure.
• Behavior Trees (e.g., Nav2): Rely on sequential polling mechanisms (“ticks”) that process logic sequentially. They are latency-prone, can block the system’s ability to react during complex actions, and make global scope safety triggers (like a universal killswitch) notoriously difficult to implement.

The Sugarcoat Solution: Sugarcoat provides an imperative, event-driven middle layer. It operates on a Parallel Event Engine that doesn’t “tick” through a list; it listens to the entire system at once, offering true distributed automation with immediate microsecond reaction times.

Key Features & Core Pillars

Packages Built with Sugarcoat

• Kompass: A framework for building robust and comprehensive event-driven navigation stacks using an easy-to-use and intuitive Python API.
• EmbodiedAgents: A fully-loaded framework for creating interactive embodied agents that can think, understand and act.

Get Started

• Learn more about the design concepts in Sugarcoat
• Learn how to create your own ROS2 package using Sugarcoat
• Port your automation recipes across different hardware using Robot Plugins
• Explore the Dynamic Web UI for real-time system visualization and control

How Sugarcoat Works

The core of Sugarcoat revolves around bringing seemless orchestration and reactive autonomy to your robot.

1. Components (Smart Execution)

A Component is your main execution unit, replacing the standard ROS2 Node. It validates its own configuration, automatically wires topics declaratively, and manages its own lifecycle natively.

2. Events & Actions (Reactive Middle Layer)

Define dynamic behavior using pure Python expressions. Events monitor topics continuously in parallel, completely independent of the execution state of your components.

from ros_sugar.core import Event, Action

# A global event monitored in parallel, executing instantly with zero polling latency
collision_risk = Event(sensor.msg.min_dist < 0.5)

# Trigger a System-Wide Action instantly
launcher.add_pkg(
    components=[...],
    events_actions={collision_risk: Action(stop_motors)}
)

3. Launcher (Orchestration)

Takes your defined Components, Events, and Actions, and executes the system. The Launcher actively tracks health statuses and orchestrates multi-threaded or multi-process execution cleanly.

Dynamic Web UI for Sugarcoat Recipes

The Dynamic Web UI feature takes system visibility and control to the next level. Built with FastHTML and MonsterUI, it is designed to automatically generate a fully dynamic, extensible web interface for any Sugarcoat recipe, completely eliminating the need for manual front-end development.

Automatic UI Generation in Action

File truncated at 100 lines see the full file

Changelog for package automatika_ros_sugar

0.5.0 (2026-02-14)

• (refactor) Removes callback_group from component config
• (fix) Fixes action serialization for fallbacks
• (refactor) Removes optional health monitoring and enables it for all components
• (docs) Updates events/actions docs using new theme
• (docs) Updates concepts overview
• (docs) Updates core design docs pages
• (fix) Removes outdated check in component_action decorator
• (fix) Fixes UI outputs init error
• (docs) Updates overview and install sections
• (docs) Updates docs for events/actions and removes unnecessary md copying
• (docs) Uses Shibuya theme for docs
• (feature) Adds support for Path visulization in UI outputs
• (feature) Adds UI callback for Path datatype
• (fix) Handles point frame_id for UI output display on maps
• (docs) Re-orgnize the index tree
• (fix) Moves component fallback topics blackboard to init
• (feature) Adds support for displaying point-like UI outputs on a Map element
• (fix) Fixes clicked points transformation in UI map elements
• (feature) Adds support for topic inputs in Fallback Actions
• (fix) Fixes registering actions with multiple topics to events
• (fix) Fixes parsing and clearing a component internal events/actions
• (feature) Adds method to replace an Action input topic
• (fix) Fixes checking on_any event with multi-topic condition source
• (fix) Fixes sending topics blackboard values to action on internal (monitor) events
• (fix) Fixes serialization error in base config
• (fix) Fixes getting component internal events in launcher
• (docs) Updates docs with new API updates for events and actions
• (feature) Makes all UI cards draggable and resizable
• (feature) Adds dark/light mode toggle to UI
• (feature) Adds dynamic publishers creation in UI node
• (feature) Improves launcher logging display and colors
• (reafctor) Removes 'event_name' param from Event class and uses an internal unique ID instead
• (fix) Adds a timestamp and unique ID to events topics dashboard to prevent 'stale' message processing in events
• (refactor) Uses sugarcoat logger in UI node
• (fix) Fixes launching opaque actions with new multi-condition event design
• (refactor) Updates system actions
• (feature) Adds support for complex conditions (and, or, not) in event and refactors the Event class
• (refactor) Removes 'event_parsers' from action
• (feature) Updates the point input ui element based based on a present map element
• (refactor) Converts external processor types to an enum class
• (feature) Adds style for buttons tooltip
• (feature) Adds clicked point publishing to map canvas
• (fix) Fixes error in actions and adds external processor deserialization to executable
• (feature) Adds element and websocket to handle map data in UI
• (fix) Fixes condition builder class to avoid errors when usinf deepcopy or inspect on an object
• (feature) Adds automatic action parser from ROS types to Python types
• (feature) Adds property to automatically get a component health status topic
• (docs) Updates docus with new events-actions api
• (refactor) Adds Action to core module
• (refactor) Removes old events module
• (refactor) Removes unused init args for main Event class
• (feature) Adds conditions for string values (contains, not_contains, is_in, not_in)
• (refactor) Moves event condition class to a new module
• (feature) Adds condition builders for boolean values in events
• (feature) Adds OnAny to events constructed from conditions
• (refactor) Refactors actions module and adds method to create an automatic action parser from given topic message type
• (feature) Adds internal events condition constructor and updates the event API
• (feature) Adds trigger actions for sending empty ROS2 action/service calls
• (refactor) Updates status topic name
• (feature) Adds automatic parsing from topic values in Action
• (feature) Handles parsing internal component event_actions in launcher
• (feature) Update Task UI element with server info and request pop-up
• (refactor) Moves all component and system level actions to 'actions' module
• (feature) Adds component actions with automatic event parsers
• Contributors: ahr, mkabtoul

0.4.3 (2026-01-17)

• (refactor) Organizes UI custom javascript into three functional scripts
• (docs) Improves the core concepts documentation
• (fix) Fixes check for None max_retries value in fallback
• (fix) Fixes logging colors in multi-process execution
• (feature) Adds parameter for lifecycle transition timeout
• (fix) Add error catching during all fallbacks action execution
• (fix) Fixes fallback init and exposes on_giveup fallback
• (fix) Adds fallbacks serialization to support multi-process

File truncated at 100 lines see the full file