Skip to content

Clock Publisher

Introduction#

ClockPublisher allows the publication of the simulation time from the clock operating within AWSIM. The current time is retrived from a TimeSource object via the SimulatorROS2Node. The AWSIM provides convenient method for selecting the appropriate time source type as well as the flexibility to implement custom TimeSources tailored to specific user requirements.

Setup#

To enable the publication of the current time during simulation execution, ClockPublisher must be included as a component within the scene. Moreover, to allow the TimeSource to be set or changed, the TimeSourceSelector object must also be present in the active scene.

time_source_selector_hierarchy

Selecting Time Source#

The desired TimeSource can be selected in two ways:

  • Inspector Selection: TimeSource type can be conveniently choosen directly from the editor interface.

time_source_selector_inspector

  • JSON Configuration File: Alternatively, the TimeSource type can be specified in the JSON configuration file via the TimeSource field. The supported values for this field can be found in the list of available time sources in the "String Value for JSON Config" column.

time_source_selector_config

List of Time Sources#

Type String Value for JSON Config Description
UNITY unity based on the time of the Unity Engine
SS2 ss2 driven by an external source, used by the scenario simulator v2
DOTNET_SYSTEM system based on system time, starting with time since UNIX epoch, progressing according to simulation timescale
DOTNET_SIMULATION simulation based on system time, starting with zero value, progressing according to simulation timescale
ROS2 ros2 based on ROS2 time (system time by default)

Architecture#

The ClockPublisher operates within a dedicated thread called the 'Clock' thread. This design choice offers significant advantages by freeing the publishing process from the constraints imposed by fixed update limits. As a result, ClockPublisher is able to consistently publish time at a high rate, ensuring stability and accuracy.

Accessing Time Source#

Running the clock publisher in a dedicated thread introduced the challenge of accessing shared resources by different threads. In our case, the Main Thread and Clock Thread compete for TimeSoruce resources. The diagram below illustrates this concurrent behaviour, with two distinct threads vying for access to the TimeSource:

  • Main Thread: included publishing message by sensors (on the diagram blueish region labeled sensor loop),
  • Clock Thread: included clock publisher (on the diagram blueish region labeled clock loop).

Given multiple sensors, each with its own publishing frequency, alongside a clock running at 100Hz, there is a notable competition for TimeSource resources. In such cases, it becomes imperative for the TimeSource class to be thread-safe.

clock_publisher_threads

Thread-Safe Time Source#

The TimeSource synchronization mechanism employs a mutex to lock the necessary resource for the current thread. The sequence of actions undertaken each time the GetTime() method is called involves:

  • acquiring the lock,
  • getting the current time, e.g. system time since epoch, (this may be different for each type of time source),
  • obtaining the current simulation time-scale,
  • calculating the delta time since previous call, influenced by the time scale,
  • returning the current time,
  • releasing the lock.

time_source_mutex

Extensions#

There are two additional classes used to synchronise the UnityEngine TimeAsDouble and TimeScale values between threads:

  • TimeScaleProvider: facilitates the synchronisation of the simulation time scale value across threads,
  • TimeAsDoubleProvider: provides access to the UnityEngine TimeAsDouble to the threads other than the main thread.