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