fss_time

This package provides conservative lock-step simulation time for ROS 2 applications in FastSwarmSim. A ZeroMQ-based time coordinator grants the shared simulation clock only after every participating thread has announced the next time at which it is safe for the clock to advance. This makes simulation results deterministic with respect to simulation time while allowing real-time or accelerated execution.

# Launch a local coordinator, simulation clock, and control UI.
ros2 launch fss_time time_coordinator.launch.py

# Limit the simulation to 2x real time.
ros2 launch fss_time time_coordinator.launch.py max_real_time_factor:=2.0

# Run with a high speed limit (bounded by available CPU and participant work).
ros2 launch fss_time time_coordinator.launch.py max_real_time_factor:=1000.0

# Start without the UI.
ros2 launch fss_time time_coordinator.launch.py start_coordinator_ui:=false

What it contains:

1. A time coordinator that publishes /clock, receives participant safe-time announcements over ZeroMQ, and grants a shared simulation time. The coordinator also provides fss/clock_control to pause/resume the clock and set max_real_time_factor at runtime.

2. Thread time participants. Each participating thread announces the earliest future simulation time that it can safely permit; its announcement automatically registers the thread and is removed when the thread exits.

3. fss_time::Rate, fss_time::sleep_for, and fss_time::sleep_until helpers. They use the node clock and automatically announce the next safe time when use_fss_sim_time is enabled.

4. fss_time::executors::SingleThreadedExecutor and fss_time::executors::MultiThreadedExecutor, plus the convenience fss_time::spin(node). These executors make ROS callbacks participate in lock-step execution.

5. Cascaded coordinators for multi-machine simulation. A child coordinator announces its local safe time to a parent coordinator and republishes grants as its local /clock.

Launch and clock parameters

time_coordinator.launch.py starts a root coordinator. By default it uses a local IPC endpoint:

ipc:///tmp/fss_time_coordinator.ipc

Important launch arguments:

To use fss_time with application nodes, set both parameters in their launch scope:

from launch_ros.actions import SetParameter

SetParameter(name="use_fss_sim_time", value=True)
SetParameter(name="use_sim_time", value=True)

use_sim_time makes the node clock follow the coordinator’s /clock. use_fss_sim_time enables the fss_time announce-and-request behavior in its helpers and executors. They are intentionally separate: setting only use_sim_time uses /clock but does not make the application a lock-step participant; setting only use_fss_sim_time leaves ROS time inactive and causes the helpers to wait. The package launch files set both together, and use_fss_sim_time is normally enabled by default.

Set the endpoint too when it differs from the default or when running on another machine:

SetParameter(
    name="fss_time_coordinator_endpoint",
    value="tcp://coordinator-host:5545",
)

How lock-step time works

  ROS timer / loop / callback                     ROS timer / loop / callback
  +--------------------------+                    +--------------------------+
  | thread participant A     |                    | thread participant B     |
  | announce next safe time  |                    | announce next safe time  |
  +------------+-------------+                    +-------------+------------+
               | ZeroMQ ANNOUNCE tA                             | ZeroMQ ANNOUNCE tB
               '---------------------------. .------------------'
                                            v v
                              +-----------------------------------+
                              |         Time coordinator          |
                              | target = earliest safe request    |
                              | + speed/real-time constraints     |
                              +----------------+------------------+
                                               |
                                               | grant t, publish /clock
                        . . . . . . . . . . .  v  . . . . . . . . . . .
                                               |
                       +-----------------------+-----------------------+
                       | Nodes use their ROS clock at the same time t  |
                       +------------------------------------------------+

For a normal finite step, the coordinator waits until every participating thread has made a new announcement, then advances to the minimum requested safe time, subject to the configured speed regulator. A thread that is waiting for ROS work does not constrain progress: an fss_time executor announces infinite safe time while it waits. Before executing a ready callback, the executor announces the current simulation time and therefore holds the clock during that callback.

fss_time::Rate and fss_time::sleep_* announce the time at which their calling thread will resume before sleeping on the node’s ROS clock. The coordinator can consequently request the next grant proactively instead of waiting for wall time to elapse.

Converting a ROS 2 node

File truncated at 100 lines see the full file

Changelog for package fss_time

0.1.2 (2026-09-18)

• docs: add platform support and release changelog automation
• Contributors: Peixuan Shu

0.1.1 (2026-08-19 21:18)

• chore: bump all packages to 0.1.1 for ROS release
• test: remove outdated fss_time tests that hang waiting for ROS clock (#598, #615)
• Contributors: Peixuan Shu

0.1.0 (2026-08-19 20:25)

• feat: update README.md for fss_time package with detailed ZeroMQ coordination explanation and usage instructions
• feat: enhance time coordination logic with new advancement checks and update real time request handling
• feat: update CMakeLists.txt for fss_px4_sim and fss_time to include Release build type and optimize compiler flags feat: improve warning messages in MulticopterAttitudeControl and MulticopterPositionControl for loop period thresholds
• feat: update RViz configurations, enhance point cloud rendering, and improve performance settings
• fix: revert version and description changes in package.xml for consistency
• Enhance launch files with detailed descriptions and environment settings
  • Added descriptions to launch arguments in [perfect_mavros_drone_swarm.launch.py]{.title-ref}, [px4_rotor_sim_multi.launch.py]{.title-ref}, [px4_rotor_sim_single.launch.py]{.title-ref}, [sensing.launch.py]{.title-ref}, [parent_time_coordinator_example.launch.py]{.title-ref}, [time_coordinator.launch.py]{.title-ref}, [executor_time_test_case.launch.py]{.title-ref}, [multi_node_sim_time_test_case.launch.py]{.title-ref}, and [sleep_rate_test_case.launch.py]{.title-ref} for better clarity.
  • Introduced [SetEnvironmentVariable]{.title-ref} to force colorized output in logs across multiple launch files.
  • Updated launch arguments to include choices where applicable, improving validation and user experience.
  • Refactored the structure of launch files for consistency and readability.
• feat: add clear zombie participants functionality and related UI updates, improve auto unregister success rate
• feat: refactor time coordinator for improved message handling and add UI parameter for always on top
• feat: scope included launches to isolate parameters and prevent leakage
• feat: enhance launch files and visualization for drone simulation
• feat: add configuration for large-scale fastdds participant limits
• feat: remove dependencies of agent_id for px4 param and uorb messges.
• feat: add test for TimeCoordinator to allow empty pub endpoint and verify advertisement
• feat: increase speed regulator step to improve real-time factor performance
• feat: implement asynchronous task handling in TimeCoordinator for improved performance
• feat: add simulation time to status updates in CoordinatorBridge and MainWindow
• feat: update minimum operation walltime constant and optimize clock update logic
• feat: improve coordinator performance by cancling replying OK for announce and using Debug msg enum.
• feat: enhance clock subscription with QoS settings and remove unused sim_time variable
• Add MAVROS setpoint raw and system status plugins
  • Implemented SetpointRawPlugin to handle MAVLink position and attitude targets, transforming coordinates between NED and ENU frames.
  • Added SystemStatusPlugin to publish various system status messages including state, extended state, and battery status.
  • Updated thread_time_participant to remove follows_real_time parameter and adjusted related functionality in ZeroMqTimeParticipantBackend.
  • Refactored registration logic for time participants to streamline real-time settings management.
• feat: finish migration of px4_rotor_sim to fss_px4_sim
• feat: add real-time following feature for time participants and enhance coordinator communication
• feat: add detailed documentation for parent time coordinator launch file
• feat: add parent time coordinator launch file and enhance UI namespace handling
• feat: add TCP endpoint parsing and replacement functions for improved socket handling
• feat: add UUID generation and enhance coordinator communication in time management
• feat: enhance time coordination with parent-child relationship and grant messaging
• fix: increase clock status timer interval and ensure minimum real time timer period
• feat: add real time floor for time broker, and rename time broker as time coordinator
• feat: Update endpoint references from sim_time_broker to

File truncated at 100 lines see the full file